From 0a857ad6412e71613e5021afb761b1069ba8d5b9 Mon Sep 17 00:00:00 2001
From: ChethanUK <chethanuk@outlook.com>
Date: Mon, 14 Sep 2026 16:26:08 +0200
Subject: [PATCH 001/105] fix(e2e): re-point HunyuanImage3 offline test to
 text_to_image.py

Commit a7ab91fb8 removed examples/offline_inference/hunyuan_image3/end2end.py
and moved HunyuanImage-3.0 to the shared text_to_image/text_to_image.py;
tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py still invoked
the deleted path, causing test_hunyuan_image3_pixel_accuracy_offline to
fail with No such file / exit 2.

Re-point _OFFLINE_SCRIPT and remap CLI flags per the shared script:
--modality dropped, --prompts->--prompt, --steps->--num-inference-steps,
--bot-task/--sys-type->--extra-body '{"bot_task": null}' /
--use-system-prompt en_unified plus --trust-remote-code, and write
directly to the file path instead of globbing output_*.png.

Fixes #7495

Signed-off-by: ChethanUK <chethanuk@outlook.com>
---
 .../test_hunyuan_image3_pixel_accuracy.py     | 24 ++++++++-----------
 1 file changed, 10 insertions(+), 14 deletions(-)

diff --git a/tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py b/tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py
index 71dd6f3088e..4b06a6fad72 100644
--- a/tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py
+++ b/tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py
@@ -73,7 +73,7 @@ def _baseline_path() -> Path:
     return path
 
 
-_OFFLINE_SCRIPT = _REPO_ROOT / "examples" / "offline_inference" / "hunyuan_image3" / "end2end.py"
+_OFFLINE_SCRIPT = _REPO_ROOT / "examples" / "offline_inference" / "text_to_image" / "text_to_image.py"
 
 # DiT-only deploy config with trust_remote_code (based on hunyuan_image3_dit.yaml).
 _DEPLOY_CONFIG: dict[str, Any] = {
@@ -228,20 +228,17 @@ def _run_vllm_omni_hunyuan_image3_offline(*, model: str, deploy_config: str, out
     import subprocess
     import sys
 
-    output_dir = str(output_path.parent)
     subprocess.run(
         [
             sys.executable,
             str(_OFFLINE_SCRIPT),
-            "--modality",
-            "text2img",
             "--deploy-config",
             deploy_config,
-            "--prompts",
+            "--prompt",
             PROMPT,
             "--output",
-            output_dir,
-            "--steps",
+            str(output_path),
+            "--num-inference-steps",
             str(NUM_INFERENCE_STEPS),
             "--guidance-scale",
             str(GUIDANCE_SCALE),
@@ -251,21 +248,20 @@ def _run_vllm_omni_hunyuan_image3_offline(*, model: str, deploy_config: str, out
             str(HEIGHT),
             "--width",
             str(WIDTH),
-            "--bot-task",
-            "none",
-            "--sys-type",
+            "--use-system-prompt",
             "en_unified",
+            "--extra-body",
+            '{"bot_task": null}',
+            "--trust-remote-code",
             "--model",
             model,
             "--enforce-eager",
         ],
         check=True,
     )
-    images = sorted(Path(output_dir).glob("output_*.png"))
-    assert images, f"No output image found in {output_dir}"
-    image = Image.open(images[0]).convert("RGB")
+    assert output_path.exists(), f"No output image at {output_path}"
+    image = Image.open(output_path).convert("RGB")
     image.load()
-    image.save(output_path)
     return image
 
 

From 92715f3f7b67d7835c08002309402ba08b7b237e Mon Sep 17 00:00:00 2001
From: andyluo7 <43718156+andyluo7@users.noreply.github.com>
Date: Mon, 14 Sep 2026 22:24:34 -0700
Subject: [PATCH 002/105] [CI][ROCm] Add non-blocking engine and model executor
 GPU coverage (#7397)

Signed-off-by: andyluo7 <andy.luo@amd.com>
---
 .buildkite/amd/test-amd-ready.yml       | 33 ++++++++++++
 tests/buildkite/test_amd_ready_r2_01.py | 72 +++++++++++++++++++++++++
 2 files changed, 105 insertions(+)
 create mode 100644 tests/buildkite/test_amd_ready_r2_01.py

diff --git a/.buildkite/amd/test-amd-ready.yml b/.buildkite/amd/test-amd-ready.yml
index 585f089a271..181a451bbba 100644
--- a/.buildkite/amd/test-amd-ready.yml
+++ b/.buildkite/amd/test-amd-ready.yml
@@ -160,6 +160,39 @@ steps:
 #     - export VLLM_WORKER_MULTIPROC_METHOD=spawn
 #     - timeout 20m pytest -s -v tests/e2e/offline_inference/test_stable_audio_expansion.py -m "advanced_model and diffusion and L4" --run-level advanced_model
 
+- label: "ROCm · Engine & Model Executor GPU Coverage (R2-01)"
+  agent_pool: mi300_1
+  depends_on: amd-build
+  mirror_hardwares: [amdproduction]
+  grade: NonBlocking
+  timeout_in_minutes: 20
+  artifact_paths:
+    - "artifacts/rocm-r2-01/**/*"
+  commands:
+    # Native AMD tests run from /app/vllm-omni, while Buildkite uploads
+    # artifacts relative to its checkout directory.
+    - export R2_01_ARTIFACT_DIR="$$BUILDKITE_BUILD_CHECKOUT_PATH/artifacts/rocm-r2-01"
+    - mkdir -p "$$R2_01_ARTIFACT_DIR"
+    # The CUDA ready job also covers tests/worker/test_batched_omni_output.py.
+    # Keep the initial ROCm burn-in scoped to the requested directories.
+    # Verbose pytest output and JUnit retain node IDs without a second
+    # collection-only pass over the same GPU-backed test tree.
+    # The CUDA/L4-only CosyVoice3 ragged-flow parity test cold-JITs multiple
+    # AITER kernels on ROCm and is covered by the CUDA ready lane.
+    - >-
+      pytest -s -v -ra
+      tests/engine/ tests/model_executor/
+      -m 'core_model and cuda and not
+      (cards_2 or cards_3 or cards_4 or cards_5 or cards_6 or cards_7 or cards_8)'
+      -k 'not test_code2wav_streaming_batch_matches_ragged_flow_numerics'
+      --run-level "core_model"
+      --durations=0
+      --junitxml="$$R2_01_ARTIFACT_DIR/pytest.xml"
+      2>&1 | tee "$$R2_01_ARTIFACT_DIR/pytest.log"
+    - >-
+      tail -n 100 "$$R2_01_ARTIFACT_DIR/pytest.log" >
+      "$$R2_01_ARTIFACT_DIR/pytest-summary.txt"
+
 - label: "Engine Test"
   agent_pool: mi300_1
   depends_on: amd-build
diff --git a/tests/buildkite/test_amd_ready_r2_01.py b/tests/buildkite/test_amd_ready_r2_01.py
new file mode 100644
index 00000000000..9d514798290
--- /dev/null
+++ b/tests/buildkite/test_amd_ready_r2_01.py
@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from pathlib import Path
+from shlex import split
+
+import pytest
+import yaml
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+AMD_READY_PIPELINE = Path(".buildkite/amd/test-amd-ready.yml")
+R2_01_LABEL = "ROCm · Engine & Model Executor GPU Coverage (R2-01)"
+SINGLE_GPU_MARKERS = (
+    "core_model and cuda and not (cards_2 or cards_3 or cards_4 or cards_5 or cards_6 or cards_7 or cards_8)"
+)
+EXCLUDED_TEST = "test_code2wav_streaming_batch_matches_ragged_flow_numerics"
+
+
+def _find_step(label: str) -> dict:
+    pipeline = yaml.safe_load(AMD_READY_PIPELINE.read_text(encoding="utf-8"))
+
+    def walk(steps: list[dict]) -> dict | None:
+        for step in steps:
+            if step.get("label") == label:
+                return step
+            if nested := walk(step.get("steps", [])):
+                return nested
+        return None
+
+    step = walk(pipeline.get("steps", []))
+    assert step is not None, f"missing AMD pipeline step: {label}"
+    return step
+
+
+def _assert_single_gpu_selection(command: str) -> None:
+    argv = split(command)
+    assert "tests/engine/" in argv
+    assert "tests/model_executor/" in argv
+    assert "tests/worker/test_batched_omni_output.py" not in argv
+    assert argv[argv.index("-m") + 1] == SINGLE_GPU_MARKERS
+    assert argv[argv.index("-k") + 1] == f"not {EXCLUDED_TEST}"
+    assert argv[argv.index("--run-level") + 1] == "core_model"
+
+
+def test_r2_01_is_nonblocking_single_gpu_coverage() -> None:
+    step = _find_step(R2_01_LABEL)
+
+    assert step["agent_pool"] == "mi300_1"
+    assert step["grade"] == "NonBlocking"
+    assert step["timeout_in_minutes"] == 20
+    assert step["mirror_hardwares"] == ["amdproduction"]
+    assert step["artifact_paths"] == ["artifacts/rocm-r2-01/**/*"]
+
+
+def test_r2_01_runs_once_fails_closed_and_publishes_results() -> None:
+    commands = _find_step(R2_01_LABEL)["commands"]
+    pytest_commands = [command for command in commands if command.lstrip().startswith("pytest ")]
+    assert len(pytest_commands) == 1
+    run_command = pytest_commands[0]
+    artifact_dir = "$$BUILDKITE_BUILD_CHECKOUT_PATH/artifacts/rocm-r2-01"
+
+    _assert_single_gpu_selection(run_command)
+    assert "--collect-only" not in "\n".join(commands)
+    assert "VLLM_CI_ALLOW_NO_TESTS" not in "\n".join(commands)
+    assert any(artifact_dir in command for command in commands)
+    assert "-v" in split(run_command)
+    assert "-ra" in split(run_command)
+    assert "--durations=0" in split(run_command)
+    assert "--junitxml=$$R2_01_ARTIFACT_DIR/pytest.xml" in split(run_command)
+    assert "$$R2_01_ARTIFACT_DIR/pytest.log" in run_command
+    assert any("$$R2_01_ARTIFACT_DIR/pytest-summary.txt" in command for command in commands)

From 4a8ac297751b03fbe21f2d8a4550a027fe02e7cd Mon Sep 17 00:00:00 2001
From: xuexueligao <89690814+xuexueligao@users.noreply.github.com>
Date: Tue, 15 Sep 2026 18:46:13 +0800
Subject: [PATCH 003/105] [Frontend] Add MiniMax H3 video upscale workflow
 (WF-07) (#7472)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: xuezhihao <89690814+xuexueligao@users.noreply.github.com>
Signed-off-by: 汪志鹏 <wangzhipeng628@gmail.com>
Co-authored-by: 汪志鹏 <wangzhipeng628@gmail.com>
---
 apps/ComfyUI-vLLM-Omni/README.md              |   4 +
 .../ComfyUI-vLLM-Omni/docs/wf07-h3-upscale.md |  21 +
 .../vLLM-Omni MiniMax H3 Video Upscale.json   | 724 ++++++++++++++++++
 3 files changed, 749 insertions(+)
 create mode 100644 apps/ComfyUI-vLLM-Omni/docs/wf07-h3-upscale.md
 create mode 100644 apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax H3 Video Upscale.json

diff --git a/apps/ComfyUI-vLLM-Omni/README.md b/apps/ComfyUI-vLLM-Omni/README.md
index 0d607b30a4c..b848a07161d 100644
--- a/apps/ComfyUI-vLLM-Omni/README.md
+++ b/apps/ComfyUI-vLLM-Omni/README.md
@@ -139,6 +139,10 @@ You can configure per-stage sampling parameters for multi-stage models.
 >
 > Do not use `frame` and `references` together. Task routing is automatic from which inputs you connect.
 
+#### H3 video upscale (WF-07)
+
+The **vLLM-Omni MiniMax H3 Video Upscale** template generates video remotely, upscales it with SeedVR2, and saves the original and upscaled videos with the generated audio and FPS. See [workflow setup](docs/wf07-h3-upscale.md).
+
 #### FastH3 text-to-video
 
 FastH3 is fused into MiniMax-H3 when the vLLM-Omni server starts; it is not a request-switchable LoRA. Download one adapter variant and start a non-offloaded FL2VA server. For the Dense / Data-Free profile:
diff --git a/apps/ComfyUI-vLLM-Omni/docs/wf07-h3-upscale.md b/apps/ComfyUI-vLLM-Omni/docs/wf07-h3-upscale.md
new file mode 100644
index 00000000000..dfdbd166f6c
--- /dev/null
+++ b/apps/ComfyUI-vLLM-Omni/docs/wf07-h3-upscale.md
@@ -0,0 +1,21 @@
+# WF-07: H3 video upscale with SeedVR2
+
+Generate video and audio through vLLM-Omni H3, upscale the decoded frames with SeedVR2, and save both the original and upscaled videos. The generated audio and FPS connect directly to Create Video.
+
+## Requirements
+
+- ComfyUI with ComfyUI-vLLM-Omni and [ComfyUI-SeedVR2_VideoUpscaler](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler#-installation) installed.
+- An H3 service using the FL2VA checkpoint partition. Follow the [H3 recipe](../../../recipes/MiniMaxAI/MiniMax-H3.md) for server setup.
+- `seedvr2_ema_3b_fp16.safetensors` and `ema_vae_fp16.safetensors` from [SeedVR2's ComfyUI weights](https://huggingface.co/numz/SeedVR2_comfyUI/tree/main), placed in `ComfyUI/models/SEEDVR2`. The SeedVR2 nodes can also download them on first use.
+
+## Use
+
+Open **vLLM-Omni MiniMax H3 Video Upscale.json** from the example workflows. An API-format version is provided alongside it. Set the Generate Video URL/model and the LoRA path as seen by the H3 server.
+
+The preset uses the LightX2V v1.0 768p Turbo adapter in Diffusers format: `minimax_h3_fl2v_turbo_4step_v1.0_768p_bf16.safetensors`, five sigma points, video/audio flow shifts 6/3, and LoRA scale 1. Preload the same adapter on the server using the [Turbo LoRA recipe](../../../recipes/MiniMaxAI/MiniMax-H3.md#turbo-lora). For base H3, disconnect LoRA, set inference steps to 50, and set video flow shift to 12.
+
+The H3 preset requests 1344 x 768 at 24 FPS for 5.167 seconds, which gives 124 frames. SeedVR2's `resolution=1536` sets the target short edge, producing 2688 x 1536 for this input. Update this value when changing the input size; it is an output resolution, not a fixed 2x multiplier.
+
+The SeedVR2 preset uses 3B FP16, five-frame batches, one overlapping frame, uniform batch padding, and LAB color correction. The DiT loader uses CPU offload with 32 swapped blocks; the VAE uses tiled encoding and decoding. Select the local GPU in both model loaders. See the [SeedVR2 settings](https://github.com/numz/ComfyUI-SeedVR2_VideoUpscaler#-usage) when adjusting memory use or batch size.
+
+Run the workflow. The two Save Video nodes write MP4s under `WF07/generated` and `WF07/upscaled` in ComfyUI's output directory.
diff --git a/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax H3 Video Upscale.json b/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax H3 Video Upscale.json
new file mode 100644
index 00000000000..e8a21d06583
--- /dev/null
+++ b/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax H3 Video Upscale.json	
@@ -0,0 +1,724 @@
+{
+  "version": 0.4,
+  "last_node_id": 12,
+  "last_link_id": 13,
+  "nodes": [
+    {
+      "id": 1,
+      "type": "VLLMOmniGenerateVideo",
+      "pos": [
+        360,
+        20
+      ],
+      "size": [
+        330,
+        480
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "frame",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "references",
+          "type": "VIDEO_REFERENCES",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "sampling_params",
+          "type": "SAMPLING_PARAMS",
+          "shape": 7,
+          "link": 11
+        },
+        {
+          "name": "lora",
+          "type": "REMOTE_LORA",
+          "shape": 7,
+          "link": 12
+        },
+        {
+          "name": "model_params",
+          "type": "VIDEO_PARAMS",
+          "shape": 7,
+          "link": 10
+        },
+        {
+          "name": "fast_h3",
+          "type": "FASTH3_DEPLOYMENT",
+          "shape": 7,
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "links": [
+            1,
+            9
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniGenerateVideo"
+      },
+      "widgets_values": [
+        "http://127.0.0.1:8091/v1",
+        "MiniMaxAI/MiniMax-H3",
+        "A small brass bell hanging from a wooden beam in a quiet garden. A gentle breeze swings the bell and it rings clearly. Static camera, natural daylight, continuous motion, synchronized ringing and soft birdsong.",
+        "",
+        1344,
+        768,
+        24,
+        5.167
+      ]
+    },
+    {
+      "id": 2,
+      "type": "GetVideoComponents",
+      "pos": [
+        730,
+        20
+      ],
+      "size": [
+        250,
+        125
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "link": 1
+        }
+      ],
+      "outputs": [
+        {
+          "name": "images",
+          "type": "IMAGE",
+          "links": [
+            2
+          ]
+        },
+        {
+          "name": "audio",
+          "type": "AUDIO",
+          "links": [
+            6
+          ]
+        },
+        {
+          "name": "fps",
+          "type": "FLOAT",
+          "links": [
+            5
+          ]
+        },
+        {
+          "name": "bit_depth",
+          "type": "INT",
+          "links": [
+            7
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "GetVideoComponents"
+      }
+    },
+    {
+      "id": 3,
+      "type": "SeedVR2LoadDiTModel",
+      "pos": [
+        730,
+        290
+      ],
+      "size": [
+        340,
+        245
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "torch_compile_args",
+          "name": "torch_compile_args",
+          "shape": 7,
+          "type": "TORCH_COMPILE_ARGS",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "SEEDVR2_DIT",
+          "name": "SEEDVR2_DIT",
+          "type": "SEEDVR2_DIT",
+          "links": [
+            3
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "SeedVR2LoadDiTModel"
+      },
+      "widgets_values": [
+        "seedvr2_ema_3b_fp16.safetensors",
+        "cuda:0",
+        32,
+        false,
+        "cpu",
+        false,
+        "sdpa"
+      ]
+    },
+    {
+      "id": 4,
+      "type": "SeedVR2VideoUpscaler",
+      "pos": [
+        1120,
+        290
+      ],
+      "size": [
+        340,
+        415
+      ],
+      "flags": {},
+      "order": 8,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "image",
+          "name": "image",
+          "type": "IMAGE",
+          "link": 2
+        },
+        {
+          "localized_name": "dit",
+          "name": "dit",
+          "type": "SEEDVR2_DIT",
+          "link": 3
+        },
+        {
+          "localized_name": "vae",
+          "name": "vae",
+          "type": "SEEDVR2_VAE",
+          "link": 13
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "IMAGE",
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [
+            4
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "SeedVR2VideoUpscaler"
+      },
+      "widgets_values": [
+        42,
+        "fixed",
+        1536,
+        0,
+        5,
+        true,
+        "lab",
+        1,
+        0,
+        0.0,
+        0.0,
+        "cpu",
+        false
+      ]
+    },
+    {
+      "id": 5,
+      "type": "CreateVideo",
+      "pos": [
+        1490,
+        290
+      ],
+      "size": [
+        250,
+        175
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "images",
+          "type": "IMAGE",
+          "link": 4
+        },
+        {
+          "name": "fps",
+          "type": "FLOAT",
+          "widget": {
+            "name": "fps"
+          },
+          "link": 5
+        },
+        {
+          "name": "audio",
+          "type": "AUDIO",
+          "shape": 7,
+          "link": 6
+        },
+        {
+          "name": "bit_depth",
+          "type": "INT",
+          "widget": {
+            "name": "bit_depth"
+          },
+          "link": 7
+        }
+      ],
+      "outputs": [
+        {
+          "name": "VIDEO",
+          "type": "VIDEO",
+          "links": [
+            8
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "CreateVideo"
+      },
+      "widgets_values": [
+        24,
+        8
+      ]
+    },
+    {
+      "id": 6,
+      "type": "SaveVideo",
+      "pos": [
+        1790,
+        290
+      ],
+      "size": [
+        330,
+        280
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "link": 8
+        },
+        {
+          "name": "filename_prefix",
+          "type": "STRING",
+          "widget": {
+            "name": "filename_prefix"
+          },
+          "link": null
+        },
+        {
+          "name": "format",
+          "type": "COMBO",
+          "widget": {
+            "name": "format"
+          },
+          "link": null
+        },
+        {
+          "name": "codec",
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "codec"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "links": []
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "SaveVideo"
+      },
+      "widgets_values": [
+        "WF07/upscaled",
+        "mp4",
+        "auto"
+      ]
+    },
+    {
+      "id": 7,
+      "type": "VLLMOmniMiniMaxH3Params",
+      "pos": [
+        0,
+        20
+      ],
+      "size": [
+        320,
+        120
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "MiniMax-H3 video params",
+          "type": "VIDEO_PARAMS",
+          "links": [
+            10
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniMiniMaxH3Params"
+      },
+      "widgets_values": [
+        3.0,
+        6.0
+      ]
+    },
+    {
+      "id": 8,
+      "type": "VLLMOmniDiffusionSampling",
+      "pos": [
+        0,
+        200
+      ],
+      "size": [
+        320,
+        280
+      ],
+      "flags": {},
+      "order": 8,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "diffusion sampling params",
+          "type": "SAMPLING_PARAMS",
+          "links": [
+            11
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniDiffusionSampling"
+      },
+      "widgets_values": [
+        1,
+        5,
+        1.0,
+        1.0,
+        false,
+        true,
+        42,
+        "fixed"
+      ]
+    },
+    {
+      "id": 9,
+      "type": "VLLMOmniRemoteLoRA",
+      "pos": [
+        0,
+        530
+      ],
+      "size": [
+        320,
+        210
+      ],
+      "flags": {},
+      "order": 9,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "lora",
+          "type": "REMOTE_LORA",
+          "links": [
+            12
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniRemoteLoRA"
+      },
+      "widgets_values": [
+        "models/minimax-h3-turbo/minimax_h3_fl2v_turbo_4step_v1.0_768p_bf16.safetensors",
+        "h3-turbo-v1.0",
+        1.0,
+        0
+      ]
+    },
+    {
+      "id": 10,
+      "type": "SaveVideo",
+      "pos": [
+        1120,
+        20
+      ],
+      "size": [
+        330,
+        190
+      ],
+      "flags": {},
+      "order": 10,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "link": 9
+        },
+        {
+          "name": "filename_prefix",
+          "type": "STRING",
+          "widget": {
+            "name": "filename_prefix"
+          },
+          "link": null
+        },
+        {
+          "name": "format",
+          "type": "COMBO",
+          "widget": {
+            "name": "format"
+          },
+          "link": null
+        },
+        {
+          "name": "codec",
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "codec"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "links": []
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "SaveVideo"
+      },
+      "widgets_values": [
+        "WF07/generated",
+        "mp4",
+        "auto"
+      ],
+      "title": "Save generated video before upscale"
+    },
+    {
+      "id": 11,
+      "type": "Note",
+      "pos": [
+        360,
+        560
+      ],
+      "size": [
+        330,
+        260
+      ],
+      "flags": {},
+      "order": 11,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "properties": {
+        "Node name for S&R": "Note"
+      },
+      "widgets_values": [
+        "WF-07: H3 + SeedVR2\n\nInstall ComfyUI-SeedVR2_VideoUpscaler. The DiT and VAE loaders use SeedVR2 3B FP16 and ema_vae_fp16.\n\nSet the H3 service URL/model and the server-side Turbo LoRA path.\n\n1536 is the target short edge for this 1344 x 768 preset (2x). Original audio and FPS connect directly to Create Video.\n\nFor base H3: disconnect LoRA, use 50 steps and video flow shift 12."
+      ]
+    },
+    {
+      "id": 12,
+      "type": "SeedVR2LoadVAEModel",
+      "pos": [
+        730,
+        590
+      ],
+      "size": [
+        340,
+        315
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "torch_compile_args",
+          "name": "torch_compile_args",
+          "shape": 7,
+          "type": "TORCH_COMPILE_ARGS",
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "SEEDVR2_VAE",
+          "name": "SEEDVR2_VAE",
+          "type": "SEEDVR2_VAE",
+          "links": [
+            13
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "SeedVR2LoadVAEModel"
+      },
+      "widgets_values": [
+        "ema_vae_fp16.safetensors",
+        "cuda:0",
+        true,
+        1024,
+        128,
+        true,
+        768,
+        128,
+        "false",
+        "cpu",
+        false
+      ]
+    }
+  ],
+  "links": [
+    [
+      1,
+      1,
+      0,
+      2,
+      0,
+      "VIDEO"
+    ],
+    [
+      2,
+      2,
+      0,
+      4,
+      0,
+      "IMAGE"
+    ],
+    [
+      3,
+      3,
+      0,
+      4,
+      1,
+      "SEEDVR2_DIT"
+    ],
+    [
+      4,
+      4,
+      0,
+      5,
+      0,
+      "IMAGE"
+    ],
+    [
+      5,
+      2,
+      2,
+      5,
+      1,
+      "FLOAT"
+    ],
+    [
+      6,
+      2,
+      1,
+      5,
+      2,
+      "AUDIO"
+    ],
+    [
+      7,
+      2,
+      3,
+      5,
+      3,
+      "INT"
+    ],
+    [
+      8,
+      5,
+      0,
+      6,
+      0,
+      "VIDEO"
+    ],
+    [
+      9,
+      1,
+      0,
+      10,
+      0,
+      "VIDEO"
+    ],
+    [
+      10,
+      7,
+      0,
+      1,
+      4,
+      "VIDEO_PARAMS"
+    ],
+    [
+      11,
+      8,
+      0,
+      1,
+      2,
+      "SAMPLING_PARAMS"
+    ],
+    [
+      12,
+      9,
+      0,
+      1,
+      3,
+      "REMOTE_LORA"
+    ],
+    [
+      13,
+      12,
+      0,
+      4,
+      2,
+      "SEEDVR2_VAE"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "ds": {
+      "scale": 0.52,
+      "offset": [
+        100,
+        100
+      ]
+    }
+  }
+}

From a3dee6fdf52267fd56f0237f47b5bbe68dbb13b2 Mon Sep 17 00:00:00 2001
From: wtz2333 <2955110911@qq.com>
Date: Tue, 15 Sep 2026 18:49:55 +0800
Subject: [PATCH 004/105] [Lingbot World] Bound image condition storage and
 extend temporal RoPE (#6838)

Signed-off-by: wtz2333 <2955110911@qq.com>
---
 docs/design/feature/realtime_ar_diffusion.md  |  16 +-
 .../ar_diffusion_streaming_decode.py          |  20 +-
 .../diffusion/lingbot_world_v2.py             |   3 -
 .../diffusion/lingbot_world_v2_realtime.py    |  19 +-
 recipes/Robbyant/LingBot-World-2.0.md         |   8 +-
 .../test_lingbot_world_camera.py              |  29 +-
 .../test_lingbot_world_transformer.py         |  52 ++-
 .../test_pipeline_lingbot_world.py            | 347 +++++++++++++++---
 .../test_lingbot_world_v2.py                  |  24 ++
 .../diffusion/models/lingbot_world/camera.py  |   7 +-
 .../models/lingbot_world/pipeline.py          | 238 ++++++++----
 .../models/lingbot_world/transformer.py       |  24 +-
 12 files changed, 592 insertions(+), 195 deletions(-)

diff --git a/docs/design/feature/realtime_ar_diffusion.md b/docs/design/feature/realtime_ar_diffusion.md
index 426ee5afd73..2f86744b186 100644
--- a/docs/design/feature/realtime_ar_diffusion.md
+++ b/docs/design/feature/realtime_ar_diffusion.md
@@ -143,8 +143,20 @@ fraction to select additional resident sessions up to the model-declared cap.
 All model-owned reservations are deducted before the paged self-attention pool
 is allocated.
 
-LingBot reports its persistent full-horizon image-condition tensor. DreamZero
-reports the measured 603 MiB per-session Wan VAE causal-convolution state.
+LingBot advances a session-owned causal Wan VAE encoder for each condition
+block: the opening pixel frame is followed by four zero pixel frames per later
+latent frame. It retains one current condition block, with separate committed
+and in-flight encoder histories so a failed block cannot overwrite committed
+context. The state reservation includes both encoder histories, derived from
+the encoder's convolution input grids, and the streaming decoder cache. These
+caches are released through the same close/reset hooks. Condition encoding
+currently requires the unpatched, non-tiled Wan encoder path; the existing
+decoder's tiling fallback remains independent. Real-weight GPU parity with a
+full-horizon encode still requires validation because the pointwise posterior
+projection now runs per block.
+
+DreamZero reports the measured 603 MiB per-session Wan VAE causal-convolution
+state.
 
 ## Concurrency and routing limits
 
diff --git a/examples/offline_inference/diffusion/ar_diffusion_streaming_decode.py b/examples/offline_inference/diffusion/ar_diffusion_streaming_decode.py
index 2aa326f6d7a..6c87d4e63ff 100644
--- a/examples/offline_inference/diffusion/ar_diffusion_streaming_decode.py
+++ b/examples/offline_inference/diffusion/ar_diffusion_streaming_decode.py
@@ -24,10 +24,9 @@
 
 ``--action-script`` is a JSON list with one camera action list per AR block,
 for example ``[[["w"], ["w"], ["w"]], [["a"], [], []]]`` for a checkpoint that
-generates three latent frames per block. The frames per block, the temporal
-compression and the number of blocks that fit the condition horizon are read
-off the checkpoint rather than assumed, so the script can be repointed with
-``--model``.
+generates three latent frames per block. The frames per block and temporal
+compression are read off the checkpoint rather than assumed, so the script
+can be repointed with ``--model``.
 """
 
 from __future__ import annotations
@@ -49,9 +48,6 @@
     import numpy as np
 
 _MODEL = "robbyant/lingbot-world-v2-14b-causal-fast-diffusers"
-# Mirrors _MAX_RAW_FRAMES in vllm_omni/diffusion/models/lingbot_world/pipeline.py:
-# the image-condition horizon is the pipeline's constant, not the checkpoint's.
-_MAX_RAW_FRAMES = 117
 
 
 def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
@@ -67,8 +63,8 @@ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
         "--action-script",
         required=True,
         help=(
-            "JSON file holding one camera action list per AR block. Both the per-block frame count "
-            "and the number of blocks that fit are read off the checkpoint, not assumed."
+            "JSON file holding one camera action list per AR block. "
+            "The per-block frame count is read off the checkpoint, not assumed."
         ),
     )
     parser.add_argument("--output-dir", required=True, help="Directory for decoded frames and metadata.")
@@ -154,12 +150,6 @@ def _validate_against_checkpoint(
                 f"--action-script block {block_index} holds {len(block)} frame action lists, but this "
                 f"checkpoint generates {frames_per_block} latent frames per AR block."
             )
-    max_chunks = ((_MAX_RAW_FRAMES - 1) // temporal_compression + 1) // frames_per_block
-    if len(script) > max_chunks:
-        raise ValueError(
-            f"--action-script holds {len(script)} blocks, but this checkpoint's "
-            f"{_MAX_RAW_FRAMES}-frame image-condition horizon fits at most {max_chunks}."
-        )
     return (len(script) * frames_per_block - 1) * temporal_compression + 1
 
 
diff --git a/examples/offline_inference/diffusion/lingbot_world_v2.py b/examples/offline_inference/diffusion/lingbot_world_v2.py
index 4bbea2f4f69..0eb2027b1a4 100644
--- a/examples/offline_inference/diffusion/lingbot_world_v2.py
+++ b/examples/offline_inference/diffusion/lingbot_world_v2.py
@@ -32,7 +32,6 @@
 _MODEL = "robbyant/lingbot-world-v2-14b-causal-fast-diffusers"
 _MAX_SEQUENCE_LENGTH = 512
 _MAX_PIXEL_AREA = 480 * 832
-_MAX_RAW_FRAMES = 117
 _MAX_SOURCE_CAMERA_FRAMES = 4096
 _TEMPORAL_COMPRESSION = 4
 _LATENT_FRAMES_PER_BLOCK = 3
@@ -191,8 +190,6 @@ def build_request(
         raise ValueError("--height * --width must not exceed 480 * 832 pixels.")
     if args.num_frames <= 0:
         raise ValueError("--num-frames must be a positive integer.")
-    if args.num_frames > _MAX_RAW_FRAMES:
-        raise ValueError("--num-frames must not exceed 117 raw frames.")
     if args.num_frames > paths.camera_frames:
         raise ValueError("Camera arrays must contain at least --num-frames frames.")
     if (args.num_frames - 1) % _TEMPORAL_COMPRESSION:
diff --git a/examples/offline_inference/diffusion/lingbot_world_v2_realtime.py b/examples/offline_inference/diffusion/lingbot_world_v2_realtime.py
index d98fe06f97b..f0f1043ab1a 100644
--- a/examples/offline_inference/diffusion/lingbot_world_v2_realtime.py
+++ b/examples/offline_inference/diffusion/lingbot_world_v2_realtime.py
@@ -1,13 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Run LingBot-World 2.0 as an in-process realtime AR-Diffusion session.
 
 This example exercises the internal session API. It is not a public HTTP or
 WebSocket protocol. Each JSONL event advances the world by one three-latent
-frame AR block and writes the latent plus its identity metadata. The current
-scoped implementation supports at most ten ticks per generation epoch because
-its image condition is bounded to 117 pixel frames; reset or create a session
-to start a new world.
+frame AR block and writes the latent plus its identity metadata. Session-owned
+causal VAE encoder state produces each condition block without retaining or
+repeating a full image-condition horizon.
 """
 
 from __future__ import annotations
@@ -24,8 +23,6 @@
 _MODEL = "robbyant/lingbot-world-v2-14b-causal-fast-diffusers"
 _CAMERA_ACTION_SCHEMA = "lingbot.camera_actions.v1"
 _FRAMES_PER_BLOCK = 3
-# ((117 pixel frames - 1) / VAE temporal factor 4 + 1) / 3 latent frames.
-_MAX_REALTIME_TICKS = 10
 
 
 def _camera_event_data(frames: list[list[str]]) -> dict[str, Any]:
@@ -41,7 +38,7 @@ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
     parser.add_argument(
         "--events",
         required=True,
-        help="JSONL file with one prompt/action event per AR block; at most 10 events.",
+        help="JSONL file with one prompt/action event per AR block.",
     )
     parser.add_argument("--output-dir", required=True, help="Directory for chunk latents and metadata.")
     parser.add_argument("--session-id", default="lingbot-world", help="Persistent world session identifier.")
@@ -84,12 +81,6 @@ def _load_events(path: Path) -> list[dict[str, Any]]:
         events.append({"event_id": event_id, "prompt": prompt, "frames": frames})
     if not events:
         raise ValueError("events file must contain at least one event.")
-    if len(events) > _MAX_REALTIME_TICKS:
-        raise ValueError(
-            "events file must contain at most "
-            f"{_MAX_REALTIME_TICKS} events because the current LingBot realtime "
-            "image-condition horizon is 117 pixel frames."
-        )
     event_ids = [event["event_id"] for event in events]
     if event_ids != sorted(set(event_ids)):
         raise ValueError("event_id values must be unique and strictly increasing.")
diff --git a/recipes/Robbyant/LingBot-World-2.0.md b/recipes/Robbyant/LingBot-World-2.0.md
index c38e24fd2ba..ab8c498fa3a 100644
--- a/recipes/Robbyant/LingBot-World-2.0.md
+++ b/recipes/Robbyant/LingBot-World-2.0.md
@@ -48,9 +48,11 @@ python examples/offline_inference/diffusion/lingbot_world_v2.py \
 ```
 
 The current causal-fast checkpoint uses four DMD sampling steps. Raw frame
-counts must be `9 + 12k`, up to 117 frames. Camera files may contain a
-longer bounded source trajectory (the official example contains 269 frames);
-the runtime consumes only the prefix needed by the request.
+counts must be `9 + 12k` for a non-negative integer `k`; for example, 129 frames
+produce eleven AR blocks. Both camera files must contain the same number of
+source frames, at least as many as requested and at most 4096. The runtime
+consumes only the prefix needed by the request. Longer rollouts also require
+sufficient device memory.
 
 ## Realtime in-process generation (deprecated)
 
diff --git a/tests/diffusion/models/lingbot_world/test_lingbot_world_camera.py b/tests/diffusion/models/lingbot_world/test_lingbot_world_camera.py
index 121364c074d..9cb67a1424d 100644
--- a/tests/diffusion/models/lingbot_world/test_lingbot_world_camera.py
+++ b/tests/diffusion/models/lingbot_world/test_lingbot_world_camera.py
@@ -8,6 +8,7 @@
 import subprocess
 import sys
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 import numpy as np
 import pytest
@@ -20,7 +21,10 @@
 sys.modules[_SPEC.name] = _CAMERA_MODULE
 _SPEC.loader.exec_module(_CAMERA_MODULE)
 
-CameraTrajectory = _CAMERA_MODULE.CameraTrajectory
+if TYPE_CHECKING:
+    from vllm_omni.diffusion.models.lingbot_world.camera import CameraTrajectory
+else:
+    CameraTrajectory = _CAMERA_MODULE.CameraTrajectory
 build_plucker_embedding = _CAMERA_MODULE.build_plucker_embedding
 interpolate_camera_trajectory = _CAMERA_MODULE.interpolate_camera_trajectory
 load_camera_trajectory = _CAMERA_MODULE.load_camera_trajectory
@@ -138,21 +142,20 @@ def test_load_camera_trajectory_rejects_object_dtype_before_materializing(tmp_pa
         load_camera_trajectory(_trusted(tmp_path))
 
 
-def test_load_camera_trajectory_accepts_official_length_and_materializes_request_prefix(tmp_path: Path) -> None:
-    _write_trajectory(
-        tmp_path,
-        _identity_poses(269),
-        np.arange(269 * 4, dtype=np.float32).reshape(269, 4),
-    )
+@pytest.mark.parametrize("num_frames", [129, 269, 4096])
+def test_load_camera_trajectory_preserves_all_bounded_source_frames(tmp_path: Path, num_frames: int) -> None:
+    poses = _identity_poses(num_frames)
+    poses[:, 0, 3] = np.arange(num_frames)
+    intrinsics = np.arange(num_frames * 4, dtype=np.float32).reshape(num_frames, 4)
+    _write_trajectory(tmp_path, poses, intrinsics)
 
     trajectory = load_camera_trajectory(_trusted(tmp_path))
 
-    assert trajectory.poses.shape == (117, 4, 4)
-    assert trajectory.intrinsics.shape == (117, 4)
-    np.testing.assert_array_equal(
-        trajectory.intrinsics.numpy(),
-        np.arange(269 * 4, dtype=np.float32).reshape(269, 4)[:117],
-    )
+    assert trajectory.poses.shape == (num_frames, 4, 4)
+    assert trajectory.intrinsics.shape == (num_frames, 4)
+    assert trajectory.poses.dtype == trajectory.intrinsics.dtype == torch.float32
+    np.testing.assert_array_equal(trajectory.poses.numpy(), poses.astype(np.float32))
+    np.testing.assert_array_equal(trajectory.intrinsics.numpy(), intrinsics)
 
 
 def test_load_camera_trajectory_rejects_unbounded_source_frame_count(tmp_path: Path) -> None:
diff --git a/tests/diffusion/models/lingbot_world/test_lingbot_world_transformer.py b/tests/diffusion/models/lingbot_world/test_lingbot_world_transformer.py
index b4bf7805fe3..96c0b37f10d 100644
--- a/tests/diffusion/models/lingbot_world/test_lingbot_world_transformer.py
+++ b/tests/diffusion/models/lingbot_world/test_lingbot_world_transformer.py
@@ -35,11 +35,13 @@ def _tiny_model(
     num_layers: int = 2,
     num_frames_per_block: int = 1,
     sliding_window_num_frames: int = 3,
+    attention_head_dim: int = 2,
+    rope_max_seq_len: int = 16,
 ):
     return module.CausalLingBotWorldTransformer3DModel(
         patch_size=(1, 2, 2),
         num_attention_heads=2,
-        attention_head_dim=2,
+        attention_head_dim=attention_head_dim,
         in_channels=36,
         out_channels=2,
         text_dim=6,
@@ -48,7 +50,7 @@ def _tiny_model(
         num_layers=num_layers,
         cross_attn_norm=True,
         eps=1e-6,
-        rope_max_seq_len=16,
+        rope_max_seq_len=rope_max_seq_len,
         sink_size=1,
         num_frames_per_block=num_frames_per_block,
         sliding_window_num_frames=sliding_window_num_frames,
@@ -121,7 +123,8 @@ def _assert_self_cache_unchanged(cache, snapshot) -> None:
 
 
 @pytest.mark.cpu
-def test_tiny_transformer_runs_four_chunks_with_explicit_cache_commit_and_camera_path() -> None:
+@pytest.mark.parametrize("num_chunks", [4, 18])
+def test_tiny_transformer_runs_contiguous_chunks_with_explicit_cache_commit_and_camera_path(num_chunks) -> None:
     torch.manual_seed(7)
     module = attention_tests._load_module()
     model = _tiny_model(module).eval()
@@ -135,7 +138,7 @@ def test_tiny_transformer_runs_four_chunks_with_explicit_cache_commit_and_camera
     assert model.patch_embedding.in_channels == 36
     assert model.patch_embedding_wancamctrl.in_features == 6 * 8 * 8 * 1 * 2 * 2
 
-    for start_frame in range(4):
+    for start_frame in range(num_chunks):
         hidden_states = torch.randn(1, 36, 1, 4, 4)
         timestep = torch.tensor([float(start_frame + 1)])
         snapshot = _self_cache_snapshot(cache)
@@ -169,7 +172,7 @@ def test_tiny_transformer_runs_four_chunks_with_explicit_cache_commit_and_camera
         expected_token_end = (start_frame + 1) * 2 * 2
         assert all(layer_cache.absolute_end == expected_token_end for layer_cache in cache.self_attention)
 
-    assert len(outputs) == 4
+    assert len(outputs) == num_chunks
     assert all(len(outputs) == 1 for outputs in cross_key_outputs)
     assert len(text_projection_outputs) == 1
 
@@ -991,3 +994,42 @@ def test_sp4_direct_matches_sp1_bf16(tmp_path):
 @hardware_test(res={"cuda": "L4"}, num_cards=4)
 def test_tp2_sp2_paged_matches_sp1_bf16(tmp_path):
     _run(tmp_path, 2, 2, "paged", torch.bfloat16, 1)
+
+
+@pytest.mark.cpu
+@pytest.mark.parametrize("start_frame", [0, 1021, 1023, 1024, 21600])
+@pytest.mark.parametrize("dtype", [torch.float32, torch.bfloat16])
+def test_temporal_rope_matches_absolute_positions_without_growing_cache(start_frame, dtype):
+    module = attention_tests._load_module()
+    model = _tiny_model(module, num_layers=1, attention_head_dim=128, rope_max_seq_len=1024).to(dtype)
+    buffers = {name: (value.data_ptr(), value.shape) for name, value in model.named_buffers()}
+    cosine, sine = model._rotary_embedding(
+        frames=3, height=2, width=3, start_frame=start_frame, dtype=dtype, device=torch.device("cpu")
+    )
+    # Independent complex-valued reference uses absolute (time, height, width)
+    # coordinates, including blocks crossing the original precomputed table.
+    grids = torch.meshgrid(
+        torch.arange(start_frame, start_frame + 3, dtype=torch.float64),
+        torch.arange(2, dtype=torch.float64),
+        torch.arange(3, dtype=torch.float64),
+        indexing="ij",
+    )
+    reference = []
+    for positions, dim in zip(grids, (44, 42, 42), strict=True):
+        frequencies = 1.0 / 10000 ** (torch.arange(0, dim, 2, dtype=torch.float64) / dim)
+        phase = positions.flatten()[:, None] * frequencies[None, :]
+        reference.append(torch.polar(torch.ones_like(phase), phase))
+    expected = torch.cat(reference, dim=-1)
+    torch.testing.assert_close(cosine, expected.real.float().to(dtype), rtol=0, atol=0)
+    torch.testing.assert_close(sine, expected.imag.float().to(dtype), rtol=0, atol=0)
+    assert {name: (value.data_ptr(), value.shape) for name, value in model.named_buffers()} == buffers
+
+
+@pytest.mark.cpu
+def test_temporal_rope_extension_keeps_spatial_limit():
+    module = attention_tests._load_module()
+    model = _tiny_model(module, num_layers=1)
+    with pytest.raises(ValueError, match="Spatial RoPE"):
+        model._rotary_embedding(
+            frames=3, height=17, width=1, start_frame=16, dtype=torch.float32, device=torch.device("cpu")
+        )
diff --git a/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py b/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py
index 86d8e70b8d1..fb9e93a5d55 100644
--- a/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py
+++ b/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py
@@ -198,10 +198,43 @@ def __call__(self, x: torch.Tensor, *, feat_cache, feat_idx, first_chunk: bool =
         return x.new_zeros(x.shape[0], 3, num_frames, x.shape[-2] * 8, x.shape[-1] * 8)
 
 
+class _StubCausalEncoder(nn.Module):
+    """Minimal Wan cache layout; the real tiny VAE below checks numerical parity."""
+
+    def __init__(self):
+        super().__init__()
+        self.conv_in = nn.Conv3d(3, 16, 1)
+        self.down_blocks = nn.ModuleList([lingbot_pipeline.WanResample(16, mode="downsample2d") for _ in range(3)])
+        self.mid_block = SimpleNamespace(resnets=[])
+        self.conv_out = nn.Conv3d(16, 32, 1)
+        self.inputs: list[torch.Tensor] = []
+
+    def forward(self, video, *, feat_cache, feat_idx):
+        self.inputs.append(video.detach().clone())
+        first = feat_cache[0] is None
+        tail = video[:, :, -2:].clone()
+        if tail.shape[2] == 1 and feat_cache[0] is not None:
+            tail = torch.cat((feat_cache[0][:, :, -1:], tail), dim=2)
+        feat_cache[0] = tail
+        height, width = video.shape[-2] // 8, video.shape[-1] // 8
+        previous_frames = 0 if feat_cache[1] is None else feat_cache[1].shape[2]
+        feat_cache[1] = video.new_zeros(1, 16, min(2, previous_frames + 1), height, width)
+        feat_idx[0] += 2
+        moments = video.new_zeros(1, 32, 1, height, width)
+        if first:
+            moments[:, :16] = 2.0
+        return moments
+
+
 class _StubVAE(_FakePretrained):
     dtype = torch.float32
 
     def __init__(self, *, streaming: bool = True):
+        self.encoder = _StubCausalEncoder()
+        self.quant_conv = nn.Identity()
+        self._cached_conv_counts = {"encoder": 2}
+        self._enc_feat_map = ["module-owned"]
+        self._enc_conv_idx = [71]
         if streaming:
             self.decoder = _StubCausalDecoder()
             # Recorded, not discarded: on the streaming branch this is the only
@@ -209,7 +242,7 @@ def __init__(self, *, streaming: bool = True):
             # what carries the checkpoint's latent rescale.
             self.post_quant_inputs: list[torch.Tensor] = []
             self.post_quant_conv = self._record_post_quant
-            self._cached_conv_counts = {"decoder": _StubCausalDecoder.NUM_CONVS, "encoder": 2}
+            self._cached_conv_counts["decoder"] = _StubCausalDecoder.NUM_CONVS
             # Module-owned cache the shared VAE keeps for whole-clip decode;
             # streaming must never write through it.
             self._feat_map = ["module-owned"]
@@ -498,16 +531,14 @@ def test_ar_diffusion_capability_uses_transformer_local_head_geometry() -> None:
     assert spec.sink_frames == 3
     assert [(branch.name, branch.local_index) for branch in spec.kv_branches] == [("main", 0)]
     assert spec.cross_attention_lengths == {"text": 512}
-    # The image condition (9,600 B) plus the streaming decoder's own per-session
-    # temporal cache. The cache dwarfs the condition at any real resolution, and
-    # the runner subtracts this field from the KV budget before sizing its pools,
-    # so leaving the cache out of it over-commits device memory.
-    assert spec.model_owned_state_bytes_per_session == 9_600 + 2_421_248
+    # One condition block, committed + pending encoder caches, and decoder state.
+    # The stub encoder retains 2 RGB frames at 16x16 and 2 feature frames at 2x2.
+    encoder_bytes = (2 * 3 * 16 * 16 + 2 * 16 * 2 * 2) * 4
+    assert spec.model_owned_state_bytes_per_session == 960 + 2 * encoder_bytes + 2_421_248
 
 
 def test_session_admission_accounts_for_the_streaming_decoder_cache() -> None:
-    """The declaration scales with output area, and is the condition alone when
-    the VAE cannot stream."""
+    """Admission includes encoder state even when the decoder cannot stream."""
     module = _load_pipeline_module()
 
     def spec_pipeline():
@@ -526,13 +557,13 @@ def spec_pipeline():
     # than the image condition alone could account for.
     assert widened - small > 2_000_000
 
-    # A VAE without the causal-cache contract cannot stream, so there is no
-    # decoder cache to declare and the figure falls back to the condition.
+    # Removing decoder support leaves the condition and both encoder histories.
     bare = spec_pipeline()
-    for attribute in ("decoder", "post_quant_conv", "_cached_conv_counts"):
+    for attribute in ("decoder", "post_quant_conv"):
         if hasattr(bare.vae, attribute):
             delattr(bare.vae, attribute)
-    assert bare.ar_diffusion_kv_cache_spec().model_owned_state_bytes_per_session == 9_600
+    bare.vae._cached_conv_counts.pop("decoder")
+    assert bare.ar_diffusion_kv_cache_spec().model_owned_state_bytes_per_session == 960 + 2 * 6_656
 
 
 def test_preprocess_materializes_external_inputs_before_worker_execution(tmp_path: Path) -> None:
@@ -1200,20 +1231,19 @@ def test_request_validation_rejects_unsupported_contracts(request_batch, message
         _pipeline(module)._parse_request(request_batch)
 
 
-def test_resource_limits_accept_exact_documented_boundaries() -> None:
+def test_request_validation_accepts_frames_beyond_previous_limit() -> None:
     module = _load_pipeline_module()
-    sampling = _SamplingParams(height=480, width=832, num_frames=117, max_sequence_length=512)
+    sampling = _SamplingParams(height=480, width=832, num_frames=129, max_sequence_length=512)
 
     parsed = _pipeline(module)._parse_request(_RequestBatch(_prompt(), sampling))
 
-    assert (parsed.height, parsed.width, parsed.num_frames, parsed.max_sequence_length) == (480, 832, 117, 512)
+    assert (parsed.height, parsed.width, parsed.num_frames, parsed.max_sequence_length) == (480, 832, 129, 512)
 
 
 @pytest.mark.parametrize(
     ("sampling", "message"),
     [
         (_SamplingParams(height=480, width=848), "pixel area|480.*832"),
-        (_SamplingParams(num_frames=129), "num_frames.*117"),
         (_SamplingParams(max_sequence_length=511), "max_sequence_length.*512"),
         (_SamplingParams(max_sequence_length=513), "max_sequence_length.*512"),
         (_SamplingParams(max_sequence_length=512.0), "max_sequence_length.*512"),
@@ -1550,9 +1580,9 @@ def allocate(**kwargs):
     assert cache_ref() is None
 
 
-def _tick_extra_args(*, chunk_index: int, prompt: str = "move through the room"):
+def _tick_extra_args(*, chunk_index: int, prompt: str = "move through the room", session_id: str = "world-1"):
     return ARDiffusionTickRequest(
-        session_id="world-1",
+        session_id=session_id,
         request_id="legacy-lingbot-request",
         chunk_index=chunk_index,
         applied_event_ids=(chunk_index,),
@@ -1567,6 +1597,16 @@ def _tick_extra_args(*, chunk_index: int, prompt: str = "move through the room")
     ).to_extra_args()
 
 
+def test_realtime_rejects_pixel_output_before_condition_encoding() -> None:
+    pipeline = _pipeline(_load_pipeline_module())
+    pipeline._ar_diffusion_kv_state = object()
+    sampling = _SamplingParams(output_type="np", extra_args=_tick_extra_args(chunk_index=0))
+    with pytest.raises(ValueError, match="require output_type='latent'"):
+        pipeline(_request(sampling=sampling))
+    assert pipeline._ar_sessions == {}
+    assert pipeline.vae.encoder.inputs == []
+
+
 def test_typed_ticks_generate_one_global_block_and_return_standard_metadata(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
@@ -1769,7 +1809,7 @@ def test_typed_tick_rejects_non_contiguous_chunk_index(
         pipeline(_request(sampling=sampling))
 
 
-def test_typed_tick_rejects_chunk_beyond_realtime_condition_horizon(
+def test_typed_ticks_keep_bounded_encoder_state_beyond_ten_chunks(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     module = _load_pipeline_module()
@@ -1777,22 +1817,229 @@ def test_typed_tick_rejects_chunk_beyond_realtime_condition_horizon(
     pipeline._ar_height = 16
     pipeline._ar_width = 16
     pipeline._ar_diffusion_kv_state = object()
-    pipeline._ar_sessions["world-1"] = module._LingBotARSessionState(
-        next_chunk_index=10,
-    )
+    generated = []
     monkeypatch.setattr(
         pipeline,
-        "encode_prompt",
-        lambda *args, **kwargs: pytest.fail("the realtime horizon must be validated before prompt encoding"),
+        "_ar_text_caches",
+        lambda *args, **kwargs: [SimpleNamespace()],
     )
 
-    sampling = _SamplingParams(extra_args=_tick_extra_args(chunk_index=10))
-    with pytest.raises(
-        ValueError,
-        match=r"at most 10 ticks.*chunk_index 0 through 9.*117 pixel frames",
-    ):
+    def generate_block(**kwargs):
+        generated.append(
+            {
+                "condition": kwargs["condition"].clone(),
+                "start_frame": kwargs["start_frame"],
+            }
+        )
+        return torch.zeros_like(kwargs["condition"][:, :16])
+
+    monkeypatch.setattr(pipeline, "_generate_block", generate_block)
+
+    for chunk_index in range(11):
+        sampling = _SamplingParams(
+            extra_args=_tick_extra_args(chunk_index=chunk_index),
+        )
         pipeline(_request(sampling=sampling))
 
+    assert pipeline.vae.encode_inputs == []
+    assert [video.shape[2] for video in pipeline.vae.encoder.inputs] == [1] + [4] * 32
+    assert all(torch.count_nonzero(video) == 0 for video in pipeline.vae.encoder.inputs[1:])
+    encoder_cache = pipeline._ar_sessions["world-1"].encoder_cache
+    assert sum(t.numel() * t.element_size() for t in encoder_cache) == pipeline._condition_encoder_cache_bytes()
+    assert pipeline.vae._enc_feat_map == ["module-owned"]
+    assert pipeline.vae._enc_conv_idx == [71]
+    assert pipeline._ar_sessions["world-1"].next_chunk_index == 11
+    assert [item["start_frame"] for item in generated] == list(range(0, 33, 3))
+    assert torch.count_nonzero(generated[0]["condition"][:, :4]) > 0
+    torch.testing.assert_close(
+        generated[1]["condition"][:, :4],
+        torch.zeros_like(generated[1]["condition"][:, :4]),
+    )
+    for item in generated[2:]:
+        torch.testing.assert_close(item["condition"], generated[1]["condition"])
+
+
+def _tiny_condition_pipeline(monkeypatch: pytest.MonkeyPatch):
+    from diffusers import AutoencoderKLWan
+
+    from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import retrieve_latents
+
+    pipeline = _pipeline(_load_pipeline_module())
+    with torch.random.fork_rng(devices=[]):
+        torch.manual_seed(7)
+        pipeline.vae = AutoencoderKLWan(
+            base_dim=4,
+            z_dim=16,
+            dim_mult=[1, 1, 1, 1],
+            num_res_blocks=1,
+            temperal_downsample=[False, True, True],
+        ).eval()
+    monkeypatch.setattr(lingbot_pipeline, "retrieve_latents", retrieve_latents)
+    monkeypatch.setattr(pipeline, "_ar_text_caches", lambda *args, **kwargs: [SimpleNamespace()])
+    return pipeline
+
+
+@pytest.mark.parametrize("mode", ["realtime", "stepwise"])
+def test_condition_continues_real_causal_vae_beyond_initial_horizon(
+    monkeypatch: pytest.MonkeyPatch,
+    mode: str,
+) -> None:
+    pipeline = _tiny_condition_pipeline(monkeypatch)
+    blocks = 12
+    inputs = pipeline._parse_request(_request(sampling=_SamplingParams(num_frames=(blocks * 3 - 1) * 4 + 1)))
+    with torch.inference_mode():
+        expected = pipeline._prepare_condition(inputs, dtype=torch.float32)
+    module_cache = pipeline.vae._enc_feat_map
+    seen = []
+
+    def check(condition):
+        index = len(seen)
+        torch.testing.assert_close(condition, expected[:, :, index * 3 : (index + 1) * 3], rtol=1e-6, atol=1e-6)
+        seen.append(condition.clone())
+
+    if mode == "realtime":
+        pipeline._ar_diffusion_kv_state = object()
+
+        def generate_block(**kwargs):
+            check(kwargs["condition"])
+            return torch.zeros_like(kwargs["condition"][:, :16])
+
+        monkeypatch.setattr(pipeline, "_generate_block", generate_block)
+        session_id = "world-1"
+        outputs = (
+            pipeline(_request(sampling=_SamplingParams(extra_args=_tick_extra_args(chunk_index=index))))
+            for index in range(blocks)
+        )
+    else:
+
+        def probe_step(**kwargs):
+            if kwargs["step_index"] == 0:
+                check(kwargs["condition"])
+            return torch.ones_like(kwargs["current_latents"])
+
+        monkeypatch.setattr(pipeline._dmd_blocks, "probe_step", probe_step)
+        monkeypatch.setattr(pipeline._dmd_blocks, "commit_block_kv", lambda **kwargs: None)
+        state = _stepwise_state(num_frames=(blocks * 3 - 1) * 4 + 1)
+        session_id = state.request_id
+        outputs = _stepwise_chunks(pipeline, state, _FakeARState(session_id))
+
+    cache_sizes = []
+    for _ in outputs:
+        state = pipeline._ar_sessions.get(session_id)
+        if state is not None:
+            for cache in (state.encoder_cache, state.pending_encoder_cache):
+                if cache is not None:
+                    size = sum(t.numel() * t.element_size() for t in cache if t is not None)
+                    assert size == pipeline._condition_encoder_cache_bytes()
+                    assert all(t.grad_fn is None for t in cache if t is not None)
+                    cache_sizes.append(size)
+    assert len(seen) == blocks and len(set(cache_sizes)) == 1
+    assert pipeline.vae._enc_feat_map is module_cache and all(t is None for t in module_cache)
+    pipeline.close_ar_diffusion_session(session_id)
+    assert pipeline._ar_sessions == {}
+
+
+def test_condition_encoder_interleaving_retry_and_reset(monkeypatch: pytest.MonkeyPatch) -> None:
+    pipeline = _tiny_condition_pipeline(monkeypatch)
+    pipeline._ar_diffusion_kv_state = object()
+    prompts = {
+        "a": _prompt(images=Image.new("RGB", (16, 16), (255, 0, 0))),
+        "b": _prompt(images=Image.new("RGB", (16, 16), (0, 255, 0))),
+    }
+    expected = {}
+    with torch.inference_mode():
+        for name, prompt in prompts.items():
+            inputs = pipeline._parse_request(_request(prompt=prompt, sampling=_SamplingParams(num_frames=45)))
+            expected[name] = pipeline._prepare_condition(inputs, dtype=torch.float32)
+    assert not torch.equal(expected["a"], expected["b"])
+    active = None
+    failure = None
+    original_encoder = pipeline.vae.encoder.forward
+
+    def encoder(*args, **kwargs):
+        output = original_encoder(*args, **kwargs)
+        if failure == "encoder":
+            raise RuntimeError("injected encoder failure")
+        return output
+
+    def generate_block(**kwargs):
+        index = kwargs["start_frame"]
+        torch.testing.assert_close(kwargs["condition"], expected[active][:, :, index : index + 3], rtol=1e-6, atol=1e-6)
+        if failure == "dit":
+            raise RuntimeError("injected DiT failure")
+        return torch.zeros_like(kwargs["condition"][:, :16])
+
+    monkeypatch.setattr(pipeline.vae.encoder, "forward", encoder)
+    monkeypatch.setattr(pipeline, "_generate_block", generate_block)
+
+    def run(name, index):
+        nonlocal active
+        active = name
+        sampling = _SamplingParams(extra_args=_tick_extra_args(chunk_index=index, session_id=name))
+        return pipeline(_request(prompt=prompts[name], sampling=sampling))
+
+    run("a", 0)
+    for index, kind in [(1, "encoder"), (2, "dit")]:
+        state = pipeline._ar_sessions["a"]
+        committed = state.encoder_cache
+        saved = [t.clone() if t is not None else None for t in committed]
+        failure = kind
+        with pytest.raises(RuntimeError, match="injected"):
+            run("a", index)
+        assert state.next_chunk_index == index and state.encoder_cache is committed
+        assert state.pending_encoder_cache is None
+        for before, after in zip(saved, committed, strict=True):
+            if before is not None:
+                torch.testing.assert_close(before, after, rtol=0, atol=0)
+        failure = None
+        run("b", index - 1)
+        run("a", index)
+
+    old_a = pipeline._ar_sessions["a"]
+    pipeline.reset_ar_diffusion_session("a")
+    assert old_a.encoder_cache is None and old_a.pending_encoder_cache is None
+    assert "a" not in pipeline._ar_sessions and "b" in pipeline._ar_sessions
+    run("a", 0)
+    old_b = pipeline._ar_sessions["b"]
+    pipeline.close_ar_diffusion_session("b")
+    assert old_b.encoder_cache is None and old_b.pending_encoder_cache is None
+    assert "a" in pipeline._ar_sessions and "b" not in pipeline._ar_sessions
+    pipeline.close_ar_diffusion_session("a")
+    assert pipeline._ar_sessions == {}
+
+
+def test_stepwise_failed_chunk_releases_pending_encoder_on_close(monkeypatch: pytest.MonkeyPatch) -> None:
+    pipeline = _pipeline(_load_pipeline_module())
+    state = _stepwise_state()
+    transformer = pipeline.transformer
+    transformer.raise_on_call = 1
+    with pipeline.bind_ar_diffusion_state(state.request_id, _FakeARState(state.request_id)):
+        pipeline.prepare_encode(state)
+        session = pipeline._ar_sessions[state.request_id]
+        assert session.encoder_cache is None and session.pending_encoder_cache is not None
+        with pytest.raises(RuntimeError, match="forced transformer failure"):
+            pipeline.denoise_step(None, states=[state])
+        assert session.next_chunk_index == 0 and session.encoder_cache is None
+    pipeline.close_ar_diffusion_session(state.request_id)
+    assert session.encoder_cache is None and session.pending_encoder_cache is None
+    assert state.request_id not in pipeline._ar_sessions
+
+
+@pytest.mark.parametrize("mode", ["realtime", "stepwise"])
+def test_stateful_condition_rejects_tiled_encoder(monkeypatch: pytest.MonkeyPatch, mode: str) -> None:
+    pipeline = _pipeline(_load_pipeline_module())
+    _enable_vae_tiling(pipeline, tile_sample_min=8)
+    with pytest.raises(ValueError, match="does not support tiled VAE encoding"):
+        if mode == "realtime":
+            pipeline._ar_diffusion_kv_state = object()
+            pipeline(_request(sampling=_SamplingParams(extra_args=_tick_extra_args(chunk_index=0))))
+        else:
+            state = _stepwise_state()
+            with pipeline.bind_ar_diffusion_state(state.request_id, _FakeARState(state.request_id)):
+                pipeline.prepare_encode(state)
+    assert pipeline.vae.encoder.inputs == []
+    assert all(s.encoder_cache is None and s.pending_encoder_cache is None for s in pipeline._ar_sessions.values())
+
 
 def test_request_cache_is_released_before_vae_decode() -> None:
     module = _load_pipeline_module()
@@ -1820,25 +2067,25 @@ def assert_cache_released() -> None:
     assert result.output.shape[2] == 21
 
 
-def test_117_frame_request_generates_ten_complete_latent_blocks() -> None:
+def test_129_frame_request_generates_eleven_complete_latent_blocks() -> None:
     module = _load_pipeline_module()
     transformer = _RecordingTransformer()
     pipeline = _pipeline(module, transformer=transformer)
     trajectory = _CameraTrajectory(
-        poses=torch.eye(4).repeat(117, 1, 1),
-        intrinsics=torch.tensor([[100.0, 100.0, 8.0, 8.0]]).repeat(117, 1),
+        poses=torch.eye(4).repeat(129, 1, 1),
+        intrinsics=torch.tensor([[100.0, 100.0, 8.0, 8.0]]).repeat(129, 1),
     )
     sampling = _SamplingParams(
-        num_frames=117,
+        num_frames=129,
         output_type="latent",
         extra_args={"_lingbot_camera_trajectory": trajectory},
     )
 
     result = pipeline(_request(sampling=sampling))
 
-    assert result.output.shape == (1, 16, 30, 2, 2)
-    assert len(transformer.calls) == 50
-    assert [call["start_frame"] for call in transformer.calls[::5]] == list(range(0, 30, 3))
+    assert result.output.shape == (1, 16, 33, 2, 2)
+    assert len(transformer.calls) == 55
+    assert [call["start_frame"] for call in transformer.calls[::5]] == list(range(0, 33, 3))
 
 
 def test_request_cache_becomes_unreachable_after_transformer_error() -> None:
@@ -2030,13 +2277,14 @@ def test_stepwise_progress_metadata_and_commit_trace() -> None:
         assert output.output["payload"]["latents"].shape == (1, 16, 3, 2, 2)
 
 
-def test_stepwise_matches_tick_transformer_trace_and_latents() -> None:
+@pytest.mark.parametrize("num_chunks", [2, 12])
+def test_stepwise_matches_tick_transformer_trace_and_latents(num_chunks) -> None:
     module = _load_pipeline_module()
     transformer = _RecordingTransformer()
     pipeline = _pipeline(module, transformer=transformer)
     pipeline._ar_height = 16
     pipeline._ar_width = 16
-    script = ((("w",), ("w",), ("w",)), (("d",), ("d",), ("d",)))
+    script = ((("w",), ("w",), ("w",)), (("d",), ("d",), ("d",))) * (num_chunks // 2)
     fake = _FakeARState("world-1")
 
     with pipeline.bind_ar_diffusion_state("world-1", fake):
@@ -2063,7 +2311,7 @@ def test_stepwise_matches_tick_transformer_trace_and_latents() -> None:
     transformer.calls.clear()
     pipeline.close_ar_diffusion_session("world-1")
 
-    stepwise_state = _stepwise_state(request_id="req-1", num_frames=21, script=script, seed=17)
+    stepwise_state = _stepwise_state(request_id="req-1", num_frames=12 * num_chunks - 3, script=script, seed=17)
     stepwise_fake = _FakeARState(stepwise_state.request_id)
     with pipeline.bind_ar_diffusion_state(stepwise_state.request_id, stepwise_fake):
         stepwise_outputs = _run_stepwise(pipeline, stepwise_state)
@@ -2072,6 +2320,15 @@ def test_stepwise_matches_tick_transformer_trace_and_latents() -> None:
     assert [call["start_frame"] for call in transformer.calls] == [call["start_frame"] for call in tick_calls]
     for tick_latent, output in zip(tick_latents, stepwise_outputs, strict=True):
         torch.testing.assert_close(output.output["payload"]["latents"], tick_latent)
+    for step_call, tick_call in zip(transformer.calls, tick_calls, strict=True):
+        torch.testing.assert_close(step_call["hidden_states"], tick_call["hidden_states"])
+        torch.testing.assert_close(step_call["camera_hidden_states"], tick_call["camera_hidden_states"])
+    assert stepwise_state.extra["condition"].shape[2] == 3
+    assert pipeline.vae.encode_inputs == []
+    assert [video.shape[2] for video in pipeline.vae.encoder.inputs] == ([1] + [4] * (num_chunks * 3 - 1)) * 2
+    assert stepwise_fake.commits == ["main"] * num_chunks
+    assert len(stepwise_outputs) == num_chunks and stepwise_outputs[-1].finished
+    assert pipeline.vae.decode_inputs == []
 
 
 def test_stepwise_trajectory_camera_matches_request_mode_under_non_uniform_speed(monkeypatch) -> None:
@@ -2387,6 +2644,7 @@ def test_streaming_decode_is_reported_to_the_profiler(monkeypatch) -> None:
     durations = pipeline.stage_durations
     assert stage in durations, f"streamed decode is unprofiled; stages seen: {sorted(durations)}"
     assert durations[stage] > 0.0
+    assert durations[f"{type(pipeline).__name__}._prepare_condition_chunk"] > 0.0
     # The stage reaches the consumer on every streamed chunk, not just at the end.
     assert all(stage in (output.stage_durations or {}) for output in outputs)
 
@@ -2398,11 +2656,10 @@ def test_streaming_decode_falls_back_when_the_vae_would_tile(monkeypatch) -> Non
     pipeline = _streaming_pipeline(module)
     # A latent of 2x2 exceeds a one-latent-cell tile, so vae.decode would tile.
     _enable_vae_tiling(pipeline, tile_sample_min=8)
-    state = _stepwise_state(num_frames=21)
-    state.sampling.output_type = "np"
-
-    with pipeline.bind_ar_diffusion_state(state.request_id, _FakeARState(state.request_id)):
-        outputs = _run_stepwise(pipeline, state)
+    outputs = [
+        pipeline._decode_chunk_to_pixels(torch.zeros(1, 16, 3, 2, 2), output_type="np", session_id="tiled")
+        for _ in range(2)
+    ]
 
     # One whole-clip decode per AR block, each seeing only that block's frames.
     assert [tuple(latents.shape) for latents in pipeline.vae.decode_inputs] == [(1, 16, 3, 2, 2)] * 2
@@ -2410,7 +2667,7 @@ def test_streaming_decode_falls_back_when_the_vae_would_tile(monkeypatch) -> Non
     assert pipeline._streaming_decode_states == {}
     # Nine frames per chunk instead of 9 then 12: the frame loss being removed.
     assert [shape for shape, _ in processed] == [(1, 3, 9, 16, 16), (1, 3, 9, 16, 16)]
-    assert [output.output["payload"] for output in outputs] == [{"video": "frames-1"}, {"video": "frames-2"}]
+    assert outputs == ["frames-1", "frames-2"]
 
 
 def test_streaming_decode_survives_tiling_enabled_below_the_tile_threshold(monkeypatch) -> None:
diff --git a/tests/examples/offline_inference/test_lingbot_world_v2.py b/tests/examples/offline_inference/test_lingbot_world_v2.py
index 41d2e73b712..d8328885320 100644
--- a/tests/examples/offline_inference/test_lingbot_world_v2.py
+++ b/tests/examples/offline_inference/test_lingbot_world_v2.py
@@ -1,10 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
+import json
 from pathlib import Path
 
 import pytest
 
+from examples.offline_inference.diffusion import ar_diffusion_streaming_decode as streaming_example
 from examples.offline_inference.diffusion import lingbot_world_v2 as example
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
@@ -22,3 +24,25 @@ def test_offline_ulysses_argument(tmp_path):
     args.ulysses_degree = 0
     with pytest.raises(ValueError, match="--ulysses-degree"):
         example.build_omni_kwargs(args, paths)
+
+
+@pytest.mark.parametrize(("num_blocks", "num_frames"), [(10, 117), (11, 129)])
+def test_streaming_action_script_accepts_long_rollouts(tmp_path, num_blocks, num_frames):
+    action_script = tmp_path / "actions.json"
+    action_script.write_text(json.dumps([[["w"], [], ["a"]] for _ in range(num_blocks)]))
+
+    script = streaming_example._load_action_script(action_script)
+
+    assert len(script) == num_blocks
+    assert (
+        streaming_example._validate_against_checkpoint(script, frames_per_block=3, temporal_compression=4) == num_frames
+    )
+
+
+def test_streaming_action_script_rejects_wrong_frame_count_in_eleventh_block(tmp_path):
+    action_script = tmp_path / "actions.json"
+    action_script.write_text(json.dumps([[[], [], []] for _ in range(10)] + [[[], []]]))
+    script = streaming_example._load_action_script(action_script)
+
+    with pytest.raises(ValueError, match="block 10 holds 2 frame action lists"):
+        streaming_example._validate_against_checkpoint(script, frames_per_block=3, temporal_compression=4)
diff --git a/vllm_omni/diffusion/models/lingbot_world/camera.py b/vllm_omni/diffusion/models/lingbot_world/camera.py
index 0e78e53e6ca..504d850c74c 100644
--- a/vllm_omni/diffusion/models/lingbot_world/camera.py
+++ b/vllm_omni/diffusion/models/lingbot_world/camera.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Camera trajectory loading and geometry for LingBot World v2 conditioning."""
 
 from __future__ import annotations
@@ -19,7 +19,6 @@
 
 _REFERENCE_HEIGHT = 480
 _REFERENCE_WIDTH = 832
-_MAX_ACTION_FRAMES = 117
 _MAX_SOURCE_ACTION_FRAMES = 4096
 _MAX_NPY_HEADER_BYTES = 10_000
 _DIRECTORY_OPEN_FLAGS = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
@@ -207,9 +206,7 @@ def _load_bounded_npy(
             array = np.load(snapshot_file, allow_pickle=False)
         except (EOFError, TypeError, ValueError):
             raise ValueError(f"{filename} does not contain a valid numeric NPY array.") from None
-    # Official LingBot trajectories may be longer than one request. Only
-    # materialize the bounded prefix that any supported request can consume.
-    result: np.ndarray = np.asarray(array[:_MAX_ACTION_FRAMES], dtype=np.float32)
+    result: np.ndarray = np.asarray(array, dtype=np.float32)
     return result
 
 
diff --git a/vllm_omni/diffusion/models/lingbot_world/pipeline.py b/vllm_omni/diffusion/models/lingbot_world/pipeline.py
index 6e32844fcb1..ccaa677e069 100644
--- a/vllm_omni/diffusion/models/lingbot_world/pipeline.py
+++ b/vllm_omni/diffusion/models/lingbot_world/pipeline.py
@@ -7,7 +7,7 @@
 import math
 import os
 from collections.abc import Callable, Iterable, Iterator, Sequence
-from contextlib import contextmanager
+from contextlib import contextmanager, nullcontext
 from dataclasses import dataclass, replace
 from typing import TYPE_CHECKING, Any, ClassVar, cast
 
@@ -15,6 +15,7 @@
 import PIL.Image
 import torch
 import torch.nn.functional as F
+from diffusers.models.autoencoders.autoencoder_kl_wan import CACHE_T, WanAttentionBlock, WanResample, WanResidualBlock
 from diffusers.utils.torch_utils import randn_tensor
 from torch import nn
 from transformers import AutoTokenizer, UMT5EncoderModel
@@ -97,7 +98,6 @@
 _CAMERA_SPATIAL_FOLD = 8
 _MAX_PIXEL_AREA = 480 * 832
 _MAX_SOURCE_IMAGE_PIXELS = 4096 * 4096
-_MAX_RAW_FRAMES = 117
 _MAX_SEQUENCE_LENGTH = 512
 _ACTION_ROOT_ENV = "VLLM_OMNI_LINGBOT_ACTION_ROOT"
 _PREPROCESSED_CAMERA_KEY = "_lingbot_camera_trajectory"
@@ -150,12 +150,13 @@ class _LingBotRequestInputs:
 
 @dataclass
 class _LingBotARSessionState:
-    """Small model-owned state; attention tensors remain runner-owned."""
+    """Model-owned state; attention tensors remain runner-owned."""
 
     next_chunk_index: int = 0
     prompt: str | None = None
     generator_state: torch.Tensor | None = None
-    image_condition: torch.Tensor | None = None
+    encoder_cache: list[torch.Tensor | None] | None = None
+    pending_encoder_cache: list[torch.Tensor | None] | None = None
     camera_tail: CameraTrajectory | None = None
     camera_pitch: float = 0.0
 
@@ -577,6 +578,7 @@ def __init__(
         self.setup_diffusion_pipeline_profiler(
             profiler_targets=[
                 "vae.encode",
+                "_prepare_condition_chunk",
                 "vae.decode",
                 # Streaming decode never reaches vae.decode, so it needs its
                 # own stage or a streamed rollout reports no decode time at
@@ -609,11 +611,11 @@ def ar_diffusion_kv_cache_spec(self) -> ARDiffusionKVCacheSpec:
         recent_window_frames = total_window_frames - sink_frames
         if recent_window_frames <= 0:
             raise ValueError("LingBot AR-Diffusion cache needs a positive recent window after reserving sink frames.")
-        horizon_latent_frames = (_MAX_RAW_FRAMES - 1) // self.vae_scale_factor_temporal + 1
+        condition_latent_frames = int(self.transformer.config.num_frames_per_block)
         condition_channels = self.vae_scale_factor_temporal + int(self.transformer.config.out_channels)
         condition_bytes_per_session = (
             condition_channels
-            * horizon_latent_frames
+            * condition_latent_frames
             * latent_height
             * latent_width
             * torch.empty((), dtype=self.transformer.dtype).element_size()
@@ -635,10 +637,34 @@ def ar_diffusion_kv_cache_spec(self) -> ARDiffusionKVCacheSpec:
                 ),
             ),
             model_owned_state_bytes_per_session=(
-                condition_bytes_per_session + self._streaming_decode_bytes_per_session()
+                condition_bytes_per_session
+                + 2 * self._condition_encoder_cache_bytes()  # Committed and in-flight histories.
+                + self._streaming_decode_bytes_per_session()
             ),
         )
 
+    def _condition_encoder_cache_bytes(self) -> int:
+        """Bound one Wan encoder history from its per-convolution input grids."""
+        if getattr(self.vae.config, "patch_size", None) is not None:
+            raise ValueError("Stateful LingBot conditioning requires an unpatched Wan VAE.")
+        encoder = self.vae.encoder
+        height, width = self._ar_height, self._ar_width
+        elements = CACHE_T * encoder.conv_in.in_channels * height * width
+        for layer in encoder.down_blocks:
+            if isinstance(layer, WanResidualBlock):
+                elements += CACHE_T * (layer.conv1.in_channels + layer.conv2.in_channels) * height * width
+            elif isinstance(layer, WanResample) and layer.mode in ("downsample2d", "downsample3d"):
+                height, width = height // 2, width // 2
+                if layer.mode == "downsample3d":
+                    # Temporal downsampling retains one frame after spatial downsampling.
+                    elements += layer.time_conv.in_channels * height * width
+            elif not isinstance(layer, WanAttentionBlock):
+                raise ValueError("Stateful LingBot conditioning requires the Wan encoder cache layout.")
+        for layer in encoder.mid_block.resnets:
+            elements += CACHE_T * (layer.conv1.in_channels + layer.conv2.in_channels) * height * width
+        elements += CACHE_T * encoder.conv_out.in_channels * height * width
+        return elements * torch.empty((), dtype=self.vae.dtype).element_size()
+
     def _streaming_decode_bytes_per_session(self) -> int:
         """Resident streaming-decoder bytes one session can hold, for admission.
 
@@ -678,12 +704,18 @@ def bind_ar_diffusion_state(
         finally:
             self._ar_diffusion_kv_state = None
 
+    def _release_condition_encoder_state(self, session_id: str) -> None:
+        state = self._ar_sessions.pop(session_id, None)
+        if state is not None:
+            state.encoder_cache = None
+            state.pending_encoder_cache = None
+
     def reset_ar_diffusion_session(self, session_id: str) -> None:
-        self._ar_sessions.pop(session_id, None)
+        self._release_condition_encoder_state(session_id)
         self._release_streaming_decode_state(session_id)
 
     def close_ar_diffusion_session(self, session_id: str) -> None:
-        self._ar_sessions.pop(session_id, None)
+        self._release_condition_encoder_state(session_id)
         self._release_streaming_decode_state(session_id)
 
     def _parse_request(self, req: DiffusionRequestBatch) -> _LingBotRequestInputs:
@@ -810,8 +842,6 @@ def _parse_request(self, req: DiffusionRequestBatch) -> _LingBotRequestInputs:
         num_frames = getattr(sampling, "num_frames", None)
         if isinstance(num_frames, bool) or not isinstance(num_frames, int) or num_frames <= 0:
             raise ValueError(f"num_frames must be a positive integer, got {num_frames!r}.")
-        if num_frames > _MAX_RAW_FRAMES:
-            raise ValueError(f"num_frames must not exceed {_MAX_RAW_FRAMES}.")
         temporal_factor = self.vae_scale_factor_temporal
         if (num_frames - 1) % temporal_factor:
             raise ValueError(
@@ -914,16 +944,16 @@ def _prepare_condition(self, inputs: _LingBotRequestInputs, *, dtype: torch.dtyp
             raise RuntimeError(
                 f"vae.encode returned an incompatible image latent shape: got {tuple(latent_condition.shape)}."
             )
+        return self._condition_from_latents(latent_condition, first_frame=True, dtype=dtype)
+
+    def _condition_from_latents(
+        self, latent_condition: torch.Tensor, *, first_frame: bool, dtype: torch.dtype
+    ) -> torch.Tensor:
         latent_mean, latent_std = self._vae_latent_stats(latent_condition)
         latent_condition = (latent_condition - latent_mean) / latent_std
-        temporal_mask = latent_condition.new_zeros(
-            1,
-            self.vae_scale_factor_temporal,
-            inputs.num_latent_frames,
-            latent_condition.shape[-2],
-            latent_condition.shape[-1],
-        )
-        temporal_mask[:, :, 0] = 1
+        temporal_mask = latent_condition.new_zeros(1, self.vae_scale_factor_temporal, *latent_condition.shape[2:])
+        if first_frame:
+            temporal_mask[:, :, 0] = 1
         condition = torch.cat((temporal_mask, latent_condition), dim=1).to(dtype=dtype)
         if condition.shape[1] != 20:
             raise RuntimeError(
@@ -932,6 +962,78 @@ def _prepare_condition(self, inputs: _LingBotRequestInputs, *, dtype: torch.dtyp
             )
         return condition
 
+    @torch.no_grad()
+    def _prepare_condition_chunk(
+        self,
+        inputs: _LingBotRequestInputs,
+        *,
+        start_frame: int,
+        encoder_cache: list[torch.Tensor | None] | None,
+        dtype: torch.dtype,
+    ) -> tuple[torch.Tensor, list[torch.Tensor | None]]:
+        """Continue the causal encoder without modifying its committed history."""
+        if getattr(self.vae.config, "patch_size", None) is not None or self.vae_scale_factor_temporal != 4:
+            raise ValueError("Stateful LingBot conditioning requires an unpatched Wan VAE with temporal factor 4.")
+        if getattr(self.vae, "use_tiling", False) and (
+            inputs.height > self.vae.tile_sample_min_height or inputs.width > self.vae.tile_sample_min_width
+        ):
+            raise ValueError("Stateful LingBot conditioning does not support tiled VAE encoding.")
+        if (encoder_cache is None) != (start_frame == 0):
+            raise ValueError("LingBot condition encoder history must match the current temporal position.")
+
+        count = int(self.vae._cached_conv_counts["encoder"])
+        # Wan replaces cache entries with new tensors; a separate list keeps the
+        # committed history intact until this AR block succeeds.
+        pending_cache = [None] * count if encoder_cache is None else list(encoder_cache)
+        if len(pending_cache) != count:
+            raise ValueError("LingBot condition encoder cache has an incompatible number of slots.")
+        block_frames = int(self.transformer.config.num_frames_per_block)
+        zeros = torch.zeros(
+            1,
+            3,
+            self.vae_scale_factor_temporal,
+            inputs.height,
+            inputs.width,
+            device=self.device,
+            dtype=self.vae.dtype,
+        )
+        image = (
+            self._prepare_image_tensor(inputs.image, height=inputs.height, width=inputs.width)
+            .unsqueeze(2)
+            .to(dtype=self.vae.dtype)
+            if start_frame == 0
+            else None
+        )
+        context = getattr(self.vae, "_execution_context", None)
+        encoded_frames = []
+        with context() if callable(context) else nullcontext():
+            for index in range(block_frames):
+                # Match Wan's encode loop: one opening pixel frame, then four
+                # fresh zero pixel frames per subsequent latent frame.
+                pixel_frames = image if start_frame == 0 and index == 0 else zeros
+                encoded_frames.append(self.vae.encoder(pixel_frames, feat_cache=pending_cache, feat_idx=[0]))
+            # The posterior projection is pointwise in time. GPU bitwise parity
+            # with the whole-clip projection still requires the real-weight gate.
+            moments = self.vae.quant_conv(torch.cat(encoded_frames, dim=2))
+        latent_condition = moments.chunk(2, dim=1)[0]
+        expected_shape = (
+            1,
+            self.transformer.config.out_channels,
+            block_frames,
+            inputs.height // self.vae_scale_factor_spatial,
+            inputs.width // self.vae_scale_factor_spatial,
+        )
+        if latent_condition.shape != expected_shape:
+            raise RuntimeError(
+                f"Wan condition encoder returned {tuple(latent_condition.shape)}, expected {expected_shape}."
+            )
+        condition = self._condition_from_latents(
+            latent_condition,
+            first_frame=start_frame == 0,
+            dtype=dtype,
+        )
+        return condition, pending_cache
+
     def _prepare_camera(
         self,
         inputs: _LingBotRequestInputs,
@@ -1150,6 +1252,11 @@ def forward(self, req: DiffusionRequestBatch) -> DiffusionOutput:
             raise RuntimeError("LingBot typed ticks require ARDiffusionEngine session binding.")
         if tick is None and self._ar_diffusion_kv_state is not None:
             raise ValueError("LingBot ARDiffusionEngine requests must carry ar_diffusion_tick.")
+        if tick is not None and inputs.output_type != "latent":
+            raise ValueError(
+                "LingBot realtime ticks currently require output_type='latent'; "
+                "stateful streaming VAE decode is a separate integration step."
+            )
         session_state: _LingBotARSessionState | None = None
         if tick is not None:
             if tick.prompt is not None and " ".join(tick.prompt.split()) != " ".join(inputs.prompt.split()):
@@ -1166,16 +1273,6 @@ def forward(self, req: DiffusionRequestBatch) -> DiffusionOutput:
                     "fixed cache geometry "
                     f"{self._ar_height}x{self._ar_width}."
                 )
-            horizon_latent_frames = (_MAX_RAW_FRAMES - 1) // self.vae_scale_factor_temporal + 1
-            max_realtime_ticks = horizon_latent_frames // block_frames
-            if tick.chunk_index >= max_realtime_ticks:
-                raise ValueError(
-                    "LingBot realtime generation currently supports at most "
-                    f"{max_realtime_ticks} ticks per generation epoch "
-                    f"(chunk_index 0 through {max_realtime_ticks - 1}) because "
-                    f"the image-condition horizon is {_MAX_RAW_FRAMES} pixel "
-                    "frames; reset or create a session to start a new world."
-                )
             session_state = self._ar_sessions.setdefault(
                 tick.session_id,
                 _LingBotARSessionState(),
@@ -1200,26 +1297,12 @@ def forward(self, req: DiffusionRequestBatch) -> DiffusionOutput:
             condition = self._prepare_condition(inputs, dtype=dtype)
         else:
             assert session_state is not None
-            if session_state.image_condition is None:
-                horizon_latent_frames = (_MAX_RAW_FRAMES - 1) // self.vae_scale_factor_temporal + 1
-                session_state.image_condition = self._prepare_condition(
-                    replace(
-                        inputs,
-                        num_frames=_MAX_RAW_FRAMES,
-                        num_latent_frames=horizon_latent_frames,
-                    ),
-                    dtype=dtype,
-                )
-            block_frames = int(self.transformer.config.num_frames_per_block)
-            condition_start = tick.chunk_index * block_frames
-            condition_stop = condition_start + block_frames
-            if condition_stop > session_state.image_condition.shape[2]:
-                raise ValueError("LingBot chunk_index exceeds the configured causal image condition horizon.")
-            condition = session_state.image_condition[
-                :,
-                :,
-                condition_start:condition_stop,
-            ]
+            condition, pending_encoder_cache = self._prepare_condition_chunk(
+                inputs,
+                start_frame=tick.chunk_index * block_frames,
+                encoder_cache=session_state.encoder_cache,
+                dtype=dtype,
+            )
         camera_pitch: float | None = None
         if inputs.camera_actions is not None:
             assert session_state is not None
@@ -1299,6 +1382,7 @@ def forward(self, req: DiffusionRequestBatch) -> DiffusionOutput:
             assert session_state is not None
             session_state.prompt = inputs.prompt
             session_state.generator_state = inputs.generator.get_state()
+            session_state.encoder_cache = pending_encoder_cache
             session_state.camera_tail = camera_tail
             if camera_pitch is not None:
                 session_state.camera_pitch = camera_pitch
@@ -1307,11 +1391,6 @@ def forward(self, req: DiffusionRequestBatch) -> DiffusionOutput:
         # Phase 4: either expose model-space latents or invert the checkpoint's
         # latent normalization and decode to pixel-space video.
         if tick is not None:
-            if inputs.output_type != "latent":
-                raise ValueError(
-                    "LingBot realtime ticks currently require output_type='latent'; "
-                    "stateful streaming VAE decode is a separate integration step."
-                )
             output = {
                 "payload": {"latents": generated_latents},
                 "metadata": {"ar_diffusion": ARDiffusionChunkMetadata.from_tick(tick).to_dict()},
@@ -1460,12 +1539,6 @@ def _video_processor(self) -> VideoProcessor:
             self._cached_video_processor = processor
         return processor
 
-    def _horizon_latent_frames(self) -> int:
-        return (_MAX_RAW_FRAMES - 1) // self.vae_scale_factor_temporal + 1
-
-    def _max_realtime_chunks(self) -> int:
-        return self._horizon_latent_frames() // int(self.transformer.config.num_frames_per_block)
-
     def _require_bound_ar_state(self) -> None:
         if self._ar_diffusion_kv_state is None:
             raise RuntimeError("LingBot step execution requires AR-Diffusion session binding.")
@@ -1492,13 +1565,6 @@ def prepare_encode(self, state: StepRequestState, **kwargs: Any) -> StepRequestS
             )
         block_frames = int(self.transformer.config.num_frames_per_block)
         total_chunks = inputs.num_latent_frames // block_frames
-        max_chunks = self._max_realtime_chunks()
-        if total_chunks > max_chunks:
-            raise ValueError(
-                "LingBot step execution currently supports at most "
-                f"{max_chunks} chunks because the image-condition horizon is "
-                f"{_MAX_RAW_FRAMES} pixel frames."
-            )
         if inputs.camera_action_script is not None and len(inputs.camera_action_script) != total_chunks:
             raise ValueError(
                 "camera_action_script must contain one action list per generated chunk; "
@@ -1510,14 +1576,6 @@ def prepare_encode(self, state: StepRequestState, **kwargs: Any) -> StepRequestS
             max_sequence_length=inputs.max_sequence_length,
             dtype=dtype,
         )
-        image_condition = self._prepare_condition(
-            replace(
-                inputs,
-                num_frames=_MAX_RAW_FRAMES,
-                num_latent_frames=self._horizon_latent_frames(),
-            ),
-            dtype=dtype,
-        )
         camera_trajectory_cache = None
         camera_embedding_cache = None
         if inputs.camera_trajectory is not None:
@@ -1546,7 +1604,6 @@ def prepare_encode(self, state: StepRequestState, **kwargs: Any) -> StepRequestS
         state.chunk_num_steps = len(LINGBOT_DMD_TIMESTEPS)
         state.extra = {
             "inputs": inputs,
-            "image_condition": image_condition,
             "schedule": _build_shifted_flow_schedule(flow_shift=inputs.flow_shift),
             "dtype": dtype,
             "block_frames": block_frames,
@@ -1557,7 +1614,12 @@ def prepare_encode(self, state: StepRequestState, **kwargs: Any) -> StepRequestS
             "camera_embedding_cache": camera_embedding_cache,
         }
         self._ar_text_caches(prompt_embeds, invalidate=False)
-        self._prepare_next_chunk(state)
+        self._ar_sessions[state.request_id] = _LingBotARSessionState()
+        try:
+            self._prepare_next_chunk(state)
+        except Exception:
+            self._release_condition_encoder_state(state.request_id)
+            raise
         return state
 
     def _prepare_next_chunk(self, state: StepRequestState) -> None:
@@ -1566,10 +1628,15 @@ def _prepare_next_chunk(self, state: StepRequestState) -> None:
         block_frames = int(extra["block_frames"])
         start_frame = state.chunk_index * block_frames
         stop_frame = start_frame + block_frames
-        image_condition = extra["image_condition"]
-        if stop_frame > image_condition.shape[2]:
-            raise ValueError("LingBot chunk_index exceeds the configured causal image condition horizon.")
-        condition = image_condition[:, :, start_frame:stop_frame]
+        session_state = self._ar_sessions[state.request_id]
+        if session_state.next_chunk_index != state.chunk_index:
+            raise ValueError("LingBot condition chunks must be contiguous within the session.")
+        condition, pending_encoder_cache = self._prepare_condition_chunk(
+            inputs,
+            start_frame=start_frame,
+            encoder_cache=session_state.encoder_cache,
+            dtype=extra["dtype"],
+        )
         previous = extra.get("camera_tail")
         if extra.get("camera_action_script") is not None:
             chunk_actions = extra["camera_action_script"][state.chunk_index]
@@ -1639,6 +1706,7 @@ def _prepare_next_chunk(self, state: StepRequestState) -> None:
         )
         state.step_in_chunk = 0
         state.step_index = 0
+        session_state.pending_encoder_cache = pending_encoder_cache
 
     def denoise_step(
         self,
@@ -1702,6 +1770,9 @@ def post_decode(self, state: StepRequestState, **kwargs: Any) -> DiffusionOutput
         latents = state.latents
         if latents is None:
             raise RuntimeError("LingBot step execution requires latents before post_decode.")
+        session_state = self._ar_sessions[state.request_id]
+        if session_state.pending_encoder_cache is None:
+            raise RuntimeError("LingBot condition encoder has no prepared chunk to commit.")
         self._dmd_blocks.commit_block_kv(
             latents=latents,
             condition=extra["condition"],
@@ -1737,10 +1808,15 @@ def post_decode(self, state: StepRequestState, **kwargs: Any) -> DiffusionOutput
                 ).to_dict()
             },
         }
+        session_state.encoder_cache = session_state.pending_encoder_cache
+        session_state.pending_encoder_cache = None
+        session_state.next_chunk_index += 1
         state.chunk_index += 1
         finished = state.request_denoise_completed
         if not finished:
             self._prepare_next_chunk(state)
+        else:
+            self._release_condition_encoder_state(state.request_id)
         return DiffusionOutput(
             output=output,
             stage_durations=self.stage_durations if hasattr(self, "stage_durations") else None,
diff --git a/vllm_omni/diffusion/models/lingbot_world/transformer.py b/vllm_omni/diffusion/models/lingbot_world/transformer.py
index 32931db0c9e..c7033cee85d 100644
--- a/vllm_omni/diffusion/models/lingbot_world/transformer.py
+++ b/vllm_omni/diffusion/models/lingbot_world/transformer.py
@@ -749,7 +749,7 @@ def _sinusoidal_embedding(dim: int, timestep: torch.Tensor) -> torch.Tensor:
     return torch.cat((phase.cos(), phase.sin()), dim=1)
 
 
-def _rope_axis(max_seq_len: int, dim: int) -> tuple[torch.Tensor, torch.Tensor]:
+def _rope_axis(max_seq_len: int, dim: int, *, start: int = 0) -> tuple[torch.Tensor, torch.Tensor]:
     if dim == 0:
         empty = torch.empty(max_seq_len, 0, dtype=torch.float32)
         return empty, empty.clone()
@@ -759,7 +759,7 @@ def _rope_axis(max_seq_len: int, dim: int) -> tuple[torch.Tensor, torch.Tensor]:
         10000,
         torch.arange(0, dim, 2, dtype=torch.float64) / dim,
     )
-    phase = torch.outer(torch.arange(max_seq_len, dtype=torch.float64), frequencies)
+    phase = torch.outer(torch.arange(start, start + max_seq_len, dtype=torch.float64), frequencies)
     return phase.cos().float(), phase.sin().float()
 
 
@@ -1028,23 +1028,29 @@ def _rotary_embedding(
         dtype: torch.dtype,
         device: torch.device,
     ) -> tuple[torch.Tensor, torch.Tensor]:
-        if start_frame + frames > self.config.rope_max_seq_len:
-            raise ValueError("Temporal RoPE positions exceed rope_max_seq_len.")
         if height > self.config.rope_max_seq_len or width > self.config.rope_max_seq_len:
             raise ValueError("Spatial RoPE positions exceed rope_max_seq_len.")
+        if start_frame + frames <= self._rope_temporal_cosine.shape[0]:
+            temporal_cosine = self._rope_temporal_cosine[start_frame : start_frame + frames]
+            temporal_sine = self._rope_temporal_sine[start_frame : start_frame + frames]
+        else:
+            # Keep absolute positions and checkpoint frequencies, computing only
+            # this block instead of growing a table for the whole session.
+            temporal_dim = self._rope_temporal_cosine.shape[1] * 2
+            temporal_cosine, temporal_sine = _rope_axis(frames, temporal_dim, start=start_frame)
+            temporal_cosine = temporal_cosine.to(self._rope_temporal_cosine)
+            temporal_sine = temporal_sine.to(self._rope_temporal_sine)
 
         def expand_axis(table: torch.Tensor, axis: str) -> torch.Tensor:
             if axis == "temporal":
-                return (
-                    table[start_frame : start_frame + frames].view(frames, 1, 1, -1).expand(frames, height, width, -1)
-                )
+                return table.view(frames, 1, 1, -1).expand(frames, height, width, -1)
             if axis == "height":
                 return table[:height].view(1, height, 1, -1).expand(frames, height, width, -1)
             return table[:width].view(1, 1, width, -1).expand(frames, height, width, -1)
 
         cosine = torch.cat(
             (
-                expand_axis(self._rope_temporal_cosine, "temporal"),
+                expand_axis(temporal_cosine, "temporal"),
                 expand_axis(self._rope_height_cosine, "height"),
                 expand_axis(self._rope_width_cosine, "width"),
             ),
@@ -1052,7 +1058,7 @@ def expand_axis(table: torch.Tensor, axis: str) -> torch.Tensor:
         )
         sine = torch.cat(
             (
-                expand_axis(self._rope_temporal_sine, "temporal"),
+                expand_axis(temporal_sine, "temporal"),
                 expand_axis(self._rope_height_sine, "height"),
                 expand_axis(self._rope_width_sine, "width"),
             ),

From 952022c8ec62aa0b3ad0ed57d89630e54fd041ec Mon Sep 17 00:00:00 2001
From: dongbo910220 <32610838+dongbo910220@users.noreply.github.com>
Date: Tue, 15 Sep 2026 22:28:48 +0800
Subject: [PATCH 005/105] [Diffusion][Perf] Add Qwen-Image QK RoPE Triton path
 (#5931)

Signed-off-by: dongbo910220 <1275604947@qq.com>
---
 .../benchmark_qwen_image_qk_norm_rope.py      | 224 ++++++++++++++++++
 .../test_qwen_image_fused_qk_norm_rope.py     | 190 +++++++++++++++
 .../qwen_image/qwen_image_transformer.py      |  92 +++++--
 3 files changed, 484 insertions(+), 22 deletions(-)
 create mode 100644 benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py
 create mode 100644 tests/diffusion/models/qwen_image/test_qwen_image_fused_qk_norm_rope.py

diff --git a/benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py b/benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py
new file mode 100644
index 00000000000..ee69f7e5906
--- /dev/null
+++ b/benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py
@@ -0,0 +1,224 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Benchmark Qwen-Image Q/K RMSNorm + interleaved RoPE.
+
+Example:
+
+    CUDA_VISIBLE_DEVICES=0 python benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py \
+      --seq-len 4096 --warmup 20 --iters 100 --include-compiled --profile
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from collections.abc import Callable
+
+import torch
+import torch.nn.functional as F
+
+from vllm_omni.diffusion.layers.fused_qk_norm_rope import (
+    _fused_cuda_supported,
+    fused_qk_norm_rope,
+)
+from vllm_omni.diffusion.models.qwen_image.qwen_image_transformer import (
+    _apply_qwen_image_rotary_emb,
+)
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--batch", type=int, default=1)
+    parser.add_argument("--seq-len", type=int, default=4096)
+    parser.add_argument("--heads", type=int, default=24)
+    parser.add_argument("--kv-heads", type=int, default=24)
+    parser.add_argument("--head-dim", type=int, default=128)
+    parser.add_argument("--warmup", type=int, default=20)
+    parser.add_argument("--iters", type=int, default=100)
+    parser.add_argument("--dtype", choices=("bf16", "fp16", "fp32"), default="bf16")
+    parser.add_argument("--packed-qkv-view", action="store_true")
+    parser.add_argument("--include-compiled", action="store_true")
+    parser.add_argument("--profile", action="store_true")
+    return parser.parse_args()
+
+
+def _dtype(name: str) -> torch.dtype:
+    return {
+        "bf16": torch.bfloat16,
+        "fp16": torch.float16,
+        "fp32": torch.float32,
+    }[name]
+
+
+def _make_inputs(args: argparse.Namespace, dtype: torch.dtype, device: torch.device):
+    torch.manual_seed(2026)
+    if args.packed_qkv_view:
+        qkv_dim = (args.heads + args.kv_heads + args.kv_heads) * args.head_dim
+        qkv = torch.randn(args.batch, args.seq_len, qkv_dim, device=device, dtype=dtype)
+        q, k, _ = qkv.split(
+            [
+                args.heads * args.head_dim,
+                args.kv_heads * args.head_dim,
+                args.kv_heads * args.head_dim,
+            ],
+            dim=-1,
+        )
+        q = q.unflatten(-1, (args.heads, args.head_dim))
+        k = k.unflatten(-1, (args.kv_heads, args.head_dim))
+    else:
+        q = torch.randn(args.batch, args.seq_len, args.heads, args.head_dim, device=device, dtype=dtype)
+        k = torch.randn(args.batch, args.seq_len, args.kv_heads, args.head_dim, device=device, dtype=dtype)
+
+    q_weight = torch.randn(args.head_dim, device=device, dtype=dtype)
+    k_weight = torch.randn(args.head_dim, device=device, dtype=dtype)
+    angles = torch.randn(args.seq_len, args.head_dim // 2, device=device, dtype=torch.float32)
+    freqs = torch.polar(torch.ones_like(angles), angles)
+    return q, k, q_weight, k_weight, freqs
+
+
+def _native(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    q_weight: torch.Tensor,
+    k_weight: torch.Tensor,
+    freqs: torch.Tensor,
+    eps: float,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    q = F.rms_norm(q, (q.shape[-1],), q_weight, eps)
+    k = F.rms_norm(k, (k.shape[-1],), k_weight, eps)
+    return (
+        _apply_qwen_image_rotary_emb(q, freqs),
+        _apply_qwen_image_rotary_emb(k, freqs),
+    )
+
+
+def _fused(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    q_weight: torch.Tensor,
+    k_weight: torch.Tensor,
+    freqs: torch.Tensor,
+    eps: float,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    batch, seq_len, num_heads, head_dim = q.shape
+    num_kv_heads = k.shape[2]
+    rope_table = torch.cat((freqs.real, freqs.imag), dim=-1)
+    rope_table = rope_table.unsqueeze(0).expand(batch, -1, -1).reshape(batch * seq_len, head_dim)
+    out_q, out_k = fused_qk_norm_rope(
+        q.reshape(batch * seq_len, num_heads, head_dim),
+        k.reshape(batch * seq_len, num_kv_heads, head_dim),
+        q_weight,
+        k_weight,
+        rope_table,
+        eps,
+        interleaved=True,
+    )
+    return (
+        out_q.reshape(batch, seq_len, num_heads, head_dim),
+        out_k.reshape(batch, seq_len, num_kv_heads, head_dim),
+    )
+
+
+def _measure(fn: Callable[[], tuple[torch.Tensor, torch.Tensor]], warmup: int, iters: int) -> list[float]:
+    for _ in range(warmup):
+        fn()
+    torch.accelerator.synchronize()
+    start = torch.cuda.Event(enable_timing=True)
+    end = torch.cuda.Event(enable_timing=True)
+    samples = []
+    for _ in range(iters):
+        start.record()
+        fn()
+        end.record()
+        end.synchronize()
+        samples.append(start.elapsed_time(end))
+    return samples
+
+
+def _stats(samples: list[float]) -> dict[str, float]:
+    samples = sorted(samples)
+    return {
+        "median_ms": samples[len(samples) // 2],
+        "p90_ms": samples[int(len(samples) * 0.9)],
+        "mean_ms": sum(samples) / len(samples),
+    }
+
+
+def _profile(fn: Callable[[], tuple[torch.Tensor, torch.Tensor]]) -> str:
+    from torch.profiler import ProfilerActivity, profile
+
+    with profile(activities=[ProfilerActivity.CPU, ProfilerActivity.CUDA]) as prof:
+        fn()
+        torch.accelerator.synchronize()
+    return prof.key_averages().table(sort_by="self_cuda_time_total", row_limit=15)
+
+
+def main() -> None:
+    args = _parse_args()
+    if not torch.cuda.is_available():
+        raise RuntimeError("This benchmark requires CUDA")
+    device = torch.device("cuda")
+    dtype = _dtype(args.dtype)
+    eps = 1e-6
+    q, k, q_weight, k_weight, freqs = _make_inputs(args, dtype, device)
+
+    def native():
+        return _native(q, k, q_weight, k_weight, freqs, eps)
+
+    def fused():
+        return _fused(q, k, q_weight, k_weight, freqs, eps)
+
+    results: dict[str, object] = {
+        "device": torch.cuda.get_device_name(),
+        "batch": args.batch,
+        "seq_len": args.seq_len,
+        "heads": args.heads,
+        "kv_heads": args.kv_heads,
+        "head_dim": args.head_dim,
+        "dtype": args.dtype,
+        "packed_qkv_view": args.packed_qkv_view,
+        "fused_fast_path_supported": _fused_cuda_supported(
+            q.reshape(args.batch * args.seq_len, args.heads, args.head_dim),
+            k.reshape(args.batch * args.seq_len, args.kv_heads, args.head_dim),
+            args.head_dim,
+            args.head_dim,
+            interleaved=True,
+        ),
+    }
+
+    native_samples = _measure(native, args.warmup, args.iters)
+    fused_samples = _measure(fused, args.warmup, args.iters)
+    expected_q, expected_k = native()
+    actual_q, actual_k = fused()
+    torch.accelerator.synchronize()
+
+    native_stats = _stats(native_samples)
+    fused_stats = _stats(fused_samples)
+    results["native"] = native_stats
+    results["fused"] = fused_stats
+    results["speedup_vs_native"] = native_stats["median_ms"] / fused_stats["median_ms"]
+    results["max_abs_q"] = (actual_q.float() - expected_q.float()).abs().max().item()
+    results["max_abs_k"] = (actual_k.float() - expected_k.float()).abs().max().item()
+    results["mean_abs_q"] = (actual_q.float() - expected_q.float()).abs().mean().item()
+    results["mean_abs_k"] = (actual_k.float() - expected_k.float()).abs().mean().item()
+
+    if args.include_compiled:
+        compiled_native = torch.compile(native, dynamic=True, fullgraph=True)
+        compiled_fused = torch.compile(fused, dynamic=True, fullgraph=True)
+        compiled_native_stats = _stats(_measure(compiled_native, args.warmup, args.iters))
+        compiled_fused_stats = _stats(_measure(compiled_fused, args.warmup, args.iters))
+        results["compiled_native"] = compiled_native_stats
+        results["compiled_fused"] = compiled_fused_stats
+        results["compiled_fused_speedup_vs_compiled_native"] = (
+            compiled_native_stats["median_ms"] / compiled_fused_stats["median_ms"]
+        )
+
+    print(json.dumps(results, indent=2))
+    if args.profile:
+        print("\n# fused profile")
+        print(_profile(fused))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/diffusion/models/qwen_image/test_qwen_image_fused_qk_norm_rope.py b/tests/diffusion/models/qwen_image/test_qwen_image_fused_qk_norm_rope.py
new file mode 100644
index 00000000000..2f10ea33e9c
--- /dev/null
+++ b/tests/diffusion/models/qwen_image/test_qwen_image_fused_qk_norm_rope.py
@@ -0,0 +1,190 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import pytest
+import torch
+import torch.nn as nn
+
+from vllm_omni.diffusion.layers.rope import RotaryEmbedding
+from vllm_omni.diffusion.models.qwen_image.qwen_image_transformer import (
+    _apply_qwen_image_rotary_emb,
+    _qwen_image_qk_norm_rope,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion]
+
+BATCH = 2
+Q_HEADS = 24
+K_HEADS = 24
+HEAD_DIM = 128
+EPS = 1e-6
+SEED = 2026
+
+
+@dataclass(frozen=True)
+class QwenImageQKInput:
+    q: torch.Tensor
+    k: torch.Tensor
+    norm_q: nn.RMSNorm
+    norm_k: nn.RMSNorm
+    freqs: torch.Tensor
+
+
+def _make_input(
+    *,
+    seq_len: int,
+    dtype: torch.dtype,
+    device: torch.device,
+    packed_qkv_view: bool,
+) -> QwenImageQKInput:
+    gen = torch.Generator(device=device)
+    gen.manual_seed(SEED + seq_len)
+
+    if packed_qkv_view:
+        qkv_dim = (Q_HEADS + K_HEADS + K_HEADS) * HEAD_DIM
+        qkv = torch.randn(BATCH, seq_len, qkv_dim, device=device, dtype=dtype, generator=gen)
+        q, k, _ = qkv.split(
+            [
+                Q_HEADS * HEAD_DIM,
+                K_HEADS * HEAD_DIM,
+                K_HEADS * HEAD_DIM,
+            ],
+            dim=-1,
+        )
+        q = q.unflatten(-1, (Q_HEADS, HEAD_DIM))
+        k = k.unflatten(-1, (K_HEADS, HEAD_DIM))
+    else:
+        q = torch.randn(BATCH, seq_len, Q_HEADS, HEAD_DIM, device=device, dtype=dtype, generator=gen)
+        k = torch.randn(BATCH, seq_len, K_HEADS, HEAD_DIM, device=device, dtype=dtype, generator=gen)
+
+    norm_q = nn.RMSNorm(HEAD_DIM, eps=EPS, device=device, dtype=dtype)
+    norm_k = nn.RMSNorm(HEAD_DIM, eps=EPS, device=device, dtype=dtype)
+    norm_q.requires_grad_(False)
+    norm_k.requires_grad_(False)
+    with torch.no_grad():
+        norm_q.weight.copy_(torch.randn(HEAD_DIM, device=device, dtype=dtype, generator=gen))
+        norm_k.weight.copy_(torch.randn(HEAD_DIM, device=device, dtype=dtype, generator=gen))
+    angles = torch.randn(seq_len, HEAD_DIM // 2, device=device, dtype=torch.float32, generator=gen)
+    freqs = torch.polar(torch.ones_like(angles), angles)
+    return QwenImageQKInput(q=q, k=k, norm_q=norm_q, norm_k=norm_k, freqs=freqs)
+
+
+def _reference(data: QwenImageQKInput) -> tuple[torch.Tensor, torch.Tensor]:
+    q = data.norm_q(data.q)
+    k = data.norm_k(data.k)
+    if data.q.device.type == "cuda":
+        return (
+            _apply_qwen_image_rotary_emb(q, data.freqs),
+            _apply_qwen_image_rotary_emb(k, data.freqs),
+        )
+
+    rope = RotaryEmbedding(is_neox_style=False)
+    cos = data.freqs.real.to(data.q.dtype)
+    sin = data.freqs.imag.to(data.q.dtype)
+    return rope(q, cos, sin), rope(k, cos, sin)
+
+
+def _run(data: QwenImageQKInput) -> tuple[torch.Tensor, torch.Tensor]:
+    return _qwen_image_qk_norm_rope(
+        data.q,
+        data.k,
+        data.norm_q,
+        data.norm_k,
+        data.freqs,
+        RotaryEmbedding(is_neox_style=False),
+        EPS,
+    )
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+def test_qwen_image_qk_norm_rope_cuda_fp32_fallback_matches_reference():
+    data = _make_input(
+        seq_len=7,
+        dtype=torch.float32,
+        device=torch.device("cuda:0"),
+        packed_qkv_view=True,
+    )
+
+    actual_q, actual_k = _run(data)
+    expected_q, expected_k = _reference(data)
+
+    torch.testing.assert_close(actual_q, expected_q, atol=1e-5, rtol=1e-5)
+    torch.testing.assert_close(actual_k, expected_k, atol=1e-5, rtol=1e-5)
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+def test_qwen_image_qk_norm_rope_cuda_fp16_fallback_matches_reference():
+    data = _make_input(
+        seq_len=7,
+        dtype=torch.float16,
+        device=torch.device("cuda:0"),
+        packed_qkv_view=True,
+    )
+
+    actual_q, actual_k = _run(data)
+    expected_q, expected_k = _reference(data)
+
+    torch.testing.assert_close(actual_q, expected_q, atol=1e-3, rtol=1e-3)
+    torch.testing.assert_close(actual_k, expected_k, atol=1e-3, rtol=1e-3)
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.parametrize("seq_len", [1, 7, 257, 1024])
+@pytest.mark.parametrize("packed_qkv_view", [False, True])
+def test_qwen_image_fused_qk_norm_rope_cuda_matches_fp32_rope_reference(
+    seq_len: int,
+    packed_qkv_view: bool,
+):
+    data = _make_input(
+        seq_len=seq_len,
+        dtype=torch.bfloat16,
+        device=torch.device("cuda:0"),
+        packed_qkv_view=packed_qkv_view,
+    )
+
+    actual_q, actual_k = _run(data)
+    expected_q, expected_k = _reference(data)
+
+    torch.testing.assert_close(actual_q, expected_q, atol=0.0625, rtol=0.02)
+    torch.testing.assert_close(actual_k, expected_k, atol=0.0625, rtol=0.02)
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+def test_qwen_image_fused_qk_norm_rope_torch_compile_fullgraph_capture():
+    data = _make_input(
+        seq_len=257,
+        dtype=torch.bfloat16,
+        device=torch.device("cuda:0"),
+        packed_qkv_view=True,
+    )
+    rope = RotaryEmbedding(is_neox_style=False)
+
+    def fn(
+        q: torch.Tensor,
+        k: torch.Tensor,
+        freqs: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        return _qwen_image_qk_norm_rope(
+            q,
+            k,
+            data.norm_q,
+            data.norm_k,
+            freqs,
+            rope,
+            EPS,
+        )
+
+    compiled_fn = torch.compile(fn, dynamic=True, fullgraph=True)
+    expected_q, expected_k = fn(data.q, data.k, data.freqs)
+    actual_q, actual_k = compiled_fn(data.q, data.k, data.freqs)
+
+    torch.testing.assert_close(actual_q, expected_q, atol=0.0625, rtol=0.02)
+    torch.testing.assert_close(actual_k, expected_k, atol=0.0625, rtol=0.02)
diff --git a/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py b/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
index 696728b9043..8e4dac3a304 100644
--- a/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
+++ b/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
@@ -45,6 +45,10 @@
 )
 from vllm_omni.diffusion.forward_context import get_forward_context
 from vllm_omni.diffusion.layers.adalayernorm import AdaLayerNorm
+from vllm_omni.diffusion.layers.fused_qk_norm_rope import (
+    _fused_cuda_supported,
+    fused_qk_norm_rope,
+)
 from vllm_omni.diffusion.layers.rope import RotaryEmbedding
 
 logger = init_logger(__name__)
@@ -61,6 +65,53 @@ def _apply_qwen_image_rotary_emb(x: torch.Tensor, freqs: torch.Tensor) -> torch.
     return torch.view_as_real(paired * freqs.unsqueeze(1)).flatten(3).to(x.dtype)
 
 
+def _qwen_image_qk_norm_rope(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    norm_q: nn.Module,
+    norm_k: nn.Module,
+    freqs: torch.Tensor,
+    rope: RotaryEmbedding,
+    eps: float,
+    *,
+    use_fused: bool = True,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    head_dim = q.shape[-1]
+    rotary_dim = freqs.shape[-1] * 2
+    if use_fused and _fused_cuda_supported(q, k, head_dim, rotary_dim, interleaved=True):
+        batch, seq_len, num_heads, _ = q.shape
+        num_kv_heads = k.shape[2]
+        rope_table = torch.cat((freqs.real, freqs.imag), dim=-1)
+        rope_table = rope_table.unsqueeze(0).expand(batch, -1, -1).reshape(batch * seq_len, rotary_dim)
+        fused_q, fused_k = fused_qk_norm_rope(
+            q.reshape(batch * seq_len, num_heads, head_dim),
+            k.reshape(batch * seq_len, num_kv_heads, head_dim),
+            norm_q.weight,
+            norm_k.weight,
+            rope_table,
+            eps,
+            interleaved=True,
+        )
+        return (
+            fused_q.reshape(batch, seq_len, num_heads, head_dim),
+            fused_k.reshape(batch, seq_len, num_kv_heads, head_dim),
+        )
+
+    q = norm_q(q)
+    k = norm_k(k)
+    if q.device.type == "cuda":
+        return (
+            _apply_qwen_image_rotary_emb(q, freqs),
+            _apply_qwen_image_rotary_emb(k, freqs),
+        )
+
+    # Retain the platform-specific kernels on other accelerators, which may
+    # not support complex tensors.
+    cos = torch.real(freqs).to(q.dtype)
+    sin = torch.imag(freqs).to(q.dtype)
+    return rope(q, cos, sin), rope(k, cos, sin)
+
+
 def _normalize_qwen_image_weight_name(name: str) -> str:
     name = name.removeprefix("transformer.")
     if ".to_out.0." in name:
@@ -648,28 +699,25 @@ def forward(
         txt_key = txt_key.unflatten(-1, (self.add_kv_num_heads, self.head_dim))
         txt_value = txt_value.unflatten(-1, (self.add_kv_num_heads, self.head_dim))
 
-        img_query = self.norm_q(img_query)
-        img_key = self.norm_k(img_key)
-        txt_query = self.norm_added_q(txt_query)
-        txt_key = self.norm_added_k(txt_key)
-
-        if img_query.device.type == "cuda":
-            img_query = _apply_qwen_image_rotary_emb(img_query, vid_freqs)
-            img_key = _apply_qwen_image_rotary_emb(img_key, vid_freqs)
-            txt_query = _apply_qwen_image_rotary_emb(txt_query, txt_freqs)
-            txt_key = _apply_qwen_image_rotary_emb(txt_key, txt_freqs)
-        else:
-            # Retain the platform-specific kernels on other accelerators,
-            # which may not support complex tensors.
-            img_cos = torch.real(vid_freqs).to(img_query.dtype)
-            img_sin = torch.imag(vid_freqs).to(img_query.dtype)
-            txt_cos = torch.real(txt_freqs).to(txt_query.dtype)
-            txt_sin = torch.imag(txt_freqs).to(txt_query.dtype)
-
-            img_query = self.rope(img_query, img_cos, img_sin)
-            img_key = self.rope(img_key, img_cos, img_sin)
-            txt_query = self.rope(txt_query, txt_cos, txt_sin)
-            txt_key = self.rope(txt_key, txt_cos, txt_sin)
+        img_query, img_key = _qwen_image_qk_norm_rope(
+            img_query,
+            img_key,
+            self.norm_q,
+            self.norm_k,
+            vid_freqs,
+            self.rope,
+            self.eps,
+            use_fused=self.qk_norm,
+        )
+        txt_query, txt_key = _qwen_image_qk_norm_rope(
+            txt_query,
+            txt_key,
+            self.norm_added_q,
+            self.norm_added_k,
+            txt_freqs,
+            self.rope,
+            self.eps,
+        )
 
         seq_len_txt = encoder_hidden_states.shape[1]
         joint_query = torch.cat([txt_query, img_query], dim=1)

From 78934753ff7e092b24ada0e34062cf3d121efd25 Mon Sep 17 00:00:00 2001
From: Nick Cao <ncao@redhat.com>
Date: Tue, 15 Sep 2026 12:36:34 -0400
Subject: [PATCH 006/105] [Tests] Test image edit input limits in tiny model
 framework (#7434)

Signed-off-by: Nick Cao <ncao@redhat.com>
Co-authored-by: Codex <noreply@openai.com>
---
 tests/model_tests/diffusion/task_runners.py   | 50 +++++++++++++++++++
 .../diffusion/test_common_online.py           | 17 +++++++
 2 files changed, 67 insertions(+)

diff --git a/tests/model_tests/diffusion/task_runners.py b/tests/model_tests/diffusion/task_runners.py
index 010d7377719..991c74603d5 100644
--- a/tests/model_tests/diffusion/task_runners.py
+++ b/tests/model_tests/diffusion/task_runners.py
@@ -15,6 +15,8 @@
 import pytest
 from PIL import Image
 
+from benchmarks.accuracy.common import pil_to_png_bytes
+from tests.helpers.assertions import assert_images_generations_response
 from tests.helpers.runtime import DiffusionResponse, OmniServer, OnlineOmniClient, dummy_messages_from_mix_data
 from tests.model_tests.diffusion.config_types import DiffusionTasks
 from vllm_omni.entrypoints.omni import Omni
@@ -204,6 +206,25 @@ def _run_online_i2i(
     return client.send_diffusion_request(request_config)
 
 
+def _build_online_image_edits_request(model: str, num_images: int) -> dict[str, Any]:
+    """Build a multipart ``/v1/images/edits`` request with repeated image fields."""
+    files = [
+        ("image", (f"image_{index}.png", pil_to_png_bytes(INPUT_IMAGE), "image/png")) for index in range(num_images)
+    ]
+    return {
+        "data": {
+            "model": model,
+            "prompt": PROMPT,
+            "size": f"{WIDTH}x{HEIGHT}",
+            "n": 1,
+            "response_format": "b64_json",
+            "num_inference_steps": 2,
+            "seed": 42,
+        },
+        "files": files,
+    }
+
+
 ### Offline task runners
 def run_and_validate_text_to_image_request(omni: Omni):
     """Run and validate a text to image request."""
@@ -324,6 +345,35 @@ def run_and_validate_online_image_to_image_request(server: OmniServer, client: O
     _validate_images(_get_online_images(_run_online_i2i(server, client)))
 
 
+def run_and_validate_online_image_edits(
+    server: OmniServer,
+    client: OnlineOmniClient,
+    num_images: int,
+    max_multimodal_image_inputs: int,
+):
+    """Run and validate one request through ``/v1/images/edits``."""
+    request = _build_online_image_edits_request(server.model, num_images)
+    if num_images <= max_multimodal_image_inputs:
+        response = client.send_images_edits_http_request(request)[0]
+        assert response.success, response.error_message
+        assert isinstance(response.json_body, dict)
+        assert_images_generations_response(
+            response.json_body,
+            {"json": {"n": 1, "size": f"{WIDTH}x{HEIGHT}"}},
+        )
+    else:
+        err_message = (
+            "Only a single image is supported by this model."
+            if max_multimodal_image_inputs == 1
+            else f"At most {max_multimodal_image_inputs} images are supported"
+        )
+        client.send_images_edits_http_request(
+            request,
+            err_code=400,
+            err_message=err_message,
+        )
+
+
 def run_and_validate_online_determinism(server: OmniServer, client: OnlineOmniClient, task_type: DiffusionTasks):
     """Checks for determinism through the server, dispatching by task type.
 
diff --git a/tests/model_tests/diffusion/test_common_online.py b/tests/model_tests/diffusion/test_common_online.py
index 65089e3efcb..ed7f0e2fa65 100644
--- a/tests/model_tests/diffusion/test_common_online.py
+++ b/tests/model_tests/diffusion/test_common_online.py
@@ -20,12 +20,14 @@
 from tests.model_tests.diffusion.model_settings import DIFFUSION_TEST_SETTINGS
 from tests.model_tests.diffusion.task_runners import (
     run_and_validate_online_determinism,
+    run_and_validate_online_image_edits,
     run_and_validate_online_image_to_image_request,
     run_and_validate_online_image_to_video_request,
     run_and_validate_online_multi_output,
     run_and_validate_online_text_to_image_request,
     run_and_validate_online_text_to_video_request,
 )
+from vllm_omni.diffusion.model_metadata import get_diffusion_model_metadata
 
 # NOTE : Hardware marks are added dynamically based on test requirements
 pytestmark = [pytest.mark.diffusion, pytest.mark.xdist]
@@ -84,6 +86,21 @@ def test_online_on_supported_tasks(
                     run_and_validate_online_text_to_image_request(server, client)
                 elif task_type == DiffusionTasks.IMAGE_TO_IMAGE:
                     run_and_validate_online_image_to_image_request(server, client)
+                    max_multimodal_image_inputs = (
+                        get_diffusion_model_metadata(model_name).max_multimodal_image_inputs or 1
+                    )
+                    image_counts = [1]
+                    if max_multimodal_image_inputs != 1:
+                        image_counts.append(max_multimodal_image_inputs)
+                    image_counts.append(max_multimodal_image_inputs + 1)
+                    for num_images in image_counts:
+                        with subtests.test(api="/v1/images/edits", num_images=num_images):
+                            run_and_validate_online_image_edits(
+                                server,
+                                client,
+                                num_images=num_images,
+                                max_multimodal_image_inputs=max_multimodal_image_inputs,
+                            )
                 elif task_type == DiffusionTasks.TEXT_TO_VIDEO:
                     run_and_validate_online_text_to_video_request(server, client)
                 elif task_type == DiffusionTasks.IMAGE_TO_VIDEO:

From c17126c21994edc5aaf1fa3a6248d67bd0ab9d29 Mon Sep 17 00:00:00 2001
From: Mengjie Zhao <38148457+mjZhaoElaine@users.noreply.github.com>
Date: Tue, 15 Sep 2026 14:56:51 -0700
Subject: [PATCH 007/105] [Model] Add Gepard-1.0 OpenAI /v1/audio/speech
 serving (#7499)

Signed-off-by: Mengjie Zhao <zmj0129@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .buildkite/cuda/test-weekly.yml               |   3 +-
 docs/serving/speech_api.md                    |  49 +-
 .../examples/online_serving/text_to_speech.md |  58 +-
 .../text_to_speech/README.md                  |   8 +-
 .../online_serving/text_to_speech/README.md   |  43 +-
 .../text_to_speech/gepard/run_server.sh       |  33 ++
 .../text_to_speech/gepard/speech_client.py    | 116 ++++
 tests/e2e/online_serving/test_gepard_tts.py   | 524 ++++++++++++++++++
 .../openai_api/test_gepard_tts_adapter.py     | 276 +++++++++
 .../openai_api/test_serving_speech_metrics.py |   1 +
 .../openai_api/test_tts_adapter.py            |  12 +
 .../openai_api/test_tts_detection.py          |   1 +
 tests/worker/test_gpu_ar_model_runner.py      |   1 +
 .../entrypoints/openai/serving_speech.py      |  49 +-
 .../openai/tts_adapters/__init__.py           |   1 +
 .../entrypoints/openai/tts_adapters/gepard.py | 168 ++++++
 .../openai/tts_adapters/moss_tts.py           |  11 +-
 17 files changed, 1329 insertions(+), 25 deletions(-)
 create mode 100755 examples/online_serving/text_to_speech/gepard/run_server.sh
 create mode 100755 examples/online_serving/text_to_speech/gepard/speech_client.py
 create mode 100644 tests/e2e/online_serving/test_gepard_tts.py
 create mode 100644 tests/entrypoints/openai_api/test_gepard_tts_adapter.py
 create mode 100644 vllm_omni/entrypoints/openai/tts_adapters/gepard.py

diff --git a/.buildkite/cuda/test-weekly.yml b/.buildkite/cuda/test-weekly.yml
index 7809fcbc7c4..70ab5935673 100644
--- a/.buildkite/cuda/test-weekly.yml
+++ b/.buildkite/cuda/test-weekly.yml
@@ -191,13 +191,14 @@ steps:
       # from downgrading transformers; see
       # examples/offline_inference/text_to_speech/README.md.
       - label: "TTS · Gepard-1.0 · L4"
-        timeout_in_minutes: 60
+        timeout_in_minutes: 90
         commands:
           - export VLLM_ALLOW_LONG_MAX_MODEL_LEN="1"
           - printf '%s\n' "transformers>=5.5.3" "huggingface-hub>=1.0" > /tmp/gepard-overrides.txt
           - uv pip install --python "$(python3 -c 'import sys; print(sys.executable)')" "nemo_toolkit[tts]==2.7.3" --overrides /tmp/gepard-overrides.txt
           - >-
             pytest -s -v tests/e2e/offline_inference/test_gepard_tts.py
+            tests/e2e/online_serving/test_gepard_tts.py
             -m "tts and cuda"
             --run-level "full_model"
         mirror_hardwares: l4_1
diff --git a/docs/serving/speech_api.md b/docs/serving/speech_api.md
index d4fad42063c..b4b2e7f5585 100644
--- a/docs/serving/speech_api.md
+++ b/docs/serving/speech_api.md
@@ -6,6 +6,7 @@ vLLM-Omni provides an OpenAI-compatible API for text-to-speech (TTS) generation.
 - **Fish Speech S2 Pro** (`fishaudio/s2-pro`) -- Dual-AR TTS with DAC codec. Supports text-to-speech and voice cloning via reference audio. Output: 44.1 kHz.
 - **Voxtral TTS** (`mistralai/Voxtral-4B-TTS-2603`) -- AR + FlowMatching TTS with preset voices. Output: 24 kHz.
 - **CosyVoice3** (`FunAudioLLM/Fun-CosyVoice3-0.5B-2512`) -- 2-stage talker + flow-matching code2wav. Voice cloning via `ref_audio` + `ref_text` (no presets). Output: 24 kHz.
+- **Gepard-1.0** (`nineninesix/gepard-1.0`) -- single-stage native-AR TTS with a 22.05 kHz NanoCodec. Zero-shot default voice only.
 
 See the [Supported Models](#supported-models) section below for the full list, including OmniVoice, VoxCPM2, MOSS-TTS-Nano, and Breeze-TTS-2.
 
@@ -40,11 +41,16 @@ vllm serve mistralai/Voxtral-4B-TTS-2603 --omni --port 8091
 # CosyVoice3 (voice cloning only — supply ref_audio + ref_text per request)
 vllm serve FunAudioLLM/Fun-CosyVoice3-0.5B-2512 \
     --omni --port 8091 --trust-remote-code
+
+# Gepard-1.0 (zero-shot default voice; packaged gepard.yaml)
+vllm-omni serve nineninesix/gepard-1.0 --omni --port 8091 --trust-remote-code \
+    --stage-init-timeout 900 \
+    --deploy-config vllm_omni/deploy/gepard.yaml
 ```
 
 ### Generate Speech
 
-**Using curl:**
+**Qwen3-TTS CustomVoice, using curl:**
 
 ```bash
 curl -X POST http://localhost:8091/v1/audio/speech \
@@ -56,7 +62,24 @@ curl -X POST http://localhost:8091/v1/audio/speech \
     }' --output output.wav
 ```
 
-**Using Python:**
+**Gepard-1.0, using curl:**
+
+Gepard accepts `input` (required), `voice` (`"default"`), `response_format`,
+`stream` / `stream_format`, `max_new_tokens`, and `seed`. Unsupported fields
+include `speed`, `language`, `instructions`, `task_type`, `ref_audio`,
+`ref_text`, `extra_params`, and `word_timestamps`.
+
+```bash
+curl -X POST http://localhost:8091/v1/audio/speech \
+    -H "Content-Type: application/json" \
+    -d '{
+        "input": "Hello, this is Gepard speaking.",
+        "voice": "default",
+        "seed": 7
+    }' --output output.wav
+```
+
+**Qwen3-TTS CustomVoice, using Python:**
 
 ```python
 import httpx
@@ -761,6 +784,28 @@ Fish Speech uses `ref_audio` and `ref_text` for voice cloning (no `task_type` ne
 | ------- | ------------- |
 | `FunAudioLLM/Fun-CosyVoice3-0.5B-2512` | Voice cloning from `ref_audio` + `ref_text`. No built-in voice presets — upload a voice or pass `ref_audio`/`ref_text` per request. |
 
+### Gepard-1.0
+
+| Model | Description |
+| ----- | ----------- |
+| `nineninesix/gepard-1.0` | Zero-shot native-AR TTS. 22.05 kHz mono. `voice` must be omitted or `"default"`. |
+
+Gepard request fields:
+
+| Field | Behavior |
+| ----- | -------- |
+| `input` | Required. Empty/whitespace-only returns 400. |
+| `voice` | Omitted or `"default"` only. Other values 400. |
+| `response_format` | `wav` default. Non-streaming: `wav`/`pcm`/`flac`/`mp3`. `opus` returns 400 (22.05 kHz is not an Opus sample rate). Streaming: `pcm`/`wav` only. |
+| `stream` / `stream_format` | SSE (`speech.audio.*`) and raw `audio` byte streaming. |
+| `speed` | Must be `1.0`. Gepard has no native speed control. |
+| `max_new_tokens` | Frame budget (1 token = 1 frame = 1024 samples ≈ 46.4 ms). Default 1000 from deploy YAML; adapter bounds 1..4096. |
+| `seed` | Optional. Reaches the in-model 32-head sampler. The packaged YAML currently pins `seed: 42`, so serving is deterministic by default until that pin is removed. |
+| `extra_params` | Any key returns 400, including `temperature`/`top_p`/`top_k`. |
+| Cloning / style fields | `ref_audio`, `ref_text`, `speaker_embedding`, `instructions`, `language`, `task_type`, `word_timestamps`, and similar declared-but-unsupported fields return 400. |
+
+See the [Gepard section of the online TTS hub](../user_guide/examples/online_serving/text_to_speech.md#gepard-10) for launch commands. Native-AR recompute preemption is a known limitation under concurrency.
+
 ### OmniVoice
 
 | Model | Description |
diff --git a/docs/user_guide/examples/online_serving/text_to_speech.md b/docs/user_guide/examples/online_serving/text_to_speech.md
index 2b4f617f42d..e9499551f8a 100644
--- a/docs/user_guide/examples/online_serving/text_to_speech.md
+++ b/docs/user_guide/examples/online_serving/text_to_speech.md
@@ -18,6 +18,7 @@ For the full list of supported architectures across all modalities, see
 | --- | --- | --- | --- | --- | --- |
 | CosyVoice3 | `FunAudioLLM/Fun-CosyVoice3-0.5B-2512` | ✓ (`ref_audio`+`ref_text`) | ✓ (PCM stream) | — | — |
 | Fish Speech S2 Pro | `fishaudio/s2-pro` | ✓ (`ref_audio`+`ref_text`) | ✓ (PCM stream) | — | ✓ |
+| Gepard-1.0 | `nineninesix/gepard-1.0` | — (zero-shot default voice) | ✓ (PCM / WAV stream) | `default` only | — |
 | higgs-audio v2 | `bosonai/higgs-audio-v2-generation-3B-base` | ✓ (`ref_audio`+`ref_text`) | ✓ (codec_streaming) | — | — |
 | GLM-TTS | `zai-org/GLM-TTS` | ✓ (`ref_audio`+`ref_text`, required) | ✓ (PCM stream) | — | ✓ |
 | OmniVoice | `k2-fsa/OmniVoice` | (offline only) | — | — | — |
@@ -92,7 +93,7 @@ curl -X POST http://localhost:8091/v1/audio/speech \
     }' --no-buffer | play -t raw -r 24000 -e signed -b 16 -c 1 -
 ```
 
-Adjust the player's sample rate to match the model (44.1 kHz for Fish Speech, 48 kHz for VoxCPM2, 24 kHz for the others).
+Adjust the player's sample rate to match the model (44.1 kHz for Fish Speech, 48 kHz for VoxCPM2, 22.05 kHz for Gepard, 24 kHz for the others).
 
 For full request-shape documentation (all parameters, response formats, error codes), see the [Speech API reference](https://github.com/vllm-project/vllm-omni/tree/main/docs/serving/speech_api.md).
 
@@ -212,6 +213,61 @@ python fish_speech/gradio_demo.py --api-base http://localhost:8091  # if server
 
 ---
 
+## Gepard-1.0
+
+Single-stage native AR TTS at 22.05 kHz mono. Zero-shot only: omit `voice` or pass `"default"`. Voice cloning from reference audio is not available yet.
+
+### Prerequisites
+
+Same NeMo NanoCodec install as the [offline Gepard section](https://github.com/vllm-project/vllm-omni/tree/main/examples/offline_inference/text_to_speech/README.md#gepard-10). On a host whose CUDA toolkit cannot build kernels — no `nvcc`/`ninja`, or a consumer Blackwell (`sm_120`) card — also `export VLLM_USE_FLASHINFER_SAMPLER=0` before launch. That env is not a deploy-YAML field.
+
+### Launch
+
+```bash
+vllm-omni serve nineninesix/gepard-1.0 --omni --port 8091 --trust-remote-code \
+    --stage-init-timeout 900 \
+    --deploy-config vllm_omni/deploy/gepard.yaml
+# or:
+./gepard/run_server.sh
+```
+
+`--stage-init-timeout 900` matches the online e2e fixture and the offline example. Serve defaults to 300s, which is often too short for a cold download of the talker plus NanoCodec.
+
+The packaged `vllm_omni/deploy/gepard.yaml` must be passed with `--deploy-config`. The checkpoint self-identifies as `qwen3_5_text`, so omitting the YAML launches a diffusion fallback instead of the Gepard pipeline. The YAML sets `async_chunk: false`, `max_num_seqs: 4`, and currently pins `seed: 42`, so serving is deterministic by default until that YAML seed is removed. Pass an explicit per-request `seed` in tests and clients rather than depending on either default.
+
+### Sending requests
+
+```bash
+python examples/online_serving/text_to_speech/gepard/speech_client.py \
+    --text "Hello, this is Gepard speaking."
+
+python examples/online_serving/text_to_speech/gepard/speech_client.py \
+    --text "Hello, this is Gepard speaking." --seed 7 --stream --output output.pcm
+```
+
+Gepard accepts `input` (required), `voice` (`"default"`), `response_format`, `stream` / `stream_format`, `max_new_tokens`, and `seed`. Unsupported fields include `speed`, `language`, `instructions`, `task_type`, `ref_audio`, `ref_text`, `extra_params`, and `word_timestamps`.
+
+```bash
+curl -X POST http://localhost:8091/v1/audio/speech \
+    -H "Content-Type: application/json" \
+    -d '{
+        "input": "Hello, this is Gepard speaking.",
+        "voice": "default",
+        "seed": 7
+    }' --output output.wav
+```
+
+### Notes
+
+- Output: 22.05 kHz mono. `max_new_tokens` is a **frame** budget (1 token = 1 frame = 1024 samples ≈ 46.4 ms at 21.5 fps; adapter bounds 1..4096).
+- Supported request fields: `input` (required), `voice` (`default` only), `response_format` (`wav` default; `wav/pcm/flac/mp3` non-streaming; `opus` 400 because 22.05 kHz is not an Opus sample rate; streaming `pcm/wav` only), `stream` / `stream_format`, `max_new_tokens`, `seed`.
+- Unsupported: `speed`, `extra_params` (including `temperature`/`top_p`/`top_k`), `ref_audio`, `ref_text`, `speaker_embedding`, `task_type`, `instructions`, `language`, and `word_timestamps`.
+- Concurrent requests at `max_num_seqs: 4` are supported. Native-AR recompute preemption is a known limitation of this architecture (a request that is preempted mid-generation can resume incorrectly); keep concurrency at or below `max_num_seqs` and treat preemption as out of scope until the platform fix lands.
+- Optional comparison against the upstream Gepard reference server needs Blackwell/Hopper + CUDA 13 + Postgres and is not part of CI.
+- For the request-field table, see the [Speech API Gepard section](https://github.com/vllm-project/vllm-omni/blob/main/docs/serving/speech_api.md#gepard-10).
+
+---
+
 ## higgs-audio v2
 
 2-stage TTS at 24 kHz: a vLLM-native Llama-3.2-3B talker with a DualFFN audio expert (Stage 0) feeding a HiggsAudio codec decoder (Stage 1) that streams chunks back to the client.
diff --git a/examples/offline_inference/text_to_speech/README.md b/examples/offline_inference/text_to_speech/README.md
index 954b96bd3e3..04ff1a97d84 100644
--- a/examples/offline_inference/text_to_speech/README.md
+++ b/examples/offline_inference/text_to_speech/README.md
@@ -19,7 +19,7 @@ list of supported architectures across all modalities, see
 | Breeze-TTS-2 | `BreezeBlue/Breeze-TTS-2` | 2 (talker + codec) | ✓ | ✓ (async chunk) | voice design / voice direction (`--instruction`) | 24 kHz |
 | CosyVoice3 | `FunAudioLLM/Fun-CosyVoice3-0.5B-2512` | 2 (talker + code2wav) | ✓ | ✓ | — | 24 kHz |
 | Fish Speech S2 Pro | `fishaudio/s2-pro` | dual-AR | ✓ | ✓ | — | 44.1 kHz |
-| Gepard-1.0 | `nineninesix/gepard-1.0` | single (native AR + NanoCodec) | — (zero-shot; cloning WIP) | — (serving WIP) | zero-shot | 22.05 kHz |
+| Gepard-1.0 | `nineninesix/gepard-1.0` | single (native AR + NanoCodec) | — (zero-shot; cloning later) | ✓ (online) | zero-shot | 22.05 kHz |
 | GLM-TTS | `zai-org/GLM-TTS` | 2 (AR + DiT) | ✓ (required) | ✓ | — | 24 kHz |
 | Ming-omni-tts | `inclusionAI/Ming-omni-tts-0.5B` | 2 (AR + audio VAE) | ✓ | ✓ | style / IP / dialect / TTA / podcast | 44.1 kHz |
 | Ming-flash-omni-TTS | `Jonathan1909/Ming-flash-omni-2.0` | single (talker only) | — (caption-controlled) | — | style / IP / basic captions | 44.1 kHz |
@@ -167,7 +167,7 @@ python examples/offline_inference/text_to_speech/glm_tts/end2end.py \
 ```
 
 ### Architecture
-```
+```text
 Text → [Stage 0: AR] → Speech Tokens → [Stage 1: DiT + HiFT] → Audio (24 kHz)
         (Llama-based)    (32k vocab)      (Flow Matching)
 ```
@@ -491,8 +491,8 @@ Not yet — PR1 is zero-shot only (the learned `null_prefix` default voice). Ref
 ### Notes
 - Output: 22.05 kHz mono WAV.
 - First run downloads two checkpoints, not one: the model itself, and the NanoCodec decoder it names in `codec_id` (`nvidia/nemo-nano-codec-22khz-1.89kbps-21.5fps` by default). Both are fetched automatically; expect the first startup to be correspondingly slower.
-- Offline only for now; the `/v1/audio/speech` adapter is a follow-up PR.
-- Deploy config: `vllm_omni/deploy/gepard.yaml` (the example's default; copy it and pass `--deploy-config` to change it).
+- Offline and online: `examples/offline_inference/text_to_speech/gepard/end2end.py` and `/v1/audio/speech` (see the [online Gepard section](../../online_serving/text_to_speech/README.md#gepard-10)).
+- Deploy config: `vllm_omni/deploy/gepard.yaml` (the example's default; copy it and pass `--deploy-config` to change it). Online serving **must** pass `--deploy-config vllm_omni/deploy/gepard.yaml` because the checkpoint self-identifies as `qwen3_5_text`.
 - Generation length and reproducibility are stage settings, not script flags. One output token is one audio frame, so `max_tokens` in the YAML is the frame budget; `seed` makes the in-model 32-head sampling reproducible. The script deliberately passes no `SamplingParams`: one supplied by a caller replaces the stage defaults wholesale rather than merging, which would drop the pipeline's stop token and run every request to `max_tokens`.
 - Text length: short texts are repeated internally to match the training layout (the checkpoint's `text_repetition` block); the upper bound is the stage's `max_model_len`, enforced by the engine. Empty text is rejected rather than voiced.
 - `VLLM_GEPARD_GREEDY=1` swaps the 32-head Gumbel-max sampling for argmax, for reproducible comparisons that do not depend on a seed.
diff --git a/examples/online_serving/text_to_speech/README.md b/examples/online_serving/text_to_speech/README.md
index 7ad939415f2..b749731e025 100644
--- a/examples/online_serving/text_to_speech/README.md
+++ b/examples/online_serving/text_to_speech/README.md
@@ -17,6 +17,7 @@ For the full list of supported architectures across all modalities, see
 | Breeze-TTS-2 | `BreezeBlue/Breeze-TTS-2` | ✓ (`ref_audio`+`ref_text`) | ✓ (PCM stream) | speaker tags (`S0`..`S9`, default `S0`) | — |
 | Audio8 TTS Preview | `Audio8/Audio8-TTS-Preview-0.6b` | ✓ (`ref_audio`+`ref_text`) | ✓ (PCM stream) | uploaded audio voice only; no presets | ✓ |
 | Fish Speech S2 Pro | `fishaudio/s2-pro` | ✓ (`ref_audio`+`ref_text`) | ✓ (PCM stream) | — | ✓ |
+| Gepard-1.0 | `nineninesix/gepard-1.0` | — (zero-shot default voice) | ✓ (PCM / WAV stream) | `default` only | — |
 | GLM-TTS | `zai-org/GLM-TTS` | ✓ (`ref_audio`+`ref_text`, required) | ✓ (PCM stream) | — | ✓ |
 | IndexTTS-2 | `IndexTeam/IndexTTS-2` | ✓ (`ref_audio` or uploaded `voice`) | `stream=true` response, non-chunk | uploaded audio voice only; no presets | — |
 | IndexTTS-2.5 | native `checkpoints/` bundle | ✓ (`ref_audio` or uploaded `voice`) | `stream=true` response, non-chunk | uploaded audio voice only; no presets | — |
@@ -96,12 +97,52 @@ curl -X POST http://localhost:8091/v1/audio/speech \
     }' --no-buffer | play -t raw -r 24000 -e signed -b 16 -c 1 -
 ```
 
-Adjust the player's sample rate to match the model (44.1 kHz for Fish Speech, 48 kHz for VoxCPM2, 22.05 kHz for IndexTTS-2, and 24 kHz for many others).
+Adjust the player's sample rate to match the model (44.1 kHz for Fish Speech, 48 kHz for VoxCPM2, 22.05 kHz for Gepard and IndexTTS-2, and 24 kHz for many others).
 
 For full request-shape documentation (all parameters, response formats, error codes), see the [Speech API reference](../../../docs/serving/speech_api.md).
 
 ---
 
+## Gepard-1.0
+
+Single-stage native AR TTS at 22.05 kHz mono. Zero-shot only: omit `voice` or pass `"default"`. Voice cloning from reference audio is not available yet.
+
+### Prerequisites
+
+Same NeMo NanoCodec install as the [offline Gepard section](../../offline_inference/text_to_speech/README.md#gepard-10). On a host whose CUDA toolkit cannot build kernels — no `nvcc`/`ninja`, or a consumer Blackwell (`sm_120`) card — also `export VLLM_USE_FLASHINFER_SAMPLER=0` before launch (same note as offline). That env is not a deploy-YAML field.
+
+### Launch
+
+```bash
+vllm-omni serve nineninesix/gepard-1.0 --omni --port 8091 --trust-remote-code \
+    --stage-init-timeout 900 \
+    --deploy-config vllm_omni/deploy/gepard.yaml
+# or:
+./gepard/run_server.sh
+```
+
+`--stage-init-timeout 900` matches the online e2e fixture and the offline example. Serve defaults to 300s, which is often too short for a cold download of the talker plus NanoCodec.
+
+The packaged `vllm_omni/deploy/gepard.yaml` must be passed with `--deploy-config`. The checkpoint self-identifies as `qwen3_5_text`, so omitting the YAML launches a diffusion fallback instead of the Gepard pipeline. The YAML sets `async_chunk: false`, `max_num_seqs: 4`, and currently pins `seed: 42`, so serving is deterministic by default until that YAML seed is removed. Pass an explicit per-request `seed` in tests and clients rather than depending on either default.
+
+### Sending requests
+
+```bash
+python examples/online_serving/text_to_speech/gepard/speech_client.py \
+    --text "Hello, this is Gepard speaking."
+
+python examples/online_serving/text_to_speech/gepard/speech_client.py \
+    --text "Hello, this is Gepard speaking." --seed 7 --stream --output output.pcm
+```
+
+### Notes
+
+- Output: 22.05 kHz mono. `max_new_tokens` is a **frame** budget (1 token = 1 frame = 1024 samples ≈ 46.4 ms at 21.5 fps; adapter bounds 1..4096).
+- Supported request fields: `input` (required), `voice` (`default` only), `response_format` (`wav` default; `wav/pcm/flac/mp3` non-streaming; `opus` 400 because 22.05 kHz is not an Opus sample rate; streaming `pcm/wav` only), `stream` / `stream_format`, `max_new_tokens`, `seed`.
+- Unsupported: `speed`, `extra_params` (including `temperature`/`top_p`/`top_k`), `ref_audio`, `ref_text`, `speaker_embedding`, `task_type`, `instructions`, `language`, and `word_timestamps`.
+- Concurrent requests at `max_num_seqs: 4` are supported. Native-AR recompute preemption is a known limitation of this architecture (a request that is preempted mid-generation can resume incorrectly); keep concurrency at or below `max_num_seqs` and treat preemption as out of scope until the platform fix lands.
+- Optional comparison against the upstream Gepard reference server needs Blackwell/Hopper + CUDA 13 + Postgres and is not part of CI.
+
 ## dots.tts
 
 Single-stage, text-only TTS at 48 kHz. The current integration supports
diff --git a/examples/online_serving/text_to_speech/gepard/run_server.sh b/examples/online_serving/text_to_speech/gepard/run_server.sh
new file mode 100755
index 00000000000..420591288d1
--- /dev/null
+++ b/examples/online_serving/text_to_speech/gepard/run_server.sh
@@ -0,0 +1,33 @@
+#!/bin/bash
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+# Launch vLLM-Omni server for Gepard-1.0 TTS (zero-shot default voice).
+#
+# Usage:
+#   ./run_server.sh
+#   CUDA_VISIBLE_DEVICES=0 ./run_server.sh
+#
+# Packaged deploy config: vllm_omni/deploy/gepard.yaml (async_chunk=false,
+# 22.05 kHz mono, default seed 42 until the YAML seed is removed).
+# Cold start downloads the talker and NeMo NanoCodec; the serve default of
+# --stage-init-timeout 300 is too tight (offline end2end.py uses 900).
+#
+# On a host whose CUDA toolkit cannot JIT FlashInfer (no nvcc/ninja, or a
+# consumer Blackwell sm_120 card), also:
+#   export VLLM_USE_FLASHINFER_SAMPLER=0
+
+set -e
+
+MODEL="${MODEL:-nineninesix/gepard-1.0}"
+PORT="${PORT:-8091}"
+
+echo "Starting Gepard-1.0 server with model: $MODEL"
+
+vllm-omni serve "$MODEL" \
+    --host 0.0.0.0 \
+    --port "$PORT" \
+    --trust-remote-code \
+    --omni \
+    --stage-init-timeout 900 \
+    --deploy-config vllm_omni/deploy/gepard.yaml
diff --git a/examples/online_serving/text_to_speech/gepard/speech_client.py b/examples/online_serving/text_to_speech/gepard/speech_client.py
new file mode 100755
index 00000000000..4db4f1c7d40
--- /dev/null
+++ b/examples/online_serving/text_to_speech/gepard/speech_client.py
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Client for Gepard-1.0 TTS via /v1/audio/speech.
+
+Gepard is zero-shot: omit ``voice`` or pass ``"default"``. Output is 22.05 kHz
+mono. ``seed`` is optional; the packaged deploy YAML currently pins ``seed: 42``
+until that default is removed, so requests without an explicit seed are still
+deterministic.
+
+Examples:
+    python speech_client.py --text "Hello, this is Gepard speaking."
+    python speech_client.py --text "Hello, this is Gepard speaking." --seed 7
+    python speech_client.py --text "Hello, this is Gepard speaking." --stream --output output.pcm
+"""
+
+from __future__ import annotations
+
+import argparse
+
+import httpx
+
+DEFAULT_API_BASE = "http://localhost:8091"
+DEFAULT_API_KEY = "EMPTY"
+DEFAULT_MODEL = "nineninesix/gepard-1.0"
+
+
+def run_tts(args) -> None:
+    payload = {
+        "model": args.model,
+        "input": args.text,
+        "voice": args.voice,
+        "response_format": args.response_format,
+    }
+    if args.seed is not None:
+        payload["seed"] = args.seed
+    if args.max_new_tokens is not None:
+        payload["max_new_tokens"] = args.max_new_tokens
+    if args.stream:
+        payload["stream"] = True
+        payload["stream_format"] = "audio"
+        if args.response_format not in ("pcm", "wav"):
+            print(f"Note: streaming requires pcm/wav; overriding --response-format {args.response_format} to 'pcm'")
+            payload["response_format"] = "pcm"
+
+    print(f"Model: {args.model}")
+    print(f"Text: {args.text}")
+    print(f"Voice: {args.voice}")
+    if args.seed is not None:
+        print(f"Seed: {args.seed}")
+    print("Generating audio...")
+
+    api_url = f"{args.api_base}/v1/audio/speech"
+    headers = {
+        "Content-Type": "application/json",
+        "Authorization": f"Bearer {args.api_key}",
+    }
+
+    if args.stream:
+        output_path = args.output or ("output.wav" if payload["response_format"] == "wav" else "output.pcm")
+        with httpx.Client(timeout=300.0) as client:
+            with client.stream("POST", api_url, json=payload, headers=headers) as resp:
+                if resp.status_code != 200:
+                    print(f"Error: {resp.status_code}")
+                    print(resp.read().decode())
+                    return
+                total_bytes = 0
+                with open(output_path, "wb") as f:
+                    for chunk in resp.iter_bytes():
+                        f.write(chunk)
+                        total_bytes += len(chunk)
+                print(f"Streamed {total_bytes} bytes to: {output_path}")
+        return
+
+    with httpx.Client(timeout=300.0) as client:
+        response = client.post(api_url, json=payload, headers=headers)
+
+    if response.status_code != 200:
+        print(f"Error: {response.status_code}")
+        print(response.text)
+        return
+
+    output_path = args.output or "output.wav"
+    with open(output_path, "wb") as f:
+        f.write(response.content)
+    print(f"Audio saved to: {output_path}")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Gepard-1.0 TTS client")
+    parser.add_argument("--api-base", default=DEFAULT_API_BASE, help="API base URL")
+    parser.add_argument("--api-key", default=DEFAULT_API_KEY, help="API key")
+    parser.add_argument("--model", "-m", default=DEFAULT_MODEL, help="Model name")
+    parser.add_argument("--text", required=True, help="Text to synthesize")
+    parser.add_argument("--voice", default="default", help="Voice name (only 'default' is supported)")
+    parser.add_argument("--seed", type=int, default=None, help="Sampling seed")
+    parser.add_argument(
+        "--max-new-tokens",
+        type=int,
+        default=None,
+        help="Frame budget (1 token = 1 frame ≈ 46.4 ms at 21.5 fps)",
+    )
+    parser.add_argument("--stream", action="store_true", help="Enable streaming (PCM output)")
+    parser.add_argument(
+        "--response-format",
+        default="wav",
+        choices=["wav", "mp3", "flac", "pcm"],
+        help="Audio format (default: wav). Streaming is pcm/wav only. Opus is not supported at 22.05 kHz.",
+    )
+    parser.add_argument("--output", "-o", default=None, help="Output file path")
+    args = parser.parse_args()
+    run_tts(args)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/e2e/online_serving/test_gepard_tts.py b/tests/e2e/online_serving/test_gepard_tts.py
new file mode 100644
index 00000000000..e6887bbbcac
--- /dev/null
+++ b/tests/e2e/online_serving/test_gepard_tts.py
@@ -0,0 +1,524 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""E2E online serving tests for Gepard-1.0 via ``/v1/audio/speech``.
+
+Zero-shot default voice. Needs a GPU and the NeMo NanoCodec; the weekly
+``TTS · Gepard-1.0 · L4`` step installs NeMo then runs this file.
+"""
+
+from __future__ import annotations
+
+import array
+import os
+import statistics
+import struct
+import time
+import wave
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from io import BytesIO
+
+os.environ.setdefault("VLLM_WORKER_MULTIPROC_METHOD", "spawn")
+
+import pytest
+import requests
+import soundfile as sf
+
+from tests.helpers.mark import hardware_test
+from tests.helpers.media import convert_audio_bytes_to_text
+from tests.helpers.runtime import OmniServerParams
+from tests.helpers.stage_config import get_deploy_config_path
+
+pytest.importorskip("nemo.collections.tts.models")
+
+pytestmark = [pytest.mark.slow, pytest.mark.tts]
+
+MODEL = "nineninesix/gepard-1.0"
+SAMPLE_RATE = 22050
+SAMPLES_PER_FRAME = 1024
+PCM16_BYTES_PER_FRAME = SAMPLES_PER_FRAME * 2
+DEFAULT_TIMEOUT_S = 180.0
+
+_DISTINGUISHABLE_PROMPTS = {
+    "He drinks coffee every morning.": "coffee",
+    "Machine learning is interesting.": "learning",
+    "Please close the window before leaving.": "window",
+    "My favorite color is purple.": "purple",
+}
+
+tts_server_params = [
+    pytest.param(
+        OmniServerParams(
+            model=MODEL,
+            stage_config_path=get_deploy_config_path("gepard.yaml"),
+            server_args=["--trust-remote-code", "--disable-log-stats"],
+            stage_init_timeout=900,
+        ),
+        id="gepard",
+    )
+]
+
+
+def _base_config(omni_server, text: str, **extra) -> dict:
+    cfg = {
+        "model": omni_server.model,
+        "input": text,
+        "voice": "default",
+        "timeout": DEFAULT_TIMEOUT_S,
+        "seed": 7,
+        # NanoCodec is quieter than the 24 kHz models the PCM HNR helper was
+        # calibrated on; keep the catastrophic-failure check, not a quality gate.
+        "min_hnr_db": -2.0,
+        "transcript_escalation_model": "large-v3",
+    }
+    cfg.update(extra)
+    return cfg
+
+
+def _wav_sample_rate(wav_bytes: bytes) -> int:
+    return struct.unpack_from("<I", wav_bytes, 24)[0]
+
+
+def _wav_pcm_payload_len(wav_bytes: bytes) -> int:
+    data, _sr = sf.read(BytesIO(wav_bytes), dtype="int16")
+    return int(data.size) * 2
+
+
+def _pcm16le_to_wav(pcm: bytes, sample_rate: int = SAMPLE_RATE) -> bytes:
+    """Whisper helpers expect a container; streamed speech is raw s16le."""
+    buf = BytesIO()
+    with wave.open(buf, "wb") as wf:
+        wf.setnchannels(1)
+        wf.setsampwidth(2)
+        wf.setframerate(sample_rate)
+        wf.writeframes(pcm)
+    return buf.getvalue()
+
+
+def _pcm16_samples(pcm: bytes) -> array.array:
+    samples = array.array("h")
+    samples.frombytes(pcm)
+    return samples
+
+
+def _pcm16_diag(label: str, left: bytes, right: bytes) -> None:
+    extra_frames = (len(left) - len(right)) // PCM16_BYTES_PER_FRAME
+    overlap = min(len(left), len(right))
+    first_frame_match = (
+        overlap >= PCM16_BYTES_PER_FRAME and left[:PCM16_BYTES_PER_FRAME] == right[:PCM16_BYTES_PER_FRAME]
+    )
+    worst = None
+    corr = None
+    first_diff_sample = None
+    if overlap >= 2 and overlap % 2 == 0:
+        a = _pcm16_samples(left[:overlap])
+        b = _pcm16_samples(right[:overlap])
+        worst = max(abs(x - y) for x, y in zip(a, b, strict=True))
+        for i, (x, y) in enumerate(zip(a, b, strict=True)):
+            if x != y:
+                first_diff_sample = i
+                break
+        try:
+            corr = round(statistics.correlation(a, b), 6)
+        except statistics.StatisticsError:
+            corr = None
+    print(
+        f"[Gepard pcm-diag] {label} left={len(left)} right={len(right)} "
+        f"extra_frames={extra_frames} first_frame_match={first_frame_match} "
+        f"first_diff_sample={first_diff_sample} max_abs={worst} corr={corr}"
+    )
+
+
+def _scan_logs_for_preemption(omni_server) -> None:
+    log_paths = getattr(omni_server, "_stage_log_paths", {}) or {}
+    hits: list[str] = []
+    for path in log_paths.values():
+        if path is None or not path.exists():
+            continue
+        text = path.read_text(encoding="utf-8", errors="replace").lower()
+        if "preempt" in text:
+            hits.append(str(path))
+    assert not hits, f"preemption mentioned in stage logs: {hits}"
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+@pytest.mark.parametrize("response_format", ["wav", "pcm"])
+def test_text_to_audio_basic(omni_server, online_client, response_format: str, run_level: str) -> None:
+    text = "Hello, this is Gepard speaking."
+    # whisper-small/large-v3 mishear 22.05 kHz WAV of this prompt as
+    # "Jeb Ard" / "Jeff Bard" (cosine 0.80 / 0.75). Offline uses keyword
+    # containment; the PCM twin below still goes through the 0.9 ASR gate.
+    if response_format == "wav":
+        url = f"http://{omni_server.host}:{omni_server.port}/v1/audio/speech"
+        payload = {
+            "model": omni_server.model,
+            "input": text,
+            "voice": "default",
+            "seed": 7,
+            "stream": False,
+            "response_format": "wav",
+        }
+        r = requests.post(url, json=payload, timeout=DEFAULT_TIMEOUT_S)
+        r.raise_for_status()
+        audio = r.content
+        assert _wav_sample_rate(audio) == SAMPLE_RATE
+        pcm_len = _wav_pcm_payload_len(audio)
+    else:
+        [resp] = online_client.send_audio_speech_request(
+            _base_config(omni_server, text, stream=False, response_format=response_format)
+        )
+        assert resp.audio_bytes
+        pcm_len = len(resp.audio_bytes)
+    assert pcm_len % PCM16_BYTES_PER_FRAME == 0
+    if run_level in {"advanced_model", "full_model"}:
+        duration = pcm_len / 2 / SAMPLE_RATE
+        assert 0.5 < duration < 30.0, f"implausible duration {duration:.2f}s"
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_seed_determinism(omni_server, online_client) -> None:
+    text = "Hello, this is Gepard speaking."
+    [a] = online_client.send_audio_speech_request(_base_config(omni_server, text, seed=7, response_format="pcm"))
+    [b] = online_client.send_audio_speech_request(_base_config(omni_server, text, seed=7, response_format="pcm"))
+    [c] = online_client.send_audio_speech_request(_base_config(omni_server, text, seed=11, response_format="pcm"))
+    assert a.audio_bytes == b.audio_bytes
+    assert a.audio_bytes != c.audio_bytes
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_streaming_pcm_incremental(omni_server, online_client) -> None:
+    text = "Hello, this is Gepard speaking."
+    url = f"http://{omni_server.host}:{omni_server.port}/v1/audio/speech"
+    payload = {
+        "model": omni_server.model,
+        "input": text,
+        "voice": "default",
+        "seed": 7,
+        "stream": True,
+        "stream_format": "audio",
+        "response_format": "pcm",
+    }
+    start = time.perf_counter()
+    arrivals: list[tuple[float, int]] = []
+    streamed = bytearray()
+    with requests.post(url, json=payload, stream=True, timeout=DEFAULT_TIMEOUT_S) as resp:
+        resp.raise_for_status()
+        content_type = resp.headers.get("content-type") or ""
+        assert "pcm" in content_type or "octet-stream" in content_type
+        for chunk in resp.iter_content(chunk_size=None):
+            if not chunk:
+                continue
+            arrivals.append((time.perf_counter(), len(chunk)))
+            streamed.extend(chunk)
+    assert len(arrivals) >= 2, f"expected incremental chunks, got {len(arrivals)}"
+    assert arrivals[1][0] > arrivals[0][0]
+    ttfa_ms = (arrivals[0][0] - start) * 1000.0
+    cadence_ms = [(arrivals[i][0] - arrivals[i - 1][0]) * 1000.0 for i in range(1, len(arrivals))]
+    print(f"[Gepard streaming] TTFA_ms={ttfa_ms:.1f} chunk_cadence_ms={cadence_ms}")
+
+    [non_stream] = online_client.send_audio_speech_request(
+        _base_config(omni_server, text, seed=7, stream=False, response_format="pcm")
+    )
+    assert bytes(streamed) == non_stream.audio_bytes
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_seeded_streaming_stops(omni_server) -> None:
+    url = f"http://{omni_server.host}:{omni_server.port}/v1/audio/speech"
+    payload = {
+        "model": omni_server.model,
+        "input": "Hello, this is Gepard speaking.",
+        "voice": "default",
+        "seed": 7,
+        "stream": True,
+        "stream_format": "audio",
+        "response_format": "pcm",
+    }
+    with requests.post(url, json=payload, stream=True, timeout=DEFAULT_TIMEOUT_S) as resp:
+        resp.raise_for_status()
+        audio = b"".join(chunk for chunk in resp.iter_content(chunk_size=None) if chunk)
+    duration = len(audio) / 2 / SAMPLE_RATE
+    assert duration < 30.0, f"seeded stream ran {duration:.1f}s — stop constraint dropped?"
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_sse_stream_emits_delta_then_done(omni_server) -> None:
+    url = f"http://{omni_server.host}:{omni_server.port}/v1/audio/speech"
+    payload = {
+        "model": omni_server.model,
+        "input": "Hello, this is Gepard speaking.",
+        "voice": "default",
+        "seed": 7,
+        "stream": True,
+        "stream_format": "sse",
+        "response_format": "pcm",
+    }
+    with requests.post(url, json=payload, stream=True, timeout=DEFAULT_TIMEOUT_S) as resp:
+        resp.raise_for_status()
+        assert resp.headers.get("content-type", "").startswith("text/event-stream")
+        body = b"".join(resp.iter_content(chunk_size=None)).decode("utf-8", errors="replace")
+    assert "speech.audio.delta" in body
+    assert "speech.audio.done" in body
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_concurrent_requests_stay_isolated(omni_server, online_client, run_level: str) -> None:
+    def _one(text: str):
+        return online_client.send_audio_speech_request(_base_config(omni_server, text, seed=7, response_format="wav"))[
+            0
+        ]
+
+    texts = list(_DISTINGUISHABLE_PROMPTS)
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        responses = list(pool.map(_one, texts))
+
+    assert all(r.success for r in responses)
+    for i in range(len(responses)):
+        for j in range(i + 1, len(responses)):
+            assert responses[i].audio_bytes != responses[j].audio_bytes
+
+    if run_level in {"advanced_model", "full_model"}:
+        for text, resp in zip(texts, responses, strict=True):
+            keyword = _DISTINGUISHABLE_PROMPTS[text]
+            transcript = convert_audio_bytes_to_text(resp.audio_bytes, language="en").lower()
+            assert keyword in transcript, f"expected {keyword!r} in {transcript!r} for {text!r}"
+
+    _scan_logs_for_preemption(omni_server)
+
+
+def _speech_url(omni_server) -> str:
+    return f"http://{omni_server.host}:{omni_server.port}/v1/audio/speech"
+
+
+def _stream_payload(omni_server, text: str, **extra) -> dict:
+    payload = {
+        "model": omni_server.model,
+        "input": text,
+        "voice": "default",
+        "seed": 7,
+        "stream": True,
+        "stream_format": "audio",
+        "response_format": "pcm",
+    }
+    payload.update(extra)
+    return payload
+
+
+@dataclass
+class _StreamCapture:
+    pcm: bytes
+    arrivals: list[tuple[float, int]]
+
+    @property
+    def duration_s(self) -> float:
+        return len(self.pcm) / 2 / SAMPLE_RATE
+
+
+def _capture_stream(
+    url: str,
+    payload: dict,
+    timeout_s: float,
+    *,
+    sleep_after_first_s: float = 0.0,
+) -> _StreamCapture:
+    start = time.perf_counter()
+    arrivals: list[tuple[float, int]] = []
+    pcm = bytearray()
+    with requests.post(url, json=payload, stream=True, timeout=timeout_s) as resp:
+        resp.raise_for_status()
+        first = True
+        for chunk in resp.iter_content(chunk_size=None):
+            if not chunk:
+                continue
+            arrivals.append((time.perf_counter() - start, len(chunk)))
+            pcm.extend(chunk)
+            if first and sleep_after_first_s > 0:
+                time.sleep(sleep_after_first_s)
+            first = False
+    return _StreamCapture(bytes(pcm), arrivals)
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_concurrent_streaming_stays_isolated(omni_server, run_level: str) -> None:
+    url = _speech_url(omni_server)
+    texts = list(_DISTINGUISHABLE_PROMPTS)
+
+    def _one(text: str) -> tuple[str, _StreamCapture]:
+        return text, _capture_stream(url, _stream_payload(omni_server, text), DEFAULT_TIMEOUT_S)
+
+    with ThreadPoolExecutor(max_workers=4) as pool:
+        results = list(pool.map(_one, texts))
+
+    captures = [cap for _, cap in results]
+    assert all(len(c.arrivals) >= 2 for c in captures)
+    for i in range(len(captures)):
+        for j in range(i + 1, len(captures)):
+            assert captures[i].pcm != captures[j].pcm
+
+    if run_level in {"advanced_model", "full_model"}:
+        for text, cap in results:
+            keyword = _DISTINGUISHABLE_PROMPTS[text]
+            transcript = convert_audio_bytes_to_text(_pcm16le_to_wav(cap.pcm), language="en").lower()
+            assert keyword in transcript, f"expected {keyword!r} in {transcript!r} for {text!r}"
+
+    _scan_logs_for_preemption(omni_server)
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_slow_client_still_completes(omni_server, online_client) -> None:
+    """Slow reader must finish, and seed=7 must match a prior non-stream.
+
+    Runs before ``test_client_disconnect_releases_capacity`` so an abort
+    storm cannot contaminate this comparison. Prints overlap diagnostics
+    before the bit-exact asserts.
+    """
+    text = "Hello, this is Gepard speaking."
+    [baseline] = online_client.send_audio_speech_request(
+        _base_config(omni_server, text, seed=7, stream=False, response_format="pcm")
+    )
+    cap = _capture_stream(
+        url=_speech_url(omni_server),
+        payload=_stream_payload(omni_server, text),
+        timeout_s=DEFAULT_TIMEOUT_S,
+        sleep_after_first_s=3.0,
+    )
+    assert len(cap.arrivals) >= 2
+    assert len(cap.pcm) % PCM16_BYTES_PER_FRAME == 0
+    assert 0.5 < cap.duration_s < 30.0
+    print(f"[Gepard slow-client] chunks={len(cap.arrivals)} duration_s={cap.duration_s:.3f}")
+    _pcm16_diag("slow-vs-prior-nonstream", cap.pcm, baseline.audio_bytes)
+    [after] = online_client.send_audio_speech_request(
+        _base_config(omni_server, text, seed=7, stream=False, response_format="pcm")
+    )
+    _pcm16_diag("after-nonstream-vs-prior", after.audio_bytes, baseline.audio_bytes)
+    assert cap.pcm == baseline.audio_bytes
+    assert after.audio_bytes == baseline.audio_bytes
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_client_disconnect_releases_capacity(omni_server, online_client) -> None:
+    """A follow-up request must complete after in-flight streams are closed.
+
+    Logs PCM diagnostics against a pre-abort ``seed=7`` baseline. Bit-exact
+    equality after abort is not asserted here: a dying stream can still share
+    a GPU batch with the next generate after ``abort()`` returns, and Gepard's
+    in-model stop head / bf16 GEMM are not row-stable in that batch.
+    """
+    url = _speech_url(omni_server)
+    text = "Hello, this is Gepard speaking."
+    [baseline] = online_client.send_audio_speech_request(
+        _base_config(omni_server, text, seed=7, stream=False, response_format="pcm")
+    )
+    long_payload = _stream_payload(
+        omni_server,
+        "Please keep talking about the weather, the window, coffee, and purple flowers.",
+        max_new_tokens=80,
+    )
+    for _ in range(4):
+        resp = requests.post(url, json=long_payload, stream=True, timeout=DEFAULT_TIMEOUT_S)
+        resp.raise_for_status()
+        try:
+            chunk = next(c for c in resp.iter_content(chunk_size=None) if c)
+            assert chunk
+        finally:
+            resp.close()
+
+    t0 = time.perf_counter()
+    follow = requests.post(
+        url,
+        json={
+            "model": omni_server.model,
+            "input": text,
+            "voice": "default",
+            "seed": 7,
+            "stream": False,
+            "response_format": "pcm",
+        },
+        timeout=DEFAULT_TIMEOUT_S,
+    )
+    follow.raise_for_status()
+    elapsed = time.perf_counter() - t0
+    pcm_len = len(follow.content)
+    assert pcm_len % PCM16_BYTES_PER_FRAME == 0
+    print(f"[Gepard disconnect] followup_s={elapsed:.2f} pcm_bytes={pcm_len}")
+    _pcm16_diag("disconnect-followup-vs-prior", follow.content, baseline.audio_bytes)
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_mixed_stream_and_nonstream_isolated(omni_server, online_client, run_level: str) -> None:
+    url = _speech_url(omni_server)
+    stream_text = "He drinks coffee every morning."
+    nonstream_text = "My favorite color is purple."
+
+    def _stream():
+        return _capture_stream(url, _stream_payload(omni_server, stream_text), DEFAULT_TIMEOUT_S)
+
+    def _nonstream():
+        return online_client.send_audio_speech_request(
+            _base_config(omni_server, nonstream_text, seed=7, response_format="wav")
+        )[0]
+
+    with ThreadPoolExecutor(max_workers=2) as pool:
+        stream_future = pool.submit(_stream)
+        nonstream_future = pool.submit(_nonstream)
+        streamed = stream_future.result()
+        nonstream = nonstream_future.result()
+
+    assert streamed.pcm
+    assert nonstream.success
+    assert streamed.pcm != nonstream.audio_bytes
+    if run_level in {"advanced_model", "full_model"}:
+        stream_tr = convert_audio_bytes_to_text(_pcm16le_to_wav(streamed.pcm), language="en").lower()
+        nonstream_tr = convert_audio_bytes_to_text(nonstream.audio_bytes, language="en").lower()
+        assert "coffee" in stream_tr, stream_tr
+        assert "purple" in nonstream_tr, nonstream_tr
+    _scan_logs_for_preemption(omni_server)
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
+def test_max_new_tokens_caps_whole_frames(omni_server) -> None:
+    frames = 16
+    url = _speech_url(omni_server)
+    r = requests.post(
+        url,
+        json={
+            "model": omni_server.model,
+            "input": "Hello, this is Gepard speaking.",
+            "voice": "default",
+            "seed": 7,
+            "stream": False,
+            "response_format": "pcm",
+            "max_new_tokens": frames,
+        },
+        timeout=DEFAULT_TIMEOUT_S,
+    )
+    assert r.status_code == 200, r.text
+    pcm_len = len(r.content)
+    assert pcm_len % PCM16_BYTES_PER_FRAME == 0
+    assert pcm_len == frames * PCM16_BYTES_PER_FRAME, f"got {pcm_len} bytes, want {frames} frames"
+    duration = pcm_len / 2 / SAMPLE_RATE
+    assert duration < 1.0, f"budget cap should stop near 16 frames, got {duration:.2f}s"
+
+    over = requests.post(
+        url,
+        json={
+            "model": omni_server.model,
+            "input": "Hello, this is Gepard speaking.",
+            "voice": "default",
+            "max_new_tokens": 4097,
+        },
+        timeout=DEFAULT_TIMEOUT_S,
+    )
+    assert over.status_code == 400
+    assert "max_new_tokens" in over.text
diff --git a/tests/entrypoints/openai_api/test_gepard_tts_adapter.py b/tests/entrypoints/openai_api/test_gepard_tts_adapter.py
new file mode 100644
index 00000000000..f9e1e3dd235
--- /dev/null
+++ b/tests/entrypoints/openai_api/test_gepard_tts_adapter.py
@@ -0,0 +1,276 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""CPU tests for the Gepard-1.0 speech adapter.
+
+Covers detection, the reject matrix, voice default, empty input, extra_params,
+max_new_tokens frame bounds, and build() parity with the offline prompt helper.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+import torch
+from pydantic import ValidationError
+from pytest_mock import MockerFixture
+
+from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
+from vllm_omni.entrypoints.openai.serving_speech import OmniOpenAIServingSpeech
+from vllm_omni.entrypoints.openai.tts_adapters import detect_tts_model_type, resolve_adapter
+from vllm_omni.entrypoints.openai.tts_adapters.base import SpeechServingContext
+from vllm_omni.entrypoints.openai.tts_adapters.gepard import GepardAdapter
+from vllm_omni.model_executor.models.gepard.configuration_gepard import GepardConfig
+from vllm_omni.model_executor.models.gepard.prompt import build_gepard_prompt_ids
+from vllm_omni.outputs import OmniRequestOutput
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+_MODEL = "nineninesix/gepard-1.0"
+
+
+def _adapter(*, revision: str | None = None) -> GepardAdapter:
+    engine = SimpleNamespace(model_config=SimpleNamespace(model=_MODEL, revision=revision))
+    return GepardAdapter(SpeechServingContext(server=SimpleNamespace(engine_client=engine), engine_client=engine))
+
+
+def test_gepard_detection_and_registration() -> None:
+    assert resolve_adapter("gepard") is GepardAdapter
+    assert GepardAdapter.stage_keys == {"gepard"}
+    assert GepardAdapter.model_archs == {"GepardTalkerForConditionalGeneration"}
+    assert detect_tts_model_type("gepard", None) == "gepard"
+    assert detect_tts_model_type("gepard", "GepardTalkerForConditionalGeneration") == "gepard"
+    assert detect_tts_model_type(None, "GepardTalkerForConditionalGeneration") == "gepard"
+
+
+def test_gepard_accepts_omitted_and_default_voice() -> None:
+    adapter = _adapter()
+    assert adapter.validate(OpenAICreateSpeechRequest(input="Hello from Gepard.")) is None
+    assert adapter.validate(OpenAICreateSpeechRequest(input="Hello from Gepard.", voice="default")) is None
+    assert adapter.validate(OpenAICreateSpeechRequest(input="Hello from Gepard.", voice="Default")) is None
+    assert (
+        adapter.validate(
+            OpenAICreateSpeechRequest.model_validate({"input": "Hello from Gepard.", "speaker": "default"})
+        )
+        is None
+    )
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "field"),
+    [
+        ({"voice": "vivian"}, "voice"),
+        ({"speed": 1.2}, "speed"),
+        ({"extra_params": {"temperature": 0.3}}, "extra_params"),
+        ({"extra_params": {"top_p": 0.9}}, "extra_params"),
+        ({"extra_params": {"top_k": 20}}, "extra_params"),
+        ({"extra_params": {"foo": 1}}, "extra_params"),
+        ({"ref_audio": "https://example.com/ref.wav"}, "ref_audio"),
+        ({"ref_text": "transcript"}, "ref_text"),
+        ({"ref_audio_2": "https://example.com/ref2.wav"}, "ref_audio_2"),
+        ({"speaker_embedding": [0.1, 0.2]}, "speaker_embedding"),
+        ({"x_vector_only_mode": True}, "x_vector_only_mode"),
+        ({"task_type": "Base"}, "task_type"),
+        ({"non_streaming_mode": True}, "non_streaming_mode"),
+        ({"instructions": "speak happily"}, "instructions"),
+        ({"language": "English"}, "language"),
+        ({"ambient_sound": "rain"}, "ambient_sound"),
+        ({"duration_seconds": 2.0}, "duration_seconds"),
+        ({"initial_codec_chunk_frames": 4}, "initial_codec_chunk_frames"),
+        ({"word_timestamps": True}, "word_timestamps"),
+        ({"response_format": "opus"}, "opus"),
+    ],
+)
+def test_gepard_rejects_unsupported_fields(kwargs: dict, field: str) -> None:
+    adapter = _adapter()
+    err = adapter.validate(OpenAICreateSpeechRequest(input="Hello from Gepard.", **kwargs))
+    assert err is not None
+    assert field in err
+
+
+@pytest.mark.parametrize("text", ["", "   ", "\n\t"])
+def test_gepard_rejects_empty_input(text: str) -> None:
+    adapter = _adapter()
+    err = adapter.validate(OpenAICreateSpeechRequest(input=text))
+    assert err is not None
+    assert "empty" in err.lower()
+
+
+@pytest.mark.parametrize("max_new_tokens", [0, -1])
+def test_gepard_schema_rejects_non_positive_max_new_tokens(max_new_tokens: int) -> None:
+    with pytest.raises(ValidationError, match="greater than or equal to 1"):
+        OpenAICreateSpeechRequest(input="Hello from Gepard.", max_new_tokens=max_new_tokens)
+
+
+def test_gepard_rejects_max_new_tokens_above_frame_budget() -> None:
+    adapter = _adapter()
+    err = adapter.validate(OpenAICreateSpeechRequest(input="Hello from Gepard.", max_new_tokens=4097))
+    assert err is not None
+    assert "max_new_tokens" in err
+    assert "frames" in err
+
+
+def test_gepard_accepts_max_new_tokens_bounds() -> None:
+    adapter = _adapter()
+    assert adapter.validate(OpenAICreateSpeechRequest(input="Hello from Gepard.", max_new_tokens=1)) is None
+    assert adapter.validate(OpenAICreateSpeechRequest(input="Hello from Gepard.", max_new_tokens=4096)) is None
+
+
+def test_gepard_apply_sampling_overrides_uses_frames() -> None:
+    adapter = _adapter()
+    stage_defaults = [SimpleNamespace(max_tokens=1000)]
+    overridden = adapter.apply_sampling_overrides(
+        stage_defaults,
+        OpenAICreateSpeechRequest(input="Hello from Gepard.", max_new_tokens=32),
+    )
+    assert overridden[0].max_tokens == 32
+    assert stage_defaults[0].max_tokens == 1000
+
+
+def test_gepard_build_matches_offline_prompt_builder(monkeypatch) -> None:
+    adapter = _adapter()
+    cfg = GepardConfig()
+    monkeypatch.setattr(
+        "vllm_omni.model_executor.models.gepard.configuration_gepard.GepardConfig.from_checkpoint",
+        staticmethod(lambda *_a, **_k: cfg),
+    )
+
+    class _Tok:
+        def __call__(self, text, add_special_tokens=False):
+            return {"input_ids": [11, 12, 13]}
+
+    adapter._tokenizer = _Tok()
+    adapter._gepard_config = cfg
+    text = "Hello from Gepard."
+    prepared = asyncio.run(adapter.build(OpenAICreateSpeechRequest(input=text, seed=7), [], False))
+
+    expected = build_gepard_prompt_ids([11, 12, 13], config=cfg)
+    assert prepared.prompt["prompt_token_ids"] == expected
+    assert prepared.prompt["additional_information"] == {"text": [text]}
+    assert prepared.model_type == "gepard"
+    assert prepared.output_policy.accumulate_nonstreaming is True
+
+
+def test_gepard_loads_tokenizer_and_config_at_served_revision(monkeypatch) -> None:
+    adapter = _adapter(revision="abc123")
+    seen: dict[str, object] = {}
+
+    def fake_from_checkpoint(model, backbone_config=None, revision=None):
+        seen["config"] = (model, revision)
+        return GepardConfig()
+
+    class _Tok:
+        def __init__(self, *args, **kwargs):
+            seen["tok"] = (args[0] if args else None, kwargs.get("revision"))
+
+        def __call__(self, text, add_special_tokens=False):
+            return {"input_ids": [11, 12, 13]}
+
+    monkeypatch.setattr(
+        "vllm_omni.model_executor.models.gepard.configuration_gepard.GepardConfig.from_checkpoint",
+        staticmethod(fake_from_checkpoint),
+    )
+    monkeypatch.setattr("transformers.AutoTokenizer.from_pretrained", _Tok)
+    prepared = asyncio.run(adapter.build(OpenAICreateSpeechRequest(input="Hello from Gepard."), [], False))
+    assert seen["config"] == (_MODEL, "abc123")
+    assert seen["tok"] == (_MODEL, "abc123")
+    assert prepared.prompt["prompt_token_ids"] == build_gepard_prompt_ids([11, 12, 13], config=GepardConfig())
+
+
+def _gepard_mock_output(sample_rate: int = 22050, num_samples: int = 2048) -> OmniRequestOutput:
+    class MockCompletionOutput:
+        def __init__(self) -> None:
+            self.index = 0
+            self.text = ""
+            self.token_ids: list[int] = []
+            self.finish_reason = "stop"
+            self.stop_reason = None
+            self.logprobs = None
+
+    class MockRequestOutput:
+        def __init__(self) -> None:
+            self.request_id = "speech-gepard-mock"
+            self.outputs = [MockCompletionOutput()]
+            self.multimodal_output = {
+                "audio": torch.zeros(num_samples),
+                "sr": torch.tensor(sample_rate),
+            }
+            self.finished = True
+            self.prompt_token_ids = None
+            self.encoder_prompt_token_ids = None
+            self.num_cached_tokens = None
+            self.prompt_logprobs = None
+            self.kv_transfer_params = None
+
+    output = OmniRequestOutput.from_stage_output(MockRequestOutput(), stage_id=0, final_output_type="audio")
+    output.metrics = {"stage_metrics": {"0": {"num_tokens_in": 0, "num_tokens_out": 2}}}
+    return output
+
+
+@pytest.fixture
+def gepard_server(mocker: MockerFixture):
+    mocker.patch(
+        "vllm_omni.entrypoints.openai.tts_adapters.base.load_supported_speakers",
+        return_value={"default"},
+    )
+    mocker.patch(
+        "vllm_omni.entrypoints.openai.tts_adapters.base.load_codec_frame_rate",
+        return_value=22050.0,
+    )
+
+    async def _gen(*_args, **_kwargs):
+        yield _gepard_mock_output()
+
+    mock_engine_client = mocker.MagicMock()
+    mock_engine_client.errored = False
+    mock_engine_client.model_config = mocker.MagicMock(model=_MODEL, async_chunk=False, revision=None)
+    mock_engine_client.default_sampling_params_list = [SimpleNamespace(max_tokens=1000, seed=42, extra_args=None)]
+    mock_engine_client.tts_batch_max_items = 32
+    mock_engine_client.generate = mocker.MagicMock(side_effect=lambda **_k: _gen())
+    mock_engine_client.stage_configs = [
+        SimpleNamespace(
+            engine_args=SimpleNamespace(model_stage="gepard", model_arch="GepardTalkerForConditionalGeneration"),
+            tts_args={},
+        )
+    ]
+
+    mock_models = mocker.MagicMock()
+    mock_models.is_base_model.return_value = True
+    server = OmniOpenAIServingSpeech(
+        engine_client=mock_engine_client,
+        models=mock_models,
+        request_logger=mocker.MagicMock(),
+    )
+    cfg = GepardConfig()
+    server._adapter._gepard_config = cfg
+    server._adapter._tokenizer = lambda text, add_special_tokens=False: {"input_ids": [11, 12, 13]}
+    yield server
+    server.shutdown()
+
+
+def test_gepard_prepare_uses_prompt_builder(gepard_server) -> None:
+    request_id, _generator, _ = asyncio.run(
+        gepard_server._prepare_speech_generation(OpenAICreateSpeechRequest(input="Hello from Gepard."))
+    )
+    assert request_id.startswith("speech-")
+    prompt = gepard_server.engine_client.generate.call_args.kwargs["prompt"]
+    assert prompt["prompt_token_ids"] == build_gepard_prompt_ids([11, 12, 13], config=GepardConfig())
+
+
+@pytest.mark.parametrize("response_format", ["wav", "pcm", "flac", "mp3"])
+def test_gepard_mocked_engine_encodes_response_formats(gepard_server, response_format: str) -> None:
+    audio, media_type = asyncio.run(
+        gepard_server._generate_audio_bytes(
+            OpenAICreateSpeechRequest(input="Hello from Gepard.", response_format=response_format)
+        )
+    )
+    assert isinstance(audio, (bytes, str))
+    assert len(audio) > 0
+    expected_media_type = {"wav": "audio/wav", "pcm": "audio/pcm", "flac": "audio/flac", "mp3": "audio/mpeg"}
+    assert media_type == expected_media_type[response_format]
+
+
+def test_gepard_streaming_rejects_non_pcm_wav() -> None:
+    with pytest.raises(ValidationError, match="requires response_format='pcm' or 'wav'"):
+        OpenAICreateSpeechRequest(input="Hello from Gepard.", stream=True, response_format="mp3")
diff --git a/tests/entrypoints/openai_api/test_serving_speech_metrics.py b/tests/entrypoints/openai_api/test_serving_speech_metrics.py
index a5e284a0177..a1fb74a4653 100644
--- a/tests/entrypoints/openai_api/test_serving_speech_metrics.py
+++ b/tests/entrypoints/openai_api/test_serving_speech_metrics.py
@@ -46,6 +46,7 @@ def _serving(metrics: _MetricsStub, *, adapter=None) -> OmniOpenAIServingSpeech:
     serving._tts_model_type = "qwen3_tts"
     serving.engine_client = SimpleNamespace(mod_metrics=metrics, request_states={})
     serving._get_tts_adapter = lambda: adapter
+    serving._speech_output_policies = {}
     serving.create_audio = lambda audio_obj: SimpleNamespace(
         audio_data=b"\0\0" * int(audio_obj.audio_tensor.size),
         media_type="audio/pcm",
diff --git a/tests/entrypoints/openai_api/test_tts_adapter.py b/tests/entrypoints/openai_api/test_tts_adapter.py
index edd2b4cd419..e0a165a5571 100644
--- a/tests/entrypoints/openai_api/test_tts_adapter.py
+++ b/tests/entrypoints/openai_api/test_tts_adapter.py
@@ -69,6 +69,7 @@
     "step_audio2",
     "indextts2",
     "indextts2_5",
+    "gepard",
     "dots_tts",
 }
 
@@ -143,6 +144,17 @@ def _build_moss_tts_request(adapter_cls, mocker, *, request_seed):
     )
 
 
+@pytest.mark.parametrize(
+    ("adapter_cls", "expect_accumulate"),
+    [(MossTTSAdapter, False), (MossTTSNanoAdapter, True)],
+)
+def test_moss_tts_accumulate_nonstreaming_follows_adapter_flag(adapter_cls, expect_accumulate, mocker):
+    prepared = _build_moss_tts_request(adapter_cls, mocker, request_seed=7)
+
+    assert adapter_cls.accumulate_nonstreaming is expect_accumulate
+    assert prepared.output_policy.accumulate_nonstreaming is expect_accumulate
+
+
 # Full-family coverage pins the adapter contract; only Nano consumes this seed end to end today.
 @pytest.mark.parametrize("adapter_cls", [MossTTSAdapter, MossTTSNanoAdapter])
 @pytest.mark.parametrize("request_seed", [0, 1234])
diff --git a/tests/entrypoints/openai_api/test_tts_detection.py b/tests/entrypoints/openai_api/test_tts_detection.py
index 6c7671659d2..90e7e0feeb6 100644
--- a/tests/entrypoints/openai_api/test_tts_detection.py
+++ b/tests/entrypoints/openai_api/test_tts_detection.py
@@ -148,6 +148,7 @@ def _legacy_detect(model_stage, model_arch):
     "dit",
     "fish_speech_slow_ar",
     "fused_thinker_talker",
+    "gepard",
     "glm_tts",
     "glm_tts_dit",
     "higgs_audio_v2",
diff --git a/tests/worker/test_gpu_ar_model_runner.py b/tests/worker/test_gpu_ar_model_runner.py
index be282da812a..33abbb618fd 100644
--- a/tests/worker/test_gpu_ar_model_runner.py
+++ b/tests/worker/test_gpu_ar_model_runner.py
@@ -231,6 +231,7 @@ def apply_sampling_overrides(
     serving._tts_model_type = "higgs_audio_v3"
     serving._get_tts_adapter = lambda: Adapter()
     serving._track_ref_audio_artifact_warmup = lambda *args, **kwargs: None
+    serving._speech_output_policies = {}
 
     _, stage_sampling_params, _ = asyncio.run(serving._prepare_speech_generation(request, request_id="speech-test"))
     stage0_params = stage_sampling_params[0]
diff --git a/vllm_omni/entrypoints/openai/serving_speech.py b/vllm_omni/entrypoints/openai/serving_speech.py
index d4aa72818ae..f54ca3e2850 100644
--- a/vllm_omni/entrypoints/openai/serving_speech.py
+++ b/vllm_omni/entrypoints/openai/serving_speech.py
@@ -53,6 +53,7 @@
     qwen3_tts_input_token_details,
 )
 from vllm_omni.entrypoints.openai.tts_adapters import (
+    OutputPolicy,
     SpeechServingContext,
     TTSGenerationError,
     all_tts_stage_keys,
@@ -396,6 +397,11 @@ def __init__(self, *args, **kwargs):
         self._max_instructions_length = self._compute_max_instructions_length()
 
         self._tts_tokenizer = None
+        # Per-request output policy from the adapter's PreparedRequest. Keyed
+        # by request_id so concurrent speech requests cannot overwrite each
+        # other. Stored only for non-streaming requests and consumed (popped)
+        # by the non-streaming accumulator in `_generate_audio_bytes`.
+        self._speech_output_policies: dict[str, OutputPolicy] = {}
 
         # Batch configuration
         self._batch_max_items: int = getattr(self.engine_client, "tts_batch_max_items", 32)
@@ -1872,6 +1878,7 @@ async def _prepare_speech_generation(
             tts_params = prepared.tts_params
             model_type = prepared.model_type
             qwen3_ref_audio_warmup_artifact_key = prepared.warmup_artifact_key
+            output_policy = prepared.output_policy
         else:
             # Qwen omni models (Qwen3-Omni, Qwen2.5-Omni) use a "talker"
             # stage whose preprocess requires chat-templated tokens.  The
@@ -1893,6 +1900,7 @@ async def _prepare_speech_generation(
                 )
             tts_params = {}
             prompt = {"prompt": request.input}
+            output_policy = OutputPolicy()
 
         if model_type is None:
             if self._is_tts:
@@ -1962,6 +1970,13 @@ async def _prepare_speech_generation(
             qwen3_ref_audio_warmup_artifact_key,
             x_vector_only=self._tts_x_vector_only(tts_params),
         )
+        # Only the non-streaming path consumes output policies (in
+        # `_generate_audio_bytes`); streaming never reads them. Store late —
+        # after every fallible step above — and skip streaming requests
+        # entirely, so no caller has to discard entries (request ids are
+        # unique per request, so a stranded entry would never be reclaimed).
+        if not request.is_streaming():
+            self._speech_output_policies[request_id] = output_policy
         return request_id, generator, tts_params
 
     async def _generate_pcm_chunks(
@@ -2041,13 +2056,17 @@ async def _generate_audio_bytes(
         artifact_ready = False
 
         try:
-            # MOSS-TTS-Nano emits delta chunks per yield (single-stage,
-            # async_chunk=false). The engine surfaces each yield as its own
-            # RequestOutput, so we need to accumulate across the async-for loop —
-            # final_output alone only carries the last (often empty) sentinel.
-            is_moss = self._tts_model_type == "moss_tts_nano"
-            moss_chunks: list[Any] = []
-            moss_sample_rate: int | None = None
+            # Sparse-audio models (MOSS-TTS-Nano, Gepard) emit delta chunks per
+            # yield with async_chunk=false. The engine surfaces each yield as its
+            # own RequestOutput, so we accumulate across the async-for loop when
+            # the adapter asks for it — final_output alone may only carry the
+            # last (often empty) sentinel. Prefer the engine's own concatenated
+            # waveform when FINAL_ONLY already produced one.
+            accumulate_nonstreaming = self._speech_output_policies.pop(
+                request_id, OutputPolicy()
+            ).accumulate_nonstreaming
+            delta_chunks: list[Any] = []
+            delta_sample_rate: int | None = None
 
             final_output: OmniRequestOutput | None = None
             # Non-streaming is FINAL_ONLY, so the stage-0 output carries the full
@@ -2067,7 +2086,7 @@ async def _generate_audio_bytes(
                     _, audio_key = self._extract_audio_output(res)
                     if audio_key is not None:
                         audio_res = res
-                if not is_moss:
+                if not accumulate_nonstreaming:
                     continue
                 try:
                     step_audio, step_key = self._extract_audio_output(res)
@@ -2080,11 +2099,11 @@ async def _generate_audio_bytes(
                 candidates = chunk if isinstance(chunk, list) else [chunk]
                 for cand in candidates:
                     if hasattr(cand, "numel") and cand.numel() > 0:
-                        moss_chunks.append(cand)
+                        delta_chunks.append(cand)
                 sr_step = step_audio.get("sr")
                 if sr_step is not None:
                     sr_val_step = sr_step[-1] if isinstance(sr_step, list) and sr_step else sr_step
-                    moss_sample_rate = int(sr_val_step.item()) if hasattr(sr_val_step, "item") else int(sr_val_step)
+                    delta_sample_rate = int(sr_val_step.item()) if hasattr(sr_val_step, "item") else int(sr_val_step)
 
             if final_output is None:
                 raise ValueError("No output generated from the model.")
@@ -2117,7 +2136,7 @@ async def _generate_audio_bytes(
             sr_val = sr_raw[-1] if isinstance(sr_raw, list) and sr_raw else sr_raw
             sample_rate = sr_val.item() if hasattr(sr_val, "item") else int(sr_val)
 
-            if is_moss:
+            if accumulate_nonstreaming:
                 # Prefer the engine's own consolidated audio when present. After the
                 # vllm 0.20 rebase non-stream requests resolve to FINAL_ONLY, so
                 # final_output already carries the full concatenated waveform; the
@@ -2133,12 +2152,12 @@ async def _generate_audio_bytes(
 
                 if final_audio is not None:
                     audio_tensor = final_audio
-                elif moss_chunks:
-                    audio_tensor = torch.cat(moss_chunks, dim=-1)
+                elif delta_chunks:
+                    audio_tensor = torch.cat(delta_chunks, dim=-1)
                 else:
                     audio_tensor = np.zeros((0,), dtype=np.float32)
-                if moss_sample_rate is not None:
-                    sample_rate = moss_sample_rate
+                if delta_sample_rate is not None:
+                    sample_rate = delta_sample_rate
             elif isinstance(audio_tensor, list):
                 async_chunk = bool(getattr(self.engine_client.model_config, "async_chunk", False))
                 if async_chunk:
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/__init__.py b/vllm_omni/entrypoints/openai/tts_adapters/__init__.py
index 8ed54afd899..9f5387a7f56 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/__init__.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/__init__.py
@@ -110,6 +110,7 @@ def tts_entry_stage_archs() -> frozenset[str]:
     covo_audio,
     dots_tts,
     fish_speech,
+    gepard,
     glm_tts,
     higgs_audio_v2,
     higgs_audio_v3,
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/gepard.py b/vllm_omni/entrypoints/openai/tts_adapters/gepard.py
new file mode 100644
index 00000000000..255525a0ddc
--- /dev/null
+++ b/vllm_omni/entrypoints/openai/tts_adapters/gepard.py
@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Gepard-1.0 serving adapter for ``/v1/audio/speech``.
+
+Zero-shot only: the trained ``null_prefix`` is the default voice. Prompt IDs
+are assembled with the same layout helper the offline path uses. Frame budget
+rides ``SamplingParams.max_tokens`` (one token = one 1024-sample frame).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from vllm.utils.async_utils import make_async
+
+from vllm_omni.entrypoints.openai.tts_adapters import register_tts_adapter
+from vllm_omni.entrypoints.openai.tts_adapters.base import (
+    ARTTSAdapter,
+    OutputPolicy,
+    PreparedRequest,
+    apply_max_new_tokens,
+    conditioning_cache_salt,
+)
+
+if TYPE_CHECKING:
+    from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
+    from vllm_omni.model_executor.models.gepard.configuration_gepard import GepardConfig
+
+_DEFAULT_VOICE = "default"
+
+# Declared schema fields Gepard does not consume. Rejecting them here is
+# load-bearing: the pydantic model silently drops undeclared keys, so a
+# declared-but-ignored field would otherwise succeed and mislead.
+_UNSUPPORTED_OPTIONAL_FIELDS: tuple[tuple[str, str], ...] = (
+    ("ref_audio", "ref_audio"),
+    ("ref_text", "ref_text"),
+    ("ref_audio_2", "ref_audio_2"),
+    ("speaker_embedding", "speaker_embedding"),
+    ("x_vector_only_mode", "x_vector_only_mode"),
+    ("task_type", "task_type"),
+    ("non_streaming_mode", "non_streaming_mode"),
+    ("instructions", "instructions"),
+    ("language", "language"),
+    ("ambient_sound", "ambient_sound"),
+    ("duration_seconds", "duration_seconds"),
+    ("initial_codec_chunk_frames", "initial_codec_chunk_frames"),
+)
+
+
+@register_tts_adapter
+class GepardAdapter(ARTTSAdapter):
+    name = "gepard"
+    stage_keys = frozenset({"gepard"})
+    model_archs = frozenset({"GepardTalkerForConditionalGeneration"})
+
+    def __init__(self, ctx) -> None:
+        super().__init__(ctx)
+        self._tokenizer: Any = None
+        self._gepard_config: GepardConfig | None = None
+        self._build_prompt_async = make_async(self._build_prompt, executor=getattr(ctx.server, "_tts_executor", None))
+
+    def _load_supported_speakers(self) -> set[str]:
+        return {_DEFAULT_VOICE}
+
+    def validate(self, request: OpenAICreateSpeechRequest) -> str | None:
+        if not request.input or not request.input.strip():
+            return "Input text cannot be empty"
+
+        if request.voice is not None:
+            voice = request.voice.lower()
+            if voice != _DEFAULT_VOICE:
+                return (
+                    f"Invalid voice '{request.voice}'. Supported: {_DEFAULT_VOICE}. "
+                    "Voice cloning from reference audio is not available yet."
+                )
+
+        if request.speed is not None and request.speed != 1.0:
+            return "Gepard does not support 'speed' adjustments; audio is rendered at the native 22.05 kHz rate"
+
+        if request.extra_params:
+            keys = ", ".join(sorted(request.extra_params))
+            return (
+                f"Gepard does not accept extra_params (got: {keys}). "
+                "Sampling is fixed in-model; temperature/top_p/top_k cannot be overridden."
+            )
+
+        if request.word_timestamps:
+            return "Gepard does not support 'word_timestamps'; there is no forced-aligner stage in this pipeline"
+
+        fmt = (request.response_format or "").lower()
+        if fmt == "opus":
+            return (
+                "Gepard does not support 'response_format'='opus'; "
+                "native 22.05 kHz is not an Opus sample rate (8000, 12000, 16000, 24000, 48000)"
+            )
+
+        if request.max_new_tokens is not None:
+            if request.max_new_tokens < self.max_new_tokens_min or request.max_new_tokens > self.max_new_tokens_max:
+                return f"max_new_tokens must be between {self.max_new_tokens_min} and {self.max_new_tokens_max} frames"
+
+        for attr, field in _UNSUPPORTED_OPTIONAL_FIELDS:
+            if getattr(request, attr, None) is not None:
+                return f"Gepard does not support '{field}'"
+
+        return None
+
+    def apply_sampling_overrides(
+        self,
+        sampling_params_list: list,
+        request: OpenAICreateSpeechRequest,
+        prompt: dict | None = None,
+        request_id: str | None = None,
+    ) -> list:
+        return apply_max_new_tokens(sampling_params_list, request)
+
+    async def build(
+        self,
+        request: OpenAICreateSpeechRequest,
+        sampling_params_list: list,
+        has_inline_ref_audio: bool,
+    ) -> PreparedRequest:
+        tts_params: dict = {}
+        prompt = await self._build_prompt_async(request.input)
+        prompt["cache_salt"] = conditioning_cache_salt(request, tts_params)
+        return PreparedRequest(
+            prompt=prompt,
+            tts_params=tts_params,
+            model_type=self.name,
+            output_policy=OutputPolicy(accumulate_nonstreaming=True),
+        )
+
+    def _build_prompt(self, text: str) -> dict[str, Any]:
+        from vllm_omni.model_executor.models.gepard.prompt import build_gepard_prompt_ids
+
+        prompt_token_ids = build_gepard_prompt_ids(self._tokenize(text), config=self._config())
+        return {
+            "prompt_token_ids": prompt_token_ids,
+            "additional_information": {"text": [text]},
+        }
+
+    def _model_config(self) -> Any:
+        engine = self.ctx.engine_client
+        assert engine is not None
+        return engine.model_config
+
+    def _config(self) -> GepardConfig:
+        if self._gepard_config is None:
+            from vllm_omni.model_executor.models.gepard.configuration_gepard import GepardConfig
+
+            model_config = self._model_config()
+            self._gepard_config = GepardConfig.from_checkpoint(
+                model_config.model, revision=getattr(model_config, "revision", None)
+            )
+        return self._gepard_config
+
+    def _tokenize(self, text: str) -> list[int]:
+        tokenizer = self._tokenizer
+        if tokenizer is None:
+            from transformers import AutoTokenizer
+
+            model_config = self._model_config()
+            tokenizer = AutoTokenizer.from_pretrained(
+                model_config.model,
+                revision=getattr(model_config, "revision", None),
+                trust_remote_code=True,
+            )
+            self._tokenizer = tokenizer
+        return tokenizer(text, add_special_tokens=False)["input_ids"]
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py b/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
index 07e4bb197e3..bed20efc225 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
@@ -13,6 +13,7 @@
 from vllm_omni.entrypoints.openai.tts_adapters import register_tts_adapter
 from vllm_omni.entrypoints.openai.tts_adapters.base import (
     ARTTSAdapter,
+    OutputPolicy,
     PreparedRequest,
     apply_max_new_tokens,
     conditioning_cache_salt,
@@ -23,6 +24,8 @@
 
 
 class _MossTTSAdapterBase(ARTTSAdapter):
+    accumulate_nonstreaming: bool = False
+
     def __init__(self, ctx) -> None:
         super().__init__(ctx)
         self._moss_variant = None if self.name == "moss_tts_nano" else self._detect_moss_variant()
@@ -369,7 +372,12 @@ async def build(
             prompt = tokens_input(prompt_token_ids=[1])
         prompt["additional_information"] = tts_params
         prompt["cache_salt"] = conditioning_cache_salt(request, tts_params)
-        return PreparedRequest(prompt=prompt, tts_params=tts_params, model_type=self.name)
+        return PreparedRequest(
+            prompt=prompt,
+            tts_params=tts_params,
+            model_type=self.name,
+            output_policy=OutputPolicy(accumulate_nonstreaming=self.accumulate_nonstreaming),
+        )
 
     def apply_sampling_overrides(
         self,
@@ -385,6 +393,7 @@ def apply_sampling_overrides(
 class MossTTSNanoAdapter(_MossTTSAdapterBase):
     stage_keys = frozenset({"moss_tts_nano"})
     name = "moss_tts_nano"
+    accumulate_nonstreaming = True
 
 
 @register_tts_adapter

From 6040bb97e2036927632151a87b0aaed94ccbce7d Mon Sep 17 00:00:00 2001
From: yzhautouskay <yzhautouskay@nvidia.com>
Date: Tue, 15 Sep 2026 23:57:15 +0200
Subject: [PATCH 008/105] [Perf][Cosmos3] Add SeaCache support for Cosmos3
 (#6922)

Signed-off-by: Yuliya Zhautouskaya <yzhautouskay@nvidia.com>
---
 recipes/cosmos3/Cosmos3-Nano.md               |  61 +-
 recipes/cosmos3/Cosmos3-Super.md              |  27 +-
 tests/diffusion/cache/test_seacache.py        | 635 ++++++++++++++++++
 .../models/cosmos3/test_cosmos3_pipeline.py   | 105 ++-
 .../cosmos3/test_cosmos3_transformer.py       | 104 ++-
 .../diffusion/cache/seacache/__init__.py      |  18 +
 vllm_omni/diffusion/cache/seacache/backend.py | 100 +++
 vllm_omni/diffusion/cache/seacache/config.py  |  36 +
 vllm_omni/diffusion/cache/seacache/hook.py    | 397 +++++++++++
 .../diffusion/cache/seacache/sea_filter.py    |  93 +++
 vllm_omni/diffusion/cache/seacache/state.py   |  26 +
 vllm_omni/diffusion/cache/selector.py         |  11 +-
 .../diffusion/cache/teacache/extractors.py    | 100 ++-
 vllm_omni/diffusion/data.py                   |   8 +
 .../models/cosmos3/pipeline_cosmos3.py        |  77 ++-
 .../models/cosmos3/transformer_cosmos3.py     | 280 +++++---
 .../worker/diffusion_model_runner.py          |  49 +-
 vllm_omni/entrypoints/cli/serve.py            |   5 +-
 18 files changed, 1969 insertions(+), 163 deletions(-)
 create mode 100644 tests/diffusion/cache/test_seacache.py
 create mode 100644 vllm_omni/diffusion/cache/seacache/__init__.py
 create mode 100644 vllm_omni/diffusion/cache/seacache/backend.py
 create mode 100644 vllm_omni/diffusion/cache/seacache/config.py
 create mode 100644 vllm_omni/diffusion/cache/seacache/hook.py
 create mode 100644 vllm_omni/diffusion/cache/seacache/sea_filter.py
 create mode 100644 vllm_omni/diffusion/cache/seacache/state.py

diff --git a/recipes/cosmos3/Cosmos3-Nano.md b/recipes/cosmos3/Cosmos3-Nano.md
index 6ef24bcf49d..29088e94c76 100644
--- a/recipes/cosmos3/Cosmos3-Nano.md
+++ b/recipes/cosmos3/Cosmos3-Nano.md
@@ -32,13 +32,13 @@ mode is selected per request:
   T2V/I2V `/v1/videos/sync` request to also generate synchronized audio, muxed into
   the mp4 as AAC 48 kHz stereo. See the official model card's "Video + Audio" examples.
 - **Action** — pass `extra_params={"action_mode": ...}` to drive Physical-AI tasks:
-  - `forward_dynamics` — given a first frame or video **and** an action trajectory,
+    - `forward_dynamics` — given a first frame or video **and** an action trajectory,
     roll out the resulting video. Synchronous: `POST /v1/videos/sync`.
-  - `policy` — given a first frame or video and a language instruction,
+    - `policy` — given a first frame or video and a language instruction,
     **predict** the action trajectory (and a rollout video). Use the async
     `POST /v1/videos` endpoint and read the predicted action from the top-level
     `action` field.
-  - `inverse_dynamics` — given a video, **recover** the action trajectory. Use
+    - `inverse_dynamics` — given a video, **recover** the action trajectory. Use
     the async `POST /v1/videos` endpoint and read the recovered action from
     the top-level `action` field
     (`{data, shape, dtype, raw_action_dim, domain_id}`).
@@ -106,6 +106,25 @@ vllm serve nvidia/Cosmos3-Nano \
   --init-timeout 1800
 ```
 
+For Cosmos3, SeaCache is the recommended default choice when opting into
+diffusion caching. Caching remains opt-in; add `--cache-backend sea_cache` to
+the command above. Its default threshold and maximum cached-step streak are
+tuned for Cosmos3, so no `--cache-config` is required.
+
+Override individual defaults with a JSON cache configuration; for example:
+
+```bash
+vllm serve nvidia/Cosmos3-Nano \
+  --omni \
+  --cache-backend sea_cache \
+  --cache-config '{"sea_threshold":0.2,"sea_max_consecutive_cached":3}'
+```
+
+Lower `sea_threshold` values and smaller `sea_max_consecutive_cached` caps are
+more conservative. Higher values allow more cached steps and may improve
+speed, but can increase quality loss. Setting `sea_max_consecutive_cached` to
+`0` removes the streak cap.
+
 To run **without** guardrails (you are responsible for license compliance),
 add `--no-guardrails` (no token/`cosmos-guardrail` needed). For extra GPUs use
 `--ulysses-degree N` (context parallel) or `--tensor-parallel-size N`;
@@ -382,12 +401,12 @@ OpenPI route uses the normal API authentication middleware. RoboLab's
 
 #### Notes
 
-- **Measured latency (1x B300, bf16, guardrails off):**
-  - T2I 1024² — 10 / 25 / 50 steps → ~0.4 / 0.7 / **1.3 s**
-  - T2V 1280×720 @ 35 steps — 25 / 49 / 93 / **189** frames → ~7 / 15 / 33 / **~93 s**
-  - I2V 1280×720, 189 frames @ 35 steps → ~**99 s**
-  - Action 640×480 @ 30 steps — forward-dynamics 61f ~**4 s**, policy 17f ~**1–3 s**.
-  - Guardrails-on overhead: ~8% on T2I, negligible on video.
+- **Measured latency (1x B300, bf16, guardrails off, diffusion cache off):**
+    - T2I 1024² — 10 / 25 / 50 steps → ~0.4 / 0.7 / **1.3 s**
+    - T2V 1280×720 @ 35 steps — 25 / 49 / 93 / **189** frames → ~7 / 15 / 33 / **~93 s**
+    - I2V 1280×720, 189 frames @ 35 steps → ~**99 s**
+    - Action 640×480 @ 30 steps — forward-dynamics 61f ~**4 s**, policy 17f ~**1–3 s**.
+    - Guardrails-on overhead: ~8% on T2I, negligible on video.
 - **Memory:** transformer ~17 GiB (bf16); peak ~46 GiB for 720p video on 1 GPU;
   full repo (transformer + Wan VAE + Qwen3-VL vision encoder + audio tokenizer)
   ~33 GB on disk.
@@ -443,12 +462,12 @@ OpenPI route uses the normal API authentication middleware. RoboLab's
   `conditioning_fps`, `action_chunk_size`, `raw_action_dim`, `deterministic_seed`,
   and `session_id`.
 - **Known limitations:**
-  - Guardrails-on requires `cosmos-guardrail` **and** access to the gated
+    - Guardrails-on requires `cosmos-guardrail` **and** access to the gated
     `nvidia/Cosmos-1.0-Guardrail` repo (accept license + `HF_TOKEN`); otherwise
     the server fails at pipeline build with a gated-repo / safety-checker error.
-  - A guardrail-blocked prompt currently returns HTTP 500
+    - A guardrail-blocked prompt currently returns HTTP 500
     (`"Guardrail blocked prompt"`).
-  - Action `forward_dynamics`, `policy`, and `inverse_dynamics` are supported
+    - Action `forward_dynamics`, `policy`, and `inverse_dynamics` are supported
     online. Use async `POST /v1/videos` when you need the predicted/recovered
     action payload under the top-level `action` field; sync `/v1/videos/sync`
     returns raw MP4 bytes and does not expose action metadata in the response body.
@@ -579,14 +598,14 @@ so an md5 comparison across two runs also works as a smoke check.
   a ~390 s build of the VAE decode path *for that shape*, so warming 1024² images
   does nothing for 189-frame video. At 720p / 189 frames / 35 steps this is
   **540 s cold vs 161 s warm, with byte-identical output**.
-- **Measured on 1x MI350X (bf16, guardrails off, warm):** T2I 1024² @ 50 steps
+- **Measured on 1x MI350X (bf16, guardrails off, diffusion cache off, warm):** T2I 1024² @ 50 steps
   **~2.7 s**; T2V 1280×720 / 189 frames @ 35 steps **~161 s**, of which ~92% is
   the DiT denoise loop and ~4% VAE decode, so optimization effort belongs in the
   denoise loop. The optional flags act on different terms of the memory bill and
   are therefore complementary rather than redundant:
 
   | Flag | Latency | Peak reserved | Peak allocated | Acts on |
-  |---|---|---|---|---|
+  | --- | --- | --- | --- | --- |
   | *(none)* | 161 s | 120 GiB | 95 GiB | — |
   | `--vae-use-tiling` | 183 s (+13.5%) | **38 GiB** (−68%) | **36 GiB** (−62%) | decode activations |
   | `--enable-layerwise-offload` | 162 s (+0.8%) | 84 GiB (−30%) | 69 GiB (−27%) | weights |
@@ -768,11 +787,11 @@ curl -sS -X POST http://localhost:8000/v1/videos/sync \
 
 #### Notes
 
-- **Measured latency (1x Ascend 910B / 910C, bf16, guardrails off):**
-  - T2I 1024² — 10 steps → ~8 s
-  - T2V 1280×720 @ 20 steps — 49 frames → ~55 s
-  - I2V 1280×720 @ 10 steps — 25 frames → ~25 s
-  - V2V 480×320 @ 10 steps — 17 frames → ~12 s
+- **Measured latency (1x Ascend 910B / 910C, bf16, guardrails off, diffusion cache off):**
+    - T2I 1024² — 10 steps → ~8 s
+    - T2V 1280×720 @ 20 steps — 49 frames → ~55 s
+    - I2V 1280×720 @ 10 steps — 25 frames → ~25 s
+    - V2V 480×320 @ 10 steps — 17 frames → ~12 s
 - **Memory:** transformer ~17 GiB (bf16); peak ~46 GiB for 720p video on 1 NPU;
   full repo (transformer + Wan VAE + Qwen3-VL vision encoder + audio tokenizer)
   ~33 GB on disk.
@@ -785,9 +804,9 @@ curl -sS -X POST http://localhost:8000/v1/videos/sync \
   (for model loading), `--tensor-parallel-size 8` for multi-NPU, and
   `--model-class-name Cosmos3OmniDiffusersPipeline` to force the pipeline class.
 - **Known limitations:**
-  - Transfer V2V with `extra_params` (`edge`/`blur`/`depth`/`seg`/`wsm`) hits a
+    - Transfer V2V with `extra_params` (`edge`/`blur`/`depth`/`seg`/`wsm`) hits a
     resolution-parsing bug; basic V2V without transfer hints works.
-  - FP8 online quantization and layerwise offload are not supported on NPU.
+    - FP8 online quantization and layerwise offload are not supported on NPU.
 
 ### 1x Ascend 910B / 910C (Atlas A2 / A3) — Offline generation
 
diff --git a/recipes/cosmos3/Cosmos3-Super.md b/recipes/cosmos3/Cosmos3-Super.md
index c8bfb6bbd72..82ae1f20a67 100644
--- a/recipes/cosmos3/Cosmos3-Super.md
+++ b/recipes/cosmos3/Cosmos3-Super.md
@@ -62,6 +62,21 @@ disable. `--enable-layerwise-offload` reduces VRAM on smaller GPUs;
 generation from ~83 GB to ~55 GB per GPU (2-GPU) with BF16-level quality (T2V
 composition can shift at the same seed).
 
+SeaCache is the recommended default choice when opting into diffusion caching,
+which remains opt-in. Add `--cache-backend sea_cache` to either command above;
+its defaults are tuned for Cosmos3.
+
+Override individual defaults with `--cache-config`; for example:
+
+```bash
+--cache-config '{"sea_threshold":0.2,"sea_max_consecutive_cached":3}'
+```
+
+Lower `sea_threshold` values and smaller `sea_max_consecutive_cached` caps are
+more conservative. Higher values allow more cached steps and may improve
+speed, but can increase quality loss. Setting `sea_max_consecutive_cached` to
+`0` removes the streak cap.
+
 #### Verification
 
 Requests are identical to Nano (see [`Cosmos3-Nano.md`](./Cosmos3-Nano.md) for full
@@ -109,12 +124,12 @@ curl -sS -X POST http://localhost:8000/v1/videos/sync -H "Accept: video/mp4" \
 
 #### Notes
 
-- **Measured (2x B300, bf16, guardrails off, official 2-GPU config above):**
-  - T2I 1024², 50 steps → **~6 s**
-  - T2V 1280×720, 189 frames, 35 steps → **~197 s**
-  - I2V 1280×720, 189 frames, 35 steps → **~200 s**
-  - T2V + sound (189 frames, 35 steps) → **~198 s**, output muxes **AAC 48 kHz stereo**
-  - (NVIDIA's reference: 8×H200 @ 50 steps ≈ 55 s/video; 2×H200 @ 35 steps ≈ 3 min/video.)
+- **Measured (2x B300, bf16, guardrails off, diffusion cache off, official 2-GPU config above):**
+    - T2I 1024², 50 steps → **~6 s**
+    - T2V 1280×720, 189 frames, 35 steps → **~197 s**
+    - I2V 1280×720, 189 frames, 35 steps → **~200 s**
+    - T2V + sound (189 frames, 35 steps) → **~198 s**, output muxes **AAC 48 kHz stereo**
+    - (NVIDIA's reference: 8×H200 @ 50 steps ≈ 55 s/video; 2×H200 @ 35 steps ≈ 3 min/video.)
 - **Memory:** ~61.5 GiB per GPU when sharded across 2 GPUs (HSDP shard 2); repo ~135 GB on disk.
 - Same generation defaults, supported sizes, V2V reference-video controls
   (`condition_frame_indexes_vision`, `condition_video_keep`), and
diff --git a/tests/diffusion/cache/test_seacache.py b/tests/diffusion/cache/test_seacache.py
new file mode 100644
index 00000000000..ea11537d194
--- /dev/null
+++ b/tests/diffusion/cache/test_seacache.py
@@ -0,0 +1,635 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import datetime
+from contextlib import nullcontext
+from types import SimpleNamespace
+
+import pytest
+import torch
+
+from tests.helpers.runtime import get_distributed_init_method
+from vllm_omni.diffusion.cache.seacache import (
+    SeaCacheBackend,
+    SeaCacheConfig,
+    SeaCacheRootHook,
+    apply_sea_cache_hook,
+)
+from vllm_omni.diffusion.cache.seacache.sea_filter import (
+    apply_sea_filter,
+    extrapolate_residual,
+    indicator_distance,
+)
+from vllm_omni.diffusion.cache.selector import get_cache_backend
+from vllm_omni.diffusion.cache.teacache.extractors import EXTRACTOR_REGISTRY, CacheContext, get_extractor
+from vllm_omni.diffusion.data import DiffusionCacheConfig
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+class TinyCosmos3Transformer(torch.nn.Module):
+    """Small model that exposes a cache-neutral execution boundary."""
+
+    def _run_gen_layers(self, hidden_gen: torch.Tensor) -> torch.Tensor:
+        return hidden_gen * 2
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        timestep: torch.Tensor,
+        text_ids: torch.Tensor | None = None,
+        text_mask: torch.Tensor | None = None,
+        video_shape: tuple[int, int, int] | None = None,
+        noisy_frame_mask: torch.Tensor | None = None,
+        control_latents: list[torch.Tensor] | torch.Tensor | None = None,
+        **kwargs,
+    ) -> torch.Tensor:
+        del timestep, text_ids, text_mask, video_shape, noisy_frame_mask
+        if kwargs:
+            raise TypeError(f"Unexpected tiny transformer kwargs: {sorted(kwargs)}")
+        controls = (
+            []
+            if control_latents is None
+            else [control_latents]
+            if isinstance(control_latents, torch.Tensor)
+            else list(control_latents)
+        )
+        inputs = [*controls, hidden_states]
+        gen_input = torch.cat(
+            [value.movedim(1, -1).flatten(1, 3) for value in inputs],
+            dim=1,
+        )
+        return self._run_gen_layers(gen_input)
+
+
+def _extract_tiny_cosmos3_context(
+    module: TinyCosmos3Transformer,
+    hidden_states: torch.Tensor,
+    timestep: torch.Tensor,
+    text_ids: torch.Tensor | None = None,
+    text_mask: torch.Tensor | None = None,
+    video_shape: tuple[int, int, int] | None = None,
+    noisy_frame_mask: torch.Tensor | None = None,
+    control_latents: list[torch.Tensor] | torch.Tensor | None = None,
+    **kwargs,
+) -> CacheContext:
+    del timestep, text_ids, text_mask, video_shape
+    if kwargs:
+        raise TypeError(f"Unexpected tiny transformer kwargs: {sorted(kwargs)}")
+    controls = (
+        []
+        if control_latents is None
+        else [control_latents]
+        if isinstance(control_latents, torch.Tensor)
+        else list(control_latents)
+    )
+    vision_items = [*controls, hidden_states]
+    gen_input = torch.cat(
+        [value.movedim(1, -1).flatten(1, 3) for value in vision_items],
+        dim=1,
+    )
+    return CacheContext(
+        modulated_input=gen_input,
+        hidden_states=gen_input,
+        encoder_hidden_states=None,
+        temb=torch.zeros_like(gen_input[:, 0]),
+        run_transformer_blocks=lambda: (module._run_gen_layers(gen_input),),
+        postprocess=lambda output: output,
+        extra_states={
+            "sea_cache_latents": vision_items,
+            "sea_cache_noisy_frame_mask": noisy_frame_mask,
+        },
+    )
+
+
+class Cosmos3OmniDiffusersPipeline:
+    def __init__(self) -> None:
+        self.transformer = TinyCosmos3Transformer()
+        self._current_step_index: int | None = None
+        self._current_sigma: float | None = None
+        self._num_timesteps: int | None = None
+
+    @property
+    def current_step_index(self) -> int | None:
+        return self._current_step_index
+
+    @property
+    def current_sigma(self) -> float | None:
+        return self._current_sigma
+
+    @property
+    def num_timesteps(self) -> int | None:
+        return self._num_timesteps
+
+
+def _latent(value: float) -> torch.Tensor:
+    return torch.full((1, 2, 2, 2, 2), value)
+
+
+def _run_step(
+    transformer: TinyCosmos3Transformer,
+    timestep: int,
+    value: float,
+    *,
+    hook: SeaCacheRootHook | None = None,
+    context: str = "cond",
+    control: float | None = None,
+    noisy_frame_mask: torch.Tensor | None = None,
+) -> torch.Tensor:
+    controls = None if control is None else [_latent(control)]
+    cache_context = hook.cache_context(context) if hook is not None else nullcontext()
+    with torch.inference_mode(), cache_context:
+        return transformer(
+            hidden_states=_latent(value),
+            timestep=torch.tensor([timestep]),
+            noisy_frame_mask=noisy_frame_mask,
+            control_latents=controls,
+        )
+
+
+def _apply_test_hook(
+    transformer: TinyCosmos3Transformer,
+    metadata: SimpleNamespace,
+    config: SeaCacheConfig | None = None,
+) -> SeaCacheRootHook:
+    return apply_sea_cache_hook(
+        transformer,
+        config or SeaCacheConfig(threshold=100.0),
+        current_step_callback=lambda: metadata.step,
+        current_sigma_callback=lambda: metadata.sigma,
+        num_inference_steps_callback=lambda: metadata.num_steps,
+        extractor_fn=_extract_tiny_cosmos3_context,
+    )
+
+
+def test_config_validation() -> None:
+    assert SeaCacheConfig().threshold == 0.25
+    with pytest.raises(ValueError, match="residual_order"):
+        SeaCacheConfig(residual_order=-1)
+    with pytest.raises(ValueError, match="max_consecutive_cached"):
+        SeaCacheConfig(max_consecutive_cached=-1)
+
+
+def test_sea_filter_matches_reference_equation() -> None:
+    hidden = torch.randn(3, 4, 5, 2, dtype=torch.float32)
+    sigma = 0.4
+    power_exp = 3.0
+
+    spectrum = torch.fft.fftn(hidden, dim=(0, 1, 2))
+    gain = None
+    for axis in (0, 1, 2):
+        frequencies = torch.fft.fftfreq(hidden.shape[axis], dtype=torch.float32)
+        clean_power = 1.0 / (frequencies.abs().pow(power_exp) + 1e-16)
+        axis_gain = (1.0 - sigma) * clean_power / ((1.0 - sigma) ** 2 * clean_power + sigma**2 + 1e-16)
+        shape = [1] * hidden.ndim
+        shape[axis] = hidden.shape[axis]
+        gain = axis_gain.reshape(shape) if gain is None else gain * axis_gain.reshape(shape)
+    assert gain is not None
+    gain = gain / gain.mean()
+    expected = torch.fft.ifftn(spectrum * gain, dim=(0, 1, 2)).real
+
+    torch.testing.assert_close(
+        apply_sea_filter(hidden, sigma=sigma, power_exp=power_exp),
+        expected,
+    )
+
+
+def test_indicator_distance_and_linear_extrapolation() -> None:
+    previous = [torch.ones(2, 2)]
+    current = [torch.full((2, 2), 1.5)]
+    assert indicator_distance(current, previous) == pytest.approx(0.5)
+    assert indicator_distance([torch.ones(3)], previous) == float("inf")
+
+    history = [
+        (0, torch.full((2, 2), 2.0)),
+        (2, torch.full((2, 2), 6.0)),
+    ]
+    torch.testing.assert_close(
+        extrapolate_residual(history, step=3, order=1),
+        torch.full((2, 2), 8.0),
+    )
+    torch.testing.assert_close(
+        extrapolate_residual(history, step=3, order=0),
+        torch.full((2, 2), 6.0),
+    )
+    quadratic_history = [
+        (0, torch.zeros(2, 2)),
+        (1, torch.ones(2, 2)),
+        (2, torch.full((2, 2), 4.0)),
+    ]
+    torch.testing.assert_close(
+        extrapolate_residual(quadratic_history, step=3, order=2),
+        torch.full((2, 2), 9.0),
+    )
+
+
+def test_hook_skips_middle_steps_and_forces_endpoints() -> None:
+    transformer = TinyCosmos3Transformer()
+    metadata = SimpleNamespace(step=0, sigma=1.0, num_steps=4)
+    hook = _apply_test_hook(
+        transformer,
+        metadata,
+        SeaCacheConfig(threshold=100.0, max_consecutive_cached=2),
+    )
+    hook.refresh(transformer)
+
+    for step, timestep in enumerate((1000, 750, 500, 250)):
+        metadata.step = step
+        metadata.sigma = timestep / 1000
+        _run_step(transformer, timestep, 1.0 - step * 0.01, hook=hook)
+
+    assert hook.full_count == 2
+    assert hook.skip_count == 2
+    assert [step for step, _ in hook.state_manager._states["cond"].history] == [0, 3]
+
+
+def test_parameter_sharded_hook_skips_when_all_shard_ranks_agree(monkeypatch: pytest.MonkeyPatch) -> None:
+    from vllm_omni.diffusion.distributed import parallel_state
+
+    transformer = TinyCosmos3Transformer()
+    metadata = SimpleNamespace(step=0, sigma=1.0, num_steps=3)
+    hook = _apply_test_hook(transformer, metadata)
+    hook._parameter_sharded = True
+    fs_group = object()
+    reduced_groups: list[object] = []
+
+    monkeypatch.setattr(torch.distributed, "is_available", lambda: True)
+    monkeypatch.setattr(torch.distributed, "is_initialized", lambda: True)
+    monkeypatch.setattr(
+        parallel_state,
+        "get_fs_group",
+        lambda: SimpleNamespace(world_size=2, device_group=fs_group),
+    )
+    monkeypatch.setattr(parallel_state, "get_sequence_parallel_world_size", lambda: 1)
+
+    def all_reduce(decision, *, op, group):
+        assert op == torch.distributed.ReduceOp.MAX
+        reduced_groups.append(group)
+
+    monkeypatch.setattr(torch.distributed, "all_reduce", all_reduce)
+
+    _run_step(transformer, 1000, 1.0, hook=hook)
+    metadata.step = 1
+    metadata.sigma = 0.5
+    _run_step(transformer, 500, 0.99, hook=hook)
+
+    assert hook.full_count == 1
+    assert hook.skip_count == 1
+    assert reduced_groups == [fs_group, fs_group]
+
+
+def test_parameter_sharded_peer_forces_full_compute(monkeypatch: pytest.MonkeyPatch) -> None:
+    from vllm_omni.diffusion.distributed import parallel_state
+
+    transformer = TinyCosmos3Transformer()
+    metadata = SimpleNamespace(step=0, sigma=1.0, num_steps=3)
+    hook = _apply_test_hook(transformer, metadata)
+    hook._parameter_sharded = True
+
+    monkeypatch.setattr(torch.distributed, "is_available", lambda: True)
+    monkeypatch.setattr(torch.distributed, "is_initialized", lambda: True)
+    monkeypatch.setattr(
+        parallel_state,
+        "get_fs_group",
+        lambda: SimpleNamespace(world_size=2, device_group=object()),
+    )
+    monkeypatch.setattr(parallel_state, "get_sequence_parallel_world_size", lambda: 1)
+    reduce_count = 0
+
+    def all_reduce(decision, *, op, group):
+        nonlocal reduce_count
+        del op, group
+        reduce_count += 1
+        if reduce_count == 2:
+            decision.fill_(1)
+
+    monkeypatch.setattr(torch.distributed, "all_reduce", all_reduce)
+
+    _run_step(transformer, 1000, 1.0, hook=hook)
+    metadata.step = 1
+    metadata.sigma = 0.5
+    _run_step(transformer, 500, 0.99, hook=hook)
+
+    assert hook.full_count == 2
+    assert hook.skip_count == 0
+    assert hook.state_manager._states["cond"].accumulated_distance == 0.0
+
+
+def _uneven_cfg_sharded_worker(
+    rank: int,
+    init_method: str,
+    result_queue: torch.multiprocessing.Queue,
+) -> None:
+    from vllm_omni.diffusion.distributed import parallel_state
+
+    torch.distributed.init_process_group(
+        "gloo",
+        init_method=init_method,
+        rank=rank,
+        world_size=4,
+        timeout=datetime.timedelta(seconds=10),
+    )
+    try:
+        fs_groups = [
+            (ranks, torch.distributed.new_group(ranks, timeout=datetime.timedelta(seconds=10)))
+            for ranks in ([0, 1], [2, 3])
+        ]
+        sp_groups = [
+            (ranks, torch.distributed.new_group(ranks, timeout=datetime.timedelta(seconds=10)))
+            for ranks in ([0, 1], [2, 3])
+        ]
+        cfg_groups = [
+            (ranks, torch.distributed.new_group(ranks, timeout=datetime.timedelta(seconds=10)))
+            for ranks in ([0, 2], [1, 3])
+        ]
+        fs_group = next(group for ranks, group in fs_groups if rank in ranks)
+        sp_group = next(group for ranks, group in sp_groups if rank in ranks)
+        cfg_group = next(group for ranks, group in cfg_groups if rank in ranks)
+        parallel_state._FS = SimpleNamespace(world_size=2, device_group=fs_group)
+        parallel_state._SP = SimpleNamespace(world_size=2, device_group=sp_group)
+
+        hook = SeaCacheRootHook(SeaCacheConfig())
+        hook._parameter_sharded = True
+        hook._synchronize_compute(False, torch.device("cpu"))
+        if rank in (0, 1):
+            hook._synchronize_compute(False, torch.device("cpu"))
+
+        gathered = [torch.zeros(1) for _ in range(2)]
+        torch.distributed.all_gather(
+            gathered,
+            torch.tensor([rank], dtype=torch.float32),
+            group=cfg_group,
+        )
+        result_queue.put((rank, [int(value.item()) for value in gathered]))
+    finally:
+        parallel_state._FS = None
+        parallel_state._SP = None
+        torch.distributed.destroy_process_group()
+
+
+def test_parameter_sharded_hook_handles_uneven_cfg_branch_dispatch() -> None:
+    mp_context = torch.multiprocessing.get_context("spawn")
+    manager = mp_context.Manager()
+    result_queue = manager.Queue()
+    torch.multiprocessing.spawn(
+        _uneven_cfg_sharded_worker,
+        args=(get_distributed_init_method("seacache_uneven_cfg_"), result_queue),
+        nprocs=4,
+    )
+
+    results = sorted(result_queue.get(timeout=2) for _ in range(4))
+    assert results == [
+        (0, [0, 2]),
+        (1, [1, 3]),
+        (2, [0, 2]),
+        (3, [1, 3]),
+    ]
+
+
+def _hybrid_sp_worker(
+    rank: int,
+    init_method: str,
+    result_queue: torch.multiprocessing.Queue,
+) -> None:
+    from vllm_omni.diffusion.distributed import parallel_state
+
+    torch.distributed.init_process_group(
+        "gloo",
+        init_method=init_method,
+        rank=rank,
+        world_size=4,
+        timeout=datetime.timedelta(seconds=10),
+    )
+    try:
+        fs_groups = [
+            (ranks, torch.distributed.new_group(ranks, timeout=datetime.timedelta(seconds=10)))
+            for ranks in ([0, 1], [2, 3])
+        ]
+        ulysses_groups = [
+            (ranks, torch.distributed.new_group(ranks, timeout=datetime.timedelta(seconds=10)))
+            for ranks in ([0, 1], [2, 3])
+        ]
+        ring_groups = [
+            (ranks, torch.distributed.new_group(ranks, timeout=datetime.timedelta(seconds=10)))
+            for ranks in ([0, 2], [1, 3])
+        ]
+        sp_group = torch.distributed.new_group(
+            [0, 1, 2, 3],
+            timeout=datetime.timedelta(seconds=10),
+        )
+        fs_group = next(group for ranks, group in fs_groups if rank in ranks)
+        ulysses_group = next(group for ranks, group in ulysses_groups if rank in ranks)
+        ring_group = next(group for ranks, group in ring_groups if rank in ranks)
+        parallel_state._FS = SimpleNamespace(world_size=2, device_group=fs_group)
+        parallel_state._SP = SimpleNamespace(
+            world_size=4,
+            device_group=sp_group,
+            ulysses_world_size=2,
+            ulysses_group=ulysses_group,
+            ring_world_size=2,
+            ring_group=ring_group,
+        )
+
+        compute = rank == 3
+        non_sharded_hook = SeaCacheRootHook(SeaCacheConfig())
+        non_sharded_result = non_sharded_hook._synchronize_compute(compute, torch.device("cpu"))
+
+        sharded_hook = SeaCacheRootHook(SeaCacheConfig())
+        sharded_hook._parameter_sharded = True
+        sharded_result = sharded_hook._synchronize_compute(compute, torch.device("cpu"))
+        result_queue.put((rank, non_sharded_result, sharded_result))
+    finally:
+        parallel_state._FS = None
+        parallel_state._SP = None
+        torch.distributed.destroy_process_group()
+
+
+def test_hook_synchronizes_full_hybrid_sequence_parallel_group() -> None:
+    mp_context = torch.multiprocessing.get_context("spawn")
+    manager = mp_context.Manager()
+    result_queue = manager.Queue()
+    torch.multiprocessing.spawn(
+        _hybrid_sp_worker,
+        args=(get_distributed_init_method("seacache_hybrid_sp_"), result_queue),
+        nprocs=4,
+    )
+
+    results = sorted(result_queue.get(timeout=2) for _ in range(4))
+    assert results == [
+        (0, True, True),
+        (1, True, True),
+        (2, True, True),
+        (3, True, True),
+    ]
+
+
+def test_parameter_sharded_hook_fails_open_without_distributed_state(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    hook = SeaCacheRootHook(SeaCacheConfig())
+    hook._parameter_sharded = True
+    monkeypatch.setattr(torch.distributed, "is_available", lambda: True)
+    monkeypatch.setattr(torch.distributed, "is_initialized", lambda: False)
+
+    assert hook._synchronize_compute(False, torch.device("cpu")) is True
+
+
+def test_hook_keeps_three_transfer_branches_separate() -> None:
+    transformer = TinyCosmos3Transformer()
+    metadata = SimpleNamespace(step=0, sigma=1.0, num_steps=3)
+    hook = _apply_test_hook(transformer, metadata)
+    hook.refresh(transformer)
+
+    contexts = ("cond", "cond_no_control", "uncond")
+    for step, (timestep, value) in enumerate(((1000, 1.0), (500, 0.9))):
+        metadata.step = step
+        metadata.sigma = timestep / 1000
+        _run_step(transformer, timestep, value, hook=hook, context=contexts[0], control=0.5)
+        _run_step(transformer, timestep, value, hook=hook, context=contexts[1])
+        _run_step(transformer, timestep, value, hook=hook, context=contexts[2], control=0.5)
+
+    assert set(hook.state_manager._states) == set(contexts)
+    assert hook.full_count == 3
+    assert hook.skip_count == 3
+    assert len(hook.state_manager._states["cond"].previous_indicator) == 2
+    assert len(hook.state_manager._states["cond_no_control"].previous_indicator) == 1
+
+
+def test_hook_fails_open_without_noisy_vision() -> None:
+    transformer = TinyCosmos3Transformer()
+    metadata = SimpleNamespace(step=0, sigma=1.0, num_steps=3)
+    hook = _apply_test_hook(transformer, metadata)
+    hook.refresh(transformer)
+    all_clean = torch.zeros(1, 1, 2, 1, 1)
+
+    _run_step(transformer, 1000, 1.0, hook=hook, noisy_frame_mask=all_clean)
+    metadata.step = 1
+    metadata.sigma = 0.5
+    _run_step(transformer, 500, 0.9, hook=hook, noisy_frame_mask=all_clean)
+
+    assert hook.full_count == 0
+    assert hook.skip_count == 0
+
+
+def test_conditioning_only_model_failure_runs_forward_once(monkeypatch: pytest.MonkeyPatch) -> None:
+    transformer = TinyCosmos3Transformer()
+    metadata = SimpleNamespace(step=0, sigma=1.0, num_steps=3)
+    hook = _apply_test_hook(transformer, metadata)
+    hook.refresh(transformer)
+    forward_calls = 0
+
+    def fail_forward(hidden_gen: torch.Tensor) -> torch.Tensor:
+        nonlocal forward_calls
+        forward_calls += 1
+        raise RuntimeError("model forward failed")
+
+    monkeypatch.setattr(transformer, "_run_gen_layers", fail_forward)
+    all_clean = torch.zeros(1, 1, 2, 1, 1)
+
+    with pytest.raises(RuntimeError, match="model forward failed"):
+        _run_step(transformer, 1000, 1.0, hook=hook, noisy_frame_mask=all_clean)
+
+    assert forward_calls == 1
+
+
+def test_hook_fails_open_without_explicit_context() -> None:
+    transformer = TinyCosmos3Transformer()
+    metadata = SimpleNamespace(step=0, sigma=1.0, num_steps=2)
+    hook = _apply_test_hook(transformer, metadata)
+    hook.refresh(transformer)
+
+    _run_step(transformer, 1000, 1.0)
+
+    assert hook.full_count == 0
+    assert hook.skip_count == 0
+    assert hook.state_manager._states == {}
+
+
+def test_hook_uses_exact_sigma_callback(monkeypatch: pytest.MonkeyPatch) -> None:
+    from vllm_omni.diffusion.cache.seacache import hook as hook_module
+
+    transformer = TinyCosmos3Transformer()
+    metadata = SimpleNamespace(step=0, sigma=0.37, num_steps=2)
+    observed_sigmas: list[float] = []
+    original_filter = hook_module.apply_sea_filter
+
+    def recording_filter(hidden_states: torch.Tensor, sigma: float, power_exp: float) -> torch.Tensor:
+        observed_sigmas.append(sigma)
+        return original_filter(hidden_states, sigma, power_exp)
+
+    monkeypatch.setattr(hook_module, "apply_sea_filter", recording_filter)
+    hook = _apply_test_hook(transformer, metadata)
+    hook.refresh(transformer)
+    _run_step(transformer, timestep=999, value=1.0, hook=hook)
+
+    assert observed_sigmas
+    assert all(sigma == pytest.approx(0.37) for sigma in observed_sigmas)
+
+
+def test_backend_selector_and_refresh(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setitem(EXTRACTOR_REGISTRY, "TinyCosmos3Transformer", _extract_tiny_cosmos3_context)
+
+    class FSDPTinyCosmos3Transformer(TinyCosmos3Transformer):
+        pass
+
+    assert get_extractor(FSDPTinyCosmos3Transformer) is _extract_tiny_cosmos3_context
+    backend = get_cache_backend(
+        "sea_cache",
+        {
+            "sea_threshold": 0.4,
+            "sea_residual_order": 0,
+        },
+    )
+    assert isinstance(backend, SeaCacheBackend)
+    assert backend.config.sea_threshold == 0.4
+
+    pipeline = Cosmos3OmniDiffusersPipeline()
+    backend.enable(pipeline)
+    hook = pipeline.transformer._hook_registry.get_hook(SeaCacheRootHook._HOOK_NAME)
+    assert isinstance(hook, SeaCacheRootHook)
+    assert callable(getattr(pipeline, "_cache_context_factory", None))
+    for name in ("_seacache_skip", "_seacache_record", "_seacache_residual", "_seacache_last_residual"):
+        assert not hasattr(pipeline.transformer, name)
+    pipeline._current_step_index = 0
+    pipeline._current_sigma = 1.0
+    pipeline._num_timesteps = 7
+    _run_step(pipeline.transformer, 1000, 1.0, hook=hook)
+    assert hook.full_count == 1
+
+    backend.refresh(pipeline, num_inference_steps=7)
+    assert hook.full_count == 0
+    assert hook.skip_count == 0
+    assert hook.state_manager._states == {}
+
+
+def test_backend_uses_resolved_pipeline_metadata_not_refresh_argument(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setitem(EXTRACTOR_REGISTRY, "TinyCosmos3Transformer", _extract_tiny_cosmos3_context)
+    pipeline = Cosmos3OmniDiffusersPipeline()
+    backend = SeaCacheBackend(DiffusionCacheConfig())
+    backend.enable(pipeline)
+    hook = pipeline.transformer._hook_registry.get_hook(SeaCacheRootHook._HOOK_NAME)
+    assert isinstance(hook, SeaCacheRootHook)
+    backend.refresh(pipeline, num_inference_steps=35)
+    pipeline._num_timesteps = 50
+    pipeline._current_step_index = 0
+    pipeline._current_sigma = 1.0
+    _run_step(pipeline.transformer, 1000, 1.0, hook=hook)
+    assert hook.full_count == 1
+    assert hook.num_inference_steps_callback is not None
+    assert hook.num_inference_steps_callback() == 50
+
+    pipeline._current_step_index = 1
+    pipeline._current_sigma = 0.98
+    _run_step(pipeline.transformer, 980, 0.99, hook=hook)
+    assert hook.full_count == 1
+    assert hook.skip_count == 1
+
+
+def test_shared_config_defaults() -> None:
+    config = DiffusionCacheConfig()
+    assert config.sea_threshold == 0.25
+    assert config.sea_residual_order == 1
+    assert config.sea_max_consecutive_cached == 2
+    assert config.sea_power_exp == 3.0
diff --git a/tests/diffusion/models/cosmos3/test_cosmos3_pipeline.py b/tests/diffusion/models/cosmos3/test_cosmos3_pipeline.py
index 9892a72d744..e73dd7ff614 100644
--- a/tests/diffusion/models/cosmos3/test_cosmos3_pipeline.py
+++ b/tests/diffusion/models/cosmos3/test_cosmos3_pipeline.py
@@ -1,11 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from __future__ import annotations
 
 import json
 import sys
 import types
+from contextlib import contextmanager
 from dataclasses import dataclass
 from types import SimpleNamespace
 from typing import Any
@@ -85,6 +86,7 @@ def __init__(
         flow_shift: float = 1.0,
     ) -> None:
         self.timesteps = torch.tensor(timesteps or [9, 3], dtype=torch.int64)
+        self.sigmas = self.timesteps.float() / 10
         self.config = SimpleNamespace(
             num_train_timesteps=1000,
             flow_shift=flow_shift,
@@ -113,6 +115,7 @@ def set_timesteps(
         else:
             assert num_inference_steps is not None
             self.timesteps = torch.arange(num_inference_steps, 0, -1, dtype=torch.int64, device=device)
+        self.sigmas = self.timesteps.float()
 
     def step(self, noise_pred: torch.Tensor, timestep: torch.Tensor, latents: torch.Tensor, **kwargs):
         del kwargs
@@ -250,7 +253,7 @@ def passthrough_progress_bar(iterable):
 
 @pytest.fixture(autouse=True)
 def fake_cosmos3_guardrails(monkeypatch: pytest.MonkeyPatch):
-    module = types.ModuleType("vllm_omni.diffusion.models.cosmos3.guardrails")
+    module: Any = types.ModuleType("vllm_omni.diffusion.models.cosmos3.guardrails")
     module.is_guardrails_enabled = lambda od_config, sampling_params=None: False
     module.ensure_initialized = lambda od_config: None
     module.check_text_safety = lambda text: None
@@ -283,6 +286,8 @@ def _make():
         pipeline.is_edge_model = False
         pipeline._guidance_scale = None
         pipeline._num_timesteps = None
+        pipeline._current_step_index = None
+        pipeline._current_sigma = None
         pipeline._cosmos3_branch_caches = None
         pipeline._cache_dit_requires_paired_cfg = False
         pipeline._sound_tokenizer = None
@@ -300,7 +305,7 @@ def sequential_cfg_parallel(monkeypatch: pytest.MonkeyPatch) -> None:
 
 
 def make_sampling_params(**overrides: Any) -> SimpleNamespace:
-    values = {
+    values: dict[str, Any] = {
         "height": None,
         "width": None,
         "num_frames": None,
@@ -814,7 +819,7 @@ def test_pipeline_resolves_scheduler_class_from_checkpoint_file(
     t_list = [1.0, 0.75, 0.5, 0.25]
     scheduler_dir = tmp_path / "scheduler"
     scheduler_dir.mkdir()
-    scheduler_config = {"_class_name": scheduler_class_name}
+    scheduler_config: dict[str, Any] = {"_class_name": scheduler_class_name}
     if expected_distilled:
         scheduler_config["fixed_step_sampler_config"] = {"sample_type": "sde", "t_list": t_list}
     (scheduler_dir / "scheduler_config.json").write_text(json.dumps(scheduler_config))
@@ -1531,7 +1536,7 @@ class FakeIrOpPriorityConfig:
         fused_add_rms_norm: list[str]
         custom_op: list[str]
 
-    fake_kernel = types.ModuleType("vllm.config.kernel")
+    fake_kernel: Any = types.ModuleType("vllm.config.kernel")
     fake_kernel.IrOpPriorityConfig = FakeIrOpPriorityConfig
     monkeypatch.setitem(sys.modules, fake_kernel.__name__, fake_kernel)
 
@@ -2154,6 +2159,47 @@ def test_diffuse_covers_cfg_i2v_and_multimodal_steps(make_cosmos3_pipeline) -> N
     torch.testing.assert_close(action_result, torch.full((), 44.0).expand_as(action_result))
 
 
+def test_diffuse_publishes_exact_seacache_metadata_and_cfg_contexts(make_cosmos3_pipeline) -> None:
+    pipeline = make_cosmos3_pipeline()
+    pipeline.scheduler.sigmas = torch.tensor([0.91, 0.17])
+    observations: list[tuple[str, int | None, float | None, int | None]] = []
+
+    class RecordingHook:
+        @contextmanager
+        def cache_context(self, name: str):
+            sigma = pipeline.current_sigma
+            observations.append(
+                (
+                    name,
+                    pipeline.current_step_index,
+                    None if sigma is None else float(sigma),
+                    pipeline.num_timesteps,
+                )
+            )
+            yield
+
+    pipeline._cache_context_factory = RecordingHook().cache_context
+    pipeline.diffuse(
+        latents=torch.zeros(1, 2, 1, 1, 1),
+        timesteps=torch.tensor([900, 100]),
+        cond_ids=_ids(2),
+        cond_mask=_mask(),
+        uncond_ids=_ids(1),
+        uncond_mask=_mask(),
+        guidance_scale=3.0,
+        shared_kwargs={"video_shape": (1, 1, 1), "fps": 24.0},
+    )
+
+    assert observations == [
+        ("cond", 0, pytest.approx(0.91), 2),
+        ("uncond", 0, pytest.approx(0.91), 2),
+        ("cond", 1, pytest.approx(0.17), 2),
+        ("uncond", 1, pytest.approx(0.17), 2),
+    ]
+    assert pipeline.current_step_index is None
+    assert pipeline.current_sigma is None
+
+
 def test_diffuse_drops_session_when_progress_iteration_fails(make_cosmos3_pipeline) -> None:
     pipeline = make_cosmos3_pipeline()
     pipeline._use_session_state = True
@@ -2213,6 +2259,53 @@ def test_diffuse_transfer_applies_control_cfg(make_cosmos3_pipeline, sequential_
     torch.testing.assert_close(result, torch.full_like(latents, 254.0))
 
 
+def test_diffuse_transfer_uses_named_seacache_contexts(make_cosmos3_pipeline, sequential_cfg_parallel) -> None:
+    pipeline = make_cosmos3_pipeline()
+    pipeline.scheduler.sigmas = torch.tensor([0.42])
+    contexts: list[tuple[str, int | None, float | None, int | None]] = []
+
+    class RecordingHook:
+        @contextmanager
+        def cache_context(self, name: str):
+            sigma = pipeline.current_sigma
+            contexts.append(
+                (
+                    name,
+                    pipeline.current_step_index,
+                    None if sigma is None else float(sigma),
+                    pipeline.num_timesteps,
+                )
+            )
+            yield
+
+    pipeline._cache_context_factory = RecordingHook().cache_context
+    latents = torch.zeros(1, 2, 1, 1, 1)
+    velocity_mask = torch.ones(1, 1, 1, 1, 1)
+    pipeline.diffuse_transfer(
+        latents=latents,
+        timesteps=torch.tensor([7]),
+        cond_ids=_ids(2),
+        cond_mask=_mask(),
+        uncond_ids=_ids(1),
+        uncond_mask=_mask(),
+        guidance_scale=3.0,
+        control_guidance=1.5,
+        control_guidance_interval=None,
+        control_latents=[torch.zeros_like(latents)],
+        shared_kwargs={"video_shape": (1, 1, 1), "fps": 24.0, "noisy_frame_mask": velocity_mask},
+        velocity_mask=velocity_mask,
+        condition_latents=torch.zeros_like(latents),
+    )
+
+    assert contexts == [
+        ("cond", 0, pytest.approx(0.42), 1),
+        ("cond_no_control", 0, pytest.approx(0.42), 1),
+        ("uncond", 0, pytest.approx(0.42), 1),
+    ]
+    assert pipeline.current_step_index is None
+    assert pipeline.current_sigma is None
+
+
 def test_diffuse_transfer_rejects_session_state_manager(make_cosmos3_pipeline) -> None:
     pipeline = make_cosmos3_pipeline()
     pipeline._use_session_state = True
@@ -2583,7 +2676,7 @@ def test_diffuse_keeps_paired_cfg_when_cache_dit_active(make_cosmos3_pipeline) -
 
 class TestForwardRouting:
     def _install_forward_stubs(self, pipeline):
-        captured: dict[str, object] = {"diffuse_calls": [], "prepare_calls": []}
+        captured: dict[str, Any] = {"diffuse_calls": [], "prepare_calls": []}
 
         def fake_format(
             prompt,
diff --git a/tests/diffusion/models/cosmos3/test_cosmos3_transformer.py b/tests/diffusion/models/cosmos3/test_cosmos3_transformer.py
index 44bd8e9a71f..de14ee233fd 100644
--- a/tests/diffusion/models/cosmos3/test_cosmos3_transformer.py
+++ b/tests/diffusion/models/cosmos3/test_cosmos3_transformer.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from __future__ import annotations
 
@@ -513,6 +513,108 @@ def test_forward_returns_video_prediction(monkeypatch: pytest.MonkeyPatch) -> No
     assert tuple(output.shape) == (1, 2, 1, 2, 2)
 
 
+def test_cache_execution_residual_spans_final_gen_norm(monkeypatch: pytest.MonkeyPatch) -> None:
+    from vllm_omni.diffusion.cache.teacache.extractors import extract_cosmos3_context
+    from vllm_omni.diffusion.models.cosmos3 import transformer_cosmos3
+
+    class TrackingNorm(nn.Module):
+        def __init__(self) -> None:
+            super().__init__()
+            self.calls = 0
+
+        def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
+            self.calls += 1
+            return hidden_states + 5.0
+
+    monkeypatch.setattr(transformer_cosmos3, "_get_ulysses_state", lambda: (1, 0, None))
+    model = transformer_cosmos3.Cosmos3VFMTransformer(
+        SimpleNamespace(tf_model_config=_tiny_cosmos3_config(), dtype=torch.float32)
+    )
+    norm = TrackingNorm()
+    model.norm_moe_gen = norm
+    captured: dict[str, torch.Tensor] = {}
+
+    def run_gen_layers(hidden_gen: torch.Tensor, **kwargs) -> torch.Tensor:
+        del kwargs
+        captured["input"] = hidden_gen.detach().clone()
+        return hidden_gen + 2.0
+
+    monkeypatch.setattr(model, "_run_gen_layers", run_gen_layers)
+    forward_kwargs = {
+        "hidden_states": torch.zeros(1, 2, 1, 2, 2),
+        "timestep": torch.tensor([1.0]),
+        "text_ids": torch.tensor([[1, 2]], dtype=torch.long),
+        "text_mask": torch.ones(1, 2, dtype=torch.long),
+        "video_shape": (1, 2, 2),
+        "fps": 24.0,
+    }
+
+    full_output = model(**forward_kwargs)
+
+    assert norm.calls == 1
+    norm.calls = 0
+
+    ctx = extract_cosmos3_context(model, **forward_kwargs)
+    execution_input = ctx.hidden_states.detach().clone()
+    execution_output = ctx.run_transformer_blocks()[0]
+    residual = execution_output - execution_input
+    extracted_output = ctx.postprocess(execution_output)
+
+    assert norm.calls == 1
+    expected_residual = ((captured["input"] + 2.0) + 5.0) - captured["input"]
+    assert torch.equal(residual, expected_residual)
+    assert torch.equal(extracted_output, full_output)
+
+    norm.calls = 0
+
+    def fail_if_gen_layers_run(*args, **kwargs):
+        del args, kwargs
+        raise AssertionError("SeaCache hit unexpectedly executed GEN layers")
+
+    monkeypatch.setattr(model, "_run_gen_layers", fail_if_gen_layers_run)
+
+    cached_ctx = extract_cosmos3_context(model, **forward_kwargs)
+    cached_output = cached_ctx.postprocess(cached_ctx.hidden_states + residual)
+
+    assert norm.calls == 0
+    assert torch.equal(cached_output, full_output)
+    for name in ("_seacache_skip", "_seacache_record", "_seacache_residual", "_seacache_last_residual"):
+        assert not hasattr(model, name)
+
+
+def test_no_cache_still_runs_final_gen_norm_once(monkeypatch: pytest.MonkeyPatch) -> None:
+    from vllm_omni.diffusion.models.cosmos3 import transformer_cosmos3
+
+    class CountingNorm(nn.Module):
+        def __init__(self, original: nn.Module) -> None:
+            super().__init__()
+            self.original = original
+            self.calls = 0
+
+        def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
+            self.calls += 1
+            return self.original(hidden_states)
+
+    monkeypatch.setattr(transformer_cosmos3, "_get_ulysses_state", lambda: (1, 0, None))
+    model = transformer_cosmos3.Cosmos3VFMTransformer(
+        SimpleNamespace(tf_model_config=_tiny_cosmos3_config(), dtype=torch.float32)
+    )
+    norm = CountingNorm(model.norm_moe_gen)
+    model.norm_moe_gen = norm
+
+    output = model(
+        hidden_states=torch.zeros(1, 2, 1, 2, 2),
+        timestep=torch.tensor([1.0]),
+        text_ids=torch.tensor([[1, 2]], dtype=torch.long),
+        text_mask=torch.ones(1, 2, dtype=torch.long),
+        video_shape=(1, 2, 2),
+        fps=24.0,
+    )
+
+    assert norm.calls == 1
+    assert tuple(output.shape) == (1, 2, 1, 2, 2)
+
+
 def test_qwen_gen_mlp_remains_gated() -> None:
     from vllm_omni.diffusion.models.cosmos3.transformer_cosmos3 import Cosmos3GatedMLP, Cosmos3VFMTransformer
 
diff --git a/vllm_omni/diffusion/cache/seacache/__init__.py b/vllm_omni/diffusion/cache/seacache/__init__.py
new file mode 100644
index 00000000000..2821c4de04a
--- /dev/null
+++ b/vllm_omni/diffusion/cache/seacache/__init__.py
@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from vllm_omni.diffusion.cache.seacache.backend import SeaCacheBackend
+from vllm_omni.diffusion.cache.seacache.config import SeaCacheConfig
+from vllm_omni.diffusion.cache.seacache.hook import (
+    SeaCacheRootHook,
+    apply_sea_cache_hook,
+)
+from vllm_omni.diffusion.cache.seacache.state import SeaCacheState
+
+__all__ = [
+    "SeaCacheBackend",
+    "SeaCacheConfig",
+    "SeaCacheRootHook",
+    "SeaCacheState",
+    "apply_sea_cache_hook",
+]
diff --git a/vllm_omni/diffusion/cache/seacache/backend.py b/vllm_omni/diffusion/cache/seacache/backend.py
new file mode 100644
index 00000000000..e5e513a73fb
--- /dev/null
+++ b/vllm_omni/diffusion/cache/seacache/backend.py
@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+from typing import Any
+
+from vllm.logger import init_logger
+
+from vllm_omni.diffusion.cache.base import CacheBackend
+from vllm_omni.diffusion.cache.seacache.config import SeaCacheConfig
+from vllm_omni.diffusion.cache.seacache.hook import (
+    SeaCacheRootHook,
+    apply_sea_cache_hook,
+)
+from vllm_omni.diffusion.data import DiffusionCacheConfig
+
+logger = init_logger(__name__)
+
+
+def enable_cosmos3_seacache(
+    pipeline: Any,
+    config: DiffusionCacheConfig,
+) -> SeaCacheRootHook:
+    transformer = getattr(pipeline, "transformer", None)
+    if transformer is None:
+        raise ValueError("SeaCache requires a pipeline with a transformer")
+
+    sea_config = SeaCacheConfig(
+        threshold=config.sea_threshold,
+        residual_order=config.sea_residual_order,
+        max_consecutive_cached=config.sea_max_consecutive_cached,
+        power_exp=config.sea_power_exp,
+    )
+    hook = apply_sea_cache_hook(
+        transformer,
+        sea_config,
+        current_step_callback=lambda: getattr(pipeline, "current_step_index", None),
+        current_sigma_callback=lambda: getattr(pipeline, "current_sigma", None),
+        num_inference_steps_callback=lambda: getattr(
+            pipeline,
+            "num_timesteps",
+            None,
+        ),
+    )
+    logger.info(
+        "SeaCache enabled for %s (threshold=%s, residual_order=%d, max_consecutive_cached=%d, power_exp=%s)",
+        pipeline.__class__.__name__,
+        sea_config.threshold,
+        sea_config.residual_order,
+        sea_config.max_consecutive_cached,
+        sea_config.power_exp,
+    )
+    return hook
+
+
+CUSTOM_SEACACHE_ENABLERS = {
+    "Cosmos3OmniDiffusersPipeline": enable_cosmos3_seacache,
+    "Cosmos3OmniPipeline": enable_cosmos3_seacache,
+}
+
+
+class SeaCacheBackend(CacheBackend):
+    """Backend for spectral-evolution-aware diffusion caching."""
+
+    def __init__(self, config: DiffusionCacheConfig):
+        super().__init__(config)
+        self._transformer_id: int | None = None
+
+    def enable(self, pipeline: Any) -> None:
+        pipeline_type = pipeline.__class__.__name__
+        enabler = CUSTOM_SEACACHE_ENABLERS.get(pipeline_type)
+        if enabler is None:
+            raise ValueError(f"SeaCache does not support pipeline type {pipeline_type}")
+        hook = enabler(pipeline, self.config)
+        self._transformer_id = id(pipeline.transformer)
+        self.enabled = True
+        pipeline._cache_context_factory = hook.cache_context
+
+    def refresh(
+        self,
+        pipeline: Any,
+        num_inference_steps: int,
+        verbose: bool = True,
+    ) -> None:
+        del num_inference_steps
+        transformer = getattr(pipeline, "transformer", None)
+        if transformer is None:
+            raise ValueError("SeaCache requires a pipeline with a transformer")
+        if not self.enabled or self._transformer_id != id(transformer):
+            self.enable(pipeline)
+
+        registry = getattr(transformer, "_hook_registry", None)
+        hook = registry.get_hook(SeaCacheRootHook._HOOK_NAME) if registry is not None else None
+        if not isinstance(hook, SeaCacheRootHook):
+            raise RuntimeError("SeaCache hook is not installed on the pipeline transformer")
+        hook.refresh(transformer)
+        pipeline._cache_context_factory = hook.cache_context
+        if verbose:
+            logger.debug("SeaCache state refreshed")
diff --git a/vllm_omni/diffusion/cache/seacache/config.py b/vllm_omni/diffusion/cache/seacache/config.py
new file mode 100644
index 00000000000..501d4653e29
--- /dev/null
+++ b/vllm_omni/diffusion/cache/seacache/config.py
@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class SeaCacheConfig:
+    """Configuration for SeaCache.
+
+    Defaults are tuned for Cosmos3 and may require adjustment for other models.
+    """
+
+    threshold: float = 0.25
+    residual_order: int = 1
+    max_consecutive_cached: int = 2
+    power_exp: float = 3.0
+
+    def __post_init__(self) -> None:
+        if not math.isfinite(self.threshold) or self.threshold < 0:
+            raise ValueError(f"threshold must be finite and non-negative, got {self.threshold}")
+        if isinstance(self.residual_order, bool) or not isinstance(self.residual_order, int) or self.residual_order < 0:
+            raise ValueError(f"residual_order must be a non-negative integer, got {self.residual_order!r}")
+        if (
+            isinstance(self.max_consecutive_cached, bool)
+            or not isinstance(self.max_consecutive_cached, int)
+            or self.max_consecutive_cached < 0
+        ):
+            raise ValueError(
+                f"max_consecutive_cached must be a non-negative integer, got {self.max_consecutive_cached!r}"
+            )
+        if not math.isfinite(self.power_exp) or self.power_exp <= 0:
+            raise ValueError(f"power_exp must be finite and positive, got {self.power_exp}")
diff --git a/vllm_omni/diffusion/cache/seacache/hook.py b/vllm_omni/diffusion/cache/seacache/hook.py
new file mode 100644
index 00000000000..3fac58c0941
--- /dev/null
+++ b/vllm_omni/diffusion/cache/seacache/hook.py
@@ -0,0 +1,397 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import Any
+
+import torch
+from vllm.logger import init_logger
+
+from vllm_omni.diffusion.cache.seacache.config import SeaCacheConfig
+from vllm_omni.diffusion.cache.seacache.sea_filter import (
+    apply_sea_filter,
+    extrapolate_residual,
+    indicator_distance,
+)
+from vllm_omni.diffusion.cache.seacache.state import SeaCacheState
+from vllm_omni.diffusion.cache.teacache.extractors import CacheContext, get_extractor
+from vllm_omni.diffusion.hooks import HookRegistry, ModelHook, StateManager
+
+logger = init_logger(__name__)
+
+
+def _is_parameter_sharded(module: torch.nn.Module) -> bool:
+    """Detect parameter-sharding runtimes whose collectives cannot be skipped."""
+    for submodule in module.modules():
+        module_type = type(submodule)
+        if callable(getattr(submodule, "_get_fsdp_state", None)):
+            return True
+        if module_type.__name__ == "FullyShardedDataParallel" and module_type.__module__.startswith(
+            "torch.distributed.fsdp"
+        ):
+            return True
+        for parameter in submodule.parameters(recurse=False):
+            parameter_type = type(parameter)
+            if (
+                parameter_type.__name__ == "FlatParameter"
+                and parameter_type.__module__.startswith("torch.distributed.fsdp")
+            ) or (
+                parameter_type.__name__ == "DTensor"
+                and parameter_type.__module__.startswith("torch.distributed.tensor")
+            ):
+                return True
+    return False
+
+
+class SeaCacheRootHook(ModelHook):
+    """Drive SeaCache gating and transformer forward control."""
+
+    _HOOK_NAME = "sea_cache"
+
+    def __init__(
+        self,
+        config: SeaCacheConfig,
+        *,
+        current_step_callback: Callable[[], int | torch.Tensor | None] | None = None,
+        current_sigma_callback: Callable[[], float | torch.Tensor | None] | None = None,
+        num_inference_steps_callback: Callable[[], int | torch.Tensor | None] | None = None,
+        extractor_fn: Callable[..., CacheContext] | None = None,
+    ) -> None:
+        super().__init__()
+        self.config = config
+        self.current_step_callback = current_step_callback
+        self.current_sigma_callback = current_sigma_callback
+        self.num_inference_steps_callback = num_inference_steps_callback
+        self.state_manager = StateManager(SeaCacheState)
+        self._warned_messages: set[str] = set()
+        self.full_count = 0
+        self.skip_count = 0
+        self.extractor_fn = extractor_fn
+        self._parameter_sharded = False
+        self._collective_skip_groups: list[torch.distributed.ProcessGroup] = []
+
+    def initialize_hook(self, module: torch.nn.Module) -> torch.nn.Module:
+        if self.extractor_fn is None:
+            self.extractor_fn = get_extractor(type(module))
+        self._parameter_sharded = _is_parameter_sharded(module)
+        seen_groups: set[int] = set()
+        for block in getattr(module, "gen_layers", ()):
+            registry = getattr(block, "_hook_registry", None)
+            dlo_hook = registry.get_hook("distributed_layerwise_offload") if registry is not None else None
+            group = getattr(dlo_hook, "dp_group", None)
+            if group is not None and int(getattr(dlo_hook, "dp_size", 1)) > 1 and id(group) not in seen_groups:
+                seen_groups.add(id(group))
+                self._collective_skip_groups.append(group)
+        return module
+
+    def _warn_once(self, message: str) -> None:
+        if message not in self._warned_messages:
+            logger.warning(message)
+            self._warned_messages.add(message)
+
+    @contextmanager
+    def cache_context(self, name: str) -> Iterator[None]:
+        previous_context = self.state_manager._context
+        self.state_manager.set_context(name)
+        try:
+            yield
+        finally:
+            self.state_manager.set_context(previous_context)
+
+    def _build_indicator(
+        self,
+        vision_items: list[torch.Tensor] | None,
+        sigma: float,
+    ) -> list[torch.Tensor] | None:
+        if not vision_items:
+            return None
+        hidden_states = vision_items[-1]
+        if not isinstance(hidden_states, torch.Tensor) or hidden_states.ndim != 5:
+            return None
+
+        # Controls precede the denoised target in packed vision-token order,
+        # and each vision item is filtered independently.
+        if any(
+            not isinstance(item, torch.Tensor)
+            or item.ndim != 5
+            or item.shape[0] != hidden_states.shape[0]
+            or item.shape[1:] != hidden_states.shape[1:]
+            for item in vision_items
+        ):
+            return None
+
+        indicator = []
+        for batch_index in range(hidden_states.shape[0]):
+            for latent in vision_items:
+                thwc = latent[batch_index].movedim(0, -1)
+                indicator.append(
+                    apply_sea_filter(
+                        thwc,
+                        sigma=sigma,
+                        power_exp=self.config.power_exp,
+                    ).detach()
+                )
+        return indicator or None
+
+    def _resolve_gate(
+        self,
+        state: SeaCacheState,
+        indicator: list[torch.Tensor] | None,
+        step: int,
+        num_inference_steps: int,
+    ) -> bool:
+        if state.last_step is not None and step != state.last_step + 1:
+            state.reset()
+        state.last_step = step
+        max_consecutive = bool(
+            self.config.max_consecutive_cached and state.consecutive_cached >= self.config.max_consecutive_cached
+        )
+        forced_compute = (
+            step < 1
+            or step >= num_inference_steps - 1
+            or max_consecutive
+            or not state.history
+            or indicator is None
+            or state.previous_indicator is None
+        )
+        if forced_compute:
+            state.accumulated_distance = 0.0
+            state.previous_indicator = None if indicator is None else [value.detach() for value in indicator]
+            return True
+
+        assert indicator is not None
+        assert state.previous_indicator is not None
+        distance = indicator_distance(indicator, state.previous_indicator)
+        state.previous_indicator = [value.detach() for value in indicator]
+        if not math.isfinite(distance):
+            state.accumulated_distance = 0.0
+            self._warn_once("SeaCache indicator history changed shape, device, or dtype; running full.")
+            return True
+
+        state.accumulated_distance += distance
+        if state.accumulated_distance < self.config.threshold:
+            return False
+        state.accumulated_distance = 0.0
+        return True
+
+    def _synchronize_compute(self, compute: bool, device: torch.device) -> bool:
+        if not torch.distributed.is_available() or not torch.distributed.is_initialized():
+            return True if self._parameter_sharded else compute
+        decision = torch.tensor(int(compute), dtype=torch.int32, device=device)
+        if self._parameter_sharded:
+            from vllm_omni.diffusion.distributed.parallel_state import (
+                get_fs_group,
+                get_sequence_parallel_world_size,
+                get_sp_group,
+            )
+
+            fs_group = get_fs_group()
+            if fs_group.world_size > 1:
+                torch.distributed.all_reduce(
+                    decision,
+                    op=torch.distributed.ReduceOp.MAX,
+                    group=fs_group.device_group,
+                )
+            if get_sequence_parallel_world_size() > 1:
+                torch.distributed.all_reduce(
+                    decision,
+                    op=torch.distributed.ReduceOp.MAX,
+                    group=get_sp_group().device_group,
+                )
+            return bool(decision.item())
+
+        for group in self._collective_skip_groups:
+            torch.distributed.all_reduce(
+                decision,
+                op=torch.distributed.ReduceOp.MAX,
+                group=group,
+            )
+        from vllm_omni.diffusion.distributed.parallel_state import (
+            get_sequence_parallel_world_size,
+            get_sp_group,
+        )
+
+        if get_sequence_parallel_world_size() > 1:
+            torch.distributed.all_reduce(
+                decision,
+                op=torch.distributed.ReduceOp.MAX,
+                group=get_sp_group().device_group,
+            )
+        return bool(decision.item())
+
+    @torch.compiler.disable
+    def new_forward(
+        self,
+        module: torch.nn.Module,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        if self.extractor_fn is None:
+            raise RuntimeError("SeaCache extractor was not initialized")
+        ctx = self.extractor_fn(module, *args, **kwargs)
+
+        if torch.is_grad_enabled():
+            self._warn_once("SeaCache is inference-only; autograd-enabled calls run in full.")
+            return self._run_uncached(ctx)
+        if self.state_manager._current_context is None:
+            self._warn_once("SeaCache requires an explicit cache context; running full.")
+            return self._run_uncached(ctx)
+        callbacks = (
+            self.current_step_callback,
+            self.current_sigma_callback,
+            self.num_inference_steps_callback,
+        )
+        if any(callback is None for callback in callbacks):
+            self._warn_once("SeaCache requires scheduler step, sigma, and step-count callbacks; running full.")
+            return self._run_uncached(ctx)
+        assert self.current_step_callback is not None
+        assert self.current_sigma_callback is not None
+        assert self.num_inference_steps_callback is not None
+
+        try:
+            extra_states = ctx.extra_states or {}
+            vision_items = extra_states.get("sea_cache_latents")
+            if not isinstance(vision_items, list):
+                raise ValueError("extractor did not provide SeaCache vision inputs")
+            noisy_frame_mask = extra_states.get("sea_cache_noisy_frame_mask")
+            conditioning_only = isinstance(noisy_frame_mask, torch.Tensor) and not bool(
+                torch.any(noisy_frame_mask != 0).item()
+            )
+
+            step = self.current_step_callback()
+            sigma = self.current_sigma_callback()
+            num_inference_steps = self.num_inference_steps_callback()
+            if isinstance(step, torch.Tensor):
+                step = step.item()
+            if isinstance(sigma, torch.Tensor):
+                sigma = sigma.item()
+            if isinstance(num_inference_steps, torch.Tensor):
+                num_inference_steps = num_inference_steps.item()
+            if step is None or sigma is None or num_inference_steps is None:
+                raise ValueError("scheduler metadata is unavailable")
+            step = int(step)
+            sigma = float(sigma)
+            num_inference_steps = int(num_inference_steps)
+            if (
+                step < 0
+                or num_inference_steps <= 0
+                or step >= num_inference_steps
+                or not math.isfinite(sigma)
+                or not 0.0 <= sigma <= 1.0
+            ):
+                raise ValueError("expected a valid step index and exact sigma in [0, 1]")
+        except (IndexError, TypeError, ValueError, RuntimeError) as error:
+            self._warn_once(f"SeaCache metadata is invalid; running full: {error}")
+            return self._run_uncached(ctx)
+
+        if conditioning_only:
+            self._warn_once("SeaCache requires noisy vision; conditioning-only calls run in full.")
+            return self._run_uncached(ctx)
+
+        state: SeaCacheState = self.state_manager.get_state()
+        try:
+            indicator = self._build_indicator(vision_items, sigma)
+        except (TypeError, ValueError, RuntimeError) as error:
+            self._warn_once(f"SeaCache could not construct its vision indicator; running full: {error}")
+            indicator = None
+
+        local_compute = self._resolve_gate(state, indicator, step, num_inference_steps)
+        should_compute = self._synchronize_compute(local_compute, ctx.hidden_states.device)
+        if should_compute and not local_compute:
+            state.accumulated_distance = 0.0
+
+        if should_compute:
+            self.full_count += 1
+            output = self._run_full_stack(ctx)
+            result = ctx.postprocess(output)
+            self._record_execution(state, step, ctx.hidden_states, output)
+            return result
+
+        residual = extrapolate_residual(
+            state.history,
+            step,
+            self.config.residual_order,
+        )
+        if residual.device != ctx.hidden_states.device:
+            residual = residual.to(ctx.hidden_states.device)
+        state.consecutive_cached += 1
+        self.skip_count += 1
+
+        can_reuse = (
+            residual.shape == ctx.hidden_states.shape
+            and residual.device == ctx.hidden_states.device
+            and residual.dtype == ctx.hidden_states.dtype
+        )
+        if can_reuse:
+            return ctx.postprocess(ctx.hidden_states + residual)
+
+        output = self._run_full_stack(ctx)
+        result = ctx.postprocess(output)
+        self._record_execution(state, step, ctx.hidden_states, output)
+        return result
+
+    @staticmethod
+    def _run_full_stack(ctx: CacheContext) -> torch.Tensor:
+        outputs = ctx.run_transformer_blocks()
+        if not outputs:
+            raise RuntimeError("Cache extractor returned no transformer outputs")
+        return outputs[0]
+
+    @staticmethod
+    def _run_uncached(ctx: CacheContext) -> Any:
+        return ctx.postprocess(SeaCacheRootHook._run_full_stack(ctx))
+
+    def _record_execution(
+        self,
+        state: SeaCacheState,
+        step: int,
+        execution_input: torch.Tensor,
+        output: torch.Tensor,
+    ) -> None:
+        if (
+            output.shape == execution_input.shape
+            and output.device == execution_input.device
+            and output.dtype == execution_input.dtype
+        ):
+            state.history.append((step, (output - execution_input).detach().clone()))
+            state.history = state.history[-(self.config.residual_order + 1) :]
+            state.consecutive_cached = 0
+            return
+
+        state.history.clear()
+        state.accumulated_distance = 0.0
+        self._warn_once("SeaCache execution boundary returned an incompatible tensor; clearing cache history.")
+
+    def reset_state(self, module: torch.nn.Module) -> torch.nn.Module:
+        self.state_manager.reset()
+        self.full_count = 0
+        self.skip_count = 0
+        return module
+
+    def refresh(self, module: torch.nn.Module) -> None:
+        self.reset_state(module)
+
+
+def apply_sea_cache_hook(
+    module: torch.nn.Module,
+    config: SeaCacheConfig,
+    *,
+    current_step_callback: Callable[[], int | torch.Tensor | None] | None = None,
+    current_sigma_callback: Callable[[], float | torch.Tensor | None] | None = None,
+    num_inference_steps_callback: Callable[[], int | torch.Tensor | None] | None = None,
+    extractor_fn: Callable[..., CacheContext] | None = None,
+) -> SeaCacheRootHook:
+    registry = HookRegistry.get_or_create(module)
+    hook = SeaCacheRootHook(
+        config,
+        current_step_callback=current_step_callback,
+        current_sigma_callback=current_sigma_callback,
+        num_inference_steps_callback=num_inference_steps_callback,
+        extractor_fn=extractor_fn,
+    )
+    registry.register_hook(SeaCacheRootHook._HOOK_NAME, hook)
+    return hook
diff --git a/vllm_omni/diffusion/cache/seacache/sea_filter.py b/vllm_omni/diffusion/cache/seacache/sea_filter.py
new file mode 100644
index 00000000000..f68b5c28886
--- /dev/null
+++ b/vllm_omni/diffusion/cache/seacache/sea_filter.py
@@ -0,0 +1,93 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import math
+
+import torch
+
+
+# SeaCache paper: "Spectral-Evolution-Aware Cache for Accelerating Diffusion Models"
+# https://arxiv.org/abs/2602.18993
+def apply_sea_filter(hidden_states: torch.Tensor, sigma: float, power_exp: float = 3.0) -> torch.Tensor:
+    """Apply the separable SEA Wiener filter over ``(T, H, W)``."""
+    original_dtype = hidden_states.dtype
+    hidden_states = hidden_states.contiguous().float()
+    dimensions = (0, 1, 2)
+    spectrum = torch.fft.fftn(hidden_states, dim=dimensions)
+
+    sigma = max(1e-6, min(1.0 - 1e-6, float(sigma)))
+    signal_scale = 1.0 - sigma
+    noise_scale = sigma
+    gain: torch.Tensor | None = None
+    for axis in dimensions:
+        frequencies = torch.fft.fftfreq(
+            hidden_states.shape[axis],
+            device=hidden_states.device,
+            dtype=torch.float32,
+        )
+        clean_power = 1.0 / (frequencies.abs().pow(power_exp) + 1e-16)
+        axis_gain = signal_scale * clean_power / (signal_scale**2 * clean_power + noise_scale**2 + 1e-16)
+        axis_shape = [1] * hidden_states.ndim
+        axis_shape[axis] = axis_gain.shape[0]
+        reshaped_gain = axis_gain.reshape(axis_shape)
+        gain = reshaped_gain if gain is None else gain * reshaped_gain
+
+    assert gain is not None
+    gain = gain / gain.mean()
+    return torch.fft.ifftn(spectrum * gain, dim=dimensions).real.to(original_dtype)
+
+
+def relative_l1_distance(current: torch.Tensor, previous: torch.Tensor, eps: float = 1e-16) -> float:
+    numerator = (current.float() - previous.float()).abs().mean()
+    denominator = previous.float().abs().mean() + eps
+    return float((numerator / denominator).detach().cpu())
+
+
+def indicator_distance(
+    current: list[torch.Tensor] | None,
+    previous: list[torch.Tensor] | None,
+) -> float:
+    """Mean relative-L1 distance, or infinity for incompatible indicators."""
+    if current is None or previous is None or not current or len(current) != len(previous):
+        return float("inf")
+
+    total = 0.0
+    for current_value, previous_value in zip(current, previous, strict=True):
+        if (
+            current_value.shape != previous_value.shape
+            or current_value.device != previous_value.device
+            or current_value.dtype != previous_value.dtype
+        ):
+            return float("inf")
+        total += relative_l1_distance(current_value, previous_value)
+    distance = total / len(current)
+    return distance if math.isfinite(distance) else float("inf")
+
+
+def extrapolate_residual(
+    history: list[tuple[int, torch.Tensor]],
+    step: int,
+    order: int,
+) -> torch.Tensor:
+    """Evaluate a Newton residual polynomial at ``step``."""
+    if not history:
+        raise ValueError("SeaCache residual extrapolation requires non-empty history")
+
+    polynomial_order = max(0, min(order, len(history) - 1))
+    window = history[-(polynomial_order + 1) :]
+    steps = [history_step for history_step, _ in window]
+    coefficients = [residual.clone() for _, residual in window]
+
+    for level in range(1, polynomial_order + 1):
+        for index in range(polynomial_order, level - 1, -1):
+            denominator = steps[index] - steps[index - level]
+            if denominator == 0:
+                return window[-1][1].clone()
+            coefficients[index] = (coefficients[index] - coefficients[index - 1]) / float(denominator)
+
+    result = coefficients[polynomial_order]
+    for index in range(polynomial_order - 1, -1, -1):
+        result = result * float(step - steps[index]) + coefficients[index]
+    return result
diff --git a/vllm_omni/diffusion/cache/seacache/state.py b/vllm_omni/diffusion/cache/seacache/state.py
new file mode 100644
index 00000000000..bdf21c1f46c
--- /dev/null
+++ b/vllm_omni/diffusion/cache/seacache/state.py
@@ -0,0 +1,26 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import torch
+
+
+@dataclass(slots=True)
+class SeaCacheState:
+    """Per-cache-context trajectory state."""
+
+    last_step: int | None = None
+    accumulated_distance: float = 0.0
+    previous_indicator: list[torch.Tensor] | None = None
+    history: list[tuple[int, torch.Tensor]] = field(default_factory=list)
+    consecutive_cached: int = 0
+
+    def reset(self) -> None:
+        self.last_step = None
+        self.accumulated_distance = 0.0
+        self.previous_indicator = None
+        self.history.clear()
+        self.consecutive_cached = 0
diff --git a/vllm_omni/diffusion/cache/selector.py b/vllm_omni/diffusion/cache/selector.py
index d58bada6cef..79bb86a4c4a 100644
--- a/vllm_omni/diffusion/cache/selector.py
+++ b/vllm_omni/diffusion/cache/selector.py
@@ -1,8 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from typing import Any
 
 from vllm_omni.diffusion.cache.base import CacheBackend
 from vllm_omni.diffusion.cache.cachedit import CacheDiTBackend
 from vllm_omni.diffusion.cache.magcache import MagCacheBackend
+from vllm_omni.diffusion.cache.seacache import SeaCacheBackend
 from vllm_omni.diffusion.cache.stepcache import StepCacheBackend
 from vllm_omni.diffusion.cache.teacache import TeaCacheBackend
 from vllm_omni.diffusion.data import DiffusionCacheConfig
@@ -15,11 +19,12 @@ def get_cache_backend(cache_backend: str | None, cache_config: Any) -> CacheBack
     - cache_dit: Uses CacheDiTBackend with enable()/refresh() interface
     - tea_cache: Uses TeaCacheBackend with enable()/refresh() interface
     - mag_cache: Uses MagCacheBackend with enable()/refresh() interface
+    - sea_cache: Uses SeaCacheBackend for spectral residual caching
     - step_cache: Uses StepCacheBackend for DreamZero velocity step skip
 
     Args:
         cache_backend: Cache backend name ("cache_dit", "tea_cache",
-            "mag_cache", "step_cache", or None).
+            "mag_cache", "sea_cache", "step_cache", or None).
         cache_config: Cache configuration (dict or DiffusionCacheConfig instance).
 
     Returns:
@@ -40,10 +45,12 @@ def get_cache_backend(cache_backend: str | None, cache_config: Any) -> CacheBack
         return TeaCacheBackend(cache_config)
     elif cache_backend == "mag_cache":
         return MagCacheBackend(cache_config)
+    elif cache_backend == "sea_cache":
+        return SeaCacheBackend(cache_config)
     elif cache_backend in ("step_cache", "stepcache", "step_cache_dit"):
         return StepCacheBackend(cache_config)
     else:
         raise ValueError(
             f"Unsupported cache backend: {cache_backend}. "
-            "Supported: 'cache_dit', 'tea_cache', 'mag_cache', 'step_cache'"
+            "Supported: 'cache_dit', 'tea_cache', 'mag_cache', 'sea_cache', 'step_cache'"
         )
diff --git a/vllm_omni/diffusion/cache/teacache/extractors.py b/vllm_omni/diffusion/cache/teacache/extractors.py
index 7f0242d57ab..3aca638ec69 100644
--- a/vllm_omni/diffusion/cache/teacache/extractors.py
+++ b/vllm_omni/diffusion/cache/teacache/extractors.py
@@ -199,7 +199,7 @@ def extract_qwen_context(
     hidden_states, vid_freqs, txt_freqs = module.image_rope_prepare(hidden_states, img_shapes, txt_seq_lens)
     image_rotary_emb = (vid_freqs, txt_freqs)
 
-    timestep = timestep.to(device=hidden_states.device, dtype=hidden_states.dtype)
+    timestep = torch.as_tensor(timestep, device=hidden_states.device, dtype=hidden_states.dtype)
 
     # Call modulate_index_prepare instead of handling timestep directly.
     # For zero_cond_t=False: timestep unchanged, modulate_index=None.
@@ -618,6 +618,8 @@ def extract_flux2_klein_context(
     # ============================================================================
     dtype = hidden_states.dtype
 
+    if encoder_hidden_states is None:
+        raise ValueError("Flux2Klein requires encoder_hidden_states")
     num_txt_tokens = encoder_hidden_states.shape[1]
 
     timestep = timestep.to(dtype=dtype) * 1000
@@ -1466,6 +1468,77 @@ def postprocess(hidden: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
     )
 
 
+def extract_cosmos3_context(
+    module: nn.Module,
+    hidden_states: torch.Tensor,
+    timestep: torch.Tensor,
+    text_ids: torch.Tensor,
+    text_mask: torch.Tensor,
+    video_shape: tuple[int, int, int],
+    fps: float | None = None,
+    action_latents: torch.Tensor | None = None,
+    action_domain_ids: torch.Tensor | None = None,
+    action_noisy_mask: torch.Tensor | None = None,
+    action_start_frame_offset: int = 1,
+    action_fps: float | None = None,
+    sound_latents: torch.Tensor | None = None,
+    noisy_frame_mask: torch.Tensor | None = None,
+    control_latents: list[torch.Tensor] | tuple[torch.Tensor, ...] | torch.Tensor | None = None,
+    control_weights: list[float] | tuple[float, ...] | torch.Tensor | None = None,
+    transfer_share_vision_temporal_positions: bool = True,
+    **kwargs: Any,
+) -> CacheContext:
+    """Build the shared cache execution context for Cosmos3's GEN pathway."""
+    if kwargs:
+        raise TypeError(f"Unexpected Cosmos3 transformer kwargs: {sorted(kwargs)}")
+
+    prep = module._gen_preprocess(
+        hidden_states,
+        timestep,
+        text_ids,
+        text_mask,
+        video_shape,
+        fps=fps,
+        action_latents=action_latents,
+        action_domain_ids=action_domain_ids,
+        action_noisy_mask=action_noisy_mask,
+        action_start_frame_offset=action_start_frame_offset,
+        action_fps=action_fps,
+        sound_latents=sound_latents,
+        noisy_frame_mask=noisy_frame_mask,
+        control_latents=control_latents,
+        control_weights=control_weights,
+        transfer_share_vision_temporal_positions=transfer_share_vision_temporal_positions,
+    )
+
+    def run_transformer_blocks() -> tuple[torch.Tensor, ...]:
+        return (module._run_gen_stack(prep),)
+
+    def postprocess(hidden: torch.Tensor) -> Any:
+        return module._gen_postprocess(hidden, prep)
+
+    if control_latents is None:
+        controls: list[torch.Tensor] = []
+    elif isinstance(control_latents, torch.Tensor):
+        controls = [control_latents]
+    else:
+        controls = list(control_latents)
+
+    return CacheContext(
+        # SeaCache uses the separate inputs in extra_states for its decision.
+        modulated_input=prep.hidden_gen,
+        hidden_states=prep.hidden_gen,
+        encoder_hidden_states=None,
+        temb=prep.time_embed,
+        run_transformer_blocks=run_transformer_blocks,
+        postprocess=postprocess,
+        extra_states={
+            "sea_cache_latents": [*controls, hidden_states],
+            "sea_cache_noisy_frame_mask": noisy_frame_mask,
+        },
+    )
+
+
 # Registry for model-specific extractors
 # Key: Transformer class name
 # Value: extractor function with signature (module, *args, **kwargs) -> CacheContext
@@ -1475,6 +1548,8 @@ def postprocess(hidden: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
 EXTRACTOR_REGISTRY: dict[str, Callable] = {
     "QwenImageTransformer2DModel": extract_qwen_context,
     "Bagel": extract_bagel_context,
+    "Cosmos3EdgeVFMTransformer": extract_cosmos3_context,
+    "Cosmos3VFMTransformer": extract_cosmos3_context,
     "ZImageTransformer2DModel": extract_zimage_context,
     "Flux2Klein": extract_flux2_klein_context,
     "StableAudioDiTModel": extract_stable_audio_context,
@@ -1521,16 +1596,15 @@ def register_extractor(transformer_cls_name: str, extractor_fn: Callable) -> Non
     EXTRACTOR_REGISTRY[transformer_cls_name] = extractor_fn
 
 
-def get_extractor(transformer_cls_name: str) -> Callable:
+def get_extractor(transformer_type: str | type) -> Callable:
     """
     Get extractor function for given transformer class.
 
-    This function looks up the extractor based on the exact transformer_cls_name string,
-    which should match the transformer type in the pipeline (i.e., pipeline.transformer.__class__.__name__).
+    String lookups match an exact registered name. Type lookups also check base
+    classes so runtime wrappers such as FSDP retain the underlying model extractor.
 
     Args:
-        transformer_cls_name: Transformer class name (e.g., "QwenImageTransformer2DModel")
-                                Must exactly match a key in EXTRACTOR_REGISTRY.
+        transformer_type: Transformer class name or runtime type.
 
     Returns:
         Extractor function with signature (module, *args, **kwargs) -> CacheContext
@@ -1543,14 +1617,18 @@ def get_extractor(transformer_cls_name: str) -> Callable:
         >>> extractor = get_extractor("QwenImageTransformer2DModel")
         >>> ctx = extractor(transformer, hidden_states, encoder_hidden_states, timestep, ...)
     """
-    # Direct lookup - no substring matching
-    if transformer_cls_name in EXTRACTOR_REGISTRY:
-        return EXTRACTOR_REGISTRY[transformer_cls_name]
+    candidate_names: tuple[str, ...]
+    if isinstance(transformer_type, str):
+        candidate_names = (transformer_type,)
+    else:
+        candidate_names = tuple(candidate.__name__ for candidate in transformer_type.__mro__)
+    for candidate_name in candidate_names:
+        if candidate_name in EXTRACTOR_REGISTRY:
+            return EXTRACTOR_REGISTRY[candidate_name]
 
-    # No match found
     available_types = list(EXTRACTOR_REGISTRY.keys())
     raise ValueError(
-        f"Unknown model type: '{transformer_cls_name}'. "
+        f"Unknown model type: '{transformer_type}'. "
         f"Available types: {available_types}\n"
         f"To add support for a new model, use register_extractor() or add to EXTRACTOR_REGISTRY."
     )
diff --git a/vllm_omni/diffusion/data.py b/vllm_omni/diffusion/data.py
index 7a7de3bb1d6..c333fb11ade 100644
--- a/vllm_omni/diffusion/data.py
+++ b/vllm_omni/diffusion/data.py
@@ -541,6 +541,8 @@ class DiffusionCacheConfig:
                     scm_steps_mask_policy, scm_steps_policy
         - MagCache: mag_threshold, mag_max_skip_steps, mag_retention_ratio,
                     mag_ratios, mag_calibrate
+        - SeaCache: sea_threshold, sea_residual_order,
+                    sea_max_consecutive_cached, sea_power_exp
         - step_cache: step_cache_dit_enabled, velocity_sim_thresholds,
                           velocity_skip_countdowns, step_cache_dit_min_history
 
@@ -560,6 +562,12 @@ class DiffusionCacheConfig:
     rel_l1_thresh: float | None = None
     coefficients: list[float] | None = None  # Uses model-specific defaults if None
 
+    # SeaCache parameters [sea_cache only]
+    sea_threshold: float = 0.25
+    sea_residual_order: int = 1
+    sea_max_consecutive_cached: int = 2
+    sea_power_exp: float = 3.0
+
     # MagCache parameters [mag_cache only]
     # Default: 0.24 threshold for accumulated magnitude error
     mag_threshold: float = 0.24
diff --git a/vllm_omni/diffusion/models/cosmos3/pipeline_cosmos3.py b/vllm_omni/diffusion/models/cosmos3/pipeline_cosmos3.py
index 5977e0eeaac..04f25ac58d9 100644
--- a/vllm_omni/diffusion/models/cosmos3/pipeline_cosmos3.py
+++ b/vllm_omni/diffusion/models/cosmos3/pipeline_cosmos3.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Cosmos3 text/image/video/sound/action pipeline for vllm-omni.
 
 One pipeline class serves the Cosmos3 family modes. Output modality is selected
@@ -34,6 +34,7 @@
 import os
 import time
 from collections.abc import Iterable, Mapping
+from contextlib import nullcontext
 from dataclasses import fields
 from typing import Any, ClassVar
 
@@ -1075,6 +1076,8 @@ def __init__(
 
         self._guidance_scale = None
         self._num_timesteps = None
+        self._current_step_index = None
+        self._current_sigma = None
         self._cosmos3_branch_caches: dict[str, tuple[Any, Any]] | None = None
         self._robolab_transforms: dict[bool, Any] = {}
 
@@ -1291,17 +1294,24 @@ def predict_noise(self, **kwargs) -> torch.Tensor | tuple[torch.Tensor, ...]:
         or a tuple in video, action, sound order for multimodal generation.
         """
         cache_key = kwargs.pop("_cosmos3_cache_key", None)
-        if cache_key is None:
-            return self.transformer(**kwargs)
+        context_name = str(kwargs.pop("_cache_context", "cond"))
 
-        branch_caches = self._cosmos3_branch_caches
-        if branch_caches is None:
-            return self.transformer(**kwargs)
-
-        cache_key = str(cache_key)
-        self.transformer.cached_kv, self.transformer.cached_freqs_gen = branch_caches.get(cache_key, (None, None))
-        prediction = self.transformer(**kwargs)
-        branch_caches[cache_key] = (self.transformer.cached_kv, self.transformer.cached_freqs_gen)
+        context_factory = getattr(self, "_cache_context_factory", None)
+        context = context_factory(context_name) if callable(context_factory) else nullcontext()
+        with context:
+            if cache_key is None:
+                prediction = self.transformer(**kwargs)
+            else:
+                branch_caches = self._cosmos3_branch_caches
+                if branch_caches is None:
+                    prediction = self.transformer(**kwargs)
+                else:
+                    cache_key = str(cache_key)
+                    self.transformer.cached_kv, self.transformer.cached_freqs_gen = branch_caches.get(
+                        cache_key, (None, None)
+                    )
+                    prediction = self.transformer(**kwargs)
+                    branch_caches[cache_key] = (self.transformer.cached_kv, self.transformer.cached_freqs_gen)
         return prediction
 
     def combine_multi_branch_cfg_noise(
@@ -1840,6 +1850,29 @@ def do_classifier_free_guidance(self):
     def num_timesteps(self):
         return self._num_timesteps
 
+    @property
+    def current_step_index(self):
+        return self._current_step_index
+
+    @property
+    def current_sigma(self):
+        return self._current_sigma
+
+    def _set_denoise_step_metadata(
+        self,
+        step_index: int,
+        timesteps: torch.Tensor,
+        scheduler: Any,
+    ) -> None:
+        self._current_step_index = step_index
+        self._num_timesteps = len(timesteps)
+        sigmas = getattr(scheduler, "sigmas", None)
+        self._current_sigma = sigmas[step_index] if sigmas is not None and step_index < len(sigmas) else None
+
+    def _clear_denoise_step_metadata(self) -> None:
+        self._current_step_index = None
+        self._current_sigma = None
+
     def _set_mixed_precision_step(self, step_index: int, num_steps: int) -> None:
         setter = getattr(self.transformer, "set_mixed_precision_step", None)
         if setter is not None:
@@ -2848,6 +2881,7 @@ def _assign_step_out(step_out: torch.Tensor | tuple[torch.Tensor, ...]) -> None:
                 # else uncond), so session keying loads/stores only this rank's branch.
                 cfg_rank_is_negative = get_classifier_free_guidance_rank() != 0
                 for step_index, t in enumerate(self.progress_bar(timesteps)):
+                    self._set_denoise_step_metadata(step_index, timesteps, step_scheduler)
                     self._set_mixed_precision_step(step_index, len(timesteps))
                     timestep = t.unsqueeze(0)
                     # Outside the interval, scale=1 makes the combined output equal
@@ -2859,6 +2893,7 @@ def _assign_step_out(step_out: torch.Tensor | tuple[torch.Tensor, ...]) -> None:
                         do_true_cfg=True,
                         true_cfg_scale=step_scale,
                         positive_kwargs=dict(
+                            _cache_context="cond",
                             hidden_states=latents,
                             timestep=timestep,
                             text_ids=cond_ids,
@@ -2868,6 +2903,7 @@ def _assign_step_out(step_out: torch.Tensor | tuple[torch.Tensor, ...]) -> None:
                             **shared_kwargs,
                         ),
                         negative_kwargs=dict(
+                            _cache_context="uncond",
                             hidden_states=latents,
                             timestep=timestep,
                             text_ids=uncond_ids,
@@ -2888,13 +2924,15 @@ def _assign_step_out(step_out: torch.Tensor | tuple[torch.Tensor, ...]) -> None:
                 keep_uncond_for_cache = self._cache_requires_paired_cfg()
 
                 for step_index, t in enumerate(self.progress_bar(timesteps)):
+                    self._set_denoise_step_metadata(step_index, timesteps, step_scheduler)
                     self._set_mixed_precision_step(step_index, len(timesteps))
                     timestep = t.unsqueeze(0)
                     cfg_active = _cfg_active_at(t)
 
                     if not self._kv_load_und(kv_state, is_negative=False):
                         self.transformer.cached_kv, self.transformer.cached_freqs_gen = cond_cache
-                    noise_cond = self.transformer(
+                    noise_cond = self.predict_noise(
+                        _cache_context="cond",
                         hidden_states=latents,
                         timestep=timestep,
                         text_ids=cond_ids,
@@ -2911,7 +2949,8 @@ def _assign_step_out(step_out: torch.Tensor | tuple[torch.Tensor, ...]) -> None:
                     if cfg_active or keep_uncond_for_cache:
                         if not self._kv_load_und(kv_state, is_negative=True):
                             self.transformer.cached_kv, self.transformer.cached_freqs_gen = uncond_cache
-                        noise_uncond = self.transformer(
+                        noise_uncond = self.predict_noise(
+                            _cache_context="uncond",
                             hidden_states=latents,
                             timestep=timestep,
                             text_ids=uncond_ids,
@@ -2943,10 +2982,12 @@ def _assign_step_out(step_out: torch.Tensor | tuple[torch.Tensor, ...]) -> None:
                 # No CFG: a single cond branch per step. Bespoke (state None) keeps
                 # using the transformer-instance cache exactly as before.
                 for step_index, t in enumerate(self.progress_bar(timesteps)):
+                    self._set_denoise_step_metadata(step_index, timesteps, step_scheduler)
                     self._set_mixed_precision_step(step_index, len(timesteps))
                     timestep = t.unsqueeze(0)
                     self._kv_load_und(kv_state, is_negative=False)
-                    noise_pred = self.transformer(
+                    noise_pred = self.predict_noise(
+                        _cache_context="cond",
                         hidden_states=latents,
                         timestep=timestep,
                         text_ids=cond_ids,
@@ -2959,6 +3000,7 @@ def _assign_step_out(step_out: torch.Tensor | tuple[torch.Tensor, ...]) -> None:
                         self._kv_capture_und(kv_state, is_negative=False)
                     _assign_step_out(_step(noise_pred, t, latents, action_latents, sound_latents))
         finally:
+            self._clear_denoise_step_metadata()
             self._reset_mixed_precision()
             # Cosmos3 currently receives a unique request_id rather than a
             # reusable rollout session id. Retaining its state would only pin
@@ -3145,6 +3187,7 @@ def _active_at(t: torch.Tensor, interval: tuple[float, float] | None) -> bool:
         self._cosmos3_branch_caches = {}
         try:
             for step_index, t in enumerate(self.progress_bar(timesteps)):
+                self._set_denoise_step_metadata(step_index, timesteps, self.scheduler)
                 self._set_mixed_precision_step(step_index, len(timesteps))
                 timestep = t.unsqueeze(0)
                 step_guidance = guidance_scale if _active_at(t, guidance_interval) else 1.0
@@ -3153,6 +3196,7 @@ def _active_at(t: torch.Tensor, interval: tuple[float, float] | None) -> bool:
                 needs_control_cfg = step_control != 1.0
 
                 cond_full_kwargs = dict(
+                    _cache_context="cond",
                     hidden_states=latents,
                     timestep=timestep,
                     text_ids=cond_ids,
@@ -3166,6 +3210,7 @@ def _active_at(t: torch.Tensor, interval: tuple[float, float] | None) -> bool:
                     branches_kwargs = [
                         cond_full_kwargs,
                         dict(
+                            _cache_context="cond_no_control",
                             hidden_states=latents,
                             timestep=timestep,
                             text_ids=cond_ids,
@@ -3175,6 +3220,7 @@ def _active_at(t: torch.Tensor, interval: tuple[float, float] | None) -> bool:
                             **shared_kwargs,
                         ),
                         dict(
+                            _cache_context="uncond",
                             hidden_states=latents,
                             timestep=timestep,
                             text_ids=uncond_ids,
@@ -3200,6 +3246,7 @@ def _active_at(t: torch.Tensor, interval: tuple[float, float] | None) -> bool:
                     branches_kwargs = [
                         cond_full_kwargs,
                         dict(
+                            _cache_context="cond_no_control",
                             hidden_states=latents,
                             timestep=timestep,
                             text_ids=cond_ids,
@@ -3223,6 +3270,7 @@ def _active_at(t: torch.Tensor, interval: tuple[float, float] | None) -> bool:
                     branches_kwargs = [
                         cond_full_kwargs,
                         dict(
+                            _cache_context="uncond",
                             hidden_states=latents,
                             timestep=timestep,
                             text_ids=uncond_ids,
@@ -3257,6 +3305,7 @@ def _active_at(t: torch.Tensor, interval: tuple[float, float] | None) -> bool:
                 )[0]
                 latents = velocity_mask * latents + (1.0 - velocity_mask) * condition_latents
         finally:
+            self._clear_denoise_step_metadata()
             self._reset_mixed_precision()
             self._cosmos3_branch_caches = None
             self.transformer.reset_cache()
diff --git a/vllm_omni/diffusion/models/cosmos3/transformer_cosmos3.py b/vllm_omni/diffusion/models/cosmos3/transformer_cosmos3.py
index 1ded3db2f0d..fc5a6f7cc72 100644
--- a/vllm_omni/diffusion/models/cosmos3/transformer_cosmos3.py
+++ b/vllm_omni/diffusion/models/cosmos3/transformer_cosmos3.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Cosmos3 VFM Transformer for vllm-omni.
 
 Implements the Mixture-of-Transformers architecture with two pathways:
@@ -14,7 +14,7 @@
 import math
 from collections.abc import Iterator
 from contextlib import AbstractContextManager, contextmanager, nullcontext
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 import torch
 import torch.distributed as dist
@@ -427,7 +427,7 @@ def __init__(
         max_period: int = 10000,
     ) -> None:
         super().__init__()
-        # Following diffusers naming pattern here for checkpoint compatibility.
+        # Preserve checkpoint-compatible parameter names.
         self.linear_1 = nn.Linear(frequency_embedding_size, hidden_size, bias=True)
         self.act = nn.SiLU()
         self.linear_2 = nn.Linear(hidden_size, hidden_size, bias=True)
@@ -1105,6 +1105,28 @@ def forward(
         return hidden_gen, freqs_cos, freqs_sin
 
 
+class _GenPrepared(NamedTuple):
+    """GEN-pathway state shared by normal and cached execution."""
+
+    hidden_gen: torch.Tensor
+    time_embed: torch.Tensor
+    t: int
+    h: int
+    w: int
+    s_video: int
+    s_control: int
+    s_action: int
+    s_sound: int
+    has_control: bool
+    has_action: bool
+    has_sound: bool
+    action_domain_ids: torch.Tensor | None
+    ulysses_size: int
+    use_multi_control_attention: bool
+    multi_control_token_sizes: tuple[int, ...] | None
+    multi_control_weights: tuple[float, ...] | None
+
+
 class Cosmos3VFMTransformer(nn.Module):
     """Cosmos3 VFM Transformer: UND language model + GEN denoising layers.
 
@@ -1675,6 +1697,61 @@ def sound_latent_frames_for_sequence_parallel(
         pad = (-(base + sound_frames)) % ulysses_size
         return sound_frames + pad
 
+    def _run_gen_layers(
+        self,
+        hidden_gen: torch.Tensor,
+        *,
+        s_video: int,
+        s_control: int,
+        s_action: int,
+        s_sound: int,
+        has_action: bool,
+        has_sound: bool,
+        has_control: bool,
+        ulysses_size: int,
+        use_multi_control_attention: bool,
+        multi_control_token_sizes: tuple[int, ...] | None,
+        multi_control_weights: tuple[float, ...] | None,
+    ) -> torch.Tensor:
+        """Run the complete GEN decoder between full-layout boundaries."""
+        if self.cached_kv is None or self.cached_freqs_gen is None:
+            raise RuntimeError("Cosmos3 GEN cache was not initialized before running GEN layers.")
+        freqs_cos, freqs_sin = self.cached_freqs_gen
+        if not use_multi_control_attention:
+            hidden_gen, freqs_cos, freqs_sin = self.gen_sp_prepare(hidden_gen, freqs_cos, freqs_sin)
+        freqs_gen = (freqs_cos, freqs_sin)
+
+        if len(self.gen_layers) == len(self.cached_kv):
+            for layer, (k_und, v_und) in zip(self.gen_layers, self.cached_kv, strict=True):
+                hidden_gen = layer(
+                    hidden_gen,
+                    k_und=k_und,
+                    v_und=v_und,
+                    freqs_cos=freqs_cos,
+                    freqs_sin=freqs_sin,
+                    control_token_sizes=multi_control_token_sizes,
+                    control_weights=multi_control_weights,
+                )
+                # Cache-dit's block wrapper may return a tuple; unwrap it.
+                if isinstance(hidden_gen, tuple):
+                    hidden_gen = hidden_gen[0]
+        else:
+            # Cache-dit patches gen_layers to a grouped wrapper.
+            for layer in self.gen_layers:
+                hidden_gen = layer(
+                    hidden_gen,
+                    cached_kv=self.cached_kv,
+                    freqs_gen=freqs_gen,
+                    control_token_sizes=multi_control_token_sizes,
+                    control_weights=multi_control_weights,
+                )
+                if isinstance(hidden_gen, tuple):
+                    hidden_gen = hidden_gen[0]
+
+        if not use_multi_control_attention:
+            hidden_gen = self.gen_sp_gather(hidden_gen)
+        return hidden_gen
+
     # -- Forward -------------------------------------------------------------
 
     def forward(
@@ -1697,7 +1774,51 @@ def forward(
         transfer_share_vision_temporal_positions: bool = True,
         **kwargs,
     ) -> torch.Tensor | tuple[torch.Tensor, ...]:
+        """Run the shared Cosmos3 GEN preprocess, stack, and postprocess path."""
+        if kwargs:
+            raise TypeError(f"Unexpected Cosmos3 transformer kwargs: {sorted(kwargs)}")
+        prep = self._gen_preprocess(
+            hidden_states,
+            timestep,
+            text_ids,
+            text_mask,
+            video_shape,
+            fps=fps,
+            action_latents=action_latents,
+            action_domain_ids=action_domain_ids,
+            action_noisy_mask=action_noisy_mask,
+            action_start_frame_offset=action_start_frame_offset,
+            action_fps=action_fps,
+            sound_latents=sound_latents,
+            noisy_frame_mask=noisy_frame_mask,
+            control_latents=control_latents,
+            control_weights=control_weights,
+            transfer_share_vision_temporal_positions=transfer_share_vision_temporal_positions,
+        )
+        return self._gen_postprocess(self._run_gen_stack(prep), prep)
+
+    def _gen_preprocess(
+        self,
+        hidden_states: torch.Tensor,
+        timestep: torch.Tensor,
+        text_ids: torch.Tensor,
+        text_mask: torch.Tensor,
+        video_shape: tuple[int, int, int],
+        fps: float | None = None,
+        action_latents: torch.Tensor | None = None,
+        action_domain_ids: torch.Tensor | None = None,
+        action_noisy_mask: torch.Tensor | None = None,
+        action_start_frame_offset: int = 1,
+        action_fps: float | None = None,
+        sound_latents: torch.Tensor | None = None,
+        noisy_frame_mask: torch.Tensor | None = None,
+        control_latents: list[torch.Tensor] | tuple[torch.Tensor, ...] | torch.Tensor | None = None,
+        control_weights: list[float] | tuple[float, ...] | torch.Tensor | None = None,
+        transfer_share_vision_temporal_positions: bool = True,
+    ) -> _GenPrepared:
         """
+        Prepare the packed GEN sequence before its cacheable execution region.
+
         Args:
             hidden_states: [B, C, t, h, w] noisy latents
             timestep: [B] diffusion timestep
@@ -1720,13 +1841,9 @@ def forward(
                 transfer controls. Values are normalized to sum to one.
 
         Returns:
-            [B, C, t, h, w] velocity prediction, or
-            tuple outputs in video, action, sound order when action/sound streams
-            are provided. Transfer-control streams condition the video prediction
-            and are not returned.
+            Packed GEN inputs and metadata consumed by the shared execution and
+            postprocessing helpers.
         """
-        if kwargs:
-            raise TypeError(f"Unexpected Cosmos3 transformer kwargs: {sorted(kwargs)}")
         t, h, w = video_shape
         hp, wp, _, _ = self._pad_to_patch_size(h, w)
         text_lengths = text_mask.sum(dim=1)
@@ -1926,78 +2043,81 @@ def forward(
                 hidden_parts.append(hidden_sound)
             hidden_gen = torch.cat(hidden_parts, dim=1)
 
-            # Run GEN layers.  UND K/V (replicated) is passed to each layer;
-            # the Cosmos3CrossAttention forwards them as joint_key/value so the
-            # framework Attention handles the Ulysses head-slicing internally.
-            if self.cached_kv is None or self.cached_freqs_gen is None:
-                raise RuntimeError("Cosmos3 GEN cache was not initialized before running GEN layers.")
-            freqs_cos, freqs_sin = self.cached_freqs_gen
-            if not use_multi_control_attention:
-                hidden_gen, freqs_cos, freqs_sin = self.gen_sp_prepare(hidden_gen, freqs_cos, freqs_sin)
-            freqs_gen = (freqs_cos, freqs_sin)
-
-            if len(self.gen_layers) == len(self.cached_kv):
-                for layer, (k_und, v_und) in zip(self.gen_layers, self.cached_kv, strict=True):
-                    hidden_gen = layer(
-                        hidden_gen,
-                        k_und=k_und,
-                        v_und=v_und,
-                        freqs_cos=freqs_cos,
-                        freqs_sin=freqs_sin,
-                        control_token_sizes=multi_control_token_sizes,
-                        control_weights=multi_control_weights,
-                    )
-                    # Cache-dit's block wrapper may return a tuple; unwrap it.
-                    if isinstance(hidden_gen, tuple):
-                        hidden_gen = hidden_gen[0]
-            else:
-                # Cache-dit patches gen_layers to a grouped wrapper.
-                for layer in self.gen_layers:
-                    hidden_gen = layer(
-                        hidden_gen,
-                        cached_kv=self.cached_kv,
-                        freqs_gen=freqs_gen,
-                        control_token_sizes=multi_control_token_sizes,
-                        control_weights=multi_control_weights,
-                    )
-                    if isinstance(hidden_gen, tuple):
-                        hidden_gen = hidden_gen[0]
-
-            if not use_multi_control_attention:
-                hidden_gen = self.gen_sp_gather(hidden_gen)
-
-            # Final norm and project back to latent space
-            hidden_gen = self.norm_moe_gen(hidden_gen)
-            if not has_action and not has_sound and not has_control:
-                return self.unpatchify(self.proj_out(hidden_gen), t, h, w)
-
-            split_sizes = []
-            if has_control:
-                split_sizes.append(s_control)
-            split_sizes.append(s_video)
-            if has_action:
-                split_sizes.append(s_action)
-            if has_sound:
-                split_sizes.append(s_sound)
-            split_hidden = hidden_gen.split(split_sizes, dim=1)
-            split_idx = 0
-            if has_control:
-                split_idx += 1
-            hidden_video = split_hidden[split_idx]
+            return _GenPrepared(
+                hidden_gen=hidden_gen,
+                time_embed=time_embed,
+                t=t,
+                h=h,
+                w=w,
+                s_video=s_video,
+                s_control=s_control,
+                s_action=s_action,
+                s_sound=s_sound,
+                has_control=has_control,
+                has_action=has_action,
+                has_sound=has_sound,
+                action_domain_ids=action_domain_ids,
+                ulysses_size=ulysses_size,
+                use_multi_control_attention=use_multi_control_attention,
+                multi_control_token_sizes=multi_control_token_sizes,
+                multi_control_weights=multi_control_weights,
+            )
+
+    def _run_gen_stack(self, prep: _GenPrepared) -> torch.Tensor:
+        """Execute the cacheable full-layout GEN stack, including final norm."""
+        hidden_gen = self._run_gen_layers(
+            prep.hidden_gen,
+            s_video=prep.s_video,
+            s_control=prep.s_control,
+            s_action=prep.s_action,
+            s_sound=prep.s_sound,
+            has_action=prep.has_action,
+            has_sound=prep.has_sound,
+            has_control=prep.has_control,
+            ulysses_size=prep.ulysses_size,
+            use_multi_control_attention=prep.use_multi_control_attention,
+            multi_control_token_sizes=prep.multi_control_token_sizes,
+            multi_control_weights=prep.multi_control_weights,
+        )
+        return self.norm_moe_gen(hidden_gen)
+
+    def _gen_postprocess(
+        self,
+        hidden_gen: torch.Tensor,
+        prep: _GenPrepared,
+    ) -> torch.Tensor | tuple[torch.Tensor, ...]:
+        """Project an already-normalized packed GEN state to model outputs."""
+        if not prep.has_action and not prep.has_sound and not prep.has_control:
+            return self.unpatchify(self.proj_out(hidden_gen), prep.t, prep.h, prep.w)
+
+        split_sizes = []
+        if prep.has_control:
+            split_sizes.append(prep.s_control)
+        split_sizes.append(prep.s_video)
+        if prep.has_action:
+            split_sizes.append(prep.s_action)
+        if prep.has_sound:
+            split_sizes.append(prep.s_sound)
+        split_hidden = hidden_gen.split(split_sizes, dim=1)
+        split_idx = 0
+        if prep.has_control:
             split_idx += 1
-            video_pred = self.unpatchify(self.proj_out(hidden_video), t, h, w)
-            if has_control:
-                return video_pred
-            outputs: list[torch.Tensor] = [video_pred]
-            if has_action:
-                hidden_action = split_hidden[split_idx]
-                split_idx += 1
-                assert action_domain_ids is not None
-                outputs.append(self.unpack_action(self.action_proj_out(hidden_action, action_domain_ids)))
-            if has_sound:
-                hidden_sound = split_hidden[split_idx]
-                outputs.append(self.unpack_sound(self.audio_proj_out(hidden_sound)))
-            return tuple(outputs)
+        hidden_video = split_hidden[split_idx]
+        split_idx += 1
+        video_pred = self.unpatchify(self.proj_out(hidden_video), prep.t, prep.h, prep.w)
+        if prep.has_control:
+            return video_pred
+
+        outputs: list[torch.Tensor] = [video_pred]
+        if prep.has_action:
+            hidden_action = split_hidden[split_idx]
+            split_idx += 1
+            assert prep.action_domain_ids is not None
+            outputs.append(self.unpack_action(self.action_proj_out(hidden_action, prep.action_domain_ids)))
+        if prep.has_sound:
+            hidden_sound = split_hidden[split_idx]
+            outputs.append(self.unpack_sound(self.audio_proj_out(hidden_sound)))
+        return tuple(outputs)
 
     def post_load_weights(self) -> None:
         """Post-load processing: ensure correct dtypes."""
diff --git a/vllm_omni/diffusion/worker/diffusion_model_runner.py b/vllm_omni/diffusion/worker/diffusion_model_runner.py
index 9dfcd6f3fb2..5fb124a185b 100644
--- a/vllm_omni/diffusion/worker/diffusion_model_runner.py
+++ b/vllm_omni/diffusion/worker/diffusion_model_runner.py
@@ -25,7 +25,7 @@
 from vllm.v1.kv_cache_interface import KVCacheConfig, KVCacheSpec
 
 from vllm_omni.diffusion.attention.layer import Attention
-from vllm_omni.diffusion.cache.cachedit import cache_summary
+from vllm_omni.diffusion.cache.cachedit import CacheDiTBackend, cache_summary
 from vllm_omni.diffusion.cache.prompt_embed_cache import (
     install_prompt_embed_cache,
     resolve_prompt_embed_cache_config,
@@ -409,7 +409,7 @@ def get_memory_context() -> AbstractContextManager[Any]:
                 # may explicitly adopt the enabled Cache-DiT backend and then
                 # own all later request-boundary enable/disable transitions.
                 self.cache_backend.enable(self.pipeline)
-                if str(self.od_config.cache_backend).lower() == "cache_dit" and adopt_request_scoped_cache_dit(
+                if isinstance(self.cache_backend, CacheDiTBackend) and adopt_request_scoped_cache_dit(
                     self.pipeline,
                     self.cache_backend,
                 ):
@@ -663,12 +663,13 @@ def _refresh_cache_for_requests(
             num_inference_steps = getattr(self.pipeline, "default_num_inference_steps", None)
         if num_inference_steps is None and od_config.cache_backend in (
             "tea_cache",
+            "sea_cache",
             "step_cache",
         ):
             # When num_inference_steps is None, some pipelines defer to their
-            # own defaults. TeaCache refresh ignores this value; step_cache
-            # refresh is a no-op because per-chunk state resets in the denoise
-            # loop. Use the pipeline default when available to keep refresh
+            # own defaults. These backends use refresh to reset request state;
+            # runtime step metadata is either unused or resolved in the
+            # pipeline. Use the pipeline default when available to keep refresh
             # behavior aligned with single-request execution.
             num_inference_steps = getattr(self.pipeline, "num_inference_steps", 0) or 0
 
@@ -1046,6 +1047,8 @@ def _prepare_batch_inputs(
         new_request_ids: list[str],
     ) -> tuple[list[StepRequestState], InputBatch | None, list[RunnerOutput]]:
         # process new reqs
+        pipeline = self.pipeline
+        assert pipeline is not None, "Model not loaded. Call load_model() first."
         prepared_states: list[StepRequestState] = []
         error_outputs: list[RunnerOutput] = []
         for state in states:
@@ -1058,12 +1061,12 @@ def _prepare_batch_inputs(
                 per_req_exc: BaseException | None = None
                 try:
                     self._initialize_generator(state.sampling)
-                    clear_pipeline_stage_durations(self.pipeline)
+                    clear_pipeline_stage_durations(pipeline)
                     # encode
-                    self.pipeline.prepare_encode(state)
+                    pipeline.prepare_encode(state)
                     merge_stage_durations(
                         state,
-                        consume_pipeline_stage_durations(self.pipeline),
+                        consume_pipeline_stage_durations(pipeline),
                     )
                 except Exception as exc:
                     per_req_exc = exc
@@ -1247,6 +1250,8 @@ def _execute_stepwise_core(
         use_hsdp = self.od_config.parallel_config.use_hsdp
         grad_context = torch.no_grad() if use_hsdp else torch.inference_mode()
         with grad_context:
+            pipeline = self.pipeline
+            assert pipeline is not None, "Model not loaded. Call load_model() first."
             had_active_states = bool(self.state_cache)
             states, new_request_ids = self._update_states(scheduler_output)
             is_primary = not torch.distributed.is_initialized() or torch.distributed.get_rank() == 0
@@ -1261,7 +1266,7 @@ def _execute_stepwise_core(
             states, input_batch, runner_output_list = self._prepare_batch_inputs(states, new_request_ids)
             if input_batch is None:
                 return BatchRunnerOutput.from_list(runner_output_list)
-            attn_metadata = {}
+            attn_metadata: dict[str, Any] = {}
 
             kv_backend = getattr(self, "diffusion_kv_backend", None)
             paged_kv_runtime = kv_backend if getattr(kv_backend, "paged_attention_adapter", None) is not None else None
@@ -1272,16 +1277,16 @@ def _execute_stepwise_core(
                 paged_kv_runtime=paged_kv_runtime,
                 in_diffusion_kv_memory_profile=in_diffusion_kv_memory_profile,
             ):
-                clear_pipeline_stage_durations(self.pipeline)
-                noise_pred = self.pipeline.denoise_step(input_batch, states=states)
-                denoise_stage_durations = consume_pipeline_stage_durations(self.pipeline)
+                clear_pipeline_stage_durations(pipeline)
+                noise_pred = pipeline.denoise_step(input_batch, states=states)
+                denoise_stage_durations = consume_pipeline_stage_durations(pipeline)
                 for state in states:
                     merge_stage_durations(
                         state,
                         denoise_stage_durations,
                     )
 
-                pipeline_interrupted = getattr(self.pipeline, "interrupt", False)
+                pipeline_interrupted = getattr(pipeline, "interrupt", False)
                 if noise_pred is None and pipeline_interrupted:
                     for state in states:
                         runner_output_list.append(
@@ -1296,9 +1301,11 @@ def _execute_stepwise_core(
                 else:
                     offset = 0
                     for req in states:
+                        if req.latents is None:
+                            raise RuntimeError(f"Stepwise request {req.request_id} has no latent state.")
                         row_num = req.latents.shape[0]
                         try:
-                            self.pipeline.step_scheduler(
+                            pipeline.step_scheduler(
                                 req, noise_pred[offset : offset + row_num] if noise_pred is not None else None
                             )
                             if self.od_config.streaming_output:
@@ -1307,8 +1314,8 @@ def _execute_stepwise_core(
                                 should_decode = req.denoise_completed
 
                             if should_decode:
-                                clear_pipeline_stage_durations(self.pipeline)
-                                result = self.pipeline.post_decode(req)
+                                clear_pipeline_stage_durations(pipeline)
+                                result = pipeline.post_decode(req)
                                 if result is not None:
                                     result = self._prepare_output_for_transport(result, req.sampling)
                                     self._attach_stepwise_metadata(
@@ -1317,8 +1324,8 @@ def _execute_stepwise_core(
                                     )
                                     # After consuming this chunk's interaction metadata, apply pending interactions and
                                     # prepare the next chunk (prepare_next_chunk may be a no-op---depending on pipeline)
-                                    if supports_interaction_apply(self.pipeline) and not req.request_denoise_completed:
-                                        pipe = cast(SupportsInteractionApply, self.pipeline)
+                                    if supports_interaction_apply(pipeline) and not req.request_denoise_completed:
+                                        pipe = cast(SupportsInteractionApply, pipeline)
                                         pipe.apply_interaction_at_chunk_boundary(req)
                                         pipe.prepare_next_chunk(req)
                             else:
@@ -1370,12 +1377,12 @@ def _execute_stepwise_core(
                     for runner_output in runner_output_list:
                         if runner_output.result is None:
                             continue
-                        state = states_by_id.get(runner_output.request_id)
-                        if state is None:
+                        matched_state = states_by_id.get(runner_output.request_id)
+                        if matched_state is None:
                             continue
                         runner_output.result.peak_memory_mb = max(
                             runner_output.result.peak_memory_mb,
-                            state.peak_memory_mb,
+                            matched_state.peak_memory_mb,
                         )
 
                 terminal_request_ids = [
diff --git a/vllm_omni/entrypoints/cli/serve.py b/vllm_omni/entrypoints/cli/serve.py
index 0166cb4c1a9..bc7f81132a7 100644
--- a/vllm_omni/entrypoints/cli/serve.py
+++ b/vllm_omni/entrypoints/cli/serve.py
@@ -712,7 +712,10 @@ def subparser_init(self, subparsers: argparse._SubParsersAction) -> TrackingArgu
             "--cache-backend",
             type=str,
             default="none",
-            help="Cache backend for diffusion models, options: 'tea_cache', 'cache_dit', 'mag_cache', 'step_cache'",
+            help=(
+                "Cache backend for diffusion models, options: 'tea_cache', "
+                "'cache_dit', 'mag_cache', 'sea_cache', 'step_cache'"
+            ),
         )
         omni_config_group.add_argument(
             "--cache-config",

From bbf77cce69bff7dfd43234e938f1b8149e2a4359 Mon Sep 17 00:00:00 2001
From: andyluo7 <43718156+andyluo7@users.noreply.github.com>
Date: Tue, 15 Sep 2026 16:25:56 -0700
Subject: [PATCH 009/105] [CI][ROCm] Add non-blocking entrypoint GPU coverage
 (#7398)

Signed-off-by: andyluo7 <andy.luo@amd.com>
---
 .buildkite/amd/test-amd-ready.yml | 65 +++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/.buildkite/amd/test-amd-ready.yml b/.buildkite/amd/test-amd-ready.yml
index 181a451bbba..505ed1b8723 100644
--- a/.buildkite/amd/test-amd-ready.yml
+++ b/.buildkite/amd/test-amd-ready.yml
@@ -205,6 +205,71 @@ steps:
               pytest -s -v tests/engine/test_async_omni_engine_abort.py
       '
 
+- label: "ROCm · Entrypoints GPU Coverage (R2-02)"
+  agent_pool: mi300_1
+  depends_on: amd-build
+  mirror_hardwares: [amdproduction]
+  grade: NonBlocking
+  timeout_in_minutes: 30
+  env:
+    VLLM_WORKER_MULTIPROC_METHOD: spawn
+  artifact_paths:
+    - "artifacts/rocm-r2-02/**/*"
+  commands:
+    # Native AMD tests run from /app/vllm-omni, while Buildkite uploads
+    # artifacts relative to its checkout directory.
+    - export R2_02_ARTIFACT_DIR="$$BUILDKITE_BUILD_CHECKOUT_PATH/artifacts/rocm-r2-02"
+    - mkdir -p "$$R2_02_ARTIFACT_DIR"
+    - >-
+      ps -eo pid=,ppid=,lstart=,stat=,comm= >
+      "$$R2_02_ARTIFACT_DIR/processes-before.txt"
+    # Verbose pytest output and JUnit retain selected node IDs without a
+    # second collection-only pass over the same GPU-backed test tree.
+    # The inner timeout leaves five minutes for teardown verification and
+    # artifact generation before the Buildkite step timeout.
+    - >-
+      timeout --signal=TERM --kill-after=1m 25m
+      pytest -s -v -ra
+      tests/entrypoints/
+      -m 'core_model and cuda and not
+      (cards_2 or cards_3 or cards_4 or cards_5 or cards_6 or cards_7 or cards_8)'
+      --run-level "core_model"
+      --durations=0
+      --junitxml="$$R2_02_ARTIFACT_DIR/pytest.xml"
+      2>&1 | tee "$$R2_02_ARTIFACT_DIR/pytest.log"
+    - >-
+      tail -n 100 "$$R2_02_ARTIFACT_DIR/pytest.log" >
+      "$$R2_02_ARTIFACT_DIR/pytest-summary.txt"
+    - |
+      sleep 5
+      ps -eo pid=,ppid=,lstart=,stat=,comm= > "$$R2_02_ARTIFACT_DIR/processes-after.txt"
+      # Compare PID plus process start time so PID reuse cannot hide a leak.
+      # Double dollars preserve awk field references through Buildkite interpolation.
+      awk '
+        NR == FNR {
+          if ($$9 != "ps") {
+            baseline[$$1 "|" $$3 "|" $$4 "|" $$5 "|" $$6 "|" $$7] = 1
+          }
+          next
+        }
+        $$9 != "ps" {
+          identity = $$1 "|" $$3 "|" $$4 "|" $$5 "|" $$6 "|" $$7
+          if (!(identity in baseline)) {
+            print
+            leaked = 1
+          }
+        }
+        END {
+          if (leaked) {
+            print "status=FAIL leaked_processes_detected=1"
+            exit 1
+          }
+          print "status=PASS leaked_processes=0"
+        }
+      ' "$$R2_02_ARTIFACT_DIR/processes-before.txt" \
+        "$$R2_02_ARTIFACT_DIR/processes-after.txt" \
+        2>&1 | tee "$$R2_02_ARTIFACT_DIR/process-cleanup.txt"
+
 # - label: "Omni Model Test Qwen3-Omni"
 #   agent_pool: mi300_2
 #   depends_on: amd-build

From 65693b30fb52da47f1ce9129508e9cd524c86513 Mon Sep 17 00:00:00 2001
From: LOGO127 <luozijian0924@gmail.com>
Date: Wed, 16 Sep 2026 07:50:32 +0800
Subject: [PATCH 010/105] [Bugfix][Core] Keep sample-rate snapshots bounded in
 delta output (#7448)

Signed-off-by: luozijian <luozijian0924@gmail.com>
---
 .../engine/test_output_metadata_snapshots.py  | 143 ++++++++++++++++++
 vllm_omni/outputs/mm_outputs.py               |  17 ++-
 2 files changed, 157 insertions(+), 3 deletions(-)
 create mode 100644 tests/engine/test_output_metadata_snapshots.py

diff --git a/tests/engine/test_output_metadata_snapshots.py b/tests/engine/test_output_metadata_snapshots.py
new file mode 100644
index 00000000000..688f1252d6d
--- /dev/null
+++ b/tests/engine/test_output_metadata_snapshots.py
@@ -0,0 +1,143 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Snapshot metadata must not accumulate as if it were generated content."""
+
+import pytest
+import torch
+from vllm.outputs import PoolingRequestOutput
+from vllm.sampling_params import RequestOutputKind
+from vllm.v1.engine import FinishReason
+
+from vllm_omni.outputs.mm_outputs import MultimodalPayload
+from vllm_omni.outputs.output_modality import OutputModality, TensorAccumulationStrategy
+from vllm_omni.outputs.output_processor import MultimodalOutputProcessor, OmniRequestState
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+RATE_KEYS = ("sr", "sample_rate", "audio_sample_rate")
+
+
+def _state(kind: RequestOutputKind) -> OmniRequestState:
+    return OmniRequestState(
+        request_id="audio",
+        external_req_id="audio",
+        parent_req=None,
+        request_index=0,
+        lora_request=None,
+        prompt=None,
+        prompt_token_ids=[0],
+        prompt_embeds=None,
+        logprobs_processor=None,
+        detokenizer=None,
+        max_tokens_param=None,
+        arrival_time=0.0,
+        queue=None,
+        log_stats=False,
+        stream_interval=1,
+        output_kind=kind,
+    )
+
+
+@pytest.mark.parametrize("key", RATE_KEYS)
+@pytest.mark.parametrize("representation", ["integer", "scalar_tensor", "vector_tensor", "metadata_tensor"])
+def test_rate_is_latest_snapshot_before_consolidation(key, representation):
+    payload = MultimodalPayload()
+    for index, rate in enumerate((16000, 24000, 48000)):
+        value = (
+            rate if representation == "integer" else torch.tensor([rate] if representation == "vector_tensor" else rate)
+        )
+        incoming = (
+            MultimodalPayload(tensors={"audio": torch.full((2,), index)}, metadata={key: value})
+            if representation == "metadata_tensor"
+            else MultimodalPayload.from_dict({"audio": torch.full((2,), index), key: value})
+        )
+        assert incoming is not None
+        payload = payload.merged_with(incoming)
+        snapshot = payload[key]
+        assert not isinstance(snapshot, list)
+        assert int(snapshot) == rate
+        assert payload.get(key) is payload.to_dict()[key]
+    payload = payload.merged_with(MultimodalPayload(tensors={"audio": torch.full((2,), 3)}))
+    assert int(payload[key]) == 48000  # Missing metadata means retain, not clear.
+    payload.consolidate_tensors(TensorAccumulationStrategy.CONCAT_LAST)
+    payload.consolidate_metadata()
+    torch.testing.assert_close(payload["audio"], torch.arange(4).repeat_interleave(2))
+
+
+@pytest.mark.parametrize("key", RATE_KEYS)
+@pytest.mark.parametrize("tensor_first", [False, True])
+def test_rate_representation_change_removes_stale_partition(key, tensor_first):
+    first = torch.tensor(16000) if tensor_first else 16000
+    last = 24000 if tensor_first else torch.tensor(24000)
+    payload = MultimodalPayload.from_dict({key: first})
+    incoming = MultimodalPayload.from_dict({key: last})
+    assert payload is not None and incoming is not None
+    incoming_keys = (set(incoming.tensors), set(incoming.metadata))
+    payload = payload.merged_with(incoming)
+    assert int(payload[key]) == 24000
+    assert payload[key] is payload.to_dict()[key]
+    assert (key in payload.tensors) != (key in payload.metadata)
+    assert incoming[key] is last
+    assert incoming_keys == (set(incoming.tensors), set(incoming.metadata))
+
+
+@pytest.mark.parametrize("key", RATE_KEYS)
+def test_self_merge_retains_snapshot_and_content(key):
+    payload = MultimodalPayload.from_dict({key: torch.tensor(24000), "audio": torch.tensor([1.0, 2.0])})
+    assert payload is not None
+    payload = payload.merged_with(payload)
+    assert int(payload[key]) == 24000
+    payload.consolidate_tensors(TensorAccumulationStrategy.CONCAT_LAST)
+    torch.testing.assert_close(payload["audio"], torch.tensor([1.0, 2.0, 1.0, 2.0]))
+
+
+@pytest.mark.parametrize("key", RATE_KEYS)
+@pytest.mark.parametrize("kind", [RequestOutputKind.DELTA, RequestOutputKind.CUMULATIVE])
+def test_long_stream_keeps_rate_bounded_without_losing_audio(key, kind):
+    state = _state(kind)
+    for index in range(1000):
+        state.add_multimodal_tensor(
+            {"model_outputs": torch.full((3,), index / 1000), key: torch.tensor(24000)}, "audio"
+        )
+        output = state.make_request_output([], None, None, None)
+        assert output is not None and not isinstance(output, PoolingRequestOutput)
+        payload = output.outputs[0].multimodal_output
+        assert isinstance(payload[key], torch.Tensor) and payload[key].numel() == 1
+        audio = payload["audio"]
+        assert audio.numel() == (3 if kind == RequestOutputKind.DELTA else 3 * (index + 1))
+        torch.testing.assert_close(audio[-3:], torch.full((3,), index / 1000))
+        assert ("audio" in state.mm_accumulated) is (kind == RequestOutputKind.CUMULATIVE)
+    final = state.make_request_output([], None, FinishReason.STOP, None)
+    assert final is not None and final.finished
+    if kind == RequestOutputKind.DELTA:
+        assert "audio" not in final.outputs[0].multimodal_output
+
+
+@pytest.mark.parametrize("pending", [0, 3])
+def test_abort_flushes_only_pending_content_with_latest_rate(pending):
+    state = _state(RequestOutputKind.DELTA)
+    processor = MultimodalOutputProcessor(tokenizer=None, log_stats=False, output_modality=OutputModality.AUDIO)
+    processor.request_states[state.request_id] = state
+    processor.external_req_ids[state.external_req_id] = [state.request_id]
+    for rate in (16000, 24000):
+        state.add_multimodal_tensor({"model_outputs": torch.ones(3), "sr": torch.tensor(rate)}, "audio")
+        output = state.make_request_output([], None, None, None)
+        assert output is not None
+    if pending:
+        state.add_multimodal_tensor({"model_outputs": torch.ones(pending)}, "audio")
+    aborted, outputs = processor.abort_requests_collecting_outputs([state.request_id], internal=True)
+    assert aborted == [state.request_id] and len(outputs) == 1 and outputs[0].finished
+    payload = outputs[0].outputs[0].multimodal_output
+    assert int(payload["sr"]) == 24000
+    assert (payload["audio"].numel() if "audio" in payload else 0) == pending
+    assert state.request_id not in processor.request_states
+
+
+def test_non_snapshot_tensors_still_accumulate_and_empty_merge_keeps_identity():
+    first = MultimodalPayload.from_dict({"latent": torch.tensor([1.0]), "audio": torch.tensor([2.0])})
+    second = MultimodalPayload.from_dict({"latent": torch.tensor([3.0]), "audio": torch.tensor([4.0])})
+    assert first is not None and second is not None
+    assert MultimodalPayload().merged_with(first) is first
+    merged = first.merged_with(second)
+    merged.consolidate_tensors(TensorAccumulationStrategy.CONCAT_LAST)
+    torch.testing.assert_close(merged["latent"], torch.tensor([1.0, 3.0]))
+    torch.testing.assert_close(merged["audio"], torch.tensor([2.0, 4.0]))
diff --git a/vllm_omni/outputs/mm_outputs.py b/vllm_omni/outputs/mm_outputs.py
index 8c5fe6442b6..b1393ba1924 100644
--- a/vllm_omni/outputs/mm_outputs.py
+++ b/vllm_omni/outputs/mm_outputs.py
@@ -1,3 +1,5 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Multimodal output data structures for vLLM-Omni.
 
 This module defines structured types for multimodal outputs.
@@ -113,7 +115,7 @@ def get(self, key: str, default: Any = None) -> Any:
             return self.tensors[key]
         return self.metadata.get(key, default)
 
-    def __contains__(self, key: str) -> bool:
+    def __contains__(self, key: object) -> bool:
         return key in self.tensors or key in self.metadata
 
     def __getitem__(self, key: str) -> Any:
@@ -145,15 +147,24 @@ def __eq__(self, other: object) -> bool:
     def merged_with(self, incoming: MultimodalPayload) -> MultimodalPayload:
         """Merge *incoming* onto this payload and return the result.
 
-        Tensor values accumulate into lists for deferred concatenation;
-        non-tensor values are replaced with the latest. When this payload
+        Content tensors accumulate into lists for deferred concatenation;
+        known sample-rate keys are snapshots replaced immediately, including
+        in DELTA streams that do not consolidate each emission. Missing keys
+        retain their previous value. Other values keep the existing merge
+        behavior. When this payload
         is empty, *incoming* is returned as-is, so callers should use the
         return value: ``accumulated = accumulated.merged_with(incoming)``.
         """
         if self.is_empty:
             return incoming
+        # Capture before merging: incoming may be this payload. Store these
+        # snapshots in only one partition even if their representation changes.
+        snapshots = {key: incoming[key] for key in _METADATA_TENSOR_KEYS if key in incoming}
         _append_entries(self.tensors, incoming.tensors)
         _append_entries(self.metadata, incoming.metadata)
+        for key, value in snapshots.items():
+            self.tensors.pop(key, None)
+            self.metadata[key] = value
         return self
 
     def consolidate_tensors(self, strategy: TensorAccumulationStrategy) -> None:

From f420cfcfbf5d7dff2ed471305e0ef145dc32f956 Mon Sep 17 00:00:00 2001
From: ChangXiong Deng <101780062+peterDengcx@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:06:41 +0800
Subject: [PATCH 011/105] [NPU][CosyVoice3] Add CPU STFT fallback (#7520)

Signed-off-by: dengchangxiong <dengchangxiong1@huawei.com>
Co-authored-by: dengchangxiong <dengchangxiong1@huawei.com>
---
 .../cosyvoice3/test_cosyvoice3_components.py  | 68 +++++++++++++++++++
 .../cosyvoice3/code2wav_core/hifigan.py       | 42 ++++++++++--
 2 files changed, 106 insertions(+), 4 deletions(-)

diff --git a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
index 1b1df636728..7dfbe6e741f 100644
--- a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
+++ b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
@@ -76,6 +76,74 @@ def test_causal_hift_stft_moves_window_to_input_device(causal_hift):
     assert causal_hift.stft_window.device == waveform.device
 
 
+def test_causal_hift_routes_npu_transforms_to_cpu_fallback(causal_hift, monkeypatch):
+    class NpuTensor:
+        device = SimpleNamespace(type="npu")
+
+    tensor = NpuTensor()
+    stft_calls = []
+    istft_calls = []
+    monkeypatch.setattr(
+        causal_hift,
+        "_stft_on_cpu",
+        lambda value: stft_calls.append(value) or ("real", "imag"),
+    )
+    monkeypatch.setattr(
+        causal_hift,
+        "_istft_on_cpu",
+        lambda magnitude, phase: istft_calls.append((magnitude, phase)) or "waveform",
+    )
+
+    assert causal_hift._stft(tensor) == ("real", "imag")
+    assert causal_hift._istft(tensor, tensor) == "waveform"
+    assert stft_calls == [tensor]
+    assert istft_calls == [(tensor, tensor)]
+
+
+def test_causal_hift_stft_cpu_fallback_uses_float32(causal_hift, monkeypatch):
+    original_stft = torch.stft
+
+    def assert_cpu_float32_stft(input, *args, window, **kwargs):
+        assert input.device.type == "cpu"
+        assert input.dtype == torch.float32
+        assert window.device.type == "cpu"
+        assert window.dtype == torch.float32
+        return original_stft(input, *args, window=window, **kwargs)
+
+    monkeypatch.setattr(torch, "stft", assert_cpu_float32_stft)
+
+    waveform = torch.randn(1, 64, dtype=torch.float64)
+    real, imag = causal_hift._stft_on_cpu(waveform)
+
+    assert real.device == waveform.device
+    assert imag.device == waveform.device
+    assert real.dtype == waveform.dtype
+    assert imag.dtype == waveform.dtype
+
+
+def test_causal_hift_istft_cpu_fallback_uses_float32(causal_hift, monkeypatch):
+    original_istft = torch.istft
+
+    def assert_cpu_complex64_istft(input, *args, window, **kwargs):
+        assert input.device.type == "cpu"
+        assert input.dtype == torch.complex64
+        assert window.device.type == "cpu"
+        assert window.dtype == torch.float32
+        return original_istft(input, *args, window=window, **kwargs)
+
+    monkeypatch.setattr(torch, "istft", assert_cpu_complex64_istft)
+
+    waveform = torch.randn(1, 64, dtype=torch.float32)
+    spec = torch.stft(waveform, 16, 4, 16, window=causal_hift.stft_window, return_complex=True)
+    magnitude = torch.abs(spec).to(torch.float64)
+    phase = torch.angle(spec).to(torch.float64)
+    reconstructed = causal_hift._istft_on_cpu(magnitude, phase)
+
+    assert reconstructed.device == magnitude.device
+    assert reconstructed.dtype == magnitude.dtype
+    torch.testing.assert_close(reconstructed, waveform.to(torch.float64), rtol=1e-5, atol=1e-5)
+
+
 class TestPreLookaheadLayer:
     """Tests for PreLookaheadLayer."""
 
diff --git a/vllm_omni/model_executor/models/cosyvoice3/code2wav_core/hifigan.py b/vllm_omni/model_executor/models/cosyvoice3/code2wav_core/hifigan.py
index 2a5d472a055..7cbd31e9ccd 100644
--- a/vllm_omni/model_executor/models/cosyvoice3/code2wav_core/hifigan.py
+++ b/vllm_omni/model_executor/models/cosyvoice3/code2wav_core/hifigan.py
@@ -489,6 +489,9 @@ def remove_weight_norm(self):
             block.remove_weight_norm()
 
     def _stft(self, x):
+        if x.device.type == "npu":
+            return self._stft_on_cpu(x)
+
         spec = torch.stft(
             x,
             self.istft_params["n_fft"],
@@ -500,18 +503,49 @@ def _stft(self, x):
         spec = torch.view_as_real(spec)  # [B, F, TT, 2]
         return spec[..., 0], spec[..., 1]
 
+    def _stft_on_cpu(self, x):
+        target_device = x.device
+        target_dtype = x.dtype
+        spec = torch.stft(
+            x.float().cpu(),
+            self.istft_params["n_fft"],
+            self.istft_params["hop_len"],
+            self.istft_params["n_fft"],
+            window=self.stft_window.float().cpu(),
+            return_complex=True,
+        )
+        spec = torch.view_as_real(spec).to(device=target_device, dtype=target_dtype)
+        return spec[..., 0], spec[..., 1]
+
     def _istft(self, magnitude, phase):
+        if magnitude.device.type == "npu":
+            return self._istft_on_cpu(magnitude, phase)
+
         magnitude = torch.clip(magnitude, max=1e2)
         real = magnitude * torch.cos(phase)
-        img = magnitude * torch.sin(phase)
-        inverse_transform = torch.istft(
-            torch.complex(real, img),
+        imag = magnitude * torch.sin(phase)
+        return torch.istft(
+            torch.complex(real, imag),
             self.istft_params["n_fft"],
             self.istft_params["hop_len"],
             self.istft_params["n_fft"],
             window=self._get_stft_window(magnitude),
         )
-        return inverse_transform
+
+    def _istft_on_cpu(self, magnitude, phase):
+        target_device = magnitude.device
+        target_dtype = magnitude.dtype
+        magnitude = torch.clip(magnitude, max=1e2)
+        real = magnitude * torch.cos(phase)
+        imag = magnitude * torch.sin(phase)
+        waveform = torch.istft(
+            torch.complex(real.float().cpu(), imag.float().cpu()),
+            self.istft_params["n_fft"],
+            self.istft_params["hop_len"],
+            self.istft_params["n_fft"],
+            window=self.stft_window.float().cpu(),
+        )
+        return waveform.to(device=target_device, dtype=target_dtype)
 
     def _get_stft_window(self, tensor: torch.Tensor) -> torch.Tensor:
         if self.stft_window.device != tensor.device:

From 5527f3f407e224dc3908098a1513cca974c62b53 Mon Sep 17 00:00:00 2001
From: Weiming Liao <liaowm5@gmail.com>
Date: Wed, 16 Sep 2026 09:07:44 +0800
Subject: [PATCH 012/105] [CI][Bugfix] Update Qwen3-TTS CI Validation Message
 (#7276)

Signed-off-by: Weiming Liao <liaowm5@gmail.com>
---
 .../qwen3_tts/batch_speech_client.py          |  5 ++-
 .../text_to_speech/qwen3_tts/gradio_demo.py   | 39 ++++++++++++-------
 .../qwen3_tts/openai_speech_client.py         |  7 +++-
 .../qwen3_tts/run_gradio_demo.sh              |  5 ++-
 .../test_invalid_audio_speech.py              | 10 +----
 5 files changed, 40 insertions(+), 26 deletions(-)

diff --git a/examples/online_serving/text_to_speech/qwen3_tts/batch_speech_client.py b/examples/online_serving/text_to_speech/qwen3_tts/batch_speech_client.py
index 47fdc3691c7..1b91905b75e 100644
--- a/examples/online_serving/text_to_speech/qwen3_tts/batch_speech_client.py
+++ b/examples/online_serving/text_to_speech/qwen3_tts/batch_speech_client.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 """Batch speech client for Qwen3-TTS via /v1/audio/speech/batch endpoint.
 
 This script demonstrates how to synthesize multiple texts in a single request.
@@ -7,7 +10,7 @@
 
 Start the server (with batch-optimized stage settings for best throughput):
 
-    vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
+    vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-Base \
         --omni \
         --trust-remote-code \
         --stage-overrides '{"0":{"max_num_seqs":4,"gpu_memory_utilization":0.2},
diff --git a/examples/online_serving/text_to_speech/qwen3_tts/gradio_demo.py b/examples/online_serving/text_to_speech/qwen3_tts/gradio_demo.py
index 3c99a82d31c..105571f384e 100644
--- a/examples/online_serving/text_to_speech/qwen3_tts/gradio_demo.py
+++ b/examples/online_serving/text_to_speech/qwen3_tts/gradio_demo.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 """Gradio demo for Qwen3-TTS with gapless streaming audio playback.
 
 Uses a custom AudioWorklet-based player for gap-free streaming,
@@ -351,7 +354,7 @@ def generate_speech(
         raise gr.Error(f"Failed to decode audio: {e}")
 
 
-def create_app(api_base: str):
+def create_app(api_base: str, task_type: str = "CustomVoice"):
     """Create the FastAPI app with streaming proxy + Gradio UI."""
     fastapi_app = FastAPI()
 
@@ -463,10 +466,11 @@ async def relay():
                     lines=4,
                 )
                 with gr.Row():
-                    task_type = gr.Radio(
+                    task_type_input = gr.Radio(
                         choices=TASK_TYPES,
-                        value="CustomVoice",
+                        value=task_type,
                         label="Task Type",
+                        interactive=False,
                         scale=2,
                     )
                     language = gr.Dropdown(
@@ -479,17 +483,21 @@ async def relay():
                     choices=voices,
                     value=voices[0] if voices else None,
                     label="speaker",
-                    visible=True,
+                    visible=task_type == "CustomVoice",
                     allow_custom_value=True,
                 )
                 instructions = gr.Textbox(
                     label="Instructions",
                     placeholder="e.g., Speak with excitement / A warm, friendly female voice",
                     lines=2,
-                    visible=True,
-                    info="Optional style/emotion instructions",
+                    visible=task_type != "Base",
+                    info=(
+                        "Required: describe the voice style"
+                        if task_type == "VoiceDesign"
+                        else "Optional style/emotion instructions"
+                    ),
                 )
-                with gr.Column(visible=False) as ref_group:
+                with gr.Column(visible=task_type == "Base") as ref_group:
                     ref_audio = gr.Audio(
                         label="Reference Audio (upload for voice cloning)",
                         type="numpy",
@@ -563,7 +571,7 @@ async def relay():
                     autoplay=True,
                     visible=False,
                 )
-                with gr.Column(visible=True) as examples_cv:
+                with gr.Column(visible=task_type == "CustomVoice") as examples_cv:
                     gr.Examples(
                         examples=[
                             [
@@ -588,7 +596,7 @@ async def relay():
                         inputs=[text_input, voice, language, instructions],
                         label="examples",
                     )
-                with gr.Column(visible=False) as examples_vd:
+                with gr.Column(visible=task_type == "VoiceDesign") as examples_vd:
                     gr.Examples(
                         examples=[
                             [
@@ -605,7 +613,7 @@ async def relay():
                         inputs=[text_input, language, instructions],
                         label="examples",
                     )
-                with gr.Column(visible=False) as examples_base:
+                with gr.Column(visible=task_type == "Base") as examples_base:
                     gr.Examples(
                         examples=[
                             [
@@ -653,9 +661,9 @@ def on_task_change(tt):
                 gr.update(visible=is_base),  # examples_base
             )
 
-        task_type.change(
+        task_type_input.change(
             fn=on_task_change,
-            inputs=[task_type],
+            inputs=[task_type_input],
             outputs=[
                 voice,
                 instructions,
@@ -703,7 +711,7 @@ def on_reset():
 
         all_inputs = [
             text_input,
-            task_type,
+            task_type_input,
             voice,
             language,
             instructions,
@@ -788,6 +796,9 @@ def parse_args():
         description="Gradio demo for Qwen3-TTS with gapless AudioWorklet streaming.",
     )
     add_common_args(parser)
+    parser.add_argument(
+        "--task-type", choices=TASK_TYPES, default="CustomVoice", help="Task matching the served checkpoint"
+    )
     return parser.parse_args()
 
 
@@ -796,7 +807,7 @@ def main():
     logging.basicConfig(level=logging.INFO)
     print(f"Connecting to vLLM server at: {args.api_base}")
 
-    app = create_app(args.api_base)
+    app = create_app(args.api_base, task_type=args.task_type)
 
     import uvicorn
 
diff --git a/examples/online_serving/text_to_speech/qwen3_tts/openai_speech_client.py b/examples/online_serving/text_to_speech/qwen3_tts/openai_speech_client.py
index 7b2fecef56f..a3f45bce8c2 100644
--- a/examples/online_serving/text_to_speech/qwen3_tts/openai_speech_client.py
+++ b/examples/online_serving/text_to_speech/qwen3_tts/openai_speech_client.py
@@ -8,25 +8,28 @@
 
 Examples:
     # CustomVoice task (predefined speaker)
-    python openai_speech_client.py --text "Hello, how are you?" --voice vivian
+    python openai_speech_client.py --text "Hello, how are you?" --speaker vivian
 
     # CustomVoice with emotion instruction
-    python openai_speech_client.py --text "I'm so happy!" --voice vivian \
+    python openai_speech_client.py --text "I'm so happy!" --speaker vivian \
         --instructions "Speak with excitement"
 
     # VoiceDesign task (voice from description)
     python openai_speech_client.py --text "Hello world" \
+        --model Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign \
         --task-type VoiceDesign \
         --instructions "A warm, friendly female voice"
 
     # Base task (voice cloning)
     python openai_speech_client.py --text "Hello world" \
+        --model Qwen/Qwen3-TTS-12Hz-1.7B-Base \
         --task-type Base \
         --ref-audio "https://example.com/reference.wav" \
         --ref-text "This is the reference transcript"
 
     # Base task with pre-computed speaker embedding
     python openai_speech_client.py --text "Hello world" \
+        --model Qwen/Qwen3-TTS-12Hz-1.7B-Base \
         --task-type Base \
         --speaker-embedding embedding.json
 """
diff --git a/examples/online_serving/text_to_speech/qwen3_tts/run_gradio_demo.sh b/examples/online_serving/text_to_speech/qwen3_tts/run_gradio_demo.sh
index d79be3c2abd..650797beba7 100644
--- a/examples/online_serving/text_to_speech/qwen3_tts/run_gradio_demo.sh
+++ b/examples/online_serving/text_to_speech/qwen3_tts/run_gradio_demo.sh
@@ -1,4 +1,7 @@
 #!/bin/bash
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 # Launch both vLLM server and Gradio demo for Qwen3-TTS
 #
 # Usage:
@@ -179,7 +182,7 @@ fi
 echo ""
 echo "Starting Gradio demo..."
 cd "$SCRIPT_DIR"
-GRADIO_CMD=("python" "gradio_demo.py" "--api-base" "$API_BASE" "--host" "$GRADIO_IP" "--port" "$GRADIO_PORT")
+GRADIO_CMD=("python" "gradio_demo.py" "--api-base" "$API_BASE" "--host" "$GRADIO_IP" "--port" "$GRADIO_PORT" "--task-type" "$TASK_TYPE")
 if [ "$GRADIO_SHARE" = true ]; then
     GRADIO_CMD+=("--share")
 fi
diff --git a/tests/dfx/reliability/invalid_param_test/test_invalid_audio_speech.py b/tests/dfx/reliability/invalid_param_test/test_invalid_audio_speech.py
index 9861b609e74..98b4184d948 100644
--- a/tests/dfx/reliability/invalid_param_test/test_invalid_audio_speech.py
+++ b/tests/dfx/reliability/invalid_param_test/test_invalid_audio_speech.py
@@ -157,14 +157,8 @@ def test_speech_missing_required_fields(omni_server: OmniServer, online_client:
                 "ref_audio": None,
                 "ref_text": None,
             },
-            # NOTE: This is delegating down the TTS adapter, so the message is both specific
-            # to the Qwen3TTS adapter and dependent on whether or not the model has any speakers
-            # (as opposed to having valida speakers, but getting an invalid speaker). it would
-            # be more ideal to validate that this is landing on `.validate()` on the adapter
-            # and ensuring that the returned message matches what we would get from calling the
-            # adapter validate directly.
-            ("no speakers configured",),
-            id="customvoice_invalid_voice",
+            ("Base checkpoint does not support task_type='CustomVoice'",),
+            id="base_checkpoint_customvoice_task_mismatch",
         ),
         pytest.param(
             {"task_type": "InvalidEnum"}, ("task_type", "literal_error", "CustomVoice"), id="task_type_invalid"

From 45a3e77351b9ef2b36612159bb0d5a3df812466b Mon Sep 17 00:00:00 2001
From: leo <92263211+liuyao0322@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:08:06 +0800
Subject: [PATCH 013/105] [Bugfix] Route Music3 float32 attention to SDPA
 (#7354)

Signed-off-by: liuyao0322 <yaoliu548926@gmail.com>
---
 .../test_minimax_music3_dit_attention.py      | 117 ++++++++++++++++++
 .../models/minimax_music3/dit.py              |  47 ++++---
 2 files changed, 150 insertions(+), 14 deletions(-)
 create mode 100644 tests/model_executor/models/test_minimax_music3_dit_attention.py

diff --git a/tests/model_executor/models/test_minimax_music3_dit_attention.py b/tests/model_executor/models/test_minimax_music3_dit_attention.py
new file mode 100644
index 00000000000..cdbb5779690
--- /dev/null
+++ b/tests/model_executor/models/test_minimax_music3_dit_attention.py
@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Attention dtype routing for MiniMax Music 3's float32 acoustic stage."""
+
+from __future__ import annotations
+
+import pytest
+import torch
+from torch import nn
+
+from vllm_omni.model_executor.models.minimax_music3 import dit
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+_FLOAT32_INCOMPATIBLE_BACKENDS = [
+    "FLASH_ATTN",
+    "FLASH_ATTN_HUB",
+    "FLASH_ATTN_3_HUB",
+    "CUDNN_ATTN",
+    "FLASHINFER_ATTN",
+]
+
+
+class _BackendType:
+    def __init__(self, name: str) -> None:
+        self.name = name
+
+    def get_name(self) -> str:
+        return self.name
+
+
+class _Backend(nn.Module):
+    def __init__(self, *, name: str, explicit: bool) -> None:
+        super().__init__()
+        self.attn_backend = _BackendType(name)
+        self.backend_explicit = explicit
+        self.calls = 0
+
+    def forward(self, q, k, v):
+        del k, v
+        self.calls += 1
+        return torch.full_like(q, 7)
+
+
+def _attention(monkeypatch, *, backend_name: str, explicit: bool):
+    backend = _Backend(name=backend_name, explicit=explicit)
+    monkeypatch.setattr(dit, "_build_native_attention", lambda **_kwargs: backend)
+    return dit.Attention(8, head_dim=4), backend
+
+
+@pytest.mark.parametrize(
+    "backend_name",
+    _FLOAT32_INCOMPATIBLE_BACKENDS,
+)
+def test_float32_uses_sdpa_for_automatic_incompatible_backend(monkeypatch, backend_name):
+    attention, backend = _attention(monkeypatch, backend_name=backend_name, explicit=False)
+    q = torch.randn(2, 5, 2, 4)
+
+    actual = attention._attend(q, q, q)
+
+    expected = torch.nn.functional.scaled_dot_product_attention(
+        q.transpose(1, 2),
+        q.transpose(1, 2),
+        q.transpose(1, 2),
+        is_causal=False,
+        scale=attention.softmax_scale,
+    ).transpose(1, 2)
+    torch.testing.assert_close(actual, expected)
+    assert backend.calls == 0
+    assert attention.backend_name == f"TORCH_SDPA(float32)/{backend_name}(lower precision)"
+
+
+@pytest.mark.parametrize("backend_name", _FLOAT32_INCOMPATIBLE_BACKENDS)
+@pytest.mark.parametrize(
+    ("dtype", "explicit"),
+    [
+        (torch.float16, False),
+        (torch.bfloat16, False),
+        (torch.float32, True),
+    ],
+)
+def test_lower_precision_or_explicit_backend_remains_authoritative(monkeypatch, backend_name, dtype, explicit):
+    attention, backend = _attention(monkeypatch, backend_name=backend_name, explicit=explicit)
+    q = torch.zeros(1, 3, 2, 4, dtype=dtype)
+
+    actual = attention._attend(q, q, q)
+
+    assert backend.calls == 1
+    torch.testing.assert_close(actual, torch.full_like(q, 7))
+
+
+def test_float32_uses_sdpa_when_native_attention_is_unavailable(monkeypatch):
+    monkeypatch.setattr(dit, "_build_native_attention", lambda **_kwargs: None)
+    attention = dit.Attention(8, head_dim=4)
+    q = torch.randn(1, 3, 2, 4)
+
+    actual = attention._attend(q, q, q)
+
+    expected = torch.nn.functional.scaled_dot_product_attention(
+        q.transpose(1, 2),
+        q.transpose(1, 2),
+        q.transpose(1, 2),
+        is_causal=False,
+        scale=attention.softmax_scale,
+    ).transpose(1, 2)
+    torch.testing.assert_close(actual, expected)
+    assert attention.backend_name == "TORCH_SDPA"
+
+
+def test_float32_keeps_compatible_automatic_backend(monkeypatch):
+    attention, backend = _attention(monkeypatch, backend_name="SDPA", explicit=False)
+    q = torch.zeros(1, 3, 2, 4)
+
+    actual = attention._attend(q, q, q)
+
+    assert backend.calls == 1
+    torch.testing.assert_close(actual, torch.full_like(q, 7))
diff --git a/vllm_omni/model_executor/models/minimax_music3/dit.py b/vllm_omni/model_executor/models/minimax_music3/dit.py
index cf180ac5221..1e7af63fce7 100644
--- a/vllm_omni/model_executor/models/minimax_music3/dit.py
+++ b/vllm_omni/model_executor/models/minimax_music3/dit.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Condition encoder and flow-matching transformer for MiniMax Music 3.
 
 Stage 1 turns the AR stage's conditioning frames into a DAC latent in two
@@ -16,13 +16,13 @@
 :func:`remap_transformer_state` performs that fusion, and is the only place
 the checkpoint's layout is reinterpreted.
 
-Attention runs through the project's own diffusion attention layer, so this
-model picks up the same backend selection, sequence-parallel plumbing and
-KV-quant policy as every other transformer in the tree. That layer resolves
-its backend from the diffusion config, which an ``LLM_GENERATION`` stage such
-as this one does not set; it tolerates that and falls through to the platform
-default. If it cannot be built at all the block runs plain SDPA instead, a
-choice made once when the blocks are built and never inside ``forward``.
+Attention uses the project's diffusion attention layer when its selected
+backend supports the runtime dtype. This ``LLM_GENERATION`` stage does not set
+a diffusion backend and therefore gets the platform default. CUDA commonly
+resolves that default to FlashAttention, cuDNN, or FlashInfer, so the model
+routes its native float32 decode through SDPA while retaining the selected
+backend for supported lower-precision inputs. An explicitly selected backend
+remains authoritative.
 """
 
 from __future__ import annotations
@@ -75,6 +75,19 @@
 # reaches exactly zero, so the noise term never fully vanishes.
 _SIGMA_FLOOR = 1e-6
 
+# These backends reject float32 Q/K/V. MiniMax Music 3 decodes in float32, so
+# automatically selected incompatible backends must not receive its attention
+# tensors. This includes cuDNN and FlashInfer selected on Blackwell. Explicit
+# backend choices retain the shared layer's fail-fast contract instead of
+# being silently replaced here.
+_FLOAT32_UNSUPPORTED_BACKENDS = {
+    "FLASH_ATTN",
+    "FLASH_ATTN_HUB",
+    "FLASH_ATTN_3_HUB",
+    "CUDNN_ATTN",
+    "FLASHINFER_ATTN",
+}
+
 
 class FourierFeatures(nn.Module):
     """Random-Fourier timestep features: ``[B, 1] -> [B, out_features]``."""
@@ -149,10 +162,7 @@ def _build_native_attention(*, num_heads: int, head_size: int, softmax_scale: fl
     except Exception as exc:  # noqa: BLE001 - any failure means: use SDPA
         _NATIVE_ATTENTION_UNAVAILABLE = repr(exc)
         logger.warning(
-            "MiniMax Music 3 DiT could not build the diffusion attention layer "
-            "(%s); running torch SDPA instead. The stage decodes in float32, "
-            "for which the diffusion layer dispatches to SDPA anyway, so this "
-            "changes performance bookkeeping and not the audio.",
+            "MiniMax Music 3 DiT could not build the diffusion attention layer (%s); running torch SDPA instead.",
             exc,
         )
         return None
@@ -180,10 +190,19 @@ def __init__(self, dim: int, *, head_dim: int, prefix: str = "") -> None:
             softmax_scale=self.softmax_scale,
             prefix=prefix,
         )
-        self.backend_name = self.backend.attn_backend.get_name() if self.backend is not None else "TORCH_SDPA"
+        native_backend_name = self.backend.attn_backend.get_name() if self.backend is not None else None
+        self._auto_float32_sdpa = (
+            self.backend is not None
+            and not getattr(self.backend, "backend_explicit", False)
+            and native_backend_name in _FLOAT32_UNSUPPORTED_BACKENDS
+        )
+        if self._auto_float32_sdpa:
+            self.backend_name = f"TORCH_SDPA(float32)/{native_backend_name}(lower precision)"
+        else:
+            self.backend_name = native_backend_name or "TORCH_SDPA"
 
     def _attend(self, q: Tensor, k: Tensor, v: Tensor) -> Tensor:
-        if self.backend is not None:
+        if self.backend is not None and not (q.dtype == torch.float32 and self._auto_float32_sdpa):
             return self.backend(q, k, v)
         q, k, v = (t.transpose(1, 2) for t in (q, k, v))
         out = F.scaled_dot_product_attention(q, k, v, is_causal=False, scale=self.softmax_scale)

From a1a234a0b439c2c00469e8c841a0286604156a8d Mon Sep 17 00:00:00 2001
From: Clodagh Walsh <42538837+clodaghwalsh17@users.noreply.github.com>
Date: Wed, 16 Sep 2026 02:26:08 +0100
Subject: [PATCH 014/105] [Voxtral] Raise BadRequest for ref_audio (#7012)

Signed-off-by: Clodagh Walsh <clodaghwalsh17@gmail.com>
---
 recipes/mistralai/Voxtral-TTS.md              |  2 +-
 .../test_voxtral_tts_expansion.py             | 21 +++++++++++++++++
 .../openai_api/test_serving_speech.py         |  2 ++
 .../openai/tts_adapters/voxtral.py            | 23 +++++++++++++++++--
 .../models/voxtral_tts/voxtral_tts.py         |  5 ++++
 .../voxtral_tts_audio_tokenizer.py            |  6 ++++-
 vllm_omni/worker/base.py                      | 13 +++++++++++
 7 files changed, 68 insertions(+), 4 deletions(-)

diff --git a/recipes/mistralai/Voxtral-TTS.md b/recipes/mistralai/Voxtral-TTS.md
index 8868ed3c333..c4eb2d12f8c 100644
--- a/recipes/mistralai/Voxtral-TTS.md
+++ b/recipes/mistralai/Voxtral-TTS.md
@@ -178,7 +178,7 @@ mistralai/Voxtral-4B-TTS-2603 checkpoint. running the
 voice-cloning e2e test ([`Voice cloning (capability gated upstream)`](../../examples/offline_inference/text_to_speech/README.md#voice-cloning-capability-gated-upstream)
 ) or adding a `ref_audio` request parameter will fail
 because the public checkpoint does not provide the encoder weights needed to
-convert reference audio into conditioning features. The expected failure is: `RuntimeError: encode_waveforms requires encoder weights which are not available in the open-source checkpoint.`
+convert reference audio into conditioning features. The expected failure is a 400 BadRequest `Voice cloning with 'ref_audio' requires the full Voxtral checkpoint with encoder weights. The open-source variant only supports preset voices via the 'voice' parameter.`.
 
 ### 1x NVIDIA RTX A6000 48GB
 
diff --git a/tests/e2e/online_serving/test_voxtral_tts_expansion.py b/tests/e2e/online_serving/test_voxtral_tts_expansion.py
index 278e563e879..40d419a9178 100644
--- a/tests/e2e/online_serving/test_voxtral_tts_expansion.py
+++ b/tests/e2e/online_serving/test_voxtral_tts_expansion.py
@@ -12,11 +12,14 @@
 os.environ.setdefault("VLLM_WORKER_MULTIPROC_METHOD", "spawn")
 
 import pytest
+from openai import BadRequestError as OpenAIBadRequestError
 
 from tests.helpers.mark import hardware_test
+from tests.helpers.media import generate_synthetic_audio
 from tests.helpers.runtime import OmniServerParams
 from tests.helpers.stage_config import get_deploy_config_path
 
+# Note this model is the public checkpoint without the encoder weights required for voice cloning
 MODEL = "mistralai/Voxtral-4B-TTS-2603"
 STAGE_CONFIG = get_deploy_config_path("voxtral_tts.yaml")
 EXTRA_ARGS = ["--trust-remote-code", "--enforce-eager", "--disable-log-stats"]
@@ -173,3 +176,21 @@ def test_speech_batches(omni_server, online_client) -> None:
             "timeout": 120.0,
         }
     )
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+def test_speech_ref_audio(omni_server, online_client) -> None:
+    """Test ref_audio failure is handled as a BadRequest instead of a RuntimeError"""
+    audio_data = f"data:audio/wav;base64,{generate_synthetic_audio(5, 1)['base64']}"
+    with pytest.raises(OpenAIBadRequestError) as exc_info:
+        online_client.send_audio_speech_request(
+            {
+                "model": omni_server.model,
+                "input": "how are you",
+                "ref_audio": audio_data,
+                "language": "English",
+                "response_format": "wav",
+            }
+        )
+
+    assert exc_info.value.status_code == 400
diff --git a/tests/entrypoints/openai_api/test_serving_speech.py b/tests/entrypoints/openai_api/test_serving_speech.py
index e7666ee3388..f910c68af0c 100644
--- a/tests/entrypoints/openai_api/test_serving_speech.py
+++ b/tests/entrypoints/openai_api/test_serving_speech.py
@@ -5133,6 +5133,7 @@ def test_voxtral_loads_supported_speakers(self, mocker: MockerFixture):
 
     def test_prepare_speech_generation_awaits_voxtral_async(self, voxtral_server, mocker: MockerFixture):
         """Voxtral path in _prepare_speech_generation should call the async wrapper."""
+        voxtral_server._adapter._encoder_loaded = mocker.AsyncMock(return_value=False)
         voxtral_server._adapter._build_prompt_async = mocker.AsyncMock(
             return_value={
                 "prompt_token_ids": [1, 2, 3],
@@ -5288,6 +5289,7 @@ def test_prepare_speech_generation_no_async_chunk_stream_keeps_delta_for_non_qwe
         """FINAL_ONLY streaming for async_chunk=False is scoped to qwen3_tts only."""
         voxtral_server.engine_client.model_config.async_chunk = False
         mocker.patch.object(voxtral_server._get_tts_adapter(), "validate", return_value=None)
+        voxtral_server._adapter._encoder_loaded = mocker.AsyncMock(return_value=False)
         voxtral_server._adapter._build_prompt_async = mocker.AsyncMock(
             return_value={
                 "prompt_token_ids": [1, 2, 3],
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/voxtral.py b/vllm_omni/entrypoints/openai/tts_adapters/voxtral.py
index f9d7639caf7..5ea82babd86 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/voxtral.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/voxtral.py
@@ -22,6 +22,7 @@ class VoxtralTTSAdapter(ARTTSAdapter):
     def __init__(self, ctx) -> None:
         super().__init__(ctx)
         self._build_prompt_async = make_async(self._build_prompt, executor=getattr(ctx.server, "_tts_executor", None))
+        self._encoder_loaded = None
 
     def _build_prompt(self, request: "OpenAICreateSpeechRequest") -> dict[str, Any]:
         """Build a Voxtral prompt for either a preset voice or inline reference audio."""
@@ -31,13 +32,24 @@ def _build_prompt(self, request: "OpenAICreateSpeechRequest") -> dict[str, Any]:
         ref_audio = request.ref_audio
         if not request.voice and not ref_audio:
             raise ValueError("Voxtral requires either a voice name or ref_audio.")
-        if isinstance(ref_audio, str) and ref_audio.startswith("data:"):
-            _, _, ref_audio = ref_audio.partition(",")
+
+        if ref_audio is not None and not self._encoder_loaded:
+            validation_error = (
+                "Voice cloning with 'ref_audio' requires the full Voxtral checkpoint "
+                "with encoder weights. The open-source variant only supports "
+                "preset voices via the 'voice' parameter."
+            )
+            raise ValueError(validation_error)
+
         server = self.ctx.server
         if server._tts_tokenizer is None:
             from vllm.tokenizers import cached_tokenizer_from_config
 
             server._tts_tokenizer = cached_tokenizer_from_config(self.ctx.engine_client.model_config).instruct
+
+        if isinstance(ref_audio, str) and ref_audio.startswith("data:"):
+            _, _, ref_audio = ref_audio.partition(",")
+
         if request.voice is not None:
             tokenized = server._tts_tokenizer.encode_speech_request(
                 SpeechRequest(input=request.input, voice=request.voice)
@@ -45,6 +57,7 @@ def _build_prompt(self, request: "OpenAICreateSpeechRequest") -> dict[str, Any]:
             prompt = tokens_input(prompt_token_ids=tokenized.tokens)
             prompt["additional_information"] = {"voice": [request.voice]}
             return prompt
+
         tokenized = server._tts_tokenizer.encode_speech_request(SpeechRequest(input=request.input, ref_audio=ref_audio))
         audio = tokenized.audios[0]
         return {
@@ -84,6 +97,12 @@ def validate(self, request: "OpenAICreateSpeechRequest") -> str | None:
     async def build(
         self, request: "OpenAICreateSpeechRequest", sampling_params_list: list, has_inline_ref_audio: bool
     ) -> PreparedRequest:
+        # Cache encoder_loaded property to avoid RPC call on every request with ref_audio
+        if self._encoder_loaded is None:
+            loaded = await self.ctx.server.engine_client.collective_rpc("encoder_loaded")
+            #  Flatten results before checking if encoder loaded property is set
+            self._encoder_loaded = any(sum(loaded, []))
+
         prompt = await self._build_prompt_async(request)
         return PreparedRequest(prompt=prompt, tts_params={}, model_type="voxtral_tts")
 
diff --git a/vllm_omni/model_executor/models/voxtral_tts/voxtral_tts.py b/vllm_omni/model_executor/models/voxtral_tts/voxtral_tts.py
index c61aeaaadbb..de79c4cbaeb 100644
--- a/vllm_omni/model_executor/models/voxtral_tts/voxtral_tts.py
+++ b/vllm_omni/model_executor/models/voxtral_tts/voxtral_tts.py
@@ -174,6 +174,11 @@ def get_language_model(self) -> "nn.Module":
             return self.model.get_language_model()
         return self.model
 
+    def encoder_loaded(self):
+        if self.audio_tokenizer is not None:
+            return self.audio_tokenizer.encoder_loaded
+        return False
+
     def _enable_acoustic_transformer_cudagraph(self):
         """Initialize and capture CUDA graphs for compute_mm_logits."""
         if self.model_stage != "audio_generation" or not hasattr(self, "_vllm_config"):
diff --git a/vllm_omni/model_executor/models/voxtral_tts/voxtral_tts_audio_tokenizer.py b/vllm_omni/model_executor/models/voxtral_tts/voxtral_tts_audio_tokenizer.py
index 9be16c0f19b..ac8e096259e 100644
--- a/vllm_omni/model_executor/models/voxtral_tts/voxtral_tts_audio_tokenizer.py
+++ b/vllm_omni/model_executor/models/voxtral_tts/voxtral_tts_audio_tokenizer.py
@@ -900,6 +900,10 @@ def codebook_sizes(self) -> list[int]:
         """List of size of each codebook"""
         return self.quantizer.codebook_sizes
 
+    @property
+    def encoder_loaded(self) -> bool:
+        return self._encoder_loaded
+
     def load_weight(self, weight: tuple[str, torch.Tensor]) -> str:
         params_dict = dict(self.named_parameters())
         name, loaded_weight = weight
@@ -985,7 +989,7 @@ def encode_tokens(self, x: list[torch.Tensor]) -> list[torch.Tensor]:
 
     def encode_waveforms(self, x: list[torch.Tensor]) -> list[torch.Tensor]:
         if not self._encoder_loaded:
-            raise RuntimeError(
+            raise ValueError(
                 "encode_waveforms requires encoder weights which are not available in the open-source checkpoint."
             )
         audio_codes = []
diff --git a/vllm_omni/worker/base.py b/vllm_omni/worker/base.py
index 2a7e9c876ac..44ec3dad588 100644
--- a/vllm_omni/worker/base.py
+++ b/vllm_omni/worker/base.py
@@ -308,3 +308,16 @@ def handle_wake_task(self, task: OmniWakeTask) -> OmniACK:
                     pass
             tid = task.task_id if hasattr(task, "task_id") else "unknown"
             return OmniACK(task_id=tid, status="ERROR", error_msg=str(e))
+
+    def encoder_loaded(self) -> bool:
+        """Check if encoder weights are loaded in the model.
+
+        This method is exposed via collective_rpc to check encoder availability
+        for models that support voice cloning with reference audio.
+
+        Returns:
+            bool: True if encoder weights are available, False otherwise.
+        """
+        if hasattr(self.model_runner, "model") and hasattr(self.model_runner.model, "encoder_loaded"):
+            return self.model_runner.model.encoder_loaded()
+        return False

From c197cd242207eaa1d3dc13622ceac8a4fc273ef5 Mon Sep 17 00:00:00 2001
From: Deep Shah <deep@socratic.co>
Date: Tue, 15 Sep 2026 18:26:43 -0700
Subject: [PATCH 015/105] [Bugfix] Fix Qwen3-Omni streaming crops in
 mixed-length batches (#7340)

Signed-off-by: Deep Shah <deep@socratic.co>
---
 .../test_qwen3_omni_code2wav_streaming.py     | 66 +++++++++++++------
 .../models/qwen3_omni/qwen3_omni_code2wav.py  | 21 +++---
 2 files changed, 53 insertions(+), 34 deletions(-)

diff --git a/tests/model_executor/models/qwen3_omni/test_qwen3_omni_code2wav_streaming.py b/tests/model_executor/models/qwen3_omni/test_qwen3_omni_code2wav_streaming.py
index 7be4f6afad7..69dd4e9ceb1 100644
--- a/tests/model_executor/models/qwen3_omni/test_qwen3_omni_code2wav_streaming.py
+++ b/tests/model_executor/models/qwen3_omni/test_qwen3_omni_code2wav_streaming.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Regression tests for ``Qwen3OmniMoeCode2Wav.chunked_decode_streaming``.
 
 Background
@@ -210,26 +210,50 @@ def test_no_shift_when_decoder_returns_nominal_length():
     torch.testing.assert_close(streamed, gt)
 
 
-def test_batched_streaming_only_shifts_the_boundary_row():
-    """Per-row tail: in a shared window the shorter row had right context from
-    the longer row's frames, so it lost nothing (tail==0, no shift); only the
-    row at the decoded boundary (code_seq_len == window length) is shifted."""
-    model = _ShortTrimDecoder()
-    # One window of W=30 frames, two rows. codes[:, 0, :] are absolute indices.
-    idx = torch.arange(30, dtype=torch.long)
-    window = idx.view(1, 1, 30).expand(2, _Q, 30).contiguous()
+@pytest.mark.parametrize("cudagraph", [False, True])
+@pytest.mark.parametrize("trim", [_TRIM, 0])
+@pytest.mark.parametrize("short_frames,left_context", [(1, 0), (4, 0), (29, 4), (26, 25), (37, 25)])
+@pytest.mark.parametrize("reverse", [False, True])
+def test_streaming_batch_matches_independent_requests(cudagraph, trim, short_frames, left_context, reverse):
+    """Padding a request beside a longer one cannot supply valid future codec frames.
 
-    long_frames, short_frames = 30, 20  # row0 spans the full window, row1 is shorter
-    lc = 5
-    out = Qwen3OmniMoeCode2Wav.chunked_decode_streaming(
+    Compare values as well as lengths: an incorrect start and end can shift
+    the whole chunk while preserving its duration. The independent request
+    is the oracle, rather than another copy of the slicing arithmetic.
+    """
+    model = _ShortTrimDecoder(trim=trim, cudagraph=cudagraph)
+    short = _make_codes(short_frames)
+    long = _make_codes(50) + 100
+    windows = [(short, left_context), (long, 25)]
+    if reverse:
+        windows.reverse()
+    batch = torch.zeros(2, _Q, 50, dtype=torch.long)
+    for i, (window, _) in enumerate(windows):
+        batch[i, :, : window.shape[-1]] = window[0]
+    actual = Qwen3OmniMoeCode2Wav.chunked_decode_streaming(
         model,
-        window,
-        left_context_size=[lc, lc],
-        seq_token_counts=[long_frames * _Q, short_frames * _Q],
+        batch,
+        left_context_size=[lc for _, lc in windows],
+        seq_token_counts=[window.numel() for window, _ in windows],
     )
-
-    batch_len = 30 * _UP - _TRIM  # actual decoder output width
-    # Row 0 (boundary row): tail == TRIM -> start = lc*up - TRIM
-    assert out[0].shape[-1] == batch_len - (lc * _UP - _TRIM)
-    # Row 1 (shorter): code_seq_len*up < batch_len -> tail == 0 -> start = lc*up
-    assert out[1].shape[-1] == short_frames * _UP - lc * _UP
+    assert len(actual) == len(windows)
+    for output, (window, lc) in zip(actual, windows):
+        expected = _decode_chunk(model, window, lc)
+        torch.testing.assert_close(output.reshape(-1), expected, rtol=0, atol=0)
+
+
+@pytest.mark.parametrize("cudagraph", [False, True])
+def test_streaming_preserves_samples_when_batch_composition_changes(cudagraph):
+    """A singleton -> mixed batch -> singleton stream cannot skip then repeat samples."""
+    model = _ShortTrimDecoder(cudagraph=cudagraph)
+    codes = _make_codes(54)
+    first = _decode_chunk(model, codes[:, :, :4], 0)
+    middle_batch = torch.zeros(2, _Q, 50, dtype=torch.long)
+    middle_batch[0, :, :29] = codes[0, :, :29]
+    middle_batch[1] = _make_codes(50)[0] + 100
+    middle = Qwen3OmniMoeCode2Wav.chunked_decode_streaming(
+        model, middle_batch, left_context_size=[4, 25], seq_token_counts=[29 * _Q, 50 * _Q]
+    )[0].reshape(-1)
+    last = _decode_chunk(model, codes[:, :, 4:54], 25)
+    streamed = torch.cat((first, middle, last))
+    torch.testing.assert_close(streamed, _single_shot(model, codes), rtol=0, atol=0)
diff --git a/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_code2wav.py b/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_code2wav.py
index 67352eecb6c..bc8f6b3b49e 100644
--- a/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_code2wav.py
+++ b/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_code2wav.py
@@ -316,21 +316,16 @@ def chunked_decode_streaming(
         else:
             # Fallback: assume all batch elements share the same sequence length.
             code_seq_lens = [codes.shape[-1]] * codes.shape[0]
+        # The decoder trims the same right-edge tail from every batch row.
+        # Infer it from the decoded window, not a shorter request's length:
+        # padding that request with codec zeros does not provide valid context.
+        tail = max(0, int(codes.shape[-1] * self.total_upsample) - batch_wav.shape[-1])
         for idx, code_seq_len in enumerate(code_seq_lens):
-            # The eager decoder (self(codes)) emits a fixed `tail` fewer samples than
-            # code_seq_len*total_upsample: the causal conv stack trims the sequence end
-            # because it lacks right context. The original slice assumed full length, so
-            # under async_chunk every streaming chunk silently dropped its last `tail`
-            # samples -> a ~23ms gap at every chunk boundary + cumulative ~1.2% time
-            # compression. Shift the start back by `tail` so this chunk refills the gap the
-            # previous chunk left (those frames are re-decoded here with proper context).
-            # `tail` is measured per call, so this is a no-op only when the decoder returns
-            # the nominal full length (tail==0, e.g. a C==0 decoder like Qwen3-TTS); for
-            # Qwen3-Omni Code2Wav both the eager forward AND the CUDA-graph wrapper
-            # (_trim_replay_output -> actual*upsample - 555) are short, so it applies to both.
-            tail = max(0, int(code_seq_len * self.total_upsample) - batch_wav.shape[-1])
+            # Refill the previous chunk's tail using the re-decoded left context,
+            # and exclude the current row's padded tail just as singleton decode does.
             start = max(0, left_context_size[idx] * self.total_upsample - tail)
-            wav_chunk = batch_wav[idx, :, start : code_seq_len * self.total_upsample]
+            end = max(0, code_seq_len * self.total_upsample - tail)
+            wav_chunk = batch_wav[idx, :, start:end]
             wavs.append(wav_chunk)
         return wavs
 

From 2185c4e26f9aded75553760bf2d29bf175a2d137 Mon Sep 17 00:00:00 2001
From: tlysanhuo <166924864+tlysanhuo@users.noreply.github.com>
Date: Wed, 16 Sep 2026 09:51:49 +0800
Subject: [PATCH 016/105] [Bugfix] Tolerate a bounded TTS tail in the
 audio-text similarity gate (#7358)

Signed-off-by: tly <2200895168@qq.com>
---
 tests/helpers/assertions.py            | 43 ++++++++++++++++++++++-
 tests/helpers/tests/test_assertions.py | 47 ++++++++++++++++++++++++++
 2 files changed, 89 insertions(+), 1 deletion(-)

diff --git a/tests/helpers/assertions.py b/tests/helpers/assertions.py
index dd25aca7187..7dc7a6ab302 100644
--- a/tests/helpers/assertions.py
+++ b/tests/helpers/assertions.py
@@ -171,6 +171,38 @@ def _short_transcript_contains_expected(transcript: str, expected: str) -> bool:
     return short_text and small_word_delta and expected_clean in transcript_clean
 
 
+_MAX_TAIL_WORDS_FLOOR = 2
+_TAIL_WORD_RATIO = 0.2
+
+
+def _transcript_has_bounded_tail(transcript: str, expected: str) -> bool:
+    """Pass when the expected text is spoken verbatim, only trailed by noise.
+
+    A short, unrelated tail after the complete expected sentence is the exact
+    case #6828's rationale anticipated: a different valid TTS sample can append
+    an audible tail even when the spoken text is identical, and Whisper can
+    hallucinate brief words on a non-speech tail. The length-penalized n-gram
+    cosine stays below the gate for such tails, so accept the match when the
+    expected text is a word-aligned prefix of the transcript and the trailing
+    words stay within the floor/ratio bounds.
+    """
+    transcript_clean = preprocess_text(transcript)
+    expected_clean = preprocess_text(expected)
+    if not transcript_clean or not expected_clean:
+        return False
+
+    transcript_words = transcript_clean.split()
+    expected_words = expected_clean.split()
+    if not transcript_words or not expected_words:
+        return False
+
+    if transcript_words[: len(expected_words)] != expected_words:
+        return False
+    tail_words = len(transcript_words) - len(expected_words)
+    max_tail_words = max(_MAX_TAIL_WORDS_FLOOR, math.ceil(_TAIL_WORD_RATIO * len(expected_words)))
+    return tail_words <= max_tail_words
+
+
 def assert_image_diffusion_response(
     response: "DiffusionResponse",
     request_config: dict[str, Any],
@@ -834,7 +866,16 @@ def assert_omni_response(response: Any, request_config: dict[str, Any], run_leve
                         text_output.lower(),
                     )
                     print(f"similarity is: {similarity}")
-                    assert similarity > similarity_threshold, AUDIO_MISMATCH_MESSAGE
+                    if similarity <= similarity_threshold and _transcript_has_bounded_tail(transcript, text_output):
+                        # The full answer is spoken verbatim and only a short
+                        # noise tail follows it; see #6828's rationale.
+                        print(
+                            "bounded-tail containment check passed: "
+                            f"text={text_output!r} is a word-aligned prefix of "
+                            f"transcript={transcript!r}"
+                        )
+                    else:
+                        assert similarity > similarity_threshold, AUDIO_MISMATCH_MESSAGE
             if audio_ref_text:
                 assert transcript is not None, "No audio transcript for reference-text validation"
                 audio_similarity = cosine_similarity_text(
diff --git a/tests/helpers/tests/test_assertions.py b/tests/helpers/tests/test_assertions.py
index 98deaa51113..e9b1a771c25 100644
--- a/tests/helpers/tests/test_assertions.py
+++ b/tests/helpers/tests/test_assertions.py
@@ -126,3 +126,50 @@ def test_escalated_transcript_keeps_declared_language(monkeypatch):
 
     assert captured["model_size"] == "large-v3"
     assert captured["language"] == "en"
+
+
+def test_bounded_tail_after_complete_answer_passes():
+    # The exact shape from the #6815 nightly failure: the full answer is spoken
+    # verbatim, then a two-word unrelated tail trips the cosine gate.
+    assert assertions._transcript_has_bounded_tail(
+        "The squares in this image are black. nack shit.",
+        "The squares in this image are black.",
+    )
+
+
+def test_bounded_tail_exact_match_passes():
+    assert assertions._transcript_has_bounded_tail(
+        "The squares in this image are black.",
+        "The squares in this image are black.",
+    )
+
+
+def test_bounded_tail_rejects_different_content():
+    assert not assertions._transcript_has_bounded_tail(
+        "The circles in this picture are black and white.",
+        "The squares in this image are black.",
+    )
+
+
+def test_bounded_tail_rejects_long_tail():
+    # Eight expected words allow at most max(2, ceil(0.2 * 8)) = 2 tail words.
+    assert not assertions._transcript_has_bounded_tail(
+        "The squares in this image are black and some extra words follow here",
+        "The squares in this image are black.",
+    )
+
+
+def test_bounded_tail_rejects_word_boundary_split():
+    assert not assertions._transcript_has_bounded_tail(
+        "The squares in this image are blacks.",
+        "The squares in this image are black.",
+    )
+
+
+def test_bounded_tail_allows_ratio_bound_for_long_answers():
+    expected = " ".join(["word"] * 20)
+    four_word_tail = expected + " one two three four"
+    five_word_tail = expected + " one two three four five"
+    # Twenty expected words allow up to max(2, ceil(0.2 * 20)) = 4 tail words.
+    assert assertions._transcript_has_bounded_tail(four_word_tail, expected)
+    assert not assertions._transcript_has_bounded_tail(five_word_tail, expected)

From 3eb5c3b4e6c9a26c5d37858bbf3f75bdb6d17bf0 Mon Sep 17 00:00:00 2001
From: HAAZZZEEEE <49724853+HAAZZZEEEE@users.noreply.github.com>
Date: Wed, 16 Sep 2026 10:06:41 +0800
Subject: [PATCH 017/105] [Bugfix][Wan2.2] Apply UniPC flow shift once (#7576)

Signed-off-by: HAAZZZEEEE <wang-taicheng@qq.com>
---
 tests/diffusion/models/wan2_2/conftest.py     |  5 +-
 .../wan2_2/fixtures/native_unipc_shift12.json | 97 +++++++++++++++++++
 .../models/wan2_2/test_wan22_i2v_pipeline.py  | 34 +++++--
 .../wan2_2/test_wan22_pipeline_diffuse.py     | 33 ++++++-
 .../models/wan2_2/test_wan22_s2v_pipeline.py  | 44 ++++++++-
 .../models/wan2_2/test_wan22_scheduler.py     | 54 +++++++++++
 .../models/wan2_2/test_wan22_vace_pipeline.py | 40 ++++++--
 .../models/wan2_2/pipeline_wan2_2.py          |  9 +-
 .../models/wan2_2/pipeline_wan2_2_i2v.py      |  5 +-
 .../models/wan2_2/pipeline_wan2_2_s2v.py      |  6 +-
 .../models/wan2_2/pipeline_wan2_2_vace.py     |  5 +-
 11 files changed, 298 insertions(+), 34 deletions(-)
 create mode 100644 tests/diffusion/models/wan2_2/fixtures/native_unipc_shift12.json
 create mode 100644 tests/diffusion/models/wan2_2/test_wan22_scheduler.py

diff --git a/tests/diffusion/models/wan2_2/conftest.py b/tests/diffusion/models/wan2_2/conftest.py
index f836fa545fd..cc95914c007 100644
--- a/tests/diffusion/models/wan2_2/conftest.py
+++ b/tests/diffusion/models/wan2_2/conftest.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from __future__ import annotations
 
 from contextlib import contextmanager
@@ -33,7 +36,7 @@ def __init__(self, timesteps: list[int]) -> None:
         self.config = SimpleNamespace(num_train_timesteps=1000)
         self.set_timesteps_calls: list[tuple[int, torch.device]] = []
 
-    def set_timesteps(self, num_steps: int, device: torch.device) -> None:
+    def set_timesteps(self, num_steps: int, device: torch.device, shift: float | None = None) -> None:
         self.set_timesteps_calls.append((num_steps, device))
 
 
diff --git a/tests/diffusion/models/wan2_2/fixtures/native_unipc_shift12.json b/tests/diffusion/models/wan2_2/fixtures/native_unipc_shift12.json
new file mode 100644
index 00000000000..9b6fd24331b
--- /dev/null
+++ b/tests/diffusion/models/wan2_2/fixtures/native_unipc_shift12.json
@@ -0,0 +1,97 @@
+{
+  "source_url": "https://github.com/Wan-Video/Wan2.2/blob/42bf4cfaa384bc21833865abc2f9e6c0e67233dc/wan/utils/fm_solvers_unipc.py",
+  "source_sha256": "0dec8c7ed17f6f2049275c6848113314da6ccec1c8db5bdc89df43c05c6038d9",
+  "git_head": "42bf4cfaa384bc21833865abc2f9e6c0e67233dc",
+  "num_train_timesteps": 1000,
+  "use_dynamic_shifting": false,
+  "reproduction": "Load FlowUniPCMultistepScheduler from source_url; construct with num_train_timesteps=1000, shift=1.0, use_dynamic_shifting=False; call set_timesteps(40, device='cpu', shift=12.0); record timesteps.tolist() and sigmas.tolist().",
+  "constructor_shift": 1.0,
+  "runtime_shift": 12.0,
+  "steps": 40,
+  "timesteps": [
+    999,
+    997,
+    995,
+    993,
+    990,
+    988,
+    985,
+    982,
+    979,
+    976,
+    972,
+    969,
+    965,
+    961,
+    956,
+    952,
+    947,
+    941,
+    936,
+    929,
+    922,
+    915,
+    907,
+    898,
+    888,
+    877,
+    865,
+    852,
+    837,
+    819,
+    799,
+    776,
+    749,
+    717,
+    678,
+    631,
+    571,
+    492,
+    386,
+    235
+  ],
+  "sigmas": [
+    0.9999166131019592,
+    0.9977826476097107,
+    0.9955461621284485,
+    0.9931996464729309,
+    0.9907346963882446,
+    0.988142192363739,
+    0.9854119420051575,
+    0.9825326800346375,
+    0.9794917702674866,
+    0.9762753844261169,
+    0.9728676676750183,
+    0.9692512154579163,
+    0.9654061794281006,
+    0.961310088634491,
+    0.9569376707077026,
+    0.95225989818573,
+    0.9472436308860779,
+    0.9418508410453796,
+    0.9360373020172119,
+    0.9297519326210022,
+    0.9229347705841064,
+    0.9155154228210449,
+    0.9074103832244873,
+    0.8985199332237244,
+    0.888724148273468,
+    0.8778772950172424,
+    0.865800678730011,
+    0.8522725701332092,
+    0.8370144367218018,
+    0.8196719288825989,
+    0.7997865080833435,
+    0.7767546772956848,
+    0.7497654557228088,
+    0.717703104019165,
+    0.6789888143539429,
+    0.6313128471374512,
+    0.5711563229560852,
+    0.49288034439086914,
+    0.38684695959091187,
+    0.23510953783988953,
+    0.0
+  ],
+  "implementation": "Wan-Video/Wan2.2 wan/utils/fm_solvers_unipc.py"
+}
diff --git a/tests/diffusion/models/wan2_2/test_wan22_i2v_pipeline.py b/tests/diffusion/models/wan2_2/test_wan22_i2v_pipeline.py
index 26e78ddabc5..70bb146aba9 100644
--- a/tests/diffusion/models/wan2_2/test_wan22_i2v_pipeline.py
+++ b/tests/diffusion/models/wan2_2/test_wan22_i2v_pipeline.py
@@ -1,15 +1,16 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from types import SimpleNamespace
 
+import numpy as np
 import pytest
 import torch
 from PIL import Image
 from torch import nn
 
 from tests.diffusion.models.wan2_2.conftest import StubScheduler, StubTransformer, StubVAE, noop_progress_bar
-from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import _WAN_TEXT_ENCODER_OFFLOAD_PLAN
+from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import _WAN_TEXT_ENCODER_OFFLOAD_PLAN, build_wan_scheduler
 from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_i2v import (
     Wan22I2VPipeline,
     get_wan22_i2v_post_process_func,
@@ -50,7 +51,7 @@ def _make_i2v_pipeline(*, expand_timesteps: bool) -> Wan22I2VPipeline:
 
 
 def _make_i2v_sampling(**overrides):
-    values = {
+    values: dict[str, object] = {
         "height": 16,
         "width": 16,
         "num_frames": 5,
@@ -275,16 +276,18 @@ def test_i2v_prepare_latents_preserves_batched_image_conditions() -> None:
     assert first_frame_mask.shape == (2, 1, 2, 2, 2)
 
 
-def test_i2v_forward_batches_conditions_random_inputs_and_outputs(monkeypatch) -> None:
+@pytest.mark.parametrize("solver", ["unipc", "euler"])
+@pytest.mark.parametrize("shift", [3.0, 5.0, 12.0])
+def test_i2v_forward_batches_conditions_random_inputs_and_outputs(monkeypatch, solver: str, shift: float) -> None:
     monkeypatch.setattr(
         "vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_i2v.current_omni_platform",
         SimpleNamespace(is_available=lambda: False),
     )
     pipeline = _make_i2v_pipeline(expand_timesteps=True)
-    pipeline.scheduler = StubScheduler([9])
-    pipeline.od_config = SimpleNamespace(flow_shift=5.0)
-    pipeline._sample_solver = "unipc"
-    pipeline._flow_shift = 5.0
+    pipeline.scheduler = build_wan_scheduler(solver, shift)
+    pipeline.od_config = SimpleNamespace(flow_shift=shift)
+    pipeline._sample_solver = solver
+    pipeline._flow_shift = shift
     pipeline.boundary_ratio = 0.875
     pipeline.has_image_encoder = False
     pipeline._guidance_scale = None
@@ -327,6 +330,8 @@ def _fake_prepare_latents(**kwargs):
                     generator=gen_a,
                     latents=latents_a,
                     num_outputs_per_prompt=2,
+                    num_inference_steps=50,
+                    extra_args={"sample_solver": solver, "flow_shift": shift},
                 ),
             ),
             SimpleNamespace(
@@ -336,12 +341,25 @@ def _fake_prepare_latents(**kwargs):
                     generator=gen_b,
                     latents=latents_b,
                     num_outputs_per_prompt=2,
+                    num_inference_steps=50,
+                    extra_args={"sample_solver": solver, "flow_shift": shift},
                 ),
             ),
         ]
     )
 
     outputs = pipeline.forward(batch)
+    if solver == "unipc":
+        sigmas = np.linspace(float(np.float32(0.999)), 0.0, 51)[:-1]
+        sigmas = shift * sigmas / (1.0 + (shift - 1.0) * sigmas)
+        torch.testing.assert_close(
+            pipeline.scheduler.sigmas, torch.tensor(np.append(sigmas, 0.0), dtype=torch.float32), rtol=0, atol=0
+        )
+        assert pipeline.scheduler.timesteps.tolist() == (sigmas * 1000).astype(np.int64).tolist()
+    else:
+        reference = build_wan_scheduler("euler", shift)
+        reference.set_timesteps(50, device="cpu")
+        torch.testing.assert_close(pipeline.scheduler.sigmas, reference.sigmas, rtol=0, atol=0)
 
     assert prepare_call["batch_size"] == 4
     assert prepare_call["generator"] == [gen_a, gen_a, gen_b, gen_b]
diff --git a/tests/diffusion/models/wan2_2/test_wan22_pipeline_diffuse.py b/tests/diffusion/models/wan2_2/test_wan22_pipeline_diffuse.py
index 6f7833ff820..526eeeb1568 100644
--- a/tests/diffusion/models/wan2_2/test_wan22_pipeline_diffuse.py
+++ b/tests/diffusion/models/wan2_2/test_wan22_pipeline_diffuse.py
@@ -10,7 +10,7 @@
 from torch import nn
 
 from vllm_omni.diffusion.media import VideoTensorEncoding, VideoTensorLayout, VideoValueRange
-from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import Wan22Pipeline
+from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import Wan22Pipeline, build_wan_scheduler
 from vllm_omni.diffusion.models.wan2_2.wan2_2_transformer import WanSelfAttention
 from vllm_omni.diffusion.request import OmniDiffusionRequest
 from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch
@@ -19,6 +19,12 @@
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
 
 
+@pytest.fixture(autouse=True)
+def _cpu_platform(monkeypatch):
+    module = importlib.import_module("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2")
+    monkeypatch.setattr(module.current_omni_platform, "is_available", lambda: False)
+
+
 class _StubTransformer(nn.Module):
     @property
     def dtype(self) -> torch.dtype:
@@ -51,10 +57,10 @@ class _StubScheduler:
     def __init__(self, timesteps: list[int]) -> None:
         self.timesteps = torch.tensor(timesteps, dtype=torch.int64)
         self.config = SimpleNamespace(num_train_timesteps=1000)
-        self.set_timesteps_calls: list[tuple[int, torch.device]] = []
+        self.set_timesteps_calls: list[tuple[int, torch.device, float | None]] = []
 
-    def set_timesteps(self, num_steps: int, device: torch.device) -> None:
-        self.set_timesteps_calls.append((num_steps, device))
+    def set_timesteps(self, num_steps: int, device: torch.device, shift: float | None = None) -> None:
+        self.set_timesteps_calls.append((num_steps, device, shift))
 
 
 @contextmanager
@@ -184,7 +190,24 @@ def _fake_diffuse(**kwargs):
     assert captured["boundary_timestep"] == pytest.approx(875.0)
     assert captured["latent_condition"] is None
     assert captured["first_frame_mask"] is None
-    assert pipeline.scheduler.set_timesteps_calls == [(2, torch.device("cpu"))]
+    assert pipeline.scheduler.set_timesteps_calls == [(2, torch.device("cpu"), 5.0)]
+
+
+@pytest.mark.parametrize("solver", ["unipc", "euler"])
+def test_forward_passes_request_shift_without_mutating_scheduler_config(solver: str) -> None:
+    pipeline = _make_pipeline()
+    pipeline.diffuse = lambda **kwargs: kwargs["latents"]
+    for shift in (3.0, 12.0, 5.0):
+        sampling = _make_sampling(num_inference_steps=5, extra_args={"sample_solver": solver, "flow_shift": shift})
+        request = OmniDiffusionRequest(prompt="prompt", request_id="schedule", sampling_params=sampling)
+        pipeline.forward(DiffusionRequestBatch(requests=[request]))
+        reference = build_wan_scheduler(solver, shift)
+        if solver == "unipc":
+            reference.set_timesteps(5, device="cpu", shift=shift)
+            assert pipeline.scheduler.config.shift == pipeline.scheduler.config["shift"] == 1.0
+        else:
+            reference.set_timesteps(5, device="cpu")
+        torch.testing.assert_close(pipeline.scheduler.sigmas, reference.sigmas, rtol=0, atol=0)
 
 
 def test_forward_batches_text_generators_latents_and_splits_outputs() -> None:
diff --git a/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py b/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
index 3b49d7edb66..94f8b86fd20 100644
--- a/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
+++ b/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from types import SimpleNamespace
 from unittest.mock import MagicMock, patch
 
@@ -7,6 +10,7 @@
 import torch
 import torch.nn as nn
 
+from vllm_omni.diffusion.models.schedulers import FlowUniPCMultistepScheduler
 from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v import (
     Wan22S2VPipeline,
     _make_clip_generators,
@@ -14,11 +18,32 @@
 from vllm_omni.diffusion.models.wan2_2.wan2_2_s2v_transformer import WanS2VTransformer3DModel
 from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch
 
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
+
+
+@pytest.mark.parametrize("configured_shift", [None, 12.0])
+def test_s2v_constructor_preserves_unshifted_endpoints(configured_shift: float | None) -> None:
+    module = "vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v"
+    config = SimpleNamespace(model="unused", flow_shift=configured_shift, enable_diffusion_pipeline_profiler=False)
+
+    def init_components(pipeline, *args):
+        pipeline.vae = SimpleNamespace(config=SimpleNamespace(scale_factor_temporal=4, scale_factor_spatial=8))
+
+    with (
+        patch(f"{module}.get_local_device", return_value=torch.device("cpu")),
+        patch(f"{module}._resolve_model_path", return_value="unused"),
+        patch(f"{module}._is_diffusers_format", return_value=True),
+        patch.object(Wan22S2VPipeline, "_init_diffusers_format", init_components),
+        patch.object(Wan22S2VPipeline, "setup_diffusion_pipeline_profiler"),
+    ):
+        pipeline = Wan22S2VPipeline(od_config=config)
+    assert pipeline._flow_shift == (3.0 if configured_shift is None else configured_shift)
+    assert pipeline.scheduler.config.shift == pipeline.scheduler.config["shift"] == 1.0
+    assert pipeline.scheduler.sigma_max == float(np.float32(0.999))
 
 
 def _make_s2v_sampling(**overrides):
-    values = {
+    values: dict[str, object] = {
         "height": 16,
         "width": 16,
         "num_frames": 8,
@@ -211,7 +236,8 @@ def test_s2v_forward_rejects_different_raw_audio_shapes() -> None:
         pipeline.forward(batch)
 
 
-def test_s2v_forward_batches_request_local_inputs_and_splits_outputs() -> None:
+@pytest.mark.parametrize("shift", [3.0, 12.0])
+def test_s2v_forward_batches_request_local_inputs_and_splits_outputs(shift: float) -> None:
     pipeline = object.__new__(Wan22S2VPipeline)
     nn.Module.__init__(pipeline)
     pipeline.device = torch.device("cpu")
@@ -227,7 +253,8 @@ def test_s2v_forward_batches_request_local_inputs_and_splits_outputs() -> None:
         enable_cpu_offload=False,
         parallel_config=SimpleNamespace(use_hsdp=False),
     )
-    pipeline.scheduler = MagicMock(timesteps=torch.tensor([1.0]))
+    pipeline._flow_shift = shift
+    pipeline.scheduler = FlowUniPCMultistepScheduler(shift=1.0)
     pipeline.vae_scale_factor_spatial = 8
     pipeline.resolution_divisor = 16
     pipeline.motion_frames = 7
@@ -262,6 +289,7 @@ def test_s2v_forward_batches_request_local_inputs_and_splits_outputs() -> None:
                     "multi_modal_data": {"image": image, "audio": audio_a},
                 },
                 sampling_params=_make_s2v_sampling(
+                    num_inference_steps=5,
                     num_outputs_per_prompt=2,
                     generator=generators_a,
                     latents=latents_a,
@@ -275,6 +303,7 @@ def test_s2v_forward_batches_request_local_inputs_and_splits_outputs() -> None:
                     "multi_modal_data": {"image": image, "audio": audio_b},
                 },
                 sampling_params=_make_s2v_sampling(
+                    num_inference_steps=5,
                     num_outputs_per_prompt=2,
                     generator=generators_b,
                     latents=latents_b,
@@ -287,6 +316,12 @@ def test_s2v_forward_batches_request_local_inputs_and_splits_outputs() -> None:
         platform.is_available.return_value = False
         outputs = pipeline.forward(batch)
 
+    expected = np.linspace(float(np.float32(0.999)), 0.0, 6)[:-1]
+    expected = shift * expected / (1.0 + (shift - 1.0) * expected)
+    torch.testing.assert_close(
+        pipeline.scheduler.sigmas, torch.tensor(np.append(expected, 0.0), dtype=torch.float32), rtol=0, atol=0
+    )
+    assert pipeline.scheduler.config.shift == pipeline.scheduler.config["shift"] == 1.0
     assert len(outputs) == 2
     assert outputs[0].output[0].shape[0] == 2
     assert outputs[1].output[0].shape[0] == 2
@@ -519,6 +554,7 @@ def test_s2v_pipeline_hsdp_forward_complete_process():
     mock_scheduler.timesteps = torch.linspace(999, 0, 5)
     mock_scheduler.step = MagicMock(return_value=(torch.zeros(1, 16, 20, 88, 128),))
     pipeline.scheduler = mock_scheduler
+    pipeline._flow_shift = 3.0
 
     # -- Bind methods from the real class --
     pipeline.encode_prompt = Wan22S2VPipeline.encode_prompt.__get__(pipeline)
diff --git a/tests/diffusion/models/wan2_2/test_wan22_scheduler.py b/tests/diffusion/models/wan2_2/test_wan22_scheduler.py
new file mode 100644
index 00000000000..87cc2467098
--- /dev/null
+++ b/tests/diffusion/models/wan2_2/test_wan22_scheduler.py
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Compare actual Wan schedules to native Wan outputs and independent sigma arithmetic."""
+
+import json
+from pathlib import Path
+
+import numpy as np
+import numpy.typing as npt
+import pytest
+import torch
+
+from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import (
+    FASTWAN_DMD_SCHEDULER_SHIFT,
+    build_wan_scheduler,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
+
+
+def test_wan_unipc_matches_captured_native_full_schedule() -> None:
+    # The fixture pins the official Wan source and records how to regenerate it.
+    golden = json.loads((Path(__file__).parent / "fixtures/native_unipc_shift12.json").read_text())
+    scheduler = build_wan_scheduler("unipc", golden["runtime_shift"])
+    for steps in (golden["steps"], 20, golden["steps"]):
+        scheduler.set_timesteps(steps, device="cpu", shift=golden["runtime_shift"])
+        if steps == golden["steps"]:
+            assert scheduler.timesteps.tolist() == golden["timesteps"]
+            torch.testing.assert_close(scheduler.sigmas, torch.tensor(golden["sigmas"]), rtol=0, atol=0)
+
+
+@pytest.mark.parametrize("shift", [1.0, 3.0, 5.0, 12.0])
+@pytest.mark.parametrize("steps", [20, 40])
+def test_wan_unipc_shifts_unmodified_training_endpoints(shift: float, steps: int) -> None:
+    # Native Wan: float32 training sigma_max=(1-1/1000), sigma_min=0;
+    # interpolate in float64, apply the runtime shift, then cast sigma to FP32.
+    unshifted = np.linspace(float(np.float32(0.999)), 0.0, steps + 1)[:-1]
+    shifted = shift * unshifted / (1.0 + (shift - 1.0) * unshifted)
+    expected_timesteps = (shifted * 1000).astype(np.int64)
+    expected_sigmas: npt.NDArray[np.float32] = np.append(shifted, 0.0).astype(np.float32)
+    scheduler = build_wan_scheduler("unipc", shift)
+    scheduler.set_timesteps(steps, device="cpu", shift=shift)
+    assert scheduler.config.shift == scheduler.config["shift"] == 1.0
+    torch.testing.assert_close(scheduler.timesteps, torch.from_numpy(expected_timesteps), rtol=0, atol=0)
+    torch.testing.assert_close(scheduler.sigmas, torch.from_numpy(expected_sigmas), rtol=0, atol=0)
+
+
+def test_wan_euler_keeps_dmd_shift_semantics() -> None:
+    scheduler = build_wan_scheduler("euler", FASTWAN_DMD_SCHEDULER_SHIFT)
+    scheduler.set_timesteps(3, device="cpu")
+    # The unchanged Euler branch starts at sigma=1, with shift=8 for DMD.
+    expected = torch.tensor([1.0, 16.0 / 17.0, 0.8, 0.0])
+    torch.testing.assert_close(scheduler.sigmas, expected, rtol=0, atol=1e-7)
+    torch.testing.assert_close(scheduler.timesteps, expected[:-1] * 1000, rtol=0, atol=1e-4)
diff --git a/tests/diffusion/models/wan2_2/test_wan22_vace_pipeline.py b/tests/diffusion/models/wan2_2/test_wan22_vace_pipeline.py
index 5f712bc8ae4..75cf868ce2b 100644
--- a/tests/diffusion/models/wan2_2/test_wan22_vace_pipeline.py
+++ b/tests/diffusion/models/wan2_2/test_wan22_vace_pipeline.py
@@ -1,15 +1,17 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from dataclasses import dataclass, field
 from types import SimpleNamespace
 
+import numpy as np
 import pytest
 import torch
 from PIL import Image
 from torch import nn
 
 from tests.diffusion.models.wan2_2.conftest import StubScheduler, StubTransformer, StubVAE, noop_progress_bar
+from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import build_wan_scheduler
 from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_vace import (
     Wan22VACEPipeline,
     create_vace_transformer_from_config,
@@ -33,6 +35,8 @@ class RuntimeConfig:
         )
         enable_layerwise_offload: bool = True
         post_init_calls: int = 0
+        _resolved_diffusion_offload: object = None
+        _diffusion_offload_flags_materialized: bool = False
 
         def __post_init__(self) -> None:
             self.post_init_calls += 1
@@ -41,7 +45,7 @@ def __post_init__(self) -> None:
     resolved_offload = object()
     config._resolved_diffusion_offload = resolved_offload
     config._diffusion_offload_flags_materialized = True
-    captured = {}
+    captured: dict[str, object] = {}
 
     def capture_base_init(self, *, od_config, prefix="") -> None:
         captured.update(od_config=od_config, prefix=prefix)
@@ -51,6 +55,7 @@ def capture_base_init(self, *, od_config, prefix="") -> None:
     Wan22VACEPipeline(od_config=config, prefix="stage")
 
     forwarded = captured["od_config"]
+    assert isinstance(forwarded, RuntimeConfig)
     assert forwarded is not config
     assert config.flow_shift is None
     assert forwarded.flow_shift == 3.0
@@ -75,7 +80,7 @@ def _make_vace_pipeline() -> Wan22VACEPipeline:
 
 
 def _make_vace_sampling(**overrides):
-    values = {
+    values: dict[str, object] = {
         "height": 16,
         "width": 16,
         "num_frames": 5,
@@ -123,7 +128,7 @@ def test_vace_preprocess_collects_reference_video_and_mask_inputs() -> None:
 
 
 def test_create_vace_transformer_from_config_maps_vace_specific_keys(monkeypatch) -> None:
-    captured = {}
+    captured: dict[str, object] = {}
 
     class FakeVACETransformer:
         def __init__(self, **kwargs) -> None:
@@ -203,7 +208,9 @@ def fake_predict_noise_maybe_with_cfg(**kwargs):
     torch.testing.assert_close(result, torch.ones_like(latents))
 
 
-def test_vace_forward_batches_random_inputs_and_splits_outputs(monkeypatch) -> None:
+@pytest.mark.parametrize("solver", ["unipc", "euler"])
+@pytest.mark.parametrize("shift", [3.0, 5.0, 12.0])
+def test_vace_forward_batches_random_inputs_and_splits_outputs(monkeypatch, solver: str, shift: float) -> None:
     monkeypatch.setattr(
         "vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_vace.current_omni_platform",
         SimpleNamespace(is_available=lambda: False),
@@ -211,10 +218,10 @@ def test_vace_forward_batches_random_inputs_and_splits_outputs(monkeypatch) -> N
     pipeline = _make_vace_pipeline()
     pipeline.transformer.vace_patch_embedding = None
     pipeline.transformer_2 = None
-    pipeline.scheduler = StubScheduler([9])
-    pipeline.od_config = SimpleNamespace(flow_shift=3.0)
-    pipeline._sample_solver = "unipc"
-    pipeline._flow_shift = 3.0
+    pipeline.scheduler = build_wan_scheduler(solver, shift)
+    pipeline.od_config = SimpleNamespace(flow_shift=shift)
+    pipeline._sample_solver = solver
+    pipeline._flow_shift = shift
     pipeline.boundary_ratio = None
     pipeline._guidance_scale = None
     pipeline._num_timesteps = None
@@ -247,6 +254,8 @@ def _fake_prepare_latents(**kwargs):
                     generator=gen_a,
                     latents=latents_a,
                     num_outputs_per_prompt=2,
+                    num_inference_steps=50,
+                    extra_args={"sample_solver": solver, "flow_shift": shift},
                 ),
             ),
             SimpleNamespace(
@@ -256,12 +265,25 @@ def _fake_prepare_latents(**kwargs):
                     generator=gen_b,
                     latents=latents_b,
                     num_outputs_per_prompt=2,
+                    num_inference_steps=50,
+                    extra_args={"sample_solver": solver, "flow_shift": shift},
                 ),
             ),
         ]
     )
 
     outputs = pipeline.forward(batch)
+    if solver == "unipc":
+        sigmas = np.linspace(float(np.float32(0.999)), 0.0, 51)[:-1]
+        sigmas = shift * sigmas / (1.0 + (shift - 1.0) * sigmas)
+        torch.testing.assert_close(
+            pipeline.scheduler.sigmas, torch.tensor(np.append(sigmas, 0.0), dtype=torch.float32), rtol=0, atol=0
+        )
+        assert pipeline.scheduler.timesteps.tolist() == (sigmas * 1000).astype(np.int64).tolist()
+    else:
+        reference = build_wan_scheduler("euler", shift)
+        reference.set_timesteps(50, device="cpu")
+        torch.testing.assert_close(pipeline.scheduler.sigmas, reference.sigmas, rtol=0, atol=0)
 
     assert prepare_call["batch_size"] == 4
     assert prepare_call["generator"] == [gen_a, gen_a, gen_b, gen_b]
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
index a285e0009d3..15b0368641b 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
@@ -59,9 +59,11 @@
 
 def build_wan_scheduler(sample_solver: str, flow_shift: float) -> Any:
     if sample_solver == "unipc":
+        # Keep native Wan's unshifted training endpoints; set_timesteps applies
+        # the requested shift to the interpolated inference sigmas.
         return FlowUniPCMultistepScheduler(
             num_train_timesteps=1000,
-            shift=flow_shift,
+            shift=1.0,
             prediction_type="flow_prediction",
         )
     if sample_solver == "euler":
@@ -774,7 +776,10 @@ def forward(self, req: DiffusionRequestBatch) -> list[DiffusionOutput]:
                 self._sample_solver = sample_solver
                 self._flow_shift = flow_shift
 
-            self.scheduler.set_timesteps(num_steps, device=device)
+            if sample_solver == "unipc":
+                self.scheduler.set_timesteps(num_steps, device=device, shift=flow_shift)
+            else:
+                self.scheduler.set_timesteps(num_steps, device=device)
             timesteps = self.scheduler.timesteps
         self._num_timesteps = len(timesteps)
         boundary_timestep = None
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
index 908a350202b..01bd53bb89b 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
@@ -629,7 +629,10 @@ def forward(self, req: DiffusionRequestBatch) -> list[DiffusionOutput]:
             self._flow_shift = flow_shift
 
         # Timesteps
-        self.scheduler.set_timesteps(num_steps, device=device)
+        if sample_solver == "unipc":
+            self.scheduler.set_timesteps(num_steps, device=device, shift=flow_shift)
+        else:
+            self.scheduler.set_timesteps(num_steps, device=device)
         timesteps = self.scheduler.timesteps
         self._num_timesteps = len(timesteps)
 
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.py
index ea99e065f1f..1d28b425dbb 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.py
@@ -545,10 +545,10 @@ def __init__(
             self._init_original_format(model_path, dtype)
 
         # -- Scheduler --
-        flow_shift = od_config.flow_shift if od_config.flow_shift is not None else 3.0  # S2V default
+        self._flow_shift = od_config.flow_shift if od_config.flow_shift is not None else 3.0  # S2V default
         self.scheduler = FlowUniPCMultistepScheduler(
             num_train_timesteps=1000,
-            shift=flow_shift,
+            shift=1.0,
             prediction_type="flow_prediction",
         )
 
@@ -1342,7 +1342,7 @@ def forward(
                 )
 
             # -- Scheduler --
-            self.scheduler.set_timesteps(num_steps, device=device)
+            self.scheduler.set_timesteps(num_steps, device=device, shift=self._flow_shift)
             timesteps = self.scheduler.timesteps
             self._num_timesteps = len(timesteps)
 
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_vace.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_vace.py
index 0d48dffb564..aeecff60807 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_vace.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_vace.py
@@ -690,7 +690,10 @@ def forward(
         )
 
         # Set up scheduler
-        self.scheduler.set_timesteps(num_inference_steps, device=device)
+        if self._sample_solver == "unipc":
+            self.scheduler.set_timesteps(num_inference_steps, device=device, shift=self._flow_shift)
+        else:
+            self.scheduler.set_timesteps(num_inference_steps, device=device)
         timesteps = self.scheduler.timesteps
         self._num_timesteps = len(timesteps)
 

From 3319f6ca7891c53b267ae6a6beb65d128362e8f5 Mon Sep 17 00:00:00 2001
From: Genghong Hu <111997394+GodHu777777@users.noreply.github.com>
Date: Wed, 16 Sep 2026 10:37:50 +0800
Subject: [PATCH 018/105] [CI/Build][Hardware][Ascend] Add torchmetrics to the
 NPU CI image (#7570)

Signed-off-by: Genghong Hu <godhu777777@gmail.com>
---
 docker/Dockerfile.npu.ci | 1 +
 1 file changed, 1 insertion(+)

diff --git a/docker/Dockerfile.npu.ci b/docker/Dockerfile.npu.ci
index b65b803d6bc..a2515511173 100644
--- a/docker/Dockerfile.npu.ci
+++ b/docker/Dockerfile.npu.ci
@@ -44,6 +44,7 @@ RUN python3 -m pip install -U pip && \
       "onnx>=1.16.0" \
       "librosa>=0.10.0" \
       "datasets>=3.0.0" \
+      "torchmetrics==1.9.0" \
       --index-url http://cache-service.nginx-pypi-cache.svc.cluster.local/pypi/simple \
       --trusted-host cache-service.nginx-pypi-cache.svc.cluster.local \
       --default-timeout=60

From 7bceb1a76b99652b7a7abb315c7cc6f1f952b967 Mon Sep 17 00:00:00 2001
From: psv666 <150513104+psv666@users.noreply.github.com>
Date: Wed, 16 Sep 2026 10:49:07 +0800
Subject: [PATCH 019/105] [Bugfix] Align video frame consumption reporting with
 prompt sampling (#7329)

---
 docs/serving/video_stream_api.md              |   8 +
 .../openai_api/test_serving_video_stream.py   | 194 ++++++++++++++++++
 .../openai/serving_video_stream.py            |  20 +-
 .../entrypoints/openai/video_stream_base.py   |  32 ++-
 4 files changed, 232 insertions(+), 22 deletions(-)

diff --git a/docs/serving/video_stream_api.md b/docs/serving/video_stream_api.md
index 101289fc014..23aa4cb08e4 100644
--- a/docs/serving/video_stream_api.md
+++ b/docs/serving/video_stream_api.md
@@ -50,6 +50,14 @@ WebSocket /v1/video/chat/stream
 | Server -> Client | `session.done` | none | Session closed. |
 | Server -> Client | `error` | `message` | Recoverable protocol or generation error. |
 
+### Frame Consumption Reporting
+
+When buffered frames include client-supplied `frame_id` values, the server emits `video.frames.consumed` after the first engine output. Its `frame_ids`, `frames`, and `latest_pts_ms` describe the images included in that query's prompt.
+
+Queries stride-sample the buffered frames, keeping the last frame, then exclude frames already known to have failed decoding. Excluded frames are not replaced with other buffered frames. Frames whose background decoding has not finished remain eligible through the image URL path.
+
+**Bugfix compatibility note:** `video.frames.consumed` now excludes known decode failures that were already excluded from the prompt. Older versions could report those frames and their timestamps as consumed. The event name and fields are unchanged; an empty selection reports empty lists and `latest_pts_ms: null`.
+
 ### `session.config` Fields
 
 | Field | Type | Default | Description |
diff --git a/tests/entrypoints/openai_api/test_serving_video_stream.py b/tests/entrypoints/openai_api/test_serving_video_stream.py
index f7267a0619e..c9c4f6a4b54 100644
--- a/tests/entrypoints/openai_api/test_serving_video_stream.py
+++ b/tests/entrypoints/openai_api/test_serving_video_stream.py
@@ -375,6 +375,200 @@ async def _preprocess_to_engine_prompt(self, request):
     )
 
 
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "num_frames,bad_index,expected_indices",
+    [
+        pytest.param(2, 4, [0], id="bad-last-no-refill"),
+        pytest.param(1, 4, [], id="all-selected-frames-bad"),
+        pytest.param(8, 4, [0, 1, 2, 3], id="below-sampling-limit"),
+        pytest.param(2, 1, [0, 4], id="bad-frame-not-selected"),
+        pytest.param(2, 0, [4], id="bad-first-frame"),
+    ],
+)
+async def test_video_frames_consumed_excludes_bad_frame_in_query_snapshot(
+    monkeypatch, num_frames, bad_index, expected_indices
+):
+    """A query queued before bad-frame cleanup must report only its prompt images."""
+    query_queued = asyncio.Event()
+    decode_failed = asyncio.Event()
+    release_decode = asyncio.Event()
+    pong_blocked = asyncio.Event()
+    release_pong = asyncio.Event()
+    turn_done = asyncio.Event()
+    original_to_thread = asyncio.to_thread
+    bad_image = b"not-a-jpeg"
+    frames = [_make_jpeg(r=index * 40) for index in range(5)]
+    frames[bad_index] = bad_image
+    engine_prompts = []
+
+    class ObservedQueue(asyncio.Queue):
+        def put_nowait(self, item):
+            super().put_nowait(item)
+            if isinstance(item, dict):
+                if item.get("type") == "video.query":
+                    query_queued.set()
+                elif item.get("type") == "_internal.frame_decode_failed":
+                    decode_failed.set()
+
+    async def gated_to_thread(function, *args, **kwargs):
+        if function is video_stream_base._decode_frame_bytes and args[0] == bad_image:
+            await release_decode.wait()
+        return await original_to_thread(function, *args, **kwargs)
+
+    class BackpressuredWebSocket(TimedWebSocket):
+        async def send_json(self, data):
+            await super().send_json(data)
+            if data["type"] == "pong":
+                pong_blocked.set()
+                await release_pong.wait()
+            elif data["type"] == "response.text.done":
+                turn_done.set()
+
+    class OneOutputEngine:
+        async def generate(self, **kwargs):
+            engine_prompts.append(kwargs["prompt"])
+            yield _text_result("visible")
+
+    class CapturingHandler(QwenOmniStreamingVideoHandler):
+        async def _preprocess_to_engine_prompt(self, request):
+            return {"messages": request.messages}
+
+    # Construct the client queue before observing the server's message queue.
+    ws = BackpressuredWebSocket()
+    monkeypatch.setattr(asyncio, "Queue", ObservedQueue)
+    monkeypatch.setattr(asyncio, "to_thread", gated_to_thread)
+    handler = CapturingHandler(chat_service=object(), engine_client=OneOutputEngine(), idle_timeout=5.0)
+    ws.put(
+        {
+            "type": "session.config",
+            "model": "test",
+            "modalities": ["text"],
+            "num_frames": num_frames,
+            "enable_frame_filter": False,
+        }
+    )
+    for index, frame in enumerate(frames):
+        ws.put({"type": "video.frame", "data": _b64(frame), "frame_id": f"frame-{index}", "pts_ms": index * 100})
+    ws.put({"type": "ping"})
+    ws.put({"type": "video.query", "text": "describe"})
+    task = asyncio.create_task(handler.handle_session(ws))
+    try:
+        # Hold the processor at a WebSocket send. Queue the query first, then
+        # finish the real failing decode so its cleanup lands behind the query.
+        await asyncio.wait_for(pong_blocked.wait(), timeout=5.0)
+        await asyncio.wait_for(query_queued.wait(), timeout=5.0)
+        release_decode.set()
+        await asyncio.wait_for(decode_failed.wait(), timeout=5.0)
+        release_pong.set()
+        await asyncio.wait_for(turn_done.wait(), timeout=5.0)
+        ws.put({"type": "video.done"})
+        await asyncio.wait_for(task, timeout=5.0)
+    finally:
+        release_decode.set()
+        release_pong.set()
+        if not task.done():
+            task.cancel()
+        await asyncio.gather(task, return_exceptions=True)
+
+    assert len(engine_prompts) == 1
+    images = [part for part in engine_prompts[0]["messages"][-1]["content"] if part["type"].startswith("image_")]
+    # Expected positions preserve sample-then-filter: do not refill a dropped
+    # position or shift the remaining metadata when a frame fails to decode.
+    assert len(images) == len(expected_indices)
+    for image, index in zip(images, expected_indices):
+        if image["type"] == "image_pil":
+            assert image["image_pil"].tobytes() == Image.open(io.BytesIO(frames[index])).convert("RGB").tobytes()
+        else:
+            assert image["image_url"]["url"] == f"data:image/jpeg;base64,{_b64(frames[index])}"
+    consumed_events = [message for message in ws.sent if message.get("type") == "video.frames.consumed"]
+    assert len(consumed_events) == 1
+    consumed = consumed_events[0]
+    expected_ids = [f"frame-{index}" for index in expected_indices]
+    assert consumed["frame_ids"] == expected_ids
+    assert [frame["frame_id"] for frame in consumed["frames"]] == expected_ids
+    assert [frame["pts_ms"] for frame in consumed["frames"]] == [index * 100 for index in expected_indices]
+    assert consumed["latest_pts_ms"] == (expected_indices[-1] * 100 if expected_indices else None)
+    assert {"type": "error", "message": "Frame decode failed"} in ws.sent
+    assert ws.sent[-1]["type"] == "session.done"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "num_frames,frame_ids,repeat_image,expected_indices",
+    [
+        pytest.param(2, ["f0", "f1", "f2", "f3", "f4"], False, [0, 4], id="stride-and-last"),
+        pytest.param(1, ["f0", "f1", "f2"], False, [2], id="last-only"),
+        pytest.param(8, ["f0", "f1", "f2"], False, [0, 1, 2], id="below-sampling-limit"),
+        pytest.param(2, [None, "f1", None, "f3", None], False, [0, 4], id="unidentified-selected-frames"),
+        pytest.param(2, [None, None, None], False, [0, 2], id="no-frame-ids"),
+        pytest.param(2, ["same", "same", "same"], False, [0, 2], id="repeated-frame-id"),
+        pytest.param(2, ["f0", "f1", "f2"], True, [0, 2], id="repeated-image"),
+    ],
+)
+async def test_video_frame_selection_preserves_uncached_frames(
+    monkeypatch, num_frames, frame_ids, repeat_image, expected_indices
+):
+    """Prewarm misses still use image URLs, with metadata paired by buffer position."""
+    engine_prompts = []
+    pending_decode = asyncio.Event()
+
+    async def blocked_to_thread(*args, **kwargs):
+        await pending_decode.wait()
+
+    monkeypatch.setattr(asyncio, "to_thread", blocked_to_thread)
+
+    class OneOutputEngine:
+        async def generate(self, **kwargs):
+            engine_prompts.append(kwargs["prompt"])
+            yield _text_result("visible")
+
+    class CapturingHandler(QwenOmniStreamingVideoHandler):
+        async def _preprocess_to_engine_prompt(self, request):
+            return {"messages": request.messages}
+
+    frames = [_b64(_make_jpeg(r=0 if repeat_image else index * 40)) for index in range(len(frame_ids))]
+    messages = [
+        {
+            "type": "session.config",
+            "model": "test",
+            "modalities": ["text"],
+            "num_frames": num_frames,
+            "enable_frame_filter": False,
+        },
+        *[
+            {"type": "video.frame", "data": frame, "frame_id": frame_ids[index], "pts_ms": index * 100}
+            for index, frame in enumerate(frames)
+        ],
+        {"type": "video.query", "text": "describe"},
+        {"type": "video.done"},
+    ]
+    ws = MockWebSocket([json.dumps(message) for message in messages])
+    handler = CapturingHandler(chat_service=object(), engine_client=OneOutputEngine())
+    await asyncio.wait_for(handler.handle_session(ws), timeout=5.0)
+
+    assert not [message for message in ws.sent if message["type"] == "error"]
+    assert len(engine_prompts) == 1
+    content = engine_prompts[0]["messages"][-1]["content"]
+    assert content == [
+        *[
+            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{frames[index]}"}}
+            for index in expected_indices
+        ],
+        {"type": "text", "text": "describe"},
+    ]
+    consumed_events = [message for message in ws.sent if message["type"] == "video.frames.consumed"]
+    if not any(frame_ids):
+        assert consumed_events == []
+    else:
+        assert len(consumed_events) == 1
+        consumed = consumed_events[0]
+        assert consumed["frame_ids"] == [frame_ids[index] for index in expected_indices if frame_ids[index] is not None]
+        assert [frame["frame_id"] for frame in consumed["frames"]] == [frame_ids[index] for index in expected_indices]
+        assert [frame["pts_ms"] for frame in consumed["frames"]] == [index * 100 for index in expected_indices]
+        assert consumed["latest_pts_ms"] == expected_indices[-1] * 100
+
+
 @pytest.mark.asyncio
 async def test_audio_in_video_sets_mm_processor_kwargs():
     captured_requests = []
diff --git a/vllm_omni/entrypoints/openai/serving_video_stream.py b/vllm_omni/entrypoints/openai/serving_video_stream.py
index 5b30ff0faf9..5f7334bd294 100644
--- a/vllm_omni/entrypoints/openai/serving_video_stream.py
+++ b/vllm_omni/entrypoints/openai/serving_video_stream.py
@@ -30,7 +30,6 @@
 from typing import Any
 
 from vllm_omni.entrypoints.openai.video_stream_base import (
-    _BAD_FRAME,
     _DEFAULT_CONFIG_TIMEOUT,
     _DEFAULT_IDLE_TIMEOUT,
     PrewarmedFrame,
@@ -62,22 +61,19 @@ def build_engine_prompt(
         message_history: list[dict[str, Any]],
         query_text: str,
         prewarmed_frames: Mapping[str, PrewarmedFrame],
+        *,
+        frame_indices: list[int] | None = None,
     ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
-        n_buf = len(frame_buffer)
-        if n_buf <= config.num_frames:
-            frames = list(frame_buffer)
-        else:
-            stride = max(1, n_buf // config.num_frames)
-            idx = [i * stride for i in range(config.num_frames - 1)] + [n_buf - 1]
-            frames = [frame_buffer[i] for i in idx]
-
         prewarmed = prewarmed_frames or {}
+        if frame_indices is None:
+            frame_indices = self._sample_frame_indices(frame_buffer, config.num_frames, prewarmed)
         user_content: list[dict] = []
-        for frame_b64 in frames:
+        for index in frame_indices:
+            frame_b64 = frame_buffer[index]
             cached = prewarmed.get(frame_b64)
-            if cached is _BAD_FRAME:
-                continue
             if cached is not None:
+                # The shared selector excludes failed decodes before this point.
+                assert isinstance(cached, tuple)
                 pil, pil_uuid = cached
                 user_content.append(
                     {
diff --git a/vllm_omni/entrypoints/openai/video_stream_base.py b/vllm_omni/entrypoints/openai/video_stream_base.py
index 8885e9a33c0..52ae9d89419 100644
--- a/vllm_omni/entrypoints/openai/video_stream_base.py
+++ b/vllm_omni/entrypoints/openai/video_stream_base.py
@@ -93,8 +93,10 @@ def build_engine_prompt(
         message_history: list[dict[str, Any]],
         query_text: str,
         prewarmed_frames: Mapping[str, PrewarmedFrame],
+        *,
+        frame_indices: list[int] | None = None,
     ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
-        """Build OpenAI-style messages and the current user message."""
+        """Build messages using the supplied frame selection, or sample if omitted."""
         ...
 
     def on_turn_complete(
@@ -179,6 +181,8 @@ def build_engine_prompt(
         message_history: list[dict[str, Any]],
         query_text: str,
         prewarmed_frames: Mapping[str, PrewarmedFrame],
+        *,
+        frame_indices: list[int] | None = None,
     ) -> tuple[list[dict[str, Any]], dict[str, Any]]:
         raise NotImplementedError
 
@@ -639,6 +643,9 @@ async def _process_query_engine(
             ChatCompletionRequest,
         )
 
+        # Select once from this turn's snapshot so prompt images and the
+        # consumed event refer to exactly the same frames, including decode failures.
+        frame_indices = self._sample_frame_indices(frame_buffer, config.num_frames, prewarmed_frames)
         messages, user_message = self.build_engine_prompt(
             config,
             frame_buffer,
@@ -646,6 +653,7 @@ async def _process_query_engine(
             message_history,
             query_text,
             prewarmed_frames,
+            frame_indices=frame_indices,
         )
 
         request_kwargs: dict[str, Any] = {
@@ -678,7 +686,7 @@ async def _process_query_engine(
             await self._send_error(websocket, f"Preprocess failed: {e}")
             return
         decoded_ready_ts_ms = _time.monotonic() * 1000
-        selected_metadata = self._sample_frame_metadata(frame_metadata or [], config.num_frames)
+        selected_metadata = [frame_metadata[index] for index in frame_indices] if frame_metadata else []
         model_selected_ts_ms = _time.monotonic() * 1000
 
         await websocket.send_json({"type": "response.start"})
@@ -1071,15 +1079,19 @@ async def _send_error(self, websocket: WebSocket, message: str) -> None:
             pass
 
     @staticmethod
-    def _sample_frame_metadata(
-        frame_metadata: list[dict[str, Any]],
+    def _sample_frame_indices(
+        frame_buffer: list[str],
         num_frames: int,
-    ) -> list[dict[str, Any]]:
-        if len(frame_metadata) <= num_frames:
-            return list(frame_metadata)
-        stride = max(1, len(frame_metadata) // num_frames)
-        indices = [index * stride for index in range(num_frames - 1)] + [len(frame_metadata) - 1]
-        return [frame_metadata[index] for index in indices]
+        prewarmed_frames: Mapping[str, PrewarmedFrame],
+    ) -> list[int]:
+        """Stride-sample with the last frame, then drop known bad frames without refilling."""
+        n_buf = len(frame_buffer)
+        if n_buf <= num_frames:
+            indices = list(range(n_buf))
+        else:
+            stride = max(1, n_buf // num_frames)
+            indices = [index * stride for index in range(num_frames - 1)] + [n_buf - 1]
+        return [index for index in indices if prewarmed_frames.get(frame_buffer[index]) is not _BAD_FRAME]
 
     @staticmethod
     async def _send_frame_ack(

From 5dbae2b182c1680586a25928ea5089971fd5b515 Mon Sep 17 00:00:00 2001
From: Yueqian Lin <70319226+linyueqian@users.noreply.github.com>
Date: Tue, 15 Sep 2026 20:08:49 -0700
Subject: [PATCH 020/105] [Bugfix] Per-key accumulation strategy for Qwen3-TTS
 codec frame outputs (#7608)

Signed-off-by: Yueqian Lin <linyueqian@outlook.com>
---
 tests/engine/test_output_modality.py          | 88 +++++++++++++++++++
 .../models/qwen3_tts/pipeline.py              | 14 +++
 vllm_omni/outputs/mm_outputs.py               | 49 +++++++----
 vllm_omni/outputs/output_modality.py          | 39 +++++++-
 vllm_omni/outputs/output_processor.py         |  9 +-
 5 files changed, 174 insertions(+), 25 deletions(-)

diff --git a/tests/engine/test_output_modality.py b/tests/engine/test_output_modality.py
index ff15e582479..e5c5d36c1ee 100644
--- a/tests/engine/test_output_modality.py
+++ b/tests/engine/test_output_modality.py
@@ -41,6 +41,7 @@ def _load_module(name: str, filepath: Path):
 OutputModality = _om_mod.OutputModality
 TensorAccumulationStrategy = _om_mod.TensorAccumulationStrategy
 get_accumulation_strategy = _om_mod.get_accumulation_strategy
+register_key_accumulation_strategy = _om_mod.register_key_accumulation_strategy
 MultimodalPayload = _mm_mod.MultimodalPayload
 MultimodalCompletionOutput = _mm_mod.MultimodalCompletionOutput
 
@@ -156,3 +157,90 @@ def test_output_modality_printed_examples(capsys):
     captured = capsys.readouterr()
     assert "OutputModality Parsing" in captured.out
     assert "MultimodalPayload" in captured.out
+
+
+def test_get_accumulation_strategy_key_override_precedence():
+    """A registered per-key override wins over the modality-wide default;
+    any other key under the same modality keeps using that default."""
+    assert get_accumulation_strategy(OutputModality.AUDIO, "unregistered.key") == TensorAccumulationStrategy.CONCAT_LAST
+
+    register_key_accumulation_strategy("__test_override__.frames", TensorAccumulationStrategy.CONCAT_DIM0)
+    assert (
+        get_accumulation_strategy(OutputModality.AUDIO, "__test_override__.frames")
+        == TensorAccumulationStrategy.CONCAT_DIM0
+    )
+    # A plain waveform key under the same AUDIO modality is unaffected.
+    assert get_accumulation_strategy(OutputModality.AUDIO, "waveform") == TensorAccumulationStrategy.CONCAT_LAST
+    assert get_accumulation_strategy(OutputModality.AUDIO) == TensorAccumulationStrategy.CONCAT_LAST
+
+
+def _talker_codec_frame_payload(audio_key: str, ref_key: str) -> MultimodalPayload:
+    """Synthetic stand-in for a TTS talker's accumulated per-step output.
+
+    ``audio_key`` grows one ``[1, num_codebooks]`` row per decode step on top
+    of a ``[5, num_codebooks]`` prefill block (Qwen3-TTS's ``codes.audio``);
+    ``ref_key`` re-emits the same constant ``[100, num_codebooks]``
+    reference-context matrix unchanged at every step (Qwen3-TTS's
+    ``codes.ref``). Neither is a waveform chunk.
+    """
+    payload = MultimodalPayload()
+    payload.tensors[audio_key] = [
+        torch.zeros(5, 16),
+        torch.full((1, 16), 1.0),
+        torch.full((1, 16), 2.0),
+        torch.full((1, 16), 3.0),
+    ]
+    ref_block = torch.arange(100 * 16, dtype=torch.float32).reshape(100, 16)
+    payload.tensors[ref_key] = [ref_block.clone(), ref_block.clone(), ref_block.clone()]
+    return payload
+
+
+def test_consolidate_tensors_default_audio_strategy_corrupts_codec_frame_keys():
+    """Reproduces both failure modes of forcing codec-frame keys through the
+    AUDIO modality's waveform-tuned default (CONCAT_LAST) with no per-key
+    override registered: the audio-frames key's dim-0 growth makes
+    CONCAT_LAST's dim=-1 concat raise (mismatched dim 0), which the
+    flatten-chunks fallback turns into a 1-D blob instead of the intended
+    ``[8, 16]``; the ref-frames key's matching last dim lets CONCAT_LAST
+    "succeed" by silently concatenating three identical ``[100, 16]`` blocks
+    into ``[100, 48]`` instead of keeping a single copy.
+    """
+    payload = _talker_codec_frame_payload("unregistered.codes.audio", "unregistered.codes.ref")
+
+    payload.consolidate_tensors(OutputModality.AUDIO)
+
+    assert tuple(payload.tensors["unregistered.codes.audio"].shape) != (8, 16)
+    assert tuple(payload.tensors["unregistered.codes.ref"].shape) == (100, 48)
+
+
+def test_consolidate_tensors_with_qwen3_tts_key_overrides_is_correct():
+    """With the per-key overrides Qwen3-TTS's pipeline module registers
+    (``codes.audio`` -> CONCAT_DIM0, ``codes.ref`` -> REPLACE), both keys
+    consolidate correctly under the AUDIO modality despite not being
+    waveform chunks."""
+    register_key_accumulation_strategy("codes.audio", TensorAccumulationStrategy.CONCAT_DIM0)
+    register_key_accumulation_strategy("codes.ref", TensorAccumulationStrategy.REPLACE)
+
+    payload = _talker_codec_frame_payload("codes.audio", "codes.ref")
+    expected_ref = payload.tensors["codes.ref"][0]
+
+    payload.consolidate_tensors(OutputModality.AUDIO)
+
+    assert tuple(payload.tensors["codes.audio"].shape) == (8, 16)
+    assert tuple(payload.tensors["codes.ref"].shape) == (100, 16)
+    assert torch.equal(payload.tensors["codes.ref"], expected_ref)
+
+
+def test_consolidate_tensors_raises_with_key_name_instead_of_silently_keeping_last():
+    """A concat failure under a non-CONCAT_LAST strategy must be surfaced
+    with the offending key name rather than resolved by silently keeping
+    only the last chunk. Previously the except-branch only special-cased
+    the literal key ``"audio"``, so any other mismatched key (e.g. a
+    codec-frame key routed to CONCAT_DIM0) was corrupted instead of
+    failing loudly.
+    """
+    payload = MultimodalPayload()
+    payload.tensors["latent.frames"] = [torch.zeros(2, 8), torch.zeros(3, 9)]
+
+    with pytest.raises(RuntimeError, match="latent.frames"):
+        payload.consolidate_tensors(OutputModality.LATENT)
diff --git a/vllm_omni/model_executor/models/qwen3_tts/pipeline.py b/vllm_omni/model_executor/models/qwen3_tts/pipeline.py
index 6dfe8736d8f..dd33aeca8bb 100644
--- a/vllm_omni/model_executor/models/qwen3_tts/pipeline.py
+++ b/vllm_omni/model_executor/models/qwen3_tts/pipeline.py
@@ -10,9 +10,23 @@
     StageExecutionType,
     StagePipelineConfig,
 )
+from vllm_omni.outputs.output_modality import (
+    TensorAccumulationStrategy,
+    register_key_accumulation_strategy,
+)
 
 _PROC = "vllm_omni.model_executor.stage_input_processors.qwen3_tts"
 
+# The talker's codec-frame keys are not waveform chunks, so they must not go
+# through the AUDIO modality's waveform-tuned default (CONCAT_LAST) whenever
+# a stage carrying them consolidates its output under that modality (e.g. an
+# AUDIO-typed final stage that forwards them directly instead of routing
+# through code2wav): ``codes.audio`` grows one row per decode step along
+# dim 0, and ``codes.ref`` re-emits the constant reference-context matrix
+# unchanged at every step.
+register_key_accumulation_strategy("codes.audio", TensorAccumulationStrategy.CONCAT_DIM0)
+register_key_accumulation_strategy("codes.ref", TensorAccumulationStrategy.REPLACE)
+
 QWEN3_TTS_PIPELINE = PipelineConfig(
     model_type="qwen3_tts",
     default_deploy_config_name="qwen3_tts.yaml",
diff --git a/vllm_omni/outputs/mm_outputs.py b/vllm_omni/outputs/mm_outputs.py
index b1393ba1924..45d1fc6fcdd 100644
--- a/vllm_omni/outputs/mm_outputs.py
+++ b/vllm_omni/outputs/mm_outputs.py
@@ -16,7 +16,11 @@
 from vllm.logger import init_logger
 from vllm.outputs import CompletionOutput
 
-from vllm_omni.outputs.output_modality import TensorAccumulationStrategy
+from vllm_omni.outputs.output_modality import (
+    OutputModality,
+    TensorAccumulationStrategy,
+    get_accumulation_strategy,
+)
 from vllm_omni.outputs.utils import _is_tensor_list, _to_cpu
 
 logger = init_logger(__name__)
@@ -46,21 +50,24 @@ def _consolidate_tensor_list(
     tensor_list: list[torch.Tensor],
     strategy: TensorAccumulationStrategy,
 ) -> torch.Tensor:
-    """Concatenate a deferred tensor list, with fallbacks on shape mismatch."""
+    """Concatenate a deferred tensor list, with a fallback for CONCAT_LAST only.
+
+    A shape mismatch under CONCAT_LAST is expected for genuine audio waveform
+    chunks (their non-last dims can vary between async-chunk steps), so that
+    case falls back to flattening each chunk before concatenating. Any other
+    strategy failing to concatenate means the tensors are not shaped the way
+    that strategy assumes (e.g. a key was assigned the wrong strategy), so it
+    is surfaced instead of silently keeping only the last chunk.
+    """
     try:
         return _cat_tensors(tensor_list, strategy)
-    except RuntimeError:
-        # [TODO: this part is for async chunk, not for audio only. can we come up with a design
-        # that identify this by whether using async chunk instead of modality?]
-        if key != "audio":
-            logger.warning("Error concatenating tensor for key %s; keeping last tensor", key)
-            return tensor_list[-1]
-        # Audio chunks may have mismatched shapes; retry along the last dim,
-        # then fall back to flattening each chunk.
-        try:
-            return torch.cat(tensor_list, dim=-1)
-        except RuntimeError:
-            return torch.cat([chunk.reshape(-1) for chunk in tensor_list], dim=0)
+    except RuntimeError as exc:
+        if strategy is not TensorAccumulationStrategy.CONCAT_LAST:
+            raise RuntimeError(
+                f"Error concatenating tensor list for key {key!r} under strategy {strategy}: {exc}"
+            ) from exc
+        logger.warning("CONCAT_LAST failed for key %s; flattening each chunk before concatenating", key)
+        return torch.cat([chunk.reshape(-1) for chunk in tensor_list], dim=0)
 
 
 def _append_entries(store: dict[str, Any], incoming: dict[str, Any]) -> None:
@@ -167,12 +174,17 @@ def merged_with(self, incoming: MultimodalPayload) -> MultimodalPayload:
             self.metadata[key] = value
         return self
 
-    def consolidate_tensors(self, strategy: TensorAccumulationStrategy) -> None:
+    def consolidate_tensors(self, modality: OutputModality) -> None:
         """Concatenate deferred tensor lists into single tensors.
 
-        Tensors are generated content accumulated as chunks, so lists are
-        concatenated according to *strategy* (e.g. audio chunks along the
-        time dimension, latent frames along the batch dimension).
+        Tensors are generated content accumulated as chunks, so each key's
+        list is concatenated according to the strategy
+        ``get_accumulation_strategy(modality, key)`` resolves for it (e.g.
+        audio waveform chunks along the time dimension, latent frames along
+        the batch dimension). Most keys share *modality*'s default, but a
+        key can be registered for a different strategy -- e.g. a codec-frame
+        matrix that grows along dim 0 rather than the waveform-tuned default
+        for its modality -- via ``register_key_accumulation_strategy``.
         """
         # Relocate scalar metadata tensors (e.g. sample rate) that from_dict
         # routed into .tensors, so they take the REPLACE path via .metadata
@@ -185,6 +197,7 @@ def consolidate_tensors(self, strategy: TensorAccumulationStrategy) -> None:
 
         for key, value in list(self.tensors.items()):
             if _is_tensor_list(value):
+                strategy = get_accumulation_strategy(modality, key)
                 self.tensors[key] = _consolidate_tensor_list(key, value, strategy)
 
     def consolidate_metadata(self) -> None:
diff --git a/vllm_omni/outputs/output_modality.py b/vllm_omni/outputs/output_modality.py
index 7cdbc1f1966..412e6161905 100644
--- a/vllm_omni/outputs/output_modality.py
+++ b/vllm_omni/outputs/output_modality.py
@@ -115,8 +115,43 @@ class TensorAccumulationStrategy(Enum):
     """Replace previous tensor entirely with the latest one."""
 
 
-def get_accumulation_strategy(modality: OutputModality) -> TensorAccumulationStrategy:
-    """Determine tensor merge strategy from the multimodal flags."""
+# Per-tensor-key overrides for the modality-wide default below. A modality
+# is a coarse hint (e.g. AUDIO tensors are usually waveform chunks that grow
+# along the last dimension), but some models emit tensors under that same
+# modality whose accumulation semantics differ -- e.g. discrete codec-frame
+# matrices that grow along dim 0, or a constant reference/context tensor
+# re-emitted unchanged at every step. Pipelines that produce such keys
+# register the correct strategy here via ``register_key_accumulation_strategy``
+# instead of forcing every tensor of the modality through one default.
+_KEY_ACCUMULATION_OVERRIDES: dict[str, TensorAccumulationStrategy] = {}
+
+
+def register_key_accumulation_strategy(key: str, strategy: TensorAccumulationStrategy) -> None:
+    """Register a per-key override for ``get_accumulation_strategy``.
+
+    Args:
+        key: The flattened multimodal output key this override applies to,
+            e.g. ``"codes.audio"`` as produced by
+            ``vllm_omni.data_entry_keys.flatten_payload`` from a nested
+            ``{"codes": {"audio": tensor}}`` payload.
+        strategy: The accumulation strategy to use for this key, regardless
+            of the modality its request is otherwise associated with.
+    """
+    _KEY_ACCUMULATION_OVERRIDES[key] = strategy
+
+
+def get_accumulation_strategy(
+    modality: OutputModality,
+    key: str | None = None,
+) -> TensorAccumulationStrategy:
+    """Determine the tensor merge strategy for one output key.
+
+    A registered per-key override (see ``register_key_accumulation_strategy``)
+    always wins; otherwise the strategy falls back to the modality-wide
+    default.
+    """
+    if key is not None and key in _KEY_ACCUMULATION_OVERRIDES:
+        return _KEY_ACCUMULATION_OVERRIDES[key]
     if OutputModality.AUDIO in modality:
         return TensorAccumulationStrategy.CONCAT_LAST
     if OutputModality.IMAGE in modality or OutputModality.LATENT in modality:
diff --git a/vllm_omni/outputs/output_processor.py b/vllm_omni/outputs/output_processor.py
index bd60e479397..5d2ede43d98 100644
--- a/vllm_omni/outputs/output_processor.py
+++ b/vllm_omni/outputs/output_processor.py
@@ -28,7 +28,7 @@
     is_non_final_delta_audio_chunk,
     replace_snapshot_keys,
 )
-from vllm_omni.outputs.output_modality import OutputModality, get_accumulation_strategy
+from vllm_omni.outputs.output_modality import OutputModality
 
 logger = init_logger(__name__)
 
@@ -140,8 +140,8 @@ def _consolidate_multimodal_tensors(self) -> None:
         """Consolidate accumulated tensor lists into single tensors.
 
         Uses TensorAccumulationStrategy derived from the output modality
-        to determine concatenation behavior. Metadata values always use
-        REPLACE (keep latest).
+        (with any per-key override applied) to determine concatenation
+        behavior. Metadata values always use REPLACE (keep latest).
         """
         if self.mm_accumulated.is_empty:
             return
@@ -150,10 +150,9 @@ def _consolidate_multimodal_tensors(self) -> None:
             modality = OutputModality.from_string(self.mm_type)
         except (ValueError, KeyError):
             modality = OutputModality.TEXT
-        strategy = get_accumulation_strategy(modality)
 
         try:
-            self.mm_accumulated.consolidate_tensors(strategy)
+            self.mm_accumulated.consolidate_tensors(modality)
             self.mm_accumulated.consolidate_metadata()
         except (RuntimeError, TypeError, KeyError):
             logger.exception("Error consolidating multimodal tensors")

From 275720b3782a321427b0a58a7efc2827bf583a62 Mon Sep 17 00:00:00 2001
From: Zheng Wengang <zwg0606@gmail.com>
Date: Wed, 16 Sep 2026 11:43:30 +0800
Subject: [PATCH 021/105] [Bugfix] Keep async video jobs queued until inference
 and abort on delete (#6759)

Signed-off-by: ZhengWG <zwg0606@gmail.com>
Signed-off-by: wuli666 <421774554@qq.com>
Co-authored-by: wuli666 <421774554@qq.com>
---
 docs/configuration/environment_variables.md   |   1 +
 docs/serving/videos_api.md                    |  10 +
 tests/config/test_environment_variables.py    |   2 +-
 tests/diffusion/test_diffusion_engine.py      |  29 ++-
 .../test_diffusion_output_formatter.py        |  11 +
 .../test_inline_stage_diffusion_client.py     |  46 +++-
 tests/diffusion/test_stage_diffusion_proc.py  |  44 ++++
 .../openai_api/test_video_server.py           | 202 +++++++++++++++++-
 tests/entrypoints/test_async_omni.py          |  55 ++++-
 tests/entrypoints/test_omni_entrypoints.py    |   3 +-
 .../config/environment_variable_inventory.py  |   1 +
 vllm_omni/diffusion/data.py                   |  15 ++
 vllm_omni/diffusion/diffusion_engine.py       |  24 ++-
 .../inline_stage_diffusion_client.py          |  13 +-
 vllm_omni/diffusion/output_formatter.py       |   4 +-
 vllm_omni/diffusion/stage_diffusion_proc.py   |  21 +-
 vllm_omni/engine/orchestrator.py              |   7 +-
 vllm_omni/entrypoints/async_omni.py           |  35 ++-
 vllm_omni/entrypoints/openai/api_server.py    |  32 ++-
 vllm_omni/entrypoints/openai/serving_video.py |  27 ++-
 .../openai/video/generation/helpers.py        |   6 +-
 vllm_omni/inputs/data.py                      |   5 +
 22 files changed, 549 insertions(+), 44 deletions(-)

diff --git a/docs/configuration/environment_variables.md b/docs/configuration/environment_variables.md
index 3a37b52d2ce..331487facc3 100644
--- a/docs/configuration/environment_variables.md
+++ b/docs/configuration/environment_variables.md
@@ -82,6 +82,7 @@ depends on the installed kernels and model path.
 | --- | --- | --- | --- | --- |
 | `SPEAKER_SAMPLES_DIR` | Filesystem path; default `~/.cache/vllm-omni/speakers` | Speech server; read when speaker storage initializes | Environment-only setting. The directory is created; filesystem errors propagate. | Stable |
 | `SPEAKER_MAX_UPLOADED` | Integer; default `1000` | Speech server; read when speaker storage initializes | Environment-only setting. A non-integer logs a warning and uses `1000`; range is not otherwise validated. | Stable |
+| `VLLM_OMNI_ABORT_TIMEOUT` | Float seconds; default `2` | Engine abort wait for Videos DELETE and `generate()` cancel/error cleanup; read when `async_omni` imports | Environment-only setting. A non-float raises `ValueError` during import. | Experimental |
 | `VLLM_OMNI_ASYNC_OUTPUT_TIMEOUT` | Float seconds; default `600` | Diffusion engine async-output wait in `step_streaming`; resolved per call on the request path, not at import | Environment-only setting. A non-float or `<=0` value warns once and uses the default. | Experimental |
 | `VLLM_OMNI_EVENT_DRIVEN_ORCH` | `1`, `true`, `yes` or `on` enables; default `0` (off) | Orchestration loop and the serving-side final-output drain; read once when the `Orchestrator` is constructed | Environment-only setting. Values are stripped and case-normalized; any unrecognized value leaves the legacy poll loop selected. | Experimental |
 | `VLLM_OMNI_INPUT_WAIT_TIMEOUT_S` | Float seconds; default `600`; `<=0` disables | Full-payload input coordinator, not async-chunk transfer; read when the scheduler module imports in each worker | Environment-only setting. A non-float logs a warning and uses `600`. | Stable operational control |
diff --git a/docs/serving/videos_api.md b/docs/serving/videos_api.md
index c6e91df60e5..1152ebce376 100644
--- a/docs/serving/videos_api.md
+++ b/docs/serving/videos_api.md
@@ -109,6 +109,16 @@ curl -L "http://localhost:8091/v1/videos/${video_id}/content" -o output.mp4
 The final content is available from `/v1/videos/{video_id}/content` after the
 job status becomes `completed`.
 
+`queued` means the request is still waiting for diffusion scheduler admission.
+The status changes to `in_progress` when the scheduler first selects the
+request for execution.
+
+`DELETE /v1/videos/{video_id}` issues a bounded engine abort
+(`VLLM_OMNI_ABORT_TIMEOUT`, default 2s), then cancels the frontend
+task. Cancellation cleanup is also bounded and best-effort: it confirms
+the abort was queued, and the current request batch may still drain.
+The job is then re-read so a completed save is not orphaned.
+
 ### Synchronous Response
 
 `POST /v1/videos/sync` blocks until generation finishes and returns raw video
diff --git a/tests/config/test_environment_variables.py b/tests/config/test_environment_variables.py
index ce608dca3cf..b7306268903 100644
--- a/tests/config/test_environment_variables.py
+++ b/tests/config/test_environment_variables.py
@@ -164,7 +164,7 @@ def test_inventory_matches_reviewed_snapshot_counts():
     """Make an inventory expansion an explicit review decision."""
     category_counts = Counter(item.category for item in ENVIRONMENT_VARIABLE_INVENTORY.values())
     assert category_counts == {
-        EnvironmentVariableCategory.PUBLIC_OMNI: 27,
+        EnvironmentVariableCategory.PUBLIC_OMNI: 28,
         EnvironmentVariableCategory.INHERITED_VLLM: 20,
         EnvironmentVariableCategory.PLATFORM_EXTERNAL: 27,
         EnvironmentVariableCategory.MODEL_SPECIFIC: 64,
diff --git a/tests/diffusion/test_diffusion_engine.py b/tests/diffusion/test_diffusion_engine.py
index 1ee7424e9df..77a6da5db56 100644
--- a/tests/diffusion/test_diffusion_engine.py
+++ b/tests/diffusion/test_diffusion_engine.py
@@ -15,7 +15,12 @@
 
 import vllm_omni.diffusion.diffusion_engine as diffusion_engine_module
 from tests.helpers.mark import hardware_test
-from vllm_omni.diffusion.data import DiffusionOutput, OmniDiffusionConfig
+from vllm_omni.diffusion.data import (
+    DIFFUSION_REQUEST_LIFECYCLE_KEY,
+    DIFFUSION_REQUEST_STARTED,
+    DiffusionOutput,
+    OmniDiffusionConfig,
+)
 from vllm_omni.diffusion.diffusion_engine import (
     DiffusionEngine,
     DiffusionExecutionMode,
@@ -183,6 +188,28 @@ def _make_request_mode_sched_output(*request_ids: str) -> RealDiffusionScheduler
     )
 
 
+@pytest.mark.cpu
+def test_request_started_output_is_emitted_only_for_opted_in_requests() -> None:
+    sched_output = _make_request_mode_sched_output("tracked", "untracked")
+    sched_output.scheduled_new_reqs[0].req.sampling_params.emit_request_lifecycle = True
+    engine = object.__new__(DiffusionEngine)
+    emitted = []
+    engine._put_output = lambda request_id, output: emitted.append((request_id, output))
+
+    engine._emit_request_started_outputs(sched_output)
+
+    assert len(emitted) == 1
+    request_id, output = emitted[0]
+    assert request_id == "tracked"
+    assert output.request_started is True
+    assert output.finished is False
+    [formatted] = engine.postprocess_output(sched_output.scheduled_new_reqs[0].req, output)
+    assert formatted.custom_output == {
+        DIFFUSION_REQUEST_LIFECYCLE_KEY: DIFFUSION_REQUEST_STARTED,
+    }
+    assert formatted.finished is False
+
+
 class TestRequestBatchCapability:
     pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
 
diff --git a/tests/diffusion/test_diffusion_output_formatter.py b/tests/diffusion/test_diffusion_output_formatter.py
index 4578d836822..a1dfec63757 100644
--- a/tests/diffusion/test_diffusion_output_formatter.py
+++ b/tests/diffusion/test_diffusion_output_formatter.py
@@ -443,3 +443,14 @@ def test_format_empty_diffusion_outputs_preserves_empty_response_shape() -> None
     assert [result.prompt for result in results] == ["prompt-0"]
     assert [result.images for result in results] == [[]]
     assert [result.metrics for result in results] == [{}]
+
+
+def test_format_empty_diffusion_outputs_preserves_custom_output() -> None:
+    [result] = format_empty_diffusion_outputs(
+        _request("prompt-0"),
+        finished=False,
+        custom_output={"lifecycle": "started"},
+    )
+
+    assert result.custom_output == {"lifecycle": "started"}
+    assert result.finished is False
diff --git a/tests/diffusion/test_inline_stage_diffusion_client.py b/tests/diffusion/test_inline_stage_diffusion_client.py
index e39c18ff480..3eadc53c185 100644
--- a/tests/diffusion/test_inline_stage_diffusion_client.py
+++ b/tests/diffusion/test_inline_stage_diffusion_client.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from __future__ import annotations
 
 import asyncio
@@ -7,7 +10,11 @@
 import pytest
 from vllm.v1.engine.exceptions import EngineDeadError
 
-from vllm_omni.diffusion.data import OmniDiffusionConfig
+from vllm_omni.diffusion.data import (
+    DIFFUSION_REQUEST_LIFECYCLE_KEY,
+    DIFFUSION_REQUEST_STARTED,
+    OmniDiffusionConfig,
+)
 from vllm_omni.diffusion.inline_stage_diffusion_client import InlineStageDiffusionClient
 from vllm_omni.engine.stage_init_utils import StageMetadata
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
@@ -80,6 +87,43 @@ async def _step_streaming(_request):
     assert output.request_id == "req-1"
 
 
+@pytest.mark.asyncio
+async def test_inline_non_streaming_dispatches_lifecycle_before_final(client, mock_engine):
+    lifecycle = OmniRequestOutput.from_diffusion(
+        request_id="req-lifecycle",
+        images=[],
+        custom_output={DIFFUSION_REQUEST_LIFECYCLE_KEY: DIFFUSION_REQUEST_STARTED},
+        finished=False,
+    )
+    intermediate = OmniRequestOutput.from_diffusion(
+        request_id="req-lifecycle",
+        images=[],
+        custom_output={"chunk": 0},
+        finished=False,
+    )
+    final = OmniRequestOutput.from_diffusion(request_id="req-lifecycle", images=[MagicMock()])
+
+    async def _step_streaming(_request):
+        yield [lifecycle]
+        yield [intermediate]
+        yield [final]
+
+    mock_engine.step_streaming = _step_streaming
+
+    await client.add_request_async("req-lifecycle", "A test prompt", OmniDiffusionSamplingParams())
+
+    outputs = []
+    for _ in range(20):
+        output = client.get_diffusion_output_nowait()
+        if output is not None:
+            outputs.append(output)
+            if output.finished:
+                break
+        await asyncio.sleep(0.01)
+
+    assert outputs == [lifecycle, final]
+
+
 @pytest.mark.asyncio
 async def test_inline_requests_clone_shared_sampling_params(client, mock_engine):
     requests = []
diff --git a/tests/diffusion/test_stage_diffusion_proc.py b/tests/diffusion/test_stage_diffusion_proc.py
index 90e753c9b5d..c6b5761d9ec 100644
--- a/tests/diffusion/test_stage_diffusion_proc.py
+++ b/tests/diffusion/test_stage_diffusion_proc.py
@@ -9,6 +9,7 @@
 
 import vllm_omni.diffusion.stage_diffusion_proc as stage_diffusion_proc
 import vllm_omni.plugins as omni_plugins
+from vllm_omni.diffusion.data import DIFFUSION_REQUEST_LIFECYCLE_KEY, DIFFUSION_REQUEST_STARTED
 from vllm_omni.diffusion.stage_diffusion_proc import StageDiffusionProc
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.outputs import OmniRequestOutput
@@ -103,6 +104,49 @@ async def step_streaming(self, request):
     assert captured["request"].kv_sender_info == {0: {"host": "127.0.0.1"}}
 
 
+@pytest.mark.asyncio
+async def test_proc_non_streaming_forwards_lifecycle_before_final_output():
+    lifecycle = OmniRequestOutput.from_diffusion(
+        request_id="",
+        images=[],
+        custom_output={DIFFUSION_REQUEST_LIFECYCLE_KEY: DIFFUSION_REQUEST_STARTED},
+        finished=False,
+    )
+    intermediate = OmniRequestOutput.from_diffusion(
+        request_id="",
+        images=[],
+        custom_output={"chunk": 0},
+        finished=False,
+    )
+    final = OmniRequestOutput.from_diffusion(request_id="", images=[], finished=True)
+
+    class _LifecycleEngine:
+        async def step_streaming(self, request):
+            del request
+            yield [lifecycle]
+            yield [intermediate]
+            yield [final]
+
+    stage_proc = object.__new__(StageDiffusionProc)
+    stage_proc._engine = _LifecycleEngine()
+    intermediate_outputs = []
+
+    async def _capture(output):
+        intermediate_outputs.append(output)
+
+    result = await stage_proc._process_request(
+        request_id="req-lifecycle",
+        prompt="prompt",
+        sampling_params_dict=asdict(OmniDiffusionSamplingParams()),
+        on_request_started=_capture,
+    )
+
+    assert intermediate_outputs == [lifecycle]
+    assert lifecycle.request_id == "req-lifecycle"
+    assert result is final
+    assert result.request_id == "req-lifecycle"
+
+
 @pytest.mark.asyncio
 async def test_proc_process_request_with_batching_async_output():
     stage_proc = object.__new__(StageDiffusionProc)
diff --git a/tests/entrypoints/openai_api/test_video_server.py b/tests/entrypoints/openai_api/test_video_server.py
index 57b2daaf88e..2de5c4056b7 100644
--- a/tests/entrypoints/openai_api/test_video_server.py
+++ b/tests/entrypoints/openai_api/test_video_server.py
@@ -25,6 +25,7 @@
 from pytest_mock import MockerFixture
 from vllm import envs
 
+from vllm_omni.diffusion.data import DIFFUSION_REQUEST_LIFECYCLE_KEY, DIFFUSION_REQUEST_STARTED
 from vllm_omni.diffusion.utils.media_utils import mux_video_audio_bytes
 from vllm_omni.entrypoints.openai import api_server, video_api_utils
 from vllm_omni.entrypoints.openai.api_server import router
@@ -58,6 +59,7 @@ def __init__(
         multimodal_output=None,
         stage_durations=None,
         peak_memory_mb=0.0,
+        custom_output=None,
     ):
         self.multimodal_output = dict(multimodal_output or {"video": videos})
         if audios is not None:
@@ -66,6 +68,7 @@ def __init__(
             self.multimodal_output["audio_sample_rate"] = sample_rate
         self.stage_durations = stage_durations or {}
         self.peak_memory_mb = peak_memory_mb
+        self.custom_output = custom_output or {}
 
 
 class FakeAsyncOmni:
@@ -102,9 +105,17 @@ async def generate(self, prompt, request_id, sampling_params_list):
         ):
             self.captured_reference_video_bytes = [Path(item).read_bytes() for item in reference_videos]
         num_outputs = sampling_params_list[0].num_outputs_per_prompt
+        if sampling_params_list[0].emit_request_lifecycle:
+            yield MockVideoResult(
+                [],
+                custom_output={DIFFUSION_REQUEST_LIFECYCLE_KEY: DIFFUSION_REQUEST_STARTED},
+            )
         videos = [object() for _ in range(num_outputs)]
         yield MockVideoResult(videos)
 
+    async def abort(self, request_id, *, timeout=None):
+        del request_id, timeout
+
 
 def test_raw_and_base64_encoders_receive_persistent_converter(mocker: MockerFixture):
     engine = FakeAsyncOmni()
@@ -224,9 +235,18 @@ def set_stage_configs_if_missing(self, stage_configs):
             self.stage_configs = stage_configs
 
     async def generate_video_bytes(
-        self, request, reference_id, *, reference_image=None, reference_video=None, reference_audio=None
+        self,
+        request,
+        reference_id,
+        *,
+        reference_image=None,
+        reference_video=None,
+        reference_audio=None,
+        on_started=None,
     ):
         del request, reference_id, reference_image, reference_video, reference_audio
+        if on_started is not None:
+            await on_started()
         self.started.set()
         try:
             await asyncio.Future()
@@ -234,6 +254,104 @@ async def generate_video_bytes(
             self.cancelled.set()
             raise
 
+    async def abort_request(self, request_id):
+        del request_id
+
+
+class HangingAbortHandler(BlockingVideoHandler):
+    """Engine abort never returns; DELETE must time out and still cancel."""
+
+    async def abort_request(self, request_id):
+        del request_id
+        await asyncio.sleep(30)
+
+
+class CompletingDuringAbortHandler(BlockingVideoHandler):
+    """Finishes and persists output while DELETE is still awaiting abort."""
+
+    def __init__(self):
+        super().__init__()
+        self._finish = asyncio.Event()
+
+    async def generate_video_bytes(
+        self,
+        request,
+        reference_id,
+        *,
+        reference_image=None,
+        reference_video=None,
+        reference_audio=None,
+        on_started=None,
+    ):
+        del request, reference_image, reference_video, reference_audio
+        if on_started is not None:
+            await on_started()
+        self.started.set()
+        await self._finish.wait()
+        return b"late-complete", {}, 0.0, None
+
+    async def abort_request(self, request_id):
+        self._finish.set()
+        deadline = time.monotonic() + 2.0
+        while time.monotonic() < deadline:
+            job = await api_server.VIDEO_STORE.get(request_id)
+            if job is not None and job.status is VideoGenerationStatus.COMPLETED and job.file_name is not None:
+                return
+            await asyncio.sleep(0.01)
+        raise RuntimeError(f"video job {request_id} did not complete during abort")
+
+
+class SchedulerQueuedVideoHandler(BlockingVideoHandler):
+    """Parks after engine submission but before scheduler admission."""
+
+    def __init__(self):
+        super().__init__()
+        self.admit = threading.Event()
+        self.in_progress = threading.Event()
+
+    async def generate_video_bytes(
+        self,
+        request,
+        reference_id,
+        *,
+        reference_image=None,
+        reference_video=None,
+        reference_audio=None,
+        on_started=None,
+    ):
+        del request, reference_id, reference_image, reference_video, reference_audio
+        self.started.set()
+        try:
+            while not self.admit.is_set():
+                await asyncio.sleep(0.01)
+            if on_started is not None:
+                await on_started()
+            self.in_progress.set()
+            await asyncio.Future()
+        except asyncio.CancelledError:
+            self.cancelled.set()
+            raise
+
+
+class AbortTrackingOmni(FakeAsyncOmni):
+    def __init__(self):
+        super().__init__()
+        self.aborted: list[str] = []
+        self.entered = threading.Event()
+
+    async def generate(self, prompt, request_id, sampling_params_list):
+        del prompt, request_id, sampling_params_list
+        self.entered.set()
+        yield MockVideoResult(
+            [],
+            custom_output={DIFFUSION_REQUEST_LIFECYCLE_KEY: DIFFUSION_REQUEST_STARTED},
+        )
+        await asyncio.Future()
+
+    async def abort(self, request_id, *, timeout=None):
+        assert timeout is not None
+        self.aborted.append(request_id)
+
 
 class FakeServerSocket:
     def __init__(self):
@@ -592,12 +710,12 @@ def test_i2v_video_generation_resizes_input_to_requested_dimensions(test_client,
 
 def test_i2v_resize_policy_can_defer_to_pipeline(monkeypatch):
     engine = FakeAsyncOmni()
-    engine.get_diffusion_od_config = lambda: SimpleNamespace(
+    engine.get_diffusion_od_config = lambda: SimpleNamespace(  # type: ignore[method-assign]
         model="org/model",
         model_class_name="ExamplePipeline",
         revision="pinned-revision",
     )
-    captured = {}
+    captured: dict[str, str | None] = {}
 
     def fake_policy(model_class_name, *, model, revision=None):
         captured.update(
@@ -625,6 +743,7 @@ def fake_policy(model_class_name, *, model, revision=None):
         )
     )
 
+    assert engine.captured_prompt is not None
     input_image = engine.captured_prompt["multi_modal_data"]["image"]
     assert isinstance(input_image, Image.Image)
     assert input_image.size == (48, 32)
@@ -718,6 +837,7 @@ def test_video_generation_bridges_request_fields(generation_request, expected_nu
 
     asyncio.run(handler._run_and_extract(generation_request, "field-bridge"))
 
+    assert engine.captured_sampling_params_list is not None
     sampling = engine.captured_sampling_params_list[0]
     # Top-level ``seconds`` bridges into extra_args["duration"]; num_frames is
     # passed through (or derived as seconds x fps when omitted). No private
@@ -1503,7 +1623,7 @@ async def _generate(prompt, request_id, sampling_params_list):
             },
         )
 
-    engine.generate = _generate
+    engine.generate = _generate  # type: ignore[method-assign]
     mocker.patch(
         "vllm_omni.entrypoints.openai.serving_video.encode_video_base64",
         return_value="encoded-video",
@@ -2096,6 +2216,80 @@ def test_delete_in_progress_job_cancels_task_and_removes_metadata(test_client):
     assert retrieve_resp.status_code == 404
 
 
+def test_async_video_stays_queued_until_scheduler_admission(test_client):
+    handler = SchedulerQueuedVideoHandler()
+    test_client.app.state.openai_serving_video = handler
+
+    create_resp = test_client.post("/v1/videos", data={"prompt": "Queue this video"})
+    assert create_resp.status_code == 200
+    video_id = create_resp.json()["id"]
+    assert handler.started.wait(timeout=2.0)
+
+    queued = test_client.get(f"/v1/videos/{video_id}")
+    assert queued.status_code == 200
+    assert queued.json()["status"] == VideoGenerationStatus.QUEUED.value
+
+    handler.admit.set()
+    assert handler.in_progress.wait(timeout=2.0)
+    in_progress = test_client.get(f"/v1/videos/{video_id}")
+    assert in_progress.status_code == 200
+    assert in_progress.json()["status"] == VideoGenerationStatus.IN_PROGRESS.value
+
+    assert test_client.delete(f"/v1/videos/{video_id}").status_code == 200
+
+
+def test_delete_times_out_engine_abort_and_still_cancels(test_client, monkeypatch):
+    monkeypatch.setattr(api_server, "VIDEO_ABORT_TIMEOUT_S", 0.05)
+    handler = HangingAbortHandler()
+    test_client.app.state.openai_serving_video = handler
+
+    create_resp = test_client.post("/v1/videos", data={"prompt": "Hang abort"})
+    assert create_resp.status_code == 200
+    video_id = create_resp.json()["id"]
+    assert handler.started.wait(timeout=2.0)
+
+    started = time.monotonic()
+    delete_resp = test_client.delete(f"/v1/videos/{video_id}")
+    assert time.monotonic() - started < 2.0
+    assert delete_resp.status_code == 200
+    assert handler.cancelled.wait(timeout=2.0)
+
+
+def test_delete_removes_artifact_if_job_completes_during_abort(test_client):
+    handler = CompletingDuringAbortHandler()
+    test_client.app.state.openai_serving_video = handler
+
+    create_resp = test_client.post("/v1/videos", data={"prompt": "Complete during delete"})
+    assert create_resp.status_code == 200
+    video_id = create_resp.json()["id"]
+    assert handler.started.wait(timeout=2.0)
+
+    assert test_client.delete(f"/v1/videos/{video_id}").status_code == 200
+    file_path = os.path.join(api_server.STORAGE_MANAGER.storage_path, video_id)
+    assert not os.path.exists(file_path)
+    assert asyncio.run(api_server.VIDEO_STORE.get(video_id)) is None
+
+
+def test_delete_aborts_engine_request_before_cancelling_task(test_client):
+    engine = AbortTrackingOmni()
+    test_client.app.state.openai_serving_video = OmniOpenAIServingVideo.for_diffusion(
+        engine,
+        model_name="Wan-AI/Wan2.2-T2V-A14B-Diffusers",
+    )
+
+    create_resp = test_client.post("/v1/videos", data={"prompt": "Abort this video"})
+    assert create_resp.status_code == 200
+    video_id = create_resp.json()["id"]
+    assert engine.entered.wait(timeout=2.0)
+    _wait_for_status(test_client, video_id, VideoGenerationStatus.IN_PROGRESS.value)
+
+    delete_resp = test_client.delete(f"/v1/videos/{video_id}")
+    assert delete_resp.status_code == 200
+    assert delete_resp.json()["deleted"] is True
+    _wait_until(lambda: engine.aborted == [video_id])
+    assert asyncio.run(api_server.VIDEO_STORE.get(video_id)) is None
+
+
 def test_video_response_file_extension_is_robust():
     response = VideoResponse(model="test-model", prompt="Make something beautiful")
     assert response.file_extension == "mp4"
diff --git a/tests/entrypoints/test_async_omni.py b/tests/entrypoints/test_async_omni.py
index a69bcce099d..2379db78e24 100644
--- a/tests/entrypoints/test_async_omni.py
+++ b/tests/entrypoints/test_async_omni.py
@@ -12,6 +12,7 @@
 from tests.helpers.mark import hardware_test
 from tests.helpers.stage_config import get_deploy_config_path
 from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
+from vllm_omni.entrypoints import async_omni as async_omni_mod
 from vllm_omni.entrypoints.async_omni import AsyncOmni
 from vllm_omni.outputs import OmniRequestOutput
 
@@ -38,7 +39,8 @@ async def fake_add_request_async(*, request_id, prompt, sampling_params_list, fi
 
 
 def get_fake_abort(aborted_request_batches):
-    async def fake_abort_async(request_ids):
+    async def fake_abort_async(request_ids, timeout=None):
+        del timeout
         aborted_request_batches.append(list(request_ids))
 
     return fake_abort_async
@@ -196,8 +198,8 @@ async def run():
         release = asyncio.Event()
         seen_during_wait: list[int] = []
 
-        async def slow_abort_async(request_ids):
-            del request_ids
+        async def slow_abort_async(request_ids, timeout=None):
+            del request_ids, timeout
             seen_during_wait.append(len(omni.request_states))
             await release.wait()
 
@@ -224,8 +226,8 @@ async def slow_abort_async(request_ids):
 @pytest.mark.cpu
 def test_abort_propagates_engine_errors_without_popping_state():
     async def run():
-        async def failing_abort_async(request_ids):
-            del request_ids
+        async def failing_abort_async(request_ids, timeout=None):
+            del request_ids, timeout
             raise RuntimeError("orchestrator abort failed")
 
         omni = get_async_omni_instance(fake_abort_request=failing_abort_async)
@@ -253,7 +255,8 @@ async def run():
 
         queue: asyncio.Queue = asyncio.Queue()
 
-        async def abort_with_prefix(request_ids):
+        async def abort_with_prefix(request_ids, timeout=None):
+            del timeout
             rid = request_ids[0]
             engine_output = OmniRequestOutput(
                 request_id=rid,
@@ -308,8 +311,8 @@ def test_abort_enqueues_synthetic_finished_when_engine_returns_empty():
     async def run():
         queue: asyncio.Queue = asyncio.Queue()
 
-        async def empty_abort_async(request_ids):
-            del request_ids
+        async def empty_abort_async(request_ids, timeout=None):
+            del request_ids, timeout
             return []
 
         omni = get_async_omni_instance(fake_abort_request=empty_abort_async)
@@ -467,6 +470,42 @@ async def collect_outputs(request_id):
     asyncio.run(run_test())
 
 
+@pytest.mark.cpu
+def test_generate_cancel_bounds_cleanup_abort(monkeypatch):
+    """Cancelled generate() must not wait forever on a wedged orchestrator abort."""
+    monkeypatch.setattr(async_omni_mod, "ABORT_TIMEOUT_S", 0.05)
+
+    async def run():
+        seen_timeouts: list[float | None] = []
+
+        async def hanging_abort_async(request_ids, timeout=None):
+            del request_ids
+            seen_timeouts.append(timeout)
+            await asyncio.Event().wait()
+
+        omni = get_async_omni_instance(fake_abort_request=hanging_abort_async)
+
+        async def collect():
+            async for _ in omni.generate(
+                prompt={"prompt": "prompt"},
+                request_id="cancel-hang-abort",
+                sampling_params_list=[SimpleNamespace()],
+                output_modalities=["image"],
+            ):
+                pass
+
+        task = asyncio.create_task(collect())
+        await asyncio.sleep(0)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(task, timeout=1.0)
+        assert seen_timeouts
+        assert seen_timeouts[-1] == 0.05
+        assert omni.request_states == {}
+
+    asyncio.run(run())
+
+
 @pytest.mark.cpu
 def test_generate_cancellation_converges_after_engine_shutdown_starts(mocker):
     async def run_test():
diff --git a/tests/entrypoints/test_omni_entrypoints.py b/tests/entrypoints/test_omni_entrypoints.py
index 95059a06ed4..01264eaea81 100644
--- a/tests/entrypoints/test_omni_entrypoints.py
+++ b/tests/entrypoints/test_omni_entrypoints.py
@@ -167,7 +167,8 @@ def get_stage_metadata(self, stage_id: int) -> StageRuntimeInfo:
     def abort(self, request_ids: list[str]) -> None:
         self.aborted.append(list(request_ids))
 
-    async def abort_async(self, request_ids: list[str]) -> None:
+    async def abort_async(self, request_ids: list[str], timeout=None) -> None:
+        del timeout
         self.abort(request_ids)
 
     async def collective_rpc_async(self, **_: Any) -> list[Any]:
diff --git a/vllm_omni/config/environment_variable_inventory.py b/vllm_omni/config/environment_variable_inventory.py
index b5214720a4e..97782328d95 100644
--- a/vllm_omni/config/environment_variable_inventory.py
+++ b/vllm_omni/config/environment_variable_inventory.py
@@ -63,6 +63,7 @@ def is_public_omni(self) -> bool:
     "OMNI_DIFFUSION_SESSION_STATE_MANAGER_MAX_SESSIONS",
     "SPEAKER_MAX_UPLOADED",
     "SPEAKER_SAMPLES_DIR",
+    "VLLM_OMNI_ABORT_TIMEOUT",
     "VLLM_OMNI_ASYNC_OUTPUT_TIMEOUT",
     "VLLM_OMNI_EVENT_DRIVEN_ORCH",
     "VLLM_OMNI_FUSED_QK_NORM_ROPE_MIN_TOKENS",
diff --git a/vllm_omni/diffusion/data.py b/vllm_omni/diffusion/data.py
index c333fb11ade..10f8642c64c 100644
--- a/vllm_omni/diffusion/data.py
+++ b/vllm_omni/diffusion/data.py
@@ -1637,6 +1637,18 @@ def from_kwargs(cls, **kwargs: Any) -> "OmniDiffusionConfig":
         return cls(**cls.normalize_init_kwargs(kwargs))
 
 
+DIFFUSION_REQUEST_LIFECYCLE_KEY = "_diffusion_request_lifecycle"
+DIFFUSION_REQUEST_STARTED = "started"
+
+
+def is_diffusion_request_started_output(output: Any) -> bool:
+    custom_output = getattr(output, "custom_output", None)
+    return (
+        isinstance(custom_output, dict)
+        and custom_output.get(DIFFUSION_REQUEST_LIFECYCLE_KEY) == DIFFUSION_REQUEST_STARTED
+    )
+
+
 @dataclass
 class DiffusionOutput:
     """
@@ -1685,6 +1697,9 @@ class DiffusionOutput:
     # mode) and the receiving side must not initialise a stray CUDA context.
     to_cpu: bool = False
 
+    # Internal control-plane event emitted on first scheduler admission.
+    request_started: bool = False
+
     # Typed video-media contract. Declared last so the pre-existing positional
     # constructor order (output, trajectory_timesteps, ...) that out-of-tree
     # pipelines rely on is preserved. Mutually exclusive with ``output``.
diff --git a/vllm_omni/diffusion/diffusion_engine.py b/vllm_omni/diffusion/diffusion_engine.py
index 417090503f5..6e53b590985 100644
--- a/vllm_omni/diffusion/diffusion_engine.py
+++ b/vllm_omni/diffusion/diffusion_engine.py
@@ -26,6 +26,8 @@
 from vllm.v1.kv_cache_interface import KVCacheConfig
 
 from vllm_omni.diffusion.data import (
+    DIFFUSION_REQUEST_LIFECYCLE_KEY,
+    DIFFUSION_REQUEST_STARTED,
     DiffusionOutput,
     DiffusionRequestAbortedError,
     OmniDiffusionConfig,
@@ -55,7 +57,7 @@
 )
 from vllm_omni.diffusion.request import DUMMY_DIFFUSION_REQUEST_ID, OmniDiffusionRequest
 from vllm_omni.diffusion.sched import BaseScheduler, RequestScheduler, StepScheduler
-from vllm_omni.diffusion.sched.interface import DiffusionRequestStatus
+from vllm_omni.diffusion.sched.interface import DiffusionRequestStatus, DiffusionSchedulerOutput
 from vllm_omni.diffusion.worker.utils import BaseRunnerOutput, BatchRunnerOutput, RunnerOutput
 from vllm_omni.errors import client_error_from_metadata, is_client_error_status
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams, OmniTextPrompt
@@ -533,7 +535,12 @@ def postprocess_output(
                     error_type=output.error_type,
                 )
             raise RuntimeError(output.error)
-        logger.debug("Generation completed successfully.")
+        if output.request_started:
+            return format_empty_diffusion_outputs(
+                request,
+                finished=False,
+                custom_output={DIFFUSION_REQUEST_LIFECYCLE_KEY: DIFFUSION_REQUEST_STARTED},
+            )
 
         if output.media is not None:
             if output.output is not None:
@@ -599,6 +606,8 @@ def _busy_loop(self):
                 sched_output = self.scheduler.schedule()
                 self._scheduler_num_waiting_reqs = max(int(sched_output.num_waiting_reqs), 0)
 
+            self._emit_request_started_outputs(sched_output)
+
             if sched_output.is_empty:
                 self._emit_finished_outputs(sched_output.finished_req_ids, None)
                 continue
@@ -629,6 +638,17 @@ def _busy_loop(self):
         # Engine is stopping: fail any RPCs still queued so callers don't hang.
         self._fail_pending_rpcs(RuntimeError("DiffusionEngine is shutting down."))
 
+    def _emit_request_started_outputs(self, sched_output: DiffusionSchedulerOutput) -> None:
+        """Notify opted-in callers when requests leave the scheduler queue."""
+        for new_req in sched_output.scheduled_new_reqs:
+            request = getattr(new_req, "req", None)
+            sampling_params = getattr(request, "sampling_params", None)
+            if getattr(sampling_params, "emit_request_lifecycle", False):
+                self._put_output(
+                    new_req.request_id,
+                    DiffusionOutput(finished=False, request_started=True),
+                )
+
     def _wait_for_admission_if_needed_locked(self) -> None:
         """Apply scheduler admission policy while holding the engine condition.
 
diff --git a/vllm_omni/diffusion/inline_stage_diffusion_client.py b/vllm_omni/diffusion/inline_stage_diffusion_client.py
index 6c8cc236c6c..f583aba14da 100644
--- a/vllm_omni/diffusion/inline_stage_diffusion_client.py
+++ b/vllm_omni/diffusion/inline_stage_diffusion_client.py
@@ -19,7 +19,10 @@
 from vllm.logger import init_logger
 from vllm.v1.engine.exceptions import EngineDeadError
 
-from vllm_omni.diffusion.data import DiffusionRequestAbortedError
+from vllm_omni.diffusion.data import (
+    DiffusionRequestAbortedError,
+    is_diffusion_request_started_output,
+)
 from vllm_omni.diffusion.diffusion_engine import DiffusionEngine
 from vllm_omni.diffusion.request import OmniDiffusionRequest
 from vllm_omni.engine.stage_client import StageClientBase
@@ -158,7 +161,13 @@ async def _dispatch_request(
                 # only publish the final output.
                 result = None
                 async for results in self._engine.step_streaming(request):
-                    result = results[0]
+                    output = results[0]
+                    if is_diffusion_request_started_output(output):
+                        if not output.request_id:
+                            output.request_id = request_id
+                        self._output_queue.put_nowait(output)
+                        continue
+                    result = output
                 if result is None:
                     raise RuntimeError("Diffusion execution finished without output.")
                 if not result.request_id:
diff --git a/vllm_omni/diffusion/output_formatter.py b/vllm_omni/diffusion/output_formatter.py
index 62c2330d5bc..4074806e1d6 100644
--- a/vllm_omni/diffusion/output_formatter.py
+++ b/vllm_omni/diffusion/output_formatter.py
@@ -5,7 +5,7 @@
 
 from collections.abc import Mapping
 from dataclasses import dataclass, field
-from typing import TypeGuard, cast
+from typing import Any, TypeGuard, cast
 
 from vllm_omni.diffusion.data import DiffusionOutput, OmniDiffusionConfig
 from vllm_omni.diffusion.io_support import get_diffusion_output_type, supports_audio_output
@@ -106,6 +106,7 @@ def format_empty_diffusion_outputs(
     request: OmniDiffusionRequest,
     *,
     finished: bool = True,
+    custom_output: dict[str, Any] | None = None,
 ) -> list[OmniRequestOutput]:
     return [
         OmniRequestOutput.from_diffusion(
@@ -114,6 +115,7 @@ def format_empty_diffusion_outputs(
             prompt=request.prompt,
             metrics={},
             latents=None,
+            custom_output=custom_output,
             finished=finished,
         )
     ]
diff --git a/vllm_omni/diffusion/stage_diffusion_proc.py b/vllm_omni/diffusion/stage_diffusion_proc.py
index aedb730e3bb..220158f1fbc 100644
--- a/vllm_omni/diffusion/stage_diffusion_proc.py
+++ b/vllm_omni/diffusion/stage_diffusion_proc.py
@@ -13,7 +13,7 @@
 import contextlib
 import multiprocessing.connection
 import signal
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Awaitable, Callable
 from concurrent.futures import ThreadPoolExecutor
 from types import SimpleNamespace
 from typing import TYPE_CHECKING, Any
@@ -33,7 +33,10 @@
 )
 from vllm.v1.utils import shutdown
 
-from vllm_omni.diffusion.data import DiffusionRequestAbortedError
+from vllm_omni.diffusion.data import (
+    DiffusionRequestAbortedError,
+    is_diffusion_request_started_output,
+)
 from vllm_omni.diffusion.diffusion_engine import DiffusionEngine
 from vllm_omni.diffusion.request import OmniDiffusionRequest
 from vllm_omni.distributed.omni_connectors.utils.serialization import (
@@ -163,6 +166,7 @@ async def _process_request(
         prompt: Any,
         sampling_params_dict: dict,
         kv_sender_info: dict[str, Any] | None = None,
+        on_request_started: Callable[[OmniRequestOutput], Awaitable[None]] | None = None,
         kv_transfer_params: dict[str, Any] | None = None,
     ) -> OmniRequestOutput:
         """Build a diffusion request and consume DiffusionEngine.step_streaming() to completion."""
@@ -180,7 +184,13 @@ async def _process_request(
         # return the final output.
         result = None
         async for results in self._engine.step_streaming(request):
-            result = results[0]
+            output = results[0]
+            if is_diffusion_request_started_output(output) and on_request_started is not None:
+                if not output.request_id:
+                    output.request_id = request_id
+                await on_request_started(output)
+                continue
+            result = output
         if result is None:
             raise RuntimeError("Diffusion execution finished without output.")
         if not result.request_id:
@@ -354,11 +364,16 @@ async def _dispatch_request(
             """Process a single diffusion request and send the response."""
             try:
                 if not self._od_config.streaming_output:
+
+                    async def _send_request_started(output: OmniRequestOutput) -> None:
+                        await response_socket.send(encoder.encode({"type": "result", "output": output}))
+
                     result = await self._process_request(
                         request_id,
                         prompt,
                         sampling_params_dict,
                         kv_sender_info=kv_sender_info,
+                        on_request_started=_send_request_started,
                         kv_transfer_params=kv_transfer_params,
                     )
                     await response_socket.send(encoder.encode({"type": "result", "output": result}))
diff --git a/vllm_omni/engine/orchestrator.py b/vllm_omni/engine/orchestrator.py
index 498a9dc8950..75620bec9a2 100644
--- a/vllm_omni/engine/orchestrator.py
+++ b/vllm_omni/engine/orchestrator.py
@@ -35,6 +35,7 @@
 from vllm.v1.metrics.stats import IterationStats
 
 from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.diffusion.data import is_diffusion_request_started_output
 from vllm_omni.distributed.omni_connectors.utils.config import stage_receives_chunks
 from vllm_omni.engine import OmniEngineCoreRequest
 from vllm_omni.engine.cfg_companion_tracker import CfgCompanionTracker
@@ -1199,7 +1200,8 @@ async def _orchestration_loop(self) -> None:
                                 idle = False
                                 continue
 
-                            pool.record_output_timestamps([diffusion_output])
+                            if not is_diffusion_request_started_output(diffusion_output):
+                                pool.record_output_timestamps([diffusion_output])
                             processed = [diffusion_output]
                         else:
                             raw_outputs = await pool.poll_llm_raw_output(replica_id, timeout_s=0.001)
@@ -1441,7 +1443,8 @@ def _reconcile_readers() -> None:
                         if self._absorb_diffusion_metrics(stage_id, replica_id, payload):
                             self._orch_monitor.note_loop(idle=False)
                             continue
-                        pool.record_output_timestamps([payload])
+                        if not is_diffusion_request_started_output(payload):
+                            pool.record_output_timestamps([payload])
                         processed = [payload]
                     else:
                         processed = await self._process_llm_stage_outputs(
diff --git a/vllm_omni/entrypoints/async_omni.py b/vllm_omni/entrypoints/async_omni.py
index 0012039e0fb..993f0ca1edf 100644
--- a/vllm_omni/entrypoints/async_omni.py
+++ b/vllm_omni/entrypoints/async_omni.py
@@ -11,6 +11,7 @@
 from __future__ import annotations
 
 import asyncio
+import os
 import time
 import uuid
 from collections.abc import AsyncGenerator, Iterable, Mapping, Sequence
@@ -64,6 +65,8 @@
 # the janus queue's condition variable; this timeout only bounds how often the
 # orchestrator liveness check runs while the pipeline is idle.
 _FINAL_OUTPUT_BLOCKING_WAIT_S = 1.0
+# Shared DELETE / generate() cleanup abort bound. Env is the documented knob.
+ABORT_TIMEOUT_S = float(os.environ.get("VLLM_OMNI_ABORT_TIMEOUT", 2.0))
 
 
 class AsyncEventResolver:
@@ -661,12 +664,12 @@ async def generate(
 
         except (asyncio.CancelledError, GeneratorExit):
             self._record_request_failure_once(request_id, reason="client_disconnect")
-            await self._abort_internal_requests(request_id)
+            await self._abort_internal_requests(request_id, timeout=ABORT_TIMEOUT_S)
             logger.info(f"[AsyncOmni] Request {request_id} aborted.")
             raise
         except Exception as e:
             self._record_request_failure_once(request_id, reason="stage_error")
-            await self._abort_internal_requests(request_id)
+            await self._abort_internal_requests(request_id, timeout=ABORT_TIMEOUT_S)
             logger.info(f"[AsyncOmni] Request {request_id} failed (input error): {e}")
             raise
         finally:
@@ -1120,14 +1123,14 @@ def _coerce_stage_bool(result: Any) -> bool:
             return all(bool(item) for item in result)
         return bool(result)
 
-    async def abort(self, request_id: str | Iterable[str]) -> None:
+    async def abort(self, request_id: str | Iterable[str], *, timeout: float | None = None) -> None:
         """Abort request(s) via the Orchestrator."""
         request_ids = [request_id] if isinstance(request_id, str) else list(request_id)
         # Map the external user request IDs to internal IDs used by the Orchestrator.
         # NOTE: If the user request_id matches multiple requests, all of them will be
         # aborted. This is also what happens in this case in vLLM's output processor.
         internal_ids = [s.request_id for s in self.request_states.values() if s.external_request_id in request_ids]
-        await self._abort(internal_ids)
+        await self._abort(internal_ids, timeout=timeout)
 
     async def submit_interaction_async(
         self,
@@ -1169,16 +1172,32 @@ async def submit_interaction_async(
         if self.log_stats:
             logger.info("[AsyncOmni] Queued interaction for request %s", request_id)
 
-    async def _abort_internal_requests(self, request_id: str | Iterable[str]):
+    async def _abort_internal_requests(
+        self,
+        request_id: str | Iterable[str],
+        *,
+        timeout: float = ABORT_TIMEOUT_S,
+    ):
         """Abort request(s) via the Orchestrator given internal request IDs,
         which take the format <external_request_id>-<UUID>.
         """
         request_ids = [request_id] if isinstance(request_id, str) else list(request_id)
         # Request IDs are already internal, so we just need to get the matching states.
         internal_req_ids = [rid for rid in request_ids if rid in self.request_states]
-        await self._abort(internal_req_ids)
+        try:
+            # Unbind generate() if abort_async blocks in the executor.
+            await asyncio.wait_for(self._abort(internal_req_ids, timeout=timeout), timeout=timeout)
+        except TimeoutError:
+            logger.warning(
+                "[AsyncOmni] Timed out aborting %s after %.1fs; "
+                "engine abort is best-effort until the current batch drains",
+                ",".join(internal_req_ids),
+                timeout,
+            )
+        except Exception:
+            logger.exception("[AsyncOmni] Cleanup abort failed for %s", ",".join(internal_req_ids))
 
-    async def _abort(self, request_ids: list[str]) -> None:
+    async def _abort(self, request_ids: list[str], *, timeout: float | None = None) -> None:
         """Abort request IDs via the engine and enqueue terminal abort outputs.
 
         Waits for orchestrator abort acknowledgment, enqueues any AR terminal
@@ -1191,7 +1210,7 @@ async def _abort(self, request_ids: list[str]) -> None:
         registered yet, unbound replica, or orchestrator id drop), enqueue a
         synthetic finished abort so ``generate()`` cannot hang on ``queue.get``.
         """
-        abort_outputs = await self.engine.abort_async(request_ids) or []
+        abort_outputs = await self.engine.abort_async(request_ids, timeout=timeout) or []
         delivered: set[str] = set()
         for output_msg in abort_outputs:
             req_id = getattr(output_msg, "request_id", None)
diff --git a/vllm_omni/entrypoints/openai/api_server.py b/vllm_omni/entrypoints/openai/api_server.py
index 8acd1d6fa71..36b7544ee4e 100644
--- a/vllm_omni/entrypoints/openai/api_server.py
+++ b/vllm_omni/entrypoints/openai/api_server.py
@@ -86,7 +86,7 @@
 from vllm_omni.config.endpoint_policy import (
     shutdown_unsupported_routes,
 )
-from vllm_omni.entrypoints.async_omni import AsyncOmni
+from vllm_omni.entrypoints.async_omni import ABORT_TIMEOUT_S, AsyncOmni
 from vllm_omni.entrypoints.duplex.capability import should_enable_duplex_endpoint
 from vllm_omni.entrypoints.duplex.serving import OmniDuplexSessionHandler
 from vllm_omni.entrypoints.duplex.warmup import _warmup_duplex_realtime
@@ -201,6 +201,8 @@
 logger = init_logger(__name__)
 router = APIRouter()
 
+VIDEO_ABORT_TIMEOUT_S = ABORT_TIMEOUT_S
+
 profiler_router = APIRouter()
 
 
@@ -2518,11 +2520,11 @@ async def retrieve_video(video_id: str) -> VideoResponse | JSONResponse:
 
 
 @router.delete("/v1/videos/{video_id}")
-async def delete_video(video_id: str) -> VideoDeleteResponse:
+async def delete_video(video_id: str, raw_request: Request) -> VideoDeleteResponse:
     """Delete a stored video job and any generated output.
 
-    If the job is still queued or running, this endpoint first attempts to
-    cancel the in-flight generation task before removing the stored metadata.
+    In-flight jobs get a bounded engine abort, then frontend cancel. The job
+    is re-read afterwards so a completed save is not orphaned.
 
     Args:
         video_id: Identifier of the video job to delete.
@@ -2539,19 +2541,37 @@ async def delete_video(video_id: str) -> VideoDeleteResponse:
         raise HTTPException(status_code=404, detail="Video not found")
 
     if job.status in (VideoGenerationStatus.QUEUED, VideoGenerationStatus.IN_PROGRESS):
+        handler = raw_request.app.state.openai_serving_video
+        try:
+            await asyncio.wait_for(handler.abort_request(video_id), timeout=VIDEO_ABORT_TIMEOUT_S)
+        except asyncio.TimeoutError:
+            logger.warning(
+                "Timed out aborting video request %s after %.1fs; "
+                "engine abort is best-effort until the current batch drains",
+                video_id,
+                VIDEO_ABORT_TIMEOUT_S,
+            )
+        except Exception:
+            logger.exception("Failed to abort in-flight video request %s", video_id)
         task = await VIDEO_TASKS.get(video_id)
         if task is not None:
             task.cancel()
             try:
-                await asyncio.wait_for(task, timeout=2.0)
+                # Cancel cleanup may spend a full abort budget; +2s covers scheduling slack.
+                await asyncio.wait_for(task, timeout=VIDEO_ABORT_TIMEOUT_S + 2.0)
             except asyncio.TimeoutError:
                 raise HTTPException(status_code=409, detail="Cancellation in progress. Please try again later.")
             except asyncio.CancelledError:
                 pass
 
+        job = await VIDEO_STORE.get(video_id)
+        if job is None:
+            return VideoDeleteResponse(id=video_id, deleted=True)
+        if job.status in (VideoGenerationStatus.QUEUED, VideoGenerationStatus.IN_PROGRESS):
             await VIDEO_STORE.pop(video_id)
             return VideoDeleteResponse(id=job.id, deleted=True)
-    elif job.status is VideoGenerationStatus.FAILED:
+
+    if job.status is VideoGenerationStatus.FAILED:
         if job.file_name is not None:
             try:
                 await STORAGE_MANAGER.delete(video_id)
diff --git a/vllm_omni/entrypoints/openai/serving_video.py b/vllm_omni/entrypoints/openai/serving_video.py
index 5ff055fa2b1..9a24a1ef969 100644
--- a/vllm_omni/entrypoints/openai/serving_video.py
+++ b/vllm_omni/entrypoints/openai/serving_video.py
@@ -6,7 +6,7 @@
 import copy
 import math
 import time
-from collections.abc import Mapping
+from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass
 from functools import cached_property
 from http import HTTPStatus
@@ -19,9 +19,10 @@
 from vllm.engine.protocol import EngineClient
 from vllm.logger import init_logger
 
+from vllm_omni.diffusion.data import is_diffusion_request_started_output
 from vllm_omni.diffusion.model_metadata import get_diffusion_model_metadata
 from vllm_omni.diffusion.utils.media_utils import count_mp4_frames, normalize_preencode_batch_frames
-from vllm_omni.entrypoints.async_omni import AsyncOmni
+from vllm_omni.entrypoints.async_omni import ABORT_TIMEOUT_S, AsyncOmni
 from vllm_omni.entrypoints.openai.protocol.videos import (
     VideoAction,
     VideoData,
@@ -256,6 +257,9 @@ def for_diffusion(
     def shutdown(self) -> None:
         self._video_frame_converter.shutdown()
 
+    async def abort_request(self, request_id: str) -> None:
+        await self._engine_client.abort(request_id, timeout=ABORT_TIMEOUT_S)
+
     async def _run_and_extract(
         self,
         request: VideoGenerationRequest,
@@ -264,6 +268,7 @@ async def _run_and_extract(
         reference_image: ReferenceImage | None = None,
         reference_video: ReferenceVideo | None = None,
         reference_audio: ReferenceAudio | None = None,
+        on_started: Callable[[], Awaitable[None]] | None = None,
     ) -> VideoGenerationArtifacts:
         """Run the generation pipeline and extract video/audio/profiler outputs."""
         prompt: OmniTextPrompt = OmniTextPrompt(prompt=request.prompt, modalities=["video"])
@@ -444,7 +449,12 @@ async def _run_and_extract(
             gen_params.seed,
         )
 
-        result = await self._run_generation(prompt, gen_params, reference_id)
+        result = await self._run_generation(
+            prompt,
+            gen_params,
+            reference_id,
+            on_started=on_started,
+        )
         multimodal_output = self._extract_multimodal_output(result)
         metadata = multimodal_output.get("metadata") if isinstance(multimodal_output, dict) else {}
         common_metadata = metadata.get("common") if isinstance(metadata, dict) else {}
@@ -528,6 +538,7 @@ async def generate_video_bytes(
         reference_image: ReferenceImage | None = None,
         reference_video: ReferenceVideo | None = None,
         reference_audio: ReferenceAudio | None = None,
+        on_started: Callable[[], Awaitable[None]] | None = None,
     ) -> tuple[bytes, dict[str, float], float, VideoAction | None, dict[str, object]]:
         """Generate a video and return raw MP4 bytes, bypassing base64 encoding."""
         artifacts = await self._run_and_extract(
@@ -536,6 +547,7 @@ async def generate_video_bytes(
             reference_image=reference_image,
             reference_video=reference_video,
             reference_audio=reference_audio,
+            on_started=on_started,
         )
         if len(artifacts.videos) > 1:
             logger.warning(
@@ -641,6 +653,8 @@ async def _run_generation(
         prompt: OmniTextPrompt,
         gen_params: OmniDiffusionSamplingParams,
         request_id: str,
+        *,
+        on_started: Callable[[], Awaitable[None]] | None = None,
     ) -> object:
         stage_configs = self._stage_configs or getattr(self._engine_client, "stage_configs", None)
 
@@ -660,6 +674,7 @@ async def _run_generation(
 
         # Common generation logic for both paths
         engine_client = cast(AsyncOmni, self._engine_client)
+        gen_params.emit_request_lifecycle = on_started is not None
         sampling_params_list = build_stage_sampling_params_list(
             list(stage_configs),
             get_default_sampling_params_list(engine_client),
@@ -668,11 +683,17 @@ async def _run_generation(
         )
 
         result = None
+        started_notified = False
         async for output in engine_client.generate(
             prompt=prompt,
             request_id=request_id,
             sampling_params_list=sampling_params_list,
         ):
+            if is_diffusion_request_started_output(output):
+                if on_started is not None and not started_notified:
+                    await on_started()
+                    started_notified = True
+                continue
             result = output
 
         if result is None:
diff --git a/vllm_omni/entrypoints/openai/video/generation/helpers.py b/vllm_omni/entrypoints/openai/video/generation/helpers.py
index e23d876e5c1..4473fce071a 100644
--- a/vllm_omni/entrypoints/openai/video/generation/helpers.py
+++ b/vllm_omni/entrypoints/openai/video/generation/helpers.py
@@ -330,9 +330,12 @@ async def _run_video_generation_job(
         _cleanup_video_references(reference_video, reference_audio, control_path)
         return
 
-    await VIDEO_STORE.update_fields(video_id, {"status": VideoGenerationStatus.IN_PROGRESS})
     started_at = time.perf_counter()
     try:
+
+        async def _mark_started() -> None:
+            await VIDEO_STORE.update_fields(video_id, {"status": VideoGenerationStatus.IN_PROGRESS})
+
         video_bytes, stage_durations, peak_memory_mb, action, video_metadata = _unpack_video_generation_result(
             await handler.generate_video_bytes(
                 request,
@@ -340,6 +343,7 @@ async def _run_video_generation_job(
                 reference_image=reference_image,
                 reference_video=reference_video,
                 reference_audio=reference_audio,
+                on_started=_mark_started,
             )
         )
 
diff --git a/vllm_omni/inputs/data.py b/vllm_omni/inputs/data.py
index f9f0a9a9a67..287ddb3fb60 100644
--- a/vllm_omni/inputs/data.py
+++ b/vllm_omni/inputs/data.py
@@ -349,6 +349,11 @@ class OmniDiffusionSamplingParams:
     # results
     output: torch.Tensor | None = None
 
+    # Internal control-plane event used by asynchronous APIs. When enabled,
+    # the diffusion engine emits a non-terminal output when the scheduler
+    # first admits this request for execution.
+    emit_request_lifecycle: bool = False
+
     def __post_init__(self) -> None:
         if self.quality is not None and self.quality not in DIFFUSION_QUALITY_LEVELS:
             raise ValueError(f"quality must be one of {list(DIFFUSION_QUALITY_LEVELS)}, got {self.quality!r}")

From a2138b830fe01230f39f0149cce3d14eec0beec6 Mon Sep 17 00:00:00 2001
From: GXIN <37653830+gxxx-hum@users.noreply.github.com>
Date: Wed, 16 Sep 2026 12:50:00 +0800
Subject: [PATCH 022/105] [Feature][Qwen3-TTS] Make Code2Wav honor the stage
 dtype (#6059)

Signed-off-by: XIN GAO <1037396230@qq.com>
---
 tests/config/test_config_factory.py           | 20 +++++++
 .../qwen3_tts/test_qwen3_tts_code2wav.py      | 22 ++++++--
 tests/platforms/npu/test_310p_patches.py      | 52 ++++++++++++++++---
 vllm_omni/deploy/qwen3_tts.yaml               |  2 +
 .../deploy/qwen3_tts_high_concurrency.yaml    |  2 +
 .../models/qwen3_tts/qwen3_tts_code2wav.py    |  4 +-
 vllm_omni/platforms/npu/models/qwen3_tts.py   | 19 ++++---
 7 files changed, 100 insertions(+), 21 deletions(-)

diff --git a/tests/config/test_config_factory.py b/tests/config/test_config_factory.py
index 82c1fb32ea3..d1dc0fd6d2c 100644
--- a/tests/config/test_config_factory.py
+++ b/tests/config/test_config_factory.py
@@ -2587,6 +2587,26 @@ def test_qwen3_tts_rocm_disables_code2wav_outer_cudagraph(self):
         assert rocm.stages[0].enforce_eager is None
         assert rocm.stages[1].enforce_eager is True
 
+    @pytest.mark.parametrize("deploy_name", ["qwen3_tts.yaml", "qwen3_tts_high_concurrency.yaml"])
+    @pytest.mark.parametrize("platform", ["cuda", "npu", "rocm"])
+    def test_qwen3_tts_default_code2wav_dtype_is_bf16(self, deploy_name, platform):
+        deploy = load_deploy_config(Path(get_deploy_config_path(deploy_name)))
+        deploy = _apply_platform_overrides(deploy, platform=platform)
+        stages = merge_pipeline_deploy(resolve_pipeline_config("qwen3_tts"), deploy)
+
+        assert stages[1].yaml_engine_args["dtype"] == "bfloat16"
+
+    @pytest.mark.parametrize("deploy_name", ["qwen3_tts.yaml", "qwen3_tts_high_concurrency.yaml"])
+    @pytest.mark.parametrize("platform", ["cuda", "npu"])
+    @pytest.mark.parametrize("dtype", ["float32", "bfloat16", "float16"])
+    def test_qwen3_tts_propagates_explicit_code2wav_dtype(self, deploy_name, platform, dtype):
+        deploy = load_deploy_config(Path(get_deploy_config_path(deploy_name)))
+        deploy.stages[1].engine_extras["dtype"] = dtype
+        deploy = _apply_platform_overrides(deploy, platform=platform)
+        stages = merge_pipeline_deploy(resolve_pipeline_config("qwen3_tts"), deploy)
+
+        assert stages[1].yaml_engine_args["dtype"] == dtype
+
     def test_higgs_audio_v3_rocm_uses_triton_attention(self):
         deploy_path = Path(get_deploy_config_path("higgs_multimodal_qwen3.yaml"))
 
diff --git a/tests/model_executor/models/qwen3_tts/test_qwen3_tts_code2wav.py b/tests/model_executor/models/qwen3_tts/test_qwen3_tts_code2wav.py
index 64f9ac8de33..8ad2b519fb1 100644
--- a/tests/model_executor/models/qwen3_tts/test_qwen3_tts_code2wav.py
+++ b/tests/model_executor/models/qwen3_tts/test_qwen3_tts_code2wav.py
@@ -23,7 +23,7 @@ class _FakeDecoder(nn.Module):
     def __init__(self, total_upsample: int = _TOTAL_UPSAMPLE):
         super().__init__()
         self.total_upsample = total_upsample
-        self.decode_calls: list[dict[str, int]] = []
+        self.decode_calls: list[dict[str, int | tuple[int, ...]]] = []
         self.batched_decode_calls: list[dict[str, object]] = []
         self.decode_codes: list[torch.Tensor] = []
         self.cudagraph_calls: list[dict[str, int | torch.device]] = []
@@ -63,7 +63,7 @@ def batched_chunked_decode(
         chunk_size: int = 300,
         left_context_size: int = 25,
         max_batch_size: int = 0,
-    ) -> torch.Tensor:
+    ) -> list[torch.Tensor]:
         self.batched_decode_calls.append(
             {
                 "chunk_size": chunk_size,
@@ -91,8 +91,8 @@ def batched_chunked_decode(
         wav_len = frames * self.total_upsample + 6
         wav = torch.arange(wav_len, dtype=torch.float32).view(1, 1, -1)
         offsets = torch.arange(batch, dtype=torch.float32).view(batch, 1, 1) * 1000
-        outputs = wav.expand(batch, 1, wav_len) + offsets
-        return [outputs[row, :, : lengths[row] * self.total_upsample] for row in range(batch)]
+        batched_wav = wav.expand(batch, 1, wav_len) + offsets
+        return [batched_wav[row, :, : lengths[row] * self.total_upsample] for row in range(batch)]
 
     def enable_cudagraph(self, **kwargs):
         self.cudagraph_calls.append(kwargs)
@@ -131,6 +131,7 @@ def _make_model(
                 load_config=SimpleNamespace(),
                 model_config=SimpleNamespace(
                     model="unused",
+                    dtype=torch.bfloat16,
                     revision=None,
                     stage_connector_config=stage_connector_config,
                     async_chunk=async_chunk,
@@ -708,3 +709,16 @@ def test_invalid_decode_chunking_is_rejected():
 
     with pytest.raises(ValueError, match="decode_chunk_frames=0"):
         _load_weights_noop(model)
+
+
+@pytest.mark.parametrize("dtype", [torch.float32, torch.bfloat16, torch.float16])
+def test_load_weights_uses_model_dtype_before_precomputing_caches(dtype):
+    model = _make_model()
+    model.vllm_config.model_config.dtype = dtype
+    model.decoder = nn.Linear(2, 2)
+    cache_dtypes = []
+    model.decoder.precompute_snake_caches = lambda: cache_dtypes.append(model.decoder.weight.dtype)
+
+    assert _load_weights_noop(model) == {"decoder.fake_weight"}
+    assert model.decoder.weight.dtype is dtype
+    assert cache_dtypes == [dtype]
diff --git a/tests/platforms/npu/test_310p_patches.py b/tests/platforms/npu/test_310p_patches.py
index c19dcd99782..0db4b9d41b8 100644
--- a/tests/platforms/npu/test_310p_patches.py
+++ b/tests/platforms/npu/test_310p_patches.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Unit tests for 310P patch wiring.
 
 The tests load patch modules from source with fake Qwen3-TTS dependencies, so
@@ -644,7 +644,11 @@ def original_rope(q, k, cos, sin):
     torch.testing.assert_close(norm_out, torch.tensor([[2.0, 3.0]]))
 
 
-def test_qwen3_tts_code2wav_npu_patch_prepares_loaded_decoder(monkeypatch: pytest.MonkeyPatch) -> None:
+def _load_qwen3_tts_code2wav_npu_patch(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    platform_dtype_override: bool = True,
+):
     linear_weights = []
     conv_weights = []
 
@@ -674,15 +678,22 @@ def __init__(self, *, vllm_config, prefix=""):
             self.prefix = prefix
             self.decoder = FakeDecoder()
 
-        def _npu_decoder_runtime_dtype(self, _device):
-            return torch.float16
-
         def load_weights(self, weights):
             assert list(weights) == []
+            self.decoder.to(dtype=self.vllm_config.model_config.dtype)
+            self.decoder.precompute_snake_caches()
             return {"loaded"}
 
-    logger = SimpleNamespace(info=lambda *_: None, debug=lambda *_: None)
+    if platform_dtype_override:
+
+        def _npu_decoder_runtime_dtype(self, _device: torch.device) -> torch.dtype:
+            return torch.float16
+
+        FakeCode2Wav._npu_decoder_runtime_dtype = _npu_decoder_runtime_dtype  # type: ignore[attr-defined]
+
+    logger = SimpleNamespace(info=lambda *_: None, debug=lambda *_: None, warning=lambda *_: None)
     current_platform = SimpleNamespace(is_npu=lambda: False)
+
     target = _install_fake_module(
         monkeypatch,
         "vllm_omni.model_executor.models.qwen3_tts.qwen3_tts_code2wav",
@@ -702,11 +713,23 @@ def load_weights(self, weights):
     path = _repo_root() / "vllm_omni" / "platforms" / "npu" / "models" / "qwen3_tts.py"
     module = _load_source_module("vllm_omni_test_qwen3_tts_code2wav_npu_patch", path)
     module.apply_qwen3_tts_code2wav_patch()
+    return module, target, linear_weights, conv_weights
 
-    model = target.Qwen3TTSCode2Wav(
-        vllm_config=SimpleNamespace(device_config=SimpleNamespace(device=torch.device("cpu"))),
+
+def _make_patched_code2wav(target, *, dtype=torch.bfloat16):
+    return target.Qwen3TTSCode2Wav(
+        vllm_config=SimpleNamespace(
+            device_config=SimpleNamespace(device=torch.device("cpu")),
+            model_config=SimpleNamespace(dtype=dtype),
+        ),
         prefix="stage1",
     )
+
+
+def test_qwen3_tts_code2wav_npu_patch_prepares_loaded_decoder(monkeypatch: pytest.MonkeyPatch) -> None:
+    module, target, linear_weights, conv_weights = _load_qwen3_tts_code2wav_npu_patch(monkeypatch)
+    model = _make_patched_code2wav(target, dtype=torch.bfloat16)
+
     assert model.load_weights(iter(())) == {"loaded"}
 
     assert model.prefix == "stage1"
@@ -717,4 +740,17 @@ def load_weights(self, weights):
         model.decoder.deconv.weight.data_ptr(),
     }
     assert all(fmt == module._ACL_FORMAT_FRACTAL_Z for _, fmt in conv_weights)
+    assert model.decoder.cache_precompute_calls == 2
+
+
+@pytest.mark.parametrize("dtype", [torch.float32, torch.bfloat16, torch.float16])
+def test_qwen3_tts_code2wav_npu_patch_preserves_stage_dtype(
+    monkeypatch: pytest.MonkeyPatch,
+    dtype: torch.dtype,
+) -> None:
+    _, target, _, _ = _load_qwen3_tts_code2wav_npu_patch(monkeypatch, platform_dtype_override=False)
+    model = _make_patched_code2wav(target, dtype=dtype)
+
+    assert model.load_weights(iter(())) == {"loaded"}
+    assert all(parameter.dtype is dtype for parameter in model.decoder.parameters())
     assert model.decoder.cache_precompute_calls == 1
diff --git a/vllm_omni/deploy/qwen3_tts.yaml b/vllm_omni/deploy/qwen3_tts.yaml
index 747b688526d..4019f10aaa4 100644
--- a/vllm_omni/deploy/qwen3_tts.yaml
+++ b/vllm_omni/deploy/qwen3_tts.yaml
@@ -95,6 +95,8 @@ stages:
       top_p: 1.0
 
   - stage_id: 1
+    # Decoder compute dtype on GPU/NPU; 310P requires FP16 and overrides this.
+    dtype: bfloat16
     # Tuned for Base voice clone; CustomVoice / VoiceDesign are TTFA-optimal at 1.
     max_num_seqs: 64
     gpu_memory_utilization: 0.3
diff --git a/vllm_omni/deploy/qwen3_tts_high_concurrency.yaml b/vllm_omni/deploy/qwen3_tts_high_concurrency.yaml
index 7a73dd50aad..7914ecd5255 100644
--- a/vllm_omni/deploy/qwen3_tts_high_concurrency.yaml
+++ b/vllm_omni/deploy/qwen3_tts_high_concurrency.yaml
@@ -85,6 +85,8 @@ stages:
       top_p: 1.0
 
   - stage_id: 1
+    # Decoder compute dtype on GPU/NPU; 310P requires FP16 and overrides this.
+    dtype: bfloat16
     max_num_seqs: 10
     gpu_memory_utilization: 0.3
     enforce_eager: true
diff --git a/vllm_omni/model_executor/models/qwen3_tts/qwen3_tts_code2wav.py b/vllm_omni/model_executor/models/qwen3_tts/qwen3_tts_code2wav.py
index f1692f73de0..8ab5c5e340c 100644
--- a/vllm_omni/model_executor/models/qwen3_tts/qwen3_tts_code2wav.py
+++ b/vllm_omni/model_executor/models/qwen3_tts/qwen3_tts_code2wav.py
@@ -499,7 +499,7 @@ def _meta_bool(value: Any) -> bool:
             if wav.numel() == 0:
                 continue
             if wav.shape[0] > 0:
-                # Decoder already runs in fp32, so the .to(float32) is a redundant dispatch.
+                # Return FP32 audio regardless of the decoder compute dtype.
                 audios[idx] = (wav if wav.dtype == torch.float32 else wav.to(torch.float32)).reshape(-1)
 
         for req_id, finished, segment_finished in zip(
@@ -560,7 +560,7 @@ def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
         )
 
         device = self.vllm_config.device_config.device
-        self.decoder.to(device=device, dtype=torch.float32)
+        self.decoder.to(device=device, dtype=self.vllm_config.model_config.dtype)
 
         # Precompute SnakeBeta exp caches (benefits both Triton and eager paths)
         if hasattr(self.decoder, "precompute_snake_caches"):
diff --git a/vllm_omni/platforms/npu/models/qwen3_tts.py b/vllm_omni/platforms/npu/models/qwen3_tts.py
index a91d2cf80cd..124e606241b 100644
--- a/vllm_omni/platforms/npu/models/qwen3_tts.py
+++ b/vllm_omni/platforms/npu/models/qwen3_tts.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 """Patch Qwen3-TTS NPU runtime setup and weights.
 
@@ -68,11 +68,16 @@ def _patched_load_weights(self, weights):
     assert _original_load_weights is not None
     loaded = _original_load_weights(self, weights)
     device = self.vllm_config.device_config.device
-    runtime_dtype = getattr(self, "_npu_decoder_runtime_dtype", lambda _: torch.float32)(device)
-    self.decoder.to(device=device, dtype=runtime_dtype)
+    platform_dtype_override = getattr(self, "_npu_decoder_runtime_dtype", None)
+    if platform_dtype_override is not None:
+        # 310P requires FP16 and deliberately overrides the stage dtype.
+        runtime_dtype = platform_dtype_override(device)
+        self.decoder.to(device=device, dtype=runtime_dtype)
+        if hasattr(self.decoder, "precompute_snake_caches"):
+            self.decoder.precompute_snake_caches()
     _prepare_npu_decoder_weights(self.decoder)
-    if runtime_dtype != torch.float32 and hasattr(self.decoder, "precompute_snake_caches"):
-        self.decoder.precompute_snake_caches()
+    actual_dtype = next(self.decoder.parameters()).dtype
+    logger.info("Prepared NPU Code2Wav decoder with runtime dtype %s", actual_dtype)
     return loaded
 
 
@@ -108,8 +113,8 @@ class _Qwen3TTSPromptEmbedsBuilderA5(prompt_embeds_builder.Qwen3TTSPromptEmbedsB
 
     # The talker imports the builder by name at module scope, so its reference
     # must be swapped as well (same as the 310P patch).
-    prompt_embeds_builder.Qwen3TTSPromptEmbedsBuilder = _Qwen3TTSPromptEmbedsBuilderA5
-    qwen3_tts_talker.Qwen3TTSPromptEmbedsBuilder = _Qwen3TTSPromptEmbedsBuilderA5
+    setattr(prompt_embeds_builder, "Qwen3TTSPromptEmbedsBuilder", _Qwen3TTSPromptEmbedsBuilderA5)
+    setattr(qwen3_tts_talker, "Qwen3TTSPromptEmbedsBuilder", _Qwen3TTSPromptEmbedsBuilderA5)
     _A5_PATCHED = True
     logger.debug("Applied A5 prompt-embeds builder patch for Qwen3-TTS")
 

From 21d86ec9239d5aba08ea5fcac7e20a8f0679b0c9 Mon Sep 17 00:00:00 2001
From: vOv <124694036+cr-gao@users.noreply.github.com>
Date: Wed, 16 Sep 2026 13:01:26 +0800
Subject: [PATCH 023/105] [Diffusion] MAGI-2: regional compile coverage (#7174)

Signed-off-by: cr-gao <gaochenrui@sjtu.edu.cn>
---
 .../models/magi2/test_native_compile.py       | 137 +++++++++++++
 .../models/magi2/test_native_compile_cuda.py  |  77 +++++++
 .../magi2/test_native_compile_distributed.py  | 179 ++++++++++++++++
 .../models/magi2/test_native_packing.py       | 118 +++++++++++
 .../diffusion/models/magi2/modeling_magi2.py  | 194 +++++++++++++-----
 .../diffusion/models/magi2/pipeline_magi2.py  |  18 ++
 .../diffusion/models/magi2/sampler_magi2.py   |  28 +--
 7 files changed, 672 insertions(+), 79 deletions(-)
 create mode 100644 tests/diffusion/models/magi2/test_native_compile.py
 create mode 100644 tests/diffusion/models/magi2/test_native_compile_cuda.py
 create mode 100644 tests/diffusion/models/magi2/test_native_compile_distributed.py
 create mode 100644 tests/diffusion/models/magi2/test_native_packing.py

diff --git a/tests/diffusion/models/magi2/test_native_compile.py b/tests/diffusion/models/magi2/test_native_compile.py
new file mode 100644
index 00000000000..0abac75f877
--- /dev/null
+++ b/tests/diffusion/models/magi2/test_native_compile.py
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import pytest
+import torch
+
+from tests.diffusion.models.magi2.test_native_packing import (
+    _longer_text_tensors,
+    _sampler_tensors,
+    _tiny_model,
+    _tiny_sampler,
+)
+from vllm_omni.diffusion.models.magi2.sampler_magi2 import CFGConfig
+
+pytestmark = [pytest.mark.diffusion, pytest.mark.cpu, pytest.mark.core_model]
+
+
+def test_layer_regions_bracket_the_eager_kernels() -> None:
+    moe_layer, dense_layer = _tiny_model().block.layers
+
+    assert moe_layer.region_methods == ("_attention_input", "_moe_input", "_moe_output")
+    assert dense_layer.region_methods == ("_attention_input", "_dense_output")
+
+
+def test_compile_regions_fullgraph_matches_eager_bitwise() -> None:
+    model = _tiny_model()
+    sampler = _tiny_sampler(model)
+    steps = [
+        sampler.prepare_model_input(**_sampler_tensors(seed), t=t, cfg_config=CFGConfig())
+        for seed, t in enumerate((torch.tensor([900.0]), torch.tensor([450.0])))
+    ]
+    expected = [sampler.forward(step) for step in steps]
+
+    torch._dynamo.reset()
+    graphs_before = torch._dynamo.utils.counters["stats"]["unique_graphs"]
+    model.compile_regions(fullgraph=True, backend="eager", dynamic=True)
+    first = sampler.forward(steps[0])
+    graphs = torch._dynamo.utils.counters["stats"]["unique_graphs"] - graphs_before
+    with torch._dynamo.config.patch(error_on_recompile=True):
+        second = sampler.forward(steps[1])
+
+    for (video, audio), (video_ref, audio_ref) in zip((first, second), expected, strict=True):
+        assert torch.equal(video, video_ref)
+        assert torch.equal(audio, audio_ref)
+    # pre adapter, post adapter, three MoE-layer regions, two dense-layer regions
+    assert graphs == 7
+
+
+def test_pipeline_setup_compile_forwards_config_dynamic() -> None:
+    from vllm_omni.diffusion.data import OmniDiffusionConfig
+    from vllm_omni.diffusion.models.magi2.pipeline_magi2 import Magi2Pipeline
+
+    calls: list[dict[str, object]] = []
+
+    class _Transformer(torch.nn.Module):
+        def compile_regions(self, **compile_kwargs: object) -> None:
+            calls.append(compile_kwargs)
+
+    pipeline = object.__new__(Magi2Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = OmniDiffusionConfig(
+        model="sand-ai/MAGI-2-preview",
+        model_class_name="Magi2Pipeline",
+        diffusion_compile_dynamic=False,
+    )
+    pipeline.transformer = _Transformer()
+
+    pipeline.setup_compile()
+
+    assert calls == [{"fullgraph": True, "dynamic": False, "options": {"emulate_precision_casts": True}}]
+
+
+def test_pipeline_setup_compile_warns_when_granularity_is_not_regional(caplog: pytest.LogCaptureFixture) -> None:
+    from vllm_omni.diffusion.data import OmniDiffusionConfig
+    from vllm_omni.diffusion.models.magi2.pipeline_magi2 import Magi2Pipeline
+
+    calls: list[dict[str, object]] = []
+
+    class _Transformer(torch.nn.Module):
+        def compile_regions(self, **compile_kwargs: object) -> None:
+            calls.append(compile_kwargs)
+
+    pipeline = object.__new__(Magi2Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = OmniDiffusionConfig(
+        model="sand-ai/MAGI-2-preview",
+        model_class_name="Magi2Pipeline",
+        diffusion_compile_granularity="full",
+    )
+    pipeline.transformer = _Transformer()
+
+    pipeline.setup_compile()
+
+    assert calls == [{"fullgraph": True, "dynamic": True, "options": {"emulate_precision_casts": True}}]
+    assert "diffusion_compile_granularity='full'" in caplog.text
+
+
+def test_compiled_graphs_are_shared_across_layers_of_one_kind() -> None:
+    model = _tiny_model(moe_layers=2)
+    sampler = _tiny_sampler(model)
+    step = sampler.prepare_model_input(**_sampler_tensors(0), t=torch.tensor([900.0]), cfg_config=CFGConfig())
+    expected = sampler.forward(step)
+
+    torch._dynamo.reset()
+    graphs_before = torch._dynamo.utils.counters["stats"]["unique_graphs"]
+    model.compile_regions(fullgraph=True, backend="eager", dynamic=True)
+    actual = sampler.forward(step)
+
+    assert torch.equal(actual[0], expected[0])
+    # Two MoE layers and two dense layers still compile one graph per region
+    # kind: pre adapter, post adapter, three MoE regions, two dense regions.
+    assert torch._dynamo.utils.counters["stats"]["unique_graphs"] - graphs_before == 7
+
+
+def test_compiled_regions_survive_new_requests_without_recompiling() -> None:
+    model = _tiny_model()
+    sampler = _tiny_sampler(model)
+    t = torch.tensor([900.0])
+    first_request = sampler.prepare_model_input(**_sampler_tensors(0), t=t, cfg_config=CFGConfig())
+    second_request = sampler.prepare_model_input(**_sampler_tensors(1), t=t, cfg_config=CFGConfig())
+    longer_request = sampler.prepare_model_input(**_longer_text_tensors(2), t=t, cfg_config=CFGConfig())
+    expected = [sampler.forward(request) for request in (first_request, second_request, longer_request)]
+
+    torch._dynamo.reset()
+    graphs_before = torch._dynamo.utils.counters["stats"]["unique_graphs"]
+    model.compile_regions(fullgraph=True, backend="eager", dynamic=True)
+    actual = [sampler.forward(first_request)]
+    with torch._dynamo.config.patch(error_on_recompile=True):
+        actual.append(sampler.forward(second_request))
+        actual.append(sampler.forward(longer_request))
+
+    for (video, audio), (video_ref, audio_ref) in zip(actual, expected, strict=True):
+        assert torch.equal(video, video_ref)
+        assert torch.equal(audio, audio_ref)
+    assert torch._dynamo.utils.counters["stats"]["unique_graphs"] - graphs_before == 7
diff --git a/tests/diffusion/models/magi2/test_native_compile_cuda.py b/tests/diffusion/models/magi2/test_native_compile_cuda.py
new file mode 100644
index 00000000000..1db394750bb
--- /dev/null
+++ b/tests/diffusion/models/magi2/test_native_compile_cuda.py
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import pytest
+import torch
+
+from tests.diffusion.models.magi2.test_native_packing import (
+    _longer_text_tensors,
+    _sampler_tensors,
+    _tiny_model,
+    _tiny_sampler,
+)
+from tests.helpers.mark import hardware_marks
+from vllm_omni.diffusion.models.magi2.sampler_magi2 import CFGConfig
+
+pytestmark = [
+    pytest.mark.diffusion,
+    pytest.mark.core_model,
+    *hardware_marks(res={"cuda": "L4"}, num_cards=1),
+    pytest.mark.skipif(not torch.cuda.is_available(), reason="requires CUDA"),
+]
+
+
+def _cuda_steps(sampler, tensors=_sampler_tensors):
+    timesteps = (torch.tensor([900.0]), torch.tensor([600.0]), torch.tensor([300.0]))
+    return [
+        sampler.prepare_model_input(
+            **{name: value.cuda() for name, value in tensors(seed).items()},
+            t=t,
+            cfg_config=CFGConfig(),
+        )
+        for seed, t in enumerate(timesteps)
+    ]
+
+
+def test_inductor_regions_match_eager_in_deterministic_mode(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("MAGI2_DETERMINISTIC", "1")
+    model = _tiny_model(params_dtype=torch.bfloat16).cuda()
+    sampler = _tiny_sampler(model)
+    steps = _cuda_steps(sampler)
+    expected = [sampler.forward(step) for step in steps]
+    new_request_step = _cuda_steps(sampler)[0]
+    longer_text_step = _cuda_steps(sampler, _longer_text_tensors)[0]
+    expected_new_request = sampler.forward(new_request_step)
+    expected_longer_text = sampler.forward(longer_text_step)
+
+    torch._dynamo.reset()
+    graphs_before = torch._dynamo.utils.counters["stats"]["unique_graphs"]
+    # The pipeline compiles with inductor emulating eager's intermediate
+    # low-precision casts, so fused bf16 chains keep eager's rounding.
+    model.compile_regions(fullgraph=True, dynamic=True, options={"emulate_precision_casts": True})
+    first = sampler.forward(steps[0])
+    with torch._dynamo.config.patch(error_on_recompile=True):
+        compiled = [first, sampler.forward(steps[1]), sampler.forward(steps[2])]
+        repeated = [sampler.forward(step) for step in steps]
+        # A second request repacks the same shapes; a third changes the
+        # text length and therefore every token count.
+        compiled_new_request = sampler.forward(new_request_step)
+        compiled_longer_text = sampler.forward(longer_text_step)
+
+    # Emulated precision casts restore eager's rounding boundaries; what is
+    # left is one-ulp transcendental noise that some Triton backends carry.
+    for (video, audio), (video_ref, audio_ref) in zip(compiled, expected, strict=True):
+        torch.testing.assert_close(video, video_ref, atol=1e-6, rtol=0)
+        torch.testing.assert_close(audio, audio_ref, atol=1e-6, rtol=0)
+    for (video, audio), (video_again, audio_again) in zip(compiled, repeated, strict=True):
+        assert torch.equal(video, video_again)
+        assert torch.equal(audio, audio_again)
+    for (video, audio), (video_ref, audio_ref) in (
+        (compiled_new_request, expected_new_request),
+        (compiled_longer_text, expected_longer_text),
+    ):
+        torch.testing.assert_close(video, video_ref, atol=1e-6, rtol=0)
+        torch.testing.assert_close(audio, audio_ref, atol=1e-6, rtol=0)
+    assert torch._dynamo.utils.counters["stats"]["unique_graphs"] - graphs_before == 7
diff --git a/tests/diffusion/models/magi2/test_native_compile_distributed.py b/tests/diffusion/models/magi2/test_native_compile_distributed.py
new file mode 100644
index 00000000000..03f6f601cd7
--- /dev/null
+++ b/tests/diffusion/models/magi2/test_native_compile_distributed.py
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import os
+import tempfile
+from contextlib import ExitStack, contextmanager
+from unittest.mock import patch
+
+import pytest
+import torch
+import torch.distributed as dist
+import torch.multiprocessing as mp
+import torch.nn as nn
+from torch.distributed import init_device_mesh
+from torch.distributed.fsdp import MixedPrecisionPolicy
+
+import vllm_omni.diffusion.offloader.distributed_layerwise_backend as dlo_module
+from tests.diffusion.models.magi2.test_native_distributed_parity import (
+    _current_group,
+    _new_groups,
+    _patched_groups,
+)
+from tests.diffusion.models.magi2.test_native_packing import _tiny_config, _tiny_model, _tiny_sampler
+from tests.diffusion.offloader.helpers import patch_offload_runtime
+from vllm_omni.diffusion.distributed.hsdp import shard_model
+from vllm_omni.diffusion.models.magi2.modeling_magi2 import Magi2PreviewTransformer
+from vllm_omni.diffusion.models.magi2.parallel import Magi2ParallelGroup
+from vllm_omni.diffusion.models.magi2.pipeline_magi2 import Magi2Pipeline
+from vllm_omni.diffusion.models.magi2.sampler_magi2 import CFGConfig
+from vllm_omni.diffusion.offloader.base import OffloadConfig
+from vllm_omni.diffusion.offloader.config import OffloadStrategy
+
+_WORLD_SIZE = 4
+pytestmark = [pytest.mark.diffusion, pytest.mark.cpu, pytest.mark.core_model]
+
+
+@contextmanager
+def _cpu_offload_runtime():
+    with pytest.MonkeyPatch.context() as monkeypatch:
+        patch_offload_runtime(monkeypatch, dlo_module.current_omni_platform, synchronize=True)
+        yield
+
+
+def _enable_dlo(
+    model: Magi2PreviewTransformer,
+    *,
+    dp_group: dist.ProcessGroup | None,
+    dp_size: int,
+    dp_rank: int,
+) -> None:
+    pipeline = Magi2Pipeline.__new__(Magi2Pipeline)
+    nn.Module.__init__(pipeline)
+    pipeline.transformer = model
+    backend = dlo_module.DistributedLayerwiseOffloadBackend(
+        OffloadConfig(
+            strategy=OffloadStrategy.DISTRIBUTED_LAYER_WISE,
+            pin_cpu_memory=False,
+            dp_size=dp_size,
+            dlo_use_allgather=dp_size > 1,
+        ),
+        torch.device("cpu"),
+    )
+    backend.dp_group = dp_group
+    backend.rank = dp_rank
+    backend.enable(pipeline)
+    assert backend.enabled
+
+
+def _enable_hsdp(model: Magi2PreviewTransformer) -> None:
+    mesh = init_device_mesh("cpu", mesh_shape=(1, _WORLD_SIZE), mesh_dim_names=("replicate", "shard"))
+    ignored = {
+        parameter for name in model._hsdp_ignored_modules for parameter in model.get_submodule(name).parameters()
+    }
+    shard_model(
+        model,
+        mesh=mesh,
+        mp_policy=MixedPrecisionPolicy(cast_forward_inputs=False),
+        hsdp_shard_conditions=model._hsdp_shard_conditions,
+        ignored_params=ignored,
+    )
+    model.requires_grad_(False)
+
+
+def _sampler_tensors(seed: int) -> dict[str, torch.Tensor]:
+    # 14 tokens per CFG branch, so the packed sequence splits evenly across
+    # two Ulysses ranks; gloo cannot gather uneven shards.
+    generator = torch.Generator(device="cpu").manual_seed(seed)
+    return {
+        "latent": torch.randn(1, 4, 2, 1, 3, generator=generator),
+        "audio_latent": torch.randn(1, 5, 4, generator=generator),
+        "txt_feat": torch.randn(1, 3, 4, generator=generator),
+        "null_txt_feat": torch.randn(1, 3, 4, generator=generator),
+    }
+
+
+def _steps(sampler):
+    return [
+        sampler.prepare_model_input(**_sampler_tensors(seed), t=t, cfg_config=CFGConfig())
+        for seed, t in enumerate((torch.tensor([900.0]), torch.tensor([450.0])))
+    ]
+
+
+def _run(model: Magi2PreviewTransformer, *, compile_regions: bool) -> list[tuple[torch.Tensor, torch.Tensor]]:
+    sampler = _tiny_sampler(model)
+    steps = _steps(sampler)
+    if not compile_regions:
+        return [sampler.forward(step) for step in steps]
+    torch._dynamo.reset()
+    model.compile_regions(fullgraph=True, backend="eager", dynamic=True)
+    outputs = [sampler.forward(steps[0])]
+    with torch._dynamo.config.patch(error_on_recompile=True):
+        outputs.append(sampler.forward(steps[1]))
+    return outputs
+
+
+def _assert_same(actual, expected, *, exact: bool, label: str) -> None:
+    for (video, audio), (video_ref, audio_ref) in zip(actual, expected, strict=True):
+        if exact:
+            assert torch.equal(video, video_ref), label
+            assert torch.equal(audio, audio_ref), label
+        else:
+            torch.testing.assert_close(video, video_ref, atol=2e-5, rtol=2e-4, msg=label)
+            torch.testing.assert_close(audio, audio_ref, atol=2e-5, rtol=2e-4, msg=label)
+
+
+def _distributed_worker(rank: int, rendezvous: str) -> None:
+    torch.set_num_threads(1)
+    dist.init_process_group("gloo", init_method=rendezvous, rank=rank, world_size=_WORLD_SIZE)
+    try:
+        singleton = Magi2ParallelGroup(None, world_size=1, rank=0)
+        with _patched_groups(singleton, singleton):
+            oracle = _tiny_model()
+            checkpoint = [(name, value.detach().clone()) for name, value in oracle.state_dict().items()]
+            expected = _run(oracle, compile_regions=False)
+
+        sp2_groups = _new_groups(((0, 1), (2, 3)))
+        dp2_groups = _new_groups(((0, 2), (1, 3)))
+        sp_group = _current_group(rank, sp2_groups)
+        dp_ranks, dp_process_group = next((ranks, group) for ranks, group in dp2_groups if rank in ranks)
+
+        def dlo_rank_local(model: Magi2PreviewTransformer) -> None:
+            _enable_dlo(model, dp_group=None, dp_size=1, dp_rank=0)
+
+        def dlo_allgather(model: Magi2PreviewTransformer) -> None:
+            _enable_dlo(model, dp_group=dp_process_group, dp_size=len(dp_ranks), dp_rank=dp_ranks.index(rank))
+
+        variants = (
+            ("dlo_rank_local_sp2", sp_group, dlo_rank_local),
+            ("dlo_allgather_dp2sp2", sp_group, dlo_allgather),
+            ("hsdp4", singleton, _enable_hsdp),
+        )
+        for name, ulysses_group, enable in variants:
+            with ExitStack() as stack:
+                stack.enter_context(_patched_groups(singleton, ulysses_group))
+                stack.enter_context(_cpu_offload_runtime())
+                outputs = {}
+                for compile_regions in (False, True):
+                    model = Magi2PreviewTransformer(_tiny_config())
+                    assert model.load_weights(checkpoint) == set(model.state_dict())
+                    enable(model)
+                    outputs[compile_regions] = _run(model, compile_regions=compile_regions)
+            _assert_same(outputs[False], expected, exact=False, label=f"{name} eager vs single-rank oracle")
+            _assert_same(outputs[True], outputs[False], exact=True, label=f"{name} compiled vs eager")
+            dist.barrier()
+    finally:
+        dist.destroy_process_group()
+
+
+@pytest.mark.skipif(
+    not dist.is_available() or not dist.is_gloo_available(),
+    reason="requires torch.distributed gloo",
+)
+def test_compiled_regions_match_eager_under_dlo_and_hsdp() -> None:
+    with tempfile.TemporaryDirectory() as temp_dir:
+        rendezvous = f"file://{os.path.join(temp_dir, 'gloo-rendezvous')}"
+        with patch.dict(os.environ, {"CUDA_VISIBLE_DEVICES": ""}):
+            mp.spawn(_distributed_worker, args=(rendezvous,), nprocs=_WORLD_SIZE, join=True)
diff --git a/tests/diffusion/models/magi2/test_native_packing.py b/tests/diffusion/models/magi2/test_native_packing.py
new file mode 100644
index 00000000000..cedabebcbb6
--- /dev/null
+++ b/tests/diffusion/models/magi2/test_native_packing.py
@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import pytest
+import torch
+
+from vllm_omni.diffusion.models.magi2.configuration_magi2 import (
+    Magi2MHCConfig,
+    Magi2MoEConfig,
+    Magi2PreviewConfig,
+)
+from vllm_omni.diffusion.models.magi2.layers import MultiModalityRMSNorm
+from vllm_omni.diffusion.models.magi2.mh_moe import Magi2MultiHeadMoE
+from vllm_omni.diffusion.models.magi2.modeling_magi2 import Magi2PreviewTransformer
+from vllm_omni.diffusion.models.magi2.preview_data_proxy import (
+    Magi2DataProxy,
+    Magi2PreviewDataProxyConfig,
+)
+from vllm_omni.diffusion.models.magi2.sampler_magi2 import CFGConfig, Magi2PreviewSampler
+
+pytestmark = [pytest.mark.diffusion, pytest.mark.cpu, pytest.mark.core_model]
+
+
+def _tiny_config(params_dtype: torch.dtype = torch.float32, *, moe_layers: int = 1) -> Magi2PreviewConfig:
+    # The leading layers are multimodal with MoE, the rest single-modality
+    # dense, so every layer belongs to one of two kinds.
+    moe_indices = tuple(range(moe_layers))
+    return Magi2PreviewConfig(
+        num_layers=2 * moe_layers,
+        hidden_size=16,
+        head_dim=8,
+        num_query_groups=2,
+        video_in_channels=4,
+        audio_in_channels=4,
+        text_in_channels=4,
+        intermediate_factor=2,
+        multimodal_layers=moe_indices,
+        params_dtype=params_dtype,
+        mhc=Magi2MHCConfig(num_streams=2),
+        moe=Magi2MoEConfig(
+            num_heads=2,
+            num_experts=4,
+            top_k=2,
+            expert_intermediate_size=8,
+            shared_expert_intermediate_size=8,
+            modality_shared_expert_intermediate_size=8,
+            layers=moe_indices,
+        ),
+    )
+
+
+def _tiny_model(
+    seed: int = 11,
+    params_dtype: torch.dtype = torch.float32,
+    *,
+    moe_layers: int = 1,
+) -> Magi2PreviewTransformer:
+    model = Magi2PreviewTransformer(_tiny_config(params_dtype, moe_layers=moe_layers))
+    generator = torch.Generator(device="cpu").manual_seed(seed)
+    with torch.no_grad():
+        for parameter in model.parameters():
+            parameter.copy_(torch.randn(parameter.shape, generator=generator, dtype=parameter.dtype) * 0.02)
+        for module in model.modules():
+            if isinstance(module, MultiModalityRMSNorm):
+                module.weight.zero_()
+            elif isinstance(module, Magi2MultiHeadMoE):
+                module.router.expert_bias.zero_()
+                module.router.expert_bias_ema.zero_()
+    return model
+
+
+def _tiny_sampler(model: torch.nn.Module) -> Magi2PreviewSampler:
+    return Magi2PreviewSampler(model, Magi2DataProxy(Magi2PreviewDataProxyConfig(time_channel_dim=8)))
+
+
+def _sampler_tensors(seed: int) -> dict[str, torch.Tensor]:
+    generator = torch.Generator(device="cpu").manual_seed(seed)
+    return {
+        "latent": torch.randn(1, 4, 2, 1, 3, generator=generator),
+        "audio_latent": torch.randn(1, 5, 4, generator=generator),
+        "txt_feat": torch.randn(1, 3, 4, generator=generator),
+        "null_txt_feat": torch.randn(1, 2, 4, generator=generator),
+    }
+
+
+def _longer_text_tensors(seed: int) -> dict[str, torch.Tensor]:
+    tensors = _sampler_tensors(seed)
+    generator = torch.Generator(device="cpu").manual_seed(seed + 100)
+    tensors["txt_feat"] = torch.randn(1, 4, 4, generator=generator)
+    return tensors
+
+
+def test_prepare_model_input_keeps_lengths_on_host() -> None:
+    sampler = Magi2PreviewSampler(torch.nn.Identity())
+    model_input = sampler.prepare_model_input(**_sampler_tensors(0), t=torch.tensor([500.0]), cfg_config=CFGConfig())
+
+    assert model_input.audio_feat_len == [5, 5]
+    assert model_input.txt_feat_len == [3, 2]
+    assert model_input.ref_audio_feat_len == [0, 0]
+    assert model_input.ref_video_feat_len == [0, 0]
+
+    positive, negative = Magi2PreviewSampler._split_cfg_model_input(model_input)
+    assert positive.txt_feat_len == [3]
+    assert negative.txt_feat_len == [2]
+
+
+def test_pre_adapter_embeds_directly_in_checkpoint_dtype() -> None:
+    model = _tiny_model(params_dtype=torch.bfloat16)
+    packed = torch.randn(6, 4)
+    indices = torch.tensor([0, 1]), torch.tensor([2, 3]), torch.tensor([4, 5])
+
+    with torch.no_grad():
+        hidden = model.pre_adapter(packed, *indices)
+
+    assert hidden.dtype == torch.bfloat16
+    assert hidden.shape == (6, model.config.virtual_width)
diff --git a/vllm_omni/diffusion/models/magi2/modeling_magi2.py b/vllm_omni/diffusion/models/magi2/modeling_magi2.py
index 87d3402d3bd..44e282aa0ec 100644
--- a/vllm_omni/diffusion/models/magi2/modeling_magi2.py
+++ b/vllm_omni/diffusion/models/magi2/modeling_magi2.py
@@ -16,6 +16,7 @@
 from collections.abc import Iterable
 from enum import IntEnum
 from functools import partial
+from typing import Any
 
 import torch
 import torch.nn as nn
@@ -28,6 +29,7 @@
 from .layers import (
     ElementWiseFourierEmbed,
     MHCHandler,
+    MHCTensorTuple,
     ModalityDispatcher,
     MultiModalityRMSNorm,
     make_grouped_linear,
@@ -130,14 +132,12 @@ def _shard_sinks(self, checkpoint_tensor: torch.Tensor) -> torch.Tensor:
         start = self.tp_group.rank * self.num_heads_q
         return checkpoint_tensor[:, start : start + self.num_heads_q]
 
-    def forward(
+    def project(
         self,
         hidden_states: torch.Tensor,
         rope: torch.Tensor,
-        varlen_handler: VarlenHandler,
         modality_dispatcher: ModalityDispatcher,
-        cp_split_sizes: list[int] | torch.Tensor,
-    ) -> torch.Tensor:
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
         normalized = self.pre_norm(hidden_states, modality_dispatcher)
         gates = self.linear_g(normalized, modality_dispatcher)
         qkv = self.linear_qkv(normalized, modality_dispatcher)
@@ -159,8 +159,17 @@ def forward(
         q = apply_rotary_emb(q, cos, sin).squeeze(0).to(self.config.params_dtype)
         k = apply_rotary_emb(k, cos, sin).squeeze(0).to(self.config.params_dtype)
         v = v.squeeze(0).to(self.config.params_dtype)
+        return q, k, v, gates
 
-        output = self.packed_attention(
+    def attend(
+        self,
+        q: torch.Tensor,
+        k: torch.Tensor,
+        v: torch.Tensor,
+        varlen_handler: VarlenHandler,
+        cp_split_sizes: list[int] | torch.Tensor,
+    ) -> torch.Tensor:
+        return self.packed_attention(
             q,
             k,
             v,
@@ -172,7 +181,14 @@ def forward(
                 }
             ),
         )
-        output = modality_dispatcher.permute(output)
+
+    def output(
+        self,
+        attention: torch.Tensor,
+        gates: torch.Tensor,
+        modality_dispatcher: ModalityDispatcher,
+    ) -> torch.Tensor:
+        output = modality_dispatcher.permute(attention)
         output = output * torch.sigmoid(gates)
         output = output.reshape(-1, self.q_size).to(self.config.params_dtype)
         return self.linear_proj(output, modality_dispatcher)
@@ -303,12 +319,21 @@ def _shared_experts(
             modality.contiguous(), dispatcher
         )
 
-    def forward(self, hidden_states: torch.Tensor, dispatcher: ModalityDispatcher) -> torch.Tensor:
+    def route_input(
+        self,
+        hidden_states: torch.Tensor,
+        dispatcher: ModalityDispatcher,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
         normalized = self.pre_norm(hidden_states, dispatcher)
-        routed = self.split_linear(normalized)
-        routed = self.moe_mlp(routed)
-        routed = self.merge_linear(routed)
-        return routed + self._shared_experts(normalized, dispatcher)
+        return normalized, self.split_linear(normalized)
+
+    def combine(
+        self,
+        normalized: torch.Tensor,
+        routed: torch.Tensor,
+        dispatcher: ModalityDispatcher,
+    ) -> torch.Tensor:
+        return self.merge_linear(routed) + self._shared_experts(normalized, dispatcher)
 
 
 class Magi2PreAdapter(nn.Module):
@@ -339,37 +364,28 @@ def __init__(self, config: Magi2PreviewConfig) -> None:
     def forward(
         self,
         packed: torch.Tensor,
-        coords_mapping: torch.Tensor,
         video_indices: torch.Tensor,
         audio_indices: torch.Tensor,
         text_indices: torch.Tensor,
-    ) -> tuple[torch.Tensor, torch.Tensor]:
-        rope = self.rope(coords_mapping)
-        output = torch.zeros(
+    ) -> torch.Tensor:
+        # Every token belongs to exactly one modality, so the three copies
+        # below cover the whole buffer.  Embedding in fp32 and rounding each
+        # modality once matches the released cast at the block boundary.
+        output = torch.empty(
             packed.shape[0],
             self.adapter_dim,
-            dtype=torch.float32,
+            dtype=self.config.params_dtype,
             device=packed.device,
         )
-        if text_indices.numel():
-            output.index_copy_(
-                0,
-                text_indices,
-                self.text_embedder(packed.index_select(0, text_indices)[:, : self.config.text_in_channels].float()),
-            )
-        if audio_indices.numel():
-            output.index_copy_(
-                0,
-                audio_indices,
-                self.audio_embedder(packed.index_select(0, audio_indices)[:, : self.config.audio_in_channels].float()),
-            )
-        if video_indices.numel():
-            output.index_copy_(
-                0,
-                video_indices,
-                self.video_embedder(packed.index_select(0, video_indices)[:, : self.config.video_in_channels].float()),
-            )
-        return output, rope
+        for indices, embedder, in_channels in (
+            (text_indices, self.text_embedder, self.config.text_in_channels),
+            (audio_indices, self.audio_embedder, self.config.audio_in_channels),
+            (video_indices, self.video_embedder, self.config.video_in_channels),
+        ):
+            if indices.numel():
+                tokens = packed[:, :in_channels].index_select(0, indices).float()
+                output.index_copy_(0, indices, embedder(tokens).to(output.dtype))
+        return output
 
 
 class Magi2PostAdapter(nn.Module):
@@ -425,8 +441,10 @@ def __init__(self, config: Magi2PreviewConfig, layer_index: int) -> None:
         self.mlp: nn.Module
         if layer_index in config.moe.layers:
             self.mlp = Magi2MultiHeadMoELayer(config)
+            self.region_methods = ("_attention_input", "_moe_input", "_moe_output")
         else:
             self.mlp = Magi2MLP(config, num_modality=num_modality)
+            self.region_methods = ("_attention_input", "_dense_output")
         self._init_mhc(num_modality)
 
     def _init_mhc(self, num_modality: int) -> None:
@@ -525,31 +543,92 @@ def _connect(
         )
         return self.mhc_handler.hyper_connect(streams, output, post, residual)
 
-    def forward(
+    # The layer forward is split into compile regions around the two eager
+    # kernels: packed attention and the multi-head MoE.
+
+    def _attention_input(
         self,
         hidden_states: torch.Tensor,
         rope: torch.Tensor,
-        varlen_handler: VarlenHandler,
         modality_dispatcher: ModalityDispatcher,
-        cp_split_sizes: list[int] | torch.Tensor,
-    ) -> torch.Tensor:
+    ) -> tuple[torch.Tensor, MHCTensorTuple, torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
         streams = hidden_states.reshape(hidden_states.shape[0], self.config.mhc.num_streams, self.config.hidden_size)
         attention_logits = self._branch_logits(streams, "attn", modality_dispatcher)
         attention_input = self._branch_input(streams, "attn", attention_logits)
-        attention_output = self.attention(
-            attention_input,
-            rope,
-            varlen_handler,
-            modality_dispatcher,
-            cp_split_sizes,
-        )
+        q, k, v, gates = self.attention.project(attention_input, rope, modality_dispatcher)
+        return streams, attention_logits, q, k, v, gates
+
+    def _mlp_input(
+        self,
+        streams: torch.Tensor,
+        attention: torch.Tensor,
+        gates: torch.Tensor,
+        attention_logits: MHCTensorTuple,
+        modality_dispatcher: ModalityDispatcher,
+    ) -> tuple[torch.Tensor, MHCTensorTuple, torch.Tensor]:
+        attention_output = self.attention.output(attention, gates, modality_dispatcher)
         streams = self._connect(streams, attention_output, "attn", attention_logits)
         mlp_logits = self._branch_logits(streams, "mlp", modality_dispatcher)
-        mlp_input = self._branch_input(streams, "mlp", mlp_logits)
-        mlp_output = self.mlp(mlp_input, modality_dispatcher)
+        return streams, mlp_logits, self._branch_input(streams, "mlp", mlp_logits)
+
+    def _dense_output(
+        self,
+        streams: torch.Tensor,
+        attention: torch.Tensor,
+        gates: torch.Tensor,
+        attention_logits: MHCTensorTuple,
+        modality_dispatcher: ModalityDispatcher,
+    ) -> torch.Tensor:
+        streams, mlp_logits, mlp_input = self._mlp_input(
+            streams, attention, gates, attention_logits, modality_dispatcher
+        )
+        streams = self._connect(streams, self.mlp(mlp_input, modality_dispatcher), "mlp", mlp_logits)
+        return streams.reshape(streams.shape[0], -1)
+
+    def _moe_input(
+        self,
+        streams: torch.Tensor,
+        attention: torch.Tensor,
+        gates: torch.Tensor,
+        attention_logits: MHCTensorTuple,
+        modality_dispatcher: ModalityDispatcher,
+    ) -> tuple[torch.Tensor, MHCTensorTuple, torch.Tensor, torch.Tensor]:
+        streams, mlp_logits, mlp_input = self._mlp_input(
+            streams, attention, gates, attention_logits, modality_dispatcher
+        )
+        normalized, routed = self.mlp.route_input(mlp_input, modality_dispatcher)
+        return streams, mlp_logits, normalized, routed
+
+    def _moe_output(
+        self,
+        streams: torch.Tensor,
+        mlp_logits: MHCTensorTuple,
+        normalized: torch.Tensor,
+        routed: torch.Tensor,
+        modality_dispatcher: ModalityDispatcher,
+    ) -> torch.Tensor:
+        mlp_output = self.mlp.combine(normalized, routed, modality_dispatcher)
         streams = self._connect(streams, mlp_output, "mlp", mlp_logits)
         return streams.reshape(streams.shape[0], -1)
 
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        rope: torch.Tensor,
+        varlen_handler: VarlenHandler,
+        modality_dispatcher: ModalityDispatcher,
+        cp_split_sizes: list[int] | torch.Tensor,
+    ) -> torch.Tensor:
+        streams, attention_logits, q, k, v, gates = self._attention_input(hidden_states, rope, modality_dispatcher)
+        attention = self.attention.attend(q, k, v, varlen_handler, cp_split_sizes)
+        if not isinstance(self.mlp, Magi2MultiHeadMoELayer):
+            return self._dense_output(streams, attention, gates, attention_logits, modality_dispatcher)
+        streams, mlp_logits, normalized, routed = self._moe_input(
+            streams, attention, gates, attention_logits, modality_dispatcher
+        )
+        routed = self.mlp.moe_mlp(routed)
+        return self._moe_output(streams, mlp_logits, normalized, routed, modality_dispatcher)
+
 
 class Magi2TransformerBlock(nn.Module):
     def __init__(self, config: Magi2PreviewConfig) -> None:
@@ -570,7 +649,6 @@ def forward(
         modality_dispatcher: ModalityDispatcher,
         cp_split_sizes: list[int] | torch.Tensor,
     ) -> torch.Tensor:
-        hidden_states = hidden_states.to(self.config.params_dtype)
         hidden_states = modality_dispatcher.permute(hidden_states)
         for layer in self.layers:
             hidden_states = layer(
@@ -630,6 +708,15 @@ def layers(self) -> nn.ModuleList:
 
         return self.block.layers
 
+    def compile_regions(self, **compile_kwargs: Any) -> None:
+        """Compile the dense compute between the eager attention and MoE kernels."""
+
+        self.pre_adapter.forward = torch.compile(self.pre_adapter.forward, **compile_kwargs)
+        self.post_adapter.forward = torch.compile(self.post_adapter.forward, **compile_kwargs)
+        for layer in self.block.layers:
+            for name in layer.region_methods:
+                setattr(layer, name, torch.compile(getattr(layer, name), **compile_kwargs))
+
     def forward(
         self,
         x: torch.Tensor,
@@ -647,6 +734,7 @@ def forward(
         assert dispatcher.split_sizes is not None
         cp_split_sizes = dispatcher.split_sizes
 
+        rope = self.pre_adapter.rope(coords_mapping)
         time_mask = modality_mapping == int(Modality.TIME)
         modality_mapping = torch.where(time_mask, int(Modality.TEXT), modality_mapping)
         modality_dispatcher = ModalityDispatcher(modality_mapping, 3)
@@ -654,13 +742,7 @@ def forward(
         audio_indices = torch.nonzero(modality_mapping == int(Modality.AUDIO)).flatten()
         text_indices = torch.nonzero(modality_mapping == int(Modality.TEXT)).flatten()
 
-        hidden_states, rope = self.pre_adapter(
-            x,
-            coords_mapping,
-            video_indices,
-            audio_indices,
-            text_indices,
-        )
+        hidden_states = self.pre_adapter(x, video_indices, audio_indices, text_indices)
         if time_token_sequence is not None and time_token_sequence.shape[-1] > 0:
             hidden_states[:, : time_token_sequence.shape[-1]] = time_token_sequence.to(hidden_states.dtype)
         hidden_states = self.block(
diff --git a/vllm_omni/diffusion/models/magi2/pipeline_magi2.py b/vllm_omni/diffusion/models/magi2/pipeline_magi2.py
index c7c48087649..910e0d074c2 100644
--- a/vllm_omni/diffusion/models/magi2/pipeline_magi2.py
+++ b/vllm_omni/diffusion/models/magi2/pipeline_magi2.py
@@ -695,6 +695,24 @@ def vae(self) -> nn.Module:
 
         return self.video_decoder.module
 
+    def setup_compile(self) -> None:
+        """Compile the transformer regions; the attention and MoE kernels stay eager."""
+
+        granularity = self.od_config.diffusion_compile_granularity
+        if granularity != "regional":
+            logger.warning(
+                "MAGI-2 compiles the transformer regions itself; diffusion_compile_granularity=%r is ignored.",
+                granularity,
+            )
+
+        # The mHC connections chain bf16 ops that eager rounds after every op.
+        # Emulating those casts keeps the compiled rounding boundaries equal.
+        self.transformer.compile_regions(
+            fullgraph=True,
+            dynamic=self.od_config.diffusion_compile_dynamic,
+            options={"emulate_precision_casts": True},
+        )
+
     def load_weights(
         self,
         weights: Iterable[tuple[str, torch.Tensor]],
diff --git a/vllm_omni/diffusion/models/magi2/sampler_magi2.py b/vllm_omni/diffusion/models/magi2/sampler_magi2.py
index 994fdd3e4db..35dd2dab917 100644
--- a/vllm_omni/diffusion/models/magi2/sampler_magi2.py
+++ b/vllm_omni/diffusion/models/magi2/sampler_magi2.py
@@ -308,29 +308,11 @@ def prepare_model_input(
         per_token_video_t = t_batch.view(-1, 1, 1, 1, 1).expand(cfg_batch, 1, video_t, video_h, video_w)
         per_token_audio_t = t_batch.view(-1, 1, 1).expand(cfg_batch, audio_t, 1)
 
-        audio_lengths = torch.full(
-            (cfg_batch,),
-            audio_latent_len,
-            device=latent.device,
-            dtype=torch.long,
-        )
-        text_lengths = torch.tensor(
-            [txt_feat_len] * batch_size + [null_txt_feat_len] * batch_size,
-            device=latent.device,
-            dtype=torch.long,
-        )
-        ref_audio_lengths = torch.full(
-            (cfg_batch,),
-            ref_audio_feat_len,
-            device=latent.device,
-            dtype=torch.long,
-        )
-        ref_video_lengths = torch.full(
-            (cfg_batch,),
-            ref_video_feat_len,
-            device=latent.device,
-            dtype=torch.long,
-        )
+        # Lengths stay host integers; the data proxy reads them as Python ints.
+        audio_lengths = [audio_latent_len] * cfg_batch
+        text_lengths = [txt_feat_len] * batch_size + [null_txt_feat_len] * batch_size
+        ref_audio_lengths = [ref_audio_feat_len] * cfg_batch
+        ref_video_lengths = [ref_video_feat_len] * cfg_batch
 
         return ModelInput(
             x_t=torch.cat((latent, latent), dim=0),

From 5e9024171d4a8ceb9089b7f8306e266d0eb5526a Mon Sep 17 00:00:00 2001
From: Zhou Taichang <tzhouam@connect.ust.hk>
Date: Wed, 16 Sep 2026 14:43:18 +0800
Subject: [PATCH 024/105] [Bugfix] Skip generic text-only warmup for DreamZero
 (#7548)

Signed-off-by: tzhouam <tzhouam@connect.ust.hk>
---
 .../test_diffusion_engine_dummy_run.py          | 17 +++++++++++++++++
 .../models/dreamzero/pipeline_dreamzero.py      |  5 +++++
 2 files changed, 22 insertions(+)

diff --git a/tests/diffusion/test_diffusion_engine_dummy_run.py b/tests/diffusion/test_diffusion_engine_dummy_run.py
index 8d524c57233..1f1e8cbab73 100644
--- a/tests/diffusion/test_diffusion_engine_dummy_run.py
+++ b/tests/diffusion/test_diffusion_engine_dummy_run.py
@@ -7,6 +7,7 @@
 import pytest
 
 from vllm_omni.diffusion import io_support
+from vllm_omni.diffusion.data import OmniDiffusionConfig
 from vllm_omni.diffusion.diffusion_engine import DiffusionEngine, DiffusionExecutionMode
 from vllm_omni.diffusion.diffusion_kv.config import DiffusionKVCacheMode
 from vllm_omni.diffusion.diffusion_kv.request import DiffusionKVRequest
@@ -16,6 +17,22 @@
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
 
 
+@pytest.mark.parametrize("model_class_name", ["DreamZeroPipeline", "LingBotWorldCausalDMDPipeline"])
+def test_observation_conditioned_startup_skips_generic_warmup(model_class_name: str) -> None:
+    """Observation-conditioned pipelines must not receive generic text requests."""
+    engine = DiffusionEngine.__new__(DiffusionEngine)
+    engine.od_config = OmniDiffusionConfig.__new__(OmniDiffusionConfig)
+    engine.od_config.model_class_name = model_class_name
+    engine.od_config.diffusion_load_format = "default"
+    engine.add_req_and_wait_for_response = Mock(side_effect=AssertionError("generic text warmup submitted"))
+    engine.close = Mock()
+
+    engine.run_startup_warmup()
+
+    engine.add_req_and_wait_for_response.assert_not_called()
+    engine.close.assert_not_called()
+
+
 @pytest.mark.parametrize("step_execution", [False, True])
 def test_dummy_run_uses_enough_steps_for_execution_mode(
     monkeypatch: pytest.MonkeyPatch,
diff --git a/vllm_omni/diffusion/models/dreamzero/pipeline_dreamzero.py b/vllm_omni/diffusion/models/dreamzero/pipeline_dreamzero.py
index 09bd536cd7f..939544a9f01 100644
--- a/vllm_omni/diffusion/models/dreamzero/pipeline_dreamzero.py
+++ b/vllm_omni/diffusion/models/dreamzero/pipeline_dreamzero.py
@@ -17,6 +17,7 @@
 from collections import OrderedDict
 from collections.abc import Iterable
 from contextlib import contextmanager
+from typing import ClassVar
 
 import numpy as np
 import torch
@@ -121,6 +122,10 @@ class DreamZeroPipeline(nn.Module, CFGParallelMixin):
     methods below. The runner binds one session state only for ``forward()``.
     """
 
+    # Generic warmup cannot synthesize robot observations. AR-Diffusion uses
+    # ar_diffusion_warmup_requests() for model-specific warmup instead.
+    dummy_run_num_frames: ClassVar[int] = 0
+
     _POSITIVE_BRANCH = "positive"
     _NEGATIVE_BRANCH = "negative"
     _ar_diffusion_kv_state = None

From 9005d789033b8c3ec5876a7a68c4e2d9238f5c69 Mon Sep 17 00:00:00 2001
From: linzhenpl07 <60651557+linzhenpl07@users.noreply.github.com>
Date: Wed, 16 Sep 2026 15:01:11 +0800
Subject: [PATCH 025/105] [LingBot World] Reuse the text encode for a prompt
 already encoded (#6845)

Signed-off-by: linzhenpl07 <linzhenpl07@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
---
 .../test_pipeline_lingbot_world.py            | 122 ++++++++++++++++++
 .../models/lingbot_world/pipeline.py          |  34 ++++-
 2 files changed, 154 insertions(+), 2 deletions(-)

diff --git a/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py b/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py
index fb9e93a5d55..9d5e958c58a 100644
--- a/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py
+++ b/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py
@@ -2711,3 +2711,125 @@ def test_registry_and_model_exports_resolve_official_pipeline_class_name() -> No
     assert "from .pipeline import" in lingbot_init
     assert '"LingBotWorldCausalDMDPipeline"' in lingbot_init
     assert '"CausalLingBotWorldTransformer3DModel"' in lingbot_init
+
+
+# ---------------------------------------------------------------------------
+# a prompt is encoded once, whichever path asks for it
+# ---------------------------------------------------------------------------
+def _counting_text_encoder(pipeline) -> list[str]:
+    """Give ``pipeline`` its real encode_prompt over stubs that record each encode."""
+    del pipeline.encode_prompt  # _pipeline() replaces it; these tests need the real one
+    encoded: list[str] = []
+
+    def tokenizer(texts, **kwargs):
+        del kwargs
+        encoded.extend(texts)
+        return SimpleNamespace(
+            input_ids=torch.arange(512).view(1, 512),
+            attention_mask=torch.ones(1, 512, dtype=torch.long),
+        )
+
+    def text_encoder(input_ids, attention_mask):
+        del input_ids, attention_mask
+        return SimpleNamespace(last_hidden_state=torch.full((1, 512, 8), float(len(encoded))))
+
+    pipeline.tokenizer = tokenizer
+    pipeline.text_encoder = text_encoder
+    return encoded
+
+
+def test_the_text_encoder_runs_once_per_distinct_prompt() -> None:
+    module = _load_pipeline_module()
+    pipeline = _pipeline(module)
+    encoded = _counting_text_encoder(pipeline)
+
+    def encode(prompt, *, length=512, dtype=torch.float32):
+        return pipeline.encode_prompt(prompt, max_sequence_length=length, dtype=dtype)
+
+    first = encode("move through the room")
+    assert encode("move through the room") is first
+    # The key is the text the tokenizer actually sees, so spacing alone is not new.
+    assert encode("  move   through the room ") is first
+    assert encoded == ["move through the room"]
+
+    encode("enter the snowy valley")
+    # dtype and sequence length change the tensor, so each is its own entry.
+    encode("move through the room", dtype=torch.float16)
+    encode("move through the room", length=256)
+    assert encoded == [
+        "move through the room",
+        "enter the snowy valley",
+        "move through the room",
+        "move through the room",
+    ]
+
+
+def test_the_prompt_encode_cache_is_bounded() -> None:
+    module = _load_pipeline_module()
+    pipeline = _pipeline(module)
+    encoded = _counting_text_encoder(pipeline)
+    size = module._PROMPT_EMBEDS_CACHE_SIZE
+
+    for index in range(size + 1):
+        pipeline.encode_prompt(f"prompt {index}", max_sequence_length=512, dtype=torch.float32)
+    assert len(pipeline._prompt_embeds_cache) == size
+
+    # The oldest entry was the one evicted, so it is the one encoded again.
+    pipeline.encode_prompt("prompt 0", max_sequence_length=512, dtype=torch.float32)
+    pipeline.encode_prompt(f"prompt {size}", max_sequence_length=512, dtype=torch.float32)
+    assert encoded == [f"prompt {index}" for index in range(size + 1)] + ["prompt 0"]
+
+
+def test_realtime_ticks_reuse_the_encode_and_still_invalidate_on_a_prompt_change(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    module = _load_pipeline_module()
+    pipeline = _pipeline(module)
+    pipeline._ar_height = 16
+    pipeline._ar_width = 16
+    pipeline._ar_diffusion_kv_state = object()
+    encoded = _counting_text_encoder(pipeline)
+    invalidations: list[bool] = []
+
+    def ar_text_caches(prompt_embeds, *, invalidate):
+        del prompt_embeds
+        invalidations.append(invalidate)
+        return [SimpleNamespace()]
+
+    monkeypatch.setattr(pipeline, "_ar_text_caches", ar_text_caches)
+    monkeypatch.setattr(
+        pipeline,
+        "_generate_block",
+        lambda **kwargs: torch.randn((1, 16, 3, 2, 2), generator=kwargs["generator"]),
+    )
+
+    for chunk_index in range(3):
+        pipeline(_request(sampling=_SamplingParams(extra_args=_tick_extra_args(chunk_index=chunk_index))))
+    switched = _prompt()
+    switched["prompt"] = "enter the snowy valley"
+    pipeline(
+        _request(
+            sampling=_SamplingParams(extra_args=_tick_extra_args(chunk_index=3, prompt=switched["prompt"])),
+            prompt=switched,
+        )
+    )
+
+    assert encoded == ["move through the room", "enter the snowy valley"]
+    # A new prompt must still drop the cross-attention K/V built from the old one.
+    assert invalidations == [False, False, False, True]
+
+
+def test_stepwise_requests_with_the_same_prompt_share_one_encode() -> None:
+    module = _load_pipeline_module()
+    pipeline = _pipeline(module, transformer=_RecordingTransformer())
+    pipeline._ar_height = 16
+    pipeline._ar_width = 16
+    encoded = _counting_text_encoder(pipeline)
+
+    states = [_stepwise_state(request_id=request_id, num_frames=21) for request_id in ("req-a", "req-b")]
+    for state in states:
+        with pipeline.bind_ar_diffusion_state(state.request_id, _FakeARState(state.request_id)):
+            pipeline.prepare_encode(state)
+
+    assert encoded == ["move through the room"]
+    assert states[0].prompt_embeds is states[1].prompt_embeds
diff --git a/vllm_omni/diffusion/models/lingbot_world/pipeline.py b/vllm_omni/diffusion/models/lingbot_world/pipeline.py
index ccaa677e069..8e8d5dea4d0 100644
--- a/vllm_omni/diffusion/models/lingbot_world/pipeline.py
+++ b/vllm_omni/diffusion/models/lingbot_world/pipeline.py
@@ -6,6 +6,7 @@
 
 import math
 import os
+from collections import OrderedDict
 from collections.abc import Callable, Iterable, Iterator, Sequence
 from contextlib import contextmanager, nullcontext
 from dataclasses import dataclass, replace
@@ -99,6 +100,10 @@
 _MAX_PIXEL_AREA = 480 * 832
 _MAX_SOURCE_IMAGE_PIXELS = 4096 * 4096
 _MAX_SEQUENCE_LENGTH = 512
+# Distinct prompts whose text encodes are kept. One entry is a single padded
+# sequence -- a few MiB at 512 tokens -- so a handful covers a session's prompt
+# plus the switches it makes, at no meaningful cost next to its KV.
+_PROMPT_EMBEDS_CACHE_SIZE = 4
 _ACTION_ROOT_ENV = "VLLM_OMNI_LINGBOT_ACTION_ROOT"
 _PREPROCESSED_CAMERA_KEY = "_lingbot_camera_trajectory"
 _PREPROCESSED_CAMERA_ACTIONS_KEY = "_lingbot_camera_actions"
@@ -569,6 +574,8 @@ def __init__(
         self._ar_width = int(model_config.get("ar_diffusion_width", 832))
         self._ar_diffusion_kv_state: ARDiffusionKVState | None = None
         self._ar_sessions: dict[str, _LingBotARSessionState] = {}
+        # Text encodes keyed by what they depend on; see encode_prompt.
+        self._prompt_embeds_cache: OrderedDict[tuple[str, int, torch.dtype], torch.Tensor] = OrderedDict()
         # One temporal decoder cache per stepwise session, keyed the way the
         # runner keys AR sessions (session_id == request_id) so both are
         # released together rather than through two independent lifecycles.
@@ -1221,8 +1228,27 @@ def encode_prompt(
         max_sequence_length: int,
         dtype: torch.dtype,
     ) -> torch.Tensor:
+        """Encode ``prompt`` with UMT5, reusing the result for a prompt already encoded.
+
+        The encode depends only on the whitespace-normalised text, the sequence
+        length and the dtype -- the tokenizer and text encoder are fixed once
+        loaded -- so those three are the key. That covers every caller the same
+        way: a realtime tick repeats its session's prompt on every block, a
+        stepwise request encodes once per request, and a server tends to open
+        many sessions with the same scene prompt.
+
+        A hit returns the stored tensor itself. Callers only read it: the
+        cross-attention projection and the DMD transformer both work out of
+        place, so a shared encode is never changed under another session.
+        """
+        text = " ".join(prompt.strip().split())
+        key = (text, int(max_sequence_length), dtype)
+        cached = self._prompt_embeds_cache.get(key)
+        if cached is not None:
+            self._prompt_embeds_cache.move_to_end(key)
+            return cached
         text_inputs = self.tokenizer(
-            [" ".join(prompt.strip().split())],
+            [text],
             padding="max_length",
             max_length=max_sequence_length,
             truncation=True,
@@ -1234,7 +1260,11 @@ def encode_prompt(
         attention_mask = text_inputs.attention_mask.to(self.device)
         prompt_embeds = self.text_encoder(input_ids, attention_mask).last_hidden_state
         prompt_embeds = prompt_embeds.to(device=self.device, dtype=dtype)
-        return prompt_embeds * attention_mask.unsqueeze(-1).to(dtype=prompt_embeds.dtype)
+        prompt_embeds = prompt_embeds * attention_mask.unsqueeze(-1).to(dtype=prompt_embeds.dtype)
+        self._prompt_embeds_cache[key] = prompt_embeds
+        if len(self._prompt_embeds_cache) > _PROMPT_EMBEDS_CACHE_SIZE:
+            self._prompt_embeds_cache.popitem(last=False)
+        return prompt_embeds
 
     def forward(self, req: DiffusionRequestBatch) -> DiffusionOutput:
         inputs = self._parse_request(req)

From 99ff4f307040e85ba99e849ef013fdee89525378 Mon Sep 17 00:00:00 2001
From: chickeyton <ngton2014@gmail.com>
Date: Wed, 16 Sep 2026 15:35:36 +0800
Subject: [PATCH 026/105] [Core][Frontend] Unified Full-duplex Framework
 (#7413)

Signed-off-by: chickeyton <ngton2014@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../common/ci_source_file_dependencies.yml    |   10 +-
 .buildkite/cuda/test-merge.yml                |    4 +-
 docs/api/README.md                            |    7 +-
 docs/configuration/stage_configs.md           |    3 +-
 docs/design/fullduplex.md                     | 1397 +--
 docs/design/module/engine_orchestration.md    |   11 +-
 docs/design/module/entrypoints.md             |   11 +-
 docs/mkdocs/hooks/generate_api_readme.py      |    4 +-
 docs/models/supported_models.md               |    2 +-
 docs/serving/README.md                        |   17 +-
 docs/serving/full_duplex_api.md               |   87 +-
 docs/serving/realtime_duplex_api.md           |  355 +-
 examples/online_serving/barge_in_client.py    |  236 +-
 .../online_serving/barge_in_client_flow.md    |   15 +-
 .../online_serving/minicpmo/barge_in_serve.sh |   10 +-
 .../minicpmo/realtime_duplex_demo.py          |    2 -
 .../minicpmo/realtime_web/app/static/app.js   |    2 -
 recipes/OpenBMB/MiniCPM-o-4_5.md              |   75 +-
 recipes/README.md                             |    2 +-
 tests/benchmarks/patch/test_patch.py          |   68 +-
 tests/benchmarks/test_omniinteract.py         |   27 +-
 tests/benchmarks/test_realtime_tts_probe.py   |  179 +
 tests/clients/test_duplex_client.py           |  514 +-
 tests/clients/test_model_session_configs.py   |    7 +-
 tests/dfx/perf/tests/test_minicpmo_4_5.json   |   86 +-
 .../test_minicpmo_4_5_duplex_seed_tts.json    |   38 +-
 .../perf/tests/test_minicpmo_4_5_ready.json   |   40 +-
 .../test_diffusion_streaming_output.py        |    3 +-
 .../test_prompt_interaction.py                |    3 +-
 .../test_diffusion_engine_metrics.py          |   26 +-
 .../fullduplex/test_core_contracts.py         |   11 +-
 .../minicpmo_realtime_duplex_scenarios.py     |   25 +-
 .../run_minicpmo_realtime_duplex_demo_pair.py |    3 -
 ..._minicpmo_realtime_duplex_multi_session.py |   34 +-
 ...minicpmo_realtime_duplex_soft_interrupt.py |    3 -
 .../online_serving/test_duplex_client_live.py |    2 -
 .../test_minicpmo_4_5_duplex.py               |  386 +-
 .../test_minicpmo_4_5_duplex_expansion.py     |    2 +-
 .../test_minicpmo_realtime_duplex_drivers.py  |   26 +-
 .../duplex/test_duplex_audio.py               |    2 +-
 tests/engine/duplex/test_duplex_commands.py   |  453 +
 .../duplex/test_duplex_control_client.py      |  110 -
 .../duplex/test_duplex_control_plane.py       | 1270 ---
 tests/engine/duplex/test_duplex_events.py     |  386 +
 tests/engine/duplex/test_duplex_lease.py      |  206 +-
 tests/engine/duplex/test_duplex_plugin.py     |  324 +
 tests/engine/duplex/test_duplex_runtime.py    |  563 -
 tests/engine/duplex/test_engine_session.py    |  612 ++
 tests/engine/duplex/test_overlap_policy.py    |  229 +
 tests/engine/duplex/test_session_manager.py   | 1569 +++
 tests/engine/duplex/test_session_runner.py    | 1195 +++
 tests/engine/duplex/test_vad_backend.py       |  379 +
 .../test_async_omni_engine_abort_ack.py       |    8 +-
 .../engine/test_async_omni_engine_outputs.py  |  336 +-
 .../test_async_omni_engine_stage_init.py      |    4 +-
 .../test_diffusion_streaming_output_kwarg.py  |    2 +-
 tests/engine/test_duplex_import_boundary.py   |   83 +-
 tests/engine/test_duplex_omni_engine.py       |  210 +
 tests/engine/test_duplex_orchestrator.py      |  517 +
 tests/engine/test_orchestrator.py             |  887 --
 .../test_orchestrator_error_handling.py       |   38 +-
 .../test_orchestrator_segment_stage_keying.py |   44 +-
 .../test_orchestrator_stage_input_bridge.py   |  107 +-
 .../engine/test_output_metadata_snapshots.py  |    8 +-
 tests/engine/test_single_stage_mode.py        |   15 +-
 .../entrypoints/duplex/test_duplex_serving.py |  609 ++
 .../duplex/test_runtime_adapter_boundary.py   |  145 -
 .../duplex/test_runtime_control_redaction.py  |  115 -
 .../duplex/test_websocket_actor.py            |  145 -
 .../openai/test_duplex_protocol.py            |  601 --
 .../openai/test_duplex_session_attachment.py  |  129 +-
 .../openai_api/test_api_server_guards.py      |    1 -
 .../openai_api/test_duplex_api_server.py      |  414 +
 .../openai_api/test_duplex_handler.py         | 9491 -----------------
 .../test_qwen3_omni_realtime_websocket.py     |    2 +-
 .../entrypoints/openai_api/test_server_vad.py |  429 -
 .../test_async_omni_diffusion_config.py       |    2 +-
 tests/entrypoints/test_async_omni_duplex.py   |  601 --
 .../test_disable_log_stats_routing.py         |    2 +-
 .../test_duplex_fence_propagation.py          |  126 -
 tests/entrypoints/test_duplex_omni.py         |  326 +
 tests/entrypoints/test_omni_base_profiler.py  |   19 +-
 tests/entrypoints/test_omni_entrypoints.py    |    5 +-
 .../test_minicpmo_realtime_web_static.py      |    2 +-
 .../minicpmo_4_5/duplex/test_commit_policy.py |   14 +-
 .../duplex/test_data_plane_audio_cursor.py    |   78 +
 .../models/minicpmo_4_5/test_pipeline.py      |   12 +-
 .../nemotron_voicechat/duplex/conftest.py     |   20 +
 .../duplex/test_data_plane.py                 |    2 +-
 .../models/personaplex/duplex/conftest.py     |   21 +
 .../duplex/test_unified_runtime.py            |   12 +-
 tests/worker/test_native_duplex_hooks.py      |   38 +-
 tools/pre_commit/check_forbidden_imports.py   |   11 +-
 vllm_omni/benchmarks/omniinteract.py          |   27 +-
 vllm_omni/benchmarks/patch/patch.py           |  316 +-
 vllm_omni/clients/__init__.py                 |    6 +-
 vllm_omni/clients/duplex.py                   |  365 +-
 vllm_omni/clients/inline_duplex.py            |  136 +
 vllm_omni/clients/minicpmo_4_5.py             |    2 +-
 vllm_omni/config/stage_config.py              |   21 +-
 vllm_omni/deploy/minicpmo_4_5.yaml            |    4 +-
 vllm_omni/deploy/minicpmo_4_5_2gpu.yaml       |    4 +-
 vllm_omni/deploy/minicpmo_4_5_3gpu.yaml       |    4 +-
 vllm_omni/deploy/minicpmo_4_5_8x4090.yaml     |    5 +-
 vllm_omni/engine/async_omni_engine.py         | 1169 +-
 vllm_omni/engine/duplex/__init__.py           |    3 +-
 .../{entrypoints => engine}/duplex/audio.py   |    8 +-
 vllm_omni/engine/duplex/commands.py           |  324 +
 vllm_omni/engine/duplex/config.py             |  815 ++
 vllm_omni/engine/duplex/contracts.py          |  146 +-
 vllm_omni/engine/duplex/control_client.py     |  228 -
 vllm_omni/engine/duplex/control_plane.py      | 1063 --
 vllm_omni/engine/duplex/events.py             |  756 ++
 vllm_omni/engine/duplex/messages.py           |  128 +-
 vllm_omni/engine/duplex/plugin.py             |  329 +
 vllm_omni/engine/duplex/realtime_commands.py  |  887 ++
 vllm_omni/engine/duplex/realtime_events.py    | 1526 +++
 vllm_omni/engine/duplex/runtime.py            |  108 -
 vllm_omni/engine/duplex/session.py            |  534 -
 vllm_omni/engine/duplex/session/__init__.py   |   38 +
 .../engine/duplex/session/append_task.py      |  195 +
 .../duplex/session}/commit_policy.py          |    4 +-
 vllm_omni/engine/duplex/session/context.py    |  161 +
 vllm_omni/engine/duplex/session/control.py    |  328 +
 vllm_omni/engine/duplex/session/emitter.py    |  249 +
 .../duplex/session/engine_session.py}         | 1207 +--
 vllm_omni/engine/duplex/session/helpers.py    |  195 +
 .../engine/duplex/{ => session}/lease.py      |   13 -
 vllm_omni/engine/duplex/session/manager.py    |  872 ++
 .../engine/duplex/session/model_channel.py    | 1100 ++
 .../engine/duplex/session/overlap_policy.py   |  388 +
 .../engine/duplex/session/playback_ledger.py  |  137 +
 vllm_omni/engine/duplex/session/runner.py     | 1772 +++
 vllm_omni/engine/duplex/turn_detection.py     |  301 +
 vllm_omni/engine/duplex/vad.py                |  488 +
 vllm_omni/engine/duplex_omni_engine.py        |  299 +
 vllm_omni/engine/duplex_orchestrator.py       |  352 +
 vllm_omni/engine/omni_engine_base.py          | 1229 +++
 vllm_omni/engine/orchestrator.py              |  947 +-
 vllm_omni/entrypoints/async_omni.py           |  724 +-
 vllm_omni/entrypoints/async_omni_base.py      |  557 +
 .../entrypoints/cli/benchmark/cli_args.py     |    6 +-
 vllm_omni/entrypoints/duplex/__init__.py      |   11 +-
 .../entrypoints/duplex/audio_encoding.py      |   55 +
 vllm_omni/entrypoints/duplex/capability.py    |   34 -
 vllm_omni/entrypoints/duplex/chat_fallback.py |  302 -
 .../entrypoints/duplex/realtime_input.py      | 1679 +--
 .../entrypoints/duplex/realtime_output.py     | 1007 --
 .../entrypoints/duplex/realtime_session.py    |  147 -
 .../entrypoints/duplex/realtime_state.py      |  245 -
 .../entrypoints/duplex/runtime_adapter.py     |  331 -
 .../entrypoints/duplex/runtime_bridge.py      | 1454 ---
 vllm_omni/entrypoints/duplex/server_vad.py    |  528 -
 vllm_omni/entrypoints/duplex/serving.py       | 2421 +----
 .../entrypoints/duplex/session_attachment.py  |  149 +-
 .../entrypoints/duplex/session_runner.py      | 2520 -----
 vllm_omni/entrypoints/duplex/warmup.py        |    7 +-
 vllm_omni/entrypoints/duplex/websocket.py     |  286 +-
 vllm_omni/entrypoints/duplex_omni.py          |  476 +
 .../entrypoints/duplex_request_client.py      |  383 -
 vllm_omni/entrypoints/omni.py                 |    6 +-
 vllm_omni/entrypoints/omni_base.py            |   18 +-
 vllm_omni/entrypoints/openai/api_server.py    |  219 +-
 .../entrypoints/openai/audio_utils_mixin.py   |  153 +-
 vllm_omni/experimental/fullduplex/README.md   |   29 +-
 vllm_omni/model_executor/duplex_sampling.py   |    6 -
 .../models/minicpmo_4_5/duplex/__init__.py    |    6 +-
 .../models/minicpmo_4_5/duplex/adapter.py     |  335 -
 .../minicpmo_4_5/duplex/capabilities.py       |   14 +-
 .../models/minicpmo_4_5/duplex/compat.py      |    6 +-
 .../models/minicpmo_4_5/duplex/data_plane.py  |   30 +-
 .../models/minicpmo_4_5/duplex/input.py       |   12 +-
 .../models/minicpmo_4_5/duplex/plugin.py      |  773 ++
 .../models/minicpmo_4_5/duplex/policy.py      |    7 +-
 .../models/minicpmo_4_5/duplex/runtime.py     |  439 -
 .../minicpmo_4_5/duplex/serving_adapter.py    |  102 -
 .../models/minicpmo_4_5/duplex/session.py     |   11 +-
 .../models/minicpmo_4_5/duplex/stage0.py      |  107 +-
 .../models/minicpmo_4_5/minicpmo_4_5_omni.py  |   14 +-
 .../models/minicpmo_4_5/pipeline.py           |    8 +-
 .../minicpmo_4_5_omni.py                      |    3 -
 vllm_omni/utils/audio_resample.py             |  167 +
 182 files changed, 26923 insertions(+), 34715 deletions(-)
 create mode 100644 tests/benchmarks/test_realtime_tts_probe.py
 rename tests/{entrypoints => engine}/duplex/test_duplex_audio.py (95%)
 create mode 100644 tests/engine/duplex/test_duplex_commands.py
 delete mode 100644 tests/engine/duplex/test_duplex_control_client.py
 delete mode 100644 tests/engine/duplex/test_duplex_control_plane.py
 create mode 100644 tests/engine/duplex/test_duplex_events.py
 create mode 100644 tests/engine/duplex/test_duplex_plugin.py
 delete mode 100644 tests/engine/duplex/test_duplex_runtime.py
 create mode 100644 tests/engine/duplex/test_engine_session.py
 create mode 100644 tests/engine/duplex/test_overlap_policy.py
 create mode 100644 tests/engine/duplex/test_session_manager.py
 create mode 100644 tests/engine/duplex/test_session_runner.py
 create mode 100644 tests/engine/duplex/test_vad_backend.py
 create mode 100644 tests/engine/test_duplex_omni_engine.py
 create mode 100644 tests/engine/test_duplex_orchestrator.py
 create mode 100644 tests/entrypoints/duplex/test_duplex_serving.py
 delete mode 100644 tests/entrypoints/duplex/test_runtime_adapter_boundary.py
 delete mode 100644 tests/entrypoints/duplex/test_runtime_control_redaction.py
 delete mode 100644 tests/entrypoints/duplex/test_websocket_actor.py
 delete mode 100644 tests/entrypoints/openai/test_duplex_protocol.py
 create mode 100644 tests/entrypoints/openai_api/test_duplex_api_server.py
 delete mode 100644 tests/entrypoints/openai_api/test_duplex_handler.py
 delete mode 100644 tests/entrypoints/openai_api/test_server_vad.py
 delete mode 100644 tests/entrypoints/test_async_omni_duplex.py
 delete mode 100644 tests/entrypoints/test_duplex_fence_propagation.py
 create mode 100644 tests/entrypoints/test_duplex_omni.py
 create mode 100644 tests/model_executor/models/minicpmo_4_5/duplex/test_data_plane_audio_cursor.py
 create mode 100644 tests/model_executor/models/nemotron_voicechat/duplex/conftest.py
 create mode 100644 tests/model_executor/models/personaplex/duplex/conftest.py
 create mode 100644 vllm_omni/clients/inline_duplex.py
 rename vllm_omni/{entrypoints => engine}/duplex/audio.py (96%)
 create mode 100644 vllm_omni/engine/duplex/commands.py
 create mode 100644 vllm_omni/engine/duplex/config.py
 delete mode 100644 vllm_omni/engine/duplex/control_client.py
 delete mode 100644 vllm_omni/engine/duplex/control_plane.py
 create mode 100644 vllm_omni/engine/duplex/events.py
 create mode 100644 vllm_omni/engine/duplex/plugin.py
 create mode 100644 vllm_omni/engine/duplex/realtime_commands.py
 create mode 100644 vllm_omni/engine/duplex/realtime_events.py
 delete mode 100644 vllm_omni/engine/duplex/runtime.py
 delete mode 100644 vllm_omni/engine/duplex/session.py
 create mode 100644 vllm_omni/engine/duplex/session/__init__.py
 create mode 100644 vllm_omni/engine/duplex/session/append_task.py
 rename vllm_omni/{entrypoints/duplex => engine/duplex/session}/commit_policy.py (91%)
 create mode 100644 vllm_omni/engine/duplex/session/context.py
 create mode 100644 vllm_omni/engine/duplex/session/control.py
 create mode 100644 vllm_omni/engine/duplex/session/emitter.py
 rename vllm_omni/{entrypoints/duplex/protocol.py => engine/duplex/session/engine_session.py} (56%)
 create mode 100644 vllm_omni/engine/duplex/session/helpers.py
 rename vllm_omni/engine/duplex/{ => session}/lease.py (92%)
 create mode 100644 vllm_omni/engine/duplex/session/manager.py
 create mode 100644 vllm_omni/engine/duplex/session/model_channel.py
 create mode 100644 vllm_omni/engine/duplex/session/overlap_policy.py
 create mode 100644 vllm_omni/engine/duplex/session/playback_ledger.py
 create mode 100644 vllm_omni/engine/duplex/session/runner.py
 create mode 100644 vllm_omni/engine/duplex/turn_detection.py
 create mode 100644 vllm_omni/engine/duplex/vad.py
 create mode 100644 vllm_omni/engine/duplex_omni_engine.py
 create mode 100644 vllm_omni/engine/duplex_orchestrator.py
 create mode 100644 vllm_omni/engine/omni_engine_base.py
 create mode 100644 vllm_omni/entrypoints/async_omni_base.py
 create mode 100644 vllm_omni/entrypoints/duplex/audio_encoding.py
 delete mode 100644 vllm_omni/entrypoints/duplex/capability.py
 delete mode 100644 vllm_omni/entrypoints/duplex/chat_fallback.py
 delete mode 100644 vllm_omni/entrypoints/duplex/realtime_output.py
 delete mode 100644 vllm_omni/entrypoints/duplex/realtime_session.py
 delete mode 100644 vllm_omni/entrypoints/duplex/realtime_state.py
 delete mode 100644 vllm_omni/entrypoints/duplex/runtime_adapter.py
 delete mode 100644 vllm_omni/entrypoints/duplex/runtime_bridge.py
 delete mode 100644 vllm_omni/entrypoints/duplex/server_vad.py
 delete mode 100644 vllm_omni/entrypoints/duplex/session_runner.py
 create mode 100644 vllm_omni/entrypoints/duplex_omni.py
 delete mode 100644 vllm_omni/entrypoints/duplex_request_client.py
 delete mode 100644 vllm_omni/model_executor/models/minicpmo_4_5/duplex/adapter.py
 create mode 100644 vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py
 delete mode 100644 vllm_omni/model_executor/models/minicpmo_4_5/duplex/runtime.py
 delete mode 100644 vllm_omni/model_executor/models/minicpmo_4_5/duplex/serving_adapter.py
 create mode 100644 vllm_omni/utils/audio_resample.py

diff --git a/.buildkite/common/ci_source_file_dependencies.yml b/.buildkite/common/ci_source_file_dependencies.yml
index 33def4de450..e29001d9a46 100644
--- a/.buildkite/common/ci_source_file_dependencies.yml
+++ b/.buildkite/common/ci_source_file_dependencies.yml
@@ -38,9 +38,13 @@ x-minicpmo-4-5: &minicpmo_4_5
 x-minicpmo-4-5-duplex: &minicpmo_4_5_duplex
   - vllm_omni/deploy/minicpmo_4_5_duplex.yaml
   - vllm_omni/engine/duplex/
+  - vllm_omni/engine/duplex_omni_engine.py
+  - vllm_omni/engine/duplex_orchestrator.py
+  - vllm_omni/engine/omni_engine_base.py
   - vllm_omni/entrypoints/duplex/
+  - vllm_omni/entrypoints/duplex_omni.py
+  - vllm_omni/entrypoints/async_omni_base.py
   - vllm_omni/clients/
-  - vllm_omni/entrypoints/duplex_request_client.py
   - vllm_omni/outputs/duplex.py
   - vllm_omni/model_executor/duplex_sampling.py
   - vllm_omni/experimental/fullduplex/
@@ -249,7 +253,11 @@ source_file_dependencies:
     - tests/assets/minicpmo_4_5/
     - tests/clients/
     - tests/engine/duplex/
+    - tests/engine/test_duplex_omni_engine.py
+    - tests/engine/test_duplex_orchestrator.py
     - tests/entrypoints/duplex/
+    - tests/entrypoints/test_duplex_omni.py
+    - tests/entrypoints/openai_api/test_duplex_api_server.py
     - tests/model_executor/models/minicpmo_4_5/duplex/
 
   omni_minicpmo_4_5_duplex_perf:
diff --git a/.buildkite/cuda/test-merge.yml b/.buildkite/cuda/test-merge.yml
index d600e8fbef8..87d4c536231 100644
--- a/.buildkite/cuda/test-merge.yml
+++ b/.buildkite/cuda/test-merge.yml
@@ -66,7 +66,9 @@ steps:
         # 0.26 startup regression is understood and fixed.
         timeout_in_minutes: 90
         commands:
-          - pytest -s -v tests/entrypoints/ -m "advanced_model and cuda and H100" --run-level "advanced_model"
+          # Turn-based server VAD over /v1/realtime is deferred to RFC #7181 PR 5
+          # (see the P0 thread on #7413); the test stays in the tree and runs again there.
+          - pytest -s -v tests/entrypoints/ -m "advanced_model and cuda and H100" --run-level "advanced_model" --deselect tests/entrypoints/openai_api/test_qwen3_omni_realtime_websocket.py::TestQwen3OmniRealtimeWebSocket::test_server_vad_multi_turn_without_client_commit
         mirror_hardwares: h100_2
 
       - label: "Entrypoint Test with L4"
diff --git a/docs/api/README.md b/docs/api/README.md
index b2d4ea1ba3b..db760506eaf 100644
--- a/docs/api/README.md
+++ b/docs/api/README.md
@@ -5,6 +5,9 @@
 Main entry points for vLLM-Omni inference and serving.
 
 - [vllm_omni.entrypoints.async_omni.AsyncOmni][]
+- [vllm_omni.entrypoints.async_omni_base.AsyncOmniBase][]
+- [vllm_omni.entrypoints.duplex_omni.DuplexOmni][]
+- [vllm_omni.entrypoints.duplex_omni.DuplexSessionHandle][]
 - [vllm_omni.engine.cfg_companion_tracker.CfgCompanionTracker][]
 - [vllm_omni.entrypoints.cli.benchmark.base.OmniBenchmarkSubcommandBase][]
 - [vllm_omni.entrypoints.cli.benchmark.main.OmniBenchmarkSubcommand][]
@@ -17,12 +20,13 @@ Main entry points for vLLM-Omni inference and serving.
 
 ## Clients
 
-Client libraries that talk to a running vLLM-Omni server (the full-duplex Realtime client and its per-model session presets).
+Client libraries for full-duplex sessions: the Realtime WebSocket client, the in-process client over `DuplexOmni`, and the per-model session presets.
 
 - [vllm_omni.clients.duplex.AudioDelta][]
 - [vllm_omni.clients.duplex.AudioFormat][]
 - [vllm_omni.clients.duplex.ConnectionResumed][]
 - [vllm_omni.clients.duplex.DuplexClient][]
+- [vllm_omni.clients.duplex.DuplexClientBase][]
 - [vllm_omni.clients.duplex.DuplexClientError][]
 - [vllm_omni.clients.duplex.DuplexConnectionError][]
 - [vllm_omni.clients.duplex.DuplexEvent][]
@@ -44,6 +48,7 @@ Client libraries that talk to a running vLLM-Omni server (the full-duplex Realti
 - [vllm_omni.clients.duplex.TextDelta][]
 - [vllm_omni.clients.duplex.TranscriptDelta][]
 - [vllm_omni.clients.duplex.WebSocketTransport][]
+- [vllm_omni.clients.inline_duplex.InlineDuplexClient][]
 
 ## Inputs
 
diff --git a/docs/configuration/stage_configs.md b/docs/configuration/stage_configs.md
index 07beef2de45..aa81d42c684 100644
--- a/docs/configuration/stage_configs.md
+++ b/docs/configuration/stage_configs.md
@@ -17,6 +17,7 @@ Common `PipelineConfig` fields include:
 | ------- | ------------- |
 | `model_type` | Pipeline identifier used during model and config resolution. |
 | `default_deploy_config_name` | Bundled deploy YAML loaded when the user does not pass `deploy_config`. |
+| `duplex_plugin` | Dotted path of the model's `DuplexModelPlugin`. Set only for full-duplex models; it makes `vllm-omni serve` run the model through `DuplexOmni` (a server whose every surface runs on a duplex session) and the engine host a `DuplexOrchestrator` with the plugin loaded. |
 | `model_arch` | Default Hugging Face architecture for the pipeline. |
 | `hf_architectures` | Architecture names used to identify checkpoints whose `model_type` is shared. |
 | `hf_config_predicate` | Optional predicate used to select between pipelines with otherwise identical HF metadata. |
@@ -52,7 +53,7 @@ The new deploy schema lives under `vllm_omni/deploy/` and is paired with a froze
 | ------- | ------ | ---------- | --------- | ------------- |
 | `base_config` | str (path) | optional | — | Overlay parent (relative or absolute). `stages:` / `platforms:` deep-merged by stage_id; other scalars overlay-wins. Intended for user-authored overlays; prod yamls stay flat. |
 | `async_chunk` | bool | optional | `true` | Enable chunked streaming between stages. Pin to `false` if the pipeline runs end-to-end. |
-| `session_mode` | str | optional | `"turn"` | Session behavior. MiniCPM-o 4.5 deploy YAMLs set `"duplex"` so `/v1/realtime` and chat share the same profile. |
+| `session_mode` | str | optional | `"turn"` | Session behavior. Duplex models (pipelines with a `duplex_plugin`, e.g. MiniCPM-o 4.5) set `"duplex"`; `vllm-omni serve` then serves it over `/v1/realtime?duplex=1` and `/v1/chat/completions`, both on duplex sessions. |
 | `active_stream_window` | int | optional | `0` | Number of active downstream stream slots; `0` preserves all-stream cycling. |
 | `duplex_session` | dict | optional | runtime defaults | Full-duplex session lifecycle, buffering, replay, and capacity limits. |
 | `connectors` | dict | optional | `null` | Named connector specs (`{name, extra}`). Referenced by each stage's `input_connectors` / `output_connectors`. See [Connector schema](#connector-schema). |
diff --git a/docs/design/fullduplex.md b/docs/design/fullduplex.md
index 7d3d5ec9572..4646b85cd0b 100644
--- a/docs/design/fullduplex.md
+++ b/docs/design/fullduplex.md
@@ -1,1070 +1,373 @@
-# MiniCPM-o 4.5 Full-Duplex Runtime Architecture
+# Unified Full-Duplex Framework
 
-> Relocation note: after the H20 validation recorded below, the full-duplex
-> implementation moved out of `vllm_omni/experimental/fullduplex/` into the
-> stable tree (`vllm_omni/engine/duplex/`, `vllm_omni/entrypoints/duplex/`,
-> `vllm_omni/model_executor/models/minicpmo_4_5/duplex/`, and companion
-> modules). Module paths in this document reflect the new layout; the runtime
-> evidence was produced on the pre-move tree, which is file-identical apart
-> from module paths.
+This document is the design record of the full-duplex serving framework:
+the engine-resident session model, the typed command/event contract, the
+single model plugin, and the serving/API surfaces built on top of them. It is
+the owner document for `vllm_omni/engine/duplex/**`,
+`vllm_omni/engine/duplex_omni_engine.py`,
+`vllm_omni/engine/duplex_orchestrator.py`,
+`vllm_omni/entrypoints/duplex_omni.py`, `vllm_omni/entrypoints/duplex/**`,
+`vllm_omni/clients/**` and the per-model `duplex/` packages.
 
-## Purpose
-
-This document records the runtime architecture implemented by PR #3907, the
-cleanup applied after published commit `e011d936`, and the remaining work that
-must not be advertised as complete. Implemented contracts and future
-architecture work are called out separately below.
-
-The checkpoint preserves the active runtime path already exercised on H20. It does
-not introduce another reducer, controller, worker provider, or shadow runtime.
-
-## Review Snapshot
-
-- PR: `vllm-project/vllm-omni#3907`
-- Published head before this refactor: `e011d936`
-- Published base snapshot: `62589203`
-- Published diff: 93 files, approximately `+29.2k/-0.6k`
-- Local runtime and pytest validation: intentionally not used
-- Required validation environment: an NVIDIA H20 CUDA host
-- PR head reviewed for the current cleanup:
-  `f4f78fa555af4d65e46b003022d352ca2ea9d703`
-- Validated tree: the uncommitted refactor synchronized file-for-file to the
-  isolated H20 worktree on 2026-07-20
-
-The current tree has received fresh H20 focused and E2E validation against vLLM
-0.25.0. The final affected matrix includes the pre-response continuation and
-Stage1 CUDA Graph padding regressions. The checked-in MiniCPM profile admits
-two concurrent sessions through an engine-owned limit; a third
-session was rejected and capacity returned after one session closed. The two
-accepted sessions independently completed their audio, transcript, response,
-playback, and close lifecycles. This is isolation and admission evidence for the
-tested two-session deployment, not a production fairness, arbitrary-capacity,
-or failure-recovery claim. The validated paths include the MiniCPM duplex
-runtime extension, typed resumable policy, extracted control plane and clients, request
-preregistration, typed direct-output decision, engine-managed two-session
-capacity in the checked-in deploy profile, separate public/runtime configuration
-channels, private Session ledgers, ordered `session.update`, the MiniCPM runner
-fast path, continuous
-browser input, and the final Realtime input-lifecycle fixes. Exact evidence and
-scope limits are recorded below.
-
-## Scope
-
-The checkpoint keeps these verified contracts:
-
-- MiniCPM Stage0 conversation KV continuity;
-- Stage1 TTS and Token2Wav continuity;
-- model-owned listen/speak decisions on the normal auto-response path;
-- continuous browser PCM upload during assistant playback, without browser VAD
-  or browser-generated input commits;
-- segment EOS and turn EOS as different boundaries;
-- transcript/audio cursors scoped to a response and turn;
-- playback acknowledgement and history commit;
-- Stage0 request metadata routed per batch row rather than inherited from the
-  first request in the batch;
-- Stage0 token timing snapshots and client-observed audio chunk cadence;
-- scheduler data-plane append over a resumable request;
-- stale epoch/turn/response fencing;
-- `/v1/duplex` and OpenAI Realtime projection;
-- optional OpenAI `server_vad` turn detection backed by a process-shared Silero
-  model and per-session VAD state;
-- existing JoyVL behavior.
-
-The checkpoint does not claim:
-
-- scheduler-native KV append;
-- an acoustic-onset-to-cancel latency target across arbitrary client chunk sizes;
-- production multi-session admission, fairness, capacity, or failure recovery;
-- bounded long-session KV;
-- audio/video synchronization beyond one camera frame per model unit (camera
-  frames ride the audio appends as `video_frames`; the wire contract is in the
-  [Realtime Duplex API](../serving/realtime_duplex_api.md) guide).
-
-## Active Runtime Path
-
-The actual path is:
-
-```text
-WebSocket
-  -> OmniDuplexSessionHandler
-  -> DuplexSession + MiniCPMO45ServingSessionState
-  -> DuplexRequestClient
-  -> AsyncOmni thin open/append/signal/close proxies
-  -> DuplexControlClient over the engine-owned correlated RPC transport
-  -> DuplexControlPlane + DuplexSessionRuntimeManager
-  -> MiniCPM DuplexRuntimeExtension + engine session/stage bindings
-  -> StagePool
-  -> resumable scheduler request
-  -> MiniCPM Stage0
-  -> Stage1 TTS / Token2Wav
-  -> output processor
-  -> Realtime protocol projection
-  -> WebSocket writer
-```
-
-The removed typed reducer/facade and worker-provider runtimes were not in this
-path. This refactor continues to modify only the path above.
-
-## State Ownership
-
-The architecture allows several state objects only when their facts are
-orthogonal.
-
-| Owner | Authoritative facts |
-| --- | --- |
-| `DuplexSession` | session state, epoch, turn, active/last response, pending input, overlap duration, playback cursor, history |
-| `MiniCPMO45ServingSessionState` | MiniCPM PCM buffer, deferred overlap payload, data-plane task, continuation effect counter |
-| `DuplexWebSocketActor` | inbound mailbox, outbound queue, writer, transport close state, effect task handles |
-| `NativeRealtimeSessionProtocol` | wire-only response/item projection and input-buffer projection |
-| `DuplexSessionRuntimeManager` | fence snapshot, append reservation, completed-operation cache, resource reservations, stage bindings |
-| `DuplexControlPlane` | control-message validation, transactional open/append/update/close, extension invocation, typed segment/output decisions |
-
-Important distinctions:
+The public wire contract lives in
+[`docs/serving/realtime_duplex_api.md`](../serving/realtime_duplex_api.md);
+this page describes how it is produced.
 
-- Realtime response IDs are projection caches, not domain decision sources.
-- Engine fences duplicate identity across a process boundary by design; they
-  are immutable validation snapshots.
-- Stage bindings are engine resources, not serving response state.
-- `continuation_owner_id` scopes an effect counter either to a visible response
-  or, before `response.created`, to an explicit model turn. A pre-response
-  continuation also revalidates request, epoch, turn state, and model-turn
-  identity immediately before append; it cannot survive turn completion.
-- runtime open/close acknowledgements are handler-local effect bookkeeping,
-  not Session lifecycle.
-
-## Implemented Concurrency Contracts
-
-### Single inbound mailbox
-
-The Actor now uses one:
-
-```python
-asyncio.Queue[event]
-```
-
-This replaces competing control/input/event `Queue.get()` tasks and the
-deferred-event list while preserving WebSocket arrival order. A later close,
-cancel, or clear must not overtake earlier append, playback ACK, or
-session-update events. Slow runtime appends remain background tasks. Cancelling
-their asyncio task does not stop a synchronous callable already running in the
-default executor, so cancellation correctness is provided by the engine fence,
-not by `Task.cancel()`.
-
-Properties covered by focused tests:
-
-- every enqueued event is delivered exactly once;
-- terminal control preserves wire order while cancelling background work;
-- clear and cancel never scan or delete later mailbox events;
-- one writer owns all WebSocket sends.
-
-### Correlated RPC result router
-
-`AsyncOmniEngine` now has one consumer for `rpc_output_queue`. Results route by:
-
-```text
-("duplex", control_id)
-("collective", rpc_id)
-```
-
-The router replaces the global RPC lock. It supports out-of-order replies,
-timeout unregister, late-result rejection, fatal-error broadcast, and close
-unblocking.
-
-Additional lifecycle rules:
-
-- uncorrelated non-fatal errors are not broadcast to unrelated waiters;
-- a latched fatal rejects new calls before they enter the request queue;
-- `EngineDeadError` is broadcast directly to the RPC queue even though the
-  orchestrator consumes that exception during teardown;
-- shutdown closes the router before joining the orchestrator;
-- failure to enqueue shutdown closes the request queue and still attempts a
-  bounded orchestrator join;
-- `StageRuntime` cleanup runs only after the orchestrator has stopped, avoiding
-  concurrent client teardown.
-
-The router removes wait-side head-of-line blocking. The orchestrator request
-handler remains ordered, but executor submission order is not itself a session
-ordering guarantee.
-
-### Extracted control ownership
-
-The generic engine mechanism and the duplex plugin are split by
-responsibility:
-
-| Module | Responsibility |
-| --- | --- |
-| `engine.messages` | ordinary engine queue messages and collective RPC envelopes |
-| `engine.rpc_result_router` | generic correlation routing through each result message's `rpc_correlation_key` |
-| `engine.duplex.contracts` | immutable duplex DTOs, extension/stage protocols, typed decisions, request-ID codec |
-| `engine.duplex.lease` | duplex lease activity, TTL/grace configuration, and expiry records |
-| `engine.duplex.messages` | identity fence and duplex control message/result envelopes |
-| `engine.duplex.runtime` | extension loading, validation, and compatibility exports |
-| `engine.duplex.session` | session resources, fences, append reservations, idempotency cache, binding cleanup |
-| `engine.duplex.control_plane` | control algorithms and the narrow `DuplexStagePort` used to submit and clean up stage requests |
-| `engine.duplex.control_client` | typed control-message construction and calls through the engine-owned correlated RPC transport |
-| `entrypoints.duplex_request_client` | deterministic request identity, client-state preregistration, acknowledgement validation, data-plane collection, rollback |
-
-`Orchestrator`, `AsyncOmniEngine`, and `AsyncOmni` retain explicit wiring and
-compatibility proxies. They no longer own the corresponding duplex algorithms.
-The ControlClient does not own waiters or consume the result queue;
-`RpcResultRouter` remains the single correlation owner for both duplex and
-collective RPC. The ControlPlane receives a narrow stage port rather than the
-Orchestrator object.
-
-Control-plane enablement is independent from extension presence.
-`PipelineConfig.duplex_control_enabled` determines whether an Orchestrator
-constructs a ControlPlane. This preserves extension-free
-`TURN_COMMIT_ONLY` deployments while allowing ordinary deployments to use a
-single `None` fast-path check. The MiniCPM pipeline explicitly enables control
-and separately selects its runtime extension.
-
-### Transactional open and append
-
-Opening a native session registers its engine state and reserves the Stage0
-request resource as one externally atomic operation. If capability, sampling,
-extension, or request-state initialization fails, the ControlPlane removes the
-session, reserved request resources, and any preregistered request state before
-returning the error. Cleanup distinguishes a reserved resource from a submitted
-request, so it does not decrement the running counter for unrelated work.
-Closing a session that never appended also removes the preregistered resource.
-
-Expiry and request-triggered cleanup use a two-step close. The runtime manager
-first marks the session closing but retains it in the admission set. Only a
-successful stage cleanup finalizes and removes the session. A blocked or failed
-cleanup therefore continues to consume its server-owned slot and is retried;
-replacement admission cannot overlap request or KV resources that are still
-owned by the closing session.
-
-Append uses prepare/submit/commit ordering. `prepare_append()` computes the
-next sequence values without mutating the session. Prompt planning and stage
-submission use that reservation, and only a successful submit commits
-`input_seq`, `input_turn_seq`, and the accepted fence. Serving uses a matching
-PCM reservation and consumes bytes only after the append acknowledgement;
-failure or a closed predecessor rolls the bytes back. An `operation_id` caches
-completed append results so a retry cannot submit the same physical append
-twice.
-
-### Ordered append and configuration effects
-
-Native append effects form a per-session tail. Each append awaits its
-predecessor before entering the engine, and `session.update` awaits that same
-tail before changing either the serving aggregate or engine configuration.
-Consequently, an append received before an update uses the old immutable
-sampling snapshot, while the first accepted append after the update uses
-the new generation.
-
-The engine increments `config_generation` when it accepts the replacement
-configuration. At the next append boundary, the control plane rebuilds sampling
-parameters from stage defaults through the model extension. It never mutates
-the snapshot of a segment already in progress.
-
-### Irreversible cancellation fence
-
-Every cancel control carries the cancelled fence and the next session fence.
-The `AsyncOmni` facade preserves both values across the serving,
-entrypoint, engine-message, and orchestrator boundaries. The orchestrator then
-atomically:
-
-1. advances the runtime state to the next fence;
-2. releases and aborts bindings owned by the cancelled fence;
-3. permanently rejects an append that arrives later with the old fence.
-
-Missing `next_fence` is rejected without releasing bindings; the engine never
-advances independently from serving. A late cancel cannot move a session
-backward when the runtime is already on a newer fence. Idle playback clear does
-not send an engine cancel because no runtime resource is being cancelled.
-
-`model_native_duplex` also validates its engine-client contract before opening
-the session. The open, append, signal, and close methods must exist and declare
-the required `fence` arguments; signal must additionally accept `next_fence`.
-An older or custom client that cannot preserve this boundary fails with
-`runtime_contract_invalid` instead of silently running an unfenced native
-session. The generic serving-session adapter retains its compatibility behavior.
-
-`DuplexFence` also carries a server-side session incarnation. Reusing a public
-session ID after close increments that incarnation, and resource request IDs
-include it after the first incarnation. A synchronous append from a closed
-session therefore cannot be accepted by a newly opened session with the same
-public ID. Stale close validates the full fence before removing the runtime
-registry entry or releasing bindings.
-
-## Implemented Serving Ownership
-
-### Session-owned response and overlap state
-
-The Actor no longer stores:
-
-- a Session reference;
-- lifecycle mirror state;
-- active or last response ID;
-- overlap duration;
-- response-in-progress or playback business predicates;
-- runtime open/close acknowledgements.
-
-`DuplexSession.begin_response()` owns both active and last response identity.
-The Session owns overlap accumulation/reset and playback state.
-
-One `native_response_in_progress()` predicate now covers:
-
-- active response ID;
-- active engine request ID;
-- uncommitted ACK-only playback;
-- active generic response task;
-- response-bound append tasks;
-- MiniCPM data-plane task;
-- assistant-generating turn state.
-
-The write-only `MiniCPMO45ServingSessionState.response_emitted` field and a dead
-data-plane task mirror were removed.
-
-### Response-scoped options
-
-`response.create` is represented by an immutable `ResponseCreateOptions` value.
-The Session reserves it for one response, applies it to a response-local copy
-when that response begins, and restores the base session configuration on
-completion, listen, cancellation, or failure. Instructions, voice, modalities,
-temperature, token limit, format, tools, and conversation metadata therefore do
-not mutate the permanent session configuration or leak into a later response.
-
-### Explicit event effects and pure writer
-
-Business paths call `emit_event()`. It serializes domain effects and outbound
-queue insertion with one session-local lock. Deferred append starts outside the
-lock so recursive event emission cannot deadlock.
-
-The writer only:
-
-1. dequeues an event;
-2. applies late stale filtering to streaming model output;
-3. projects the event to the selected wire protocol;
-4. sends JSON.
+## Purpose
 
-The writer does not promote overlap, clear input, advance Session state, call
-the engine, or commit history.
+A full-duplex model listens and speaks at the same time: audio streams into
+the model while it produces audio, the model decides when to speak, and the
+user can interrupt. Serving such a model needs a long-lived session with its
+own identity (epoch, turn), ledgers (input, response, playback, history), a
+lease (idle TTL, disconnect grace, resume) and a binding to the resumable
+stage requests that carry the session's audio through the pipeline.
 
-### Single terminal acceptance point
+The framework gives that session exactly one owner, keeps the generic
+turn-based stack free of duplex code, and exposes the same session to three
+consumers: the OpenAI Realtime WebSocket route, the in-process Python API and
+the model plugins.
 
-Terminal events are accepted or rejected before domain effects run:
+## Architecture
 
 ```text
-response.done
-response.listen
-audio.cancelled
-input.cancelled
-session.closed
+              Python users                                WebSocket clients
+        ┌──────────────────────┐                    ┌────────────────────────┐
+        │  InlineDuplexClient  │                    │      DuplexClient      │
+        │  (DuplexClientBase)  │                    │   (DuplexClientBase)   │
+        └──────────┬───────────┘                    └───────────┬────────────┘
+                   │   DuplexSessionHandle                      │ /v1/realtime?duplex=1 (alias /v1/duplex)
+                   │                                            ▼
+                   │                          ┌──────────────────────────────────────┐
+                   │                          │ OmniDuplexSessionHandler (thin)      │
+                   │                          │  websocket I/O, command_from_realtime│
+                   │                          │  event.to_realtime(), attachment /   │
+                   │                          │  resume tokens / replay journal      │
+                   │                          └──────────────────┬───────────────────┘
+                   ▼                                             ▼   DuplexSessionHandle
+        ┌──────────────────────────────────────────────────────────────────────────────┐
+        │ DuplexOmni(AsyncOmni)                      [entrypoints/duplex_omni.py, thin] │
+        │   open_session / get_session / resume_session / detach_session / close_session│
+        │   DuplexSessionHandle: submit(DuplexCommand) / events() -> DuplexEvent       │
+        └──────────────────────────────────────┬───────────────────────────────────────┘
+                                               │ engine.open/close/resume/touch_session_async (RPC)
+                                               │ engine.submit_command_async (one-way)
+                                               ▼
+        ┌──────────────────────────────────────────────────────────────────────────────┐
+        │ DuplexOmniEngine(AsyncOmniEngine) [engine/duplex_omni_engine.py, thin]        │
+        │   loads the plugin, validates session_mode, builds queue messages            │
+        │  └─ DuplexOrchestrator(Orchestrator)            [engine/duplex_orchestrator.py]│
+        │       template seams + DuplexStagePort over the shared stage machinery       │
+        │       ├─ DuplexSessionManager      admission, backpressure, lease reaper,     │
+        │       │                            open/close/resume/touch, command dispatch  │
+        │       └─ DuplexSessionRunner ×N    ONE session state (DuplexEngineSession),   │
+        │                                    ordered mailbox, append planning + stage   │
+        │                                    submit, output projection, response /     │
+        │                                    playback / history, VAD, typed events     │
+        │       plugin: DuplexModelPlugin    (PipelineConfig.duplex_plugin, one/model)  │
+        └──────────────────────────────────────────────────────────────────────────────┘
 ```
 
-For a terminal carrying an epoch, that epoch must match the current Session.
-Stale cancellation therefore cannot reset overlap belonging to a later turn.
-Once a terminal is accepted and its effect is applied, the writer cannot revoke
-it because close or epoch state changed while it waited in the output queue.
-
-Streaming audio/text deltas still receive late stale filtering at send time,
-which prevents queued old audio from leaking after a cancel or epoch bump.
-
-## Runtime Type Boundary
-
-The stable kernel is deliberately limited to generic engine and scheduler
-mechanisms:
+In each layer the duplex class extends the turn-based one, which extends
+the shared base. The dependency runs duplex -> turn-based and never the
+reverse, so the turn-based stack is unchanged and the duplex stack reuses
+its request machinery instead of duplicating it:
 
 ```text
-vllm_omni.engine.messages                  # ordinary queue and collective RPC envelopes
-vllm_omni.engine.rpc_result_router         # generic correlation routing
-vllm_omni.engine.async_engine_utils        # ordinary engine lifecycle helpers
+OmniBase                          OmniEngineBase                        OrchestratorBase
+ ├─ Omni       (sync, turn)        └─ AsyncOmniEngine  (turn requests)   └─ Orchestrator        (turn-based admission)
+ └─ AsyncOmniBase                      └─ DuplexOmniEngine (session msgs)    └─ DuplexOrchestrator  (hosts DuplexSessionManager,
+     └─ AsyncOmni  (EngineClient)                                                                     implements DuplexStagePort)
+         └─ DuplexOmni
+
+AsyncOmni._create_engine  -> AsyncOmniEngine     AsyncOmniEngine._create_orchestrator  -> Orchestrator
+DuplexOmni._create_engine -> DuplexOmniEngine    DuplexOmniEngine._create_orchestrator -> DuplexOrchestrator
 ```
 
-The full-duplex implementation lives in dedicated duplex modules:
+Each concrete class constructs its collaborator in an explicit factory
+method the base calls at the right moment: `OmniBase.__init__` calls
+`self._create_engine(...)`; `OmniEngineBase._bootstrap_orchestrator` calls
+`self._create_orchestrator(...)` on the orchestrator thread once the stages
+are initialized. `DuplexOmniEngine._create_orchestrator` passes the loaded
+plugin and the session runtime config to `DuplexOrchestrator` directly.
+
+### Design rules
+
+1. **One session authority.** The whole duplex session (config, epoch/turn,
+   ledgers, lease, stage request resources, model state, projection state) is
+   one object, `DuplexEngineSession`, owned by one `DuplexSessionRunner` on
+   the orchestrator loop. Nothing above the engine keeps session state beyond
+   a handle (session id, event queue, capabilities, public session object).
+2. **Typed contract.** Commands into a session are `DuplexCommand`
+   dataclasses (`engine/duplex/commands.py`); outputs are `DuplexEvent`
+   dataclasses (`engine/duplex/events.py`). `command_from_realtime()` and
+   `DuplexEvent.to_realtime()` derive the OpenAI Realtime JSON, so the wire
+   format is never hand-built, and the websocket handler and the inline client
+   share one conversion.
+3. **Generic bases and the turn-based classes have zero duplex vocabulary.**
+   `OmniBase`, `AsyncOmniBase`, `AsyncOmni`, `OmniEngineBase`,
+   `AsyncOmniEngine`, `OrchestratorBase` and `Orchestrator` carry only
+   template seams; `tests/engine/test_duplex_import_boundary.py` checks that
+   importing the turn-based stack loads no duplex module.
+4. **Every surface a duplex server exposes is backed by a session.**
+   `vllm-omni serve` constructs `DuplexOmni` when the pipeline declares
+   `duplex_plugin`; the server exposes `/v1/realtime?duplex=1` (alias
+   `/v1/duplex`), `POST /v1/chat/completions`, `/v1/models` and `/health`, and
+   every other turn-based route reports "not available". The chat route is
+   served by `DuplexChatCompletionsAdapter`, a Realtime client that runs one
+   short-lived session per request: speech becomes a committed turn, text is
+   seeded as the session's opening turn because a model-native model takes a
+   turn only when it hears speech. Whether a model can be reached with text is
+   `DuplexCapabilities.supports_chat_completions`; one that cannot is refused
+   at once rather than left to idle out. Turn-based use of the same model stays
+   available offline through `Omni` / `AsyncOmni`.
+5. **Serving is transport only.** The websocket handler does socket I/O,
+   wire-envelope validation, command translation, event rendering and the
+   attachment/resume/replay bookkeeping; it holds no session state.
+6. **No `typing.Protocol`** in the duplex surfaces: the plugin, data plane,
+   session state, PCM buffer, stage port and client transport seams are ABCs.
+
+## Package layout
 
 ```text
-vllm_omni.engine.duplex.runtime
-                                           # extension loading and validation
-vllm_omni.engine.duplex.contracts
-                                           # immutable DTOs and narrow protocols
-vllm_omni.engine.duplex.lease
-                                           # duplex lease primitives
-vllm_omni.engine.duplex.messages
-                                           # duplex identity and queue envelopes
-vllm_omni.engine.duplex.session
-                                           # session transaction implementation
-vllm_omni.engine.duplex.control_plane
-                                           # engine-side control algorithms
-vllm_omni.engine.duplex.control_client
-                                           # correlated control client
-vllm_omni.entrypoints.duplex_request_client
-                                           # entrypoint request/output lifecycle
+vllm_omni/
+├── entrypoints/
+│   ├── omni_base.py                 OmniBase (+ abstract _create_engine)
+│   ├── async_omni_base.py           AsyncOmniBase (output pump, _route_engine_message seam)
+│   ├── async_omni.py                AsyncOmni (turn-based requests)
+│   ├── duplex_omni.py               DuplexOmni, DuplexSessionHandle (thin pipe)
+│   ├── duplex/                      SERVING (thin)
+│   │   ├── serving.py               OmniDuplexSessionHandler
+│   │   ├── realtime_input.py        RealtimeEnvelope (query rules, first message), parse_resume_request
+│   │   ├── session_attachment.py    DuplexSessionAttachmentRegistry (resume tokens, replay journal)
+│   │   ├── audio_encoding.py        encode_audio, injected into DuplexOmniEngine for the plugin's data plane
+│   │   ├── chat_completions.py      DuplexChatCompletionsAdapter (/v1/chat/completions on a session per request)
+│   │   └── websocket.py             websocket send/close/receive helpers
+│   └── openai/api_server.py         builds DuplexOmni for duplex models; session-backed app state
+├── engine/
+│   ├── omni_engine_base.py          OmniEngineBase (stage processes, orchestrator thread, queues, RPC)
+│   ├── async_omni_engine.py         AsyncOmniEngine (turn-based request building)
+│   ├── duplex_omni_engine.py        DuplexOmniEngine (session message surface, creates DuplexOrchestrator)
+│   ├── orchestrator.py              OrchestratorBase + Orchestrator
+│   ├── duplex_orchestrator.py       DuplexOrchestrator (+ DuplexOrchestratorRequestState; implements DuplexStagePort)
+│   └── duplex/
+│       ├── commands.py              DuplexCommand dataclasses, command_from_realtime
+│       ├── realtime_commands.py     Realtime client event -> DuplexCommand translation
+│       ├── events.py                DuplexEvent dataclasses (+ to_realtime), REALTIME_ERROR_TYPES_BY_CODE
+│       ├── realtime_events.py       RealtimeProjectionState: internal event -> typed events
+│       ├── messages.py              queue envelopes (Open/Close/Resume/Touch/Command/Result/Event), DuplexSessionError
+│       ├── config.py                DuplexSessionConfig, DuplexCapabilities, ResponseCreateOptions
+│       ├── contracts.py             DuplexFence (session_id, epoch, turn_id), stage request records, DuplexStagePort
+│       ├── plugin.py                DuplexModelPlugin, DuplexModelSessionState, DuplexDataPlane, PcmAppendBuffer ABCs
+│       ├── turn_detection.py        server-side VAD turn detector used by the session
+│       ├── audio.py / vad.py / intermediate.py
+│       └── session/                 one engine-resident session and everything that runs it
+│           ├── engine_session.py    DuplexEngineSession: ledgers, lease, fence, stage resources, append sequencing
+│           ├── runner.py            DuplexSessionRunner (per-session mailbox on the orchestrator loop)
+│           ├── manager.py           DuplexSessionManager (admission, backpressure, reaper, dispatch)
+│           ├── context.py           DuplexSessionContext / DuplexRunState: what the runner shares with its components
+│           ├── emitter.py           SessionEmitter: projection, epoch filter, domain effects of a terminal event
+│           ├── model_channel.py     ModelChannel: submit an append, project stage output, continue a turn
+│           ├── control.py           SessionControl: server VAD and the events that reconfigure it
+│           ├── append_task.py       AppendAttempt: one append in flight and the rollback its failure owes
+│           ├── helpers.py           pure reads and payload builders over a session
+│           ├── lease.py             DuplexLeaseState (idle TTL, disconnect grace, resume generation)
+│           └── overlap_policy.py / commit_policy.py / playback_ledger.py
+├── config/stage_config.py           PipelineConfig.duplex_plugin; DuplexSessionRuntimeConfig
+├── model_executor/models/minicpmo_4_5/duplex/plugin.py   MiniCPMO45DuplexPlugin (+ data_plane, input, policy, ...)
+└── clients/
+    ├── duplex.py                    DuplexClientBase (ABC), DuplexClient (websocket), client-side events
+    ├── inline_duplex.py             InlineDuplexClient (in-process, over DuplexOmni)
+    ├── minicpmo_4_5.py              MiniCPM-o 4.5 session preset
+    └── personaplex.py               PersonaPlex session preset
 ```
 
-Stable engine and entrypoint modules import the duplex kernel eagerly at
-module load (top-of-file imports). Duplex behavior remains opt-in: the
-ControlPlane, ControlClient, and request client are *constructed* only on
-duplex-enabled deployments, and the model runtime extension still loads only
-through the dotted-string plugin path. The client-side package
-(`vllm_omni/clients/`, home of the public `DuplexClient`) is never imported
-by runtime code.
-
-`PipelineConfig.duplex_control_enabled` enables the generic mechanism, while
-`PipelineConfig.duplex_runtime_extension` separately selects the model adapter.
-The MiniCPM pipeline opts into both and installs
-`MiniCPMO45DuplexRuntimeExtension`; ordinary pipelines construct neither a
-ControlPlane nor a ControlClient. The model-neutral protocol exposes
-sampling-parameter configuration, append planning, and a typed stage-output
-decision. MiniCPM owns
-stage-specific overrides, PCM-to-token budgeting, force-listen payload policy,
-special-token interpretation, and `listen` response metadata. The generic
-Orchestrator does not parse MiniCPM session keys, `listen_token_id`, or construct
-MiniCPM metadata, and it does not import the adapter.
-
-Extension loading is fail-fast. Startup validates every required callable and
-the number and type of returned stage sampling parameters. Invalid custom
-extensions fail before a session can open.
-
-Direct listen/speak outcomes use `DuplexOutputDecision` on
-`OmniRequestOutput`. That typed envelope is authoritative over inner completion
-metadata for native projection, so a processed output cannot hide a listen
-decision merely because it retains unrelated multimodal metadata.
-
-Generic multimodal chunk accumulation lives in
-`vllm_omni.outputs.multimodal_accumulation`. It owns snapshot replacement,
-DELTA draining, and audio-finality interpretation; `OmniRequestState` only
-invokes that policy while assembling request output. Model output processors no
-longer need to add chunk-retention rules to the main output orchestration file.
-
-The strict chunk-transfer schema still contains `hidden_states.tts` as the
-generic AR-stage-to-TTS handoff and several MiniCPM streaming token IDs as
-compatibility wire fields. The latter are not a preferred generic model
-contract. Moving them behind a model-namespaced metadata envelope requires a
-versioned producer/consumer migration because unknown msgspec fields are
-rejected; silently deleting or renaming them in this checkpoint would break
-existing Stage0-to-Stage1 transfer.
-
-### Public and runtime configuration channels
-
-Control messages carry two independent snapshots:
-
-- `session_config` contains the public Realtime/session values used by serving
-  and model prompt policy;
-- `runtime_config` contains server-derived MiniCPM sampling, scheduler, context
-  reserve, prefix-budget, and resolved reference-audio values.
-
-The MiniCPM serving adapter derives `runtime_config` from deploy/model defaults
-and validated public options. Clients cannot provide private runtime keys in
-`session.create` or `session.update`; response-scoped `extra_body` drops those
-keys rather than turning them into engine policy. The ControlPlane constructs
-sampling parameters only from `runtime_config`,
-while append planning receives both snapshots explicitly. Raw Realtime
-`extra_body` is not used as the engine's sampling-policy channel.
-
-`session.update` prepares both candidates, validates the runtime candidate in
-the engine, and replaces the serving snapshots only after the engine ACK. A
-rejected candidate therefore leaves both the public configuration and runtime
-sampling generation unchanged.
-
-`DeployConfig.duplex_session` is an immutable, server-owned
-`DuplexSessionRuntimeConfig`. These limits are not read from client
-`extra_body` or session payloads:
-
-| Field | Default | Owner | Lifecycle or resource effect |
-| --- | ---: | --- | --- |
-| `idle_ttl_s` | `300.0` | Engine lease manager | Expires an attached or detached session after inactivity; `null` disables only idle expiry. |
-| `disconnect_grace_s` | `30.0` | Engine lease manager and API attachment registry | Bounds how long a detached session may retain engine resources before cleanup. |
-| `reaper_interval_s` | `5.0` | Orchestrator | Sets the cadence for lease expiry and pending cleanup retries. |
-| `resume_replay_ttl_s` | `60.0` | API attachment registry | Expires replay events retained for resume or takeover. |
-| `resume_replay_max_bytes_per_session` | `8388608` | API attachment registry | Bounds each session's replay buffer. |
-| `max_pending_input_bytes_per_session` | `16777216` | API session input ledger | Applies per-session byte backpressure before input is admitted. |
-| `max_pending_turns_per_session` | `4` | API session input ledger | Bounds queued turns that have not completed runtime processing. |
-| `max_sessions` | `1` | Engine session manager | Atomically enforces admission; closing sessions retain capacity until cleanup finalizes. |
-| `completed_append_cache_size` | `256` | Engine session manager | Bounds completed append idempotency records per session. |
-
-Deploy profiles may lower or raise these values to match scheduler capacity,
-but clients cannot override them. The engine remains authoritative for
-admission and cleanup ownership even when the API performs an early check.
-
-### Client-side companion package
-
-The public client surface ships under `vllm_omni/clients/` and stays on the
-consumer side of the boundary above: `vllm_omni.clients.duplex` provides the
-model-agnostic `DuplexClient` (typed events, per-response demux via
-`ResponseHandle`, `session.resume` with acknowledgement-based replay dedup)
-and the `EventCollector` helper used for timing and request-metric summaries.
-Model-specific session defaults live in thin per-model preset modules —
-`vllm_omni.clients.minicpmo_4_5.create_duplex_session_config()` and
-`vllm_omni.clients.personaplex.create_duplex_session_config()` — so the core
-client never imports model packages and the model duplex plugin packages
-never import the client (both directions are enforced by tests:
-`tests/engine/test_duplex_import_boundary.py`,
-`tests/entrypoints/openai_api/test_duplex_capability.py`, and the subprocess
-purity guards in `tests/clients/test_model_session_configs.py`).
-`examples/online_serving/barge_in_client.py` (with its flow companion
-`barge_in_client_flow.md`) is the runnable reference for the client library
-against a live duplex deployment. The wire vocabulary the client speaks —
-every `/v1/realtime?duplex=1` event with its OpenAI-compatibility tier and a
-JSON example, plus the native-to-Realtime name map — is catalogued in the
-[Realtime Duplex API](../serving/realtime_duplex_api.md) serving guide; that
-page derives from the normative contract table above and must be updated
-with it.
-
-## Generic-Path Cleanup
-
-Model-specific `MINICPMO45_PROFILE_LOGS` probes were removed from:
-
-- the generic AR scheduler;
-- orchestrator;
-- AsyncOmni;
-- the generic GPU AR runner.
-
-The cleanup removes the temporary serving and generic-runtime probes. The
-generic AR runner builds `DuplexSamplingRow` values only when the model exposes
-the optional `prepare_duplex_sampling()` hook, then invokes that hook exactly
-once before the normal sampler. Ordinary models do not scan request rows.
-MiniCPM owns force-listen logits, turn-ended state, and its row-local sampling
-policy behind that hook; the runner no longer reads `_minicpmo45_*` attributes
-or retries sampling after matching `TypeError` text.
-
-The scheduler no longer parses serving `session_config`, `extra_body`, or
-`duplex_stage_sampling_params`. Stage-specific overrides are materialized as
-ordinary `SamplingParams` by the model runtime extension before scheduler
-admission. Existing vLLM stop-token, EOS, and max-token handling defines each
-segment boundary; `resumable=True` parks the request for the next streaming
-update. The scheduler does not inspect a duplex dictionary, Realtime
-configuration, or MiniCPM sampling fields.
-
-The generic runner's unused `_duplex_force_listen_applied_segments` cleanup and
-the obsolete `streaming_accumulated_keys` accumulation hook were removed. The
-latter had no model producer after its upstream Qwen removal; streaming input
-still performs the ordinary replacement merge needed by active models.
-
-Local `turn.signal` transitions such as `user_started` and
-`assistant_started` no longer perform an engine RPC. Only cancellation and
-`session.update` cross the engine boundary because those operations change
-runtime resource identity or runtime configuration.
-
-During a stage transition, `StreamingInputState.source_token_decoder` exposes a
-short-lived, model-neutral decoder sourced from the upstream output processor.
-The MiniCPM Stage1 input processor consumes that capability for token-faithful
-delta transcripts. The generic orchestrator no longer installs or names a
-MiniCPM-specific bridge-state key.
-
-The stable API server imports the duplex serving package eagerly and inspects
-the deployment `session_mode` before constructing the duplex handler. Ordinary
-deployments do not create its registries and background state.
-For an enabled deployment, the client still selects the Realtime duplex route
-with `?duplex=1` (or an equivalent explicit true value). Model-name matching is
-not used for routing or native-runtime activation. MiniCPM clients explicitly
-set `extra_body.native_duplex=true`; the canonical way to do so is
-the `vllm_omni.clients.minicpmo_4_5.create_duplex_session_config()` preset,
-which the repository's barge-in example
-(`examples/online_serving/barge_in_client.py`) uses in its session payload.
-
-`DuplexRequestClient` derives the data-plane request identity from the accepted
-fence and preregisters a resumable `ClientRequestState` before the append crosses
-the engine boundary. The acknowledgement must return the same identity or the
-operation fails. Unregistered outputs, including names that merely use the old
-`duplex-` prefix, are dropped. Timeout, cancel, and close remove the
-preregistered state.
-
-## Why Scheduler Changes Remain
-
-Serving cannot preserve model KV after a segment ends. The scheduler must keep
-one resumable request in a waiting state and accept a later update:
+## Session identity
+
+- **The server allocates every session id.** `DuplexOmni.open_session`
+  generates `duplex-<uuid4 hex>`; a `session_id` / `id` key inside the
+  Realtime session object is ignored (Realtime clients echo the session object
+  back). The allocated id reaches the client in `session.created` and is the
+  only handle for `session.resume`, `close` and every command.
+- **Ids are never reused** within an engine's lifetime, so the id alone
+  identifies a session. There is no incarnation counter: stage request ids are
+  `duplex-s.<b64 session id>.e.<epoch>.r.<role>`, model-side per-session state
+  is keyed by `session_id` alone, and a command, close, touch or resume for an
+  id the manager no longer holds is answered with `unknown_session`.
+- **Staleness inside a live session is epoch-based.** `DuplexFence
+  (session_id, epoch, turn_id)` is an engine-internal identity: every stage
+  request is bound to the fence it was submitted under, cancels advance the
+  epoch, and tracked tasks re-check the epoch after each `await`.
+- **Resume identity** is `(session_id, resume_token, expected_lease_generation)`:
+  the token belongs to the attachment registry, the lease generation is the
+  engine-side compare-and-swap.
+
+## Session lifecycle
 
 ```text
-RUNNING
-  -> segment stop
-WAITING_FOR_STREAMING_REQ  (KV retained)
-  -> next append
-RUNNING
-  -> session close
-FINISHED                   (KV released)
+open   DuplexOmni.open_session(config)
+         -> engine.open_session_async(session_id, DuplexSessionConfig)      [RPC]
+         -> DuplexSessionManager.open: admission (max_sessions, closing sessions keep their slot),
+            plugin.validate_client_extra_body / prepare_runtime_config, DuplexEngineSession,
+            Stage0 request id reserved (ensure_stage_request), DuplexSessionRunner.start()
+         -> first event: SessionCreated (announces the allocated id)
+command  handle.submit(DuplexCommand)
+         -> engine.submit_command_async -> DuplexSessionCommandMessage on the request queue [one-way]
+         -> DuplexSessionManager.dispatch: unknown_session / input_backpressure checks, then runner mailbox
+output   DuplexOrchestrator._intercept_stage_output -> runner.on_stage_output -> mailbox -> typed events
+         -> output_sink (DuplexSessionEventMessage) -> DuplexOmni._route_engine_message -> handle.events()
+detach   DuplexOmni.detach_session -> touch(DETACH): engine-owned disconnect grace; expiry -> SessionExpired
+resume   DuplexOmni.resume_session(expected_lease_generation) -> lease CAS; the existing handle is re-entered
+close    DuplexOmni.close_session -> close RPC; the manager tears the runner down, then the stage cleanup
+         (abort submitted requests, release reserved ids), then SessionClosed, then the RPC result: seeing
+         the event means the admission slot is free (it is held until the cleanup succeeded)
+reap     DuplexSessionManager.reaper_loop: idle TTL / disconnect grace expiry, cleanup retries
 ```
 
-Scheduler responsibilities are limited to resumable request state, runtime
-context update, stop/boundary handling, and final release. Scheduler must not
-own response IDs, playback, overlap, Realtime events, or model policy.
-
-## Serving and Compatibility Boundaries
-
-### Normative Realtime event contract
-
-The public contract in this section applies to `/v1/realtime?duplex=1`. Internal
-duplex event names such as `response.output_audio.delta` are projection inputs,
-not additional public aliases. Events for one attachment preserve mailbox
-order; replay after resume preserves the original event order and `event_id`.
-
-Accepted compatibility aliases are normalized before mailbox admission:
-
-| Canonical input event | Accepted aliases | Contract |
-| --- | --- | --- |
-| `input.text.append` | `input_text.append`, `push_text` | Appends text to the open input item. |
-| `input_audio_buffer.append` | `input.audio.append`, `push_chunk` | Appends audio; legacy aliases default to WAV when no format is supplied. |
-| `turn.signal` | `signal_turn` | Sends an explicit turn signal; it does not imply response creation. |
-| `playback.ack` | `audio.playback_ack` | Advances playback/history only for the identified response and attachment. |
-| `session.close` | `close_session`, `close` | Closes the session after previously admitted mailbox events. |
-
-The Realtime projector emits the following response lifecycle. Cardinality is
-scoped to one `response_id` unless stated otherwise.
-
-| Public event | Trigger and ordering | Cardinality |
+### Concurrency and ordering model of the runner
+
+Everything below runs on the orchestrator asyncio loop; there is no lock.
+
+- **Single writer per session.** `DuplexEngineSession` is mutated only by its
+  runner. Inputs reach the runner through one mailbox in this order: client
+  commands (from `_request_handler`, in request-queue order), stage outputs
+  (`on_stage_output` enqueues an internal item; it does not mutate the session
+  inline), timers (silence continuation, bounded auto-response) and internal
+  items (deferred overlap promotion, VAD-synthesized commits). The mailbox
+  worker processes items one at a time.
+- **Slow work is not awaited inline.** An `AppendAudio` handler reserves
+  bytes, then schedules a tracked append task on the per-session append tail:
+  the task awaits `_offload(decode/resample/VAD)` on a dedicated
+  `ThreadPoolExecutor` owned by the manager, then `plugin.plan_append`, then
+  `stage_port.submit`. The worker returns to the mailbox immediately, so a
+  later `CancelResponse` is not blocked behind an in-flight append.
+- **Re-validation after every `await`.** A tracked task captures `(epoch,
+  turn_id)` when it starts and re-checks them before the stage submit and
+  before committing ledgers; a task that finds the epoch advanced rolls back
+  its PCM reservation and exits.
+- **Cancel is atomic at the session.** `CancelResponse` / `BargeIn` advance
+  the epoch, cancel tracked append tasks, abort the owned stage bindings
+  through the stage port and emit the cancelled terminal events before
+  yielding. An append task already past its last check is harmless: its stage
+  request is bound to the old epoch's request id, which the abort covers, and
+  the base never emits session-owned outputs to a client.
+- **Ordered event stream.** Because the epoch bump and every emission happen
+  on one loop in program order, nothing can be emitted for an old epoch after
+  its terminal event; `runner.emit()` still drops a terminal carrying a stale
+  epoch and stamps `epoch` on every event for clients that filter
+  defensively. This is a statement about order, not about latency: the engine
+  output queue and each `DuplexSessionHandle` outbox are unbounded and FIFO,
+  so a cancellation is delivered behind whatever audio was already emitted for
+  the response it cancels. A client that must stop quickly cancels its own
+  playback on `response.done` / `audio.cancelled` rather than waiting for the
+  stream to drain. Bounding those buffers and letting an accepted invalidation
+  skip undelivered media is left to the follow-up RFC.
+- **Backpressure before the mailbox.** `DuplexSessionManager.dispatch`
+  checks `max_pending_input_bytes_per_session` and reserves a pending turn for
+  `Commit` before the put; a rejected command is answered with
+  `ErrorEvent(code="input_backpressure")`.
+- **Per-response stage metrics.** `_route_output` computes the per-segment
+  `StageMetrics` before calling `_intercept_stage_output`; the runner
+  accumulates the snapshot into the active response, so
+  `ResponseDone.stage_metrics` and `metadata.vllm_omni.stage_metrics` on the
+  wire keep their meaning.
+
+## Orchestrator seams
+
+`OrchestratorBase` keeps the generic machinery (request handler skeleton,
+abort, collective RPC, output loops, stage error and dead-replica handling,
+`_route_output`, stage forwarding, prewarm, cleanup, shutdown) and offers
+these seams. `DuplexOrchestrator` extends `Orchestrator` rather than sitting
+beside it: a seam it does not override falls through to the turn-based
+implementation, and `_dispatch_message` hands anything that is not a session
+message to `super()`:
+
+| Seam | `Orchestrator` | `DuplexOrchestrator` |
 | --- | --- | --- |
-| `response.created` | First event for a visible assistant response; precedes its output-item, content-part, speak, text, and audio events. | Exactly once for every visible response. |
-| `response.speak` | The model selected speak; emitted after `response.created` and no later than the first `response.output_audio.delta`. It carries decision metadata, not transcript text. | At most once. |
-| `response.output_audio.delta` | Carries one ordered audio chunk. Every emitted audio delta is followed by a `response.output_audio_transcript.delta` for the same chunk. | Zero or more. |
-| `response.output_audio_transcript.delta` | Append-only transcript contribution paired with an audio delta; it may be empty for a text-less audio unit and must not repeat or overlap earlier text. | One per audio delta. |
-| `response.output_audio.done` | Closes the audio stream after its final delta and before response terminal events. It is omitted for a response with no audio or transcript. | At most once. |
-| `response.output_audio_transcript.done` | Contains the exact concatenation of all non-overlapping transcript deltas for the response. | At most once, and only for a non-empty transcript. |
-| `response.output_item.done` / `conversation.item.done` | Finalize the assistant item after content-part terminal events and before `response.done`. | At most once each. |
-| `response.done` | Terminal event for a created response; follows audio, transcript, content-part, and item terminal events. | Exactly once for every created response that reaches a terminal state. |
-| `rate_limits.updated` | Compatibility event emitted immediately after `response.done`; the current payload has an empty rate-limit list. | Once per emitted `response.done`. |
-| `response.listen` | The model selected listen at a model-unit boundary. It may be emitted without `response.created`; clients must not infer a missing or pending response from it. | Zero or more per session, at most once per model-unit decision. |
-
-Session lifecycle events (`session.created`, `session.updated`,
-`session.resumed`, `session.replaced`, `session.expired`, and
-`session.resync_required`) are session-scoped rather than response-scoped.
-`session.created` is emitted before held response output on a new attachment.
-Cancellation and truncation use terminal status/details on the affected
-response and never reuse that response ID for later model turns.
-
-Compatibility changes must update this table and its protocol contract tests in
-the same change. The golden transcript test requires joined
-`response.output_audio_transcript.delta` values to equal
-`response.output_audio_transcript.done.transcript`; response tests separately enforce
-at-most-once `response.speak` and terminal event cardinality.
-
-### Session internal ledgers
-
-`DuplexSession` remains the serving aggregate root and now composes
-`InputBufferState`, `ResponseState`, `PlaybackLedger`, and
-`ConversationHistory`. The ledgers are private. Read-only properties return
-tuples, snapshots, or mapping proxies, and serving modules mutate them through
-Session transition methods for request, response-turn, lifecycle, playback,
-capability replacement, and history. The Realtime session-update parser still
-normalizes individual fields before atomically retaining or rolling back the
-aggregate configuration. Further work may narrow the read-only compatibility
-surface, but it must not introduce another reducer or a second session state
-machine.
-
-### Realtime input ownership
-
-The browser is a continuous PCM producer. While the session is open and the
-microphone is unmuted, it sends `input_audio_buffer.append` every 200 ms,
-including while assistant audio is being generated or played. It does not run
-VAD and does not send `input_audio_buffer.commit`. Native Stage0 consumes the
-stream in approximately one-second model units; MiniCPM listen, speak, and turn
-EOS decisions advance the model conversation.
-
-Explicit Realtime clients may still use `input_audio_buffer.commit` to create a
-conversation item. The translator validates that wire input before producing a
-commit carrying `item_id`. Native auto-response may already have
-streamed those PCM samples into the runtime, so the runner accepts a validated
-commit even when no runtime-side chunk remains. A truly empty explicit buffer
-continues to return `input_audio_buffer_empty`.
-
-The commit-to-response contract is:
-
-| Session state at `input_audio_buffer.commit` | Runtime action | Required event outcome |
-| --- | --- | --- |
-| Auto-response disabled, valid idle input | Commit and retain the input item. | Emit `input_audio_buffer.committed`; emit no response until an explicit `response.create`. |
-| Auto-response enabled, valid idle speech | Submit the final native append for the current model turn. | Emit `input_audio_buffer.committed` before model output. Create a response only on the first visible text/audio output; a model listen decision may end with `response.listen` and no response. |
-| Auto-response enabled, short overlap during an active response | Discard the short overlap as an acknowledgement. | Emit the committed/no-response acknowledgement; do not create or defer a response. |
-| Auto-response enabled, meaningful overlap during an active response | Retain one deferred payload and promote it after the active response terminates. | Emit `input_audio_buffer.committed` with deferred metadata. A later response follows the same visible-output rule and never reuses the prior response ID. |
-| Explicit silence/noise (`is_speech=false`) | Clear the physical input without a runtime append. | Emit the committed/no-response acknowledgement followed by `response.listen`. |
-| Empty or invalid input | Reject without changing response ownership. | Emit one typed `error`; do not emit `response.created`. |
-| Previous response cancelled or truncated and cleanup complete | Apply the corresponding idle rule above. | The prior response remains terminal; any later visible output receives a new response ID. |
-
-Append tasks, explicit commits, cancellation, and deferred promotion are
-serialized by the session actor. Tests cover post-response commits, active
-playback deferral, truncated-response ownership, and two-turn
-response-required execution; the H20 validation record below is the golden
-multi-turn runtime evidence.
-
-During auto-response overlap, `preserve_realtime_input` distinguishes "do not
-append this silent chunk to the native buffer" from "clear the open Realtime
-item". Silent overlap no longer discards earlier user PCM.
-
-The first chunk of one overlapping input item also reserves its target model
-turn. A later Realtime commit uses that reserved identity even if response EOS
-has already advanced the Session turn; clear, cancel, close, and successful
-promotion release the reservation.
-
-### Physical input and model-turn identity
-
-A Realtime input item, an optional `input_audio_buffer.commit`, and a MiniCPM
-model turn are intentionally different identities. The browser normally keeps
-one input stream open without commits. Native Stage0 evaluates that stream in
-approximately one-second model units. A sampled `<|turn_eos|>` closes the
-current model turn and allows a later streamed unit to start another turn.
-Explicitly committed input may also produce only model-listen decisions and no
-spoken response.
-
-Therefore neither `model_turn_id` nor response cardinality is derived from the
-number of physical inputs. `model_turn_id` advances at model EOS. The
-`response-required` fixture may require exactly one response per requested
-turn, but `model-policy` validation must accept additional model-owned responses
-and cannot assert cross-turn transcript independence through physical-input
-attribution.
-Before closing, the model-policy demo drains every created response through
-`response.done`, acknowledges every completed audio playback, and requires a
-bounded quiet interval with no newly created response. This validates lifecycle
-completion without suppressing or overriding the model's listen/speak policy.
-
-### Non-cancel signal semantics
-
-`turn.signal` remains a public compatibility surface for local Session and
-Realtime transitions. Serving forwards only cancellation and `session.update`
-to the engine. The engine rejects arbitrary non-cancel signal names instead of
-returning a misleading supported acknowledgement. `session.update` remains a
-real engine operation because it replaces the configuration consumed by later
-append plans.
-
-## Remaining Architecture Work
-
-The following work is deliberately not hidden inside this checkpoint.
-
-### Serving composition
-
-The generic runner and runtime bridge now depend on the model-neutral
-`ServingRuntimeAdapter` protocol and no longer import MiniCPM modules. The
-`MiniCPMO45ServingRuntimeAdapter` owns MiniCPM serving state, PCM preparation,
-data-plane projection, client/runtime configuration validation, prefix policy,
-and capability projection. `PipelineConfig.duplex_serving_adapter` explicitly
-selects its import path; `AsyncOmniEngine` and `AsyncOmni` carry that path to the
-API server, which passes it into the generic handler. The handler has no model
-default and fails startup when the duplex endpoint is enabled without an
-adapter. Tests may inject an adapter instance directly. Import-boundary tests
-verify that loading the generic runner, bridge, or handler does not load MiniCPM
-modules.
-
-Behavior is still assembled through `DuplexSessionRunnerMixin`,
-`NativeRuntimeBridgeMixin`, and `ChatFallbackProjectorMixin`, so explicit
-adapter composition is only the model-policy boundary, not a completed removal
-of host-method coupling. A later refactor may replace the remaining mixins with
-explicit protocol and effect-runner dependencies while preserving one actor
-mailbox and one `DuplexSession` transition owner. Splitting those components
-must not create a second reducer or concurrent state machine.
-
-The four private Session ledgers are data partitions, not independent owners.
-`DuplexSession` intentionally remains the aggregate root. Further encapsulation
-may narrow compatibility properties, but serving code must continue to perform
-state changes through Session transitions.
-
-### Plugin descriptor and typed payloads
-
-The pipeline currently selects the MiniCPM engine extension and Serving adapter
-through two explicit fields, but there is not yet one versioned plugin descriptor
-that binds those identities in an open handshake. Realtime client payloads do
-not select either implementation. Adding a second native model should first
-introduce that descriptor and reject serving/engine plugin mismatches explicitly.
-
-The stable boundary has typed fences, plans, policies, decisions, and control
-messages, but `session_config`, `runtime_config`, and append payloads still use
-generic mappings or objects at the extension boundary. Model-neutral typed
-session and input-chunk contracts remain follow-up work, especially before
-adding video.
-
-### Output modality policy
-
-The current Realtime duplex contract supports text and audio output. Unknown
-output modalities fail closed with `unsupported_response_modality`; they are
-never silently projected as text. This checkpoint deliberately does not add a
-modality registry because there is only one native text/audio projection path
-to register.
-
-A registry becomes justified when a second non-audio/non-text implementation
-uses the same validation, encoding, lifecycle, and projection contract. At that
-point the abstraction must be extracted from two working adapters and retain
-the same fail-closed behavior. A speculative registry before that condition
-would add selection state without removing any existing branch.
-
-### Performance measurement contract
-
-Stage0 token timing comes only from the engine's per-segment metric snapshot:
-`vllm_ttft_ms`, `vllm_tpot_ms`, and `vllm_itls_ms`. A resumable Stage0 request
-exports its segment-local `num_generation_tokens`; ordinary requests retain the
-existing output-token fallback. Realtime response state clears its metric
-accumulator at `response.created`, combines only model units owned by that
-response, and ignores session-level events with no matching `response_id`.
-Realtime projection carries the result under
-`metadata.vllm_omni.stage_metrics`; clients do not estimate TPOT from transcript
-deltas or subtract cumulative snapshots.
-
-Audio timing uses the client's monotonic receive clock and is partitioned by
-`response_id`. `response_created_to_first_audio_ms` measures projection startup
-after `response.created`; `commit_to_first_audio_ms` measures end-to-end output
-from an explicit input commit. Neither field is called TTFP without naming its
-origin. Reports also include inter-chunk and chunk-duration
-count/mean/p50/p95/max plus maximum chunk gap. Engine and client measurements
-have different clock origins and must not be merged into one timeline.
-
-### Stage1 CUDA Graph boundary
-
-Native Stage1 streaming advances Python-owned request generators and turn
-state on every scheduler step. A full-model CUDA Graph would execute that
-Python control flow only while capturing and then replay stale chunk and turn
-metadata, even if its host-to-device tensor construction were made
-capture-safe. The duplex deploy profile therefore keeps `enforce_eager=false`
-but selects `cudagraph_mode=PIECEWISE` for Stage1. Python orchestration runs on
-every step while fixed-topology compiled regions remain eligible for CUDA
-Graph capture. This is a model execution constraint, not an E2E-only override.
-
-### Resource capabilities
-
-At the time of this snapshot the checked-in MiniCPM duplex deploy profile set
-Stage0 and Stage1 `max_num_seqs` to two and configured the engine runtime
-manager with `max_sessions=2`; the duplex settings have since been folded into
-`vllm_omni/deploy/minicpmo_4_5.yaml`, which admits four sessions
-(`duplex_session.max_sessions: 4`, matching its stage `max_num_seqs`). The
-Realtime capability response advertises
-multi-session and same-replica multi-session support with
-`session_admission_mode="engine_managed"`. Client session fields cannot raise
-this server-owned limit. Fresh E2E evidence covers two concurrent sessions in
-both model-policy and response-required modes, rejection of a third session,
-and admission of a replacement after one accepted session closes. It does not
-establish behavior beyond that configured limit.
-
-Session leases, lease TTL, resumable attachment, orphan reaping, and bounded
-Serving input/backpressure are implemented. A production admission controller,
-KV-aware capacity budgeting, fairness, starvation metrics, and multi-session
-worker-failure recovery remain follow-up work. Capability claims must stay
-limited to the mechanisms and two-session execution shape validated here.
-
-## Validation Evidence
-
-All pytest and runtime evidence for this branch must run on the remote H20.
-
-### Current synchronized tree
-
-The current dirty tree was synchronized to the isolated H20 worktree at
-`/home/admin/workspace/aop_lab/model_runner_v2/vllm-omni-worktrees/pr3907-boundary-cg-0721`.
-
-- Final affected matrix: 661 passed, one network-dependent config test
-  deselected, 20 warnings. It includes the complete MiniCPM native-duplex hook
-  file and all control/session/handler/Orchestrator/import-boundary suites. The
-  run is task `be221f67` (`/tmp/remote_gpu_logs/be221f67.log`). The deselected
-  `test_resolve_when_autodetect_resolves_none` attempted a Hugging Face model
-  lookup and hung in the isolated environment; the duplex deploy-config test
-  passed independently.
-- Stage1 PIECEWISE CUDA Graph validation: the deploy-config assertion first
-  failed with no Stage1 compilation config, then passed in task `3ed6091d`.
-  Server task `95827027` started with `enforce_eager=False`, logged
-  `cudagraph_mode=PIECEWISE`, and captured batch sizes 1, 2, and 4 without the
-  CPU-to-CUDA capture error. The first concurrent E2E exposed graph padding as
-  `request_token_spans` covering three valid rows in a four-row capture. A
-  focused RED/GREEN now verifies both single-request and batched-request
-  padding, and the full MiniCPM hook file passed 47 tests in task `e89dba88`.
-  After the fix, two concurrent response-required sessions each completed two
-  spoken responses, playback acknowledgements, and history lifecycles with no
-  error or stale event. Artifacts are under
-  `/tmp/pr3907_piecewise_response_required_2x2_fixed_20260721`.
-- An exploratory two-session, two-turn model-policy run still left one session
-  waiting after its second input commit while the other session completed both
-  turns. The same liveness symptom was reproduced with Stage1 eager mode before
-  the padding fix, and no Stage1 fatal occurred after the fix. This run is not
-  counted as PIECEWISE acceptance evidence; the remaining Stage0 resumable
-  reactivation path requires separate diagnosis. Artifacts are under
-  `/tmp/pr3907_piecewise_model_policy_2x2_fixed_20260721`.
-- Latest broad affected matrix before the final pre-response continuation fix:
-  608 passed, 19 warnings. This includes the
-  Stage0 row-routing regression, cleanup-held admission regressions,
-  segment-local token accounting, response-owned metric filtering, the generic
-  output-processor suite, direct E2E script execution, and continuous-response
-  overlap ownership. The run is task `e2146318`
-  (`/tmp/remote_gpu_logs/e2146318.log`).
-- The pre-response continuation regression group passed 5 focused tests. The
-  response-required two-turn scenario then passed 5/5 repeated runs in task
-  two-session semantic isolation plus resume, takeover, and
-  admission passed in task `49225794`; model-unit overlap passed in task
-  `3888387d`. The final affected matrix above supersedes the earlier pending
-  rerun requirement.
-- Serving plugin selection was first reproduced as three RED tests: the generic
-  handler silently selected MiniCPM and the pipeline had no explicit Serving
-  adapter field. The final pipeline/import/fail-fast group passed 9 tests in task
-  `4db6d959` (`/tmp/remote_gpu_logs/4db6d959.log`). The token-metric and client
-  audio-cadence producer-to-consumer group passed 8 tests in task `cf80f6b2`
-  (`/tmp/remote_gpu_logs/cf80f6b2.log`).
-- Stable-import isolation was first reproduced as a RED that loaded twelve
-  `experimental.fullduplex` modules. After extracting the kernel and making
-  implementation loading conditional, the isolated import regression passed.
-  The focused ControlPlane/ControlClient/session/runtime/Orchestrator/AsyncOmni
-  suite then passed 139 tests in task `fad613ea`
-  (`/tmp/remote_gpu_logs/fad613ea.log`).
-  After the final contract-import cleanup, the import-boundary, runtime, and
-  lease suites passed 45 tests in task `bc138887`
-  (`/tmp/remote_gpu_logs/bc138887.log`).
-- Concurrency and failure-path hardening now has direct regressions for
-  single-flight cancel/close cleanup, cleanup retry without dropping request
-  resources, failed-replica affinity cleanup and same-address reattachment,
-  append ordering across resume, takeover ownership of pending-turn
-  reservations, and a closed-transport send immediately after resumable
-  credentials are delivered. The final focused resume/takeover group passed 5
-  tests in task `dc2ac96e` (`/tmp/remote_gpu_logs/dc2ac96e.log`).
-- Stage1 batching regression: the focused test first failed because only the
-  first request in `runtime_additional_information` reached the talker. After
-  routing every request by `request_token_spans`, preserving per-row terminal
-  flags, and emitting request-keyed sparse audio, the complete MiniCPM duplex
-  hook file passed 42 tests.
-- Stage0 batching regression: two requests in one batch now retain different
-  `duplex_prompt_token_ids` and `special_token_ids`. The model emits row-aligned
-  payload elements, so Stage0 no longer copies request zero's duplex metadata to
-  later sessions.
-- Admission finalization regressions cover `max_sessions=1` with blocked and
-  failed expiry cleanup plus request-triggered cleanup. Every replacement is
-  rejected with `resource_exhausted` until stage resources are cleaned and the
-  old session is explicitly finalized.
-- Resumable token accounting exports each model unit's native generation-token
-  count instead of recounting the request's cumulative token IDs. Realtime
-  response state resets and accumulates those segment snapshots, and the client
-  ignores unowned session-level metrics while summarizing a response.
-- Engine-owned admission and two-session model-policy E2E: two random session
-  IDs were admitted and remained isolated, a third was rejected with
-  `resource_exhausted`, closing one accepted session returned capacity, and a
-  random replacement session was admitted. The capability projection reported
-  `configured_limit=2`, `advertised_multi_session=true`, and
-  `session_admission_mode=engine_managed`. In the same run one session selected
-  speak and the other selected listen without identity leakage. Detach/resume
-  advanced attachment generation from one to two and rotated its token; active
-  takeover rejected all four writes from the replaced connection. The run is
-  task `1d9dd1ed` (`/tmp/remote_gpu_logs/1d9dd1ed.log`), with artifacts under
-  `/tmp/pr3907_resume_takeover_native_metrics`.
-- Concurrent two-session, two-turn response-required E2E: both sessions produced
-  two complete spoken responses, committed two playback acknowledgements and
-  history records, and emitted no error, cancel, truncate, or stale events. The
-  semantically distinct inputs produced isolated transcripts containing
-  "当时" and "一加一" respectively. Per-response Stage0 output counts were 20,
-  38, 32, and 33 tokens rather than cumulative request totals. The run is task
-  `a16f1467` (`/tmp/remote_gpu_logs/a16f1467.log`), with artifacts under
-  `/tmp/pr3907_semantic_2turn_native_metrics`.
-- Disconnect-grace E2E: a detached session expired after the configured
-  30-second engine grace, and a later resume was rejected with
-  `session_resume_expired`. The run is task `9872d50c`, with artifacts under
-  `/tmp/pr3907_0719_disconnect_grace_expiry`.
-- A separate black-box takeover client exercised the current backend with two
-  semantically distinct concurrent inputs. Active resume replayed 17 events
-  including five audio deltas and committed playback history; takeover rejected
-  all four stale-attachment sends, emitted `session.replaced`, and preserved
-  attachment/session isolation. Both transcripts contained only their expected
-  semantic token. The client task is `6773bd34`
-  (`/tmp/remote_gpu_logs/6773bd34.log`), with artifacts under
-  `/tmp/pr3907_gaohan_final_takeover`. The backend task was `5abcd1ee`.
-- Across the final response-required, overlap, and resume/takeover runs, engine
-  Stage0 TTFT ranged from 31.17 to 310.18 ms, TPOT from 15.18 to 21.18 ms, and
-  reported ITL p95 from 16.35 to 32.83 ms. Explicit
-  `commit_to_first_audio_ms` ranged from 386.80 to 1033.25 ms, while the
-  client-monotonic maximum audio chunk gap ranged from 388.30 to 1316.37 ms.
-  These are response-scoped observations from a small, warm-state-sensitive
-  sample, not an SLO claim. The slowest response still does not satisfy a 200 ms
-  end-to-end first-output target.
-- Post-merge focused handler/demo/Web/Stage0/runner/video suite: 324 passed,
-  19 warnings. The run is task `f78cb7a8`
-  (`/tmp/remote_gpu_logs/f78cb7a8.log`). The Web contract explicitly rejects
-  browser VAD markers and browser-generated input commits while the merged
-  video path retains camera-frame admission.
-- No-response listen and residual accounting: the focused handler regressions
-  passed after first reproducing both failures. A model-listen unit without a
-  Realtime response no longer defers the next committed input, and three
-  consecutive 1.2-second `pcm_f32le` inputs each returned pending input bytes
-  to zero.
-- Model-unit overlap E2E: the second physical input streamed while the first
-  response remained active. Seven overlap decisions had
-  `defer_runtime_append=false`; the one-second model-unit boundary occurred
-  before the first `response.done`, and no barge-in, cancel, truncate, stale, or
-  error event occurred. The model-policy contract accepts a later unit ending
-  the continuous response instead of requiring a second physical-input-owned
-  response. The two response-owned Stage0 snapshots independently reported 20
-  tokens / 152.8 ms TTFT and 19 tokens / 43.3 ms TTFT. The run is task
-  `a4977622` (`/tmp/remote_gpu_logs/a4977622.log`), with artifacts under
-  `/tmp/pr3907_overlap_native_metrics_scoped`.
-- The split multi-session E2E runner is directly executable from the repository
-  even when another installed package owns the top-level `tests` name. Its
-  script-import and continuous-terminal regressions passed in task `f11b106c`.
-- Pinned response-required E2E: the first 1400 ms of the pinned fixture produced
-  one complete spoken response, five audio/transcript deltas, and one playback
-  history commit, with symmetric created/audio-done/done lifecycle and no
-  duplicate `response.speak`. The client task is `a76dec52`
-  (`/tmp/remote_gpu_logs/a76dec52.log`).
-- Continuous-input model-policy E2E: 36 browser-like 200 ms chunks produced
-  seven model-listen decisions with zero input commits and no
-  error/cancel/truncate/stale events. The client task is `fb256595`; artifacts
-  are in `/tmp/minicpmo_pr3907_continuous_model_policy_20260718`.
-- Three-response continuous-input E2E: three consecutive 9469 ms streams,
-  composed of the original fixture plus four seconds of silence, produced three
-  spoken responses in one session. All three completed `response.done`, audio
-  transcript, playback ACK, and history commit; the run had 22 audio/transcript
-  deltas, zero input commits, and no error/cancel/truncate/stale events. This is
-  lifecycle evidence, not semantic cross-input independence, because the same
-  fixture was repeated. The client task is `2a5f29f0`; artifacts are in
-  `/tmp/minicpmo_pr3907_continuous_three_response_20260718`.
-- The fresh validation backend was stopped after the E2E runs and GPU0/1 returned
-  to baseline. Audio-quality and ASR evaluation were not rerun for these
-  lifecycle-only changes. Other GPU workloads were not modified.
-
-### Regression lineage
-
-Earlier synchronized checkpoints passed broader affected matrices before the
-extension, policy, and ledger consolidation. Those runs were useful while
-developing the refactor but are superseded by the current file-identical H20
-matrix and E2E evidence above; they are intentionally omitted to avoid mixing
-different trees in the acceptance argument.
-
-### Focused suites
-
-- RPC router and AsyncOmni shutdown/error routing;
-- orchestrator fatal and duplex control paths;
-- WebSocket Actor mailbox and writer;
-- duplex protocol and Session ownership;
-- Realtime handler, terminal ordering, overlap, playback ACK;
-- scheduler resumable boundary;
-- MiniCPM runner and Stage0/Stage1 lifecycle.
-
-### E2E contract
-
-Run two deliberately separate fixture contracts:
-
-- model-policy uses three distinct inputs, no transcript hints, 200 ms
-  real-time pacing, and continuous input with no browser commit. It allows
-  natural listen or speak decisions and assumes no 1:1 mapping between
-  physical inputs, model turns, and responses;
-- response-required uses `minicpmo_pr3907_jiayan_16k.wav` pinned to SHA-256
-  `2e5fd4eb3ee434ce107ee3a0591fa624a33f7683c7462f45fe651c443c9af941`,
-  sends its first 1400 ms, and requires one complete spoken response.
-  It is an output-lifecycle fixture, not evidence that arbitrary no-hint,
-  real-time input must select speak;
-- late and old-response playback ACK handling in the affected test matrix;
-- final model-policy response drain before `session.close`;
-- close/disconnect with no post-terminal audio;
-- transcript delta/final consistency;
-- generated WAV validity and external ASR sanity.
-
-Distinct-input fixtures must also be semantically distinct. Different files or
-waveform hashes containing the same greeting can legitimately produce the same
-reply and are not sufficient evidence for cross-turn transcript independence.
-
-For each run record the exact SHA/worktree, command, server log, client log,
-WAV path, and cleanup result.
-
-## Acceptance Criteria
-
-This checkpoint is ready to publish only when:
-
-- one mailbox passes exactly-once and wire-order tests;
-- cancel advances the engine fence even when the old append continues in an
-  executor, and the next-epoch append remains accepted;
-- request completion removes MiniCPM helper and model-owned force-listen state;
-- RPC fatal/close wakes every waiter and no new work enters after terminal;
-- Session is the only serving response/overlap authority;
-- stale terminal events cannot mutate a newer epoch;
-- an accepted terminal cannot be dropped by the writer;
-- no duplicate `response.speak` or transcript delta appears;
-- Stage0 KV continuity and Stage1 turn reset pass;
-- the real H20 multi-turn audio E2E passes;
-- ordinary non-duplex paths in the affected matrix still pass;
-- no local path, proxy token, temporary profiling probe, or test-only switch is present.
-
-Passing this checkpoint supports the statement:
-
-> Single-session, model-owned MiniCPM-o 4.5 native duplex is reviewable on the
-> validated H20 configuration.
-
-It does not support claims for an acoustic-onset barge-in latency target across
-arbitrary client chunk sizes, multi-session production concurrency, bounded
-long-session KV, or scheduler-native append. Camera-frame input
-(`video_frames`) landed after this snapshot and is covered by its own E2E
-test rather than by the evidence above.
+| `_dispatch_message(msg) -> bool` | `add_request`, `streaming_update`, `add_companion_request`, `interaction` | open/command/close/resume/touch messages -> `DuplexSessionManager` |
+| `_background_tasks()` | — | `[manager.reaper_loop()]` |
+| `_shutdown_extensions()` | — | `await manager.shutdown()` |
+| `_on_stage_submitted(stage_id, request_id, replica_id, req_state)` | — | bind the forwarded stage request to the owning session |
+| `_intercept_stage_output(...) -> bool` | — | hand every session-owned output (Stage0 decision, Stage1 audio) plus its metric snapshot to `runner.on_stage_output`; `True` = do not forward |
+| `_handle_forward_failure(...) -> bool` | — | fail the owning session's response and close the session, keep the loop alive |
+| `_cleanup_request_ids(ids, abort=, release_owners=)` | ignores `release_owners` | brackets `super()` with `close_sessions_for_request_ids` / `defer_request_cleanups` / `finalize_closed_sessions` |
+| `OrchestratorRequestState.session_owned` | never set | set by `ensure_request`: no synthetic terminal, no client emission, no terminal re-forward, no auto-cleanup on finish |
+
+`DuplexOrchestrator` also implements the `DuplexStagePort` ABC the manager and
+runner use (`stage_count`, `sampling_defaults`, `ensure_request`, `submit`,
+`cleanup`, `abort_requests`): the resumable Stage0 request is preregistered at
+open with `DuplexOrchestratorRequestState(session_owned=True, session_id,
+fence)`, submitted with `submit_initial` on the first unit and
+`submit_update` afterwards, and the request's `streaming.bridge_states["duplex"]`
+carries the session identity (`session_id`, `fence`, `epoch`, `turn_id`,
+`model_turn_id`), the public session config and the server-owned runtime
+config for the worker-side model hooks.
+
+## Model plugin
+
+`DuplexModelPlugin` (ABC, `engine/duplex/plugin.py`) is the one class a model
+provides, selected by `PipelineConfig.duplex_plugin`; "is a duplex model" is
+`duplex_plugin is not None`. It merges the engine policy and the session
+policy that used to be two separately configured objects:
+
+| Half | Members |
+| --- | --- |
+| engine policy | `configure_sampling_params(runtime_config, defaults)`, `plan_append(...) -> DuplexAppendPlan` (the resumable Stage0 prompt for one unit), `decide_output(...) -> DuplexOutputDecision \| None` (e.g. the listen decision on a finished Stage0 segment) |
+| session policy | `capabilities(max_sessions)`, `validate_client_extra_body`, `prepare_runtime_config(config, model_config)` (server-owned runtime keys, reference audio resolution), `runtime_config_for_update`, `runtime_config_for_function_output`, `create_session_state() -> DuplexModelSessionState`, `data_plane: DuplexDataPlane` (projects raw stage outputs into internal events), `data_plane_context(...)` |
+
+`DuplexOmniEngine._validate_deployment` loads the plugin before any stage
+starts; `DuplexSessionManager.__init__` validates it against the stage
+sampling defaults once the stage pools exist. Plugin hooks that may block
+(`prepare_runtime_config` fetching `ref_audio`) are awaited in `open()` and
+offloaded from the loop.
+
+The MiniCPM-o 4.5 plugin (`model_executor/models/minicpmo_4_5/duplex/plugin.py`)
+is the only integration in this framework version. PersonaPlex and Nemotron
+VoiceChat still carry their pre-framework duplex code (runtime extension plus
+serving adapter) and are therefore not served over this framework yet: their
+pipelines declare no `duplex_plugin`, so they run turn-based until the
+follow-up PRs port them (RFC vllm-omni#7181, PR 2/3).
+
+## Serving
+
+`OmniDuplexSessionHandler.handle_realtime_session(websocket)`:
+
+1. accept; build the `RealtimeEnvelope` (autostart / default session from
+   query params, `event_id` correlation, error rendering through the typed
+   `ErrorEvent`);
+2. handshake: first message `session.update` -> `omni.open_session(session)`
+   (the id inside the payload is ignored; the allocated id is announced in
+   `session.created` together with `resume_token` / `attachment_generation`
+   when the model supports resume); `session.resume(session_id, resume_token,
+   last_received_server_event_seq)` -> `attachment.authenticate_resume` ->
+   `omni.resume_session`;
+3. reader loop: JSON -> `RealtimeEnvelope.translate` (`translate_realtime_command`
+   with the session's declared audio defaults) -> `handle.submit`;
+   envelope-level errors (invalid JSON, oversize frame, unknown type,
+   event acks) are answered locally;
+4. writer pump (session-scoped, survives reconnects): `async for ev in
+   handle.events(): attachment.send_event(ev.to_realtime())`, journaling
+   for replay until the journal overflows (`session.resync_required`);
+5. disconnect: a resumable session is detached (`attachment.detach` +
+   `omni.detach_session`, engine-owned grace); a superseded socket's
+   disconnect is a no-op; a non-resumable session is closed. Takeover sends
+   `session.replaced` to the old socket and closes it.
+
+## Validation
+
+- CPU suites: `tests/engine/duplex/**` (session, lease, manager, runner,
+  plugin, events, commands), `tests/engine/test_duplex_orchestrator.py`,
+  `tests/engine/test_duplex_omni_engine.py`,
+  `tests/entrypoints/test_duplex_omni.py`,
+  `tests/entrypoints/duplex/test_duplex_serving.py`,
+  `tests/entrypoints/openai/test_duplex_session_attachment.py`,
+  `tests/entrypoints/openai_api/test_duplex_api_server.py` (the duplex
+  server: pipeline probe, app state, routes, warmup gate),
+  `tests/entrypoints/duplex/test_chat_completions_adapter.py`,
+  `tests/clients/**`, `tests/engine/test_duplex_import_boundary.py`,
+  `tests/model_executor/models/minicpmo_4_5/duplex/**`,
+  `tests/worker/test_native_duplex_hooks.py`.
+- GPU: `examples/online_serving/minicpmo/realtime_duplex_demo.py` (one turn
+  over the websocket), `examples/online_serving/barge_in_client.py` (cancel
+  during playback; `--inline` drives the same scenario through
+  `InlineDuplexClient`), `tests/e2e/online_serving/run_minicpmo_realtime_duplex_multi_session.py`
+  (admission, resume, takeover, expiry).
diff --git a/docs/design/module/engine_orchestration.md b/docs/design/module/engine_orchestration.md
index d4dbf51a243..df22f3ce1f7 100644
--- a/docs/design/module/engine_orchestration.md
+++ b/docs/design/module/engine_orchestration.md
@@ -16,6 +16,7 @@ required_reviewers:
   - "@yenuo26"
   - "@NickCao"
 primary_code_paths:
+  - vllm_omni/engine/omni_engine_base.py
   - vllm_omni/engine/async_omni_engine.py
   - vllm_omni/engine/async_engine_utils.py
   - vllm_omni/engine/orchestrator.py
@@ -28,8 +29,12 @@ related_code_paths:
   - vllm_omni/engine/stage_pool.py
   - vllm_omni/outputs/output_processor.py
   - vllm_omni/distributed/omni_coordinator/**
-  # Duplex kernel design is owned by ../fullduplex.md; listed here because the
-  # orchestrator hosts the duplex control plane.
+  # The duplex siblings (DuplexOmniEngine / DuplexOrchestrator) and the
+  # engine-resident session framework are owned by ../fullduplex.md; listed
+  # here because they fill the template seams of OmniEngineBase and
+  # OrchestratorBase.
+  - vllm_omni/engine/duplex_omni_engine.py
+  - vllm_omni/engine/duplex_orchestrator.py
   - vllm_omni/engine/duplex/**
 depends_on:
   - input_output_modality_contracts.md
@@ -48,6 +53,8 @@ validation_paths:
   - tests/engine/test_cfg_companion_lifecycle.py
   - tests/engine/test_rpc_result_router.py
   - tests/engine/duplex/**
+  - tests/engine/test_duplex_orchestrator.py
+  - tests/engine/test_duplex_omni_engine.py
   - tests/engine/test_duplex_import_boundary.py
 upstream_refs:
   - vllm.v1.engine.EngineCoreRequest
diff --git a/docs/design/module/entrypoints.md b/docs/design/module/entrypoints.md
index a0dee90b900..db62f9cb67e 100644
--- a/docs/design/module/entrypoints.md
+++ b/docs/design/module/entrypoints.md
@@ -19,7 +19,9 @@ required_reviewers:
 primary_code_paths:
   - vllm_omni/entrypoints/omni.py
   - vllm_omni/entrypoints/async_omni.py
+  - vllm_omni/entrypoints/async_omni_base.py
   - vllm_omni/entrypoints/omni_base.py
+  - vllm_omni/entrypoints/duplex_omni.py
   - vllm_omni/entrypoints/cli/**
   - vllm_omni/entrypoints/openai/**
   - vllm_omni/entrypoints/openpi/**
@@ -27,14 +29,13 @@ primary_code_paths:
   - vllm_omni/entrypoints/stage_utils.py
   - vllm_omni/entrypoints/utils.py
   - vllm_omni/entrypoints/duplex/**
-  - vllm_omni/entrypoints/duplex_request_client.py
   - vllm_omni/clients/**
 primary_path_exceptions:
   - path: vllm_omni/entrypoints/openai/errors.py
     owner: error_contracts.md
   - path: vllm_omni/entrypoints/duplex/**
     owner: ../fullduplex.md
-  - path: vllm_omni/entrypoints/duplex_request_client.py
+  - path: vllm_omni/entrypoints/duplex_omni.py
     owner: ../fullduplex.md
   - path: vllm_omni/clients/**
     owner: ../fullduplex.md
@@ -42,7 +43,9 @@ related_code_paths:
   - vllm_omni/errors.py
   - vllm_omni/inputs/**
   - vllm_omni/outputs/**
+  - vllm_omni/engine/omni_engine_base.py
   - vllm_omni/engine/async_omni_engine.py
+  - vllm_omni/engine/duplex_omni_engine.py
   - vllm_omni/config/**
   - vllm_omni/deploy/**
 depends_on:
@@ -53,7 +56,9 @@ validation_paths:
   - tests/entrypoints/test_omni_entrypoints.py
   - tests/entrypoints/test_async_omni.py
   - tests/entrypoints/test_async_omni_pause_sleep_routing.py
-  - tests/entrypoints/test_async_omni_duplex.py
+  - tests/entrypoints/test_duplex_omni.py
+  - tests/entrypoints/duplex/**
+  - tests/entrypoints/openai_api/test_duplex_api_server.py
   - tests/entrypoints/test_serve.py
   - tests/entrypoints/test_stream_finish_reason.py
   - tests/entrypoints/openai/**
diff --git a/docs/mkdocs/hooks/generate_api_readme.py b/docs/mkdocs/hooks/generate_api_readme.py
index 3130e688f75..d236c1129e6 100644
--- a/docs/mkdocs/hooks/generate_api_readme.py
+++ b/docs/mkdocs/hooks/generate_api_readme.py
@@ -25,8 +25,8 @@
     "clients": {
         "name": "Clients",
         "description": (
-            "Client libraries that talk to a running vLLM-Omni server "
-            "(the full-duplex Realtime client and its per-model session presets)."
+            "Client libraries for full-duplex sessions: the Realtime WebSocket client, "
+            "the in-process client over `DuplexOmni`, and the per-model session presets."
         ),
     },
     "inputs": {
diff --git a/docs/models/supported_models.md b/docs/models/supported_models.md
index f8db9eb9268..42971ed979b 100644
--- a/docs/models/supported_models.md
+++ b/docs/models/supported_models.md
@@ -107,7 +107,7 @@ th {
 | `VoxtralTTSForConditionalGeneration` | Voxtral TTS | `mistralai/Voxtral-4B-TTS-2603` | ✅︎ | ✅︎ | | | — |
 | `CovoAudioForConditionalGeneration` | Covo-Audio-Chat | `tencent/Covo-Audio-Chat` | ✅︎ | | | | — |
 | `DyninOmniForConditionalGeneration` | Dynin-Omni | `snu-aidas/Dynin-Omni` | ✅︎ | | | ✅︎ | — |
-| `MiniCPMO45OmniForConditionalGeneration` | MiniCPM-o 4.5 | `openbmb/MiniCPM-o-4_5` | ✅︎ | | ✅︎ | | — |
+| `MiniCPMO45OmniForConditionalGeneration` | MiniCPM-o 4.5 | `openbmb/MiniCPM-o-4_5` | ✅︎ | | ✅︎ | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/OpenBMB/MiniCPM-o-4_5.md) |
 | `ErnieImagePipeline` | ERNIE-Image | `baidu/ERNIE-Image`, `baidu/ERNIE-Image-Turbo` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
 | `GepardTalkerForConditionalGeneration` | Gepard-1.0 | `nineninesix/gepard-1.0` | ✅︎ | | | ✅︎ | — |
 | `HiDreamImagePipeline` | HiDream-I1-Full | `HiDream-ai/HiDream-I1-Full` | ✅︎ | ✅︎ | | | — |
diff --git a/docs/serving/README.md b/docs/serving/README.md
index 8167f4c9b64..472ab2a492b 100644
--- a/docs/serving/README.md
+++ b/docs/serving/README.md
@@ -145,15 +145,22 @@ interchangeably.
 | Incremental text input for speech synthesis | `WS /v1/audio/speech/stream` | Send text events and receive audio | [Streaming Text to Speech](speech_api.md#streaming-text-input-websocket) |
 | Live video understanding | `WS /v1/video/chat/stream` | Send video frames and receive text/audio | [Streaming Video Input](video_stream_api.md) |
 | Turn-based realtime audio | `WS /v1/realtime` | Stream one audio input and receive transcript/audio events | [Realtime Audio](realtime_api.md) |
-| Continuous speech-to-speech interaction | `WS /v1/realtime?duplex=1` or `WS /v1/duplex` | Listen and speak concurrently with session control | [Full Duplex](full_duplex_api.md) |
+| Continuous speech-to-speech interaction | `WS /v1/realtime?duplex=1` (alias `WS /v1/duplex`) | Listen and speak concurrently with session control | [Full Duplex](full_duplex_api.md) |
 | Generated video chunks | `WS /v1/realtime/video` | Start a diffusion request and receive fragmented MP4 | [Streaming Video Output](streaming_video_output_api.md) |
 | Robot policy inference | `WS /v1/realtime/robot/openpi` | Send MessagePack observations and receive action arrays | [OpenPI Robot Policy](openpi_api.md) |
 
 All six routes are model- or configuration-dependent. In particular,
-`/v1/realtime` is not full duplex unless the client sets `duplex=1` and the
-deployment explicitly enables duplex sessions. Clients should also verify the
-duplex capability payload because the query-parameter form falls back to the
-ordinary realtime handler when duplex is unavailable.
+`/v1/realtime` is full duplex when the model is a duplex model (its pipeline
+declares a `duplex_plugin` and the deploy configuration sets
+`session_mode: duplex`); a stock Realtime client needs no vendor query
+parameter, and `duplex=0` is the explicit opt-out. Such a server serves the
+websocket route plus `POST /v1/chat/completions`, and no other turn-based
+HTTP route. On a duplex server that chat route is not the turn-based path:
+each request runs on a short-lived duplex session, so it holds one of
+`duplex_session.max_sessions` for its lifetime and answers at the model's
+real-time pace -- see [Full Duplex](full_duplex_api.md). Clients should
+also verify the duplex capability payload because the query-parameter form
+falls back to the ordinary realtime handler when duplex is unavailable.
 
 ## Related Endpoints
 
diff --git a/docs/serving/full_duplex_api.md b/docs/serving/full_duplex_api.md
index 4e8bf974890..92511e84ffe 100644
--- a/docs/serving/full_duplex_api.md
+++ b/docs/serving/full_duplex_api.md
@@ -15,40 +15,52 @@ capability gates, see the [Realtime Duplex API guide](realtime_duplex_api.md).
 
 | Endpoint | Protocol | Recommended use |
 | --- | --- | --- |
-| `WS /v1/realtime?duplex=1` | OpenAI Realtime-style event projection | Applications and browser clients |
-| `WS /v1/duplex` | Native vLLM-Omni duplex events | Runtime integration and low-level testing |
-
-Both endpoints use the same duplex engine and require the same model-side
-adapter. Prefer the Realtime projection unless the native lifecycle events are
-specifically required.
+| `WS /v1/realtime?duplex=1` | OpenAI Realtime-style events (the normative contract) | Applications and browser clients |
+| `WS /v1/duplex` | Alias of `/v1/realtime?duplex=1` (same protocol, same handler) | Clients that prefer a dedicated path |
+| Python: `DuplexOmni` / `InlineDuplexClient` | Typed commands and events in-process | Embedding the model without a server |
 
 ## Enable Full Duplex
 
-The route becomes usable only when the deployment configuration explicitly
-sets:
+A model is served full duplex when its registered pipeline declares a
+`duplex_plugin` (the model's `DuplexModelPlugin`). That declaration alone
+decides it: `vllm-omni serve` constructs `DuplexOmni` instead of `AsyncOmni`,
+and every surface the server exposes is backed by a duplex session. It serves
+`/v1/realtime?duplex=1` (and its alias `/v1/duplex`),
+`POST /v1/chat/completions`, `/v1/models` and `/health`; every other
+turn-based HTTP route (speech, batch, embeddings, video, ...) answers "not
+available". Turn-based use of such a model stays available offline through the
+Python API (`Omni` / `AsyncOmni`).
+
+`/v1/chat/completions` is the ordinary chat service running on the duplex
+engine: a request is a turn-based generation on the same stages, served
+alongside the live websocket sessions, with the request options the chat
+service supports. It is wired only when the model's plugin declares
+`DuplexCapabilities.supports_chat_completions`; on any other duplex model the
+route reports "not available". A model that should not serve the route at all
+lists it in the deploy configuration's `endpoint_restrictions`.
+
+The deploy configuration of such a model must agree:
 
 ```yaml
 session_mode: duplex
 ```
 
-The selected model pipeline must also provide a duplex serving adapter.
-Model-native deployments configure the corresponding engine runtime extension
-and control plane as part of their registered pipeline.
+A duplex model started with a deploy configuration that does not set it fails
+at startup rather than falling back to turn-based serving.
 
 !!! warning
 
-    `WS /v1/duplex` fails with `Duplex API is not available` when duplex is not
-    enabled. By contrast, `/v1/realtime?duplex=1` falls back to the ordinary
-    turn-based realtime handler when no duplex handler exists. Confirm that
+    On a deployment that is *not* duplex, `WS /v1/duplex` fails with
+    `Duplex API is not available` and `/v1/realtime?duplex=1` falls back to the
+    ordinary turn-based realtime handler. Confirm that
     `session.created.session.capabilities` is present before treating the
     connection as full duplex.
 
-The current unified-runtime integrations are:
-
-- MiniCPM-o 4.5, using `vllm_omni/deploy/minicpmo_4_5.yaml`
-  (`session_mode: duplex`);
-- PersonaPlex, whose default `vllm_omni/deploy/personaplex.yaml` enables duplex;
-- Nemotron VoiceChat, via its registered duplex plugin package.
+**MiniCPM-o 4.5** (`vllm_omni/deploy/minicpmo_4_5.yaml`) is the only model
+served over this endpoint today. PersonaPlex and Nemotron VoiceChat still carry
+their pre-framework duplex code: their pipelines declare no `duplex_plugin`, so
+they run turn-based until the follow-up PRs port them to the plugin contract
+(RFC [vllm-omni#7181](https://github.com/vllm-project/vllm-omni/issues/7181)).
 
 JoyVL is a separate HTTP interaction orchestrator and does not use these
 WebSocket endpoints. See [Standalone Experimental Servers](standalone_servers.md).
@@ -101,22 +113,23 @@ deferred, treated as a short acknowledgement, or used to interrupt output.
 The `session.created` payload includes capability fields such as
 `supports_barge_in`, `supports_playback_ack`, `supports_multi_session`,
 `supports_session_resume`, and `chunk_period_ms`. Treat this payload as the
-runtime contract.
-
-For example, PersonaPlex supports native overlapping speech but currently
-advertises `supports_barge_in=false`; destructive output interruption and
-model-state rewind have not been validated for that integration. Capacity and
-session-resume behavior also depend on the selected deployment configuration.
-
-## Native Protocol
-
-`WS /v1/duplex` exposes lower-level lifecycle names including
-`session.create`, `input_audio_buffer.append`, `turn.signal`, `playback.ack`,
-and `session.close`. It returns native session, input, response, overlap, and
-error events. This protocol is experimental and may evolve with the runtime;
-applications should use the provided Realtime client where possible.
-
-See the [MiniCPM-o example](https://github.com/vllm-project/vllm-omni/tree/main/examples/online_serving/minicpmo),
-[PersonaPlex example](https://github.com/vllm-project/vllm-omni/tree/main/examples/online_serving/personaplex),
+runtime contract and branch on the flags, never on the model name: a model
+that supports native overlapping speech may still advertise
+`supports_barge_in=false` when destructive output interruption and model-state
+rewind are not validated for it. Capacity and session-resume behavior also
+depend on the selected deployment configuration. The per-model table lives in
+the [Realtime Duplex API guide](realtime_duplex_api.md#capability-negotiation-by-model).
+
+## Python API
+
+`vllm_omni.entrypoints.duplex_omni.DuplexOmni` runs the same engine-resident
+sessions in-process: `open_session()` returns a `DuplexSessionHandle` whose
+`submit()` takes typed `DuplexCommand` objects and whose `events()` yields
+typed `DuplexEvent` objects (each with a `to_realtime()` wire rendering).
+`vllm_omni.clients.inline_duplex.InlineDuplexClient` exposes that handle
+behind the `DuplexClient` API. See the
+[Realtime Duplex API guide](realtime_duplex_api.md#using-the-python-api).
+
+See the [MiniCPM-o example](https://github.com/vllm-project/vllm-omni/tree/main/examples/online_serving/minicpmo)
 and the [full-duplex runtime design](../design/fullduplex.md)
 for model-specific validation and architecture details.
diff --git a/docs/serving/realtime_duplex_api.md b/docs/serving/realtime_duplex_api.md
index 288c934e88e..cc10d99c96c 100644
--- a/docs/serving/realtime_duplex_api.md
+++ b/docs/serving/realtime_duplex_api.md
@@ -1,17 +1,18 @@
 # Realtime Duplex API
 
 vLLM-Omni serves full-duplex speech models over a WebSocket endpoint,
-`/v1/realtime`, that speaks the OpenAI Realtime vocabulary plus a
+`/v1/realtime?duplex=1`, that speaks the OpenAI Realtime vocabulary plus a
 set of duplex extensions: the model decides when to listen and when to speak,
 the user can talk over the assistant, playback progress is reported back so
 history stays honest, and a dropped connection can resume the same session.
 This page covers how to run a duplex deployment, how to drive it from Python
 with `vllm_omni.clients.duplex.DuplexClient`, and the complete wire contract.
 
-The handler is enabled by either a model-native `session_mode: duplex`
-deployment or an explicit `duplex_session` configuration for turn-based
-Server VAD. The runtime architecture is described in
-[Full-Duplex Runtime (MiniCPM-o 4.5)](../design/fullduplex.md).
+The endpoint is served for models that ship a duplex plugin — currently
+MiniCPM-o 4.5 only — and just for deploy configurations that declare
+`session_mode: duplex`. PersonaPlex and Nemotron VoiceChat are ported to the
+plugin contract in follow-up PRs and are not served over this endpoint yet. The runtime architecture
+is described in [Full-Duplex Runtime (MiniCPM-o 4.5)](../design/fullduplex.md).
 
 ## Quick Start
 
@@ -26,11 +27,38 @@ vllm-omni serve openbmb/MiniCPM-o-4_5 \
 ```
 
 `vllm_omni/deploy/minicpmo_4_5.yaml` declares `session_mode: duplex` and
-`duplex_session.max_sessions: 4`, which mounts the WebSocket routes
-`ws://<host>:8099/v1/realtime` (this page) and `ws://<host>:8099/v1/duplex`
-(the native dialect for raw-protocol clients) next to the usual HTTP API.
-PersonaPlex and Nemotron VoiceChat use `vllm_omni/deploy/personaplex.yaml` and
-`vllm_omni/deploy/nemotron_labs_voicechat_duplex.yaml` in the same way.
+`duplex_session.max_sessions: 4`. Because the MiniCPM-o 4.5 pipeline declares a
+`duplex_plugin`, `vllm-omni serve` runs it through `DuplexOmni`: the server
+mounts `ws://<host>:8099/v1/realtime?duplex=1` (this page; `ws://<host>:8099/v1/duplex`
+is an alias of the same route), `POST /v1/chat/completions`, `/v1/models` and
+`/health`, and nothing else. The remaining turn-based HTTP routes (speech,
+batch, embeddings, video, ...) are not served by a duplex model.
+
+`/v1/chat/completions` is not a turn-based path on a duplex server: each
+request opens a short-lived duplex session and reads the answer off it. Audio
+content becomes an ordinary committed turn; text is seeded as the session's
+opening turn, because a model-native model takes a turn only when it hears
+speech. A model that cannot be seeded that way declares so, and a text request
+to it is refused with 400. Two consequences are worth sizing for:
+
+- **Every request holds an admission slot** for its lifetime, so
+  `duplex_session.max_sessions` caps HTTP concurrency as well as websocket
+  sessions. Beyond it a request is refused with HTTP 503.
+- **Latency follows the model's own clock.** A model-native session generates
+  per audio unit, so even a short answer costs what that many units cost --
+  noticeably more than the same model would take turn-based.
+
+`n > 1`, `logprobs`, `tools`, and image or video content parts have no
+representation in one duplex turn and are refused with HTTP 400 -- a Realtime
+conversation item carries text and audio only. `temperature`,
+`max_completion_tokens`, `modalities` and
+`chat_template_kwargs.use_tts_template` apply; the other
+`chat_template_kwargs` keys are logged as ignored. `extra_body` is passed to
+the session unchanged, exactly as a websocket client's session `extra_body`
+is, which is how a request asking for `modalities: ["text", "audio"]` supplies
+the `ref_audio` MiniCPM-o requires for audio output. A model that should not
+serve the route lists it in the deploy config's `endpoint_restrictions`,
+exactly as a turn-based model does.
 
 ### Run the Example Client
 
@@ -81,25 +109,24 @@ ships a preset:
 
 | Preset | Input / output audio | What it sets |
 | --- | --- | --- |
-| `vllm_omni.clients.minicpmo_4_5.create_duplex_session_config(ref_audio=...)` | 16 kHz `pcm16` / 24 kHz `pcm16` | `extra_body.native_duplex=True` (opt in to the model-native lane), `force_listen_count=0`, `overlap_policy="listen_only"`, `playback_commit_policy="ack_only"`; `ref_audio` is the assistant voice clip |
+| `vllm_omni.clients.minicpmo_4_5.create_duplex_session_config(ref_audio=...)` | 16 kHz `pcm16` / 24 kHz `pcm16` | `force_listen_count=0`, `overlap_policy="listen_only"`, `playback_commit_policy="ack_only"`; `ref_audio` is the assistant voice clip |
 | `vllm_omni.clients.personaplex.create_duplex_session_config(voice="NATF2.pt", persona="")` | 24 kHz `pcm_f32le` / 24 kHz `pcm16` | bundled `.pt` voice prompt and the persona as `instructions` |
 | `SessionConfig(...)` | 16 kHz `pcm16` / 24 kHz `pcm16` | model-neutral defaults; pass `extra_body`, `turn_detection`, `overlap_policy`, `playback_commit_policy`, `instructions`, `voice`, `temperature` yourself |
 
 Keyword overrides on a preset replace the corresponding `SessionConfig`
 field, e.g. `create_duplex_session_config(ref_audio=..., temperature=0.6)`.
 
-Constructor options: `session_id` (names the session the client creates; it
-does not resume or take over an existing session — entering the client always
-performs the `session.update` handshake), `reconnect` (a `ReconnectPolicy`,
-default five attempts with 0.25–4 s jittered backoff; `None` disables
-auto-resume), `heartbeat_interval_s` (default 30 s; `None` disables the lease
-heartbeat), `handshake_timeout_s`, and `connect` (a custom transport factory,
-used by tests and benchmarks). Resume is supported only as automatic reconnect
-within the same `DuplexClient` instance (see
-[Reconnect and resume](#reconnect-and-resume)); re-attaching from a new client
-or process requires the wire-level `session.resume` handshake
-(`resume_token`, `incarnation`, `last_received_server_event_seq`), which this
-client does not expose.
+Constructor options: `reconnect` (a `ReconnectPolicy`, default five
+attempts with 0.25–4 s jittered backoff; `None` disables auto-resume),
+`heartbeat_interval_s` (default 30 s; `None` disables the lease heartbeat),
+`handshake_timeout_s`, and `connect` (a custom transport factory, used by
+tests and benchmarks). The session id is allocated by the server and becomes
+`client.session_id` once `session.created` arrives; a client cannot choose
+it. Resume is supported only as automatic reconnect within the same
+`DuplexClient` instance (see [Reconnect and resume](#reconnect-and-resume));
+re-attaching from a new client or process requires the wire-level
+`session.resume` handshake (`resume_token`,
+`last_received_server_event_seq`), which this client does not expose.
 
 ### Stream audio and commit a turn
 
@@ -195,7 +222,7 @@ the stamped `event_id`.
 On a transport drop the client reconnects with the `ReconnectPolicy` backoff
 and sends `session.resume` from the last acknowledged `server_event_seq`.
 Replayed events are deduplicated, consumers see one `ConnectionResumed`
-event, and `client.incarnation` / `client.resume_token` are refreshed. The
+event, and `client.resume_token` is refreshed. The
 server keeps a detached session alive for `disconnect_grace_s` (30 s by
 default); after that a resume fails with `session_resume_expired`. Resume is
 gated by `capabilities.supports_session_resume` (MiniCPM-o 4.5 and Nemotron
@@ -238,9 +265,67 @@ definitions out of the dependency-free client. `audio_bytes(response_id)`, `coun
 `openai-realtime-duplex` benchmark backend (`vllm-omni bench serve`) is built
 on the same helpers.
 
+## Using the Python API
+
+`vllm_omni.entrypoints.duplex_omni.DuplexOmni` is the in-process Python API
+of a duplex model: sessions run inside the engine, and the class only opens,
+resumes and closes them and pipes typed commands in and typed events out
+through a `DuplexSessionHandle`.
+
+```python
+from vllm_omni.engine.duplex.commands import AppendAudio, Commit
+from vllm_omni.engine.duplex.events import AudioDelta, SessionClosed
+from vllm_omni.entrypoints.duplex_omni import DuplexOmni
+
+omni = DuplexOmni(model="openbmb/MiniCPM-o-4_5", trust_remote_code=True)
+async with await omni.open_session({"modalities": ["audio", "text"], "ref_audio": ref_audio_data_url}) as session:
+    async def consume():
+        async for event in session.events():          # typed DuplexEvent objects
+            if isinstance(event, AudioDelta):
+                play(event.audio)
+            elif isinstance(event, ResponseDone):
+                break                                  # one turn is enough here
+    task = asyncio.create_task(consume())
+    await session.submit(AppendAudio(audio=pcm16_bytes, format="pcm16", sample_rate_hz=16000))
+    await session.submit(Commit())
+    await task
+# leaving the block closes the session (the last event is SessionClosed)
+```
+
+`open_session` takes a `DuplexSessionConfig` or the same Realtime `session`
+object the WebSocket handshake takes; the session id is always allocated by
+`DuplexOmni`. `DuplexSessionHandle` offers `submit(command)` plus one
+convenience wrapper per command (`append_audio`, `commit`, `create_response`,
+`cancel_response`, `barge_in`, `ack_playback`, `update`, `create_item`,
+`delete_item`, `truncate_item`, `heartbeat`, ...). `events()` is a
+single-consumer async iterator that ends after `session.closed` /
+`session.expired`; rejected commands come back as `ErrorEvent`s on it.
+Every event renders the wire JSON with `to_realtime()`, so anything written
+against the WebSocket protocol works unchanged on the typed stream.
+
+`vllm_omni.clients.inline_duplex.InlineDuplexClient` wraps a `DuplexOmni`
+behind the `DuplexClient` API, so the same application code runs in-process
+(no server) or over the network:
+
+```python
+from vllm_omni.clients.inline_duplex import InlineDuplexClient
+from vllm_omni.clients.minicpmo_4_5 import create_duplex_session_config
+
+config = create_duplex_session_config(ref_audio=audio_data_url(Path("reference_voice.wav")))
+async with InlineDuplexClient(omni, model="openbmb/MiniCPM-o-4_5", config=config) as client:
+    await client.stream_pcm(question)
+    await client.commit()
+    async for response in client.responses():
+        ...
+```
+
+`examples/online_serving/barge_in_client.py --inline` drives the barge-in
+scenario this way. The inline client has no transport, so it has no
+reconnect, resume, heartbeat or event-acknowledgement machinery.
+
 ## API Reference
 
-This section is the complete wire contract of `/v1/realtime`: how
+This section is the complete wire contract of `/v1/realtime?duplex=1`: how
 the dialect relates to the OpenAI Realtime protocol, which surfaces each
 model's capability flags gate, a catalogue of every client-to-server and
 server-to-client event, and a JSON example for each. `DuplexClient` speaks
@@ -253,21 +338,26 @@ its protocol tests.
 
 ### Endpoint and transport
 
-The endpoint is `ws(s)://<host>/v1/realtime`. Bare connections select the
-session handler when the deployment declares either `session_mode: duplex`
-or `duplex_session`. `?duplex=1` remains a compatibility alias, while
-`?duplex=0` selects the legacy Realtime handler. Optional query parameters
-are `model`, `session_id`,
-`autostart` (`0` means resume-only), `resume`, and `native_duplex`
-(`minicpmo45_native_duplex` is accepted as a deprecated alias and folded
-into the canonical name). Every message is one JSON object per WebSocket
+The endpoint is `ws(s)://<host>/v1/realtime`. On a deployment whose pipeline
+declares a `duplex_plugin` and whose deploy configuration declares
+`session_mode: duplex`, a bare connection is already a duplex session, so a
+stock Realtime client needs no vendor query parameter. `?duplex=1` (`1`,
+`true` or `on`) is the spelling this page uses and stays valid;
+`?duplex=0` (`0`, `false`, `off`) explicitly opts out and selects the
+turn-based Realtime handler, which a duplex server does not mount --
+that connection is answered with `Realtime API is not available`.
+`ws(s)://<host>/v1/duplex` is an alias that always selects the duplex
+handler. Optional query parameters are `model`, `autostart` (`0` means
+resume-only) and `resume`. Every message is one JSON object per WebSocket
 text frame, discriminated by `type`. Inbound events are applied in arrival
 order through one per-session mailbox; outbound events preserve that order
 and carry a monotonically increasing `server_event_seq`, which is the replay
 cursor for `session.resume`. Client events may carry an `event_id`, echoed in
 `error.error.event_id` when the event is rejected.
 
-Session identity is `(session_id, incarnation)`; `attachment_generation`
+Session identity is the server-allocated `session_id` (`duplex-<uuid>`,
+announced in `session.created`; a `session_id` the client puts in the session
+object is ignored, and ids are never reused); `attachment_generation`
 names the current socket; `epoch` is the interruption fence that advances on
 every cancel, clear, or barge-in; `turn_id` counts committed model turns;
 `response_id` (item id `item_<response_id>`) names one assistant utterance.
@@ -281,12 +371,13 @@ with no OpenAI counterpart.
 
 The event vocabulary is uniform, but several surfaces are gated by the
 `capabilities` object the server returns in `session.created`; a client must
-branch on those flags rather than on the model name. The current model
-plugins advertise:
+branch on those flags rather than on the model name. MiniCPM-o 4.5 is the
+only model on the plugin contract today; the other two columns record what
+their integrations advertise once the follow-up PRs port them:
 
 | Capability | MiniCPM-o 4.5 | PersonaPlex | Nemotron VoiceChat | Gated surface |
 | --- | --- | --- | --- | --- |
-| `implementation_level` | `model_native_duplex` (when `extra_body.native_duplex=true`) | `model_native_duplex` | `model_native_duplex` | model-owned `response.listen` / `response.speak`; the chat-fallback lane otherwise |
+| `implementation_level` | `model_native_duplex` | `model_native_duplex` | `model_native_duplex` | model-owned `response.listen` / `response.speak` (constant: every duplex model is model-native) |
 | `chunk_period_ms` | 1000 | 80 | 80 | the model unit that `response.listen` decisions and camera frames align to |
 | `supports_session_resume` | yes | no | yes | `session.resume`, `session.resumed`, `session.replaced`, replay after a transport drop |
 | `supports_barge_in` | yes | no | no | `barge_in`, `turn.signal{event:"barge_in"}`, `overlap_policy=barge_in_on_speech`, `turn_detection.server_vad` |
@@ -316,14 +407,8 @@ work unmodified. The overlap falls into the three tiers used by the event catalo
 | Object shapes | `realtime.session`, `realtime.item`, `realtime.response`; item content parts `input_text` / `input_audio` / `output_text` / `output_audio`; `function_call` and `function_call_output` items; `previous_item_id` chaining; `output_index` / `content_index` addressing |
 | Sequencing | `response.created → output_item.added → content_part.added → deltas → *.done → content_part.done → output_item.done → response.done → rate_limits.updated`; `speech_started → speech_stopped → committed` |
 
-Audio/transcript output uses only the current (non-beta) OpenAI event names
-(`response.output_audio.delta`, not the deprecated `response.audio.delta`),
-matching `openai.types.realtime` in the official `openai` Python SDK and what
-clients built against it (e.g. `livekit-plugins-openai`'s non-Azure code path)
-expect; a client still on the old beta SDK types would not recognize these
-events. Session fields and `conversation.item.*` events, in contrast, are
-deliberately dual: the server emits and accepts **both** the beta and the GA
-spellings at once (`output_modalities` alongside `modalities`,
+The server deliberately emits and accepts **both** the beta and the GA
+spellings at once (`response.output_audio.delta` alongside `output_modalities`,
 `conversation.item.added` alongside `conversation.item.created`) so either
 generation of OpenAI client parses the stream.
 
@@ -333,7 +418,7 @@ A stock client ignores the extra keys; the extensions are additive.
 
 | Message | Extension |
 | --- | --- |
-| `session.created` / `session.updated` | top-level `incarnation`, `attachment_generation`, `resume_token`; inside `session`: `state`, `turn_state`, `epoch`, `turn_id`, `active_request_id`, `active_response_id`, `active_response_turn_id`, `overlap_policy`, `overlap_*_ms/rms`, `playback_commit_policy`, `playback`, `capabilities`, `ref_audio`, `extra_body`, `idle_timeout_s`, `response_format` |
+| `session.created` / `session.updated` | top-level `attachment_generation`, `resume_token`; inside `session`: `state`, `turn_state`, `epoch`, `turn_id`, `active_request_id`, `active_response_id`, `active_response_turn_id`, `overlap_policy`, `overlap_*_ms/rms`, `playback_commit_policy`, `playback`, `capabilities`, `ref_audio`, `extra_body`, `idle_timeout_s`, `response_format` |
 | `response.created` / `response.done` / `response.listen` | `response_id` at top level; the raw duplex event under `response.metadata` (`duplex_event`); `status_details.reason` uses vLLM reasons (`barge_in`, `client_cancelled`, `new_response`, …) |
 | `response.output_audio.delta` | `format`, `sample_rate_hz`, `metadata{session_id, epoch, model_speak, end_of_turn, audio_duration_ms, audio_text_marks, playback}` |
 | `response.speak` (inserted before the first delta) | not an OpenAI event, but rides the OpenAI response envelope (`response_id`, `item_id`, `output_index`, `content_index`) |
@@ -349,14 +434,9 @@ Semantic divergences hidden behind shared names:
   before any commit; a commit may end in `response.listen` and no
   response, and the model may open a response with no commit at all.
   OpenAI: commit ⇒ item, `response.create` ⇒ exactly one response.
-- With `turn_detection={"type":"server_vad"}`, omitted `interrupt_response`
-  defaults to `false` on turn-based models such as Qwen3-Omni, enabling
-  endpointing and automatic responses without interruption. Explicit `true`
-  is rejected there. Model-native duplex keeps the `true` default and rejects
-  `false`; its VAD implies `overlap_policy=barge_in_on_speech`.
-  This capability-dependent default differs from OpenAI's `true` default;
-  the effective configuration is returned in `session.created` / `session.updated`.
-  `semantic_vad` is unsupported.
+- `turn_detection.interrupt_response=false` is rejected;
+  `create_response` is ignored; `semantic_vad` is unsupported; the VAD
+  runs per session (Silero) and implies `overlap_policy=barge_in_on_speech`.
 - `rate_limits.updated` is always an empty list (compatibility only).
 - Cancellation never reuses a `response_id`; truncation is driven by
   `playback.ack` as well as `conversation.item.truncate`.
@@ -365,11 +445,11 @@ Semantic divergences hidden behind shared names:
 
 | Area | Messages / fields |
 | --- | --- |
-| Session lifetime | `session.heartbeat` / `session.heartbeat_ack`, `session.event_ack`, `session.close` / `session.closed`, `session.resume` / `session.resumed` / `session.replaced` / `session.expired` / `session.resync_required`; `server_event_seq`, `resume_token`, `incarnation`, `attachment_generation`; query params `?duplex=1`, `autostart`, `resume`, `native_duplex` |
+| Session lifetime | `session.heartbeat` / `session.heartbeat_ack`, `session.event_ack`, `session.close` / `session.closed`, `session.resume` / `session.resumed` / `session.replaced` / `session.expired` / `session.resync_required`; `server_event_seq`, `resume_token`, `attachment_generation`; query params `?duplex=1`, `autostart`, `resume` |
 | Turn-taking | `response.speak`, `response.listen`, `overlap.decision`, `overlap_policy`, `barge_in`, `turn.signal`, `input.cancel`, `input.text.append`, `epoch` / `turn_id` fencing, `force_listen` |
 | Playback truth | `playback.ack` / `playback.acknowledged`, `playback_commit_policy` (`ack_only` \| `commit_all_on_done`), `playback{generated_ms, sent_ms, played_ms, committed_ms}`, `history_committed`, `audio_text_marks` |
-| Model negotiation | `capabilities{implementation_level, supports_input_append, supports_barge_in, supports_session_resume, chunk_period_ms, input_modes, …}`, `ref_audio`, `extra_body` (`auto_response`, `native_duplex` — deprecated alias `minicpmo45_native_duplex` is folded into it, `force_listen_count`, `duplex_initial_user_text`) |
-| Diagnostics | `runtime.control`, `duplex.function_call.done`, the full error-code vocabulary (`REALTIME_ERROR_TYPES_BY_CODE` in `vllm_omni/entrypoints/duplex/realtime_state.py`) |
+| Model negotiation | `capabilities{implementation_level, supports_input_append, supports_barge_in, supports_session_resume, chunk_period_ms, input_modes, …}`, `ref_audio`, `extra_body` (`auto_response`, `force_listen_count`, `duplex_initial_user_text`) |
+| Diagnostics | `duplex.function_call.done`, the full error-code vocabulary (`REALTIME_ERROR_TYPES_BY_CODE` in `vllm_omni/engine/duplex/events.py`) |
 
 #### Consequences for clients
 
@@ -433,11 +513,15 @@ remains an approximation, not word-level audio alignment.
 ### Event catalogue
 
 Every event type the Realtime route accepts or emits, with a worked example in the next section: 21
-client→server and 42 server→client. Aliases (`push_chunk`,
-`input.audio.append`, `input_text.append`, `push_text`, `signal_turn`,
-`audio.playback_ack`, `close_session`, `close`, `session_close`) share the
-payload of their canonical event and are not listed separately; the alias
-table lives in the normative contract section of [Full-Duplex Runtime (MiniCPM-o 4.5)](../design/fullduplex.md).
+client→server and 42 server→client. Aliases (`input_text.append`,
+`push_text`, `signal_turn`, `audio.playback_ack`, `close_session`, `close`)
+share the payload of their canonical event and are not listed
+separately; the alias table is `translate_realtime_command` in
+`vllm_omni/engine/duplex/realtime_commands.py`. The pre-Realtime WAV-append
+aliases `push_chunk` and `input.audio.append` are **not** accepted on this
+route: send `input_audio_buffer.append` with one of the supported input
+formats (`pcm16`, `pcm_s16le`, `s16le`, `pcm_f32le`, `g711_ulaw`,
+`g711_alaw`).
 
 #### Client to server
 
@@ -447,18 +531,18 @@ table lives in the normative contract section of [Full-Duplex Runtime (MiniCPM-o
 | `session.heartbeat` | 3 | Keepalive; refreshes the engine session lease. |
 | `session.event_ack` | 3 | Acknowledges received server events by `server_event_seq`; trims the resume replay journal. |
 | `session.close` | 3 | Graceful close; answered with `session.closed`. |
-| `session.resume` | 3 | Re-attach a live session on a new socket (`resume_token`, `incarnation`, `last_received_server_event_seq`). |
+| `session.resume` | 3 | Re-attach a live session on a new socket (`session_id`, `resume_token`, `last_received_server_event_seq`). |
 | `input_audio_buffer.append` | 2 | Append one audio chunk. OpenAI name; extended with `is_speech`, `video_frames`, `duration_ms`, `audio_end_ms`, per-event `format`/`sample_rate_hz`. |
 | `input_audio_buffer.commit` | 2 | Seal the buffered utterance into a user item. OpenAI name; extended with `final`, `response_create`, `is_speech:false`. |
 | `input.commit` | 3 | Alias of `input_audio_buffer.commit` accepted by the runner. |
 | `input_audio_buffer.clear` | 1 | Drop un-committed input audio. |
 | `input.cancel` | 3 | Cancel pending input; advances `epoch`. |
-| `input.text.append` | 3 | Append text to the open input item (chat-fallback lane only). |
+| `input.text.append` | 3 | Append text input; model-native sessions reject it with `native_text_append_unsupported`. |
 | `conversation.item.create` | 1 | Add a completed user item (text, audio, or `function_call_output`) to history. |
 | `conversation.item.retrieve` | 1 | Fetch a stored item by id. |
 | `conversation.item.delete` | 1 | Delete a stored item by id. |
 | `conversation.item.truncate` | 1 | Truncate an assistant item's audio/transcript at `audio_end_ms`. |
-| `response.create` | 1 | Explicitly request a response with per-response overrides. |
+| `response.create` | 1 | Explicitly request a response with per-response overrides. Requires committed audio input; otherwise `response_create_without_input`. |
 | `response.cancel` | 1 | Cancel the active (or named) response; advances `epoch`. |
 | `output_audio_buffer.clear` | 1 | Discard queued output audio; advances `epoch` (OpenAI: WebRTC-only, here also WebSocket). |
 | `barge_in` | 3 | Explicit hard interrupt; requires `capabilities.supports_barge_in`. |
@@ -469,10 +553,10 @@ table lives in the normative contract section of [Full-Duplex Runtime (MiniCPM-o
 
 | Event type | Tier | Description |
 | --- | --- | --- |
-| `session.created` | 2 | Session opened. OpenAI name; adds `incarnation`, `attachment_generation`, `resume_token` and vLLM-Omni keys inside `session` (`epoch`, `turn_id`, `playback`, `capabilities`, ...). |
+| `session.created` | 2 | Session opened. OpenAI name; adds `attachment_generation`, `resume_token` and vLLM-Omni keys inside `session` (`id` is the server-allocated session id, `epoch`, `turn_id`, `playback`, `capabilities`, ...). |
 | `session.updated` | 2 | Echo of the effective session config after every `session.update` (same extended `session` object). |
 | `session.heartbeat_ack` | 3 | Reply to `session.heartbeat`. |
-| `session.closed` | 3 | Last event on the socket; `reason` ∈ `session_close`, `timeout`, `disconnect`, ... |
+| `session.closed` | 3 | Last event on the socket, emitted once the engine released the session; `reason` ∈ `client_close`, `disconnect`, `timeout`, `transport_error`, `shutdown`, ... |
 | `session.resumed` | 3 | Resume accepted; carries the new `attachment_generation` and rotated `resume_token`; journaled events are replayed after it. |
 | `session.replaced` | 3 | Sent to the superseded socket when another socket resumes the session. |
 | `session.expired` | 3 | Engine lease reaped (`disconnect_grace_expired`, `idle_ttl_expired`); socket closes after it. |
@@ -508,8 +592,8 @@ table lives in the normative contract section of [Full-Duplex Runtime (MiniCPM-o
 | `duplex.function_call.done` | 3 | Raw fallback when a model tool call is malformed. |
 | `output_audio_buffer.cleared` | 1 | Reply to `output_audio_buffer.clear`. |
 | `playback.acknowledged` | 3 | Reply to `playback.ack`; returns the playback ledger and `history_committed`. |
-| `overlap.decision` | 3 | How an append that overlapped an active response was handled (`drop` \| `listen` \| `barge_in`). |
-| `runtime.control` | 3 | Diagnostic: an engine control signal was partially unsupported. |
+| `overlap.decision` | 3 | How an append that overlapped an active response was handled (`drop` \| `listen` \| `barge_in`); details under `metadata`. |
+| `turn.event` | 3 | A turn-taking signal the session accepted (`event`, resulting `turn_state`). |
 | `error` | 2 | Error envelope. OpenAI shape and classes; vLLM-Omni error codes. |
 
 ### Message examples
@@ -528,7 +612,6 @@ additionally carries `"server_event_seq": <int>` (omitted below for brevity).
   "event_id": "evt_0001",
   "session": {
     "model": "openbmb/MiniCPM-o-4_5",
-    "session_id": "sess_demo_01",
     "modalities": ["audio", "text"],
     "instructions": "You are a concise voice assistant.",
     "input_audio_format": "pcm16",
@@ -541,7 +624,6 @@ additionally carries `"server_event_seq": <int>` (omitted below for brevity).
     "idle_timeout_s": 300,
     "extra_body": {
       "auto_response": true,
-      "native_duplex": true,
       "force_listen_count": 0
     }
   }
@@ -553,13 +635,12 @@ additionally carries `"server_event_seq": <int>` (omitted below for brevity).
 ```json
 {
   "type": "session.created",
-  "incarnation": 0,
   "attachment_generation": 1,
   "resume_token": "rt_3f9c…",
   "session": {
     "object": "realtime.session",
     "type": "realtime",
-    "id": "sess_demo_01",
+    "id": "duplex-5f2a…",
     "model": "openbmb/MiniCPM-o-4_5",
     "state": "open",
     "turn_state": "idle",
@@ -612,7 +693,7 @@ additionally carries `"server_event_seq": <int>` (omitted below for brevity).
 `session.created` and every later `session.update`)
 
 ```json
-{"type": "session.updated", "session": {"object": "realtime.session", "id": "sess_demo_01", "…": "…"}}
+{"type": "session.updated", "session": {"object": "realtime.session", "id": "duplex-5f2a…", "…": "…"}}
 ```
 
 `C→S session.heartbeat` / `S→C session.heartbeat_ack`
@@ -622,7 +703,7 @@ additionally carries `"server_event_seq": <int>` (omitted below for brevity).
 ```
 
 ```json
-{"type": "session.heartbeat_ack", "session_id": "sess_demo_01"}
+{"type": "session.heartbeat_ack", "session_id": "duplex-5f2a…"}
 ```
 
 `C→S session.event_ack`
@@ -638,7 +719,7 @@ additionally carries `"server_event_seq": <int>` (omitted below for brevity).
 ```
 
 ```json
-{"type": "session.closed", "session_id": "sess_demo_01", "reason": "session_close"}
+{"type": "session.closed", "session_id": "duplex-5f2a…", "epoch": 3, "reason": "client_close", "event": {"type": "session.closed", "reason": "client_close"}}
 ```
 
 `C→S session.resume` (new socket, `?duplex=1&autostart=0`)
@@ -646,8 +727,7 @@ additionally carries `"server_event_seq": <int>` (omitted below for brevity).
 ```json
 {
   "type": "session.resume",
-  "session_id": "sess_demo_01",
-  "incarnation": 0,
+  "session_id": "duplex-5f2a…",
   "resume_token": "rt_3f9c…",
   "last_received_server_event_seq": 40
 }
@@ -659,8 +739,8 @@ events with `server_event_seq > 40` are replayed in order)
 ```json
 {
   "type": "session.resumed",
-  "session_id": "sess_demo_01",
-  "incarnation": 0,
+  "session_id": "duplex-5f2a…",
+  "session": {"id": "duplex-5f2a…", "state": "open", "epoch": 3, "turn_id": 2, "...": "the engine's current session object"},
   "attachment_generation": 2,
   "resume_token": "rt_a71e…"
 }
@@ -669,19 +749,19 @@ events with `server_event_seq > 40` are replayed in order)
 `S→C session.replaced` (sent to the superseded socket, which is then closed)
 
 ```json
-{"type": "session.replaced", "session_id": "sess_demo_01", "attachment_generation": 1}
+{"type": "session.replaced", "session_id": "duplex-5f2a…", "attachment_generation": 1}
 ```
 
 `S→C session.expired`
 
 ```json
-{"type": "session.expired", "session_id": "sess_demo_01", "incarnation": 0, "reason": "disconnect_grace_expired"}
+{"type": "session.expired", "session_id": "duplex-5f2a…", "reason": "disconnect_grace_expired"}
 ```
 
 `S→C session.resync_required`
 
 ```json
-{"type": "session.resync_required", "session_id": "sess_demo_01", "reason": "journal_gap"}
+{"type": "session.resync_required", "session_id": "duplex-5f2a…", "reason": "journal_gap"}
 ```
 
 #### Input
@@ -772,7 +852,7 @@ silence/noise declaration (no runtime append; answered with `response.listen`)
   "item_id": "item_9b2d…",
   "event": {
     "type": "input.committed",
-    "session_id": "sess_demo_01",
+    "session_id": "duplex-5f2a…",
     "turn_id": 1,
     "epoch": 0,
     "history_len": 1,
@@ -802,7 +882,7 @@ deferred commit during an active response (`event.response_create_deferred`)
   "type": "input_audio_buffer.committed",
   "previous_item_id": "item_9b2d…",
   "item_id": "item_c044…",
-  "event": {"type": "input.committed", "session_id": "sess_demo_01", "turn_id": 2, "epoch": 0, "history_len": 3, "response_create_deferred": true, "message": {"…": "…"}}
+  "event": {"type": "input.committed", "session_id": "duplex-5f2a…", "turn_id": 2, "epoch": 0, "history_len": 3, "response_create_deferred": true, "message": {"…": "…"}}
 }
 ```
 
@@ -911,7 +991,7 @@ deferred commit during an active response (`event.response_create_deferred`)
     "status_details": null,
     "output": [],
     "modalities": ["audio", "text"],
-    "metadata": {"duplex_event": {"type": "response.created", "session_id": "sess_demo_01", "response_id": "resp_01", "epoch": 0, "turn_id": 1}}
+    "metadata": {"duplex_event": {"type": "response.created", "session_id": "duplex-5f2a…", "response_id": "resp_01", "epoch": 0, "turn_id": 1}}
   }
 }
 ```
@@ -947,7 +1027,7 @@ deferred commit during an active response (`event.response_create_deferred`)
   "item_id": "item_resp_01",
   "output_index": 0,
   "content_index": 0,
-  "metadata": {"session_id": "sess_demo_01", "epoch": 0, "model_speak": true}
+  "metadata": {"session_id": "duplex-5f2a…", "epoch": 0, "model_speak": true}
 }
 ```
 
@@ -964,7 +1044,7 @@ deferred commit during an active response (`event.response_create_deferred`)
   "format": "pcm16",
   "sample_rate_hz": 24000,
   "metadata": {
-    "session_id": "sess_demo_01",
+    "session_id": "duplex-5f2a…",
     "epoch": 0,
     "model_speak": true,
     "end_of_turn": false,
@@ -1029,7 +1109,7 @@ deferred commit during an active response (`event.response_create_deferred`)
     "status": "completed",
     "status_details": null,
     "output": [{"id": "item_resp_01", "object": "realtime.item", "type": "message", "role": "assistant", "status": "completed", "content": [{"type": "output_audio", "transcript": "It is sunny, 24 degrees."}]}],
-    "metadata": {"type": "response.done", "session_id": "sess_demo_01", "response_id": "resp_01", "epoch": 0, "committed": true, "playback": {"generated_ms": 2400, "sent_ms": 2400, "played_ms": 2400, "committed_ms": 2400}}
+    "metadata": {"type": "response.done", "session_id": "duplex-5f2a…", "response_id": "resp_01", "epoch": 0, "committed": true, "playback": {"generated_ms": 2400, "sent_ms": 2400, "played_ms": 2400, "committed_ms": 2400}}
   }
 }
 ```
@@ -1055,9 +1135,9 @@ deferred commit during an active response (`event.response_create_deferred`)
 ```json
 {
   "type": "response.listen",
-  "session_id": "sess_demo_01",
+  "session_id": "duplex-5f2a…",
   "epoch": 0,
-  "response": {"object": "realtime.response", "status": "listening", "metadata": {"type": "response.listen", "session_id": "sess_demo_01", "epoch": 0, "reason": "model_listen"}}
+  "response": {"object": "realtime.response", "status": "listening", "metadata": {"type": "response.listen", "session_id": "duplex-5f2a…", "epoch": 0, "reason": "model_listen"}}
 }
 ```
 
@@ -1104,7 +1184,7 @@ function-call response (Nemotron VoiceChat tools)
 raw fallback when a model tool call is malformed (`call_id`/`name` missing)
 
 ```json
-{"type": "duplex.function_call.done", "event": {"type": "function_call.done", "session_id": "sess_demo_01", "epoch": 0, "call_id": null, "name": null, "arguments": "{"}}
+{"type": "duplex.function_call.done", "event": {"type": "function_call.done", "session_id": "duplex-5f2a…", "epoch": 0, "call_id": null, "name": null, "arguments": "{"}}
 ```
 
 #### Playback
@@ -1120,7 +1200,7 @@ raw fallback when a model tool call is malformed (`call_id`/`name` missing)
   "type": "playback.acknowledged",
   "event": {
     "type": "playback.acknowledged",
-    "session_id": "sess_demo_01",
+    "session_id": "duplex-5f2a…",
     "epoch": 0,
     "item_id": "item_resp_01",
     "played_ms": 1000,
@@ -1145,20 +1225,17 @@ truncating ack after an interruption (what was actually heard)
 ```json
 {
   "type": "overlap.decision",
-  "session_id": "sess_demo_01",
+  "session_id": "duplex-5f2a…",
   "epoch": 0,
   "policy": "listen_only",
   "action": "listen",
   "reason": "long_overlap_speech",
-  "overlap_ms": 1400,
-  "buffer_audio": true,
-  "defer_runtime_append": true,
-  "force_listen": true
+  "metadata": {"overlap_ms": 1400, "buffer_audio": true, "defer_runtime_append": true, "force_listen": true}
 }
 ```
 
 ```json
-{"type": "overlap.decision", "session_id": "sess_demo_01", "epoch": 0, "policy": "barge_in_on_speech", "action": "barge_in", "reason": "server_vad_utterance_active"}
+{"type": "overlap.decision", "session_id": "duplex-5f2a…", "epoch": 0, "policy": "barge_in_on_speech", "action": "barge_in", "reason": "server_vad_utterance_active"}
 ```
 
 server-VAD session (`session.update` fragment) and the annotated append the
@@ -1172,12 +1249,6 @@ translator forwards internally (shown for reference; clients never see it)
 {"type": "input_audio_buffer.append", "audio": "…", "format": "pcm16", "sample_rate_hz": 16000, "is_speech": true, "force_listen": true, "vad": {"backend": "silero", "is_speech": true, "speech_active": true, "speech_started": true, "speech_stopped": false, "speech_probability": 0.93}}
 ```
 
-`S→C runtime.control` (only when an engine signal was partially unsupported)
-
-```json
-{"type": "runtime.control", "session_id": "sess_demo_01", "epoch": 1, "result": {"…": "redacted engine control result"}}
-```
-
 #### Errors
 
 `S→C error` — Realtime shape
@@ -1203,71 +1274,79 @@ translator forwards internally (shown for reference; clients never see it)
 ```
 
 ```json
-{"type": "error", "error": {"type": "rate_limit_error", "code": "duplex_session_busy", "message": "duplex session capacity reached (max_sessions=4)"}}
+{"type": "error", "error": {"type": "rate_limit_error", "code": "resource_exhausted", "message": "duplex_session_capacity_exhausted: limit=4"}}
 ```
 
 Handshake-stage errors (before the Realtime projector is bound) use the
 flat native shape:
 
 ```json
-{"type": "error", "error": "Unknown or expired duplex session: sess_demo_01", "code": "session_resume_expired"}
+{"type": "error", "error": "Unknown or expired duplex session: duplex-5f2a…", "code": "session_resume_expired"}
 ```
 
 #### Coverage
 
 The examples above cover every event type the Realtime route emits or
 accepts (verified by diffing the `type` literals in
-`vllm_omni/entrypoints/duplex/` against this document). Not shown, because
-they never reach a `/v1/realtime?duplex=1` client unprojected: the native
-`/v1/duplex` dialect (`session.create` / `open_session` / `session.config`,
-`input.committed`, `input.cancelled`, `audio.cancelled`,
-`response.output_audio.delta`, `response.text.delta`, `response.message`,
-`function_call.done`) — their Realtime projections are the examples above
-(see the name map at the end of this section) — and the runner-internal markers `__timeout__`,
-`__disconnect__`, `__replaced_attachment__`. Input aliases (`push_chunk`,
-`input.audio.append`, `input_text.append`, `push_text`, `signal_turn`,
-`audio.playback_ack`, `close_session`, `close`, `session_close`) share the
-payload of their canonical event (see the alias table in [Full-Duplex Runtime (MiniCPM-o 4.5)](../design/fullduplex.md)).
-
-#### Native to Realtime name map
-
-The native `/v1/duplex` dialect is what the session runner produces; the
-Realtime projector renames and fans out these events before they reach a
-`/v1/realtime?duplex=1` client.
-
-| Native / internal event | Realtime projection |
+`vllm_omni/engine/duplex/events.py` and `vllm_omni/engine/duplex/commands.py`
+against this document). Not shown, because they never reach a client
+unprojected: the session-internal events the runner produces
+(`input.committed`, `input.cancelled`, `audio.cancelled`,
+`response.output_audio.delta`, `response.text.delta`, `function_call.done`)
+— their Realtime projections are the examples above (see the name map at the
+end of this section). Every public event is a typed `DuplexEvent` whose
+`to_realtime()` is the wire object; every client event is parsed into a
+typed `DuplexCommand` by `command_from_realtime()`.
+
+#### Internal to Realtime name map
+
+The session runner emits these session-internal events; the Realtime
+projector (`vllm_omni/engine/duplex/realtime_events.py`) renames and fans
+them out into typed events before they reach a client.
+
+| Internal event | Realtime projection |
 | --- | --- |
-| `session.create` (`open_session`, `session.config`) | first `session.update` |
 | `input.committed` | `conversation.item.added` / `conversation.item.created`, `input_audio_buffer.committed`, `conversation.item.input_audio_transcription.completed`, `conversation.item.done` |
 | `input.cancelled` | `input_audio_buffer.cleared` |
 | `response.output_audio.delta` (with `audio_transcript`) | optional `response.speak`, then `response.output_audio.delta` and `response.output_audio_transcript.delta` |
 | `response.output_audio.done` / `response.output_text.done` | `response.output_audio.done` / `response.output_text.done` |
 | `response.text.delta` | `response.output_text.delta` |
-| `response.message` (chat-fallback raw chunk) | passed through |
 | `audio.cancelled` | optional `output_audio_buffer.cleared`, then the cancelled terminal events and `response.done` with `status: "cancelled"` |
 | `function_call.done` | `response.created`, `response.output_item.added` (`function_call` item), `response.function_call_arguments.delta` / `.done`, `response.output_item.done`, `response.done` |
 | `playback.acknowledged` | `playback.acknowledged` (wrapped verbatim under `event`) |
-| `runtime.control`, `session.resumed`, `session.replaced`, `session.expired`, `session.resync_required`, `session.heartbeat_ack` | passed through unchanged |
+| `session.resumed`, `session.replaced`, `session.expired`, `session.resync_required`, `session.heartbeat_ack` | passed through unchanged |
 
 ## Known Limitations
 
+- Only MiniCPM-o 4.5 is served over this endpoint today; PersonaPlex and
+  Nemotron VoiceChat arrive with the follow-up PRs that port them to the
+  plugin contract.
 - Several surfaces are capability-gated per model (see *Capability
   negotiation by model* above): PersonaPlex does not support session resume,
   barge-in, or audio truncation; Nemotron VoiceChat does not support barge-in
   or audio truncation; camera frames are consumed only by MiniCPM-o 4.5; tool
   calls are produced only by Nemotron VoiceChat.
-- `turn_detection` supports `server_vad` or `null`, not `semantic_vad`.
-  Turn-based models support endpointing without interruption, including
-  `create_response=false` for explicit response creation. Model-native duplex
-  requires `interrupt_response=true` and `create_response=true`.
+- A response is generated from committed **audio**, so the OpenAI text-prompt
+  shape does not drive one: `conversation.item.create` with an `input_text`
+  part adds the item to history, but a following `response.create` with no
+  committed audio is rejected with `response_create_without_input`, and
+  `input.text.append` is rejected with `native_text_append_unsupported`.
+  Text-to-speech has its own shape here — put the text in
+  `extra_body.duplex_initial_user_text` on `session.update`, then stream audio
+  units (silence is enough). The seeded turn is what the model answers.
+- `turn_detection` supports only `server_vad` with `interrupt_response=true`;
+  `semantic_vad`, `interrupt_response=false`, and `create_response` are not
+  supported.
 - `input_audio_transcription` and `input_audio_noise_reduction` are accepted
   and echoed but no separate transcription or noise-reduction stage runs;
   transcripts come from the model.
 - `rate_limits.updated` is emitted for compatibility only and always carries
   an empty list.
 - Session capacity is bounded by `duplex_session.max_sessions` in the deploy
-  configuration; admission beyond it fails with `duplex_session_busy` or
-  `resource_exhausted`.
-- The native `/v1/duplex` route speaks the internal dialect and does not
-  support `session.resume`; use `/v1/realtime?duplex=1` for the contract on
-  this page.
+  configuration; admission beyond it fails with `resource_exhausted`
+  (`rate_limit_error`, retryable).
+- A duplex deployment serves the duplex session surfaces only: the websocket
+  route and `/v1/chat/completions`, the latter on a session per request (see
+  [Start the Server](#start-the-server)). The other turn-based HTTP routes
+  report "not available" on a MiniCPM-o 4.5 server; turn-based use of the
+  model stays available offline through `Omni` / `AsyncOmni`.
diff --git a/examples/online_serving/barge_in_client.py b/examples/online_serving/barge_in_client.py
index b144da9f40c..b9d95c7904e 100644
--- a/examples/online_serving/barge_in_client.py
+++ b/examples/online_serving/barge_in_client.py
@@ -14,7 +14,10 @@
 
 The demo is model-neutral: it drives any duplex model through the public
 :class:`vllm_omni.clients.duplex.DuplexClient` over
-``/v1/realtime?duplex=1``. Model-specific session shape comes from the
+``/v1/realtime?duplex=1``, or — with ``--inline`` — through
+:class:`vllm_omni.clients.inline_duplex.InlineDuplexClient` on an in-process
+:class:`vllm_omni.entrypoints.duplex_omni.DuplexOmni` (no server needed; the
+model loads in this process). Model-specific session shape comes from the
 per-model presets under ``vllm_omni.clients.<model>`` selected with
 ``--preset`` (default ``minicpmo_4_5``, whose model decides listen/speak on
 its own — no VAD).
@@ -31,6 +34,15 @@
         --interrupt-wav follow_up_16k.wav \
         --output-dir ./duplex_out
 
+or, without a server, in-process (``--deploy-config`` is optional and defaults
+to the model's bundled duplex profile):
+
+    python barge_in_client.py --inline \
+        --model /path/to/MiniCPM-o-4_5 \
+        --ref-audio /path/to/reference_voice.wav \
+        --question-wav question_16k.wav \
+        --interrupt-wav follow_up_16k.wav
+
 Input WAVs must be mono 16 kHz PCM16; when a preset's session takes a
 different capture format (the PersonaPlex preset streams 24 kHz float32),
 the audio is converted before streaming. ``--ref-audio`` is required by the
@@ -55,6 +67,7 @@
 from vllm_omni.clients.duplex import (  # noqa: E402
     AudioFormat,
     DuplexClient,
+    DuplexClientBase,
     EventCollector,
     SessionConfig,
     acknowledge_collected_playback,
@@ -139,6 +152,39 @@ def _fold_responses(collector: EventCollector) -> dict[str, dict[str, object]]:
     return out
 
 
+def _make_client(args: argparse.Namespace, config: SessionConfig) -> DuplexClientBase:
+    """Websocket client by default; ``--inline`` drives an in-process DuplexOmni."""
+    if not args.inline:
+        return DuplexClient(
+            args.url,
+            model=args.model,
+            config=config,
+            reconnect=None,
+            heartbeat_interval_s=None,
+            handshake_timeout_s=args.timeout_s,
+        )
+    # Imported lazily: the in-process path loads the model (and its engine
+    # dependencies) in this process, which the websocket path never needs.
+    from vllm_omni.clients.inline_duplex import InlineDuplexClient
+    from vllm_omni.entrypoints.duplex_omni import DuplexOmni
+
+    # Models shipped with custom HF code (MiniCPM-o) need trust_remote_code to
+    # resolve their pipeline; harmless for the others.
+    omni_kwargs: dict[str, object] = {"model": args.model, "trust_remote_code": True}
+    if args.deploy_config:
+        omni_kwargs["deploy_config"] = args.deploy_config
+    omni = DuplexOmni(**omni_kwargs)
+    client = InlineDuplexClient(
+        omni,
+        model=args.model,
+        config=config,
+        handshake_timeout_s=args.timeout_s,
+    )
+    # The client owns no engine; stop the in-process one when the run ends.
+    client.owned_omni = omni  # type: ignore[attr-defined]
+    return client
+
+
 async def run(args: argparse.Namespace) -> int:
     config = _session_config(args.preset, ref_audio_path=args.ref_audio)
     question = _convert_to_session_format(read_pcm16_wav(Path(args.question_wav)), config.input_audio)
@@ -148,105 +194,117 @@ async def run(args: argparse.Namespace) -> int:
     output_dir.mkdir(parents=True, exist_ok=True)
 
     collector = EventCollector()
-    client = DuplexClient(
-        args.url,
-        model=args.model,
-        config=config,
-        reconnect=None,
-        heartbeat_interval_s=None,
-        handshake_timeout_s=args.timeout_s,
-    )
+    client = _make_client(args, config)
     # GREET: open the voice session (handshake happens on enter).
-    async with client:
-        consume_task = asyncio.create_task(collector.consume(client))
-
-        # ASK: stream the question at realtime pace, then commit the turn.
-        # The model decides on its own to answer (no VAD).
-        print("[1] streaming question ...", file=sys.stderr)
-        await client.stream_pcm(question, chunk_ms=chunk_ms)
-        await client.commit(create_response=False)
-        await wait_for_condition(
-            lambda: collector.count("response.created") > 0,
-            timeout_s=args.timeout_s,
-            label="first response.created",
-        )
-        print("[1] assistant is answering", file=sys.stderr)
-
-        # Let the answer play for a moment, as a listening user would.
-        await asyncio.sleep(args.listen_s)
-
-        # INTERRUPT: talk over the assistant while its audio still streams.
-        # The serving overlap policy decides: enough overlapped speech barges
-        # in (the first response is cancelled) or a short remark is deferred
-        # until the model yields the turn.
-        print("[2] interrupting mid-answer ...", file=sys.stderr)
-        ids_before_interrupt = set(collector.response_ids)
-        await client.stream_pcm(interrupt, chunk_ms=chunk_ms)
-        await client.commit(create_response=False)
-
-        # ANSWER AGAIN: wait for a response created *after* the interruption
-        # to finish. The first answer may still be streaming here; matching on
-        # any response.done would let its completion satisfy the wait and cut
-        # off the actual follow-up answer at close.
-        def follow_up_answer_done() -> bool:
-            return any(
-                event.get("type") == "response.done"
-                and collector.response_id(event) is not None
-                and collector.response_id(event) not in ids_before_interrupt
-                for event in collector.events
+    try:
+        async with client:
+            consume_task = asyncio.create_task(collector.consume(client))
+
+            # ASK: stream the question at realtime pace, then commit the turn.
+            # The model decides on its own to answer (no VAD).
+            print("[1] streaming question ...", file=sys.stderr)
+            await client.stream_pcm(question, chunk_ms=chunk_ms)
+            await client.commit(create_response=False)
+            await wait_for_condition(
+                lambda: collector.count("response.created") > 0,
+                timeout_s=args.timeout_s,
+                label="first response.created",
+            )
+            print("[1] assistant is answering", file=sys.stderr)
+
+            # Let the answer play for a moment, as a listening user would.
+            await asyncio.sleep(args.listen_s)
+
+            # INTERRUPT: talk over the assistant while its audio still streams.
+            # The serving overlap policy decides: enough overlapped speech barges
+            # in (the first response is cancelled) or a short remark is deferred
+            # until the model yields the turn.
+            print("[2] interrupting mid-answer ...", file=sys.stderr)
+            ids_before_interrupt = set(collector.response_ids)
+            await client.stream_pcm(interrupt, chunk_ms=chunk_ms)
+            await client.commit(create_response=False)
+
+            # ANSWER AGAIN: wait for a response created *after* the interruption
+            # to finish. The first answer may still be streaming here; matching on
+            # any response.done would let its completion satisfy the wait and cut
+            # off the actual follow-up answer at close.
+            def follow_up_answer_done() -> bool:
+                return any(
+                    event.get("type") == "response.done"
+                    and collector.response_id(event) is not None
+                    and collector.response_id(event) not in ids_before_interrupt
+                    for event in collector.events
+                )
+
+            await wait_for_condition(
+                follow_up_answer_done,
+                timeout_s=args.timeout_s,
+                label="response.done for the response answering the interruption",
             )
 
-        await wait_for_condition(
-            follow_up_answer_done,
-            timeout_s=args.timeout_s,
-            label="response.done for the response answering the interruption",
+            # HANG UP: report playback, close the session cleanly.
+            await acknowledge_collected_playback(client, collector)
+            await client.close(timeout_s=args.timeout_s)
+            try:
+                await asyncio.wait_for(consume_task, timeout=5.0)
+            except (asyncio.TimeoutError, asyncio.CancelledError):
+                consume_task.cancel()
+
+        # Report: one WAV per response; statuses show what the overlap did.
+        responses = _fold_responses(collector)
+        summary: list[dict[str, object]] = []
+        for index, (response_id, item) in enumerate(responses.items(), start=1):
+            audio = item["audio"]
+            assert isinstance(audio, bytes)
+            sample_rate_hz = int(item["sample_rate_hz"])  # type: ignore[arg-type]
+            wav_path = output_dir / f"response_{index}_{item['status']}.wav"
+            if audio:
+                write_pcm16_wav(wav_path, audio, sample_rate_hz=sample_rate_hz)
+            summary.append(
+                {
+                    "response_id": response_id,
+                    "status": item["status"],
+                    "audio_s": round(len(audio) / (sample_rate_hz * 2), 2),
+                    "text": item["text"],
+                    "wav": wav_path.name if audio else None,
+                }
+            )
+        (output_dir / "summary.json").write_text(json.dumps(summary, indent=2, ensure_ascii=False))
+        (output_dir / "events.jsonl").write_text(
+            "".join(json.dumps(event, ensure_ascii=False) + "\n" for event in collector.events),
+            encoding="utf-8",
         )
-
-        # HANG UP: report playback, close the session cleanly.
-        await acknowledge_collected_playback(client, collector)
-        await client.close(timeout_s=args.timeout_s)
-        try:
-            await asyncio.wait_for(consume_task, timeout=5.0)
-        except (asyncio.TimeoutError, asyncio.CancelledError):
-            consume_task.cancel()
-
-    # Report: one WAV per response; statuses show what the overlap did.
-    responses = _fold_responses(collector)
-    summary: list[dict[str, object]] = []
-    for index, (response_id, item) in enumerate(responses.items(), start=1):
-        audio = item["audio"]
-        assert isinstance(audio, bytes)
-        sample_rate_hz = int(item["sample_rate_hz"])  # type: ignore[arg-type]
-        wav_path = output_dir / f"response_{index}_{item['status']}.wav"
-        if audio:
-            write_pcm16_wav(wav_path, audio, sample_rate_hz=sample_rate_hz)
-        summary.append(
-            {
-                "response_id": response_id,
-                "status": item["status"],
-                "audio_s": round(len(audio) / (sample_rate_hz * 2), 2),
-                "text": item["text"],
-                "wav": wav_path.name if audio else None,
-            }
+        print(json.dumps(summary, indent=2, ensure_ascii=False))
+        cancelled = sum(1 for item in summary if item["status"] == "cancelled")
+        print(
+            f"\n{len(summary)} responses ({cancelled} interrupted); outputs in {output_dir}",
+            file=sys.stderr,
         )
-    (output_dir / "summary.json").write_text(json.dumps(summary, indent=2, ensure_ascii=False))
-    (output_dir / "events.jsonl").write_text(
-        "".join(json.dumps(event, ensure_ascii=False) + "\n" for event in collector.events),
-        encoding="utf-8",
-    )
-    print(json.dumps(summary, indent=2, ensure_ascii=False))
-    cancelled = sum(1 for item in summary if item["status"] == "cancelled")
-    print(
-        f"\n{len(summary)} responses ({cancelled} interrupted); outputs in {output_dir}",
-        file=sys.stderr,
-    )
+    finally:
+        owned_omni = getattr(client, "owned_omni", None)
+        if owned_omni is not None:
+            owned_omni.shutdown()
     return 0
 
 
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     parser.add_argument("--url", default="ws://127.0.0.1:8099/v1/realtime")
-    parser.add_argument("--model", default="openbmb/MiniCPM-o-4_5")
+    parser.add_argument(
+        "--model",
+        default="openbmb/MiniCPM-o-4_5",
+        help="served model name, or the model path with --inline",
+    )
+    parser.add_argument(
+        "--inline",
+        action="store_true",
+        help="run the model in this process through DuplexOmni + InlineDuplexClient instead of connecting to --url",
+    )
+    parser.add_argument(
+        "--deploy-config",
+        default=None,
+        help="deploy YAML for --inline (default: the model's bundled profile)",
+    )
     parser.add_argument(
         "--preset",
         choices=["minicpmo_4_5", "personaplex", "none"],
diff --git a/examples/online_serving/barge_in_client_flow.md b/examples/online_serving/barge_in_client_flow.md
index d32a00e5adf..9562d4c9cd8 100644
--- a/examples/online_serving/barge_in_client_flow.md
+++ b/examples/online_serving/barge_in_client_flow.md
@@ -1,8 +1,10 @@
 # `barge_in_client.py` — what happens, at a glance
 
-The demo plays one everyday conversation pattern against the full-duplex
-server: ask something, get talked-over mid-answer, and see the assistant
-cope. High-level flow below — for the exact wire events, read the
+The demo plays one everyday conversation pattern against a full-duplex
+model: ask something, get talked-over mid-answer, and see the assistant
+cope. It runs either against a server over `/v1/realtime?duplex=1` or, with
+`--inline`, against an in-process `DuplexOmni` — the conversation below is the
+same in both modes. High-level flow — for the exact wire events, read the
 docstring in `barge_in_client.py`.
 
 ```mermaid
@@ -48,7 +50,8 @@ answer is saved as `response_1_cancelled.wav`, a completed one as
 duration per answer.
 
 Companion: the runtime architecture lives in
-[`docs/design/fullduplex.md`](../../docs/design/fullduplex.md); the client
-API is `vllm_omni.clients.duplex.DuplexClient`, documented with the wire
-protocol in
+[`docs/design/fullduplex.md`](../../docs/design/fullduplex.md); the client API is
+`vllm_omni.clients.duplex.DuplexClient` over the websocket and
+`vllm_omni.clients.inline_duplex.InlineDuplexClient` in-process — both are
+documented with the wire protocol in
 [`docs/serving/realtime_duplex_api.md`](../../docs/serving/realtime_duplex_api.md).
diff --git a/examples/online_serving/minicpmo/barge_in_serve.sh b/examples/online_serving/minicpmo/barge_in_serve.sh
index 6dade8c5c22..1aabd304278 100644
--- a/examples/online_serving/minicpmo/barge_in_serve.sh
+++ b/examples/online_serving/minicpmo/barge_in_serve.sh
@@ -5,10 +5,10 @@
 # Server side for barge_in_client.py: start MiniCPM-o 4.5 in native
 # full-duplex mode.
 #
-# The duplex deploy profile registers the WS /v1/duplex endpoint (with
-# /v1/realtime?duplex=1 projecting onto the same handler), enables the
-# engine duplex control plane, and bounds the Thinker/Talker/Code2Wav
-# stages to four live duplex sessions on one GPU. See
+# MiniCPM-o 4.5 declares a duplex plugin, so vllm-omni serve runs it through
+# DuplexOmni: the server is duplex-only (WS /v1/realtime?duplex=1, alias
+# /v1/duplex, plus /v1/models and /health) and bounds the
+# Thinker/Talker/Code2Wav stages to four live duplex sessions on one GPU. See
 # vllm_omni/deploy/minicpmo_4_5.yaml (session_mode: duplex) for the session
 # limits; every other duplex_session knob keeps its runtime default
 # (idle TTL 300s, disconnect grace 30s, 16MiB pending input per session).
@@ -22,4 +22,4 @@ exec vllm-omni serve "$MODEL" \
     --deploy-config vllm_omni/deploy/minicpmo_4_5.yaml \
     --trust-remote-code \
     --host 0.0.0.0 --port "$PORT"
-# duplex endpoints: ws://<host>:$PORT/v1/duplex and /v1/realtime?duplex=1
+# duplex endpoint: ws://<host>:$PORT/v1/realtime?duplex=1 (alias /v1/duplex)
diff --git a/examples/online_serving/minicpmo/realtime_duplex_demo.py b/examples/online_serving/minicpmo/realtime_duplex_demo.py
index 9fc75621e6d..6dc3fd6e79f 100644
--- a/examples/online_serving/minicpmo/realtime_duplex_demo.py
+++ b/examples/online_serving/minicpmo/realtime_duplex_demo.py
@@ -445,7 +445,6 @@ async def run_demo(args: argparse.Namespace) -> dict[str, object]:
             ref_audio=_ref_audio_data_url(args.ref_audio),
             temperature=args.temperature,
         ),
-        session_id=args.session_id,
         reconnect=None,
         heartbeat_interval_s=None,
         handshake_timeout_s=args.timeout_s,
@@ -638,7 +637,6 @@ def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser()
     parser.add_argument("--url", default="ws://localhost:8099/v1/realtime?duplex=1")
     parser.add_argument("--model", default="openbmb/MiniCPM-o-4_5")
-    parser.add_argument("--session-id")
     parser.add_argument(
         "--input-wav",
         help="Mono 16 kHz PCM16 clip to stream. Optional when --input-video carries the audio track.",
diff --git a/examples/online_serving/minicpmo/realtime_web/app/static/app.js b/examples/online_serving/minicpmo/realtime_web/app/static/app.js
index 1ea2ba09343..4d2b782474c 100644
--- a/examples/online_serving/minicpmo/realtime_web/app/static/app.js
+++ b/examples/online_serving/minicpmo/realtime_web/app/static/app.js
@@ -86,7 +86,6 @@
     url.protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
     url.searchParams.set('duplex', '1');
     url.searchParams.set('model', config.model || 'openbmb/MiniCPM-o-4_5');
-    url.searchParams.set('native_duplex', '1');
     url.searchParams.set('autostart', '0');
     return url.toString();
   }
@@ -458,7 +457,6 @@
         settled = true;
         const extraBody = {
           auto_response: true,
-          native_duplex: true,
         };
         const session = {
           modalities: ['audio', 'text'],
diff --git a/recipes/OpenBMB/MiniCPM-o-4_5.md b/recipes/OpenBMB/MiniCPM-o-4_5.md
index fb0934d4f51..01580843fb1 100644
--- a/recipes/OpenBMB/MiniCPM-o-4_5.md
+++ b/recipes/OpenBMB/MiniCPM-o-4_5.md
@@ -1,6 +1,6 @@
 # MiniCPM-o 4.5
 
-> Online serving and offline inference for omni multimodal chat
+> Online full-duplex and chat-completions serving, and offline inference, for omni multimodal chat
 > (text / image / audio / video → text + 24 kHz speech)
 
 ## Summary
@@ -9,8 +9,12 @@
 - Model: [`openbmb/MiniCPM-o-4_5`](https://huggingface.co/openbmb/MiniCPM-o-4_5)
 - Task: Omni multimodal chat — accepts text / image / audio / video input;
   emits text and 24 kHz mono speech in the same response
-- Mode: Online serving via the OpenAI-compatible `/v1/chat/completions`
-  API (plus Gradio demo), and offline inference via `Omni.generate`
+- Mode: Online full-duplex serving over the OpenAI Realtime protocol
+  (`/v1/realtime?duplex=1`, alias `/v1/duplex`), the OpenAI-compatible
+  `/v1/chat/completions` API (plus Gradio demo) on the same server, and
+  offline turn-based inference via `Omni.generate`. Besides those the server
+  exposes only `/v1/models` and `/health`; the other turn-based HTTP routes
+  are not available on a duplex deployment.
 - Maintainer: [`@tc-mb`](https://github.com/tc-mb) (MiniCPM-V / MiniCPM-o team)
 
 ## When to use this recipe
@@ -18,9 +22,10 @@
 Use this recipe as a known-good starting point for serving
 `openbmb/MiniCPM-o-4_5` on vLLM-Omni. MiniCPM-o 4.5 is the omni member
 of the MiniCPM-o family — it runs a multimodal thinker, a streaming
-MiniCPMTTS codec talker, and a separate batched Code2Wav stage so a single
-`/v1/chat/completions` call can return text and 24 kHz speech in one
-shot. The recommended batching deploy isolates the Thinker on GPU 0 and
+MiniCPMTTS codec talker, and a separate batched Code2Wav stage, so a live
+duplex session streams text and 24 kHz speech while it keeps listening, and a
+single `/v1/chat/completions` call returns both in one shot. The
+recommended batching deploy isolates the Thinker on GPU 0 and
 co-locates Talker and Code2Wav on GPU 1; 1-GPU, 3-GPU, and 8x4090 layouts are
 also provided.
 
@@ -36,8 +41,11 @@ also provided.
     [`vllm_omni/deploy/minicpmo_4_5_3gpu.yaml`](../../vllm_omni/deploy/minicpmo_4_5_3gpu.yaml)
     - 8x RTX 4090 layout:
     [`vllm_omni/deploy/minicpmo_4_5_8x4090.yaml`](../../vllm_omni/deploy/minicpmo_4_5_8x4090.yaml)
-- Online example + Gradio demo:
+- Online examples (Realtime CLI demo, browser client, barge-in client,
+  chat-completions client, curl script, Gradio demo):
   [`examples/online_serving/minicpmo/`](../../examples/online_serving/minicpmo/)
+- Duplex API and Python client docs:
+  [`docs/serving/realtime_duplex_api.md`](../../docs/serving/realtime_duplex_api.md)
 - Offline end-to-end example:
   [`examples/offline_inference/minicpmo/`](../../examples/offline_inference/minicpmo/)
 - Pipeline / talker source:
@@ -179,6 +187,13 @@ as one aggregated chunk, so the table reports Stage 0 metrics.
 
 #### Verification
 
+**Health and model listing**:
+
+```bash
+curl http://localhost:8099/health
+curl http://localhost:8099/v1/models
+```
+
 **Quick smoke test (text-only output)**:
 
 ```bash
@@ -191,8 +206,31 @@ curl http://localhost:8099/v1/chat/completions \
     }'
 ```
 
-**Text + speech in one response** (the headline 4.5 feature). The model
-bridge conditions the Talker from the generated assistant span, so the
+**One duplex turn over the Realtime WebSocket** (text + speech stream back
+while the session keeps listening):
+
+```bash
+python examples/online_serving/minicpmo/realtime_duplex_demo.py \
+    --url ws://localhost:8099/v1/realtime?duplex=1 \
+    --model openbmb/MiniCPM-o-4_5 \
+    --input-wav /path/to/input_16k_mono_pcm16.wav \
+    --ref-audio /path/to/MiniCPM-o-Demo/assets/ref_audio/ref_minicpm_signature.wav \
+    --output-dir /tmp/minicpmo_realtime_duplex_demo
+```
+
+The demo prints transcript deltas as they arrive and saves the streamed
+24 kHz audio to WAV files. The same session shape is available from Python
+through `vllm_omni.clients.duplex.DuplexClient` (over the server) or
+`vllm_omni.clients.inline_duplex.InlineDuplexClient` (in-process, no server;
+`examples/online_serving/barge_in_client.py --inline`).
+
+**Barge-in**: `examples/online_serving/barge_in_client.py` plays a question,
+interrupts the answer with a second WAV and checks that the first response is
+cancelled and the second one is answered.
+
+**Text + speech in one response over `/v1/chat/completions`** (the headline
+4.5 feature, served by the ordinary chat service on the duplex engine). The
+model bridge conditions the Talker from the generated assistant span, so the
 generic serving layer does not inject MiniCPM-specific template defaults.
 `use_tts_template=true` remains supported when explicitly requested:
 
@@ -243,6 +281,12 @@ python examples/online_serving/minicpmo/gradio_demo.py \
 Open `http://<host>:7862` and try a text prompt with the **"Generate
 speech output (TTS)"** checkbox on / off.
 
+**Turn-based generation** is also available offline
+(`examples/offline_inference/minicpmo/`, `Omni.generate`).
+
+The Daily-Omni numbers above were measured on the `/v1/chat/completions`
+route.
+
 #### Notes
 
 - Memory budget: Thinker, Talker, and Code2Wav reserve 0.55, 0.15, and
@@ -326,9 +370,13 @@ vllm serve openbmb/MiniCPM-o-4_5 --omni \
   and defaults to deterministic seed 42. Stage-1 deploy sampling parameters
   control only vLLM's binary continue/stop token.
 
-- **Output audio**: 24 kHz mono WAV inside the OpenAI-style
-  `message.audio.data` (base64). The Gradio demo's WAV player decodes
-  this automatically.
+- **Output audio**: 24 kHz mono. On `/v1/chat/completions` it is base64 WAV
+  inside the OpenAI-style `message.audio.data` (the Gradio demo's WAV player
+  decodes this automatically); on a duplex session it streams as base64
+  `response.audio.delta` events; offline `Omni.generate` returns WAV.
+- **Response choices**: on `/v1/chat/completions` text and audio are separate
+  choices. SDK clients should select the choice whose `message.audio.data` is
+  populated rather than assuming `choices[0]` contains audio.
 
 - **Routing**: MiniCPM-o 4.5 and 2.6 both ship `architectures=
   ["MiniCPMO"]` in HF config; routing is disambiguated by
@@ -340,6 +388,3 @@ vllm serve openbmb/MiniCPM-o-4_5 --omni \
 - **Async chunking**: enabled in all deploy configs. Talker sends
   25-code chunks with three-code left context to Code2Wav through
   `SharedMemoryConnector`; terminal chunks flush held lookahead state.
-- **Response choices**: text and audio are separate choices. SDK clients
-  should select the choice whose `message.audio.data` is populated rather
-  than assuming `choices[0]` contains audio.
diff --git a/recipes/README.md b/recipes/README.md
index 33e29c08662..078466e804a 100644
--- a/recipes/README.md
+++ b/recipes/README.md
@@ -71,7 +71,7 @@ recipes/
 | [`cosmos3/Cosmos3-Nano.md`](./cosmos3/Cosmos3-Nano.md) | Text-to-image, text-to-video, image-to-video, video-to-video generation, text to video with sound, action policy | 1x H200 141GB / B300 |
 | [`cosmos3/Cosmos3-Edge.md`](./cosmos3/Cosmos3-Edge.md) | T2I / T2V / I2V + action (Physical-AI) generation on the Nemotron-based Edge transformer | 1x GPU (~8 GiB) |
 | [`cosmos3/Cosmos3-Super.md`](./cosmos3/Cosmos3-Super.md) | 64B T2I / T2V / I2V / V2V generation (+ optional audio) / Action policy | 8x H200/H100/A100 / 2x H200 / B300 |
-| [`OpenBMB/MiniCPM-o-4_5.md`](./OpenBMB/MiniCPM-o-4_5.md) | Online serving for omni multimodal chat (text / image / audio / video → text + 24 kHz speech) | 2x A100/H100 80GB / 3x mid-tier GPU / 8x RTX 4090 24GB |
+| [`OpenBMB/MiniCPM-o-4_5.md`](./OpenBMB/MiniCPM-o-4_5.md) | Online full-duplex serving and offline inference for omni multimodal chat (text / image / audio / video → text + 24 kHz speech) | 2x A100/H100 80GB / 3x mid-tier GPU / 8x RTX 4090 24GB |
 | [`OpenBMB/VoxCPM2.md`](./OpenBMB/VoxCPM2.md) | Online + offline TTS with native AR pipeline (48 kHz, 30+ languages) | 1x RTX 4090 24GB |
 | [`OpenMOSS/MOSS-TTS.md`](./OpenMOSS/MOSS-TTS.md) | Online + offline multilingual TTS (MOSS-TTS family, 8B) | 1x H100 80GB |
 | [`OpenMOSS/MOSS-TTS-Nano-NPU.md`](./OpenMOSS/MOSS-TTS-Nano-NPU.md) | Online multilingual voice-cloned TTS | 1x Ascend 910B3 64GB |
diff --git a/tests/benchmarks/patch/test_patch.py b/tests/benchmarks/patch/test_patch.py
index 60e071ad5d9..d2552bbff53 100644
--- a/tests/benchmarks/patch/test_patch.py
+++ b/tests/benchmarks/patch/test_patch.py
@@ -135,6 +135,7 @@ async def __aexit__(self, exc_type, exc_val, exc_tb):
 async def test_seed_tts_realtime_duplex_exports_per_request_metrics(monkeypatch):
     class FakeRealtimeClient:
         last_instance = None
+        instances: list = []
 
         def __init__(self, url):
             assert url == "ws://localhost:8000/v1/realtime?duplex=1"
@@ -143,6 +144,9 @@ def __init__(self, url):
             self.sent = []
             self.response_count = 0
             self.ack_count = 0
+            self.silence_seconds = []
+            self.closed = 0
+            type(self).instances.append(self)
             type(self).last_instance = self
 
         async def __aenter__(self):
@@ -155,10 +159,22 @@ async def configure(self, model, **kwargs):
             assert model == "openbmb/MiniCPM-o-4_5"
             self.configure_kwargs = kwargs
 
+        async def stream_silence(self, *, seconds, chunk_ms=200, until=None):
+            # A model-native session speaks off its seeded context once audio
+            # units arrive; the silence itself carries no content. The probe
+            # stops the silence as soon as the turn settles.
+            self.silence_seconds.append(seconds)
+            self._emit_response()
+            assert until is not None and until()
+            return 1.0
+
         async def send(self, event):
             self.sent.append(event)
             if event["type"] != "response.create":
                 return
+            self._emit_response()
+
+        def _emit_response(self):
             self.response_count += 1
             response_id = f"resp-{self.response_count}"
             now = time.monotonic()
@@ -210,7 +226,7 @@ async def acknowledge_playback(self):
             self.ack_count += 1
 
         async def close_session(self, **_kwargs):
-            return None
+            self.closed += 1
 
     monkeypatch.setattr(
         "vllm_omni.benchmarks.patch.patch._RealtimeTTSProbe",
@@ -239,30 +255,27 @@ async def close_session(self, **_kwargs):
         session=None,
     )
 
-    client = FakeRealtimeClient.last_instance
-    assert client.configure_kwargs["native_duplex"] is False
-    assert client.configure_kwargs["extra_body"] == {
-        "ref_audio": "data:audio/wav;base64,AAAA",
-        "return_stage_metrics": True,
-    }
-    assert client.sent == [
-        event
-        for index in range(4)
-        for event in (
-            {
-                "type": "conversation.item.create",
-                "item": {
-                    "type": "message",
-                    "role": "user",
-                    "content": [{"type": "input_text", "text": f"text {index}"}],
-                },
-            },
-            {"type": "response.create"},
-        )
-    ]
-    assert client.ack_count == 4
+    # One session per utterance: a model-native duplex session takes its text
+    # once, in the session context, so it cannot be re-seeded for a second one.
+    sessions = FakeRealtimeClient.instances
+    assert len(sessions) == 4
+    for index, client in enumerate(sessions):
+        assert "native_duplex" not in client.configure_kwargs
+        assert client.configure_kwargs["extra_body"] == {
+            "ref_audio": "data:audio/wav;base64,AAAA",
+            "return_stage_metrics": True,
+            "duplex_initial_user_text": f"text {index}",
+            "force_listen_count": 0,
+        }
+        # The target text rides the session context, never a conversation item:
+        # a text-only response.create is rejected by a model-native session.
+        assert client.sent == []
+        assert client.silence_seconds and all(seconds > 0 for seconds in client.silence_seconds)
+        assert client.ack_count == 1
+        assert client.closed == 1
+
     assert output.success is True
-    assert output.generated_text == "turn 1 turn 2 turn 3 turn 4"
+    assert output.generated_text == "turn 1 turn 1 turn 1 turn 1"
     assert output.audio_duration == pytest.approx(0.4)
     assert output.ttft > 0
     assert output.audio_ttfp > output.ttft
@@ -281,11 +294,12 @@ async def close_session(self, **_kwargs):
             "session_id": session_id,
             "request_index": index,
             "utterance_id": f"utt-{index}",
-            "response_id": f"resp-{index + 1}",
+            # Response ids are per session, and each utterance now gets its own.
+            "response_id": "resp-1",
             "source": "client_monotonic_receive",
             "measurement_origin": {
-                "ttft": "conversation.item.create client send to first non-empty text delta",
-                "ttfp": "conversation.item.create client send to first audio packet",
+                "ttft": "first silence append client send to first non-empty text delta",
+                "ttfp": "first silence append client send to first audio packet",
                 "rtf": "request-start-to-last-audio receive time divided by emitted audio duration",
                 "tpot": "Stage-0 engine mean time per output token",
             },
diff --git a/tests/benchmarks/test_omniinteract.py b/tests/benchmarks/test_omniinteract.py
index 73cedfb32be..1a6acaca58b 100644
--- a/tests/benchmarks/test_omniinteract.py
+++ b/tests/benchmarks/test_omniinteract.py
@@ -467,6 +467,27 @@ def test_tolerated_playback_ack_rejection_is_a_warning_not_a_failure():
         oi._raise_if_session_terminated(collector, 0, warnings=warnings)
 
 
+def test_our_own_close_is_expected_even_though_the_server_stamps_a_reason():
+    """``session.close`` is answered with ``session.closed`` carrying ``client_close``.
+
+    The guard exists to catch a session that ended for a reason we did not ask
+    for. A close we requested is not that, whether or not the server names it.
+    """
+    collector = _collector(({"type": "session.closed", "reason": "client_close"}, 1.0))
+    oi._raise_if_session_terminated(collector, 0, explicit_close_from=0)
+
+    collector = _collector(({"type": "session.closed", "event": {"reason": "client_close"}}, 1.0))
+    oi._raise_if_session_terminated(collector, 0, explicit_close_from=0)
+
+    collector = _collector(({"type": "session.closed", "reason": "disconnect"}, 1.0))
+    with pytest.raises(RuntimeError, match="Unexpected session.closed: disconnect"):
+        oi._raise_if_session_terminated(collector, 0, explicit_close_from=0)
+
+    collector = _collector(({"type": "session.expired", "reason": "timeout"}, 1.0))
+    with pytest.raises(RuntimeError, match="session.expired: timeout"):
+        oi._raise_if_session_terminated(collector, 0, explicit_close_from=0)
+
+
 @pytest.mark.parametrize(
     ("event", "match"),
     [
@@ -561,8 +582,8 @@ class _RealtimeClient(oi._RealtimeSession):
 
     instances: list[_RealtimeClient] = []
 
-    def __init__(self, config: oi.OmniInteractBenchmarkConfig, session_id: str, reference_audio: str):
-        super().__init__(config, session_id, reference_audio)
+    def __init__(self, config: oi.OmniInteractBenchmarkConfig, reference_audio: str):
+        super().__init__(config, reference_audio)
         self.acks: list[tuple[str, int]] = []
         self.instances.append(self)
 
@@ -621,7 +642,7 @@ async def test_public_runner_executes_one_prepared_session(tmp_path: Path, monke
     assert "autostart=0" in _RealtimeClient.instances[-1].url
     session_config = _RealtimeClient.instances[-1].session_config
     assert session_config.extra_body["custom"] == "value"
-    assert session_config.extra_body["native_duplex"] is True
+    assert "native_duplex" not in session_config.extra_body
     assert session_config.ref_audio == "data:audio/wav;base64,ref"
     acks = _RealtimeClient.instances[-1].acks
     # Cumulative acks for the one response: an optional 0 ms checkpoint the
diff --git a/tests/benchmarks/test_realtime_tts_probe.py b/tests/benchmarks/test_realtime_tts_probe.py
new file mode 100644
index 00000000000..c07a09b62d7
--- /dev/null
+++ b/tests/benchmarks/test_realtime_tts_probe.py
@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The Seed-TTS Realtime probe queues for a duplex session slot instead of failing."""
+
+from __future__ import annotations
+
+import pytest
+
+from vllm_omni.benchmarks.patch import patch as bench_patch
+from vllm_omni.clients import duplex as duplex_client
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+class _AdmissionGate:
+    """Stands in for ``DuplexClient``: refuses admission ``refusals`` times, then admits."""
+
+    instances: list[_AdmissionGate] = []
+    refusals = 0
+    refusal_code = "resource_exhausted"
+
+    def __init__(self, url: str, **kwargs: object) -> None:
+        del url, kwargs
+        self.entered = False
+        type(self).instances.append(self)
+
+    async def __aenter__(self) -> _AdmissionGate:
+        cls = type(self)
+        if cls.refusals > 0:
+            cls.refusals -= 1
+            raise duplex_client.DuplexProtocolError("duplex_session_capacity_exhausted: limit=4", code=cls.refusal_code)
+        self.entered = True
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        del exc_type, exc, tb
+
+    async def events(self):  # the collector's consume loop ends at once
+        return
+        yield  # pragma: no cover
+
+
+@pytest.fixture
+def gate(monkeypatch: pytest.MonkeyPatch) -> type[_AdmissionGate]:
+    _AdmissionGate.instances = []
+    _AdmissionGate.refusals = 0
+    _AdmissionGate.refusal_code = "resource_exhausted"
+    monkeypatch.setattr(duplex_client, "DuplexClient", _AdmissionGate)
+    return _AdmissionGate
+
+
+async def _configure(probe: bench_patch._RealtimeTTSProbe) -> None:
+    try:
+        await probe.configure("test-model", auto_response=True)
+    finally:
+        await probe.__aexit__(None, None, None)
+
+
+@pytest.mark.asyncio
+async def test_configure_waits_for_a_free_session_slot(gate) -> None:
+    """Two refusals, then a slot: the request is served, not counted as failed."""
+    gate.refusals = 2
+    probe = bench_patch._RealtimeTTSProbe("ws://test/v1/realtime?duplex=1")
+    await _configure(probe)
+    assert len(gate.instances) == 3
+    assert gate.instances[-1].entered is True
+    assert probe._client is gate.instances[-1]
+
+
+@pytest.mark.asyncio
+async def test_configure_raises_other_rejections_at_once(gate) -> None:
+    gate.refusals = 1
+    gate.refusal_code = "unsupported_turn_detection"
+    probe = bench_patch._RealtimeTTSProbe("ws://test/v1/realtime?duplex=1")
+    with pytest.raises(duplex_client.DuplexProtocolError):
+        await _configure(probe)
+    assert len(gate.instances) == 1
+
+
+@pytest.mark.asyncio
+async def test_configure_gives_up_when_the_slot_wait_budget_is_spent(gate, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setattr(bench_patch._RealtimeTTSProbe, "_SESSION_SLOT_WAIT_S", 0.0)
+    gate.refusals = 5
+    probe = bench_patch._RealtimeTTSProbe("ws://test/v1/realtime?duplex=1")
+    with pytest.raises(duplex_client.DuplexProtocolError) as excinfo:
+        await _configure(probe)
+    assert excinfo.value.code == "resource_exhausted"
+    assert len(gate.instances) == 1
+
+
+class _SilenceSink:
+    """Stands in for a configured ``DuplexClient``: records every appended chunk."""
+
+    def __init__(self) -> None:
+        self.config = duplex_client.SessionConfig()
+        self.chunks: list[bytes] = []
+
+    async def append_audio(self, pcm: bytes, *, is_speech: bool | None = None, video_frames=None) -> None:
+        del video_frames
+        assert is_speech is False
+        self.chunks.append(pcm)
+
+
+@pytest.mark.asyncio
+async def test_stream_silence_stops_at_the_turn_end(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Silence is fed until the turn settles, not for the whole cap."""
+    probe = bench_patch._RealtimeTTSProbe("ws://test/v1/realtime?duplex=1")
+    sink = _SilenceSink()
+    probe._client = sink
+
+    async def no_wait(_: float) -> None:
+        return
+
+    monkeypatch.setattr(bench_patch.asyncio, "sleep", no_wait)
+    streamed = await probe.stream_silence(seconds=12.0, chunk_ms=200, until=lambda: len(sink.chunks) >= 3)
+    assert len(sink.chunks) == 3
+    assert streamed == pytest.approx(0.6)
+    assert all(len(chunk) == sink.config.input_audio.byte_count(200) for chunk in sink.chunks)
+
+
+@pytest.mark.asyncio
+async def test_stream_silence_runs_to_the_cap_when_the_turn_never_settles(monkeypatch: pytest.MonkeyPatch) -> None:
+    probe = bench_patch._RealtimeTTSProbe("ws://test/v1/realtime?duplex=1")
+    sink = _SilenceSink()
+    probe._client = sink
+
+    async def no_wait(_: float) -> None:
+        return
+
+    monkeypatch.setattr(bench_patch.asyncio, "sleep", no_wait)
+    streamed = await probe.stream_silence(seconds=1.0, chunk_ms=200, until=lambda: False)
+    assert len(sink.chunks) == 5
+    assert streamed == pytest.approx(1.0)
+
+
+class _TurnEvents:
+    def __init__(self, response_ids: list[str], audio: dict[str, bytes], text: dict[str, str] | None = None) -> None:
+        self.response_ids = response_ids
+        self._audio = audio
+        self._text = text or {}
+
+    def audio_bytes(self, response_id: str) -> bytes:
+        return self._audio.get(response_id, b"")
+
+    def response_text(self, response_id: str) -> str:
+        return self._text.get(response_id, "")
+
+
+def test_turn_response_is_the_first_one_with_audio_even_if_the_model_spoke_again(caplog) -> None:
+    events = _TurnEvents(["r0", "r1", "r2"], {"r1": b"\x01\x00", "r2": b"\x02\x00"})
+    with caplog.at_level("WARNING", logger=bench_patch.logger.name):
+        assert bench_patch._seed_tts_turn_response_id(events, 0, 0) == "r1"
+    assert "spoke again" in caplog.text
+
+
+def test_turn_response_ignores_responses_from_before_the_turn() -> None:
+    events = _TurnEvents(["r0", "r1"], {"r0": b"\x01\x00", "r1": b"\x02\x00"})
+    assert bench_patch._seed_tts_turn_response_id(events, 1, 0) == "r1"
+
+
+def test_turn_without_audio_is_an_error() -> None:
+    events = _TurnEvents(["r0"], {})
+    with pytest.raises(RuntimeError, match="no audio response"):
+        bench_patch._seed_tts_turn_response_id(events, 0, 0)
+
+
+def test_stall_report_says_the_model_never_answered() -> None:
+    events = _TurnEvents(["r0"], {"r0": b"\x01\x00"})
+    report = bench_patch._seed_tts_turn_stall_report(events, 1, 3, 30.0)
+    assert "turn 3 never started a response" in report
+    assert "30.0s of silence" in report
+
+
+def test_stall_report_lists_a_response_that_never_finished() -> None:
+    events = _TurnEvents(["r1"], {"r1": b"\x01\x00\x02\x00"}, {"r1": "hello"})
+    report = bench_patch._seed_tts_turn_stall_report(events, 0, 0, 4.2)
+    assert "started 1 response(s) after 4.2s of silence" in report
+    assert "r1 (4 audio bytes, text 'hello')" in report
diff --git a/tests/clients/test_duplex_client.py b/tests/clients/test_duplex_client.py
index ab2a389516f..43b7547cbd4 100644
--- a/tests/clients/test_duplex_client.py
+++ b/tests/clients/test_duplex_client.py
@@ -1,6 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-"""Unit tests for the public duplex client (fake transport, no server)."""
+"""Unit tests for the public duplex clients (fake transports, no server).
+
+``DuplexClient`` runs over a fake websocket; ``InlineDuplexClient`` over a
+fake ``DuplexOmni`` whose handle records typed commands and replays typed
+events. The demux / handshake tests that only need "feed a server event" are
+parameterized over both clients.
+"""
 
 from __future__ import annotations
 
@@ -8,6 +14,8 @@
 import base64
 import json
 import wave
+from collections.abc import Callable
+from typing import Any
 from urllib.parse import parse_qs, urlsplit
 
 import pytest
@@ -16,8 +24,11 @@
     AudioFormat,
     ConnectionResumed,
     DuplexClient,
+    DuplexClientBase,
+    DuplexConnectionError,
     DuplexProtocolError,
     DuplexSessionClosedError,
+    ErrorEvent,
     EventCollector,
     ReconnectPolicy,
     SessionConfig,
@@ -31,17 +42,26 @@
     summarize_session_request_metrics,
     write_pcm16_wav,
 )
+from vllm_omni.clients.inline_duplex import InlineDuplexClient
+from vllm_omni.engine.duplex import commands as duplex_commands
+from vllm_omni.engine.duplex import events as duplex_events
+from vllm_omni.engine.duplex.messages import DuplexSessionError
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
+SESSION_ID = "duplex-0123456789abcdef"
+# session.created is not journaled by the server, so it carries no server_event_seq.
 SESSION_CREATED = {
     "type": "session.created",
-    "session": {"session_id": "sess-1"},
-    "incarnation": 0,
+    "session": {"id": SESSION_ID, "model": "test-model"},
+    "attachment_generation": 1,
     "resume_token": "tok-1",
-    "server_event_seq": 1,
 }
-SESSION_CLOSED = {"type": "session.closed", "session_id": "sess-1", "server_event_seq": 99}
+SESSION_CLOSED = {"type": "session.closed", "session_id": SESSION_ID, "reason": "client_close", "server_event_seq": 99}
+
+
+# ---------------------------------------------------------------------------
+# Fake websocket transport
 
 
 class FakeSocket:
@@ -88,14 +108,139 @@ async def connect(url: str):
     return client, calls
 
 
+# ---------------------------------------------------------------------------
+# Fake DuplexOmni for the inline client
+
+
+class _WireEvent:
+    """A typed-event stand-in that renders a fixed wire payload."""
+
+    def __init__(self, raw: dict[str, object]) -> None:
+        self.raw = raw
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.raw.get("type") in {"session.closed", "session.expired"}
+
+    def to_realtime(self) -> dict[str, object]:
+        return dict(self.raw)
+
+
+class FakeInlineHandle:
+    def __init__(self, session_id: str) -> None:
+        self.session_id = session_id
+        self.closed = False
+        self.close_calls = 0
+        self.commands: list[duplex_commands.DuplexCommand] = []
+        self.consumer_active = False
+        self._outbox: asyncio.Queue = asyncio.Queue()
+
+    def deliver(self, event: Any) -> None:
+        self._outbox.put_nowait(event)
+
+    def feed(self, raw: dict[str, object]) -> None:
+        self.deliver(_WireEvent(raw))
+
+    async def submit(self, command: duplex_commands.DuplexCommand) -> None:
+        if self.closed:
+            raise DuplexSessionError("closed", code="session_closed", session_id=self.session_id)
+        self.commands.append(command)
+
+    async def events(self):
+        self.consumer_active = True
+        try:
+            while True:
+                event = await self._outbox.get()
+                yield event
+                if event.is_terminal:
+                    return
+        finally:
+            self.consumer_active = False
+
+    async def close(self, *, reason: str = "client_close", timeout: float | None = None) -> None:
+        self.close_calls += 1
+        if self.closed:
+            return
+        self.closed = True
+        self.deliver(duplex_events.SessionClosed(session_id=self.session_id, reason=reason))
+
+
+class FakeInlineOmni:
+    def __init__(self) -> None:
+        self.opened: list[dict[str, object]] = []
+        self.handles: list[FakeInlineHandle] = []
+
+    async def open_session(self, config: dict[str, object]) -> FakeInlineHandle:
+        self.opened.append(dict(config))
+        handle = FakeInlineHandle(SESSION_ID)
+        self.handles.append(handle)
+        handle.deliver(
+            duplex_events.SessionCreated(
+                session_id=SESSION_ID,
+                session={"id": SESSION_ID, "model": config.get("model")},
+            )
+        )
+        return handle
+
+
+def make_inline_client(**kwargs) -> tuple[InlineDuplexClient, FakeInlineOmni]:
+    omni = FakeInlineOmni()
+    kwargs.setdefault("handshake_timeout_s", 5.0)
+    return InlineDuplexClient(omni, model="test-model", **kwargs), omni
+
+
+# ---------------------------------------------------------------------------
+# One rig over both clients: ``feed`` a server event, drive ``client``
+
+
+class Rig:
+    def __init__(self, client: DuplexClientBase, feed: Callable[[dict[str, object]], None]) -> None:
+        self.client = client
+        self.feed = feed
+
+
+def _websocket_rig(*, handshake: dict[str, object] | None = SESSION_CREATED) -> Rig:
+    sock = FakeSocket()
+    if handshake is not None:
+        sock.feed(handshake)
+    client, _ = make_client(sock)
+    return Rig(client, sock.feed)
+
+
+def _inline_rig(*, handshake: dict[str, object] | None = SESSION_CREATED) -> Rig:
+    client, omni = make_inline_client()
+    original_open = omni.open_session
+
+    async def open_session(config: dict[str, object]) -> FakeInlineHandle:
+        handle = await original_open(config)
+        if handshake is not SESSION_CREATED:
+            # Replace the default session.created with the requested first event.
+            handle._outbox = asyncio.Queue()
+            if handshake is not None:
+                handle.feed(handshake)
+        return handle
+
+    omni.open_session = open_session  # type: ignore[method-assign]
+
+    def feed(raw: dict[str, object]) -> None:
+        omni.handles[-1].feed(raw)
+
+    return Rig(client, feed)
+
+
+@pytest.fixture(params=["websocket", "inline"])
+def make_rig(request: pytest.FixtureRequest) -> Callable[..., Rig]:
+    return _websocket_rig if request.param == "websocket" else _inline_rig
+
+
 # ---------------------------------------------------------------------------
 # SessionConfig
 
 
 def test_session_config_payload_defaults():
-    payload = SessionConfig().to_session_payload(model="m", session_id="s")
+    payload = SessionConfig().to_session_payload(model="m")
     assert payload["model"] == "m"
-    assert payload["session_id"] == "s"
+    assert "session_id" not in payload
     assert payload["modalities"] == ["audio", "text"]
     assert payload["input_audio_format"] == "pcm16"
     assert payload["output_audio_format"] == "pcm16"
@@ -137,19 +282,59 @@ def test_audio_format_math():
 
 
 # ---------------------------------------------------------------------------
-# Handshake and lifecycle
+# Handshake and lifecycle (both clients)
+
 
+@pytest.mark.asyncio
+async def test_handshake_adopts_server_allocated_session_id(make_rig):
+    rig = make_rig()
+    async with rig.client as client:
+        assert client.session_id == SESSION_ID
+        assert client.session_info == {"id": SESSION_ID, "model": "test-model"}
+        rig.feed(SESSION_CLOSED)
 
-async def test_handshake_adopts_session_and_acks():
+
+@pytest.mark.asyncio
+async def test_handshake_error_raises_protocol_error(make_rig):
+    rig = make_rig(handshake={"type": "error", "error": {"code": "unsupported_audio_format", "message": "bad"}})
+    with pytest.raises(DuplexProtocolError) as excinfo:
+        async with rig.client:
+            pass
+    assert excinfo.value.code == "unsupported_audio_format"
+
+
+@pytest.mark.asyncio
+async def test_session_expired_raises_from_event_stream(make_rig):
+    rig = make_rig()
+    async with rig.client as client:
+        rig.feed(
+            {"type": "session.expired", "session_id": SESSION_ID, "reason": "lease_expired", "server_event_seq": 2}
+        )
+        with pytest.raises(DuplexSessionClosedError) as excinfo:
+            async for _ in client.events():
+                pass
+        assert "lease_expired" in excinfo.value.reason
+
+
+# ---------------------------------------------------------------------------
+# Websocket transport specifics
+
+
+@pytest.mark.asyncio
+async def test_websocket_handshake_sends_session_update_and_acks_sequenced_events():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
     client, calls = make_client(sock)
     async with client:
-        assert client.session_id == "sess-1"
+        assert client.session_id == SESSION_ID
         assert client.resume_token == "tok-1"
         assert calls == ["ws://test-host:8099/v1/realtime?duplex=1&model=test-model&autostart=0"]
         assert sock.sent[0]["type"] == "session.update"
         assert sock.sent[0]["session"]["model"] == "test-model"
+        assert "session_id" not in sock.sent[0]["session"]
+        # session.created is unjournaled (no seq): nothing to ack yet.
+        assert _acks(sock) == []
+        sock.feed({"type": "response.listen", "server_event_seq": 1})
         await _drain(lambda: {"type": "session.event_ack", "server_event_seq": 1} in _acks(sock))
         close_task = asyncio.create_task(client.close())
         await _drain(lambda: "session.close" in sock.sent_types())
@@ -158,28 +343,7 @@ async def test_handshake_adopts_session_and_acks():
     assert "session.close" in sock.sent_types()
 
 
-async def test_handshake_error_raises_protocol_error():
-    sock = FakeSocket()
-    sock.feed({"type": "error", "error": {"code": "unsupported_audio_format", "message": "bad"}})
-    client, _ = make_client(sock)
-    with pytest.raises(DuplexProtocolError) as excinfo:
-        async with client:
-            pass
-    assert excinfo.value.code == "unsupported_audio_format"
-
-
-async def test_session_expired_raises_from_event_stream():
-    sock = FakeSocket()
-    sock.feed(SESSION_CREATED)
-    client, _ = make_client(sock)
-    async with client:
-        sock.feed({"type": "session.expired", "reason": "lease_expired", "server_event_seq": 2})
-        with pytest.raises(DuplexSessionClosedError) as excinfo:
-            async for _ in client.events():
-                pass
-        assert "lease_expired" in excinfo.value.reason
-
-
+@pytest.mark.asyncio
 async def test_resync_required_drops_resume_credential():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -187,7 +351,7 @@ async def test_resync_required_drops_resume_credential():
     async with client:
         assert client.resume_token == "tok-1"
         stream = client.events()
-        sock.feed({"type": "session.resync_required", "session_id": "sess-1", "server_event_seq": 2})
+        sock.feed({"type": "session.resync_required", "session_id": SESSION_ID, "server_event_seq": 2})
         async for event in stream:
             if event.type == "session.resync_required":
                 break
@@ -202,9 +366,10 @@ async def test_resync_required_drops_resume_credential():
 
 
 # ---------------------------------------------------------------------------
-# Input events
+# Input events (websocket wire shape)
 
 
+@pytest.mark.asyncio
 async def test_append_audio_tracks_cumulative_end_ms():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -224,6 +389,7 @@ async def test_append_audio_tracks_cumulative_end_ms():
         sock.feed(SESSION_CLOSED)
 
 
+@pytest.mark.asyncio
 async def test_append_audio_strips_video_frame_data_url_prefix():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -238,6 +404,7 @@ async def test_append_audio_strips_video_frame_data_url_prefix():
         sock.feed(SESSION_CLOSED)
 
 
+@pytest.mark.asyncio
 async def test_stream_pcm_chunking():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -249,6 +416,7 @@ async def test_stream_pcm_chunking():
         sock.feed(SESSION_CLOSED)
 
 
+@pytest.mark.asyncio
 async def test_interruption_primitives_send_documented_events():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -262,22 +430,21 @@ async def test_interruption_primitives_send_documented_events():
 
 
 # ---------------------------------------------------------------------------
-# Response demultiplexing
+# Response demultiplexing (both clients)
 
 
 def _b64(data: bytes) -> str:
     return base64.b64encode(data).decode("ascii")
 
 
-async def test_response_handle_flow():
-    sock = FakeSocket()
-    sock.feed(SESSION_CREATED)
+@pytest.mark.asyncio
+async def test_response_handle_flow(make_rig):
+    rig = make_rig()
     chunk = b"\x00\x01" * 2400  # 100 ms of pcm16 @ 24 kHz
-    client, _ = make_client(sock)
-    async with client:
-        sock.feed({"type": "response.created", "response": {"id": "resp-1"}, "server_event_seq": 2})
-        sock.feed({"type": "response.speak", "response_id": "resp-1", "server_event_seq": 3})
-        sock.feed(
+    async with rig.client as client:
+        rig.feed({"type": "response.created", "response": {"id": "resp-1"}, "server_event_seq": 2})
+        rig.feed({"type": "response.speak", "response_id": "resp-1", "server_event_seq": 3})
+        rig.feed(
             {
                 "type": "response.output_audio.delta",
                 "response_id": "resp-1",
@@ -286,7 +453,7 @@ async def test_response_handle_flow():
                 "server_event_seq": 4,
             }
         )
-        sock.feed(
+        rig.feed(
             {
                 "type": "response.output_audio_transcript.delta",
                 "response_id": "resp-1",
@@ -294,7 +461,7 @@ async def test_response_handle_flow():
                 "server_event_seq": 5,
             }
         )
-        sock.feed({"type": "response.done", "response_id": "resp-1", "server_event_seq": 6})
+        rig.feed({"type": "response.done", "response_id": "resp-1", "server_event_seq": 6})
 
         async for response in client.responses():
             chunks = [piece async for piece in response.audio()]
@@ -304,49 +471,46 @@ async def test_response_handle_flow():
             assert response.played_ms == pytest.approx(100.0)
             assert response.finished
             break
-        sock.feed(SESSION_CLOSED)
+        rig.feed(SESSION_CLOSED)
 
 
-async def test_listen_decision_yields_finished_silent_handle():
-    sock = FakeSocket()
-    sock.feed(SESSION_CREATED)
-    client, _ = make_client(sock)
-    async with client:
-        sock.feed({"type": "response.listen", "server_event_seq": 2})
+@pytest.mark.asyncio
+async def test_listen_decision_yields_finished_silent_handle(make_rig):
+    rig = make_rig()
+    async with rig.client as client:
+        rig.feed({"type": "response.listen", "server_event_seq": 2})
         async for response in client.responses():
             assert response.decision == "listen"
             assert response.finished
             assert [piece async for piece in response.audio()] == []
             break
-        sock.feed(SESSION_CLOSED)
+        rig.feed(SESSION_CLOSED)
 
 
-async def test_listen_terminates_active_response():
-    sock = FakeSocket()
-    sock.feed(SESSION_CREATED)
-    client, _ = make_client(sock)
-    async with client:
-        sock.feed({"type": "response.created", "response": {"id": "resp-1"}, "server_event_seq": 2})
-        sock.feed({"type": "response.listen", "response_id": "resp-1", "server_event_seq": 3})
+@pytest.mark.asyncio
+async def test_listen_terminates_active_response(make_rig):
+    rig = make_rig()
+    async with rig.client as client:
+        rig.feed({"type": "response.created", "response": {"id": "resp-1"}, "server_event_seq": 2})
+        rig.feed({"type": "response.listen", "response_id": "resp-1", "server_event_seq": 3})
         async for response in client.responses():
             await response.wait(timeout_s=5.0)
             assert response.decision == "listen"
             break
-        sock.feed(SESSION_CLOSED)
+        rig.feed(SESSION_CLOSED)
 
 
-async def test_id_less_listen_never_closes_an_in_flight_response():
+@pytest.mark.asyncio
+async def test_id_less_listen_never_closes_an_in_flight_response(make_rig):
     # An id-less listen is a standalone decision beat (e.g. a silence-skip
     # while a response streams); it must surface as its own finished handle
     # and leave the in-flight response to its real terminal.
-    sock = FakeSocket()
-    sock.feed(SESSION_CREATED)
-    client, _ = make_client(sock)
-    async with client:
-        sock.feed({"type": "response.created", "response": {"id": "resp-1"}, "server_event_seq": 2})
-        sock.feed({"type": "response.speak", "response_id": "resp-1", "server_event_seq": 3})
-        sock.feed({"type": "response.listen", "server_event_seq": 4})
-        sock.feed({"type": "response.done", "response_id": "resp-1", "server_event_seq": 5})
+    rig = make_rig()
+    async with rig.client as client:
+        rig.feed({"type": "response.created", "response": {"id": "resp-1"}, "server_event_seq": 2})
+        rig.feed({"type": "response.speak", "response_id": "resp-1", "server_event_seq": 3})
+        rig.feed({"type": "response.listen", "server_event_seq": 4})
+        rig.feed({"type": "response.done", "response_id": "resp-1", "server_event_seq": 5})
         seen: list[tuple[str | None, str | None, bool]] = []
         async for response in client.responses():
             await response.wait(timeout_s=5.0)
@@ -355,20 +519,19 @@ async def test_id_less_listen_never_closes_an_in_flight_response():
                 break
         assert ("resp-1", "speak", True) in seen
         assert (None, "listen", True) in seen
-        sock.feed(SESSION_CLOSED)
+        rig.feed(SESSION_CLOSED)
 
 
-async def test_terminal_listen_keeps_spoken_decision():
+@pytest.mark.asyncio
+async def test_terminal_listen_keeps_spoken_decision(make_rig):
     # A terminal listen after the response spoke is the model yielding the
     # turn; the handle must stay decision="speak" with its audio intact.
-    sock = FakeSocket()
-    sock.feed(SESSION_CREATED)
+    rig = make_rig()
     chunk = b"\x00\x01" * 2400
-    client, _ = make_client(sock)
-    async with client:
-        sock.feed({"type": "response.created", "response": {"id": "resp-1"}, "server_event_seq": 2})
-        sock.feed({"type": "response.speak", "response_id": "resp-1", "server_event_seq": 3})
-        sock.feed(
+    async with rig.client as client:
+        rig.feed({"type": "response.created", "response": {"id": "resp-1"}, "server_event_seq": 2})
+        rig.feed({"type": "response.speak", "response_id": "resp-1", "server_event_seq": 3})
+        rig.feed(
             {
                 "type": "response.output_audio.delta",
                 "response_id": "resp-1",
@@ -377,24 +540,23 @@ async def test_terminal_listen_keeps_spoken_decision():
                 "server_event_seq": 4,
             }
         )
-        sock.feed({"type": "response.listen", "response_id": "resp-1", "server_event_seq": 5})
+        rig.feed({"type": "response.listen", "response_id": "resp-1", "server_event_seq": 5})
         async for response in client.responses():
             chunks = [piece async for piece in response.audio()]
             assert chunks == [chunk]
             assert response.decision == "speak"
             assert response.finished
             break
-        sock.feed(SESSION_CLOSED)
+        rig.feed(SESSION_CLOSED)
 
 
-async def test_error_event_surfaces_on_response_path():
+@pytest.mark.asyncio
+async def test_error_event_surfaces_on_response_path(make_rig):
     # A rejected send produces no response; a consumer waiting in responses()
     # must see the rejection instead of waiting forever.
-    sock = FakeSocket()
-    sock.feed(SESSION_CREATED)
-    client, _ = make_client(sock)
-    async with client:
-        sock.feed(
+    rig = make_rig()
+    async with rig.client as client:
+        rig.feed(
             {
                 "type": "error",
                 "error": {"code": "input_audio_buffer_empty", "message": "empty commit"},
@@ -405,9 +567,10 @@ async def test_error_event_surfaces_on_response_path():
             async for _ in client.responses():
                 pass
         assert excinfo.value.code == "input_audio_buffer_empty"
-        sock.feed(SESSION_CLOSED)
+        rig.feed(SESSION_CLOSED)
 
 
+@pytest.mark.asyncio
 async def test_slow_audio_consumer_drops_oldest_instead_of_stalling():
     from vllm_omni.clients.duplex import AudioDelta, ResponseHandle
 
@@ -425,24 +588,24 @@ async def test_slow_audio_consumer_drops_oldest_instead_of_stalling():
 
 
 # ---------------------------------------------------------------------------
-# Resume
+# Resume (websocket only)
 
 
+@pytest.mark.asyncio
 async def test_resume_after_transport_drop():
     first = FakeSocket()
     first.feed(SESSION_CREATED)
     second = FakeSocket()
     # Mirror the real resume activation payload
     # (entrypoints/duplex/serving.py, activation_payload_factory): it carries
-    # no nested "session" object, only the identity fields.
+    # the identity fields plus the (empty) public session object.
     second.feed(
         {
             "type": "session.resumed",
-            "session_id": "sess-1",
-            "incarnation": 0,
-            "attachment_generation": 1,
+            "session_id": SESSION_ID,
+            "session": {},
+            "attachment_generation": 2,
             "resume_token": "tok-2",
-            "server_event_seq": 5,
         }
     )
     client, calls = make_client(
@@ -453,34 +616,39 @@ async def test_resume_after_transport_drop():
     async with client:
         stream = client.events()
 
-        async def take_two():
+        async def collect_until_resumed():
             seen = []
             async for event in stream:
                 seen.append(event)
-                if len(seen) == 2:
+                if isinstance(event, SessionResumed):
                     return seen
 
-        consumer = asyncio.create_task(take_two())
+        consumer = asyncio.create_task(collect_until_resumed())
         await asyncio.sleep(0)  # let the consumer subscribe before the drop
         await asyncio.sleep(0)
+        first.feed({"type": "response.listen", "server_event_seq": 7})
+        await _drain(lambda: {"type": "session.event_ack", "server_event_seq": 7} in _acks(first))
         first.feed(RuntimeError("transport dropped"))
         seen = await asyncio.wait_for(consumer, timeout=5.0)
-        assert isinstance(seen[0], ConnectionResumed)
-        assert isinstance(seen[1], SessionResumed)
+        assert [type(event) for event in seen[-2:]] == [ConnectionResumed, SessionResumed]
         assert client.resume_token == "tok-2"
+        # The superseded transport is closed, not leaked.
+        assert first.closed
         # The activation payload has no session object; the info captured at
         # the original handshake must survive the resume.
-        assert client.session_info == {"session_id": "sess-1"}
+        assert client.session_info == {"id": SESSION_ID, "model": "test-model"}
         assert len(calls) == 2
         resume = second.sent[0]
-        assert resume["type"] == "session.resume"
-        assert resume["session_id"] == "sess-1"
-        assert resume["incarnation"] == 0
-        assert resume["resume_token"] == "tok-1"
-        assert resume["last_received_server_event_seq"] == 1
+        assert resume == {
+            "type": "session.resume",
+            "session_id": SESSION_ID,
+            "resume_token": "tok-1",
+            "last_received_server_event_seq": 7,
+        }
         second.feed(SESSION_CLOSED)
 
 
+@pytest.mark.asyncio
 async def test_no_reconnect_policy_surfaces_closed():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -493,6 +661,7 @@ async def test_no_reconnect_policy_surfaces_closed():
                 pass
 
 
+@pytest.mark.asyncio
 async def test_heartbeat_survives_transient_send_failure():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -514,6 +683,7 @@ async def flaky_send(raw: str) -> None:
         sock.feed(SESSION_CLOSED)
 
 
+@pytest.mark.asyncio
 async def test_aexit_sends_session_close_on_error_path():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -534,6 +704,7 @@ def test_target_url_forces_autostart_off():
     assert query["autostart"] == ["0"]
 
 
+@pytest.mark.asyncio
 async def test_fatal_resume_error_gives_up():
     first = FakeSocket()
     first.feed(SESSION_CREATED)
@@ -553,6 +724,121 @@ async def test_fatal_resume_error_gives_up():
         assert len(calls) == 2  # no retry after a fatal resume error
 
 
+# ---------------------------------------------------------------------------
+# Inline client over a fake DuplexOmni
+
+
+@pytest.mark.asyncio
+async def test_inline_handshake_opens_session_with_payload_and_adopts_id():
+    client, omni = make_inline_client(config=SessionConfig(ref_audio="data:audio/wav;base64,AAA="))
+    async with client:
+        assert omni.opened == [client.config.to_session_payload(model="test-model")]
+        assert omni.opened[0]["ref_audio"] == "data:audio/wav;base64,AAA="
+        assert client.session_id == SESSION_ID
+        handle = omni.handles[0]
+        # The session was opened with the full session object already; the
+        # base handshake's session.update must not be re-submitted as a patch
+        # (a ref_audio patch would be rejected by the runner).
+        assert handle.commands == []
+        await client.send({"type": "session.update", "session": {"instructions": "later"}})
+        assert [type(command) for command in handle.commands] == [duplex_commands.UpdateSession]
+        assert handle.commands[0].patch == {"instructions": "later"}
+
+
+@pytest.mark.asyncio
+async def test_inline_client_submits_typed_commands_in_order():
+    client, omni = make_inline_client()
+    async with client:
+        handle = omni.handles[0]
+        pcm = b"\x01\x00" * 1600
+        await client.append_audio(pcm, is_speech=True)
+        await client.commit(create_response=True)
+        await client.cancel_response("resp-1")
+        await client.ack_playback(120.9, response_id="resp-1")
+        assert [type(command) for command in handle.commands] == [
+            duplex_commands.AppendAudio,
+            duplex_commands.Commit,
+            duplex_commands.CancelResponse,
+            duplex_commands.AckPlayback,
+        ]
+        append, commit, cancel, ack = handle.commands
+        assert append.is_speech is True
+        assert append.audio_end_ms == 100
+        assert append.event_id
+        assert commit.final is True and commit.create_response is True
+        assert cancel.response_id == "resp-1"
+        assert ack.played_ms == 120 and ack.response_id == "resp-1"
+
+
+@pytest.mark.asyncio
+async def test_inline_session_close_maps_to_handle_close():
+    client, omni = make_inline_client()
+    async with client:
+        pass
+    handle = omni.handles[0]
+    assert handle.closed
+    assert handle.close_calls >= 1
+    assert not any(isinstance(command, duplex_commands.CloseSession) for command in handle.commands)
+    # The typed session.closed reached the client as the expected end.
+    with pytest.raises(DuplexSessionClosedError):
+        await client.send({"type": "session.heartbeat"})
+
+
+@pytest.mark.asyncio
+async def test_inline_client_forwards_heartbeats_and_drops_event_acks():
+    client, omni = make_inline_client()
+    async with client:
+        handle = omni.handles[0]
+        await client.send({"type": "session.heartbeat"})
+        await client.send({"type": "session.event_ack", "server_event_seq": 3})
+        # A heartbeat is a lease touch the engine must see; the ack is a journal concern.
+        assert [type(command).__name__ for command in handle.commands] == ["Heartbeat"]
+
+
+@pytest.mark.asyncio
+async def test_inline_malformed_payload_surfaces_as_error_event():
+    client, omni = make_inline_client()
+    async with client:
+        handle = omni.handles[0]
+        # Subscribe before sending: the translation error is dispatched inline.
+        first_event = asyncio.create_task(client.wait_for("error", timeout_s=5.0))
+        await asyncio.sleep(0)
+        event_id = await client.send({"type": "playback.ack"})  # played_ms missing
+        event = await first_event
+        assert isinstance(event, ErrorEvent)
+        assert event.code == "bad_event"
+        assert event.related_event_id == event_id
+        assert handle.commands == []
+        with pytest.raises(DuplexProtocolError) as excinfo:
+            async for _ in client.responses():
+                pass
+        assert excinfo.value.code == "bad_event"
+
+
+@pytest.mark.asyncio
+async def test_inline_teardown_cancels_pump_and_closes_handle():
+    client, omni = make_inline_client()
+    async with client:
+        handle = omni.handles[0]
+        await _drain(lambda: handle.consumer_active)
+        pump = client._pump_task
+        assert pump is not None and not pump.done()
+    assert pump.done()
+    assert not handle.consumer_active
+    assert handle.closed
+
+
+@pytest.mark.asyncio
+async def test_inline_send_after_handle_closed_raises_connection_error():
+    client, omni = make_inline_client()
+    async with client:
+        handle = omni.handles[0]
+        handle.closed = True  # the engine ended the session without an event yet
+        with pytest.raises(DuplexConnectionError, match="not open"):
+            await client.send({"type": "input_audio_buffer.clear"})
+        handle.closed = False
+
+
 # ---------------------------------------------------------------------------
 # Collector
 
@@ -600,8 +886,7 @@ def test_build_realtime_url_with_model_extra_query():
     url = build_realtime_url(
         "ws://localhost:8099/v1/realtime?custom=1",
         "openbmb/MiniCPM-o-4_5",
-        session_id="session-a",
-        extra_query={"native_duplex": "1"},
+        extra_query={"probe": "1"},
     )
 
     query = parse_qs(urlsplit(url).query)
@@ -609,8 +894,7 @@ def test_build_realtime_url_with_model_extra_query():
         "custom": ["1"],
         "duplex": ["1"],
         "model": ["openbmb/MiniCPM-o-4_5"],
-        "native_duplex": ["1"],
-        "session_id": ["session-a"],
+        "probe": ["1"],
     }
 
 
@@ -619,12 +903,11 @@ def test_build_realtime_url_resume_only_when_autostart_disabled():
         "ws://localhost:8099/v1/realtime?duplex=1",
         "openbmb/MiniCPM-o-4_5",
         autostart=False,
-        extra_query={"native_duplex": "1"},
     )
 
     query = parse_qs(urlsplit(url).query)
     assert query["autostart"] == ["0"]
-    assert query["native_duplex"] == ["1"]
+    assert "session_id" not in query
 
 
 def test_event_collector_partitions_audio_by_response():
@@ -989,6 +1272,7 @@ def test_duplex_unit_boundary_and_residual_math():
     assert chunk_period_ms([{"type": "session.created", "session": {}}]) == 1000
 
 
+@pytest.mark.asyncio
 async def test_stream_pcm_sends_each_units_composite_beside_its_base_frame():
     sock = FakeSocket()
     sock.feed(SESSION_CREATED)
@@ -1011,16 +1295,16 @@ async def test_stream_pcm_sends_each_units_composite_beside_its_base_frame():
         sock.feed(SESSION_CLOSED)
 
 
-def test_build_realtime_url_native_duplex_flag_and_http_scheme():
-    url = build_realtime_url("http://localhost:8099/v1/realtime", None, native_duplex=None)
+def test_build_realtime_url_rewrites_http_scheme_and_rejects_others():
+    url = build_realtime_url("http://localhost:8099/v1/realtime", None)
     parts = urlsplit(url)
     assert parts.scheme == "ws"
     assert parse_qs(parts.query) == {"duplex": ["1"]}
 
-    url = build_realtime_url("https://host/v1/realtime", "m", native_duplex=False)
+    url = build_realtime_url("https://host/v1/realtime", "m", autostart=True)
     parts = urlsplit(url)
     assert parts.scheme == "wss"
-    assert parse_qs(parts.query)["native_duplex"] == ["0"]
+    assert parse_qs(parts.query) == {"duplex": ["1"], "model": ["m"], "autostart": ["1"]}
 
     with pytest.raises(ValueError):
         build_realtime_url("ftp://host/v1/realtime", "m")
diff --git a/tests/clients/test_model_session_configs.py b/tests/clients/test_model_session_configs.py
index 00741d3c6d7..080fea879b1 100644
--- a/tests/clients/test_model_session_configs.py
+++ b/tests/clients/test_model_session_configs.py
@@ -18,13 +18,13 @@
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
 
-def test_minicpmo45_session_config_matches_native_duplex_deployment():
+def test_minicpmo45_session_config_matches_duplex_deployment():
     config = create_minicpmo45_session_config(ref_audio="data:audio/wav;base64,AAA=", temperature=0.0)
     payload = config.to_session_payload(model="openbmb/MiniCPM-o-4_5")
     assert payload["ref_audio"] == "data:audio/wav;base64,AAA="
     assert payload["overlap_policy"] == "listen_only"
     assert payload["playback_commit_policy"] == "ack_only"
-    assert payload["extra_body"]["native_duplex"] is True
+    assert "native_duplex" not in payload["extra_body"]
     assert payload["extra_body"]["auto_response"] is True
     assert payload["temperature"] == 0.0
 
@@ -41,8 +41,9 @@ def test_personaplex_session_config_matches_deployment():
 @pytest.mark.parametrize(
     "duplex_package",
     [
+        # PersonaPlex and Nemotron VoiceChat rejoin this list with the follow-up
+        # PRs that port them to the duplex plugin framework.
         "vllm_omni.model_executor.models.minicpmo_4_5.duplex",
-        "vllm_omni.model_executor.models.personaplex.duplex",
     ],
 )
 def test_model_duplex_packages_stay_clear_of_client_library(duplex_package: str):
diff --git a/tests/dfx/perf/tests/test_minicpmo_4_5.json b/tests/dfx/perf/tests/test_minicpmo_4_5.json
index 7d7ca08adcd..b384d61a0e6 100644
--- a/tests/dfx/perf/tests/test_minicpmo_4_5.json
+++ b/tests/dfx/perf/tests/test_minicpmo_4_5.json
@@ -26,8 +26,8 @@
       {
         "dataset_name": "seed-tts",
         "dataset_path": "zhaochenyang20/seed-tts-eval",
-        "backend": "openai-chat-omni",
-        "endpoint": "/v1/chat/completions",
+        "backend": "openai-realtime-tts",
+        "endpoint": "/v1/realtime",
         "num_prompts": [
           32,
           64,
@@ -42,73 +42,7 @@
         "disable_shuffle": true,
         "trust_remote_code": true,
         "seed_tts_locale": "en",
-        "extra_body": {
-          "modalities": [
-            "text",
-            "audio"
-          ],
-          "chat_template_kwargs": {
-            "enable_thinking": false,
-            "use_tts_template": true
-          }
-        },
-        "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration",
-        "baseline": {
-          "H100": {
-            "request_throughput": [
-              0.9731,
-              1.1986,
-              1.686
-            ],
-            "mean_ttft_ms": [
-              152.5665,
-              270.2559,
-              301.455
-            ],
-            "mean_e2el_ms": [
-              1027.2953,
-              3306.3735,
-              4686.5366
-            ],
-            "mean_audio_ttfp_ms": [
-              458.1553,
-              2030.2335,
-              2068.6233
-            ],
-            "mean_audio_rtf": [
-              0.2357,
-              0.791,
-              1.0324
-            ]
-          },
-          "A3": {
-            "request_throughput": [
-              0.5383,
-              0.6042,
-              0.7547
-            ],
-            "mean_ttft_ms": [
-              333.2633,
-              533.8656,
-              547.3388
-            ],
-            "mean_e2el_ms": [
-              1857.2154,
-              6600.5101,
-              10450.6811
-            ],
-            "mean_audio_ttfp_ms": [
-              986.4666,
-              3411.0754,
-              3352.7515
-            ],
-            "mean_audio_rtf": [
-              0.4423,
-              1.5734,
-              2.3024
-            ]
-          }
-        }
+        "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration"
       }
     ]
   },
@@ -138,8 +72,8 @@
       {
         "dataset_name": "seed-tts",
         "dataset_path": "zhaochenyang20/seed-tts-eval",
-        "backend": "openai-chat-omni",
-        "endpoint": "/v1/chat/completions",
+        "backend": "openai-realtime-tts",
+        "endpoint": "/v1/realtime",
         "num_prompts": [
           32,
           64,
@@ -154,16 +88,6 @@
         "disable_shuffle": true,
         "trust_remote_code": true,
         "seed_tts_locale": "en",
-        "extra_body": {
-          "modalities": [
-            "text",
-            "audio"
-          ],
-          "chat_template_kwargs": {
-            "enable_thinking": false,
-            "use_tts_template": true
-          }
-        },
         "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration"
       }
     ]
diff --git a/tests/dfx/perf/tests/test_minicpmo_4_5_duplex_seed_tts.json b/tests/dfx/perf/tests/test_minicpmo_4_5_duplex_seed_tts.json
index bb059941921..a145459ed6d 100644
--- a/tests/dfx/perf/tests/test_minicpmo_4_5_duplex_seed_tts.json
+++ b/tests/dfx/perf/tests/test_minicpmo_4_5_duplex_seed_tts.json
@@ -43,43 +43,7 @@
         "extra_body": {
           "save_duplex_request_metrics": true
         },
-        "percentile-metrics": "ttft,tpot,itl,e2el,audio_ttfp,audio_rtf,audio_duration",
-        "baseline": {
-          "H100": {
-            "request_throughput": [
-              0.3038
-            ],
-            "mean_ttft_ms": [
-              139.997
-            ],
-            "mean_e2el_ms": [
-              3269.8807
-            ],
-            "mean_audio_ttfp_ms": [
-              456.073
-            ],
-            "mean_audio_rtf": [
-              0.2254
-            ]
-          },
-          "A3": {
-            "request_throughput": [
-              0.1594
-            ],
-            "mean_ttft_ms": [
-              274.164
-            ],
-            "mean_e2el_ms": [
-              6250.7696
-            ],
-            "mean_audio_ttfp_ms": [
-              994.422
-            ],
-            "mean_audio_rtf": [
-              0.46163
-            ]
-          }
-        }
+        "percentile-metrics": "ttft,tpot,itl,e2el,audio_ttfp,audio_rtf,audio_duration"
       }
     ]
   }
diff --git a/tests/dfx/perf/tests/test_minicpmo_4_5_ready.json b/tests/dfx/perf/tests/test_minicpmo_4_5_ready.json
index 26dc54aab08..4fd78d68139 100644
--- a/tests/dfx/perf/tests/test_minicpmo_4_5_ready.json
+++ b/tests/dfx/perf/tests/test_minicpmo_4_5_ready.json
@@ -26,8 +26,8 @@
       {
         "dataset_name": "seed-tts",
         "dataset_path": "zhaochenyang20/seed-tts-eval",
-        "backend": "openai-chat-omni",
-        "endpoint": "/v1/chat/completions",
+        "backend": "openai-realtime-tts",
+        "endpoint": "/v1/realtime",
         "num_prompts": [
           10,
           40
@@ -40,41 +40,7 @@
         "disable_shuffle": true,
         "trust_remote_code": true,
         "seed_tts_locale": "en",
-        "extra_body": {
-          "modalities": [
-            "text",
-            "audio"
-          ],
-          "chat_template_kwargs": {
-            "enable_thinking": false,
-            "use_tts_template": true
-          }
-        },
-        "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration",
-        "baseline": {
-          "H100": {
-            "request_throughput": [
-              0.9731,
-              1.1986
-            ],
-            "mean_ttft_ms": [
-              152.5665,
-              270.2559
-            ],
-            "mean_e2el_ms": [
-              1027.2953,
-              3306.3735
-            ],
-            "mean_audio_ttfp_ms": [
-              458.1553,
-              2030.2335
-            ],
-            "mean_audio_rtf": [
-              0.2357,
-              0.791
-            ]
-          }
-        }
+        "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration"
       }
     ]
   }
diff --git a/tests/diffusion/streaming_interactive_generation/test_diffusion_streaming_output.py b/tests/diffusion/streaming_interactive_generation/test_diffusion_streaming_output.py
index c833ae7a11b..e0b0a6c5361 100644
--- a/tests/diffusion/streaming_interactive_generation/test_diffusion_streaming_output.py
+++ b/tests/diffusion/streaming_interactive_generation/test_diffusion_streaming_output.py
@@ -39,7 +39,8 @@
 from vllm_omni.engine.async_omni_engine import StageRuntimeInfo
 from vllm_omni.engine.messages import ShutdownRequestMessage, StageSubmissionMessage
 from vllm_omni.engine.stage_init_utils import StageMetadata
-from vllm_omni.entrypoints.async_omni import AsyncEventResolver, AsyncOmni
+from vllm_omni.entrypoints.async_omni import AsyncOmni
+from vllm_omni.entrypoints.async_omni_base import AsyncEventResolver
 from vllm_omni.entrypoints.openai.serving_video_output_stream import OmniStreamingVideoOutputHandler
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.outputs import OmniRequestOutput
diff --git a/tests/diffusion/streaming_interactive_generation/test_prompt_interaction.py b/tests/diffusion/streaming_interactive_generation/test_prompt_interaction.py
index 2e5ceb8e2f4..7780f047535 100644
--- a/tests/diffusion/streaming_interactive_generation/test_prompt_interaction.py
+++ b/tests/diffusion/streaming_interactive_generation/test_prompt_interaction.py
@@ -42,7 +42,8 @@
 from vllm_omni.engine.stage_client import StagePoolClient
 from vllm_omni.engine.stage_init_utils import StageMetadata
 from vllm_omni.engine.stage_pool import StagePool
-from vllm_omni.entrypoints.async_omni import AsyncEventResolver, AsyncOmni
+from vllm_omni.entrypoints.async_omni import AsyncOmni
+from vllm_omni.entrypoints.async_omni_base import AsyncEventResolver
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams, OmniInteractionPrompt
 from vllm_omni.outputs import OmniRequestOutput
 
diff --git a/tests/diffusion/test_diffusion_engine_metrics.py b/tests/diffusion/test_diffusion_engine_metrics.py
index 1dad9facef9..ec222bcd307 100644
--- a/tests/diffusion/test_diffusion_engine_metrics.py
+++ b/tests/diffusion/test_diffusion_engine_metrics.py
@@ -90,6 +90,7 @@ def _get_function_source(source: str, class_name: str | None, func_name: str) ->
     Args:
         source: Full file source code.
         class_name: Enclosing class name, or None for module-level functions.
+            The method may be inherited from a base class defined in the same file.
         func_name: Function/method name.
 
     Returns:
@@ -97,13 +98,24 @@ def _get_function_source(source: str, class_name: str | None, func_name: str) ->
     """
     tree = ast.parse(source)
     if class_name is not None:
-        for node in ast.walk(tree):
-            if isinstance(node, ast.ClassDef) and node.name == class_name:
-                for item in node.body:
-                    if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and item.name == func_name:
-                        result = ast.get_source_segment(source, item)
-                        assert result is not None, f"{class_name}.{func_name} source not found"
-                        return result
+        # Follow the bases: ``Orchestrator`` inherits its loops and helpers from
+        # ``OrchestratorBase`` in the same module, and the lookup stays anchored
+        # on the public class rather than on where the split happens to fall.
+        classes = {node.name: node for node in ast.walk(tree) if isinstance(node, ast.ClassDef)}
+        pending = [class_name]
+        seen: set[str] = set()
+        while pending:
+            name = pending.pop(0)
+            if name in seen or name not in classes:
+                continue
+            seen.add(name)
+            node = classes[name]
+            for item in node.body:
+                if isinstance(item, (ast.FunctionDef, ast.AsyncFunctionDef)) and item.name == func_name:
+                    result = ast.get_source_segment(source, item)
+                    assert result is not None, f"{class_name}.{func_name} source not found"
+                    return result
+            pending.extend(base.id for base in node.bases if isinstance(base, ast.Name))
     else:
         for node in ast.walk(tree):
             if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name == func_name:
diff --git a/tests/e2e/features/fullduplex/test_core_contracts.py b/tests/e2e/features/fullduplex/test_core_contracts.py
index 12a87640f07..45493745cd0 100644
--- a/tests/e2e/features/fullduplex/test_core_contracts.py
+++ b/tests/e2e/features/fullduplex/test_core_contracts.py
@@ -14,7 +14,7 @@
 
 import pytest
 
-from vllm_omni.engine.duplex.messages import DuplexFence
+from vllm_omni.engine.duplex.contracts import DuplexFence
 from vllm_omni.experimental.fullduplex.core import protocol as ev
 from vllm_omni.experimental.fullduplex.core.adapter import (
     DuplexAdapter,
@@ -32,12 +32,15 @@
 
 
 def test_fence_is_frozen_value_identity():
+    # The fence carries (session_id, epoch, turn_id). response_seq was
+    # dropped with the incarnation concept: response identity is the session's
+    # active_response_id, not a field of the fence.
     f = DuplexFence(session_id="s1")
-    assert (f.epoch, f.turn_id, f.response_seq) == (0, 0, 0)
+    assert (f.epoch, f.turn_id) == (0, 0)
     with pytest.raises(dataclasses.FrozenInstanceError):
         f.epoch = 1  # type: ignore[misc]
-    assert DuplexFence("s1", 1, 2, 3) == DuplexFence("s1", 1, 2, 3)
-    assert DuplexFence("s1", 1, 2, 3) != DuplexFence("s1", 2, 2, 3)
+    assert DuplexFence("s1", 1, 2) == DuplexFence("s1", 1, 2)
+    assert DuplexFence("s1", 1, 2) != DuplexFence("s1", 2, 2)
 
 
 def test_session_identity_rules():
diff --git a/tests/e2e/online_serving/helpers/minicpmo_realtime_duplex_scenarios.py b/tests/e2e/online_serving/helpers/minicpmo_realtime_duplex_scenarios.py
index f5bba11e431..0f9b4af5101 100644
--- a/tests/e2e/online_serving/helpers/minicpmo_realtime_duplex_scenarios.py
+++ b/tests/e2e/online_serving/helpers/minicpmo_realtime_duplex_scenarios.py
@@ -71,15 +71,8 @@
 from vllm_omni.metrics.definitions import compute_audio_rtf  # noqa: E402
 
 
-def _url_with_model(url, model, *, autostart=None, session_id=None):
-    # This driver speaks the MiniCPM-o native duplex wire contract.
-    return build_realtime_url(
-        url,
-        model,
-        autostart=autostart,
-        session_id=session_id,
-        extra_query={"native_duplex": "1"},
-    )
+def _url_with_model(url, model, *, autostart=None):
+    return build_realtime_url(url, model, autostart=autostart)
 
 
 _read_wav_pcm16 = read_pcm16_wav
@@ -630,7 +623,6 @@ def _session_update_event(args: DemoArgs) -> dict[str, object]:
         "playback_commit_policy": "ack_only",
         "extra_body": {
             "auto_response": True,
-            "native_duplex": True,
             "force_listen_count": 0,
         },
     }
@@ -646,9 +638,6 @@ def _session_update_event(args: DemoArgs) -> dict[str, object]:
         "type": "session.update",
         "session": session_payload,
     }
-    session_id = getattr(args, "session_id", None)
-    if session_id:
-        session_payload["session_id"] = session_id
     return event
 
 
@@ -1462,7 +1451,6 @@ async def run_demo(args: DemoArgs) -> dict[str, object]:
         args.url,
         args.model,
         autostart=False if getattr(args, "ref_audio", None) else None,
-        session_id=getattr(args, "session_id", None),
     )
     state = DemoState()
     stop = asyncio.Event()
@@ -1674,6 +1662,10 @@ async def run_demo(args: DemoArgs) -> dict[str, object]:
     )
     unexpected_error_events = _unexpected_error_events(state)
     continuous_input_ok = not continuous_input or state.count("input_audio_buffer.committed") == 0
+    # The server allocates every session id; label metrics with the one it announced.
+    created = state.events[0] if state.events else {}
+    created_session = created.get("session") if isinstance(created, dict) else None
+    server_session_id = created_session.get("id") if isinstance(created_session, dict) else None
     result = {
         "ok": terminal_activity_ok
         and state.count("session.closed") > 0
@@ -1711,8 +1703,8 @@ async def run_demo(args: DemoArgs) -> dict[str, object]:
         "input_transcription_ok": input_transcription_ok,
         "completed_response_ids": completed_response_ids,
         "response_timings": state.response_timing_summaries(),
-        "request_metrics": state.session_request_metrics(session_id=args.session_id),
-        "session_metrics": state.session_metric_summary(session_id=args.session_id),
+        "request_metrics": state.session_request_metrics(session_id=server_session_id),
+        "session_metrics": state.session_metric_summary(session_id=server_session_id),
         "lifecycle_counts_ok": lifecycle_counts_ok,
         "validation_mode": validation_mode,
         "scenario": scenario,
@@ -1773,7 +1765,6 @@ def parse_args() -> argparse.Namespace:
     parser = argparse.ArgumentParser()
     parser.add_argument("--url", default="ws://localhost:8099/v1/realtime?duplex=1")
     parser.add_argument("--model", default="openbmb/MiniCPM-o-4_5")
-    parser.add_argument("--session-id", help="Use an explicit public session ID, including for close/reopen tests.")
     parser.add_argument("--input-wav", required=True)
     parser.add_argument("--ref-audio", help="Optional WAV used as the MiniCPM-o voice prompt.")
     parser.add_argument(
diff --git a/tests/e2e/online_serving/run_minicpmo_realtime_duplex_demo_pair.py b/tests/e2e/online_serving/run_minicpmo_realtime_duplex_demo_pair.py
index b5d04097bfe..19b4b8107fe 100644
--- a/tests/e2e/online_serving/run_minicpmo_realtime_duplex_demo_pair.py
+++ b/tests/e2e/online_serving/run_minicpmo_realtime_duplex_demo_pair.py
@@ -17,7 +17,6 @@
 import io
 import json
 import sys
-import uuid
 import wave
 from pathlib import Path
 
@@ -266,8 +265,6 @@ async def _run_demo_process(
         str(args.chunk_ms),
         "--timeout-s",
         str(args.timeout_s),
-        "--session-id",
-        f"duplex-pair-{label}-{uuid.uuid4().hex}",
     ]
     if args.no_realtime_pacing:
         command.append("--no-realtime-pacing")
diff --git a/tests/e2e/online_serving/run_minicpmo_realtime_duplex_multi_session.py b/tests/e2e/online_serving/run_minicpmo_realtime_duplex_multi_session.py
index 32e6e01da5b..c13f8ca7fb3 100644
--- a/tests/e2e/online_serving/run_minicpmo_realtime_duplex_multi_session.py
+++ b/tests/e2e/online_serving/run_minicpmo_realtime_duplex_multi_session.py
@@ -21,7 +21,7 @@
 from websockets.exceptions import ConnectionClosed
 
 SCRIPT_DIR = Path(__file__).resolve().parent
-REPO_ROOT = SCRIPT_DIR.parents[3]
+REPO_ROOT = SCRIPT_DIR.parents[2]
 if str(REPO_ROOT) not in sys.path:
     sys.path.insert(0, str(REPO_ROOT))
 
@@ -42,6 +42,15 @@ def _url_with_model(*args, **kwargs) -> str:
     return _scenario_module()._url_with_model(*args, **kwargs)
 
 
+def _created_session_id(created: dict[str, object]) -> str:
+    """The server-allocated session id announced by ``session.created``."""
+    session = created.get("session")
+    session_id = session.get("id") if isinstance(session, dict) else None
+    if not isinstance(session_id, str) or not session_id:
+        raise RuntimeError("session.created omitted the server-allocated session id")
+    return session_id
+
+
 async def run_demo(args):
     return await _scenario_module().run_demo(args)
 
@@ -217,7 +226,6 @@ async def _open_admission_session(
         args.url,
         args.model,
         autostart=False if getattr(args, "ref_audio", None) else None,
-        session_id=session_id,
     )
     ws = await websockets.connect(url, max_size=64 * 1024 * 1024)
     await ws.send(
@@ -225,10 +233,8 @@ async def _open_admission_session(
             {
                 "type": "session.update",
                 "session": {
-                    "session_id": session_id,
                     "model": args.model,
                     "modalities": ["audio", "text"],
-                    "extra_body": {"native_duplex": True},
                     **({"ref_audio": _ref_audio_data_url(args.ref_audio)} if getattr(args, "ref_audio", None) else {}),
                 },
             }
@@ -255,12 +261,10 @@ async def _admission_probe(args: argparse.Namespace, *, limit: int) -> dict[str,
         for index in range(limit):
             accepted.append(await _open_admission_session(args, f"{prefix}-accepted-{index}"))
 
-        overflow_id = f"{prefix}-overflow"
         overflow_url = _url_with_model(
             args.url,
             args.model,
             autostart=False if getattr(args, "ref_audio", None) else None,
-            session_id=overflow_id,
         )
         async with websockets.connect(overflow_url, max_size=64 * 1024 * 1024) as overflow:
             await overflow.send(
@@ -268,10 +272,8 @@ async def _admission_probe(args: argparse.Namespace, *, limit: int) -> dict[str,
                     {
                         "type": "session.update",
                         "session": {
-                            "session_id": overflow_id,
                             "model": args.model,
                             "modalities": ["audio", "text"],
-                            "extra_body": {"native_duplex": True},
                             **(
                                 {"ref_audio": _ref_audio_data_url(args.ref_audio)}
                                 if getattr(args, "ref_audio", None)
@@ -326,7 +328,6 @@ async def _resume_probe(
         args.url,
         args.model,
         autostart=False if getattr(args, "ref_audio", None) else None,
-        session_id=session_id,
     )
     async with websockets.connect(url, max_size=64 * 1024 * 1024) as first:
         await first.send(
@@ -334,10 +335,8 @@ async def _resume_probe(
                 {
                     "type": "session.update",
                     "session": {
-                        "session_id": session_id,
                         "model": args.model,
                         "modalities": ["audio", "text"],
-                        "extra_body": {"native_duplex": True},
                         **(
                             {"ref_audio": _ref_audio_data_url(args.ref_audio)}
                             if getattr(args, "ref_audio", None)
@@ -348,10 +347,10 @@ async def _resume_probe(
             )
         )
         created, first_events = await _receive_until(first, "session.created", timeout_s=args.timeout_s)
+        session_id = _created_session_id(created)
         token = created.get("resume_token")
-        incarnation = created.get("incarnation")
         generation = created.get("attachment_generation")
-        if not isinstance(token, str) or not isinstance(incarnation, int):
+        if not isinstance(token, str):
             raise RuntimeError("session.created omitted resumable credentials")
         last_seq = max(_server_event_sequences(first_events), default=0)
 
@@ -366,7 +365,6 @@ async def _resume_probe(
                 {
                     "type": "session.resume",
                     "session_id": session_id,
-                    "incarnation": incarnation,
                     "resume_token": token,
                     "last_received_server_event_seq": last_seq,
                 }
@@ -429,7 +427,6 @@ async def _takeover_probe(
         args.url,
         args.model,
         autostart=False if getattr(args, "ref_audio", None) else None,
-        session_id=session_id,
     )
     first = await websockets.connect(url, max_size=64 * 1024 * 1024)
     second = None
@@ -439,10 +436,8 @@ async def _takeover_probe(
                 {
                     "type": "session.update",
                     "session": {
-                        "session_id": session_id,
                         "model": args.model,
                         "modalities": ["audio", "text"],
-                        "extra_body": {"native_duplex": True},
                         **(
                             {"ref_audio": _ref_audio_data_url(args.ref_audio)}
                             if getattr(args, "ref_audio", None)
@@ -453,10 +448,10 @@ async def _takeover_probe(
             )
         )
         created, first_events = await _receive_until(first, "session.created", timeout_s=args.timeout_s)
+        session_id = _created_session_id(created)
         token = created.get("resume_token")
-        incarnation = created.get("incarnation")
         generation = created.get("attachment_generation")
-        if not isinstance(token, str) or not isinstance(incarnation, int) or not isinstance(generation, int):
+        if not isinstance(token, str) or not isinstance(generation, int):
             raise RuntimeError("session.created omitted takeover credentials")
         last_seq = max(_server_event_sequences(first_events), default=0)
 
@@ -466,7 +461,6 @@ async def _takeover_probe(
                 {
                     "type": "session.resume",
                     "session_id": session_id,
-                    "incarnation": incarnation,
                     "resume_token": token,
                     "last_received_server_event_seq": last_seq,
                 }
diff --git a/tests/e2e/online_serving/run_minicpmo_realtime_duplex_soft_interrupt.py b/tests/e2e/online_serving/run_minicpmo_realtime_duplex_soft_interrupt.py
index 5e0cfff3a00..2eee43fae9f 100644
--- a/tests/e2e/online_serving/run_minicpmo_realtime_duplex_soft_interrupt.py
+++ b/tests/e2e/online_serving/run_minicpmo_realtime_duplex_soft_interrupt.py
@@ -18,7 +18,6 @@
 import io
 import json
 import sys
-import uuid
 import wave
 from pathlib import Path
 
@@ -412,8 +411,6 @@ async def run_soft_interrupt(args: argparse.Namespace) -> dict[str, object]:
         str(args.chunk_ms),
         "--timeout-s",
         str(args.timeout_s),
-        "--session-id",
-        f"duplex-soft-interrupt-{uuid.uuid4().hex}",
     ]
     command.extend(["--ref-audio", str(_canonical_path(args.ref_audio))])
     temperature = getattr(args, "temperature", None)
diff --git a/tests/e2e/online_serving/test_duplex_client_live.py b/tests/e2e/online_serving/test_duplex_client_live.py
index d90a8a68340..28044cdd1c6 100644
--- a/tests/e2e/online_serving/test_duplex_client_live.py
+++ b/tests/e2e/online_serving/test_duplex_client_live.py
@@ -12,7 +12,6 @@
 from __future__ import annotations
 
 import asyncio
-import uuid
 from pathlib import Path
 
 import pytest
@@ -47,7 +46,6 @@ async def _run_live_session(*, url: str, model: str, ref_audio: Path, input_wav:
         url,
         model=model,
         config=config,
-        session_id=f"duplex-client-live-{uuid.uuid4().hex}",
         reconnect=ReconnectPolicy(max_attempts=5, backoff_s=(0.25, 1.0)),
         # Short interval so the periodic heartbeat path runs during the
         # session — including across the forced transport drop below.
diff --git a/tests/e2e/online_serving/test_minicpmo_4_5_duplex.py b/tests/e2e/online_serving/test_minicpmo_4_5_duplex.py
index c04d3acec4a..59b40f5e502 100644
--- a/tests/e2e/online_serving/test_minicpmo_4_5_duplex.py
+++ b/tests/e2e/online_serving/test_minicpmo_4_5_duplex.py
@@ -6,8 +6,8 @@
 from __future__ import annotations
 
 import asyncio
+import base64
 import json
-import uuid
 from pathlib import Path
 
 import pytest
@@ -90,25 +90,16 @@ async def receive() -> list[dict[str, object]]:
 
 
 async def _run_protocol_smoke(*, url: str, model: str, ref_audio: Path) -> list[dict[str, object]]:
-    session_id = f"duplex-ci-protocol-{uuid.uuid4().hex}"
-    websocket_url = build_realtime_url(
-        url,
-        model,
-        autostart=False,
-        session_id=session_id,
-        extra_query={"native_duplex": "1"},
-    )
+    websocket_url = build_realtime_url(url, model, autostart=False)
     async with websockets.connect(websocket_url, max_size=64 * 1024 * 1024) as ws:
         await ws.send(
             json.dumps(
                 {
                     "type": "session.update",
                     "session": {
-                        "session_id": session_id,
                         "model": model,
                         "modalities": ["audio", "text"],
                         "ref_audio": _ref_audio_data_url(str(ref_audio)),
-                        "extra_body": {"native_duplex": True},
                     },
                 }
             )
@@ -123,6 +114,170 @@ async def _run_protocol_smoke(*, url: str, model: str, ref_audio: Path) -> list[
     return events
 
 
+async def _run_text_only_response_create(
+    *,
+    url: str,
+    model: str,
+    ref_audio: Path,
+    text: str,
+    timeout_s: float = 120.0,
+) -> dict[str, object]:
+    """Drive a text prompt with no audio and return the server's answer.
+
+    A Realtime client asks for speech from text with a user message item
+    followed by ``response.create``. A model-native duplex session generates
+    from audio units, so this returns whatever the server answers rather than
+    assuming a response.
+    """
+    websocket_url = build_realtime_url(url, model, autostart=False)
+    async with websockets.connect(websocket_url, max_size=64 * 1024 * 1024) as ws:
+        await ws.send(
+            json.dumps(
+                {
+                    "type": "session.update",
+                    "session": {
+                        "model": model,
+                        "modalities": ["audio", "text"],
+                        "output_audio_format": "pcm16",
+                        "turn_detection": None,
+                        "temperature": 0.0,
+                        "ref_audio": _ref_audio_data_url(str(ref_audio)),
+                        "extra_body": {"auto_response": False},
+                    },
+                }
+            )
+        )
+        await _receive_protocol_events(ws, {"session.created", "session.updated"}, timeout_s=60)
+        await ws.send(
+            json.dumps(
+                {
+                    "type": "conversation.item.create",
+                    "item": {
+                        "type": "message",
+                        "role": "user",
+                        "content": [{"type": "input_text", "text": text}],
+                    },
+                }
+            )
+        )
+        await ws.send(json.dumps({"type": "response.create"}))
+
+        async def receive_outcome() -> dict[str, object]:
+            while True:
+                raw = await ws.recv()
+                if not isinstance(raw, str):
+                    continue
+                event = json.loads(raw)
+                if isinstance(event, dict) and event.get("type") in {"error", "response.done"}:
+                    return event
+
+        return await asyncio.wait_for(receive_outcome(), timeout=timeout_s)
+
+
+async def _run_seeded_text_to_audio(
+    *,
+    url: str,
+    model: str,
+    ref_audio: Path | None,
+    text: str,
+    modalities: tuple[str, ...] = ("audio", "text"),
+    silence_seconds: float = 12.0,
+    timeout_s: float = 180.0,
+) -> dict[str, object]:
+    """Speak a seeded text: the duplex route's text-to-speech shape.
+
+    A model-native session takes its text once, in the session context
+    (``duplex_initial_user_text``), and then generates per audio unit. Silence
+    carries no content of its own, so it only advances the clock and lets the
+    model answer the seeded turn.
+    """
+    websocket_url = build_realtime_url(url, model, autostart=False)
+    audio_bytes = 0
+    transcript: list[str] = []
+    output_text: list[str] = []
+    seen: list[str] = []
+    session_payload: dict[str, object] = {
+        "model": model,
+        "modalities": list(modalities),
+        "input_audio_format": "pcm16",
+        "output_audio_format": "pcm16",
+        "turn_detection": None,
+        "temperature": 0.0,
+        "extra_body": {
+            "auto_response": True,
+            "force_listen_count": 0,
+            "duplex_initial_user_text": text,
+        },
+    }
+    if ref_audio is not None:
+        session_payload["ref_audio"] = _ref_audio_data_url(str(ref_audio))
+    async with websockets.connect(websocket_url, max_size=64 * 1024 * 1024) as ws:
+        await ws.send(json.dumps({"type": "session.update", "session": session_payload}))
+
+        async def reader() -> None:
+            nonlocal audio_bytes
+            while True:
+                raw = await ws.recv()
+                if not isinstance(raw, str):
+                    continue
+                event = json.loads(raw)
+                if not isinstance(event, dict):
+                    continue
+                event_type = event.get("type")
+                if isinstance(event_type, str):
+                    seen.append(event_type)
+                delta = event.get("delta")
+                if event_type == "response.output_audio.delta" and isinstance(delta, str):
+                    audio_bytes += len(base64.b64decode(delta))
+                elif event_type == "response.output_audio_transcript.delta" and isinstance(delta, str):
+                    transcript.append(delta)
+                elif event_type == "response.output_text.delta" and isinstance(delta, str):
+                    output_text.append(delta)
+                elif event_type == "error":
+                    raise AssertionError(f"seeded text turn received an error: {event}")
+
+        reader_task = asyncio.create_task(reader())
+        silence = bytes(2 * 16_000 * 200 // 1000)
+        sent_ms = 0
+        try:
+            while sent_ms < silence_seconds * 1000 and "response.done" not in seen:
+                sent_ms += 200
+                await ws.send(
+                    json.dumps(
+                        {
+                            "type": "input_audio_buffer.append",
+                            "audio": base64.b64encode(silence).decode("ascii"),
+                            "input_audio_format": "pcm16",
+                            "sample_rate_hz": 16_000,
+                            "duration_ms": 200,
+                            "audio_end_ms": sent_ms,
+                        }
+                    )
+                )
+                await asyncio.sleep(0.2)
+            loop = asyncio.get_running_loop()
+            deadline = loop.time() + timeout_s
+            while loop.time() < deadline and "response.done" not in seen:
+                await asyncio.sleep(0.5)
+            if reader_task.done():
+                await reader_task
+            # Close explicitly. Dropping the socket parks the session in its
+            # disconnect grace, where it keeps holding an admission slot and
+            # starves the tests that follow.
+            await ws.send(json.dumps({"type": "session.close"}))
+            deadline = loop.time() + 30
+            while loop.time() < deadline and "session.closed" not in seen:
+                await asyncio.sleep(0.25)
+        finally:
+            reader_task.cancel()
+    return {
+        "audio_bytes": audio_bytes,
+        "transcript": "".join(transcript),
+        "output_text": "".join(output_text),
+        "event_types": seen,
+    }
+
+
 @pytest.mark.core_model
 @hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
 @pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
@@ -205,6 +360,215 @@ def test_duplex_single_session_video_input(omni_server, tmp_path: Path) -> None:
     _assert_session_metrics(result["session_metrics"], expected_count=2)
 
 
+@pytest.mark.advanced_model
+@hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
+@pytest.mark.parametrize(
+    ("locale", "text"),
+    [
+        ("en", "Please say exactly: the quick brown fox jumps over the lazy dog."),
+        ("zh", "请朗读：今天天气很好，我们一起去公园散步。"),
+    ],
+)
+def test_duplex_seeded_text_to_audio(omni_server, locale: str, text: str) -> None:
+    """text -> audio over the duplex route, in both locales.
+
+    This is the case the deleted turn-based ``text -> audio`` tests covered.
+    It is also the shape the Seed-TTS Realtime backend uses, so it guards the
+    benchmark path as well as the modality.
+    """
+    result = asyncio.run(
+        _run_seeded_text_to_audio(
+            url=realtime_url(omni_server),
+            model=omni_server.model,
+            ref_audio=resolve_ref_audio(),
+            text=text,
+        )
+    )
+
+    assert "response.done" in result["event_types"], result["event_types"]
+    assert int(result["audio_bytes"]) > 0, f"{locale} seeded text produced no audio"
+    assert str(result["transcript"]).strip(), f"{locale} seeded text produced audio with no transcript"
+
+
+@pytest.mark.advanced_model
+@hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
+def test_duplex_seeded_text_to_text_needs_no_reference_voice(omni_server) -> None:
+    """text -> text, the one duplex session that opens without a reference voice.
+
+    ``ref_audio`` is required only when the session asks for audio output, so a
+    ``modalities: ["text"]`` session is the duplex equivalent of the deleted
+    turn-based ``text -> text`` case. The model is model-native and still
+    speaks its answer, so this asserts the text side and the absence of the
+    ``ref_audio_required`` rejection, not the absence of audio.
+    """
+    result = asyncio.run(
+        _run_seeded_text_to_audio(
+            url=realtime_url(omni_server),
+            model=omni_server.model,
+            ref_audio=None,
+            text="What is the capital of France? Answer in one short sentence.",
+            modalities=("text",),
+        )
+    )
+
+    assert "response.done" in result["event_types"], result["event_types"]
+    produced_text = str(result["output_text"]) or str(result["transcript"])
+    assert produced_text.strip(), f"text-only session produced nothing: {result['event_types']}"
+
+
+@pytest.mark.advanced_model
+@hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
+def test_duplex_seeded_text_to_long_audio_output(omni_server) -> None:
+    """A longer answer, so Code2Wav runs across many frames rather than one.
+
+    Replaces the deleted ``text_to_audio_long_output`` case. The assertion is
+    on the amount of audio rather than its content: the point is that a long
+    answer streams to completion, not that the model says any given word.
+    """
+    result = asyncio.run(
+        _run_seeded_text_to_audio(
+            url=realtime_url(omni_server),
+            model=omni_server.model,
+            ref_audio=resolve_ref_audio(),
+            text="What is the capital of China? Answer in about 40 words.",
+            silence_seconds=30.0,
+            timeout_s=240.0,
+        )
+    )
+
+    assert "response.done" in result["event_types"], result["event_types"]
+    # 24 kHz mono pcm16: 2 s of speech is 96000 bytes, comfortably more than a
+    # single Code2Wav frame and well under a 40-word answer.
+    assert int(result["audio_bytes"]) > 96_000, f"expected a long answer, got {result['audio_bytes']} bytes"
+    assert str(result["transcript"]).strip()
+
+
+@pytest.mark.advanced_model
+@hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
+def test_duplex_seeded_long_form_generation(omni_server) -> None:
+    """Long-form Chinese generation, replacing the deleted long-form case."""
+    result = asyncio.run(
+        _run_seeded_text_to_audio(
+            url=realtime_url(omni_server),
+            model=omni_server.model,
+            ref_audio=resolve_ref_audio(),
+            text="帮我讲一个100字的故事。",
+            silence_seconds=30.0,
+            timeout_s=240.0,
+        )
+    )
+
+    assert "response.done" in result["event_types"], result["event_types"]
+    assert int(result["audio_bytes"]) > 96_000, f"expected long-form audio, got {result['audio_bytes']} bytes"
+    assert str(result["transcript"]).strip()
+
+
+@pytest.mark.advanced_model
+@hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
+def test_duplex_sequential_sessions_are_independent(omni_server) -> None:
+    """A second session must answer its own prompt, not replay the first one.
+
+    Replaces the deleted ``sequential_requests_independent`` case. Sessions are
+    engine-resident now, so this is the check that one session's context does
+    not leak into the next one on the same stages.
+    """
+    first = asyncio.run(
+        _run_seeded_text_to_audio(
+            url=realtime_url(omni_server),
+            model=omni_server.model,
+            ref_audio=resolve_ref_audio(),
+            text="What is the capital of France? Answer in one short sentence.",
+        )
+    )
+    second = asyncio.run(
+        _run_seeded_text_to_audio(
+            url=realtime_url(omni_server),
+            model=omni_server.model,
+            ref_audio=resolve_ref_audio(),
+            text="What is the capital of China? Answer in one short sentence.",
+        )
+    )
+
+    for result in (first, second):
+        assert "response.done" in result["event_types"], result["event_types"]
+        assert int(result["audio_bytes"]) > 0
+        assert str(result["transcript"]).strip()
+
+    # Different prompts must not produce the same answer: that would mean the
+    # second session inherited the first one's context.
+    assert str(first["transcript"]).strip() != str(second["transcript"]).strip()
+
+
+@pytest.mark.advanced_model
+@hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
+def test_duplex_text_only_response_create_is_rejected(omni_server) -> None:
+    """A duplex session generates from audio: a text-only prompt is refused, not ignored.
+
+    Every session on this route is model-native, and such a model decides per
+    audio unit whether to speak: conversation items are context, not a turn.
+    Refusing is the point -- opening a response the model never fills costs the
+    caller the session's whole idle timeout to discover. A text prompt reaches
+    the model through the session's seeded opening turn
+    (``initial_user_text``) instead, which is what ``/v1/chat/completions``
+    uses and what the Seed-TTS Realtime backend has to be ported to.
+    """
+    outcome = asyncio.run(
+        _run_text_only_response_create(
+            url=realtime_url(omni_server),
+            model=omni_server.model,
+            ref_audio=resolve_ref_audio(),
+            text="Please say: the quick brown fox jumps over the lazy dog.",
+        )
+    )
+
+    assert outcome.get("type") == "error", outcome
+    error = outcome.get("error")
+    assert isinstance(error, dict), outcome
+    assert error.get("code") == "text_only_turn_unsupported", outcome
+    assert error.get("type") == "invalid_request_error", outcome
+
+
+@pytest.mark.advanced_model
+@hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
+def test_duplex_single_session_still_image_input(omni_server, tmp_path: Path) -> None:
+    """A spoken turn with one still image attached.
+
+    The still-image case is a one-element frame list, which the client repeats
+    on every unit of the turn: unlike the camera track it never advances, so
+    this covers the image path the turn-based ``image -> text + audio`` request
+    used to cover.
+    """
+    args = demo_args(
+        omni_server=omni_server,
+        input_wav=validated_input_wav(),
+        ref_audio=resolve_ref_audio(),
+        output_dir=tmp_path / "still_image",
+    )
+    args.turns = 2
+    args.turn_duration_ms = [args.first_turn_ms] * args.turns
+    args.video_frames_b64 = duplex_camera_frames(seconds=1, cache_dir=tmp_path / "still")[:1]
+
+    result = asyncio.run(run_demo(args))
+
+    assert result["ok"] is True
+    assert result["video_frame_count"] == 1
+    assert result["video_stacked_frame_count"] == 0
+    _assert_positive_int(result["audio_delta_count"])
+    assert result["done_count"] == 2
+    assert result["error_count"] == 0
+    assert result["all_audio_responses_have_transcript"] is True
+    assert result["transcript_delta_done_ok"] is True
+    _assert_request_metrics(result["request_metrics"], expected_count=2)
+    _assert_session_metrics(result["session_metrics"], expected_count=2)
+
+
 @pytest.mark.advanced_model
 @hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
 @pytest.mark.parametrize("omni_server", SERVER_PARAMS, indirect=True)
diff --git a/tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py b/tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py
index 628040001be..f931fb95d16 100644
--- a/tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py
+++ b/tests/e2e/online_serving/test_minicpmo_4_5_duplex_expansion.py
@@ -30,7 +30,7 @@
     run_soft_interrupt,
 )
 from tests.helpers.mark import hardware_test
-from vllm_omni.entrypoints.duplex.server_vad import (
+from vllm_omni.engine.duplex.vad import (
     SILERO_VAD_FILENAME,
     SILERO_VAD_REPO_ID,
     SILERO_VAD_REVISION,
diff --git a/tests/e2e/online_serving/test_minicpmo_realtime_duplex_drivers.py b/tests/e2e/online_serving/test_minicpmo_realtime_duplex_drivers.py
index ecd885dd60f..a23ce73e817 100644
--- a/tests/e2e/online_serving/test_minicpmo_realtime_duplex_drivers.py
+++ b/tests/e2e/online_serving/test_minicpmo_realtime_duplex_drivers.py
@@ -152,7 +152,6 @@ def test_realtime_duplex_demo_pair_launches_demo_processes_concurrently(tmp_path
                 "parser.add_argument('--output-dir')",
                 "parser.add_argument('--chunk-ms')",
                 "parser.add_argument('--timeout-s')",
-                "parser.add_argument('--session-id')",
                 "parser.add_argument('--ref-audio')",
                 "parser.add_argument('--require-audio', action='store_true')",
                 "parser.add_argument('--no-realtime-pacing', action='store_true')",
@@ -1027,7 +1026,7 @@ def test_realtime_duplex_demo_resolves_distinct_turn_inputs():
         demo._turn_input_paths(primary, ["second.wav"], turns=3)
 
 
-def test_realtime_duplex_demo_explicitly_enables_native_runtime_before_connect():
+def test_realtime_duplex_demo_url_carries_no_model_opt_in_or_session_id():
     demo = _load_demo_module()
 
     url = demo._url_with_model(
@@ -1036,23 +1035,12 @@ def test_realtime_duplex_demo_explicitly_enables_native_runtime_before_connect()
     )
 
     query = parse_qs(urlsplit(url).query)
-    assert query["native_duplex"] == ["1"]
+    assert query["duplex"] == ["1"]
+    assert "native_duplex" not in query
+    assert "session_id" not in query
 
 
-def test_realtime_duplex_demo_explicit_session_id_reaches_autostart_query():
-    demo = _load_demo_module()
-
-    url = demo._url_with_model(
-        "ws://localhost:8099/v1/realtime?duplex=1",
-        "openbmb/MiniCPM-o-4_5",
-        session_id="reopen-e2e",
-    )
-
-    query = parse_qs(urlsplit(url).query)
-    assert query["session_id"] == ["reopen-e2e"]
-
-
-def test_realtime_duplex_demo_session_update_uses_explicit_session_id():
+def test_realtime_duplex_demo_session_update_leaves_session_id_to_the_server():
     demo = _load_demo_module()
 
     event = demo._session_update_event(
@@ -1066,8 +1054,8 @@ def test_realtime_duplex_demo_session_update_uses_explicit_session_id():
 
     assert event["type"] == "session.update"
     assert "session_id" not in event
-    assert event["session"]["session_id"] == "reopen-e2e"
-    assert event["session"]["extra_body"]["native_duplex"] is True
+    assert "session_id" not in event["session"]
+    assert "native_duplex" not in event["session"]["extra_body"]
 
 
 def test_realtime_duplex_demo_response_required_uses_deterministic_sampling():
diff --git a/tests/entrypoints/duplex/test_duplex_audio.py b/tests/engine/duplex/test_duplex_audio.py
similarity index 95%
rename from tests/entrypoints/duplex/test_duplex_audio.py
rename to tests/engine/duplex/test_duplex_audio.py
index d0be020721c..ca358abb03d 100644
--- a/tests/entrypoints/duplex/test_duplex_audio.py
+++ b/tests/engine/duplex/test_duplex_audio.py
@@ -6,7 +6,7 @@
 import numpy as np
 import pytest
 
-from vllm_omni.entrypoints.duplex.audio import convert_input_audio_with_rate
+from vllm_omni.engine.duplex.audio import convert_input_audio_with_rate
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
diff --git a/tests/engine/duplex/test_duplex_commands.py b/tests/engine/duplex/test_duplex_commands.py
new file mode 100644
index 00000000000..ad45c835583
--- /dev/null
+++ b/tests/engine/duplex/test_duplex_commands.py
@@ -0,0 +1,453 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""OpenAI Realtime client events -> typed ``DuplexCommand`` objects and their mailbox payloads."""
+
+from __future__ import annotations
+
+import base64
+
+import numpy as np
+import pytest
+
+from vllm_omni.engine.duplex.commands import (
+    REALTIME_COMMAND_TYPES,
+    AckPlayback,
+    AppendAudio,
+    AppendText,
+    BargeIn,
+    CancelInput,
+    CancelResponse,
+    ClearInput,
+    ClearOutputAudio,
+    CloseSession,
+    Commit,
+    CreateItem,
+    CreateResponse,
+    DeleteItem,
+    DuplexCommand,
+    DuplexCommandError,
+    Heartbeat,
+    SignalTurn,
+    TruncateItem,
+    UpdateSession,
+    command_from_realtime,
+)
+from vllm_omni.engine.duplex.realtime_commands import (
+    RealtimeInputDefaults,
+    translate_realtime_command,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+_LOUD_PCM16 = base64.b64encode(b"\x00\x10" * 8).decode("ascii")
+_SILENT_PCM16 = base64.b64encode(b"\x00\x00" * 8).decode("ascii")
+_JPEG_FRAME = base64.b64encode(b"\xff\xd8\xff\xe0" + b"\x00" * 12).decode("ascii")
+
+_MINIMAL_PAYLOADS: dict[str, tuple[dict[str, object], type[DuplexCommand]]] = {
+    "input_audio_buffer.append": ({"audio": _LOUD_PCM16}, AppendAudio),
+    "input_audio_buffer.commit": ({}, Commit),
+    "input_audio_buffer.clear": ({}, ClearInput),
+    "output_audio_buffer.clear": ({}, ClearOutputAudio),
+    "response.create": ({}, CreateResponse),
+    "response.cancel": ({}, CancelResponse),
+    "conversation.item.create": ({"item": {"type": "message", "role": "user", "content": []}}, CreateItem),
+    "conversation.item.delete": ({"item_id": "item_1"}, DeleteItem),
+    "conversation.item.truncate": ({"item_id": "item_1", "audio_end_ms": 100}, TruncateItem),
+    "session.update": ({"session": {"instructions": "hi"}}, UpdateSession),
+    "playback.ack": ({"played_ms": 10}, AckPlayback),
+    "session.heartbeat": ({}, Heartbeat),
+    "session.close": ({}, CloseSession),
+    "turn.signal": ({"event": "user_started"}, SignalTurn),
+    "input.text.append": ({"text": "hello"}, AppendText),
+    "input.cancel": ({}, CancelInput),
+    "barge_in": ({}, BargeIn),
+}
+
+
+def test_every_realtime_command_type_has_a_mapping_case():
+    assert set(_MINIMAL_PAYLOADS) == set(REALTIME_COMMAND_TYPES)
+
+
+@pytest.mark.parametrize("event_type", sorted(REALTIME_COMMAND_TYPES))
+def test_command_from_realtime_maps_each_type_to_its_dataclass_and_propagates_event_id(event_type: str):
+    body, expected_cls = _MINIMAL_PAYLOADS[event_type]
+
+    command = command_from_realtime({"type": event_type, "event_id": f"evt-{event_type}", **body})
+
+    assert type(command) is expected_cls
+    assert command.event_id == f"evt-{event_type}"
+    payload = command.payload()
+    assert payload["type"] == expected_cls.type
+    assert payload["realtime_event_id"] == f"evt-{event_type}"
+    assert "event_id" not in payload
+
+    anonymous = command_from_realtime({"type": event_type, **body})
+    assert anonymous.event_id is None
+    assert "realtime_event_id" not in anonymous.payload()
+
+
+@pytest.mark.parametrize(
+    ("alias", "expected_cls", "body"),
+    [
+        ("push_text", AppendText, {"text": "hello"}),
+        ("input_text.append", AppendText, {"text": "hello"}),
+        ("signal_turn", SignalTurn, {"event": "user_started"}),
+        ("close_session", CloseSession, {}),
+        ("close", CloseSession, {}),
+        ("audio.playback_ack", AckPlayback, {"played_ms": 10}),
+        ("input.commit", Commit, {}),
+    ],
+)
+def test_pre_realtime_client_event_aliases_map_to_their_canonical_command(
+    alias: str, expected_cls: type[DuplexCommand], body: dict[str, object]
+):
+    assert type(command_from_realtime({"type": alias, **body})) is expected_cls
+
+
+def test_append_audio_decodes_and_converts_pcm16_to_16k_float32():
+    command = command_from_realtime(
+        {"type": "input_audio_buffer.append", "audio": _LOUD_PCM16, "format": "pcm16", "sample_rate_hz": 16000}
+    )
+
+    assert isinstance(command, AppendAudio)
+    assert command.format == "pcm_f32le"
+    assert command.sample_rate_hz == 16000
+    samples = np.frombuffer(command.audio, dtype="<f4")
+    assert samples.shape == (8,)
+    assert np.allclose(samples, 4096 / 32768.0)
+    assert command.is_speech is True
+    assert command.video_frames == ()
+    assert command.duration_ms is None
+    assert command.audio_end_ms is None
+
+
+def test_append_audio_defaults_come_from_the_session_payload():
+    defaults = RealtimeInputDefaults().with_session_payload({"input_audio_format": "pcm16", "sample_rate_hz": 8000})
+    assert defaults.input_audio_format == "pcm16"
+    assert defaults.input_sample_rate_hz == 8000
+
+    command = translate_realtime_command({"type": "input_audio_buffer.append", "audio": _LOUD_PCM16}, defaults=defaults)
+
+    assert isinstance(command, AppendAudio)
+    assert command.format == "pcm_f32le"
+    # 8 kHz input is resampled to the model's 16 kHz float stream.
+    assert command.sample_rate_hz == 16000
+    assert len(command.audio) > 8 * 4
+
+    passthrough = translate_realtime_command(
+        {"type": "input_audio_buffer.append", "audio": base64.b64encode(np.zeros(4, dtype="<f4").tobytes()).decode()},
+        defaults=RealtimeInputDefaults(input_audio_format="pcm_f32le", input_sample_rate_hz=16000),
+    )
+    assert passthrough.format == "pcm_f32le"
+    assert passthrough.audio == np.zeros(4, dtype="<f4").tobytes()
+
+
+def test_append_audio_speech_classification_uses_hints_then_rms():
+    silent = command_from_realtime({"type": "input_audio_buffer.append", "audio": _SILENT_PCM16})
+    assert silent.is_speech is False
+
+    forced = command_from_realtime({"type": "input_audio_buffer.append", "audio": _SILENT_PCM16, "is_speech": True})
+    assert forced.is_speech is True
+    assert forced.hints == {"is_speech": True}
+
+    vad = command_from_realtime(
+        {"type": "input_audio_buffer.append", "audio": _LOUD_PCM16, "vad": {"speech_probability": 0.1}}
+    )
+    assert vad.is_speech is False
+    assert vad.hints["vad"] == {"speech_probability": 0.1}
+
+
+def test_append_audio_carries_wire_hints_and_video_frames():
+    command = command_from_realtime(
+        {
+            "type": "input_audio_buffer.append",
+            "event_id": "evt-append",
+            "audio": _LOUD_PCM16,
+            "transcript": "hi there",
+            "duration_ms": 1000,
+            "audio_end_ms": 3000,
+            "video_frames": [_JPEG_FRAME],
+            "unknown_key": "dropped",
+        }
+    )
+
+    assert isinstance(command, AppendAudio)
+    assert command.duration_ms == 1000
+    assert command.audio_end_ms == 3000
+    assert command.video_frames == (_JPEG_FRAME,)
+    assert dict(command.hints) == {"transcript": "hi there", "duration_ms": 1000, "audio_end_ms": 3000}
+
+    payload = command.payload()
+    assert payload["type"] == "input_audio_buffer.append"
+    assert payload["realtime_event_id"] == "evt-append"
+    assert payload["audio"] == base64.b64encode(command.audio).decode("ascii")
+    assert payload["format"] == "pcm_f32le"
+    assert payload["sample_rate_hz"] == 16000
+    assert payload["is_speech"] is True
+    assert payload["transcript"] == "hi there"
+    assert payload["duration_ms"] == 1000
+    assert payload["audio_end_ms"] == 3000
+    assert payload["video_frames"] == [_JPEG_FRAME]
+    assert "hints" not in payload
+    assert "unknown_key" not in payload
+
+
+def test_append_audio_payload_re_encodes_bytes_and_flattens_hints():
+    command = AppendAudio(audio=b"\x01\x02", hints={"vad": {"is_speech": True}}, is_speech=True)
+
+    assert command.payload() == {
+        "type": "input_audio_buffer.append",
+        "audio": "AQI=",
+        "format": "pcm16",
+        "is_speech": True,
+        "vad": {"is_speech": True},
+    }
+
+
+@pytest.mark.parametrize(
+    ("body", "code"),
+    [
+        ({"audio": _LOUD_PCM16, "format": "mp3"}, "unsupported_audio_format"),
+        ({"audio": "@@@@", "format": "pcm_f32le"}, "bad_audio"),
+        ({"audio": _LOUD_PCM16, "video_frames": ["aGVsbG8="]}, "invalid_video_frames"),
+        ({"audio": _LOUD_PCM16, "video_frames": [_JPEG_FRAME], "max_slice_nums": 4}, "invalid_video_frames"),
+        ({"audio": _LOUD_PCM16, "format": "pcm16", "sample_rate_hz": 3}, "bad_event"),
+    ],
+)
+def test_malformed_append_raises_command_error_with_code(body: dict[str, object], code: str):
+    with pytest.raises(DuplexCommandError) as excinfo:
+        command_from_realtime({"type": "input_audio_buffer.append", "event_id": "evt-bad", **body})
+
+    assert excinfo.value.code == code
+    assert excinfo.value.event_id == "evt-bad"
+
+
+# ---- other malformed payloads ----
+
+
+@pytest.mark.parametrize(
+    ("payload", "code"),
+    [
+        ({}, "bad_event"),
+        ({"type": 7}, "bad_event"),
+        ({"type": "session.resume", "session_id": "s", "resume_token": "t"}, "unknown_event"),
+        ({"type": "session.event_ack", "server_event_seq": 1}, "unknown_event"),
+        ({"type": "conversation.item.frobnicate", "item_id": "item_1"}, "unknown_event"),
+        ({"type": "conversation.item.create"}, "bad_event"),
+        (
+            {
+                "type": "conversation.item.create",
+                "item": {"type": "message", "role": "user", "content": [{"type": "input_audio", "format": "mp3"}]},
+            },
+            "unsupported_audio_format",
+        ),
+        ({"type": "conversation.item.delete"}, "missing_item_id"),
+        ({"type": "conversation.item.truncate", "audio_end_ms": 1}, "missing_item_id"),
+        ({"type": "conversation.item.truncate", "item_id": "item_1"}, "bad_event"),
+        ({"type": "session.update", "session": {"output_audio_format": "opus"}}, "unsupported_audio_format"),
+        (
+            {"type": "session.update", "session": {"turn_detection": {"type": "semantic_vad"}}},
+            "unsupported_turn_detection",
+        ),
+        ({"type": "response.create", "response": {"output_audio_format": "opus"}}, "unsupported_audio_format"),
+        ({"type": "playback.ack"}, "bad_event"),
+        ({"type": "input.text.append"}, "bad_event"),
+        ({"type": "turn.signal"}, "bad_event"),
+        ({"type": "turn.signal", "event": "conversation.item.delete", "payload": {}}, "missing_item_id"),
+        ({"type": "turn.signal", "event": "conversation.item.truncate", "payload": {"item_id": "i"}}, "bad_event"),
+    ],
+)
+def test_malformed_payloads_raise_command_error_with_code(payload: dict[str, object], code: str):
+    with pytest.raises(DuplexCommandError) as excinfo:
+        command_from_realtime({"event_id": "evt-bad", **payload})
+
+    assert excinfo.value.code == code
+    assert excinfo.value.event_id == "evt-bad"
+
+
+# ---- payload() rendering ----
+
+
+def test_commit_maps_create_response_to_response_create():
+    command = command_from_realtime(
+        {"type": "input_audio_buffer.commit", "event_id": "evt-commit", "response_create": True, "final": False}
+    )
+
+    assert command == Commit(event_id="evt-commit", final=False, create_response=True)
+    assert command.payload() == {
+        "type": "input_audio_buffer.commit",
+        "realtime_event_id": "evt-commit",
+        "final": False,
+        "response_create": True,
+    }
+    assert Commit().payload() == {"type": "input_audio_buffer.commit", "final": True}
+    assert Commit(is_speech=False, realtime_item_id="item_1").payload() == {
+        "type": "input_audio_buffer.commit",
+        "final": True,
+        "is_speech": False,
+        "realtime_item_id": "item_1",
+    }
+    assert (
+        command_from_realtime({"type": "input_audio_buffer.commit", "create_response": False}).create_response is False
+    )
+
+
+def test_create_response_renders_options_as_response_object():
+    command = command_from_realtime({"type": "response.create", "response": {"modalities": ["text"]}})
+
+    assert isinstance(command, CreateResponse)
+    assert dict(command.options) == {"modalities": ["text"]}
+    assert command.payload() == {"type": "response.create", "response": {"modalities": ["text"]}}
+    assert command_from_realtime({"type": "response.create"}).payload() == {"type": "response.create", "response": {}}
+
+
+def test_cancel_and_clear_commands_keep_optional_response_id():
+    assert command_from_realtime({"type": "response.cancel", "response_id": ""}).response_id is None
+    cancel = command_from_realtime({"type": "response.cancel", "response_id": "resp_1"})
+    assert cancel == CancelResponse(response_id="resp_1")
+    assert cancel.payload() == {"type": "response.cancel", "response_id": "resp_1"}
+    clear = command_from_realtime({"type": "output_audio_buffer.clear", "response_id": "resp_2"})
+    assert clear == ClearOutputAudio(response_id="resp_2")
+    assert ClearInput().payload() == {"type": "input_audio_buffer.clear"}
+
+
+def test_update_session_renders_as_turn_signal_payload():
+    command = command_from_realtime(
+        {"type": "session.update", "session": {"instructions": "be brief", "voice": "alloy"}}
+    )
+
+    assert command == UpdateSession(patch={"instructions": "be brief", "voice": "alloy"})
+    assert command.payload() == {
+        "type": "turn.signal",
+        "event": "session.update",
+        "payload": {"instructions": "be brief", "voice": "alloy"},
+    }
+
+
+def test_create_item_normalizes_item_and_renders_as_turn_signal_payload():
+    command = command_from_realtime(
+        {
+            "type": "conversation.item.create",
+            "previous_item_id": "item_0",
+            "item": {"type": "message", "role": "assistant", "content": [{"type": "text", "text": "hi"}]},
+        }
+    )
+
+    assert isinstance(command, CreateItem)
+    assert command.previous_item_id == "item_0"
+    assert command.item["id"].startswith("item_")
+    assert command.item["object"] == "realtime.item"
+    assert command.item["status"] == "completed"
+    payload = command.payload()
+    assert payload["type"] == "turn.signal"
+    assert payload["event"] == "conversation.item.create"
+    assert payload["payload"] == {"item": dict(command.item), "previous_item_id": "item_0"}
+    assert "item" not in payload
+    assert "previous_item_id" not in payload
+
+    without_previous = command_from_realtime({"type": "conversation.item.create", "item": {"content": "x"}})
+    assert without_previous.item["role"] == "user"
+    assert without_previous.item["content"] == []
+    assert without_previous.payload()["payload"] == {"item": dict(without_previous.item)}
+
+
+def test_delete_and_truncate_render_as_turn_signal_payloads():
+    delete = command_from_realtime({"type": "conversation.item.delete", "item_id": "item_1"})
+    assert delete == DeleteItem(item_id="item_1")
+    assert delete.payload() == {
+        "type": "turn.signal",
+        "event": "conversation.item.delete",
+        "payload": {"item_id": "item_1"},
+    }
+
+    truncate = command_from_realtime(
+        {"type": "conversation.item.truncate", "item_id": "item_1", "audio_end_ms": 1500.0, "content_index": 1}
+    )
+    assert truncate == TruncateItem(item_id="item_1", audio_end_ms=1500, content_index=1)
+    assert truncate.payload() == {
+        "type": "turn.signal",
+        "event": "conversation.item.truncate",
+        "payload": {"item_id": "item_1", "audio_end_ms": 1500, "content_index": 1},
+    }
+
+
+def test_playback_ack_close_and_text_append_payloads():
+    ack = command_from_realtime(
+        {"type": "playback.ack", "played_ms": 1200.0, "committed_ms": 1000, "response_id": "resp_1", "item_id": ""}
+    )
+    assert ack == AckPlayback(played_ms=1200, committed_ms=1000, response_id="resp_1")
+    assert ack.payload() == {
+        "type": "playback.ack",
+        "played_ms": 1200,
+        "committed_ms": 1000,
+        "response_id": "resp_1",
+    }
+
+    assert command_from_realtime({"type": "session.close"}) == CloseSession(reason="client_close")
+    assert command_from_realtime({"type": "session.close", "reason": "done"}).payload() == {
+        "type": "session.close",
+        "reason": "done",
+    }
+    assert command_from_realtime({"type": "input.text.append", "text": "hello"}).payload() == {
+        "type": "input.text.append",
+        "text": "hello",
+    }
+    assert Heartbeat().payload() == {"type": "session.heartbeat"}
+
+
+def test_turn_signal_renders_payload_only_when_present_and_dispatches_known_events():
+    signal = command_from_realtime({"type": "turn.signal", "event": "user_started", "payload": {"source": "client"}})
+    assert signal == SignalTurn(event="user_started", signal_payload={"source": "client"})
+    assert signal.payload() == {"type": "turn.signal", "event": "user_started", "payload": {"source": "client"}}
+    assert command_from_realtime({"type": "turn.signal", "event": "user_started"}).payload() == {
+        "type": "turn.signal",
+        "event": "user_started",
+    }
+
+    assert command_from_realtime({"type": "turn.signal", "event": "barge_in"}) == BargeIn()
+    assert command_from_realtime({"type": "turn.signal", "event": "input.cancel"}) == CancelInput()
+    assert command_from_realtime(
+        {"type": "turn.signal", "event": "response.cancel", "payload": {"response_id": "resp_1"}}
+    ) == CancelResponse(response_id="resp_1")
+    assert command_from_realtime(
+        {"type": "turn.signal", "event": "session.update", "payload": {"voice": "alloy"}}
+    ) == UpdateSession(patch={"voice": "alloy"})
+    assert command_from_realtime(
+        {"type": "turn.signal", "event": "conversation.item.delete", "payload": {"item_id": "item_1"}}
+    ) == DeleteItem(item_id="item_1")
+    assert command_from_realtime(
+        {"type": "turn.signal", "event": "conversation.item.truncate", "payload": {"item_id": "i", "audio_end_ms": 5}}
+    ) == TruncateItem(item_id="i", audio_end_ms=5)
+    created = command_from_realtime(
+        {"type": "turn.signal", "event": "conversation.item.create", "payload": {"item": {"role": "system"}}}
+    )
+    assert isinstance(created, CreateItem)
+    assert created.item["role"] == "system"
+
+
+def test_raw_wire_hints_cannot_override_the_normalized_typed_fields():
+    """``build_append_audio`` normalizes; a client's raw value must not undo it.
+
+    A wire ``"is_speech": 0`` used to land in ``hints`` and overwrite the
+    computed ``bool | None`` in the rendered payload, so the runner's
+    silent-commit fast path (``event.get("is_speech") is False``) missed and
+    overlap classification followed the unvalidated value.
+    """
+    command = AppendAudio(
+        audio=b"\x00\x00" * 8,
+        is_speech=False,
+        hints={"is_speech": 0, "rms": 0.001},
+    )
+
+    payload = command.payload()
+
+    assert payload["is_speech"] is False, "the normalized field wins over the raw hint"
+    assert payload["rms"] == 0.001, "a hint with no typed counterpart still comes through"
+
+
+def test_a_hint_survives_when_its_typed_field_is_unset():
+    """Unset typed fields are absent from the payload, so the hint is the only value."""
+    command = AppendAudio(audio=b"\x00\x00" * 8, hints={"is_speech": True})
+
+    assert command.payload()["is_speech"] is True
diff --git a/tests/engine/duplex/test_duplex_control_client.py b/tests/engine/duplex/test_duplex_control_client.py
deleted file mode 100644
index 7974b14c943..00000000000
--- a/tests/engine/duplex/test_duplex_control_client.py
+++ /dev/null
@@ -1,110 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import pytest
-
-from vllm_omni.engine.duplex.control_client import (
-    DuplexControlClient,
-    DuplexControlRequestError,
-)
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity
-from vllm_omni.engine.duplex.messages import (
-    DuplexControlError,
-    DuplexControlResultMessage,
-    DuplexFence,
-    ResumeDuplexSessionMessage,
-    TouchDuplexSessionMessage,
-)
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-class _Transport:
-    def __init__(self) -> None:
-        self.calls = []
-
-    def execute(self, key, message, **kwargs):
-        self.calls.append((key, message, kwargs))
-        return DuplexControlResultMessage(
-            control_id=message.control_id,
-            fence=message.fence,
-            operation="touch" if isinstance(message, TouchDuplexSessionMessage) else "resume",
-            session_id=message.session_id,
-            ok=True,
-            stage_results=[],
-        )
-
-
-class _UnsupportedTransport:
-    def execute(self, key, message, **kwargs):
-        del key, kwargs
-        return DuplexControlResultMessage(
-            control_id=message.control_id,
-            fence=message.fence,
-            operation="touch",
-            session_id=message.session_id,
-            ok=False,
-            stage_results=[{"result": {"supported": False}}],
-            unsupported_count=1,
-            error=DuplexControlError(code="invalid_capability", message="unsupported", retryable=False),
-            accepted_fence=DuplexFence(message.session_id, epoch=2),
-            lease_generation=7,
-        )
-
-
-def test_control_client_routes_touch_and_resume_by_control_id() -> None:
-    transport = _Transport()
-    control_ids = iter(("touch-id", "resume-id"))
-    client = DuplexControlClient(transport, control_id_factory=lambda: next(control_ids))
-    fence = DuplexFence("sid-client")
-
-    assert (
-        client.touch(
-            fence.session_id,
-            fence=fence,
-            activity=DuplexLeaseActivity.PLAYBACK_ACK,
-            timeout=2.0,
-        )["ok"]
-        is True
-    )
-    assert (
-        client.resume(
-            fence.session_id,
-            fence=fence,
-            expected_lease_generation=7,
-            timeout=3.0,
-        )["ok"]
-        is True
-    )
-
-    touch_key, touch_message, touch_kwargs = transport.calls[0]
-    assert touch_key == ("duplex", "touch-id")
-    assert isinstance(touch_message, TouchDuplexSessionMessage)
-    assert touch_message.activity == DuplexLeaseActivity.PLAYBACK_ACK.value
-    assert touch_kwargs["timeout"] == 2.0
-
-    resume_key, resume_message, resume_kwargs = transport.calls[1]
-    assert resume_key == ("duplex", "resume-id")
-    assert isinstance(resume_message, ResumeDuplexSessionMessage)
-    assert resume_message.expected_lease_generation == 7
-    assert resume_kwargs["timeout"] == 3.0
-
-
-def test_control_client_treats_ok_false_as_authoritative_failure() -> None:
-    client = DuplexControlClient(_UnsupportedTransport(), control_id_factory=lambda: "unsupported")
-    fence = DuplexFence("sid-unsupported")
-
-    with pytest.raises(DuplexControlRequestError, match="duplex touch failed") as exc_info:
-        client.touch(
-            fence.session_id,
-            fence=fence,
-            activity=DuplexLeaseActivity.HEARTBEAT,
-            timeout=1.0,
-        )
-
-    assert exc_info.value.code == "invalid_capability"
-    assert exc_info.value.retryable is False
-    assert exc_info.value.accepted_fence == DuplexFence(fence.session_id, epoch=2)
-    assert exc_info.value.lease_generation == 7
diff --git a/tests/engine/duplex/test_duplex_control_plane.py b/tests/engine/duplex/test_duplex_control_plane.py
deleted file mode 100644
index 14da4d21c61..00000000000
--- a/tests/engine/duplex/test_duplex_control_plane.py
+++ /dev/null
@@ -1,1270 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from dataclasses import FrozenInstanceError
-
-import msgspec
-import pytest
-
-from vllm_omni.engine.duplex.control_plane import (
-    DuplexControlPlane,
-    DuplexOutputContext,
-    DuplexRequestIdentity,
-    DuplexStageRequestContext,
-    DuplexStageSubmission,
-    DuplexStageSubmissionResult,
-)
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity, DuplexLeaseConfig
-from vllm_omni.engine.duplex.messages import (
-    AppendDuplexInputMessage,
-    CloseDuplexSessionMessage,
-    DuplexFence,
-    DuplexSessionLifecycleMessage,
-    OpenDuplexSessionMessage,
-    ResumeDuplexSessionMessage,
-    SignalDuplexTurnMessage,
-    TouchDuplexSessionMessage,
-)
-from vllm_omni.engine.duplex.runtime import (
-    DuplexAppendPlan,
-    DuplexInputMode,
-    DuplexRuntimeCapabilities,
-)
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-class _Extension:
-    def configure_sampling_params(self, *, runtime_config, defaults):
-        del runtime_config
-        return tuple(f"configured-{stage_id}" for stage_id, _ in enumerate(defaults))
-
-    def plan_append(
-        self,
-        *,
-        request_id,
-        fence,
-        session_config,
-        runtime_config,
-        seq,
-        turn_seq,
-        mode,
-        payload,
-        final,
-        sampling_params,
-    ):
-        del request_id, fence, session_config, runtime_config, seq, turn_seq, mode, payload, final
-        assert sampling_params == "configured-0"
-        return DuplexAppendPlan(prompt={"prompt_token_ids": [1, 2, 3]})
-
-    def decide_output(self, **kwargs):
-        del kwargs
-        return None
-
-
-class _TypedStagePort:
-    stage_count = 2
-
-    def __init__(self) -> None:
-        self.ensure_calls: list[DuplexStageRequestContext] = []
-        self.submit_calls: list[DuplexStageSubmission] = []
-        self.cleanup_calls: list[tuple[list[str], bool]] = []
-
-    def sampling_defaults(self) -> tuple[object, ...]:
-        return ("default-0", "default-1")
-
-    def ensure_request(self, context: DuplexStageRequestContext) -> None:
-        self.ensure_calls.append(context)
-
-    async def submit(self, submission: DuplexStageSubmission) -> DuplexStageSubmissionResult:
-        self.submit_calls.append(submission)
-        return DuplexStageSubmissionResult(
-            request_id=submission.context.request_id,
-            stage_id=submission.context.stage_id,
-            replica_id=3,
-        )
-
-    async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-        self.cleanup_calls.append((request_ids, abort))
-
-
-class _Clock:
-    def __init__(self) -> None:
-        self.value = 0.0
-
-    def __call__(self) -> float:
-        return self.value
-
-    def advance(self, seconds: float) -> None:
-        self.value += seconds
-
-
-@pytest.mark.asyncio
-async def test_control_plane_uses_frozen_typed_stage_context_without_request_state() -> None:
-    stage_port = _TypedStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=_Extension(),
-        stage_port=stage_port,
-        result_sink=result_sink,
-    )
-    fence = DuplexFence("typed-port")
-
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open",
-            fence=fence,
-            session_id=fence.session_id,
-            capabilities={
-                "input_modes": [DuplexInputMode.APPEND_AUDIO_CHUNK.value],
-            },
-            session_config={"voice": "test"},
-            runtime_config={"runtime": "test"},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-
-    context = stage_port.ensure_calls[-1]
-    assert context.session_id == fence.session_id
-    assert context.fence == fence
-    assert context.stage_id == 0
-    assert context.final_stage_id == 1
-    assert context.sampling_params == ("configured-0", "configured-1")
-    assert context.session_config == {"voice": "test"}
-    assert context.runtime_config == {"runtime": "test"}
-    with pytest.raises(FrozenInstanceError):
-        context.stage_id = 1  # type: ignore[misc]
-
-    await plane.handle(
-        AppendDuplexInputMessage(
-            control_id="append",
-            fence=fence,
-            session_id=fence.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"audio": b"pcm"},
-            final=True,
-        )
-    )
-    append_result = await result_sink.get()
-    assert append_result.ok is True
-    assert append_result.stage_results[0]["replica_id"] == 3
-    assert append_result.stage_results[0]["result"]["response_stage_id"] == 1
-
-    submission = stage_port.submit_calls[-1]
-    assert submission.context == stage_port.ensure_calls[-1]
-    assert submission.prompt == {"prompt_token_ids": [1, 2, 3]}
-    assert submission.already_submitted is False
-    assert not hasattr(submission, "request_state")
-
-
-def test_control_plane_accepts_only_typed_duplex_messages() -> None:
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=_TypedStagePort(),
-        result_sink=asyncio.Queue(),
-    )
-
-    assert plane.accepts(
-        OpenDuplexSessionMessage(
-            control_id="open",
-            fence=DuplexFence("typed-message"),
-            session_id="typed-message",
-            capabilities=DuplexRuntimeCapabilities().__dict__,
-        )
-    )
-    assert plane.accepts(type("Lookalike", (), {"type": "open_duplex_session"})()) is False
-
-
-@pytest.mark.parametrize(
-    "message",
-    [
-        TouchDuplexSessionMessage(
-            control_id="touch-1",
-            fence=DuplexFence("sid-message"),
-            session_id="sid-message",
-            activity=DuplexLeaseActivity.HEARTBEAT.value,
-        ),
-        ResumeDuplexSessionMessage(
-            control_id="resume-1",
-            fence=DuplexFence("sid-message"),
-            session_id="sid-message",
-            expected_lease_generation=3,
-        ),
-        DuplexSessionLifecycleMessage(
-            fence=DuplexFence("sid-message"),
-            session_id="sid-message",
-            event="expired",
-            reason="idle_ttl_expired",
-            lease_generation=4,
-            submitted_request_ids=["req-submitted"],
-            reserved_request_ids=["req-reserved"],
-        ),
-    ],
-)
-def test_duplex_lease_messages_round_trip(message) -> None:
-    encoded = msgspec.json.encode(message)
-    decoded = msgspec.json.decode(encoded, type=type(message))
-
-    assert decoded == message
-
-
-@pytest.mark.asyncio
-async def test_control_plane_touches_append_signal_and_explicit_activity() -> None:
-    clock = _Clock()
-    stage_port = _TypedStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    lifecycle_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=_Extension(),
-        stage_port=stage_port,
-        result_sink=result_sink,
-        lifecycle_sink=lifecycle_sink,
-        lease_config=DuplexLeaseConfig(idle_ttl_s=30.0, disconnect_grace_s=5.0),
-        clock=clock,
-    )
-    fence = DuplexFence("sid-touch")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open",
-            fence=fence,
-            session_id=fence.session_id,
-            capabilities={"input_modes": [DuplexInputMode.APPEND_AUDIO_CHUNK.value]},
-        )
-    )
-    await result_sink.get()
-    session = plane.sessions.require(fence.session_id)
-
-    clock.advance(1.0)
-    await plane.handle(
-        AppendDuplexInputMessage(
-            control_id="append",
-            fence=fence,
-            session_id=fence.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"audio": b"pcm"},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    assert session.lease.last_activity == 1.0
-
-    clock.advance(1.0)
-    await plane.handle(
-        SignalDuplexTurnMessage(
-            control_id="signal",
-            fence=fence,
-            session_id=fence.session_id,
-            event="session.update",
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    assert session.lease.last_activity == 2.0
-
-    submit_count = len(stage_port.submit_calls)
-    clock.advance(1.0)
-    await plane.handle(
-        TouchDuplexSessionMessage(
-            control_id="heartbeat",
-            fence=fence,
-            session_id=fence.session_id,
-            activity=DuplexLeaseActivity.HEARTBEAT.value,
-        )
-    )
-    touch_result = await result_sink.get()
-    assert touch_result.ok is True
-    assert session.lease.last_activity == 3.0
-    assert len(stage_port.submit_calls) == submit_count
-    assert lifecycle_sink.empty()
-
-
-@pytest.mark.asyncio
-async def test_control_plane_resume_requires_expected_lease_generation() -> None:
-    clock = _Clock()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=_TypedStagePort(),
-        result_sink=result_sink,
-        lifecycle_sink=asyncio.Queue(),
-        lease_config=DuplexLeaseConfig(),
-        clock=clock,
-    )
-    fence = DuplexFence("sid-resume-control")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open",
-            fence=fence,
-            session_id=fence.session_id,
-            capabilities={},
-        )
-    )
-    await result_sink.get()
-    await plane.handle(
-        TouchDuplexSessionMessage(
-            control_id="detach",
-            fence=fence,
-            session_id=fence.session_id,
-            activity=DuplexLeaseActivity.DETACH.value,
-        )
-    )
-    await result_sink.get()
-
-    await plane.handle(
-        ResumeDuplexSessionMessage(
-            control_id="resume",
-            fence=fence,
-            session_id=fence.session_id,
-            expected_lease_generation=0,
-        )
-    )
-    result = await result_sink.get()
-
-    assert result.ok is True
-    assert result.stage_results[0]["result"]["lease_generation"] == 1
-
-    await plane.handle(
-        ResumeDuplexSessionMessage(
-            control_id="stale-resume",
-            fence=fence,
-            session_id=fence.session_id,
-            expected_lease_generation=0,
-        )
-    )
-    stale_result = await result_sink.get()
-    assert stale_result.ok is False
-    assert stale_result.accepted_fence == fence
-    assert stale_result.lease_generation == 1
-
-
-@pytest.mark.asyncio
-async def test_control_plane_reaps_one_session_through_cleanup_and_lifecycle_sink() -> None:
-    clock = _Clock()
-    stage_port = _TypedStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    lifecycle_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=stage_port,
-        result_sink=result_sink,
-        lifecycle_sink=lifecycle_sink,
-        lease_config=DuplexLeaseConfig(idle_ttl_s=2.0, disconnect_grace_s=1.0),
-        clock=clock,
-    )
-    for session_id in ("sid-a", "sid-b"):
-        fence = DuplexFence(session_id)
-        await plane.handle(
-            OpenDuplexSessionMessage(
-                control_id=f"open-{session_id}",
-                fence=fence,
-                session_id=session_id,
-                capabilities={},
-            )
-        )
-        await result_sink.get()
-    clock.advance(1.0)
-    plane.sessions.require("sid-b").touch(DuplexFence("sid-b"), DuplexLeaseActivity.HEARTBEAT)
-    clock.advance(1.1)
-
-    expired_count = await plane.reap_expired()
-
-    assert expired_count == 1
-    assert plane.sessions.get("sid-a") is None
-    assert plane.sessions.get("sid-b") is not None
-    assert stage_port.cleanup_calls == []
-    lifecycle = await lifecycle_sink.get()
-    assert isinstance(lifecycle, DuplexSessionLifecycleMessage)
-    assert lifecycle.session_id == "sid-a"
-    assert lifecycle.reason == "idle_ttl_expired"
-    assert result_sink.empty()
-
-
-@pytest.mark.asyncio
-async def test_control_plane_retries_expired_cleanup_before_publishing_lifecycle() -> None:
-    class _FailOnceStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.failures_remaining = 1
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            if self.failures_remaining:
-                self.failures_remaining -= 1
-                raise RuntimeError("transient cleanup failure")
-            await super().cleanup(request_ids, abort=abort)
-
-    clock = _Clock()
-    stage_port = _FailOnceStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    lifecycle_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=stage_port,
-        result_sink=result_sink,
-        lifecycle_sink=lifecycle_sink,
-        lease_config=DuplexLeaseConfig(idle_ttl_s=1.0, disconnect_grace_s=1.0),
-        clock=clock,
-    )
-    fence = DuplexFence("sid-retry-expiry")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-retry",
-            fence=fence,
-            session_id=fence.session_id,
-            capabilities={},
-        )
-    )
-    await result_sink.get()
-    request_id = plane.stage_request_id(fence, stage_id=0)
-    plane.sessions.require(fence.session_id).reserve_stage_request(0, request_id, fence=fence)
-    clock.advance(2.0)
-
-    assert await plane.reap_expired() == 0
-    assert lifecycle_sink.empty()
-
-    assert await plane.reap_expired() == 1
-    assert (await lifecycle_sink.get()).session_id == fence.session_id
-
-
-@pytest.mark.asyncio
-async def test_expired_session_holds_admission_slot_while_cleanup_is_blocked() -> None:
-    class _BlockedCleanupStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.cleanup_started = asyncio.Event()
-            self.release_cleanup = asyncio.Event()
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            self.cleanup_started.set()
-            await self.release_cleanup.wait()
-            await super().cleanup(request_ids, abort=abort)
-
-    clock = _Clock()
-    stage_port = _BlockedCleanupStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=stage_port,
-        result_sink=result_sink,
-        lease_config=DuplexLeaseConfig(idle_ttl_s=1.0, disconnect_grace_s=1.0),
-        clock=clock,
-        max_sessions=1,
-    )
-    old_fence = DuplexFence("sid-expired-blocked")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-expired-blocked",
-            fence=old_fence,
-            session_id=old_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    old_session = plane.sessions.require(old_fence.session_id)
-    old_session.bind_stage_request(0, "req-expired-blocked", fence=old_fence)
-    clock.advance(2.0)
-
-    reap_task = asyncio.create_task(plane.reap_expired())
-    await asyncio.wait_for(stage_port.cleanup_started.wait(), timeout=1.0)
-    replacement_fence = DuplexFence("sid-replacement-blocked")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-replacement-blocked",
-            fence=replacement_fence,
-            session_id=replacement_fence.session_id,
-            capabilities={},
-        )
-    )
-
-    blocked_result = await result_sink.get()
-    assert blocked_result.ok is False
-    assert blocked_result.error is not None
-    assert blocked_result.error.code == "resource_exhausted"
-    assert plane.sessions.get(old_fence.session_id) is old_session
-
-    stage_port.release_cleanup.set()
-    assert await reap_task == 1
-    assert plane.sessions.get(old_fence.session_id) is None
-
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-replacement-after-cleanup",
-            fence=replacement_fence,
-            session_id=replacement_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-
-
-@pytest.mark.asyncio
-async def test_failed_expiry_cleanup_retains_admission_slot_for_retry() -> None:
-    class _FailingCleanupStagePort(_TypedStagePort):
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            del request_ids, abort
-            raise RuntimeError("cleanup failed")
-
-    clock = _Clock()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=_FailingCleanupStagePort(),
-        result_sink=result_sink,
-        lease_config=DuplexLeaseConfig(idle_ttl_s=1.0, disconnect_grace_s=1.0),
-        clock=clock,
-        max_sessions=1,
-    )
-    old_fence = DuplexFence("sid-expired-failed")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-expired-failed",
-            fence=old_fence,
-            session_id=old_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    old_session = plane.sessions.require(old_fence.session_id)
-    old_session.bind_stage_request(0, "req-expired-failed", fence=old_fence)
-    clock.advance(2.0)
-
-    assert await plane.reap_expired() == 0
-    replacement_fence = DuplexFence("sid-replacement-failed")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-replacement-failed",
-            fence=replacement_fence,
-            session_id=replacement_fence.session_id,
-            capabilities={},
-        )
-    )
-
-    blocked_result = await result_sink.get()
-    assert blocked_result.ok is False
-    assert blocked_result.error is not None
-    assert blocked_result.error.code == "resource_exhausted"
-    assert plane.sessions.get(old_fence.session_id) is old_session
-
-
-@pytest.mark.asyncio
-async def test_capacity_rejection_is_an_info_event(caplog: pytest.LogCaptureFixture) -> None:
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=_TypedStagePort(),
-        result_sink=result_sink,
-        max_sessions=1,
-    )
-    first_fence = DuplexFence("sid-capacity-first")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-capacity-first",
-            fence=first_fence,
-            session_id=first_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    caplog.clear()
-
-    rejected_fence = DuplexFence("sid-capacity-rejected")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-capacity-rejected",
-            fence=rejected_fence,
-            session_id=rejected_fence.session_id,
-            capabilities={},
-        )
-    )
-
-    result = await result_sink.get()
-    assert result.error.code == "resource_exhausted"
-    assert not [record for record in caplog.records if record.levelno >= logging.ERROR]
-
-
-@pytest.mark.asyncio
-async def test_failed_request_cleanup_retries_before_releasing_admission() -> None:
-    class _FailOnceCleanupStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.attempts = 0
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            self.cleanup_calls.append((list(request_ids), abort))
-            self.attempts += 1
-            if self.attempts == 1:
-                raise RuntimeError("transient request cleanup failure")
-
-    stage_port = _FailOnceCleanupStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=stage_port,
-        result_sink=result_sink,
-        max_sessions=1,
-    )
-    old_fence = DuplexFence("sid-request-cleanup")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-request-cleanup",
-            fence=old_fence,
-            session_id=old_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    old_session = plane.sessions.require(old_fence.session_id)
-    old_session.bind_stage_request(0, "req-request-cleanup", fence=old_fence)
-
-    closed = plane.close_sessions_for_request_ids(
-        ["req-request-cleanup"],
-        abort=True,
-    )
-    assert closed == {old_fence.session_id: ["req-request-cleanup"]}
-    assert plane.sessions.get(old_fence.session_id) is old_session
-    with pytest.raises(RuntimeError, match="transient request cleanup failure"):
-        await stage_port.cleanup(closed[old_fence.session_id], abort=True)
-
-    replacement_fence = DuplexFence("sid-request-cleanup-replacement")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-request-cleanup-replacement-blocked",
-            fence=replacement_fence,
-            session_id=replacement_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).error.code == "resource_exhausted"
-
-    assert await plane.reap_expired() == 1
-    assert plane.sessions.get(old_fence.session_id) is None
-    assert stage_port.cleanup_calls == [
-        (["req-request-cleanup"], True),
-        (["req-request-cleanup"], True),
-    ]
-
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-request-cleanup-replacement",
-            fence=replacement_fence,
-            session_id=replacement_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-
-
-@pytest.mark.asyncio
-async def test_stale_request_cleanup_does_not_finalize_reopened_incarnation() -> None:
-    stage_port = _TypedStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=stage_port,
-        result_sink=result_sink,
-        max_sessions=1,
-    )
-    old_fence = DuplexFence("sid-request-cleanup-reopen")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-request-cleanup-old",
-            fence=old_fence,
-            session_id=old_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    old_session = plane.sessions.require(old_fence.session_id)
-    old_session.bind_stage_request(0, "req-request-cleanup-old", fence=old_fence)
-    closed = plane.close_sessions_for_request_ids(
-        ["req-request-cleanup-old"],
-        abort=True,
-        cleanup_in_progress=True,
-    )
-    assert closed == {old_fence.session_id: ["req-request-cleanup-old"]}
-    plane.defer_request_cleanups([old_fence.session_id])
-
-    await plane.handle(
-        CloseDuplexSessionMessage(
-            control_id="close-request-cleanup-old",
-            fence=old_fence,
-            session_id=old_fence.session_id,
-            reason="client_close",
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    assert plane.sessions.get(old_fence.session_id) is None
-
-    new_fence = DuplexFence(old_fence.session_id, incarnation=1)
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-request-cleanup-new",
-            fence=new_fence,
-            session_id=new_fence.session_id,
-            capabilities={},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-    new_session = plane.sessions.require(new_fence.session_id)
-    assert new_session.resume(new_fence, expected_lease_generation=0) == 1
-
-    assert await plane.reap_expired() == 1
-    assert plane.sessions.get(new_fence.session_id) is new_session
-
-
-@pytest.mark.asyncio
-async def test_failed_open_cleanup_is_retried_before_releasing_admission() -> None:
-    class _FailOpenAndFirstCleanupStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.ensure_attempts = 0
-            self.cleanup_attempts = 0
-
-        def ensure_request(self, context: DuplexStageRequestContext) -> None:
-            self.ensure_attempts += 1
-            if self.ensure_attempts == 1:
-                raise RuntimeError("initial stage setup failed")
-            super().ensure_request(context)
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            self.cleanup_calls.append((list(request_ids), abort))
-            self.cleanup_attempts += 1
-            if self.cleanup_attempts == 1:
-                raise RuntimeError("transient open rollback failure")
-
-    stage_port = _FailOpenAndFirstCleanupStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=_Extension(),
-        stage_port=stage_port,
-        result_sink=result_sink,
-        max_sessions=1,
-    )
-    failed_fence = DuplexFence("sid-open-rollback")
-
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-fails-during-stage-setup",
-            fence=failed_fence,
-            session_id=failed_fence.session_id,
-            capabilities={"input_modes": ["append_audio_chunk"]},
-        )
-    )
-
-    failed_result = await result_sink.get()
-    assert failed_result.ok is False
-    assert plane.sessions.get(failed_fence.session_id) is not None
-
-    replacement_fence = DuplexFence("sid-open-rollback-replacement")
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-replacement-before-rollback",
-            fence=replacement_fence,
-            session_id=replacement_fence.session_id,
-            capabilities={"input_modes": ["append_audio_chunk"]},
-        )
-    )
-    assert (await result_sink.get()).error.code == "resource_exhausted"
-
-    assert await plane.reap_expired() == 0
-    assert plane.sessions.get(failed_fence.session_id) is None
-
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-replacement-after-rollback",
-            fence=replacement_fence,
-            session_id=replacement_fence.session_id,
-            capabilities={"input_modes": ["append_audio_chunk"]},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-
-
-@pytest.mark.asyncio
-async def test_expired_cleanup_failure_does_not_block_other_sessions() -> None:
-    class _OneStuckExpiryStagePort(_TypedStagePort):
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            if request_ids == [stuck_request_id]:
-                raise RuntimeError("stuck expiry cleanup")
-            await super().cleanup(request_ids, abort=abort)
-
-    clock = _Clock()
-    stage_port = _OneStuckExpiryStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    lifecycle_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(
-        extension=None,
-        stage_port=stage_port,
-        result_sink=result_sink,
-        lifecycle_sink=lifecycle_sink,
-        lease_config=DuplexLeaseConfig(idle_ttl_s=1.0, disconnect_grace_s=1.0),
-        clock=clock,
-    )
-    stuck_fence = DuplexFence("sid-expiry-stuck")
-    ready_fence = DuplexFence("sid-expiry-ready")
-    stuck_request_id = plane.stage_request_id(stuck_fence, stage_id=0)
-    ready_request_id = plane.stage_request_id(ready_fence, stage_id=0)
-    for fence in (stuck_fence, ready_fence):
-        await plane.handle(
-            OpenDuplexSessionMessage(
-                control_id=f"open-{fence.session_id}",
-                fence=fence,
-                session_id=fence.session_id,
-                capabilities={},
-            )
-        )
-        assert (await result_sink.get()).ok is True
-        plane.sessions.require(fence.session_id).reserve_stage_request(
-            0,
-            plane.stage_request_id(fence, stage_id=0),
-            fence=fence,
-        )
-    clock.advance(2.0)
-
-    assert await plane.reap_expired() == 1
-
-    assert (await lifecycle_sink.get()).session_id == ready_fence.session_id
-    assert stage_port.cleanup_calls == [([ready_request_id], False)]
-
-
-@pytest.mark.asyncio
-async def test_cancel_retains_request_resources_until_abort_succeeds() -> None:
-    class _FailOnceStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.failures_remaining = 1
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            if self.failures_remaining:
-                self.failures_remaining -= 1
-                raise RuntimeError("transient abort failure")
-            await super().cleanup(request_ids, abort=abort)
-
-    stage_port = _FailOnceStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=None, stage_port=stage_port, result_sink=result_sink)
-    cancelled_fence = DuplexFence("sid-cancel-retry")
-    next_fence = DuplexFence("sid-cancel-retry", epoch=1)
-    session = plane.sessions.open_session(cancelled_fence)
-    session.bind_stage_request(0, "req-cancel-retry", fence=cancelled_fence)
-
-    def signal(control_id: str) -> SignalDuplexTurnMessage:
-        return SignalDuplexTurnMessage(
-            control_id=control_id,
-            fence=cancelled_fence,
-            next_fence=next_fence,
-            session_id=cancelled_fence.session_id,
-            event="input.cancel",
-        )
-
-    await plane.handle(signal("cancel-first"))
-    assert (await result_sink.get()).ok is False
-    assert session.fence == next_fence
-    assert session.resource_request_ids(cancelled_fence) == ["req-cancel-retry"]
-
-    await plane.handle(signal("cancel-retry"))
-    assert (await result_sink.get()).ok is True
-    assert session.resource_request_ids(cancelled_fence) == []
-    assert stage_port.cleanup_calls == [(["req-cancel-retry"], True)]
-
-
-@pytest.mark.asyncio
-async def test_close_retains_session_resources_until_cleanup_succeeds() -> None:
-    class _FailOnceStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.failures_remaining = 1
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            if self.failures_remaining:
-                self.failures_remaining -= 1
-                raise RuntimeError("transient close cleanup failure")
-            await super().cleanup(request_ids, abort=abort)
-
-    stage_port = _FailOnceStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=None, stage_port=stage_port, result_sink=result_sink)
-    fence = DuplexFence("sid-close-retry")
-    session = plane.sessions.open_session(fence)
-    session.bind_stage_request(0, "req-close-retry", fence=fence)
-
-    def close(control_id: str) -> CloseDuplexSessionMessage:
-        return CloseDuplexSessionMessage(
-            control_id=control_id,
-            fence=fence,
-            session_id=fence.session_id,
-            reason="client_close",
-        )
-
-    await plane.handle(close("close-first"))
-    assert (await result_sink.get()).ok is False
-    assert plane.sessions.get(fence.session_id) is session
-    assert session.resource_request_ids() == ["req-close-retry"]
-
-    await plane.handle(close("close-retry"))
-    assert (await result_sink.get()).ok is True
-    assert plane.sessions.get(fence.session_id) is None
-    assert stage_port.cleanup_calls == [(["req-close-retry"], True)]
-
-
-@pytest.mark.asyncio
-async def test_control_cleanup_failure_does_not_block_other_sessions() -> None:
-    class _IndependentFailureStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.attempts: dict[str, int] = {}
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            request_id = request_ids[0]
-            self.attempts[request_id] = self.attempts.get(request_id, 0) + 1
-            if request_id == "req-stuck" or self.attempts[request_id] == 1:
-                raise RuntimeError(f"cleanup failed for {request_id}")
-            await super().cleanup(request_ids, abort=abort)
-
-    stage_port = _IndependentFailureStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=None, stage_port=stage_port, result_sink=result_sink)
-
-    for session_id, request_id in (("sid-stuck", "req-stuck"), ("sid-ready", "req-ready")):
-        fence = DuplexFence(session_id)
-        session = plane.sessions.open_session(fence)
-        session.bind_stage_request(0, request_id, fence=fence)
-        await plane.handle(
-            CloseDuplexSessionMessage(
-                control_id=f"close-{session_id}",
-                fence=fence,
-                session_id=session_id,
-                reason="client_close",
-            )
-        )
-        assert (await result_sink.get()).ok is False
-
-    await plane.reap_expired()
-
-    assert plane.sessions.get("sid-stuck") is not None
-    assert plane.sessions.get("sid-ready") is None
-    assert stage_port.cleanup_calls == [(["req-ready"], True)]
-
-
-@pytest.mark.asyncio
-async def test_control_cleanup_is_single_flight_with_concurrent_reaper() -> None:
-    class _SlowCleanupStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.cleanup_started = asyncio.Event()
-            self.release_cleanup = asyncio.Event()
-            self.cleanup_attempts = 0
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            self.cleanup_attempts += 1
-            self.cleanup_started.set()
-            await self.release_cleanup.wait()
-            await super().cleanup(request_ids, abort=abort)
-
-    stage_port = _SlowCleanupStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=None, stage_port=stage_port, result_sink=result_sink)
-    fence = DuplexFence("sid-concurrent-cleanup")
-    session = plane.sessions.open_session(fence)
-    session.bind_stage_request(0, "req-concurrent-cleanup", fence=fence)
-
-    close_task = asyncio.create_task(
-        plane.handle(
-            CloseDuplexSessionMessage(
-                control_id="close-concurrent-cleanup",
-                fence=fence,
-                session_id=fence.session_id,
-                reason="client_close",
-            )
-        )
-    )
-    await asyncio.wait_for(stage_port.cleanup_started.wait(), timeout=1)
-
-    reaper_task = asyncio.create_task(plane.reap_expired())
-    await asyncio.sleep(0)
-    await asyncio.sleep(0)
-    assert stage_port.cleanup_attempts == 1
-
-    stage_port.release_cleanup.set()
-    await asyncio.gather(close_task, reaper_task)
-
-    assert (await result_sink.get()).ok is True
-    assert plane.sessions.get(fence.session_id) is None
-    assert stage_port.cleanup_calls == [(["req-concurrent-cleanup"], True)]
-
-
-@pytest.mark.asyncio
-async def test_unknown_input_mode_rejects_open_without_registering_session() -> None:
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=None, stage_port=_TypedStagePort(), result_sink=result_sink)
-    fence = DuplexFence("sid-unknown-mode")
-
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-unknown-mode",
-            fence=fence,
-            session_id=fence.session_id,
-            capabilities={"input_modes": ["future_mode"]},
-        )
-    )
-
-    result = await result_sink.get()
-    assert result.ok is False
-    assert result.error is not None
-    assert result.error.code == "invalid_capability"
-    assert plane.sessions.get(fence.session_id) is None
-
-
-@pytest.mark.asyncio
-async def test_extension_free_turn_commit_does_not_allocate_or_submit_stage_request() -> None:
-    stage_port = _TypedStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=None, stage_port=stage_port, result_sink=result_sink)
-    fence = DuplexFence("sid-turn-commit")
-
-    await plane.handle(
-        OpenDuplexSessionMessage(
-            control_id="open-turn-commit",
-            fence=fence,
-            session_id=fence.session_id,
-            capabilities={"input_modes": [DuplexInputMode.TURN_COMMIT_ONLY.value]},
-        )
-    )
-    assert (await result_sink.get()).ok is True
-
-    await plane.handle(
-        AppendDuplexInputMessage(
-            control_id="append-turn-commit",
-            fence=fence,
-            session_id=fence.session_id,
-            mode=DuplexInputMode.TURN_COMMIT_ONLY.value,
-            payload=None,
-            final=True,
-        )
-    )
-    result = await result_sink.get()
-
-    assert result.ok is True
-    assert result.stage_results[0]["result"]["data_plane_append"] is False
-    assert stage_port.ensure_calls == []
-    assert stage_port.submit_calls == []
-
-
-@pytest.mark.asyncio
-async def test_session_update_replaces_both_configs_with_one_generation() -> None:
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=_Extension(), stage_port=_TypedStagePort(), result_sink=result_sink)
-    fence = DuplexFence("sid-atomic-config")
-    session = plane.sessions.open_session(fence)
-
-    await plane.handle(
-        SignalDuplexTurnMessage(
-            control_id="update-config",
-            fence=fence,
-            session_id=fence.session_id,
-            event="session.update",
-            session_config={"voice": "new"},
-            runtime_config={"temperature": 0.5},
-        )
-    )
-
-    assert (await result_sink.get()).ok is True
-    assert session.config_generation == 1
-    assert session.session_config == {"voice": "new"}
-    assert session.runtime_config == {"temperature": 0.5}
-
-
-@pytest.mark.asyncio
-async def test_stage_submission_is_compensated_when_local_commit_fails() -> None:
-    stage_port = _TypedStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=_Extension(), stage_port=stage_port, result_sink=result_sink)
-    fence = DuplexFence("sid-submit-compensation")
-    session = plane.sessions.open_session(
-        fence,
-        capabilities=DuplexRuntimeCapabilities(input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK}),
-    )
-    request_id = plane.stage_request_id(fence, stage_id=0)
-
-    def fail_commit(_reservation):
-        raise RuntimeError("local commit failed")
-
-    session.commit_append = fail_commit  # type: ignore[method-assign]
-    await plane.handle(
-        AppendDuplexInputMessage(
-            control_id="append-compensation",
-            fence=fence,
-            session_id=fence.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"audio": b"pcm"},
-        )
-    )
-
-    assert (await result_sink.get()).ok is False
-    assert stage_port.cleanup_calls == [([request_id], True)]
-
-
-@pytest.mark.asyncio
-async def test_failed_submission_compensation_blocks_append_until_reaper_cleans_it() -> None:
-    class _FailingCleanupStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.cleanup_failures = 2
-
-        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-            await super().cleanup(request_ids, abort=abort)
-            if self.cleanup_failures > 0:
-                self.cleanup_failures -= 1
-                raise RuntimeError("stage abort failed")
-
-    stage_port = _FailingCleanupStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=_Extension(), stage_port=stage_port, result_sink=result_sink)
-    fence = DuplexFence("sid-durable-submit-compensation")
-    session = plane.sessions.open_session(
-        fence,
-        capabilities=DuplexRuntimeCapabilities(input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK}),
-    )
-    original_commit = session.commit_append
-
-    def fail_commit(_reservation):
-        raise RuntimeError("local commit failed")
-
-    session.commit_append = fail_commit  # type: ignore[method-assign]
-    first = AppendDuplexInputMessage(
-        control_id="append-compensation-1",
-        fence=fence,
-        session_id=fence.session_id,
-        mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-        payload={"audio": b"pcm"},
-    )
-    await plane.handle(first)
-    assert (await result_sink.get()).ok is False
-    assert plane.pending_submission_cleanup_count == 1
-    assert len(stage_port.submit_calls) == 1
-
-    await plane.handle(
-        AppendDuplexInputMessage(
-            control_id="append-compensation-2",
-            fence=fence,
-            session_id=fence.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"audio": b"pcm"},
-        )
-    )
-    assert (await result_sink.get()).ok is False
-    assert plane.pending_submission_cleanup_count == 1
-    assert len(stage_port.submit_calls) == 1
-
-    session.commit_append = original_commit  # type: ignore[method-assign]
-    stage_port.cleanup_failures = 0
-    await plane.reap_expired()
-
-    assert plane.pending_submission_cleanup_count == 0
-    assert session.resource_request_ids() == []
-
-
-def test_stale_output_is_rejected_before_extension_decision() -> None:
-    class _CountingExtension(_Extension):
-        def __init__(self) -> None:
-            self.decision_calls = 0
-
-        def decide_output(self, **kwargs):
-            del kwargs
-            self.decision_calls += 1
-            return None
-
-    extension = _CountingExtension()
-    plane = DuplexControlPlane(extension=extension, stage_port=_TypedStagePort(), result_sink=asyncio.Queue())
-    current = DuplexFence("sid-stale-output", epoch=1)
-    plane.sessions.open_session(current)
-    context = DuplexOutputContext(
-        identity=DuplexRequestIdentity(
-            session_id=current.session_id,
-            fence=DuplexFence(current.session_id, epoch=0),
-        ),
-        final_stage_id=1,
-        segment_finished=True,
-    )
-
-    assert plane.decide_output(0, object(), context) is None
-    assert extension.decision_calls == 0
-
-
-@pytest.mark.asyncio
-async def test_control_dispatch_is_ordered_per_session_without_blocking_other_sessions() -> None:
-    class _BlockingStagePort(_TypedStagePort):
-        def __init__(self) -> None:
-            super().__init__()
-            self.started = asyncio.Event()
-            self.release = asyncio.Event()
-
-        async def submit(self, submission: DuplexStageSubmission) -> DuplexStageSubmissionResult:
-            if submission.context.session_id == "sid-blocked":
-                self.started.set()
-                await self.release.wait()
-            return await super().submit(submission)
-
-    stage_port = _BlockingStagePort()
-    result_sink: asyncio.Queue = asyncio.Queue()
-    plane = DuplexControlPlane(extension=_Extension(), stage_port=stage_port, result_sink=result_sink)
-    blocked = DuplexFence("sid-blocked")
-    independent = DuplexFence("sid-independent")
-    capabilities = DuplexRuntimeCapabilities(input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK})
-    plane.sessions.open_session(blocked, capabilities=capabilities)
-    plane.sessions.open_session(independent, capabilities=capabilities)
-
-    plane.dispatch(
-        AppendDuplexInputMessage(
-            control_id="blocked-append",
-            fence=blocked,
-            session_id=blocked.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"audio": b"pcm"},
-            operation_id="blocked-operation",
-        )
-    )
-    await asyncio.wait_for(stage_port.started.wait(), timeout=1)
-    plane.dispatch(
-        AppendDuplexInputMessage(
-            control_id="blocked-append-retry",
-            fence=blocked,
-            session_id=blocked.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"audio": b"pcm"},
-            operation_id="blocked-operation",
-        )
-    )
-    plane.dispatch(
-        TouchDuplexSessionMessage(
-            control_id="blocked-touch",
-            fence=blocked,
-            session_id=blocked.session_id,
-            activity=DuplexLeaseActivity.HEARTBEAT.value,
-        )
-    )
-    plane.dispatch(
-        TouchDuplexSessionMessage(
-            control_id="independent-touch",
-            fence=independent,
-            session_id=independent.session_id,
-            activity=DuplexLeaseActivity.HEARTBEAT.value,
-        )
-    )
-
-    independent_result = await asyncio.wait_for(result_sink.get(), timeout=1)
-    assert independent_result.control_id == "independent-touch"
-
-    stage_port.release.set()
-    await plane.drain()
-    assert [result_sink.get_nowait().control_id for _ in range(3)] == [
-        "blocked-append",
-        "blocked-append-retry",
-        "blocked-touch",
-    ]
-    assert [
-        submission.context.session_id
-        for submission in stage_port.submit_calls
-        if submission.context.session_id == blocked.session_id
-    ] == [blocked.session_id]
diff --git a/tests/engine/duplex/test_duplex_events.py b/tests/engine/duplex/test_duplex_events.py
new file mode 100644
index 00000000000..a4ebfbf5a3d
--- /dev/null
+++ b/tests/engine/duplex/test_duplex_events.py
@@ -0,0 +1,386 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Typed duplex events: pure ``to_realtime()`` rendering and the stateful Realtime projection."""
+
+from __future__ import annotations
+
+import base64
+import inspect
+
+import pytest
+
+from vllm_omni.engine.duplex import events as events_module
+from vllm_omni.engine.duplex.events import (
+    REALTIME_ERROR_TYPES_BY_CODE,
+    AudioDelta,
+    DuplexEvent,
+    DuplexRawEvent,
+    ErrorEvent,
+    InputCommitted,
+    ItemAdded,
+    ItemCreated,
+    ItemDone,
+    Listen,
+    OutputItemAdded,
+    OverlapDecision,
+    ResponseDone,
+    SessionClosed,
+    SessionCreated,
+    SessionExpired,
+    SessionHeartbeatAck,
+    SessionReplaced,
+    SessionResumed,
+    SessionResyncRequired,
+    TextDelta,
+    TranscriptDone,
+    TurnEvent,
+    error_event,
+)
+from vllm_omni.engine.duplex.realtime_events import (
+    RealtimeProjectionState,
+    project_internal_event,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+#: Classes whose wire object carries ``session_id`` by contract.
+_SESSION_ID_ON_WIRE = {
+    SessionClosed,
+    SessionExpired,
+    SessionHeartbeatAck,
+    Listen,
+    TurnEvent,
+    OverlapDecision,
+    SessionResumed,
+    SessionReplaced,
+    SessionResyncRequired,
+}
+#: Classes whose wire object carries ``epoch`` by contract.
+_EPOCH_ON_WIRE = {Listen, TurnEvent, OverlapDecision}
+
+
+def _public_event_classes() -> list[type[DuplexEvent]]:
+    classes = [
+        getattr(events_module, name)
+        for name in events_module.__all__
+        if inspect.isclass(getattr(events_module, name)) and issubclass(getattr(events_module, name), DuplexEvent)
+    ]
+    assert len(classes) > 40
+    return [cls for cls in classes if cls is not DuplexEvent]
+
+
+@pytest.mark.parametrize("event_cls", _public_event_classes(), ids=lambda cls: cls.__name__)
+def test_to_realtime_renders_wire_type_event_id_and_documented_fields(event_cls: type[DuplexEvent]):
+    event = event_cls(session_id="duplex-hidden", epoch=7)
+
+    wire = event.to_realtime()
+
+    assert wire["type"] == event.type
+    assert wire["event_id"] == event.event_id
+    assert wire["event_id"].startswith("event_")
+    if event_cls is DuplexRawEvent:
+        assert wire["type"] == "duplex."
+    else:
+        assert wire["type"] == event_cls.wire_type
+    if event_cls in _SESSION_ID_ON_WIRE:
+        assert wire["session_id"] == "duplex-hidden"
+    else:
+        assert "session_id" not in wire
+    if event_cls in _EPOCH_ON_WIRE:
+        assert wire["epoch"] == 7
+    else:
+        assert "epoch" not in wire
+    # Every value is plain JSON (mappings / sequences are copied into dict / list).
+    for value in wire.values():
+        assert isinstance(value, str | int | float | bool | dict | list) or value is None
+
+
+def test_optional_wire_fields_are_omitted_when_none():
+    created = SessionCreated(session={"id": "sid"})
+    assert created.optional_wire_fields == frozenset({"attachment_generation", "resume_token"})
+    wire = created.to_realtime()
+    assert "attachment_generation" not in wire
+    assert "resume_token" not in wire
+    assert wire["session"] == {"id": "sid"}
+
+    with_resume = SessionCreated(session={"id": "sid"}, attachment_generation=2, resume_token="tok").to_realtime()
+    assert with_resume["attachment_generation"] == 2
+    assert with_resume["resume_token"] == "tok"
+
+    delta = AudioDelta(response_id="resp_1", item_id="item_resp_1", delta="AAAA").to_realtime()
+    assert "sample_rate_hz" not in delta
+    assert "metadata" not in delta
+    assert delta["format"] == "pcm16"
+    assert delta["output_index"] == 0
+    assert delta["content_index"] == 0
+
+    anonymous_listen = Listen(session_id="sid", epoch=0, details={"reason": "silence"}).to_realtime()
+    assert "response_id" not in anonymous_listen
+    assert "id" not in anonymous_listen["response"]
+    assert anonymous_listen["response"]["status"] == "listening"
+    assert anonymous_listen["response"]["metadata"] == {"reason": "silence"}
+
+    bound_listen = Listen(session_id="sid", epoch=0, response_id="resp_1").to_realtime()
+    assert bound_listen["response_id"] == "resp_1"
+    assert bound_listen["response"]["id"] == "resp_1"
+
+
+def test_error_event_maps_codes_to_openai_error_types_and_echoes_client_event_id():
+    assert REALTIME_ERROR_TYPES_BY_CODE["resource_exhausted"] == "rate_limit_error"
+    assert REALTIME_ERROR_TYPES_BY_CODE["internal_error"] == "server_error"
+    assert REALTIME_ERROR_TYPES_BY_CODE["bad_event"] == "invalid_request_error"
+
+    error = ErrorEvent(
+        code="resource_exhausted",
+        message="too many sessions",
+        related_event_id="evt_client",
+        param="session",
+        extra={"retryable": True},
+    )
+
+    assert error.error_type == "rate_limit_error"
+    assert error.text == "too many sessions"
+    assert error.error == {
+        "type": "rate_limit_error",
+        "code": "resource_exhausted",
+        "message": "too many sessions",
+        "event_id": "evt_client",
+        "param": "session",
+        "retryable": True,
+    }
+    wire = error.to_realtime()
+    assert wire["type"] == "error"
+    assert wire["error"] == error.error
+    # The server event id and the echoed client event id are distinct.
+    assert wire["event_id"] != "evt_client"
+    assert ErrorEvent(code="never-seen-code").error_type == "invalid_request_error"
+
+
+def test_error_event_helper_normalizes_optional_client_event_id_and_param():
+    event = error_event("bad_event", "nope", event_id="evt_1", param="item", extra={"retryable": False})
+    assert isinstance(event, ErrorEvent)
+    assert event.related_event_id == "evt_1"
+    assert event.param == "item"
+    assert event.error["retryable"] is False
+
+    anonymous = error_event("bad_event", "nope", event_id=42, param="")
+    assert anonymous.related_event_id is None
+    assert anonymous.param is None
+    assert "event_id" not in anonymous.error
+    assert "param" not in anonymous.error
+
+
+def test_audio_delta_decodes_base64_and_invalid_payloads_yield_none():
+    raw = bytes(range(16))
+    delta = AudioDelta(delta=base64.b64encode(raw).decode("ascii"), format="pcm16", sample_rate_hz=24000)
+
+    assert delta.audio == raw
+    assert delta.to_realtime()["sample_rate_hz"] == 24000
+    assert AudioDelta(delta="@@not base64@@").audio is None
+
+
+def test_session_closed_and_expired_are_the_only_terminal_events():
+    closed = SessionClosed(session_id="sid", reason="client_close", details={"type": "session.closed"})
+    expired = SessionExpired(session_id="sid", reason="idle_timeout")
+
+    assert closed.is_terminal is True
+    assert expired.is_terminal is True
+    assert closed.to_realtime() == {
+        "type": "session.closed",
+        "event_id": closed.event_id,
+        "session_id": "sid",
+        "reason": "client_close",
+        "event": {"type": "session.closed"},
+    }
+    assert expired.to_realtime() == {
+        "type": "session.expired",
+        "event_id": expired.event_id,
+        "session_id": "sid",
+        "reason": "idle_timeout",
+    }
+    non_terminal = [cls for cls in _public_event_classes() if cls().is_terminal]
+    assert non_terminal == [SessionClosed, SessionExpired]
+
+
+def test_generic_accessors_expose_response_item_text_and_status():
+    assert TextDelta(response_id="resp_1", item_id="item_resp_1", delta="hi").text == "hi"
+    assert TranscriptDone(transcript="done").text == "done"
+    assert OutputItemAdded(item={"id": "item_1"}).item_id == "item_1"
+    assert ItemAdded(item={"id": 3}).item_id is None
+    assert ResponseDone(response={"status": "cancelled"}).status == "cancelled"
+    assert ResponseDone().status is None
+    assert TurnEvent(event="user_started", turn_state="user_speaking").response_id is None
+    assert TurnEvent().audio is None
+
+
+def test_raw_event_prefixes_internal_type_and_wraps_details():
+    raw = DuplexRawEvent(internal_type="model.custom", details={"type": "model.custom", "value": (1, 2)})
+
+    assert raw.type == "duplex.model.custom"
+    assert raw.to_realtime() == {
+        "type": "duplex.model.custom",
+        "event_id": raw.event_id,
+        "event": {"type": "model.custom", "value": [1, 2]},
+    }
+
+
+def test_turn_event_and_overlap_decision_carry_session_identity_on_the_wire():
+    turn = TurnEvent(session_id="sid", epoch=2, event="barge_in", turn_state="barge_in").to_realtime()
+    assert turn == {
+        "type": "turn.event",
+        "event_id": turn["event_id"],
+        "session_id": "sid",
+        "event": "barge_in",
+        "turn_state": "barge_in",
+        "epoch": 2,
+    }
+    decision = OverlapDecision(
+        session_id="sid", epoch=2, policy="listen_only", action="ignore", reason="short", details={"ms": 300}
+    ).to_realtime()
+    assert decision["policy"] == "listen_only"
+    assert decision["action"] == "ignore"
+    assert decision["metadata"] == {"ms": 300}
+    assert decision["session_id"] == "sid"
+
+
+# ---- RealtimeProjectionState / project_internal_event ----
+
+
+def _types(events: list[DuplexEvent]) -> list[str]:
+    return [event.type for event in events]
+
+
+def test_projection_of_the_main_internal_event_sequence():
+    state = RealtimeProjectionState(session_id="duplex-proj", model="test-model", initial_session_update=True)
+    pcm = base64.b64encode(b"\x00\x10" * 8).decode("ascii")
+
+    created = project_internal_event(state, {"type": "session.created", "session": {"voice": "alloy"}})
+    assert _types(created) == ["session.created", "session.updated"]
+    assert isinstance(created[0], SessionCreated)
+    session_payload = created[0].session
+    assert session_payload["id"] == "duplex-proj"
+    assert session_payload["model"] == "test-model"
+    assert session_payload["voice"] == "alloy"
+    assert session_payload["input_audio_format"] == "pcm16"
+    assert session_payload["output_audio_format"] == "pcm16"
+    assert state.initial_session_update is False
+    # The extra session.updated is a one-shot for the opening session.update.
+    assert _types(project_internal_event(state, {"type": "session.created", "session": {}})) == ["session.created"]
+
+    response_created = project_internal_event(
+        state, {"type": "response.created", "response_id": "resp_1", "modalities": ["audio", "text"]}
+    )
+    assert _types(response_created) == [
+        "response.created",
+        "conversation.item.added",
+        "conversation.item.created",
+        "response.output_item.added",
+        "response.content_part.added",
+    ]
+    assert state.active_response_id == "resp_1"
+    assert response_created[0].response_id == "resp_1"
+    assert response_created[0].to_realtime()["response"]["status"] == "in_progress"
+    assert isinstance(response_created[1], ItemAdded)
+    assert isinstance(response_created[2], ItemCreated)
+    assert response_created[1].item_id == "item_resp_1"
+    assert response_created[3].item_id == "item_resp_1"
+    assert response_created[4].to_realtime()["part"] == {"type": "audio", "transcript": ""}
+
+    audio_delta = project_internal_event(
+        state,
+        {"type": "response.output_audio.delta", "response_id": "resp_1", "audio": pcm, "text": "hi", "format": "pcm16"},
+    )
+    assert _types(audio_delta) == ["response.output_audio.delta", "response.output_audio_transcript.delta"]
+    assert isinstance(audio_delta[0], AudioDelta)
+    assert audio_delta[0].delta == pcm
+    assert audio_delta[0].format == "pcm16"
+    assert audio_delta[0].item_id == "item_resp_1"
+    assert audio_delta[1].text == "hi"
+    assert state.conversation_items["item_resp_1"]["content"][0]["transcript"] == "hi"
+
+    done = project_internal_event(state, {"type": "response.done", "response_id": "resp_1"})
+    assert _types(done) == [
+        "response.output_audio.done",
+        "response.output_audio_transcript.done",
+        "response.content_part.done",
+        "response.output_item.done",
+        "conversation.item.done",
+        "response.done",
+        "rate_limits.updated",
+    ]
+    assert done[1].text == "hi"
+    assert isinstance(done[4], ItemDone)
+    assert done[4].item["status"] == "completed"
+    assert isinstance(done[5], ResponseDone)
+    assert done[5].status == "completed"
+    assert done[5].response["output"][0]["content"][0] == {"type": "output_audio", "transcript": "hi"}
+    assert state.active_response_id is None
+    # A duplicate terminal for the same response is idempotent.
+    assert project_internal_event(state, {"type": "response.done", "response_id": "resp_1"}) == []
+
+    committed = project_internal_event(
+        state, {"type": "input.committed", "message": {"role": "user", "content": "hello"}, "input_commit_seq": 1}
+    )
+    assert _types(committed) == [
+        "conversation.item.added",
+        "conversation.item.created",
+        "input_audio_buffer.committed",
+        "conversation.item.done",
+    ]
+    assert isinstance(committed[2], InputCommitted)
+    assert committed[2].previous_item_id == "item_resp_1"
+    assert committed[2].item_id == committed[0].item_id
+    assert committed[2].to_realtime()["event"]["input_commit_seq"] == 1
+    assert committed[0].item["content"] == [{"type": "input_text", "text": "hello"}]
+
+    project_internal_event(state, {"type": "response.created", "response_id": "resp_2"})
+    project_internal_event(state, {"type": "response.output_audio.delta", "response_id": "resp_2", "audio": pcm})
+    cancelled = project_internal_event(
+        state, {"type": "audio.cancelled", "response_id": "resp_2", "reason": "barge_in", "committed_ms": 0}
+    )
+    assert _types(cancelled) == [
+        "response.output_audio.done",
+        "response.content_part.done",
+        "response.output_item.done",
+        "conversation.item.done",
+        "response.done",
+        "rate_limits.updated",
+    ]
+    assert cancelled[4].status == "cancelled"
+    assert cancelled[4].response["status_details"] == {"type": "cancelled", "reason": "barge_in"}
+    assert state.active_response_id is None
+
+    closed = project_internal_event(state, {"type": "session.closed", "reason": "client_close"})
+    assert _types(closed) == ["session.closed"]
+    assert closed[0].is_terminal is True
+    assert closed[0].to_realtime()["reason"] == "client_close"
+
+
+def test_projection_of_output_audio_buffer_clear_emits_cleared_before_terminals():
+    state = RealtimeProjectionState(session_id="duplex-clear")
+    pcm = base64.b64encode(b"\x00\x10" * 8).decode("ascii")
+    project_internal_event(state, {"type": "response.created", "response_id": "resp_1"})
+    project_internal_event(state, {"type": "response.output_audio.delta", "response_id": "resp_1", "audio": pcm})
+
+    cleared = project_internal_event(
+        state, {"type": "audio.cancelled", "reason": "output_audio_buffer_clear", "committed_ms": 250}
+    )
+
+    assert _types(cleared)[:2] == ["output_audio_buffer.cleared", "response.output_audio.done"]
+    assert cleared[0].response_id == "resp_1"
+    assert _types(cleared)[-2:] == ["response.done", "rate_limits.updated"]
+    assert state.item_truncation_cursors["item_resp_1"] == (0, 250)
+
+
+def test_projection_leaves_error_to_typed_emit_sites():
+    # Errors are constructed typed (``error_event``) at the emit site; the projector
+    # has no ``error`` branch and falls back to the raw wrapper for such a dict.
+    state = RealtimeProjectionState(session_id="duplex-err")
+
+    projected = project_internal_event(state, {"type": "error", "code": "bad_event", "error": "nope"})
+
+    assert len(projected) == 1
+    assert isinstance(projected[0], DuplexRawEvent)
+    assert projected[0].type == "duplex.error"
+    assert projected[0].to_realtime()["event"]["code"] == "bad_event"
diff --git a/tests/engine/duplex/test_duplex_lease.py b/tests/engine/duplex/test_duplex_lease.py
index 62fc8c70c66..bd26b57402a 100644
--- a/tests/engine/duplex/test_duplex_lease.py
+++ b/tests/engine/duplex/test_duplex_lease.py
@@ -1,19 +1,22 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
+"""Lease semantics of the engine-resident duplex session (idle TTL, disconnect grace, resume CAS)."""
+
 from __future__ import annotations
 
 from dataclasses import FrozenInstanceError
 
 import pytest
 
-from vllm_omni.engine.duplex.lease import (
+from vllm_omni.engine.duplex.config import DuplexSessionConfig
+from vllm_omni.engine.duplex.contracts import DuplexFence
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession, DuplexFenceMismatchError
+from vllm_omni.engine.duplex.session.lease import (
     DuplexLeaseActivity,
     DuplexLeaseConfig,
+    DuplexLeaseState,
 )
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.runtime import DuplexInputMode
-from vllm_omni.engine.duplex.session import DuplexSessionRuntimeManager
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
@@ -30,195 +33,148 @@ def advance(self, seconds: float) -> None:
 
 
 def _lease_config(*, idle_ttl_s: float | None = 300.0) -> DuplexLeaseConfig:
-    return DuplexLeaseConfig(
-        idle_ttl_s=idle_ttl_s,
-        disconnect_grace_s=30.0,
+    return DuplexLeaseConfig(idle_ttl_s=idle_ttl_s, disconnect_grace_s=30.0)
+
+
+def _session(session_id: str, clock: FakeMonotonicClock, *, idle_ttl_s: float | None = 300.0) -> DuplexEngineSession:
+    return DuplexEngineSession(
+        session_id=session_id,
+        config=DuplexSessionConfig(),
+        lease=DuplexLeaseState(config=_lease_config(idle_ttl_s=idle_ttl_s), generation=0, last_activity=clock()),
+        _clock=clock,
     )
 
 
-def test_open_touch_detach_and_idle_expiry_use_monotonic_time() -> None:
+def test_open_touch_detach_and_expiry_use_monotonic_time() -> None:
     clock = FakeMonotonicClock(100.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    fence = DuplexFence("sid-expiry")
-    session = manager.open_session(fence, lease_config=_lease_config())
+    session = _session("sid-expiry", clock)
 
     assert session.lease.last_activity == 100.0
     clock.advance(10.0)
-    session.touch(fence, DuplexLeaseActivity.HEARTBEAT)
-    session.detach(fence)
+    session.touch_lease(DuplexLeaseActivity.HEARTBEAT)
+    assert session.lease.last_activity == 110.0
+    session.detach_lease()
     clock.advance(29.0)
     assert session.lease.disconnect_grace_expired(clock()) is False
-    assert manager.collect_expired() == []
+    assert session.lease.idle_expired(clock()) is False
 
-    clock.advance(272.0)
-    expired = manager.collect_expired()
+    clock.advance(1.0)
+    assert session.lease.disconnect_grace_expired(clock()) is True
 
-    assert [item.session_id for item in expired] == ["sid-expiry"]
-    assert expired[0].reason == "disconnect_grace_expired"
-    assert manager.get("sid-expiry") is session
-    manager.finalize_close_session(session)
-    assert manager.get("sid-expiry") is None
+    clock.advance(271.0)
+    assert session.lease.idle_expired(clock()) is True
 
 
-def test_detach_grace_and_resume_advance_token_independent_lease_generation() -> None:
+def test_detach_grace_and_resume_advance_the_lease_generation() -> None:
     clock = FakeMonotonicClock(10.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    fence = DuplexFence("sid-resume")
-    session = manager.open_session(fence, lease_config=_lease_config())
+    session = _session("sid-resume", clock)
 
-    session.detach(fence)
+    session.detach_lease()
     clock.advance(29.0)
     assert session.lease.disconnect_grace_expired(clock()) is False
     clock.advance(2.0)
     assert session.lease.disconnect_grace_expired(clock()) is True
 
-    generation = session.resume(fence, expected_lease_generation=0)
+    generation = session.resume_lease(expected_lease_generation=0)
 
     assert generation == 1
+    assert session.lease_generation == 1
     assert session.lease.detached_at is None
     assert session.lease.disconnect_grace_expired(clock()) is False
     with pytest.raises(ValueError, match="lease generation mismatch"):
-        session.resume(fence, expected_lease_generation=0)
+        session.resume_lease(expected_lease_generation=0)
 
 
 def test_active_operation_prevents_mid_transaction_expiry() -> None:
     clock = FakeMonotonicClock(0.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    fence = DuplexFence("sid-operation")
-    session = manager.open_session(fence, lease_config=_lease_config(idle_ttl_s=5.0))
+    session = _session("sid-operation", clock, idle_ttl_s=5.0)
 
-    session.begin_operation(fence, "append-1")
+    session.begin_lease_operation(session.fence, "append-1")
     clock.advance(10.0)
-    assert manager.collect_expired() == []
+    assert session.lease.idle_expired(clock()) is False
 
-    session.end_operation(fence, "append-1")
-    assert manager.collect_expired() == []
+    session.end_lease_operation("append-1")
+    assert session.lease.idle_expired(clock()) is False
     clock.advance(6.0)
-    assert [item.session_id for item in manager.collect_expired()] == ["sid-operation"]
+    assert session.lease.idle_expired(clock()) is True
 
 
 def test_sessions_have_independent_activity_deadlines_and_resources() -> None:
     clock = FakeMonotonicClock(0.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    fence_a = DuplexFence("sid-a")
-    fence_b = DuplexFence("sid-b")
-    session_a = manager.open_session(fence_a, lease_config=_lease_config(idle_ttl_s=10.0))
-    session_b = manager.open_session(fence_b, lease_config=_lease_config(idle_ttl_s=10.0))
-    session_a.reserve_stage_request(0, "req-a-reserved", fence=fence_a)
-    session_a.bind_stage_request(1, "req-a-submitted", fence=fence_a)
-    session_b.bind_stage_request(0, "req-b", fence=fence_b)
+    session_a = _session("sid-a", clock, idle_ttl_s=10.0)
+    session_b = _session("sid-b", clock, idle_ttl_s=10.0)
+    session_a.reserve_stage_request(0, "req-a-reserved", fence=session_a.fence)
+    session_a.bind_stage_request(1, "req-a-submitted", fence=session_a.fence)
+    session_b.bind_stage_request(0, "req-b", fence=session_b.fence)
 
     clock.advance(6.0)
-    session_b.touch(fence_b, DuplexLeaseActivity.MODEL_OUTPUT)
+    session_b.touch_lease(DuplexLeaseActivity.MODEL_OUTPUT)
     clock.advance(5.0)
-    expired = manager.collect_expired()
 
-    assert len(expired) == 1
-    assert expired[0].session_id == "sid-a"
-    assert expired[0].reserved_request_ids == ("req-a-reserved",)
-    assert expired[0].submitted_request_ids == ("req-a-submitted",)
-    assert manager.get("sid-b") is session_b
+    assert session_a.lease.idle_expired(clock()) is True
+    assert session_b.lease.idle_expired(clock()) is False
+    assert session_a.resource_request_ids(submitted=False) == ["req-a-reserved"]
+    assert session_a.resource_request_ids(submitted=True) == ["req-a-submitted"]
     assert session_b.resource_request_ids() == ["req-b"]
 
 
-def test_close_and_reaper_select_exactly_one_terminal_transition() -> None:
+def test_close_is_a_single_terminal_transition() -> None:
     clock = FakeMonotonicClock(0.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    fence = DuplexFence("sid-race")
-    manager.open_session(fence, lease_config=_lease_config(idle_ttl_s=1.0))
+    session = _session("sid-race", clock, idle_ttl_s=1.0)
     clock.advance(2.0)
+    assert session.lease.idle_expired(clock()) is True
 
-    assert len(manager.collect_expired()) == 1
-    assert manager.close_session(fence, reason="explicit_close") is None
-    assert manager.collect_expired() == []
-
-    fence_2 = DuplexFence("sid-race-2")
-    manager.open_session(fence_2, lease_config=_lease_config(idle_ttl_s=1.0))
-    assert manager.close_session(fence_2, reason="explicit_close") is not None
-    clock.advance(2.0)
-    assert manager.collect_expired() == []
+    assert session.begin_close(reason="explicit_close") is True
+    assert session.lease.terminal_reason == "explicit_close"
+    # A terminal lease is never reaped again and a second close is a no-op.
+    assert session.lease.idle_expired(clock()) is False
+    assert session.lease.disconnect_grace_expired(clock()) is False
+    assert session.begin_close(reason="idle_ttl_expired") is True
+    assert session.lease.terminal_reason == "explicit_close"
+    with pytest.raises(RuntimeError, match="terminal"):
+        session.touch_lease(DuplexLeaseActivity.HEARTBEAT)
 
 
-def test_stale_fence_cannot_touch_detach_or_resume_lease() -> None:
+def test_stale_fence_cannot_start_a_lease_operation() -> None:
     clock = FakeMonotonicClock(0.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    current = DuplexFence("sid-fence", epoch=1)
+    session = _session("sid-fence", clock)
+    session.epoch = 1
+    session.sync_fence()
     stale = DuplexFence("sid-fence", epoch=0)
-    session = manager.open_session(current, lease_config=_lease_config())
 
-    with pytest.raises(RuntimeError, match="fence mismatch"):
-        session.touch(stale, DuplexLeaseActivity.APPEND)
-    with pytest.raises(RuntimeError, match="fence mismatch"):
-        session.detach(stale)
-    with pytest.raises(RuntimeError, match="fence mismatch"):
-        session.resume(stale, expected_lease_generation=0)
+    with pytest.raises(DuplexFenceMismatchError, match="fence mismatch"):
+        session.begin_lease_operation(stale, "append-1")
+    with pytest.raises(DuplexFenceMismatchError, match="fence mismatch"):
+        session.begin_lease_operation(DuplexFence("other-session", epoch=1), "append-2")
 
 
-def test_disabled_idle_expiry_never_collects_session() -> None:
+def test_disabled_idle_expiry_never_expires_session() -> None:
     clock = FakeMonotonicClock(0.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    manager.open_session(DuplexFence("sid-no-expiry"), lease_config=_lease_config(idle_ttl_s=None))
+    session = _session("sid-no-expiry", clock, idle_ttl_s=None)
 
     clock.advance(1_000_000.0)
 
-    assert manager.collect_expired() == []
+    assert session.lease.expires_at is None
+    assert session.lease.idle_expired(clock()) is False
 
 
 def test_detached_session_expires_at_disconnect_grace_when_idle_ttl_is_disabled() -> None:
     clock = FakeMonotonicClock(0.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    fence = DuplexFence("sid-disconnect-grace")
-    session = manager.open_session(fence, lease_config=_lease_config(idle_ttl_s=None))
+    session = _session("sid-disconnect-grace", clock, idle_ttl_s=None)
 
-    session.detach(fence)
+    session.detach_lease()
     clock.advance(29.0)
-    assert manager.collect_expired() == []
+    assert session.lease.disconnect_grace_expired(clock()) is False
 
     clock.advance(1.0)
-    expired = manager.collect_expired()
-
-    assert [item.session_id for item in expired] == [fence.session_id]
-    assert expired[0].reason == "disconnect_grace_expired"
-
-
-def test_runtime_manager_enforces_server_owned_session_admission() -> None:
-    manager = DuplexSessionRuntimeManager(max_sessions=2)
-    manager.open_session(DuplexFence("sid-admission-a"))
-    manager.open_session(DuplexFence("sid-admission-b"))
-
-    with pytest.raises(RuntimeError, match="duplex_session_capacity_exhausted"):
-        manager.open_session(DuplexFence("sid-admission-c"))
-
-
-def test_completed_append_cache_is_bounded() -> None:
-    manager = DuplexSessionRuntimeManager(completed_append_limit=2)
-    fence = DuplexFence("sid-completed-cache")
-    session = manager.open_session(fence)
-
-    for index in range(3):
-        session.record_completed_append(
-            f"operation-{index}",
-            fence=fence,
-            mode=DuplexInputMode.TURN_COMMIT_ONLY,
-            final=True,
-            stage_results=[{"index": index}],
-        )
-
-    assert list(session.completed_appends) == ["operation-1", "operation-2"]
-
-    session.accept_fence(DuplexFence(fence.session_id, epoch=1))
-    assert session.completed_appends == {}
+    assert session.lease.disconnect_grace_expired(clock()) is True
 
 
-def test_lease_config_and_expiry_record_are_immutable() -> None:
+def test_lease_config_is_immutable_and_validated() -> None:
     config = _lease_config()
     with pytest.raises(FrozenInstanceError):
         config.idle_ttl_s = 1.0  # type: ignore[misc]
-
-    clock = FakeMonotonicClock(0.0)
-    manager = DuplexSessionRuntimeManager(clock=clock)
-    manager.open_session(DuplexFence("sid-record"), lease_config=_lease_config(idle_ttl_s=1.0))
-    clock.advance(2.0)
-    record = manager.collect_expired()[0]
-    with pytest.raises(FrozenInstanceError):
-        record.reason = "changed"  # type: ignore[misc]
+    with pytest.raises(ValueError, match="idle_ttl_s"):
+        DuplexLeaseConfig(idle_ttl_s=0.0)
+    with pytest.raises(ValueError, match="disconnect_grace_s"):
+        DuplexLeaseConfig(disconnect_grace_s=0.0)
diff --git a/tests/engine/duplex/test_duplex_plugin.py b/tests/engine/duplex/test_duplex_plugin.py
new file mode 100644
index 00000000000..f45b625e792
--- /dev/null
+++ b/tests/engine/duplex/test_duplex_plugin.py
@@ -0,0 +1,324 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""``DuplexModelPlugin`` loading/validation helpers and the ``PipelineConfig.duplex_plugin`` binding."""
+
+from __future__ import annotations
+
+from dataclasses import fields
+from pathlib import Path
+from typing import Any
+
+import pytest
+from vllm.sampling_params import SamplingParams
+
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig, PipelineConfig
+from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig
+from vllm_omni.engine.duplex.contracts import DuplexAppendPlan
+from vllm_omni.engine.duplex.plugin import (
+    DuplexDataPlane,
+    DuplexModelPlugin,
+    DuplexModelSessionState,
+    DuplexRuntimeConfigError,
+    coerce_int,
+    load_duplex_plugin,
+    payload_turn_id,
+    reject_changed_runtime_value,
+    validate_duplex_plugin_sampling,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def _encode_audio(audio: object, sample_rate_hz: int, fmt: str, speed: float | None) -> str | None:
+    del audio, sample_rate_hz, fmt, speed
+    return None
+
+
+class FakeDataPlane(DuplexDataPlane):
+    def begin_request(self, request_id: str) -> None:
+        pass
+
+    def is_terminal(self, request_id: str | None) -> bool:
+        return False
+
+    def mark_terminal(self, request_id: str) -> None:
+        pass
+
+    def close_stream(self, request_id: str) -> None:
+        pass
+
+    def close_session(self, session_id: str, *, active_request_id: str | None = None) -> None:
+        pass
+
+    def project(self, result, *, context=None):
+        del result, context
+        return []
+
+
+class FakePlugin(DuplexModelPlugin):
+    """Minimal plugin; referenced by dotted path from ``load_duplex_plugin`` tests."""
+
+    plugin_id = "fake-duplex"
+
+    def __init__(self, encode_audio) -> None:
+        super().__init__(encode_audio)
+        self.data_plane = FakeDataPlane()
+
+    def configure_sampling_params(self, *, runtime_config, defaults):
+        del runtime_config
+        return tuple(defaults)
+
+    def plan_append(self, **kwargs) -> DuplexAppendPlan:
+        del kwargs
+        return DuplexAppendPlan(prompt={"prompt_token_ids": [1]})
+
+    def decide_output(self, **kwargs):
+        del kwargs
+        return None
+
+    def create_session_state(self) -> DuplexModelSessionState:
+        raise NotImplementedError
+
+    def capabilities(self, *, max_sessions: int) -> DuplexCapabilities:
+        del max_sessions
+        return DuplexCapabilities()
+
+    def validate_client_extra_body(self, extra_body: object) -> None:
+        pass
+
+    async def prepare_runtime_config(self, config: DuplexSessionConfig, *, model_config: Any) -> dict[str, object]:
+        del config, model_config
+        return {}
+
+    def runtime_config_for_update(self, config, current):
+        del config
+        return dict(current)
+
+    def data_plane_context(self, **kwargs) -> object:
+        return dict(kwargs)
+
+
+class PluginWithoutId(FakePlugin):
+    plugin_id = ""
+
+
+class PluginWithoutDataPlane(FakePlugin):
+    def __init__(self, encode_audio) -> None:
+        DuplexModelPlugin.__init__(self, encode_audio)
+
+
+class PluginWithWrongDataPlane(FakePlugin):
+    def __init__(self, encode_audio) -> None:
+        DuplexModelPlugin.__init__(self, encode_audio)
+        self.data_plane = object()  # type: ignore[assignment]
+
+
+class NotAPlugin:
+    plugin_id = "lookalike"
+    data_plane = FakeDataPlane()
+
+    def __init__(self, encode_audio) -> None:
+        self.encode_audio = encode_audio
+
+
+def _path(cls: type) -> str:
+    return f"{__name__}.{cls.__name__}"
+
+
+# --------------------------------------------------------------------------- #
+# load_duplex_plugin                                                          #
+# --------------------------------------------------------------------------- #
+
+
+def test_load_duplex_plugin_instantiates_the_class_at_the_dotted_path() -> None:
+    plugin = load_duplex_plugin(_path(FakePlugin), _encode_audio)
+
+    assert type(plugin) is FakePlugin
+    assert plugin.plugin_id == "fake-duplex"
+    assert isinstance(plugin.data_plane, FakeDataPlane)
+    # Defaults of the optional class-level policy.
+    assert plugin.private_runtime_config_keys == frozenset()
+    assert plugin.silence_continuation_samples == 16000
+    assert plugin.runtime_config_for_function_output(DuplexSessionConfig(), {}, {"name": "tool"}) is None
+
+
+def test_load_duplex_plugin_rejects_a_non_plugin_class() -> None:
+    with pytest.raises(TypeError, match="not a DuplexModelPlugin"):
+        load_duplex_plugin(_path(NotAPlugin), _encode_audio)
+
+
+def test_load_duplex_plugin_requires_a_plugin_id() -> None:
+    with pytest.raises(TypeError, match="plugin_id"):
+        load_duplex_plugin(_path(PluginWithoutId), _encode_audio)
+
+
+@pytest.mark.parametrize("plugin_cls", [PluginWithoutDataPlane, PluginWithWrongDataPlane])
+def test_load_duplex_plugin_requires_a_data_plane(plugin_cls: type) -> None:
+    with pytest.raises(TypeError, match="DuplexDataPlane as data_plane"):
+        load_duplex_plugin(_path(plugin_cls), _encode_audio)
+
+
+def test_load_duplex_plugin_rejects_paths_without_a_module() -> None:
+    with pytest.raises(ValueError, match="Invalid duplex plugin path"):
+        load_duplex_plugin("FakePlugin", _encode_audio)
+
+
+def test_load_duplex_plugin_propagates_missing_attributes() -> None:
+    with pytest.raises(AttributeError):
+        load_duplex_plugin(f"{__name__}.NoSuchPlugin", _encode_audio)
+
+
+# --------------------------------------------------------------------------- #
+# validate_duplex_plugin_sampling                                             #
+# --------------------------------------------------------------------------- #
+
+
+def test_validate_duplex_plugin_sampling_accepts_one_parameter_per_stage() -> None:
+    plugin = FakePlugin(_encode_audio)
+
+    validate_duplex_plugin_sampling(plugin, sampling_defaults=(SamplingParams(), SamplingParams()))
+    validate_duplex_plugin_sampling(plugin, sampling_defaults=())
+
+
+def test_validate_duplex_plugin_sampling_rejects_stage_count_mismatch() -> None:
+    class WrongStageCountPlugin(FakePlugin):
+        def configure_sampling_params(self, *, runtime_config, defaults):
+            del runtime_config
+            return defaults[:1]
+
+    with pytest.raises(ValueError, match="one sampling parameter per stage"):
+        validate_duplex_plugin_sampling(
+            WrongStageCountPlugin(_encode_audio),
+            sampling_defaults=(SamplingParams(), SamplingParams()),
+        )
+
+
+def test_validate_duplex_plugin_sampling_rejects_type_mismatch() -> None:
+    class WrongSamplingTypePlugin(FakePlugin):
+        def configure_sampling_params(self, *, runtime_config, defaults):
+            del runtime_config
+            return tuple(object() for _ in defaults)
+
+    with pytest.raises(TypeError, match="sampling parameter type mismatch for stage 0"):
+        validate_duplex_plugin_sampling(
+            WrongSamplingTypePlugin(_encode_audio),
+            sampling_defaults=(SamplingParams(), SamplingParams()),
+        )
+
+
+def test_validate_duplex_plugin_sampling_skips_type_check_for_stages_without_defaults() -> None:
+    class ObjectSamplingPlugin(FakePlugin):
+        def configure_sampling_params(self, *, runtime_config, defaults):
+            del runtime_config
+            return tuple(object() for _ in defaults)
+
+    validate_duplex_plugin_sampling(ObjectSamplingPlugin(_encode_audio), sampling_defaults=(None, None))
+
+
+def test_validate_duplex_plugin_sampling_rejects_non_tuple_results() -> None:
+    class ListSamplingPlugin(FakePlugin):
+        def configure_sampling_params(self, *, runtime_config, defaults):
+            del runtime_config
+            return list(defaults)
+
+    with pytest.raises(TypeError, match="as a tuple"):
+        validate_duplex_plugin_sampling(ListSamplingPlugin(_encode_audio), sampling_defaults=(SamplingParams(),))
+
+
+# --------------------------------------------------------------------------- #
+# Runtime-config helpers                                                      #
+# --------------------------------------------------------------------------- #
+
+
+def test_reject_changed_runtime_value_only_raises_on_change() -> None:
+    reject_changed_runtime_value("voice-a", "voice-a", message="voice is fixed", code="voice_changed")
+
+    with pytest.raises(DuplexRuntimeConfigError, match="voice is fixed") as excinfo:
+        reject_changed_runtime_value("voice-b", "voice-a", message="voice is fixed", code="voice_changed")
+
+    assert excinfo.value.code == "voice_changed"
+    assert isinstance(excinfo.value, ValueError)
+
+
+def test_reject_changed_runtime_value_uses_the_requested_error_class() -> None:
+    class CustomRuntimeConfigError(DuplexRuntimeConfigError):
+        pass
+
+    with pytest.raises(CustomRuntimeConfigError) as excinfo:
+        reject_changed_runtime_value(1, 2, message="changed", code="custom", error_cls=CustomRuntimeConfigError)
+
+    assert excinfo.value.code == "custom"
+
+
+def test_duplex_runtime_config_error_defaults_its_code() -> None:
+    assert DuplexRuntimeConfigError("bad").code == "invalid_duplex_runtime_config"
+
+
+@pytest.mark.parametrize(
+    ("payload", "expected"),
+    [
+        ({"duplex_turn_id": 3}, 3),
+        ({"duplex_turn_id": "7"}, 7),
+        ({"model_turn_id": 2}, 2),
+        ({"duplex_turn_id": 5, "model_turn_id": 9}, 5),
+        ({"duplex_turn_id": "not-a-number"}, None),
+        ({}, None),
+        ("turn", None),
+        (None, None),
+    ],
+)
+def test_payload_turn_id_prefers_duplex_turn_id_and_coerces(payload: object, expected: int | None) -> None:
+    assert payload_turn_id(payload) == expected
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [(4, 4), ("11", 11), (2.9, 2), (True, 1), (None, None), ("x", None), (object(), None), ([1], None)],
+)
+def test_coerce_int(value: object, expected: int | None) -> None:
+    assert coerce_int(value) == expected
+
+
+# --------------------------------------------------------------------------- #
+# PipelineConfig binding                                                      #
+# --------------------------------------------------------------------------- #
+
+
+def test_pipeline_config_binds_one_duplex_plugin_path() -> None:
+    field_defaults = {f.name: f.default for f in fields(PipelineConfig)}
+
+    assert "duplex_plugin" in field_defaults
+    assert field_defaults["duplex_plugin"] is None
+
+    # The pre-framework fields survive only so that the pipelines of the models
+    # that are not ported yet still construct (RFC vllm-omni#7181 ports them).
+    # Nothing in the duplex framework may read them: a pipeline is a duplex
+    # model iff it declares ``duplex_plugin``.
+    legacy_fields = ("duplex_runtime_extension", "duplex_serving_adapter", "duplex_control_enabled")
+    for legacy_field in legacy_fields:
+        assert legacy_field in field_defaults
+
+    framework_sources = [
+        *(Path("vllm_omni/engine/duplex").glob("*.py")),
+        *(Path("vllm_omni/entrypoints/duplex").glob("*.py")),
+        Path("vllm_omni/engine/duplex_omni_engine.py"),
+        Path("vllm_omni/engine/duplex_orchestrator.py"),
+        Path("vllm_omni/entrypoints/duplex_omni.py"),
+    ]
+    readers = [
+        f"{source}:{legacy_field}"
+        for source in framework_sources
+        for legacy_field in legacy_fields
+        if legacy_field in source.read_text(encoding="utf-8")
+    ]
+    assert readers == []
+
+    # Same rule for the runtime-config knob the framework stopped reading: the
+    # append-retry table it bounded went away with the correlated append RPC.
+    assert "completed_append_cache_size" in {f.name for f in fields(DuplexSessionRuntimeConfig)}
+    assert [
+        str(source)
+        for source in framework_sources
+        if "completed_append_cache_size" in source.read_text(encoding="utf-8")
+    ] == []
diff --git a/tests/engine/duplex/test_duplex_runtime.py b/tests/engine/duplex/test_duplex_runtime.py
deleted file mode 100644
index 475cf79d0b8..00000000000
--- a/tests/engine/duplex/test_duplex_runtime.py
+++ /dev/null
@@ -1,563 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from dataclasses import FrozenInstanceError
-from types import SimpleNamespace
-
-import pytest
-from vllm.sampling_params import SamplingParams
-
-from vllm_omni.engine.duplex import runtime as duplex_runtime
-from vllm_omni.engine.duplex.contracts import (
-    duplex_data_plane_request_info,
-    duplex_resource_request_belongs_to_session,
-    duplex_resource_request_id,
-)
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.runtime import (
-    DuplexInputMode,
-    DuplexOutputAction,
-    DuplexOutputDecision,
-    DuplexRuntimeCapabilities,
-    DuplexSessionRuntimeManager,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.runtime import (
-    MiniCPMO45DuplexRuntimeExtension,
-    _duplex_hd_slice_count,
-    build_duplex_data_plane_prompt,
-    duplex_scheduler_token_budget,
-)
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-def test_duplex_fence_is_immutable():
-    fence = DuplexFence("session")
-
-    with pytest.raises(FrozenInstanceError):
-        fence.epoch = 1  # type: ignore[misc]
-
-    assert not hasattr(fence, "__dict__")
-
-
-def test_duplex_runtime_tracks_stage_bindings_and_barge_in_epoch():
-    manager = DuplexSessionRuntimeManager()
-    session = manager.open_session(
-        DuplexFence("sid-1"),
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_TOKENS},
-        ),
-    )
-    session.bind_stage_request(stage_id=0, request_id="req-stage0", fence=session.fence)
-    session.bind_stage_request(stage_id=1, request_id="req-stage1", fence=session.fence)
-
-    update = session.append_input(mode=DuplexInputMode.APPEND_TOKENS, fence=session.fence)
-    next_fence = DuplexFence("sid-1", epoch=1)
-    stale_request_ids = session.release_fence(session.fence)
-    session.accept_fence(next_fence)
-
-    assert update.seq == 1
-    assert session.fence == next_fence
-    assert stale_request_ids == ["req-stage0", "req-stage1"]
-    assert session.stage_bindings == {}
-
-
-def test_duplex_runtime_tracks_same_request_id_for_each_pipeline_stage():
-    manager = DuplexSessionRuntimeManager()
-    fence = DuplexFence("sid-shared-pipeline-request")
-    session = manager.open_session(fence)
-
-    session.reserve_stage_request(0, "req-shared", fence=fence)
-    session.bind_stage_request(0, "req-shared", fence=fence)
-    session.bind_stage_request(1, "req-shared", fence=fence)
-
-    assert session.stage_bindings[0].request_id == "req-shared"
-    assert session.stage_bindings[1].request_id == "req-shared"
-    assert session.resource_request_ids() == ["req-shared"]
-    assert session.input_seq == 0
-
-
-def test_duplex_runtime_extension_validation_rejects_missing_methods():
-    class IncompleteExtension:
-        def configure_sampling_params(self, *, runtime_config, defaults):
-            del runtime_config
-            return defaults
-
-    with pytest.raises(TypeError, match="plan_append"):
-        duplex_runtime.validate_duplex_runtime_extension(IncompleteExtension())
-
-
-def test_duplex_runtime_extension_validation_rejects_stage_count_mismatch():
-    class WrongStageCountExtension(MiniCPMO45DuplexRuntimeExtension):
-        def configure_sampling_params(self, *, runtime_config, defaults):
-            del runtime_config
-            return defaults[:1]
-
-    with pytest.raises(ValueError, match="one sampling parameter per stage"):
-        duplex_runtime.validate_duplex_runtime_extension(
-            WrongStageCountExtension(),
-            sampling_defaults=(SamplingParams(), SamplingParams()),
-        )
-
-
-def test_duplex_runtime_extension_validation_rejects_sampling_type_mismatch():
-    class WrongSamplingTypeExtension(MiniCPMO45DuplexRuntimeExtension):
-        def configure_sampling_params(self, *, runtime_config, defaults):
-            del runtime_config
-            return tuple(object() for _ in defaults)
-
-    with pytest.raises(TypeError, match="sampling parameter type"):
-        duplex_runtime.validate_duplex_runtime_extension(
-            WrongSamplingTypeExtension(),
-            sampling_defaults=(SamplingParams(), SamplingParams()),
-        )
-
-
-def test_duplex_output_decision_metadata_is_immutable():
-    decision = DuplexOutputDecision(
-        action=DuplexOutputAction.DIRECT_RESPONSE,
-        metadata={"model_listen": True},
-    )
-
-    with pytest.raises(TypeError):
-        decision.metadata["model_listen"] = False
-
-
-def _decide_minicpmo_output(
-    output: object,
-    *,
-    segment_token_ids: tuple[int, ...] = (),
-    segment_output_metadata: dict | None = None,
-):
-    return MiniCPMO45DuplexRuntimeExtension().decide_output(
-        stage_id=0,
-        final_stage_id=1,
-        segment_finished=True,
-        segment_token_ids=segment_token_ids,
-        segment_output_metadata=segment_output_metadata or {},
-        output=output,
-    )
-
-
-def test_minicpmo_extension_owns_stage_sampling_overrides():
-    defaults = (
-        SamplingParams(max_tokens=4),
-        SamplingParams(max_tokens=8),
-    )
-
-    configured = MiniCPMO45DuplexRuntimeExtension().configure_sampling_params(
-        runtime_config={
-            "duplex_stage_max_tokens": {"0": 20},
-            "duplex_stage_sampling_params": {"1": {"stop_token_ids": [151645]}},
-        },
-        defaults=defaults,
-    )
-
-    assert configured[0].max_tokens == 20
-    assert configured[1].stop_token_ids == [151645]
-    assert defaults[0].max_tokens == 4
-    assert 151645 not in (defaults[1].stop_token_ids or [])
-
-
-def test_minicpmo_output_decision_uses_raw_streaming_token_snapshot():
-    decision = _decide_minicpmo_output(
-        SimpleNamespace(outputs=[SimpleNamespace()]),
-        segment_token_ids=(151705,),
-        segment_output_metadata={"special_token_ids": {"listen_token_id": 151705}},
-    )
-
-    assert decision is not None
-    assert decision.action is DuplexOutputAction.DIRECT_RESPONSE
-    assert decision.metadata["duplex_native_decision"] == "listen"
-    assert decision.metadata["model_listen"] is True
-
-
-@pytest.mark.parametrize("attr", ["token_ids", "cumulative_token_ids"])
-def test_minicpmo_output_decision_ignores_output_level_token_history(attr):
-    output = SimpleNamespace(
-        multimodal_output={"special_token_ids": {"listen_token_id": 151705}},
-        outputs=[SimpleNamespace()],
-        **{attr: [42, 151705]},
-    )
-
-    assert _decide_minicpmo_output(output) is None
-
-
-@pytest.mark.parametrize("attr", ["token_ids", "cumulative_token_ids"])
-def test_minicpmo_output_decision_uses_completion_token_ids(attr):
-    output = SimpleNamespace(
-        multimodal_output={"special_token_ids": {"listen_token_id": 151705}},
-        outputs=[SimpleNamespace(**{attr: [42, 151705]})],
-    )
-
-    assert _decide_minicpmo_output(output) is not None
-
-
-def test_minicpmo_output_decision_uses_completion_stop_reason():
-    output = SimpleNamespace(
-        multimodal_output={"special_token_ids": {"listen_token_id": 151705}},
-        outputs=[SimpleNamespace(stop_reason=151705)],
-    )
-
-    assert _decide_minicpmo_output(output) is not None
-
-
-def test_duplex_runtime_cancel_fence_rejects_late_append_and_accepts_next_epoch():
-    manager = DuplexSessionRuntimeManager()
-    cancelled_fence = DuplexFence("sid-cancel-race")
-    next_fence = DuplexFence("sid-cancel-race", epoch=1)
-    session = manager.open_session(
-        cancelled_fence,
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-    session.bind_stage_request(
-        stage_id=0,
-        request_id="req-cancelled",
-        fence=cancelled_fence,
-    )
-
-    stale_request_ids = session.cancel_fence(cancelled_fence, next_fence)
-
-    assert stale_request_ids == ["req-cancelled"]
-    assert session.fence == next_fence
-    assert session.stage_bindings == {}
-    with pytest.raises(RuntimeError, match="fence mismatch"):
-        session.append_input(
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-            fence=cancelled_fence,
-        )
-    update = session.append_input(
-        mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-        fence=next_fence,
-    )
-    assert update.seq == 1
-
-
-def test_duplex_runtime_stale_close_preserves_live_session_and_bindings():
-    manager = DuplexSessionRuntimeManager()
-    current_fence = DuplexFence("sid-stale-close", epoch=1)
-    session = manager.open_session(
-        current_fence,
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-    session.bind_stage_request(0, "req-live", fence=current_fence)
-
-    with pytest.raises(RuntimeError, match="fence mismatch"):
-        manager.close_session(DuplexFence("sid-stale-close"))
-
-    assert manager.get("sid-stale-close") is session
-    assert session.stage_request_ids() == ["req-live"]
-
-
-def test_duplex_runtime_reopen_rejects_late_append_from_old_incarnation():
-    manager = DuplexSessionRuntimeManager()
-    old_fence = DuplexFence("sid-reopen", incarnation=0)
-    old_session = manager.open_session(
-        old_fence,
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-    manager.close_session(old_fence)
-
-    new_fence = DuplexFence("sid-reopen", incarnation=1)
-    new_session = manager.open_session(
-        new_fence,
-        capabilities=old_session.capabilities,
-    )
-
-    with pytest.raises(RuntimeError, match="fence mismatch"):
-        new_session.append_input(
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-            fence=old_fence,
-        )
-    assert (
-        new_session.append_input(
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-            fence=new_fence,
-        ).seq
-        == 1
-    )
-
-
-def test_duplex_prompt_expands_incarnation_metadata():
-    fence = DuplexFence("sid-incarnation", incarnation=3)
-
-    prompt = build_duplex_data_plane_prompt(
-        request_id=duplex_resource_request_id(fence, "stage0"),
-        fence=fence,
-        session_config={},
-        runtime_config={},
-        seq=1,
-        turn_seq=1,
-        mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-        payload={"is_speech": True},
-        final=False,
-    )
-
-    assert prompt["model_intermediate_buffer"]["duplex"]["incarnation"] == 3
-
-
-def test_duplex_runtime_tracks_turn_local_append_sequence():
-    manager = DuplexSessionRuntimeManager()
-    session = manager.open_session(
-        DuplexFence("sid-turn-seq"),
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-
-    first = session.append_input(mode=DuplexInputMode.APPEND_AUDIO_CHUNK, fence=session.fence)
-    second = session.append_input(mode=DuplexInputMode.APPEND_AUDIO_CHUNK, fence=session.fence)
-    next_turn = DuplexFence("sid-turn-seq", turn_id=1, response_seq=1)
-    third = session.append_input(
-        mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-        fence=next_turn,
-    )
-    fourth = session.append_input(
-        mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-        fence=next_turn,
-    )
-
-    assert [first.seq, second.seq, third.seq, fourth.seq] == [1, 2, 3, 4]
-    assert [first.turn_seq, second.turn_seq, third.turn_seq, fourth.turn_seq] == [1, 2, 1, 2]
-    assert [first.turn_id, second.turn_id, third.turn_id, fourth.turn_id] == [0, 0, 1, 1]
-
-
-def test_duplex_runtime_rejects_unsupported_append_mode():
-    manager = DuplexSessionRuntimeManager()
-    session = manager.open_session(
-        DuplexFence("sid-2"),
-        capabilities=DuplexRuntimeCapabilities(input_modes={DuplexInputMode.TURN_COMMIT_ONLY}),
-    )
-
-    with pytest.raises(ValueError, match="not supported"):
-        session.append_input(mode=DuplexInputMode.APPEND_TOKENS, fence=session.fence)
-
-
-def test_duplex_data_plane_request_info_extracts_structured_stage_result():
-    request_id, response_stage_id = duplex_data_plane_request_info(
-        {
-            "stage_results": [
-                {"result": {"supported": True}},
-                {
-                    "result": {
-                        "data_plane_append": True,
-                        "request_id": "duplex-sid-e0-stage0-s1",
-                        "response_stage_id": 1,
-                    }
-                },
-            ]
-        }
-    )
-
-    assert request_id == "duplex-sid-e0-stage0-s1"
-    assert response_stage_id == 1
-
-
-def test_duplex_data_plane_request_info_rejects_missing_request_id():
-    assert duplex_data_plane_request_info(
-        {
-            "stage_results": [
-                {
-                    "result": {
-                        "data_plane_append": True,
-                        "request_id": "",
-                        "response_stage_id": 1,
-                    }
-                }
-            ]
-        }
-    ) == (None, None)
-
-
-def test_duplex_scheduler_token_budget_estimates_pcm_slots():
-    assert (
-        duplex_scheduler_token_budget(
-            {
-                "audio": "AAAAAA==",
-                "format": "pcm_f32le",
-                "sample_rate_hz": 16000,
-            }
-        )
-        == 16
-    )
-
-
-def test_duplex_scheduler_token_budget_ignores_client_budget_fields():
-    assert (
-        duplex_scheduler_token_budget(
-            {
-                "audio": "AAAAAA==",
-                "format": "pcm_f32le",
-                "duplex_num_input_tokens": 999,
-                "num_input_tokens": 999,
-            }
-        )
-        == 16
-    )
-
-
-def test_resource_state_rejects_fence_regression_and_requires_explicit_fence():
-    current = DuplexFence("sid", epoch=2, turn_id=3, response_seq=4)
-    manager = DuplexSessionRuntimeManager()
-    session = manager.open_session(
-        current,
-        capabilities=DuplexRuntimeCapabilities(input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK}),
-    )
-
-    for stale in (
-        DuplexFence("sid", epoch=1, turn_id=99, response_seq=99),
-        DuplexFence("sid", epoch=2, turn_id=2, response_seq=4),
-        DuplexFence("sid", epoch=2, turn_id=3, response_seq=3),
-    ):
-        with pytest.raises(RuntimeError, match="fence mismatch"):
-            session.accept_fence(stale)
-        assert session.fence == current
-
-    with pytest.raises(TypeError, match="fence"):
-        session.bind_stage_request(0, "request")
-    with pytest.raises(TypeError, match="fence"):
-        session.append_input(mode=DuplexInputMode.APPEND_AUDIO_CHUNK)
-    with pytest.raises(TypeError, match="DuplexFence"):
-        manager.open_session("legacy-session")
-    with pytest.raises(TypeError, match="DuplexFence"):
-        manager.close_session("legacy-session")
-
-
-def test_resource_request_id_is_derived_from_fence_and_role():
-    fence = DuplexFence("sid-with-dashes", epoch=7, turn_id=11, response_seq=13)
-
-    assert duplex_resource_request_id(fence, "stage0") == "duplex-s.c2lkLXdpdGgtZGFzaGVz.i.0.e.7.r.stage0"
-    assert duplex_resource_request_id(fence, "stage1") == "duplex-s.c2lkLXdpdGgtZGFzaGVz.i.0.e.7.r.stage1"
-
-
-def test_resource_request_id_codec_separates_session_id_from_incarnation():
-    embedded_incarnation = duplex_resource_request_id(
-        DuplexFence("foo-i1", incarnation=0),
-        "stage0",
-    )
-    actual_incarnation = duplex_resource_request_id(
-        DuplexFence("foo", incarnation=1),
-        "stage0",
-    )
-
-    assert embedded_incarnation != actual_incarnation
-
-
-def test_resource_request_id_session_membership_uses_encoded_identity():
-    request_id = duplex_resource_request_id(
-        DuplexFence("sid-with-dashes", incarnation=2, epoch=7),
-        "stage0",
-    )
-
-    assert duplex_resource_request_belongs_to_session(request_id, "sid-with-dashes") is True
-    assert duplex_resource_request_belongs_to_session(request_id, "sid") is False
-    assert duplex_resource_request_belongs_to_session("duplex-s.invalid.i.x.e.7.r.stage0", "sid") is False
-
-
-def test_placeholder_budget_is_planned_inside_omni_engine_boundary():
-    fence = DuplexFence("sid", turn_id=1, response_seq=1)
-    prompt = build_duplex_data_plane_prompt(
-        request_id=duplex_resource_request_id(fence, "stage0"),
-        fence=fence,
-        session_config={},
-        runtime_config={},
-        seq=2,
-        turn_seq=1,
-        mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-        payload={
-            "audio": "AAAAAA==",
-            "format": "pcm_f32le",
-            "duplex_num_input_tokens": 999,
-            "num_input_tokens": 999,
-        },
-        final=False,
-    )
-
-    assert len(prompt["prompt_token_ids"]) == 16
-    assert prompt["model_intermediate_buffer"]["duplex"]["fence"] == fence
-    assert prompt["model_intermediate_buffer"]["duplex"]["scheduler_token_budget"] == 16
-
-
-def _jpeg_b64(width: int, height: int) -> str:
-    import base64
-    from io import BytesIO
-
-    from PIL import Image
-
-    buffer = BytesIO()
-    Image.new("RGB", (width, height), (32, 64, 96)).save(buffer, format="JPEG")
-    return base64.b64encode(buffer.getvalue()).decode("ascii")
-
-
-def _pcm_unit_payload(frames: list[str]) -> dict[str, object]:
-    import base64
-
-    return {
-        "audio": base64.b64encode(b"\x00" * (16000 * 4)).decode("ascii"),
-        "format": "pcm_f32le",
-        "sample_rate_hz": 16000,
-        "video_frames": frames,
-    }
-
-
-def test_duplex_scheduler_token_budget_one_frame_is_one_block():
-    audio_only = duplex_scheduler_token_budget(_pcm_unit_payload([]))
-    one_frame = duplex_scheduler_token_budget(_pcm_unit_payload([_jpeg_b64(960, 540)]))
-
-    assert one_frame - audio_only == 66
-
-
-@pytest.mark.parametrize(
-    ("base_size", "expected_blocks"),
-    [
-        ((960, 540), 4),  # official camera frame: source + 2 HD patches + composite
-        ((540, 960), 4),  # portrait phone capture
-        ((640, 360), 4),
-        ((448, 448), 2),  # fits one tile: the processor does not slice it
-        ((320, 240), 2),
-    ],
-)
-def test_duplex_scheduler_token_budget_matches_stage0_hd_slicing(base_size, expected_blocks):
-    """A stacked pair is processed with max_slice_nums=[2, 1]; the budget must
-    equal the blocks Stage0 builds for that base-frame size."""
-    audio_only = duplex_scheduler_token_budget(_pcm_unit_payload([]))
-    pair = duplex_scheduler_token_budget(_pcm_unit_payload([_jpeg_b64(*base_size), _jpeg_b64(448, 448)]))
-
-    assert pair - audio_only == expected_blocks * 66
-
-
-@pytest.mark.parametrize(
-    ("size", "expected_patches"),
-    [
-        # multiple = min(ceil(w * h / 448**2), max_slice_nums); <= 1 is never sliced.
-        ((448, 448), 0),  # exactly one tile
-        ((320, 240), 0),  # smaller than one tile
-        ((447, 449), 0),  # just under one tile
-        ((449, 449), 2),  # just over: the processor cuts a 2-tile grid
-        ((640, 360), 2),
-        ((960, 540), 2),  # official camera frame
-        ((540, 960), 2),  # same frame rotated
-        ((1920, 1080), 2),  # capped by max_slice_nums=2, not by area
-    ],
-)
-def test_duplex_hd_slice_count_matches_official_grid(size, expected_patches):
-    """Lock the port of ``MiniCPMVImageProcessor.get_sliced_grid``.
-
-    Stage0 slices a stacked unit with ``max_slice_nums=[2, 1]``, so the patch
-    count for the base frame decides the scheduler budget. A frame that fits one
-    ``scale_resolution=448`` tile is not sliced at all.
-    """
-    assert _duplex_hd_slice_count(size, 2) == expected_patches
-
-
-def test_duplex_scheduler_token_budget_unreadable_base_frame_keeps_hd_fallback():
-    audio_only = duplex_scheduler_token_budget(_pcm_unit_payload([]))
-    pair = duplex_scheduler_token_budget(_pcm_unit_payload(["not-an-image", _jpeg_b64(448, 448)]))
-
-    assert pair - audio_only == 4 * 66
diff --git a/tests/engine/duplex/test_engine_session.py b/tests/engine/duplex/test_engine_session.py
new file mode 100644
index 00000000000..fccaa59e887
--- /dev/null
+++ b/tests/engine/duplex/test_engine_session.py
@@ -0,0 +1,612 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Session-state semantics of the engine-resident duplex session (``DuplexEngineSession``)."""
+
+from __future__ import annotations
+
+from dataclasses import FrozenInstanceError
+
+import pytest
+
+from vllm_omni.engine.duplex.config import (
+    DuplexCapabilities,
+    DuplexConfigError,
+    DuplexOverlapPolicy,
+    DuplexSessionConfig,
+    DuplexTurnEventType,
+    DuplexTurnState,
+    ResponseCreateOptions,
+)
+from vllm_omni.engine.duplex.contracts import DuplexFence
+from vllm_omni.engine.duplex.events import TurnEvent
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession, DuplexFenceMismatchError
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.capabilities import (
+    minicpmo45_native_capabilities,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def _session(session_id: str = "duplex-test", config: DuplexSessionConfig | None = None) -> DuplexEngineSession:
+    return DuplexEngineSession(session_id=session_id, config=config or DuplexSessionConfig(model="test-model"))
+
+
+def test_commit_audio_input_does_not_advance_model_turn_identity():
+    session = _session()
+
+    first = session.commit_audio_input(transcript="first chunk")
+    second = session.commit_audio_input(transcript="second chunk")
+
+    assert session.input_commit_seq == 2
+    assert first.input_commit_seq == 1
+    assert second.input_commit_seq == 2
+    assert first.turn_id == second.turn_id == session.turn_id == 0
+    assert first.message["transcript"] == "first chunk"
+    assert first.message["content"] == [
+        {"type": "audio_url", "audio_url": {"url": "native-duplex:input-audio"}, "transcript": "first chunk"}
+    ]
+    assert len(session.history) == 2
+    assert session.turn_state == DuplexTurnState.USER_COMMITTED
+
+
+def test_commit_audio_input_accepts_explicit_turn_id():
+    session = _session()
+
+    committed = session.commit_audio_input(turn_id=4)
+
+    assert committed.turn_id == 4
+    assert session.turn_id == 0
+    assert "transcript" not in committed.message
+
+
+# ---- response options ----
+
+
+def test_response_options_apply_to_one_response_without_mutating_session_defaults():
+    session = _session(config=DuplexSessionConfig(instructions="base", voice="base-voice", max_tokens=64))
+    session.reserve_response_options(
+        ResponseCreateOptions(instructions="one response", voice="override-voice", max_tokens=8)
+    )
+
+    assert session.config.instructions == "base"
+    assert session.config.voice == "base-voice"
+    assert session.response_config is session.config
+    session.begin_response()
+    assert session.config.instructions == "base"
+    assert session.config.voice == "base-voice"
+    assert session.response_config.instructions == "one response"
+    assert session.response_config.voice == "override-voice"
+    assert session.response_config.max_tokens == 8
+
+    session.end_response()
+    assert session.response_config is session.config
+    assert session.config.instructions == "base"
+    assert session.config.voice == "base-voice"
+    assert session.config.max_tokens == 64
+
+
+def test_response_options_cannot_overwrite_an_unconsumed_reservation():
+    session = _session(config=DuplexSessionConfig(instructions="base"))
+    session.reserve_response_options(ResponseCreateOptions(instructions="first"))
+
+    with pytest.raises(RuntimeError, match="already reserved"):
+        session.reserve_response_options(ResponseCreateOptions(instructions="second"))
+
+    session.begin_response()
+    assert session.response_config.instructions == "first"
+
+
+def test_response_options_cannot_be_reserved_while_response_is_active():
+    session = _session(config=DuplexSessionConfig(instructions="base"))
+    session.begin_response()
+
+    with pytest.raises(RuntimeError, match="active"):
+        session.reserve_response_options(ResponseCreateOptions(instructions="too late"))
+
+
+def test_discarded_response_options_do_not_apply():
+    session = _session(config=DuplexSessionConfig(instructions="base"))
+    session.reserve_response_options(ResponseCreateOptions(instructions="dropped"))
+    session.discard_response_options()
+
+    session.begin_response()
+
+    assert session.response_config.instructions == "base"
+
+
+# ---- response / overlap identity ----
+
+
+def test_session_owns_response_and_overlap_identity():
+    session = _session()
+
+    response_id = session.begin_response()
+    assert session.turn_state == DuplexTurnState.ASSISTANT_GENERATING
+    session.accumulate_overlap_speech(320)
+    session.accumulate_overlap_speech(180)
+    session.end_response()
+
+    assert session.active_response_id is None
+    assert session.last_response_id == response_id
+    assert session.overlap_speech_ms == 500
+    assert session.reset_overlap_speech() == 500
+    assert session.overlap_speech_ms == 0
+    assert session.turn_state == DuplexTurnState.IDLE
+
+
+def test_session_composes_single_owner_ledgers_with_immutable_views():
+    session = _session()
+
+    session.bind_request("req-1")
+    response_id = session.begin_response(turn_id=3)
+    session.mark_audio_sent(duration_ms=240)
+
+    assert session.active_request_id == "req-1"
+    assert session.active_response_id == response_id
+    assert session.active_response_turn_id == 3
+    assert session.playback.sent_ms == 240
+    assert session.turn_state == DuplexTurnState.ASSISTANT_PLAYING
+    with pytest.raises(FrozenInstanceError):
+        session.playback.sent_ms = 480  # type: ignore[misc]
+    assert session.playback.sent_ms == 240
+
+
+def test_barge_in_advances_epoch_and_drops_uncommitted_assistant_text():
+    session = _session()
+    response_id = session.begin_response()
+    session.bind_request("chatcmpl-duplex-test")
+    session.append_assistant_text("unplayed answer")
+
+    new_epoch = session.barge_in()
+
+    assert response_id is not None
+    assert new_epoch == 1
+    assert session.epoch == 1
+    assert session.accepted_fence == DuplexFence(session.session_id, epoch=1, turn_id=0)
+    assert session.active_request_id is None
+    assert session.active_response_id is None
+    assert session.assistant_text_buffer == ()
+    assert session.history == ()
+    assert session.turn_state == DuplexTurnState.BARGE_IN
+
+
+# ---- playback ledger ----
+
+
+def test_playback_ack_tracks_committed_cursor_separately():
+    session = _session()
+    session.mark_audio_sent(duration_ms=10_000)
+
+    session.acknowledge_playback(played_ms=2_000)
+
+    assert session.playback.generated_ms == 10_000
+    assert session.playback.sent_ms == 10_000
+    assert session.playback.played_ms == 2_000
+    assert session.playback.committed_ms == 2_000
+    assert session.playback.as_dict() == {
+        "generated_ms": 10_000,
+        "sent_ms": 10_000,
+        "played_ms": 2_000,
+        "committed_ms": 2_000,
+    }
+
+
+def test_playback_ack_is_scoped_per_response():
+    session = _session()
+    first = session.begin_response()
+    session.mark_audio_sent(duration_ms=3_000)
+    session.end_response()
+    second = session.begin_response()
+    session.mark_audio_sent(duration_ms=1_000)
+
+    session.acknowledge_playback(played_ms=2_500, response_id=first)
+
+    assert session.playback_for_response(first).played_ms == 2_500
+    assert session.playback_for_response(second).played_ms == 0
+    assert session.playback.played_ms == 0
+
+
+def test_history_commit_uses_audio_text_alignment_marks():
+    session = _session()
+    session.begin_response()
+
+    session.append_assistant_text("hello ")
+    session.mark_audio_sent(duration_ms=1_000, text_chars=6)
+    session.append_assistant_text("world")
+    session.mark_audio_sent(duration_ms=2_000, text_chars=11)
+    assert [(mark.text_chars, mark.audio_end_ms) for mark in session.assistant_audio_text_marks] == [
+        (6, 1_000),
+        (11, 2_000),
+    ]
+    session.acknowledge_playback(played_ms=1_200, committed_ms=1_200)
+
+    committed = session.end_response(commit_text=True)
+
+    assert committed == {"role": "assistant", "content": "hello w"}
+    assert session.history[-1] == committed
+    assert session.last_assistant_full_message == {"role": "assistant", "content": "hello world"}
+
+
+def test_history_commit_with_ack_only_policy_defers_unacknowledged_text():
+    session = _session(config=DuplexSessionConfig(playback_commit_policy="ack_only"))
+    response_id = session.begin_response()
+    session.append_assistant_text("never played")
+    session.mark_audio_sent(duration_ms=1_000, text_chars=12)
+
+    committed = session.end_response(commit_text=True)
+
+    assert committed is None
+    assert session.history == ()
+    assert f"item_{response_id}" in session.pending_history_item_ids
+
+
+def test_truncate_history_item_uses_response_alignment_marks():
+    session = _session()
+    response_id = session.begin_response()
+    session.append_assistant_text("hello ")
+    session.mark_audio_sent(duration_ms=1_000, text_chars=6)
+    session.append_assistant_text("world")
+    session.mark_audio_sent(duration_ms=2_000, text_chars=11)
+    session.acknowledge_playback(played_ms=2_000)
+    committed = session.end_response(commit_text=True)
+    assert committed == {"role": "assistant", "content": "hello world"}
+    item_id = f"item_{response_id}"
+    session.register_history_item(item_id, committed)
+
+    assert session.truncate_history_item(item_id, audio_end_ms=1_000) is True
+
+    assert session.history[-1] == {"role": "assistant", "content": "hello"}
+    assert session.history_item_ids[item_id] == {"role": "assistant", "content": "hello"}
+    assert session.delete_history_item(item_id) is True
+    assert session.history == ()
+
+
+# ---- turn signals / model turns ----
+
+
+@pytest.mark.parametrize(
+    ("event_type", "turn_state"),
+    [
+        (DuplexTurnEventType.USER_STARTED, DuplexTurnState.USER_SPEAKING),
+        (DuplexTurnEventType.USER_COMMITTED, DuplexTurnState.USER_COMMITTED),
+        (DuplexTurnEventType.ASSISTANT_STARTED, DuplexTurnState.ASSISTANT_GENERATING),
+        (DuplexTurnEventType.ASSISTANT_DONE, DuplexTurnState.IDLE),
+        (DuplexTurnEventType.BARGE_IN, DuplexTurnState.BARGE_IN),
+    ],
+)
+def test_signal_turn_transitions_and_returns_typed_turn_event(event_type, turn_state):
+    session = _session()
+
+    event = session.signal_turn(event_type.value)
+
+    assert isinstance(event, TurnEvent)
+    assert session.turn_state == turn_state
+    wire = event.to_realtime()
+    assert wire["type"] == "turn.event"
+    assert wire["event"] == event_type.value
+    assert wire["turn_state"] == turn_state.value
+
+
+def test_signal_turn_playback_ack_updates_cursor_and_close_marks_session_closing():
+    session = _session()
+    session.mark_audio_sent(duration_ms=5_000)
+
+    ack = session.signal_turn("playback_ack", {"played_ms": 1_500, "committed_ms": 1_000})
+    assert ack.event == "playback_ack"
+    assert session.playback.played_ms == 1_500
+    assert session.playback.committed_ms == 1_000
+
+    close = session.signal_turn(DuplexTurnEventType.CLOSE.value)
+    assert close.event == "close"
+    assert session.state.value == "closing"
+
+
+def test_complete_model_turn_advances_turn_id_and_fence():
+    session = _session()
+    assert session.fence == DuplexFence(session.session_id, epoch=0, turn_id=0)
+
+    session.complete_model_turn(0)
+
+    assert session.turn_id == 1
+    assert session.fence == DuplexFence(session.session_id, epoch=0, turn_id=1)
+    assert session.accepted_fence == session.fence
+
+    # A stale terminal for an already-completed turn does not move identity backwards.
+    session.complete_model_turn(0)
+    assert session.turn_id == 1
+    session.complete_model_turn(3)
+    assert session.turn_id == 4
+    assert session.accepted_fence.turn_id == 4
+
+
+# ---- fence validation ----
+
+
+def test_accept_fence_rejects_stale_or_foreign_fences():
+    session = _session("sid-fence")
+    session.complete_model_turn(0)
+
+    with pytest.raises(DuplexFenceMismatchError):
+        session.accept_fence(DuplexFence("sid-fence", epoch=0, turn_id=0))
+    with pytest.raises(DuplexFenceMismatchError):
+        session.accept_fence(DuplexFence("sid-other", epoch=0, turn_id=1))
+
+    session.accept_fence(DuplexFence("sid-fence", epoch=1, turn_id=0))
+    assert session.accepted_fence == DuplexFence("sid-fence", epoch=1, turn_id=0)
+
+
+def test_prepare_and_commit_append_sequence_chunks_per_turn_and_epoch():
+    session = _session("sid-append")
+    fence = session.fence
+
+    first = session.commit_append(session.prepare_append(fence))
+    second = session.commit_append(session.prepare_append(fence))
+    assert (first.seq, first.turn_seq, first.turn_id) == (1, 1, 0)
+    assert (second.seq, second.turn_seq, second.turn_id) == (2, 2, 0)
+
+    session.complete_model_turn(0)
+    third = session.commit_append(session.prepare_append(session.fence))
+    assert (third.seq, third.turn_seq, third.turn_id) == (3, 1, 1)
+
+    # Barge-in advances the epoch (turn_id is kept) and restarts the append sequence.
+    session.barge_in()
+    assert session.fence == DuplexFence("sid-append", epoch=1, turn_id=1)
+    fourth = session.commit_append(session.prepare_append(session.fence))
+    assert (fourth.seq, fourth.turn_seq, fourth.turn_id) == (1, 1, 1)
+    assert session.input_seq == 1
+
+
+def test_commit_append_rejects_stale_reservation():
+    session = _session("sid-append-stale")
+    fence = session.fence
+    reservation = session.prepare_append(fence)
+    session.commit_append(session.prepare_append(fence))
+
+    with pytest.raises(RuntimeError, match="stale"):
+        session.commit_append(reservation)
+
+    with pytest.raises(DuplexFenceMismatchError):
+        session.prepare_append(DuplexFence("sid-other", epoch=0, turn_id=0))
+
+
+def test_cancel_fence_releases_stage_requests_and_advances_identity():
+    session = _session("sid-cancel")
+    cancelled = session.fence
+    session.reserve_stage_request(0, "req-a", fence=cancelled)
+    session.bind_stage_request(1, "req-b", fence=cancelled)
+    assert session.stage_request_submitted(1, "req-b") is True
+    assert session.stage_request_submitted(0, "req-a") is False
+    next_fence = DuplexFence("sid-cancel", epoch=1, turn_id=0)
+
+    stale = session.cancel_fence(cancelled, next_fence)
+
+    assert stale == ["req-a", "req-b"]
+    assert session.resource_request_ids() == []
+    assert session.accepted_fence == next_fence
+
+    with pytest.raises(DuplexFenceMismatchError):
+        session.cancel_fence(next_fence, DuplexFence("sid-cancel", epoch=1, turn_id=1))
+    with pytest.raises(DuplexFenceMismatchError):
+        session.cancel_fence(DuplexFence("sid-other", epoch=1, turn_id=0), DuplexFence("sid-cancel", epoch=2))
+
+
+# ---- public view ----
+
+
+def test_as_public_dict_exposes_identity_capabilities_and_playback():
+    session = _session("duplex-public", config=DuplexSessionConfig(model="m", voice="alloy"))
+    session.mark_audio_sent(duration_ms=100)
+
+    payload = session.as_public_dict()
+
+    assert payload["id"] == "duplex-public"
+    assert payload["model"] == "m"
+    assert payload["voice"] == "alloy"
+    assert payload["state"] == "open"
+    assert payload["turn_state"] == "assistant_playing"
+    assert payload["epoch"] == 0
+    assert payload["turn_id"] == 0
+    assert payload["capabilities"] == DuplexCapabilities().as_dict()
+    assert payload["playback"] == {"generated_ms": 100, "sent_ms": 100, "played_ms": 0, "committed_ms": 0}
+
+
+# ---- DuplexSessionConfig.from_realtime ----
+
+
+def test_from_realtime_rejects_unsupported_audio_formats():
+    with pytest.raises(DuplexConfigError) as excinfo:
+        DuplexSessionConfig.from_realtime({"input_audio_format": "mp3"})
+    assert excinfo.value.code == "unsupported_audio_format"
+
+    with pytest.raises(DuplexConfigError) as excinfo:
+        DuplexSessionConfig.from_realtime({"audio": {"output": {"format": {"type": "audio/opus"}}}})
+    assert excinfo.value.code == "unsupported_audio_format"
+
+
+def test_from_realtime_validates_turn_detection():
+    with pytest.raises(DuplexConfigError) as excinfo:
+        DuplexSessionConfig.from_realtime({"turn_detection": {"type": "semantic_vad"}})
+    assert excinfo.value.code == "unsupported_turn_detection"
+    assert excinfo.value.param == "turn_detection"
+
+    with pytest.raises(DuplexConfigError) as excinfo:
+        DuplexSessionConfig.from_realtime({"overlap_policy": "barge_in_on_speech"})
+    assert excinfo.value.code == "unsupported_turn_detection"
+
+    server_vad = DuplexSessionConfig.from_realtime({"turn_detection": {"type": "server_vad"}})
+    assert server_vad.overlap_policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value
+    assert server_vad.extra_body["realtime_turn_detection"]["threshold"] == 0.5
+
+    model_owned = DuplexSessionConfig.from_realtime({"turn_detection": None})
+    assert model_owned.overlap_policy == DuplexOverlapPolicy.LISTEN_ONLY.value
+    assert model_owned.extra_body["realtime_turn_detection"] is None
+
+
+def test_from_realtime_maps_wire_fields_and_stores_realtime_keys_in_extra_body():
+    config = DuplexSessionConfig.from_realtime(
+        {
+            "model": "openbmb/MiniCPM-o-4_5",
+            "instructions": "be brief",
+            "output_audio_format": "pcm16",
+            "max_response_output_tokens": "inf",
+            "audio": {"output": {"voice": "alloy", "speed": 1.25}},
+            "tools": [{"type": "function", "name": "lookup"}],
+            "tool_choice": "auto",
+            "metadata": {"tenant": "t1"},
+            "include": ["item.input_audio_transcription.logprobs"],
+            "input_audio_transcription": {"model": "whisper-1"},
+            "extra_body": {"custom": True},
+        }
+    )
+
+    assert config.model == "openbmb/MiniCPM-o-4_5"
+    assert config.instructions == "be brief"
+    assert config.voice == "alloy"
+    assert config.speed == 1.25
+    assert config.max_tokens is None
+    assert config.response_format == "pcm"
+    assert config.modalities == ["text", "audio"]
+    assert config.extra_body["custom"] is True
+    assert config.extra_body["realtime_tools"] == [{"type": "function", "name": "lookup"}]
+    assert config.extra_body["realtime_tool_choice"] == "auto"
+    assert config.extra_body["realtime_metadata"] == {"tenant": "t1"}
+    assert config.extra_body["realtime_include"] == ["item.input_audio_transcription.logprobs"]
+    assert config.extra_body["realtime_input_audio_transcription"] == {"model": "whisper-1"}
+    assert config.extra_body["realtime_audio"] == {"output": {"voice": "alloy", "speed": 1.25}}
+    assert config.extra_body["realtime_output_audio_format"] == "pcm16"
+    assert "extra_body" not in config.extra_body["realtime_session_payload"]
+    assert config.extra_body["realtime_session_payload"]["model"] == "openbmb/MiniCPM-o-4_5"
+
+
+def test_from_realtime_uses_served_model_when_payload_has_none():
+    config = DuplexSessionConfig.from_realtime({}, model="served-model")
+
+    assert config.model == "served-model"
+    assert config.response_format == "pcm"
+    assert config.idle_timeout_s == 300.0
+
+
+def test_from_realtime_ignores_client_chosen_session_ids():
+    config = DuplexSessionConfig.from_realtime({"id": "client-chosen", "session_id": "also-client-chosen"})
+
+    assert not hasattr(config, "session_id")
+    assert "id" not in config.as_dict()
+    session = _session("duplex-engine-allocated", config=config)
+    assert session.as_public_dict()["id"] == "duplex-engine-allocated"
+
+
+# ---- DuplexSessionConfig.apply_realtime_update ----
+
+
+def test_apply_realtime_update_rejects_model_change():
+    config = DuplexSessionConfig(model="served-model")
+
+    with pytest.raises(DuplexConfigError) as excinfo:
+        config.apply_realtime_update({"model": "other-model"}, session_id="sid")
+
+    assert excinfo.value.code == "model_update_unsupported"
+    assert config.model == "served-model"
+
+
+def test_apply_realtime_update_rejects_voice_change_after_audio_started():
+    config = DuplexSessionConfig(model="m", voice="alloy")
+
+    config.apply_realtime_update({"voice": "verse"}, audio_started=False)
+    assert config.voice == "verse"
+    with pytest.raises(DuplexConfigError) as excinfo:
+        config.apply_realtime_update({"audio": {"output": {"voice": "alloy"}}}, audio_started=True)
+    assert excinfo.value.code == "voice_update_after_audio_unsupported"
+    assert config.voice == "verse"
+
+
+def test_apply_realtime_update_rejects_ref_audio_change():
+    config = DuplexSessionConfig(model="m")
+
+    with pytest.raises(DuplexConfigError) as excinfo:
+        config.apply_realtime_update({"ref_audio": "/tmp/voice.wav"})
+
+    assert excinfo.value.code == "ref_audio_update_unsupported"
+    assert config.ref_audio is None
+
+
+def test_apply_realtime_update_patches_fields_and_realtime_keys():
+    config = DuplexSessionConfig(model="m", instructions="old", extra_body={"realtime_tools": [{"name": "x"}]})
+
+    config.apply_realtime_update(
+        {
+            "instructions": "new",
+            "output_audio_format": "g711_ulaw",
+            "max_output_tokens": 32,
+            "tools": None,
+            "metadata": {"k": "v"},
+            "overlap_policy": "not-a-policy",
+        }
+    )
+
+    assert config.instructions == "new"
+    assert config.response_format == "pcm"
+    assert config.max_tokens == 32
+    assert "realtime_tools" not in config.extra_body
+    assert config.extra_body["realtime_metadata"] == {"k": "v"}
+    assert config.overlap_policy == DuplexOverlapPolicy.LISTEN_ONLY.value
+    assert config.extra_body["realtime_session_payload"]["instructions"] == "new"
+
+
+# ---- overlap policy / capabilities ----
+
+
+def test_overlap_policy_defaults_and_invalid_values_to_listen_only():
+    assert DuplexSessionConfig().overlap_policy == DuplexOverlapPolicy.LISTEN_ONLY.value
+    assert DuplexSessionConfig._normalize_overlap_policy("auto") == DuplexOverlapPolicy.LISTEN_ONLY.value
+    assert DuplexSessionConfig._normalize_overlap_policy("not-a-policy") == DuplexOverlapPolicy.LISTEN_ONLY.value
+    assert (
+        DuplexSessionConfig._normalize_overlap_policy(" Barge_In_On_Speech ")
+        == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value
+    )
+    assert DuplexSessionConfig.from_event({"session": {"overlap_policy": "bogus"}}).overlap_policy == "listen_only"
+
+
+def test_capabilities_as_dict_reports_model_native_duplex_constants():
+    caps = DuplexCapabilities().as_dict()
+
+    assert caps["implementation_level"] == "model_native_duplex"
+    assert caps["input_modes"] == ["append_audio_chunk"]
+    assert caps["supports_kv_lease"] is False
+    assert caps["supports_core_kv_lease"] is False
+    assert "client_event" in caps["signal_sources"]
+    assert set(caps) == set(minicpmo45_native_capabilities().as_dict())
+
+
+def test_minicpmo_native_capabilities_separate_model_state_from_core_kv_lease():
+    caps = minicpmo45_native_capabilities(max_sessions=2).as_dict()
+
+    assert caps["implementation_level"] == "model_native_duplex"
+    assert caps["supports_input_append"] is True
+    assert caps["input_modes"] == ["append_audio_chunk"]
+    assert caps["adapter_patterns"] == ["scheduler_data_plane"]
+    assert caps["supports_model_internal_state"] is True
+    assert caps["requires_model_runner_kv"] is True
+    assert caps["requires_native_stage_role"] is True
+    assert caps["supports_kv_lease"] is False
+    assert caps["supports_core_kv_lease"] is False
+    assert caps["supports_stage_resumption"] is True
+    assert caps["supports_scheduler_native_append"] is False
+    assert caps["supports_core_resumable_request"] is True
+    assert caps["supports_stage_connector_handoff"] is True
+    assert caps["supports_audio_truncate"] is True
+    assert caps["supports_barge_in"] is True
+    assert caps["target_barge_in_latency_ms"] is None
+    assert caps["supports_multi_session"] is True
+    assert caps["supports_multi_session_same_replica"] is True
+    assert caps["supports_session_lease"] is True
+    assert caps["supports_session_resume"] is True
+    assert caps["session_admission_mode"] == "engine_managed"
+    assert caps["stage_handoff_transport"] == "scheduler_data_plane"
+
+
+def test_minicpmo_native_capabilities_do_not_overclaim_single_session_deployment():
+    caps = minicpmo45_native_capabilities(max_sessions=1).as_dict()
+
+    assert caps["supports_multi_session"] is False
+    assert caps["supports_multi_session_same_replica"] is False
diff --git a/tests/engine/duplex/test_overlap_policy.py b/tests/engine/duplex/test_overlap_policy.py
new file mode 100644
index 00000000000..096b7c7c9d5
--- /dev/null
+++ b/tests/engine/duplex/test_overlap_policy.py
@@ -0,0 +1,229 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The overlap decision, reached directly.
+
+These rules decide what happens when input arrives while the model is speaking.
+They were unreachable except by driving a whole append through the runner, so
+none of them had a test that named the rule it was checking.
+"""
+
+from __future__ import annotations
+
+import base64
+
+import numpy as np
+import pytest
+
+from vllm_omni.engine.duplex.config import DuplexSessionConfig
+from vllm_omni.engine.duplex.session import overlap_policy
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def _session(**config: object) -> DuplexEngineSession:
+    values: dict[str, object] = {"model": "fake-model"}
+    values.update(config)
+    return DuplexEngineSession(session_id="sid", config=DuplexSessionConfig(**values))
+
+
+def _pcm16(rms: float, samples: int = 1600) -> str:
+    data = np.full(samples, int(rms * 32768), dtype=np.int16)
+    return base64.b64encode(data.tobytes()).decode("ascii")
+
+
+# --------------------------------------------------------------------------- #
+# Speech detection                                                            #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.parametrize("flag", [True, False])
+def test_an_explicit_is_speech_flag_wins_over_the_audio(flag: bool) -> None:
+    session = _session()
+    payload = {"format": "pcm16", "audio": _pcm16(0.9 if not flag else 0.0)}
+    assert overlap_policy.input_looks_like_speech(session, {"is_speech": flag}, payload) is flag
+
+
+def test_vad_probability_decides_when_no_flag_is_given() -> None:
+    session = _session()
+    payload = {"format": "pcm16", "audio": _pcm16(0.0)}
+    assert overlap_policy.input_looks_like_speech(session, {"vad": {"speech_probability": 0.9}}, payload) is True
+    assert overlap_policy.input_looks_like_speech(session, {"vad": {"speech_probability": 0.1}}, payload) is False
+
+
+def test_quiet_audio_below_the_configured_rms_is_not_speech() -> None:
+    session = _session(overlap_silence_rms=0.05)
+    loud = {"format": "pcm16", "audio": _pcm16(0.5)}
+    quiet = {"format": "pcm16", "audio": _pcm16(0.001)}
+    assert overlap_policy.input_looks_like_speech(session, {}, loud) is True
+    assert overlap_policy.input_looks_like_speech(session, {}, quiet) is False
+
+
+def test_undecodable_audio_is_treated_as_speech() -> None:
+    """Fail toward listening: dropping real speech is worse than a spurious turn."""
+    session = _session()
+    assert overlap_policy.input_looks_like_speech(session, {}, {"format": "pcm16", "audio": "!!not base64!!"}) is True
+
+
+# --------------------------------------------------------------------------- #
+# Barge-in                                                                    #
+# --------------------------------------------------------------------------- #
+
+
+def test_an_explicit_client_overlap_action_requests_barge_in() -> None:
+    session = _session()
+    payload = {"format": "pcm16", "audio": _pcm16(0.5)}
+    decision = overlap_policy.decide(session, {"overlap_action": "barge_in"}, payload, auto_responds=True)
+    assert decision["action"] == "barge_in"
+    assert decision["reason"] == "client_overlap_action"
+
+
+def test_barge_in_is_deferred_when_the_session_cannot_support_it() -> None:
+    session = _session()
+    session.capabilities = type(session.capabilities)(supports_barge_in=False)
+    payload = {"format": "pcm16", "audio": _pcm16(0.5)}
+    decision = overlap_policy.decide(session, {"force_barge_in": True}, payload, auto_responds=True)
+    assert decision["action"] != "barge_in"
+
+
+# --------------------------------------------------------------------------- #
+# Force-listen                                                                #
+# --------------------------------------------------------------------------- #
+
+
+def test_a_short_response_create_is_forced_to_listen() -> None:
+    """A sub-threshold ack should not take the turn from the model."""
+    session = _session(overlap_short_ack_ms=700)
+    short = {"response_create": True, "duration_ms": 200}
+    long = {"response_create": True, "duration_ms": 1500}
+    assert overlap_policy.should_force_listen_for_short_commit(session, short, {}) is True
+    assert overlap_policy.should_force_listen_for_short_commit(session, long, {}) is False
+
+
+def test_force_barge_in_overrides_the_short_ack_rule() -> None:
+    session = _session(overlap_short_ack_ms=700)
+    event = {"response_create": True, "duration_ms": 200, "force_barge_in": True}
+    assert overlap_policy.should_force_listen_for_short_commit(session, event, {}) is False
+
+
+def test_auto_response_overlap_forces_listen_only_when_auto_responding() -> None:
+    event = {"force_listen": True}
+    assert overlap_policy.should_force_listen_for_auto_response_overlap(event, {}, auto_responds=True) is True
+    assert overlap_policy.should_force_listen_for_auto_response_overlap(event, {}, auto_responds=False) is False
+
+
+# --------------------------------------------------------------------------- #
+# Payload merging                                                             #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.parametrize("speech_first", [True, False], ids=["speech-then-silence", "silence-then-speech"])
+def test_merging_two_appends_keeps_speech_if_either_half_was_speech(speech_first: bool) -> None:
+    """Matching rates and decodable audio, so the halves really are concatenated.
+
+    Without a ``sample_rate_hz`` on both, ``merge_audio_payloads`` falls back
+    to the newer chunk before merging, and the speech flag it returned was the
+    second chunk's own -- the test passed without exercising the merge.
+    """
+    speech = {
+        "format": "pcm_f32le",
+        "audio": base64.b64encode(b"\x01" * 8).decode("ascii"),
+        "sample_rate_hz": 16000,
+        "is_speech": True,
+    }
+    silence = {
+        "format": "pcm_f32le",
+        "audio": base64.b64encode(b"\x00" * 8).decode("ascii"),
+        "sample_rate_hz": 16000,
+        "is_speech": False,
+    }
+    first, second = (speech, silence) if speech_first else (silence, speech)
+    merged = overlap_policy.merge_audio_payloads(first, second)
+    assert base64.b64decode(merged["audio"]) == base64.b64decode(first["audio"]) + base64.b64decode(second["audio"])
+    assert merged["sample_rate_hz"] == 16000
+    assert merged["is_speech"] is True
+
+
+@pytest.mark.parametrize(
+    ("first", "second"),
+    [
+        ({"format": "pcm_f32le", "audio": "", "sample_rate_hz": 16000}, {"format": "pcm16", "audio": ""}),
+        (
+            {"format": "pcm_f32le", "audio": "", "sample_rate_hz": 16000},
+            {"format": "pcm_f32le", "audio": "", "sample_rate_hz": 24000},
+        ),
+        (
+            {"format": "pcm_f32le", "audio": "!!not base64!!", "sample_rate_hz": 16000},
+            {"format": "pcm_f32le", "audio": "", "sample_rate_hz": 16000},
+        ),
+    ],
+    ids=["format-mismatch", "rate-mismatch", "undecodable"],
+)
+def test_unmergeable_payloads_fall_back_to_the_newer_one(first: dict, second: dict) -> None:
+    """Whatever cannot be concatenated keeps the newer chunk and drops the older.
+
+    Worth pinning: the fallback discards ``first`` silently, so a bug that makes
+    two mergeable payloads look mismatched loses buffered audio rather than
+    raising.
+    """
+    assert overlap_policy.merge_audio_payloads(first, second) == second
+
+
+def test_mergeable_payloads_are_concatenated_in_order() -> None:
+    head = bytes([1, 2, 3, 4])
+    tail = bytes([5, 6, 7, 8])
+    first = {"format": "pcm_f32le", "audio": base64.b64encode(head).decode(), "sample_rate_hz": 16000}
+    second = {"format": "pcm_f32le", "audio": base64.b64encode(tail).decode(), "sample_rate_hz": 16000}
+    merged = overlap_policy.merge_audio_payloads(first, second)
+    assert base64.b64decode(merged["audio"]) == head + tail
+    assert merged["sample_rate_hz"] == 16000
+
+
+# --------------------------------------------------------------------------- #
+# Server VAD + barge_in_on_speech                                             #
+# --------------------------------------------------------------------------- #
+
+
+def test_server_vad_speech_started_reaches_a_barge_in_decision() -> None:
+    """The configuration this PR introduces must decide, not raise.
+
+    Both call sites read the VAD verdict through the module-level
+    ``vad_speech_started`` helper while binding its result to a local of the
+    same name, which made the name local for the whole scope and raised
+    ``UnboundLocalError`` on the call itself. Every ``server_vad`` +
+    ``barge_in_on_speech`` append hit it, and the client saw ``internal_error``
+    instead of a barge-in. The MiniCPM-o preset is ``listen_only``, so no demo
+    exercised this branch.
+    """
+    session = _session(overlap_policy="barge_in_on_speech")
+    payload = {"format": "pcm16", "audio": _pcm16(0.5)}
+    event = {"vad": {"speech_started": True}}
+
+    decision = overlap_policy.decide(session, event, payload, auto_responds=True)
+
+    assert decision["action"] == "barge_in"
+    assert decision["reason"] == "server_vad_speech_started"
+    assert decision["cancel_reason"] == "turn_detected"
+
+
+def test_server_vad_mid_utterance_keeps_listening_instead_of_barging_in() -> None:
+    """``speech_started`` false means the utterance is already running: not a new turn."""
+    session = _session(overlap_policy="barge_in_on_speech")
+    payload = {"format": "pcm16", "audio": _pcm16(0.5)}
+    event = {"vad": {"speech_started": False}}
+
+    decision = overlap_policy.decide(session, event, payload, auto_responds=True)
+
+    assert decision["action"] != "barge_in"
+
+
+def test_barge_in_on_speech_without_vad_still_barges_in_on_speech() -> None:
+    """No VAD verdict: the policy falls back to its own speech classification."""
+    session = _session(overlap_policy="barge_in_on_speech")
+    payload = {"format": "pcm16", "audio": _pcm16(0.5)}
+
+    decision = overlap_policy.decide(session, {}, payload, auto_responds=True)
+
+    assert decision["action"] == "barge_in"
+    assert decision["reason"] == "barge_in_on_speech"
diff --git a/tests/engine/duplex/test_session_manager.py b/tests/engine/duplex/test_session_manager.py
new file mode 100644
index 00000000000..0323f16d8d4
--- /dev/null
+++ b/tests/engine/duplex/test_session_manager.py
@@ -0,0 +1,1569 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""``DuplexSessionManager``: admission, control RPC, command backpressure, reaper and request cleanup."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import logging
+from dataclasses import FrozenInstanceError, dataclass, field
+from typing import Any
+
+import pytest
+
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex.commands import AppendAudio, CloseSession, Commit, DuplexCommand, Heartbeat
+from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig, DuplexSessionState
+from vllm_omni.engine.duplex.contracts import (
+    DuplexAppendPlan,
+    DuplexFence,
+    DuplexStagePort,
+    DuplexStageRequestContext,
+    DuplexStageSubmission,
+    DuplexStageSubmissionResult,
+    duplex_resource_request_belongs_to_session,
+)
+from vllm_omni.engine.duplex.events import (
+    DuplexEvent,
+    ErrorEvent,
+    SessionClosed,
+    SessionCreated,
+    SessionExpired,
+    SessionHeartbeatAck,
+)
+from vllm_omni.engine.duplex.messages import (
+    CloseDuplexSessionMessage,
+    DuplexControlResultMessage,
+    DuplexSessionCommandMessage,
+    DuplexSessionEventMessage,
+    OpenDuplexSessionMessage,
+    ResumeDuplexSessionMessage,
+    TouchDuplexSessionMessage,
+)
+from vllm_omni.engine.duplex.plugin import (
+    DuplexDataPlane,
+    DuplexModelPlugin,
+    DuplexModelSessionState,
+    DuplexRuntimeConfigError,
+    PcmAppendBuffer,
+    PcmAppendReservation,
+)
+from vllm_omni.engine.duplex.session import manager as session_manager_module
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession
+from vllm_omni.engine.duplex.session.lease import DuplexLeaseActivity
+from vllm_omni.engine.duplex.session.manager import DuplexSessionManager
+from vllm_omni.engine.duplex.session.runner import _Internal
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+# --------------------------------------------------------------------------- #
+# Fakes                                                                       #
+# --------------------------------------------------------------------------- #
+
+
+class FakeClock:
+    def __init__(self, value: float = 0.0) -> None:
+        self.value = value
+
+    def __call__(self) -> float:
+        return self.value
+
+    def advance(self, seconds: float) -> None:
+        self.value += seconds
+
+
+class FakePcmAppendBuffer(PcmAppendBuffer):
+    @property
+    def pending_byte_count(self) -> int:
+        return 0
+
+    def clear(self) -> None:
+        pass
+
+    def clear_force_listen(self) -> None:
+        pass
+
+    def has_pending(self) -> bool:
+        return False
+
+    def has_reserved(self) -> bool:
+        return False
+
+    def prepare_append(self, payload, *, operation_id, chunk_period_ms, allow_emit) -> PcmAppendReservation | None:
+        del payload, operation_id, chunk_period_ms, allow_emit
+        return None
+
+    def prepare_commit(self, *, operation_id, chunk_period_ms) -> PcmAppendReservation:
+        del operation_id, chunk_period_ms
+        raise NotImplementedError("fake buffer never commits")
+
+    def flush(self, *, chunk_period_ms) -> dict[str, object] | None:
+        del chunk_period_ms
+        return None
+
+
+class FakeModelSessionState(DuplexModelSessionState):
+    def __init__(self) -> None:
+        self.audio_buffer = FakePcmAppendBuffer()
+        self.input_since_commit = False
+        self.speech_since_commit = False
+        self.context_locked = False
+        self.committed_audio_payload = None
+        self.committed_audio_operation_id = None
+        self.committed_audio_reserved_bytes = 0
+        self.deferred_response_create = False
+        self.deferred_precreate_response = False
+        self.continuation_owner_id = None
+        self.continuation_units = 0
+        self.pending_silence_task = None
+        self.pending_silence_owner_id = None
+
+    def retain_committed_audio(self, payload, *, operation_id, reserved_bytes=0) -> None:
+        self.committed_audio_payload = payload
+        self.committed_audio_operation_id = operation_id
+        self.committed_audio_reserved_bytes = reserved_bytes
+
+    def clear_committed_audio(self) -> int:
+        reserved = self.committed_audio_reserved_bytes
+        self.committed_audio_payload = None
+        self.committed_audio_operation_id = None
+        self.committed_audio_reserved_bytes = 0
+        return reserved
+
+    def clear_continuation(self) -> None:
+        self.continuation_owner_id = None
+        self.continuation_units = 0
+
+
+class FakeDataPlane(DuplexDataPlane):
+    def __init__(self) -> None:
+        self.closed_sessions: list[str] = []
+
+    def begin_request(self, request_id: str) -> None:
+        pass
+
+    def is_terminal(self, request_id: str | None) -> bool:
+        return False
+
+    def mark_terminal(self, request_id: str) -> None:
+        pass
+
+    def close_stream(self, request_id: str) -> None:
+        pass
+
+    def close_session(self, session_id: str, *, active_request_id: str | None = None) -> None:
+        self.closed_sessions.append(session_id)
+
+    def project(self, result, *, context=None):
+        del result, context
+        return []
+
+
+class FakePlugin(DuplexModelPlugin):
+    plugin_id = "fake-duplex"
+
+    def __init__(self, encode_audio=None) -> None:
+        super().__init__(encode_audio or (lambda *args: None))
+        self.data_plane = FakeDataPlane()
+        self.runtime_config: dict[str, object] = {"runtime": "test"}
+        self.runtime_config_error: Exception | None = None
+        #: Session ids whose ``prepare_runtime_config`` waits for ``runtime_config_gate``.
+        self.blocked_session_ids: set[str] = set()
+        self.runtime_config_gate = asyncio.Event()
+        self.runtime_config_started = asyncio.Event()
+
+    def configure_sampling_params(self, *, runtime_config, defaults):
+        del runtime_config
+        return tuple(f"configured-{stage_id}" for stage_id, _ in enumerate(defaults))
+
+    def plan_append(self, **kwargs) -> DuplexAppendPlan:
+        del kwargs
+        return DuplexAppendPlan(prompt={"prompt_token_ids": [1, 2, 3]})
+
+    def decide_output(self, **kwargs):
+        del kwargs
+        return None
+
+    def create_session_state(self) -> DuplexModelSessionState:
+        return FakeModelSessionState()
+
+    def capabilities(self, *, max_sessions: int) -> DuplexCapabilities:
+        del max_sessions
+        return DuplexCapabilities(supports_input_append=True)
+
+    def validate_client_extra_body(self, extra_body: object) -> None:
+        pass
+
+    async def prepare_runtime_config(self, config: DuplexSessionConfig, *, model_config: Any) -> dict[str, object]:
+        del model_config
+        if self.runtime_config_error is not None:
+            raise self.runtime_config_error
+        if config.instructions in self.blocked_session_ids:
+            self.runtime_config_started.set()
+            await self.runtime_config_gate.wait()
+        return dict(self.runtime_config)
+
+    def runtime_config_for_update(self, config, current):
+        del config
+        return dict(current)
+
+    def data_plane_context(self, **kwargs) -> object:
+        return dict(kwargs)
+
+
+class FakeStagePort(DuplexStagePort):
+    def __init__(self, stage_count: int = 2) -> None:
+        self._stage_count = stage_count
+        self.ensure_calls: list[DuplexStageRequestContext] = []
+        self.submit_calls: list[DuplexStageSubmission] = []
+        #: Every cleanup attempt, including the ones that were made to fail.
+        self.cleanup_calls: list[tuple[list[str], bool]] = []
+        self.abort_calls: list[list[str]] = []
+        self.cleanup_failures_remaining = 0
+        self.cleanup_gate: asyncio.Event | None = None
+        self.cleanup_started = asyncio.Event()
+
+    @property
+    def stage_count(self) -> int:
+        return self._stage_count
+
+    def sampling_defaults(self) -> tuple[object, ...]:
+        return tuple(f"default-{stage_id}" for stage_id in range(self._stage_count))
+
+    def ensure_request(self, context: DuplexStageRequestContext) -> None:
+        self.ensure_calls.append(context)
+
+    async def submit(self, submission: DuplexStageSubmission) -> DuplexStageSubmissionResult:
+        self.submit_calls.append(submission)
+        return DuplexStageSubmissionResult(
+            request_id=submission.context.request_id,
+            stage_id=submission.context.stage_id,
+            replica_id=3,
+        )
+
+    async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
+        self.cleanup_calls.append((list(request_ids), abort))
+        self.cleanup_started.set()
+        if self.cleanup_gate is not None:
+            await self.cleanup_gate.wait()
+        if self.cleanup_failures_remaining:
+            self.cleanup_failures_remaining -= 1
+            raise RuntimeError("transient cleanup failure")
+
+    async def abort_requests(self, request_ids: list[str]) -> None:
+        self.abort_calls.append(list(request_ids))
+
+
+# --------------------------------------------------------------------------- #
+# Harness                                                                     #
+# --------------------------------------------------------------------------- #
+
+
+def _runtime_config(**overrides: Any) -> DuplexSessionRuntimeConfig:
+    values: dict[str, Any] = {
+        "idle_ttl_s": 300.0,
+        "disconnect_grace_s": 30.0,
+        "max_sessions": 4,
+        "max_pending_input_bytes_per_session": 1024,
+        "max_pending_turns_per_session": 2,
+    }
+    values.update(overrides)
+    return DuplexSessionRuntimeConfig(**values)
+
+
+def stage0_request_id(session_id: str, *, epoch: int = 0) -> str:
+    encoded = base64.urlsafe_b64encode(session_id.encode("utf-8")).decode("ascii").rstrip("=")
+    return f"duplex-s.{encoded}.e.{epoch}.r.stage0"
+
+
+@dataclass
+class Harness:
+    manager: DuplexSessionManager
+    plugin: FakePlugin
+    stage_port: FakeStagePort
+    clock: FakeClock
+    output_sink: asyncio.Queue = field(default_factory=asyncio.Queue)
+    result_sink: asyncio.Queue = field(default_factory=asyncio.Queue)
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        plugin: FakePlugin | None = None,
+        stage_port: FakeStagePort | None = None,
+        clock: FakeClock | None = None,
+        **runtime_overrides: Any,
+    ) -> Harness:
+        plugin = plugin or FakePlugin()
+        stage_port = stage_port or FakeStagePort()
+        clock = clock or FakeClock()
+        output_sink: asyncio.Queue = asyncio.Queue()
+        result_sink: asyncio.Queue = asyncio.Queue()
+        manager = DuplexSessionManager(
+            plugin=plugin,
+            stage_port=stage_port,
+            output_sink=output_sink,
+            result_sink=result_sink,
+            runtime_config=_runtime_config(**runtime_overrides),
+            model_config=None,
+            clock=clock,
+        )
+        return cls(manager, plugin, stage_port, clock, output_sink, result_sink)
+
+    async def __aenter__(self) -> Harness:
+        return self
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.manager.shutdown()
+
+    async def open(self, session_id: str, config: DuplexSessionConfig | None = None) -> DuplexControlResultMessage:
+        await self.manager.handle(
+            OpenDuplexSessionMessage(
+                control_id=f"open-{session_id}",
+                session_id=session_id,
+                session_config=config or DuplexSessionConfig(model="fake-model"),
+            )
+        )
+        return await self.result()
+
+    async def close(self, session_id: str, *, reason: str = "client_close") -> DuplexControlResultMessage:
+        await self.manager.handle(
+            CloseDuplexSessionMessage(control_id=f"close-{session_id}", session_id=session_id, reason=reason)
+        )
+        return await self.result()
+
+    async def resume(self, session_id: str, *, expected_lease_generation: int) -> DuplexControlResultMessage:
+        await self.manager.handle(
+            ResumeDuplexSessionMessage(
+                control_id=f"resume-{session_id}-{expected_lease_generation}",
+                session_id=session_id,
+                expected_lease_generation=expected_lease_generation,
+            )
+        )
+        return await self.result()
+
+    async def touch(self, session_id: str, activity: str) -> DuplexControlResultMessage:
+        await self.manager.handle(
+            TouchDuplexSessionMessage(
+                control_id=f"touch-{session_id}-{activity}", session_id=session_id, activity=activity
+            )
+        )
+        return await self.result()
+
+    def command(self, session_id: str, command: DuplexCommand) -> None:
+        self.manager.dispatch(DuplexSessionCommandMessage(session_id=session_id, command=command))
+
+    async def result(self) -> DuplexControlResultMessage:
+        result = await asyncio.wait_for(self.result_sink.get(), timeout=2.0)
+        assert isinstance(result, DuplexControlResultMessage)
+        return result
+
+    def events(self, session_id: str | None = None) -> list[DuplexEvent]:
+        events: list[DuplexEvent] = []
+        while not self.output_sink.empty():
+            message = self.output_sink.get_nowait()
+            assert isinstance(message, DuplexSessionEventMessage)
+            assert message.event.session_id == message.session_id
+            if session_id is None or message.session_id == session_id:
+                events.append(message.event)
+        return events
+
+    def session(self, session_id: str) -> DuplexEngineSession:
+        session = self.manager.get(session_id)
+        assert session is not None
+        return session
+
+    def capture_submissions(self, session_id: str) -> list[DuplexCommand]:
+        """Replace the runner mailbox with a list so admitted commands can be inspected."""
+        runner = self.manager.runners[session_id]
+        submitted: list[DuplexCommand] = []
+        runner.submit = submitted.append  # type: ignore[method-assign]
+        return submitted
+
+
+async def _settle() -> None:
+    for _ in range(10):
+        await asyncio.sleep(0)
+
+
+# --------------------------------------------------------------------------- #
+# Open                                                                        #
+# --------------------------------------------------------------------------- #
+
+
+async def test_open_answers_with_capabilities_and_emits_session_created() -> None:
+    async with Harness.create() as harness:
+        config = DuplexSessionConfig(model="fake-model", voice="test")
+        result = await harness.open("sid-open", config)
+
+        assert result.ok is True
+        assert result.operation == "open"
+        assert result.control_id == "open-sid-open"
+        assert result.session_id == "sid-open"
+        assert result.lease_generation == 0
+        assert result.capabilities == DuplexCapabilities(supports_input_append=True)
+        assert result.public_session is not None
+        assert result.public_session["id"] == "sid-open"
+        assert result.public_session["voice"] == "test"
+        assert result.error_code is None
+
+        events = harness.events("sid-open")
+        assert isinstance(events[0], SessionCreated)
+        assert events[0].epoch == 0
+        assert events[0].session["id"] == "sid-open"
+        wire = events[0].to_realtime()
+        assert wire["type"] == "session.created"
+        assert "incarnation" not in wire and "incarnation" not in wire["session"]
+
+        session = harness.session("sid-open")
+        assert session.state == DuplexSessionState.OPEN
+        assert session.runtime_config == {"runtime": "test"}
+        assert isinstance(session.model_state, FakeModelSessionState)
+        assert harness.manager.active_count() == 1
+        assert harness.manager.sessions() == {"sid-open": session}
+
+
+async def test_open_reserves_the_fenced_stage0_request_with_a_frozen_context() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-context", DuplexSessionConfig(model="fake-model", voice="test"))
+
+        request_id = stage0_request_id("sid-context")
+        context = harness.stage_port.ensure_calls[-1]
+        assert isinstance(context, DuplexStageRequestContext)
+        assert context.request_id == request_id
+        assert context.session_id == "sid-context"
+        assert context.fence == DuplexFence("sid-context")
+        assert context.stage_id == 0
+        assert context.final_stage_id == 1
+        assert context.config_generation == 0
+        assert context.sampling_params == ("configured-0", "configured-1")
+        assert context.stage_sampling_params == "configured-0"
+        assert context.session_config["voice"] == "test"
+        assert context.runtime_config == {"runtime": "test"}
+        with pytest.raises(FrozenInstanceError):
+            context.stage_id = 1  # type: ignore[misc]
+
+        session = harness.session("sid-context")
+        assert session.resource_request_ids() == [request_id]
+        assert session.stage_request_submitted(0, request_id) is False
+        assert harness.manager.runner_for_request_id(request_id) is harness.manager.runners["sid-context"]
+        assert harness.stage_port.submit_calls == []
+
+
+def test_stage_request_id_is_derived_from_the_fence() -> None:
+    fence = DuplexFence("sid/with+special", epoch=2, turn_id=5)
+
+    request_id = DuplexSessionManager.stage_request_id(fence, stage_id=0)
+
+    assert request_id == stage0_request_id("sid/with+special", epoch=2)
+    assert duplex_resource_request_belongs_to_session(request_id, "sid/with+special")
+    assert not duplex_resource_request_belongs_to_session(request_id, "sid/other")
+
+
+async def test_ensure_stage_request_ignores_stages_beyond_the_pipeline() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-stages")
+        session = harness.session("sid-stages")
+
+        assert harness.manager.ensure_stage_request(session, stage_id=2) is None
+        context = harness.manager.ensure_stage_request(session, stage_id=1)
+
+        assert context is not None
+        assert context.request_id.endswith(".r.stage1")
+        assert harness.manager.runner_for_request_id(context.request_id) is harness.manager.runners["sid-stages"]
+        assert session.resource_request_ids() == [stage0_request_id("sid-stages"), context.request_id]
+
+
+async def test_sampling_params_for_validates_the_plugin_policy() -> None:
+    class ShortSamplingPlugin(FakePlugin):
+        def configure_sampling_params(self, *, runtime_config, defaults):
+            if runtime_config:
+                return defaults[:1]
+            return tuple(defaults)
+
+    class ListSamplingPlugin(FakePlugin):
+        def configure_sampling_params(self, *, runtime_config, defaults):
+            if runtime_config:
+                return list(defaults)
+            return tuple(defaults)
+
+    async with Harness.create(plugin=ShortSamplingPlugin()) as harness:
+        result = await harness.open("sid-short")
+        assert result.ok is False
+        assert result.error_code == "invalid_argument"
+        assert "one sampling parameter per stage" in str(result.error_message)
+        assert harness.manager.get("sid-short") is None
+        assert harness.manager.active_count() == 0
+
+    async with Harness.create(plugin=ListSamplingPlugin()) as harness:
+        result = await harness.open("sid-list")
+        assert result.ok is False
+        assert result.error_code == "invalid_argument"
+        assert "as a tuple" in str(result.error_message)
+
+
+async def test_duplicate_open_is_rejected_with_session_exists() -> None:
+    async with Harness.create() as harness:
+        assert (await harness.open("sid-dup")).ok is True
+        first_session = harness.session("sid-dup")
+
+        result = await harness.open("sid-dup")
+
+        assert result.ok is False
+        assert result.error_code == "session_exists"
+        assert result.error_retryable is False
+        assert harness.session("sid-dup") is first_session
+        assert harness.manager.active_count() == 1
+        assert len(harness.stage_port.ensure_calls) == 1
+
+
+async def test_capacity_rejection_is_retryable_and_logged_at_info(caplog: pytest.LogCaptureFixture) -> None:
+    manager_logger = session_manager_module.logger
+    manager_logger.addHandler(caplog.handler)
+    try:
+        async with Harness.create(max_sessions=1) as harness:
+            assert (await harness.open("sid-first")).ok is True
+            caplog.clear()
+
+            with caplog.at_level(logging.INFO, logger=manager_logger.name):
+                result = await harness.open("sid-rejected")
+
+            assert result.ok is False
+            assert result.error_code == "resource_exhausted"
+            assert result.error_retryable is True
+            assert harness.manager.get("sid-rejected") is None
+            assert harness.manager.active_count() == 1
+            rejections = [record for record in caplog.records if "rejected" in record.getMessage()]
+            assert rejections and all(record.levelno == logging.INFO for record in rejections)
+            assert not [record for record in caplog.records if record.levelno >= logging.ERROR]
+    finally:
+        manager_logger.removeHandler(caplog.handler)
+
+
+@pytest.mark.parametrize(
+    ("error", "expected_code"),
+    [
+        (ValueError("reference audio not found"), "invalid_duplex_runtime_config"),
+        (DuplexRuntimeConfigError("bad ref", code="unsupported_ref_audio_path"), "unsupported_ref_audio_path"),
+        (DuplexRuntimeConfigError("bad voice", code="invalid_voice"), "invalid_voice"),
+    ],
+)
+async def test_plugin_runtime_config_rejection_rolls_back_the_open(error: Exception, expected_code: str) -> None:
+    plugin = FakePlugin()
+    plugin.runtime_config_error = error
+    async with Harness.create(plugin=plugin) as harness:
+        result = await harness.open("sid-runtime")
+
+        assert result.ok is False
+        assert result.error_code == expected_code
+        assert result.error_message == str(error)
+        assert result.capabilities is None
+        assert harness.manager.get("sid-runtime") is None
+        assert harness.manager.active_count() == 0
+        assert harness.stage_port.ensure_calls == []
+        assert harness.events() == []
+
+        # Nothing was registered under the rejected id and the slot is free again.
+        plugin.runtime_config_error = None
+        assert (await harness.open("sid-runtime")).ok is True
+
+
+# --------------------------------------------------------------------------- #
+# Command dispatch                                                            #
+# --------------------------------------------------------------------------- #
+
+
+async def test_command_for_unknown_session_emits_unknown_session_error() -> None:
+    async with Harness.create() as harness:
+        harness.command("sid-missing", Heartbeat(event_id="evt-hb"))
+
+        events = harness.events("sid-missing")
+        assert len(events) == 1
+        error = events[0]
+        assert isinstance(error, ErrorEvent)
+        assert error.code == "unknown_session"
+        assert error.related_event_id == "evt-hb"
+        assert error.session_id == "sid-missing"
+        assert error.epoch is None
+        assert error.to_realtime()["error"]["code"] == "unknown_session"
+
+
+async def test_command_for_closed_session_emits_unknown_session_error() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-closed")
+        assert (await harness.close("sid-closed")).ok is True
+        harness.events()
+
+        harness.command("sid-closed", Heartbeat(event_id="evt-late"))
+
+        events = harness.events("sid-closed")
+        assert [type(event) for event in events] == [ErrorEvent]
+        assert events[0].code == "unknown_session"
+        assert events[0].related_event_id == "evt-late"
+
+
+async def test_admitted_command_reaches_the_session_runner_in_order() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-runner")
+        harness.events()
+        harness.clock.advance(5.0)
+
+        harness.command("sid-runner", Heartbeat(event_id="evt-1"))
+        harness.command("sid-runner", Heartbeat(event_id="evt-2"))
+        await _settle()
+
+        events = harness.events("sid-runner")
+        assert [type(event) for event in events] == [SessionHeartbeatAck, SessionHeartbeatAck]
+        assert all(event.epoch == 0 for event in events)
+        assert harness.session("sid-runner").lease.last_activity == 5.0
+
+
+async def test_append_audio_is_backpressured_by_pending_input_bytes() -> None:
+    async with Harness.create(max_pending_input_bytes_per_session=8) as harness:
+        await harness.open("sid-bytes")
+        harness.events()
+        session = harness.session("sid-bytes")
+        submitted = harness.capture_submissions("sid-bytes")
+        assert session.reserve_input_bytes(6, limit=8)
+
+        harness.command("sid-bytes", AppendAudio(audio=b"pcm", event_id="evt-over"))
+        harness.command("sid-bytes", AppendAudio(audio=b"pc", event_id="evt-fits"))
+
+        events = harness.events("sid-bytes")
+        assert len(events) == 1
+        assert isinstance(events[0], ErrorEvent)
+        assert events[0].code == "input_backpressure"
+        assert events[0].related_event_id == "evt-over"
+        assert events[0].epoch == 0
+        assert [command.event_id for command in submitted] == ["evt-fits"]
+        # Admission reserved the wire size of the admitted append; the runner
+        # released it on dequeue and re-reserved the decoded size (2 bytes).
+        assert session.pending_input_bytes == 8
+
+
+async def test_commit_holds_a_pending_turn_reservation_until_the_runner_dequeues_it() -> None:
+    async with Harness.create(max_pending_turns_per_session=1) as harness:
+        await harness.open("sid-turns")
+        harness.events()
+        session = harness.session("sid-turns")
+        submitted = harness.capture_submissions("sid-turns")
+
+        harness.command("sid-turns", Commit(event_id="evt-commit-1"))
+        harness.command("sid-turns", Commit(event_id="evt-commit-2"))
+
+        assert [command.event_id for command in submitted] == ["evt-commit-1"]
+        assert session.pending_input_turns == 1
+        events = harness.events("sid-turns")
+        assert len(events) == 1
+        assert isinstance(events[0], ErrorEvent)
+        assert events[0].code == "input_backpressure"
+        assert events[0].related_event_id == "evt-commit-2"
+
+        # The runner releases the reservation when it dequeues the commit.
+        session.release_pending_turn()
+        harness.command("sid-turns", Commit(event_id="evt-commit-3"))
+        assert [command.event_id for command in submitted] == ["evt-commit-1", "evt-commit-3"]
+        assert harness.events("sid-turns") == []
+
+
+def test_accepts_only_duplex_message_types() -> None:
+    manager = DuplexSessionManager(
+        plugin=FakePlugin(),
+        stage_port=FakeStagePort(),
+        output_sink=asyncio.Queue(),
+        result_sink=asyncio.Queue(),
+        runtime_config=_runtime_config(),
+        model_config=None,
+        clock=FakeClock(),
+    )
+    try:
+        config = DuplexSessionConfig()
+        assert manager.accepts(OpenDuplexSessionMessage(control_id="c", session_id="s", session_config=config))
+        assert manager.accepts(CloseDuplexSessionMessage(control_id="c", session_id="s"))
+        assert manager.accepts(ResumeDuplexSessionMessage(control_id="c", session_id="s", expected_lease_generation=0))
+        assert manager.accepts(TouchDuplexSessionMessage(control_id="c", session_id="s", activity="heartbeat"))
+        assert manager.accepts(DuplexSessionCommandMessage(session_id="s", command=Heartbeat()))
+        assert manager.accepts(type("Lookalike", (), {"type": "open_duplex_session", "session_id": "s"})()) is False
+        assert (
+            manager.accepts(DuplexControlResultMessage(control_id="c", operation="open", session_id="s", ok=True))
+            is False
+        )
+        assert manager.accepts(Heartbeat()) is False
+        with pytest.raises(TypeError, match="Unsupported duplex control message"):
+            manager.dispatch(object())
+    finally:
+        manager.executor.shutdown(wait=False)
+
+
+# --------------------------------------------------------------------------- #
+# Close / resume / touch                                                      #
+# --------------------------------------------------------------------------- #
+
+
+async def test_close_releases_stage_resources_and_is_idempotent() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-close")
+        harness.events()
+        session = harness.session("sid-close")
+        request_id = stage0_request_id("sid-close")
+        session.bind_stage_request(0, request_id, fence=session.fence)
+        reserved_context = harness.manager.ensure_stage_request(session, stage_id=1)
+        assert reserved_context is not None
+
+        result = await harness.close("sid-close", reason="client_close")
+
+        assert result.ok is True
+        assert result.operation == "close"
+        assert result.lease_generation == 1
+        assert result.public_session is not None and result.public_session["state"] == "closed"
+        assert session.state == DuplexSessionState.CLOSED
+        assert session.lease.terminal_reason == "client_close"
+        assert session.resource_request_ids() == []
+        assert harness.manager.get("sid-close") is None
+        assert harness.manager.active_count() == 0
+        assert harness.manager.runner_for_request_id(request_id) is None
+        assert harness.stage_port.cleanup_calls == [([request_id], True), ([reserved_context.request_id], False)]
+        assert harness.plugin.data_plane.closed_sessions == ["sid-close"]
+        closed = [event for event in harness.events("sid-close") if isinstance(event, SessionClosed)]
+        assert len(closed) == 1
+        assert closed[0].reason == "client_close"
+        assert closed[0].is_terminal is True
+
+        again = await harness.close("sid-close")
+        assert again.ok is True
+        assert again.lease_generation is None
+        assert again.public_session is None
+        assert harness.stage_port.cleanup_calls[2:] == []
+        assert harness.events() == []
+
+
+async def test_close_retains_the_admission_slot_until_stage_cleanup_succeeds() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-close-retry")
+        session = harness.session("sid-close-retry")
+        session.bind_stage_request(0, stage0_request_id("sid-close-retry"), fence=session.fence)
+        harness.stage_port.cleanup_failures_remaining = 1
+
+        result = await harness.close("sid-close-retry")
+
+        # The session is closed from the client's point of view; only the
+        # stage cleanup is outstanding and the reaper retries it.
+        assert result.ok is True
+        assert harness.manager.get("sid-close-retry") is None
+        assert session.state == DuplexSessionState.CLOSED
+        assert (await harness.open("sid-replacement")).error_code == "resource_exhausted"
+
+        assert await harness.manager.reap_expired() == 1
+        assert harness.stage_port.cleanup_calls == [([stage0_request_id("sid-close-retry")], True)] * 2
+        assert (await harness.open("sid-replacement")).ok is True
+
+
+async def test_resume_requires_the_expected_lease_generation() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-resume")
+        session = harness.session("sid-resume")
+        harness.clock.advance(3.0)
+        assert (await harness.touch("sid-resume", DuplexLeaseActivity.DETACH.value)).ok is True
+        assert session.lease.detached_at == 3.0
+
+        harness.clock.advance(1.0)
+        result = await harness.resume("sid-resume", expected_lease_generation=0)
+
+        assert result.ok is True
+        assert result.operation == "resume"
+        assert result.lease_generation == 1
+        assert result.public_session is not None and result.public_session["id"] == "sid-resume"
+        assert session.lease_generation == 1
+        assert session.lease.detached_at is None
+        assert session.lease.last_activity == 4.0
+
+        stale = await harness.resume("sid-resume", expected_lease_generation=0)
+        assert stale.ok is False
+        assert stale.error_code == "session_resume_conflict"
+        assert stale.lease_generation == 1
+        assert session.lease_generation == 1
+
+        unknown = await harness.resume("sid-unknown", expected_lease_generation=0)
+        assert unknown.ok is False
+        assert unknown.error_code == "unknown_session"
+        assert unknown.lease_generation is None
+
+
+async def test_touch_records_activity_and_detach_marks_the_lease_detached() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-touch")
+        session = harness.session("sid-touch")
+        assert session.lease.last_activity == 0.0
+
+        harness.clock.advance(2.0)
+        result = await harness.touch("sid-touch", DuplexLeaseActivity.HEARTBEAT.value)
+        assert result.ok is True
+        assert result.operation == "touch"
+        assert session.lease.last_activity == 2.0
+        assert session.lease.detached_at is None
+
+        harness.clock.advance(1.0)
+        assert (await harness.touch("sid-touch", DuplexLeaseActivity.DETACH.value)).ok is True
+        assert session.lease.last_activity == 3.0
+        assert session.lease.detached_at == 3.0
+
+        harness.clock.advance(1.0)
+        assert (await harness.touch("sid-touch", DuplexLeaseActivity.ATTACH.value)).ok is True
+        assert session.lease.last_activity == 4.0
+        # Only resume clears a detach.
+        assert session.lease.detached_at == 3.0
+
+        invalid = await harness.touch("sid-touch", "bogus")
+        assert invalid.ok is False
+        assert invalid.error_code == "invalid_argument"
+
+        unknown = await harness.touch("sid-unknown", DuplexLeaseActivity.HEARTBEAT.value)
+        assert unknown.ok is False
+        assert unknown.error_code == "unknown_session"
+        assert harness.stage_port.submit_calls == []
+
+
+# --------------------------------------------------------------------------- #
+# Reaper                                                                      #
+# --------------------------------------------------------------------------- #
+
+
+async def test_reaper_expires_idle_sessions_and_emits_session_expired() -> None:
+    async with Harness.create(idle_ttl_s=2.0, disconnect_grace_s=1.0) as harness:
+        await harness.open("sid-idle")
+        await harness.open("sid-active")
+        harness.events()
+        harness.clock.advance(1.0)
+        assert (await harness.touch("sid-active", DuplexLeaseActivity.HEARTBEAT.value)).ok is True
+        harness.clock.advance(1.1)
+
+        assert await harness.manager.reap_expired() == 1
+
+        assert harness.manager.get("sid-idle") is None
+        assert harness.manager.get("sid-active") is not None
+        assert harness.manager.active_count() == 1
+        expired = harness.events("sid-idle")
+        assert len(expired) == 1
+        assert isinstance(expired[0], SessionExpired)
+        assert expired[0].reason == "idle_ttl_expired"
+        assert expired[0].to_realtime() == {
+            "type": "session.expired",
+            "event_id": expired[0].event_id,
+            "session_id": "sid-idle",
+            "reason": "idle_ttl_expired",
+        }
+        assert harness.events("sid-active") == []
+        assert harness.stage_port.cleanup_calls == [([stage0_request_id("sid-idle")], False)]
+        assert harness.result_sink.empty()
+
+        assert await harness.manager.reap_expired() == 0
+
+
+async def test_reaper_expires_detached_sessions_after_the_disconnect_grace() -> None:
+    async with Harness.create(idle_ttl_s=300.0, disconnect_grace_s=1.0) as harness:
+        await harness.open("sid-detached")
+        harness.events()
+        assert (await harness.touch("sid-detached", DuplexLeaseActivity.DETACH.value)).ok is True
+        harness.clock.advance(0.5)
+        assert await harness.manager.reap_expired() == 0
+        harness.clock.advance(0.5)
+
+        assert await harness.manager.reap_expired() == 1
+
+        assert harness.manager.get("sid-detached") is None
+        expired = harness.events("sid-detached")
+        assert [type(event) for event in expired] == [SessionExpired]
+        assert expired[0].reason == "disconnect_grace_expired"
+        assert (await harness.resume("sid-detached", expected_lease_generation=0)).error_code == "unknown_session"
+
+
+async def test_session_closed_is_emitted_only_after_stage_cleanup_so_a_reopen_is_admitted() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-closing")
+        harness.events()
+        session = harness.session("sid-closing")
+        session.bind_stage_request(0, stage0_request_id("sid-closing"), fence=session.fence)
+        harness.stage_port.cleanup_gate = asyncio.Event()
+
+        close_task = asyncio.create_task(harness.close("sid-closing"))
+        await asyncio.wait_for(harness.stage_port.cleanup_started.wait(), timeout=1.0)
+        # The runner is gone but the stage request is still being aborted:
+        # no session.closed yet, so a client cannot race the admission slot.
+        assert harness.events("sid-closing") == []
+
+        harness.stage_port.cleanup_gate.set()
+        assert (await close_task).ok is True
+        events = harness.events("sid-closing")
+        assert [type(event) for event in events] == [SessionClosed]
+        assert events[0].reason == "client_close"
+        assert (await harness.open("sid-replacement")).ok is True
+
+
+async def test_wire_close_command_frees_the_slot_before_session_closed() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-wire-close")
+        harness.events()
+        session = harness.session("sid-wire-close")
+        request_id = stage0_request_id("sid-wire-close")
+        session.bind_stage_request(0, request_id, fence=session.fence)
+        harness.stage_port.cleanup_gate = asyncio.Event()
+
+        harness.command("sid-wire-close", CloseSession(reason="client_close"))
+        await asyncio.wait_for(harness.stage_port.cleanup_started.wait(), timeout=1.0)
+        assert harness.manager.get("sid-wire-close") is None
+        assert harness.events("sid-wire-close") == []
+
+        harness.stage_port.cleanup_gate.set()
+        for _ in range(50):
+            if harness.manager._admission_count() == 0:
+                break
+            await asyncio.sleep(0.01)
+        assert harness.stage_port.cleanup_calls == [([request_id], True)]
+        events = harness.events("sid-wire-close")
+        assert [type(event) for event in events] == [SessionClosed]
+        assert events[0].reason == "client_close"
+        assert (await harness.open("sid-replacement")).ok is True
+
+
+async def test_wire_close_stops_the_worker_and_refuses_later_control_ops() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-wire")
+        harness.events()
+        runner = harness.manager.runners["sid-wire"]
+        worker = runner._worker
+        assert worker is not None
+        harness.stage_port.cleanup_gate = asyncio.Event()
+
+        harness.command("sid-wire", CloseSession(reason="client_close"))
+        await asyncio.wait_for(harness.stage_port.cleanup_started.wait(), timeout=1.0)
+        # Control operations issued while the close is in flight are refused,
+        # not silently accepted on a half-torn session.
+        resumed = await harness.resume("sid-wire", expected_lease_generation=0)
+        assert resumed.ok is False
+        assert resumed.error_code in {"session_closed", "unknown_session"}
+        harness.command("sid-wire", Heartbeat())
+
+        harness.stage_port.cleanup_gate.set()
+        for _ in range(50):
+            if worker.done() and harness.manager._admission_count() == 0:
+                break
+            await asyncio.sleep(0.01)
+        assert worker.done(), "the mailbox worker must exit after a wire close"
+        events = harness.events("sid-wire")
+        assert [type(event) for event in events] == [ErrorEvent, SessionClosed] or [
+            type(event) for event in events
+        ] == [SessionClosed, ErrorEvent]
+        assert (await harness.open("sid-after")).ok is True
+
+
+async def test_concurrent_opens_cannot_exceed_max_sessions() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        harness.plugin.blocked_session_ids.add("first")
+        first = asyncio.create_task(
+            harness.open("first", DuplexSessionConfig(model="fake-model", instructions="first"))
+        )
+        await asyncio.wait_for(harness.plugin.runtime_config_started.wait(), timeout=1.0)
+
+        # The first open holds the only slot while it awaits the plugin.
+        second = await harness.open("second", DuplexSessionConfig(model="fake-model", instructions="second"))
+        assert second.ok is False
+        assert second.error_code == "resource_exhausted"
+
+        harness.plugin.runtime_config_gate.set()
+        assert (await first).ok is True
+        assert harness.manager.active_count() == 1
+
+
+async def test_runtime_close_without_stage_requests_frees_the_slot() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-runtime")
+        harness.events()
+        runner = harness.manager.runners["sid-runtime"]
+        runner.session.release_all_requests()
+
+        await runner._close_from_runtime("model_failed")
+        for _ in range(50):
+            if harness.manager._admission_count() == 0:
+                break
+            await asyncio.sleep(0.01)
+
+        assert harness.manager.get("sid-runtime") is None
+        assert [type(event) for event in harness.events("sid-runtime")] == [SessionClosed]
+        assert (await harness.open("sid-next")).ok is True
+
+
+async def test_close_of_a_forgotten_session_is_idempotent() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        result = await harness.close("never-opened")
+
+        assert result.ok is True
+
+
+async def test_append_bytes_are_reserved_at_admission_until_the_runner_dequeues() -> None:
+    async with Harness.create(max_sessions=1, max_pending_input_bytes_per_session=8) as harness:
+        await harness.open("sid-bytes")
+        harness.events()
+        session = harness.session("sid-bytes")
+        runner = harness.manager.runners["sid-bytes"]
+        # Park the worker so admitted commands stay in the mailbox.
+        gate = asyncio.Event()
+        runner._mailbox.put_nowait(_Internal("wait", {"gate": gate}))
+        runner._on_internal = lambda item: gate.wait()  # type: ignore[method-assign]
+        await asyncio.sleep(0)
+
+        harness.command("sid-bytes", AppendAudio(audio=b"12345"))
+        assert session.pending_input_bytes == 5
+        harness.command("sid-bytes", AppendAudio(audio=b"12345"))
+        errors = [event for event in harness.events("sid-bytes") if isinstance(event, ErrorEvent)]
+        assert [error.code for error in errors] == ["input_backpressure"]
+        gate.set()
+
+
+async def test_expired_session_retains_the_admission_slot_until_cleanup_succeeds() -> None:
+    async with Harness.create(max_sessions=1, idle_ttl_s=1.0) as harness:
+        await harness.open("sid-expired")
+        harness.events()
+        session = harness.session("sid-expired")
+        request_id = stage0_request_id("sid-expired")
+        session.bind_stage_request(0, request_id, fence=session.fence)
+        harness.stage_port.cleanup_failures_remaining = 1
+        harness.clock.advance(2.0)
+
+        assert await harness.manager.reap_expired() == 0
+
+        assert harness.manager.get("sid-expired") is None
+        assert session.state == DuplexSessionState.CLOSED
+        assert [type(event) for event in harness.events("sid-expired")] == [SessionExpired]
+        assert (await harness.open("sid-replacement")).error_code == "resource_exhausted"
+
+        assert await harness.manager.reap_expired() == 1
+
+        assert harness.stage_port.cleanup_calls == [([request_id], True)] * 2
+        assert session.resource_request_ids() == []
+        assert harness.events("sid-expired") == []
+        assert (await harness.open("sid-replacement")).ok is True
+
+
+async def test_expired_session_holds_the_admission_slot_while_cleanup_is_blocked() -> None:
+    async with Harness.create(max_sessions=1, idle_ttl_s=1.0) as harness:
+        await harness.open("sid-blocked")
+        session = harness.session("sid-blocked")
+        session.bind_stage_request(0, stage0_request_id("sid-blocked"), fence=session.fence)
+        harness.stage_port.cleanup_gate = asyncio.Event()
+        harness.clock.advance(2.0)
+
+        reap_task = asyncio.create_task(harness.manager.reap_expired())
+        await asyncio.wait_for(harness.stage_port.cleanup_started.wait(), timeout=1.0)
+        assert (await harness.open("sid-replacement")).error_code == "resource_exhausted"
+
+        harness.stage_port.cleanup_gate.set()
+        assert await reap_task == 1
+        assert (await harness.open("sid-replacement")).ok is True
+
+
+async def test_expired_cleanup_failure_does_not_block_other_sessions() -> None:
+    class OneStuckStagePort(FakeStagePort):
+        async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
+            await super().cleanup(request_ids, abort=abort)
+            if request_ids == [stage0_request_id("sid-stuck")]:
+                raise RuntimeError("stuck expiry cleanup")
+
+    async with Harness.create(stage_port=OneStuckStagePort(), idle_ttl_s=1.0) as harness:
+        await harness.open("sid-stuck")
+        await harness.open("sid-fine")
+        harness.events()
+        harness.clock.advance(2.0)
+
+        assert await harness.manager.reap_expired() == 1
+
+        assert harness.manager.active_count() == 0
+        assert {type(event) for event in harness.events()} == {SessionExpired}
+        assert (await harness.open("sid-fine")).ok is True
+        assert (await harness.open("sid-stuck")).error_code == "session_exists"
+
+
+# --------------------------------------------------------------------------- #
+# Request-triggered cleanup (orchestrator error paths)                        #
+# --------------------------------------------------------------------------- #
+
+
+async def test_close_sessions_for_request_ids_expires_the_owner_and_retries_cleanup() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-request")
+        harness.events()
+        session = harness.session("sid-request")
+        request_id = stage0_request_id("sid-request")
+        session.bind_stage_request(0, request_id, fence=session.fence)
+        harness.stage_port.cleanup_failures_remaining = 1
+
+        closed = harness.manager.close_sessions_for_request_ids([request_id, "req-unrelated"], abort=True)
+
+        assert closed == {"sid-request": [request_id]}
+        assert harness.manager.get("sid-request") is None
+        assert session.lease.terminal_reason == "request_cleanup"
+        await _settle()
+        expired = harness.events("sid-request")
+        assert [type(event) for event in expired] == [SessionExpired]
+        assert expired[0].reason == "request_cleanup"
+        assert session.state == DuplexSessionState.CLOSED
+        # The stage resources are still owned by the pending cleanup.
+        assert session.resource_request_ids() == [request_id]
+        assert (await harness.open("sid-replacement")).error_code == "resource_exhausted"
+
+        assert await harness.manager.reap_expired() == 0
+        assert harness.stage_port.cleanup_calls == [([request_id], True)]
+        assert (await harness.open("sid-replacement")).error_code == "resource_exhausted"
+
+        assert await harness.manager.reap_expired() == 1
+        assert harness.stage_port.cleanup_calls == [([request_id], True)] * 2
+        assert session.resource_request_ids() == []
+        assert harness.manager.runner_for_request_id(request_id) is None
+        assert (await harness.open("sid-replacement")).ok is True
+        assert harness.manager.close_sessions_for_request_ids([request_id], abort=True) == {}
+
+
+async def test_in_progress_request_cleanup_is_finalized_by_the_orchestrator_not_the_reaper() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-in-progress")
+        session = harness.session("sid-in-progress")
+        request_id = stage0_request_id("sid-in-progress")
+        session.bind_stage_request(0, request_id, fence=session.fence)
+
+        closed = harness.manager.close_sessions_for_request_ids([request_id], abort=True, cleanup_in_progress=True)
+        assert closed == {"sid-in-progress": [request_id]}
+
+        # The orchestrator owns this cleanup: the reaper neither retries nor releases it.
+        assert await harness.manager.reap_expired() == 0
+        assert harness.stage_port.cleanup_calls == []
+        assert (await harness.open("sid-replacement")).error_code == "resource_exhausted"
+
+        harness.manager.finalize_closed_sessions(["sid-in-progress"])
+
+        assert session.resource_request_ids() == []
+        assert session.state == DuplexSessionState.CLOSED
+        assert harness.manager.runner_for_request_id(request_id) is None
+        assert await harness.manager.reap_expired() == 0
+        assert harness.stage_port.cleanup_calls == []
+        assert (await harness.open("sid-replacement")).ok is True
+
+
+async def test_deferred_request_cleanup_is_retried_by_the_reaper() -> None:
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-deferred")
+        session = harness.session("sid-deferred")
+        request_id = stage0_request_id("sid-deferred")
+        session.bind_stage_request(0, request_id, fence=session.fence)
+        harness.manager.close_sessions_for_request_ids([request_id], abort=True, cleanup_in_progress=True)
+        assert await harness.manager.reap_expired() == 0
+        assert harness.stage_port.cleanup_calls == []
+
+        # The orchestrator's own cleanup failed: hand the retry to the reaper.
+        harness.manager.defer_request_cleanups(["sid-deferred"])
+
+        assert await harness.manager.reap_expired() == 1
+        assert harness.stage_port.cleanup_calls == [([request_id], True)]
+        assert session.resource_request_ids() == []
+        assert (await harness.open("sid-replacement")).ok is True
+
+
+async def test_request_cleanup_closes_the_owner_of_any_of_its_stage_requests() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-merge")
+        session = harness.session("sid-merge")
+        stage0 = stage0_request_id("sid-merge")
+        session.bind_stage_request(0, stage0, fence=session.fence)
+        stage1 = harness.manager.ensure_stage_request(session, stage_id=1)
+        assert stage1 is not None
+
+        closed = harness.manager.close_sessions_for_request_ids([stage1.request_id])
+
+        assert closed == {"sid-merge": [stage0, stage1.request_id]}
+        assert harness.manager.close_sessions_for_request_ids([stage0]) == {}
+        assert await harness.manager.reap_expired() == 1
+        assert harness.stage_port.cleanup_calls == [([stage0, stage1.request_id], False)]
+
+
+# --------------------------------------------------------------------------- #
+# Dispatch ordering / shutdown                                                #
+# --------------------------------------------------------------------------- #
+
+
+async def test_control_dispatch_is_ordered_per_session_without_blocking_other_sessions() -> None:
+    plugin = FakePlugin()
+    plugin.blocked_session_ids.add("sid-blocked")
+    async with Harness.create(plugin=plugin) as harness:
+        manager = harness.manager
+        blocked_config = DuplexSessionConfig(model="fake-model", instructions="sid-blocked")
+
+        manager.dispatch(
+            OpenDuplexSessionMessage(control_id="blocked-open", session_id="sid-blocked", session_config=blocked_config)
+        )
+        await asyncio.wait_for(plugin.runtime_config_started.wait(), timeout=1.0)
+        manager.dispatch(
+            TouchDuplexSessionMessage(
+                control_id="blocked-touch",
+                session_id="sid-blocked",
+                activity=DuplexLeaseActivity.HEARTBEAT.value,
+            )
+        )
+        manager.dispatch(
+            OpenDuplexSessionMessage(
+                control_id="independent-open",
+                session_id="sid-independent",
+                session_config=DuplexSessionConfig(model="fake-model"),
+            )
+        )
+        manager.dispatch(
+            TouchDuplexSessionMessage(
+                control_id="independent-touch",
+                session_id="sid-independent",
+                activity=DuplexLeaseActivity.HEARTBEAT.value,
+            )
+        )
+
+        assert [(await harness.result()).control_id for _ in range(2)] == ["independent-open", "independent-touch"]
+        assert harness.result_sink.empty()
+        assert manager.get("sid-blocked") is None
+
+        plugin.runtime_config_gate.set()
+        results = [await harness.result() for _ in range(2)]
+        assert [result.control_id for result in results] == ["blocked-open", "blocked-touch"]
+        assert all(result.ok for result in results)
+        assert manager.active_count() == 2
+
+
+async def test_shutdown_closes_every_runner_and_stops_dispatch_tasks() -> None:
+    harness = Harness.create()
+    await harness.open("sid-a")
+    await harness.open("sid-b")
+    sessions = [harness.session("sid-a"), harness.session("sid-b")]
+    harness.events()
+
+    await harness.manager.shutdown()
+
+    assert harness.manager.active_count() == 0
+    assert harness.manager.runners == {}
+    assert all(session.state == DuplexSessionState.CLOSED for session in sessions)
+    assert harness.manager.runner_for_request_id(stage0_request_id("sid-b")) is None
+    # Shutdown is silent: no session.closed / session.expired is emitted.
+    assert harness.events() == []
+    assert harness.stage_port.cleanup_calls == []
+
+
+def test_manager_rejects_a_plugin_whose_sampling_policy_mismatches_the_stages() -> None:
+    class WrongStageCountPlugin(FakePlugin):
+        def configure_sampling_params(self, *, runtime_config, defaults):
+            del runtime_config
+            return defaults[:1]
+
+    with pytest.raises(ValueError, match="one sampling parameter per stage"):
+        DuplexSessionManager(
+            plugin=WrongStageCountPlugin(),
+            stage_port=FakeStagePort(),
+            output_sink=asyncio.Queue(),
+            result_sink=asyncio.Queue(),
+            runtime_config=_runtime_config(),
+            model_config=None,
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Admission bookkeeping                                                       #
+# --------------------------------------------------------------------------- #
+
+
+async def test_duplicate_open_in_flight_does_not_release_the_first_opens_slot() -> None:
+    """A duplicate id arriving mid-flight must not free the slot the first open holds.
+
+    The rejection runs the same ``finally`` as a successful open, so without a
+    guard it discards an ``_admitting`` entry it never added, and the next open
+    of a *different* id sails past ``max_sessions``. Server-allocated ids make
+    this a guard rather than a live path, which is exactly why a sequential
+    duplicate cannot exercise it.
+    """
+    async with Harness.create(max_sessions=1) as harness:
+        harness.plugin.blocked_session_ids.add("dup")
+        first = asyncio.create_task(harness.open("dup", DuplexSessionConfig(model="fake-model", instructions="dup")))
+        await asyncio.wait_for(harness.plugin.runtime_config_started.wait(), timeout=1.0)
+
+        duplicate = await harness.open("dup", DuplexSessionConfig(model="fake-model", instructions="dup"))
+        assert duplicate.ok is False
+        assert duplicate.error_code == "session_exists"
+
+        # The in-flight open still holds the only slot.
+        overflow = await harness.open("other", DuplexSessionConfig(model="fake-model", instructions="other"))
+        assert overflow.ok is False
+        assert overflow.error_code == "resource_exhausted"
+
+        harness.plugin.runtime_config_gate.set()
+        assert (await first).ok is True
+        assert harness.manager.active_count() == 1
+
+
+async def test_expiry_emits_a_terminal_event_even_when_a_close_deferred_it() -> None:
+    """Every session ends with exactly one terminal event, whoever tears it down.
+
+    A wire ``session.close`` defers its ``session.closed`` to the manager. If a
+    stage failure then takes the runner away from the manager (the orchestrator
+    cleanup path), nobody would emit the deferred event unless ``expire``
+    upgrades it.
+    """
+    async with Harness.create() as harness:
+        await harness.open("sid-deferred")
+        runner = harness.manager.runners["sid-deferred"]
+        # What the runner does for a wire close: tear down, defer the terminal.
+        await runner.close("client_close", emit_closed=False)
+        harness.events("sid-deferred")
+
+        await runner.expire("request_cleanup", emit_expired=True)
+
+        terminal = [
+            event for event in harness.events("sid-deferred") if isinstance(event, SessionClosed | SessionExpired)
+        ]
+        assert len(terminal) == 1, terminal
+        assert isinstance(terminal[0], SessionExpired)
+        assert terminal[0].reason == "request_cleanup"
+
+
+async def test_an_open_abandoned_by_its_caller_does_not_hold_the_admission_slot() -> None:
+    """A control-RPC timeout must not leave the engine holding a session.
+
+    The caller's timeout unregisters its RPC waiter but cannot cancel the
+    manager's open, which is already past the capacity check. Without the
+    compensating close, that session lands, keeps its slot and its Stage0
+    reservation, and with ``max_sessions=1`` the next open is refused until
+    idle expiry.
+    """
+    async with Harness.create(max_sessions=1) as harness:
+        harness.plugin.blocked_session_ids.add("blocked")
+        config = DuplexSessionConfig(model="fake-model", instructions="blocked")
+
+        open_task = asyncio.create_task(harness.open("sid-abandoned", config))
+        await asyncio.wait_for(harness.plugin.runtime_config_started.wait(), timeout=1.0)
+
+        # The caller gave up: DuplexOmni sends the compensating close while the
+        # open is still awaiting the plugin.
+        await harness.close("sid-abandoned", reason="open_abandoned")
+
+        harness.plugin.runtime_config_gate.set()
+        await open_task
+
+        assert "sid-abandoned" not in harness.manager.runners
+        # The slot came back, so a replacement is admitted.
+        assert (await harness.open("sid-replacement")).ok is True
+
+
+async def test_a_runtime_close_racing_a_manager_close_still_emits_one_terminal() -> None:
+    """Two teardown drivers, one terminal event.
+
+    The window is inside ``runner.close()``: ``cancel_append_tasks()`` is awaited
+    *before* the terminal is deferred, so an append task that dies there finds
+    the session merely CLOSING with neither ``closed_emitted`` nor
+    ``closed_deferred`` set, and emits ``session.closed`` itself. The manager
+    decided to emit before any of this and must re-check, or the session ends
+    with two terminal events.
+    """
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-race")
+        harness.events()
+        session = harness.session("sid-race")
+        session.bind_stage_request(0, stage0_request_id("sid-race"), fence=session.fence)
+        runner = harness.manager.runners["sid-race"]
+
+        async def dying_append() -> bool:
+            try:
+                await asyncio.Event().wait()
+            except asyncio.CancelledError:
+                # What AppendAttempt does when its submit fails mid-teardown.
+                await runner._close_from_runtime("runtime_append_task_failed")
+                raise
+            return True
+
+        task = asyncio.ensure_future(dying_append())
+        await asyncio.sleep(0)
+        runner.tasks.track_append_task(task, epoch=session.epoch, final=True, response_bound=True)
+
+        await harness.close("sid-race")
+
+        terminal = [event for event in harness.events("sid-race") if isinstance(event, SessionClosed | SessionExpired)]
+        assert len(terminal) == 1, terminal
+
+
+async def test_a_terminal_event_is_emitted_once_even_if_expiry_runs_twice() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-once")
+        runner = harness.manager.runners["sid-once"]
+
+        await runner.expire("idle_ttl_expired", emit_expired=True)
+        await runner.expire("idle_ttl_expired", emit_expired=True)
+
+        terminal = [event for event in harness.events("sid-once") if isinstance(event, SessionClosed | SessionExpired)]
+        assert len(terminal) == 1, terminal
+
+
+# --------------------------------------------------------------------------- #
+# Resume and takeover lifecycle                                               #
+# --------------------------------------------------------------------------- #
+
+
+async def test_resume_inside_the_grace_window_stops_the_reaper_expiring_the_session() -> None:
+    """Resuming clears the disconnect deadline, not just the lease generation.
+
+    The reaper decides expiry from ``lease.detached_at``. A resume that bumped
+    the generation without clearing it would let the reaper kill a session a
+    client had already come back to.
+    """
+    async with Harness.create(disconnect_grace_s=30.0) as harness:
+        await harness.open("sid-grace")
+        session = harness.session("sid-grace")
+        assert (await harness.touch("sid-grace", DuplexLeaseActivity.DETACH.value)).ok is True
+        harness.clock.advance(10.0)
+
+        assert (await harness.resume("sid-grace", expected_lease_generation=0)).ok is True
+        assert session.lease.detached_at is None
+
+        # Past the original deadline: the session survives because it is attached.
+        harness.clock.advance(25.0)
+        assert await harness.manager.reap_expired() == 0
+        assert harness.manager.get("sid-grace") is not None
+
+
+async def test_resume_after_the_grace_window_reports_unknown_session() -> None:
+    """Once the reaper has expired a detached session, resume has nothing to attach to."""
+    async with Harness.create(disconnect_grace_s=5.0) as harness:
+        await harness.open("sid-late")
+        assert (await harness.touch("sid-late", DuplexLeaseActivity.DETACH.value)).ok is True
+        harness.clock.advance(6.0)
+        assert await harness.manager.reap_expired() == 1
+
+        late = await harness.resume("sid-late", expected_lease_generation=0)
+
+        assert late.ok is False
+        assert late.error_code == "unknown_session"
+
+
+async def test_takeover_invalidates_the_generation_the_replaced_client_held() -> None:
+    """Two clients cannot both hold the session: the first one's generation goes stale.
+
+    This is the engine half of a websocket takeover — the transport picks the
+    winning socket, and the lease generation is what stops the loser from
+    resuming behind it.
+    """
+    async with Harness.create() as harness:
+        await harness.open("sid-takeover")
+        session = harness.session("sid-takeover")
+        assert (await harness.touch("sid-takeover", DuplexLeaseActivity.DETACH.value)).ok is True
+
+        winner = await harness.resume("sid-takeover", expected_lease_generation=0)
+        assert winner.ok is True
+        assert winner.lease_generation == 1
+
+        # The replaced client still believes it holds generation 0.
+        loser = await harness.resume("sid-takeover", expected_lease_generation=0)
+        assert loser.ok is False
+        assert loser.error_code == "session_resume_conflict"
+        assert session.lease_generation == 1
+
+        # The winner can still act on the session it took over.
+        assert (await harness.touch("sid-takeover", DuplexLeaseActivity.HEARTBEAT.value)).ok is True
+
+
+async def test_resume_is_refused_once_a_close_has_begun() -> None:
+    async with Harness.create() as harness:
+        await harness.open("sid-closing")
+        await harness.close("sid-closing")
+
+        resumed = await harness.resume("sid-closing", expected_lease_generation=0)
+
+        assert resumed.ok is False
+        assert resumed.error_code == "unknown_session"
+
+
+async def test_wire_close_of_an_idle_session_still_emits_session_closed() -> None:
+    """The protocol smoke shape: open, send nothing, close.
+
+    A session that never bound a stage request has nothing for the reaper to
+    clean up, so the terminal event is the only thing the client ever gets
+    back for its ``session.close``. Regression guard for a close path that
+    only emitted after a cleanup it never performed.
+    """
+    async with Harness.create(max_sessions=1) as harness:
+        await harness.open("sid-idle-close")
+        harness.events()
+
+        harness.command("sid-idle-close", CloseSession(reason="client_close"))
+        events: list[DuplexEvent] = []
+        for _ in range(200):
+            events.extend(harness.events("sid-idle-close"))
+            if events:
+                break
+            await asyncio.sleep(0.01)
+
+        assert [type(event) for event in events] == [SessionClosed]
+        assert events[0].reason == "client_close"
+        assert harness.manager.get("sid-idle-close") is None
+        assert (await harness.open("sid-idle-replacement")).ok is True
+
+
+# --------------------------------------------------------------------------- #
+# Reaper loop                                                                 #
+# --------------------------------------------------------------------------- #
+
+
+async def test_reaper_loop_waits_between_ticks() -> None:
+    """The loop paces itself; it does not spin on the expiry check.
+
+    Ported from the pre-framework ``Orchestrator._duplex_reaper_loop`` tests:
+    the loop moved to the session manager with the sessions it reaps.
+    """
+    manager = object.__new__(DuplexSessionManager)
+    calls = 0
+
+    async def reap_expired(now: float | None = None) -> int:
+        nonlocal calls
+        calls += 1
+        return 0
+
+    manager.reap_expired = reap_expired  # type: ignore[method-assign]
+    manager.runtime_config = DuplexSessionRuntimeConfig(reaper_interval_s=0.01)
+    shutdown = asyncio.Event()
+
+    task = asyncio.create_task(manager.reaper_loop(shutdown))
+    await asyncio.sleep(0.035)
+    shutdown.set()
+    await asyncio.wait_for(task, timeout=5.0)
+
+    assert 2 <= calls <= 5
+
+
+@pytest.mark.parametrize("first_cleanup_delay", [0.0, 0.05], ids=["immediate", "delayed"])
+async def test_reaper_loop_survives_one_cleanup_failure(first_cleanup_delay: float) -> None:
+    """A failed expiry sweep is retried on the next tick, not fatal to the loop."""
+    recovered = asyncio.Event()
+    calls = 0
+
+    manager = object.__new__(DuplexSessionManager)
+
+    async def reap_expired(now: float | None = None) -> int:
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            await asyncio.sleep(first_cleanup_delay)
+            raise RuntimeError("transient cleanup failure")
+        recovered.set()
+        return 0
+
+    manager.reap_expired = reap_expired  # type: ignore[method-assign]
+    manager.runtime_config = DuplexSessionRuntimeConfig(reaper_interval_s=0.01)
+    shutdown = asyncio.Event()
+
+    task = asyncio.create_task(manager.reaper_loop(shutdown))
+    try:
+        await asyncio.wait_for(recovered.wait(), timeout=5.0)
+        assert calls >= 2
+    finally:
+        shutdown.set()
+        await asyncio.wait_for(task, timeout=5.0)
diff --git a/tests/engine/duplex/test_session_runner.py b/tests/engine/duplex/test_session_runner.py
new file mode 100644
index 00000000000..51711f52a91
--- /dev/null
+++ b/tests/engine/duplex/test_session_runner.py
@@ -0,0 +1,1195 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Engine-resident session runner scenarios (the old serving handler tests, re-homed).
+
+The runner is driven exactly the way ``DuplexOrchestrator`` drives it: typed
+commands go through ``DuplexSessionManager.dispatch``, stage outputs are pushed
+with ``runner.on_stage_output`` and everything the session says is read back
+from the manager's output sink as typed events. The stage port is a recording
+fake; the model plugin is the real MiniCPM-o 4.5 one so append planning and
+output projection are exercised end to end.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import struct
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from types import SimpleNamespace
+from typing import Any
+
+import numpy as np
+import pytest
+from vllm.sampling_params import SamplingParams
+
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex import commands
+from vllm_omni.engine.duplex.commands import DuplexCommand
+from vllm_omni.engine.duplex.config import DuplexSessionConfig, DuplexSessionState
+from vllm_omni.engine.duplex.contracts import (
+    DuplexOutputContext,
+    DuplexRequestIdentity,
+    DuplexStagePort,
+    DuplexStageRequestContext,
+    DuplexStageSubmission,
+    DuplexStageSubmissionResult,
+    duplex_resource_request_id,
+)
+from vllm_omni.engine.duplex.events import DuplexEvent
+from vllm_omni.engine.duplex.messages import (
+    CloseDuplexSessionMessage,
+    DuplexControlResultMessage,
+    DuplexSessionCommandMessage,
+    DuplexSessionEventMessage,
+    OpenDuplexSessionMessage,
+)
+from vllm_omni.engine.duplex.session.manager import DuplexSessionManager
+from vllm_omni.engine.duplex.session.runner import DuplexSessionRunner
+from vllm_omni.metrics.stats import StageRequestStats, StageStats
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.plugin import MiniCPMO45DuplexPlugin
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+SESSION_ID = "duplex-test"
+LISTEN_TOKEN_ID = 7
+
+
+# --------------------------------------------------------------------------- #
+# Fakes                                                                       #
+# --------------------------------------------------------------------------- #
+
+
+class RecordingStagePort(DuplexStagePort):
+    """Records what the runner asks of the orchestrator; never talks to a stage."""
+
+    def __init__(self, *, stage_count: int = 2) -> None:
+        self._stage_count = stage_count
+        self.ensured: list[DuplexStageRequestContext] = []
+        self.submissions: list[DuplexStageSubmission] = []
+        self.cleanups: list[tuple[list[str], bool]] = []
+        self.aborts: list[list[str]] = []
+        self.fail_submit: Exception | None = None
+
+    @property
+    def stage_count(self) -> int:
+        return self._stage_count
+
+    def sampling_defaults(self) -> tuple[object, ...]:
+        return tuple(SamplingParams(max_tokens=8) for _ in range(self._stage_count))
+
+    def ensure_request(self, context: DuplexStageRequestContext) -> None:
+        self.ensured.append(context)
+
+    async def submit(self, submission: DuplexStageSubmission) -> DuplexStageSubmissionResult:
+        if self.fail_submit is not None:
+            raise self.fail_submit
+        self.submissions.append(submission)
+        return DuplexStageSubmissionResult(
+            request_id=submission.context.request_id,
+            stage_id=submission.context.stage_id,
+            replica_id=0,
+        )
+
+    async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
+        self.cleanups.append((list(request_ids), abort))
+
+    async def abort_requests(self, request_ids: list[str]) -> None:
+        self.aborts.append(list(request_ids))
+
+
+def _fake_encode_audio(audio: object, sample_rate_hz: int, response_format: str, speed: float | None) -> str | None:
+    del sample_rate_hz, response_format, speed
+    if audio is None:
+        return None
+    samples = int(np.asarray(audio, dtype=np.float32).size)
+    return f"wav-{samples}" if samples > 0 else None
+
+
+@dataclass
+class Harness:
+    manager: DuplexSessionManager
+    port: RecordingStagePort
+    output: asyncio.Queue[Any]
+    results: asyncio.Queue[Any]
+    runner: DuplexSessionRunner
+    events: list[DuplexEvent] = field(default_factory=list)
+
+    @property
+    def session(self):
+        return self.runner.session
+
+    def submit(self, command: DuplexCommand) -> None:
+        self.manager.dispatch(DuplexSessionCommandMessage(session_id=SESSION_ID, command=command))
+
+    async def settle(self, *, idle_s: float = 0.05, timeout_s: float = 3.0) -> list[DuplexEvent]:
+        """Run the loop until the runner mailbox and append tasks are quiet; return new events."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout_s
+        quiet_since: float | None = None
+        collected: list[DuplexEvent] = []
+        while True:
+            drained = False
+            while not self.output.empty():
+                message = self.output.get_nowait()
+                if isinstance(message, DuplexSessionEventMessage):
+                    collected.append(message.event)
+                    drained = True
+            busy = (
+                drained
+                or not self.runner._mailbox.empty()
+                or any(not task.done() for task in self.runner.tasks.append_tasks)
+                or any(not task.done() for task in self.runner._background_tasks)
+            )
+            now = loop.time()
+            if busy:
+                quiet_since = None
+            elif quiet_since is None:
+                quiet_since = now
+            elif now - quiet_since >= idle_s:
+                break
+            if now >= deadline:
+                break
+            await asyncio.sleep(0.005)
+        self.events.extend(collected)
+        return collected
+
+    async def run(self, command: DuplexCommand) -> list[DuplexEvent]:
+        self.submit(command)
+        return await self.settle()
+
+    def deliver(
+        self,
+        output: object,
+        *,
+        stage_id: int = 1,
+        segment_finished: bool = False,
+        segment_output_metadata: dict[str, Any] | None = None,
+        segment_token_ids: Sequence[int] = (),
+        epoch: int | None = None,
+        metrics: Any = None,
+    ) -> bool:
+        session = self.session
+        fence = session.fence if epoch is None else session.fence.__class__(SESSION_ID, epoch=epoch)
+        context = DuplexOutputContext(
+            identity=DuplexRequestIdentity(session_id=SESSION_ID, fence=fence),
+            final_stage_id=self.port.stage_count - 1,
+            segment_finished=segment_finished,
+            segment_token_ids=tuple(segment_token_ids),
+            segment_output_metadata=dict(segment_output_metadata or {}),
+        )
+        return self.runner.on_stage_output(stage_id, output, metrics, request_id=output.request_id, context=context)
+
+    async def deliver_and_settle(self, output: object, **kwargs: Any) -> list[DuplexEvent]:
+        self.deliver(output, **kwargs)
+        return await self.settle()
+
+    def stage0_request_id(self, epoch: int | None = None) -> str:
+        fence = self.session.fence if epoch is None else self.session.fence.__class__(SESSION_ID, epoch=epoch)
+        return duplex_resource_request_id(fence, "stage0")
+
+
+async def open_harness(
+    *,
+    auto_response: bool = True,
+    modalities: Sequence[str] = ("text",),
+    extra_body: dict[str, object] | None = None,
+    runtime_config: DuplexSessionRuntimeConfig | None = None,
+    stage_count: int = 2,
+    clock: Any = None,
+) -> Harness:
+    plugin = MiniCPMO45DuplexPlugin(_fake_encode_audio)
+    port = RecordingStagePort(stage_count=stage_count)
+    output: asyncio.Queue[Any] = asyncio.Queue()
+    results: asyncio.Queue[Any] = asyncio.Queue()
+    manager = DuplexSessionManager(
+        plugin=plugin,
+        stage_port=port,
+        output_sink=output,
+        result_sink=results,
+        runtime_config=runtime_config or DuplexSessionRuntimeConfig(),
+        model_config=None,
+        clock=clock,
+    )
+    body: dict[str, object] = {"auto_response": auto_response, **(extra_body or {})}
+    config = DuplexSessionConfig(
+        model="openbmb/MiniCPM-o-4_5",
+        modalities=list(modalities),
+        instructions="You are a concise assistant.",
+        extra_body=body,
+    )
+    await manager.handle(OpenDuplexSessionMessage(control_id="c-open", session_id=SESSION_ID, session_config=config))
+    result = await asyncio.wait_for(results.get(), timeout=2.0)
+    assert isinstance(result, DuplexControlResultMessage) and result.ok, result
+    harness = Harness(manager=manager, port=port, output=output, results=results, runner=manager.runners[SESSION_ID])
+    await harness.settle()
+    return harness
+
+
+async def close_harness(harness: Harness) -> None:
+    await harness.manager.shutdown()
+
+
+# --------------------------------------------------------------------------- #
+# Payload / output builders                                                   #
+# --------------------------------------------------------------------------- #
+
+
+def pcm_f32(samples: int, *, value: float = 0.05) -> bytes:
+    return struct.pack(f"<{samples}f", *([value] * samples))
+
+
+def append_audio(
+    samples: int = 16000,
+    *,
+    value: float = 0.05,
+    is_speech: bool | None = True,
+    event_id: str | None = None,
+) -> commands.AppendAudio:
+    return commands.AppendAudio(
+        audio=pcm_f32(samples, value=value),
+        format="pcm_f32le",
+        sample_rate_hz=16000,
+        is_speech=is_speech,
+        event_id=event_id,
+    )
+
+
+def stage_stats(
+    *,
+    stage_id: int,
+    request_id: str,
+    num_tokens_out: int,
+    itls_ms: list[float] | None = None,
+) -> StageRequestStats:
+    """The per-request stats the orchestrator hands to the runner with an output."""
+    return StageRequestStats(
+        batch_id=0,
+        batch_size=1,
+        num_tokens_in=7,
+        num_tokens_out=num_tokens_out,
+        stage_gen_time_ms=120.0,
+        rx_transfer_bytes=0,
+        rx_decode_time_ms=0.0,
+        rx_in_flight_time_ms=0.0,
+        stage_stats=StageStats(),
+        stage_id=stage_id,
+        request_id=request_id,
+        final_output_type="text",
+        vllm_itls_ms=list(itls_ms or []),
+    )
+
+
+def tts_output(
+    request_id: str,
+    *,
+    samples: int = 24000,
+    finished: bool = False,
+    text: str = "hello",
+    tts_is_last_chunk: bool = False,
+    turn_end: bool = False,
+    turn_id: int = 0,
+    epoch: int = 0,
+) -> SimpleNamespace:
+    """A Stage1 (TTS) output the way the orchestrator hands it to the runner."""
+    return SimpleNamespace(
+        request_id=request_id,
+        finished=finished,
+        outputs=[SimpleNamespace(text=text, token_ids=[], multimodal_output={})],
+        multimodal_output={
+            "audio": np.zeros(samples, dtype=np.float32),
+            "sr": 24000,
+            "meta.tts_is_last_chunk": np.array([int(tts_is_last_chunk)], dtype=np.int32),
+            "meta.turn_end": np.array([int(turn_end)], dtype=np.int32),
+            "meta.duplex_turn_id": np.array([turn_id], dtype=np.int32),
+            "meta.duplex_epoch": np.array([epoch], dtype=np.int32),
+        },
+    )
+
+
+def listen_output(request_id: str) -> SimpleNamespace:
+    """A finished Stage0 segment that ends with the listen token."""
+    return SimpleNamespace(
+        request_id=request_id,
+        finished=True,
+        outputs=[
+            SimpleNamespace(
+                text="",
+                token_ids=[11, 12, LISTEN_TOKEN_ID],
+                stop_reason=LISTEN_TOKEN_ID,
+                multimodal_output={},
+            )
+        ],
+        multimodal_output={"meta.listen_token_id": LISTEN_TOKEN_ID},
+    )
+
+
+def types(events: Sequence[DuplexEvent]) -> list[str]:
+    return [event.type for event in events]
+
+
+def find(events: Sequence[DuplexEvent], wire_type: str) -> DuplexEvent:
+    for event in events:
+        if event.type == wire_type:
+            return event
+    raise AssertionError(f"no {wire_type!r} in {types(events)}")
+
+
+def b64(data: bytes) -> str:
+    return base64.b64encode(data).decode("ascii")
+
+
+# --------------------------------------------------------------------------- #
+# Session lifecycle                                                           #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_open_announces_the_session_and_reserves_the_stage0_request() -> None:
+    h = await open_harness()
+    try:
+        assert types(h.events) == ["session.created", "session.updated"]
+        created = h.events[0]
+        assert created.session_id == SESSION_ID
+        assert created.session["id"] == SESSION_ID
+        assert created.session["capabilities"]["supports_input_append"] is True
+        assert created.to_realtime()["type"] == "session.created"
+        assert "incarnation" not in created.to_realtime()
+        assert h.session.state == DuplexSessionState.OPEN
+        # Admission reserves the resumable Stage0 request atomically with the open.
+        assert [context.request_id for context in h.port.ensured] == [h.stage0_request_id(epoch=0)]
+        assert h.stage0_request_id(epoch=0) == "duplex-s.ZHVwbGV4LXRlc3Q.e.0.r.stage0"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_close_emits_session_closed_and_releases_stage_requests() -> None:
+    h = await open_harness()
+    await h.run(append_audio())
+    request_id = h.stage0_request_id()
+    await h.manager.handle(
+        CloseDuplexSessionMessage(control_id="c-close", session_id=SESSION_ID, reason="client_close")
+    )
+    result = await asyncio.wait_for(h.results.get(), timeout=2.0)
+    events = await h.settle()
+
+    assert result.ok and result.operation == "close"
+    assert types(events) == ["session.closed"]
+    assert events[0].reason == "client_close"
+    assert events[0].is_terminal
+    assert h.session.state == DuplexSessionState.CLOSED
+    assert h.port.cleanups == [([request_id], True)]
+    assert SESSION_ID not in h.manager.runners
+    await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_idle_expiry_emits_session_expired() -> None:
+    clock = {"now": 100.0}
+    h = await open_harness(runtime_config=DuplexSessionRuntimeConfig(idle_ttl_s=1.0), clock=lambda: clock["now"])
+    clock["now"] += 2.0
+    assert await h.manager.reap_expired() == 1
+    events = await h.settle()
+
+    assert types(events) == ["session.expired"]
+    assert events[0].reason == "idle_ttl_expired"
+    assert events[0].is_terminal
+    assert SESSION_ID not in h.manager.runners
+    assert not h.manager._closing
+    await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_commands_for_a_closed_session_are_answered_with_unknown_session() -> None:
+    h = await open_harness()
+    await h.manager.handle(CloseDuplexSessionMessage(control_id="c-close", session_id=SESSION_ID, reason="bye"))
+    await h.results.get()
+    await h.settle()
+
+    h.submit(commands.Heartbeat(event_id="evt-late"))
+    events = await h.settle()
+
+    assert types(events) == ["error"]
+    assert events[0].code == "unknown_session"
+    assert events[0].related_event_id == "evt-late"
+    await close_harness(h)
+
+
+# --------------------------------------------------------------------------- #
+# Input path                                                                  #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_append_plans_and_submits_one_model_unit_in_wire_order() -> None:
+    h = await open_harness()
+    try:
+        events = await h.run(append_audio())
+        assert types(events) == ["input_audio_buffer.speech_started"]
+        assert len(h.port.submissions) == 1
+        first = h.port.submissions[0]
+        assert first.context.request_id == h.stage0_request_id(epoch=0)
+        assert first.context.stage_id == 0
+        assert first.already_submitted is False
+        duplex = first.prompt["model_intermediate_buffer"]["duplex"]
+        assert duplex["session_id"] == SESSION_ID
+        assert (duplex["epoch"], duplex["seq"], duplex["turn_id"], duplex["turn_seq"]) == (0, 1, 0, 1)
+        assert duplex["final"] is False
+        assert "incarnation" not in duplex
+        assert len(base64.b64decode(duplex["payload"]["audio"])) == 16000 * 4
+        assert duplex["payload"]["is_speech"] is True
+        assert h.session.input_seq == 1
+        assert h.session.stage_request_submitted(0, first.context.request_id)
+
+        await h.run(append_audio())
+        second = h.port.submissions[1]
+        assert second.already_submitted is True
+        assert second.prompt["model_intermediate_buffer"]["duplex"]["seq"] == 2
+        assert h.session.input_seq == 2
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_partial_units_are_buffered_until_a_whole_chunk_is_available() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio(samples=8000))
+        assert h.port.submissions == []
+        assert h.runner.model_state.audio_buffer.has_pending()
+
+        await h.run(append_audio(samples=8000))
+        assert len(h.port.submissions) == 1
+        assert not h.runner.model_state.audio_buffer.has_pending()
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_input_backpressure_is_rejected_before_the_buffer_is_touched() -> None:
+    h = await open_harness(runtime_config=DuplexSessionRuntimeConfig(max_pending_input_bytes_per_session=1000))
+    try:
+        events = await h.run(append_audio(event_id="evt-big"))
+        assert types(events) == ["error"]
+        assert events[0].code == "input_backpressure"
+        assert events[0].related_event_id == "evt-big"
+        assert h.port.submissions == []
+        assert not h.runner.model_state.audio_buffer.has_pending()
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_text_append_is_not_supported_by_the_native_runtime() -> None:
+    h = await open_harness()
+    try:
+        events = await h.run(commands.AppendText(text="hello", event_id="evt-text"))
+        assert types(events) == ["error"]
+        assert events[0].code == "native_text_append_unsupported"
+        assert events[0].related_event_id == "evt-text"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_clear_input_drops_buffered_audio() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio(samples=8000))
+        assert h.runner.model_state.audio_buffer.has_pending()
+        events = await h.run(commands.ClearInput())
+        assert types(events) == ["input_audio_buffer.cleared"]
+        assert not h.runner.model_state.audio_buffer.has_pending()
+        assert h.session.pending_input_bytes == 0
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_commit_without_audio_is_rejected() -> None:
+    h = await open_harness()
+    try:
+        events = await h.run(commands.Commit(event_id="evt-commit"))
+        assert types(events) == ["error"]
+        assert events[0].code == "input_audio_buffer_empty"
+        assert events[0].related_event_id == "evt-commit"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_commit_projects_the_user_item_and_does_not_resubmit_consumed_audio() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        events = await h.run(commands.Commit())
+        assert types(events) == [
+            "input_audio_buffer.speech_stopped",
+            "conversation.item.added",
+            "conversation.item.created",
+            "input_audio_buffer.committed",
+            "conversation.item.done",
+        ]
+        committed = find(events, "input_audio_buffer.committed")
+        assert committed.item_id == find(events, "conversation.item.added").item_id
+        # The unit already reached Stage0; a commit is only a turn marker here.
+        assert len(h.port.submissions) == 1
+        assert h.session.input_commit_seq == 1
+        assert h.session.history[-1]["role"] == "user"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_heartbeat_touches_the_lease_and_acks() -> None:
+    clock = {"now": 100.0}
+    h = await open_harness(clock=lambda: clock["now"])
+    try:
+        clock["now"] = 150.0
+        events = await h.run(commands.Heartbeat())
+        assert types(events) == ["session.heartbeat_ack"]
+        assert h.session.lease.last_activity == 150.0
+    finally:
+        await close_harness(h)
+
+
+# --------------------------------------------------------------------------- #
+# Model output path                                                           #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_stage1_audio_opens_a_response_and_streams_deltas() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+
+        events = await h.deliver_and_settle(tts_output(request_id, samples=24000, text="he"))
+        assert types(events) == [
+            "response.created",
+            "conversation.item.added",
+            "conversation.item.created",
+            "response.output_item.added",
+            "response.speak",
+            "response.content_part.added",
+            "response.output_audio.delta",
+            "response.output_audio_transcript.delta",
+        ]
+        response_id = find(events, "response.created").response_id
+        assert response_id == h.session.active_response_id
+        assert h.session.active_request_id == request_id
+        delta = find(events, "response.output_audio.delta")
+        assert (delta.delta, delta.format, delta.sample_rate_hz) == ("wav-24000", "wav", 24000)
+        assert delta.response_id == response_id
+        assert find(events, "response.output_audio_transcript.delta").delta == "he"
+        assert h.session.playback.sent_ms == 1000
+
+        # Cumulative Stage1 audio is sliced to the new samples only.
+        events = await h.deliver_and_settle(tts_output(request_id, samples=48000, text="hello"))
+        assert types(events) == ["response.output_audio.delta", "response.output_audio_transcript.delta"]
+        assert find(events, "response.output_audio.delta").delta == "wav-24000"
+        assert find(events, "response.output_audio_transcript.delta").delta == "llo"
+        assert h.session.playback.sent_ms == 2000
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_turn_end_completes_the_response_and_advances_the_model_turn() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hello"))
+
+        events = await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hello", turn_end=True))
+        assert types(events) == [
+            "response.output_audio.done",
+            "response.output_audio_transcript.done",
+            "response.content_part.done",
+            "response.output_item.done",
+            "conversation.item.done",
+            "response.done",
+            "rate_limits.updated",
+        ]
+        done = find(events, "response.done")
+        assert done.status == "completed"
+        assert find(events, "response.output_audio_transcript.done").transcript == "hello"
+        assert h.session.active_response_id is None
+        assert h.session.turn_id == 1
+        # Ack-only playback: the assistant text enters history on playback ack.
+        assert h.session.history == ()
+
+        ack = await h.run(commands.AckPlayback(played_ms=1000, response_id=done.response_id))
+        assert types(ack) == ["playback.acknowledged"]
+        assert ack[0].details["history_committed"] is True
+        assert ack[0].details["playback"]["committed_ms"] == 1000
+        assert h.session.history == ({"role": "assistant", "content": "hello"},)
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_playback_ack_for_an_unknown_response_is_rejected() -> None:
+    h = await open_harness()
+    try:
+        events = await h.run(commands.AckPlayback(played_ms=10, response_id="resp-unknown", event_id="evt-ack"))
+        assert types(events) == ["error"]
+        assert events[0].code == "playback_item_not_found"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_stale_epoch_output_is_dropped_after_barge_in() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, text="he"))
+
+        events = await h.run(commands.BargeIn())
+        assert h.session.epoch == 1
+        assert h.session.active_response_id is None
+        assert h.port.aborts == [[request_id]]
+        assert h.port.cleanups == [([request_id], True)]
+        done = find(events, "response.done")
+        assert done.status == "cancelled"
+        assert types(events)[: types(events).index("response.done")] == [
+            "response.output_audio.done",
+            "response.output_audio_transcript.done",
+            "response.content_part.done",
+            "response.output_item.done",
+            "conversation.item.done",
+        ]
+
+        late = tts_output(request_id, samples=48000, text="hello", epoch=0)
+        assert h.deliver(late, epoch=0) is True  # consumed, never forwarded
+        assert await h.settle() == []
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_cancel_response_without_active_response_is_rejected() -> None:
+    h = await open_harness()
+    try:
+        events = await h.run(commands.CancelResponse(event_id="evt-cancel"))
+        assert types(events) == ["error"]
+        assert events[0].code == "response_not_active"
+        assert events[0].related_event_id == "evt-cancel"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_cancel_response_aborts_the_stage_request_and_reports_playback() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hello"))
+        await h.run(commands.AckPlayback(played_ms=400, response_id=h.session.active_response_id))
+
+        events = await h.run(commands.CancelResponse())
+        done = find(events, "response.done")
+        assert done.status == "cancelled"
+        assert done.response["status_details"]["reason"] == "client_cancelled"
+        assert h.port.aborts == [[request_id]]
+        assert h.session.epoch == 1
+        # Only the played prefix of the cancelled answer is kept in history.
+        assert h.session.history == ({"role": "assistant", "content": "he"},)
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_listen_decision_is_consumed_and_never_forwarded_to_tts() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        # An unfinished Stage0 segment is plain text for the TTS stage: forwarded.
+        text_output = SimpleNamespace(
+            request_id=request_id,
+            finished=False,
+            outputs=[SimpleNamespace(text="hi", token_ids=[11], multimodal_output={})],
+            multimodal_output={},
+        )
+        assert h.deliver(text_output, stage_id=0) is False
+
+        consumed = h.deliver(
+            listen_output(request_id),
+            stage_id=0,
+            segment_finished=True,
+            segment_token_ids=[11, 12, LISTEN_TOKEN_ID],
+            segment_output_metadata={"meta.listen_token_id": LISTEN_TOKEN_ID},
+        )
+        events = await h.settle()
+        assert consumed is True
+        assert types(events) == ["response.listen"]
+        assert events[0].details["reason"] == "model_listen"
+        assert events[0].details["model_listen"] is True
+        assert events[0].to_realtime()["response"]["status"] == "listening"
+        assert h.session.active_response_id is None
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_listen_decision_on_a_resumable_request_closes_the_bounded_response() -> None:
+    """A live stage-0 request is resumable: its output never says ``finished``,
+    only its segment does. The listen that answers the last continuation unit
+    must still close the response, or the session sits forever with no
+    terminal event (the live-client E2E hang)."""
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hello"))
+        response_id = h.session.active_response_id
+        assert response_id is not None
+        # The continuation budget is spent: the unit being answered was the forced listen.
+        model_state = h.runner.model_state
+        model_state.continuation_owner_id = f"response:{response_id}"
+        model_state.continuation_units = h.runner.model._AUTO_RESPONSE_MAX_CONTINUATION_UNITS
+
+        listen = listen_output(request_id)
+        listen.finished = False
+        events = await h.deliver_and_settle(
+            listen,
+            stage_id=0,
+            segment_finished=True,
+            segment_token_ids=[11, 12, LISTEN_TOKEN_ID],
+            segment_output_metadata={"meta.listen_token_id": LISTEN_TOKEN_ID},
+        )
+
+        assert types(events)[0] == "response.listen"
+        assert events[0].details["model_listen"] is True
+        assert find(events, "response.done").response_id == response_id
+        assert h.session.active_response_id is None
+        assert model_state.continuation_units == 0
+        assert len(h.port.submissions) == 1  # no further silence unit was scheduled
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_listen_decision_on_a_resumable_request_keeps_the_turn_going() -> None:
+    """Same unfinished listen, budget left: it must schedule the next unit.
+
+    A non-terminal auto-response listen is answered with the next silence
+    unit, not with a ``response.listen`` event, so the submission is the
+    observable. Before the fix the projector saw ``finished=False`` and
+    yielded nothing: no silence unit, the response left open with nothing in
+    flight -- the same hang, one unit earlier.
+    """
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hello"))
+        response_id = h.session.active_response_id
+        assert response_id is not None
+        submissions_before = len(h.port.submissions)
+
+        listen = listen_output(request_id)
+        listen.finished = False
+        events = await h.deliver_and_settle(
+            listen,
+            stage_id=0,
+            segment_finished=True,
+            segment_token_ids=[11, 12, LISTEN_TOKEN_ID],
+            segment_output_metadata={"meta.listen_token_id": LISTEN_TOKEN_ID},
+        )
+
+        assert not [event for event in events if event.type == "error"], types(events)
+        assert len(h.port.submissions) == submissions_before + 1, "the next silence unit was not scheduled"
+        assert h.runner.model_state.continuation_units == 1
+        assert h.session.active_response_id == response_id
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_tts_segment_end_schedules_a_silence_continuation_unit() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hello"))
+        await h.deliver_and_settle(
+            tts_output(request_id, samples=48000, text="hello", tts_is_last_chunk=True, finished=True)
+        )
+
+        assert len(h.port.submissions) == 2
+        silence = h.port.submissions[1]
+        assert silence.already_submitted is True
+        duplex = silence.prompt["model_intermediate_buffer"]["duplex"]
+        assert duplex["seq"] == 2
+        assert duplex["payload"]["duplex_turn_id"] == 0
+        assert set(base64.b64decode(duplex["payload"]["audio"])) == {0}
+        assert h.runner.model_state.continuation_units == 1
+        # The response stays open across the segment boundary.
+        assert h.session.active_response_id is not None
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_stage_failure_fails_the_active_response() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hello"))
+
+        h.runner.on_stage_failure(1, RuntimeError("boom"))
+        events = await h.settle()
+        assert types(events)[0] == "error"
+        assert events[0].code == "runtime_data_plane_stream_failed"
+        done = find(events, "response.done")
+        assert done.status == "failed"
+        assert done.response["status_details"]["reason"] == "runtime_data_plane_stream_failed"
+        assert h.session.active_response_id is None
+    finally:
+        await close_harness(h)
+
+
+# --------------------------------------------------------------------------- #
+# Turn mode (no auto response)                                                #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_turn_mode_skips_silent_chunks() -> None:
+    h = await open_harness(auto_response=False)
+    try:
+        events = await h.run(append_audio(is_speech=False, value=0.0))
+        assert types(events) == ["response.listen"]
+        assert events[0].details["reason"] == "silence_or_noise"
+        assert h.port.submissions == []
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_turn_mode_commit_with_response_create_starts_one_response() -> None:
+    h = await open_harness(auto_response=False)
+    try:
+        events = await h.run(append_audio())
+        assert types(events) == ["input_audio_buffer.speech_started"]
+        assert h.port.submissions == []  # buffered until the commit
+
+        events = await h.run(commands.Commit(create_response=True))
+        assert "input_audio_buffer.committed" in types(events)
+        assert "response.created" in types(events)
+        assert len(h.port.submissions) == 1
+        final = h.port.submissions[0]
+        assert final.prompt["model_intermediate_buffer"]["duplex"]["final"] is True
+        request_id = final.context.request_id
+        response_id = h.session.active_response_id
+        assert response_id is not None
+
+        events = await h.deliver_and_settle(tts_output(request_id, samples=24000, text="sure"))
+        assert types(events)[-2:] == ["response.output_audio.delta", "response.output_audio_transcript.delta"]
+        events = await h.deliver_and_settle(tts_output(request_id, samples=24000, text="sure", finished=True))
+        done = find(events, "response.done")
+        assert done.response_id == response_id
+        assert done.status == "completed"
+        assert h.session.active_response_id is None
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_response_create_with_no_input_at_all_is_rejected() -> None:
+    """Nothing committed and no items: refuse rather than emit an empty turn."""
+    h = await open_harness(auto_response=False)
+    try:
+        events = await h.run(commands.CreateResponse(event_id="evt-resp"))
+        assert types(events) == ["error"]
+        assert events[0].code == "response_create_without_input"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_an_item_only_response_create_is_refused_not_left_hanging() -> None:
+    """Items are context, not a turn, and the refusal must be immediate.
+
+    A model-native model decides to speak from the audio it hears, so a turn
+    with no audio in it is one it never answers. Opening a response anyway
+    submits work that never completes, and the caller only finds out when the
+    session idles out -- observed as a 300-second HTTP 500 against a real
+    server. Refusing costs the same information and none of the wait.
+    """
+    h = await open_harness(auto_response=False)
+    try:
+        await h.run(
+            commands.CreateItem(
+                item={
+                    "id": "item_prompt",
+                    "type": "message",
+                    "role": "user",
+                    "content": [{"type": "input_text", "text": "What is 2+2?"}],
+                }
+            )
+        )
+        events = await h.run(commands.CreateResponse(event_id="evt-resp"))
+        assert types(events) == ["error"], events
+        assert events[0].code == "text_only_turn_unsupported"
+        assert not h.port.submissions, "nothing may be submitted for a turn the model cannot answer"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_conversation_items_are_consumed_by_the_turn_they_start() -> None:
+    """The items belong to the turn that answered them, not to the next one.
+
+    Without this, a session that once received an item would let every later
+    ``response.create`` start an empty turn off the same stale input.
+    """
+    h = await open_harness(auto_response=False)
+    try:
+        await h.run(
+            commands.CreateItem(
+                item={
+                    "id": "item_hi",
+                    "type": "message",
+                    "role": "user",
+                    "content": [{"type": "input_text", "text": "hi"}],
+                }
+            )
+        )
+        assert h.session.unanswered_user_items() == 1
+        # Consumed by the response.create that refused them: a later one must
+        # not see the same stale input and refuse for a second time.
+        await h.run(commands.CreateResponse(event_id="evt-first"))
+        assert h.session.unanswered_user_items() == 0
+        events = await h.run(commands.CreateResponse(event_id="evt-second"))
+        assert events[0].code == "response_create_without_input"
+    finally:
+        await close_harness(h)
+
+
+# --------------------------------------------------------------------------- #
+# Session update and conversation items                                       #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_session_update_rejects_instruction_changes_after_the_context_is_locked() -> None:
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        assert h.runner.model_state.context_locked
+        events = await h.run(commands.UpdateSession(patch={"instructions": "changed"}, event_id="evt-upd"))
+        assert types(events) == ["error"]
+        assert events[0].code == "instructions_update_unsupported"
+        assert events[0].related_event_id == "evt-upd"
+        assert h.session.config.instructions == "You are a concise assistant."
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_session_update_replaces_config_and_runtime_config_together() -> None:
+    h = await open_harness()
+    try:
+        generation = h.session.config_generation
+        events = await h.run(commands.UpdateSession(patch={"temperature": 0.3}))
+        assert types(events) == ["session.updated"]
+        assert events[0].session["temperature"] == 0.3
+        assert h.session.config.temperature == 0.3
+        assert h.session.runtime_config["duplex_stage_sampling_params"]["0"]["temperature"] == 0.3
+        assert h.session.config_generation == generation + 2
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_conversation_items_can_be_injected_and_deleted() -> None:
+    h = await open_harness()
+    try:
+        item = {"id": "item_hist", "type": "message", "role": "user", "content": [{"type": "input_text", "text": "hi"}]}
+        events = await h.run(commands.CreateItem(item=item))
+        assert types(events) == ["conversation.item.added", "conversation.item.created", "conversation.item.done"]
+        assert h.session.history == ({"role": "user", "content": "hi"},)
+
+        events = await h.run(commands.DeleteItem(item_id="item_hist"))
+        assert types(events) == ["conversation.item.deleted"]
+        assert h.session.history == ()
+
+        events = await h.run(commands.DeleteItem(item_id="item_missing", event_id="evt-del"))
+        assert types(events) == ["error"]
+        assert events[0].code == "item_not_found"
+    finally:
+        await close_harness(h)
+
+
+def _stage_metrics_of(event: object) -> dict[str, dict[str, object]]:
+    """Per-stage engine metrics as the client reads them off one wire event."""
+    payload = event.to_realtime()
+    metadata = payload.get("metadata")
+    assert isinstance(metadata, dict), payload
+    vllm_omni = metadata.get("vllm_omni")
+    assert isinstance(vllm_omni, dict), metadata
+    stage_metrics = vllm_omni.get("stage_metrics")
+    assert isinstance(stage_metrics, dict), vllm_omni
+    return stage_metrics
+
+
+@pytest.mark.asyncio
+async def test_stage0_metrics_reach_the_response_even_though_its_output_feeds_tts() -> None:
+    """A pass-through Stage0 output still has to report its tokens.
+
+    Stage0 text with no decision is forwarded to the TTS stage rather than
+    consumed, and before sessions moved into the engine the orchestrator
+    published its metrics separately. Returning ``False`` here must not also
+    throw the metrics away, or every response reports no engine token count and
+    the benchmark cannot compute TPOT.
+    """
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        text_output = SimpleNamespace(
+            request_id=request_id,
+            finished=False,
+            outputs=[SimpleNamespace(text="hi", token_ids=[11], multimodal_output={})],
+            multimodal_output={},
+        )
+        forwarded = h.deliver(
+            text_output,
+            stage_id=0,
+            metrics=stage_stats(stage_id=0, request_id=request_id, num_tokens_out=3, itls_ms=[9.0, 11.0]),
+        )
+        assert forwarded is False
+        assert await h.settle() == []
+
+        events = await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hi"))
+        stage_metrics = _stage_metrics_of(find(events, "response.output_audio.delta"))
+        assert stage_metrics["0"]["num_tokens_out"] == 3
+        assert stage_metrics["0"]["vllm_itls_ms"] == [9.0, 11.0]
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_stage0_metrics_from_several_units_are_summed_into_one_response() -> None:
+    """Two pass-through segments before the first audio are one response's tokens."""
+    h = await open_harness()
+    try:
+        await h.run(append_audio())
+        request_id = h.stage0_request_id()
+        for tokens in (3, 4):
+            h.deliver(
+                SimpleNamespace(
+                    request_id=request_id,
+                    finished=False,
+                    outputs=[SimpleNamespace(text="hi", token_ids=[11], multimodal_output={})],
+                    multimodal_output={},
+                ),
+                stage_id=0,
+                metrics=stage_stats(stage_id=0, request_id=request_id, num_tokens_out=tokens),
+            )
+        assert await h.settle() == []
+
+        events = await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hi"))
+        stage_metrics = _stage_metrics_of(find(events, "response.output_audio.delta"))
+        assert stage_metrics["0"]["num_tokens_out"] == 7
+    finally:
+        await close_harness(h)
+
+
+# --------------------------------------------------------------------------- #
+# Server VAD                                                                  #
+# --------------------------------------------------------------------------- #
+
+
+class _ScriptedDetector:
+    """A turn detector that answers each appended chunk with a pre-decided result."""
+
+    def __init__(self, results: list[object]) -> None:
+        self._results = list(results)
+        self.resets = 0
+
+    def process(self, base64_audio: str, *, fmt: str, sample_rate_hz: int | None, audio_end_ms: int | None = None):
+        del base64_audio, fmt, sample_rate_hz, audio_end_ms
+        return self._results.pop(0)
+
+    def reset(self) -> None:
+        self.resets += 1
+
+
+def _speech_then_stop() -> _ScriptedDetector:
+    from vllm_omni.engine.duplex.turn_detection import TurnDetectionResult
+
+    return _ScriptedDetector(
+        [
+            TurnDetectionResult(is_speech=True, speech_active=True, speech_started=True, speech_probability=0.9),
+            TurnDetectionResult(
+                is_speech=False,
+                speech_active=False,
+                speech_stopped=True,
+                speech_probability=0.05,
+                should_commit=True,
+                create_response=True,
+            ),
+        ]
+    )
+
+
+def _final_submissions(h: Harness) -> list[object]:
+    return [s for s in h.port.submissions if s.prompt["model_intermediate_buffer"]["duplex"].get("final") is True]
+
+
+@pytest.mark.asyncio
+async def test_server_vad_speech_stopped_does_not_end_the_turn_of_an_auto_response_session() -> None:
+    """A model-native session keeps its turn open past the detector's stop.
+
+    Committing at ``speech_stopped`` cut the utterance short: the model
+    listened on that early final unit, the trailing silence became a second,
+    near-empty turn, and the client's own commit answered nothing (the
+    server-VAD hard-interrupt E2E timed out waiting for the follow-up
+    response). The old translator synthesized that commit for turn-based
+    server VAD only.
+    """
+    h = await open_harness()
+    try:
+        h.runner.control._detector = _speech_then_stop()
+        first = await h.run(append_audio())
+        assert "input_audio_buffer.speech_started" in types(first)
+        # A partial unit, like the trailing silence of a real utterance: it is
+        # what a commit here would submit as the turn's final append.
+        second = await h.run(append_audio(samples=8000, is_speech=False, value=0.0))
+        assert "input_audio_buffer.speech_stopped" in types(second)
+        assert "input_audio_buffer.committed" not in types(first) + types(second)
+        assert _final_submissions(h) == [], "the detector must not close a model-native turn"
+
+        events = await h.run(commands.Commit())
+        assert types(events).count("input_audio_buffer.committed") == 1
+        assert len(_final_submissions(h)) == 1, "the client's commit closes the turn exactly once"
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_server_vad_speech_stopped_still_commits_a_turn_mode_session() -> None:
+    """Turn-based server VAD keeps the contract the old translator implemented."""
+    h = await open_harness(auto_response=False)
+    try:
+        h.runner.control._detector = _speech_then_stop()
+        await h.run(append_audio())
+        events = await h.run(append_audio(is_speech=False, value=0.0))
+        assert "input_audio_buffer.speech_stopped" in types(events)
+        assert "input_audio_buffer.committed" in types(events)
+        assert len(_final_submissions(h)) == 1, "the detector's stop commits the turn and starts the response"
+    finally:
+        await close_harness(h)
diff --git a/tests/engine/duplex/test_vad_backend.py b/tests/engine/duplex/test_vad_backend.py
new file mode 100644
index 00000000000..8a22259acb4
--- /dev/null
+++ b/tests/engine/duplex/test_vad_backend.py
@@ -0,0 +1,379 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The engine-side Silero VAD: backend selection and endpoint rules.
+
+The endpoint rules are the part worth pinning hardest. They were reimplemented
+when turn detection moved into the engine, and drifted from upstream's
+``ThresholdEndpointPolicy`` in two ways that only show up mid-utterance: a loud
+frame used to cancel an in-progress silence timer, and ``audio_end_ms`` used to
+exclude the trailing silence OpenAI says it should include. The parity cases
+below hold upstream's own outputs, so neither can come back unnoticed.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import sys
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+
+from vllm_omni.engine.duplex.turn_detection import validate_realtime_turn_detection
+from vllm_omni.engine.duplex.vad import (
+    SILERO_VAD_SHA256,
+    ServerVADUnavailableError,
+    SileroStreamingVAD,
+    SileroVADBackend,
+    SileroVADBackendProvider,
+    SileroVADConfig,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+FRAME = 512
+SAMPLE_RATE_HZ = 16_000
+
+
+def _drive(config: SileroVADConfig, probabilities: list[float]) -> list[tuple[str, int | None]]:
+    """Feed one probability per frame and collect the endpoint events."""
+    scores = iter(probabilities)
+    vad = SileroStreamingVAD(config, frame_scorer=lambda _frame: next(scores))
+    events: list[tuple[str, int | None]] = []
+    for _ in probabilities:
+        result = vad.process(np.zeros(FRAME, dtype=np.float32))
+        if result.speech_started:
+            events.append(("start", result.speech_start_ms))
+        if result.speech_stopped:
+            events.append(("stop", result.speech_end_ms))
+    return events
+
+
+# --------------------------------------------------------------------------- #
+# Parity with the serving-side policy this was ported from                    #
+# --------------------------------------------------------------------------- #
+
+#: Probability sequences with the endpoint events upstream's
+#: ``ThresholdEndpointPolicy`` produced for them, captured from
+#: ``entrypoints/duplex/server_vad.py`` at `e2d2617f` before that module was
+#: removed. Golden rather than computed because the oracle no longer ships: the
+#: serving layer is transport only, so the VAD it used to carry is gone. Any
+#: drift in the engine's rules still breaks these.
+_PARITY_CASES = {
+    "one utterance": (
+        [0.0, 0.9, 0.9, 0.9, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0],
+        {"threshold": 0.5, "prefix_padding_ms": 0, "silence_duration_ms": 100, "min_speech_duration_ms": 32},
+        [("start", 32), ("stop", 256)],
+    ),
+    "prefix padding reaches back": (
+        [0.0, 0.9, 0.9, 0.0, 0.0, 0.0, 0.0],
+        {"threshold": 0.5, "prefix_padding_ms": 300, "silence_duration_ms": 64, "min_speech_duration_ms": 32},
+        [("start", 0), ("stop", 160)],
+    ),
+    "loud frames inside the silence timer": (
+        [0.9, 0.9, 0.1, 0.45, 0.1, 0.1, 0.1],
+        {"threshold": 0.5, "prefix_padding_ms": 0, "silence_duration_ms": 96, "min_speech_duration_ms": 32},
+        [("start", 0), ("stop", 160)],
+    ),
+    "min speech duration rejects a blip": (
+        [0.9, 0.0, 0.9, 0.9, 0.9, 0.0, 0.0, 0.0, 0.0],
+        {"threshold": 0.5, "prefix_padding_ms": 0, "silence_duration_ms": 64, "min_speech_duration_ms": 96},
+        [("start", 64), ("stop", 224)],
+    ),
+    "negative threshold floor at a low threshold": (
+        [0.9, 0.9, 0.1, 0.1, 0.1, 0.1],
+        {"threshold": 0.16, "prefix_padding_ms": 0, "silence_duration_ms": 64, "min_speech_duration_ms": 32},
+        [("start", 0)],
+    ),
+}
+
+
+@pytest.mark.parametrize(("probabilities", "options", "expected"), _PARITY_CASES.values(), ids=list(_PARITY_CASES))
+def test_endpoint_decisions_match_the_serving_side_policy(
+    probabilities: list[float],
+    options: dict[str, object],
+    expected: list[tuple[str, int | None]],
+) -> None:
+    """The engine detector reproduces the policy server VAD shipped with upstream."""
+    assert _drive(SileroVADConfig(**options), probabilities) == expected
+
+
+# --------------------------------------------------------------------------- #
+# The two rules that had drifted                                              #
+# --------------------------------------------------------------------------- #
+
+
+def test_a_loud_frame_does_not_restart_the_silence_timer() -> None:
+    """Silero v6.2 hysteresis: once silence is running, a loud frame only delays it.
+
+    The frame at 0.45 sits above the negative threshold (0.35) but below the
+    activation threshold. It must not cancel the pending endpoint, or a speaker
+    who trails off unevenly never gets their turn committed.
+    """
+    config = SileroVADConfig(threshold=0.5, prefix_padding_ms=0, silence_duration_ms=96, min_speech_duration_ms=32)
+    assert _drive(config, [0.9, 0.9, 0.1, 0.45, 0.1, 0.1]) == [("start", 0), ("stop", 160)]
+
+
+def test_audio_end_ms_includes_the_trailing_silence() -> None:
+    """OpenAI defines audio_end_ms as the end of the audio sent to the model.
+
+    That includes the silence spent deciding the turn was over, so it is the
+    frame boundary the detector stopped on, not where speech last was.
+    """
+    config = SileroVADConfig(threshold=0.5, prefix_padding_ms=0, silence_duration_ms=100, min_speech_duration_ms=32)
+    events = _drive(config, [0.0, 0.9, 0.9, 0.9, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0])
+    stop_ms = next(ms for kind, ms in events if kind == "stop")
+    # 8 frames consumed when the timer expires: 8 * 512 / 16 kHz = 256 ms.
+    assert stop_ms == 256
+
+
+def test_reset_keeps_the_session_clock_and_clamps_the_prefix() -> None:
+    """A barge-in resets the detector but not the session's timeline.
+
+    Timestamps have to stay comparable with the rest of the session, and prefix
+    padding must not reach back into audio the reset discarded.
+    """
+    config = SileroVADConfig(threshold=0.5, prefix_padding_ms=300, silence_duration_ms=64, min_speech_duration_ms=32)
+    scores = iter([0.0] * 10 + [0.9, 0.9, 0.9])
+    vad = SileroStreamingVAD(config, frame_scorer=lambda _frame: next(scores))
+    for _ in range(10):
+        vad.process(np.zeros(FRAME, dtype=np.float32))
+
+    stream_start_ms = round(10 * FRAME * 1000 / SAMPLE_RATE_HZ)
+    vad.reset()
+    result = vad.process(np.zeros(FRAME * 3, dtype=np.float32))
+
+    assert result.speech_started
+    # Without the clock the start would land at 0; without the clamp, 300 ms of
+    # prefix would reach back before the reset.
+    assert result.speech_start_ms == stream_start_ms
+
+
+# --------------------------------------------------------------------------- #
+# Input handling                                                              #
+# --------------------------------------------------------------------------- #
+
+
+def _pcm16_b64(samples: np.ndarray) -> str:
+    return base64.b64encode((samples * 32767).astype("<i2").tobytes()).decode("ascii")
+
+
+def test_pcm16_input_is_accepted_alongside_float32() -> None:
+    config = SileroVADConfig(threshold=0.5)
+    tone = np.zeros(FRAME * 2, dtype=np.float32)
+    seen: list[int] = []
+    vad = SileroStreamingVAD(config, frame_scorer=lambda frame: seen.append(frame.size) or 0.0)
+    vad.process_base64(_pcm16_b64(tone), fmt="pcm16", sample_rate_hz=SAMPLE_RATE_HZ)
+    assert seen == [FRAME, FRAME]
+
+
+def test_an_odd_pcm16_byte_count_is_rejected() -> None:
+    vad = SileroStreamingVAD(SileroVADConfig(), frame_scorer=lambda _frame: 0.0)
+    with pytest.raises(ValueError, match="incomplete pcm16"):
+        vad.process_base64(base64.b64encode(b"\x00\x01\x02").decode(), fmt="pcm16", sample_rate_hz=SAMPLE_RATE_HZ)
+
+
+def test_resampling_keeps_the_frame_grid_from_drifting() -> None:
+    """The 24 kHz remainder carries across chunks, so frame boundaries cannot drift.
+
+    This is a weaker claim than upstream's ``StreamingAudioResampler``: the
+    interpolation is per chunk, so values near a chunk edge differ slightly.
+    What must hold is the frame *count* and alignment, which is what the
+    endpoint timestamps are derived from.
+    """
+    source = np.sin(np.linspace(0, 40 * np.pi, 24_000, dtype=np.float32))
+
+    def frames_for(chunk_sizes: list[int]) -> int:
+        frames = 0
+
+        def count(_frame: np.ndarray) -> float:
+            nonlocal frames
+            frames += 1
+            return 0.0
+
+        vad = SileroStreamingVAD(SileroVADConfig(), frame_scorer=count)
+        offset = 0
+        for size in chunk_sizes:
+            vad.process_base64(_pcm16_b64(source[offset : offset + size]), fmt="pcm16", sample_rate_hz=24_000)
+            offset += size
+        assert offset == source.size
+        return frames
+
+    whole = frames_for([source.size])
+    split = frames_for([7, 13, 511, 512, 513, source.size - 1_556])
+    assert whole == split == 16_000 // FRAME
+
+
+def test_a_sample_rate_change_mid_stream_is_rejected() -> None:
+    vad = SileroStreamingVAD(SileroVADConfig(), frame_scorer=lambda _frame: 0.0)
+    chunk = _pcm16_b64(np.zeros(1_024, dtype=np.float32))
+    vad.process_base64(chunk, fmt="pcm16", sample_rate_hz=24_000)
+    with pytest.raises(ValueError, match="sample rate cannot change"):
+        vad.process_base64(chunk, fmt="pcm16", sample_rate_hz=48_000)
+
+
+# --------------------------------------------------------------------------- #
+# Backend selection                                                           #
+# --------------------------------------------------------------------------- #
+
+
+def test_a_configured_model_path_that_does_not_exist_is_an_error() -> None:
+    """An operator who names an artifact gets told it is missing, not a fallback."""
+    provider = SileroVADBackendProvider(model_path="/nonexistent/silero_vad.onnx")
+    with pytest.raises(ServerVADUnavailableError, match="does not exist"):
+        provider.get()
+
+
+def test_a_configured_model_with_the_wrong_checksum_is_refused(tmp_path) -> None:
+    """A different Silero revision changes endpointing, so the pin is enforced."""
+    impostor = tmp_path / "silero_vad.onnx"
+    impostor.write_bytes(b"not the pinned model")
+    provider = SileroVADBackendProvider(model_path=str(impostor))
+    with pytest.raises(ServerVADUnavailableError, match="checksum mismatch"):
+        provider.get()
+    assert hashlib.sha256(impostor.read_bytes()).hexdigest() != SILERO_VAD_SHA256
+
+
+def test_the_onnx_backend_is_shared_by_every_session() -> None:
+    """One ONNX session for the whole engine: its state is passed in, not held."""
+    provider = SileroVADBackendProvider()
+    try:
+        backend = provider.get()
+    except ServerVADUnavailableError as exc:
+        pytest.skip(f"no Silero backend available here: {exc}")
+    if not isinstance(backend, SileroVADBackend):
+        pytest.skip("no local ONNX artifact; the torch fallback is per-session by design")
+
+    assert provider.get() is backend
+    # State is the caller's, so two sessions on one backend cannot interfere.
+    first, second = backend.new_state(), backend.new_state()
+    assert first is not second
+    probability, next_state = backend.infer(np.zeros(FRAME, dtype=np.float32), first)
+    assert 0.0 <= probability <= 1.0
+    assert next_state is not first
+
+
+def test_the_onnx_backend_holds_the_upstream_silero_v62_contract(monkeypatch, tmp_path) -> None:
+    """Pin the ONNX call shape without needing the real artifact or runtime.
+
+    The context carry is the part worth pinning: Silero v6.2 is fed 64 samples
+    of the previous frame ahead of the current 512, and that tail travels in the
+    caller's state rather than inside the session -- which is exactly what lets
+    one session serve every duplex session at once.
+    """
+    sessions: list[FakeInferenceSession] = []
+
+    class FakeSessionOptions:
+        inter_op_num_threads = 0
+        intra_op_num_threads = 0
+
+    class FakeInferenceSession:
+        def __init__(self, path: str, *, providers: list[str], sess_options: object) -> None:
+            self.providers = providers
+            self.sess_options = sess_options
+            self.calls: list[dict[str, np.ndarray]] = []
+            self.run_barrier: threading.Barrier | None = None
+            sessions.append(self)
+
+        def get_inputs(self) -> list[SimpleNamespace]:
+            return [SimpleNamespace(name=name) for name in ("input", "state", "sr")]
+
+        def run(self, _outputs: object, inputs: dict[str, np.ndarray]) -> list[np.ndarray]:
+            self.calls.append({name: np.array(value, copy=True) for name, value in inputs.items()})
+            if self.run_barrier is not None:
+                self.run_barrier.wait(timeout=5)
+            return [
+                np.asarray([[0.75]], dtype=np.float32),
+                np.full((2, 1, 128), len(self.calls), dtype=np.float32),
+            ]
+
+    monkeypatch.setitem(
+        sys.modules,
+        "onnxruntime",
+        SimpleNamespace(SessionOptions=FakeSessionOptions, InferenceSession=FakeInferenceSession),
+    )
+
+    model_path = tmp_path / "silero_vad.onnx"
+    model_path.write_bytes(b"fake-model")
+    backend = SileroVADBackend(model_path)
+    session = sessions[0]
+
+    # Single-threaded on purpose: many sessions share this one ORT session, so
+    # it must not fan out per call.
+    assert session.providers == ["CPUExecutionProvider"]
+    assert session.sess_options.inter_op_num_threads == 1
+    assert session.sess_options.intra_op_num_threads == 1
+    # Warm-up already ran: 64 context + 512 frame.
+    assert session.calls[0]["input"].shape == (1, 576)
+    assert session.calls[0]["state"].shape == (2, 1, 128)
+    assert session.calls[0]["sr"].item() == SAMPLE_RATE_HZ
+
+    state = backend.new_state()
+    first_frame = np.arange(backend.frame_samples, dtype=np.float32)
+    probability, state = backend.infer(first_frame, state)
+    first_call = session.calls[1]
+
+    assert probability == pytest.approx(0.75)
+    np.testing.assert_array_equal(
+        first_call["input"][:, : backend.context_samples],
+        np.zeros((1, backend.context_samples), dtype=np.float32),
+    )
+    np.testing.assert_array_equal(first_call["input"][:, backend.context_samples :], first_frame[None, :])
+
+    second_frame = -first_frame
+    backend.infer(second_frame, state)
+    second_call = session.calls[2]
+    # The previous frame's tail becomes this frame's context.
+    np.testing.assert_array_equal(
+        second_call["input"][:, : backend.context_samples],
+        first_frame[None, -backend.context_samples :],
+    )
+    np.testing.assert_array_equal(second_call["state"], np.full((2, 1, 128), 2, dtype=np.float32))
+
+    # Two sessions may enter the shared ORT session at the same time.
+    session.run_barrier = threading.Barrier(2)
+    with ThreadPoolExecutor(max_workers=2) as executor:
+        futures = [
+            executor.submit(backend.infer, first_frame, backend.new_state()),
+            executor.submit(backend.infer, second_frame, backend.new_state()),
+        ]
+        assert [future.result()[0] for future in futures] == pytest.approx([0.75, 0.75])
+
+
+# --------------------------------------------------------------------------- #
+# Session payload validation                                                  #
+# --------------------------------------------------------------------------- #
+
+
+def test_an_unknown_server_vad_field_is_refused() -> None:
+    """A misspelled knob that silently does nothing is worse than a refusal.
+
+    The endpointing would still look configured while running on defaults.
+    """
+    error = validate_realtime_turn_detection({"turn_detection": {"type": "server_vad", "semantic_eagerness": "high"}})
+    assert error is not None
+    assert "semantic_eagerness" in error
+
+
+def test_the_documented_server_vad_fields_are_all_accepted() -> None:
+    assert (
+        validate_realtime_turn_detection(
+            {
+                "turn_detection": {
+                    "type": "server_vad",
+                    "threshold": 0.6,
+                    "prefix_padding_ms": 200,
+                    "silence_duration_ms": 400,
+                    "create_response": True,
+                    "interrupt_response": True,
+                    "min_speech_duration_ms": 120,
+                },
+                "overlap_policy": "barge_in_on_speech",
+            }
+        )
+        is None
+    )
diff --git a/tests/engine/test_async_omni_engine_abort_ack.py b/tests/engine/test_async_omni_engine_abort_ack.py
index 86276ec6634..43a29bf3ae7 100644
--- a/tests/engine/test_async_omni_engine_abort_ack.py
+++ b/tests/engine/test_async_omni_engine_abort_ack.py
@@ -54,7 +54,7 @@ def test_abort_async_waits_for_ack(mocker: MockerFixture):
     rpc_q: queue.Queue = queue.Queue()
     engine = _make_engine(request_q, rpc_q)
     mocker.patch(
-        "vllm_omni.engine.async_omni_engine.uuid.uuid4",
+        "vllm_omni.engine.omni_engine_base.uuid.uuid4",
         return_value=SimpleNamespace(hex="abort-rpc-1"),
     )
 
@@ -81,7 +81,7 @@ def test_abort_async_raises_on_orchestrator_error(mocker: MockerFixture):
     rpc_q: queue.Queue = queue.Queue()
     engine = _make_engine(request_q, rpc_q)
     mocker.patch(
-        "vllm_omni.engine.async_omni_engine.uuid.uuid4",
+        "vllm_omni.engine.omni_engine_base.uuid.uuid4",
         return_value=SimpleNamespace(hex="abort-rpc-err"),
     )
 
@@ -109,7 +109,7 @@ def test_abort_async_times_out_without_result(mocker: MockerFixture):
     rpc_q: queue.Queue = queue.Queue()
     engine = _make_engine(request_q, rpc_q)
     mocker.patch(
-        "vllm_omni.engine.async_omni_engine.uuid.uuid4",
+        "vllm_omni.engine.omni_engine_base.uuid.uuid4",
         return_value=SimpleNamespace(hex="abort-rpc-timeout"),
     )
 
@@ -139,7 +139,7 @@ def put(self, item, block=True, timeout=None):
     rpc_q: queue.Queue = queue.Queue()
     engine = _make_engine(request_q, rpc_q)
     mocker.patch(
-        "vllm_omni.engine.async_omni_engine.uuid.uuid4",
+        "vllm_omni.engine.omni_engine_base.uuid.uuid4",
         return_value=SimpleNamespace(hex="blocked-abort"),
     )
 
diff --git a/tests/engine/test_async_omni_engine_outputs.py b/tests/engine/test_async_omni_engine_outputs.py
index 6b0d6a188d0..425a16fc1b1 100644
--- a/tests/engine/test_async_omni_engine_outputs.py
+++ b/tests/engine/test_async_omni_engine_outputs.py
@@ -7,7 +7,6 @@
 subsequent attempts to collect output raise RuntimeError.
 """
 
-import asyncio
 import queue
 import threading
 from concurrent.futures import ThreadPoolExecutor
@@ -18,16 +17,6 @@
 
 from vllm_omni.engine.async_engine_utils import weak_shutdown_async_omni_engine
 from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
-from vllm_omni.engine.duplex.control_client import (
-    DuplexControlClient,
-    DuplexControlRequestError,
-)
-from vllm_omni.engine.duplex.messages import (
-    AppendDuplexInputMessage,
-    DuplexControlResultMessage,
-    DuplexFence,
-    SignalDuplexTurnMessage,
-)
 from vllm_omni.engine.messages import (
     CollectiveRPCResultMessage,
     ErrorMessage,
@@ -166,9 +155,9 @@ def test_output_remains_on_shared_output_path(mocker: MockerFixture):
     raw_queue = queue.Queue()
     raw_queue.put_nowait(
         OutputMessage(
-            request_id="legacy-duplex-request",
+            request_id="shared-path-request",
             stage_id=0,
-            engine_outputs=OmniRequestOutput(request_id="legacy-duplex-request"),
+            engine_outputs=OmniRequestOutput(request_id="shared-path-request"),
             finished=False,
         )
     )
@@ -176,293 +165,7 @@ def test_output_remains_on_shared_output_path(mocker: MockerFixture):
 
     output = engine.try_get_output(timeout=0.01)
 
-    assert output.request_id == "legacy-duplex-request"
-
-
-def test_duplex_control_client_uses_engine_owned_correlated_transport():
-    engine = object.__new__(AsyncOmniEngine)
-    engine._duplex_control_client = None
-    engine._correlated_rpc_client = CorrelatedRpcClient(queue.Queue(), queue.Queue())
-
-    try:
-        client = engine._get_duplex_control_client()
-
-        assert isinstance(client, DuplexControlClient)
-        assert client._transport is engine._correlated_rpc_client
-        assert not hasattr(engine, "_submit_rpc_and_wait")
-    finally:
-        engine._correlated_rpc_client.close()
-
-
-def test_duplex_control_api_requires_explicit_fence():
-    engine = object.__new__(AsyncOmniEngine)
-
-    with pytest.raises(TypeError, match="fence"):
-        engine.open_duplex_session("sid")
-    with pytest.raises(TypeError, match="fence"):
-        engine.append_duplex_input("sid", mode="append_audio_chunk", payload={})
-    with pytest.raises(TypeError, match="fence"):
-        engine.signal_duplex_turn("sid", event="turn.end")
-    with pytest.raises(TypeError, match="fence"):
-        engine.close_duplex_session("sid")
-
-
-def test_open_duplex_session_waits_for_control_ack(mocker: MockerFixture):
-    request_q = queue.Queue()
-    rpc_q = queue.Queue()
-    control_result = DuplexControlResultMessage(
-        control_id="ctrl-1",
-        fence=DuplexFence("sid"),
-        operation="open",
-        session_id="sid",
-        ok=False,
-        stage_results=[{"stage_id": 0, "replica_id": 0, "result": {"supported": False}}],
-        unsupported_count=1,
-        error_count=0,
-    )
-
-    engine = object.__new__(AsyncOmniEngine)
-    engine.request_queue = SimpleNamespace(sync_q=request_q)
-    engine.rpc_output_queue = SimpleNamespace(sync_q=rpc_q)
-    engine._correlated_rpc_client = CorrelatedRpcClient(request_q, rpc_q)
-    engine._duplex_control_client = None
-    mocker.patch("vllm_omni.engine.async_omni_engine.uuid.uuid4", return_value=SimpleNamespace(hex="ctrl-1"))
-
-    with ThreadPoolExecutor(max_workers=1) as executor:
-        pending = executor.submit(engine.open_duplex_session, "sid", fence=DuplexFence("sid"), timeout=1)
-        msg = request_q.get(timeout=1)
-        assert msg.type == "open_duplex_session"
-        assert msg.control_id == "ctrl-1"
-        rpc_q.put(control_result)
-        with pytest.raises(DuplexControlRequestError) as exc_info:
-            pending.result(timeout=1)
-
-    assert exc_info.value.result["unsupported_count"] == 1
-    assert exc_info.value.result["stage_results"][0]["result"]["supported"] is False
-    engine._correlated_rpc_client.close()
-
-
-def test_signal_duplex_turn_message_carries_next_fence(mocker: MockerFixture):
-    request_q = queue.Queue()
-    rpc_q = queue.Queue()
-    cancelled_fence = DuplexFence("sid-cancel", epoch=4, turn_id=2)
-    next_fence = DuplexFence("sid-cancel", epoch=5, turn_id=2)
-    control_result = DuplexControlResultMessage(
-        control_id="ctrl-signal",
-        fence=cancelled_fence,
-        operation="signal",
-        session_id="sid-cancel",
-        ok=True,
-        stage_results=[],
-    )
-
-    engine = object.__new__(AsyncOmniEngine)
-    engine.request_queue = SimpleNamespace(sync_q=request_q)
-    engine.rpc_output_queue = SimpleNamespace(sync_q=rpc_q)
-    engine._correlated_rpc_client = CorrelatedRpcClient(request_q, rpc_q)
-    engine._duplex_control_client = None
-    mocker.patch("vllm_omni.engine.async_omni_engine.uuid.uuid4", return_value=SimpleNamespace(hex="ctrl-signal"))
-
-    with ThreadPoolExecutor(max_workers=1) as executor:
-        pending = executor.submit(
-            engine.signal_duplex_turn,
-            "sid-cancel",
-            event="input.cancel",
-            fence=cancelled_fence,
-            next_fence=next_fence,
-            session_config={"temperature": 0.0},
-            timeout=1,
-        )
-        msg = request_q.get(timeout=1)
-        assert isinstance(msg, SignalDuplexTurnMessage)
-        assert msg.fence == cancelled_fence
-        assert msg.next_fence == next_fence
-        assert msg.session_config == {"temperature": 0.0}
-        rpc_q.put(control_result)
-        assert pending.result(timeout=1)["ok"] is True
-
-    engine._correlated_rpc_client.close()
-
-
-@pytest.mark.asyncio
-async def test_cancelled_async_append_does_not_stop_executor_callable(mocker: MockerFixture):
-    entered = threading.Event()
-    release = threading.Event()
-    completed = threading.Event()
-    engine = object.__new__(AsyncOmniEngine)
-
-    def blocking_append(*args, **kwargs):
-        del args, kwargs
-        entered.set()
-        release.wait(timeout=1)
-        completed.set()
-        return {}
-
-    mocker.patch.object(engine, "append_duplex_input", side_effect=blocking_append)
-    task = asyncio.create_task(
-        engine.append_duplex_input_async(
-            "sid-executor-cancel",
-            mode="append_audio_chunk",
-            payload=b"audio",
-            fence=DuplexFence("sid-executor-cancel"),
-        )
-    )
-    assert await asyncio.to_thread(entered.wait, 1)
-
-    task.cancel()
-    with pytest.raises(asyncio.CancelledError):
-        await task
-    release.set()
-
-    assert await asyncio.to_thread(completed.wait, 1)
-
-
-def test_duplex_controls_route_out_of_order_without_global_lock():
-    request_q = queue.Queue()
-    rpc_q = queue.Queue()
-    engine = object.__new__(AsyncOmniEngine)
-    engine.request_queue = SimpleNamespace(sync_q=request_q)
-    engine.rpc_output_queue = SimpleNamespace(sync_q=rpc_q)
-    engine._correlated_rpc_client = CorrelatedRpcClient(request_q, rpc_q)
-    engine._duplex_control_client = None
-    first_fence = DuplexFence("sid", epoch=1)
-    second_fence = DuplexFence("sid", epoch=2)
-    first = AppendDuplexInputMessage(
-        control_id="first",
-        fence=first_fence,
-        session_id="sid",
-        expected_epoch=1,
-        mode="audio",
-        payload=b"first",
-    )
-    second = AppendDuplexInputMessage(
-        control_id="second",
-        fence=second_fence,
-        session_id="sid",
-        expected_epoch=2,
-        mode="audio",
-        payload=b"second",
-    )
-
-    with ThreadPoolExecutor(max_workers=2) as executor:
-        client = engine._get_duplex_control_client()
-        first_result = executor.submit(client.execute, first, timeout=1)
-        second_result = executor.submit(client.execute, second, timeout=1)
-        submitted = {request_q.get(timeout=1).control_id, request_q.get(timeout=1).control_id}
-        assert submitted == {"first", "second"}
-        rpc_q.put(
-            DuplexControlResultMessage(
-                control_id="second",
-                fence=second_fence,
-                operation="append",
-                session_id="sid",
-                ok=True,
-                stage_results=[],
-            )
-        )
-        rpc_q.put(
-            DuplexControlResultMessage(
-                control_id="first",
-                fence=first_fence,
-                operation="append",
-                session_id="sid",
-                ok=True,
-                stage_results=[],
-            )
-        )
-
-        assert first_result.result(timeout=1)["fence"] == first_fence
-        assert second_result.result(timeout=1)["fence"] == second_fence
-
-    assert not hasattr(engine, "_rpc_lock")
-    engine._correlated_rpc_client.close()
-
-
-def test_terminal_rpc_router_rejects_without_enqueuing_new_control():
-    request_q = queue.Queue()
-    rpc_q = queue.Queue()
-    engine = object.__new__(AsyncOmniEngine)
-    engine.request_queue = SimpleNamespace(sync_q=request_q)
-    engine.rpc_output_queue = SimpleNamespace(sync_q=rpc_q)
-    engine._correlated_rpc_client = CorrelatedRpcClient(request_q, rpc_q)
-    engine._duplex_control_client = None
-    pending_message = AppendDuplexInputMessage(
-        control_id="pending",
-        fence=DuplexFence("sid"),
-        session_id="sid",
-        mode="audio",
-        payload=b"audio",
-    )
-    message = AppendDuplexInputMessage(
-        control_id="after-fatal",
-        fence=DuplexFence("sid"),
-        session_id="sid",
-        mode="audio",
-        payload=b"audio",
-    )
-
-    try:
-        with ThreadPoolExecutor(max_workers=1) as executor:
-            pending = executor.submit(engine._get_duplex_control_client().execute, pending_message, timeout=1)
-            assert request_q.get(timeout=1).control_id == "pending"
-            rpc_q.put(ErrorMessage(error="orchestrator failed", fatal=True))
-            with pytest.raises(RuntimeError, match="orchestrator failed"):
-                pending.result(timeout=1)
-
-        with pytest.raises(RuntimeError, match="orchestrator failed"):
-            engine._get_duplex_control_client().execute(message, timeout=1)
-
-        assert request_q.empty()
-    finally:
-        engine._correlated_rpc_client.close()
-
-
-def test_collective_and_duplex_results_share_router_without_swapping(mocker: MockerFixture):
-    request_q = queue.Queue()
-    rpc_q = queue.Queue()
-    engine = object.__new__(AsyncOmniEngine)
-    engine.request_queue = SimpleNamespace(sync_q=request_q)
-    engine.rpc_output_queue = SimpleNamespace(sync_q=rpc_q)
-    engine._correlated_rpc_client = CorrelatedRpcClient(request_q, rpc_q)
-    engine._duplex_control_client = None
-    fence = DuplexFence("sid")
-    duplex = AppendDuplexInputMessage(
-        control_id="duplex-control",
-        fence=fence,
-        session_id="sid",
-        mode="audio",
-        payload=b"audio",
-    )
-    mocker.patch("vllm_omni.engine.async_omni_engine.uuid.uuid4", return_value=SimpleNamespace(hex="collective-rpc"))
-
-    with ThreadPoolExecutor(max_workers=2) as executor:
-        duplex_result = executor.submit(engine._get_duplex_control_client().execute, duplex, timeout=1)
-        collective_result = executor.submit(engine.collective_rpc, "health", timeout=1)
-        submitted_types = {request_q.get(timeout=1).type, request_q.get(timeout=1).type}
-        assert submitted_types == {"append_duplex_input", "collective_rpc"}
-        rpc_q.put(
-            CollectiveRPCResultMessage(
-                rpc_id="collective-rpc",
-                method="health",
-                stage_ids=[0],
-                results=["healthy"],
-            )
-        )
-        rpc_q.put(
-            DuplexControlResultMessage(
-                control_id="duplex-control",
-                fence=fence,
-                operation="append",
-                session_id="sid",
-                ok=True,
-                stage_results=[],
-            )
-        )
-
-        assert collective_result.result(timeout=1) == ["healthy"]
-        assert duplex_result.result(timeout=1)["fence"] == fence
-
-    engine._correlated_rpc_client.close()
+    assert output.request_id == "shared-path-request"
 
 
 def test_collective_rpc_preserves_request_queue_backpressure(mocker: MockerFixture):
@@ -483,8 +186,7 @@ def put(self, item, block=True, timeout=None):
     engine.request_queue = SimpleNamespace(sync_q=request_q)
     engine.rpc_output_queue = SimpleNamespace(sync_q=rpc_q)
     engine._correlated_rpc_client = CorrelatedRpcClient(request_q, rpc_q)
-    engine._duplex_control_client = None
-    mocker.patch("vllm_omni.engine.async_omni_engine.uuid.uuid4", return_value=SimpleNamespace(hex="blocked-rpc"))
+    mocker.patch("vllm_omni.engine.omni_engine_base.uuid.uuid4", return_value=SimpleNamespace(hex="blocked-rpc"))
 
     with ThreadPoolExecutor(max_workers=1) as executor:
         pending = executor.submit(engine.collective_rpc, "health", timeout=1)
@@ -506,36 +208,6 @@ def put(self, item, block=True, timeout=None):
     engine._correlated_rpc_client.close()
 
 
-def test_open_duplex_session_raises_on_stage_control_error(mocker: MockerFixture):
-    request_q = queue.Queue()
-    rpc_q = queue.Queue()
-    control_result = DuplexControlResultMessage(
-        control_id="ctrl-error",
-        fence=DuplexFence("sid"),
-        operation="open",
-        session_id="sid",
-        ok=False,
-        stage_results=[{"stage_id": 0, "replica_id": 0, "result": {"supported": False, "error": "boom"}}],
-        unsupported_count=1,
-        error_count=1,
-    )
-
-    engine = object.__new__(AsyncOmniEngine)
-    engine.request_queue = SimpleNamespace(sync_q=request_q)
-    engine.rpc_output_queue = SimpleNamespace(sync_q=rpc_q)
-    engine._correlated_rpc_client = CorrelatedRpcClient(request_q, rpc_q)
-    engine._duplex_control_client = None
-    mocker.patch("vllm_omni.engine.async_omni_engine.uuid.uuid4", return_value=SimpleNamespace(hex="ctrl-error"))
-
-    with ThreadPoolExecutor(max_workers=1) as executor:
-        pending = executor.submit(engine.open_duplex_session, "sid", fence=DuplexFence("sid"), timeout=1)
-        request_q.get(timeout=1)
-        rpc_q.put(control_result)
-        with pytest.raises(RuntimeError, match="duplex open failed"):
-            pending.result(timeout=1)
-    engine._correlated_rpc_client.close()
-
-
 def test_shutdown_does_not_race_runtime_cleanup_with_live_orchestrator(mocker: MockerFixture):
     engine = object.__new__(AsyncOmniEngine)
     engine._shutdown_called = False
diff --git a/tests/engine/test_async_omni_engine_stage_init.py b/tests/engine/test_async_omni_engine_stage_init.py
index 27677bd546b..f052f7e9db8 100644
--- a/tests/engine/test_async_omni_engine_stage_init.py
+++ b/tests/engine/test_async_omni_engine_stage_init.py
@@ -12,7 +12,7 @@
 import pytest
 
 from vllm_omni.diffusion.data import AttentionConfig
-from vllm_omni.engine import async_omni_engine as async_omni_engine_module
+from vllm_omni.engine import omni_engine_base as async_omni_engine_module
 from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
 from vllm_omni.engine.stage_init_utils import (
     LogicalStageInitPlan,
@@ -188,7 +188,7 @@ def test_stage_engine_core_client_module_reload_keeps_forward_refs_deferred():
 
 
 def test_async_omni_engine_initialize_stages_passes_log_stats_to_runtime(monkeypatch):
-    import vllm_omni.engine.async_omni_engine as engine_mod
+    import vllm_omni.engine.omni_engine_base as engine_mod
 
     engine = object.__new__(AsyncOmniEngine)
     engine.stage_configs = [types.SimpleNamespace()]
diff --git a/tests/engine/test_diffusion_streaming_output_kwarg.py b/tests/engine/test_diffusion_streaming_output_kwarg.py
index a6f3dff02b3..8bc00f58766 100644
--- a/tests/engine/test_diffusion_streaming_output_kwarg.py
+++ b/tests/engine/test_diffusion_streaming_output_kwarg.py
@@ -33,7 +33,7 @@ def _fake_load(model, forwarded_kwargs, **_: Any):
         return "config.yaml", [], None
 
     monkeypatch.setattr(
-        "vllm_omni.engine.async_omni_engine.load_and_resolve_stage_configs",
+        "vllm_omni.engine.omni_engine_base.load_and_resolve_stage_configs",
         _fake_load,
     )
     engine = SimpleNamespace(
diff --git a/tests/engine/test_duplex_import_boundary.py b/tests/engine/test_duplex_import_boundary.py
index 013ab86617d..1da5131827f 100644
--- a/tests/engine/test_duplex_import_boundary.py
+++ b/tests/engine/test_duplex_import_boundary.py
@@ -45,27 +45,62 @@ def test_isolated_import_ignores_conflicting_gpu_visibility(monkeypatch: pytest.
     _assert_isolated_import_succeeds("import vllm_omni.outputs")
 
 
-def test_stable_engine_imports_load_duplex_kernel_eagerly() -> None:
-    # The duplex kernel is imported eagerly by the stable engine modules.
-    # Model-specific duplex adapters must still load only via the
-    # dotted-string plugin paths, and the client-side vllm_omni.clients
-    # package must never enter the stable runtime import graph.
+def test_turn_based_stack_has_no_duplex_vocabulary() -> None:
+    # The generic bases and the turn-based siblings (AsyncOmni / AsyncOmniEngine /
+    # Orchestrator) carry no duplex code: importing them must not load the
+    # engine-side duplex package, the model plugins or the client library.
     _assert_isolated_import_succeeds("""
 import sys
 
 import vllm_omni.engine.async_omni_engine
+import vllm_omni.engine.omni_engine_base
 import vllm_omni.engine.orchestrator
 import vllm_omni.entrypoints.async_omni
+import vllm_omni.entrypoints.async_omni_base
+
+forbidden_prefixes = (
+    "vllm_omni.engine.duplex",
+    "vllm_omni.engine.duplex_omni_engine",
+    "vllm_omni.engine.duplex_orchestrator",
+    "vllm_omni.entrypoints.duplex",
+    "vllm_omni.entrypoints.duplex_omni",
+    "vllm_omni.clients",
+    "vllm_omni.model_executor.models.minicpmo_4_5.duplex",
+    "vllm_omni.model_executor.models.nemotron_voicechat.duplex",
+    "vllm_omni.model_executor.models.personaplex.duplex",
+)
+loaded = sorted(
+    name
+    for name in sys.modules
+    if any(name == prefix or name.startswith(prefix + ".") for prefix in forbidden_prefixes)
+)
+if loaded:
+    raise SystemExit("turn-based imports loaded duplex modules: " + ", ".join(loaded))
+""")
+
+
+def test_duplex_stack_loads_the_framework_but_not_the_model_plugins() -> None:
+    # The duplex siblings import the engine-side duplex framework eagerly;
+    # model plugins still load only through PipelineConfig.duplex_plugin, and
+    # the client-side package never enters the server import graph.
+    _assert_isolated_import_succeeds("""
+import sys
+
+import vllm_omni.engine.duplex_omni_engine
+import vllm_omni.engine.duplex_orchestrator
+import vllm_omni.entrypoints.duplex_omni
+import vllm_omni.entrypoints.duplex.serving
 
 expected_eager = (
-    "vllm_omni.engine.duplex.contracts",
-    "vllm_omni.engine.duplex.control_plane",
-    "vllm_omni.entrypoints.duplex_request_client",
-    "vllm_omni.outputs.duplex",
+    "vllm_omni.engine.duplex.commands",
+    "vllm_omni.engine.duplex.events",
+    "vllm_omni.engine.duplex.session.engine_session",
+    "vllm_omni.engine.duplex.session.manager",
+    "vllm_omni.engine.duplex.plugin",
 )
 missing = sorted(name for name in expected_eager if name not in sys.modules)
 if missing:
-    raise SystemExit("duplex kernel modules not imported eagerly: " + ", ".join(missing))
+    raise SystemExit("duplex framework modules not imported eagerly: " + ", ".join(missing))
 
 forbidden_prefixes = (
     "vllm_omni.clients",
@@ -79,7 +114,7 @@ def test_stable_engine_imports_load_duplex_kernel_eagerly() -> None:
     if any(name == prefix or name.startswith(prefix + ".") for prefix in forbidden_prefixes)
 )
 if loaded:
-    raise SystemExit("stable imports loaded plugin-only duplex modules: " + ", ".join(loaded))
+    raise SystemExit("duplex imports loaded plugin-only or client modules: " + ", ".join(loaded))
 """)
 
 
@@ -190,16 +225,32 @@ def test_engine_duplex_uses_canonical_contract_module_names() -> None:
     core_dir = REPO_ROOT / "vllm_omni" / "experimental" / "fullduplex" / "core"
 
     for name in (
+        "commands.py",
         "contracts.py",
-        "lease.py",
+        "events.py",
         "messages.py",
-        "session.py",
-        "control_plane.py",
-        "control_client.py",
-        "runtime.py",
+        "plugin.py",
         "intermediate.py",
     ):
         assert (engine_dir / name).is_file()
+    # one session and everything that runs it lives in the session subpackage
+    for name in (
+        "__init__.py",
+        "engine_session.py",
+        "manager.py",
+        "runner.py",
+        "context.py",
+        "emitter.py",
+        "model_channel.py",
+        "control.py",
+        "append_task.py",
+        "helpers.py",
+        "lease.py",
+    ):
+        assert (engine_dir / "session" / name).is_file()
+    assert not (engine_dir / "session.py").exists()
+    for removed in ("control_plane.py", "control_client.py", "runtime.py"):
+        assert not (engine_dir / removed).exists()
     # the duplex_ prefix is dropped inside the duplex package
     assert not (engine_dir / "duplex_session.py").exists()
     assert not (engine_dir / "duplex_lease.py").exists()
diff --git a/tests/engine/test_duplex_omni_engine.py b/tests/engine/test_duplex_omni_engine.py
new file mode 100644
index 00000000000..06af9e7afb3
--- /dev/null
+++ b/tests/engine/test_duplex_omni_engine.py
@@ -0,0 +1,210 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""``DuplexOmniEngine``: the session message surface over the generic engine base."""
+
+from __future__ import annotations
+
+import asyncio
+import queue
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+
+from vllm_omni.engine.duplex.commands import Heartbeat
+from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig
+from vllm_omni.engine.duplex.messages import (
+    CloseDuplexSessionMessage,
+    DuplexControlResultMessage,
+    DuplexSessionCommandMessage,
+    DuplexSessionError,
+    OpenDuplexSessionMessage,
+    ResumeDuplexSessionMessage,
+    TouchDuplexSessionMessage,
+)
+from vllm_omni.engine.duplex_omni_engine import DuplexOmniEngine
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+class _FakeRpcClient:
+    def __init__(self, result: Any) -> None:
+        self.result = result
+        self.calls: list[tuple[tuple[str, str], Any, float | None]] = []
+        #: Control RPCs must block rather than raise a raw queue.Full.
+        self.block_on_submit_flags: list[bool] = []
+
+    def execute(self, key, message, *, timeout=None, timeout_message=None, block_on_submit=False):
+        self.calls.append((key, message, timeout))
+        self.block_on_submit_flags.append(block_on_submit)
+        if isinstance(self.result, BaseException):
+            raise self.result
+        return self.result
+
+
+class _FakeSyncQueue:
+    def __init__(self, *, full: bool = False) -> None:
+        self.items: list[Any] = []
+        self.full = full
+
+    def put(self, item: Any, timeout: float | None = None) -> None:
+        if self.full:
+            raise queue.Full
+        self.items.append(item)
+
+
+def _engine(result: Any, *, alive: bool = True, full: bool = False) -> DuplexOmniEngine:
+    engine = object.__new__(DuplexOmniEngine)
+    engine._correlated_rpc_client = _FakeRpcClient(result)
+    engine.request_queue = SimpleNamespace(sync_q=_FakeSyncQueue(full=full))
+    engine.is_alive = lambda: alive
+    engine.plugin = None
+    return engine
+
+
+def _ok(operation: str, **fields: Any) -> DuplexControlResultMessage:
+    return DuplexControlResultMessage(control_id="c", operation=operation, session_id="sid", ok=True, **fields)
+
+
+@pytest.mark.asyncio
+async def test_open_session_runs_the_correlated_rpc_with_the_typed_config() -> None:
+    result = _ok("open", capabilities=DuplexCapabilities(), public_session={"id": "sid"}, lease_generation=0)
+    engine = _engine(result)
+    config = DuplexSessionConfig(model="m")
+
+    returned = await engine.open_session_async("sid", config, timeout=3.0)
+
+    assert returned is result
+    ((key, message, timeout),) = engine.rpc_client.calls
+    assert key == ("duplex", message.control_id)
+    assert isinstance(message, OpenDuplexSessionMessage)
+    assert message.session_id == "sid" and message.session_config is config
+    assert timeout == 3.0
+    # A momentarily full request queue is backpressure, not a failed open: the
+    # control RPC blocks rather than raising an untyped queue.Full at the caller.
+    assert engine.rpc_client.block_on_submit_flags == [True]
+
+
+@pytest.mark.asyncio
+async def test_close_resume_and_touch_build_their_messages_without_incarnation() -> None:
+    engine = _engine(_ok("close"))
+    await engine.close_session_async("sid", reason="bye")
+    await engine.resume_session_async("sid", expected_lease_generation=4)
+    await engine.touch_session_async("sid", activity="detach")
+
+    close, resume, touch = (call[1] for call in engine.rpc_client.calls)
+    assert isinstance(close, CloseDuplexSessionMessage) and close.reason == "bye"
+    assert isinstance(resume, ResumeDuplexSessionMessage) and resume.expected_lease_generation == 4
+    assert isinstance(touch, TouchDuplexSessionMessage) and touch.activity == "detach"
+    for message in (close, resume, touch):
+        assert message.session_id == "sid"
+        assert not hasattr(message, "incarnation")
+
+
+@pytest.mark.asyncio
+async def test_failed_control_result_maps_to_a_typed_session_error() -> None:
+    engine = _engine(
+        DuplexControlResultMessage(
+            control_id="c",
+            operation="open",
+            session_id="sid",
+            ok=False,
+            error_code="resource_exhausted",
+            error_message="duplex_session_capacity_exhausted: limit=1",
+            error_retryable=True,
+        )
+    )
+    with pytest.raises(DuplexSessionError) as excinfo:
+        await engine.open_session_async("sid", DuplexSessionConfig())
+    assert excinfo.value.code == "resource_exhausted"
+    assert excinfo.value.retryable is True
+    assert excinfo.value.session_id == "sid"
+
+
+@pytest.mark.asyncio
+async def test_engine_error_and_timeout_map_to_session_errors() -> None:
+    # The correlated RPC client raises RuntimeError for a closed router or a
+    # terminal orchestrator error; both become a typed engine_error.
+    engine = _engine(RuntimeError("orchestrator exploded"))
+    with pytest.raises(DuplexSessionError, match="orchestrator exploded") as excinfo:
+        await engine.close_session_async("sid")
+    assert excinfo.value.code == "engine_error"
+
+    engine = _engine(TimeoutError("duplex open timed out for session sid"))
+    with pytest.raises(DuplexSessionError) as excinfo:
+        await engine.open_session_async("sid", DuplexSessionConfig())
+    assert excinfo.value.code == "timeout" and excinfo.value.retryable is True
+
+
+@pytest.mark.asyncio
+async def test_submit_command_is_one_way_on_the_request_queue() -> None:
+    engine = _engine(None)
+    command = Heartbeat(event_id="evt-1")
+
+    await engine.submit_command_async("sid", command)
+
+    (message,) = engine.request_queue.sync_q.items
+    assert isinstance(message, DuplexSessionCommandMessage)
+    assert message.session_id == "sid" and message.command is command
+    assert engine.rpc_client.calls == []
+
+
+@pytest.mark.asyncio
+async def test_submit_command_rejects_dead_engine_and_full_queue() -> None:
+    with pytest.raises(DuplexSessionError) as excinfo:
+        await _engine(None, alive=False).submit_command_async("sid", Heartbeat())
+    assert excinfo.value.code == "engine_dead"
+
+    with pytest.raises(DuplexSessionError) as excinfo:
+        await _engine(None, full=True).submit_command_async("sid", Heartbeat())
+    assert excinfo.value.code == "engine_backpressure" and excinfo.value.retryable is True
+
+
+def test_duplex_capabilities_come_from_the_loaded_plugin() -> None:
+    engine = object.__new__(DuplexOmniEngine)
+    engine.plugin = None
+    with pytest.raises(RuntimeError, match="not loaded"):
+        engine.duplex_capabilities
+    capabilities = DuplexCapabilities(supports_barge_in=False)
+    engine.plugin = SimpleNamespace(capabilities=lambda *, max_sessions: capabilities)
+    engine.duplex_session_config = SimpleNamespace(max_sessions=3)
+    assert engine.duplex_capabilities is capabilities
+
+
+def test_validate_deployment_requires_a_plugin_and_duplex_session_mode() -> None:
+    engine = object.__new__(DuplexOmniEngine)
+    engine.model = "plain-model"
+    engine.pipeline_config = SimpleNamespace(duplex_plugin=None)
+    engine.deploy_config = SimpleNamespace(session_mode="duplex")
+    with pytest.raises(ValueError, match="not a duplex model"):
+        engine._validate_deployment()
+
+    engine.pipeline_config = SimpleNamespace(duplex_plugin="pkg.mod.Plugin")
+    engine.deploy_config = SimpleNamespace(session_mode="turn")
+    with pytest.raises(ValueError, match="session_mode: duplex"):
+        engine._validate_deployment()
+
+    engine.deploy_config = None
+    with pytest.raises(ValueError, match="none resolved"):
+        engine._validate_deployment()
+
+
+@pytest.mark.asyncio
+async def test_async_wrappers_run_the_blocking_calls_off_the_event_loop() -> None:
+    loop = asyncio.get_running_loop()
+    engine = _engine(_ok("touch"))
+    seen: list[bool] = []
+    original = engine.rpc_client.execute
+
+    def execute(*args, **kwargs):
+        # Called from the default executor thread, never on the event loop thread.
+        try:
+            seen.append(asyncio.get_running_loop() is loop)
+        except RuntimeError:
+            seen.append(False)
+        return original(*args, **kwargs)
+
+    engine.rpc_client.execute = execute
+    await engine.touch_session_async("sid", activity="heartbeat")
+    assert seen == [False]
diff --git a/tests/engine/test_duplex_orchestrator.py b/tests/engine/test_duplex_orchestrator.py
new file mode 100644
index 00000000000..5b8130c36a1
--- /dev/null
+++ b/tests/engine/test_duplex_orchestrator.py
@@ -0,0 +1,517 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""``DuplexOrchestrator``: the template seams and the stage port around ``OrchestratorBase``."""
+
+from __future__ import annotations
+
+import asyncio
+import struct
+from types import SimpleNamespace
+from typing import Any
+
+import numpy as np
+import pytest
+from vllm.v1.engine.exceptions import EngineDeadError
+
+from tests.engine.test_orchestrator import (
+    FakeOutputProcessor,
+    FakeRunningCounter,
+    FakeStageClient,
+    _build_stage_pools,
+)
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex import commands
+from vllm_omni.engine.duplex.config import DuplexSessionConfig, DuplexSessionState
+from vllm_omni.engine.duplex.contracts import DuplexFence, duplex_resource_request_id
+from vllm_omni.engine.duplex.messages import (
+    CloseDuplexSessionMessage,
+    DuplexControlResultMessage,
+    DuplexSessionCommandMessage,
+    OpenDuplexSessionMessage,
+)
+from vllm_omni.engine.duplex_orchestrator import DuplexOrchestrator, DuplexOrchestratorRequestState
+from vllm_omni.engine.messages import AbortRequestMessage, ShutdownRequestMessage
+from vllm_omni.engine.orchestrator import Orchestrator
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.plugin import MiniCPMO45DuplexPlugin
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+SESSION_ID = "duplex-orch"
+
+
+def _encode_audio(audio: object, sample_rate_hz: int, response_format: str, speed: float | None) -> str | None:
+    del sample_rate_hz, response_format, speed
+    samples = int(np.asarray(audio, dtype=np.float32).size) if audio is not None else 0
+    return f"wav-{samples}" if samples > 0 else None
+
+
+def _stage_configs(count: int) -> list[object]:
+    return [SimpleNamespace(model_config=SimpleNamespace(max_model_len=4096)) for _ in range(count)]
+
+
+def _build(
+    *,
+    stages: int = 1,
+    running_counter: FakeRunningCounter | None = None,
+    runtime_config: DuplexSessionRuntimeConfig | None = None,
+) -> tuple[DuplexOrchestrator, list[FakeStageClient], asyncio.Queue, asyncio.Queue]:
+    clients = [FakeStageClient(stage_type="llm", final_output=index == stages - 1) for index in range(stages)]
+    pools = _build_stage_pools(
+        [[client] for client in clients],
+        output_processors=[FakeOutputProcessor() for _ in clients],
+        stage_vllm_configs=_stage_configs(stages),
+    )
+    rpc_q: asyncio.Queue = asyncio.Queue()
+    output_q: asyncio.Queue = asyncio.Queue()
+    orchestrator = DuplexOrchestrator(
+        request_async_queue=asyncio.Queue(),
+        output_async_queue=output_q,
+        rpc_async_queue=rpc_q,
+        stage_pools=pools,
+        running_counter=running_counter,
+        plugin=MiniCPMO45DuplexPlugin(_encode_audio),
+        duplex_session_config=runtime_config or DuplexSessionRuntimeConfig(reaper_interval_s=0.01),
+        model_config=None,
+    )
+    return orchestrator, clients, rpc_q, output_q
+
+
+def _open_message(extra_body: dict[str, object] | None = None) -> OpenDuplexSessionMessage:
+    return OpenDuplexSessionMessage(
+        control_id=f"open-{SESSION_ID}",
+        session_id=SESSION_ID,
+        session_config=DuplexSessionConfig(
+            model="openbmb/MiniCPM-o-4_5",
+            modalities=["text"],
+            instructions="public instructions",
+            extra_body={"auto_response": True, **(extra_body or {})},
+        ),
+    )
+
+
+async def _open(orchestrator: DuplexOrchestrator, rpc_q: asyncio.Queue, **kwargs: Any) -> DuplexControlResultMessage:
+    await orchestrator._dispatch_message(_open_message(**kwargs))
+    result = await asyncio.wait_for(rpc_q.get(), timeout=2.0)
+    assert isinstance(result, DuplexControlResultMessage)
+    return result
+
+
+async def _close(orchestrator: DuplexOrchestrator, rpc_q: asyncio.Queue) -> DuplexControlResultMessage:
+    await orchestrator._dispatch_message(
+        CloseDuplexSessionMessage(control_id=f"close-{SESSION_ID}", session_id=SESSION_ID, reason="test")
+    )
+    result = await asyncio.wait_for(rpc_q.get(), timeout=2.0)
+    await _settle(orchestrator)
+    return result
+
+
+def _stage0_request_id(epoch: int = 0) -> str:
+    return duplex_resource_request_id(DuplexFence(SESSION_ID, epoch=epoch), "stage0")
+
+
+def _append_audio(samples: int = 16000) -> commands.AppendAudio:
+    return commands.AppendAudio(
+        audio=struct.pack(f"<{samples}f", *([0.05] * samples)),
+        format="pcm_f32le",
+        sample_rate_hz=16000,
+        is_speech=True,
+    )
+
+
+async def _submit(orchestrator: DuplexOrchestrator, command: commands.DuplexCommand) -> None:
+    assert await orchestrator._dispatch_message(DuplexSessionCommandMessage(session_id=SESSION_ID, command=command))
+    await _settle(orchestrator)
+
+
+async def _settle(orchestrator: DuplexOrchestrator, *, timeout_s: float = 3.0) -> None:
+    """Let the session runner drain its mailbox and append tasks."""
+    loop = asyncio.get_running_loop()
+    deadline = loop.time() + timeout_s
+    quiet = 0
+    while loop.time() < deadline:
+        runner = orchestrator.session_manager.runners.get(SESSION_ID)
+        busy = runner is not None and (
+            not runner._mailbox.empty()
+            or any(not task.done() for task in runner.tasks.append_tasks)
+            or any(not task.done() for task in runner._background_tasks)
+        )
+        busy = busy or any(not task.done() for task in orchestrator.session_manager._dispatched_control_tasks)
+        quiet = 0 if busy else quiet + 1
+        if quiet >= 5:
+            return
+        await asyncio.sleep(0.01)
+
+
+def _tts_output(request_id: str, *, samples: int = 24000, text: str = "hello") -> SimpleNamespace:
+    return SimpleNamespace(
+        request_id=request_id,
+        finished=False,
+        outputs=[SimpleNamespace(text=text, token_ids=[], multimodal_output={})],
+        multimodal_output={
+            "audio": np.zeros(samples, dtype=np.float32),
+            "sr": 24000,
+            "meta.duplex_turn_id": np.array([0], dtype=np.int32),
+            "meta.duplex_epoch": np.array([0], dtype=np.int32),
+        },
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Message dispatch and session lifecycle                                      #
+# --------------------------------------------------------------------------- #
+
+
+def test_turn_based_orchestrator_has_no_session_manager() -> None:
+    orchestrator = Orchestrator(
+        request_async_queue=asyncio.Queue(),
+        output_async_queue=asyncio.Queue(),
+        rpc_async_queue=asyncio.Queue(),
+        stage_pools=[],
+    )
+    assert not hasattr(orchestrator, "session_manager")
+
+
+@pytest.mark.asyncio
+async def test_duplex_messages_are_dispatched_and_generic_ones_are_not() -> None:
+    orchestrator, _, rpc_q, _ = _build()
+    assert await orchestrator._dispatch_message(AbortRequestMessage(request_ids=["x"])) is False
+    assert await orchestrator._dispatch_message(ShutdownRequestMessage()) is False
+    assert await orchestrator._dispatch_message(_open_message()) is True
+    assert (await asyncio.wait_for(rpc_q.get(), timeout=2.0)).ok is True
+    await orchestrator.session_manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_open_preregisters_the_stage0_request_and_close_releases_it() -> None:
+    counter = FakeRunningCounter()
+    orchestrator, clients, rpc_q, _ = _build(running_counter=counter)
+    result = await _open(orchestrator, rpc_q)
+    assert result.ok is True
+    assert result.public_session["id"] == SESSION_ID
+    assert result.capabilities is not None and result.capabilities.supports_input_append
+
+    request_id = _stage0_request_id()
+    request_state = orchestrator.request_states[request_id]
+    assert isinstance(request_state, DuplexOrchestratorRequestState)
+    assert request_state.session_owned is True
+    assert request_state.session_id == SESSION_ID
+    assert request_state.fence == DuplexFence(SESSION_ID)
+    assert request_state.streaming.enabled is True
+    # Preregistration reserves the id; nothing is running until an append submits.
+    assert counter.value == 0
+    assert clients[0].add_request_calls == []
+    assert orchestrator.session_manager.runner_for_request_id(request_id) is not None
+
+    closed = await _close(orchestrator, rpc_q)
+    assert closed.ok is True
+    assert request_id not in orchestrator.request_states
+    assert orchestrator.session_manager.runner_for_request_id(request_id) is None
+    assert counter.value == 0
+    assert orchestrator.session_manager.active_count() == 0
+
+
+@pytest.mark.asyncio
+async def test_open_failure_rolls_back_session_and_reserved_request() -> None:
+    orchestrator, _, rpc_q, _ = _build()
+    # Server-owned runtime keys may not come from the client.
+    result = await _open(orchestrator, rpc_q, extra_body={"duplex_stage_max_tokens": {"0": 99}})
+
+    assert result.ok is False
+    assert result.error_code == "invalid_duplex_runtime_config"
+    assert orchestrator.request_states == {}
+    assert orchestrator.session_manager.active_count() == 0
+
+
+@pytest.mark.asyncio
+async def test_open_fails_cleanly_when_a_stage_has_no_live_replica() -> None:
+    orchestrator, _, rpc_q, _ = _build(stages=2)
+    orchestrator.stage_pools[1].evict_replica(0)
+
+    result = await _open(orchestrator, rpc_q)
+
+    assert result.ok is False
+    assert "stage 1 has no live replica" in (result.error_message or "")
+    assert orchestrator.request_states == {}
+    assert orchestrator.session_manager.active_count() == 0
+
+
+@pytest.mark.asyncio
+async def test_bridge_state_keeps_public_and_runtime_config_separate() -> None:
+    orchestrator, _, rpc_q, _ = _build()
+    await _open(orchestrator, rpc_q)
+    request_state = orchestrator.request_states[_stage0_request_id()]
+    bridge = request_state.streaming.bridge_states["duplex"]
+
+    assert bridge["session_id"] == SESSION_ID
+    assert bridge["fence"] == DuplexFence(SESSION_ID)
+    assert (bridge["epoch"], bridge["turn_id"], bridge["model_turn_id"]) == (0, 0, 0)
+    assert "incarnation" not in bridge
+    assert bridge["session_config"]["instructions"] == "public instructions"
+    assert "duplex_stage_sampling_params" not in bridge["session_config"]
+    assert bridge["runtime_config"]["instructions"] == "public instructions"
+    assert bridge["runtime_config"]["duplex_stage_max_tokens"] == {"0": 20, "1": 8192}
+    # The plugin's sampling policy is applied to the preregistered request.
+    assert request_state.sampling_params_list[0].max_tokens == 20
+    await orchestrator.session_manager.shutdown()
+
+
+# --------------------------------------------------------------------------- #
+# Stage port                                                                  #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_append_submits_the_resumable_stage0_request_and_counts_it_running() -> None:
+    counter = FakeRunningCounter()
+    orchestrator, clients, rpc_q, _ = _build(running_counter=counter)
+    await _open(orchestrator, rpc_q)
+    request_id = _stage0_request_id()
+
+    await _submit(orchestrator, _append_audio())
+    assert len(clients[0].add_request_calls) == 1
+    submitted = clients[0].add_request_calls[0][0]
+    assert submitted.request_id == request_id
+    assert submitted.resumable is True
+    assert submitted.sampling_params.max_tokens == 20
+    request_state = orchestrator.request_states[request_id]
+    assert request_state.stage_fences[0] == DuplexFence(SESSION_ID)
+    assert 0 in request_state.stage_submit_ts
+    assert counter.value == 1
+    session = orchestrator.session_manager.get(SESSION_ID)
+    assert session is not None and session.stage_request_submitted(0, request_id)
+
+    # Later units update the same resumable request; the counter stays at one.
+    await _submit(orchestrator, _append_audio())
+    assert len(clients[0].add_request_calls) == 2
+    assert clients[0].add_request_calls[1][0].request_id == request_id
+    assert counter.value == 1
+
+    await _close(orchestrator, rpc_q)
+    assert clients[0].abort_calls == [[request_id]]
+    assert counter.value == 0
+
+
+@pytest.mark.asyncio
+async def test_session_update_refreshes_the_next_append_sampling_params() -> None:
+    orchestrator, clients, rpc_q, _ = _build()
+    await _open(orchestrator, rpc_q)
+    request_state = orchestrator.request_states[_stage0_request_id()]
+    assert request_state.sampling_params_list[0].max_tokens == 20
+
+    await _submit(orchestrator, commands.UpdateSession(patch={"max_output_tokens": 7}))
+    await _submit(orchestrator, _append_audio())
+
+    assert request_state.sampling_params_list[0].max_tokens == 7
+    assert clients[0].add_request_calls[-1][0].sampling_params.max_tokens == 7
+    await orchestrator.session_manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_forwarded_stage_requests_are_bound_and_barge_in_aborts_them() -> None:
+    orchestrator, clients, rpc_q, _ = _build(stages=2)
+    await _open(orchestrator, rpc_q)
+    request_id = _stage0_request_id()
+    await _submit(orchestrator, _append_audio())
+    request_state = orchestrator.request_states[request_id]
+    session = orchestrator.session_manager.get(SESSION_ID)
+    assert session is not None
+
+    # The base forwards Stage0 text to the TTS stage and reports the submission.
+    forwarded = SimpleNamespace(request_id=request_id, prompt_token_ids=[1, 2], resumable=True)
+    replica_id = await orchestrator.stage_pools[1].submit_initial(request_id, request_state, forwarded)
+    orchestrator._on_stage_submitted(1, request_id, replica_id, request_state)
+    assert request_state.stage_fences[1] == DuplexFence(SESSION_ID)
+    assert session.stage_request_submitted(1, request_id)
+
+    await _submit(orchestrator, commands.BargeIn())
+    assert session.epoch == 1
+    assert clients[0].abort_calls == [[request_id]]
+    assert clients[1].abort_calls == [[request_id]]
+    assert request_id not in orchestrator.request_states
+    assert session.resource_request_ids() == []
+    await orchestrator.session_manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_session_owned_outputs_reach_the_runner_and_never_the_client_queue() -> None:
+    orchestrator, _, rpc_q, output_q = _build(stages=2)
+    await _open(orchestrator, rpc_q)
+    request_id = _stage0_request_id()
+    await _submit(orchestrator, _append_audio())
+    request_state = orchestrator.request_states[request_id]
+    while not output_q.empty():
+        output_q.get_nowait()
+
+    consumed = await orchestrator._intercept_stage_output(1, 0, _tts_output(request_id), request_state, None, None)
+    await _settle(orchestrator)
+
+    assert consumed is True
+    session = orchestrator.session_manager.get(SESSION_ID)
+    assert session is not None and session.active_response_id is not None
+    types = [message.event.type for message in [output_q.get_nowait() for _ in range(output_q.qsize())]]
+    assert "response.created" in types and "response.output_audio.delta" in types
+
+    orphan = DuplexOrchestratorRequestState(
+        request_id="duplex-s.b3RoZXI.e.0.r.stage0",
+        prompt=None,
+        sampling_params_list=[],
+        final_stage_id=1,
+        session_owned=True,
+        session_id="other",
+        fence=DuplexFence("other"),
+    )
+    assert await orchestrator._intercept_stage_output(1, 0, _tts_output(orphan.request_id), orphan, None, None)
+    await orchestrator.session_manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_forward_failure_closes_the_owning_session() -> None:
+    orchestrator, clients, rpc_q, output_q = _build(stages=2)
+    await _open(orchestrator, rpc_q)
+    request_id = _stage0_request_id()
+    await _submit(orchestrator, _append_audio())
+    request_state = orchestrator.request_states[request_id]
+    session = orchestrator.session_manager.get(SESSION_ID)
+    assert session is not None
+
+    absorbed = await orchestrator._handle_forward_failure(request_id, 1, request_state, ValueError("bad thinker"))
+    await _settle(orchestrator)
+
+    assert absorbed is True
+    assert request_id not in orchestrator.request_states
+    assert clients[0].abort_calls == [[request_id]]
+    assert SESSION_ID not in orchestrator.session_manager.runners
+    assert session.state == DuplexSessionState.CLOSED
+    assert orchestrator.session_manager.active_count() == 0
+    types = [message.event.type for message in [output_q.get_nowait() for _ in range(output_q.qsize())]]
+    # The stage failure is reported before the session expires, never after.
+    assert types.index("error") < types.index("session.expired")
+    assert types[-1] == "session.expired"
+
+
+@pytest.mark.asyncio
+async def test_request_cleanup_failure_is_deferred_and_retried_by_the_reaper(monkeypatch) -> None:
+    orchestrator, clients, rpc_q, _ = _build()
+    await _open(orchestrator, rpc_q)
+    request_id = _stage0_request_id()
+    await _submit(orchestrator, _append_audio())
+    manager = orchestrator.session_manager
+
+    async def failing_abort(request_ids: list[str]) -> None:
+        raise RuntimeError("stage abort failed")
+
+    monkeypatch.setattr(clients[0], "abort_requests_async", failing_abort)
+    with pytest.raises(RuntimeError, match="stage abort failed"):
+        await orchestrator._cleanup_request_ids([request_id], abort=True, release_owners=True)
+    await _settle(orchestrator)
+
+    assert SESSION_ID not in manager.runners
+    assert SESSION_ID in manager._closing  # admission slot retained
+    assert manager._pending_request_cleanups and not manager._request_cleanups_in_progress
+    assert manager.active_count() == 0 and manager._admission_count() == 1
+
+    monkeypatch.undo()
+    assert await manager.reap_expired() >= 1
+    assert manager._pending_request_cleanups == {}
+    assert manager._admission_count() == 0
+    assert request_id not in orchestrator.request_states
+
+
+@pytest.mark.asyncio
+async def test_reaper_runs_as_a_background_task_and_survives_one_failure(monkeypatch) -> None:
+    orchestrator, _, _, _ = _build(runtime_config=DuplexSessionRuntimeConfig(reaper_interval_s=0.01))
+    calls = {"count": 0}
+
+    async def reap_expired(now: float | None = None) -> int:
+        calls["count"] += 1
+        if calls["count"] == 1:
+            raise RuntimeError("transient cleanup failure")
+        return 0
+
+    monkeypatch.setattr(orchestrator.session_manager, "reap_expired", reap_expired)
+    tasks = orchestrator._background_tasks()
+    assert len(tasks) == 1
+    task = asyncio.create_task(tasks[0])
+    await asyncio.sleep(0.05)
+    orchestrator._shutdown_event.set()
+    await task
+    assert calls["count"] >= 2
+    await orchestrator._shutdown_extensions()
+
+
+# --------------------------------------------------------------------------- #
+# The hierarchy the two surfaces depend on                                    #
+# --------------------------------------------------------------------------- #
+
+
+def test_the_duplex_stack_extends_the_turn_based_one() -> None:
+    """One engine serves a session and an ordinary request, so duplex must extend turn-based.
+
+    Pinned because it is the kind of relationship a later tidy-up turns back
+    into siblings over a shared base. If it does, a duplex server silently
+    stops serving /v1/chat/completions: the chat service needs a real
+    EngineClient with generate(), which only the turn-based side provides.
+    """
+    from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
+    from vllm_omni.engine.duplex_omni_engine import DuplexOmniEngine
+    from vllm_omni.engine.orchestrator import Orchestrator
+    from vllm_omni.entrypoints.async_omni import AsyncOmni
+    from vllm_omni.entrypoints.duplex_omni import DuplexOmni
+
+    assert issubclass(DuplexOrchestrator, Orchestrator)
+    assert issubclass(DuplexOmniEngine, AsyncOmniEngine)
+    assert issubclass(DuplexOmni, AsyncOmni)
+    # What the chat route actually needs off the engine client.
+    assert hasattr(DuplexOmni, "generate")
+
+
+@pytest.mark.asyncio
+async def test_an_unrecognised_message_reaches_the_turn_based_handler() -> None:
+    """The duplex orchestrator consumes session messages and passes the rest down.
+
+    Without the fall-through, an ordinary add_request on a duplex engine is
+    silently dropped and the chat request that sent it hangs forever.
+    """
+    orchestrator, _clients, _rpc_q, _output_q = _build()
+    handled: list[str] = []
+
+    async def _turn_based(msg: object) -> None:
+        handled.append(getattr(msg, "type", ""))
+
+    orchestrator._handle_add_request = _turn_based  # type: ignore[method-assign]
+    msg = SimpleNamespace(type="add_request")
+
+    assert await orchestrator._dispatch_message(msg) is True
+    assert handled == ["add_request"], "an add_request must reach Orchestrator, not be dropped"
+
+
+@pytest.mark.asyncio
+async def test_a_dead_replica_closes_the_sessions_it_was_serving() -> None:
+    """A session outlives its stage request, so replica death has to release the owner.
+
+    ``_handle_dead_replica`` cleaned the stage request but not the runner that
+    owned it: the session stayed alive holding an admission slot, and the client
+    was told nothing — the request-scoped ``ErrorMessage`` it emits has no
+    frontend ``request_states`` entry to land in for a session-owned request, so
+    the frontend drops it. Heartbeats would then keep an unusable session
+    occupying capacity.
+    """
+    orchestrator, clients, rpc_q, output_q = _build()
+    await _open(orchestrator, rpc_q)
+    request_id = _stage0_request_id()
+    await _submit(orchestrator, _append_audio())
+    session = orchestrator.session_manager.get(SESSION_ID)
+    assert session is not None
+    assert orchestrator.session_manager.active_count() == 1
+
+    await orchestrator._handle_dead_replica(0, 0, EngineDeadError("stage 0 replica 0 died"))
+    await _settle(orchestrator)
+
+    assert request_id not in orchestrator.request_states
+    assert SESSION_ID not in orchestrator.session_manager.runners
+    assert session.state == DuplexSessionState.CLOSED
+    assert orchestrator.session_manager.active_count() == 0, "the admission slot must come back"
+    messages = [output_q.get_nowait() for _ in range(output_q.qsize())]
+    types = [getattr(getattr(m, "event", None), "type", type(m).__name__) for m in messages]
+    assert types[-1] in {"session.expired", "session.closed"}, f"the client needs a terminal event, got {types}"
diff --git a/tests/engine/test_orchestrator.py b/tests/engine/test_orchestrator.py
index aa4f25ded2b..beddd2106ca 100644
--- a/tests/engine/test_orchestrator.py
+++ b/tests/engine/test_orchestrator.py
@@ -21,20 +21,6 @@
 from vllm.v1.engine.exceptions import EngineDeadError
 from vllm.v1.metrics.stats import IterationStats
 
-from vllm_omni.engine.duplex.control_plane import DuplexControlPlane
-from vllm_omni.engine.duplex.messages import (
-    AppendDuplexInputMessage,
-    CloseDuplexSessionMessage,
-    DuplexFence,
-    OpenDuplexSessionMessage,
-    SignalDuplexTurnMessage,
-)
-from vllm_omni.engine.duplex.runtime import (
-    DuplexInputMode,
-    DuplexRuntimeCapabilities,
-    DuplexSessionRuntimeState,
-    duplex_resource_request_id,
-)
 from vllm_omni.engine.messages import (
     AbortRequestMessage,
     AbortResultMessage,
@@ -54,7 +40,6 @@
 )
 from vllm_omni.engine.stage_pool import StagePool
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.runtime import MiniCPMO45DuplexRuntimeExtension
 from vllm_omni.outputs import OmniRequestOutput
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
@@ -1118,778 +1103,6 @@ async def boom(_request_ids, *, abort=False):
     assert "cleanup exploded" in (result.error or "")
 
 
-def _duplex_open_message(
-    session_id: str,
-    *,
-    incarnation: int = 0,
-    session_config: dict[str, object] | None = None,
-    runtime_config: dict[str, object] | None = None,
-) -> OpenDuplexSessionMessage:
-    return OpenDuplexSessionMessage(
-        control_id=f"open-{session_id}",
-        fence=DuplexFence(session_id, incarnation=incarnation),
-        session_id=session_id,
-        capabilities={
-            "input_modes": [DuplexInputMode.APPEND_AUDIO_CHUNK.value],
-            "implementation_level": "model_native_duplex",
-        },
-        session_config=session_config or {},
-        runtime_config=runtime_config or {},
-    )
-
-
-async def _handle_duplex(orchestrator: Orchestrator, message: object) -> None:
-    await orchestrator._require_duplex_control_plane().handle(message)
-
-
-def _duplex_request_state(
-    orchestrator: Orchestrator,
-    session: DuplexSessionRuntimeState,
-    *,
-    stage_id: int,
-) -> OrchestratorRequestState | None:
-    context = orchestrator._require_duplex_control_plane().ensure_stage_request(
-        session,
-        stage_id=stage_id,
-    )
-    if context is None:
-        return None
-    return orchestrator.request_states.get(context.request_id)
-
-
-@pytest.mark.asyncio
-async def test_duplex_control_plane_keeps_public_and_runtime_config_separate() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=_build_stage_pools([[stage0]]),
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-    )
-    open_message = _duplex_open_message(
-        "sid-config-channels",
-        incarnation=3,
-        session_config={
-            "instructions": "public instructions",
-            "extra_body": {"duplex_stage_max_tokens": {"0": 99}},
-        },
-        runtime_config={
-            "duplex_stage_max_tokens": {"0": 3},
-            "duplex_stage_sampling_params": {"0": {"stop_token_ids": [151705]}},
-        },
-    )
-
-    await _handle_duplex(orchestrator, open_message)
-
-    assert rpc_q.get_nowait().ok is True
-    session = orchestrator.duplex_sessions.require(open_message.session_id)
-    request_state = _duplex_request_state(orchestrator, session, stage_id=0)
-    assert request_state.sampling_params_list[0].max_tokens == 3
-    assert request_state.sampling_params_list[0].stop_token_ids == [151705]
-    bridge = request_state.streaming.bridge_states["duplex"]
-    assert bridge["incarnation"] == open_message.fence.incarnation
-    assert bridge["session_config"] == open_message.session_config
-    assert bridge["runtime_config"] == open_message.runtime_config
-
-
-@pytest.mark.asyncio
-async def test_duplex_control_plane_preserves_turn_commit_without_model_extension() -> None:
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=[],
-        duplex_runtime_extension=None,
-        enable_duplex_control=True,
-    )
-    assert isinstance(orchestrator.duplex_control_plane, DuplexControlPlane)
-
-    message = OpenDuplexSessionMessage(
-        control_id="open-turn-commit",
-        fence=DuplexFence("sid-turn-commit"),
-        session_id="sid-turn-commit",
-        capabilities={"input_modes": [DuplexInputMode.TURN_COMMIT_ONLY.value]},
-        session_config={},
-    )
-    await _handle_duplex(orchestrator, message)
-
-    result = rpc_q.get_nowait()
-    assert result.ok is True
-    assert result.stage_results[0]["result"]["scheduler_request_context"] is False
-
-
-def test_ordinary_orchestrator_bypasses_duplex_control_plane() -> None:
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=asyncio.Queue(),
-        stage_pools=[],
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-    )
-
-    assert orchestrator.duplex_control_plane is None
-
-
-@pytest.mark.asyncio
-async def test_duplex_close_cleans_preregistered_request_without_append() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    running_counter = FakeRunningCounter()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=_build_stage_pools([[stage0]]),
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-        running_counter=running_counter,
-    )
-    open_message = _duplex_open_message("sid-preregister-close")
-
-    await _handle_duplex(orchestrator, open_message)
-    open_result = rpc_q.get_nowait()
-    request_id = open_result.stage_results[0]["result"]["request_id"]
-    assert request_id in orchestrator.request_states
-
-    await _handle_duplex(
-        orchestrator,
-        CloseDuplexSessionMessage(
-            control_id="close-preregistered",
-            fence=open_message.fence,
-            session_id=open_message.session_id,
-        ),
-    )
-
-    assert rpc_q.get_nowait().ok is True
-    assert request_id not in orchestrator.request_states
-    assert orchestrator.duplex_sessions.get(open_message.session_id) is None
-    assert running_counter.value == 0
-
-
-@pytest.mark.asyncio
-async def test_duplex_open_failure_rolls_back_session_and_reserved_request() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=_build_stage_pools([[stage0]]),
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-    )
-    open_message = _duplex_open_message(
-        "sid-open-rollback",
-        runtime_config={
-            "duplex_stage_sampling_params": {
-                "0": {"stop_token_ids": 123},
-            }
-        },
-    )
-
-    await _handle_duplex(orchestrator, open_message)
-
-    assert rpc_q.get_nowait().ok is False
-    assert orchestrator.duplex_sessions.get(open_message.session_id) is None
-    assert orchestrator.request_states == {}
-
-
-@pytest.mark.asyncio
-async def test_duplex_running_counter_tracks_only_submitted_request() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    running_counter = FakeRunningCounter()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=_build_stage_pools([[stage0]]),
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-        running_counter=running_counter,
-    )
-    open_message = _duplex_open_message("sid-duplex-counter")
-    await _handle_duplex(orchestrator, open_message)
-    assert rpc_q.get_nowait().ok is True
-    assert running_counter.value == 0
-
-    await _handle_duplex(
-        orchestrator,
-        AppendDuplexInputMessage(
-            control_id="append-duplex-counter",
-            fence=open_message.fence,
-            session_id=open_message.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"is_speech": True},
-        ),
-    )
-    assert rpc_q.get_nowait().ok is True
-    assert running_counter.value == 1
-
-    await _handle_duplex(
-        orchestrator,
-        CloseDuplexSessionMessage(
-            control_id="close-duplex-counter",
-            fence=open_message.fence,
-            session_id=open_message.session_id,
-        ),
-    )
-    assert rpc_q.get_nowait().ok is True
-    assert running_counter.value == 0
-
-
-@pytest.mark.asyncio
-async def test_duplex_failed_append_does_not_advance_sequence_or_fence() -> None:
-    class FailingPlanExtension(MiniCPMO45DuplexRuntimeExtension):
-        def plan_append(self, **kwargs):
-            raise RuntimeError("planned append failure")
-
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=_build_stage_pools([[stage0]]),
-        duplex_runtime_extension=FailingPlanExtension(),
-        enable_duplex_control=True,
-    )
-    fence = DuplexFence("sid-append-rollback", turn_id=1)
-    session = orchestrator.duplex_sessions.open_session(
-        DuplexFence("sid-append-rollback"),
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-
-    await _handle_duplex(
-        orchestrator,
-        AppendDuplexInputMessage(
-            control_id="append-rollback",
-            fence=fence,
-            session_id=fence.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"is_speech": True},
-        ),
-    )
-
-    result = rpc_q.get_nowait()
-    assert result.ok is False
-    assert session.fence == DuplexFence("sid-append-rollback")
-    assert session.input_seq == 0
-    assert session.input_turn_seq == 0
-    assert stage0.add_request_calls == []
-
-
-@pytest.mark.asyncio
-async def test_duplex_duplicate_append_operation_is_submitted_once() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=_build_stage_pools([[stage0]]),
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-    )
-    fence = DuplexFence("sid-idempotent-append")
-    session = orchestrator.duplex_sessions.open_session(
-        fence,
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-
-    for control_id in ("append-first", "append-timeout-retry"):
-        await _handle_duplex(
-            orchestrator,
-            AppendDuplexInputMessage(
-                control_id=control_id,
-                operation_id="physical-input-1",
-                fence=fence,
-                session_id=fence.session_id,
-                mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-                payload={"is_speech": True},
-            ),
-        )
-
-    first = rpc_q.get_nowait()
-    retry = rpc_q.get_nowait()
-    assert first.ok is True
-    assert retry.ok is True
-    assert first.stage_results == retry.stage_results
-    assert len(stage0.add_request_calls) == 1
-    assert session.input_seq == 1
-
-
-@pytest.mark.asyncio
-async def test_duplex_barge_in_aborts_bound_stage_requests_before_releasing_fence() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=False)
-    stage1 = FakeStageClient(stage_type="llm", final_output=True)
-    stage_pools = _build_stage_pools(
-        [[stage0], [stage1]],
-        output_processors=[FakeOutputProcessor(), FakeOutputProcessor()],
-        stage_vllm_configs=[
-            SimpleNamespace(model_config=SimpleNamespace(max_model_len=64)),
-            SimpleNamespace(model_config=SimpleNamespace(max_model_len=64)),
-        ],
-    )
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=stage_pools,
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-    )
-    session = orchestrator.duplex_sessions.open_session(
-        DuplexFence("sid-stage-signal"),
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-    session.bind_stage_request(0, "req-stage0", fence=session.fence)
-    session.bind_stage_request(1, "req-stage1", fence=session.fence)
-    assert stage_pools[0].select_replica_id("req-stage0") == 0
-    assert stage_pools[1].select_replica_id("req-stage1") == 0
-    session.append_input(
-        mode=DuplexInputMode.APPEND_AUDIO_CHUNK,
-        fence=session.fence,
-    )
-    await _handle_duplex(
-        orchestrator,
-        SignalDuplexTurnMessage(
-            control_id="ctrl-signal",
-            fence=session.fence,
-            next_fence=DuplexFence("sid-stage-signal", epoch=1),
-            session_id="sid-stage-signal",
-            event="barge_in",
-        ),
-    )
-
-    assert stage0.abort_calls == [["req-stage0"]]
-    assert stage1.abort_calls == [["req-stage1"]]
-    assert stage0.collective_rpc_calls == []
-    assert stage1.collective_rpc_calls == []
-    assert session.stage_bindings == {}
-    assert session.fence == DuplexFence("sid-stage-signal", epoch=1)
-    result = rpc_q.get_nowait()
-    assert result.ok is True
-
-
-@pytest.mark.asyncio
-async def test_duplex_late_barge_in_releases_only_cancelled_fence_bindings() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=False)
-    stage1 = FakeStageClient(stage_type="llm", final_output=True)
-    stage_pools = _build_stage_pools(
-        [[stage0], [stage1]],
-        output_processors=[FakeOutputProcessor(), FakeOutputProcessor()],
-        stage_vllm_configs=[
-            SimpleNamespace(model_config=SimpleNamespace(max_model_len=64)),
-            SimpleNamespace(model_config=SimpleNamespace(max_model_len=64)),
-        ],
-    )
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=stage_pools,
-        enable_duplex_control=True,
-    )
-    cancelled_fence = DuplexFence("sid-late-stage-signal")
-    session = orchestrator.duplex_sessions.open_session(
-        cancelled_fence,
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-    session.bind_stage_request(0, "req-stage0", fence=cancelled_fence)
-    session.bind_stage_request(1, "req-stage1", fence=cancelled_fence)
-    assert stage_pools[0].select_replica_id("req-stage0") == 0
-    assert stage_pools[1].select_replica_id("req-stage1") == 0
-    current_fence = DuplexFence("sid-late-stage-signal", epoch=1)
-    session.accept_fence(current_fence)
-
-    await _handle_duplex(
-        orchestrator,
-        SignalDuplexTurnMessage(
-            control_id="ctrl-late-signal",
-            fence=cancelled_fence,
-            next_fence=current_fence,
-            session_id="sid-late-stage-signal",
-            event="barge_in",
-        ),
-    )
-
-    assert stage0.abort_calls == [["req-stage0"]]
-    assert stage1.abort_calls == [["req-stage1"]]
-    assert session.stage_bindings == {}
-    assert session.fence == current_fence
-    result = rpc_q.get_nowait()
-    assert result.ok is True
-
-
-@pytest.mark.asyncio
-async def test_duplex_cancel_without_next_fence_is_rejected_without_releasing_bindings() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    stage_pools = _build_stage_pools(
-        [[stage0]],
-        output_processors=[FakeOutputProcessor()],
-        stage_vllm_configs=[SimpleNamespace(model_config=SimpleNamespace(max_model_len=64))],
-    )
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=stage_pools,
-        enable_duplex_control=True,
-    )
-    fence = DuplexFence("sid-cancel-contract")
-    session = orchestrator.duplex_sessions.open_session(fence)
-    session.bind_stage_request(0, "req-live", fence=fence)
-
-    await _handle_duplex(
-        orchestrator,
-        SignalDuplexTurnMessage(
-            control_id="cancel-without-next",
-            fence=fence,
-            session_id=fence.session_id,
-            event="input.cancel",
-        ),
-    )
-
-    result = rpc_q.get_nowait()
-    assert result.ok is False
-    assert result.error_count == 1
-    assert "next_fence" in result.stage_results[0]["result"]["error"]
-    assert session.fence == fence
-    assert session.stage_request_ids() == ["req-live"]
-    assert stage0.abort_calls == []
-
-
-@pytest.mark.asyncio
-async def test_duplex_session_update_replaces_runtime_config() -> None:
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=[],
-        enable_duplex_control=True,
-    )
-    fence = DuplexFence("sid-update-config")
-    session = orchestrator.duplex_sessions.open_session(
-        fence,
-        session_config={"temperature": 0.7},
-    )
-
-    await _handle_duplex(
-        orchestrator,
-        SignalDuplexTurnMessage(
-            control_id="update-config",
-            fence=fence,
-            session_id=fence.session_id,
-            event="session.update",
-            session_config={"temperature": 0.0, "instructions": "updated"},
-        ),
-    )
-
-    result = rpc_q.get_nowait()
-    assert result.ok is True
-    assert session.session_config == {"temperature": 0.0, "instructions": "updated"}
-
-
-@pytest.mark.asyncio
-async def test_duplex_session_update_refreshes_next_append_sampling_params() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    stage_pools = _build_stage_pools(
-        [[stage0]],
-        output_processors=[FakeOutputProcessor()],
-        stage_vllm_configs=[SimpleNamespace(model_config=SimpleNamespace(max_model_len=64))],
-    )
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=stage_pools,
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-    )
-    fence = DuplexFence("sid-update-policy")
-    session = orchestrator.duplex_sessions.open_session(
-        fence,
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-        runtime_config={
-            "duplex_stage_max_tokens": {"0": 2},
-            "duplex_stage_sampling_params": {"0": {"stop_token_ids": [151645]}},
-        },
-    )
-    req_state = _duplex_request_state(orchestrator, session, stage_id=0)
-    assert req_state is not None
-    assert req_state.sampling_params_list[0].max_tokens == 2
-
-    await _handle_duplex(
-        orchestrator,
-        SignalDuplexTurnMessage(
-            control_id="update-policy",
-            fence=fence,
-            session_id=fence.session_id,
-            event="session.update",
-            runtime_config={
-                "duplex_stage_max_tokens": {"0": 7},
-                "duplex_stage_sampling_params": {"0": {"stop_token_ids": [151705]}},
-            },
-        ),
-    )
-    assert rpc_q.get_nowait().ok is True
-
-    await _handle_duplex(
-        orchestrator,
-        AppendDuplexInputMessage(
-            control_id="append-updated-policy",
-            fence=fence,
-            session_id=fence.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"is_speech": True},
-        ),
-    )
-
-    assert rpc_q.get_nowait().ok is True
-    assert req_state.sampling_params_list[0].max_tokens == 7
-    assert req_state.sampling_params_list[0].stop_token_ids == [151705]
-    submitted_request = stage0.add_request_calls[0][0]
-    assert submitted_request.sampling_params.stop_token_ids == [151705]
-    assert submitted_request.sampling_params.max_tokens == 7
-
-
-@pytest.mark.asyncio
-async def test_duplex_invalid_session_update_preserves_previous_config() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=_build_stage_pools([[stage0]]),
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-    )
-    fence = DuplexFence("sid-invalid-update")
-    original_runtime_config = {
-        "duplex_stage_sampling_params": {"0": {"stop_token_ids": [151645]}},
-    }
-    session = orchestrator.duplex_sessions.open_session(
-        fence,
-        runtime_config=original_runtime_config,
-    )
-
-    await _handle_duplex(
-        orchestrator,
-        SignalDuplexTurnMessage(
-            control_id="invalid-update",
-            fence=fence,
-            session_id=fence.session_id,
-            event="session.update",
-            runtime_config={
-                "duplex_stage_sampling_params": {"0": {"stop_token_ids": 123}},
-            },
-        ),
-    )
-
-    result = rpc_q.get_nowait()
-    assert result.ok is False
-    assert session.runtime_config == original_runtime_config
-    assert session.config_generation == 0
-
-
-@pytest.mark.asyncio
-async def test_duplex_arbitrary_non_cancel_signal_is_rejected() -> None:
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=[],
-        enable_duplex_control=True,
-    )
-    fence = DuplexFence("sid-unsupported-signal")
-    orchestrator.duplex_sessions.open_session(fence)
-
-    await _handle_duplex(
-        orchestrator,
-        SignalDuplexTurnMessage(
-            control_id="unsupported-signal",
-            fence=fence,
-            session_id=fence.session_id,
-            event="turn.end",
-        ),
-    )
-
-    result = rpc_q.get_nowait()
-    assert result.ok is False
-    assert "unsupported duplex runtime signal" in result.stage_results[0]["result"]["error"]
-
-
-@pytest.mark.asyncio
-async def test_duplex_cancel_rejects_late_old_append_and_accepts_next_epoch() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    stage_pools = _build_stage_pools(
-        [[stage0]],
-        output_processors=[FakeOutputProcessor()],
-        stage_vllm_configs=[SimpleNamespace(model_config=SimpleNamespace(max_model_len=64))],
-    )
-    rpc_q: asyncio.Queue = asyncio.Queue()
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=rpc_q,
-        stage_pools=stage_pools,
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-    )
-    cancelled_fence = DuplexFence("sid-cancel-late-append")
-    next_fence = DuplexFence("sid-cancel-late-append", epoch=1)
-    session = orchestrator.duplex_sessions.open_session(
-        cancelled_fence,
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-    )
-
-    await _handle_duplex(
-        orchestrator,
-        SignalDuplexTurnMessage(
-            control_id="cancel-old-fence",
-            fence=cancelled_fence,
-            next_fence=next_fence,
-            session_id=session.session_id,
-            event="input.cancel",
-        ),
-    )
-
-    cancel_result = rpc_q.get_nowait()
-    assert cancel_result.ok is True
-    assert session.fence == next_fence
-
-    await _handle_duplex(
-        orchestrator,
-        AppendDuplexInputMessage(
-            control_id="late-old-append",
-            fence=cancelled_fence,
-            session_id=session.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"is_speech": True},
-        ),
-    )
-
-    stale_result = rpc_q.get_nowait()
-    assert stale_result.ok is False
-    assert stage0.add_request_calls == []
-    assert session.stage_bindings == {}
-
-    await _handle_duplex(
-        orchestrator,
-        AppendDuplexInputMessage(
-            control_id="next-epoch-append",
-            fence=next_fence,
-            session_id=session.session_id,
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"is_speech": True},
-        ),
-    )
-
-    next_result = rpc_q.get_nowait()
-    assert next_result.ok is True
-    assert len(stage0.add_request_calls) == 1
-    assert session.stage_bindings[0].fence == next_fence
-
-
-@pytest.mark.asyncio
-async def test_duplex_append_updates_bridge_turn_id_on_long_lived_stage0_request() -> None:
-    stage0 = FakeStageClient(stage_type="llm", final_output=True)
-    stage_pools = _build_stage_pools(
-        [[stage0]],
-        output_processors=[FakeOutputProcessor()],
-        stage_vllm_configs=[SimpleNamespace(model_config=SimpleNamespace(max_model_len=64))],
-    )
-    orchestrator = Orchestrator(
-        request_async_queue=asyncio.Queue(),
-        output_async_queue=asyncio.Queue(),
-        rpc_async_queue=asyncio.Queue(),
-        stage_pools=stage_pools,
-        duplex_runtime_extension=MiniCPMO45DuplexRuntimeExtension(),
-        enable_duplex_control=True,
-    )
-    session = orchestrator.duplex_sessions.open_session(
-        DuplexFence("sid-bridge-turn"),
-        capabilities=DuplexRuntimeCapabilities(
-            input_modes={DuplexInputMode.APPEND_AUDIO_CHUNK},
-        ),
-        session_config={
-            "voice": "test",
-        },
-        runtime_config={
-            "duplex_stage_sampling_params": {
-                "0": {"stop_token_ids": [151645]},
-            },
-        },
-    )
-
-    await _handle_duplex(
-        orchestrator,
-        AppendDuplexInputMessage(
-            control_id="append-1",
-            fence=DuplexFence("sid-bridge-turn"),
-            session_id="sid-bridge-turn",
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"is_speech": True},
-        ),
-    )
-    req_state1 = _duplex_request_state(orchestrator, session, stage_id=0)
-    assert req_state1 is not None
-    duplex_state1 = req_state1.streaming.bridge_states["duplex"]
-    assert duplex_state1["session_id"] == "sid-bridge-turn"
-    assert duplex_state1["epoch"] == 0
-    assert duplex_state1["turn_id"] == 0
-    assert duplex_state1["session_config"] == session.session_config
-    assert req_state1.sampling_params_list[0].stop_token_ids == [151645]
-    submitted_request = stage0.add_request_calls[0][0]
-    assert submitted_request.sampling_params.stop_token_ids == [151645]
-    assert submitted_request.sampling_params.max_tokens == 1
-
-    await _handle_duplex(
-        orchestrator,
-        AppendDuplexInputMessage(
-            control_id="append-2",
-            fence=DuplexFence("sid-bridge-turn", turn_id=1, response_seq=1),
-            session_id="sid-bridge-turn",
-            mode=DuplexInputMode.APPEND_AUDIO_CHUNK.value,
-            payload={"is_speech": True, "new_user_turn": True},
-        ),
-    )
-    req_state2 = _duplex_request_state(orchestrator, session, stage_id=0)
-    assert req_state2 is req_state1
-    duplex_state2 = req_state2.streaming.bridge_states["duplex"]
-    assert duplex_state2["turn_id"] == 1
-    assert duplex_state2["epoch"] == 0
-    expected_request_id = duplex_resource_request_id(DuplexFence("sid-bridge-turn"), "stage0")
-    assert [call[0].request_id for call in stage0.add_request_calls] == [
-        expected_request_id,
-        expected_request_id,
-    ]
-
-
 # ---------------------------------------------------------------------------
 # Multi-replica tests
 # ---------------------------------------------------------------------------
@@ -2641,61 +1854,6 @@ async def test_stage_pool_process_llm_raw_outputs_mutates_iteration_stats() -> N
     assert iteration_stats.num_generation_tokens == 3
 
 
-@pytest.mark.asyncio
-async def test_duplex_reaper_loop_waits_between_ticks():
-    class _Plane:
-        def __init__(self) -> None:
-            self.calls = 0
-
-        async def reap_expired(self) -> int:
-            self.calls += 1
-            return 0
-
-    orchestrator = object.__new__(Orchestrator)
-    orchestrator.duplex_control_plane = _Plane()
-    orchestrator._duplex_reaper_interval_s = 0.01
-    orchestrator._shutdown_event = asyncio.Event()
-
-    task = asyncio.create_task(orchestrator._duplex_reaper_loop())
-    await asyncio.sleep(0.035)
-    orchestrator._shutdown_event.set()
-    await task
-
-    assert 2 <= orchestrator.duplex_control_plane.calls <= 5
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("first_cleanup_delay", [0.0, 0.05], ids=["immediate", "delayed"])
-async def test_duplex_reaper_loop_survives_one_cleanup_failure(first_cleanup_delay: float) -> None:
-    recovered = asyncio.Event()
-
-    class _Plane:
-        def __init__(self) -> None:
-            self.calls = 0
-
-        async def reap_expired(self) -> int:
-            self.calls += 1
-            if self.calls == 1:
-                await asyncio.sleep(first_cleanup_delay)
-                raise RuntimeError("transient cleanup failure")
-            recovered.set()
-            return 0
-
-    orchestrator = object.__new__(Orchestrator)
-    orchestrator.duplex_control_plane = _Plane()
-    orchestrator._duplex_reaper_interval_s = 0.01
-    orchestrator._shutdown_event = asyncio.Event()
-
-    task = asyncio.create_task(orchestrator._duplex_reaper_loop())
-    try:
-        # Wait for recovery itself, including when cleanup exceeds the old 35 ms window.
-        await asyncio.wait_for(recovered.wait(), timeout=5.0)
-        assert orchestrator.duplex_control_plane.calls >= 2
-    finally:
-        orchestrator._shutdown_event.set()
-        await asyncio.wait_for(task, timeout=5.0)
-
-
 @pytest.mark.asyncio
 async def test_abort_retry_does_not_repeat_successful_stage_abort():
     class _Pool:
@@ -2733,48 +1891,3 @@ def release_bindings(self, request_ids: list[str]) -> None:
     assert first.physical_abort_calls == 1
     assert second.physical_abort_calls == 2
     assert second.bound == set()
-
-
-@pytest.mark.asyncio
-async def test_request_cleanup_failure_is_deferred_to_control_plane():
-    class _FailingPool:
-        async def abort_requests(self, request_ids: list[str]) -> None:
-            raise RuntimeError("stage abort failed")
-
-        def release_bindings(self, request_ids: list[str]) -> None:
-            pass
-
-    class _Plane:
-        def __init__(self) -> None:
-            self.deferred: list[str] = []
-            self.finalized: list[str] = []
-
-        def close_sessions_for_request_ids(self, request_ids: list[str], **kwargs):
-            assert kwargs == {"abort": True, "cleanup_in_progress": True}
-            return {"sid-cleanup": ["req-a"]}
-
-        def defer_request_cleanups(self, session_ids: list[str]) -> None:
-            self.deferred.extend(session_ids)
-
-        def finalize_closed_sessions(self, session_ids: list[str]) -> None:
-            self.finalized.extend(session_ids)
-
-    from vllm_omni.engine.cfg_companion_tracker import CfgCompanionTracker
-
-    orchestrator = object.__new__(Orchestrator)
-    orchestrator.stage_pools = [_FailingPool()]
-    orchestrator.duplex_control_plane = _Plane()
-    orchestrator._pd_kv_params = {}
-    orchestrator.request_states = {}
-    orchestrator._running_counter = None
-    orchestrator._cfg_tracker = CfgCompanionTracker()
-
-    with pytest.raises(RuntimeError, match="stage abort failed"):
-        await orchestrator._cleanup_request_ids(
-            ["req-a"],
-            abort=True,
-            close_duplex_sessions=True,
-        )
-
-    assert orchestrator.duplex_control_plane.deferred == ["sid-cleanup"]
-    assert orchestrator.duplex_control_plane.finalized == []
diff --git a/tests/engine/test_orchestrator_error_handling.py b/tests/engine/test_orchestrator_error_handling.py
index eaa246072de..b8949786e20 100644
--- a/tests/engine/test_orchestrator_error_handling.py
+++ b/tests/engine/test_orchestrator_error_handling.py
@@ -1054,7 +1054,7 @@ def process_engine_inputs(self, *args, **kwargs):
         final_stage_id=1,
     )
     state.streaming.enabled = True
-    assert state.duplex_identity is None
+    assert state.session_owned is False
     orchestrator.request_states[state.request_id] = state
     try:
         await orchestrator._route_output(0, 0, _build_request_output(state.request_id), state, stage_metrics=None)
@@ -1074,34 +1074,14 @@ def process_engine_inputs(self, *args, **kwargs):
             q.close()
 
 
-@pytest.mark.asyncio
-async def test_duplex_input_processor_failure_is_request_scoped(orchestrator_factory, monkeypatch) -> None:
-    class FailingStage(FakeStageClient):
-        def process_engine_inputs(self, *_args, **_kwargs):
-            raise ValueError("No latent or hidden_states found in thinker output")
-
-    fixture = orchestrator_factory(
-        [FakeStageClient(stage_type="llm"), FailingStage(stage_type="llm", final_output=True)]
-    )
-    state = OrchestratorRequestState(
-        request_id="bad",
-        prompt=SimpleNamespace(request_id="bad", prompt_token_ids=[1]),
-        sampling_params_list=[_sampling_params(), _sampling_params()],
-        final_stage_id=1,
-        duplex_identity=SimpleNamespace(),
-    )
-
-    async def no_cleanup(*_args, **_kwargs):
-        pass
-
-    monkeypatch.setattr(fixture.orchestrator, "_cleanup_request_ids", no_cleanup)
-    try:
-        await fixture.orchestrator._forward_to_next_stage_unguarded("bad", 0, _build_request_output("raw"), state)
-        error = await _wait_for_error_message(fixture, request_id="bad")
-        assert error.fatal is False
-    finally:
-        fixture.request_sync_q.put_nowait(ShutdownRequestMessage())
-        fixture.thread.join(timeout=5)
+# ``test_duplex_input_processor_failure_is_request_scoped`` lived here upstream,
+# where one Orchestrator served both turn-based and duplex requests. Duplex
+# request ownership now belongs to DuplexOrchestrator, and the base
+# ``_handle_forward_failure`` deliberately absorbs nothing, so the equivalent
+# assertion is
+# ``tests/engine/test_duplex_orchestrator.py::test_forward_failure_closes_the_owning_session``
+# -- which also checks the stage abort, the session teardown and the
+# error-before-session.expired ordering.
 
 
 @pytest.mark.asyncio
diff --git a/tests/engine/test_orchestrator_segment_stage_keying.py b/tests/engine/test_orchestrator_segment_stage_keying.py
index 5d3952e4bb4..9c52902458e 100644
--- a/tests/engine/test_orchestrator_segment_stage_keying.py
+++ b/tests/engine/test_orchestrator_segment_stage_keying.py
@@ -2,10 +2,13 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Streaming segment-boundary state must be keyed by stage.
 
-``Orchestrator._orchestration_loop`` polls every stage into the same
+``OrchestratorBase._orchestration_loop`` polls every stage into the same
 ``OrchestratorRequestState``. While the segment-boundary fields lived in a single
 flat slot per request, whichever stage polled most recently overwrote the others,
 and the per-stage consumers then read back a different stage's boundary.
+
+The duplex consumer of the per-stage segment (``DuplexOrchestrator``'s output
+context) is covered in ``test_duplex_orchestrator.py``.
 """
 
 from __future__ import annotations
@@ -15,8 +18,6 @@
 import pytest
 from vllm.sampling_params import SamplingParams
 
-from vllm_omni.engine.duplex.contracts import DuplexRequestIdentity
-from vllm_omni.engine.duplex.messages import DuplexFence
 from vllm_omni.engine.orchestrator import (
     Orchestrator,
     OrchestratorRequestState,
@@ -54,22 +55,19 @@ def build_stage_metrics(self, outputs: list[_StageOutput], **_kwargs: object) ->
         return _StageMetrics()
 
 
-def _duplex_req_state(request_id: str = "req-duplex") -> OrchestratorRequestState:
+def _streaming_req_state(request_id: str = "req-streaming") -> OrchestratorRequestState:
     req_state = OrchestratorRequestState(
         request_id=request_id,
         sampling_params_list=[SamplingParams(max_tokens=1), SamplingParams(max_tokens=1)],
         final_stage_id=TALKER_STAGE,
+        session_owned=True,
     )
     req_state.streaming.enabled = True
-    req_state.duplex_identity = DuplexRequestIdentity(
-        session_id="session-1",
-        fence=DuplexFence(session_id="session-1"),
-    )
     return req_state
 
 
-def test_duplex_output_context_reads_only_its_own_stage_segment() -> None:
-    req_state = _duplex_req_state()
+def test_segment_accessor_reads_only_its_own_stage() -> None:
+    req_state = _streaming_req_state()
     req_state.streaming.segments[THINKER_STAGE] = StreamingSegmentState(
         finished=True,
         token_ids=[11, 22],
@@ -78,26 +76,28 @@ def test_duplex_output_context_reads_only_its_own_stage_segment() -> None:
     # The talker polls after the thinker and is still mid-segment.
     req_state.streaming.segments[TALKER_STAGE] = StreamingSegmentState(finished=False)
 
-    thinker = Orchestrator._duplex_output_context(req_state, stage_id=THINKER_STAGE)
-    talker = Orchestrator._duplex_output_context(req_state, stage_id=TALKER_STAGE)
-
-    assert thinker is not None
-    assert talker is not None
+    thinker = req_state.streaming.segment(THINKER_STAGE)
+    talker = req_state.streaming.segment(TALKER_STAGE)
 
     # These are the assertions that fail on the flat field: the talker is written
     # second, so the thinker loses its boundary to whichever stage polled last.
-    assert thinker.segment_finished is True
-    assert thinker.segment_token_ids == (11, 22)
-    assert thinker.segment_output_metadata == {"stage": "thinker"}
+    assert thinker.finished is True
+    assert thinker.token_ids == [11, 22]
+    assert thinker.output_metadata == {"stage": "thinker"}
+
+    assert talker.finished is False
+    assert talker.token_ids == []
+    assert talker.output_metadata == {}
 
-    assert talker.segment_finished is False
-    assert talker.segment_token_ids == ()
-    assert talker.segment_output_metadata == {}
+    # A stage that never reported a boundary gets a fresh, unshared segment.
+    unreported = req_state.streaming.segment(2)
+    unreported.output_metadata["poisoned"] = True
+    assert req_state.streaming.segment(2).output_metadata == {}
 
 
 @pytest.mark.asyncio
 async def test_segment_boundary_on_one_stage_does_not_build_metrics_on_another() -> None:
-    req_state = _duplex_req_state()
+    req_state = _streaming_req_state()
     req_state.streaming.segments[THINKER_STAGE] = StreamingSegmentState(finished=True)
 
     talker_pool = _RecordingPool()
diff --git a/tests/engine/test_orchestrator_stage_input_bridge.py b/tests/engine/test_orchestrator_stage_input_bridge.py
index 69df7123108..842824c2d55 100644
--- a/tests/engine/test_orchestrator_stage_input_bridge.py
+++ b/tests/engine/test_orchestrator_stage_input_bridge.py
@@ -7,23 +7,17 @@
 import queue
 from types import SimpleNamespace
 from typing import Any
-from unittest.mock import ANY, AsyncMock, MagicMock
+from unittest.mock import AsyncMock, MagicMock
 
 import janus
 import pytest
 from vllm.outputs import CompletionOutput, RequestOutput
 from vllm.sampling_params import SamplingParams
 
-from vllm_omni.engine.duplex.contracts import (
-    DuplexStageRequestContext,
-    DuplexStageSubmission,
-)
-from vllm_omni.engine.duplex.messages import DuplexFence
 from vllm_omni.engine.orchestrator import (
     Orchestrator,
     OrchestratorRequestState,
     StreamingSegmentState,
-    _OrchestratorDuplexStagePort,
 )
 from vllm_omni.engine.stage_pool import StagePool
 
@@ -131,64 +125,6 @@ def get_bound_client(self, request_id):
         return self.stage_client if self.get_bound_replica_id(request_id) is not None else None
 
 
-def _duplex_stage_port_submission():
-    stage_pools = []
-    for stage_id in range(3):
-        pool = SimpleNamespace(
-            stage_client=SimpleNamespace(default_sampling_params=SamplingParams(max_tokens=1)),
-            stage_vllm_config=SimpleNamespace(model_config=SimpleNamespace(max_model_len=64)),
-            submit_initial=AsyncMock(return_value=stage_id + 10),
-            submit_update=AsyncMock(return_value=stage_id + 20),
-        )
-        stage_pools.append(pool)
-    request_states: dict[str, OrchestratorRequestState] = {}
-    prewarm = AsyncMock()
-    port = _OrchestratorDuplexStagePort(
-        stage_pools=stage_pools,
-        request_states=request_states,
-        running_counter=None,
-        cleanup_request_ids=AsyncMock(),
-        async_chunk=True,
-        prewarm_async_chunk_stages=prewarm,
-    )
-    context = DuplexStageRequestContext(
-        request_id="req-duplex",
-        session_id="session-duplex",
-        fence=DuplexFence("session-duplex"),
-        stage_id=0,
-        final_stage_id=2,
-        config_generation=0,
-        sampling_params=tuple(SamplingParams(max_tokens=1) for _ in range(3)),
-    )
-    port.ensure_request(context)
-    submission = DuplexStageSubmission(
-        context=context,
-        prompt={"prompt_token_ids": [1, 2]},
-        already_submitted=False,
-    )
-    return port, stage_pools, request_states, prewarm, submission
-
-
-def test_duplex_bridge_state_catches_up_after_serving_turn_boundary() -> None:
-    port, _, request_states, _, submission = _duplex_stage_port_submission()
-    request_state = request_states[submission.context.request_id]
-    bridge_state = request_state.streaming.bridge_states["duplex"]
-    bridge_state["model_turn_id"] = 0
-
-    next_context = DuplexStageRequestContext(
-        request_id=submission.context.request_id,
-        session_id=submission.context.session_id,
-        fence=DuplexFence(submission.context.session_id, turn_id=1),
-        stage_id=submission.context.stage_id,
-        final_stage_id=submission.context.final_stage_id,
-        config_generation=submission.context.config_generation,
-        sampling_params=submission.context.sampling_params,
-    )
-    port.ensure_request(next_context)
-
-    assert bridge_state["model_turn_id"] == 1
-
-
 def _request_output(request_id: str) -> RequestOutput:
     completion = CompletionOutput(
         index=0,
@@ -279,13 +215,12 @@ async def test_async_prewarm_skips_outgoing_only_stage(payload_sender_info) -> N
         stage1.stage_client.get_payload_sender_info = MagicMock(return_value=payload_sender_info)
     orchestrator.stage_pools = [stage0, stage1, stage2]
     orchestrator._emit_tx_edge = lambda **_kwargs: None
-    orchestrator._record_duplex_stage_submission = MagicMock()
+    orchestrator._on_stage_submitted = MagicMock()
     req_state = OrchestratorRequestState(
         request_id="req-prewarm",
         prompt={"prompt_token_ids": [1, 2]},
         sampling_params_list=[SamplingParams(max_tokens=1) for _ in range(3)],
         final_stage_id=2,
-        duplex_identity=SimpleNamespace(),
     )
 
     prewarmed = await orchestrator._prewarm_async_chunk_stages(
@@ -306,7 +241,7 @@ async def test_async_prewarm_skips_outgoing_only_stage(payload_sender_info) -> N
     assert stage2.submitted[0].resumable is True
     assert 1 not in req_state.stage_submit_ts
     assert 2 in req_state.stage_submit_ts
-    orchestrator._record_duplex_stage_submission.assert_called_once_with(
+    orchestrator._on_stage_submitted.assert_called_once_with(
         2,
         "req-prewarm",
         0,
@@ -314,42 +249,6 @@ async def test_async_prewarm_skips_outgoing_only_stage(payload_sender_info) -> N
     )
 
 
-@pytest.mark.asyncio
-async def test_duplex_prewarm_runs_after_first_stage0_submission() -> None:
-    port, stage_pools, request_states, prewarm, submission = _duplex_stage_port_submission()
-    prewarm.return_value = True
-
-    result = await port.submit(submission)
-
-    assert result.stage_id == 0
-    stage_pools[0].submit_initial.assert_awaited_once()
-    prewarm.assert_awaited_once_with("req-duplex", ANY, request_states["req-duplex"])
-
-
-@pytest.mark.asyncio
-async def test_duplex_submit_bails_out_when_prewarm_failed_the_request() -> None:
-    """A failed prewarm has already aborted the request and popped its state.
-
-    Returning a success result here would hand the control plane a replica for a
-    request that no longer exists, and the trailing bookkeeping would re-register
-    a running counter the cleanup just released -- a leak that never decrements.
-    """
-    port, stage_pools, request_states, prewarm, submission = _duplex_stage_port_submission()
-    counter = MagicMock()
-    port._running_counter = counter
-    prewarm.return_value = False
-    request_state = request_states["req-duplex"]
-
-    with pytest.raises(RuntimeError, match="prewarm failed"):
-        await port.submit(submission)
-
-    prewarm.assert_awaited_once()
-    assert request_state.duplex_stage_fences == {}
-    assert request_state.stage_submit_ts == {}
-    assert request_state.running_counter_registered is False
-    counter.increment.assert_not_called()
-
-
 @pytest.mark.asyncio
 async def test_async_route_forwards_to_outgoing_only_stage() -> None:
     orchestrator = object.__new__(Orchestrator)
diff --git a/tests/engine/test_output_metadata_snapshots.py b/tests/engine/test_output_metadata_snapshots.py
index 688f1252d6d..9670994c4aa 100644
--- a/tests/engine/test_output_metadata_snapshots.py
+++ b/tests/engine/test_output_metadata_snapshots.py
@@ -9,7 +9,7 @@
 from vllm.v1.engine import FinishReason
 
 from vllm_omni.outputs.mm_outputs import MultimodalPayload
-from vllm_omni.outputs.output_modality import OutputModality, TensorAccumulationStrategy
+from vllm_omni.outputs.output_modality import OutputModality
 from vllm_omni.outputs.output_processor import MultimodalOutputProcessor, OmniRequestState
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
@@ -58,7 +58,7 @@ def test_rate_is_latest_snapshot_before_consolidation(key, representation):
         assert payload.get(key) is payload.to_dict()[key]
     payload = payload.merged_with(MultimodalPayload(tensors={"audio": torch.full((2,), 3)}))
     assert int(payload[key]) == 48000  # Missing metadata means retain, not clear.
-    payload.consolidate_tensors(TensorAccumulationStrategy.CONCAT_LAST)
+    payload.consolidate_tensors(OutputModality.AUDIO)
     payload.consolidate_metadata()
     torch.testing.assert_close(payload["audio"], torch.arange(4).repeat_interleave(2))
 
@@ -86,7 +86,7 @@ def test_self_merge_retains_snapshot_and_content(key):
     assert payload is not None
     payload = payload.merged_with(payload)
     assert int(payload[key]) == 24000
-    payload.consolidate_tensors(TensorAccumulationStrategy.CONCAT_LAST)
+    payload.consolidate_tensors(OutputModality.AUDIO)
     torch.testing.assert_close(payload["audio"], torch.tensor([1.0, 2.0, 1.0, 2.0]))
 
 
@@ -138,6 +138,6 @@ def test_non_snapshot_tensors_still_accumulate_and_empty_merge_keeps_identity():
     assert first is not None and second is not None
     assert MultimodalPayload().merged_with(first) is first
     merged = first.merged_with(second)
-    merged.consolidate_tensors(TensorAccumulationStrategy.CONCAT_LAST)
+    merged.consolidate_tensors(OutputModality.AUDIO)
     torch.testing.assert_close(merged["latent"], torch.tensor([1.0, 3.0]))
     torch.testing.assert_close(merged["audio"], torch.tensor([2.0, 4.0]))
diff --git a/tests/engine/test_single_stage_mode.py b/tests/engine/test_single_stage_mode.py
index 675a0650b89..41d63af9ead 100644
--- a/tests/engine/test_single_stage_mode.py
+++ b/tests/engine/test_single_stage_mode.py
@@ -389,7 +389,7 @@ def _make_engine_no_thread(
                 return_value=None,
             )
             mocker.patch(
-                "vllm_omni.engine.async_omni_engine.load_deploy_config",
+                "vllm_omni.engine.omni_engine_base.load_deploy_config",
                 return_value=SimpleNamespace(duplex_session=DuplexSessionRuntimeConfig()),
             )
         mocker.patch.object(
@@ -446,11 +446,11 @@ def test_no_stage_id_no_single_stage_mode(self, mocker: MockerFixture):
     def test_deploy_config_loads_duplex_runtime_config(self, mocker: MockerFixture):
         duplex_session = DuplexSessionRuntimeConfig(max_sessions=2)
         get_pipeline_config = mocker.patch(
-            "vllm_omni.engine.async_omni_engine.StageConfigFactory.get_pipeline_config",
+            "vllm_omni.engine.omni_engine_base.StageConfigFactory.get_pipeline_config",
             return_value=None,
         )
         load_deploy_config = mocker.patch(
-            "vllm_omni.engine.async_omni_engine.load_deploy_config",
+            "vllm_omni.engine.omni_engine_base.load_deploy_config",
             return_value=SimpleNamespace(duplex_session=duplex_session),
         )
 
@@ -467,7 +467,8 @@ def test_deploy_config_loads_duplex_runtime_config(self, mocker: MockerFixture):
             deploy_config_path="/fake/duplex.yaml",
         )
         load_deploy_config.assert_called_once_with("/fake/duplex.yaml")
-        assert engine.duplex_session_config is duplex_session
+        # The turn-based engine only keeps the resolved deploy profile for introspection.
+        assert engine.deploy_config.duplex_session is duplex_session
 
     def test_auto_discovered_deploy_loads_duplex_runtime_config(
         self,
@@ -476,11 +477,11 @@ def test_auto_discovered_deploy_loads_duplex_runtime_config(
         deploy_path = "/resolved/qwen3_omni_moe.yaml"
         duplex_session = DuplexSessionRuntimeConfig(server_vad_model_path="/models/silero_vad.onnx")
         mocker.patch(
-            "vllm_omni.engine.async_omni_engine.StageConfigFactory.get_pipeline_config",
+            "vllm_omni.engine.omni_engine_base.StageConfigFactory.get_pipeline_config",
             return_value=None,
         )
         load_deploy_config = mocker.patch(
-            "vllm_omni.engine.async_omni_engine.load_deploy_config",
+            "vllm_omni.engine.omni_engine_base.load_deploy_config",
             return_value=SimpleNamespace(duplex_session=duplex_session),
         )
 
@@ -557,7 +558,7 @@ def clear_config_factory_caches(self):
 
     def _make_engine_no_thread(self, mocker: MockerFixture, **kwargs: Any) -> AsyncOmniEngine:
         mocker.patch(
-            "vllm_omni.engine.async_omni_engine.load_deploy_config",
+            "vllm_omni.engine.omni_engine_base.load_deploy_config",
             return_value=SimpleNamespace(duplex_session=DuplexSessionRuntimeConfig()),
         )
         mocker.patch.object(
diff --git a/tests/entrypoints/duplex/test_duplex_serving.py b/tests/entrypoints/duplex/test_duplex_serving.py
new file mode 100644
index 00000000000..dde616d94d3
--- /dev/null
+++ b/tests/entrypoints/duplex/test_duplex_serving.py
@@ -0,0 +1,609 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The thin websocket handler: handshake, command translation, event pump, resume/takeover."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+from contextlib import suppress
+from typing import Any
+
+import pytest
+from fastapi import WebSocketDisconnect
+
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex import commands
+from vllm_omni.engine.duplex.config import DuplexCapabilities
+from vllm_omni.engine.duplex.events import AudioDelta, DuplexEvent, SessionClosed, SessionCreated
+from vllm_omni.engine.duplex.messages import DuplexSessionError
+from vllm_omni.entrypoints.duplex.realtime_input import RealtimeEnvelope, parse_resume_request
+from vllm_omni.entrypoints.duplex.serving import OmniDuplexSessionHandler
+from vllm_omni.entrypoints.duplex.websocket import MAX_EVENT_BYTES
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+_DISCONNECT = object()
+
+
+class FakeWebSocket:
+    def __init__(self, query: dict[str, str] | None = None) -> None:
+        self.query_params = dict(query or {})
+        self.sent: list[dict[str, Any]] = []
+        self.accepted = False
+        self.closed: list[tuple[int, str]] = []
+        self._send_failure: str | None = None
+        self._inbound: asyncio.Queue[Any] = asyncio.Queue()
+
+    async def accept(self) -> None:
+        self.accepted = True
+
+    async def send_json(self, payload: dict[str, Any]) -> None:
+        if self.closed or self._send_failure is not None:
+            raise RuntimeError(
+                self._send_failure or "Unexpected ASGI message 'websocket.send', after sending 'websocket.close'."
+            )
+        self.sent.append(json.loads(json.dumps(payload)))
+
+    async def receive_text(self) -> str:
+        item = await self._inbound.get()
+        if item is _DISCONNECT:
+            raise WebSocketDisconnect(code=1000)
+        return item
+
+    async def close(self, code: int = 1000, reason: str = "") -> None:
+        self.closed.append((code, reason))
+        # A closed socket ends the reader exactly like a client disconnect.
+        self._inbound.put_nowait(_DISCONNECT)
+
+    # ---- test helpers ----
+
+    def feed(self, payload: dict[str, Any] | str) -> None:
+        self._inbound.put_nowait(payload if isinstance(payload, str) else json.dumps(payload))
+
+    def disconnect(self) -> None:
+        self._inbound.put_nowait(_DISCONNECT)
+
+    def break_sends(self) -> None:
+        """Kill the write half only: the reader stays parked, as it does in practice."""
+        self._send_failure = "Unexpected ASGI message 'websocket.send', after sending 'websocket.close'."
+
+    def types(self) -> list[str]:
+        return [payload["type"] for payload in self.sent]
+
+    async def wait_for(self, wire_type: str, *, timeout_s: float = 2.0) -> dict[str, Any]:
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + timeout_s
+        while loop.time() < deadline:
+            for payload in self.sent:
+                if payload["type"] == wire_type:
+                    return payload
+            await asyncio.sleep(0.005)
+        raise AssertionError(f"no {wire_type!r} in {self.types()}")
+
+
+class FakeHandle:
+    def __init__(self, session_id: str, capabilities: DuplexCapabilities, *, idle_timeout_s: float = 300) -> None:
+        self.session_id = session_id
+        self.capabilities = capabilities
+        self.public_session: dict[str, Any] = {"id": session_id, "idle_timeout_s": idle_timeout_s}
+        self.lease_generation = 0
+        self.closed = False
+        self.close_reasons: list[str] = []
+        self.commands: list[commands.DuplexCommand] = []
+        self._outbox: asyncio.Queue[DuplexEvent] = asyncio.Queue()
+
+    def deliver(self, event: DuplexEvent) -> None:
+        self._outbox.put_nowait(event)
+
+    async def submit(self, command: commands.DuplexCommand) -> None:
+        if self.closed:
+            raise DuplexSessionError("closed", code="session_closed", session_id=self.session_id)
+        self.commands.append(command)
+
+    async def events(self):
+        while True:
+            event = await self._outbox.get()
+            yield event
+            if event.is_terminal:
+                return
+
+    async def close(self, *, reason: str = "client_close", timeout: float | None = None) -> None:
+        self.close_reasons.append(reason)
+        if self.closed:
+            return
+        self.closed = True
+        self.deliver(SessionClosed(session_id=self.session_id, reason=reason))
+
+
+class FakeOmni:
+    def __init__(
+        self, *, resumable: bool = True, replay_max_bytes: int = 64 * 1024, idle_timeout_s: float = 300
+    ) -> None:
+        self.duplex_session_config = DuplexSessionRuntimeConfig(
+            resume_replay_ttl_s=60.0, resume_replay_max_bytes_per_session=replay_max_bytes
+        )
+        self.capabilities = DuplexCapabilities(supports_session_resume=resumable)
+        self.idle_timeout_s = idle_timeout_s
+        self.opened: list[dict[str, Any]] = []
+        self.handles: dict[str, FakeHandle] = {}
+        self.resumed: list[tuple[str, int]] = []
+        self.detached: list[str] = []
+        self.open_error: DuplexSessionError | None = None
+
+    async def open_session(self, config: Any) -> FakeHandle:
+        self.opened.append(dict(config))
+        if self.open_error is not None:
+            raise self.open_error
+        session_id = f"duplex-{len(self.handles) + 1:032x}"
+        handle = FakeHandle(session_id, self.capabilities, idle_timeout_s=self.idle_timeout_s)
+        self.handles[session_id] = handle
+        handle.deliver(SessionCreated(session_id=session_id, session={"id": session_id, "model": config.get("model")}))
+        return handle
+
+    def get_session(self, session_id: str) -> FakeHandle | None:
+        return self.handles.get(session_id)
+
+    async def resume_session(self, session_id: str, *, expected_lease_generation: int) -> FakeHandle:
+        self.resumed.append((session_id, expected_lease_generation))
+        handle = self.handles[session_id]
+        handle.lease_generation = expected_lease_generation + 1
+        return handle
+
+    async def detach_session(self, session_id: str) -> None:
+        self.detached.append(session_id)
+
+
+def _handler(omni: FakeOmni, **kwargs: Any) -> OmniDuplexSessionHandler:
+    kwargs.setdefault("config_timeout_s", 1.0)
+    kwargs.setdefault("idle_timeout_s", 5.0)
+    return OmniDuplexSessionHandler(duplex_omni=omni, **kwargs)
+
+
+def _session_update(**session: Any) -> dict[str, Any]:
+    return {"type": "session.update", "session": {"model": "test-model", "modalities": ["audio", "text"], **session}}
+
+
+async def _open(
+    handler: OmniDuplexSessionHandler, omni: FakeOmni, **session: Any
+) -> tuple[FakeWebSocket, FakeHandle, asyncio.Task]:
+    ws = FakeWebSocket({"duplex": "1", "autostart": "0"})
+    task = asyncio.create_task(handler.handle_realtime_session(ws))
+    ws.feed(_session_update(**session))
+    created = await ws.wait_for("session.created")
+    handle = omni.handles[created["session"]["id"]]
+    return ws, handle, task
+
+
+# --------------------------------------------------------------------------- #
+# Handshake and commands                                                      #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_session_update_opens_a_session_and_announces_the_server_id() -> None:
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni, session_id="mine", instructions="hi")
+
+    assert ws.accepted
+    created = ws.sent[0]
+    assert created["type"] == "session.created"
+    assert created["session"]["id"] == handle.session_id != "mine"
+    assert created["attachment_generation"] == 1
+    assert isinstance(created["resume_token"], str) and created["resume_token"]
+    assert "incarnation" not in created
+    assert "server_event_seq" not in created
+    # The whole session object went to open_session; the id inside it is ignored there.
+    assert omni.opened == [
+        {"model": "test-model", "modalities": ["audio", "text"], "session_id": "mine", "instructions": "hi"}
+    ]
+
+    ws.feed({"type": "input_audio_buffer.append", "audio": base64.b64encode(b"\x00\x01" * 8).decode("ascii")})
+    ws.feed({"type": "input_audio_buffer.commit", "event_id": "evt-c"})
+    await asyncio.sleep(0.05)
+    assert [type(command) for command in handle.commands] == [commands.AppendAudio, commands.Commit]
+    assert handle.commands[1].event_id == "evt-c"
+
+    ws.disconnect()
+    await asyncio.wait_for(task, timeout=2.0)
+    # A resumable session is detached (engine-owned grace), not closed.
+    assert omni.detached == [handle.session_id]
+    assert handle.close_reasons == []
+
+
+@pytest.mark.asyncio
+async def test_session_events_are_journaled_and_sent_in_order() -> None:
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni)
+
+    handle.deliver(AudioDelta(session_id=handle.session_id, response_id="r1", delta="aGk="))
+    delta = await ws.wait_for("response.output_audio.delta")
+    assert delta["delta"] == "aGk=" and delta["server_event_seq"] == 1
+
+    ws.feed({"type": "session.event_ack", "server_event_seq": 1})
+    ws.feed({"type": "session.event_ack", "server_event_seq": 9, "event_id": "evt-ack"})
+    error = await ws.wait_for("error")
+    assert error["error"]["code"] == "invalid_event_ack" and error["error"]["event_id"] == "evt-ack"
+
+    await handle.close(reason="client_close")
+    closed = await ws.wait_for("session.closed")
+    assert closed["reason"] == "client_close"
+    await asyncio.wait_for(task, timeout=2.0)
+    assert ws.closed[0][1] == "client_close"
+
+
+@pytest.mark.asyncio
+async def test_envelope_errors_are_answered_locally_without_touching_the_session() -> None:
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni)
+
+    ws.feed("not json")
+    ws.feed("x" * (MAX_EVENT_BYTES + 1))
+    ws.feed({"type": "totally.unknown", "event_id": "evt-u"})
+    ws.feed({"type": "session.resume", "event_id": "evt-r"})
+    ws.feed({"type": "playback.ack", "event_id": "evt-p"})  # played_ms missing
+    await asyncio.sleep(0.1)
+
+    codes = [payload["error"]["code"] for payload in ws.sent if payload["type"] == "error"]
+    assert codes == ["invalid_json", "event_too_large", "unknown_event", "unsupported_session_resume", "bad_event"]
+    errors = [payload for payload in ws.sent if payload["type"] == "error"]
+    assert errors[2]["error"]["event_id"] == "evt-u"
+    assert errors[4]["error"]["event_id"] == "evt-p"
+    assert handle.commands == []
+    ws.disconnect()
+    await asyncio.wait_for(task, timeout=2.0)
+
+
+@pytest.mark.asyncio
+async def test_open_rejection_is_reported_and_the_socket_ends() -> None:
+    omni = FakeOmni()
+    omni.open_error = DuplexSessionError("no room", code="resource_exhausted", retryable=True)
+    handler = _handler(omni)
+    ws = FakeWebSocket({"duplex": "1"})
+    task = asyncio.create_task(handler.handle_realtime_session(ws))
+    ws.feed(_session_update())
+    await asyncio.wait_for(task, timeout=2.0)
+    assert ws.types() == ["error"]
+    assert ws.sent[0]["error"]["code"] == "resource_exhausted"
+
+
+@pytest.mark.asyncio
+async def test_config_timeout_and_first_message_validation() -> None:
+    omni = FakeOmni()
+    handler = _handler(omni, config_timeout_s=0.05)
+    ws = FakeWebSocket({"duplex": "1"})
+    await asyncio.wait_for(handler.handle_realtime_session(ws), timeout=2.0)
+    assert ws.sent[0]["error"]["code"] == "config_timeout"
+
+    ws = FakeWebSocket({"duplex": "1"})
+    task = asyncio.create_task(handler.handle_realtime_session(ws))
+    ws.feed("{not json")
+    await asyncio.wait_for(task, timeout=2.0)
+    assert ws.sent[0]["error"]["code"] == "invalid_json"
+    assert omni.opened == []
+
+
+@pytest.mark.asyncio
+async def test_idle_timeout_detaches_a_resumable_session_like_a_disconnect() -> None:
+    omni = FakeOmni(idle_timeout_s=0.05)
+    handler = _handler(omni, idle_timeout_s=0.05)
+    ws, handle, task = await _open(handler, omni)
+
+    await asyncio.wait_for(task, timeout=2.0)
+    # Serving makes no session-lifetime decision: the engine lease decides
+    # whether a silent, detached session expires.
+    assert handle.close_reasons == []
+    assert omni.detached == [handle.session_id]
+
+
+@pytest.mark.asyncio
+async def test_idle_timeout_closes_a_non_resumable_session() -> None:
+    omni = FakeOmni(idle_timeout_s=0.05, resumable=False)
+    handler = _handler(omni, idle_timeout_s=0.05)
+    ws, handle, task = await _open(handler, omni)
+
+    await asyncio.wait_for(task, timeout=2.0)
+    assert handle.close_reasons == ["disconnect"]
+    assert omni.detached == []
+
+
+@pytest.mark.asyncio
+async def test_transport_send_failure_detaches_the_session_instead_of_closing_it() -> None:
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni)
+
+    # Only the write half dies, so the pump's send is the one and only report
+    # of the broken socket (the reader is still parked on receive).
+    ws.break_sends()
+    handle.deliver(AudioDelta(session_id=handle.session_id, response_id="r1", delta="aGk="))
+    await asyncio.sleep(0.05)
+
+    # The engine session is alive and resumable, so this is a disconnect of
+    # the current attachment, not a session close; the pump keeps journaling.
+    assert handle.close_reasons == []
+    assert omni.detached == [handle.session_id]
+    assert not handler._pumps[handle.session_id].done()
+
+    # The reader sees the same broken socket a moment later. The attachment is
+    # already gone, so this must not detach a second time: another detach would
+    # restart the engine's disconnect grace window.
+    ws.disconnect()
+    await asyncio.wait_for(task, timeout=2.0)
+    assert omni.detached == [handle.session_id]
+    assert handle.close_reasons == []
+
+    handle.deliver(SessionClosed(session_id=handle.session_id, reason="client_close"))
+    await asyncio.sleep(0.05)
+    assert handle.session_id not in handler._pumps
+
+
+@pytest.mark.asyncio
+async def test_non_resumable_session_is_closed_on_disconnect() -> None:
+    omni = FakeOmni(resumable=False)
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni)
+    assert "resume_token" not in ws.sent[0]
+
+    ws.disconnect()
+    await asyncio.wait_for(task, timeout=2.0)
+    assert handle.close_reasons == ["disconnect"]
+    assert omni.detached == []
+
+
+@pytest.mark.asyncio
+async def test_a_client_close_still_delivers_session_closed_before_the_socket_goes() -> None:
+    """The read loop must not outrun the pump's terminal event.
+
+    ``DuplexSessionHandle._deliver`` queues ``SessionClosed`` and marks the
+    handle closed in one synchronous step, so ``handle.closed`` is already true
+    while the event is still sitting in the outbox. ``_read_loop`` loops on
+    exactly that flag: it returned, the endpoint returned, and the ASGI server
+    tore the socket down with ``session.closed`` unsent -- the client saw an
+    abrupt close (no close frame) instead of the terminal event it was waiting
+    for.
+
+    The teardown is what makes this observable, so it is modelled here: a real
+    connection stops accepting writes the moment the endpoint returns, which is
+    why a pump that is merely *still scheduled* is already too late.
+    """
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws = FakeWebSocket({"duplex": "1", "autostart": "0"})
+
+    async def serve() -> None:
+        try:
+            await handler.handle_realtime_session(ws)
+        finally:
+            # The ASGI server drops the connection when the endpoint returns;
+            # anything the pump writes after this never reaches the client.
+            ws.break_sends()
+
+    task = asyncio.create_task(serve())
+    ws.feed(_session_update())
+    created = await ws.wait_for("session.created")
+    handle = omni.handles[created["session"]["id"]]
+    submit = handle.submit
+
+    async def closing_submit(command: commands.DuplexCommand) -> None:
+        await submit(command)
+        if isinstance(command, commands.CloseSession):
+            # Same order as the real handle: queue the event, then flip the flag.
+            handle.deliver(SessionClosed(session_id=handle.session_id, reason="client_close"))
+            handle.closed = True
+
+    handle.submit = closing_submit  # type: ignore[method-assign]
+
+    ws.feed({"type": "session.close"})
+    await asyncio.wait_for(task, timeout=2.0)
+
+    assert ws.types()[-1] == "session.closed", f"terminal event never reached the wire: {ws.types()}"
+    assert ws.closed and ws.closed[0][0] == 1000, "the socket must close with a normal close frame"
+
+
+# --------------------------------------------------------------------------- #
+# Resume and takeover                                                         #
+# --------------------------------------------------------------------------- #
+
+
+async def _resume(
+    handler: OmniDuplexSessionHandler,
+    session_id: str,
+    token: str,
+    *,
+    last_seq: int = 0,
+) -> tuple[FakeWebSocket, asyncio.Task]:
+    ws = FakeWebSocket({"duplex": "1", "resume": "1"})
+    task = asyncio.create_task(handler.handle_realtime_session(ws))
+    ws.feed(
+        {
+            "type": "session.resume",
+            "session_id": session_id,
+            "resume_token": token,
+            "last_received_server_event_seq": last_seq,
+        }
+    )
+    return ws, task
+
+
+@pytest.mark.asyncio
+async def test_resume_after_disconnect_replays_missed_events_and_rotates_the_token() -> None:
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni)
+    token = ws.sent[0]["resume_token"]
+    handle.deliver(AudioDelta(session_id=handle.session_id, response_id="r1", delta="one"))
+    await ws.wait_for("response.output_audio.delta")
+    ws.disconnect()
+    await asyncio.wait_for(task, timeout=2.0)
+    assert omni.detached == [handle.session_id]
+    # Emitted while detached: journaled for replay only.
+    handle.deliver(AudioDelta(session_id=handle.session_id, response_id="r1", delta="two"))
+    await asyncio.sleep(0.05)
+
+    ws2, task2 = await _resume(handler, handle.session_id, token, last_seq=1)
+    resumed = await ws2.wait_for("session.resumed")
+    assert resumed["session_id"] == handle.session_id
+    assert resumed["attachment_generation"] == 2
+    assert resumed["resume_token"] != token
+    assert "incarnation" not in resumed
+    replayed = await ws2.wait_for("response.output_audio.delta")
+    assert replayed["delta"] == "two" and replayed["server_event_seq"] == 2
+    assert omni.resumed == [(handle.session_id, 0)]
+
+    # The old token is revoked by the rotation.
+    ws3, task3 = await _resume(handler, handle.session_id, token)
+    await asyncio.wait_for(task3, timeout=2.0)
+    assert ws3.sent[0]["error"]["code"] == "invalid_resume_token"
+
+    ws2.feed({"type": "session.close"})
+    await asyncio.sleep(0.05)
+    ws2.disconnect()
+    await asyncio.wait_for(task2, timeout=2.0)
+
+
+@pytest.mark.asyncio
+async def test_resume_takes_over_a_live_attachment() -> None:
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni)
+    token = ws.sent[0]["resume_token"]
+
+    ws2, task2 = await _resume(handler, handle.session_id, token)
+    await ws2.wait_for("session.resumed")
+    replaced = await ws.wait_for("session.replaced")
+    assert replaced["attachment_generation"] == 1
+    assert ws.closed and ws.closed[0][1] == "session_replaced"
+    # The replaced socket's later input is ignored; the new one drives the session.
+    ws.feed({"type": "input_audio_buffer.clear"})
+    ws2.feed({"type": "input_audio_buffer.clear", "event_id": "evt-new"})
+    await asyncio.sleep(0.05)
+    assert [command.event_id for command in handle.commands] == ["evt-new"]
+    await asyncio.wait_for(task, timeout=2.0)
+
+    ws2.disconnect()
+    await asyncio.wait_for(task2, timeout=2.0)
+    assert omni.detached == [handle.session_id]
+
+
+@pytest.mark.asyncio
+async def test_resume_validation_errors() -> None:
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws = FakeWebSocket({"duplex": "1", "resume": "1"})
+    task = asyncio.create_task(handler.handle_realtime_session(ws))
+    ws.feed({"type": "session.resume", "session_id": "duplex-x"})
+    await asyncio.wait_for(task, timeout=2.0)
+    assert ws.sent[0]["error"]["code"] == "invalid_session_resume"
+
+    ws, task = await _resume(handler, "duplex-unknown", "token")
+    await asyncio.wait_for(task, timeout=2.0)
+    assert ws.sent[0]["error"]["code"] == "session_resume_expired"
+
+
+@pytest.mark.asyncio
+async def test_journal_overflow_degrades_to_live_delivery_with_resync_required() -> None:
+    omni = FakeOmni(replay_max_bytes=256)
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni)
+
+    handle.deliver(AudioDelta(session_id=handle.session_id, response_id="r1", delta="x" * 400))
+    resync = await ws.wait_for("session.resync_required")
+    assert resync["reason"] == "journal_overflow"
+    delta = await ws.wait_for("response.output_audio.delta")
+    assert "server_event_seq" not in delta
+    assert ws.types().index("session.resync_required") < ws.types().index("response.output_audio.delta")
+
+    ws.disconnect()
+    await asyncio.wait_for(task, timeout=2.0)
+
+
+# --------------------------------------------------------------------------- #
+# Envelope helpers                                                            #
+# --------------------------------------------------------------------------- #
+
+
+def test_realtime_envelope_query_rules() -> None:
+    envelope = RealtimeEnvelope.from_query_params({"model": "m"})
+    assert envelope.initial_open_payload() == {"model": "m"}
+    assert envelope.initial_open_payload() is None  # autostart happens once
+
+    envelope = RealtimeEnvelope.from_query_params({"model": "m", "autostart": "0"})
+    assert envelope.resume_only is True
+    assert envelope.initial_open_payload() is None
+    assert RealtimeEnvelope.from_query_params({"resume": "1"}).resume_only is True
+    assert RealtimeEnvelope.from_query_params({"session_id": "mine"}).default_session_payload() == {"model": None}
+
+
+def test_realtime_envelope_first_message_classification() -> None:
+    envelope = RealtimeEnvelope.from_query_params({"model": "m", "autostart": "0"})
+    resume = envelope.first_message({"type": "session.resume", "session_id": "s"})
+    assert resume.kind == "resume" and resume.resume_payload["session_id"] == "s"
+
+    envelope = RealtimeEnvelope.from_query_params({"model": "m", "autostart": "0"})
+    opened = envelope.first_message({"type": "session.update", "session": {"model": "x", "instructions": "hi"}})
+    assert opened.kind == "open" and opened.session_payload == {"model": "x", "instructions": "hi"}
+    assert opened.pending_command_payload is None
+
+    envelope = RealtimeEnvelope.from_query_params({"model": "m", "autostart": "0"})
+    autostarted = envelope.first_message({"type": "input_audio_buffer.commit"})
+    assert autostarted.kind == "open" and autostarted.session_payload == {"model": "m"}
+    assert autostarted.pending_command_payload == {"type": "input_audio_buffer.commit"}
+
+
+def test_parse_resume_request_requires_the_three_fields_only() -> None:
+    request = parse_resume_request({"session_id": "s", "resume_token": "t", "last_received_server_event_seq": 3})
+    assert request is not None
+    assert (request.session_id, request.resume_token, request.last_received_server_event_seq) == ("s", "t", 3)
+    assert parse_resume_request({"session_id": "s", "resume_token": "t"}).last_received_server_event_seq == 0
+    assert parse_resume_request({"session_id": "s", "resume_token": "t", "incarnation": 1}) is not None
+    assert parse_resume_request({"session_id": "s"}) is None
+    assert parse_resume_request({"session_id": "s", "resume_token": "t", "last_received_server_event_seq": -1}) is None
+
+
+@pytest.mark.asyncio
+async def test_a_resume_that_fails_to_activate_does_not_detach_the_live_attachment() -> None:
+    """A rejected resume must roll back only what it owns.
+
+    Two reconnects can both authenticate and both complete the engine resume;
+    only one activates. The loser's activation raises, and the rollback used to
+    detach the *session*, starting the engine's disconnect grace for the winner
+    -- a grace ordinary heartbeats do not clear.
+
+    The activation failure is injected rather than raced for: what is under test
+    is the rollback's precondition, not the window that produces it.
+    """
+    omni = FakeOmni()
+    handler = _handler(omni)
+    ws, handle, task = await _open(handler, omni)
+    token = ws.sent[0]["resume_token"]
+    registry = handler._attachment_registry
+    try:
+        assert await registry.has_attachment(handle.session_id), "the opener is attached"
+        detached_before = list(omni.detached)
+
+        async def failing_resume(*args, **kwargs):
+            raise RuntimeError("transport activation lost the race")
+
+        original_resume = registry.resume
+        registry.resume = failing_resume  # type: ignore[method-assign]
+        try:
+            ws_lose, task_lose = await _resume(handler, handle.session_id, token)
+            error = await ws_lose.wait_for("error")
+        finally:
+            registry.resume = original_resume  # type: ignore[method-assign]
+
+        assert error["error"]["code"] == "session_resume_conflict"
+        assert omni.detached == detached_before, "the loser must not detach the winner"
+        assert await registry.has_attachment(handle.session_id), "the winner is still attached"
+    finally:
+        for pending in (task, locals().get("task_lose")):
+            if pending is not None:
+                pending.cancel()
+                with suppress(asyncio.CancelledError, Exception):
+                    await pending
diff --git a/tests/entrypoints/duplex/test_runtime_adapter_boundary.py b/tests/entrypoints/duplex/test_runtime_adapter_boundary.py
deleted file mode 100644
index cb90e4bd56b..00000000000
--- a/tests/entrypoints/duplex/test_runtime_adapter_boundary.py
+++ /dev/null
@@ -1,145 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import subprocess
-import sys
-from pathlib import Path
-from types import SimpleNamespace
-
-import pytest
-
-from vllm_omni.entrypoints.duplex.runtime_adapter import (
-    validate_serving_runtime_adapter,
-)
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-@pytest.mark.parametrize(
-    "module_name",
-    [
-        "vllm_omni.entrypoints.duplex.session_runner",
-        "vllm_omni.entrypoints.duplex.runtime_bridge",
-        "vllm_omni.entrypoints.duplex.serving",
-    ],
-)
-def test_generic_openai_runtime_import_does_not_load_model_adapters(module_name: str) -> None:
-    repo_root = Path(__file__).resolve().parents[3]
-    script = f"""
-import sys
-
-import {module_name}
-
-model_duplex_prefixes = (
-    "vllm_omni.model_executor.models.minicpmo_4_5.duplex",
-    "vllm_omni.model_executor.models.nemotron_voicechat.duplex",
-    "vllm_omni.model_executor.models.personaplex.duplex",
-)
-loaded = sorted(
-    name
-    for name in sys.modules
-    if any(
-        name == prefix or name.startswith(prefix + ".")
-        for prefix in model_duplex_prefixes
-    )
-)
-if loaded:
-    raise SystemExit("generic OpenAI runtime loaded model duplex modules: " + ", ".join(loaded))
-"""
-
-    result = subprocess.run(
-        [sys.executable, "-c", script],
-        cwd=repo_root,
-        capture_output=True,
-        text=True,
-        timeout=60,
-        check=False,
-    )
-
-    assert result.returncode == 0, result.stderr
-
-
-def test_generic_handler_supports_adapterless_chat_fallback() -> None:
-    repo_root = Path(__file__).resolve().parents[3]
-    script = """
-from types import SimpleNamespace
-
-from vllm_omni.entrypoints.duplex.serving import OmniDuplexSessionHandler
-
-chat_service = SimpleNamespace(
-    engine_client=SimpleNamespace(),
-    model_config=SimpleNamespace(model="test-model"),
-)
-handler = OmniDuplexSessionHandler(chat_service=chat_service)
-if handler._serving_runtime_adapter is not None:
-    raise SystemExit("generic handler silently selected a model serving adapter")
-"""
-
-    result = subprocess.run(
-        [sys.executable, "-c", script],
-        cwd=repo_root,
-        capture_output=True,
-        text=True,
-        timeout=60,
-        check=False,
-    )
-
-    assert result.returncode == 0, result.stderr
-
-
-def _valid_runtime_adapter() -> SimpleNamespace:
-    data_plane = SimpleNamespace(
-        begin_request=lambda request_id: None,
-        is_terminal=lambda request_id: False,
-        mark_terminal=lambda request_id: None,
-        close_stream=lambda request_id: None,
-        close_session=lambda session_id, **kwargs: None,
-        project=lambda result, **kwargs: (),
-    )
-    return SimpleNamespace(
-        adapter_id="test-adapter",
-        session_states={},
-        data_plane=data_plane,
-        clean_response_done_prefix="clean",
-        interrupted_tts_prefix="interrupted",
-        private_runtime_config_keys=frozenset({"private_key"}),
-        create_session_state=lambda: object(),
-        session_state=lambda session_id: object(),
-        remove_session_state=lambda session_id: None,
-        is_enabled=lambda config: True,
-        capabilities=lambda **kwargs: object(),
-        validate_client_extra_body=lambda extra_body: None,
-        prepare_runtime_config=lambda config, **kwargs: {},
-        runtime_config_for_update=lambda config, current: {},
-        data_plane_context=lambda **kwargs: object(),
-    )
-
-
-@pytest.mark.parametrize(
-    ("attribute", "invalid_value"),
-    [
-        ("session_states", None),
-        ("clean_response_done_prefix", None),
-        ("interrupted_tts_prefix", None),
-        ("private_runtime_config_keys", {"private_key"}),
-    ],
-)
-def test_runtime_adapter_validator_rejects_invalid_protocol_attributes(
-    attribute: str,
-    invalid_value: object,
-) -> None:
-    adapter = _valid_runtime_adapter()
-    setattr(adapter, attribute, invalid_value)
-
-    with pytest.raises(TypeError, match=attribute):
-        validate_serving_runtime_adapter(adapter)
-
-
-def test_runtime_adapter_validator_rejects_incomplete_data_plane() -> None:
-    adapter = _valid_runtime_adapter()
-    adapter.data_plane.close_session = None
-
-    with pytest.raises(TypeError, match="data_plane.*close_session"):
-        validate_serving_runtime_adapter(adapter)
diff --git a/tests/entrypoints/duplex/test_runtime_control_redaction.py b/tests/entrypoints/duplex/test_runtime_control_redaction.py
deleted file mode 100644
index cfc5b68c5fe..00000000000
--- a/tests/entrypoints/duplex/test_runtime_control_redaction.py
+++ /dev/null
@@ -1,115 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-"""Regression tests for duplex ``runtime_control`` payload redaction.
-
-The redacted result is emitted on the WebSocket (for example
-``session.created.runtime_control``), so it must always survive
-``json.dumps``. Control results carry typed values straight from the engine --
-``fence`` and ``accepted_fence`` are ``DuplexFence`` instances added by
-``DuplexControlClient.execute`` -- which previously reached
-``WebSocket.send_json`` unconverted and killed the session at handshake.
-"""
-
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass
-from enum import Enum
-
-import pytest
-
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.entrypoints.duplex.runtime_bridge import NativeRuntimeBridgeMixin
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-_redact = NativeRuntimeBridgeMixin._redact_runtime_control_result
-
-
-def _control_result() -> dict[str, object]:
-    """The shape ``DuplexControlClient.execute`` returns for an open."""
-    return {
-        "ok": True,
-        "operation": "open",
-        "session_id": "sess-1",
-        "fence": DuplexFence("sess-1", epoch=0, turn_id=0, response_seq=0, incarnation=0),
-        "accepted_fence": DuplexFence("sess-1", epoch=1, turn_id=2, response_seq=3, incarnation=4),
-        "stage_results": [{"stage_id": -1, "replica_id": -1, "result": {"supported": True}}],
-    }
-
-
-def test_redacted_control_result_is_json_serializable() -> None:
-    """The whole payload must serialize the way send_json does."""
-    redacted = _redact(_control_result())
-    # Must not raise.
-    json.dumps({"type": "session.created", "runtime_control": redacted})
-
-
-def test_fences_are_converted_to_plain_dicts() -> None:
-    redacted = _redact(_control_result())
-    assert redacted["fence"] == {
-        "session_id": "sess-1",
-        "epoch": 0,
-        "turn_id": 0,
-        "response_seq": 0,
-        "incarnation": 0,
-    }
-    # Field values are preserved, not just the type.
-    assert redacted["accepted_fence"]["epoch"] == 1
-    assert redacted["accepted_fence"]["turn_id"] == 2
-    assert redacted["accepted_fence"]["response_seq"] == 3
-    assert redacted["accepted_fence"]["incarnation"] == 4
-
-
-def test_nested_dataclasses_are_converted() -> None:
-    """Fences can appear inside stage results, not only at the top level."""
-    redacted = _redact(
-        {
-            "stage_results": [
-                {"stage_id": 0, "result": {"fence": DuplexFence("sess-2", epoch=7)}},
-            ]
-        }
-    )
-    json.dumps(redacted)
-    assert redacted["stage_results"][0]["result"]["fence"]["epoch"] == 7
-
-
-def test_enums_are_reduced_to_values() -> None:
-    class _Mode(str, Enum):
-        APPEND = "append_audio_chunk"
-
-    redacted = _redact({"mode": _Mode.APPEND})
-    json.dumps(redacted)
-    assert redacted["mode"] == "append_audio_chunk"
-
-
-def test_redaction_still_drops_heavy_payload_keys() -> None:
-    """The pre-existing contract must be preserved."""
-    redacted = _redact(
-        {
-            "ok": True,
-            "stage_handoff": object(),
-            "tts_handoff": object(),
-            "omni_payload": object(),
-            "tts_hidden_states": object(),
-            "tts_token_ids": object(),
-            "traceback": "long trace",
-        }
-    )
-    assert redacted == {"ok": True}
-
-
-def test_plain_values_pass_through_unchanged() -> None:
-    payload = {"ok": True, "count": 3, "name": "x", "missing": None, "items": [1, "two"]}
-    assert _redact(payload) == payload
-
-
-def test_dataclass_types_are_not_treated_as_instances() -> None:
-    """A class object is not a dataclass instance and must not be asdict'd."""
-
-    @dataclass
-    class _Shape:
-        x: int = 1
-
-    assert _redact(_Shape) is _Shape
diff --git a/tests/entrypoints/duplex/test_websocket_actor.py b/tests/entrypoints/duplex/test_websocket_actor.py
deleted file mode 100644
index 4e5d151b9b1..00000000000
--- a/tests/entrypoints/duplex/test_websocket_actor.py
+++ /dev/null
@@ -1,145 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-import asyncio
-
-import pytest
-
-from vllm_omni.entrypoints.duplex.websocket import (
-    DuplexWebSocketActor,
-    normalize_duplex_input_event,
-)
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-class FakeWebSocket:
-    def __init__(self) -> None:
-        self.sent: list[dict[str, object]] = []
-
-    async def send_json(self, payload: dict[str, object]) -> None:
-        self.sent.append(dict(payload))
-
-
-@pytest.mark.parametrize(
-    ("event", "expected"),
-    [
-        ({"type": "signal_turn", "event": "barge_in"}, {"type": "turn.signal", "event": "barge_in"}),
-        ({"type": "close_session"}, {"type": "session.close"}),
-        ({"type": "audio.playback_ack", "played_ms": 1}, {"type": "playback.ack", "played_ms": 1}),
-        ({"type": "input_text.append", "text": "a"}, {"type": "input.text.append", "text": "a"}),
-        ({"type": "push_text", "text": "b"}, {"type": "input.text.append", "text": "b"}),
-        (
-            {"type": "input.audio.append", "audio": "wav"},
-            {"type": "input_audio_buffer.append", "audio": "wav", "format": "wav"},
-        ),
-        (
-            {"type": "push_chunk", "audio": "wav", "format": "pcm_f32le"},
-            {"type": "input_audio_buffer.append", "audio": "wav", "format": "pcm_f32le"},
-        ),
-    ],
-)
-def test_input_aliases_normalize_once_at_mailbox_boundary(event, expected):
-    assert normalize_duplex_input_event(event) == expected
-
-
-def test_actor_uses_one_fifo_mailbox_for_inbound_events():
-    actor = DuplexWebSocketActor(FakeWebSocket())
-
-    assert isinstance(actor.mailbox, asyncio.Queue)
-    assert not isinstance(actor.mailbox, asyncio.PriorityQueue)
-    assert not hasattr(actor, "control_queue")
-    assert not hasattr(actor, "input_queue")
-    assert not hasattr(actor, "event_queue")
-    assert not hasattr(actor, "lifecycle_state")
-    assert not hasattr(actor, "last_response_id")
-    assert not hasattr(actor, "overlap_speech_ms")
-    assert not hasattr(actor, "transition")
-    assert not hasattr(actor, "output_generation_in_flight")
-    assert not hasattr(actor, "session")
-    assert not hasattr(actor, "runtime_opened")
-    assert not hasattr(actor, "runtime_closed")
-    assert not hasattr(actor, "drain_input_queue")
-    assert not hasattr(actor, "control_events_seen")
-    assert not hasattr(actor, "input_events_seen")
-    assert not hasattr(actor, "cancel_count")
-
-
-@pytest.mark.asyncio
-async def test_control_event_does_not_overtake_earlier_audio_input():
-    actor = DuplexWebSocketActor(FakeWebSocket())
-    await actor.enqueue_event({"type": "input_audio_buffer.append", "audio": "pcm"})
-    await actor.enqueue_event({"type": "response.cancel"})
-
-    assert await actor.next_event() == {"type": "input_audio_buffer.append", "audio": "pcm"}
-    assert await actor.next_event() == {"type": "response.cancel"}
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("event_type", ["input.cancel", "session.close", "close_session"])
-async def test_terminal_control_preserves_wire_order(event_type: str):
-    actor = DuplexWebSocketActor(FakeWebSocket())
-    await actor.enqueue_event({"type": "input_audio_buffer.append", "audio": "pcm"})
-    await actor.enqueue_event({"type": event_type})
-
-    assert await actor.next_event() == {"type": "input_audio_buffer.append", "audio": "pcm"}
-    assert await actor.next_event() == {"type": event_type}
-
-
-@pytest.mark.asyncio
-async def test_mailbox_delivers_every_enqueued_event_exactly_once():
-    actor = DuplexWebSocketActor(FakeWebSocket())
-    events = [
-        {"type": "input_audio_buffer.append", "audio": str(index)}
-        if index % 2
-        else {"type": "response.created", "response_id": f"resp-{index}"}
-        for index in range(20)
-    ]
-
-    await asyncio.gather(*(actor.enqueue_event(dict(event)) for event in events))
-    received = [await actor.next_event() for _ in events]
-
-    assert sorted(received, key=repr) == sorted(events, key=repr)
-
-
-@pytest.mark.asyncio
-async def test_writer_is_single_owner_of_websocket_send():
-    websocket = FakeWebSocket()
-    actor = DuplexWebSocketActor(websocket)
-    writer = asyncio.create_task(actor.writer_loop())
-
-    await actor.send_json({"type": "one"})
-    await actor.send_json({"type": "two"})
-    await actor.close_writer()
-    await writer
-
-    assert websocket.sent == [{"type": "one"}, {"type": "two"}]
-
-
-@pytest.mark.asyncio
-async def test_stale_fence_payload_is_dropped_before_websocket_send():
-    websocket = FakeWebSocket()
-    actor = DuplexWebSocketActor(websocket, current_epoch=lambda: 2)
-    writer = asyncio.create_task(actor.writer_loop())
-
-    await actor.send_json({"type": "response.output_audio.delta", "epoch": 1})
-    await actor.send_json({"type": "response.output_audio.delta", "epoch": 2})
-    await actor.close_writer()
-    await writer
-
-    assert websocket.sent == [{"type": "response.output_audio.delta", "epoch": 2}]
-    assert actor.stale_output_dropped == 1
-
-
-@pytest.mark.asyncio
-async def test_writer_does_not_revoke_accepted_terminal_after_close_starts():
-    websocket = FakeWebSocket()
-    actor = DuplexWebSocketActor(websocket, current_epoch=lambda: 1)
-    await actor.send_json({"type": "response.done", "epoch": 1, "response_id": "resp-1"})
-    actor.closing = True
-    await actor.close_writer()
-
-    await actor.writer_loop()
-
-    assert websocket.sent == [{"type": "response.done", "epoch": 1, "response_id": "resp-1"}]
-    assert actor.stale_output_dropped == 0
diff --git a/tests/entrypoints/openai/test_duplex_protocol.py b/tests/entrypoints/openai/test_duplex_protocol.py
deleted file mode 100644
index 77c8f2cb0cb..00000000000
--- a/tests/entrypoints/openai/test_duplex_protocol.py
+++ /dev/null
@@ -1,601 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-import asyncio
-import json
-
-import pytest
-
-from vllm_omni.entrypoints.duplex.protocol import (
-    DuplexOverlapPolicy,
-    DuplexSession,
-    DuplexSessionConfig,
-    DuplexSessionRegistry,
-    DuplexTurnController,
-    DuplexTurnEventType,
-    DuplexTurnState,
-    ResponseCreateOptions,
-)
-from vllm_omni.entrypoints.duplex.realtime_session import (
-    NativeRealtimeSessionProtocol,
-)
-from vllm_omni.entrypoints.duplex.realtime_state import RealtimeStateOwner
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.capabilities import (
-    minicpmo45_native_capabilities,
-)
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-def test_realtime_state_owner_uses_explicit_bindings_not_dynamic_attribute_proxy():
-    assert "__getattr__" not in RealtimeStateOwner.__dict__
-    assert "__setattr__" not in RealtimeStateOwner.__dict__
-
-
-class _ProtocolWebSocket:
-    def __init__(self, *events: dict[str, object]) -> None:
-        self._events = asyncio.Queue()
-        for event in events:
-            self._events.put_nowait(json.dumps(event))
-
-    async def receive_text(self) -> str:
-        return await self._events.get()
-
-
-def test_duplex_session_commits_text_and_audio_as_one_turn():
-    registry = DuplexSessionRegistry()
-    session = registry.create(DuplexSessionConfig(model="test-model"))
-
-    session.append_text("hello")
-    session.append_audio("YWJj", fmt="wav", sample_rate_hz=16000)
-    committed = session.commit_user_input()
-
-    assert committed is not None
-    assert committed.turn_id == 0
-    assert committed.input_commit_seq == 1
-    assert committed.epoch == 0
-    assert len(session.history) == 1
-    content = session.history[0]["content"]
-    assert isinstance(content, list)
-    assert content[0] == {"type": "text", "text": "hello"}
-    assert content[1]["type"] == "audio_url"
-    assert content[1]["audio_url"]["url"] == "data:audio/wav;base64,YWJj"
-    assert session.turn_state == DuplexTurnState.USER_COMMITTED
-
-
-def test_response_options_apply_to_one_response_without_mutating_session_defaults():
-    session = DuplexSession(
-        session_id="sid-response-options",
-        config=DuplexSessionConfig(instructions="base", voice="base-voice", max_tokens=64),
-    )
-    session.reserve_response_options(
-        ResponseCreateOptions(
-            instructions="one response",
-            voice="override-voice",
-            max_tokens=8,
-        )
-    )
-
-    assert session.config.instructions == "base"
-    assert session.config.voice == "base-voice"
-    session.begin_response()
-    assert session.config.instructions == "base"
-    assert session.config.voice == "base-voice"
-    assert session.response_config.instructions == "one response"
-    assert session.response_config.voice == "override-voice"
-    assert session.response_config.max_tokens == 8
-
-    session.end_response()
-    assert session.config.instructions == "base"
-    assert session.config.voice == "base-voice"
-    assert session.config.max_tokens == 64
-
-
-def test_response_options_cannot_overwrite_an_unconsumed_reservation():
-    session = DuplexSession(
-        session_id="sid-response-options-pending",
-        config=DuplexSessionConfig(instructions="base"),
-    )
-    session.reserve_response_options(ResponseCreateOptions(instructions="first"))
-
-    with pytest.raises(RuntimeError, match="already reserved"):
-        session.reserve_response_options(ResponseCreateOptions(instructions="second"))
-
-    session.begin_response()
-    assert session.response_config.instructions == "first"
-
-
-def test_response_options_cannot_be_reserved_while_response_is_active():
-    session = DuplexSession(
-        session_id="sid-response-options-active",
-        config=DuplexSessionConfig(instructions="base"),
-    )
-    session.begin_response()
-
-    with pytest.raises(RuntimeError, match="active"):
-        session.reserve_response_options(ResponseCreateOptions(instructions="too late"))
-
-
-def test_realtime_model_name_does_not_implicitly_enable_native_duplex():
-    protocol = NativeRealtimeSessionProtocol({})
-
-    event = protocol._session_create_from_realtime({"model": "openbmb/MiniCPM-o-4_5"})
-
-    assert "native_duplex" not in event["session"]["extra_body"]
-    assert "minicpmo45_native_duplex" not in event["session"]["extra_body"]
-
-
-def test_realtime_explicit_native_duplex_flag_is_preserved():
-    protocol = NativeRealtimeSessionProtocol({})
-
-    event = protocol._session_create_from_realtime(
-        {
-            "model": "openbmb/MiniCPM-o-4_5",
-            "extra_body": {"native_duplex": True},
-        }
-    )
-
-    assert event["session"]["extra_body"]["native_duplex"] is True
-
-
-def test_realtime_legacy_native_duplex_alias_is_normalized():
-    # The deprecated model-prefixed spelling still opts in, but everything
-    # downstream (and every session echo) sees only the canonical key.
-    protocol = NativeRealtimeSessionProtocol({})
-
-    event = protocol._session_create_from_realtime(
-        {
-            "model": "openbmb/MiniCPM-o-4_5",
-            "extra_body": {"minicpmo45_native_duplex": True},
-        }
-    )
-
-    assert event["session"]["extra_body"]["native_duplex"] is True
-    assert "minicpmo45_native_duplex" not in event["session"]["extra_body"]
-
-
-def test_realtime_explicit_query_native_duplex_flag_is_available_before_autostart():
-    protocol = NativeRealtimeSessionProtocol(
-        {
-            "model": "openbmb/MiniCPM-o-4_5",
-            "native_duplex": "1",
-        }
-    )
-
-    event = json.loads(asyncio.run(protocol.receive_internal_event_text(None)))
-
-    assert event["type"] == "session.create"
-    assert event["session"]["extra_body"]["native_duplex"] is True
-
-
-def test_realtime_legacy_query_native_duplex_alias_seeds_canonical_key():
-    protocol = NativeRealtimeSessionProtocol(
-        {
-            "model": "openbmb/MiniCPM-o-4_5",
-            "minicpmo45_native_duplex": "1",
-        }
-    )
-
-    event = json.loads(asyncio.run(protocol.receive_internal_event_text(None)))
-
-    assert event["type"] == "session.create"
-    assert event["session"]["extra_body"]["native_duplex"] is True
-    assert "minicpmo45_native_duplex" not in event["session"]["extra_body"]
-
-
-@pytest.mark.asyncio
-async def test_realtime_resume_heartbeat_and_event_ack_translate_without_session_autostart():
-    protocol = NativeRealtimeSessionProtocol(
-        {
-            "model": "openbmb/MiniCPM-o-4_5",
-            "native_duplex": "1",
-        }
-    )
-
-    resume = await protocol._to_duplex_event(
-        {
-            "type": "session.resume",
-            "session_id": "sid-resume",
-            "incarnation": 3,
-            "resume_token": "opaque-token",
-            "last_received_server_event_seq": 17,
-        }
-    )
-    heartbeat = await protocol._to_duplex_event(
-        {
-            "type": "session.heartbeat",
-            "event_id": "event-heartbeat",
-        }
-    )
-    event_ack = await protocol._to_duplex_event(
-        {
-            "type": "session.event_ack",
-            "server_event_seq": 19,
-        }
-    )
-
-    assert resume == {
-        "type": "session.resume",
-        "session_id": "sid-resume",
-        "incarnation": 3,
-        "resume_token": "opaque-token",
-        "last_received_server_event_seq": 17,
-    }
-    assert heartbeat == {
-        "type": "session.heartbeat",
-        "event_id": "event-heartbeat",
-    }
-    assert event_ack == {
-        "type": "session.event_ack",
-        "server_event_seq": 19,
-    }
-    assert protocol._opened is False
-
-    wire_protocol = NativeRealtimeSessionProtocol({})
-    first_wire_event = json.loads(
-        await wire_protocol.receive_internal_event_text(
-            _ProtocolWebSocket(
-                {
-                    "type": "session.resume",
-                    "session_id": "sid-resume",
-                    "incarnation": 3,
-                    "resume_token": "opaque-token",
-                    "last_received_server_event_seq": 17,
-                }
-            )
-        )
-    )
-
-    assert first_wire_event["type"] == "session.resume"
-
-
-@pytest.mark.asyncio
-async def test_realtime_resume_query_suppresses_model_autostart_on_same_url():
-    protocol = NativeRealtimeSessionProtocol(
-        {
-            "model": "openbmb/MiniCPM-o-4_5",
-            "native_duplex": "1",
-            "resume": "1",
-        }
-    )
-    resume = {
-        "type": "session.resume",
-        "session_id": "sid-resume",
-        "incarnation": 3,
-        "resume_token": "opaque-token",
-        "last_received_server_event_seq": 17,
-    }
-
-    first_wire_event = json.loads(await protocol.receive_internal_event_text(_ProtocolWebSocket(resume)))
-
-    assert first_wire_event == resume
-    assert protocol._autostarted_default_session is False
-
-
-def test_realtime_projects_resume_lifecycle_events_without_duplex_prefix():
-    protocol = NativeRealtimeSessionProtocol({})
-
-    created = protocol.encode_outbound_event(
-        {
-            "type": "session.created",
-            "session": {"id": "sid-resume"},
-            "incarnation": 3,
-            "attachment_generation": 1,
-            "resume_token": "first-token",
-        }
-    )[0]
-    resumed = protocol.encode_outbound_event(
-        {
-            "type": "session.resumed",
-            "session_id": "sid-resume",
-            "incarnation": 3,
-            "attachment_generation": 2,
-            "resume_token": "second-token",
-        }
-    )[0]
-    heartbeat = protocol.encode_outbound_event(
-        {
-            "type": "session.heartbeat_ack",
-            "session_id": "sid-resume",
-        }
-    )[0]
-    replaced = protocol.encode_outbound_event(
-        {
-            "type": "session.replaced",
-            "session_id": "sid-resume",
-            "attachment_generation": 1,
-        }
-    )[0]
-    resync = protocol.encode_outbound_event(
-        {
-            "type": "session.resync_required",
-            "session_id": "sid-resume",
-            "reason": "journal_gap",
-        }
-    )[0]
-
-    assert created["type"] == "session.created"
-    assert created["incarnation"] == 3
-    assert created["attachment_generation"] == 1
-    assert created["resume_token"] == "first-token"
-    assert resumed["type"] == "session.resumed"
-    assert resumed["resume_token"] == "second-token"
-    assert heartbeat["type"] == "session.heartbeat_ack"
-    assert replaced["type"] == "session.replaced"
-    assert resync == {
-        "type": "session.resync_required",
-        "session_id": "sid-resume",
-        "reason": "journal_gap",
-        "event_id": resync["event_id"],
-    }
-
-
-def test_realtime_projects_listen_response_identity():
-    protocol = NativeRealtimeSessionProtocol({})
-    protocol.encode_outbound_event({"type": "session.created", "session": {"id": "sid-listen"}})
-
-    bound = protocol.encode_outbound_event(
-        {
-            "type": "response.listen",
-            "session_id": "sid-listen",
-            "epoch": 0,
-            "reason": "model_listen",
-            "model_listen": True,
-            "response_id": "resp_1",
-        }
-    )[0]
-    # A listen that terminates a precreated response keeps the response
-    # identity on the Realtime dialect; clients demultiplex on response_id.
-    assert bound["type"] == "response.listen"
-    assert bound["response_id"] == "resp_1"
-    assert bound["response"]["id"] == "resp_1"
-    assert bound["response"]["status"] == "listening"
-
-    anonymous = protocol.encode_outbound_event(
-        {
-            "type": "response.listen",
-            "session_id": "sid-listen",
-            "epoch": 0,
-            "reason": "silence_or_noise",
-        }
-    )[0]
-    assert "response_id" not in anonymous
-    assert "id" not in anonymous["response"]
-
-
-def test_duplex_session_registry_advances_incarnation_when_id_is_reused():
-    registry = DuplexSessionRegistry()
-
-    first = registry.create(session_id="reused-session")
-    registry.close(first.session_id)
-    second = registry.create(session_id="reused-session")
-
-    assert first.incarnation == 0
-    assert second.incarnation == 1
-
-
-def test_native_input_commit_does_not_advance_model_turn_identity():
-    session = DuplexSession(
-        session_id="sid-model-owned-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-
-    first = session.commit_native_audio_input(transcript="first chunk")
-    second = session.commit_native_audio_input(transcript="second chunk")
-
-    assert session.input_commit_seq == 2
-    assert first.input_commit_seq == 1
-    assert second.input_commit_seq == 2
-    assert first.turn_id == second.turn_id == session.turn_id == 0
-
-
-def test_duplex_session_owns_response_and_overlap_identity():
-    session = DuplexSession(session_id="sid-state-owner", config=DuplexSessionConfig())
-
-    response_id = session.begin_response()
-    session.accumulate_overlap_speech(320)
-    session.accumulate_overlap_speech(180)
-    session.end_response()
-
-    assert session.active_response_id is None
-    assert session.last_response_id == response_id
-    assert session.overlap_speech_ms == 500
-    assert session.reset_overlap_speech() == 500
-    assert session.overlap_speech_ms == 0
-
-
-def test_duplex_session_composes_single_owner_ledgers():
-    session = DuplexSession(session_id="sid-ledgers", config=DuplexSessionConfig())
-
-    session.append_text("hello")
-    session.bind_request("req-1")
-    response_id = session.begin_response(turn_id=3)
-    session.mark_audio_sent(duration_ms=240)
-
-    assert not hasattr(session, "input")
-    assert not hasattr(session, "response")
-    assert not hasattr(session, "playback_ledger")
-    assert not hasattr(session, "conversation")
-    assert session.pending_text == ("hello",)
-    assert session.active_request_id == "req-1"
-    assert session.active_response_id == response_id
-    assert session.active_response_turn_id == 3
-    assert session.playback.sent_ms == 240
-
-    try:
-        session.playback.sent_ms = 480
-    except (AttributeError, TypeError):
-        pass
-    else:
-        raise AssertionError("playback view must be immutable")
-
-
-def test_duplex_barge_in_advances_epoch_and_drops_uncommitted_assistant_text():
-    registry = DuplexSessionRegistry()
-    session = registry.create()
-    response_id = session.begin_response()
-    session.bind_request("chatcmpl-duplex-test")
-    session.append_assistant_text("unplayed answer")
-
-    new_epoch = session.barge_in()
-
-    assert response_id is not None
-    assert new_epoch == 1
-    assert session.epoch == 1
-    assert session.active_request_id is None
-    assert session.active_response_id is None
-    assert session.assistant_text_buffer == ()
-    assert session.history == ()
-    assert session.turn_state == DuplexTurnState.BARGE_IN
-
-
-def test_duplex_playback_ack_tracks_committed_cursor_separately():
-    registry = DuplexSessionRegistry()
-    session = registry.create()
-    session.mark_audio_sent(duration_ms=10_000)
-
-    session.acknowledge_playback(played_ms=2_000)
-
-    assert session.playback.generated_ms == 10_000
-    assert session.playback.sent_ms == 10_000
-    assert session.playback.played_ms == 2_000
-    assert session.playback.committed_ms == 2_000
-
-
-@pytest.mark.parametrize("sample_rate_hz,frame_count", [(22_050, 23), (24_000, 24)])
-def test_duplex_generated_audio_rounds_only_cumulative_frames(sample_rate_hz: int, frame_count: int):
-    session = DuplexSessionRegistry().create()
-    response_id = session.begin_response()
-
-    durations = [
-        session.record_generated_audio(response_id, frame_count=1, sample_rate_hz=sample_rate_hz)
-        for _ in range(frame_count)
-    ]
-
-    assert durations[:-1] == [0] * (frame_count - 1)
-    assert durations[-1] == 1
-    assert session.playback.generated_ms == 1
-    assert session.playback.sent_ms == 0
-    assert session.playback.played_ms == 0
-
-
-def test_duplex_generated_audio_rejects_rate_change_without_advancing():
-    session = DuplexSessionRegistry().create()
-    response_id = session.begin_response()
-    session.record_generated_audio(response_id, frame_count=2205, sample_rate_hz=22_050)
-
-    with pytest.raises(ValueError, match="sample rate changed"):
-        session.record_generated_audio(response_id, frame_count=2400, sample_rate_hz=24_000)
-
-    assert session.playback.generated_ms == 100
-    assert session.playback.sent_ms == 0
-
-
-def test_duplex_late_audio_accounting_cannot_change_new_response():
-    session = DuplexSessionRegistry().create()
-    old_response = session.begin_response()
-    session.record_generated_audio(old_response, frame_count=2205, sample_rate_hz=22_050)
-    session.barge_in()
-    new_response = session.begin_response()
-    session.record_generated_audio(new_response, frame_count=2400, sample_rate_hz=48_000)
-    current_state = session.turn_state
-
-    assert session.record_generated_audio(old_response, frame_count=2205, sample_rate_hz=22_050) is None
-    session.mark_audio_sent(100, response_id=old_response, text_chars=99)
-
-    assert session.playback_for_response(old_response).sent_ms == 100
-    assert session.playback.generated_ms == 50
-    assert session.playback.sent_ms == 0
-    assert session.assistant_audio_text_marks == ()
-    assert session.turn_state == current_state
-
-
-def test_duplex_history_commit_uses_audio_text_alignment_marks():
-    registry = DuplexSessionRegistry()
-    session = registry.create()
-    session.begin_response()
-
-    session.append_assistant_text("hello ")
-    session.mark_audio_sent(duration_ms=1_000, text_chars=6)
-    session.append_assistant_text("world")
-    session.mark_audio_sent(duration_ms=2_000, text_chars=11)
-    session.acknowledge_playback(played_ms=1_200, committed_ms=1_200)
-
-    committed = session.end_response(commit_text=True)
-
-    assert committed == {"role": "assistant", "content": "hello w"}
-
-
-def test_turn_controller_accepts_external_signal_source():
-    registry = DuplexSessionRegistry()
-    session = registry.create()
-    controller = DuplexTurnController()
-
-    event = controller.signal(session, DuplexTurnEventType.USER_STARTED.value)
-
-    assert event["type"] == "turn.event"
-    assert event["event"] == "user_started"
-    assert event["turn_state"] == "user_speaking"
-    assert session.turn_state == DuplexTurnState.USER_SPEAKING
-
-
-def test_duplex_capabilities_do_not_claim_core_kv_or_input_append():
-    registry = DuplexSessionRegistry()
-    session = registry.create()
-    caps = session.capabilities.as_dict()
-
-    assert caps["implementation_level"] == "serving_session_adapter"
-    assert caps["supports_kv_lease"] is False
-    assert caps["supports_input_append"] is False
-    assert caps["supports_reencode_context"] is True
-    assert caps["adapter_patterns"] == ["chunk_group_append"]
-    assert "turn_commit_only" in caps["input_modes"]
-    assert "client_event" in caps["signal_sources"]
-
-
-def test_minicpmo_native_capabilities_separate_model_state_from_core_kv_lease():
-    caps = minicpmo45_native_capabilities(max_sessions=2).as_dict()
-
-    assert caps["implementation_level"] == "model_native_duplex"
-    assert caps["supports_input_append"] is True
-    assert caps["input_modes"] == ["append_audio_chunk"]
-    assert caps["adapter_patterns"] == ["scheduler_data_plane"]
-    assert caps["supports_model_internal_state"] is True
-    assert caps["requires_model_runner_kv"] is True
-    assert caps["requires_native_stage_role"] is True
-    assert caps["supports_kv_lease"] is False
-    assert caps["supports_core_kv_lease"] is False
-    assert caps["supports_stage_resumption"] is True
-    assert caps["supports_scheduler_native_append"] is False
-    assert caps["supports_core_resumable_request"] is True
-    assert caps["supports_stage_connector_handoff"] is True
-    assert caps["supports_audio_truncate"] is True
-    assert caps["supports_barge_in"] is True
-    assert caps["target_barge_in_latency_ms"] is None
-    assert caps["supports_multi_session"] is True
-    assert caps["supports_multi_session_same_replica"] is True
-    assert caps["supports_session_lease"] is True
-    assert caps["supports_session_resume"] is True
-    assert caps["session_admission_mode"] == "engine_managed"
-    assert caps["stage_handoff_transport"] == "scheduler_data_plane"
-
-
-def test_duplex_overlap_policy_auto_falls_back_to_listen_only():
-    from vllm_omni.entrypoints.duplex.protocol import (
-        DuplexOverlapPolicy,
-        DuplexSessionConfig,
-    )
-
-    assert DuplexSessionConfig._normalize_overlap_policy("auto") == DuplexOverlapPolicy.LISTEN_ONLY.value
-
-
-def test_minicpmo_native_capabilities_do_not_overclaim_single_session_deployment():
-    caps = minicpmo45_native_capabilities(max_sessions=1).as_dict()
-
-    assert caps["supports_multi_session"] is False
-    assert caps["supports_multi_session_same_replica"] is False
-
-
-def test_duplex_overlap_policy_defaults_and_invalid_values_to_listen_only():
-    assert DuplexSessionConfig().overlap_policy == DuplexOverlapPolicy.LISTEN_ONLY.value
-    assert DuplexSessionConfig._normalize_overlap_policy("not-a-policy") == DuplexOverlapPolicy.LISTEN_ONLY.value
diff --git a/tests/entrypoints/openai/test_duplex_session_attachment.py b/tests/entrypoints/openai/test_duplex_session_attachment.py
index 13bd327615f..9d7a208b54b 100644
--- a/tests/entrypoints/openai/test_duplex_session_attachment.py
+++ b/tests/entrypoints/openai/test_duplex_session_attachment.py
@@ -133,7 +133,7 @@ async def failing_send(payload):
         assert accepted.call_args_list == expected_calls
         raise RuntimeError("transport lost")
 
-    await registry.create("sid-send-failure", incarnation=0, send=failing_send, close=mocker.AsyncMock())
+    await registry.create("sid-send-failure", send=failing_send, close=mocker.AsyncMock())
 
     with pytest.raises(RuntimeError, match="transport lost"):
         await registry.send_event(
@@ -152,7 +152,7 @@ async def test_registry_detached_event_is_accepted_only_when_journaled(mocker, j
     registry = DuplexSessionAttachmentRegistry(replay_ttl_s=60.0, replay_max_bytes_per_session=4096)
     send = mocker.AsyncMock()
     accepted = mocker.Mock()
-    created = await registry.create("sid-detached-acceptance", incarnation=0, send=send, close=mocker.AsyncMock())
+    created = await registry.create("sid-detached-acceptance", send=send, close=mocker.AsyncMock())
     await registry.detach("sid-detached-acceptance", attachment_generation=created.attachment_generation)
 
     entry = await registry.send_event(
@@ -175,7 +175,7 @@ async def test_registry_unjournaled_event_is_accepted_after_successful_send(mock
     async def send(payload):
         accepted.assert_not_called()
 
-    await registry.create("sid-live-acceptance", incarnation=0, send=send, close=mocker.AsyncMock())
+    await registry.create("sid-live-acceptance", send=send, close=mocker.AsyncMock())
 
     entry = await registry.send_event(
         "sid-live-acceptance",
@@ -193,7 +193,7 @@ async def test_registry_overflow_does_not_accept_or_send_event(mocker) -> None:
     registry = DuplexSessionAttachmentRegistry(replay_ttl_s=60.0, replay_max_bytes_per_session=100)
     accepted = mocker.Mock()
     send = mocker.AsyncMock()
-    await registry.create("sid-overflow-acceptance", incarnation=0, send=send, close=mocker.AsyncMock())
+    await registry.create("sid-overflow-acceptance", send=send, close=mocker.AsyncMock())
 
     with pytest.raises(DuplexJournalOverflowError, match="byte limit"):
         await registry.send_event(
@@ -231,13 +231,12 @@ async def send_b(payload):
     async def close_b(reason):
         closes_b.append(reason)
 
-    created = await registry.create("sid", incarnation=2, send=send_a, close=close_a)
+    created = await registry.create("sid", send=send_a, close=close_a)
     await registry.send_event("sid", {"type": "event-1"})
     await registry.send_event("sid", {"type": "event-2"})
 
     resumed = await registry.resume(
         "sid",
-        incarnation=2,
         resume_token=created.resume_token.plaintext,
         last_received_server_event_seq=1,
         send=send_b,
@@ -260,6 +259,34 @@ async def close_b(reason):
     assert closes_a == [] and sends_b == [] and closes_b == []
 
 
+@pytest.mark.asyncio
+async def test_registry_detach_without_a_generation_targets_the_current_attachment_once() -> None:
+    registry = DuplexSessionAttachmentRegistry(replay_ttl_s=60.0, replay_max_bytes_per_session=4096)
+    sends: list[dict] = []
+
+    async def send(payload):
+        sends.append(payload)
+
+    async def close(reason):
+        return None
+
+    await registry.create("sid-current", send=send, close=close)
+
+    # The outbound pump outlives any one connection and only knows the session:
+    # ``None`` means "whichever socket is attached right now".
+    assert await registry.detach("sid-current", attachment_generation=None) is True
+    # A second report of the same dead socket is not a new detach, so it cannot
+    # restart the engine's disconnect grace window.
+    assert await registry.detach("sid-current", attachment_generation=None) is False
+    assert await registry.detach("sid-current", attachment_generation=1) is False
+    assert await registry.is_current_attachment("sid-current", 1) is False
+
+    # A detached session still journals for a later resume.
+    await registry.send_event("sid-current", {"type": "event-1"})
+    assert sends == []
+    assert await registry.detach("missing-session", attachment_generation=None) is False
+
+
 @pytest.mark.asyncio
 async def test_registry_resume_sends_activation_then_replay_before_new_live_events() -> None:
     registry = DuplexSessionAttachmentRegistry(
@@ -282,13 +309,12 @@ async def new_send(payload):
             activation_started.set()
             await release_activation.wait()
 
-    created = await registry.create("sid-order", incarnation=0, send=old_send, close=close)
+    created = await registry.create("sid-order", send=old_send, close=close)
     await registry.detach("sid-order", attachment_generation=1)
     await registry.send_event("sid-order", {"type": "replayed"})
     resume_task = asyncio.create_task(
         registry.resume(
             "sid-order",
-            incarnation=0,
             resume_token=created.resume_token.plaintext,
             last_received_server_event_seq=0,
             send=new_send,
@@ -322,13 +348,12 @@ async def failing_send(payload):
     async def close(reason):
         del reason
 
-    created = await registry.create("sid-recovery", incarnation=0, send=send, close=close)
+    created = await registry.create("sid-recovery", send=send, close=close)
     await registry.detach("sid-recovery", attachment_generation=1)
 
     with pytest.raises(RuntimeError, match="transport lost"):
         await registry.resume(
             "sid-recovery",
-            incarnation=0,
             resume_token=created.resume_token.plaintext,
             last_received_server_event_seq=0,
             send=failing_send,
@@ -342,7 +367,6 @@ async def close(reason):
 
     recovered = await registry.resume(
         "sid-recovery",
-        incarnation=0,
         resume_token=created.resume_token.plaintext,
         last_received_server_event_seq=0,
         send=send,
@@ -353,7 +377,6 @@ async def close(reason):
     with pytest.raises(InvalidResumeTokenError):
         await registry.resume(
             "sid-recovery",
-            incarnation=0,
             resume_token=created.resume_token.plaintext,
             last_received_server_event_seq=0,
             send=send,
@@ -374,13 +397,12 @@ async def send(payload):
     async def close(reason):
         del reason
 
-    created = await registry.create("sid-race", incarnation=0, send=send, close=close)
+    created = await registry.create("sid-race", send=send, close=close)
 
     async def attempt():
         try:
             return await registry.resume(
                 "sid-race",
-                incarnation=0,
                 resume_token=created.resume_token.plaintext,
                 last_received_server_event_seq=0,
                 send=send,
@@ -396,7 +418,7 @@ async def attempt():
 
 
 @pytest.mark.asyncio
-async def test_registry_keeps_sessions_journals_and_incarnations_isolated() -> None:
+async def test_registry_keeps_sessions_journals_and_tokens_isolated() -> None:
     registry = DuplexSessionAttachmentRegistry(
         replay_ttl_s=60.0,
         replay_max_bytes_per_session=4096,
@@ -408,8 +430,8 @@ async def send(payload):
     async def close(reason):
         del reason
 
-    created_a = await registry.create("sid-a", incarnation=1, send=send, close=close)
-    created_b = await registry.create("sid-b", incarnation=4, send=send, close=close)
+    created_a = await registry.create("sid-a", send=send, close=close)
+    created_b = await registry.create("sid-b", send=send, close=close)
     await registry.detach("sid-a", attachment_generation=1)
     await registry.detach("sid-b", attachment_generation=1)
     await registry.send_event("sid-a", {"type": "a-only"})
@@ -417,7 +439,6 @@ async def close(reason):
 
     resumed_a = await registry.resume(
         "sid-a",
-        incarnation=1,
         resume_token=created_a.resume_token.plaintext,
         last_received_server_event_seq=0,
         send=send,
@@ -425,7 +446,6 @@ async def close(reason):
     )
     resumed_b = await registry.resume(
         "sid-b",
-        incarnation=4,
         resume_token=created_b.resume_token.plaintext,
         last_received_server_event_seq=0,
         send=send,
@@ -434,11 +454,10 @@ async def close(reason):
 
     assert [entry.payload["type"] for entry in resumed_a.replay_entries] == ["a-only"]
     assert [entry.payload["type"] for entry in resumed_b.replay_entries] == ["b-only"]
-    with pytest.raises(ValueError, match="incarnation mismatch"):
+    with pytest.raises(InvalidResumeTokenError):
         await registry.resume(
             "sid-a",
-            incarnation=2,
-            resume_token=resumed_a.resume_token.plaintext,
+            resume_token=resumed_b.resume_token.plaintext,
             last_received_server_event_seq=1,
             send=send,
             close=close,
@@ -458,7 +477,7 @@ async def send(payload):
     async def close(reason):
         del reason
 
-    created = await registry.create("sid-repr", incarnation=0, send=send, close=close)
+    created = await registry.create("sid-repr", send=send, close=close)
     await registry.detach("sid-repr", attachment_generation=1)
     entry = await registry.send_event(
         "sid-repr",
@@ -469,3 +488,67 @@ async def close(reason):
     assert created.resume_token.plaintext not in repr(created)
     assert created.resume_token.plaintext not in repr(entry)
     assert created.resume_token.plaintext not in repr(registry)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("cancel_on", ["activation", "replay"])
+async def test_registry_resume_cancelled_mid_delivery_rolls_back_like_a_failure(cancel_on: str) -> None:
+    """Cancellation must take the same rollback as an ordinary delivery failure.
+
+    ``CancelledError`` derives from ``BaseException``, so an ``except
+    Exception`` around the activation and replay sends let a cancelled resume
+    keep its attachment as the current generation while the token it rotated
+    past was already gone — the session left attached to an unusable transport
+    with no way back. Both send points are covered because either can be the
+    one that gets cancelled.
+    """
+    registry = DuplexSessionAttachmentRegistry(replay_ttl_s=60.0, replay_max_bytes_per_session=4096)
+
+    async def send(payload):
+        del payload
+
+    async def close(reason):
+        del reason
+
+    created = await registry.create("sid-cancel", send=send, close=close)
+    # One journaled event, so the replay loop has something to send.
+    await registry.send_event("sid-cancel", {"type": "response.output_text.delta", "delta": "a"})
+    await registry.detach("sid-cancel", attachment_generation=1)
+
+    sends = 0
+    cancel_at = 1 if cancel_on == "activation" else 2
+
+    async def cancelling_send(payload):
+        del payload
+        nonlocal sends
+        sends += 1
+        if sends == cancel_at:
+            raise asyncio.CancelledError
+
+    with pytest.raises(asyncio.CancelledError):
+        await registry.resume(
+            "sid-cancel",
+            resume_token=created.resume_token.plaintext,
+            last_received_server_event_seq=0,
+            send=cancelling_send,
+            close=close,
+            activation_payload_factory=lambda token, generation: {
+                "type": "session.resumed",
+                "resume_token": token.plaintext,
+                "attachment_generation": generation,
+            },
+        )
+
+    assert sends == cancel_at, "the send that was cancelled is the one under test"
+    # The cancelled attachment must not remain current...
+    assert not await registry.has_attachment("sid-cancel")
+    # ...and the token the caller presented has to work again, or the session
+    # is unreachable: resume() had already rotated past it.
+    recovered = await registry.resume(
+        "sid-cancel",
+        resume_token=created.resume_token.plaintext,
+        last_received_server_event_seq=0,
+        send=send,
+        close=close,
+    )
+    assert recovered.attachment_generation == 3
diff --git a/tests/entrypoints/openai_api/test_api_server_guards.py b/tests/entrypoints/openai_api/test_api_server_guards.py
index 21725183a63..37e2dc4303e 100644
--- a/tests/entrypoints/openai_api/test_api_server_guards.py
+++ b/tests/entrypoints/openai_api/test_api_server_guards.py
@@ -920,7 +920,6 @@ async def warmup(self):
     monkeypatch.setattr(api_server, "create_streaming_video_handler", lambda **_k: _marker("streaming_video"))
     monkeypatch.setattr(api_server, "OpenAIServingRealtime", _FakeCtor)
     monkeypatch.setattr(api_server, "OmniOpenAIServingVideo", _FakeCtor)
-    monkeypatch.setattr(api_server, "should_enable_duplex_endpoint", lambda *_a, **_k: False)
 
     state = State()
     await api_server.omni_init_app_state(engine, state, _minimal_args())
diff --git a/tests/entrypoints/openai_api/test_duplex_api_server.py b/tests/entrypoints/openai_api/test_duplex_api_server.py
new file mode 100644
index 00000000000..b528cbc2a41
--- /dev/null
+++ b/tests/entrypoints/openai_api/test_duplex_api_server.py
@@ -0,0 +1,414 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Guards for the duplex-only API server (unified full-duplex framework).
+
+A model whose pipeline declares ``duplex_plugin`` is served through
+``DuplexOmni`` and nothing else: sessions run over ``/v1/realtime?duplex=1``
+(alias ``/v1/duplex``) and every turn-based route reports "not available".
+These tests lock that shape, which ``test_api_server_guards.py`` covers for the
+diffusion and multi-stage servers:
+
+* the pipeline probe that decides duplex vs turn-based at startup,
+* the ``app.state`` snapshot of a duplex server (what is wired, what stays
+  ``None``),
+* both duplex websocket routes reaching the session handler, and
+  ``/v1/realtime`` without the flag still reporting the turn-based Realtime API
+  as unavailable,
+* the startup-warmup gate that holds real clients while the warmup session runs.
+
+CPU-only: no engine is started; ``DuplexOmni`` is subclassed with just the
+accessors the app-state wiring reads.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from types import SimpleNamespace
+
+import pytest
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+from starlette.datastructures import State
+from starlette.websockets import WebSocketDisconnect
+
+from vllm_omni.config.config_factory import StageConfigFactory
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex.config import DuplexCapabilities
+from vllm_omni.entrypoints.duplex.serving import OmniDuplexSessionHandler
+from vllm_omni.entrypoints.duplex_omni import DuplexOmni
+from vllm_omni.entrypoints.openai import api_server
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+# ``app.state`` of a duplex-only server. Presence is not enough: a route whose
+# handler is missing answers "not available", so "not wired" is written as None.
+_DUPLEX_APP_STATE_KEYS = {
+    "engine_client",
+    "log_stats",
+    "args",
+    "sleeping_stages",
+    "stage_configs",
+    "vllm_config",
+    "diffusion_engine",
+    "openai_serving_models",
+    "serving_tokenization",
+    "serving_tokens",
+    "online_renderer",
+    "openai_serving_chat",
+    "openai_serving_chat_batch",
+    "openai_serving_completion",
+    "openai_serving_responses",
+    "openai_serving_embedding",
+    "openai_serving_pooling",
+    "openai_serving_classification",
+    "openai_serving_scores",
+    "openai_serving_transcription",
+    "openai_serving_translation",
+    "openai_serving_speech",
+    "openai_serving_audio_generate",
+    "openai_serving_video",
+    "openai_streaming_speech",
+    "openai_streaming_video",
+    "openai_streaming_video_output",
+    "openai_serving_realtime",
+    "openai_serving_realtime_robot",
+    "anthropic_serving_messages",
+    "openai_serving_duplex",
+    "enable_server_load_tracking",
+    "server_load_metrics",
+}
+#: Every turn-based service, plus the Realtime route that is not the duplex one.
+#: ``openai_serving_chat`` is absent: a duplex engine also serves chat, through
+#: the ordinary turn-based service, because DuplexOmni extends AsyncOmni.
+#: ``online_renderer`` is absent for the same reason -- the chat service needs it.
+_DUPLEX_MUST_BE_NONE = _DUPLEX_APP_STATE_KEYS - {
+    "engine_client",
+    "log_stats",
+    "args",
+    "sleeping_stages",
+    "stage_configs",
+    "vllm_config",
+    "openai_serving_models",
+    "openai_serving_duplex",
+    "openai_serving_chat",
+    "online_renderer",
+    "enable_server_load_tracking",
+    "server_load_metrics",
+}
+_DUPLEX_MUST_BE_WIRED = {
+    "engine_client",
+    "args",
+    "stage_configs",
+    "vllm_config",
+    "openai_serving_models",
+    "openai_serving_duplex",
+    "openai_serving_chat",
+}
+
+
+class _FakeDuplexOmni(DuplexOmni):
+    """A ``DuplexOmni`` without an engine: only what the app-state wiring reads."""
+
+    def __init__(self) -> None:
+        self.model = "demo-duplex-model"
+        self._stage_configs = [object(), object(), object()]
+        self._vllm_config = SimpleNamespace(
+            lora_config=None,
+            model_config=SimpleNamespace(),
+            parallel_config=SimpleNamespace(_api_process_rank=0),
+        )
+        self._duplex_session_config = DuplexSessionRuntimeConfig()
+        self._capabilities = DuplexCapabilities(supports_chat_completions=True)
+
+    async def get_vllm_config(self):
+        return self._vllm_config
+
+    async def get_supported_tasks(self) -> tuple[str, ...]:
+        return ("generate",)
+
+    async def get_tokenizer(self):
+        return SimpleNamespace(chat_template="{{ messages }}")
+
+    @property
+    def stage_configs(self) -> list[object]:
+        return self._stage_configs
+
+    @property
+    def duplex_session_config(self) -> DuplexSessionRuntimeConfig:
+        return self._duplex_session_config
+
+    @property
+    def duplex_capabilities(self) -> DuplexCapabilities:
+        return self._capabilities
+
+    # Properties on AsyncOmni, so the fake overrides rather than assigns them.
+    @property
+    def model_config(self) -> SimpleNamespace:
+        return SimpleNamespace()
+
+    @property
+    def renderer(self) -> SimpleNamespace:
+        return SimpleNamespace()
+
+
+class _FakeModels:
+    def __init__(self, *args, **kwargs) -> None:
+        self.base_model_paths = kwargs.get("base_model_paths") or []
+
+
+def _minimal_args(**overrides) -> SimpleNamespace:
+    args = SimpleNamespace(
+        model="demo-duplex-model",
+        served_model_name=None,
+        disable_log_stats=True,
+        enable_log_requests=False,
+        max_log_len=None,
+        enable_server_load_tracking=False,
+        trust_remote_code=True,
+        deploy_config=None,
+        # What the chat service reads when a duplex model also serves chat.
+        chat_template=None,
+        chat_template_content_format="auto",
+        trust_request_chat_template=False,
+        default_chat_template_kwargs=None,
+        response_role="assistant",
+        return_tokens_as_token_ids=False,
+        enable_auto_tool_choice=False,
+        exclude_tools_when_tool_choice_none=False,
+        tool_call_parser=None,
+        structured_outputs_config=SimpleNamespace(reasoning_parser=None),
+        enable_prompt_tokens_details=False,
+        enable_force_include_usage=False,
+        enable_log_outputs=False,
+        enable_log_deltas=False,
+    )
+    for key, value in overrides.items():
+        setattr(args, key, value)
+    return args
+
+
+# --------------------------------------------------------------------------- #
+# Startup: which entrypoint class serves the model                            #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.parametrize(
+    ("pipeline_config", "expected"),
+    [
+        (SimpleNamespace(duplex_plugin="pkg.mod.Plugin"), True),
+        (SimpleNamespace(duplex_plugin=None), False),
+        (SimpleNamespace(duplex_plugin=""), False),
+        (SimpleNamespace(), False),
+        (None, False),
+    ],
+)
+def test_duplex_model_probe_follows_the_pipeline_plugin(monkeypatch, pipeline_config, expected: bool) -> None:
+    """``duplex_plugin`` alone decides whether ``serve`` builds ``DuplexOmni``."""
+    seen: dict[str, object] = {}
+
+    def fake_get_pipeline_config(*, model, trust_remote_code, deploy_config_path=None, **_kwargs):
+        seen.update(model=model, trust_remote_code=trust_remote_code, deploy_config_path=deploy_config_path)
+        return pipeline_config
+
+    monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", fake_get_pipeline_config)
+
+    kwargs = {"trust_remote_code": True, "deploy_config": "deploy.yaml"}
+    assert api_server._is_duplex_model("demo-duplex-model", kwargs) is expected
+    assert seen == {
+        "model": "demo-duplex-model",
+        "trust_remote_code": True,
+        "deploy_config_path": "deploy.yaml",
+    }
+
+
+def test_duplex_model_probe_propagates_resolution_errors(monkeypatch) -> None:
+    """A pipeline that cannot be resolved must fail startup, not fall back to turn-based."""
+
+    def fake_get_pipeline_config(**_kwargs):
+        raise ValueError("needs trust_remote_code=True")
+
+    monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", fake_get_pipeline_config)
+
+    with pytest.raises(ValueError, match="trust_remote_code"):
+        api_server._is_duplex_model("demo-duplex-model", {})
+
+
+# --------------------------------------------------------------------------- #
+# app.state of a duplex-only server                                           #
+# --------------------------------------------------------------------------- #
+
+
+@pytest.mark.asyncio
+async def test_duplex_app_state_wires_only_the_session_surfaces(monkeypatch) -> None:
+    """Lock the duplex ``app.state``: the two session-backed surfaces are live, every turn-based service is None.
+
+    Fails if a turn-based service is wired into a duplex server (its route
+    would answer instead of reporting "not available"), or if a key the routes
+    read disappears. ``openai_serving_chat`` is the one shared name: the route
+    is served, but by the adapter that runs it on a duplex session, never by
+    the turn-based chat service.
+    """
+    monkeypatch.setattr(api_server, "OpenAIServingModels", _FakeModels)
+    monkeypatch.setattr(api_server, "OnlineRenderer", lambda **kwargs: SimpleNamespace(**kwargs))
+    monkeypatch.setattr(api_server, "OmniOpenAIServingChat", lambda **kwargs: SimpleNamespace(**kwargs))
+    engine = _FakeDuplexOmni()
+    state = State()
+
+    await api_server.omni_init_app_state(engine, state, _minimal_args())
+
+    present = {key for key in _DUPLEX_APP_STATE_KEYS if hasattr(state, key)}
+    assert present == _DUPLEX_APP_STATE_KEYS
+    not_wired = sorted(key for key in _DUPLEX_MUST_BE_WIRED if getattr(state, key) is None)
+    assert not not_wired, f"duplex app.state keys registered but not wired: {not_wired}"
+    unexpectedly_set = sorted(key for key in _DUPLEX_MUST_BE_NONE if getattr(state, key) is not None)
+    assert not unexpectedly_set, f"turn-based services wired into a duplex server: {unexpectedly_set}"
+    assert isinstance(state.openai_serving_duplex, OmniDuplexSessionHandler)
+    assert state.openai_serving_chat is not None
+    assert state.engine_client is engine
+    assert state.vllm_config is engine._vllm_config
+
+
+# --------------------------------------------------------------------------- #
+# Routes                                                                      #
+# --------------------------------------------------------------------------- #
+
+
+class _RecordingHandler:
+    """Stands in for ``OmniDuplexSessionHandler`` on the app state."""
+
+    def __init__(self) -> None:
+        self.queries: list[dict[str, str]] = []
+
+    async def handle_realtime_session(self, websocket) -> None:
+        await websocket.accept()
+        self.queries.append(dict(websocket.query_params))
+        await websocket.send_json({"type": "session.created", "session": {"id": "duplex-test"}})
+        await websocket.close()
+
+
+def _duplex_app(handler: object) -> FastAPI:
+    app = FastAPI()
+    app.include_router(api_server.router)
+    app.state.openai_serving_duplex = handler
+    # A duplex server serves no turn-based Realtime route.
+    app.state.openai_serving_realtime = None
+    return app
+
+
+@pytest.mark.parametrize("path", ["/v1/duplex", "/v1/realtime?duplex=1"])
+def test_both_duplex_routes_reach_the_session_handler(path: str) -> None:
+    """``/v1/duplex`` is an alias of ``/v1/realtime?duplex=1``: same handler, same protocol."""
+    handler = _RecordingHandler()
+
+    with TestClient(_duplex_app(handler)) as client:
+        with client.websocket_connect(path) as websocket:
+            assert websocket.receive_json()["type"] == "session.created"
+            with pytest.raises(WebSocketDisconnect):
+                websocket.receive_text()
+
+    assert len(handler.queries) == 1
+
+
+@pytest.mark.parametrize("flag", ["1", "true", "on"])
+def test_realtime_route_switches_to_duplex_only_for_the_documented_flag_values(flag: str) -> None:
+    handler = _RecordingHandler()
+
+    with TestClient(_duplex_app(handler)) as client:
+        with client.websocket_connect(f"/v1/realtime?duplex={flag}") as websocket:
+            assert websocket.receive_json()["type"] == "session.created"
+            with pytest.raises(WebSocketDisconnect):
+                websocket.receive_text()
+
+    assert handler.queries == [{"duplex": flag}]
+
+
+@pytest.mark.parametrize("query", ["", "?model=openbmb%2FMiniCPM-o-4_5"])
+def test_realtime_without_a_duplex_flag_reaches_the_session_handler(query: str) -> None:
+    """A bare connection to a duplex deployment is a duplex session.
+
+    ``?duplex=1`` is the spelling the server advertises, but it is not a
+    requirement: a deployment that declares a duplex plugin answers plain
+    ``/v1/realtime`` too, so a stock Realtime client needs no vendor query
+    parameter.
+    """
+    handler = _RecordingHandler()
+
+    with TestClient(_duplex_app(handler)) as client:
+        with client.websocket_connect(f"/v1/realtime{query}") as websocket:
+            assert websocket.receive_json()["type"] == "session.created"
+            with pytest.raises(WebSocketDisconnect):
+                websocket.receive_text()
+
+    assert len(handler.queries) == 1
+
+
+@pytest.mark.parametrize("query", ["?duplex=0", "?duplex=false", "?duplex=off"])
+def test_realtime_opted_out_of_duplex_falls_through_to_the_turn_based_route(query: str) -> None:
+    """An explicit opt-out selects the legacy handler, which a duplex server does not mount."""
+    handler = _RecordingHandler()
+
+    with TestClient(_duplex_app(handler)) as client:
+        with client.websocket_connect(f"/v1/realtime{query}") as websocket:
+            assert websocket.receive_json() == {
+                "type": "error",
+                "error": "Realtime API is not available",
+                "code": "unsupported",
+            }
+            with pytest.raises(WebSocketDisconnect):
+                websocket.receive_text()
+
+    assert handler.queries == []
+
+
+# --------------------------------------------------------------------------- #
+# Startup warmup gate                                                         #
+# --------------------------------------------------------------------------- #
+
+
+def _warmup_websocket(warmup_done: asyncio.Event | None, query: dict[str, str]) -> SimpleNamespace:
+    return SimpleNamespace(
+        app=SimpleNamespace(state=SimpleNamespace(duplex_warmup_done=warmup_done)),
+        query_params=query,
+    )
+
+
+@pytest.mark.asyncio
+async def test_warmup_gate_holds_clients_until_the_warmup_session_finishes() -> None:
+    warmup_done = asyncio.Event()
+    websocket = _warmup_websocket(warmup_done, {})
+
+    waiting = asyncio.create_task(api_server._wait_for_duplex_warmup(websocket))
+    with pytest.raises(asyncio.TimeoutError):
+        await asyncio.wait_for(asyncio.shield(waiting), timeout=0.05)
+
+    warmup_done.set()
+    await asyncio.wait_for(waiting, timeout=1.0)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    ("warmup_done", "query"),
+    [
+        (None, {}),
+        (asyncio.Event(), {"vllm_omni_warmup": "1"}),
+    ],
+    ids=["no-warmup-configured", "the-warmup-connection-itself"],
+)
+async def test_warmup_gate_lets_the_warmup_connection_and_plain_servers_through(warmup_done, query) -> None:
+    websocket = _warmup_websocket(warmup_done, query)
+
+    await asyncio.wait_for(api_server._wait_for_duplex_warmup(websocket), timeout=1.0)
+
+
+@pytest.mark.asyncio
+async def test_a_model_that_does_not_declare_chat_completions_does_not_get_the_route(monkeypatch) -> None:
+    """The decision stays the model's: no capability, no chat service, and the route says so."""
+    monkeypatch.setattr(api_server, "OpenAIServingModels", _FakeModels)
+    engine = _FakeDuplexOmni()
+    engine._capabilities = DuplexCapabilities(supports_chat_completions=False)
+    state = State()
+
+    await api_server.omni_init_app_state(engine, state, _minimal_args())
+
+    assert state.openai_serving_chat is None
+    assert isinstance(state.openai_serving_duplex, OmniDuplexSessionHandler)
diff --git a/tests/entrypoints/openai_api/test_duplex_handler.py b/tests/entrypoints/openai_api/test_duplex_handler.py
deleted file mode 100644
index 0b64e7f14b9..00000000000
--- a/tests/entrypoints/openai_api/test_duplex_handler.py
+++ /dev/null
@@ -1,9491 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-import base64
-import io
-import json
-import struct
-import wave
-from collections.abc import Callable
-from contextlib import nullcontext
-from types import SimpleNamespace
-from typing import Any
-
-import numpy as np
-import pytest
-from starlette.websockets import WebSocketDisconnect
-
-# Import the OpenAI entrypoints package at collection time, before pytest
-# attaches its caplog handlers to the root logger. vllm's api_server
-# transitively imports model_hosting_container_standards, whose import-time
-# configure_root_logger() raises the level of every handler then attached to
-# the root logger to ERROR. The serving runtime under test reaches this chain
-# lazily (runtime_bridge -> entrypoints.openai.protocol.audio), so without
-# this eager import the side effect fires mid-test and silences caplog for
-# the remainder of the session. Before the capability predicate moved to
-# vllm_omni.entrypoints.duplex.capability, this file imported the package at
-# module scope implicitly.
-import vllm_omni.entrypoints.openai  # noqa: F401
-from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
-from vllm_omni.engine.duplex.control_client import DuplexControlRequestError
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity
-from vllm_omni.engine.duplex.messages import DuplexFence, DuplexSessionLifecycleMessage
-from vllm_omni.engine.duplex.runtime import duplex_resource_request_id
-from vllm_omni.entrypoints.duplex.protocol import (
-    DuplexCapabilities,
-    DuplexOverlapPolicy,
-    DuplexPlaybackCommitPolicy,
-    DuplexSession,
-    DuplexSessionConfig,
-    ResponseCreateOptions,
-)
-from vllm_omni.entrypoints.duplex.realtime_session import NativeRealtimeSessionProtocol
-from vllm_omni.entrypoints.duplex.runtime_adapter import ServingRuntimeConfigError
-from vllm_omni.entrypoints.duplex.serving import (
-    OmniDuplexSessionHandler,
-    should_enable_duplex_endpoint,
-)
-from vllm_omni.entrypoints.duplex.websocket import DuplexWebSocketActor
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex import (
-    MiniCPMO45NativeDuplexServingAdapter,
-    MiniCPMO45PcmAppendBuffer,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.capabilities import (
-    minicpmo45_native_capabilities,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.data_plane import (
-    MiniCPMO45DataPlaneContext,
-    MiniCPMO45DataPlaneSession,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.runtime import (
-    MiniCPMO45DuplexRuntimeExtension,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.session import (
-    MiniCPMO45ServingSessionState,
-)
-from vllm_omni.model_executor.models.personaplex.duplex.serving_adapter import (
-    PersonaPlexServingRuntimeAdapter,
-)
-from vllm_omni.outputs import OmniRequestOutput
-from vllm_omni.outputs.duplex import attach_duplex_output_decision
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-INVALID_VALIDATED_SAMPLE_RATES = (
-    pytest.param(16_000.5, id="fractional"),
-    pytest.param(float("inf"), id="infinite"),
-    pytest.param(float("nan"), id="nan"),
-)
-
-
-def test_native_input_append_supports_explicit_session_opt_out():
-    session = DuplexSession(
-        "sid-explicit-tts",
-        DuplexSessionConfig(model="test-model"),
-        capabilities=minicpmo45_native_capabilities(),
-    )
-
-    assert OmniDuplexSessionHandler._uses_native_input_append(session) is True
-
-    session.config.extra_body["native_duplex"] = False
-    assert OmniDuplexSessionHandler._uses_native_input_append(session) is False
-
-
-class _ModelConfig:
-    model = "test-model"
-
-
-class FakeEngineClient:
-    output_modalities = ["text", "audio"]
-
-    def __init__(
-        self,
-        *,
-        fail_open: bool = False,
-        fail_signal: bool = False,
-        fail_touch: bool = False,
-        fail_signal_events: set[str] | None = None,
-        fail_close: bool = False,
-        fail_abort: bool = False,
-        control_result: dict[str, object] | None = None,
-        open_result: dict[str, object] | None = None,
-        append_result: dict[str, object] | None = None,
-        append_results: list[dict[str, object]] | None = None,
-        collect_outputs: list[list[object]] | None = None,
-        collect_delay_s: float = 0.0,
-        signal_result: dict[str, object] | None = None,
-        close_result: dict[str, object] | None = None,
-    ) -> None:
-        self.fail_open = fail_open
-        self.fail_signal = fail_signal
-        self.fail_touch = fail_touch
-        self.fail_signal_events = set(fail_signal_events or ())
-        self.fail_close = fail_close
-        self.fail_abort = fail_abort
-        self.control_result = control_result
-        self.open_result = open_result
-        self.append_result = append_result
-        self.append_results = list(append_results or [])
-        self.collect_outputs = list(collect_outputs or [])
-        self.collect_delay_s = collect_delay_s
-        self.signal_result = signal_result
-        self.close_result = close_result
-        self.opened: list[str] = []
-        self.opened_fences: list[DuplexFence | None] = []
-        self.appended: list[tuple[str, str, Any, bool]] = []
-        self.append_operation_ids: list[str | None] = []
-        self.appended_fences: list[DuplexFence | None] = []
-        self.opened_configs: list[dict[str, Any]] = []
-        self.opened_runtime_configs: list[dict[str, Any]] = []
-        self.signals: list[tuple[str, str]] = []
-        self.signal_fences: list[DuplexFence | None] = []
-        self.signal_next_fences: list[DuplexFence | None] = []
-        self.signal_session_configs: list[dict[str, Any] | None] = []
-        self.signal_runtime_configs: list[dict[str, Any] | None] = []
-        self.closed: list[tuple[str, str]] = []
-        self.touched: list[tuple[str, DuplexLeaseActivity]] = []
-        self.touch_fences: list[DuplexFence] = []
-        self.resumed: list[tuple[str, int]] = []
-        self.resume_fences: list[DuplexFence] = []
-        self.aborted: list[str] = []
-        self.abort_batches: list[list[str]] = []
-        self.internal_abort_batches: list[list[str]] = []
-        self.collected: list[tuple[str, int | None]] = []
-        self.duplex_lifecycle_events: asyncio.Queue[DuplexSessionLifecycleMessage] = asyncio.Queue()
-
-    async def open_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        session_mode: str = "duplex",
-        capabilities: dict[str, object] | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-        timeout: float | None = None,
-        fence: DuplexFence | None = None,
-    ) -> Any:
-        del timeout
-        if self.fail_open:
-            raise RuntimeError("open failed")
-        self.opened.append(session_id)
-        self.opened_fences.append(fence)
-        self.opened_configs.append(dict(session_config or {}))
-        self.opened_runtime_configs.append(dict(runtime_config or {}))
-        return self.open_result if self.open_result is not None else self.control_result
-
-    async def append_duplex_input_async(
-        self,
-        session_id: str,
-        *,
-        mode: str,
-        payload: object,
-        operation_id: str | None = None,
-        final: bool = False,
-        timeout: float | None = None,
-        collect_outputs: bool = True,
-        fence: DuplexFence | None = None,
-    ) -> Any:
-        del timeout, collect_outputs
-        self.appended.append((session_id, mode, payload, final))
-        self.append_operation_ids.append(operation_id)
-        self.appended_fences.append(fence)
-        if self.append_results:
-            return self.append_results.pop(0)
-        return self.append_result if self.append_result is not None else self.control_result
-
-    async def collect_duplex_data_plane_outputs_async(
-        self,
-        request_id: str,
-        *,
-        response_stage_id: int | None = None,
-        timeout: float | None = None,
-    ) -> list[object]:
-        del timeout
-        self.collected.append((request_id, response_stage_id))
-        if self.collect_delay_s > 0:
-            await asyncio.sleep(self.collect_delay_s)
-        if not self.collect_outputs:
-            return []
-        return self.collect_outputs.pop(0)
-
-    async def signal_duplex_turn_async(
-        self,
-        session_id: str,
-        *,
-        event: str,
-        timeout: float | None = None,
-        fence: DuplexFence | None = None,
-        next_fence: DuplexFence | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-    ) -> Any:
-        del timeout
-        if self.fail_signal or event in self.fail_signal_events:
-            raise RuntimeError("signal failed")
-        self.signals.append((session_id, event))
-        self.signal_fences.append(fence)
-        self.signal_next_fences.append(next_fence)
-        self.signal_session_configs.append(session_config)
-        self.signal_runtime_configs.append(runtime_config)
-        return self.signal_result if self.signal_result is not None else self.control_result
-
-    async def close_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        reason: str = "client_close",
-        timeout: float | None = None,
-        fence: DuplexFence | None = None,
-    ) -> Any:
-        del timeout
-        if self.fail_close:
-            raise RuntimeError("close failed")
-        self.closed.append((session_id, reason))
-        return self.close_result if self.close_result is not None else self.control_result
-
-    async def touch_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        activity: DuplexLeaseActivity,
-        timeout: float | None = None,
-    ) -> dict[str, object]:
-        del timeout
-        if self.fail_touch:
-            raise RuntimeError("touch failed")
-        self.touched.append((session_id, activity))
-        self.touch_fences.append(fence)
-        return {
-            "operation": "touch",
-            "session_id": session_id,
-            "ok": True,
-            "stage_results": [
-                {
-                    "stage_id": -1,
-                    "replica_id": -1,
-                    "result": {"supported": True, "lease_generation": 0},
-                }
-            ],
-        }
-
-    async def resume_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        expected_lease_generation: int,
-        timeout: float | None = None,
-    ) -> dict[str, object]:
-        del timeout
-        self.resumed.append((session_id, expected_lease_generation))
-        self.resume_fences.append(fence)
-        return {
-            "operation": "resume",
-            "session_id": session_id,
-            "ok": True,
-            "stage_results": [
-                {
-                    "stage_id": -1,
-                    "replica_id": -1,
-                    "result": {
-                        "supported": True,
-                        "lease_generation": expected_lease_generation + 1,
-                    },
-                }
-            ],
-        }
-
-    async def abort(self, request_ids: list[str]) -> None:
-        if self.fail_abort:
-            raise RuntimeError("abort failed")
-        assert isinstance(request_ids, list)
-        self.abort_batches.append(list(request_ids))
-        self.aborted.extend(request_ids)
-
-    async def _abort_internal_requests(self, request_ids: list[str]) -> None:
-        if self.fail_abort:
-            raise RuntimeError("abort failed")
-        assert isinstance(request_ids, list)
-        self.internal_abort_batches.append(list(request_ids))
-        self.aborted.extend(request_ids)
-
-
-class FakeChatService:
-    duplex_serving_adapter_path = (
-        "vllm_omni.model_executor.models.minicpmo_4_5.duplex.serving_adapter.MiniCPMO45ServingRuntimeAdapter"
-    )
-
-    def __init__(self, engine_client: FakeEngineClient) -> None:
-        self.engine_client = engine_client
-        self.model_config = _ModelConfig()
-        self.seen_request_ids: list[str] = []
-
-    async def create_chat_completion(self, request, raw_request=None):
-        self.seen_request_ids.append(request.request_id)
-
-        async def _gen():
-            await asyncio.sleep(999)
-            yield "data: [DONE]\n\n"
-
-        return _gen()
-
-    def create_audio(self, audio_obj):
-        return SimpleNamespace(audio_data=f"wav-{int(audio_obj.audio_tensor.shape[0])}")
-
-
-class TurnBasedFakeChatService(FakeChatService):
-    """Chat-fallback service without a model-native duplex adapter."""
-
-    duplex_serving_adapter_path = None
-
-    def __init__(self, engine_client: FakeEngineClient) -> None:
-        super().__init__(engine_client)
-        self.requests: list[Any] = []
-
-    async def create_chat_completion(self, request, raw_request=None):
-        del raw_request
-        self.requests.append(request)
-        self.seen_request_ids.append(request.request_id)
-
-        async def _gen():
-            yield "data: [DONE]\n\n"
-
-        return _gen()
-
-
-class GateChatService(FakeChatService):
-    def __init__(self, engine_client: FakeEngineClient) -> None:
-        super().__init__(engine_client)
-        self.first_response_gate = asyncio.Event()
-        self.response_count = 0
-
-    async def create_chat_completion(self, request, raw_request=None):
-        del raw_request
-        self.seen_request_ids.append(request.request_id)
-        self.response_count += 1
-        response_number = self.response_count
-
-        async def _gen():
-            if response_number == 1:
-                await self.first_response_gate.wait()
-            yield "data: [DONE]\n\n"
-
-        return _gen()
-
-
-def _test_data_plane() -> MiniCPMO45DataPlaneSession:
-    def encode_audio(
-        audio: object,
-        sample_rate_hz: int,
-        response_format: str,
-        speed: float | None,
-    ) -> str | None:
-        del sample_rate_hz, response_format, speed
-        if audio is None:
-            return None
-        if hasattr(audio, "numel"):
-            return f"wav-{int(audio.numel())}"
-        return f"wav-{int(np.asarray(audio).size)}"
-
-    return MiniCPMO45DataPlaneSession(encode_audio)
-
-
-def _data_plane_context(session: DuplexSession | None = None) -> MiniCPMO45DataPlaneContext:
-    if session is None:
-        return MiniCPMO45DataPlaneContext()
-    return MiniCPMO45DataPlaneContext(
-        epoch=session.epoch,
-        turn_id=session.turn_id,
-        active_response_turn_id=session.active_response_turn_id,
-        active_response_id=session.active_response_id,
-        auto_responds=bool(session.config.extra_body.get("auto_response", False)),
-        response_format=session.config.response_format,
-        speed=session.config.speed,
-        modalities=tuple(session.config.modalities),
-    )
-
-
-def _project_data_plane(
-    data_plane: MiniCPMO45DataPlaneSession,
-    result: object,
-    *,
-    session: DuplexSession | None = None,
-) -> list[dict[str, Any]]:
-    return list(data_plane.project(result, context=_data_plane_context(session)))
-
-
-class TimedWebSocket:
-    def __init__(self, *, on_send=None, receive_timeout_s: float = 1.0):
-        self._q: asyncio.Queue[str | BaseException] = asyncio.Queue()
-        self.sent: list[dict[str, Any]] = []
-        self.accepted = False
-        self._on_send = on_send
-        self._receive_timeout_s = receive_timeout_s
-        self.query_params: dict[str, str] = {}
-
-    async def accept(self):
-        self.accepted = True
-
-    async def receive_text(self) -> str:
-        try:
-            item = await asyncio.wait_for(self._q.get(), timeout=self._receive_timeout_s)
-        except asyncio.TimeoutError as exc:
-            raise WebSocketDisconnect(code=1000) from exc
-        if isinstance(item, BaseException):
-            raise item
-        return item
-
-    async def send_json(self, data: dict[str, Any]):
-        self.sent.append(data)
-        if self._on_send is not None:
-            self._on_send(self, data)
-
-    def put(self, payload: dict[str, Any]) -> None:
-        self._q.put_nowait(json.dumps(payload))
-
-    async def close(self, code: int = 1000, reason: str | None = None) -> None:
-        del reason
-        self._q.put_nowait(WebSocketDisconnect(code=code))
-
-    def sent_types(self) -> list[str]:
-        return [m.get("type", "") for m in self.sent]
-
-
-class FakeServerVADBackend:
-    frame_samples = 160
-
-    def __init__(self, probabilities: list[float]) -> None:
-        self.probabilities = probabilities
-        self.calls = 0
-
-    def new_state(self) -> int:
-        return 0
-
-    def infer(self, frame: np.ndarray, state: object) -> tuple[float, object]:
-        del frame
-        self.calls += 1
-        index = int(state)
-        probability = self.probabilities[index] if index < len(self.probabilities) else 0.0
-        return probability, index + 1
-
-
-class FakeServerVADProvider:
-    def __init__(self, backend: FakeServerVADBackend) -> None:
-        self.backend = backend
-
-    def get(self) -> FakeServerVADBackend:
-        return self.backend
-
-
-class FailingServerVADProvider:
-    def __init__(self) -> None:
-        self.calls = 0
-
-    def get(self) -> FakeServerVADBackend:
-        self.calls += 1
-        raise RuntimeError("server VAD backend unavailable")
-
-
-class FailOnceServerVADBackend(FakeServerVADBackend):
-    def __init__(self, probabilities: list[float]) -> None:
-        super().__init__(probabilities)
-        self._failed = False
-
-    def infer(self, frame: np.ndarray, state: object) -> tuple[float, object]:
-        if not self._failed and int(state) == 2:
-            self._failed = True
-            raise RuntimeError("server VAD inference failed")
-        return super().infer(frame, state)
-
-
-def _server_vad_turn_detection(*, create_response: bool = True) -> dict[str, Any]:
-    return {
-        "type": "server_vad",
-        "prefix_padding_ms": 10,
-        "silence_duration_ms": 20,
-        "create_response": create_response,
-        "interrupt_response": False,
-    }
-
-
-def _server_vad_session_update(
-    turn_detection: dict[str, Any] | None,
-    *,
-    event_id: str | None = None,
-    sample_rate_hz: int = 16_000,
-) -> dict[str, Any]:
-    event: dict[str, Any] = {
-        "type": "session.update",
-        "session": {
-            "model": "test-model",
-            "audio": {
-                "input": {
-                    "format": {"type": "audio/pcm", "rate": sample_rate_hz},
-                    "turn_detection": turn_detection,
-                }
-            },
-        },
-    }
-    if event_id is not None:
-        event["event_id"] = event_id
-    return event
-
-
-def _server_vad_audio_append(
-    frame_count: int = 5,
-    *,
-    event_id: str | None = None,
-    is_speech: bool | None = None,
-    sample_rate_hz: int = 16_000,
-) -> dict[str, Any]:
-    sample_count = frame_count * 160 * sample_rate_hz // 16_000
-    event: dict[str, Any] = {
-        "type": "input_audio_buffer.append",
-        "audio": base64.b64encode(np.zeros(sample_count, dtype="<i2").tobytes()).decode(),
-    }
-    if event_id is not None:
-        event["event_id"] = event_id
-    if is_speech is not None:
-        event["is_speech"] = is_speech
-    return event
-
-
-def test_native_realtime_protocol_emits_speak_once_per_response():
-    protocol = NativeRealtimeSessionProtocol({})
-    response_id = "resp-speak-once"
-
-    projected = protocol.encode_outbound_event(
-        {
-            "type": "response.created",
-            "response_id": response_id,
-            "modalities": ["audio", "text"],
-        }
-    )
-    projected.extend(
-        protocol.encode_outbound_event(
-            {
-                "type": "response.speak",
-                "response_id": response_id,
-                "text": "hello",
-                "model_speak": True,
-            }
-        )
-    )
-    projected.extend(
-        protocol.encode_outbound_event(
-            {
-                "type": "response.output_audio.delta",
-                "response_id": response_id,
-                "audio": base64.b64encode(b"\x00\x00").decode("ascii"),
-                "format": "pcm16",
-                "sample_rate_hz": 24000,
-                "model_speak": True,
-            }
-        )
-    )
-
-    assert [event["type"] for event in projected].count("response.speak") == 1
-    speak = next(event for event in projected if event["type"] == "response.speak")
-    assert "text" not in speak
-    assert speak["metadata"] == {"model_speak": True}
-
-
-def test_native_realtime_protocol_speak_does_not_expose_internal_event():
-    protocol = NativeRealtimeSessionProtocol({})
-
-    projected = protocol.encode_outbound_event(
-        {
-            "type": "response.speak",
-            "response_id": "resp-curated-speak",
-            "session_id": "sid-curated-speak",
-            "epoch": 3,
-            "text": "transcript belongs on the delta channel",
-            "model_speak": True,
-            "data_plane_request_id": "internal-request-id",
-            "uses_model_runner_scheduler": True,
-        }
-    )
-
-    assert len(projected) == 1
-    projected[0].pop("event_id")
-    assert projected == [
-        {
-            "type": "response.speak",
-            "response_id": "resp-curated-speak",
-            "item_id": "item_resp-curated-speak",
-            "output_index": 0,
-            "content_index": 0,
-            "metadata": {
-                "session_id": "sid-curated-speak",
-                "epoch": 3,
-                "model_speak": True,
-            },
-        }
-    ]
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_drains_internal_conversation_item_control_event():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    ws.put({"type": "session.update", "model": "test-model", "session_id": "rt-delete"})
-    session_create = json.loads(await protocol.receive_internal_event_text(ws))
-    assert session_create["type"] == "session.create"
-
-    ws.put(
-        {
-            "type": "conversation.item.create",
-            "item": {
-                "id": "item-a",
-                "type": "message",
-                "role": "user",
-                "content": [{"type": "input_text", "text": "hello"}],
-            },
-        }
-    )
-    assert json.loads(await protocol.receive_internal_event_text(ws)) == {
-        "type": "turn.signal",
-        "event": "conversation.item.create",
-        "payload": {
-            "item": {
-                "id": "item-a",
-                "object": "realtime.item",
-                "type": "message",
-                "status": "completed",
-                "role": "user",
-                "content": [{"type": "input_text", "text": "hello"}],
-            }
-        },
-    }
-
-    ws.put({"type": "conversation.item.delete", "item_id": "item-a"})
-    translated = json.loads(await protocol.receive_internal_event_text(ws))
-
-    assert translated == {
-        "type": "turn.signal",
-        "event": "conversation.item.delete",
-        "payload": {"item_id": "item-a"},
-    }
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_conversation_item_create_commits_user_text():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    ws.put({"type": "session.update", "model": "test-model", "session_id": "rt-item-create"})
-    session_create = json.loads(await protocol.receive_internal_event_text(ws))
-    assert session_create["type"] == "session.create"
-
-    ws.put(
-        {
-            "type": "conversation.item.create",
-            "item": {
-                "id": "item-user-text",
-                "type": "message",
-                "role": "user",
-                "content": [{"type": "input_text", "text": "hello"}],
-            },
-        }
-    )
-
-    translated = json.loads(await protocol.receive_internal_event_text(ws))
-
-    assert translated == {
-        "type": "turn.signal",
-        "event": "conversation.item.create",
-        "payload": {
-            "item": {
-                "id": "item-user-text",
-                "object": "realtime.item",
-                "type": "message",
-                "status": "completed",
-                "role": "user",
-                "content": [{"type": "input_text", "text": "hello"}],
-            }
-        },
-    }
-
-
-@pytest.mark.asyncio
-async def test_function_output_is_recorded_only_after_runtime_delivery():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-    protocol.encode_outbound_event(
-        {
-            "type": "conversation.item.created",
-            "item": {
-                "id": "item-call",
-                "type": "function_call",
-                "call_id": "call-1",
-                "name": "weather",
-                "arguments": "{}",
-                "status": "completed",
-            },
-        }
-    )
-    event = {
-        "type": "conversation.item.create",
-        "item": {
-            "id": "item-output",
-            "type": "function_call_output",
-            "call_id": "call-1",
-            "output": '{"temperature":20}',
-        },
-    }
-
-    first = await protocol._to_duplex_event(event)
-    retry = await protocol._to_duplex_event(event)
-
-    assert first is not None
-    assert retry is not None
-    assert "item-output" not in protocol._conversation_items
-
-    delivered_item = first["payload"]["item"]
-    protocol.encode_outbound_event(
-        {
-            "type": "conversation.item.created",
-            "item": delivered_item,
-        }
-    )
-
-    assert protocol._conversation_items["item-output"] == delivered_item
-    assert await protocol._to_duplex_event(event) is None
-    assert ws.sent[-1]["error"]["code"] == "invalid_function_call_output"
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_audio_commit_requires_non_empty_buffer():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    ws.put({"type": "session.update", "model": "test-model", "session_id": "rt-audio-commit"})
-    session_create = json.loads(await protocol.receive_internal_event_text(ws))
-    assert session_create["type"] == "session.create"
-
-    ws.put({"type": "input_audio_buffer.commit", "final": True})
-    with pytest.raises(WebSocketDisconnect):
-        await protocol.receive_internal_event_text(ws)
-
-    assert ws.sent[-1]["type"] == "error"
-    assert ws.sent[-1]["error"]["code"] == "input_audio_buffer_empty"
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_audio_commit_does_not_auto_create_response():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    ws.put({"type": "session.update", "model": "test-model", "session_id": "rt-audio-commit-full"})
-    session_create = json.loads(await protocol.receive_internal_event_text(ws))
-    assert session_create["type"] == "session.create"
-
-    pcm = struct.pack("<2h", 1024, -1024)
-    ws.put({"type": "input_audio_buffer.append", "audio": base64.b64encode(pcm).decode("ascii"), "format": "pcm16"})
-    append_event = json.loads(await protocol.receive_internal_event_text(ws))
-    assert append_event["type"] == "input_audio_buffer.append"
-
-    ws.put({"type": "input_audio_buffer.commit", "final": True})
-    commit_event = json.loads(await protocol.receive_internal_event_text(ws))
-
-    assert commit_event["type"] == "input_audio_buffer.commit"
-    assert commit_event["response_create"] is False
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("complete_item", [False, True], ids=["manual-commit", "complete-audio-item"])
-async def test_realtime_commit_ack_preserves_next_turn(complete_item: bool):
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol({})
-    protocol.bind_sender(ws.send_json)
-    protocol.encode_outbound_event({"type": "session.created", "session": {}})
-    audio = base64.b64encode(struct.pack("<2h", 1024, -1024)).decode()
-    append = {"type": "input_audio_buffer.append", "audio": audio, "format": "pcm16"}
-    if complete_item:
-        await protocol._to_duplex_event(
-            {
-                "type": "conversation.item.create",
-                "item": {
-                    "type": "message",
-                    "role": "user",
-                    "content": [{"type": "input_audio", "audio": audio}],
-                },
-            }
-        )
-        first_commit = json.loads(await protocol.receive_internal_event_text(ws))
-    else:
-        await protocol._to_duplex_event(append)
-        first_commit = await protocol._to_duplex_event({"type": "input_audio_buffer.commit"})
-    assert first_commit is not None
-
-    await protocol._to_duplex_event({**append, "transcript": "second turn"})
-    second_item_id = next(
-        (event["item_id"] for event in reversed(ws.sent) if event["type"] == "input_audio_buffer.speech_started"),
-        None,
-    )
-    assert second_item_id is not None
-    protocol.encode_outbound_event({"type": "input.committed", "item_id": first_commit["item_id"]})
-    second_commit = await protocol._to_duplex_event({"type": "input_audio_buffer.commit"})
-
-    assert second_commit is not None
-    assert second_commit["item_id"] == second_item_id != first_commit["item_id"]
-    assert second_commit["transcript"] == "second turn"
-    assert "error" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("pending_next_turn", [False, True])
-async def test_realtime_silence_commit_does_not_reuse_speech_item(pending_next_turn: bool):
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol({})
-    protocol.bind_sender(ws.send_json)
-    protocol.encode_outbound_event({"type": "session.created", "session": {}})
-    append = {
-        "type": "input_audio_buffer.append",
-        "audio": base64.b64encode(struct.pack("<2h", 1024, -1024)).decode(),
-        "format": "pcm16",
-    }
-    await protocol._to_duplex_event(append)
-    first_commit = await protocol._to_duplex_event({"type": "input_audio_buffer.commit"})
-    assert first_commit is not None
-    events = protocol.encode_outbound_event(
-        {"type": "input.committed", "item_id": first_commit["item_id"], "message": {"transcript": "first turn"}}
-    )
-
-    await protocol._to_duplex_event({**append, "audio": base64.b64encode(bytes(4)).decode()})
-    silence_commit = await protocol._to_duplex_event({"type": "input_audio_buffer.commit"})
-    assert silence_commit is not None and silence_commit["is_speech"] is False
-    if pending_next_turn:
-        await protocol._to_duplex_event(append)
-        next_commit = await protocol._to_duplex_event({"type": "input_audio_buffer.commit"})
-        assert next_commit is not None
-    events.extend(
-        protocol.encode_outbound_event(
-            {"type": "input.committed", "empty": True, "is_speech": False, "no_response": True}
-        )
-    )
-    if pending_next_turn:
-        events.extend(protocol.encode_outbound_event({"type": "input.committed", "item_id": next_commit["item_id"]}))
-
-    committed = [event for event in events if event["type"] == "input_audio_buffer.committed"]
-    assert len(committed) == len({event["item_id"] for event in committed}) == 2 + int(pending_next_turn)
-    assert committed[0]["item_id"] == first_commit["item_id"]
-    if pending_next_turn:
-        assert committed[2]["item_id"] == next_commit["item_id"]
-    transcripts = [
-        event for event in events if event["type"] == "conversation.item.input_audio_transcription.completed"
-    ]
-    assert [(event["item_id"], event["transcript"]) for event in transcripts] == [
-        (first_commit["item_id"], "first turn")
-    ]
-    assert "error" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize(
-    "turn_detection,sample_rate_hz",
-    [(None, 192_001), (_server_vad_turn_detection(), [16_000])],
-    ids=["manual-out-of-range", "server-vad-invalid-type"],
-)
-async def test_native_realtime_protocol_rejects_invalid_sample_rate_without_closing(turn_detection, sample_rate_hz):
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    ws.put(_server_vad_session_update(turn_detection))
-    session_create = json.loads(await protocol.receive_internal_event_text(ws))
-    assert session_create["type"] == "session.create"
-    protocol.commit_realtime_turn_detection_update()
-
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(1),
-            "format": "pcm16",
-            "sample_rate_hz": sample_rate_hz,
-            "event_id": "invalid-rate",
-        }
-    )
-    ws.put({"type": "input_audio_buffer.clear"})
-    translated = json.loads(await protocol.receive_internal_event_text(ws))
-
-    assert translated == {"type": "input_audio_buffer.clear", "reason": "input_audio_buffer.clear"}
-    error = next(event for event in ws.sent if event.get("type") == "error")
-    assert error["error"]["code"] == "bad_event"
-    assert error["error"]["param"] == "sample_rate_hz"
-    assert error["error"]["event_id"] == "invalid-rate"
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_audio_clear_is_not_barge_in_cancel():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    ws.put({"type": "session.update", "model": "test-model", "session_id": "rt-audio-clear"})
-    session_create = json.loads(await protocol.receive_internal_event_text(ws))
-    assert session_create["type"] == "session.create"
-
-    ws.put({"type": "input_audio_buffer.clear"})
-    clear_event = json.loads(await protocol.receive_internal_event_text(ws))
-
-    assert clear_event == {"type": "input_audio_buffer.clear", "reason": "input_audio_buffer.clear"}
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_preserves_input_turn_policy_hints():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    translated = await protocol._to_duplex_event(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": "AAAA",
-            "format": "pcm_f32le",
-            "duration_ms": 240,
-            "vad": {"is_speech": True, "speech_probability": 0.9},
-            "overlap_action": "listen",
-        }
-    )
-
-    assert translated is not None
-    assert translated["duration_ms"] == 240
-    assert translated["vad"] == {"is_speech": True, "speech_probability": 0.9}
-    assert translated["overlap_action"] == "listen"
-
-
-@pytest.mark.asyncio
-async def test_realtime_protocol_accepts_legacy_server_vad_alias():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    translated = await protocol._to_duplex_event(
-        {
-            "type": "session.update",
-            "model": "test-model",
-            "session_id": "rt-turn-detection",
-            "turn_detection": {
-                "type": "server_vad",
-                "interrupt_response": False,
-                "threshold": 0.4,
-            },
-        }
-    )
-
-    assert translated is not None
-    config = DuplexSessionConfig.from_event(translated)
-    assert config.server_vad is not None
-    assert config.server_vad.threshold == 0.4
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_accepts_disabled_turn_detection():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    ws.put(
-        {
-            "type": "session.update",
-            "model": "test-model",
-            "session_id": "rt-no-turn-detection",
-            "turn_detection": None,
-        }
-    )
-    translated = json.loads(await protocol.receive_internal_event_text(ws))
-
-    assert translated["type"] == "session.create"
-    assert translated["session"]["extra_body"]["realtime_session_payload"]["turn_detection"] is None
-
-
-def test_native_realtime_protocol_preserves_omitted_turn_detection():
-    protocol = NativeRealtimeSessionProtocol({})
-
-    updated = protocol._from_duplex_event(
-        {
-            "type": "session.updated",
-            "session": {},
-        }
-    )[0]
-
-    assert "turn_detection" not in updated["session"]
-    assert "turn_detection" not in updated["session"]["audio"]["input"]
-
-
-@pytest.mark.asyncio
-async def test_duplex_session_create_reports_invalid_server_vad_as_client_error():
-    session_id = "sid-invalid-server-vad-config"
-    event = _session_create(session_id)
-    event["session"]["extra_body"] = {
-        "realtime_session_payload": {"turn_detection": {"type": "server_vad", "threshold": 1.5}},
-    }
-
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(event)
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "invalid_request_error"
-    assert ws.sent[0]["error"] == "server_vad.threshold must be a number between 0 and 1"
-    assert handler._registry.get(session_id) is None
-    assert engine.opened == []
-
-
-def test_native_duplex_handler_has_no_fixed_session_admission_cap():
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    client_config = DuplexSessionConfig(
-        extra_body={"max_duplex_sessions": 99, "duplex_max_sessions": 99},
-    )
-
-    assert not hasattr(handler, "_max_native_duplex_sessions")
-    assert not hasattr(handler, "_max_duplex_sessions")
-    assert client_config.extra_body["max_duplex_sessions"] == 99
-
-
-def test_native_response_options_ignore_private_runtime_config():
-    session = DuplexSession(
-        session_id="sid-response-private-config",
-        config=DuplexSessionConfig(),
-        capabilities=minicpmo45_native_capabilities(),
-    )
-
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    handler._apply_response_create_options(
-        session,
-        {
-            "extra_body": {
-                "duplex_stage_max_tokens": {"0": 999},
-                "client_trace_id": "trace-1",
-            }
-        },
-    )
-    session.begin_response()
-
-    assert "duplex_stage_max_tokens" not in session.config.extra_body
-    assert "client_trace_id" not in session.config.extra_body
-    assert session.response_config.extra_body["client_trace_id"] == "trace-1"
-
-
-@pytest.mark.parametrize(
-    "payload",
-    [
-        {"instructions": "not wired"},
-        {"voice": "not-wired"},
-        {"temperature": 0.2},
-        {"max_output_tokens": 8},
-        {"tools": [{"type": "function", "name": "lookup"}]},
-    ],
-)
-def test_native_response_create_rejects_unwired_generation_options(payload):
-    session = DuplexSession(
-        session_id="sid-response-unwired-options",
-        config=DuplexSessionConfig(),
-        capabilities=minicpmo45_native_capabilities(),
-    )
-
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    error = handler._apply_response_create_options(session, payload)
-
-    assert error == "unsupported_native_response_options"
-    session.begin_response()
-    assert session.response_config == session.config
-
-
-def test_chat_fallback_excludes_realtime_response_metadata_from_model_request():
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-response-protocol-metadata",
-        config=DuplexSessionConfig(),
-    )
-    session.reserve_response_options(
-        ResponseCreateOptions(
-            extra_body={
-                "user": "trace-1",
-                "realtime_response_conversation": "none",
-                "realtime_response_metadata": {"source": "test"},
-                "realtime_response_prompt": {"id": "prompt-1"},
-                "realtime_response_tools": [
-                    {
-                        "type": "function",
-                        "function": {"name": "lookup", "parameters": {}},
-                    }
-                ],
-                "realtime_response_tool_choice": "auto",
-            }
-        )
-    )
-    session.begin_response()
-
-    request = handler._build_chat_request(session, "request-1")
-    created = handler._response_created_payload(session, session.active_response_id or "response-1", epoch=0)
-    dumped = request.model_dump()
-
-    assert dumped["user"] == "trace-1"
-    assert dumped["tools"][0]["function"]["name"] == "lookup"
-    assert dumped["tool_choice"] == "auto"
-    assert not any(key.startswith("realtime_response_") for key in dumped)
-    assert created["conversation"] == "none"
-    assert created["metadata"] == {"source": "test"}
-    assert created["prompt"] == {"id": "prompt-1"}
-    assert session.response_config.extra_body["realtime_response_conversation"] == "none"
-
-
-@pytest.mark.asyncio
-async def test_native_response_create_surfaces_unwired_generation_options_error():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-response-unwired-options-event"))
-    ws.put(
-        {
-            "type": "response.create",
-            "response": {"instructions": "not wired"},
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    error = next(message for message in ws.sent if message.get("type") == "error")
-    assert error["code"] == "unsupported_native_response_options"
-    assert "response_create_without_input" not in {message.get("code") for message in ws.sent}
-
-
-@pytest.mark.asyncio
-async def test_realtime_session_update_preserves_tools_and_metadata():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-rt-update-fields"))
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {
-                "tools": [{"type": "function", "name": "lookup"}],
-                "tool_choice": "auto",
-                "metadata": {"demo": "yes"},
-            },
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    updated = next(m for m in ws.sent if m.get("type") == "session.updated")
-    session = updated["session"]
-    assert session["tools"] == [{"type": "function", "name": "lookup"}]
-    assert session["tool_choice"] == "auto"
-    assert session["metadata"] == {"demo": "yes"}
-    assert "turn_detection" not in session
-    runtime_config = engine.signal_session_configs[-1]
-    assert runtime_config is not None
-    assert runtime_config["extra_body"]["realtime_tools"] == [{"type": "function", "name": "lookup"}]
-    assert runtime_config["extra_body"]["realtime_metadata"] == {"demo": "yes"}
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_non_speech_append_does_not_emit_speech_started():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    translated = await protocol._to_duplex_event(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": "AAAA",
-            "format": "pcm_f32le",
-            "vad": {"is_speech": False},
-        }
-    )
-
-    assert translated is not None
-    assert translated["vad"] == {"is_speech": False}
-    assert not any(event.get("type") == "input_audio_buffer.speech_started" for event in ws.sent)
-
-
-@pytest.mark.asyncio
-async def test_native_session_update_rebuilds_server_runtime_policy():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-runtime-update"))
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {"temperature": 0.2, "max_output_tokens": 7},
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert "session.updated" in ws.sent_types()
-    public_config = engine.signal_session_configs[-1]
-    runtime_config = engine.signal_runtime_configs[-1]
-    assert public_config is not None
-    assert runtime_config is not None
-    assert "duplex_stage_sampling_params" not in public_config["extra_body"]
-    assert runtime_config["duplex_stage_max_tokens"]["0"] == 7
-    assert runtime_config["duplex_stage_sampling_params"]["0"]["temperature"] == 0.2
-    assert runtime_config["duplex_stage_sampling_params"]["0"]["top_k"] == 20
-    assert runtime_config["duplex_stage_sampling_params"]["0"]["top_p"] == 0.8
-
-
-@pytest.mark.asyncio
-async def test_realtime_server_vad_locks_turn_detection_after_audio_append():
-    ws = TimedWebSocket()
-    ws.put(_server_vad_session_update({"type": "server_vad"}))
-    ws.put(_server_vad_audio_append(frame_count=1))
-    # Repeating the same omitted defaults must not look like a config change.
-    ws.put(_server_vad_session_update({"type": "server_vad"}))
-    ws.put(
-        {
-            "type": "session.update",
-            "event_id": "event-change-turn-detection",
-            "session": {"audio": {"input": {"turn_detection": None}}},
-        }
-    )
-    ws.put({"type": "session.close"})
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([0.0])),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    (error,) = [event["error"] for event in ws.sent if event.get("type") == "error"]
-    assert error["code"] == "unsupported_turn_detection"
-    assert error["event_id"] == "event-change-turn-detection"
-    assert "turn_detection cannot be changed after the first audio append" in error["message"]
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize(
-    "audio",
-    ["not-base64", base64.b64encode(b"\x00").decode()],
-    ids=["invalid-base64", "incomplete-pcm16-sample"],
-)
-@pytest.mark.parametrize(
-    "event_type,error_param",
-    [("input_audio_buffer.append", "audio"), ("conversation.item.create", "item.content.audio")],
-)
-async def test_realtime_invalid_server_vad_audio_is_correlated_and_unbuffered(
-    audio: str, event_type: str, error_param: str
-):
-    ws = TimedWebSocket()
-    ws.put(_server_vad_session_update(_server_vad_turn_detection(create_response=False)))
-    event = {"type": event_type, "event_id": "event-invalid-server-vad-audio"}
-    if event_type == "input_audio_buffer.append":
-        event["audio"] = audio
-    else:
-        event["item"] = {
-            "type": "message",
-            "role": "user",
-            "content": [{"type": "input_audio", "audio": audio}],
-        }
-    ws.put(event)
-    ws.put(_server_vad_session_update(None))
-    ws.put({"type": "input_audio_buffer.commit", "event_id": "event-commit-after-invalid-audio"})
-    ws.put({"type": "session.close"})
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([])),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    errors = [event["error"] for event in ws.sent if event.get("type") == "error"]
-    bad_audio = next(error for error in errors if error["code"] == "bad_audio")
-    assert bad_audio["event_id"] == "event-invalid-server-vad-audio"
-    assert bad_audio["param"] == error_param
-    empty_buffer = next(error for error in errors if error["code"] == "input_audio_buffer_empty")
-    assert empty_buffer["event_id"] == "event-commit-after-invalid-audio"
-
-
-def test_native_realtime_protocol_projects_input_commit_in_openai_order():
-    protocol = NativeRealtimeSessionProtocol(TimedWebSocket())  # type: ignore[arg-type]
-    client_event_id = "client-input-commit"
-
-    events = protocol.encode_outbound_event(
-        {
-            "type": "input.committed",
-            "item_id": "item-user-audio",
-            "message": {"role": "user"},
-            "event_id": client_event_id,
-        }
-    )
-
-    assert [event["type"] for event in events] == [
-        "input_audio_buffer.committed",
-        "conversation.item.added",
-        "conversation.item.done",
-    ]
-    committed, added, done = events
-    assert set(committed) == {
-        "event_id",
-        "item_id",
-        "previous_item_id",
-        "type",
-    }
-    assert set(added) == {"event_id", "item", "previous_item_id", "type"}
-    assert set(done) == {"event_id", "item", "previous_item_id", "type"}
-    assert committed["item_id"] == added["item"]["id"] == done["item"]["id"]
-    assert committed["previous_item_id"] == added["previous_item_id"] == done["previous_item_id"]
-    server_event_ids = [event["event_id"] for event in events]
-    assert len(set(server_event_ids)) == len(events)
-    assert client_event_id not in server_event_ids
-    assert all(isinstance(event_id, str) and event_id.startswith("event_") for event_id in server_event_ids)
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("native", [False, True])
-@pytest.mark.parametrize("interrupt_response", [False, True])
-async def test_realtime_server_vad_input_path_uses_runtime_capability(native: bool, interrupt_response: bool):
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    translated = await protocol._to_duplex_event(
-        {
-            "type": "session.update",
-            "session": {
-                "model": "test-model",
-                "audio": {
-                    "input": {
-                        "turn_detection": {
-                            "type": "server_vad",
-                            "interrupt_response": interrupt_response,
-                        }
-                    }
-                },
-            },
-        }
-    )
-    assert translated is not None
-    # Serving validates supported combinations separately. Input translation
-    # must follow the selected runtime, not infer it from interruption policy.
-    protocol.bind_native_input_append(native)
-    protocol.commit_realtime_turn_detection_update()
-
-    source = np.arange(240, dtype="<i2")
-    append = await protocol._to_duplex_event(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": base64.b64encode(source.tobytes()).decode(),
-        }
-    )
-
-    assert append is not None
-    if native:
-        assert append["format"] == "pcm_f32le"
-        assert append["sample_rate_hz"] == 16_000
-        assert len(base64.b64decode(append["audio"])) == 160 * 4
-    else:
-        assert append["format"] == "pcm16"
-        assert append["sample_rate_hz"] == 24_000
-        np.testing.assert_array_equal(np.frombuffer(base64.b64decode(append["audio"]), dtype="<i2"), source)
-
-
-@pytest.mark.parametrize(("initial_rate_hz", "updated_rate_hz"), [(16_000, 24_000), (24_000, 16_000)])
-@pytest.mark.asyncio
-async def test_turn_based_server_vad_rejects_input_rate_change_after_append(
-    initial_rate_hz: int,
-    updated_rate_hz: int,
-):
-    initial = _server_vad_session_update(_server_vad_turn_detection(create_response=False))
-    initial["session"]["audio"]["input"]["format"]["rate"] = initial_rate_hz
-    append = _server_vad_audio_append(frame_count=1)
-    append["sample_rate_hz"] = initial_rate_hz
-    append["audio"] = base64.b64encode(np.zeros(initial_rate_hz // 100, dtype="<i2").tobytes()).decode()
-    ws = TimedWebSocket()
-    ws.put(initial)
-    ws.put(append)
-    ws.put(
-        {
-            "type": "session.update",
-            "event_id": "event-rate-change",
-            "session": {
-                "audio": {
-                    "input": {
-                        "format": {"type": "audio/pcm", "rate": updated_rate_hz},
-                    }
-                }
-            },
-        }
-    )
-    ws.put({"type": "session.close"})
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([0.0])),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    error = next(
-        event["error"]
-        for event in ws.sent
-        if event.get("type") == "error" and event.get("error", {}).get("code") == "unsupported_audio_format"
-    )
-    assert error["event_id"] == "event-rate-change"
-
-
-@pytest.mark.parametrize("sample_rate_hz", INVALID_VALIDATED_SAMPLE_RATES)
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_rejects_invalid_nested_audio_sample_rate(sample_rate_hz: object):
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-
-    translated = await protocol._to_duplex_event(
-        {
-            "type": "session.update",
-            "event_id": "event-invalid-rate",
-            "session": {
-                "audio": {
-                    "input": {
-                        "format": {"type": "audio/pcm", "rate": sample_rate_hz},
-                    }
-                }
-            },
-        }
-    )
-
-    assert translated is None
-    error = ws.sent[-1]["error"]
-    assert error["code"] == "unsupported_audio_format"
-    assert error["event_id"] == "event-invalid-rate"
-    assert "sample_rate_hz" in error["message"]
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("at_creation", [True, False], ids=["create", "update"])
-@pytest.mark.parametrize(
-    "input_update",
-    [
-        {"format": "g711_ulaw"},
-        {"channels": 2},
-        {"format": {"type": "audio/pcm", "rate": 44_100}},
-    ],
-    ids=["g711", "stereo", "unsupported-rate"],
-)
-async def test_realtime_rejects_unsupported_turn_based_server_vad_audio(
-    input_update: dict[str, Any],
-    at_creation: bool,
-):
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") == "response.done":
-            ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    if not at_creation:
-        ws.put(_server_vad_session_update(_server_vad_turn_detection()))
-    update = _server_vad_session_update(_server_vad_turn_detection(), event_id="bad-vad-audio-format")
-    update["session"]["audio"]["input"].update(input_update)
-    ws.put(update)
-    if not at_creation:
-        ws.put(_server_vad_audio_append())
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([0.0, 0.9, 0.8, 0.0, 0.0])),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    (error,) = [event["error"] for event in ws.sent if event.get("type") == "error"]
-    assert error["code"] == "unsupported_turn_detection"
-    assert error["event_id"] == "bad-vad-audio-format"
-    assert "mono PCM16" in error["message"]
-    assert ("session.created" in ws.sent_types()) is not at_creation
-    assert ("response.done" in ws.sent_types()) is not at_creation
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("sample_rate_hz", [16_000, 24_000])
-@pytest.mark.parametrize("create_response", [False, True], ids=["commit-only", "minimal-config"])
-@pytest.mark.parametrize("at_creation", [True, False], ids=["create", "update"])
-async def test_realtime_server_vad_commits_without_client_commit(
-    sample_rate_hz: int, create_response: bool, at_creation: bool
-):
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        terminal_event = "response.done" if create_response else "input_audio_buffer.committed"
-        if data.get("type") == terminal_event:
-            ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    if not at_creation:
-        ws.put(_server_vad_session_update(None, sample_rate_hz=sample_rate_hz))
-    ws.put(
-        _server_vad_session_update(
-            {"type": "server_vad"} if create_response else _server_vad_turn_detection(create_response=False),
-            sample_rate_hz=sample_rate_hz,
-        )
-    )
-    # Cover the default 500 ms silence timeout, plus streaming FIR right context.
-    ws.put(_server_vad_audio_append(54, sample_rate_hz=sample_rate_hz))
-    engine = FakeEngineClient()
-    chat_service = TurnBasedFakeChatService(engine)
-    handler = OmniDuplexSessionHandler(
-        chat_service=chat_service,
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([0.0, 0.9, 0.8, 0.0, 0.0])),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    event_types = ws.sent_types()
-    assert "error" not in event_types
-    effective_session = [
-        event["session"] for event in ws.sent if event["type"] in {"session.created", "session.updated"}
-    ][-1]
-    assert effective_session["turn_detection"]["interrupt_response"] is False
-    assert effective_session["audio"]["input"]["turn_detection"] == effective_session["turn_detection"]
-    assert effective_session["overlap_policy"] == "listen_only"
-    assert event_types.index("input_audio_buffer.speech_started") < event_types.index(
-        "input_audio_buffer.speech_stopped"
-    )
-    assert event_types.index("input_audio_buffer.speech_stopped") < event_types.index("input_audio_buffer.committed")
-    assert event_types.index("input_audio_buffer.committed") < event_types.index("conversation.item.added")
-    assert event_types.index("conversation.item.added") < event_types.index("conversation.item.done")
-    assert "conversation.item.created" not in event_types
-    committed = next(event for event in ws.sent if event.get("type") == "input_audio_buffer.committed")
-    added = next(event for event in ws.sent if event.get("type") == "conversation.item.added")
-    done = next(event for event in ws.sent if event.get("type") == "conversation.item.done")
-    assert committed["item_id"] == added["item"]["id"] == done["item"]["id"]
-    assert event_types.count("response.created") == int(create_response)
-    assert len(chat_service.seen_request_ids) == int(create_response)
-    if create_response:
-        assert event_types.index("input_audio_buffer.committed") < event_types.index("response.created")
-        assert event_types.index("response.created") < event_types.index("response.done")
-    assert engine.opened == []
-    assert engine.signals == []
-    assert engine.closed == []
-
-
-@pytest.mark.asyncio
-async def test_realtime_server_vad_create_response_false_accepts_response_create():
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") == "input_audio_buffer.committed":
-            ws.put({"type": "response.create"})
-        if data.get("type") == "response.done":
-            ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    ws.put(_server_vad_session_update(_server_vad_turn_detection(create_response=False)))
-    ws.put(_server_vad_audio_append())
-    engine = FakeEngineClient()
-    chat_service = TurnBasedFakeChatService(engine)
-    handler = OmniDuplexSessionHandler(
-        chat_service=chat_service,
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([0.0, 0.9, 0.8, 0.0, 0.0])),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    event_types = ws.sent_types()
-    assert event_types.index("input_audio_buffer.committed") < event_types.index("response.created")
-    assert event_types.index("response.created") < event_types.index("response.done")
-    assert event_types.count("response.created") == 1
-    assert len(chat_service.seen_request_ids) == 1
-    assert engine.opened == engine.signals == engine.closed == []
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("sample_rate_hz", [16_000, 24_000])
-async def test_realtime_server_vad_complete_audio_item_bypasses_vad(sample_rate_hz: int):
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        item = data.get("item")
-        if (
-            data.get("type") == "conversation.item.done"
-            and isinstance(item, dict)
-            and item.get("id") == "item-complete-audio"
-        ):
-            ws.put({"type": "response.create"})
-        if data.get("type") == "response.done":
-            ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    ws.put(_server_vad_session_update(_server_vad_turn_detection(), sample_rate_hz=sample_rate_hz))
-    samples = np.arange(sample_rate_hz // 10, dtype=np.float32)
-    pcm16 = np.rint(0.5 * np.sin(2 * np.pi * 1_000 * samples / sample_rate_hz) * 32_767).astype("<i2")
-    public_audio = base64.b64encode(pcm16.tobytes()).decode()
-    ws.put(
-        {
-            "type": "conversation.item.create",
-            "event_id": "event-complete-audio",
-            "item": {
-                "id": "item-complete-audio",
-                "type": "message",
-                "role": "user",
-                "content": [{"type": "input_audio", "audio": public_audio}],
-            },
-        }
-    )
-    engine = FakeEngineClient()
-    chat_service = TurnBasedFakeChatService(engine)
-    vad_backend = FakeServerVADBackend([0.0])
-    handler = OmniDuplexSessionHandler(
-        chat_service=chat_service,
-        server_vad_backend_provider=FakeServerVADProvider(vad_backend),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    added = next(event for event in ws.sent if event.get("type") == "conversation.item.added")
-    done = next(event for event in ws.sent if event.get("type") == "conversation.item.done")
-    assert added["item"] == done["item"]
-    assert done["item"]["content"] == [{"type": "input_audio", "audio": public_audio}]
-    event_types = ws.sent_types()
-    assert event_types.index("conversation.item.added") < event_types.index("conversation.item.done")
-    assert event_types.index("conversation.item.done") < event_types.index("response.created")
-    assert not {
-        "input_audio_buffer.speech_started",
-        "input_audio_buffer.speech_stopped",
-        "input_audio_buffer.committed",
-    }.intersection(event_types)
-    assert vad_backend.calls == 0
-    assert len(chat_service.requests) == 1
-
-    request = chat_service.requests[0]
-    history_content = request.messages[-1]["content"]
-    audio_url = history_content[-1]["audio_url"]["url"]
-    assert audio_url.startswith("data:audio/wav;base64,")
-    wav_payload = base64.b64decode(audio_url.partition(",")[2])
-    with wave.open(io.BytesIO(wav_payload), "rb") as wav_file:
-        assert wav_file.getnchannels() == 1
-        assert wav_file.getsampwidth() == 2
-        assert wav_file.getframerate() == 16_000
-        assert wav_file.getnframes() == 1_600
-
-
-@pytest.mark.asyncio
-async def test_realtime_server_vad_update_initialization_failure_keeps_session_open():
-    ws = TimedWebSocket()
-    ws.put(_server_vad_session_update(None))
-    ws.put(_server_vad_session_update(_server_vad_turn_detection(), event_id="event-enable-server-vad"))
-    ws.put(
-        {
-            "type": "session.update",
-            "session": {"instructions": "session remains usable"},
-        }
-    )
-    ws.put({"type": "session.close"})
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        server_vad_backend_provider=FailingServerVADProvider(),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    initialization_error_index, initialization_error = next(
-        (index, event)
-        for index, event in enumerate(ws.sent)
-        if event.get("type") == "error" and event.get("error", {}).get("code") == "server_vad_initialization_failed"
-    )
-    recovered_update_index, recovered_update = next(
-        (index, event)
-        for index, event in enumerate(ws.sent)
-        if event.get("type") == "session.updated"
-        and event.get("session", {}).get("instructions") == "session remains usable"
-    )
-    closed_index = ws.sent_types().index("session.closed")
-    assert initialization_error_index < recovered_update_index < closed_index
-    assert initialization_error["error"]["event_id"] == "event-enable-server-vad"
-    assert recovered_update["session"]["audio"]["input"]["turn_detection"] is None
-
-
-@pytest.mark.asyncio
-async def test_realtime_session_update_barrier_enables_server_vad_before_following_commit():
-    ws = TimedWebSocket()
-    ws.put(_server_vad_session_update(None))
-    ws.put(_server_vad_session_update({"type": "server_vad"}))
-    ws.put(
-        _server_vad_session_update(
-            {"type": "server_vad", "interrupt_response": True}, event_id="unsupported-interruption"
-        )
-    )
-    ws.put({"type": "session.update", "session": {"overlap_policy": "listen_only"}})
-    ws.put(_server_vad_audio_append(frame_count=1))
-    ws.put({"type": "input_audio_buffer.commit", "event_id": "commit-after-enable"})
-    ws.put({"type": "session.close"})
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([0.0])),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    update_index = next(
-        index
-        for index, event in enumerate(ws.sent)
-        if event.get("type") == "session.updated"
-        and isinstance(
-            event.get("session", {}).get("audio", {}).get("input", {}).get("turn_detection"),
-            dict,
-        )
-        and event["session"]["audio"]["input"]["turn_detection"].get("type") == "server_vad"
-    )
-    commit_error_index, commit_error = next(
-        (index, event["error"])
-        for index, event in enumerate(ws.sent)
-        if event.get("type") == "error" and event.get("error", {}).get("code") == "server_vad_manual_commit_unsupported"
-    )
-    assert update_index < commit_error_index
-    errors = [event["error"] for event in ws.sent if event["type"] == "error"]
-    assert [error["code"] for error in errors] == [
-        "server_vad_requires_native_duplex",
-        "server_vad_manual_commit_unsupported",
-    ]
-    assert errors[0]["event_id"] == "unsupported-interruption"
-    assert "set interrupt_response=false" in errors[0]["message"]
-    assert commit_error["event_id"] == "commit-after-enable"
-    assert "input_audio_buffer.committed" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("reset_reason", ["clear", "input_backpressure", "server_vad_inference_failed"])
-async def test_realtime_server_vad_reset_preserves_timeline_and_accepts_next_turn(reset_reason: str):
-    backend_class = FailOnceServerVADBackend if reset_reason == "server_vad_inference_failed" else FakeServerVADBackend
-    backend = backend_class([0.9, 0.9, 0.8, 0.0, 0.0])
-
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") == "response.done":
-            ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    ws.put(_server_vad_session_update(_server_vad_turn_detection()))
-    first_append = _server_vad_audio_append(frame_count=2)
-    first_append["audio"] = base64.b64encode(np.full(320, 12_000, dtype="<i2").tobytes()).decode()
-    ws.put(first_append)
-    ws.put(
-        {"type": "input_audio_buffer.clear"}
-        if reset_reason == "clear"
-        else _server_vad_audio_append(
-            frame_count=6 if reset_reason == "input_backpressure" else 1,
-            event_id="event-server-vad-reset",
-        )
-    )
-    ws.put(_server_vad_audio_append())
-    chat_service = TurnBasedFakeChatService(FakeEngineClient())
-    handler = OmniDuplexSessionHandler(
-        chat_service=chat_service,
-        server_vad_backend_provider=FakeServerVADProvider(backend),
-        duplex_session_config=DuplexSessionRuntimeConfig(max_pending_input_bytes_per_session=5 * 160 * 4),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    event_types = ws.sent_types()
-    cleared_index = event_types.index("input_audio_buffer.cleared")
-    speech_started_indices = [
-        index for index, event_type in enumerate(event_types) if event_type == "input_audio_buffer.speech_started"
-    ]
-    speech_stopped_index = event_types.index("input_audio_buffer.speech_stopped")
-    committed_index = event_types.index("input_audio_buffer.committed")
-    first_started_index, second_started_index = speech_started_indices
-    assert first_started_index < cleared_index < second_started_index < speech_stopped_index < committed_index
-    errors = [(index, event["error"]) for index, event in enumerate(ws.sent) if event.get("type") == "error"]
-    if reset_reason == "clear":
-        assert not errors
-    else:
-        ((error_index, error),) = errors
-        assert first_started_index < error_index < cleared_index
-        assert error["code"] == reset_reason
-        assert error["event_id"] == "event-server-vad-reset"
-    assert not {
-        "input_audio_buffer.speech_stopped",
-        "input_audio_buffer.committed",
-    }.intersection(event_types[first_started_index + 1 : cleared_index])
-    assert ws.sent[second_started_index]["audio_start_ms"] == 20
-    assert ws.sent[speech_stopped_index]["audio_end_ms"] == 70
-    assert ws.sent[first_started_index]["item_id"] != ws.sent[second_started_index]["item_id"]
-    assert ws.sent[second_started_index]["item_id"] == ws.sent[committed_index]["item_id"]
-    assert len(chat_service.requests) == 1
-    audio_url = chat_service.requests[0].messages[-1]["content"][-1]["audio_url"]["url"]
-    with wave.open(io.BytesIO(base64.b64decode(audio_url.partition(",")[2])), "rb") as wav_file:
-        # Only the new 50 ms turn is committed; the cleared nonzero audio is gone.
-        assert wav_file.getnframes() == 800
-        assert not np.frombuffer(wav_file.readframes(800), dtype="<i2").any()
-
-
-@pytest.mark.asyncio
-async def test_realtime_failed_server_vad_append_does_not_lock_turn_detection():
-    ws = TimedWebSocket()
-    ws.put(_server_vad_session_update(_server_vad_turn_detection(create_response=False)))
-    ws.put(_server_vad_audio_append(frame_count=3, event_id="event-failed-append"))
-    ws.put(
-        {
-            "type": "session.update",
-            "session": {"audio": {"input": {"turn_detection": None}}},
-        }
-    )
-    ws.put({"type": "session.close"})
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        server_vad_backend_provider=FakeServerVADProvider(FailOnceServerVADBackend([0.9, 0.9])),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    error_index, error = next(
-        (index, event["error"])
-        for index, event in enumerate(ws.sent)
-        if event.get("type") == "error" and event.get("error", {}).get("code") == "server_vad_inference_failed"
-    )
-    event_types = ws.sent_types()
-    disabled_index = next(
-        index
-        for index, event in enumerate(ws.sent)
-        if event.get("type") == "session.updated"
-        and event.get("session", {}).get("audio", {}).get("input", {}).get("turn_detection", "missing") is None
-    )
-    assert error_index < event_types.index("input_audio_buffer.cleared") < disabled_index
-    assert error["event_id"] == "event-failed-append"
-
-
-@pytest.mark.asyncio
-async def test_realtime_server_vad_queues_one_turn_and_rejects_further_input():
-    chat_service = GateChatService(FakeEngineClient())
-    committed_count = 0
-    response_count = 0
-
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        nonlocal committed_count, response_count
-        if data.get("type") == "input_audio_buffer.committed":
-            committed_count += 1
-        if data.get("type") == "error" and data.get("error", {}).get("code") == "input_backpressure":
-            chat_service.first_response_gate.set()
-        if data.get("type") == "response.created":
-            response_count += 1
-            if response_count == 2:
-                ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    ws.put(_server_vad_session_update(_server_vad_turn_detection()))
-    for _ in range(3):
-        ws.put(_server_vad_audio_append())
-    handler = OmniDuplexSessionHandler(
-        chat_service=chat_service,
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([0.0, 0.9, 0.8, 0.0, 0.0] * 3)),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    assert committed_count == 2
-    assert response_count == 2
-    event_types = ws.sent_types()
-    committed_indices = [index for index, event in enumerate(event_types) if event == "input_audio_buffer.committed"]
-    response_created_indices = [index for index, event in enumerate(event_types) if event == "response.created"]
-    assert committed_indices[1] < event_types.index("response.done") < response_created_indices[1]
-    backpressure = [
-        event
-        for event in ws.sent
-        if event.get("type") == "error" and event.get("error", {}).get("code") == "input_backpressure"
-    ]
-    assert len(backpressure) == 1
-
-
-@pytest.mark.asyncio
-async def test_native_session_update_rejects_client_runtime_config():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-runtime-update-reject"))
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {
-                "extra_body": {"duplex_stage_max_tokens": {"0": 999}},
-            },
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    error = next(message for message in ws.sent if message.get("type") == "error")
-    assert error["code"] == "invalid_duplex_runtime_config"
-    assert ("sid-runtime-update-reject", "session.update") not in engine.signals
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_session_update_requires_ref_audio_before_enabling_audio():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-runtime-update-ref-required", modalities=["text"]))
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {"modalities": ["text", "audio"]},
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    error = next(message for message in ws.sent if message.get("type") == "error")
-    assert error["code"] == "ref_audio_required"
-    assert "session.updated" not in ws.sent_types()
-    assert ("sid-runtime-update-ref-required", "session.update") not in engine.signals
-
-
-def test_personaplex_candidate_update_does_not_leak_minicpmo_ref_audio_check():
-    handler = OmniDuplexSessionHandler(
-        chat_service=SimpleNamespace(engine_client=SimpleNamespace()),
-        served_model_name="test-model",
-        serving_runtime_adapter=PersonaPlexServingRuntimeAdapter(lambda *_: None),
-    )
-    session = DuplexSession(
-        session_id="sid-personaplex-voice-change",
-        config=DuplexSessionConfig(modalities=["audio"], voice="NATF2.pt"),
-        capabilities=PersonaPlexServingRuntimeAdapter.capabilities(max_sessions=1),
-    )
-    candidate_config = DuplexSessionConfig(modalities=["audio"], voice="OtherVoice.pt")
-
-    error = handler._runtime_session_candidate_update_error(session, candidate_config)
-
-    assert error is None
-
-
-@pytest.mark.parametrize(
-    ("native", "turn_detection", "expected_code"),
-    [
-        (False, {"type": "server_vad", "interrupt_response": False}, None),
-        (False, {"type": "server_vad"}, None),
-        (False, {"type": "server_vad", "interrupt_response": True}, "server_vad_requires_native_duplex"),
-        (True, {"type": "server_vad", "interrupt_response": False}, "unsupported_turn_detection"),
-        (True, {"type": "server_vad"}, None),
-    ],
-    ids=[
-        "turn-based-endpointing",
-        "turn-based-default-endpointing",
-        "turn-based-explicit-interruption",
-        "native-non-interrupting",
-        "native-default-interruption",
-    ],
-)
-def test_server_vad_runtime_capability_matrix(
-    native: bool,
-    turn_detection: dict[str, object],
-    expected_code: str | None,
-):
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-    )
-    capabilities = minicpmo45_native_capabilities() if native else DuplexCapabilities()
-    session = DuplexSession(
-        "sid-server-vad-capability",
-        DuplexSessionConfig(),
-        capabilities=capabilities,
-    )
-    candidate = DuplexSessionConfig.from_event({"session": {"turn_detection": turn_detection}})
-    handler._resolve_server_vad_defaults(session, candidate, {"turn_detection": turn_detection})
-
-    error = handler._runtime_session_candidate_update_error(session, candidate)
-
-    assert (error or {}).get("code") == expected_code
-    if expected_code is None:
-        assert candidate.server_vad is not None
-        assert candidate.server_vad.interrupt_response is native
-        assert candidate.overlap_policy == ("barge_in_on_speech" if native else "listen_only")
-    elif expected_code == "server_vad_requires_native_duplex":
-        assert "set interrupt_response=false" in error["error"]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_session_update_rejects_instructions_after_native_context_locked():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-instructions-locked", modalities=["text"]))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000, value=0.05),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-            "duration_ms": 1000,
-            "is_speech": True,
-        }
-    )
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {"instructions": "You are now a pirate."},
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    error = next(message for message in ws.sent if message.get("type") == "error")
-    assert error["code"] == "instructions_update_unsupported"
-    assert "session.updated" not in ws.sent_types()
-    assert ("sid-instructions-locked", "session.update") not in engine.signals
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_session_update_allows_unchanged_instructions_after_lock():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-instructions-unchanged", modalities=["text"]))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000, value=0.05),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-            "duration_ms": 1000,
-            "is_speech": True,
-        }
-    )
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {"instructions": "You are a concise assistant.", "temperature": 0.3},
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert "session.updated" in ws.sent_types()
-    assert not any(
-        message.get("type") == "error" and message.get("code") == "instructions_update_unsupported"
-        for message in ws.sent
-    )
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_session_update_rejects_instructions_before_first_real_append():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-buffered-before-lock", modalities=["text"]))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(3200, value=0.05),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-            "duration_ms": 200,
-            "is_speech": True,
-        }
-    )
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {
-                "instructions": (
-                    "You are now a swashbuckling pirate captain who speaks entirely in "
-                    "nautical slang, references buried treasure constantly, and never "
-                    "breaks character no matter what the user asks."
-                )
-            },
-        }
-    )
-    ws.put({"type": "input_audio_buffer.commit", "final": True, "response_create": True})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    error = next(message for message in ws.sent if message.get("type") == "error")
-    assert error["code"] == "instructions_update_unsupported"
-    assert "session.updated" not in ws.sent_types()
-    assert engine.appended, "the commit must still flush the buffered chunk despite the rejected update"
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_session_update_rejects_native_duplex_mode_flip():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-duplex-flag-flip", modalities=["text"]))
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {"extra_body": {"native_duplex": False}},
-        }
-    )
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {"instructions": "You are now a pirate."},
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    errors = [message for message in ws.sent if message.get("type") == "error"]
-    assert [error["code"] for error in errors] == [
-        "native_duplex_mode_update_unsupported",
-        "instructions_update_unsupported",
-    ]
-    assert "session.updated" not in ws.sent_types()
-
-
-@pytest.mark.parametrize("sample_rate_hz", [22_050, 24_000])
-def test_native_realtime_protocol_audio_delta_preserves_sample_rate_hz(sample_rate_hz: int):
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-
-    payloads = protocol._from_duplex_event(
-        {
-            "type": "response.output_audio.delta",
-            "response_id": "resp-a",
-            "audio": "AAAA",
-            "format": "pcm",
-            "sample_rate_hz": sample_rate_hz,
-            "audio_duration_ms": 135,
-        }
-    )
-
-    audio_events = [
-        payload for payload in payloads if payload["type"] in {"response.output_audio.delta", "response.audio.delta"}
-    ]
-    assert {payload["type"] for payload in audio_events} == {"response.output_audio.delta"}
-    assert {payload["format"] for payload in audio_events} == {"pcm16"}
-    assert {payload["sample_rate_hz"] for payload in audio_events} == {sample_rate_hz}
-    assert audio_events[0]["metadata"]["audio_duration_ms"] == 135
-
-
-def test_native_realtime_protocol_ignores_removed_legacy_event_switches():
-    ws = TimedWebSocket()
-    ws.query_params = {
-        "legacy_audio_events": "true",
-        "vllm_omni_legacy_events": "true",
-        "output_audio_events": "true",
-        "vllm_omni_output_audio_events": "true",
-    }
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-
-    payloads = protocol._from_duplex_event(
-        {
-            "type": "response.output_audio.delta",
-            "response_id": "resp-canonical",
-            "audio": "AAAA",
-            "text": "hello",
-            "format": "pcm",
-            "sample_rate_hz": 24000,
-            "end_of_turn": True,
-        }
-    )
-
-    event_types = {payload["type"] for payload in payloads}
-    assert "response.output_audio.delta" in event_types
-    assert "response.output_audio.done" in event_types
-    assert "response.output_audio_transcript.delta" in event_types
-    assert "response.output_audio_transcript.done" in event_types
-    assert "response.audio.delta" not in event_types
-    assert "response.audio.done" not in event_types
-    assert "response.audio_transcript.delta" not in event_types
-    assert "response.audio_transcript.done" not in event_types
-    assert "response.output_item.created" not in event_types
-    assert "response.text.delta" not in event_types
-
-
-def test_native_realtime_protocol_emits_terminal_audio_transcript_events():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-
-    payloads = protocol._from_duplex_event(
-        {
-            "type": "response.output_audio.delta",
-            "response_id": "resp-a",
-            "audio": "AAAA",
-            "text": "hello",
-            "format": "pcm",
-            "sample_rate_hz": 24000,
-            "end_of_turn": True,
-        }
-    )
-
-    by_type = {payload["type"]: payload for payload in payloads}
-    assert "response.output_audio.done" in by_type
-    assert "response.output_audio_transcript.delta" in by_type
-    assert "response.output_audio_transcript.done" in by_type
-    assert by_type["response.content_part.done"]["part"]["transcript"] == "hello"
-    assert by_type["response.output_item.done"]["item"]["object"] == "realtime.item"
-    assert by_type["response.done"]["response"]["output"][0]["object"] == "realtime.item"
-
-
-def test_native_realtime_protocol_terminal_transcript_equals_joined_deltas():
-    protocol = NativeRealtimeSessionProtocol(TimedWebSocket())  # type: ignore[arg-type]
-    response_id = "resp-transcript-contract"
-    events: list[dict[str, object]] = []
-
-    for text, end_of_turn in (("It's Canberra.", False), (" Next question.", True)):
-        events.extend(
-            protocol._from_duplex_event(
-                {
-                    "type": "response.output_audio.delta",
-                    "response_id": response_id,
-                    "audio": "AAAA",
-                    "text": text,
-                    "format": "pcm",
-                    "sample_rate_hz": 24000,
-                    "end_of_turn": end_of_turn,
-                }
-            )
-        )
-
-    transcript = "".join(
-        str(event["delta"]) for event in events if event["type"] == "response.output_audio_transcript.delta"
-    )
-    done = [str(event["transcript"]) for event in events if event["type"] == "response.output_audio_transcript.done"]
-
-    assert transcript == "It's Canberra. Next question."
-    assert done == [transcript]
-
-
-def test_native_realtime_protocol_updates_in_progress_item_for_audio_truncate():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-
-    protocol._from_duplex_event({"type": "response.created", "response_id": "resp-truncate"})
-    protocol._from_duplex_event(
-        {
-            "type": "response.output_audio.delta",
-            "response_id": "resp-truncate",
-            "audio": "AAAA",
-            "text": "hello",
-            "format": "pcm",
-            "sample_rate_hz": 24000,
-            "audio_duration_ms": 100,
-            "audio_text_marks": [{"text_chars": 5, "audio_end_ms": 100}],
-        }
-    )
-
-    item = protocol._conversation_items["item_resp-truncate"]
-    assert item["content"][0]["type"] == "output_audio"
-    assert item["content"][0]["transcript"] == "hello"
-    assert item["content"][0]["audio_duration_ms"] == 100
-
-    translated = asyncio.run(
-        protocol._to_duplex_event(
-            {
-                "type": "conversation.item.truncate",
-                "item_id": "item_resp-truncate",
-                "content_index": 0,
-                "audio_end_ms": 50,
-            }
-        )
-    )
-
-    assert translated is None
-    assert protocol._conversation_items["item_resp-truncate"]["content"][0]["transcript"] == "he"
-
-
-@pytest.mark.asyncio
-async def test_native_realtime_protocol_rejects_truncate_for_user_item():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol.bind_sender(ws.send_json)
-    protocol._conversation_items["item-user"] = {
-        "id": "item-user",
-        "object": "realtime.item",
-        "type": "message",
-        "role": "user",
-        "status": "completed",
-        "content": [{"type": "input_audio", "transcript": "hello"}],
-    }
-
-    translated = await protocol._to_duplex_event(
-        {
-            "type": "conversation.item.truncate",
-            "item_id": "item-user",
-            "content_index": 0,
-            "audio_end_ms": 10,
-        }
-    )
-
-    assert translated is None
-    error = next(event for event in ws.sent if event.get("type") == "error")
-    assert error["error"]["code"] == "bad_event"
-
-
-def test_native_realtime_protocol_response_done_emits_audio_done_before_terminal_events():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol._from_duplex_event({"type": "response.created", "response_id": "resp-done"})
-    protocol._from_duplex_event(
-        {
-            "type": "response.output_audio.delta",
-            "response_id": "resp-done",
-            "audio": "AAAA",
-            "format": "pcm",
-            "sample_rate_hz": 24000,
-        }
-    )
-
-    payloads = protocol._from_duplex_event({"type": "response.done", "response_id": "resp-done"})
-    event_types = [payload["type"] for payload in payloads]
-
-    assert event_types.index("response.output_audio.done") < event_types.index("response.content_part.done")
-    assert event_types.index("response.content_part.done") < event_types.index("response.output_item.done")
-    assert event_types.index("conversation.item.done") < event_types.index("response.done")
-    assert event_types.index("response.output_item.done") < event_types.index("response.done")
-
-
-def test_native_realtime_protocol_audio_cancelled_uses_active_response_id():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol._from_duplex_event({"type": "response.created", "response_id": "resp-cancel"})
-
-    payloads = protocol._from_duplex_event(
-        {
-            "type": "audio.cancelled",
-            "reason": "barge_in",
-            "committed_ms": 0,
-        }
-    )
-
-    done = [payload for payload in payloads if payload.get("type") == "response.done"]
-    assert len(done) == 1
-    assert done[0]["response_id"] == "resp-cancel"
-    assert done[0]["response"]["id"] == "resp-cancel"
-
-
-def test_native_realtime_protocol_audio_cancelled_does_not_reopen_completed_response():
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    protocol._from_duplex_event({"type": "response.created", "response_id": "resp-complete"})
-    protocol._from_duplex_event(
-        {
-            "type": "response.output_audio.delta",
-            "response_id": "resp-complete",
-            "audio": "AAAA",
-            "format": "pcm",
-            "sample_rate_hz": 24000,
-        }
-    )
-    protocol._from_duplex_event({"type": "response.done", "response_id": "resp-complete"})
-
-    payloads = protocol._from_duplex_event(
-        {
-            "type": "audio.cancelled",
-            "reason": "session_close",
-            "committed_ms": 999999,
-        }
-    )
-
-    assert [payload.get("type") for payload in payloads] == []
-
-
-def test_native_audio_text_marks_are_normalized_to_session_cumulative_offsets():
-    marks = OmniDuplexSessionHandler._normalize_native_audio_text_marks(
-        [{"text_chars": 3, "audio_end_ms": 200}],
-        audio_offset_ms=800,
-        text_offset_chars=5,
-    )
-
-    assert marks == [{"text_chars": 8, "audio_end_ms": 1000}]
-
-
-def test_duplex_session_playback_commit_uses_multi_delta_audio_text_marks():
-    session = DuplexSession(
-        session_id="sid-marks",
-        config=DuplexSessionConfig(playback_commit_policy=DuplexPlaybackCommitPolicy.ACK_ONLY.value),
-    )
-    session.begin_response()
-    session.append_assistant_text("hello ")
-    session.mark_audio_sent(1000, text_chars=6)
-    session.append_assistant_text("world")
-    session.mark_audio_sent(2000, text_chars=11)
-    session.acknowledge_playback(played_ms=1500, committed_ms=1500)
-
-    committed = session.end_response(commit_text=True)
-
-    assert committed == {"role": "assistant", "content": "hello wo"}
-    assert session.history == (committed,)
-
-
-def test_duplex_session_preserves_response_history_order_when_user_item_arrives_during_generation():
-    session = DuplexSession(session_id="sid-history-order", config=DuplexSessionConfig())
-    first_user = {"role": "user", "content": "first turn"}
-    next_user = {
-        "role": "user",
-        "content": [{"type": "audio_url", "audio_url": {"url": "data:audio/wav;base64,AAAA"}}],
-    }
-    session.append_history_message(first_user)
-    session.begin_response()
-    session.append_assistant_text("first answer")
-    session.append_history_message(next_user)
-
-    assistant = session.end_response(commit_text=True)
-
-    assert session.history == (first_user, assistant, next_user)
-
-
-@pytest.mark.asyncio
-async def test_duplex_session_actor_preserves_wire_order_before_control():
-    ws = TimedWebSocket()
-    actor = DuplexWebSocketActor(ws)
-
-    await actor.enqueue_event({"type": "input_audio_buffer.append", "audio": "AAAA"})
-    await actor.enqueue_event({"type": "response.cancel"})
-
-    first = await actor.next_event()
-    second = await actor.next_event()
-
-    assert first["type"] == "input_audio_buffer.append"
-    assert second["type"] == "response.cancel"
-
-
-def _pcm_f32_b64(samples: int, *, value: float = 0.05) -> str:
-    return base64.b64encode(struct.pack(f"<{samples}f", *([value] * samples))).decode("ascii")
-
-
-def _pcm16_b64(samples: int = 1, *, value: int = 1000) -> str:
-    return base64.b64encode(struct.pack(f"<{samples}h", *([value] * samples))).decode("ascii")
-
-
-def _session_create(session_id: str = "duplex-test") -> dict[str, Any]:
-    return {
-        "type": "session.create",
-        "session_id": session_id,
-        "session": {
-            "model": "test-model",
-            "modalities": ["text", "audio"],
-            "idle_timeout_s": 1,
-        },
-    }
-
-
-def _native_session_create(
-    session_id: str = "duplex-native",
-    *,
-    modalities: list[str] | None = None,
-) -> dict[str, Any]:
-    event = _session_create(session_id)
-    event["session"]["model"] = "openbmb/MiniCPM-o-4_5"
-    event["session"]["modalities"] = list(modalities or ["text"])
-    event["session"]["instructions"] = "You are a concise assistant."
-    event["session"]["extra_body"] = {"native_duplex": True}
-    return event
-
-
-def _native_realtime_session_update(
-    session_id: str,
-    *,
-    modalities: list[str] | None = None,
-) -> dict[str, Any]:
-    return {
-        "type": "session.update",
-        "session": {
-            "session_id": session_id,
-            "model": "openbmb/MiniCPM-o-4_5",
-            "modalities": list(modalities or ["text"]),
-            "instructions": "You are a concise assistant.",
-            "idle_timeout_s": 1,
-            "extra_body": {"native_duplex": True},
-        },
-    }
-
-
-def _native_server_vad_update(event_id: str, **session: object) -> dict[str, object]:
-    return {
-        "type": "session.update",
-        "event_id": event_id,
-        "session": {"turn_detection": {"type": "server_vad"}, **session},
-    }
-
-
-def test_native_stage0_request_id_matches_engine_after_same_session_id_reopen():
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    first = handler._registry.create(session_id="sid-reused")
-    handler._registry.close(first.session_id)
-    reopened = handler._registry.create(session_id="sid-reused")
-    expected = duplex_resource_request_id(
-        DuplexFence(
-            reopened.session_id,
-            epoch=reopened.epoch,
-            incarnation=reopened.incarnation,
-        ),
-        "stage0",
-    )
-
-    assert reopened.incarnation == 1
-    assert handler._native_stage0_request_id(reopened, reopened.epoch) == expected
-
-
-def _native_audio_payload(
-    *,
-    samples: int = 16000,
-    value: float = 0.05,
-    is_speech: bool | None = True,
-    force_listen: bool | None = None,
-) -> dict[str, Any]:
-    payload: dict[str, Any] = {
-        "type": "audio",
-        "audio": _pcm_f32_b64(samples, value=value),
-        "format": "pcm_f32le",
-        "sample_rate_hz": 16000,
-    }
-    if is_speech is not None:
-        payload["is_speech"] = is_speech
-    if force_listen is not None:
-        payload["force_listen"] = force_listen
-    return payload
-
-
-def _auto_response_context(
-    session_id: str,
-    *,
-    playback_active: bool = False,
-) -> tuple[OmniDuplexSessionHandler, DuplexSession]:
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id=session_id,
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    if playback_active:
-        session.config.playback_commit_policy = DuplexPlaybackCommitPolicy.ACK_ONLY.value
-        session.begin_response()
-        session.mark_audio_sent(duration_ms=1000)
-    return handler, session
-
-
-def _install_direct_silence_scheduler(
-    handler: OmniDuplexSessionHandler,
-    session: DuplexSession,
-) -> None:
-    native = handler._runtime_session_state(session)
-
-    async def _schedule(payload: object, **kwargs: Any) -> bool:
-        if handler._native_silence_continuation_is_stale(
-            session,
-            request_id=kwargs["request_id"],
-            response_id=kwargs["response_id"],
-            response_owned=kwargs["response_owned"],
-            expected_epoch=kwargs["expected_epoch"],
-            expected_incarnation=kwargs["expected_incarnation"],
-            expected_model_turn_id=kwargs["expected_model_turn_id"],
-        ):
-            return False
-        append_ok, _ = await handler._append_runtime_input(
-            session,
-            payload,
-            final=False,
-            send_json=kwargs["send_json"],
-            mode="append_audio_chunk",
-            expected_epoch=kwargs["expected_epoch"],
-        )
-        return append_ok
-
-    native.silence_continuation_scheduler = _schedule
-
-
-def test_minicpmo_pcm_append_buffer_flush_preserves_accumulated_speech_marker():
-    buffer = MiniCPMO45PcmAppendBuffer()
-    payload = _native_audio_payload(samples=8000)
-
-    assert buffer.append(payload, chunk_period_ms=1000) is None
-    flushed = buffer.flush(chunk_period_ms=1000)
-
-    assert flushed is not None
-    assert flushed["is_speech"] is True
-
-
-def test_minicpmo_pcm_append_buffer_drops_serving_new_user_turn_marker():
-    buffer = MiniCPMO45PcmAppendBuffer()
-    first = _native_audio_payload(samples=8000)
-    first.update(
-        new_user_turn=True,
-        new_user_turn_prefix_variant="clean_response_done",
-        force_speak=True,
-    )
-    second = _native_audio_payload(samples=8000)
-
-    assert buffer.append(first, chunk_period_ms=1000) is None
-    emitted = buffer.append(second, chunk_period_ms=1000)
-
-    assert emitted is not None
-    assert emitted["is_speech"] is True
-    assert "new_user_turn" not in emitted
-    assert "new_user_turn_prefix_variant" not in emitted
-    assert "force_speak" not in emitted
-
-
-def test_minicpmo_merge_native_audio_payloads_preserves_speech_marker():
-    first = _native_audio_payload(samples=8000)
-    second = _native_audio_payload(samples=8000, value=0.0, is_speech=False)
-
-    merged = OmniDuplexSessionHandler._merge_native_audio_payloads(first, second)
-
-    assert merged["is_speech"] is True
-
-
-def test_minicpmo_merge_drops_serving_new_user_turn_marker():
-    first = _native_audio_payload(samples=8000)
-    first.update(
-        new_user_turn=True,
-        new_user_turn_prefix_variant="clean_response_done",
-        force_speak=True,
-    )
-    second = _native_audio_payload(samples=8000, is_speech=False)
-
-    merged = OmniDuplexSessionHandler._merge_native_audio_payloads(first, second)
-
-    assert merged["is_speech"] is True
-    assert "new_user_turn" not in merged
-    assert "new_user_turn_prefix_variant" not in merged
-    assert "force_speak" not in merged
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_clear_continuation_does_not_cancel_pending_silence_task():
-    async def _pending() -> bool:
-        await asyncio.sleep(3600)
-        return True
-
-    native = MiniCPMO45ServingSessionState()
-    task = asyncio.create_task(_pending())
-    native.continuation_owner_id = "owner"
-    native.continuation_units = 1
-    native.pending_silence_task = task
-    native.pending_silence_owner_id = "owner"
-
-    native.clear_continuation()
-
-    assert native.continuation_owner_id is None
-    assert native.continuation_units == 0
-    assert native.pending_silence_task is None
-    assert native.pending_silence_owner_id is None
-    assert not task.cancelled()
-    task.cancel()
-    with pytest.raises(asyncio.CancelledError):
-        await task
-
-
-def test_auto_response_playback_overlap_keeps_model_owned_listen_speak_decision():
-    handler, session = _auto_response_context("sid-auto-silent-overlap", playback_active=True)
-    session.mark_audio_sent(duration_ms=1000)
-    silent_payload = _native_audio_payload(value=0.0, is_speech=None, force_listen=False)
-    speech_payload = _native_audio_payload(is_speech=None, force_listen=False)
-
-    assert handler._should_force_listen_for_auto_response_overlap(session, {}, silent_payload) is False
-    assert handler._should_force_listen_for_auto_response_overlap(session, {}, speech_payload) is False
-    assert (
-        handler._should_force_listen_for_auto_response_overlap(
-            session,
-            {"force_listen": True},
-            speech_payload,
-        )
-        is True
-    )
-    assert (
-        handler._should_force_listen_for_auto_response_overlap(
-            session,
-            {"force_barge_in": True},
-            speech_payload,
-        )
-        is False
-    )
-
-    session.acknowledge_playback(played_ms=1000, committed_ms=1000)
-    assert handler._should_force_listen_for_auto_response_overlap(session, {}, speech_payload) is False
-
-
-def test_legacy_auto_overlap_policy_falls_back_to_listen_only():
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-auto-policy-fallback",
-        config=DuplexSessionConfig(
-            overlap_policy=DuplexSessionConfig._normalize_overlap_policy("auto"),
-        ),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-
-    decision = handler._overlap_decision(
-        session,
-        {"duration_ms": session.config.overlap_barge_in_ms, "is_speech": True},
-        _native_audio_payload(is_speech=True),
-    )
-
-    assert session.config.overlap_policy == DuplexOverlapPolicy.LISTEN_ONLY.value
-    assert decision["action"] == "listen"
-    assert decision["reason"] == "policy_listen_only"
-
-
-def test_auto_response_overlap_silence_advances_model_unit_and_preserves_realtime_input():
-    handler, session = _auto_response_context(
-        "sid-auto-silent-wire-buffer",
-        playback_active=True,
-    )
-    decision = handler._overlap_decision(
-        session,
-        {"is_speech": False},
-        _native_audio_payload(samples=3200, is_speech=False),
-    )
-
-    assert decision["action"] == "listen"
-    assert decision["buffer_audio"] is True
-    assert decision["defer_runtime_append"] is False
-    assert decision["force_listen"] is False
-    assert decision["preserve_realtime_input"] is True
-
-
-def test_auto_response_playback_overlap_admits_model_units_and_tracks_speech():
-    handler, session = _auto_response_context("sid-auto-deferred-overlap", playback_active=True)
-    payload = _native_audio_payload(samples=8640)
-
-    decision = handler._overlap_decision(
-        session,
-        {"duration_ms": 540, "is_speech": True},
-        payload,
-    )
-
-    assert decision["action"] == "listen"
-    assert decision["defer_runtime_append"] is False
-    assert decision["force_listen"] is False
-    assert decision["buffer_audio"] is True
-    assert session.overlap_speech_ms == 540
-
-
-@pytest.mark.asyncio
-async def test_auto_response_overlap_exact_unit_commit_does_not_block_or_replay_next_unit():
-    class ModelUnitEngine(FakeEngineClient):
-        def __init__(self) -> None:
-            super().__init__()
-            self.append_started = asyncio.Event()
-            self.active_response_ids_at_append: list[str | None] = []
-            self.response_done_seen_at_append = False
-            self.session: DuplexSession | None = None
-            self.websocket: TimedWebSocket | None = None
-
-        async def append_duplex_input_async(self, session_id: str, **kwargs):
-            assert self.session is not None
-            assert self.websocket is not None
-            self.active_response_ids_at_append.append(self.session.active_response_id)
-            self.response_done_seen_at_append = "response.done" in self.websocket.sent_types()
-            kwargs.pop("expected_epoch", None)
-            result = await super().append_duplex_input_async(session_id, **kwargs)
-            self.append_started.set()
-            return result
-
-    engine = ModelUnitEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    engine.websocket = ws
-    create = _native_session_create("sid-auto-overlap-model-unit")
-    create["session"]["extra_body"]["auto_response"] = True
-    ws.put(create)
-    handler_task = asyncio.create_task(handler.handle_session(ws))
-
-    try:
-        for _ in range(100):
-            session = handler._registry.get("sid-auto-overlap-model-unit")
-            if session is not None and "session.created" in ws.sent_types():
-                break
-            await asyncio.sleep(0.01)
-        else:
-            pytest.fail("native duplex session did not open")
-
-        engine.session = session
-        session.config.playback_commit_policy = DuplexPlaybackCommitPolicy.ACK_ONLY.value
-        response_id = session.begin_response()
-        session.mark_audio_sent(duration_ms=2000)
-        request_id = handler._native_stage0_request_id(session, session.epoch)
-        session.bind_request(request_id)
-        expected_fence = DuplexFence(
-            session.session_id,
-            epoch=session.epoch,
-            turn_id=session.turn_id,
-            incarnation=session.incarnation,
-        )
-
-        chunk = {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(3200, value=0.05),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-            "duration_ms": 200,
-            "is_speech": True,
-        }
-        for _ in range(4):
-            ws.put(chunk)
-        await asyncio.sleep(0.05)
-        assert engine.appended == []
-
-        ws.put(chunk)
-        await asyncio.wait_for(engine.append_started.wait(), timeout=0.5)
-
-        ws.put({"type": "input_audio_buffer.commit", "final": True})
-        for _ in range(100):
-            if "input.committed" in ws.sent_types():
-                break
-            await asyncio.sleep(0.01)
-        else:
-            pytest.fail("exact model unit input did not commit")
-
-        engine.append_started.clear()
-        for _ in range(5):
-            ws.put(chunk)
-        await asyncio.wait_for(engine.append_started.wait(), timeout=0.5)
-        await asyncio.sleep(0.05)
-        assert "error" not in ws.sent_types()
-    finally:
-        ws.put({"type": "session.close"})
-        await asyncio.wait_for(handler_task, timeout=2)
-
-    assert len(engine.appended) == 2
-    for appended_session_id, mode, payload, final in engine.appended:
-        assert appended_session_id == session.session_id
-        assert mode == "append_audio_chunk"
-        assert final is False
-        assert isinstance(payload, dict)
-        assert np.frombuffer(base64.b64decode(payload["audio"]), dtype="<f4").shape == (16000,)
-        assert payload.get("force_listen") is not True
-    assert engine.appended_fences == [expected_fence, expected_fence]
-    assert engine.active_response_ids_at_append == [response_id, response_id]
-    assert engine.response_done_seen_at_append is False
-    assert not any(event in {"barge_in", "input.cancel"} for _, event in engine.signals)
-    assert ws.sent_types().count("response.speak") <= 1
-
-
-@pytest.mark.asyncio
-async def test_stale_terminal_event_does_not_reset_current_session_overlap():
-    handler, session = _auto_response_context("sid-stale-terminal")
-    session.epoch = 2
-    session.accumulate_overlap_speech(540)
-    actor = DuplexWebSocketActor(TimedWebSocket(), current_epoch=lambda: session.epoch)
-    native = MiniCPMO45ServingSessionState()
-
-    accepted, deferred = await handler._apply_outbound_session_event(
-        {"type": "response.done", "epoch": 1},
-        session=session,
-        actor=actor,
-        native=native,
-        realtime_protocol=None,
-    )
-
-    assert accepted is False
-    assert deferred is None
-    assert session.overlap_speech_ms == 540
-
-
-@pytest.mark.asyncio
-async def test_current_terminal_event_resets_session_owned_overlap():
-    handler, session = _auto_response_context("sid-current-terminal")
-    session.accumulate_overlap_speech(320)
-    actor = DuplexWebSocketActor(TimedWebSocket(), current_epoch=lambda: session.epoch)
-    native = MiniCPMO45ServingSessionState()
-
-    accepted, deferred = await handler._apply_outbound_session_event(
-        {"type": "response.done", "epoch": session.epoch},
-        session=session,
-        actor=actor,
-        native=native,
-        realtime_protocol=None,
-    )
-
-    assert accepted is True
-    assert deferred is None
-    assert session.overlap_speech_ms == 0
-
-
-@pytest.mark.asyncio
-async def test_response_listen_terminal_does_not_drive_serving_generation_state():
-    handler, session = _auto_response_context("sid-listen-terminal")
-    actor = DuplexWebSocketActor(TimedWebSocket(), current_epoch=lambda: session.epoch)
-    native = MiniCPMO45ServingSessionState()
-
-    accepted, deferred = await handler._apply_outbound_session_event(
-        {"type": "response.listen", "epoch": session.epoch},
-        session=session,
-        actor=actor,
-        native=native,
-        realtime_protocol=None,
-    )
-
-    assert accepted is True
-    assert deferred is None
-    assert session.turn_id == 0
-
-
-@pytest.mark.asyncio
-async def test_stale_audio_cancelled_does_not_reset_current_session_overlap():
-    handler, session = _auto_response_context("sid-stale-audio-cancelled")
-    session.epoch = 3
-    session.accumulate_overlap_speech(640)
-    actor = DuplexWebSocketActor(TimedWebSocket(), current_epoch=lambda: session.epoch)
-    native = MiniCPMO45ServingSessionState()
-
-    accepted, deferred = await handler._apply_outbound_session_event(
-        {"type": "audio.cancelled", "epoch": 2},
-        session=session,
-        actor=actor,
-        native=native,
-        realtime_protocol=None,
-    )
-
-    assert accepted is False
-    assert deferred is None
-    assert session.overlap_speech_ms == 640
-
-
-def test_auto_response_post_response_silence_remains_model_owned_input():
-    handler, session = _auto_response_context("sid-auto-waiting-silence", playback_active=True)
-    silent_payload = _native_audio_payload(value=0.0, is_speech=False, force_listen=False)
-    speech_payload = _native_audio_payload(force_listen=False)
-
-    assert handler._assistant_playback_active(session) is True
-    assert handler._should_force_listen_for_auto_response_overlap(session, {}, silent_payload) is False
-    assert handler._should_force_listen_for_auto_response_overlap(session, {}, speech_payload) is False
-
-
-@pytest.mark.asyncio
-async def test_auto_response_terminal_advances_open_realtime_input_without_commit():
-    handler, session = _auto_response_context("sid-auto-realtime-open-input", playback_active=True)
-    session.capabilities = minicpmo45_native_capabilities()
-    response_id = session.active_response_id
-    assert response_id is not None
-
-    native = handler._runtime_session_state(session)
-    native.input_since_commit = True
-    native.speech_since_commit = True
-    session.accumulate_overlap_speech(800)
-    assert (
-        native.audio_buffer.append(
-            _native_audio_payload(samples=8000),
-            chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
-        )
-        is None
-    )
-    session.end_response(commit_text=False, preserve_request=True)
-
-    allowed, promoted = await handler._apply_outbound_session_event(
-        {
-            "type": "response.done",
-            "response_id": response_id,
-            "epoch": session.epoch,
-            "status": "completed",
-        },
-        session=session,
-        actor=DuplexWebSocketActor(TimedWebSocket()),
-        native=native,
-        realtime_protocol=NativeRealtimeSessionProtocol({}),
-    )
-
-    assert allowed is True
-    assert promoted is None
-    assert native.audio_buffer.has_pending()
-    assert native.committed_audio_payload is None
-    assert native.deferred_response_create is False
-    assert native.input_since_commit is True
-    assert native.speech_since_commit is True
-    next_speech = _native_audio_payload(samples=8000)
-    assert "new_user_turn" not in next_speech
-
-
-@pytest.mark.asyncio
-async def test_auto_response_terminal_allows_next_model_unit_while_playback_drains():
-    handler, session = _auto_response_context(
-        "sid-auto-realtime-open-before-overlap",
-        playback_active=True,
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    response_id = session.active_response_id
-    assert response_id is not None
-
-    native = handler._runtime_session_state(session)
-    native.input_since_commit = True
-    native.speech_since_commit = True
-    session.end_response(commit_text=False, preserve_request=True)
-
-    allowed, promoted = await handler._apply_outbound_session_event(
-        {
-            "type": "response.done",
-            "response_id": response_id,
-            "epoch": session.epoch,
-            "status": "completed",
-        },
-        session=session,
-        actor=DuplexWebSocketActor(TimedWebSocket()),
-        native=native,
-        realtime_protocol=NativeRealtimeSessionProtocol({}),
-    )
-
-    assert allowed is True
-    assert promoted is None
-    assert native.input_since_commit is True
-    assert handler._assistant_playback_active(session) is True
-
-    next_speech = _native_audio_payload(samples=16_000)
-    assert "new_user_turn" not in next_speech
-
-
-@pytest.mark.asyncio
-async def test_realtime_committed_overlap_promotes_after_response_done():
-    handler, session = _auto_response_context("sid-auto-realtime-committed-input", playback_active=True)
-    session.capabilities = minicpmo45_native_capabilities()
-    response_id = session.active_response_id
-    assert response_id is not None
-
-    native = handler._runtime_session_state(session)
-    native.committed_audio_payload = _native_audio_payload()
-    native.deferred_response_create = True
-    session.accumulate_overlap_speech(1000)
-    session.end_response(commit_text=False, preserve_request=True)
-
-    allowed, promoted = await handler._apply_outbound_session_event(
-        {
-            "type": "response.done",
-            "response_id": response_id,
-            "epoch": session.epoch,
-            "status": "completed",
-        },
-        session=session,
-        actor=DuplexWebSocketActor(TimedWebSocket()),
-        native=native,
-        realtime_protocol=NativeRealtimeSessionProtocol({}),
-    )
-
-    assert allowed is True
-    assert promoted is not None
-    assert promoted["force_listen"] is False
-    assert native.committed_audio_payload is promoted
-    assert native.deferred_response_create is False
-    assert "new_user_turn" not in promoted
-
-
-@pytest.mark.asyncio
-async def test_auto_response_committed_overlap_does_not_precreate_empty_response():
-    session_id = "sid-auto-overlap-no-empty-response"
-    request_id = f"duplex-{session_id}-e0-stage0"
-
-    def _stage_output(samples: int, *, turn_end: bool = False):
-        return SimpleNamespace(
-            request_id=request_id,
-            finished=False,
-            outputs=[
-                SimpleNamespace(
-                    text="hello",
-                    multimodal_output={
-                        "audio": np.zeros(samples, dtype=np.float32),
-                        "sr": 24000,
-                        "meta": {
-                            "turn_end": turn_end,
-                            "duplex_turn_id": 0,
-                            "duplex_epoch": 0,
-                        },
-                    },
-                )
-            ],
-        )
-
-    first_append = {
-        "operation": "append",
-        "session_id": session_id,
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {
-                    "supported": True,
-                    "implementation_level": "model_native_duplex",
-                    "data_plane_append": True,
-                    "request_id": request_id,
-                    "response_stage_id": 1,
-                },
-            }
-        ],
-        "data_plane_outputs": [_stage_output(2400)],
-    }
-    promoted_append = {
-        "operation": "append",
-        "session_id": session_id,
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [],
-        "data_plane_outputs": [],
-    }
-    engine = FakeEngineClient(
-        append_results=[first_append, promoted_append],
-        collect_outputs=[[_stage_output(4800, turn_end=True)]],
-        collect_delay_s=0.1,
-    )
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=2,
-    )
-
-    overlap_sent = False
-
-    def commit_overlap_after_first_response(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        nonlocal overlap_sent
-        if data.get("type") != "response.output_audio.delta" or overlap_sent:
-            return
-        overlap_sent = True
-        chunk = {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(3200, value=0.05),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-            "duration_ms": 200,
-            "is_speech": True,
-        }
-        for _ in range(4):
-            ws.put(chunk)
-        ws.put({"type": "input_audio_buffer.commit", "final": True})
-
-    ws = TimedWebSocket(on_send=commit_overlap_after_first_response, receive_timeout_s=3)
-    create = _native_realtime_session_update(session_id)
-    create["session"]["extra_body"]["auto_response"] = True
-    ws.put(create)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000, value=0.05),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-            "duration_ms": 1000,
-            "is_speech": True,
-        }
-    )
-    ws.put({"type": "input_audio_buffer.commit", "final": True})
-
-    handler_task = asyncio.create_task(handler.handle_realtime_session(ws))
-    try:
-        for _ in range(300):
-            if len(engine.appended) >= 2:
-                break
-            await asyncio.sleep(0.01)
-        else:
-            pytest.fail(
-                f"committed overlap was not promoted after response.done: "
-                f"appends={len(engine.appended)}, events={ws.sent_types()}"
-            )
-
-        assert overlap_sent is True
-        assert len(engine.appended) == 2
-        assert engine.appended[1][3] is True
-        assert ws.sent_types().count("response.created") == 1
-    finally:
-        ws.put({"type": "session.close"})
-        await asyncio.wait_for(handler_task, timeout=3)
-
-    assert ws.sent_types().count("response.done") >= 1
-
-
-def test_auto_response_barge_in_does_not_mark_serving_new_user_turn_payload():
-    handler, session = _auto_response_context("sid-auto-barge-new-turn", playback_active=True)
-    payload = _native_audio_payload()
-
-    assert handler._should_force_listen_for_auto_response_overlap(session, {"force_barge_in": True}, payload) is False
-    assert "new_user_turn" not in payload
-    assert "new_user_turn_prefix_variant" not in payload
-    assert session.turn_id == 0
-    assert payload.get("force_speak") is not True
-
-
-def test_native_realtime_barge_in_payload_does_not_create_serving_turn_boundary():
-    payload: dict[str, object] = {
-        "type": "audio",
-        "audio": _pcm_f32_b64(16000, value=0.05),
-        "format": "pcm_f32le",
-        "sample_rate_hz": 16000,
-        "is_speech": True,
-    }
-    session = DuplexSession(session_id="sid-realtime-barge", config=DuplexSessionConfig())
-    session.turn_id = 2
-
-    assert "new_user_turn" not in payload
-    assert "new_user_turn_prefix_variant" not in payload
-    assert session.turn_id == 2
-
-
-def test_auto_response_force_barge_in_has_no_waiting_turn_variant():
-    handler, session = _auto_response_context("sid-auto-barge-keeps-variant")
-    payload = _native_audio_payload()
-
-    assert (
-        handler._should_force_listen_for_auto_response_overlap(
-            session,
-            {"force_barge_in": True},
-            payload,
-        )
-        is False
-    )
-
-
-def test_duplex_endpoint_requires_explicit_realtime_configuration():
-    assert should_enable_duplex_endpoint(None) is False
-    assert should_enable_duplex_endpoint([]) is False
-    assert should_enable_duplex_endpoint([SimpleNamespace(session_mode="turn")]) is False
-    assert should_enable_duplex_endpoint([{"session_mode": "turn"}]) is False
-    assert (
-        should_enable_duplex_endpoint(
-            [
-                SimpleNamespace(session_mode="turn"),
-                SimpleNamespace(session_mode="duplex"),
-            ]
-        )
-        is True
-    )
-    assert should_enable_duplex_endpoint([{"session_mode": "duplex"}]) is True
-
-
-def test_duplex_endpoint_supports_top_level_session_mode(tmp_path):
-    config_path = tmp_path / "stage_config.yaml"
-    config_path.write_text(
-        """
-session_mode: duplex
-stage_args:
-  - stage_id: 0
-    engine_args: {}
-""",
-        encoding="utf-8",
-    )
-
-    assert should_enable_duplex_endpoint([], config_path=str(config_path)) is True
-
-
-def test_duplex_endpoint_supports_inherited_duplex_session(tmp_path):
-    base_path = tmp_path / "base.yaml"
-    base_path.write_text(
-        """
-session_mode: turn
-duplex_session: {}
-stages: []
-""",
-        encoding="utf-8",
-    )
-    config_path = tmp_path / "deploy.yaml"
-    config_path.write_text("base_config: base.yaml\n", encoding="utf-8")
-
-    assert should_enable_duplex_endpoint([], config_path=str(config_path)) is True
-
-
-def test_duplex_handler_splits_data_plane_audio_list_into_deltas():
-    import torch
-
-    data_plane = _test_data_plane()
-    output = SimpleNamespace(
-        finished=True,
-        outputs=[
-            SimpleNamespace(
-                text="hello",
-                multimodal_output={
-                    "audio": [
-                        torch.zeros(10, dtype=torch.float32),
-                        torch.zeros(20, dtype=torch.float32),
-                    ],
-                    "sr": 24000,
-                },
-            )
-        ],
-    )
-
-    native_results = list(data_plane.project_output(output))
-
-    assert [result["audio_data"] for result in native_results] == ["wav-10", "wav-20"]
-    assert [result["text"] for result in native_results] == ["hello", ""]
-    assert [result["end_of_turn"] for result in native_results] == [False, True]
-
-
-def test_duplex_listen_latent_does_not_poison_cumulative_audio_offset():
-    import torch
-
-    data_plane = _test_data_plane()
-    request_id = "duplex-duplex-sess-stage0"
-
-    # A model-listen decision wraps the segment with a latent tensor that is
-    # NOT reply audio; it must not advance the cumulative audio offset.
-    listen_output = SimpleNamespace(
-        request_id=request_id,
-        finished=True,
-        outputs=[],
-        multimodal_output={
-            "duplex_native_decision": "listen",
-            "model_listen": True,
-            "latent": torch.zeros(331776, dtype=torch.float32),
-            "meta": {"sr": 24000},
-        },
-    )
-    listen_results = list(data_plane.project_output(listen_output))
-    assert [result.get("is_listen") for result in listen_results] == [True]
-
-    # The first speak unit carries cumulative stage-1 audio far smaller than
-    # the listen latent; it must still be delivered from sample 0.
-    speak_output = SimpleNamespace(
-        request_id=request_id,
-        finished=False,
-        outputs=[
-            SimpleNamespace(
-                text=" It was a very",
-                multimodal_output={},
-            )
-        ],
-        multimodal_output={
-            "audio": torch.zeros(32768, dtype=torch.float32),
-            "sr": 24000,
-        },
-    )
-    speak_results = list(data_plane.project_output(speak_output))
-    assert [result.get("audio_data") for result in speak_results] == ["wav-32768"]
-    assert speak_results[0]["text"] == " It was a very"
-
-
-def test_direct_listen_decision_survives_inner_completion_metadata():
-    inner_output = SimpleNamespace(
-        outputs=[
-            SimpleNamespace(
-                multimodal_output={"special_token_ids": {"listen_token_id": 151705}},
-            )
-        ]
-    )
-    decision = MiniCPMO45DuplexRuntimeExtension().decide_output(
-        stage_id=0,
-        final_stage_id=1,
-        segment_finished=True,
-        segment_token_ids=(151705,),
-        segment_output_metadata={"special_token_ids": {"listen_token_id": 151705}},
-        output=inner_output,
-    )
-    assert decision is not None
-    output = attach_duplex_output_decision(
-        OmniRequestOutput.from_stage_output(
-            inner_output,
-            request_id="duplex-direct-listen",
-            finished=True,
-            stage_id=0,
-            final_output_type=decision.final_output_type,
-            metrics={
-                "stage_metrics": {
-                    "0": {
-                        "vllm_ttft_ms": 125.0,
-                        "vllm_tpot_ms": 18.0,
-                        "vllm_itl_ms": 17.5,
-                        "vllm_itls_ms": [17.0, 18.0],
-                    }
-                }
-            },
-        ),
-        decision,
-    )
-
-    results = list(_test_data_plane().project_output(output))
-
-    assert len(results) == 1
-    assert results[0]["is_listen"] is True
-    assert results[0]["model_listen"] is True
-    assert results[0]["listen_source"] == "model_listen"
-    assert results[0]["stage_metrics"] == output.metrics["stage_metrics"]
-
-
-def test_duplex_segment_text_is_attached_once_across_streaming_batches():
-    import torch
-
-    class _ChatService:
-        model_config = _ModelConfig()
-
-        def create_audio(self, audio_obj):
-            return SimpleNamespace(audio_data=f"wav-{int(audio_obj.audio_tensor.shape[0])}")
-
-    data_plane = _test_data_plane()
-    request_id = "duplex-duplex-sess-stage0"
-    session = DuplexSession(
-        session_id="sid-auto-respond",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-
-    def _speak(total_samples: int, text: str, *, finished: bool):
-        output = SimpleNamespace(
-            request_id=request_id,
-            finished=finished,
-            outputs=[SimpleNamespace(text=text, multimodal_output={})],
-            multimodal_output={
-                "audio": torch.zeros(total_samples, dtype=torch.float32),
-                "sr": 24000,
-            },
-        )
-        return _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    def _audio(results):
-        return [r for r in results if r.get("is_listen") is False]
-
-    def _listen(results):
-        return [r for r in results if r.get("is_listen") is True]
-
-    # One talker segment streams several cumulative-audio batches, each
-    # carrying the SAME segment text; only the first may attach it.
-    assert [r["text"] for r in _audio(_speak(100, " movie called", finished=False))] == [" movie called"]
-    assert [r["text"] for r in _audio(_speak(220, " movie called", finished=False))] == [""]
-    finished_results = _speak(300, " movie called", finished=True)
-    assert [r["text"] for r in _audio(finished_results)] == [""]
-    assert _listen(finished_results) == []
-
-    # Continuation units re-run the talker with the SAME handed text past a
-    # finished boundary (every engine segment ends finished=True); the text
-    # must stay suppressed or each continuation duplicates the transcript.
-    assert [r["text"] for r in _audio(_speak(400, " movie called", finished=False))] == [""]
-    assert [r["text"] for r in _audio(_speak(450, " movie called", finished=True))] == [""]
-
-    # A genuinely new segment text is attached in full.
-    assert [r["text"] for r in _audio(_speak(500, " Titanic", finished=True))] == [" Titanic"]
-
-    # Text growing within a segment is delivered as suffix deltas.
-    assert [r["text"] for r in _audio(_speak(600, " by", finished=False))] == [" by"]
-    assert [r["text"] for r in _audio(_speak(700, " by James", finished=True))] == [" James"]
-
-    # A segment whose finished batch slices to an EMPTY audio delta (all
-    # samples already delivered) must not block the next segment's text.
-    assert [r["text"] for r in _audio(_speak(800, " James Cameron. The", finished=False))] == [" James Cameron. The"]
-    assert _speak(800, " James Cameron. The", finished=True) == []
-    assert [r["text"] for r in _audio(_speak(900, " 997.", finished=False))] == [" 997."]
-
-
-def test_duplex_data_plane_output_prefers_audio_segment_text_metadata():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-native-segment-text-e0-stage0"
-    segment_text = "你好，有什么想聊的吗？"
-    cumulative_text = segment_text * 2
-    output = SimpleNamespace(
-        request_id=request_id,
-        finished=False,
-        outputs=[SimpleNamespace(text=cumulative_text, multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(24000, dtype=np.float32),
-            "sr": 24000,
-            "meta.llm_output_text_utf8": np.frombuffer(segment_text.encode("utf-8"), dtype=np.uint8),
-        },
-    )
-
-    results = list(data_plane.project_output(output))
-
-    assert len(results) == 1
-    assert results[0]["audio_data"] == "wav-24000"
-    assert results[0]["text"] == segment_text
-
-    next_output_without_segment_metadata = SimpleNamespace(
-        request_id=request_id,
-        finished=False,
-        outputs=[SimpleNamespace(text=segment_text * 3, multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(30720, dtype=np.float32),
-            "sr": 24000,
-        },
-    )
-    next_results = list(data_plane.project_output(next_output_without_segment_metadata))
-
-    assert len(next_results) == 1
-    assert next_results[0]["audio_data"] == "wav-6720"
-    assert next_results[0]["text"] == ""
-
-
-@pytest.mark.parametrize(
-    ("request_id", "second_samples", "expected_second_audio"),
-    [
-        ("duplex-sid-model-turn-audio-e0-stage0", 36000, "wav-12000"),
-        ("duplex-sid-model-turn-audio-restart-e0-stage0", 12000, "wav-12000"),
-    ],
-    ids=["cumulative-across-model-turns", "upstream-cumulative-audio-restarts"],
-)
-def test_duplex_audio_cursor_across_model_turns(
-    request_id: str,
-    second_samples: int,
-    expected_second_audio: str,
-):
-    data_plane = _test_data_plane()
-
-    def output(turn_id: int, samples: int):
-        return SimpleNamespace(
-            request_id=request_id,
-            finished=False,
-            outputs=[SimpleNamespace(text="", multimodal_output={})],
-            multimodal_output={
-                "audio": np.zeros(samples, dtype=np.float32),
-                "sr": 24000,
-                "meta.duplex_turn_id": np.array([turn_id], dtype=np.int32),
-            },
-        )
-
-    first = list(data_plane.project_output(output(0, 24000)))
-    second = list(data_plane.project_output(output(1, second_samples)))
-
-    assert first[0]["audio_data"] == "wav-24000"
-    assert second[0]["audio_data"] == expected_second_audio
-
-
-def test_duplex_data_plane_accepts_model_turn_output_across_client_commits():
-    data_plane = _test_data_plane()
-    session = DuplexSession(
-        session_id="sid-auto-stale-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.commit_native_audio_input()
-    session.commit_native_audio_input()
-    session.turn_id = 1
-    session.epoch = 0
-    request_id = "duplex-sid-auto-stale-turn-stage0"
-    output = SimpleNamespace(
-        request_id=request_id,
-        finished=False,
-        outputs=[SimpleNamespace(text="old tail", multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(24000, dtype=np.float32),
-            "sr": 24000,
-            "meta.duplex_turn_id": np.array([1], dtype=np.int32),
-            "meta.llm_output_text_utf8": np.frombuffer("旧尾巴".encode(), dtype=np.uint8),
-        },
-    )
-
-    results = list(data_plane.project_output(output, context=_data_plane_context(session)))
-
-    assert len(results) == 1
-    assert results[0]["audio_data"] == "wav-24000"
-    assert results[0]["model_turn_id"] == 1
-
-
-def test_duplex_data_plane_accepts_active_response_turn_identity():
-    data_plane = _test_data_plane()
-    session = DuplexSession(
-        session_id="sid-active-response-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.turn_id = 1
-    session.epoch = 0
-    session.begin_response(turn_id=0)
-    output = SimpleNamespace(
-        request_id="duplex-sid-active-response-turn-stage0",
-        finished=True,
-        outputs=[SimpleNamespace(text="", multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(10, dtype=np.float32),
-            "sr": 24000,
-            "meta.duplex_turn_id": np.array([0], dtype=np.int32),
-            "meta.duplex_epoch": np.array([0], dtype=np.int32),
-        },
-    )
-
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert len(results) == 1
-
-
-def test_duplex_data_plane_listen_preserves_model_turn_identity():
-    data_plane = _test_data_plane()
-    session = DuplexSession(
-        session_id="sid-listen-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    output = SimpleNamespace(
-        request_id="duplex-sid-listen-turn-stage0",
-        finished=True,
-        outputs=[SimpleNamespace(text="", token_ids=[], multimodal_output={})],
-        multimodal_output={
-            "duplex_native_decision": "listen",
-            "meta.duplex_turn_id": np.array([2], dtype=np.int32),
-            "meta.duplex_epoch": np.array([0], dtype=np.int32),
-        },
-    )
-
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert len(results) == 1
-    assert results[0]["is_listen"] is True
-    assert results[0]["model_turn_id"] == 2
-
-
-def test_duplex_data_plane_does_not_drop_future_model_turn_while_response_active():
-    data_plane = _test_data_plane()
-    session = DuplexSession(
-        session_id="sid-future-response-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.turn_id = 0
-    session.epoch = 0
-    session.begin_response(turn_id=0)
-    output = SimpleNamespace(
-        request_id="duplex-sid-future-response-turn-stage0",
-        finished=False,
-        outputs=[SimpleNamespace(text="", multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(10, dtype=np.float32),
-            "sr": 24000,
-            "meta.duplex_turn_id": np.array([1], dtype=np.int32),
-            "meta.duplex_epoch": np.array([0], dtype=np.int32),
-        },
-    )
-
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert len(results) == 1
-    assert results[0]["model_turn_id"] == 1
-    assert results[0]["audio_data"] == "wav-10"
-
-
-def _duplex_tts_output(
-    *,
-    request_id: str,
-    samples: int,
-    finished: bool,
-    text: str = "hello",
-    tts_is_last_chunk: bool = False,
-    turn_end: bool = False,
-    turn_id: int = 0,
-    token_ids: list[int] | None = None,
-):
-    return SimpleNamespace(
-        request_id=request_id,
-        finished=finished,
-        outputs=[SimpleNamespace(text=text, token_ids=list(token_ids or []), multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(samples, dtype=np.float32),
-            "sr": 24000,
-            "meta.tts_is_last_chunk": np.array([int(tts_is_last_chunk)], dtype=np.int32),
-            "meta.turn_end": np.array([int(turn_end)], dtype=np.int32),
-            "meta.duplex_turn_id": np.array([turn_id], dtype=np.int32),
-            "meta.duplex_epoch": np.array([0], dtype=np.int32),
-        },
-    )
-
-
-@pytest.mark.parametrize(
-    (
-        "finished",
-        "tts_is_last_chunk",
-        "turn_end",
-        "consume_audio_first",
-        "expected_end_of_turn",
-        "expected_audio",
-    ),
-    [
-        (False, True, False, False, False, "wav-24000"),
-        (True, True, False, True, False, ""),
-        (True, True, True, True, True, ""),
-    ],
-    ids=[
-        "last-audio-batch-does-not-end-response",
-        "scheduler-eos-only-ends-tts-segment",
-        "explicit-turn-end-metadata-ends-response",
-    ],
-)
-def test_duplex_auto_response_tts_boundary(
-    finished: bool,
-    tts_is_last_chunk: bool,
-    turn_end: bool,
-    consume_audio_first: bool,
-    expected_end_of_turn: bool,
-    expected_audio: str,
-):
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-tts-boundary-e0-stage0"
-    session = DuplexSession(
-        session_id="sid-tts-boundary",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.bind_response_turn(0)
-    if consume_audio_first:
-        data_plane.slice_cumulative_audio(request_id, np.zeros(24000, dtype=np.float32))
-    output = _duplex_tts_output(
-        request_id=request_id,
-        samples=24000,
-        finished=finished,
-        tts_is_last_chunk=tts_is_last_chunk,
-        turn_end=turn_end,
-        token_ids=[151645] if finished else None,
-    )
-
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert len(results) == 1
-    boundary = results[0]
-    assert boundary["stage_role"] == "tts"
-    assert boundary["end_of_turn"] is expected_end_of_turn
-    assert boundary["abort_data_plane_request"] is True
-    assert boundary["audio_data"] == expected_audio
-
-
-def test_duplex_auto_response_tts_scheduler_eos_fallback():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-tts-eos-no-profile-e0-stage0"
-    session = DuplexSession(
-        session_id="sid-tts-eos-no-profile",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.bind_response_turn(0)
-    data_plane.slice_cumulative_audio(request_id, np.zeros(24000, dtype=np.float32))
-    output = _duplex_tts_output(
-        request_id=request_id,
-        samples=24000,
-        finished=True,
-        tts_is_last_chunk=False,
-        token_ids=[151645],
-    )
-
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert len(results) == 1
-    assert results[0]["stage_role"] == "tts"
-    assert results[0]["abort_data_plane_request"] is True
-
-
-def test_duplex_auto_response_rearms_tts_boundary_for_next_segment_in_same_turn():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-next-segment-same-turn-e0-stage0"
-    session = DuplexSession(
-        session_id="sid-next-segment-same-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.bind_response_turn(0)
-    data_plane.begin_request(request_id)
-
-    first_segment = _duplex_tts_output(
-        request_id=request_id,
-        samples=24000,
-        finished=False,
-        tts_is_last_chunk=True,
-        turn_id=0,
-    )
-    first_results = _project_data_plane(
-        data_plane,
-        {"data_plane_outputs": [first_segment]},
-        session=session,
-    )
-
-    assert len(first_results) == 1
-    assert first_results[0]["abort_data_plane_request"] is True
-
-    data_plane.begin_request(request_id)
-    second_segment = _duplex_tts_output(
-        request_id=request_id,
-        samples=48000,
-        finished=False,
-        text="hello again",
-        tts_is_last_chunk=True,
-        turn_id=0,
-    )
-    second_results = _project_data_plane(
-        data_plane,
-        {"data_plane_outputs": [second_segment]},
-        session=session,
-    )
-
-    assert len(second_results) == 1
-    assert second_results[0]["audio_data"] == "wav-24000"
-    assert second_results[0]["abort_data_plane_request"] is True
-
-
-def test_duplex_turn_end_is_not_swallowed_by_finished_segment_fallback():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-turn-end-after-segment-e0-stage0"
-    session = DuplexSession(
-        session_id="sid-turn-end-after-segment",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.begin_response(turn_id=0)
-    session.bind_request(request_id)
-    _project_data_plane(
-        data_plane,
-        {
-            "data_plane_outputs": [
-                _duplex_tts_output(
-                    request_id=request_id,
-                    samples=24000,
-                    finished=False,
-                    tts_is_last_chunk=True,
-                )
-            ]
-        },
-        session=session,
-    )
-    output = _duplex_tts_output(
-        request_id=request_id,
-        samples=24000,
-        finished=True,
-        text="",
-        tts_is_last_chunk=False,
-        turn_end=True,
-        token_ids=[151645],
-    )
-
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert len(results) == 1
-    assert results[0]["stage_role"] == "tts"
-    assert results[0]["end_of_turn"] is True
-
-    duplicate = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert not any(result.get("end_of_turn") is True for result in duplicate)
-
-
-def test_duplex_auto_response_discards_terminal_only_audio_before_response_creation():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-terminal-only-audio-e0-stage0"
-    session = DuplexSession(
-        session_id="sid-terminal-only-audio",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.bind_request(request_id)
-    first_audio = _duplex_tts_output(
-        request_id=request_id,
-        samples=3840,
-        finished=False,
-        text="",
-    )
-
-    assert _project_data_plane(data_plane, {"data_plane_outputs": [first_audio]}, session=session) == []
-
-    terminal = _duplex_tts_output(
-        request_id=request_id,
-        samples=3840,
-        finished=True,
-        text="",
-        tts_is_last_chunk=True,
-        turn_end=True,
-        token_ids=[151645],
-    )
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [terminal]}, session=session)
-
-    assert len(results) == 1
-    assert results[0]["audio_data"] == ""
-    assert results[0]["end_of_turn"] is True
-    assert session.active_request_id == request_id
-    assert not data_plane.is_terminal(request_id)
-
-
-def test_duplex_auto_response_releases_buffered_audio_when_transcript_arrives():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-delayed-transcript-e0-stage0"
-    session = DuplexSession(
-        session_id="sid-delayed-transcript",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    audio_before_text = _duplex_tts_output(
-        request_id=request_id,
-        samples=100,
-        finished=False,
-        text="",
-    )
-
-    assert _project_data_plane(data_plane, {"data_plane_outputs": [audio_before_text]}, session=session) == []
-
-    audio_with_text = _duplex_tts_output(
-        request_id=request_id,
-        samples=200,
-        finished=False,
-        text="hello",
-    )
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [audio_with_text]}, session=session)
-
-    assert [result["audio_data"] for result in results] == ["wav-100", "wav-100"]
-    assert [result["text"] for result in results] == ["", "hello"]
-
-
-def test_duplex_auto_response_releases_buffered_audio_on_text_only_terminal():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-delayed-terminal-text-e0-stage0"
-    session = DuplexSession(
-        session_id="sid-delayed-terminal-text",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    audio_before_text = _duplex_tts_output(
-        request_id=request_id,
-        samples=100,
-        finished=False,
-        text="",
-        turn_id=1,
-    )
-
-    assert _project_data_plane(data_plane, {"data_plane_outputs": [audio_before_text]}, session=session) == []
-
-    textless_turn_terminal = _duplex_tts_output(
-        request_id=request_id,
-        samples=100,
-        finished=True,
-        text="",
-        tts_is_last_chunk=True,
-        turn_end=True,
-        turn_id=1,
-        token_ids=[151645],
-    )
-    terminal_results = list(
-        data_plane.project(
-            {"data_plane_outputs": [textless_turn_terminal]},
-            context=_data_plane_context(session),
-        )
-    )
-
-    assert len(terminal_results) == 1
-    assert terminal_results[0]["audio_data"] == ""
-    assert terminal_results[0]["end_of_turn"] is True
-
-    text_only_terminal = SimpleNamespace(
-        request_id=request_id,
-        finished=True,
-        outputs=[SimpleNamespace(text="hello", token_ids=[151645], multimodal_output={})],
-        multimodal_output={
-            "sr": 24000,
-            "meta.tts_is_last_chunk": np.array([1], dtype=np.int32),
-            "meta.turn_end": np.array([1], dtype=np.int32),
-            "meta.duplex_turn_id": np.array([2], dtype=np.int32),
-            "meta.duplex_epoch": np.array([0], dtype=np.int32),
-        },
-    )
-    results = _project_data_plane(data_plane, {"data_plane_outputs": [text_only_terminal]}, session=session)
-
-    assert len(results) == 1
-    assert results[0]["audio_data"] == "wav-100"
-    assert results[0]["text"] == "hello"
-    assert results[0]["end_of_turn"] is True
-    assert results[0]["abort_data_plane_request"] is True
-    assert not data_plane.has_pending_audio(request_id)
-
-
-@pytest.mark.asyncio
-async def test_native_append_propagates_current_turn_fence_to_engine():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(
-        session_id="sid-fenced-append",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.turn_id = 2
-    session.begin_response(turn_id=2)
-    ws = TimedWebSocket()
-
-    await handler._append_runtime_input(
-        session,
-        {"duplex_turn_id": 2, "audio": "", "format": "pcm_f32le"},
-        final=True,
-        send_json=ws.send_json,
-        mode="append_audio_chunk",
-        expected_epoch=0,
-    )
-
-    assert engine.appended_fences == [DuplexFence("sid-fenced-append", epoch=0, turn_id=2)]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_tts_segment_boundary_appends_silence_unit():
-    request_id = "duplex-sid-segment-boundary-e0-stage0"
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-segment-boundary",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.begin_response(turn_id=0)
-    session.turn_id = 1
-    session.bind_request(request_id)
-    session.mark_audio_sent(100)
-    _install_direct_silence_scheduler(handler, session)
-    ws = TimedWebSocket()
-
-    await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "tts",
-            "is_listen": False,
-            "data_plane_request_id": request_id,
-            "text": "",
-            "audio_data": "",
-            "audio_format": "pcm16",
-            "end_of_turn": False,
-            "abort_data_plane_request": True,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-    await asyncio.sleep(0.01)
-
-    assert len(engine.appended) == 1
-    _, mode, payload, final = engine.appended[0]
-    assert mode == "append_audio_chunk"
-    assert payload["format"] == "pcm_f32le"
-    assert payload["duplex_turn_id"] == 0
-    assert "force_speak" not in payload
-    assert final is False
-    assert session.active_response_id is not None
-    assert "response.done" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_pre_response_tts_boundary_continues_model_turn():
-    request_id = "duplex-sid-pre-response-boundary-e0-stage0"
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(
-        session_id="sid-pre-response-boundary",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.bind_request(request_id)
-    _install_direct_silence_scheduler(handler, session)
-    ws = TimedWebSocket()
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "tts",
-            "is_listen": False,
-            "data_plane_request_id": request_id,
-            "model_turn_id": session.turn_id,
-            "text": "",
-            "audio_data": "",
-            "audio_format": "pcm16",
-            "end_of_turn": False,
-            "abort_data_plane_request": True,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-    await asyncio.sleep(0.01)
-
-    assert close_reason is None
-    assert emitted is False
-    assert session.active_response_id is None
-    assert ws.sent == []
-    assert len(engine.appended) == 1
-    _, mode, payload, final = engine.appended[0]
-    assert mode == "append_audio_chunk"
-    assert payload["duplex_turn_id"] == session.turn_id
-    assert final is False
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_pre_response_continuation_drops_after_model_turn_ends():
-    request_id = "duplex-sid-stale-pre-response-boundary-e0-stage0"
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(
-        session_id="sid-stale-pre-response-boundary",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.bind_request(request_id)
-    model_turn_id = session.turn_id
-
-    native = handler._runtime_session_state(session)
-
-    async def _stale_before_append(payload: object, **kwargs: Any) -> bool:
-        session.complete_model_turn(model_turn_id)
-        if handler._native_silence_continuation_is_stale(
-            session,
-            request_id=kwargs["request_id"],
-            response_id=kwargs["response_id"],
-            response_owned=kwargs["response_owned"],
-            expected_epoch=kwargs["expected_epoch"],
-            expected_incarnation=kwargs["expected_incarnation"],
-            expected_model_turn_id=kwargs["expected_model_turn_id"],
-        ):
-            return False
-        append_ok, _ = await handler._append_runtime_input(
-            session,
-            payload,
-            final=False,
-            send_json=kwargs["send_json"],
-            mode="append_audio_chunk",
-            expected_epoch=kwargs["expected_epoch"],
-        )
-        return append_ok
-
-    native.silence_continuation_scheduler = _stale_before_append
-
-    await handler._maybe_continue_native_response(
-        TimedWebSocket().send_json,
-        session=session,
-        expected_epoch=session.epoch,
-        expected_model_turn_id=model_turn_id,
-    )
-    await asyncio.sleep(0.01)
-
-    assert engine.appended == []
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_continuation_stops_at_large_safety_boundary():
-    request_id = "duplex-sid-long-response-e0-stage0"
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(
-        session_id="sid-long-response",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.begin_response(turn_id=0)
-    session.turn_id = 1
-    session.bind_request(request_id)
-    session.mark_audio_sent(100)
-    _install_direct_silence_scheduler(handler, session)
-    ws = TimedWebSocket()
-
-    for _ in range(handler._NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS):
-        await handler._maybe_continue_native_response(
-            ws.send_json,
-            session=session,
-            expected_epoch=session.epoch,
-        )
-    await asyncio.sleep(0.02)
-
-    response_id = session.active_response_id
-    assert response_id is not None
-    assert len(engine.appended) == handler._NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS
-    assert all(payload["duplex_turn_id"] == 0 for _, _, payload, _ in engine.appended)
-    assert all(not {"force_speak", "force_listen"} & payload.keys() for _, _, payload, _ in engine.appended[:-1])
-    assert engine.appended[-1][2]["force_listen"] is True
-    assert handler._native_response_continuations_remaining(session, response_id) is False
-
-    await handler._maybe_continue_native_response(
-        ws.send_json,
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert len(engine.appended) == handler._NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS
-    assert ws.sent_types()[-2:] == ["response.listen", "response.done"]
-    assert session.active_response_id is None
-    assert session.active_request_id == request_id
-    assert session.turn_id == 1
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_boundary_listen_closes_response():
-    request_id = "duplex-sid-boundary-listen-e0-stage0"
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(
-        session_id="sid-boundary-listen",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    response_id = session.begin_response(turn_id=0)
-    session.bind_request(request_id)
-    native = handler._runtime_session_state(session)
-    native.continuation_owner_id = f"response:{response_id}"
-    native.continuation_units = handler._NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS
-    _install_direct_silence_scheduler(handler, session)
-    ws = TimedWebSocket()
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "llm",
-            "is_listen": True,
-            "model_listen": True,
-            "data_plane_request_id": request_id,
-            "end_of_turn": False,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert close_reason is None
-    assert emitted is True
-    assert engine.appended == []
-    assert ws.sent_types() == ["response.listen", "response.done"]
-    # The listen terminates the precreated response: clients demultiplex the
-    # decision by its id, so the payload must carry the response identity.
-    listen_payload, done_payload = ws.sent[-2], ws.sent[-1]
-    assert listen_payload["response_id"] == response_id
-    assert done_payload["response_id"] == response_id
-    assert session.active_response_id is None
-    assert session.active_request_id == request_id
-    assert session.turn_id == 1
-    assert native.continuation_owner_id is None
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_boundary_allows_next_model_turn_response():
-    request_id = "duplex-sid-boundary-next-turn-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-boundary-next-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.begin_response(turn_id=0)
-    session.bind_request(request_id)
-    native = handler._runtime_session_state(session)
-    native.continuation_owner_id = f"response:{session.active_response_id}"
-    native.continuation_units = handler._NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS
-    ws = TimedWebSocket()
-
-    await handler._maybe_continue_native_response(
-        ws.send_json,
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert session.active_response_id is None
-    assert session.turn_id == 1
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "tts",
-            "is_listen": False,
-            "data_plane_request_id": request_id,
-            "text": "next response",
-            "audio_data": "next-audio",
-            "audio_format": "pcm16",
-            "audio_duration_ms": 100,
-            "end_of_turn": False,
-            "model_turn_id": 1,
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert close_reason is None
-    assert emitted is True
-    assert ws.sent_types() == [
-        "response.listen",
-        "response.done",
-        "response.created",
-        "response.speak",
-        "response.output_audio.delta",
-    ]
-    assert session.active_response_turn_id == 1
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_boundary_does_not_close_new_epoch_response():
-    request_id = "duplex-sid-boundary-race-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-boundary-race",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    old_response_id = session.begin_response(turn_id=0)
-    session.bind_request(request_id)
-    native = handler._runtime_session_state(session)
-    native.continuation_owner_id = f"response:{old_response_id}"
-    native.continuation_units = handler._NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS
-    sent: list[dict[str, Any]] = []
-    new_response_ids: list[str] = []
-
-    async def _barge_in_on_listen(payload: dict[str, Any]) -> None:
-        sent.append(payload)
-        if payload["type"] == "response.listen":
-            session.barge_in()
-            session.bind_request("duplex-sid-boundary-race-e1-stage0")
-            new_response_ids.append(session.begin_response(turn_id=1))
-
-    await handler._maybe_continue_native_response(
-        _barge_in_on_listen,
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert [payload["type"] for payload in sent] == ["response.listen"]
-    assert len(new_response_ids) == 1
-    assert session.active_response_id == new_response_ids[0]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_pre_speak_listen_continues_same_response():
-    request_id = "duplex-sid-pre-speak-listen-e0-stage0"
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(
-        session_id="sid-pre-speak-listen",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    response_id = session.begin_response(turn_id=0)
-    session.turn_id = 1
-    session.bind_request(request_id)
-    _install_direct_silence_scheduler(handler, session)
-    ws = TimedWebSocket()
-
-    await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "llm",
-            "is_listen": True,
-            "model_listen": True,
-            "data_plane_request_id": request_id,
-            "end_of_turn": False,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-    await asyncio.sleep(0.01)
-
-    assert len(engine.appended) == 1
-    assert session.active_response_id == response_id
-    assert session.active_request_id == request_id
-    assert "response.listen" not in ws.sent_types()
-    assert "response.done" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_listen_before_response_keeps_resumable_request():
-    request_id = "duplex-sid-listen-before-response-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-listen-before-response",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.bind_request(request_id)
-    ws = TimedWebSocket()
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "llm",
-            "is_listen": True,
-            "model_listen": True,
-            "data_plane_request_id": request_id,
-            "end_of_turn": False,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert close_reason is None
-    assert emitted is True
-    assert session.active_request_id == request_id
-    assert not handler._serving_runtime_adapter.data_plane.is_terminal(request_id)
-    assert ws.sent_types().count("response.listen") == 1
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_listen_without_response_does_not_defer_commit():
-    session_id = "sid-listen-before-response-commit"
-    request_id = duplex_resource_request_id(DuplexFence(session_id), "stage0")
-    inner_output = SimpleNamespace(
-        outputs=[
-            SimpleNamespace(
-                multimodal_output={"special_token_ids": {"listen_token_id": 151705}},
-            )
-        ]
-    )
-    decision = MiniCPMO45DuplexRuntimeExtension().decide_output(
-        stage_id=0,
-        final_stage_id=1,
-        segment_finished=True,
-        segment_token_ids=(151705,),
-        segment_output_metadata={"special_token_ids": {"listen_token_id": 151705}},
-        output=inner_output,
-    )
-    assert decision is not None
-    listen_output = attach_duplex_output_decision(
-        OmniRequestOutput.from_stage_output(
-            inner_output,
-            request_id=request_id,
-            finished=True,
-            stage_id=0,
-            final_output_type=decision.final_output_type,
-        ),
-        decision,
-    )
-    append_result = {
-        "operation": "append",
-        "session_id": session_id,
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {
-                    "supported": True,
-                    "implementation_level": "model_native_duplex",
-                    "data_plane_append": True,
-                    "request_id": request_id,
-                    "response_stage_id": 1,
-                },
-            }
-        ],
-        "data_plane_outputs": [listen_output],
-    }
-    engine = FakeEngineClient(append_result=append_result)
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    listen_count = 0
-
-    def append_residual_after_listen(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        nonlocal listen_count
-        if data.get("type") == "response.listen":
-            listen_count += 1
-            if listen_count == 1:
-                ws.put(
-                    {
-                        "type": "input_audio_buffer.append",
-                        "audio": _pcm_f32_b64(3_200),
-                        "format": "pcm_f32le",
-                        "sample_rate_hz": 16_000,
-                        "duration_ms": 200,
-                        "is_speech": True,
-                    }
-                )
-                ws.put({"type": "input_audio_buffer.commit", "final": True})
-        elif data.get("type") == "input_audio_buffer.committed":
-            asyncio.get_running_loop().call_later(0.05, ws.put, {"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=append_residual_after_listen, receive_timeout_s=2)
-    create = _native_realtime_session_update(session_id)
-    create["session"]["extra_body"]["auto_response"] = True
-    ws.put(create)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16_000),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16_000,
-            "duration_ms": 1_000,
-            "is_speech": True,
-        }
-    )
-
-    await handler.handle_realtime_session(ws)
-
-    committed = [event for event in ws.sent if event.get("type") == "input_audio_buffer.committed"]
-    assert len(engine.appended) == 2
-    assert engine.appended[1][3] is True
-    assert len(committed) == 1
-    assert committed[0].get("event", {}).get("overlap_deferred") is not True
-    assert committed[0].get("event", {}).get("response_create_deferred") is not True
-    assert "response.created" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_pcm_f32_residual_commit_releases_pending_input_bytes():
-    session_id = "sid-pcm-residual-byte-accounting"
-    control_result = {
-        "operation": "append",
-        "session_id": session_id,
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [],
-    }
-    engine = FakeEngineClient(control_result=control_result)
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket(receive_timeout_s=2)
-    create = _native_realtime_session_update(session_id)
-    create["session"]["extra_body"]["auto_response"] = True
-    ws.put(create)
-    handler_task = asyncio.create_task(handler.handle_realtime_session(ws))
-
-    try:
-        for _ in range(100):
-            session = handler._registry.get(session_id)
-            if session is not None and "session.created" in ws.sent_types():
-                break
-            await asyncio.sleep(0.01)
-        else:
-            pytest.fail("native duplex session did not open")
-
-        pending_bytes_after_turn: list[int] = []
-        for turn_index in range(3):
-            ws.put(
-                {
-                    "type": "input_audio_buffer.append",
-                    "audio": _pcm_f32_b64(19_200),
-                    "format": "pcm_f32le",
-                    "sample_rate_hz": 16_000,
-                    "duration_ms": 1_200,
-                    "is_speech": True,
-                }
-            )
-            ws.put({"type": "input_audio_buffer.commit", "final": True})
-            expected_appends = (turn_index + 1) * 2
-            for _ in range(100):
-                if len(engine.appended) >= expected_appends:
-                    await asyncio.sleep(0)
-                    break
-                await asyncio.sleep(0.01)
-            else:
-                pytest.fail(f"turn {turn_index} residual append did not complete")
-            pending_bytes_after_turn.append(session.pending_input_bytes)
-    finally:
-        ws.put({"type": "session.close"})
-        await asyncio.wait_for(handler_task, timeout=2)
-
-    assert pending_bytes_after_turn == [0, 0, 0]
-    assert not any(
-        event.get("type") == "error"
-        and isinstance(event.get("error"), dict)
-        and event["error"].get("code") == "input_backpressure"
-        for event in ws.sent
-    )
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_post_speak_listen_continues_same_response():
-    request_id = "duplex-sid-post-speak-listen-e0-stage0"
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(
-        session_id="sid-post-speak-listen",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    response_id = session.begin_response(turn_id=0)
-    session.turn_id = 1
-    session.bind_request(request_id)
-    session.mark_audio_sent(100)
-    _install_direct_silence_scheduler(handler, session)
-    ws = TimedWebSocket()
-
-    await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "llm",
-            "is_listen": True,
-            "model_listen": True,
-            "data_plane_request_id": request_id,
-            "end_of_turn": False,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-    await asyncio.sleep(0.01)
-
-    assert len(engine.appended) == 1
-    assert session.active_response_id == response_id
-    assert session.active_request_id == request_id
-    assert "response.listen" not in ws.sent_types()
-    assert "response.done" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_turn_end_preserves_resumable_request():
-    request_id = "duplex-sid-turn-end-preserve-request-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-turn-end-preserve-request",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.begin_response(turn_id=0)
-    session.bind_request(request_id)
-    ws = TimedWebSocket()
-
-    await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "tts",
-            "is_listen": False,
-            "data_plane_request_id": request_id,
-            "text": "done",
-            "audio_data": "audio",
-            "audio_format": "pcm16",
-            "audio_duration_ms": 100,
-            "end_of_turn": True,
-            "model_turn_id": 0,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert session.active_response_id is None
-    assert session.active_request_id == request_id
-    assert "response.done" in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_empty_turn_end_emits_model_listen():
-    request_id = "duplex-sid-empty-turn-end-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-empty-turn-end",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.bind_request(request_id)
-    ws = TimedWebSocket()
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "tts",
-            "is_listen": False,
-            "data_plane_request_id": request_id,
-            "text": "",
-            "audio_data": "",
-            "audio_format": "pcm16",
-            "end_of_turn": True,
-            "abort_data_plane_request": True,
-            "model_turn_id": 0,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert close_reason is None
-    assert emitted is True
-    assert session.turn_id == 1
-    assert session.active_request_id == request_id
-    assert session.active_response_id is None
-    assert ws.sent_types() == ["response.listen"]
-    assert ws.sent[0]["model_listen"] is True
-    assert ws.sent[0]["reason"] == "model_turn_completed_without_output"
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_drops_late_audio_from_completed_model_turn():
-    request_id = "duplex-sid-late-completed-turn-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-late-completed-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.bind_request(request_id)
-    session.complete_model_turn(0)
-    ws = TimedWebSocket()
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "tts",
-            "is_listen": False,
-            "data_plane_request_id": request_id,
-            "text": "late duplicate",
-            "audio_data": "late-audio",
-            "audio_format": "pcm16",
-            "audio_duration_ms": 100,
-            "end_of_turn": True,
-            "model_turn_id": 0,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert close_reason is None
-    assert emitted is False
-    assert session.turn_id == 1
-    assert session.active_response_id is None
-    assert "response.created" not in ws.sent_types()
-    assert "response.done" not in ws.sent_types()
-
-
-def test_duplex_data_plane_drops_stale_epoch_audio_after_barge_in():
-    class _ChatService:
-        model_config = _ModelConfig()
-
-        def create_audio(self, audio_obj):
-            return SimpleNamespace(audio_data=f"wav-{int(audio_obj.audio_tensor.shape[0])}")
-
-    data_plane = _test_data_plane()
-    session = DuplexSession(
-        session_id="sid-auto-stale-epoch",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.turn_id = 1
-    session.epoch = 2
-    output = SimpleNamespace(
-        request_id="duplex-sid-auto-stale-epoch-stage0",
-        finished=False,
-        outputs=[SimpleNamespace(text="old epoch", multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(24000, dtype=np.float32),
-            "sr": 24000,
-            "meta.duplex_epoch": np.array([1], dtype=np.int32),
-            "meta.duplex_turn_id": np.array([1], dtype=np.int32),
-            "meta.llm_output_text_utf8": np.frombuffer("旧轮".encode(), dtype=np.uint8),
-        },
-    )
-
-    assert list(data_plane.project_output(output, context=_data_plane_context(session))) == []
-
-
-def test_duplex_data_plane_text_delta_preserves_repeated_suffix_growth():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-native-repeated-word-e0-stage0"
-
-    assert data_plane.segment_text_delta(request_id, "好的") == "好的"
-    assert data_plane.segment_text_delta(request_id, "好的好的") == "好的"
-
-
-def test_duplex_data_plane_text_delta_appends_distinct_non_prefix_segments():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-native-rewrite-e0-stage0"
-
-    deltas = [
-        data_plane.segment_text_delta(request_id, "It's Canberra."),
-        data_plane.segment_text_delta(request_id, " Next question."),
-    ]
-
-    assert deltas == ["It's Canberra.", " Next question."]
-    assert "".join(deltas) == "It's Canberra. Next question."
-
-
-def test_duplex_data_plane_close_session_removes_encoded_request_state():
-    data_plane = _test_data_plane()
-    target_request_id = duplex_resource_request_id(
-        DuplexFence("sid-to-close", incarnation=1, epoch=2),
-        "stage0",
-    )
-    other_request_id = duplex_resource_request_id(
-        DuplexFence("sid-to-keep", incarnation=1, epoch=2),
-        "stage0",
-    )
-    data_plane.begin_request(target_request_id)
-    data_plane.begin_request(other_request_id)
-
-    data_plane.close_session("sid-to-close")
-
-    assert data_plane.has_request(target_request_id) is False
-    assert data_plane.has_request(other_request_id) is True
-
-
-def test_duplex_auto_response_segment_complete_keeps_data_plane_request_open():
-    import numpy as np
-
-    class _ChatService:
-        model_config = _ModelConfig()
-
-        def create_audio(self, audio_obj):
-            return SimpleNamespace(audio_data=f"wav-{int(audio_obj.audio_tensor.shape[0])}")
-
-    data_plane = _test_data_plane()
-    request_id = "duplex-duplex-sess-stage0"
-    session = DuplexSession(
-        session_id="sid-auto-respond",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.begin_response()
-    session.mark_audio_sent(1280)
-    data_plane.slice_cumulative_audio(request_id, np.zeros(30720, dtype=np.float32))
-
-    output = SimpleNamespace(
-        request_id=request_id,
-        finished=True,
-        outputs=[SimpleNamespace(text="hello", multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(30720, dtype=np.float32),
-            "sr": 24000,
-        },
-    )
-
-    native_results = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert len(native_results) == 1
-    assert native_results[0]["is_listen"] is True
-    assert native_results[0]["reason"] == "auto_response_segment_complete"
-    assert native_results[0]["data_plane_request_id"] == request_id
-    assert "abort_data_plane_request" not in native_results[0]
-
-
-def test_duplex_auto_response_prior_playback_does_not_abort_before_current_response():
-    data_plane = _test_data_plane()
-    request_id = "duplex-duplex-sess-stage0"
-    session = DuplexSession(
-        session_id="sid-auto-respond-next-turn",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.mark_audio_sent(1280)
-    session.acknowledge_playback(played_ms=1280, committed_ms=1280)
-
-    output = SimpleNamespace(
-        request_id=request_id,
-        finished=True,
-        outputs=[SimpleNamespace(text="", multimodal_output={})],
-        multimodal_output={},
-    )
-
-    native_results = _project_data_plane(data_plane, {"data_plane_outputs": [output]}, session=session)
-
-    assert native_results == []
-
-
-def test_duplex_auto_response_text_only_flush_does_not_consume_audio_transcript():
-    import numpy as np
-
-    data_plane = _test_data_plane()
-    request_id = "duplex-duplex-sess-stage0"
-    session = DuplexSession(
-        session_id="sid-auto-respond-delayed-audio",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    text = "你好呀，有什莫问的吗？"
-
-    text_only_output = SimpleNamespace(
-        request_id=request_id,
-        finished=False,
-        outputs=[SimpleNamespace(text=text, multimodal_output={})],
-        multimodal_output={"sr": 24000},
-    )
-
-    assert _project_data_plane(data_plane, {"data_plane_outputs": [text_only_output]}, session=session) == []
-
-    audio_output = SimpleNamespace(
-        request_id=request_id,
-        finished=False,
-        outputs=[SimpleNamespace(text=text, multimodal_output={})],
-        multimodal_output={
-            "audio": np.zeros(24000, dtype=np.float32),
-            "sr": 24000,
-        },
-    )
-
-    native_results = _project_data_plane(data_plane, {"data_plane_outputs": [audio_output]}, session=session)
-
-    assert len(native_results) == 1
-    assert native_results[0]["audio_data"].startswith("wav-")
-    assert native_results[0]["text"] == text
-
-
-@pytest.mark.asyncio
-async def test_duplex_auto_response_empty_terminal_does_not_create_empty_response():
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    request_id = "duplex-sid-native-empty-terminal-e0-stage0"
-    session = DuplexSession(
-        session_id="sid-native-empty-terminal",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.mark_audio_sent(1280)
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(payload: dict[str, Any]) -> None:
-        sent.append(payload)
-
-    output = SimpleNamespace(
-        request_id=request_id,
-        finished=False,
-        outputs=[SimpleNamespace(text="hello", multimodal_output={})],
-        multimodal_output={
-            "sr": 24000,
-            "meta": {"turn_end": True, "duplex_turn_id": 0},
-        },
-    )
-
-    native_results = list(
-        handler._serving_runtime_adapter.data_plane.project(
-            {"data_plane_outputs": [output]},
-            context=_data_plane_context(session),
-        )
-    )
-    assert len(native_results) == 1
-    assert native_results[0]["end_of_turn"] is True
-    assert native_results[0]["model_turn_id"] == 0
-
-    for native_result in native_results:
-        await handler._send_one_native_duplex_event(send_json, native_result, session=session)
-
-    assert "response.created" not in [m.get("type") for m in sent]
-    assert "response.done" not in [m.get("type") for m in sent]
-    assert session.turn_id == 1
-    assert not handler._serving_runtime_adapter.data_plane.is_terminal(request_id)
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_session_close_cleans_auto_response_data_plane_state():
-    session_id = "sid-native-cleanup"
-    request_id = f"duplex-{session_id}-e0-stage0"
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    handler._serving_runtime_adapter.data_plane.slice_cumulative_audio(request_id, np.zeros(24000, dtype=np.float32))
-    handler._serving_runtime_adapter.data_plane.segment_text_delta(request_id, "hello")
-    handler._serving_runtime_adapter.data_plane.mark_terminal(request_id)
-    native = MiniCPMO45ServingSessionState()
-    handler._serving_runtime_adapter.session_states[session_id] = native
-
-    event = _native_session_create(session_id)
-    event["session"]["extra_body"]["auto_response"] = True
-    ws = TimedWebSocket()
-    ws.put(event)
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert not handler._serving_runtime_adapter.data_plane.has_request(request_id)
-    assert session_id not in handler._serving_runtime_adapter.session_states
-
-
-@pytest.mark.asyncio
-async def test_duplex_chat_audio_stream_uses_output_audio_delta_event():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    session = DuplexSession(session_id="sid-chat-audio", config=DuplexSessionConfig())
-    response_id = session.begin_response()
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(data: dict[str, Any], *, on_accepted: Callable[[], None] | None = None) -> None:
-        sent.append(data)
-        if on_accepted is not None:
-            on_accepted()
-
-    await handler._emit_chat_payload(
-        session,
-        {
-            "modality": "audio",
-            "choices": [
-                {
-                    "delta": {
-                        "content": "AAAA",
-                    },
-                    "audio_metadata": {
-                        "format": "wav",
-                        "sample_rate_hz": 22_050,
-                        "frame_count": 2205,
-                        "channels": 1,
-                    },
-                }
-            ],
-        },
-        session.epoch,
-        response_id,
-        send_json,
-    )
-
-    assert sent == [
-        {
-            "type": "response.output_audio.delta",
-            "session_id": "sid-chat-audio",
-            "response_id": response_id,
-            "epoch": 0,
-            "audio": "AAAA",
-            "format": "wav",
-            "sample_rate_hz": 22_050,
-            "channels": 1,
-            "audio_duration_ms": 100,
-        }
-    ]
-    assert session.playback.generated_ms == 100
-    assert session.playback.sent_ms == 100
-    assert session.playback.played_ms == 0
-
-
-@pytest.mark.parametrize("response_format", ["pcm", "wav"])
-def test_duplex_chat_request_uses_response_audio_format(response_format: str):
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    extra_audio = {"format": "flac", "voice": "alloy"}
-    session = DuplexSession(
-        session_id="sid-chat-audio-format",
-        config=DuplexSessionConfig(response_format=response_format, extra_body={"audio": extra_audio}),
-    )
-    session.begin_response()
-
-    request = handler._build_chat_request(session, "format-request")
-
-    assert request.audio == {"format": response_format, "voice": "alloy"}
-    assert extra_audio == {"format": "flac", "voice": "alloy"}
-
-
-def _chat_audio_completion_payload(*, frame_count: int = 2205, sample_rate_hz: int = 22_050) -> dict[str, object]:
-    return {
-        "modality": "audio",
-        "choices": [
-            {
-                "delta": {"content": "AAAA"},
-                "audio_metadata": {
-                    "format": "pcm",
-                    "sample_rate_hz": sample_rate_hz,
-                    "frame_count": frame_count,
-                    "channels": 1,
-                },
-            }
-        ],
-    }
-
-
-@pytest.mark.asyncio
-async def test_duplex_chat_full_audio_message_preserves_actual_format_and_duration():
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-chat-full-audio", config=DuplexSessionConfig(response_format="wav"))
-    response_id = session.begin_response()
-    sent: list[dict[str, object]] = []
-
-    async def send_json(data: dict[str, object], *, on_accepted: Callable[[], None] | None = None) -> None:
-        sent.append(data)
-        if on_accepted is not None:
-            on_accepted()
-
-    await handler._emit_chat_payload(
-        session,
-        {
-            "choices": [
-                {
-                    "message": {"role": "assistant", "content": "hello", "audio": {"data": "AAAA"}},
-                    "audio_metadata": {
-                        "format": "pcm",
-                        "sample_rate_hz": 22_050,
-                        "frame_count": 2205,
-                        "channels": 1,
-                    },
-                }
-            ],
-        },
-        session.epoch,
-        response_id,
-        send_json,
-    )
-
-    assert [event["type"] for event in sent] == ["response.text.delta", "response.output_audio.delta"]
-    assert sent[1]["audio"] == "AAAA"
-    assert sent[1]["format"] == "pcm"
-    assert sent[1]["sample_rate_hz"] == 22_050
-    assert sent[1]["audio_duration_ms"] == 100
-    assert session.assistant_text_buffer == ("hello",)
-    assert session.playback.sent_ms == 100
-
-
-@pytest.mark.asyncio
-async def test_duplex_chat_audio_does_not_round_each_fragment():
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-chat-sub-ms", config=DuplexSessionConfig())
-    response_id = session.begin_response()
-    sent: list[dict[str, object]] = []
-
-    async def send_json(data: dict[str, object], *, on_accepted: Callable[[], None] | None = None) -> None:
-        sent.append(data)
-        if on_accepted is not None:
-            on_accepted()
-
-    for _ in range(23):
-        await handler._emit_chat_payload(
-            session,
-            _chat_audio_completion_payload(frame_count=1),
-            session.epoch,
-            response_id,
-            send_json,
-        )
-
-    assert [event["audio_duration_ms"] for event in sent] == [0] * 22 + [1]
-    assert session.playback.generated_ms == 1
-    assert session.playback.sent_ms == 1
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("send_error", [None, RuntimeError("output unavailable")], ids=["rejected", "failed"])
-async def test_duplex_chat_unaccepted_audio_is_generated_but_not_sent(send_error: RuntimeError | None):
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-chat-unaccepted-audio", config=DuplexSessionConfig())
-    response_id = session.begin_response()
-
-    async def send_json(data: dict[str, object], *, on_accepted: Callable[[], None] | None = None) -> None:
-        if send_error is not None:
-            raise send_error
-
-    with pytest.raises(RuntimeError, match="output unavailable") if send_error is not None else nullcontext():
-        await handler._emit_chat_payload(
-            session, _chat_audio_completion_payload(), session.epoch, response_id, send_json
-        )
-
-    assert session.playback.generated_ms == 100
-    assert session.playback.sent_ms == 0
-    assert session.playback.played_ms == 0
-
-
-@pytest.mark.asyncio
-async def test_duplex_chat_late_send_completion_only_updates_old_response():
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-chat-late-audio", config=DuplexSessionConfig())
-    old_response = session.begin_response()
-    send_started = asyncio.Event()
-    finish_send = asyncio.Event()
-
-    async def delayed_send(data: dict[str, object], *, on_accepted: Callable[[], None] | None = None) -> None:
-        send_started.set()
-        await finish_send.wait()
-        assert on_accepted is not None
-        on_accepted()
-
-    emit_task = asyncio.create_task(
-        handler._emit_chat_payload(session, _chat_audio_completion_payload(), session.epoch, old_response, delayed_send)
-    )
-    try:
-        await asyncio.wait_for(send_started.wait(), timeout=1)
-        session.barge_in()
-        new_response = session.begin_response()
-        current_state = session.turn_state
-        finish_send.set()
-        await asyncio.wait_for(emit_task, timeout=1)
-
-        assert session.active_response_id == new_response
-        assert session.playback_for_response(old_response).sent_ms == 100
-        assert session.playback.generated_ms == 0
-        assert session.playback.sent_ms == 0
-        assert session.turn_state == current_state
-    finally:
-        emit_task.cancel()
-        await asyncio.gather(emit_task, return_exceptions=True)
-
-
-@pytest.mark.asyncio
-async def test_duplex_chat_missing_audio_metadata_reports_error():
-    class MissingMetadataChatService(TurnBasedFakeChatService):
-        async def create_chat_completion(self, request, raw_request=None):
-            async def generate():
-                payload = {"modality": "audio", "choices": [{"delta": {"content": "AAAA"}}]}
-                yield f"data: {json.dumps(payload)}\n\n"
-
-            return generate()
-
-    handler = OmniDuplexSessionHandler(
-        chat_service=MissingMetadataChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-chat-missing-metadata", config=DuplexSessionConfig())
-    sent: list[dict[str, object]] = []
-
-    async def send_json(data: dict[str, object], *, on_accepted: Callable[[], None] | None = None) -> None:
-        sent.append(data)
-        if on_accepted is not None:
-            on_accepted()
-
-    await handler._run_response(session, send_json)
-
-    assert [event["type"] for event in sent] == ["response.created", "error"]
-    assert sent[-1]["code"] == "response_error"
-    assert "AudioChunkMetadata" in sent[-1]["error"]
-    assert session.playback.generated_ms == 0
-    assert session.playback.sent_ms == 0
-
-
-@pytest.mark.asyncio
-async def test_duplex_chat_stage_metrics_use_latest_streaming_snapshot():
-    class SnapshotChatService(FakeChatService):
-        async def create_chat_completion(self, request, raw_request=None):
-            del raw_request
-            self.seen_request_ids.append(request.request_id)
-            snapshots = [
-                {"num_tokens_out": 1, "vllm_tpot_ms": 0.0, "vllm_itls_ms": []},
-                {"num_tokens_out": 2, "vllm_tpot_ms": 10.0, "vllm_itls_ms": [10.0]},
-                {"num_tokens_out": 3, "vllm_tpot_ms": 11.0, "vllm_itls_ms": [10.0, 12.0]},
-            ]
-
-            async def generate():
-                for index, snapshot in enumerate(snapshots):
-                    payload = {
-                        "modality": "audio",
-                        "choices": [
-                            {
-                                "delta": {"content": f"audio-{index}"},
-                                "audio_metadata": {
-                                    "format": "pcm",
-                                    "sample_rate_hz": 24_000,
-                                    "frame_count": 2400,
-                                    "channels": 1,
-                                },
-                            }
-                        ],
-                        "metrics": {"stage_metrics": {"0": snapshot}},
-                    }
-                    yield f"data: {json.dumps(payload)}\n\n"
-
-            return generate()
-
-    handler = OmniDuplexSessionHandler(
-        chat_service=SnapshotChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-chat-snapshots",
-        config=DuplexSessionConfig(instructions="speak"),
-    )
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(data: dict[str, Any], *, on_accepted: Callable[[], None] | None = None) -> None:
-        sent.append(data)
-        if on_accepted is not None:
-            on_accepted()
-
-    await handler._run_response(session, send_json)
-
-    audio_deltas = [event for event in sent if event.get("type") == "response.output_audio.delta"]
-    done = next(event for event in sent if event.get("type") == "response.done")
-    assert [event["audio_duration_ms"] for event in audio_deltas] == [100, 200, 300]
-    assert done["playback"] == {
-        "generated_ms": 300,
-        "sent_ms": 300,
-        "played_ms": 0,
-        "committed_ms": 0,
-    }
-    assert all("vllm_omni" not in event for event in audio_deltas)
-    assert done["vllm_omni"]["stage_metrics"]["0"] == {
-        "num_tokens_out": 3,
-        "vllm_tpot_ms": 11.0,
-        "vllm_itls_ms": [10.0, 12.0],
-    }
-
-
-@pytest.mark.asyncio
-async def test_duplex_chat_rejects_unknown_output_modality():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-chat-unknown", config=DuplexSessionConfig())
-    response_id = session.begin_response()
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(data: dict[str, Any]) -> None:
-        sent.append(data)
-
-    await handler._emit_chat_payload(
-        session,
-        {
-            "modality": "video",
-            "choices": [{"delta": {"content": "not-text"}}],
-        },
-        session.epoch,
-        response_id,
-        send_json,
-    )
-
-    assert sent == [
-        {
-            "type": "error",
-            "session_id": session.session_id,
-            "response_id": response_id,
-            "epoch": session.epoch,
-            "code": "unsupported_response_modality",
-            "error": "Unsupported chat response modality: video",
-        }
-    ]
-    assert session.assistant_text_buffer == ()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_model_name_does_not_auto_enable_experimental_native_duplex():
-    event = _session_create("sid-minicpmo-default-protocol")
-    event["session"]["model"] = "openbmb/MiniCPM-o-4_5"
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(event)
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    created = next(m for m in ws.sent if m.get("type") == "session.created")
-    capabilities = created["session"]["capabilities"]
-    assert capabilities["implementation_level"] == "serving_session_adapter"
-    assert capabilities["supports_input_append"] is False
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_aborts_current_chat_request_id_on_barge_in():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") == "response.created":
-            ws.put({"type": "input.cancel", "reason": "test_barge_in"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    ws.put(_session_create("sid-a"))
-    ws.put({"type": "input.text.append", "text": "hello"})
-    ws.put({"type": "input.commit"})
-
-    await handler.handle_session(ws)
-
-    assert ws.accepted
-    assert "response.created" in ws.sent_types()
-    assert "audio.cancelled" in ws.sent_types()
-    assert chat_service.seen_request_ids == ["duplex-sid-a-0-1"]
-    assert engine.aborted == ["chatcmpl-duplex-sid-a-0-1"]
-    assert engine.internal_abort_batches == [["chatcmpl-duplex-sid-a-0-1"]]
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_runtime_open_failure_is_reported_to_client():
-    engine = FakeEngineClient(fail_open=True)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-open-fail"))
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "runtime_open_failed"
-    assert engine.opened == []
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_preserves_typed_admission_error():
-    class AdmissionRejectingEngine(FakeEngineClient):
-        async def open_duplex_session_async(self, session_id: str, **kwargs):
-            del kwargs
-            raise DuplexControlRequestError(
-                {
-                    "operation": "open",
-                    "session_id": session_id,
-                    "error": {
-                        "code": "resource_exhausted",
-                        "message": "duplex session capacity exhausted",
-                        "retryable": True,
-                    },
-                    "accepted_fence": None,
-                    "lease_generation": None,
-                }
-            )
-
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(AdmissionRejectingEngine()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-admission-rejected"))
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "resource_exhausted"
-    assert ws.sent[0]["retryable"] is True
-
-
-@pytest.mark.asyncio
-async def test_duplex_cancel_reports_playback_committed_cursor():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") == "response.created":
-            ws.put({"type": "playback.ack", "played_ms": 1200, "committed_ms": 1000})
-            ws.put({"type": "input.cancel", "reason": "test_barge_in"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    ws.put(_session_create("sid-playback"))
-    ws.put({"type": "input.text.append", "text": "hello"})
-    ws.put({"type": "input.commit"})
-
-    await handler.handle_session(ws)
-
-    ack = next(m for m in ws.sent if m.get("type") == "playback.acknowledged")
-    cancelled = next(m for m in ws.sent if m.get("type") == "audio.cancelled")
-    assert ack["playback"]["played_ms"] == 1200
-    assert ack["playback"]["committed_ms"] == 1000
-    assert cancelled["committed_ms"] == 1000
-    assert cancelled["epoch"] == 1
-
-
-@pytest.mark.asyncio
-async def test_playback_ack_response_id_selects_matching_pending_history_item():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-playback-response-id",
-        config=DuplexSessionConfig(),
-    )
-    first_item_id = "item_resp-first"
-    second_item_id = "item_resp-second"
-    session.stage_pending_history_item(
-        first_item_id,
-        {"role": "assistant", "content": "first response"},
-    )
-    session.stage_pending_history_item(
-        second_item_id,
-        {"role": "assistant", "content": "second response"},
-    )
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": "resp-second",
-            "played_ms": 1000,
-            "committed_ms": 1000,
-        },
-        ws.send_json,
-    )
-
-    ack = next(message for message in ws.sent if message.get("type") == "playback.acknowledged")
-    assert ack["item_id"] == second_item_id
-    assert ack["history_committed"] is True
-    assert first_item_id in session.pending_history_item_ids
-    assert second_item_id not in session.pending_history_item_ids
-
-
-@pytest.mark.asyncio
-async def test_playback_ack_recovers_missing_response_history_registration():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-playback-missing-registration",
-        config=DuplexSessionConfig(playback_commit_policy="ack_only"),
-    )
-    response_id = session.begin_response()
-    session.append_assistant_text("response text")
-    session.mark_audio_sent(1000, text_chars=len("response text"))
-    session.end_response(commit_text=True, preserve_request=True)
-    assert not session.history_item_ids
-    assert f"item_{response_id}" in session.pending_history_item_ids
-
-    ws = TimedWebSocket()
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": response_id,
-            "item_id": f"item_{response_id}",
-            "played_ms": 1000,
-            "committed_ms": 1000,
-        },
-        ws.send_json,
-    )
-
-    ack = next(message for message in ws.sent if message.get("type") == "playback.acknowledged")
-    assert ack["history_committed"] is True
-    assert f"item_{response_id}" in session.history_item_ids
-    assert session.history[-1] == {"role": "assistant", "content": "response text"}
-
-
-@pytest.mark.asyncio
-async def test_playback_ack_rejects_response_after_followup_user_commit():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-playback-after-followup-user",
-        config=DuplexSessionConfig(playback_commit_policy="ack_only"),
-    )
-    session.append_text("user A")
-    session.commit_user_input()
-    response_id = session.begin_response()
-    session.append_assistant_text("assistant A")
-    session.mark_audio_sent(1000, text_chars=len("assistant A"))
-    session.end_response(commit_text=False, preserve_request=True)
-    session.append_text("user B")
-    session.commit_user_input()
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": response_id,
-            "item_id": f"item_{response_id}",
-            "played_ms": 1000,
-            "committed_ms": 1000,
-        },
-        ws.send_json,
-    )
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "playback_ack_too_late"
-    assert session.history == (
-        {"role": "user", "content": "user A"},
-        {"role": "user", "content": "user B"},
-    )
-
-
-@pytest.mark.asyncio
-async def test_precommit_zero_audio_ack_reserves_history_for_response_that_finishes_after_commit():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-zero-audio-checkpoint",
-        config=DuplexSessionConfig(playback_commit_policy="ack_only"),
-    )
-    session.mark_user_input_activity()
-    response_id = session.begin_response()
-    item_id = f"item_{response_id}"
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": response_id,
-            "item_id": item_id,
-            "played_ms": 0,
-            "committed_ms": 0,
-        },
-        ws.send_json,
-    )
-    session.commit_native_audio_input(transcript="later user input")
-    session.append_assistant_text("hello world")
-    session.mark_audio_sent(1000, text_chars=len("hello world"))
-    committed_message = session.end_response(commit_text=True, preserve_request=True)
-    session.register_history_item(item_id, committed_message)
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": response_id,
-            "item_id": item_id,
-            "played_ms": 1000,
-            "committed_ms": 1000,
-        },
-        ws.send_json,
-    )
-
-    assert not any(message.get("type") == "error" for message in ws.sent)
-    assert session.history == (
-        {"role": "assistant", "content": "hello world"},
-        {
-            "role": "user",
-            "content": [
-                {
-                    "type": "audio_url",
-                    "audio_url": {"url": "native-duplex:input-audio"},
-                    "transcript": "later user input",
-                }
-            ],
-            "transcript": "later user input",
-        },
-    )
-
-
-@pytest.mark.asyncio
-async def test_precommit_partial_ack_extends_history_after_response_finishes():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-partial-checkpoint",
-        config=DuplexSessionConfig(playback_commit_policy="ack_only"),
-    )
-    session.mark_user_input_activity()
-    response_id = session.begin_response()
-    item_id = f"item_{response_id}"
-    session.append_assistant_text("hello world")
-    session.mark_audio_sent(1000, text_chars=len("hello world"))
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": response_id,
-            "item_id": item_id,
-            "played_ms": 500,
-            "committed_ms": 500,
-        },
-        ws.send_json,
-    )
-    session.commit_native_audio_input(transcript="later user input")
-    committed_message = session.end_response(commit_text=True, preserve_request=True)
-    session.register_history_item(item_id, committed_message)
-
-    assert session.history[0] == {"role": "assistant", "content": "hello"}
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": response_id,
-            "item_id": item_id,
-            "played_ms": 1000,
-            "committed_ms": 1000,
-        },
-        ws.send_json,
-    )
-
-    assert not any(message.get("type") == "error" for message in ws.sent)
-    assert session.history[0] == {"role": "assistant", "content": "hello world"}
-    assert session.history[1]["role"] == "user"
-
-
-@pytest.mark.asyncio
-async def test_explicit_truncate_seals_snapshot_against_later_playback_ack():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-hard-playback-truncate",
-        config=DuplexSessionConfig(playback_commit_policy="ack_only"),
-    )
-    response_id = session.begin_response()
-    item_id = f"item_{response_id}"
-    session.append_assistant_text("hello world")
-    session.mark_audio_sent(1000, text_chars=len("hello world"))
-    session.end_response(commit_text=False, preserve_request=True)
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": response_id,
-            "item_id": item_id,
-            "played_ms": 500,
-            "committed_ms": 500,
-            "truncate": True,
-        },
-        ws.send_json,
-    )
-    assert session.history == ({"role": "assistant", "content": "hello"},)
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": response_id,
-            "item_id": item_id,
-            "played_ms": 1000,
-            "committed_ms": 1000,
-        },
-        ws.send_json,
-    )
-
-    assert not any(message.get("type") == "error" for message in ws.sent)
-    assert session.history == ({"role": "assistant", "content": "hello"},)
-
-
-@pytest.mark.asyncio
-async def test_cancel_does_not_append_old_assistant_after_followup_user():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-cancel-after-followup-user",
-        config=DuplexSessionConfig(playback_commit_policy="ack_only"),
-    )
-    session.append_text("user A")
-    session.commit_user_input()
-    session.begin_response()
-    session.append_assistant_text("assistant A")
-    session.mark_audio_sent(1000, text_chars=len("assistant A"))
-    session.acknowledge_playback(500, 500)
-    session.append_text("user B")
-    session.commit_user_input()
-    ws = TimedWebSocket()
-
-    cancelled = await handler._cancel_active_response(session, None, ws.send_json, reason="new_response")
-
-    assert cancelled is True
-    assert session.history == (
-        {"role": "user", "content": "user A"},
-        {"role": "user", "content": "user B"},
-    )
-
-
-@pytest.mark.asyncio
-async def test_playback_ack_rejects_item_from_another_response():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-playback-mismatch", config=DuplexSessionConfig())
-    first_response_id = session.begin_response()
-    session.append_assistant_text("first response")
-    session.mark_audio_sent(1000)
-    session.end_response(commit_text=False, preserve_request=True)
-    session.register_history_item(f"item_{first_response_id}", None)
-    second_response_id = session.begin_response()
-    session.mark_audio_sent(1000)
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": second_response_id,
-            "item_id": f"item_{first_response_id}",
-            "played_ms": 500,
-            "committed_ms": 500,
-        },
-        ws.send_json,
-    )
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "playback_item_mismatch"
-    assert session.active_response_id == second_response_id
-    assert session.playback.as_dict() == {
-        "generated_ms": 1000,
-        "sent_ms": 1000,
-        "played_ms": 0,
-        "committed_ms": 0,
-    }
-
-
-@pytest.mark.asyncio
-async def test_playback_ack_rejects_user_history_item():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-playback-user-item", config=DuplexSessionConfig())
-    user_message = {"role": "user", "content": "user input"}
-    session.append_history_message(user_message)
-    session.register_history_item("item_user", user_message)
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": "user",
-            "item_id": "item_user",
-            "played_ms": 500,
-            "committed_ms": 500,
-        },
-        ws.send_json,
-    )
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "playback_item_not_found"
-    assert session.history == ({"role": "user", "content": "user input"},)
-
-
-@pytest.mark.asyncio
-async def test_late_playback_ack_recovers_response_local_history_after_next_response_begins():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(session_id="sid-playback-response-local", config=DuplexSessionConfig())
-    first_response_id = session.begin_response()
-    session.append_assistant_text("first response")
-    session.mark_audio_sent(1000, text_chars=len("first response"))
-    session.end_response(commit_text=False, preserve_request=True)
-    second_response_id = session.begin_response()
-    session.mark_audio_sent(2000, text_chars=len("second response"))
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": first_response_id,
-            "item_id": f"item_{first_response_id}",
-            "played_ms": 1000,
-            "committed_ms": 1000,
-        },
-        ws.send_json,
-    )
-
-    ack = next(message for message in ws.sent if message.get("type") == "playback.acknowledged")
-    assert ack["history_committed"] is True
-    assert session.history[-1] == {"role": "assistant", "content": "first response"}
-    assert session.active_response_id == second_response_id
-    assert session.playback.as_dict() == {
-        "generated_ms": 2000,
-        "sent_ms": 2000,
-        "played_ms": 0,
-        "committed_ms": 0,
-    }
-
-
-@pytest.mark.asyncio
-async def test_late_playback_ack_does_not_advance_new_response_cursor():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-late-playback-ack",
-        config=DuplexSessionConfig(),
-    )
-    first_response_id = session.begin_response()
-    session.append_assistant_text("first response")
-    session.mark_audio_sent(11480, text_chars=len("first response"))
-    session.end_response(commit_text=False, preserve_request=True)
-    session.register_history_item(f"item_{first_response_id}", None)
-
-    second_response_id = session.begin_response()
-    session.mark_audio_sent(2200, text_chars=len("second response"))
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": first_response_id,
-            "item_id": f"item_{first_response_id}",
-            "played_ms": 11480,
-            "committed_ms": 11480,
-        },
-        ws.send_json,
-    )
-
-    assert session.active_response_id == second_response_id
-    assert session.playback.as_dict() == {
-        "generated_ms": 2200,
-        "sent_ms": 2200,
-        "played_ms": 0,
-        "committed_ms": 0,
-    }
-    ack = next(message for message in ws.sent if message.get("type") == "playback.acknowledged")
-    assert ack["playback"] == {
-        "generated_ms": 11480,
-        "sent_ms": 11480,
-        "played_ms": 11480,
-        "committed_ms": 11480,
-    }
-    assert first_response_id not in session.response_playbacks
-    assert session.response_playbacks[second_response_id] == session.playback
-
-
-@pytest.mark.asyncio
-async def test_late_playback_ack_truncates_history_with_matching_response_cursor():
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-late-playback-history",
-        config=DuplexSessionConfig(),
-    )
-    first_response_id = session.begin_response()
-    session.append_assistant_text("abcdefghij")
-    session.mark_audio_sent(1000)
-    session.end_response(commit_text=False, preserve_request=True)
-    session.register_history_item(f"item_{first_response_id}", None)
-
-    session.begin_response()
-    session.mark_audio_sent(10000)
-    ws = TimedWebSocket()
-
-    await handler._handle_playback_ack(
-        session,
-        {
-            "type": "playback.ack",
-            "response_id": first_response_id,
-            "item_id": f"item_{first_response_id}",
-            "played_ms": 500,
-            "committed_ms": 500,
-        },
-        ws.send_json,
-    )
-
-    assert session.history[-1] == {"role": "assistant", "content": "abcde"}
-    assert first_response_id in session.response_playbacks
-
-
-@pytest.mark.asyncio
-async def test_cancel_active_response_commits_only_played_assistant_history():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    session = DuplexSession(
-        session_id="sid-playback-partial",
-        config=DuplexSessionConfig(playback_commit_policy=DuplexPlaybackCommitPolicy.COMMIT_ALL_ON_DONE.value),
-    )
-    response_id = session.begin_response()
-    session.append_assistant_text("hello world")
-    session.mark_audio_sent(1000, text_chars=len("hello world"))
-    session.acknowledge_playback(played_ms=500, committed_ms=500)
-
-    cancelled = await handler._cancel_active_response(session, None, ws.send_json, reason="barge_in")
-
-    assert cancelled is True
-    assert session.epoch == 1
-    assert session.history == ({"role": "assistant", "content": "hello"},)
-    assert session.history_item_ids[f"item_{response_id}"] == session.history[0]
-    event = next(m for m in ws.sent if m.get("type") == "audio.cancelled")
-    assert event["committed_ms"] == 500
-
-
-@pytest.mark.asyncio
-async def test_cancel_active_response_keeps_truncated_history_in_serving():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    session = DuplexSession(
-        session_id="sid-playback-runtime-rebuild",
-        config=DuplexSessionConfig(playback_commit_policy=DuplexPlaybackCommitPolicy.COMMIT_ALL_ON_DONE.value),
-    )
-    response_id = session.begin_response()
-    session.append_assistant_text("hello world")
-    session.mark_audio_sent(1000, text_chars=len("hello world"))
-    session.acknowledge_playback(played_ms=500, committed_ms=500)
-
-    cancelled = await handler._cancel_active_response(
-        session,
-        None,
-        ws.send_json,
-        reason="barge_in",
-    )
-
-    assert cancelled is True
-    assert session.history == ({"role": "assistant", "content": "hello"},)
-    assert session.history_item_ids[f"item_{response_id}"] == session.history[0]
-    assert engine.signals == []
-    assert "error" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_cancel_active_native_data_plane_request_aborts_stage_request_id():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    session = DuplexSession(session_id="sid-native-abort", config=DuplexSessionConfig())
-    session.bind_request("duplex-sid-native-abort-e0-stage0-s1")
-
-    cancelled = await handler._cancel_active_response(session, None, ws.send_json, reason="barge_in")
-
-    assert cancelled is True
-    assert engine.aborted == ["duplex-sid-native-abort-e0-stage0-s1"]
-    assert engine.internal_abort_batches == [["duplex-sid-native-abort-e0-stage0-s1"]]
-    assert "audio.cancelled" in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_cancel_chat_fallback_response_aborts_request_and_task():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(chat_service=TurnBasedFakeChatService(engine))
-    session = DuplexSession("sid-chat-cancel", DuplexSessionConfig())
-    response_id = session.begin_response()
-    session.bind_request("chatcmpl-cancel")
-    ws = TimedWebSocket()
-    task = asyncio.create_task(asyncio.sleep(60))
-    try:
-        cancelled = await handler._cancel_active_response(session, task, ws.send_json, reason="response.cancel")
-
-        assert cancelled is True
-        assert task.cancelled()
-        assert engine.internal_abort_batches == [["chatcmpl-cancel"]]
-        assert "error" not in ws.sent_types()
-        (event,) = [event for event in ws.sent if event["type"] == "audio.cancelled"]
-        assert event["response_id"] == response_id
-        assert event["reason"] == "response.cancel"
-    finally:
-        task.cancel()
-        await asyncio.gather(task, return_exceptions=True)
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_explicit_close_closes_runtime_once_with_client_reason():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-close"))
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["session.created", "session.closed"]
-    assert engine.closed == [("sid-close", "session_close")]
-
-
-@pytest.mark.asyncio
-async def test_realtime_disconnect_detaches_resumable_session_without_runtime_close():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket(receive_timeout_s=0.01)
-    ws.put(_native_realtime_session_update("sid-resumable-disconnect"))
-
-    await handler.handle_realtime_session(ws)
-
-    created = next(message for message in ws.sent if message.get("type") == "session.created")
-    assert created["session"]["id"] == "sid-resumable-disconnect"
-    assert isinstance(created["resume_token"], str)
-    assert created["resume_token"]
-    assert created["attachment_generation"] == 1
-    assert engine.closed == []
-    assert engine.touched == [
-        ("sid-resumable-disconnect", DuplexLeaseActivity.DETACH),
-    ]
-    assert handler._registry.get("sid-resumable-disconnect") is not None
-    assert "sid-resumable-disconnect" in handler._serving_runtime_adapter.session_states
-
-
-@pytest.mark.asyncio
-async def test_realtime_initial_resume_token_delivery_failure_closes_unrecoverable_session():
-    class FailingCreatedWebSocket(TimedWebSocket):
-        async def send_json(self, data: dict[str, Any]):
-            if data.get("type") == "session.created":
-                raise WebSocketDisconnect(code=1006)
-            await super().send_json(data)
-
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = FailingCreatedWebSocket(receive_timeout_s=0.01)
-    ws.put(_native_realtime_session_update("sid-created-delivery-failure"))
-
-    await handler.handle_realtime_session(ws)
-
-    assert engine.closed == [("sid-created-delivery-failure", "disconnect")]
-    assert handler._registry.get("sid-created-delivery-failure") is None
-    assert "sid-created-delivery-failure" not in handler._serving_runtime_adapter.session_states
-
-
-@pytest.mark.asyncio
-async def test_realtime_send_after_created_disconnect_preserves_resumable_session():
-    class ClosedAfterCreatedWebSocket(TimedWebSocket):
-        def __init__(self) -> None:
-            super().__init__(receive_timeout_s=0.01)
-            self.transport_closed = False
-
-        async def send_json(self, data: dict[str, Any]):
-            if self.transport_closed:
-                raise RuntimeError(
-                    "Unexpected ASGI message 'websocket.send', "
-                    "after sending 'websocket.close' or response already completed."
-                )
-            await super().send_json(data)
-            if data.get("type") == "session.created":
-                self.transport_closed = True
-
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = ClosedAfterCreatedWebSocket()
-    ws.put(_native_realtime_session_update("sid-created-then-disconnected"))
-
-    await handler.handle_realtime_session(ws)
-
-    assert engine.closed == []
-    assert engine.touched == [
-        ("sid-created-then-disconnected", DuplexLeaseActivity.DETACH),
-    ]
-    assert handler._registry.get("sid-created-then-disconnected") is not None
-    assert "sid-created-then-disconnected" in handler._serving_runtime_adapter.session_states
-
-
-@pytest.mark.asyncio
-async def test_realtime_resume_rotates_token_replays_and_preserves_runtime_identity():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    first = TimedWebSocket(receive_timeout_s=0.01)
-    first.put(_native_realtime_session_update("sid-realtime-resume"))
-    first.put({"type": "session.heartbeat"})
-
-    await handler.handle_realtime_session(first)
-
-    created = next(message for message in first.sent if message.get("type") == "session.created")
-    heartbeat = next(message for message in first.sent if message.get("type") == "session.heartbeat_ack")
-    token = created["resume_token"]
-    incarnation = created["incarnation"]
-    second = TimedWebSocket(receive_timeout_s=0.1)
-    second.query_params = {
-        "model": "openbmb/MiniCPM-o-4_5",
-        "native_duplex": "1",
-        "resume": "1",
-    }
-    second.put(
-        {
-            "type": "session.resume",
-            "session_id": "sid-realtime-resume",
-            "incarnation": incarnation,
-            "resume_token": token,
-            "last_received_server_event_seq": heartbeat["server_event_seq"] - 1,
-        }
-    )
-    second.put({"type": "session.close"})
-
-    await handler.handle_realtime_session(second)
-
-    resumed = next(message for message in second.sent if message.get("type") == "session.resumed")
-    replayed = [
-        message
-        for message in second.sent
-        if message.get("type") == "session.heartbeat_ack"
-        and message.get("server_event_seq") == heartbeat["server_event_seq"]
-    ]
-    assert resumed["session_id"] == "sid-realtime-resume"
-    assert resumed["incarnation"] == incarnation
-    assert resumed["attachment_generation"] == 2
-    assert resumed["resume_token"] != token
-    assert replayed == [heartbeat]
-    assert engine.opened == ["sid-realtime-resume"]
-    assert engine.resumed == [("sid-realtime-resume", 0)]
-    assert engine.resume_fences[0] == engine.opened_fences[0]
-    assert engine.closed == [("sid-realtime-resume", "session_close")]
-
-
-@pytest.mark.asyncio
-async def test_realtime_resume_preserves_append_tail_order_across_connections():
-    class SlowFirstAppendEngine(FakeEngineClient):
-        def __init__(self) -> None:
-            super().__init__()
-            self.first_append_started = asyncio.Event()
-            self.second_append_started = asyncio.Event()
-            self.release_first_append = asyncio.Event()
-            self.append_start_order: list[int] = []
-
-        async def append_duplex_input_async(self, session_id: str, **kwargs):
-            call_index = len(self.append_start_order) + 1
-            self.append_start_order.append(call_index)
-            if call_index == 1:
-                self.first_append_started.set()
-                await self.release_first_append.wait()
-            else:
-                self.second_append_started.set()
-            kwargs.pop("expected_epoch", None)
-            return await super().append_duplex_input_async(session_id, **kwargs)
-
-    engine = SlowFirstAppendEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    first = TimedWebSocket(receive_timeout_s=1.0)
-    session_update = _native_realtime_session_update("sid-resume-append-order")
-    session_update["session"]["extra_body"]["auto_response"] = True
-    first.put(session_update)
-    first_task = asyncio.create_task(handler.handle_realtime_session(first))
-    for _ in range(100):
-        created = next((message for message in first.sent if message.get("type") == "session.created"), None)
-        if created is not None:
-            break
-        await asyncio.sleep(0.01)
-    else:
-        pytest.fail("resumable session did not open")
-    assert created is not None
-    session = handler._registry.get("sid-resume-append-order")
-    assert session is not None
-    native_state = handler._runtime_session_state(session)
-    first_scheduler = native_state.silence_continuation_scheduler
-    assert first_scheduler is not None
-    first.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(16000),
-            "sample_rate_hz": 16000,
-            "is_speech": True,
-        }
-    )
-    await asyncio.wait_for(engine.first_append_started.wait(), timeout=1)
-    await first.close(code=1006)
-    await asyncio.wait_for(first_task, timeout=1)
-
-    second = TimedWebSocket(receive_timeout_s=0.5)
-    second.query_params = {
-        "model": "openbmb/MiniCPM-o-4_5",
-        "native_duplex": "1",
-        "resume": "1",
-    }
-    second.put(
-        {
-            "type": "session.resume",
-            "session_id": "sid-resume-append-order",
-            "incarnation": created["incarnation"],
-            "resume_token": created["resume_token"],
-            "last_received_server_event_seq": created.get("server_event_seq", 0),
-        }
-    )
-    second_task = asyncio.create_task(handler.handle_realtime_session(second))
-    for _ in range(100):
-        if "session.resumed" in second.sent_types():
-            break
-        await asyncio.sleep(0.01)
-    else:
-        pytest.fail("session did not resume")
-    assert native_state.silence_continuation_scheduler is not first_scheduler
-    second.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(16000),
-            "sample_rate_hz": 16000,
-            "is_speech": True,
-        }
-    )
-    try:
-        await asyncio.sleep(0.05)
-        assert not engine.second_append_started.is_set()
-    finally:
-        engine.release_first_append.set()
-
-    await asyncio.wait_for(engine.second_append_started.wait(), timeout=1)
-    second.put({"type": "session.close"})
-    await asyncio.wait_for(second_task, timeout=2)
-    assert engine.append_start_order == [1, 2]
-
-
-@pytest.mark.asyncio
-async def test_realtime_takeover_ignores_late_detach_from_replaced_attachment():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    first = TimedWebSocket(receive_timeout_s=1.0)
-    first.put(_native_realtime_session_update("sid-takeover"))
-    first_task = asyncio.create_task(handler.handle_realtime_session(first))
-    for _ in range(100):
-        created = next((message for message in first.sent if message.get("type") == "session.created"), None)
-        if created is not None:
-            break
-        await asyncio.sleep(0.001)
-    else:
-        raise AssertionError("first attachment did not create the session")
-
-    second = TimedWebSocket(receive_timeout_s=0.03)
-    second.put(
-        {
-            "type": "session.resume",
-            "session_id": "sid-takeover",
-            "incarnation": created["incarnation"],
-            "resume_token": created["resume_token"],
-            "last_received_server_event_seq": 0,
-        }
-    )
-    await handler.handle_realtime_session(second)
-    await first_task
-
-    detach_touches = [item for item in engine.touched if item[1] is DuplexLeaseActivity.DETACH]
-    assert detach_touches == [("sid-takeover", DuplexLeaseActivity.DETACH)]
-    assert "session.replaced" in first.sent_types()
-    assert engine.resumed == [("sid-takeover", 0)]
-    assert engine.closed == []
-
-
-@pytest.mark.asyncio
-async def test_realtime_takeover_does_not_clear_new_attachment_pending_turns():
-    class DelayedReplacementCloseWebSocket(TimedWebSocket):
-        def __init__(self) -> None:
-            super().__init__(receive_timeout_s=1.0)
-            self.replacement_close_started = asyncio.Event()
-            self.release_replacement_close = asyncio.Event()
-
-        async def close(self, code: int = 1000, reason: str | None = None) -> None:
-            if not self.replacement_close_started.is_set():
-                self.replacement_close_started.set()
-                await self.release_replacement_close.wait()
-            await super().close(code=code, reason=reason)
-
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    first = DelayedReplacementCloseWebSocket()
-    first.put(_native_realtime_session_update("sid-takeover-pending-turn"))
-    first_task = asyncio.create_task(handler.handle_realtime_session(first))
-    for _ in range(100):
-        created = next((message for message in first.sent if message.get("type") == "session.created"), None)
-        if created is not None:
-            break
-        await asyncio.sleep(0.001)
-    else:
-        pytest.fail("first attachment did not create the session")
-    assert created is not None
-
-    second = TimedWebSocket(receive_timeout_s=1.0)
-    second.put(
-        {
-            "type": "session.resume",
-            "session_id": "sid-takeover-pending-turn",
-            "incarnation": created["incarnation"],
-            "resume_token": created["resume_token"],
-            "last_received_server_event_seq": 0,
-        }
-    )
-    second_task = asyncio.create_task(handler.handle_realtime_session(second))
-    await asyncio.wait_for(first.replacement_close_started.wait(), timeout=1)
-
-    session = handler._registry.get("sid-takeover-pending-turn")
-    assert session is not None
-    assert session.reserve_pending_turn(limit=2)
-    first.release_replacement_close.set()
-    await asyncio.wait_for(first_task, timeout=1)
-
-    assert session.pending_input_turns == 1
-    session.release_pending_turn()
-    second.put({"type": "session.close"})
-    await asyncio.wait_for(second_task, timeout=2)
-
-
-@pytest.mark.asyncio
-async def test_realtime_takeover_drops_input_queued_by_replaced_attachment():
-    class DelayedReplacementCloseWebSocket(TimedWebSocket):
-        def __init__(self) -> None:
-            super().__init__(receive_timeout_s=1.0)
-            self.replacement_close_started = asyncio.Event()
-            self.release_replacement_close = asyncio.Event()
-            self.stale_heartbeat_read = asyncio.Event()
-
-        async def receive_text(self) -> str:
-            payload = await super().receive_text()
-            if json.loads(payload).get("type") == "session.heartbeat":
-                self.stale_heartbeat_read.set()
-            return payload
-
-        async def close(self, code: int = 1000, reason: str | None = None) -> None:
-            if not self.replacement_close_started.is_set():
-                self.replacement_close_started.set()
-                await self.release_replacement_close.wait()
-            await super().close(code=code, reason=reason)
-
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    first = DelayedReplacementCloseWebSocket()
-    first.put(_native_realtime_session_update("sid-takeover-stale-input"))
-    first_task = asyncio.create_task(handler.handle_realtime_session(first))
-    for _ in range(100):
-        created = next((message for message in first.sent if message.get("type") == "session.created"), None)
-        if created is not None:
-            break
-        await asyncio.sleep(0.001)
-    else:
-        pytest.fail("first attachment did not create the session")
-    assert created is not None
-
-    second = TimedWebSocket(receive_timeout_s=1.0)
-    second.put(
-        {
-            "type": "session.resume",
-            "session_id": "sid-takeover-stale-input",
-            "incarnation": created["incarnation"],
-            "resume_token": created["resume_token"],
-            "last_received_server_event_seq": 0,
-        }
-    )
-    second_task = asyncio.create_task(handler.handle_realtime_session(second))
-    await asyncio.wait_for(first.replacement_close_started.wait(), timeout=1)
-
-    first.put({"type": "session.heartbeat"})
-    await asyncio.wait_for(first.stale_heartbeat_read.wait(), timeout=1)
-    first.release_replacement_close.set()
-    await asyncio.wait_for(first_task, timeout=1)
-
-    second.put({"type": "session.close"})
-    await asyncio.wait_for(second_task, timeout=2)
-    assert all(activity is not DuplexLeaseActivity.HEARTBEAT for _, activity in engine.touched)
-    assert "session.heartbeat_ack" not in second.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_realtime_resume_rejects_invalid_token_before_engine_control():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    first = TimedWebSocket(receive_timeout_s=0.01)
-    first.put(_native_realtime_session_update("sid-invalid-resume"))
-    await handler.handle_realtime_session(first)
-
-    created = next(message for message in first.sent if message.get("type") == "session.created")
-    second = TimedWebSocket(receive_timeout_s=0.01)
-    second.put(
-        {
-            "type": "session.resume",
-            "session_id": "sid-invalid-resume",
-            "incarnation": created["incarnation"],
-            "resume_token": "invalid-token",
-            "last_received_server_event_seq": 0,
-        }
-    )
-
-    await handler.handle_realtime_session(second)
-
-    error = next(message for message in second.sent if message.get("type") == "error")
-    assert error["error"]["code"] == "invalid_resume_token"
-    assert engine.resumed == []
-    assert engine.closed == []
-
-
-@pytest.mark.asyncio
-async def test_realtime_resume_recovers_when_rotated_token_delivery_is_lost():
-    class FailingResumeWebSocket(TimedWebSocket):
-        async def send_json(self, data: dict[str, Any]):
-            if data.get("type") == "session.resumed":
-                raise RuntimeError("resume transport disappeared")
-            await super().send_json(data)
-
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    first = TimedWebSocket(receive_timeout_s=0.01)
-    first.put(_native_realtime_session_update("sid-token-delivery"))
-    await handler.handle_realtime_session(first)
-    created = next(message for message in first.sent if message.get("type") == "session.created")
-    resume_event = {
-        "type": "session.resume",
-        "session_id": "sid-token-delivery",
-        "incarnation": created["incarnation"],
-        "resume_token": created["resume_token"],
-        "last_received_server_event_seq": 0,
-    }
-
-    failed_transport = FailingResumeWebSocket(receive_timeout_s=0.01)
-    failed_transport.put(resume_event)
-    await handler.handle_realtime_session(failed_transport)
-
-    recovered_transport = TimedWebSocket(receive_timeout_s=0.1)
-    recovered_transport.put(resume_event)
-    recovered_transport.put({"type": "session.close"})
-    await handler.handle_realtime_session(recovered_transport)
-
-    assert "session.resumed" in recovered_transport.sent_types()
-    assert engine.resumed == [
-        ("sid-token-delivery", 0),
-        ("sid-token-delivery", 1),
-    ]
-    assert engine.closed == [("sid-token-delivery", "session_close")]
-
-
-@pytest.mark.asyncio
-async def test_realtime_disconnect_grace_cancels_only_orphan_response():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-        duplex_session_config=DuplexSessionRuntimeConfig(disconnect_grace_s=0.02),
-    )
-    ws = TimedWebSocket(receive_timeout_s=0.01)
-    ws.put(_native_realtime_session_update("sid-grace-response"))
-
-    await handler.handle_realtime_session(ws)
-    session = handler._registry.get("sid-grace-response")
-    assert session is not None
-    session.begin_response()
-    session.bind_request("orphan-request")
-    orphan_task = asyncio.create_task(asyncio.sleep(10))
-    handler._session_tasks[session.session_id].active_response_task = orphan_task
-    assert engine.closed == []
-
-    await asyncio.sleep(0.05)
-
-    assert engine.closed == []
-    assert engine.aborted == ["orphan-request"]
-    assert orphan_task.cancelled()
-    assert session.active_response_id is None
-    assert "sid-grace-response" in handler._serving_runtime_adapter.session_states
-
-
-@pytest.mark.asyncio
-async def test_realtime_heartbeat_control_failure_is_non_terminal():
-    engine = FakeEngineClient(fail_touch=True)
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket(receive_timeout_s=0.1)
-    ws.put(_native_realtime_session_update("sid-heartbeat-failure"))
-    ws.put({"type": "session.heartbeat"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_realtime_session(ws)
-
-    error = next(message for message in ws.sent if message.get("type") == "error")
-    assert error["error"]["code"] == "runtime_touch_failed"
-    assert engine.closed == [("sid-heartbeat-failure", "session_close")]
-
-
-@pytest.mark.asyncio
-async def test_realtime_idle_ttl_lifecycle_removes_detached_serving_projection():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket(receive_timeout_s=0.01)
-    ws.put(_native_realtime_session_update("sid-idle-expired"))
-
-    await handler.handle_realtime_session(ws)
-    fence = engine.opened_fences[0]
-    assert fence is not None
-    await engine.duplex_lifecycle_events.put(
-        DuplexSessionLifecycleMessage(
-            fence=fence,
-            session_id="sid-idle-expired",
-            event="expired",
-            reason="idle_ttl_expired",
-            lease_generation=1,
-            submitted_request_ids=[],
-            reserved_request_ids=[],
-        )
-    )
-    await asyncio.sleep(0.05)
-
-    assert handler._registry.get("sid-idle-expired") is None
-    assert "sid-idle-expired" not in handler._serving_runtime_adapter.session_states
-    assert "sid-idle-expired" not in handler._session_tasks
-    assert engine.closed == []
-
-
-@pytest.mark.asyncio
-async def test_realtime_resume_reports_resync_required_after_journal_ttl_gap():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-        duplex_session_config=DuplexSessionRuntimeConfig(resume_replay_ttl_s=0.01),
-    )
-    first = TimedWebSocket(receive_timeout_s=0.01)
-    first.put(_native_realtime_session_update("sid-journal-gap"))
-    first.put({"type": "session.heartbeat"})
-    await handler.handle_realtime_session(first)
-    created = next(message for message in first.sent if message.get("type") == "session.created")
-    await asyncio.sleep(0.02)
-
-    second = TimedWebSocket(receive_timeout_s=0.01)
-    second.put(
-        {
-            "type": "session.resume",
-            "session_id": "sid-journal-gap",
-            "incarnation": created["incarnation"],
-            "resume_token": created["resume_token"],
-            "last_received_server_event_seq": 0,
-        }
-    )
-    await handler.handle_realtime_session(second)
-
-    assert "session.resync_required" in second.sent_types()
-    assert engine.resumed == []
-    assert engine.closed == []
-
-
-@pytest.mark.asyncio
-async def test_realtime_journal_overflow_degrades_to_live_resync_without_closing_runtime():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-        duplex_session_config=DuplexSessionRuntimeConfig(resume_replay_max_bytes_per_session=128),
-    )
-    ws = TimedWebSocket(receive_timeout_s=0.01)
-    ws.put(_native_realtime_session_update("sid-journal-overflow"))
-
-    await handler.handle_realtime_session(ws)
-
-    assert "session.created" in ws.sent_types()
-    assert "session.resync_required" in ws.sent_types()
-    assert engine.closed == []
-    assert handler._registry.get("sid-journal-overflow") is not None
-
-
-@pytest.mark.asyncio
-async def test_realtime_input_backpressure_is_per_session_and_rejects_before_mutation():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-        duplex_session_config=DuplexSessionRuntimeConfig(
-            max_pending_input_bytes_per_session=100,
-        ),
-    )
-    first = TimedWebSocket(receive_timeout_s=0.1)
-    first.put(_native_realtime_session_update("sid-backpressure-a"))
-    for _ in range(2):
-        first.put(
-            {
-                "type": "input_audio_buffer.append",
-                "audio": _pcm16_b64(20),
-                "format": "pcm16",
-                "sample_rate_hz": 16000,
-            }
-        )
-    first.put({"type": "session.close"})
-
-    await handler.handle_realtime_session(first)
-
-    backpressure = [
-        event
-        for event in first.sent
-        if event.get("type") == "error"
-        and isinstance(event.get("error"), dict)
-        and event["error"].get("code") == "input_backpressure"
-    ]
-    assert len(backpressure) == 1
-
-    second = TimedWebSocket(receive_timeout_s=0.1)
-    second.put(_native_realtime_session_update("sid-backpressure-b"))
-    second.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(20),
-            "format": "pcm16",
-            "sample_rate_hz": 16000,
-        }
-    )
-    second.put({"type": "session.close"})
-
-    await handler.handle_realtime_session(second)
-
-    assert not any(
-        event.get("type") == "error"
-        and isinstance(event.get("error"), dict)
-        and event["error"].get("code") == "input_backpressure"
-        for event in second.sent
-    )
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_idle_timeout_close_does_not_emit_runtime_control():
-    control_result = {
-        "operation": "close",
-        "session_id": "sid-disconnect",
-        "ok": True,
-        "unsupported_count": 1,
-        "error_count": 0,
-        "stage_results": [{"stage_id": 0, "replica_id": 0, "result": {"supported": False}}],
-    }
-    engine = FakeEngineClient(append_result=control_result)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=0.1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-disconnect"))
-
-    await handler.handle_session(ws)
-
-    assert engine.closed == [("sid-disconnect", "timeout")]
-
-
-@pytest.mark.asyncio
-async def test_idle_output_audio_clear_does_not_advance_runtime_fence():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_session_create("sid-idle-output-clear"))
-    ws.put({"type": "output_audio_buffer.clear"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    cancelled = next(event for event in ws.sent if event.get("type") == "audio.cancelled")
-    assert cancelled["cancelled_epoch"] == cancelled["epoch"] == 0
-    assert engine.signals == []
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_runtime_close_failure_is_reported_without_closed_ack():
-    engine = FakeEngineClient(fail_close=True)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-close-fail"))
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["session.created", "error"]
-    assert ws.sent[-1]["code"] == "runtime_close_failed"
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_control_close_failure_is_reported_without_closed_ack():
-    control_result = {
-        "operation": "close",
-        "session_id": "sid-control-close-fail",
-        "ok": False,
-        "unsupported_count": 0,
-        "error_count": 1,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {"supported": False, "error": "stage close failed"},
-            }
-        ],
-    }
-    engine = FakeEngineClient(close_result=control_result)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-control-close-fail"))
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["session.created", "error"]
-    assert ws.sent[-1]["code"] == "runtime_close_failed"
-    assert ws.sent[-1]["runtime_control"]["error_count"] == 1
-
-
-@pytest.mark.asyncio
-async def test_duplex_cancel_without_active_response_clears_pending_input_and_acks():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_session_create("sid-pending-cancel"))
-    ws.put({"type": "input.text.append", "text": "hello"})
-    ws.put({"type": "input.cancel", "reason": "user_cancel"})
-    ws.put({"type": "input.commit"})
-
-    await handler.handle_session(ws)
-
-    cancelled = next(m for m in ws.sent if m.get("type") == "input.cancelled")
-    assert cancelled["cancelled"] == {"text_chunks": 1, "audio_chunks": 0}
-    assert cancelled["epoch"] == 1
-    assert chat_service.seen_request_ids == []
-    assert "response.created" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_turn_signal_input_cancel_uses_epoch_fence_transition():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-turn-signal-cancel"))
-    ws.put({"type": "input.text.append", "text": "discard me"})
-    ws.put({"type": "turn.signal", "event": "input.cancel"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert engine.signal_fences[-1] == DuplexFence("sid-turn-signal-cancel")
-    assert engine.signal_next_fences[-1] == DuplexFence("sid-turn-signal-cancel", epoch=1)
-    assert any(message.get("type") == "input.cancelled" for message in ws.sent)
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_local_turn_signal_does_not_round_trip_runtime():
-    engine = FakeEngineClient(fail_signal=True)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_session_create("sid-signal-fail"))
-    ws.put({"type": "turn.signal", "event": "user_started"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    turn_event = next(m for m in ws.sent if m.get("type") == "turn.event")
-    assert turn_event["event"] == "user_started"
-    assert not engine.signals
-    assert "runtime_signal_failed" not in {m.get("code") for m in ws.sent}
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_append_without_format_defaults_to_pcm16():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-default-pcm16"))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(16000),
-            "sample_rate_hz": 16000,
-            "is_speech": True,
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert len(engine.appended) == 1
-    _, mode, payload, final = engine.appended[0]
-    assert mode == "append_audio_chunk"
-    assert final is False
-    assert isinstance(payload, dict)
-    assert payload["format"] == "pcm_f32le"
-    assert payload["sample_rate_hz"] == 16000
-    samples = np.frombuffer(base64.b64decode(payload["audio"]), dtype="<f4")
-    assert samples.shape == (16000,)
-    assert samples[:4].tolist() == pytest.approx([1000 / 32768.0] * 4)
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_rejects_invalid_sample_rate_without_append():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-invalid-rate"))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(1),
-            "sample_rate_hz": 16_000.5,
-            "is_speech": True,
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert engine.appended == []
-    error = next(event for event in ws.sent if event.get("type") == "error")
-    assert error["code"] == "bad_event"
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("sample_rate_hz", INVALID_VALIDATED_SAMPLE_RATES)
-async def test_turn_based_server_vad_rejects_invalid_direct_sample_rate_without_closing_session(
-    sample_rate_hz: object,
-):
-    backend = FakeServerVADBackend([0.9])
-    handler = OmniDuplexSessionHandler(
-        chat_service=TurnBasedFakeChatService(FakeEngineClient()),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-        server_vad_backend_provider=FakeServerVADProvider(backend),
-    )
-    ws = TimedWebSocket()
-    session_create = _session_create("sid-server-vad-invalid-rate")
-    session_create["session"]["turn_detection"] = _server_vad_turn_detection(create_response=False)
-    ws.put(session_create)
-    invalid_append = _server_vad_audio_append(frame_count=1)
-    invalid_append["sample_rate_hz"] = sample_rate_hz
-    ws.put(invalid_append)
-    ws.put(_server_vad_audio_append(frame_count=1))
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    errors = [event for event in ws.sent if event.get("type") == "error"]
-    assert [error["code"] for error in errors] == ["bad_audio"]
-    assert "internal_error" not in {error["code"] for error in errors}
-    assert "session.created" in ws.sent_types()
-    assert "session.closed" in ws.sent_types()
-    assert backend.calls == 1
-
-
-@pytest.mark.asyncio
-async def test_native_input_commit_does_not_send_noop_runtime_signal():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-commit-without-signal"))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(16000),
-            "sample_rate_hz": 16000,
-            "is_speech": True,
-        }
-    )
-    ws.put({"type": "input_audio_buffer.commit"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert ("sid-commit-without-signal", "input.commit") not in engine.signals
-
-
-@pytest.mark.asyncio
-async def test_audio_clear_preserves_later_wire_order_append():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-clear-then-append"))
-    ws.put({"type": "input_audio_buffer.clear"})
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(16000),
-            "sample_rate_hz": 16000,
-            "is_speech": True,
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert len(engine.appended) == 1
-
-
-@pytest.mark.asyncio
-async def test_native_append_is_cancelled_by_later_wire_order_input_cancel(mocker):
-    class SlowAppendEngine(FakeEngineClient):
-        def __init__(self) -> None:
-            super().__init__()
-            self.append_started = asyncio.Event()
-            self.append_cancelled = asyncio.Event()
-            self.release_append = asyncio.Event()
-
-        async def append_duplex_input_async(
-            self,
-            session_id: str,
-            *,
-            mode: str,
-            payload: object,
-            operation_id: str | None = None,
-            final: bool = False,
-            timeout: float | None = None,
-            collect_outputs: bool = True,
-            fence: DuplexFence | None = None,
-        ) -> Any:
-            self.append_started.set()
-            try:
-                await self.release_append.wait()
-            except asyncio.CancelledError:
-                self.append_cancelled.set()
-                raise
-            return await super().append_duplex_input_async(
-                session_id,
-                mode=mode,
-                payload=payload,
-                operation_id=operation_id,
-                final=final,
-                timeout=timeout,
-                collect_outputs=collect_outputs,
-                fence=fence,
-            )
-
-    rollback = mocker.spy(MiniCPMO45PcmAppendBuffer, "_rollback_reservation")
-    engine = SlowAppendEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-cancel-slow-append"))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm16_b64(16000),
-            "sample_rate_hz": 16000,
-            "is_speech": True,
-        }
-    )
-    ws.put({"type": "input.cancel"})
-    ws.put({"type": "session.close"})
-
-    handler_task = asyncio.create_task(handler.handle_session(ws))
-    await asyncio.wait_for(engine.append_started.wait(), timeout=1)
-    try:
-        await asyncio.wait_for(engine.append_cancelled.wait(), timeout=0.2)
-    except TimeoutError:
-        pass
-    finally:
-        engine.release_append.set()
-    await asyncio.wait_for(handler_task, timeout=1)
-
-    assert engine.append_cancelled.is_set()
-    rollback.assert_called_once()
-    assert engine.signal_fences[-1] == DuplexFence("sid-cancel-slow-append")
-    assert engine.signal_next_fences[-1] == DuplexFence("sid-cancel-slow-append", epoch=1)
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_append_control_error_does_not_emit_model_delta():
-    control_result = {
-        "operation": "append",
-        "session_id": "sid-native-append-error",
-        "ok": False,
-        "unsupported_count": 0,
-        "error_count": 1,
-        "stage_results": [
-            {
-                "stage_id": -1,
-                "replica_id": -1,
-                "result": {
-                    "supported": False,
-                    "error": "duplex_stage_handoff_target_missing:tts",
-                },
-            },
-        ],
-    }
-    engine = FakeEngineClient(append_result=control_result)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-append-error"))
-    ws.put({"type": "input_audio_buffer.append", "audio": "AAAA", "format": "pcm_f32le"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert "response.output_audio.delta" not in ws.sent_types()
-    error = next(m for m in ws.sent if m.get("type") == "error")
-    assert error["code"] == "runtime_append_failed"
-    assert error["runtime_control"]["error_count"] == 1
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_session_update_control_failure_rolls_back_config():
-    control_result = {
-        "operation": "signal",
-        "session_id": "sid-control-signal-fail",
-        "ok": False,
-        "unsupported_count": 0,
-        "error_count": 1,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {"supported": False, "error": "stage signal failed"},
-            }
-        ],
-    }
-    engine = FakeEngineClient(signal_result=control_result)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-control-signal-fail"))
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {"temperature": 0.2},
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert "session.updated" not in ws.sent_types()
-    error = next(m for m in ws.sent if m.get("type") == "error")
-    assert error["code"] == "runtime_signal_failed"
-    assert error["runtime_control"]["error_count"] == 1
-    signaled_config = engine.signal_session_configs[-1]
-    assert signaled_config is not None
-    assert signaled_config["temperature"] == 0.2
-
-
-@pytest.mark.asyncio
-async def test_native_session_update_commits_config_only_after_runtime_ack():
-    class BlockingUpdateEngine(FakeEngineClient):
-        def __init__(self):
-            super().__init__()
-            self.update_started = asyncio.Event()
-            self.release_update = asyncio.Event()
-
-        async def signal_duplex_turn_async(self, session_id: str, **kwargs):
-            if kwargs.get("event") == "session.update":
-                self.update_started.set()
-                await self.release_update.wait()
-            return await super().signal_duplex_turn_async(session_id, **kwargs)
-
-    engine = BlockingUpdateEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([])),
-    )
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    ws.put(_native_realtime_session_update("sid-update-two-phase"))
-    ws.put(_native_server_vad_update("update-two-phase"))
-
-    handler_task = asyncio.create_task(handler.handle_session(ws, realtime_protocol=protocol))
-    await asyncio.wait_for(engine.update_started.wait(), timeout=10)
-    live_session = handler._registry.get("sid-update-two-phase")
-    assert live_session is not None
-    assert live_session.config.overlap_policy == DuplexOverlapPolicy.LISTEN_ONLY.value
-    assert protocol._pending_turn_detection_update is not None
-    assert protocol._turn_detection is None
-
-    protocol.encode_outbound_event({"type": "error", "code": "unrelated", "error": "unrelated"})
-    assert protocol._pending_turn_detection_update is not None
-
-    engine.release_update.set()
-    ws.put({"type": "session.close"})
-    await asyncio.wait_for(handler_task, timeout=2)
-
-    updated = next(message for message in reversed(ws.sent) if message.get("type") == "session.updated")
-    assert updated["session"]["overlap_policy"] == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value
-    assert protocol._turn_detection is not None
-
-
-@pytest.mark.parametrize(
-    ("append_fails", "expected_code"),
-    [(True, "session_update_aborted"), (False, "instructions_update_unsupported")],
-)
-@pytest.mark.asyncio
-async def test_native_server_vad_update_rejection_does_not_stall(append_fails, expected_code):
-    append_result = {"operation": "append", "ok": False, "error_count": 1} if append_fails else None
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(FakeEngineClient(append_result=append_result)),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-        server_vad_backend_provider=FakeServerVADProvider(FakeServerVADBackend([])),
-    )
-    ws = TimedWebSocket()
-    protocol = NativeRealtimeSessionProtocol(ws)  # type: ignore[arg-type]
-    create = _native_realtime_session_update("sid-rejected-vad-update")
-    create["session"]["extra_body"]["auto_response"] = append_fails
-    ws.put(create)
-    if append_fails:
-        ws.put({"type": "input_audio_buffer.append", "audio": _pcm_f32_b64(16_000), "format": "pcm_f32le"})
-    update = _native_server_vad_update("rejected-vad-update")
-    if not append_fails:
-        update["session"]["instructions"] = "You are now a pirate."
-    ws.put(update)
-    ws.put({"type": "session.close"})
-
-    await asyncio.wait_for(handler.handle_session(ws, realtime_protocol=protocol), timeout=10)
-
-    errors = [message["error"] for message in ws.sent if isinstance(message.get("error"), dict)]
-    error = next(error for error in errors if error.get("code") == expected_code)
-    assert error["event_id"] == "rejected-vad-update"
-    assert protocol._pending_turn_detection_update is None
-
-
-@pytest.mark.asyncio
-async def test_native_session_update_waits_for_prior_append_effect():
-    class OrderedUpdateEngine(FakeEngineClient):
-        def __init__(self):
-            super().__init__()
-            self.append_started = asyncio.Event()
-            self.release_append = asyncio.Event()
-            self.update_started = asyncio.Event()
-            self.effects: list[str] = []
-
-        async def append_duplex_input_async(self, session_id: str, **kwargs):
-            self.effects.append("append.started")
-            self.append_started.set()
-            await self.release_append.wait()
-            kwargs.pop("expected_epoch", None)
-            result = await super().append_duplex_input_async(session_id, **kwargs)
-            self.effects.append("append.done")
-            return result
-
-        async def signal_duplex_turn_async(self, session_id: str, **kwargs):
-            if kwargs.get("event") == "session.update":
-                self.effects.append("session.update")
-                self.update_started.set()
-            return await super().signal_duplex_turn_async(session_id, **kwargs)
-
-    engine = OrderedUpdateEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-ordered-update"))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000, value=0.05),
-            "format": "pcm_f32le",
-        }
-    )
-    ws.put(
-        {
-            "type": "turn.signal",
-            "event": "session.update",
-            "payload": {"temperature": 0.2},
-        }
-    )
-
-    handler_task = asyncio.create_task(handler.handle_session(ws))
-    await asyncio.wait_for(engine.append_started.wait(), timeout=1)
-    try:
-        await asyncio.sleep(0.05)
-        assert not engine.update_started.is_set()
-    finally:
-        engine.release_append.set()
-        ws.put({"type": "session.close"})
-        await asyncio.wait_for(handler_task, timeout=2)
-
-    assert engine.effects.index("append.done") < engine.effects.index("session.update")
-
-
-@pytest.mark.asyncio
-async def test_failed_native_append_prevents_queued_append_from_running():
-    failed_result = {
-        "operation": "append",
-        "session_id": "sid-append-chain-failure",
-        "ok": False,
-        "unsupported_count": 0,
-        "error_count": 1,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {"supported": False, "error": "append failed"},
-            }
-        ],
-    }
-
-    class BlockingFailureEngine(FakeEngineClient):
-        def __init__(self):
-            super().__init__(append_result=failed_result)
-            self.first_started = asyncio.Event()
-            self.release_first = asyncio.Event()
-
-        async def append_duplex_input_async(self, session_id: str, **kwargs):
-            if not self.appended:
-                self.first_started.set()
-                await self.release_first.wait()
-            kwargs.pop("expected_epoch", None)
-            return await super().append_duplex_input_async(session_id, **kwargs)
-
-    engine = BlockingFailureEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    create = _native_session_create("sid-append-chain-failure")
-    create["session"]["extra_body"]["auto_response"] = True
-    ws.put(create)
-    for _ in range(2):
-        ws.put(
-            {
-                "type": "input_audio_buffer.append",
-                "audio": _pcm_f32_b64(16_000, value=0.05),
-                "format": "pcm_f32le",
-            }
-        )
-
-    handler_task = asyncio.create_task(handler.handle_session(ws))
-    await asyncio.wait_for(engine.first_started.wait(), timeout=1)
-    engine.release_first.set()
-    await asyncio.sleep(0.1)
-    ws.put({"type": "session.close"})
-    await asyncio.wait_for(handler_task, timeout=2)
-
-    assert len(engine.appended) == 1
-
-
-@pytest.mark.asyncio
-async def test_failed_final_append_discards_retained_audio_without_retry():
-    failed_result = {
-        "operation": "append",
-        "session_id": "sid-final-append-retry",
-        "ok": False,
-        "unsupported_count": 0,
-        "error_count": 1,
-        "stage_results": [],
-    }
-    engine = FakeEngineClient(append_result=failed_result)
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-
-    def retry_after_runtime_error(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") == "error" and data.get("code") == "runtime_append_failed":
-            ws.put({"type": "response.create"})
-
-    ws = TimedWebSocket(on_send=retry_after_runtime_error)
-    ws.put(_native_session_create("sid-final-append-retry"))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(8_000, value=0.05),
-            "format": "pcm_f32le",
-        }
-    )
-    ws.put({"type": "input_audio_buffer.commit", "final": True})
-    ws.put({"type": "response.create"})
-
-    handler_task = asyncio.create_task(handler.handle_session(ws))
-    for _ in range(100):
-        state = handler._serving_runtime_adapter.session_states.get("sid-final-append-retry")
-        if len(engine.appended) >= 1 and state is not None and state.committed_audio_payload is None:
-            break
-        await asyncio.sleep(0.01)
-    state = handler._serving_runtime_adapter.session_states["sid-final-append-retry"]
-    assert state.committed_audio_payload is None
-    assert state.committed_audio_reserved_bytes == 0
-    assert handler._registry.get("sid-final-append-retry").pending_input_bytes == 0
-    ws.put({"type": "session.close"})
-    await asyncio.wait_for(handler_task, timeout=2)
-
-    assert len(engine.appended) == 1
-
-
-@pytest.mark.asyncio
-async def test_duplex_handler_signal_unsupported_workers_with_data_plane_ack_is_not_fatal():
-    control_result = {
-        "operation": "signal",
-        "session_id": "sid-control-signal-data-plane",
-        "ok": False,
-        "unsupported_count": 2,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {"supported": False, "reason": "worker_duplex_signal_not_implemented"},
-            },
-            {
-                "stage_id": 1,
-                "replica_id": 0,
-                "result": {"supported": False, "reason": "worker_duplex_signal_not_implemented"},
-            },
-            {
-                "stage_id": -1,
-                "replica_id": -1,
-                "result": {
-                    "supported": True,
-                    "data_plane_signal": True,
-                    "event": "barge_in",
-                    "epoch": 1,
-                },
-            },
-        ],
-    }
-    engine = FakeEngineClient(signal_result=control_result)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-control-signal-data-plane"))
-    ws.put({"type": "turn.signal", "event": "barge_in"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert "runtime_signal_failed" not in {m.get("code") for m in ws.sent}
-    assert "input.cancelled" in ws.sent_types()
-    runtime_control = next(m for m in ws.sent if m.get("type") == "runtime.control")
-    assert runtime_control["result"]["unsupported_count"] == 2
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_open_unsupported_fails_session_create():
-    control_result = {
-        "operation": "open",
-        "session_id": "sid-native-busy",
-        "ok": True,
-        "unsupported_count": 1,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {"supported": False, "reason": "native_duplex_session_busy"},
-            }
-        ],
-    }
-    engine = FakeEngineClient(control_result=control_result)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-busy"))
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "runtime_open_unsupported"
-    assert ws.sent[0]["runtime_control"]["unsupported_count"] == 1
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_rejects_engine_without_fence_contract():
-    class LegacyEngineClient(FakeEngineClient):
-        async def open_duplex_session_async(  # type: ignore[override]
-            self,
-            session_id: str,
-            *,
-            session_mode: str = "duplex",
-            capabilities: dict[str, object] | None = None,
-            session_config: dict[str, object] | None = None,
-            timeout: float | None = None,
-        ) -> Any:
-            return await super().open_duplex_session_async(
-                session_id,
-                session_mode=session_mode,
-                capabilities=capabilities,
-                session_config=session_config,
-                timeout=timeout,
-            )
-
-    engine = LegacyEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-no-fence-contract"))
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "runtime_contract_invalid"
-    assert "open_duplex_session_async" in ws.sent[0]["error"]
-    assert "fence" in ws.sent[0]["error"]
-    assert engine.opened == []
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_audio_append_does_not_retain_pending_audio():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-no-pending"))
-    short_chunk = base64.b64encode(b"\x00" * (800 * 4)).decode("ascii")
-    ws.put({"type": "input_audio_buffer.append", "audio": short_chunk, "format": "pcm_f32le"})
-    ws.put({"type": "input.cancel", "reason": "barge_in"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    cancelled = next(m for m in ws.sent if m.get("type") == "input.cancelled")
-    assert cancelled["cancelled"] == {"text_chunks": 0, "audio_chunks": 0}
-    assert cancelled["epoch"] == 1
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_rejects_text_append_before_runtime_call():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-text"))
-    ws.put({"type": "input.text.append", "text": "hello"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    error = next(m for m in ws.sent if m.get("type") == "error")
-    assert error["code"] == "native_text_append_unsupported"
-    assert engine.appended == []
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_separates_public_and_runtime_config(monkeypatch):
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-
-    async def fake_resolve_ref_audio(_, *, model_config):
-        del model_config
-        return [0.25] * 1600, 16000
-
-    monkeypatch.setattr(
-        "vllm_omni.model_executor.models.minicpmo_4_5.duplex.MiniCPMO45NativeDuplexServingAdapter.resolve_ref_audio",
-        fake_resolve_ref_audio,
-    )
-    event = _native_session_create("sid-native-ref-audio", modalities=["text", "audio"])
-    event["session"]["ref_audio"] = "data:audio/wav;base64,AAAA"
-    ws = TimedWebSocket()
-    ws.put(event)
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types()[0] == "session.created"
-    opened_config = engine.opened_configs[0]
-    opened_runtime_config = engine.opened_runtime_configs[0]
-    extra_body = opened_config["extra_body"]
-    assert "ref_audio_data" not in extra_body
-    assert "duplex_stage_max_tokens" not in extra_body
-    assert opened_runtime_config["ref_audio_format"] == "pcm_f32le"
-    assert opened_runtime_config["ref_audio_sample_rate_hz"] == 16000
-    assert opened_runtime_config["duplex_stage_max_tokens"] == {"0": 20, "1": 8192}
-    assert opened_runtime_config["duplex_stage_sampling_params"]["0"]["top_k"] == 20
-    assert opened_runtime_config["duplex_stage_sampling_params"]["0"]["top_p"] == 0.8
-    # The Talker YAML carries upstream's min_new_token=50 for chat TTS; a duplex
-    # chunk is 26 codec samples, so check_stop would never release the request.
-    assert opened_runtime_config["duplex_stage_sampling_params"]["1"] == {"min_tokens": 0}
-    assert base64.b64decode(opened_runtime_config["ref_audio_data"]) == struct.pack("<1600f", *([0.25] * 1600))
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_rejects_client_runtime_config():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    event = _native_session_create("sid-native-private-config")
-    event["session"]["extra_body"]["duplex_stage_sampling_params"] = {"0": {"temperature": 0.0}}
-    ws = TimedWebSocket()
-    ws.put(event)
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "invalid_duplex_runtime_config"
-    assert engine.opened == []
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_audio_output_requires_ref_audio(monkeypatch):
-    monkeypatch.setattr(
-        MiniCPMO45NativeDuplexServingAdapter,
-        "_load_native_tokenizer",
-        staticmethod(lambda model_config: None),
-    )
-
-    event = _native_session_create(
-        "sid-native-ref-required",
-        modalities=["text", "audio"],
-    )
-    config = DuplexSessionConfig.from_event(event)
-
-    with pytest.raises(ServingRuntimeConfigError) as exc_info:
-        await MiniCPMO45NativeDuplexServingAdapter.prepare_runtime_config(
-            config,
-            model_config=SimpleNamespace(model="openbmb/MiniCPM-o-4_5"),
-        )
-
-    assert exc_info.value.code == "ref_audio_required"
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_open_session_maps_missing_ref_audio_to_typed_error():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(
-        _native_session_create(
-            "sid-native-ref-required-open",
-            modalities=["text", "audio"],
-        )
-    )
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "ref_audio_required"
-    assert engine.opened == []
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_text_only_omits_ref_audio_when_client_does_not_provide_it(monkeypatch):
-    monkeypatch.setattr(
-        MiniCPMO45NativeDuplexServingAdapter,
-        "_load_native_tokenizer",
-        staticmethod(lambda model_config: None),
-    )
-
-    event = _native_session_create("sid-native-default-ref", modalities=["text"])
-    config = DuplexSessionConfig.from_event(event)
-
-    runtime_config = await MiniCPMO45NativeDuplexServingAdapter.prepare_runtime_config(
-        config,
-        model_config=SimpleNamespace(model="openbmb/MiniCPM-o-4_5"),
-    )
-
-    assert "ref_audio_data" not in runtime_config
-    assert "ref_audio_format" not in runtime_config
-    assert "ref_audio_sample_rate_hz" not in runtime_config
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_preserves_ref_audio_channels_until_normalize(monkeypatch):
-    class FakeMediaConnector:
-        def __init__(self, **kwargs):
-            self.kwargs = kwargs
-
-        async def fetch_audio_async(self, ref_audio):
-            assert ref_audio == "data:audio/wav;base64,AAAA"
-            return np.tile(np.array([[0.25, -0.25], [0.5, -0.5]], dtype=np.float32), (800, 1)), 16000
-
-    monkeypatch.setattr(
-        "vllm_omni.model_executor.models.minicpmo_4_5.duplex.adapter.MediaConnector",
-        FakeMediaConnector,
-    )
-
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    event = _native_session_create("sid-native-ref-audio-stereo", modalities=["text", "audio"])
-    event["session"]["ref_audio"] = "data:audio/wav;base64,AAAA"
-    ws = TimedWebSocket()
-    ws.put(event)
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    runtime_config = engine.opened_runtime_configs[0]
-    assert base64.b64decode(runtime_config["ref_audio_data"]) == struct.pack("<1600f", *([0.0] * 1600))
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_rejects_ref_audio_path():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    event = _native_session_create("sid-native-ref-path")
-    event["session"]["extra_body"] = {
-        "native_duplex": True,
-        "ref_audio_path": "/tmp/ref.wav",
-    }
-    ws = TimedWebSocket()
-    ws.put(event)
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["error"]
-    assert ws.sent[0]["code"] == "unsupported_ref_audio_path"
-    assert engine.opened == []
-
-
-def test_minicpmo_native_duplex_explicit_barge_in_request_interrupts():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-native-explicit-barge-disabled",
-        config=DuplexSessionConfig(overlap_policy=DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value),
-        capabilities=minicpmo45_native_capabilities(),
-    )
-    payload = {
-        "type": "audio",
-        "audio": _pcm_f32_b64(16000, value=0.05),
-        "format": "pcm_f32le",
-        "sample_rate_hz": 16000,
-        "is_speech": True,
-    }
-
-    decision = handler._overlap_decision(
-        session,
-        {"force_barge_in": True},
-        payload,
-    )
-
-    assert decision == {
-        "action": "barge_in",
-        "reason": "client_force_barge_in",
-        "duration_ms": 1000,
-        "buffer_audio": True,
-    }
-
-
-@pytest.mark.asyncio
-async def test_native_server_vad_complete_audio_item_reaches_runtime():
-    engine = FakeEngineClient()
-    backend = FakeServerVADBackend([0.9] * 10)
-    ws = TimedWebSocket()
-    create = _native_realtime_session_update("sid-native-complete-audio")
-    create["session"]["turn_detection"] = {"type": "server_vad"}
-    create["session"]["input_audio_format"] = "pcm16"
-    ws.put(create)
-    ws.put(
-        {
-            "type": "conversation.item.create",
-            "item": {
-                "id": "item-native-audio",
-                "type": "message",
-                "role": "user",
-                "content": [{"type": "input_audio", "audio": _pcm16_b64(2400)}],
-            },
-        }
-    )
-    ws.put({"type": "response.create"})
-    ws.put({"type": "session.close"})
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        server_vad_backend_provider=FakeServerVADProvider(backend),
-    )
-
-    await handler.handle_realtime_session(ws)  # type: ignore[arg-type]
-
-    assert any(final for _, _, _, final in engine.appended)
-    assert "error" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_native_server_vad_uses_shared_pipeline_and_emits_boundaries():
-    backend = FakeServerVADBackend([0.9] * 10 + [0.0] * 50)
-    engine = FakeEngineClient()
-
-    def commit_after_speech_stops(ws: TimedWebSocket, event: dict[str, Any]) -> None:
-        if event.get("type") == "input_audio_buffer.speech_stopped":
-            ws.put({"type": "input_audio_buffer.commit", "final": True})
-            ws.put({"type": "response.create"})
-            ws.put({"type": "session.close"})
-
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-        server_vad_backend_provider=FakeServerVADProvider(backend),
-    )
-    ws = TimedWebSocket(on_send=commit_after_speech_stops)
-    create = _native_realtime_session_update("sid-native-shared-server-vad")
-    create["session"]["turn_detection"] = {"type": "server_vad"}
-    ws.put(create)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(60 * backend.frame_samples, value=0.0),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16_000,
-        }
-    )
-    await asyncio.wait_for(
-        handler.handle_session(ws, realtime_protocol=NativeRealtimeSessionProtocol({})),
-        timeout=10,
-    )
-
-    boundary_events = [
-        event
-        for event in ws.sent
-        if event.get("type") in {"input_audio_buffer.speech_started", "input_audio_buffer.speech_stopped"}
-    ]
-    assert [event["type"] for event in boundary_events] == [
-        "input_audio_buffer.speech_started",
-        "input_audio_buffer.speech_stopped",
-    ]
-    assert boundary_events[0]["item_id"] == boundary_events[1]["item_id"]
-    created_session = next(event["session"] for event in ws.sent if event["type"] == "session.created")
-    assert created_session["audio"]["input"]["turn_detection"]["interrupt_response"] is True
-    assert created_session["overlap_policy"] == "barge_in_on_speech"
-    assert backend.calls == 60
-    assert any(final for _, _, _, final in engine.appended)
-    assert not any(event.get("error", {}).get("code") == "server_vad_manual_commit_unsupported" for event in ws.sent)
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize(
-    "barge_in_event",
-    [
-        {"type": "barge_in"},
-        {"type": "turn.signal", "event": "barge_in"},
-    ],
-)
-async def test_minicpmo_native_duplex_accepts_explicit_barge_in_control(
-    barge_in_event: dict[str, object],
-):
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-barge-control-disabled"))
-    ws.put(barge_in_event)
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert not any(message.get("code") == "barge_in_unsupported" for message in ws.sent)
-    assert ("sid-native-barge-control-disabled", "barge_in") in engine.signals
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_explicit_non_speech_stays_listening_without_append():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-silence"))
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": "AAAA",
-            "format": "pcm_f32le",
-            "is_speech": False,
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert engine.appended == []
-    assert "response.listen" in ws.sent_types()
-    assert "response.created" not in ws.sent_types()
-    assert "response.output_audio.delta" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_drains_data_plane_stream_until_done():
-    def _stage_output(samples: int, *, finished: bool):
-        return SimpleNamespace(
-            request_id="duplex-sid-native-stream-e0-stage0-s1",
-            finished=finished,
-            outputs=[
-                SimpleNamespace(
-                    text="",
-                    multimodal_output={
-                        "audio": np.zeros(samples, dtype=np.float32),
-                        "sr": 24000,
-                    },
-                )
-            ],
-        )
-
-    control_result = {
-        "operation": "append",
-        "session_id": "sid-native-stream",
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {
-                    "supported": True,
-                    "implementation_level": "model_native_duplex",
-                    "data_plane_append": True,
-                    "request_id": "duplex-sid-native-stream-e0-stage0-s1",
-                    "response_stage_id": 1,
-                },
-            }
-        ],
-        "data_plane_outputs": [_stage_output(10, finished=False)],
-    }
-    engine = FakeEngineClient(
-        append_result=control_result,
-        collect_outputs=[
-            [_stage_output(20, finished=False)],
-            [_stage_output(30, finished=True)],
-        ],
-    )
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-
-    def close_on_second_created(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if ws.sent_types().count("response.created") >= 2:
-            ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=close_on_second_created)
-    ws.put(_native_session_create("sid-native-stream"))
-    ws.put({"type": "input_audio_buffer.append", "audio": "AAAA", "format": "pcm_f32le"})
-
-    await handler.handle_session(ws)
-
-    deltas = [m for m in ws.sent if m.get("type") == "response.output_audio.delta"]
-    assert [m["audio"] for m in deltas] == ["wav-10", "wav-10", "wav-10"]
-    assert [m["end_of_turn"] for m in deltas] == [False, False, True]
-    assert len([m for m in ws.sent if m.get("type") == "response.done"]) == 1
-    assert engine.collected == [
-        ("duplex-sid-native-stream-e0-stage0-s1", 1),
-        ("duplex-sid-native-stream-e0-stage0-s1", 1),
-    ]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_restarts_drain_when_append_races_idle_exit(
-    monkeypatch: pytest.MonkeyPatch,
-):
-    request_id = "duplex-sid-native-late-output-e0-stage0"
-    late_output = object()
-    engine = FakeEngineClient(
-        collect_outputs=[[], [], [], [late_output]],
-        collect_delay_s=0.05,
-    )
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    session = DuplexSession(
-        session_id="sid-native-late-output",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    session.bind_request(request_id)
-    native = handler._runtime_session_state(session)
-    projected_batches: list[object] = []
-    projected = asyncio.Event()
-
-    async def project_late_output(_send_json, result, **_kwargs):
-        projected_batches.append(result)
-        projected.set()
-        session.close()
-        return None, True
-
-    monkeypatch.setattr(handler, "_send_native_duplex_events", project_late_output)
-    result = {
-        "stage_results": [
-            {
-                "result": {
-                    "data_plane_append": True,
-                    "request_id": request_id,
-                    "response_stage_id": 1,
-                }
-            }
-        ]
-    }
-
-    assert (
-        await handler._start_native_data_plane_stream_task(
-            None,
-            result,
-            session=session,
-            expected_epoch=session.epoch,
-        )
-        is True
-    )
-    first_drain = native.data_plane_task
-    assert first_drain is not None
-    await asyncio.sleep(0.01)
-
-    assert (
-        await handler._start_native_data_plane_stream_task(
-            None,
-            result,
-            session=session,
-            expected_epoch=session.epoch,
-        )
-        is False
-    )
-    await asyncio.wait_for(projected.wait(), timeout=1)
-    await asyncio.wait_for(first_drain, timeout=1)
-
-    assert len(engine.collected) == 4
-    assert projected_batches == [{"data_plane_outputs": [late_output]}]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_ignores_outputs_after_data_plane_turn_done():
-    request_id = "duplex-sid-native-post-done-e0-stage0-s1"
-
-    def _stage_output(samples: int, *, turn_end: bool = False):
-        return SimpleNamespace(
-            request_id=request_id,
-            finished=False,
-            outputs=[
-                SimpleNamespace(
-                    text="hello",
-                    multimodal_output={
-                        "audio": np.zeros(samples, dtype=np.float32),
-                        "sr": 24000,
-                        "meta": {
-                            "turn_end": turn_end,
-                            "duplex_turn_id": 0,
-                            "duplex_epoch": 0,
-                        },
-                    },
-                )
-            ],
-        )
-
-    control_result = {
-        "operation": "append",
-        "session_id": "sid-native-post-done",
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {
-                    "supported": True,
-                    "implementation_level": "model_native_duplex",
-                    "data_plane_append": True,
-                    "request_id": request_id,
-                    "response_stage_id": 1,
-                },
-            }
-        ],
-        "data_plane_outputs": [_stage_output(10)],
-    }
-    engine = FakeEngineClient(
-        append_result=control_result,
-        collect_outputs=[
-            [_stage_output(20, turn_end=True)],
-            [_stage_output(30)],
-        ],
-    )
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-
-    def close_on_done(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") == "response.done":
-            ws.put({"type": "session.close"})
-
-    event = _native_session_create("sid-native-post-done")
-    event["session"]["extra_body"]["auto_response"] = True
-    ws = TimedWebSocket(on_send=close_on_done)
-    ws.put(event)
-    ws.put({"type": "input_audio_buffer.append", "audio": "AAAA", "format": "pcm_f32le"})
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types().count("response.created") == 1
-    assert ws.sent_types().count("response.done") == 1
-    deltas = [m for m in ws.sent if m.get("type") == "response.output_audio.delta"]
-    assert [m["audio"] for m in deltas] == ["wav-10", "wav-10"]
-    assert engine.collected
-    assert all(collected == (request_id, 1) for collected in engine.collected)
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_accepts_next_append_after_response_done():
-    def _stage_output(*, finished: bool):
-        return SimpleNamespace(
-            request_id="duplex-sid-native-next-turn-e0-stage0-s1",
-            finished=finished,
-            outputs=[
-                SimpleNamespace(
-                    text="",
-                    multimodal_output={
-                        "audio": np.zeros(10, dtype=np.float32),
-                        "sr": 24000,
-                    },
-                )
-            ],
-        )
-
-    control_result = {
-        "operation": "append",
-        "session_id": "sid-native-next-turn",
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {
-                    "supported": True,
-                    "implementation_level": "model_native_duplex",
-                    "data_plane_append": True,
-                    "request_id": "duplex-sid-native-next-turn-e0-stage0-s1",
-                    "response_stage_id": 1,
-                },
-            }
-        ],
-        "data_plane_outputs": [_stage_output(finished=True)],
-    }
-    engine = FakeEngineClient(append_result=control_result)
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    done_count = 0
-
-    def send_next_turn_or_close(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        nonlocal done_count
-        if data.get("type") != "response.done":
-            return
-        done_count += 1
-        if done_count == 1:
-            ws.put({"type": "input_audio_buffer.append", "audio": "BBBB", "format": "pcm_f32le"})
-            ws.put({"type": "input_audio_buffer.commit", "final": True})
-            ws.put({"type": "response.create"})
-        else:
-            ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=send_next_turn_or_close, receive_timeout_s=5)
-    create = _native_session_create("sid-native-next-turn")
-    create["session"]["idle_timeout_s"] = 5
-    ws.put(create)
-    ws.put({"type": "input_audio_buffer.append", "audio": "AAAA", "format": "pcm_f32le"})
-
-    await handler.handle_session(ws)
-
-    assert len(engine.appended) >= 2, [
-        (message.get("type"), message.get("code"), message.get("reason")) for message in ws.sent
-    ]
-    assert len([m for m in ws.sent if m.get("type") == "response.done"]) == 2
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_auto_response_commit_finalizes_after_streamed_full_chunk():
-    control_result = {
-        "operation": "append",
-        "session_id": "sid-native-auto-finalize",
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [],
-    }
-    engine = FakeEngineClient(control_result=control_result)
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    event = _native_session_create("sid-native-auto-finalize")
-    event["session"]["extra_body"]["auto_response"] = True
-    ws.put(event)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-        }
-    )
-    ws.put({"type": "input_audio_buffer.commit", "final": True})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert len(engine.appended) == 1
-    assert engine.appended[0][3] is False
-    assert "response.created" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_auto_response_commit_finalizes_with_active_data_plane_stream():
-    request_id = "duplex-sid-native-auto-active-stream-stage0"
-    control_result = {
-        "operation": "append",
-        "session_id": "sid-native-auto-active-stream",
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "result": {
-                    "data_plane_append": True,
-                    "request_id": request_id,
-                    "response_stage_id": 1,
-                }
-            }
-        ],
-    }
-    engine = FakeEngineClient(
-        control_result=control_result,
-        collect_outputs=[[], [], []],
-        collect_delay_s=0.05,
-    )
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    event = _native_session_create("sid-native-auto-active-stream")
-    event["session"]["extra_body"]["auto_response"] = True
-    ws.put(event)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-        }
-    )
-    ws.put({"type": "input_audio_buffer.commit", "final": True})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert len(engine.appended) == 1
-    assert engine.appended[0][3] is False
-    assert "response.created" not in ws.sent_types()
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_auto_response_accepts_realtime_commit_after_stream_consumed():
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket()
-    event = _native_session_create("sid-native-auto-consumed-stream")
-    event["session"]["extra_body"]["auto_response"] = True
-    ws.put(event)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-        }
-    )
-    ws.put(
-        {
-            "type": "input_audio_buffer.commit",
-            "final": True,
-            "item_id": "item-consumed-stream",
-        }
-    )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert not any(message.get("code") == "input_audio_buffer_empty" for message in ws.sent)
-    committed = next(message for message in ws.sent if message.get("type") == "input.committed")
-    assert committed["item_id"] == "item-consumed-stream"
-    assert committed["native_audio"] is True
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_auto_response_post_response_commit_ignores_stale_progress_state():
-    session_id = "sid-native-auto-post-response"
-    engine = FakeEngineClient()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") != "session.created":
-            return
-        session = handler._registry.get(session_id)
-        assert session is not None
-        ws.put(
-            {
-                "type": "input_audio_buffer.append",
-                "audio": _pcm_f32_b64(8000),
-                "format": "pcm_f32le",
-                "sample_rate_hz": 16000,
-            }
-        )
-        ws.put({"type": "input_audio_buffer.commit", "final": True})
-        ws.put({"type": "session.close"})
-
-    ws = TimedWebSocket(on_send=on_send)
-    create = _native_session_create(session_id)
-    create["session"]["extra_body"]["auto_response"] = True
-    ws.put(create)
-
-    await handler.handle_session(ws)
-
-    assert len(engine.appended) == 1
-    assert engine.appended[0][3] is True
-    assert "input.committed" in ws.sent_types()
-    assert not any(message.get("code") == "response_already_active" for message in ws.sent)
-
-
-def test_realtime_overlap_commit_uses_current_generation_identity():
-    handler, session = _auto_response_context("sid-realtime-reserved-input-turn")
-    session.turn_id = 1
-    session.bind_response_turn(1)
-    session.turn_id = 3
-    committed = handler._commit_native_audio_input(session)
-
-    assert committed.turn_id == 3
-    assert session.turn_id == 3
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_auto_response_keeps_request_bound_for_segment_continuation():
-    request_id = "duplex-sid-native-auto-continuation-e0-stage0"
-    control_result = {
-        "operation": "append",
-        "session_id": "sid-native-auto-continuation",
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "result": {
-                    "data_plane_append": True,
-                    "request_id": request_id,
-                    "response_stage_id": 1,
-                }
-            }
-        ],
-    }
-    terminal_segment = _duplex_tts_output(
-        request_id=request_id,
-        samples=0,
-        finished=True,
-        tts_is_last_chunk=True,
-        token_ids=[151645],
-    )
-    engine = FakeEngineClient(
-        control_result=control_result,
-        collect_outputs=[[terminal_segment], [], []],
-        collect_delay_s=0.05,
-    )
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") != "session.created":
-            return
-        session = handler._registry.get("sid-native-auto-continuation")
-        assert session is not None
-        session.capabilities.chunk_period_ms = 50
-        ws.put(
-            {
-                "type": "input_audio_buffer.append",
-                "audio": _pcm_f32_b64(800),
-                "format": "pcm_f32le",
-                "sample_rate_hz": 16000,
-            }
-        )
-        ws.put({"type": "input_audio_buffer.commit", "final": True})
-
-    ws = TimedWebSocket(on_send=on_send)
-    event = _native_session_create("sid-native-auto-continuation")
-    event["session"]["extra_body"]["auto_response"] = True
-    ws.put(event)
-
-    await handler.handle_session(ws)
-
-    assert len(engine.appended) >= 3
-    _, mode, payload, final = engine.appended[2]
-    assert mode == "append_audio_chunk"
-    assert payload["duplex_turn_id"] == 0
-    assert final is False
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_auto_response_real_input_preempts_unsent_silence():
-    request_id = "duplex-sid-native-real-before-silence-e0-stage0"
-
-    class SequencedAppendEngine(FakeEngineClient):
-        def __init__(self) -> None:
-            control_result = {
-                "operation": "append",
-                "session_id": "sid-native-real-before-silence",
-                "ok": True,
-                "unsupported_count": 0,
-                "error_count": 0,
-                "stage_results": [
-                    {
-                        "result": {
-                            "data_plane_append": True,
-                            "request_id": request_id,
-                            "response_stage_id": 1,
-                        }
-                    }
-                ],
-            }
-            terminal_segment = _duplex_tts_output(
-                request_id=request_id,
-                samples=0,
-                finished=True,
-                tts_is_last_chunk=True,
-                token_ids=[151645],
-            )
-            super().__init__(
-                control_result=control_result,
-                collect_outputs=[[terminal_segment], [], []],
-                collect_delay_s=0.01,
-            )
-            self.append_sequence: list[str] = []
-            self.first_real_started = asyncio.Event()
-            self.second_real_started = asyncio.Event()
-            self.real_count = 0
-
-        async def append_duplex_input_async(self, session_id: str, **kwargs):
-            kwargs.pop("expected_epoch", None)
-            result = await super().append_duplex_input_async(session_id, **kwargs)
-            payload = kwargs.get("payload")
-            is_silence = (
-                isinstance(payload, dict)
-                and payload.get("audio") == OmniDuplexSessionHandler._NATIVE_SILENCE_UNIT_PAYLOAD_AUDIO
-            )
-            if is_silence:
-                self.append_sequence.append("silence")
-            else:
-                self.real_count += 1
-                self.append_sequence.append(f"real-{self.real_count}")
-                if self.real_count == 1:
-                    self.first_real_started.set()
-                elif self.real_count == 2:
-                    self.second_real_started.set()
-            return result
-
-    session_created = asyncio.Event()
-    engine = SequencedAppendEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") != "session.created":
-            return
-        session = handler._registry.get("sid-native-real-before-silence")
-        assert session is not None
-        session.capabilities.chunk_period_ms = 50
-        ws.put(
-            {
-                "type": "input_audio_buffer.append",
-                "audio": _pcm_f32_b64(800),
-                "format": "pcm_f32le",
-                "sample_rate_hz": 16000,
-            }
-        )
-        session_created.set()
-
-    ws = TimedWebSocket(on_send=on_send, receive_timeout_s=2.0)
-    event = _native_session_create("sid-native-real-before-silence")
-    event["session"]["extra_body"]["auto_response"] = True
-    ws.put(event)
-    handler_task = asyncio.create_task(handler.handle_session(ws))
-
-    await asyncio.wait_for(session_created.wait(), timeout=1)
-    await asyncio.wait_for(engine.first_real_started.wait(), timeout=1)
-    await asyncio.sleep(0.02)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(800, value=0.07),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-        }
-    )
-    await asyncio.wait_for(engine.second_real_started.wait(), timeout=1)
-    ws.put({"type": "session.close"})
-    await asyncio.wait_for(handler_task, timeout=2)
-
-    assert engine.append_sequence[:2] == ["real-1", "real-2"]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_auto_response_real_input_waits_for_submitted_silence_tail():
-    request_id = "duplex-sid-native-silence-tail-e0-stage0"
-
-    class SubmittedSilenceEngine(FakeEngineClient):
-        def __init__(self) -> None:
-            control_result = {
-                "operation": "append",
-                "session_id": "sid-native-silence-tail",
-                "ok": True,
-                "unsupported_count": 0,
-                "error_count": 0,
-                "stage_results": [
-                    {
-                        "result": {
-                            "data_plane_append": True,
-                            "request_id": request_id,
-                            "response_stage_id": 1,
-                        }
-                    }
-                ],
-            }
-            terminal_segment = _duplex_tts_output(
-                request_id=request_id,
-                samples=0,
-                finished=True,
-                tts_is_last_chunk=True,
-                token_ids=[151645],
-            )
-            super().__init__(
-                control_result=control_result,
-                collect_outputs=[[terminal_segment], [], []],
-                collect_delay_s=0.01,
-            )
-            self.silence_append_started = asyncio.Event()
-            self.release_silence_append = asyncio.Event()
-            self.append_sequence: list[str] = []
-            self.real_append_count = 0
-
-        async def append_duplex_input_async(self, session_id: str, **kwargs):
-            kwargs.pop("expected_epoch", None)
-            payload = kwargs.get("payload")
-            is_silence_continuation = (
-                isinstance(payload, dict)
-                and payload.get("format") == "pcm_f32le"
-                and payload.get("audio") == OmniDuplexSessionHandler._NATIVE_SILENCE_UNIT_PAYLOAD_AUDIO
-            )
-            if is_silence_continuation:
-                result = await super().append_duplex_input_async(session_id, **kwargs)
-                self.append_sequence.append("silence-started")
-                self.silence_append_started.set()
-                await self.release_silence_append.wait()
-                self.append_sequence.append("silence-returned")
-                return result
-            result = await super().append_duplex_input_async(session_id, **kwargs)
-            if (
-                isinstance(payload, dict)
-                and payload.get("audio") != OmniDuplexSessionHandler._NATIVE_SILENCE_UNIT_PAYLOAD_AUDIO
-            ):
-                self.real_append_count += 1
-                self.append_sequence.append(f"real-{self.real_append_count}")
-            return result
-
-    engine = SubmittedSilenceEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-
-    def on_send(ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") != "session.created":
-            return
-        session = handler._registry.get("sid-native-silence-tail")
-        assert session is not None
-        session.capabilities.chunk_period_ms = 50
-        ws.put(
-            {
-                "type": "input_audio_buffer.append",
-                "audio": _pcm_f32_b64(800, value=0.05),
-                "format": "pcm_f32le",
-                "sample_rate_hz": 16000,
-            }
-        )
-
-    ws = TimedWebSocket(on_send=on_send, receive_timeout_s=2.0)
-    event = _native_session_create("sid-native-silence-tail")
-    event["session"]["extra_body"]["auto_response"] = True
-    ws.put(event)
-    handler_task = asyncio.create_task(handler.handle_session(ws))
-
-    await asyncio.wait_for(engine.silence_append_started.wait(), timeout=1)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000, value=0.07),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-        }
-    )
-    await asyncio.sleep(0.05)
-
-    assert engine.real_append_count == 1
-    assert engine.append_sequence == ["real-1", "silence-started"]
-
-    engine.release_silence_append.set()
-    ws.put({"type": "session.close"})
-    await asyncio.wait_for(handler_task, timeout=2)
-
-    assert engine.real_append_count == 2
-    assert engine.append_sequence == ["real-1", "silence-started", "silence-returned", "real-2"]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_auto_response_preserves_silence_continuations_across_append_tails():
-    request_id = "duplex-sid-native-continuation-tails-e0-stage0"
-
-    class SequencedAppendEngine(FakeEngineClient):
-        def __init__(self) -> None:
-            control_result = {
-                "operation": "append",
-                "session_id": "sid-native-continuation-tails",
-                "ok": True,
-                "unsupported_count": 0,
-                "error_count": 0,
-                "stage_results": [
-                    {
-                        "result": {
-                            "data_plane_append": True,
-                            "request_id": request_id,
-                            "response_stage_id": 1,
-                        }
-                    }
-                ],
-            }
-            super().__init__(control_result=control_result)
-            self.real_append_started = asyncio.Event()
-            self.release_real_append = asyncio.Event()
-            self.first_silence_started = asyncio.Event()
-            self.release_first_silence = asyncio.Event()
-            self.second_silence_started = asyncio.Event()
-            self.release_collect = asyncio.Event()
-            self.silence_count = 0
-
-        async def append_duplex_input_async(self, session_id: str, **kwargs):
-            kwargs.pop("expected_epoch", None)
-            payload = kwargs.get("payload")
-            assert isinstance(payload, dict)
-            result = await super().append_duplex_input_async(session_id, **kwargs)
-            if payload.get("audio") != OmniDuplexSessionHandler._NATIVE_SILENCE_UNIT_PAYLOAD_AUDIO:
-                self.real_append_started.set()
-                await self.release_real_append.wait()
-                return result
-
-            self.silence_count += 1
-            if self.silence_count == 1:
-                self.first_silence_started.set()
-                await self.release_first_silence.wait()
-            else:
-                self.second_silence_started.set()
-            return result
-
-        async def collect_duplex_data_plane_outputs_async(
-            self,
-            request_id: str,
-            *,
-            response_stage_id: int | None = None,
-            timeout: float | None = None,
-        ) -> list[object]:
-            del timeout
-            self.collected.append((request_id, response_stage_id))
-            await self.release_collect.wait()
-            return []
-
-    session_created = asyncio.Event()
-
-    def on_send(_ws: TimedWebSocket, data: dict[str, Any]) -> None:
-        if data.get("type") == "session.created":
-            session_created.set()
-
-    engine = SequencedAppendEngine()
-    handler = OmniDuplexSessionHandler(
-        chat_service=FakeChatService(engine),
-        config_timeout_s=0.1,
-        idle_timeout_s=1,
-    )
-    ws = TimedWebSocket(on_send=on_send, receive_timeout_s=2.0)
-    event = _native_session_create("sid-native-continuation-tails")
-    event["session"]["extra_body"]["auto_response"] = True
-    ws.put(event)
-    ws.put(
-        {
-            "type": "input_audio_buffer.append",
-            "audio": _pcm_f32_b64(16000, value=0.05),
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-        }
-    )
-    handler_task = asyncio.create_task(handler.handle_session(ws))
-
-    await asyncio.wait_for(session_created.wait(), timeout=1)
-    await asyncio.wait_for(engine.real_append_started.wait(), timeout=1)
-    session = handler._registry.get("sid-native-continuation-tails")
-    assert session is not None
-    session.capabilities.chunk_period_ms = 50
-    session.bind_request(request_id)
-    response_id = session.begin_response(turn_id=session.turn_id)
-    native = handler._runtime_session_state(session)
-    scheduler = native.silence_continuation_scheduler
-    assert scheduler is not None
-
-    payload = handler._native_silence_unit_payload()
-    payload["duplex_turn_id"] = session.turn_id
-    kwargs = {
-        "request_id": request_id,
-        "owner_id": f"response:{response_id}",
-        "response_id": response_id,
-        "response_owned": True,
-        "expected_epoch": session.epoch,
-        "expected_incarnation": session.incarnation,
-        "expected_model_turn_id": None,
-        "send_json": ws.send_json,
-    }
-    assert await scheduler(payload, **kwargs) is True
-
-    next_schedule = asyncio.create_task(scheduler(payload, **kwargs))
-    await asyncio.sleep(0.05)
-    assert not next_schedule.done()
-
-    engine.release_real_append.set()
-    await asyncio.wait_for(engine.first_silence_started.wait(), timeout=1)
-    assert not next_schedule.done()
-
-    engine.release_first_silence.set()
-    assert await asyncio.wait_for(next_schedule, timeout=1) is True
-    await asyncio.wait_for(engine.second_silence_started.wait(), timeout=1)
-    ws.put({"type": "session.close"})
-    await asyncio.wait_for(handler_task, timeout=2)
-
-    assert engine.silence_count == 2
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_uses_segment_text_metadata_for_transcript_cursor():
-    request_id = "duplex-sid-native-repeat-text-e0-stage0"
-
-    def _stage_output(
-        text: str,
-        samples: int,
-        *,
-        segment_text: str,
-        turn_id: int = 0,
-        turn_end: bool = False,
-        token_ids: list[int] | None = None,
-    ):
-        return SimpleNamespace(
-            request_id=request_id,
-            finished=False,
-            outputs=[
-                SimpleNamespace(
-                    text=text,
-                    token_ids=list(token_ids or []),
-                    multimodal_output={
-                        "audio": np.zeros(samples, dtype=np.float32),
-                        "sr": 24000,
-                        "meta.llm_output_text_utf8": np.frombuffer(segment_text.encode("utf-8"), dtype=np.uint8),
-                        "meta": {"duplex_turn_id": turn_id, "turn_end": turn_end},
-                    },
-                )
-            ],
-        )
-
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-native-repeat-text",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(payload: dict[str, Any]) -> None:
-        sent.append(payload)
-
-    async def emit(output: object) -> None:
-        result = {"data_plane_outputs": [output]}
-        for native_result in handler._serving_runtime_adapter.data_plane.project(
-            result,
-            context=_data_plane_context(session),
-        ):
-            await handler._send_one_native_duplex_event(send_json, native_result, session=session)
-
-    await emit(_stage_output("same reply", 24000, segment_text="same reply"))
-    await emit(
-        _stage_output("same replysame reply", 24000, segment_text="same reply", turn_end=True, token_ids=[151645])
-    )
-
-    await emit(_stage_output("same replysame replysame reply", 48000, segment_text="same reply", turn_id=1))
-    await emit(
-        _stage_output(
-            "same replysame replysame replysame reply",
-            48000,
-            segment_text="same reply",
-            turn_id=1,
-            turn_end=True,
-            token_ids=[151645],
-        )
-    )
-
-    created = [m for m in sent if m.get("type") == "response.created"]
-    done = [m for m in sent if m.get("type") == "response.done"]
-    deltas = [m for m in sent if m.get("type") == "response.output_audio.delta" and m.get("audio")]
-    protocol = NativeRealtimeSessionProtocol(TimedWebSocket())  # type: ignore[arg-type]
-    realtime_events = [event for payload in sent for event in protocol._from_duplex_event(payload)]
-    transcript_deltas = [
-        m for m in realtime_events if m.get("type") == "response.output_audio_transcript.delta" and m.get("delta")
-    ]
-    assert len(created) == 2
-    assert len(done) == 2
-    assert len(deltas) == 2
-    assert [m["text"] for m in deltas] == ["same reply", "same reply"]
-    assert [m["audio"] for m in deltas] == ["wav-24000", "wav-24000"]
-    assert [m["delta"] for m in transcript_deltas] == ["same reply", "same reply"]
-    assert [m["response_id"] for m in deltas] == [m["response_id"] for m in created]
-    assert [m["response_id"] for m in done] == [m["response_id"] for m in created]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_continuous_speak_reuses_active_response_until_turn_end():
-    request_id = "duplex-sid-native-continuous-speak-e0-stage0"
-
-    def _stage_output(
-        text: str,
-        samples: int,
-        *,
-        turn_end: bool = False,
-        token_ids: list[int] | None = None,
-    ):
-        return SimpleNamespace(
-            request_id=request_id,
-            finished=turn_end,
-            outputs=[
-                SimpleNamespace(
-                    text=text,
-                    token_ids=list(token_ids or []),
-                    multimodal_output={},
-                )
-            ],
-            multimodal_output={
-                "audio": np.zeros(samples, dtype=np.float32),
-                "sr": 24000,
-                "meta.duplex_turn_id": np.array([0], dtype=np.int32),
-                "meta.duplex_epoch": np.array([0], dtype=np.int32),
-                "meta.turn_end": np.array([int(turn_end)], dtype=np.int32),
-                "meta.tts_is_last_chunk": np.array([int(turn_end)], dtype=np.int32),
-            },
-        )
-
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-native-continuous-speak",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(payload: dict[str, Any]) -> None:
-        sent.append(payload)
-
-    async def emit(output: object) -> None:
-        result = {"data_plane_outputs": [output]}
-        for native_result in handler._serving_runtime_adapter.data_plane.project(
-            result,
-            context=_data_plane_context(session),
-        ):
-            await handler._send_one_native_duplex_event(send_json, native_result, session=session)
-
-    await emit(_stage_output("hello", 24000))
-    await emit(_stage_output("hello again", 48000))
-
-    created = [m for m in sent if m.get("type") == "response.created"]
-    deltas = [m for m in sent if m.get("type") == "response.output_audio.delta" and m.get("audio")]
-    assert len(created) == 1
-    assert len(deltas) == 2
-    assert {m["response_id"] for m in deltas} == {created[0]["response_id"]}
-    assert "response.done" not in [m.get("type") for m in sent]
-
-    await emit(_stage_output("hello again", 48000, turn_end=True, token_ids=[151645]))
-
-    done = [m for m in sent if m.get("type") == "response.done"]
-    assert len(done) == 1
-    assert done[0]["response_id"] == created[0]["response_id"]
-    assert session.active_response_id is None
-    assert session.turn_id == 1
-
-
-def test_response_timing_binds_latest_request_start_for_model_turn():
-    session = DuplexSession(
-        session_id="sid-response-request-timing",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.mark_model_turn_request_started(0, 10.0)
-    session.mark_model_turn_request_started(0, 11.0)
-    session.begin_response(turn_id=0)
-
-    assert session.mark_response_first_outputs(
-        observed_at_s=11.2,
-        has_text=True,
-        has_audio=False,
-    )["ttft_ms"] == pytest.approx(200.0)
-
-    session.mark_model_turn_request_started(0, 12.0)
-    assert session.mark_response_first_outputs(
-        observed_at_s=12.3,
-        has_text=False,
-        has_audio=True,
-    )["ttfp_ms"] == pytest.approx(1300.0)
-
-
-def test_response_tpot_fallback_ignores_single_token_segment():
-    session = DuplexSession(
-        session_id="sid-response-tpot",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.begin_response(turn_id=0)
-
-    first_metrics = session.accumulate_response_stage_metrics({"0": {"num_tokens_out": 1, "vllm_tpot_ms": 900.0}})
-    assert "vllm_tpot_ms" not in first_metrics["0"]
-
-    second_metrics = session.accumulate_response_stage_metrics({"0": {"num_tokens_out": 2, "vllm_tpot_ms": 15.0}})
-    assert second_metrics["0"]["num_tokens_out"] == 3
-    assert second_metrics["0"]["vllm_tpot_ms"] == 15.0
-
-
-def test_response_tpot_keeps_token_weighted_value_when_itls_exist():
-    session = DuplexSession(
-        session_id="sid-response-tpot-multi-token",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.begin_response(turn_id=0)
-    metrics = session.accumulate_response_stage_metrics(
-        {
-            "0": {
-                "num_tokens_out": 4,
-                "vllm_tpot_ms": 10.0,
-                "vllm_itls_ms": [30.0],
-            }
-        }
-    )
-    assert metrics["0"]["vllm_itls_ms"] == [30.0]
-    assert metrics["0"]["vllm_itl_ms"] == 30.0
-    assert metrics["0"]["vllm_tpot_ms"] == 10.0
-
-
-@pytest.mark.asyncio
-async def test_continuous_response_metrics_accumulate_only_owned_model_units(monkeypatch):
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-response-metrics",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.mark_model_turn_request_started(0, 10.0)
-    monkeypatch.setattr(
-        "vllm_omni.entrypoints.duplex.runtime_bridge.time.monotonic",
-        lambda: 10.25,
-    )
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(payload: dict[str, Any]) -> None:
-        sent.append(payload)
-
-    async def emit(*, text: str, audio: str, tokens: int, ttft_ms: float, itls: list[float], tpot_ms: float) -> None:
-        await handler._send_one_native_duplex_event(
-            send_json,
-            {
-                "supported": True,
-                "stage_role": "tts",
-                "is_listen": False,
-                "data_plane_request_id": "duplex-sid-response-metrics-e0-stage0",
-                "text": text,
-                "audio_data": audio,
-                "audio_format": "pcm16",
-                "audio_duration_ms": 100,
-                "end_of_turn": False,
-                "model_turn_id": 0,
-                "stage_metrics": {
-                    "0": {
-                        "num_tokens_out": tokens,
-                        "stage_gen_time_ms": 80.0,
-                        "vllm_ttft_ms": ttft_ms,
-                        "vllm_tpot_ms": tpot_ms,
-                        "vllm_itls_ms": itls,
-                    }
-                },
-            },
-            session=session,
-        )
-
-    await emit(text="first", audio="audio-a", tokens=3, ttft_ms=50.0, itls=[10.0, 11.0], tpot_ms=10.5)
-    await emit(text="second", audio="audio-b", tokens=4, ttft_ms=70.0, itls=[12.0, 13.0, 14.0], tpot_ms=13.0)
-
-    deltas = [payload for payload in sent if payload.get("type") == "response.output_audio.delta"]
-    assert len(deltas) == 2
-    first_metrics = deltas[0]["vllm_omni"]["stage_metrics"]["0"]
-    second_metrics = deltas[1]["vllm_omni"]["stage_metrics"]["0"]
-    assert first_metrics["num_tokens_out"] == 3
-    assert first_metrics["vllm_tpot_ms"] == pytest.approx(10.5)
-    assert deltas[0]["vllm_omni"]["response_request_metrics"] == {
-        "source": "server_monotonic_request_start",
-        "measurement_origin": {
-            "ttft": "native model-turn request execution start to first non-empty text output",
-            "ttfp": "native model-turn request execution start to first audio output",
-        },
-        "ttft_ms": 250.0,
-        "ttfp_ms": 250.0,
-    }
-    assert second_metrics["num_tokens_out"] == 7
-    assert second_metrics["vllm_ttft_ms"] == 50.0
-    assert second_metrics["vllm_itls_ms"] == [10.0, 11.0, 12.0, 13.0, 14.0]
-    assert second_metrics["vllm_tpot_ms"] == pytest.approx(12.0)
-
-    first_response_id = deltas[0]["response_id"]
-    session.end_response()
-    await emit(text="third", audio="audio-c", tokens=3, ttft_ms=90.0, itls=[15.0, 16.0], tpot_ms=15.5)
-
-    third_delta = [payload for payload in sent if payload.get("type") == "response.output_audio.delta"][-1]
-    third_metrics = third_delta["vllm_omni"]["stage_metrics"]["0"]
-    assert third_delta["response_id"] != first_response_id
-    assert third_metrics["num_tokens_out"] == 3
-    assert third_metrics["vllm_ttft_ms"] == 90.0
-    assert third_metrics["vllm_itls_ms"] == [15.0, 16.0]
-    assert third_metrics["vllm_tpot_ms"] == pytest.approx(15.5)
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_drops_old_turn_audio_while_new_response_is_active():
-    request_id = "duplex-sid-native-old-turn-audio-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-native-old-turn-audio",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    response_id = session.begin_response(turn_id=1)
-    session.turn_id = 2
-    session.bind_request(request_id)
-    ws = TimedWebSocket()
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "tts",
-            "is_listen": False,
-            "data_plane_request_id": request_id,
-            "text": "stale",
-            "audio_data": "old-audio",
-            "audio_format": "pcm16",
-            "audio_duration_ms": 100,
-            "end_of_turn": False,
-            "model_turn_id": 0,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert close_reason is None
-    assert emitted is False
-    assert session.active_response_id == response_id
-    assert ws.sent == []
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_future_turn_audio_starts_next_response():
-    request_id = "duplex-sid-native-future-turn-audio-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-native-future-turn-audio",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    first_response_id = session.begin_response(turn_id=0)
-    session.bind_request(request_id)
-    ws = TimedWebSocket()
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "tts",
-            "is_listen": False,
-            "data_plane_request_id": request_id,
-            "text": "next",
-            "audio_data": "next-audio",
-            "audio_format": "pcm16",
-            "audio_duration_ms": 100,
-            "end_of_turn": False,
-            "model_turn_id": 1,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert close_reason is None
-    assert emitted is True
-    sent_types = [event["type"] for event in ws.sent]
-    assert sent_types == [
-        "response.done",
-        "response.created",
-        "response.speak",
-        "response.output_audio.delta",
-    ]
-    assert ws.sent[0]["response_id"] == first_response_id
-    assert ws.sent[1]["response_id"] != first_response_id
-    assert ws.sent[3]["response_id"] == ws.sent[1]["response_id"]
-    assert ws.sent[3]["vllm_omni"]["model_turn_id"] == 1
-    assert session.active_response_turn_id == 1
-    assert session.turn_id == 1
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_drops_old_turn_listen_while_new_response_is_active():
-    request_id = "duplex-sid-native-old-turn-listen-e0-stage0"
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(FakeEngineClient()))
-    session = DuplexSession(
-        session_id="sid-native-old-turn-listen",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    response_id = session.begin_response(turn_id=1)
-    session.turn_id = 2
-    session.bind_request(request_id)
-    ws = TimedWebSocket()
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        ws.send_json,
-        {
-            "supported": True,
-            "stage_role": "llm",
-            "is_listen": True,
-            "model_listen": True,
-            "data_plane_request_id": request_id,
-            "end_of_turn": False,
-            "model_turn_id": 0,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-
-    assert close_reason is None
-    assert emitted is False
-    assert session.active_response_id == response_id
-    assert ws.sent == []
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_silence_continuation_requires_active_request():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    session = DuplexSession(
-        session_id="sid-native-stale-continuation",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.begin_response()
-    session.bind_request("duplex-sid-native-stale-continuation-stage0")
-    session.mark_audio_sent(100)
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(data: dict[str, Any]) -> None:
-        sent.append(data)
-
-    _install_direct_silence_scheduler(handler, session)
-
-    await handler._maybe_continue_native_response(send_json, session=session, expected_epoch=session.epoch)
-    session.clear_request()
-    await asyncio.sleep(0.01)
-
-    assert engine.appended == []
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_auto_response_segment_complete_continues_until_model_listen():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    session = DuplexSession(
-        session_id="sid-native-segment-complete",
-        config=DuplexSessionConfig(extra_body={"auto_response": True}),
-    )
-    session.capabilities = minicpmo45_native_capabilities()
-    response_id = session.begin_response()
-    request_id = "duplex-sid-native-segment-complete-stage0"
-    session.bind_request(request_id)
-    session.mark_audio_sent(1000)
-    _install_direct_silence_scheduler(handler, session)
-    sent: list[dict[str, Any]] = []
-
-    async def send_json(data: dict[str, Any]) -> None:
-        sent.append(data)
-
-    close_reason, emitted = await handler._send_one_native_duplex_event(
-        send_json,
-        {
-            "supported": True,
-            "stage_role": "llm",
-            "is_listen": True,
-            "model_listen": False,
-            "listen_source": "auto_response_segment_complete",
-            "reason": "auto_response_segment_complete",
-            "data_plane_request_id": request_id,
-            "end_of_turn": False,
-            "uses_model_runner_scheduler": True,
-            "runner_kv_backed": True,
-            "runtime_impl": "scheduler_data_plane",
-            "owned_runtime": False,
-        },
-        session=session,
-        expected_epoch=session.epoch,
-    )
-    await asyncio.sleep(0.01)
-
-    assert close_reason is None
-    assert emitted is False
-    assert session.active_response_id == response_id
-    assert session.active_request_id == request_id
-    assert not handler._serving_runtime_adapter.data_plane.is_terminal(request_id)
-    assert sent == []
-    assert len(engine.appended) == 1
-    _, mode, payload, final = engine.appended[0]
-    assert mode == "append_audio_chunk"
-    assert payload["type"] == "audio"
-    assert payload.get("force_listen") is not True
-    assert final is False
-
-
-@pytest.mark.parametrize(
-    ("steps", "expected_deltas"),
-    [
-        (
-            [("你好呀", 1), ("你好呀", 1), ("你好呀", 2)],
-            ["你好呀", "", "你好呀"],
-        ),
-        (
-            [("你好呀", 1), ("你好呀", 2)],
-            ["你好呀", "你好呀"],
-        ),
-    ],
-    ids=["turn-scoped", "exact-repeated-turn-text"],
-)
-def test_minicpmo_data_plane_text_cursor(
-    steps: list[tuple[str, int]],
-    expected_deltas: list[str],
-):
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-native-e0-stage0"
-
-    deltas = [data_plane.segment_text_delta(request_id, text, turn_id=turn_id) for text, turn_id in steps]
-
-    assert deltas == expected_deltas
-
-
-def test_minicpmo_data_plane_text_cursor_does_not_clip_prior_turn_overlap():
-    data_plane = _test_data_plane()
-    request_id = "duplex-sid-native-e0-stage0"
-
-    assert data_plane.segment_text_delta(request_id, "你好呀。你有什么想聊的吗？", turn_id=1)
-    assert (
-        data_plane.segment_text_delta(request_id, "你有什么想聊的吗？你好呀。", turn_id=2)
-        == "你有什么想聊的吗？你好呀。"
-    )
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_cancel_interrupts_background_data_plane_stream():
-    control_result = {
-        "operation": "append",
-        "session_id": "sid-native-cancel-stream",
-        "ok": True,
-        "unsupported_count": 0,
-        "error_count": 0,
-        "stage_results": [
-            {
-                "stage_id": 0,
-                "replica_id": 0,
-                "result": {
-                    "supported": True,
-                    "implementation_level": "model_native_duplex",
-                    "data_plane_append": True,
-                    "request_id": "duplex-sid-native-cancel-stream-e0-stage0-s1",
-                    "response_stage_id": 1,
-                },
-            }
-        ],
-    }
-    engine = FakeEngineClient(
-        append_result=control_result,
-        collect_delay_s=0.2,
-        collect_outputs=[
-            [
-                SimpleNamespace(
-                    request_id="duplex-sid-native-cancel-stream-e0-stage0-s1",
-                    finished=True,
-                    outputs=[
-                        SimpleNamespace(
-                            text="",
-                            multimodal_output={"audio": np.zeros(10, dtype=np.float32), "sr": 24000},
-                        )
-                    ],
-                )
-            ]
-        ],
-    )
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-cancel-stream"))
-    ws.put({"type": "input_audio_buffer.append", "audio": "AAAA", "format": "pcm_f32le"})
-    ws.put({"type": "input.cancel"})
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert "audio.cancelled" in ws.sent_types()
-    assert "response.output_audio.delta" not in ws.sent_types()
-    assert engine.signals == [("sid-native-cancel-stream", "barge_in")]
-    assert engine.signal_fences == [DuplexFence("sid-native-cancel-stream")]
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_session_close_discards_partial_pcm_tail():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-short-chunks"))
-    chunk = _pcm_f32_b64(3200)
-    for _ in range(6):
-        ws.put(
-            {
-                "type": "input_audio_buffer.append",
-                "audio": chunk,
-                "format": "pcm_f32le",
-                "sample_rate_hz": 16000,
-            }
-        )
-    ws.put({"type": "session.close"})
-
-    await handler.handle_session(ws)
-
-    assert len(engine.appended) == 1
-    _, mode, payload, final = engine.appended[0]
-    assert mode == "append_audio_chunk"
-    assert final is False
-    assert isinstance(payload, dict)
-    assert len(base64.b64decode(payload["audio"])) == 16000 * 4
-    assert "duplex_num_input_tokens" not in payload
-
-
-@pytest.mark.asyncio
-async def test_minicpmo_native_duplex_idle_timeout_closes_runtime_with_timeout_reason():
-    engine = FakeEngineClient()
-    chat_service = FakeChatService(engine)
-    handler = OmniDuplexSessionHandler(chat_service=chat_service, config_timeout_s=0.1, idle_timeout_s=0.1)
-    ws = TimedWebSocket()
-    ws.put(_native_session_create("sid-native-timeout"))
-
-    await handler.handle_session(ws)
-
-    assert ws.sent_types() == ["session.created", "session.closed"]
-    assert ws.sent[-1]["reason"] == "timeout"
-    assert engine.closed == [("sid-native-timeout", "timeout")]
diff --git a/tests/entrypoints/openai_api/test_qwen3_omni_realtime_websocket.py b/tests/entrypoints/openai_api/test_qwen3_omni_realtime_websocket.py
index be83ea9dbde..d0476b56c14 100644
--- a/tests/entrypoints/openai_api/test_qwen3_omni_realtime_websocket.py
+++ b/tests/entrypoints/openai_api/test_qwen3_omni_realtime_websocket.py
@@ -32,7 +32,7 @@
 from tests.helpers.runtime import OmniServerParams
 from tests.helpers.stage_config import get_deploy_config_path, modify_stage_config
 from vllm_omni.config.stage_config import load_deploy_config
-from vllm_omni.entrypoints.duplex.server_vad import (
+from vllm_omni.engine.duplex.vad import (
     SILERO_VAD_FILENAME,
     SILERO_VAD_REPO_ID,
     SILERO_VAD_REVISION,
diff --git a/tests/entrypoints/openai_api/test_server_vad.py b/tests/entrypoints/openai_api/test_server_vad.py
deleted file mode 100644
index 67476be73d9..00000000000
--- a/tests/entrypoints/openai_api/test_server_vad.py
+++ /dev/null
@@ -1,429 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-import base64
-import io
-import sys
-import threading
-import wave
-import weakref
-from concurrent.futures import ThreadPoolExecutor
-from types import SimpleNamespace
-
-import numpy as np
-import pytest
-
-from vllm_omni.entrypoints.duplex.protocol import (
-    DuplexSession,
-    DuplexSessionConfig,
-)
-from vllm_omni.entrypoints.duplex.server_vad import (
-    ServerVADConfig,
-    ServerVADFrame,
-    ServerVADPipeline,
-    SileroVADBackend,
-    SileroVADBackendProvider,
-    SpeechEndpointDecision,
-    ThresholdEndpointPolicy,
-    parse_session_turn_detection,
-)
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-class SequenceDetector:
-    frame_samples = 160
-
-    def __init__(self, probabilities: list[float]) -> None:
-        self.probabilities = probabilities
-
-    def new_state(self) -> int:
-        return 0
-
-    def infer(self, frame: np.ndarray, state: object) -> tuple[float, object]:
-        index = int(state)
-        probability = self.probabilities[index] if index < len(self.probabilities) else 0.0
-        return probability, index + 1
-
-
-def test_server_vad_config_defaults_and_validation():
-    config = ServerVADConfig.from_value({"type": "server_vad"})
-
-    assert config.type == "server_vad"
-    assert config.threshold == 0.5
-    assert config.prefix_padding_ms == 300
-    assert config.silence_duration_ms == 500
-    assert config.create_response is True
-    assert config.interrupt_response is None
-    assert "interrupt_response" not in config.as_dict()
-    assert config.min_speech_duration_ms is None
-    assert config.as_dict()["type"] == config.type
-
-    interrupting = ServerVADConfig.from_value(
-        {
-            "type": "server_vad",
-            "interrupt_response": True,
-            "min_speech_duration_ms": 96,
-        }
-    )
-    assert interrupting.interrupt_response is True
-    assert interrupting.min_speech_duration_ms == 96
-    for value in (None, 0, "true"):
-        with pytest.raises(ValueError, match="interrupt_response must be a boolean"):
-            ServerVADConfig.from_value({"type": "server_vad", "interrupt_response": value})
-    for enabled in (False, True):
-        _, aliased = parse_session_turn_detection(
-            {
-                "turn_detection": {"type": "server_vad"},
-                "audio": {"input": {"turn_detection": {"type": "server_vad", "interrupt_response": enabled}}},
-            }
-        )
-        assert aliased is not None and aliased.interrupt_response is enabled
-    with pytest.raises(ValueError, match="Unknown"):
-        ServerVADConfig.from_value({"type": "server_vad", "semantic_eagerness": "high"})
-
-
-@pytest.mark.asyncio
-@pytest.mark.parametrize("prefix_padding_ms", [0, 10, 30])
-async def test_server_vad_pipeline_handles_arbitrary_chunk_boundaries(prefix_padding_ms: int):
-    detector = SequenceDetector([0.0, 0.9, 0.8, 0.0, 0.0])
-    pipeline = ServerVADPipeline(
-        detector,
-        ServerVADConfig(prefix_padding_ms=prefix_padding_ms, silence_duration_ms=20),
-    )
-    samples = np.zeros(detector.frame_samples * 5, dtype=np.float32)
-
-    batches = [
-        await pipeline.push(samples[:73]),
-        await pipeline.push(samples[73:431]),
-        await pipeline.push(samples[431:]),
-    ]
-    frames = [frame for batch in batches for frame in batch.frames]
-
-    assert len(frames) == 5
-    assert [index for index, frame in enumerate(frames) if frame.decision.speech_started] == [1]
-    assert [index for index, frame in enumerate(frames) if frame.decision.speech_stopped] == [4]
-    assert frames[1].decision.audio_start_ms == max(0, 10 - prefix_padding_ms)
-    assert frames[4].decision.audio_end_ms == 50
-
-    pipeline.reset()
-    reset_batch = await pipeline.push(samples)
-    assert [index for index, frame in enumerate(reset_batch.frames) if frame.decision.speech_started] == [1]
-    assert [index for index, frame in enumerate(reset_batch.frames) if frame.decision.speech_stopped] == [4]
-    # Keep session-relative timestamps, but never reference prefix audio
-    # discarded by reset at 50 ms.
-    assert reset_batch.frames[1].decision.audio_start_ms == max(50, 60 - prefix_padding_ms)
-    assert reset_batch.frames[4].decision.audio_end_ms == 100
-
-
-@pytest.mark.asyncio
-async def test_server_vad_retained_audio_does_not_keep_input_chunk():
-    pipeline = ServerVADPipeline(SequenceDetector([]), ServerVADConfig())
-    session = DuplexSession("server-vad-memory", DuplexSessionConfig())
-    samples = np.zeros(160 * 100 + 1, dtype=np.float32)
-    source_ref = weakref.ref(samples)
-    batch = await pipeline.push(samples)
-    session.append_server_vad_frame(
-        batch.frames[-1].samples,
-        speech_started=False,
-        speech_stopped=False,
-        prefix_samples=80,
-    )
-    session.append_server_vad_frame(
-        batch.frames[-1].samples,
-        speech_started=True,
-        speech_stopped=False,
-        prefix_samples=80,
-    )
-    del batch, samples
-    # Allow the completed to_thread callback to release its result, too.
-    await asyncio.sleep(0)
-
-    assert source_ref() is None
-    assert pipeline.scratch_bytes == 4
-    assert session.server_vad_utterance_bytes == (80 + 160) * 4
-
-
-@pytest.mark.asyncio
-async def test_server_vad_pipeline_pcm16_resampling_is_split_invariant():
-    sample_index = np.arange(2_400, dtype=np.int32)
-    source = ((sample_index * 7919) % 65_536 - 32_768).astype("<i2")
-    # Supply ample silence after the signal so the streaming resampler can
-    # emit a complete set of VAD frames without depending on its FIR width.
-    right_context = np.zeros(240, dtype="<i2")
-    continuous_source = np.concatenate((source, right_context))
-
-    async def process(chunk_sizes: list[int]) -> tuple[np.ndarray, list[SpeechEndpointDecision]]:
-        pipeline = ServerVADPipeline(
-            SequenceDetector([0.0] * 10),
-            ServerVADConfig(),
-        )
-        frames: list[ServerVADFrame] = []
-        offset = 0
-        for chunk_size in chunk_sizes:
-            chunk = continuous_source[offset : offset + chunk_size]
-            batch = await pipeline.push_pcm16(chunk.tobytes(), source_sample_rate_hz=24_000)
-            frames.extend(batch.frames)
-            offset += chunk_size
-        assert offset == continuous_source.size
-        return np.concatenate([frame.samples for frame in frames]), [frame.decision for frame in frames]
-
-    whole_samples, whole_decisions = await process([continuous_source.size])
-    split_samples, split_decisions = await process([7, 13, 511, 512, 513, continuous_source.size - 1_556])
-
-    np.testing.assert_array_equal(split_samples, whole_samples)
-    assert whole_samples.size == 1_600
-    assert split_decisions == whole_decisions
-
-
-@pytest.mark.asyncio
-async def test_server_vad_pipeline_reset_clears_resampler_and_source_rate_lock():
-    pipeline = ServerVADPipeline(
-        SequenceDetector([0.0]),
-        ServerVADConfig(),
-    )
-
-    batch = await pipeline.push_pcm16(
-        np.asarray([30_000, -30_000], dtype="<i2").tobytes(),
-        source_sample_rate_hz=24_000,
-    )
-    assert not batch.frames
-
-    pipeline.reset()
-
-    source = np.zeros(160, dtype="<i2")
-    source[:3] = [-32768, 0, 32767]
-    batch = await pipeline.push_pcm16(source.tobytes(), source_sample_rate_hz=16_000)
-
-    assert len(batch.frames) == 1
-    np.testing.assert_array_equal(
-        batch.frames[0].samples[:3],
-        np.asarray([-1.0, 0.0, 32767 / 32768], dtype=np.float32),
-    )
-
-
-def test_threshold_endpoint_policy_uses_silero_v62_exit_hysteresis():
-    policy = ThresholdEndpointPolicy(
-        ServerVADConfig(threshold=0.5, silence_duration_ms=20),
-        sample_rate_hz=16_000,
-    )
-    frame_samples = 160
-
-    started = policy.update(0.8, frame_start_sample=0, frame_samples=frame_samples)
-    assert started.speech_started is True
-
-    # Values below the activation threshold but above threshold - 0.15 must
-    # not begin a silence candidate or close an active speech segment.
-    for frame_index in range(1, 5):
-        decision = policy.update(
-            0.4,
-            frame_start_sample=frame_index * frame_samples,
-            frame_samples=frame_samples,
-        )
-        assert decision.speech_stopped is False
-
-    first_silence = policy.update(
-        0.2,
-        frame_start_sample=5 * frame_samples,
-        frame_samples=frame_samples,
-    )
-    stopped = policy.update(
-        0.2,
-        frame_start_sample=6 * frame_samples,
-        frame_samples=frame_samples,
-    )
-
-    assert first_silence.speech_stopped is False
-    assert stopped.speech_stopped is True
-
-
-def test_threshold_endpoint_policy_honors_minimum_speech_duration():
-    policy = ThresholdEndpointPolicy(
-        ServerVADConfig(prefix_padding_ms=0, min_speech_duration_ms=25),
-        sample_rate_hz=16_000,
-    )
-    frame_samples = 160
-
-    assert not policy.update(0.9, frame_start_sample=0, frame_samples=frame_samples).speech_started
-    assert not policy.update(0.9, frame_start_sample=160, frame_samples=frame_samples).speech_started
-    started = policy.update(0.9, frame_start_sample=320, frame_samples=frame_samples)
-
-    assert started.speech_started is True
-    assert started.audio_start_ms == 0
-
-
-def test_threshold_endpoint_policy_clamps_silero_exit_threshold():
-    policy = ThresholdEndpointPolicy(
-        ServerVADConfig(threshold=0.1, silence_duration_ms=20),
-        sample_rate_hz=16_000,
-    )
-    frame_samples = 160
-
-    started = policy.update(0.9, frame_start_sample=0, frame_samples=frame_samples)
-    assert started.speech_started is True
-
-    first_silence = policy.update(
-        0.0,
-        frame_start_sample=frame_samples,
-        frame_samples=frame_samples,
-    )
-    stopped = policy.update(
-        0.0,
-        frame_start_sample=2 * frame_samples,
-        frame_samples=frame_samples,
-    )
-
-    assert first_silence.speech_stopped is False
-    assert stopped.speech_stopped is True
-    # The committed audio ends at 30 ms: 10 ms of speech followed by the
-    # 20 ms of silence required to detect the endpoint.
-    assert stopped.audio_end_ms == 30
-    assert stopped.endpoint_delay_ms == 20
-
-
-def test_silero_backend_matches_upstream_v62_streaming_contract(monkeypatch, tmp_path):
-    class FakeSessionOptions:
-        inter_op_num_threads = 0
-        intra_op_num_threads = 0
-
-    class FakeInferenceSession:
-        def __init__(self, path: str, *, providers: list[str], sess_options: object) -> None:
-            self.providers = providers
-            self.sess_options = sess_options
-            self.calls: list[dict[str, np.ndarray]] = []
-            self.run_barrier: threading.Barrier | None = None
-            sessions.append(self)
-
-        def get_inputs(self) -> list[SimpleNamespace]:
-            return [SimpleNamespace(name=name) for name in ("input", "state", "sr")]
-
-        def run(self, _outputs: object, inputs: dict[str, np.ndarray]) -> list[np.ndarray]:
-            self.calls.append({name: np.array(value, copy=True) for name, value in inputs.items()})
-            if self.run_barrier is not None:
-                self.run_barrier.wait(timeout=5)
-            return [
-                np.asarray([[0.75]], dtype=np.float32),
-                np.full((2, 1, 128), len(self.calls), dtype=np.float32),
-            ]
-
-    sessions: list[FakeInferenceSession] = []
-    monkeypatch.setitem(
-        sys.modules,
-        "onnxruntime",
-        SimpleNamespace(
-            SessionOptions=FakeSessionOptions,
-            InferenceSession=FakeInferenceSession,
-        ),
-    )
-
-    model_path = tmp_path / "silero_vad.onnx"
-    model_path.write_bytes(b"fake-model")
-    backend = SileroVADBackend(model_path)
-    session = sessions[0]
-
-    assert session.providers == ["CPUExecutionProvider"]
-    assert session.sess_options.inter_op_num_threads == 1
-    assert session.sess_options.intra_op_num_threads == 1
-    assert session.calls[0]["input"].shape == (1, 576)
-    assert session.calls[0]["state"].shape == (2, 1, 128)
-    np.testing.assert_array_equal(session.calls[0]["state"], np.zeros((2, 1, 128), dtype=np.float32))
-    assert session.calls[0]["sr"].shape == ()
-    assert session.calls[0]["sr"].item() == 16_000
-
-    state = backend.new_state()
-    first_frame = np.arange(backend.frame_samples, dtype=np.float32)
-    probability, state = backend.infer(first_frame, state)
-    first_call = session.calls[1]
-
-    assert probability == pytest.approx(0.75)
-    np.testing.assert_array_equal(
-        first_call["input"][:, : backend.context_samples],
-        np.zeros((1, backend.context_samples), dtype=np.float32),
-    )
-    np.testing.assert_array_equal(
-        first_call["input"][:, backend.context_samples :],
-        first_frame[None, :],
-    )
-    np.testing.assert_array_equal(first_call["state"], np.zeros((2, 1, 128), dtype=np.float32))
-
-    second_frame = -first_frame
-    backend.infer(second_frame, state)
-    second_call = session.calls[2]
-    np.testing.assert_array_equal(
-        second_call["input"][:, : backend.context_samples],
-        first_frame[None, -backend.context_samples :],
-    )
-    np.testing.assert_array_equal(
-        second_call["input"][:, backend.context_samples :],
-        second_frame[None, :],
-    )
-    np.testing.assert_array_equal(
-        second_call["state"],
-        np.full((2, 1, 128), 2, dtype=np.float32),
-    )
-
-    # Independent pipeline states may enter the shared ORT session concurrently.
-    session.run_barrier = threading.Barrier(2)
-    with ThreadPoolExecutor(max_workers=2) as executor:
-        futures = [
-            executor.submit(backend.infer, first_frame, backend.new_state()),
-            executor.submit(backend.infer, second_frame, backend.new_state()),
-        ]
-        assert [future.result()[0] for future in futures] == pytest.approx([0.75, 0.75])
-
-
-def test_duplex_session_owns_server_vad_prefix_and_utterance_audio():
-    session = DuplexSession("server-vad-session", DuplexSessionConfig())
-    frame = np.zeros(160, dtype=np.float32)
-
-    session.reserve_input_bytes(frame.nbytes * 3, limit=frame.nbytes * 4)
-    released = session.append_server_vad_frame(
-        frame,
-        speech_started=False,
-        speech_stopped=False,
-        prefix_samples=160,
-    )
-    assert released == 0
-    released = session.append_server_vad_frame(
-        frame,
-        speech_started=False,
-        speech_stopped=False,
-        prefix_samples=160,
-    )
-    assert released == frame.nbytes
-    session.release_input_bytes(released)
-    session.append_server_vad_frame(
-        frame,
-        speech_started=True,
-        speech_stopped=False,
-        prefix_samples=160,
-    )
-
-    assert session.server_vad_utterance_bytes == frame.nbytes * 2
-    assert session.stage_server_vad_audio_for_commit() is True
-    committed = session.commit_user_input()
-    assert committed is not None
-    assert committed.message["role"] == "user"
-    audio_url = committed.message["content"][0]["audio_url"]["url"]
-    assert audio_url.startswith("data:audio/wav;base64,")
-    wav_bytes = base64.b64decode(audio_url.partition(",")[2])
-    with wave.open(io.BytesIO(wav_bytes), "rb") as wav_file:
-        assert wav_file.getnchannels() == 1
-        assert wav_file.getsampwidth() == 2
-        assert wav_file.getframerate() == 16_000
-        assert wav_file.getnframes() == frame.size * 2
-
-
-def test_silero_provider_rejects_missing_or_invalid_local_artifact(tmp_path):
-    missing = SileroVADBackendProvider(model_path=str(tmp_path / "missing.onnx"))
-    with pytest.raises(RuntimeError, match="does not exist"):
-        missing.get()
-
-    invalid_path = tmp_path / "silero_vad.onnx"
-    invalid_path.write_bytes(b"not-the-pinned-model")
-    invalid = SileroVADBackendProvider(model_path=str(invalid_path))
-    with pytest.raises(RuntimeError, match="checksum mismatch"):
-        invalid.get()
diff --git a/tests/entrypoints/test_async_omni_diffusion_config.py b/tests/entrypoints/test_async_omni_diffusion_config.py
index dda9ab38c82..3b378930ab3 100644
--- a/tests/entrypoints/test_async_omni_diffusion_config.py
+++ b/tests/entrypoints/test_async_omni_diffusion_config.py
@@ -674,7 +674,7 @@ def test_resolve_stage_configs_delegates_overrides_to_resolver(mocker):
         engine_args=SimpleNamespace(additional_config=additional_config),
     )
     resolve_config = mocker.patch(
-        "vllm_omni.engine.async_omni_engine.resolve_omni_config",
+        "vllm_omni.engine.omni_engine_base.resolve_omni_config",
         return_value=OmniConfigResolution(
             config_path="dummy.yaml",
             stage_configs=(fake_diffusion_stage,),
diff --git a/tests/entrypoints/test_async_omni_duplex.py b/tests/entrypoints/test_async_omni_duplex.py
deleted file mode 100644
index 81e0d75cb49..00000000000
--- a/tests/entrypoints/test_async_omni_duplex.py
+++ /dev/null
@@ -1,601 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from types import SimpleNamespace
-
-import pytest
-
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.runtime import (
-    DuplexOutputAction,
-    DuplexOutputDecision,
-    duplex_resource_request_id,
-)
-from vllm_omni.engine.messages import OutputMessage
-from vllm_omni.entrypoints.async_omni import AsyncOmni
-from vllm_omni.entrypoints.client_request_state import ClientRequestState
-from vllm_omni.entrypoints.duplex_request_client import DuplexRequestClient
-from vllm_omni.metrics.stats import OrchestratorAggregator, StageRequestStats, StageStats
-from vllm_omni.outputs import OmniRequestOutput
-from vllm_omni.outputs.duplex import attach_duplex_output_decision
-
-
-def test_async_omni_uses_extracted_duplex_request_client():
-    app = object.__new__(AsyncOmni)
-    app.engine = SimpleNamespace(num_stages=2)
-    app.request_states = {}
-    app._duplex_request_client = None
-
-    client = app._get_duplex_request_client()
-
-    assert isinstance(client, DuplexRequestClient)
-    assert not hasattr(client, "_async_omni")
-
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-@pytest.mark.asyncio
-async def test_async_omni_open_duplex_forwards_session_config_and_timeout():
-    calls = []
-    output_handler_starts = 0
-
-    async def open_duplex_session_async(session_id, **kwargs):
-        calls.append((session_id, kwargs))
-        return {"ok": True}
-
-    app = object.__new__(AsyncOmni)
-    app.engine = SimpleNamespace(open_duplex_session_async=open_duplex_session_async)
-
-    def start_output_handler():
-        nonlocal output_handler_starts
-        output_handler_starts += 1
-
-    app._final_output_handler = start_output_handler
-
-    result = await app.open_duplex_session_async(
-        "sid",
-        fence=DuplexFence("sid"),
-        capabilities={"implementation_level": "model_native_duplex"},
-        session_config={"instructions": "Be brief.", "idle_timeout_s": 30},
-        timeout=7.5,
-    )
-
-    assert result == {"ok": True}
-    assert output_handler_starts == 1
-    assert calls == [
-        (
-            "sid",
-            {
-                "session_mode": "duplex",
-                "capabilities": {"implementation_level": "model_native_duplex"},
-                "session_config": {"instructions": "Be brief.", "idle_timeout_s": 30},
-                "fence": DuplexFence("sid"),
-                "timeout": 7.5,
-            },
-        )
-    ]
-
-
-@pytest.mark.asyncio
-async def test_async_omni_duplex_runtime_controls_forward_timeout():
-    calls = []
-    cancelled_fence = DuplexFence("sid", epoch=2, turn_id=3)
-    next_fence = DuplexFence("sid", epoch=3, turn_id=3)
-
-    async def append_duplex_input_async(session_id, **kwargs):
-        calls.append(("append", session_id, kwargs))
-        return {"ok": True}
-
-    async def signal_duplex_turn_async(session_id, **kwargs):
-        calls.append(("signal", session_id, kwargs))
-        return {"ok": True}
-
-    async def close_duplex_session_async(session_id, **kwargs):
-        calls.append(("close", session_id, kwargs))
-        return {"ok": True}
-
-    async def touch_duplex_session_async(session_id, **kwargs):
-        calls.append(("touch", session_id, kwargs))
-        return {"ok": True}
-
-    async def resume_duplex_session_async(session_id, **kwargs):
-        calls.append(("resume", session_id, kwargs))
-        return {"ok": True}
-
-    app = object.__new__(AsyncOmni)
-    app.request_states = {}
-    app._final_output_handler = lambda: None
-    app.engine = SimpleNamespace(
-        append_duplex_input_async=append_duplex_input_async,
-        signal_duplex_turn_async=signal_duplex_turn_async,
-        close_duplex_session_async=close_duplex_session_async,
-        touch_duplex_session_async=touch_duplex_session_async,
-        resume_duplex_session_async=resume_duplex_session_async,
-    )
-
-    await app.append_duplex_input_async(
-        "sid",
-        mode="append_audio_chunk",
-        payload={},
-        fence=cancelled_fence,
-        timeout=12.5,
-    )
-    await app.signal_duplex_turn_async(
-        "sid",
-        event="barge_in",
-        fence=cancelled_fence,
-        next_fence=next_fence,
-        timeout=13.5,
-    )
-    await app.close_duplex_session_async("sid", reason="done", fence=next_fence, timeout=14.5)
-    await app.touch_duplex_session_async(
-        "sid",
-        fence=next_fence,
-        activity=DuplexLeaseActivity.HEARTBEAT,
-        timeout=15.5,
-    )
-    await app.resume_duplex_session_async(
-        "sid",
-        fence=next_fence,
-        expected_lease_generation=3,
-        timeout=16.5,
-    )
-
-    assert calls == [
-        (
-            "append",
-            "sid",
-            {
-                "mode": "append_audio_chunk",
-                "payload": {},
-                "final": False,
-                "expected_epoch": None,
-                "fence": cancelled_fence,
-                "timeout": 12.5,
-            },
-        ),
-        (
-            "signal",
-            "sid",
-            {
-                "event": "barge_in",
-                "fence": cancelled_fence,
-                "next_fence": next_fence,
-                "timeout": 13.5,
-            },
-        ),
-        (
-            "close",
-            "sid",
-            {
-                "reason": "done",
-                "fence": next_fence,
-                "timeout": 14.5,
-            },
-        ),
-        (
-            "touch",
-            "sid",
-            {
-                "fence": next_fence,
-                "activity": DuplexLeaseActivity.HEARTBEAT,
-                "timeout": 15.5,
-            },
-        ),
-        (
-            "resume",
-            "sid",
-            {
-                "fence": next_fence,
-                "expected_lease_generation": 3,
-                "timeout": 16.5,
-            },
-        ),
-    ]
-
-
-@pytest.mark.asyncio
-async def test_async_omni_duplex_append_can_defer_data_plane_output_collection():
-    app = object.__new__(AsyncOmni)
-    request_id = duplex_resource_request_id(DuplexFence("sid"), "stage0")
-
-    async def append_duplex_input_async(session_id, **kwargs):
-        del session_id, kwargs
-        request_state = app.request_states.get(request_id)
-        assert request_state is not None
-        assert request_state.metrics is not None
-        return {
-            "stage_results": [
-                {
-                    "result": {
-                        "data_plane_append": True,
-                        "request_id": request_id,
-                        "response_stage_id": 1,
-                    }
-                }
-            ]
-        }
-
-    app.engine = SimpleNamespace(append_duplex_input_async=append_duplex_input_async)
-    app.request_states = {}
-    app._final_output_handler = lambda: None
-
-    result = await app.append_duplex_input_async(
-        "sid",
-        mode="append_audio_chunk",
-        payload={},
-        fence=DuplexFence("sid"),
-        collect_outputs=False,
-    )
-
-    assert "data_plane_outputs" not in result
-
-
-@pytest.mark.asyncio
-async def test_async_omni_duplex_append_forwards_fence():
-    calls = []
-
-    async def append_duplex_input_async(session_id, **kwargs):
-        calls.append((session_id, kwargs))
-        return {"ok": True}
-
-    app = object.__new__(AsyncOmni)
-    app.request_states = {}
-    app._final_output_handler = lambda: None
-    app.engine = SimpleNamespace(append_duplex_input_async=append_duplex_input_async)
-    fence = DuplexFence("sid", epoch=1, turn_id=2)
-
-    await app.append_duplex_input_async(
-        "sid",
-        mode="append_audio_chunk",
-        payload={},
-        fence=fence,
-        collect_outputs=False,
-    )
-
-    assert calls[0][1]["fence"] is fence
-
-
-@pytest.mark.asyncio
-async def test_async_omni_duplex_collect_waits_for_response_stage():
-    app = object.__new__(AsyncOmni)
-    req_state = ClientRequestState("duplex-sid-e0-stage0")
-    stage0_output = OmniRequestOutput(
-        request_id="duplex-sid-e0-stage0",
-        stage_id=0,
-        finished=False,
-    )
-    stage1_output = OmniRequestOutput(
-        request_id="duplex-sid-e0-stage0",
-        stage_id=1,
-        final_output_type="audio",
-        finished=False,
-    )
-    await req_state.queue.put(
-        OutputMessage(
-            request_id="duplex-sid-e0-stage0",
-            stage_id=0,
-            engine_outputs=stage0_output,
-            finished=False,
-        )
-    )
-    await req_state.queue.put(
-        OutputMessage(
-            request_id="duplex-sid-e0-stage0",
-            stage_id=1,
-            engine_outputs=stage1_output,
-            finished=False,
-        )
-    )
-
-    outputs = await app._collect_duplex_data_plane_outputs(
-        "duplex-sid-e0-stage0",
-        req_state,
-        response_stage_id=1,
-        timeout=1.0,
-    )
-
-    assert outputs == [stage1_output]
-
-
-@pytest.mark.asyncio
-async def test_duplex_request_client_retains_output_route_at_segment_terminal():
-    request_id = "duplex-sid-e0-stage0"
-    request_state = ClientRequestState(request_id)
-    request_states = {request_id: request_state}
-    output = OmniRequestOutput(
-        request_id=request_id,
-        stage_id=1,
-        final_output_type="audio",
-        finished=True,
-    )
-    await request_state.queue.put(
-        OutputMessage(
-            request_id=request_id,
-            stage_id=1,
-            engine_outputs=output,
-            finished=True,
-        )
-    )
-    client = DuplexRequestClient(
-        SimpleNamespace(),
-        SimpleNamespace(
-            request_states=request_states,
-            num_stages=2,
-            log_stats=False,
-        ),
-    )
-
-    outputs = await client.collect_outputs(
-        request_id,
-        request_state,
-        response_stage_id=1,
-        timeout=1.0,
-    )
-
-    assert outputs == [output]
-    assert request_states[request_id] is request_state
-
-
-@pytest.mark.asyncio
-async def test_async_omni_duplex_direct_output_keeps_stage_metrics():
-    app = object.__new__(AsyncOmni)
-    app._duplex_request_client = None
-    app._final_output_handler = lambda: None
-    request_id = "duplex-sid-e0-stage0"
-    req_state = ClientRequestState(request_id)
-    decision = DuplexOutputDecision(
-        action=DuplexOutputAction.DIRECT_RESPONSE,
-        metadata={
-            "duplex_direct_response": True,
-            "duplex_native_decision": "speak",
-        },
-    )
-    direct_output = attach_duplex_output_decision(
-        OmniRequestOutput(
-            request_id=request_id,
-            stage_id=0,
-            final_output_type="text",
-            finished=True,
-        ),
-        decision,
-    )
-    await req_state.queue.put(
-        OutputMessage(
-            request_id=request_id,
-            stage_id=0,
-            engine_outputs=direct_output,
-            metrics=StageRequestStats(
-                batch_id=1,
-                batch_size=1,
-                num_tokens_in=160,
-                num_tokens_out=8,
-                stage_gen_time_ms=80.0,
-                rx_transfer_bytes=0,
-                rx_decode_time_ms=0.0,
-                rx_in_flight_time_ms=0.0,
-                stage_stats=StageStats(total_token=8, total_gen_time_ms=80.0),
-                vllm_ttft_ms=12.5,
-                vllm_tpot_ms=9.0,
-                vllm_itl_ms=8.75,
-                vllm_itls_ms=[8.0, 9.5],
-            ),
-            finished=True,
-        )
-    )
-
-    outputs = await app._collect_duplex_data_plane_outputs(
-        request_id,
-        req_state,
-        response_stage_id=1,
-        timeout=1.0,
-    )
-
-    assert outputs == [direct_output]
-    assert direct_output.metrics["stage_metrics"]["0"]["vllm_ttft_ms"] == 12.5
-    assert direct_output.metrics["stage_metrics"]["0"]["vllm_tpot_ms"] == 9.0
-    assert direct_output.metrics["stage_metrics"]["0"]["vllm_itls_ms"] == [8.0, 9.5]
-
-
-@pytest.mark.asyncio
-async def test_duplex_metrics_cursor_isolates_resumable_collect_windows():
-    app = object.__new__(AsyncOmni)
-    app._duplex_request_client = None
-    app._final_output_handler = lambda: None
-    request_id = "duplex-sid-e0-stage0"
-    req_state = ClientRequestState(request_id)
-    req_state.metrics = OrchestratorAggregator(
-        num_stages=2,
-        log_stats=False,
-        wall_start_ts=0.0,
-        final_stage_id_for_e2e=1,
-    )
-
-    def stage_message(*, batch_id: int, tokens: int, ttft_ms: float, itls: list[float]) -> OutputMessage:
-        decision = DuplexOutputDecision(
-            action=DuplexOutputAction.DIRECT_RESPONSE,
-            metadata={"duplex_direct_response": True, "duplex_native_decision": "speak"},
-        )
-        output = attach_duplex_output_decision(
-            OmniRequestOutput(
-                request_id=request_id,
-                stage_id=0,
-                final_output_type="text",
-                finished=True,
-            ),
-            decision,
-        )
-        return OutputMessage(
-            request_id=request_id,
-            stage_id=0,
-            engine_outputs=output,
-            metrics=StageRequestStats(
-                batch_id=batch_id,
-                batch_size=1,
-                num_tokens_in=160,
-                num_tokens_out=tokens,
-                stage_gen_time_ms=80.0,
-                rx_transfer_bytes=0,
-                rx_decode_time_ms=0.0,
-                rx_in_flight_time_ms=0.0,
-                stage_stats=StageStats(total_token=tokens, total_gen_time_ms=80.0),
-                vllm_ttft_ms=ttft_ms,
-                vllm_tpot_ms=9.0,
-                vllm_itl_ms=sum(itls) / len(itls),
-                vllm_itls_ms=itls,
-            ),
-            finished=True,
-        )
-
-    await req_state.queue.put(stage_message(batch_id=1, tokens=71, ttft_ms=62.5, itls=[10.0, 11.0]))
-    first = await app._collect_duplex_data_plane_outputs(
-        request_id,
-        req_state,
-        response_stage_id=1,
-        timeout=1.0,
-    )
-    await req_state.queue.put(stage_message(batch_id=2, tokens=155, ttft_ms=81.0, itls=[12.0, 13.0, 14.0]))
-    second = await app._collect_duplex_data_plane_outputs(
-        request_id,
-        req_state,
-        response_stage_id=1,
-        timeout=1.0,
-    )
-
-    assert first[0].metrics["stage_metrics"]["0"]["num_tokens_out"] == 71
-    second_stage0 = second[0].metrics["stage_metrics"]["0"]
-    assert second_stage0["num_tokens_out"] == 155
-    assert second_stage0["vllm_ttft_ms"] == 81.0
-    assert second_stage0["vllm_itls_ms"] == [12.0, 13.0, 14.0]
-
-
-def test_async_omni_duplex_direct_output_prefers_outer_control_metadata():
-    decision = DuplexOutputDecision(
-        action=DuplexOutputAction.DIRECT_RESPONSE,
-        metadata={
-            "duplex_direct_response": True,
-            "duplex_native_decision": "listen",
-        },
-    )
-    output = attach_duplex_output_decision(
-        OmniRequestOutput(
-            request_id="duplex-sid-e0-stage0",
-            stage_id=0,
-            outputs=[],
-            _multimodal_output={"kind": "processed-payload"},
-            _custom_output={"inner": "completion"},
-        ),
-        decision,
-    )
-
-    assert AsyncOmni._is_direct_duplex_data_plane_response(output)
-
-
-def test_async_omni_drops_unregistered_duplex_prefixed_output():
-    app = object.__new__(AsyncOmni)
-    app.request_states = {}
-    output = OmniRequestOutput(request_id="duplex-unregistered-e0-stage0", stage_id=0)
-
-    keep_processing, request_id, stage_id, request_state = app._handle_output_message(
-        OutputMessage(
-            request_id=output.request_id,
-            stage_id=0,
-            engine_outputs=output,
-            finished=False,
-        )
-    )
-
-    assert keep_processing is True
-    assert request_id is stage_id is request_state is None
-    assert app.request_states == {}
-
-
-@pytest.mark.asyncio
-async def test_async_omni_duplex_collect_wraps_raw_response_stage_output():
-    app = object.__new__(AsyncOmni)
-    app.log_stats = False
-    app._enable_ar_profiler = False
-    app.request_states = {}
-    app.prom_metrics = SimpleNamespace(
-        set_running=lambda value: None,
-        set_waiting=lambda value: None,
-    )
-    app.engine = SimpleNamespace(
-        num_stages=2,
-        get_stage_metadata=lambda stage_id: SimpleNamespace(
-            final_output=stage_id == 1,
-            final_output_type="audio",
-        ),
-    )
-    req_state = ClientRequestState("duplex-sid-e0-stage0")
-    raw_stage1_output = SimpleNamespace(
-        finished=False,
-        outputs=[],
-        stage_durations={},
-        peak_memory_mb=0.0,
-        final_output_type="audio",
-    )
-    await req_state.queue.put(
-        OutputMessage(
-            request_id="duplex-sid-e0-stage0",
-            stage_id=1,
-            engine_outputs=raw_stage1_output,
-            finished=False,
-        )
-    )
-
-    outputs = await app._collect_duplex_data_plane_outputs(
-        "duplex-sid-e0-stage0",
-        req_state,
-        response_stage_id=1,
-        timeout=1.0,
-    )
-
-    assert len(outputs) == 1
-    assert outputs[0].request_id == "duplex-sid-e0-stage0"
-    assert outputs[0].finished is False
-    assert outputs[0].stage_id == 1
-    assert outputs[0].final_output_type == "audio"
-    assert outputs[0].peak_memory_mb == raw_stage1_output.peak_memory_mb
-
-
-def test_async_omni_duplex_request_info_includes_response_stage():
-    request_id, response_stage_id = AsyncOmni._duplex_data_plane_request_info(
-        {
-            "stage_results": [
-                {
-                    "result": {
-                        "data_plane_append": True,
-                        "request_id": "duplex-sid-e0-stage0",
-                        "response_stage_id": 1,
-                    }
-                }
-            ]
-        }
-    )
-
-    assert request_id == "duplex-sid-e0-stage0"
-    assert response_stage_id == 1
-
-
-@pytest.mark.asyncio
-async def test_duplex_request_client_retains_output_route_when_close_fails():
-    fence = DuplexFence("sid-close-route")
-    request_id = duplex_resource_request_id(fence, "stage0")
-    request_states = {request_id: ClientRequestState(request_id)}
-
-    async def close_duplex_session_async(session_id, **kwargs):
-        del session_id, kwargs
-        raise RuntimeError("close failed")
-
-    client = DuplexRequestClient(
-        SimpleNamespace(close_duplex_session_async=close_duplex_session_async),
-        SimpleNamespace(request_states=request_states),
-    )
-
-    with pytest.raises(RuntimeError, match="close failed"):
-        await client.close(fence.session_id, reason="test", fence=fence, timeout=1.0)
-
-    assert request_id in request_states
diff --git a/tests/entrypoints/test_disable_log_stats_routing.py b/tests/entrypoints/test_disable_log_stats_routing.py
index f9dd2da4af0..623cc9af4ea 100644
--- a/tests/entrypoints/test_disable_log_stats_routing.py
+++ b/tests/entrypoints/test_disable_log_stats_routing.py
@@ -53,7 +53,7 @@ def fake_resolve(model: str, kwargs: dict[str, Any], **unused: Any) -> OmniConfi
         )
 
     monkeypatch.setattr(
-        "vllm_omni.engine.async_omni_engine.load_and_resolve_stage_configs",
+        "vllm_omni.engine.omni_engine_base.load_and_resolve_stage_configs",
         fake_resolve,
     )
     engine = SimpleNamespace(_apply_strategy_lb_policy=lambda *args, **kwargs: None)
diff --git a/tests/entrypoints/test_duplex_fence_propagation.py b/tests/entrypoints/test_duplex_fence_propagation.py
deleted file mode 100644
index 550723ec829..00000000000
--- a/tests/entrypoints/test_duplex_fence_propagation.py
+++ /dev/null
@@ -1,126 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-import pytest
-
-from tests.entrypoints.openai_api.test_duplex_handler import FakeChatService, TimedWebSocket
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.entrypoints.async_omni import AsyncOmni
-from vllm_omni.entrypoints.duplex.protocol import DuplexSession, DuplexSessionConfig
-from vllm_omni.entrypoints.duplex.serving import OmniDuplexSessionHandler
-
-pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
-
-
-class FenceRecordingEngine:
-    output_modalities = ["text", "audio"]
-
-    def __init__(self) -> None:
-        self.calls: list[tuple[str, DuplexFence | None]] = []
-        self.signal_next_fences: list[DuplexFence | None] = []
-
-    async def open_duplex_session_async(self, session_id, *, fence=None, **kwargs):
-        del session_id, kwargs
-        self.calls.append(("open", fence))
-        return {"ok": True}
-
-    async def append_duplex_input_async(self, session_id, *, fence=None, **kwargs):
-        del session_id, kwargs
-        self.calls.append(("append", fence))
-        return {"ok": True}
-
-    async def signal_duplex_turn_async(
-        self,
-        session_id,
-        *,
-        event,
-        fence=None,
-        next_fence=None,
-        timeout=None,
-    ):
-        del session_id, event, timeout
-        self.calls.append(("signal", fence))
-        self.signal_next_fences.append(next_fence)
-        return {"ok": True}
-
-    async def close_duplex_session_async(self, session_id, *, fence=None, **kwargs):
-        del session_id, kwargs
-        self.calls.append(("close", fence))
-        return {"ok": True}
-
-
-@pytest.mark.asyncio
-async def test_async_omni_forwards_fence_for_all_runtime_operations():
-    engine = FenceRecordingEngine()
-    app = object.__new__(AsyncOmni)
-    app.engine = engine
-    app.request_states = {}
-    app._final_output_handler = lambda: None
-    fence = DuplexFence("sid", epoch=1, turn_id=2)
-
-    await app.open_duplex_session_async("sid", fence=fence)
-    await app.append_duplex_input_async(
-        "sid", mode="append_audio_chunk", payload={}, fence=fence, collect_outputs=False
-    )
-    await app.signal_duplex_turn_async("sid", event="turn.end", fence=fence)
-    await app.close_duplex_session_async("sid", reason="done", fence=fence)
-
-    assert engine.calls == [(operation, fence) for operation in ("open", "append", "signal", "close")]
-
-
-@pytest.mark.asyncio
-async def test_openai_handler_passes_current_session_fence_for_runtime_controls():
-    engine = FenceRecordingEngine()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(
-        session_id="sid",
-        config=DuplexSessionConfig(extra_body={"native_duplex": True}),
-        epoch=1,
-        turn_id=2,
-    )
-    ws = TimedWebSocket()
-    fence = DuplexFence("sid", epoch=1, turn_id=2)
-
-    await handler._open_runtime_session(session, ws.send_json)
-    await handler._signal_runtime_session(session, "turn.end", send_json=ws.send_json)
-    await handler._close_runtime_session(session, reason="done", send_json=ws.send_json)
-
-    assert engine.calls == [(operation, fence) for operation in ("open", "signal", "close")]
-
-
-@pytest.mark.asyncio
-async def test_runtime_signal_uses_fence_captured_before_session_turn_advances():
-    engine = FenceRecordingEngine()
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(engine))
-    session = DuplexSession(session_id="sid", config=DuplexSessionConfig(extra_body={"native_duplex": True}))
-    captured_fence = DuplexFence("sid", epoch=0, turn_id=0)
-    session.turn_id = 1
-
-    await handler._signal_runtime_session(
-        session,
-        "input.commit",
-        fence=captured_fence,
-    )
-
-    assert engine.calls == [("signal", captured_fence)]
-
-
-@pytest.mark.asyncio
-async def test_openai_handler_forwards_cancel_fence_through_async_omni_facade():
-    engine = FenceRecordingEngine()
-    app = object.__new__(AsyncOmni)
-    app.engine = engine
-    handler = OmniDuplexSessionHandler(chat_service=FakeChatService(app))
-    session = DuplexSession(session_id="sid-cancel", config=DuplexSessionConfig(extra_body={"native_duplex": True}))
-    cancelled_fence = DuplexFence("sid-cancel", epoch=2, turn_id=3)
-    next_fence = DuplexFence("sid-cancel", epoch=3, turn_id=3)
-
-    assert await handler._signal_runtime_session(
-        session,
-        "input.cancel",
-        fence=cancelled_fence,
-        next_fence=next_fence,
-    )
-
-    assert engine.calls == [("signal", cancelled_fence)]
-    assert engine.signal_next_fences == [next_fence]
diff --git a/tests/entrypoints/test_duplex_omni.py b/tests/entrypoints/test_duplex_omni.py
new file mode 100644
index 00000000000..f33b3ea4d35
--- /dev/null
+++ b/tests/entrypoints/test_duplex_omni.py
@@ -0,0 +1,326 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""``DuplexOmni`` / ``DuplexSessionHandle``: the thin Python API over a fake engine."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import replace
+from typing import Any
+
+import pytest
+
+from tests.entrypoints.test_omni_entrypoints import FakeAsyncOmniEngine
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex import commands
+from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig
+from vllm_omni.engine.duplex.events import (
+    AudioDelta,
+    DuplexEvent,
+    SessionClosed,
+    SessionCreated,
+    SessionExpired,
+)
+from vllm_omni.engine.duplex.messages import (
+    DuplexControlResultMessage,
+    DuplexSessionError,
+    DuplexSessionEventMessage,
+)
+from vllm_omni.engine.messages import ErrorMessage
+from vllm_omni.entrypoints.duplex_omni import DuplexOmni, DuplexSessionHandle
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+class FakeDuplexEngine(FakeAsyncOmniEngine):
+    """The engine surface ``DuplexOmni`` uses; every call is recorded."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self.duplex_session_config = DuplexSessionRuntimeConfig(max_sessions=2)
+        self.duplex_capabilities = DuplexCapabilities(supports_session_resume=True)
+        self.opened: list[tuple[str, DuplexSessionConfig]] = []
+        self.closed: list[tuple[str, str]] = []
+        self.resumed: list[tuple[str, int]] = []
+        self.touched: list[tuple[str, str]] = []
+        self.commands: list[tuple[str, commands.DuplexCommand]] = []
+        self.open_error: DuplexSessionError | None = None
+        self.close_error: DuplexSessionError | None = None
+
+    def _result(self, operation: str, session_id: str, **fields: Any) -> DuplexControlResultMessage:
+        return DuplexControlResultMessage(control_id="c", operation=operation, session_id=session_id, ok=True, **fields)
+
+    async def open_session_async(self, session_id, session_config, *, timeout=None):
+        self.opened.append((session_id, session_config))
+        if self.open_error is not None:
+            raise self.open_error
+        return self._result(
+            "open",
+            session_id,
+            capabilities=self.duplex_capabilities,
+            public_session={"id": session_id, "idle_timeout_s": 7},
+            lease_generation=0,
+        )
+
+    async def close_session_async(self, session_id, *, reason="client_close", timeout=None):
+        self.closed.append((session_id, reason))
+        if self.close_error is not None:
+            raise self.close_error
+        # The runner emits session.closed before answering the RPC.
+        self.emit(session_id, SessionClosed(reason=reason))
+        return self._result("close", session_id)
+
+    async def resume_session_async(self, session_id, *, expected_lease_generation, timeout=None):
+        self.resumed.append((session_id, expected_lease_generation))
+        return self._result("resume", session_id, lease_generation=expected_lease_generation + 1)
+
+    async def touch_session_async(self, session_id, *, activity, timeout=None):
+        self.touched.append((session_id, activity))
+        return self._result("touch", session_id)
+
+    async def submit_command_async(self, session_id, command):
+        self.commands.append((session_id, command))
+
+    def emit(self, session_id: str, event: DuplexEvent) -> None:
+        # The session manager binds the session identity to every event it emits.
+        event = replace(event, session_id=session_id)
+        self.output_q.put(DuplexSessionEventMessage(session_id=session_id, event=event))
+
+
+def _make_omni(monkeypatch: pytest.MonkeyPatch) -> tuple[DuplexOmni, FakeDuplexEngine]:
+    engine = FakeDuplexEngine()
+    monkeypatch.setattr("vllm_omni.entrypoints.duplex_omni.DuplexOmniEngine", lambda *args, **kwargs: engine)
+    monkeypatch.setattr("vllm_omni.entrypoints.omni_base.omni_snapshot_download", lambda model: model)
+    return DuplexOmni("dummy-model"), engine
+
+
+async def _collect(handle: DuplexSessionHandle, count: int, *, timeout_s: float = 2.0) -> list[DuplexEvent]:
+    events: list[DuplexEvent] = []
+
+    async def consume() -> None:
+        async for event in handle.events():
+            events.append(event)
+            if len(events) >= count:
+                break
+
+    await asyncio.wait_for(consume(), timeout=timeout_s)
+    return events
+
+
+@pytest.mark.asyncio
+async def test_open_session_allocates_the_id_and_ignores_client_ids(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    try:
+        handle = await omni.open_session({"session_id": "mine", "id": "mine-too", "instructions": "hi"})
+
+        assert handle.session_id.startswith("duplex-") and len(handle.session_id) == len("duplex-") + 32
+        assert handle.session_id != "mine"
+        ((session_id, config),) = engine.opened
+        assert session_id == handle.session_id
+        assert isinstance(config, DuplexSessionConfig)
+        assert config.model == "dummy-model" and config.instructions == "hi"
+        assert handle.capabilities is engine.duplex_capabilities
+        assert handle.public_session["id"] == handle.session_id
+        assert omni.sessions == {handle.session_id: handle}
+        assert omni.get_session(handle.session_id) is handle
+        assert omni.active_session_count() == 1
+
+        second = await omni.open_session(DuplexSessionConfig(instructions="typed"))
+        assert second.session_id != handle.session_id
+        assert engine.opened[1][1].model == "dummy-model"
+        assert omni.duplex_session_config.max_sessions == 2
+        assert omni.duplex_capabilities.supports_session_resume is True
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_open_failure_drops_the_pending_handle_and_raises_the_engine_code(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    engine.open_error = DuplexSessionError("full", code="resource_exhausted", retryable=True)
+    try:
+        with pytest.raises(DuplexSessionError) as excinfo:
+            await omni.open_session()
+        assert excinfo.value.code == "resource_exhausted"
+        assert omni.sessions == {}
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_events_are_routed_to_their_handle_and_end_on_session_closed(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    try:
+        handle = await omni.open_session()
+        engine.emit("duplex-unknown", AudioDelta(delta="zzz"))  # dropped
+        engine.emit(handle.session_id, SessionCreated(session={"id": handle.session_id}))
+        engine.emit(handle.session_id, AudioDelta(response_id="r1", delta="abc"))
+        engine.emit(handle.session_id, SessionClosed(reason="client_close"))
+
+        events = await _collect(handle, 10)
+
+        assert [event.type for event in events] == ["session.created", "response.output_audio.delta", "session.closed"]
+        assert events[0].session_id == handle.session_id
+        assert handle.closed and handle.close_reason == "client_close"
+        assert await handle.wait_closed() == "client_close"
+        assert handle.session_id not in omni.sessions
+        with pytest.raises(DuplexSessionError) as excinfo:
+            await handle.submit(commands.Heartbeat())
+        assert excinfo.value.code == "session_closed"
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_events_is_single_consumer_but_may_be_reentered(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    try:
+        handle = await omni.open_session()
+        engine.emit(handle.session_id, AudioDelta(delta="one"))
+        first = handle.events()
+        assert (await first.__anext__()).type == "response.output_audio.delta"
+        with pytest.raises(RuntimeError, match="active events"):
+            await handle.events().__anext__()
+        await first.aclose()
+
+        engine.emit(handle.session_id, SessionExpired(reason="idle_ttl_expired"))
+        events = await _collect(handle, 1)
+        assert events[0].type == "session.expired" and events[0].is_terminal
+        assert handle.closed and handle.close_reason == "idle_ttl_expired"
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_close_session_waits_for_the_typed_session_closed_event(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    try:
+        handle = await omni.open_session()
+        consumer = asyncio.create_task(_collect(handle, 1))
+        await handle.close(reason="done")
+
+        assert engine.closed == [(handle.session_id, "done")]
+        assert handle.closed and handle.close_reason == "done"
+        assert (await consumer)[0].type == "session.closed"
+        # Idempotent: a second close is a no-op.
+        await omni.close_session(handle.session_id)
+        assert len(engine.closed) == 1
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_close_failure_marks_the_handle_closed_and_propagates(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    engine.close_error = DuplexSessionError("boom", code="engine_error")
+    try:
+        handle = await omni.open_session()
+        with pytest.raises(DuplexSessionError, match="boom"):
+            await omni.close_session(handle.session_id)
+        assert handle.closed
+        # A failed close must not leave a dead handle shadowing the id.
+        assert omni.sessions == {}
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_engine_death_ends_every_session_handle(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    try:
+        handle = await omni.open_session()
+        engine.output_q.put(ErrorMessage(error="orchestrator died", fatal=True))
+
+        await asyncio.wait_for(handle.wait_closed(), timeout=2.0)
+        assert handle.closed
+        assert "engine_dead" in (handle.close_reason or "")
+        assert omni.sessions == {}
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_resume_detach_and_touch_forward_to_the_engine(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    try:
+        handle = await omni.open_session()
+        resumed = await omni.resume_session(handle.session_id, expected_lease_generation=0)
+        assert resumed is handle and handle.lease_generation == 1
+        assert engine.resumed == [(handle.session_id, 0)]
+
+        await omni.detach_session(handle.session_id)
+        await omni.touch_session(handle.session_id, activity="heartbeat")
+        assert engine.touched == [(handle.session_id, "detach"), (handle.session_id, "heartbeat")]
+
+        for call in (
+            omni.resume_session("duplex-nope", expected_lease_generation=0),
+            omni.detach_session("duplex-nope"),
+        ):
+            with pytest.raises(DuplexSessionError) as excinfo:
+                await call
+            assert excinfo.value.code == "unknown_session"
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_handle_wrappers_build_typed_commands_in_caller_order(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    try:
+        handle = await omni.open_session()
+        await handle.append_audio(b"\x00\x01", sample_rate_hz=16000, is_speech=True)
+        await handle.commit(create_response=True)
+        await handle.create_response({"instructions": "x"})
+        await handle.cancel_response("resp-1")
+        await handle.barge_in()
+        await handle.ack_playback(120.7, response_id="resp-1", committed_ms=100)
+        await handle.update({"temperature": 0.2})
+        await handle.create_item({"id": "item_1", "type": "message"}, previous_item_id="root")
+        await handle.delete_item("item_1")
+        await handle.truncate_item("item_1", audio_end_ms=50)
+        await handle.signal_turn("user_started", {"x": 1})
+        await handle.heartbeat()
+
+        submitted = [command for session_id, command in engine.commands if session_id == handle.session_id]
+        assert [type(command) for command in submitted] == [
+            commands.AppendAudio,
+            commands.Commit,
+            commands.CreateResponse,
+            commands.CancelResponse,
+            commands.BargeIn,
+            commands.AckPlayback,
+            commands.UpdateSession,
+            commands.CreateItem,
+            commands.DeleteItem,
+            commands.TruncateItem,
+            commands.SignalTurn,
+            commands.Heartbeat,
+        ]
+        append, commit, create, cancel, _, ack, update, item, delete, truncate, signal, _ = submitted
+        assert append.audio == b"\x00\x01" and append.sample_rate_hz == 16000 and append.is_speech is True
+        assert commit.create_response is True and commit.final is True
+        assert create.options == {"instructions": "x"}
+        assert cancel.response_id == "resp-1"
+        assert ack.played_ms == 120 and ack.committed_ms == 100 and ack.response_id == "resp-1"
+        assert update.patch == {"temperature": 0.2}
+        assert item.previous_item_id == "root" and item.item["id"] == "item_1"
+        assert delete.item_id == "item_1"
+        assert truncate.audio_end_ms == 50
+        assert signal.event == "user_started" and signal.signal_payload == {"x": 1}
+    finally:
+        omni.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_shutdown_closes_every_handle(monkeypatch) -> None:
+    omni, engine = _make_omni(monkeypatch)
+    first = await omni.open_session()
+    second = await omni.open_session()
+
+    omni.shutdown()
+
+    assert first.closed and second.closed
+    assert first.close_reason == "shutdown"
+    assert omni.sessions == {}
+    assert engine.shutdown_called
diff --git a/tests/entrypoints/test_omni_base_profiler.py b/tests/entrypoints/test_omni_base_profiler.py
index 827ab67b6b8..d343e2f0365 100644
--- a/tests/entrypoints/test_omni_base_profiler.py
+++ b/tests/entrypoints/test_omni_base_profiler.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 """Unit tests for OmniBase and AsyncOmni profiler methods."""
 
 from types import SimpleNamespace
@@ -28,10 +31,14 @@ def mock_engine(self, mocker: MockerFixture):
     @pytest.fixture
     def omni_base_instance(self, mock_engine, mocker: MockerFixture):
         """Create an OmniBase instance with mocked dependencies."""
-        mocker.patch("vllm_omni.entrypoints.omni_base.AsyncOmniEngine", return_value=mock_engine)
+        from vllm_omni.entrypoints.omni_base import OmniBase
+
+        # ``OmniBase`` builds its engine through the ``_create_engine`` seam that
+        # ``AsyncOmni`` / ``DuplexOmni`` implement; there is no module-level
+        # engine class to patch any more.
+        mocker.patch.object(OmniBase, "_create_engine", return_value=mock_engine)
         mocker.patch("vllm_omni.entrypoints.omni_base.omni_snapshot_download", side_effect=lambda x: x)
         mocker.patch("vllm_omni.entrypoints.omni_base.weakref.finalize")
-        from vllm_omni.entrypoints.omni_base import OmniBase
 
         instance = OmniBase(model="test-model")
         return instance
@@ -48,10 +55,14 @@ def test_start_profile_calls_collective_rpc(self, omni_base_instance, mock_engin
 
     def test_removed_diffusion_batch_size_fails_loudly(self, mock_engine, mocker: MockerFixture):
         """Legacy diffusion_batch_size callers receive an actionable error."""
-        mocker.patch("vllm_omni.entrypoints.omni_base.AsyncOmniEngine", return_value=mock_engine)
+        from vllm_omni.entrypoints.omni_base import OmniBase
+
+        # ``OmniBase`` builds its engine through the ``_create_engine`` seam that
+        # ``AsyncOmni`` / ``DuplexOmni`` implement; there is no module-level
+        # engine class to patch any more.
+        mocker.patch.object(OmniBase, "_create_engine", return_value=mock_engine)
         mocker.patch("vllm_omni.entrypoints.omni_base.omni_snapshot_download", side_effect=lambda x: x)
         mocker.patch("vllm_omni.entrypoints.omni_base.weakref.finalize")
-        from vllm_omni.entrypoints.omni_base import OmniBase
 
         with pytest.raises(TypeError, match="diffusion_batch_size.*max_num_seqs"):
             OmniBase(model="test-model", diffusion_batch_size=8)
diff --git a/tests/entrypoints/test_omni_entrypoints.py b/tests/entrypoints/test_omni_entrypoints.py
index 01264eaea81..32d7d998819 100644
--- a/tests/entrypoints/test_omni_entrypoints.py
+++ b/tests/entrypoints/test_omni_entrypoints.py
@@ -118,8 +118,6 @@ def __init__(
         self.output_processors = [SimpleNamespace(tokenizer=None) for _ in range(self.num_stages)]
         self.input_processor = None
         self.endpoint_restrictions = ()
-        self.duplex_session_config = None
-        self.duplex_serving_adapter_path = None
 
         self.output_q: queue.Queue[Any] = queue.Queue()
         self.submitted: list[dict[str, Any]] = []
@@ -183,7 +181,8 @@ def shutdown(self) -> None:
 
 
 def _patch_engine(monkeypatch: pytest.MonkeyPatch, engine: FakeAsyncOmniEngine) -> None:
-    monkeypatch.setattr("vllm_omni.entrypoints.omni_base.AsyncOmniEngine", lambda *args, **kwargs: engine)
+    monkeypatch.setattr("vllm_omni.entrypoints.omni.AsyncOmniEngine", lambda *args, **kwargs: engine)
+    monkeypatch.setattr("vllm_omni.entrypoints.async_omni.AsyncOmniEngine", lambda *args, **kwargs: engine)
     monkeypatch.setattr("vllm_omni.entrypoints.omni_base.omni_snapshot_download", lambda model: model)
     # Don't add random UUIDs to requests calling .generate since we usually
     # just want to check for present requests anyway, and would need to just
diff --git a/tests/examples/test_minicpmo_realtime_web_static.py b/tests/examples/test_minicpmo_realtime_web_static.py
index 926ae36ef70..2027d5aa3ad 100644
--- a/tests/examples/test_minicpmo_realtime_web_static.py
+++ b/tests/examples/test_minicpmo_realtime_web_static.py
@@ -36,7 +36,7 @@ def test_client_uses_proxy_relative_realtime_url_and_model_policy_session():
     assert "new URL(config.realtimePath, window.location.href)" in source
     assert "url.protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'" in source
     assert "url.searchParams.set('autostart', '0')" in source
-    assert "url.searchParams.set('native_duplex', '1')" in source
+    assert "native_duplex" not in source
     assert "auto_response: true" in source
     assert "input_audio_buffer.append" in source
     assert "input_audio_buffer.commit" not in source
diff --git a/tests/model_executor/models/minicpmo_4_5/duplex/test_commit_policy.py b/tests/model_executor/models/minicpmo_4_5/duplex/test_commit_policy.py
index b933f7173dd..d7f3db633cf 100644
--- a/tests/model_executor/models/minicpmo_4_5/duplex/test_commit_policy.py
+++ b/tests/model_executor/models/minicpmo_4_5/duplex/test_commit_policy.py
@@ -5,7 +5,7 @@
 
 import pytest
 
-from vllm_omni.entrypoints.duplex.commit_policy import (
+from vllm_omni.engine.duplex.session.commit_policy import (
     CommitAction,
     CommitSnapshot,
     decide_commit_action,
@@ -24,7 +24,7 @@
                 speech_since_commit=True,
                 active_response_id=None,
                 overlap_speech_ms=0,
-                native_response_in_progress=False,
+                response_in_progress=False,
                 playback_active=False,
             ),
             CommitAction.START_AUTO_RESPONSE,
@@ -36,7 +36,7 @@
                 speech_since_commit=True,
                 active_response_id=None,
                 overlap_speech_ms=800,
-                native_response_in_progress=True,
+                response_in_progress=True,
                 playback_active=True,
             ),
             CommitAction.START_AUTO_RESPONSE,
@@ -48,7 +48,7 @@
                 speech_since_commit=False,
                 active_response_id=None,
                 overlap_speech_ms=0,
-                native_response_in_progress=True,
+                response_in_progress=True,
                 playback_active=False,
             ),
             CommitAction.COMMIT_ONLY,
@@ -60,7 +60,7 @@
                 speech_since_commit=True,
                 active_response_id=None,
                 overlap_speech_ms=800,
-                native_response_in_progress=True,
+                response_in_progress=True,
                 playback_active=False,
             ),
             CommitAction.DEFER_ACTIVE_RESPONSE,
@@ -72,7 +72,7 @@
                 speech_since_commit=True,
                 active_response_id=None,
                 overlap_speech_ms=800,
-                native_response_in_progress=False,
+                response_in_progress=False,
                 playback_active=True,
             ),
             CommitAction.DEFER_ACTIVE_RESPONSE,
@@ -84,7 +84,7 @@
                 speech_since_commit=True,
                 active_response_id=None,
                 overlap_speech_ms=0,
-                native_response_in_progress=False,
+                response_in_progress=False,
                 playback_active=False,
             ),
             CommitAction.COMMIT_ONLY,
diff --git a/tests/model_executor/models/minicpmo_4_5/duplex/test_data_plane_audio_cursor.py b/tests/model_executor/models/minicpmo_4_5/duplex/test_data_plane_audio_cursor.py
new file mode 100644
index 00000000000..b2be91366be
--- /dev/null
+++ b/tests/model_executor/models/minicpmo_4_5/duplex/test_data_plane_audio_cursor.py
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The cumulative Stage1 audio cursor.
+
+Stage1 hands the data plane a snapshot of every sample it has generated for the
+request so far, and only the new tail may reach the client. The cursor that
+makes that possible is the one piece of per-request state whose loss is silent
+and expensive: rewinding it re-sends the whole session as a single delta.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.data_plane import (
+    MiniCPMO45DataPlaneSession,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+REQUEST_ID = "duplex-s.c2Vzc2lvbg==.e.0.r.stage0"
+
+
+def _session() -> MiniCPMO45DataPlaneSession:
+    return MiniCPMO45DataPlaneSession(lambda *args, **kwargs: "")
+
+
+def _snapshot(num_samples: int) -> np.ndarray:
+    return np.arange(num_samples, dtype=np.float32)
+
+
+def _sliced_len(session: MiniCPMO45DataPlaneSession, num_samples: int) -> int:
+    sliced = session.slice_cumulative_audio(REQUEST_ID, _snapshot(num_samples))
+    if sliced is None:
+        return 0
+    return int(np.asarray(sliced).reshape(-1).size)
+
+
+def test_a_growing_snapshot_yields_only_the_new_tail() -> None:
+    session = _session()
+    assert _sliced_len(session, 24000) == 24000
+    assert _sliced_len(session, 48000) == 24000
+    assert _sliced_len(session, 48000) == 0  # unchanged snapshot emits nothing
+
+
+def test_a_placeholder_unit_does_not_rewind_the_cursor() -> None:
+    """The failure behind a 300s benchmark case producing 1373s of audio.
+
+    A continuation unit arrives as a one-sample snapshot. Taking that as "the
+    producer restarted" drops the cursor to 1, so the next real snapshot is
+    sliced from the start and the client is handed the entire session again.
+    """
+    session = _session()
+    assert _sliced_len(session, 637440) == 637440
+    assert _sliced_len(session, 1) == 1
+    assert _sliced_len(session, 1) == 1
+    assert _sliced_len(session, 1) == 1
+
+    # 649920 - 637440, not 649920 - 1.
+    assert _sliced_len(session, 649920) == 12480
+
+
+def test_a_genuinely_restarted_producer_is_still_picked_up() -> None:
+    """Two consecutive below-cursor snapshots that grow are a new buffer."""
+    session = _session()
+    assert _sliced_len(session, 48000) == 48000
+    assert _sliced_len(session, 1000) == 1000  # head of the new buffer
+    assert _sliced_len(session, 3000) == 2000  # its tail, not 3000 - 48000
+    assert _sliced_len(session, 5000) == 2000
+
+
+def test_close_stream_releases_the_cursor_for_the_next_stream() -> None:
+    session = _session()
+    assert _sliced_len(session, 48000) == 48000
+    session.close_stream(REQUEST_ID)
+    assert _sliced_len(session, 24000) == 24000
diff --git a/tests/model_executor/models/minicpmo_4_5/test_pipeline.py b/tests/model_executor/models/minicpmo_4_5/test_pipeline.py
index e12010ce40a..6c22b818b0d 100644
--- a/tests/model_executor/models/minicpmo_4_5/test_pipeline.py
+++ b/tests/model_executor/models/minicpmo_4_5/test_pipeline.py
@@ -55,20 +55,18 @@ def test_lazy_load_returns_pipeline_config(self) -> None:
         assert pipeline.model_type == _PIPELINE_KEY
         assert pipeline.model_arch == "MiniCPMO45OmniForConditionalGeneration"
 
-    def test_native_duplex_control_is_explicit_without_a_fixed_session_cap(self) -> None:
+    def test_duplex_plugin_is_declared_without_a_fixed_session_cap(self) -> None:
         pipeline = OMNI_PIPELINES[_PIPELINE_KEY]
-        assert pipeline.duplex_control_enabled is True
-        assert pipeline.duplex_serving_adapter == (
-            "vllm_omni.model_executor.models.minicpmo_4_5.duplex.serving_adapter.MiniCPMO45ServingRuntimeAdapter"
+        assert pipeline.duplex_plugin == (
+            "vllm_omni.model_executor.models.minicpmo_4_5.duplex.plugin.MiniCPMO45DuplexPlugin"
         )
         assert not hasattr(pipeline, "max_native_duplex_sessions")
 
-    def test_ordinary_pipeline_defaults_to_no_duplex_control(self) -> None:
+    def test_ordinary_pipeline_declares_no_duplex_plugin(self) -> None:
         pipeline = PipelineConfig(
             model_type="ordinary", stages=(StagePipelineConfig(stage_id=0, model_stage="a", final_output=True),)
         )
-        assert pipeline.duplex_control_enabled is False
-        assert pipeline.duplex_serving_adapter is None
+        assert pipeline.duplex_plugin is None
         assert not hasattr(pipeline, "max_native_duplex_sessions")
 
 
diff --git a/tests/model_executor/models/nemotron_voicechat/duplex/conftest.py b/tests/model_executor/models/nemotron_voicechat/duplex/conftest.py
new file mode 100644
index 00000000000..134731bf6b1
--- /dev/null
+++ b/tests/model_executor/models/nemotron_voicechat/duplex/conftest.py
@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Nemotron VoiceChat duplex is not on the duplex plugin framework yet.
+
+RFC vllm-omni#7181 splits the port: this PR lands the unified framework with
+MiniCPM-o 4.5, and the follow-up PR moves Nemotron VoiceChat onto
+``DuplexModelPlugin``. Until then the modules under test still import the
+pre-framework duplex runtime / serving adapter that this PR removed, so
+collecting them would fail at import time and abort the whole pytest session.
+The tests themselves are unchanged and come back with the port.
+
+Listed per file rather than globbed, so the coverage loss is visible and shrinks
+file by file as the port lands. ``test_input.py`` imports nothing that was
+removed and keeps running.
+"""
+
+#: Both import ``DuplexFence`` from ``engine.duplex.messages``, which no longer
+#: exports it; ``test_data_plane`` also imports ``engine.duplex.runtime``.
+collect_ignore = ["test_data_plane.py", "test_runtime_contract.py"]
diff --git a/tests/model_executor/models/nemotron_voicechat/duplex/test_data_plane.py b/tests/model_executor/models/nemotron_voicechat/duplex/test_data_plane.py
index 4bdc835d91f..04e57c3976a 100644
--- a/tests/model_executor/models/nemotron_voicechat/duplex/test_data_plane.py
+++ b/tests/model_executor/models/nemotron_voicechat/duplex/test_data_plane.py
@@ -7,9 +7,9 @@
 
 import numpy as np
 import pytest
+from vllm_omni.engine.duplex.runtime import duplex_resource_request_id
 
 from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.runtime import duplex_resource_request_id
 from vllm_omni.model_executor.models.nemotron_voicechat.duplex.data_plane import (
     NemotronVoiceChatDataPlaneContext,
     NemotronVoiceChatDataPlaneSession,
diff --git a/tests/model_executor/models/personaplex/duplex/conftest.py b/tests/model_executor/models/personaplex/duplex/conftest.py
new file mode 100644
index 00000000000..d49e8c61721
--- /dev/null
+++ b/tests/model_executor/models/personaplex/duplex/conftest.py
@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""PersonaPlex duplex is not on the duplex plugin framework yet.
+
+RFC vllm-omni#7181 splits the port: this PR lands the unified framework with
+MiniCPM-o 4.5, and the follow-up PR moves PersonaPlex onto ``DuplexModelPlugin``.
+Until then the modules under test still import the pre-framework duplex
+runtime / serving adapter that this PR removed, so collecting them would fail
+at import time and abort the whole pytest session. The tests themselves are
+unchanged and come back with the port.
+
+Listed per file rather than globbed, so the coverage loss is visible and shrinks
+file by file as the port lands.
+"""
+
+#: ``test_unified_runtime`` imports ``engine.duplex.runtime`` and
+#: ``entrypoints.duplex.runtime_adapter`` directly. ``test_stage0_runtime`` fails
+#: transitively: ``personaplex.duplex.runtime_extension`` imports ``DuplexFence``
+#: from ``engine.duplex.messages``, which no longer exports it.
+collect_ignore = ["test_stage0_runtime.py", "test_unified_runtime.py"]
diff --git a/tests/model_executor/models/personaplex/duplex/test_unified_runtime.py b/tests/model_executor/models/personaplex/duplex/test_unified_runtime.py
index 1f03e894b7e..e4f9ad9b1fc 100644
--- a/tests/model_executor/models/personaplex/duplex/test_unified_runtime.py
+++ b/tests/model_executor/models/personaplex/duplex/test_unified_runtime.py
@@ -8,6 +8,12 @@
 import numpy as np
 import pytest
 from vllm.sampling_params import SamplingParams
+from vllm_omni.engine.duplex.runtime import (
+    DuplexInputMode,
+)
+from vllm_omni.entrypoints.duplex.runtime_adapter import (
+    ServingRuntimeConfigError,
+)
 
 from tests.e2e.online_serving import personaplex_realtime_duplex as e2e_driver
 from vllm_omni.config.stage_config import (
@@ -15,12 +21,6 @@
     merge_pipeline_deploy,
 )
 from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.runtime import (
-    DuplexInputMode,
-)
-from vllm_omni.entrypoints.duplex.runtime_adapter import (
-    ServingRuntimeConfigError,
-)
 from vllm_omni.model_executor.models.personaplex.duplex.config import DEFAULT_PERSONA
 from vllm_omni.model_executor.models.personaplex.duplex.data_plane import (
     PersonaPlexDataPlaneContext,
diff --git a/tests/worker/test_native_duplex_hooks.py b/tests/worker/test_native_duplex_hooks.py
index c47802fbc86..388e334ccac 100644
--- a/tests/worker/test_native_duplex_hooks.py
+++ b/tests/worker/test_native_duplex_hooks.py
@@ -23,7 +23,7 @@ def _minicpmo_duplex_policy_case(
         MiniCPMO45OmniForConditionalGeneration,
     )
 
-    session_key = ("sid-policy", 1)
+    session_key = "sid-policy"
     model = MiniCPMO45OmniForConditionalGeneration.__new__(MiniCPMO45OmniForConditionalGeneration)
     model.model_stage = "llm"
     model._minicpmo45_native_duplex_token_ids_cache = {
@@ -35,8 +35,7 @@ def _minicpmo_duplex_policy_case(
     row = DuplexSamplingRow(
         row_idx=0,
         request_id="req-policy",
-        session_id=session_key[0],
-        incarnation=session_key[1],
+        session_id=session_key,
         seq=3,
         payload=payload,
         max_tokens=20,
@@ -63,13 +62,12 @@ def test_minicpmo_model_hook_owns_duplex_sampling_rows_and_force_listen():
         "tts_bos_token_id": 8,
         "turn_eos_token_id": 9,
     }
-    model._minicpmo45_duplex_data_plane_helper = SimpleNamespace(sessions={("sid-hook", 2): state})
+    model._minicpmo45_duplex_data_plane_helper = SimpleNamespace(sessions={"sid-hook": state})
     logits = torch.zeros((1, 16), dtype=torch.float32)
     row = DuplexSamplingRow(
         row_idx=0,
         request_id="req-hook",
         session_id="sid-hook",
-        incarnation=2,
         seq=3,
         payload={"force_listen": True, "is_speech": True},
         max_tokens=20,
@@ -78,7 +76,7 @@ def test_minicpmo_model_hook_owns_duplex_sampling_rows_and_force_listen():
     model.prepare_duplex_sampling(logits, SimpleNamespace(), (row,))
 
     assert model._minicpmo45_active_duplex_rows == [0]
-    assert model._minicpmo45_duplex_row_sessions == {0: ("sid-hook", 2)}
+    assert model._minicpmo45_duplex_row_sessions == {0: "sid-hook"}
     assert model._minicpmo45_duplex_row_payloads == {0: row.payload}
     assert model._minicpmo45_duplex_row_max_tokens == {0: 20}
     assert logits[0, listen_id].item() == 0.0
@@ -152,7 +150,7 @@ def test_minicpmo_model_hook_old_response_output_does_not_clear_pending_speech_c
         pending_speech_context=True,
     )
     model, row = _minicpmo_duplex_policy_case(state, {"is_speech": True})
-    model._minicpmo45_duplex_row_sessions = {0: (row.session_id, row.incarnation)}
+    model._minicpmo45_duplex_row_sessions = {0: row.session_id}
     model._minicpmo45_duplex_row_payloads = {0: row.payload}
 
     model._record_minicpmo45_duplex_terminator(
@@ -173,7 +171,7 @@ def test_minicpmo_model_hook_new_response_output_clears_pending_speech_context()
         pending_speech_context=True,
     )
     model, row = _minicpmo_duplex_policy_case(state, {"is_speech": False})
-    model._minicpmo45_duplex_row_sessions = {0: (row.session_id, row.incarnation)}
+    model._minicpmo45_duplex_row_sessions = {0: row.session_id}
     model._minicpmo45_duplex_row_payloads = {0: row.payload}
 
     model._record_minicpmo45_duplex_terminator(
@@ -195,7 +193,7 @@ def test_minicpmo_model_hook_empty_speak_envelope_preserves_pending_speech_conte
         pending_speech_response_open=False,
     )
     model, row = _minicpmo_duplex_policy_case(state, {"is_speech": False})
-    model._minicpmo45_duplex_row_sessions = {0: (row.session_id, row.incarnation)}
+    model._minicpmo45_duplex_row_sessions = {0: row.session_id}
     model._minicpmo45_duplex_row_payloads = {0: row.payload}
     token_ids = {
         "listen_token_id": 7,
@@ -236,7 +234,7 @@ def test_minicpmo_model_hook_second_new_response_step_is_not_forced_to_listen():
     original_logits = logits.clone()
 
     model.prepare_duplex_sampling(logits, SimpleNamespace(), (row,))
-    model._minicpmo45_duplex_row_sessions = {0: (row.session_id, row.incarnation)}
+    model._minicpmo45_duplex_row_sessions = {0: row.session_id}
     model._minicpmo45_duplex_row_payloads = {0: row.payload}
     model._record_minicpmo45_duplex_terminator(
         0,
@@ -269,7 +267,7 @@ def test_minicpmo_model_hook_same_speech_row_second_step_does_not_rearm_pending_
     logits[0, 10] = 20.0
 
     model.prepare_duplex_sampling(logits, SimpleNamespace(), (row,))
-    model._minicpmo45_duplex_row_sessions = {0: (row.session_id, row.incarnation)}
+    model._minicpmo45_duplex_row_sessions = {0: row.session_id}
     model._minicpmo45_duplex_row_payloads = {0: row.payload}
     model._record_minicpmo45_duplex_terminator(
         0,
@@ -339,7 +337,6 @@ def test_generic_ar_runner_builds_typed_duplex_sampling_rows():
             "duplex": {
                 "data_plane": True,
                 "session_id": "sid-runner-hook",
-                "incarnation": 4,
                 "seq": 4,
                 "payload": {"is_speech": True},
             }
@@ -359,7 +356,6 @@ def test_generic_ar_runner_builds_typed_duplex_sampling_rows():
     assert rows[0].row_idx == 0
     assert rows[0].request_id == "req-duplex"
     assert rows[0].session_id == "sid-runner-hook"
-    assert rows[0].incarnation == 4
     assert rows[0].seq == 4
     assert rows[0].payload == {"is_speech": True}
     assert rows[0].max_tokens == 32
@@ -458,13 +454,13 @@ def test_generic_ar_runner_has_no_minicpmo_sampler_state_or_typeerror_probe():
     assert 'if "duplex_rows" not in str(exc)' not in source
 
 
-def test_minicpmo_model_cleans_incarnation_state_when_request_finishes():
+def test_minicpmo_model_cleans_session_state_when_request_finishes():
     from vllm_omni.model_executor.models.minicpmo_4_5.minicpmo_4_5_omni import (
         MiniCPMO45OmniForConditionalGeneration,
     )
 
     request_id = "duplex-sid-cleanup-i3-e0-stage0"
-    session_key = ("sid-cleanup", 3)
+    session_key = "sid-cleanup"
     model = MiniCPMO45OmniForConditionalGeneration.__new__(MiniCPMO45OmniForConditionalGeneration)
     model.model = SimpleNamespace()
     model._minicpmo45_duplex_data_plane_helper = SimpleNamespace(sessions={session_key: object()})
@@ -1731,8 +1727,8 @@ def convert_tokens_to_ids(self, token):
     model = MiniCPMO45OmniForConditionalGeneration.__new__(MiniCPMO45OmniForConditionalGeneration)
     model.model_stage = "llm"
     model.thinker = SimpleNamespace(get_tokenizer=lambda: _Tokenizer())
-    session_key = ("sid-cross-chunk-repetition", 0)
-    state = _MiniCPMO45Stage0SessionState(session_id=session_key[0])
+    session_key = "sid-cross-chunk-repetition"
+    state = _MiniCPMO45Stage0SessionState(session_id=session_key)
     state.generated_tokens = [198] * 8
     model._minicpmo45_duplex_data_plane_helper = SimpleNamespace(sessions={session_key: state})
     model._minicpmo45_duplex_row_sessions = {0: session_key}
@@ -1791,8 +1787,8 @@ def convert_tokens_to_ids(self, token):
     model = MiniCPMO45OmniForConditionalGeneration.__new__(MiniCPMO45OmniForConditionalGeneration)
     model.model_stage = "llm"
     model.thinker = SimpleNamespace(get_tokenizer=lambda: _Tokenizer())
-    session_key = ("sid-negative-logit-repetition", 0)
-    state = _MiniCPMO45Stage0SessionState(session_id=session_key[0])
+    session_key = "sid-negative-logit-repetition"
+    state = _MiniCPMO45Stage0SessionState(session_id=session_key)
     repeated = 198
     alternative = 1234
     state.generated_tokens = [repeated]
@@ -1827,8 +1823,8 @@ def test_minicpmo_stage0_records_bounded_model_policy_history():
         MiniCPMO45OmniForConditionalGeneration,
     )
 
-    session_key = ("sid-text-history", 0)
-    state = _MiniCPMO45Stage0SessionState(session_id=session_key[0])
+    session_key = "sid-text-history"
+    state = _MiniCPMO45Stage0SessionState(session_id=session_key)
     model = MiniCPMO45OmniForConditionalGeneration.__new__(MiniCPMO45OmniForConditionalGeneration)
     model._minicpmo45_duplex_data_plane_helper = SimpleNamespace(sessions={session_key: state})
     model._minicpmo45_duplex_row_sessions = {0: session_key}
diff --git a/tools/pre_commit/check_forbidden_imports.py b/tools/pre_commit/check_forbidden_imports.py
index c5a96148ea2..959007c30ce 100644
--- a/tools/pre_commit/check_forbidden_imports.py
+++ b/tools/pre_commit/check_forbidden_imports.py
@@ -79,16 +79,15 @@ class ForbiddenImport:
             "vllm_omni/entrypoints/openai/video_stream_base.py",
             "vllm_omni/entrypoints/openai/video_stream_session.py",
             "vllm_omni/experimental/fullduplex/client.py",
+            "vllm_omni/engine/duplex/audio.py",
+            "vllm_omni/engine/duplex/commands.py",
             "vllm_omni/engine/duplex/contracts.py",
+            "vllm_omni/engine/duplex/events.py",
+            "vllm_omni/engine/duplex/realtime_commands.py",
             "vllm_omni/experimental/fullduplex/joyvl/memory/memory.py",
-            "vllm_omni/model_executor/models/minicpmo_4_5/duplex/adapter.py",
             "vllm_omni/model_executor/models/minicpmo_4_5/duplex/input.py",
-            "vllm_omni/model_executor/models/minicpmo_4_5/duplex/runtime.py",
+            "vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py",
             "vllm_omni/model_executor/models/minicpmo_4_5/duplex/stage0.py",
-            "vllm_omni/entrypoints/duplex/audio.py",
-            "vllm_omni/entrypoints/duplex/realtime_input.py",
-            "vllm_omni/entrypoints/duplex/runtime_bridge.py",
-            "vllm_omni/entrypoints/duplex/serving.py",
             "vllm_omni/model_executor/models/personaplex/duplex/input.py",
             "vllm_omni/model_executor/models/personaplex/duplex/runtime_extension.py",
             "vllm_omni/model_executor/models/personaplex/duplex/stage0.py",
diff --git a/vllm_omni/benchmarks/omniinteract.py b/vllm_omni/benchmarks/omniinteract.py
index 83e224f3484..e566ac12b4d 100644
--- a/vllm_omni/benchmarks/omniinteract.py
+++ b/vllm_omni/benchmarks/omniinteract.py
@@ -417,6 +417,13 @@ def _has_post_commit_decision(
 # refusal is harmless — record it instead of failing the case.
 _TOLERATED_ERROR_CODES = frozenset({"playback_ack_too_late"})
 
+# ``session.close`` carries no reason of its own, so the server stamps the
+# terminal event with the reason it inferred for it. Anything else on a
+# ``session.closed`` after our own close request means the session ended for a
+# reason we did not ask for (a disconnect, a lease timeout, a shutdown), which
+# is what this guard is looking for.
+_CLIENT_CLOSE_REASONS = frozenset({"client_close"})
+
 
 def _error_code(event: dict[str, object]) -> str | None:
     error = event.get("error")
@@ -452,7 +459,7 @@ def _raise_if_session_terminated(
             event_type == "session.closed"
             and explicit_close_from is not None
             and index >= explicit_close_from
-            and reason is None
+            and (reason is None or reason in _CLIENT_CLOSE_REASONS)
         )
         if expected:
             continue
@@ -826,7 +833,7 @@ def write_batch_artifacts(
     )
 
 
-def _websocket_url(config: OmniInteractBenchmarkConfig, session_id: str) -> str:
+def _websocket_url(config: OmniInteractBenchmarkConfig) -> str:
     endpoint = (
         config.endpoint
         if urlsplit(config.endpoint).scheme
@@ -834,13 +841,7 @@ def _websocket_url(config: OmniInteractBenchmarkConfig, session_id: str) -> str:
     )
     from vllm_omni.clients.duplex import build_realtime_url
 
-    return build_realtime_url(
-        endpoint,
-        config.model,
-        autostart=False,
-        native_duplex=True,
-        session_id=session_id,
-    )
+    return build_realtime_url(endpoint, config.model, autostart=False)
 
 
 class _RealtimeSession:
@@ -855,7 +856,7 @@ class _RealtimeSession:
 
     _MAX_FRAME_BYTES = 64 * 1024 * 1024
 
-    def __init__(self, config: OmniInteractBenchmarkConfig, session_id: str, reference_audio: str) -> None:
+    def __init__(self, config: OmniInteractBenchmarkConfig, reference_audio: str) -> None:
         from vllm_omni.clients.duplex import DuplexClient, EventCollector, SessionConfig
 
         self.session_config = SessionConfig(
@@ -864,12 +865,11 @@ def __init__(self, config: OmniInteractBenchmarkConfig, session_id: str, referen
             playback_commit_policy="ack_only",
             idle_timeout_s=float(config.timeout_s),
             extra_body={
-                "native_duplex": True,
                 "force_listen_count": 0,
                 **(config.extra_body or {}),
             },
         )
-        self.url = _websocket_url(config, session_id)
+        self.url = _websocket_url(config)
         headers = dict(config.extra_headers or {})
 
         async def connect(url: str) -> WebSocketTransport:
@@ -886,7 +886,6 @@ async def connect(url: str) -> WebSocketTransport:
             self.url,
             model=config.model,
             config=self.session_config,
-            session_id=session_id,
             reconnect=None,
             heartbeat_interval_s=None,
             handshake_timeout_s=min(config.timeout_s, 20.0),
@@ -1013,7 +1012,7 @@ async def run_omniinteract_case(
             frames = prepared_input.video_frames
         if not any(frames):
             raise ValueError(f"No video frames were decoded from {case.video_path}")
-        async with _RealtimeSession(config, session_id, reference_audio) as client:
+        async with _RealtimeSession(config, reference_audio) as client:
             session_from = 0  # the collector holds only this session's events
             pcm = _ensure_final_commit_tail(pcm, client.events.events)
             playback = _Playback()
diff --git a/vllm_omni/benchmarks/patch/patch.py b/vllm_omni/benchmarks/patch/patch.py
index a230b9c2e12..bee910c90d3 100644
--- a/vllm_omni/benchmarks/patch/patch.py
+++ b/vllm_omni/benchmarks/patch/patch.py
@@ -14,7 +14,7 @@
 import traceback
 import uuid
 import wave
-from collections.abc import Iterable, Mapping
+from collections.abc import Callable, Iterable, Mapping
 from dataclasses import dataclass, replace
 from datetime import datetime
 from pathlib import Path
@@ -2153,10 +2153,68 @@ async def async_request_openai_audio_speech(
     return output
 
 
+#: Silence budget per Seed-TTS turn: a model-native duplex session generates
+#: per audio unit, and the target text rides the session context, so the
+#: silence only advances the clock. It stops at the turn's response.done --
+#: a native model that keeps hearing silence after its turn may decide to
+#: speak again, and the benchmark measures one response per utterance -- so
+#: the budget is only spent on a turn the model is slow to take: it may
+#: choose to listen on a few units first, and a turn that has not settled
+#: when the budget runs out is reported with what the model did.
+_SEED_TTS_SILENCE_SECONDS = 30.0
+#: A native model normally answers the seeded text within this much silence;
+#: a turn that needs more is logged so a slow-to-speak model shows in the run.
+_SEED_TTS_PROMPT_RESPONSE_S = 12.0
+#: MiniCPM-o emits 24 kHz mono; used to report audio_frames after the session closed.
+_SEED_TTS_OUTPUT_SAMPLE_RATE_HZ = 24_000
+
+
+def _seed_tts_turn_stall_report(events: object, response_offset: int, request_index: int, silence_s: float) -> str:
+    """Explain a Seed-TTS turn that never settled: what the model did with the silence."""
+    response_ids = list(getattr(events, "response_ids")[response_offset:])
+    if not response_ids:
+        return (
+            f"Seed-TTS Realtime TTS turn {request_index} never started a response: the model listened "
+            f"through {silence_s:.1f}s of silence and the wait that followed"
+        )
+    audio_bytes = getattr(events, "audio_bytes")
+    response_text = getattr(events, "response_text")
+    started = ", ".join(
+        f"{response_id} ({len(audio_bytes(response_id))} audio bytes, text {response_text(response_id)!r})"
+        for response_id in response_ids
+    )
+    return (
+        f"Seed-TTS Realtime TTS turn {request_index} started {len(response_ids)} response(s) after "
+        f"{silence_s:.1f}s of silence but none reached response.done: {started}"
+    )
+
+
+def _seed_tts_turn_response_id(events: object, response_offset: int, request_index: int) -> str:
+    """The response id the Seed-TTS turn is measured on: the first one with audio.
+
+    A model-native session answers the seeded text once, but nothing in the
+    protocol stops it from speaking again on silence it hears afterwards, so
+    a later audio response is the model's own and not a failed turn.
+    """
+    response_ids = getattr(events, "response_ids")
+    audio_bytes = getattr(events, "audio_bytes")
+    audio_response_ids = [response_id for response_id in response_ids[response_offset:] if audio_bytes(response_id)]
+    if not audio_response_ids:
+        raise RuntimeError(f"Seed-TTS Realtime TTS turn {request_index} produced no audio response")
+    if len(audio_response_ids) > 1:
+        logger.warning(
+            "Seed-TTS Realtime TTS turn %d: model spoke again after its response (%d audio responses); "
+            "measuring the first",
+            request_index,
+            len(audio_response_ids),
+        )
+    return audio_response_ids[0]
+
+
 def _realtime_websocket_url(api_url: str) -> str:
     from vllm_omni.clients.duplex import build_realtime_url
 
-    return build_realtime_url(api_url, None, native_duplex=None)
+    return build_realtime_url(api_url, None)
 
 
 def _nonnegative_number(value: object) -> bool:
@@ -2321,6 +2379,13 @@ class _RealtimeTTSProbe:
     request time.
     """
 
+    #: How long ``configure`` waits for a free duplex session. Every Seed-TTS
+    #: utterance is one session and the deploy config admits ``max_sessions``
+    #: of them, so a benchmark run above that concurrency queues for a slot
+    #: rather than counting the server's (retryable) refusal as a failed
+    #: request.
+    _SESSION_SLOT_WAIT_S = 120.0
+
     def __init__(self, url: str) -> None:
         from vllm_omni.clients.duplex import EventCollector
 
@@ -2347,16 +2412,13 @@ async def configure(
         *,
         output_audio_format: str = "pcm16",
         instructions: str | None = None,
-        native_duplex: bool = False,
         auto_response: bool = False,
         extra_body: dict[str, object] | None = None,
-        session_id: str | None = None,
         timeout_s: float = 120.0,
     ) -> None:
-        from vllm_omni.clients.duplex import AudioFormat, DuplexClient, SessionConfig
+        from vllm_omni.clients.duplex import AudioFormat, DuplexClient, DuplexProtocolError, SessionConfig
 
         session_extra_body: dict[str, object] = dict(extra_body or {})
-        session_extra_body["native_duplex"] = bool(native_duplex)
         config = SessionConfig(
             output_audio=AudioFormat(output_audio_format, 24_000),
             instructions=instructions,
@@ -2365,16 +2427,33 @@ async def configure(
             playback_commit_policy="ack_only",
             extra_body=session_extra_body,
         )
-        self._client = DuplexClient(
-            self._url,
-            model=model,
-            config=config,
-            session_id=session_id,
-            reconnect=None,
-            heartbeat_interval_s=None,
-            handshake_timeout_s=timeout_s,
-        )
-        await self._client.__aenter__()
+        deadline = time.monotonic() + self._SESSION_SLOT_WAIT_S
+        delay_s = 0.25
+        waited = False
+        while True:
+            # A failed handshake closes the socket on the client's side, so
+            # a refused attempt leaves nothing behind to clean up.
+            client = DuplexClient(
+                self._url,
+                model=model,
+                config=config,
+                reconnect=None,
+                heartbeat_interval_s=None,
+                handshake_timeout_s=timeout_s,
+            )
+            try:
+                await client.__aenter__()
+            except DuplexProtocolError as exc:
+                if exc.code != "resource_exhausted" or time.monotonic() >= deadline:
+                    raise
+                if not waited:
+                    logger.info("Seed-TTS Realtime TTS: no free duplex session (%s); waiting for a slot", exc)
+                    waited = True
+                await asyncio.sleep(delay_s)
+                delay_s = min(delay_s * 2.0, 2.0)
+                continue
+            self._client = client
+            break
         self._consume_task = asyncio.create_task(self.events.consume(self._client))
 
     async def send(self, event: dict[str, object]) -> None:
@@ -2387,6 +2466,32 @@ async def acknowledge_playback(self) -> None:
         assert self._client is not None
         await acknowledge_collected_playback(self._client, self.events)
 
+    async def stream_silence(
+        self,
+        *,
+        seconds: float,
+        chunk_ms: int = 200,
+        until: Callable[[], bool] | None = None,
+    ) -> float:
+        """Append silent PCM16 units so a model-native session has units to speak on.
+
+        A duplex model generates per audio unit. The target text rides the
+        session context (``duplex_initial_user_text``), so the audio only has
+        to advance the clock; silence keeps it from adding content of its own.
+        Streams in real time for at most ``seconds``, stopping as soon as
+        ``until`` holds, and returns the seconds actually appended.
+        """
+        assert self._client is not None
+        input_format = self._client.config.input_audio
+        chunk = bytes(max(input_format.byte_count(chunk_ms), input_format.bytes_per_sample))
+        chunk_s = input_format.duration_ms(len(chunk)) / 1000.0
+        streamed_s = 0.0
+        while streamed_s < seconds and not (until is not None and until()):
+            await self._client.append_audio(chunk, is_speech=False)
+            streamed_s += chunk_s
+            await asyncio.sleep(chunk_s)
+        return streamed_s
+
     async def close_session(self, *, timeout_s: float = 20.0) -> None:
         assert self._client is not None
         await self._client.close(timeout_s=timeout_s)
@@ -2423,69 +2528,70 @@ async def async_request_openai_realtime_duplex(
     if not turn_prompts:
         turn_prompts = [("", request_func_input.prompt)]
     session_id = f"seed-tts-{request_func_input.request_id or uuid.uuid4().hex}"
+    silence_seconds = float(getattr(request_func_input, "seed_tts_silence_seconds", 0.0) or _SEED_TTS_SILENCE_SECONDS)
+    turn_metrics: list[dict[str, object]] = []
+    turn_timings: list[dict[str, object]] = []
+    turn_pcm_bytes: list[bytes] = []
+    turn_transcripts: list[str] = []
+    measurement_origin = {
+        "ttft": "first silence append client send to first non-empty text delta",
+        "ttfp": "first silence append client send to first audio packet",
+        "rtf": "request-start-to-last-audio receive time divided by emitted audio duration",
+    }
     try:
-        async with _RealtimeTTSProbe(_realtime_websocket_url(request_func_input.api_url)) as client:
-            await client.configure(
-                request_func_input.model_name or request_func_input.model,
-                output_audio_format="pcm16",
-                instructions=getattr(
-                    request_func_input,
-                    "seed_tts_system_prompt",
-                    SEED_TTS_DEFAULT_OMNI_SYSTEM_PROMPT,
-                ),
-                native_duplex=False,
-                auto_response=False,
-                extra_body=speech_extra,
-                session_id=session_id,
-                timeout_s=120.0,
-            )
-            turn_metrics: list[dict[str, object]] = []
-            turn_timings: list[dict[str, object]] = []
-            turn_pcm_bytes: list[bytes] = []
-            turn_transcripts: list[str] = []
-            measurement_origin = {
-                "ttft": "conversation.item.create client send to first non-empty text delta",
-                "ttfp": "conversation.item.create client send to first audio packet",
-                "rtf": "request-start-to-last-audio receive time divided by emitted audio duration",
-            }
-            for request_index, (utterance_id, target_text) in enumerate(turn_prompts):
+        # One session per utterance. A model-native duplex session takes its
+        # text once, in the session context (``duplex_initial_user_text``), so
+        # a session cannot be re-seeded for a second target text.
+        for request_index, (utterance_id, target_text) in enumerate(turn_prompts):
+            async with _RealtimeTTSProbe(_realtime_websocket_url(request_func_input.api_url)) as client:
+                await client.configure(
+                    request_func_input.model_name or request_func_input.model,
+                    output_audio_format="pcm16",
+                    instructions=getattr(
+                        request_func_input,
+                        "seed_tts_system_prompt",
+                        SEED_TTS_DEFAULT_OMNI_SYSTEM_PROMPT,
+                    ),
+                    auto_response=True,
+                    extra_body={
+                        **speech_extra,
+                        "duplex_initial_user_text": target_text,
+                        "force_listen_count": 0,
+                    },
+                    timeout_s=120.0,
+                )
                 response_offset = len(client.events.response_ids)
                 done_before = client.events.count("response.done")
                 errors_before = len(client.events.errors())
-                turn_started_at_s = time.monotonic()
-                await client.send(
-                    {
-                        "type": "conversation.item.create",
-                        "item": {
-                            "type": "message",
-                            "role": "user",
-                            "content": [{"type": "input_text", "text": target_text}],
-                        },
-                    }
-                )
-                await client.send({"type": "response.create"})
-                await wait_for_condition(
-                    lambda: (
+
+                def turn_settled() -> bool:
+                    return (
                         client.events.count("response.done") > done_before
                         or len(client.events.errors()) > errors_before
-                    ),
-                    timeout_s=180.0,
-                    label=f"Seed-TTS Realtime TTS turn {request_index} response.done",
-                )
+                    )
+
+                turn_started_at_s = time.monotonic()
+                silence_s = await client.stream_silence(seconds=silence_seconds, until=turn_settled)
+                if silence_s > _SEED_TTS_PROMPT_RESPONSE_S:
+                    logger.warning(
+                        "Seed-TTS Realtime TTS turn %d: the model took %.1fs of silence to settle its response",
+                        request_index,
+                        silence_s,
+                    )
+                try:
+                    await wait_for_condition(
+                        turn_settled,
+                        timeout_s=180.0,
+                        label=f"Seed-TTS Realtime TTS turn {request_index} response.done",
+                    )
+                except TimeoutError as exc:
+                    raise RuntimeError(
+                        _seed_tts_turn_stall_report(client.events, response_offset, request_index, silence_s)
+                    ) from exc
                 errors = client.events.errors()
                 if len(errors) > errors_before:
                     raise RuntimeError(f"Seed-TTS Realtime TTS server error: {errors[-1]}")
-                new_audio_response_ids = [
-                    response_id
-                    for response_id in client.events.response_ids[response_offset:]
-                    if client.events.audio_bytes(response_id)
-                ]
-                if len(new_audio_response_ids) != 1:
-                    raise RuntimeError(
-                        f"Seed-TTS Realtime TTS turn {request_index} expected one audio response, "
-                        f"got {len(new_audio_response_ids)}"
-                    )
-                response_id = new_audio_response_ids[0]
+                response_id = _seed_tts_turn_response_id(client.events, response_offset, request_index)
                 timing = client.events.timing_summary(
                     after_s=turn_started_at_s,
                     input_committed_at_s=turn_started_at_s,
@@ -2518,45 +2624,43 @@ async def async_request_openai_realtime_duplex(
                 )
                 turn_transcripts.append(client.events.response_text(response_id))
                 await client.acknowledge_playback()
-            request_finished_at = time.perf_counter()
-            session_metrics = summarize_session_request_metrics(
-                turn_metrics,
-                session_id=session_id,
-            )
-            await client.close_session(timeout_s=30.0)
+                await client.close_session(timeout_s=30.0)
+        request_finished_at = time.perf_counter()
+        session_metrics = summarize_session_request_metrics(
+            turn_metrics,
+            session_id=session_id,
+        )
 
-            output.generated_text = " ".join(filter(None, turn_transcripts))
-            from vllm_omni.clients.duplex import metric_mean
+        output.generated_text = " ".join(filter(None, turn_transcripts))
+        from vllm_omni.clients.duplex import metric_mean
 
-            output.ttft = (metric_mean(session_metrics.get("ttft_ms")) or 0.0) / 1000.0
-            output.audio_ttfp = (metric_mean(session_metrics.get("ttfp_ms")) or 0.0) / 1000.0
-            output.audio_rtf = metric_mean(session_metrics.get("rtf")) or 0.0
-            output.audio_duration = (
-                sum(float(metric.get("audio_duration_ms") or 0.0) for metric in turn_metrics) / 1000.0
-            )
-            output.audio_frames = int(output.audio_duration * client.events.output_sample_rate_hz)
-            output.latency = request_finished_at - output.start_time
-            output.tts_turn_pcm_bytes = turn_pcm_bytes
-            output.tts_output_pcm_bytes = b"".join(turn_pcm_bytes)
-            if bool((request_func_input.extra_body or {}).get("save_duplex_request_metrics")):
-                output.duplex_request_metrics = turn_metrics
-                output.duplex_session_metrics = session_metrics
-            output.output_tokens = sum(
-                int(stage0.get("output_token_count") or 0)
-                for timing in turn_timings
-                if isinstance((stage0 := timing.get("stage0_tokens")), dict)
-            )
-            token_timing_measured = _apply_stage0_token_timings(
-                output,
-                [timing.get("stage0_tokens") for timing in turn_timings],
-                expected_output_tokens=output.output_tokens,
+        output.ttft = (metric_mean(session_metrics.get("ttft_ms")) or 0.0) / 1000.0
+        output.audio_ttfp = (metric_mean(session_metrics.get("ttfp_ms")) or 0.0) / 1000.0
+        output.audio_rtf = metric_mean(session_metrics.get("rtf")) or 0.0
+        output.audio_duration = sum(float(metric.get("audio_duration_ms") or 0.0) for metric in turn_metrics) / 1000.0
+        output.audio_frames = int(output.audio_duration * _SEED_TTS_OUTPUT_SAMPLE_RATE_HZ)
+        output.latency = request_finished_at - output.start_time
+        output.tts_turn_pcm_bytes = turn_pcm_bytes
+        output.tts_output_pcm_bytes = b"".join(turn_pcm_bytes)
+        if bool((request_func_input.extra_body or {}).get("save_duplex_request_metrics")):
+            output.duplex_request_metrics = turn_metrics
+            output.duplex_session_metrics = session_metrics
+        output.output_tokens = sum(
+            int(stage0.get("output_token_count") or 0)
+            for timing in turn_timings
+            if isinstance((stage0 := timing.get("stage0_tokens")), dict)
+        )
+        token_timing_measured = _apply_stage0_token_timings(
+            output,
+            [timing.get("stage0_tokens") for timing in turn_timings],
+            expected_output_tokens=output.output_tokens,
+        )
+        if not token_timing_measured and output.output_tokens > 1:
+            logger.warning(
+                "Realtime TTS session %s omitted complete engine token timing; standard TPOT/ITL are unavailable",
+                session_id,
             )
-            if not token_timing_measured and output.output_tokens > 1:
-                logger.warning(
-                    "Realtime TTS session %s omitted complete engine token timing; standard TPOT/ITL are unavailable",
-                    session_id,
-                )
-            output.success = True
+        output.success = True
     except Exception:
         output.success = False
         output.error = traceback.format_exc()
diff --git a/vllm_omni/clients/__init__.py b/vllm_omni/clients/__init__.py
index 924582bf48f..35f90477890 100644
--- a/vllm_omni/clients/__init__.py
+++ b/vllm_omni/clients/__init__.py
@@ -2,8 +2,10 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Client-side libraries for vLLM-Omni serving APIs.
 
-Modules under this package speak to a running vLLM-Omni server over the
-network. They are for applications and tests; server runtime code
+``vllm_omni.clients.duplex`` speaks to a running vLLM-Omni server over the
+network; ``vllm_omni.clients.inline_duplex`` drives an in-process
+``DuplexOmni`` handed in by the caller with the same client API. Modules here
+import no server runtime code at module load, and server runtime code
 (``vllm_omni.engine``, ``vllm_omni.entrypoints``, ``vllm_omni.model_executor``)
 must never import from here.
 """
diff --git a/vllm_omni/clients/duplex.py b/vllm_omni/clients/duplex.py
index a1d9fc1dfc4..52266b64ea7 100644
--- a/vllm_omni/clients/duplex.py
+++ b/vllm_omni/clients/duplex.py
@@ -2,9 +2,13 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Public asynchronous client for the vLLM-Omni full-duplex Realtime API.
 
-Connects to ``/v1/realtime?duplex=1`` (the normative duplex contract) and
-provides typed events, response demultiplexing, incremental playback
-acking, and transparent session resume on transport drops.
+:class:`DuplexClientBase` holds the transport-agnostic session client (typed
+events, response demultiplexing, incremental playback acking, the session
+handshake). :class:`DuplexClient` connects it to ``/v1/realtime?duplex=1``
+(the normative duplex contract) over WebSocket with transparent session
+resume on transport drops; :class:`vllm_omni.clients.inline_duplex.InlineDuplexClient`
+drives an in-process :class:`~vllm_omni.entrypoints.duplex_omni.DuplexOmni`
+with exactly the same usage.
 
 Example::
 
@@ -35,10 +39,10 @@
 import random
 import time
 import wave
+from abc import ABC, abstractmethod
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterator, Mapping, Sequence
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Protocol
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 from uuid import uuid4
 
@@ -53,6 +57,7 @@
     "AudioDelta",
     "ConnectionResumed",
     "DuplexClient",
+    "DuplexClientBase",
     "DuplexClientError",
     "DuplexConnectionError",
     "DuplexEvent",
@@ -229,7 +234,7 @@ class SessionConfig:
     idle_timeout_s: float | None = None
     extra_body: dict[str, object] = field(default_factory=dict)
 
-    def to_session_payload(self, *, model: str, session_id: str | None = None) -> dict[str, object]:
+    def to_session_payload(self, *, model: str) -> dict[str, object]:
         payload: dict[str, object] = {
             "model": model,
             "modalities": list(self.modalities),
@@ -246,8 +251,6 @@ def to_session_payload(self, *, model: str, session_id: str | None = None) -> di
             },
             "turn_detection": self.turn_detection,
         }
-        if session_id:
-            payload["session_id"] = session_id
         if self.instructions is not None:
             payload["instructions"] = self.instructions
         if self.ref_audio is not None:
@@ -368,11 +371,6 @@ def resume_token(self) -> str | None:
         value = self.raw.get("resume_token")
         return value if isinstance(value, str) else None
 
-    @property
-    def incarnation(self) -> int:
-        value = self.raw.get("incarnation")
-        return value if isinstance(value, int) else 0
-
 
 class SessionResumed(SessionCreated):
     pass
@@ -598,79 +596,84 @@ def _finish(self, event: DuplexEvent | None) -> None:
 # Client
 
 
-class WebSocketTransport(Protocol):
+class WebSocketTransport(ABC):
     """Minimal WebSocket surface the client needs (satisfied by ``websockets``)."""
 
+    @abstractmethod
     async def send(self, data: str) -> None: ...
 
+    @abstractmethod
     async def recv(self) -> str | bytes: ...
 
+    @abstractmethod
     async def close(self) -> None: ...
 
 
 ConnectFn = Callable[[str], Awaitable["WebSocketTransport"]]
 
 
-class DuplexClient:
-    """Async client for one duplex session over ``/v1/realtime?duplex=1``.
+class DuplexClientBase(ABC):
+    """Transport-agnostic duplex session client.
 
-    ``session_id`` only names the session this client creates: entering the
-    client always performs the ``session.update`` handshake. Resuming an
-    existing session is supported only as automatic reconnect within the same
-    client instance (see ``ReconnectPolicy``); taking over a session from a
-    new client requires the wire-level ``session.resume`` handshake
-    (``resume_token``, ``incarnation``, ``last_received_server_event_seq``),
-    which this client does not expose.
+    Everything a caller touches (typed events, response demux, input helpers,
+    playback acks, the ``session.update`` handshake) lives here. A subclass
+    only supplies the transport: :meth:`_open` establishes it and must deliver
+    the server's ``session.created`` payload through :meth:`_dispatch`,
+    :meth:`_send_command` delivers one client event, :meth:`_teardown`
+    releases the transport.
     """
 
     def __init__(
         self,
-        url: str,
         *,
         model: str,
         config: SessionConfig | None = None,
-        session_id: str | None = None,
-        reconnect: ReconnectPolicy | None = ReconnectPolicy(),
-        heartbeat_interval_s: float | None = 30.0,
         handshake_timeout_s: float = 30.0,
-        connect: ConnectFn | None = None,
     ) -> None:
-        self.url = url
         self.model = model
         self.config = config or SessionConfig()
-        self.session_id = session_id
+        #: Allocated by the server; ``None`` until ``session.created`` arrives.
+        self.session_id: str | None = None
         self.session_info: dict[str, object] = {}
-        self.incarnation = 0
-        self.resume_token: str | None = None
-        self._reconnect = reconnect
-        self._heartbeat_interval_s = heartbeat_interval_s
         self._handshake_timeout_s = handshake_timeout_s
-        self._connect_fn: ConnectFn = connect or self._default_connect
-        self._ws: WebSocketTransport | None = None
-        self._reader_task: asyncio.Task[None] | None = None
-        self._heartbeat_task: asyncio.Task[None] | None = None
         self._subscribers: list[asyncio.Queue[DuplexEvent | _ClosedMarker]] = []
         self._response_queue: asyncio.Queue[ResponseHandle | _ClosedMarker | _ErrorMarker] = asyncio.Queue(
             maxsize=_MAX_BUFFERED_EVENTS
         )
         self._responses: dict[str, ResponseHandle] = {}
-        self._last_server_event_seq: int | None = None
         self._input_audio_end_ms = 0.0
         self._closing = False
         self._closed = asyncio.Event()
         self._closed_marker: _ClosedMarker | None = None
 
+    # -- transport hooks ------------------------------------------------------
+
+    @abstractmethod
+    async def _open(self) -> None:
+        """Establish the transport and start delivering server events via ``_dispatch``.
+
+        Called once from :meth:`__aenter__`; the base then sends the
+        ``session.update`` handshake and waits for ``session.created``.
+        """
+
+    @abstractmethod
+    async def _send_command(self, payload: dict[str, object]) -> None:
+        """Deliver one client event (already stamped with ``event_id``)."""
+
+    @abstractmethod
+    async def _teardown(self) -> None:
+        """Release the transport; must be idempotent."""
+
     # -- lifecycle ----------------------------------------------------------
 
-    async def __aenter__(self) -> DuplexClient:
-        self._ws = await self._connect_fn(self._target_url())
+    async def __aenter__(self) -> DuplexClientBase:
         handshake_queue = self._add_subscriber()
         try:
-            self._reader_task = asyncio.create_task(self._read_loop(), name="duplex-client-reader")
+            await self._open()
             await self.send(
                 {
                     "type": "session.update",
-                    "session": self.config.to_session_payload(model=self.model, session_id=self.session_id),
+                    "session": self.config.to_session_payload(model=self.model),
                 }
             )
             created = await self._wait_on_queue(
@@ -679,14 +682,12 @@ async def __aenter__(self) -> DuplexClient:
                 timeout_s=self._handshake_timeout_s,
             )
         except BaseException:
-            await self._teardown()
+            await self._teardown_quietly()
             raise
         finally:
             self._remove_subscriber(handshake_queue)
         assert isinstance(created, SessionCreated)
         self._adopt_session(created)
-        if self._heartbeat_interval_s is not None:
-            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop(), name="duplex-client-heartbeat")
         return self
 
     async def __aexit__(self, exc_type, exc, traceback) -> None:
@@ -706,7 +707,7 @@ async def __aexit__(self, exc_type, exc, traceback) -> None:
                 except DuplexClientError:
                     pass
         finally:
-            await self._teardown()
+            await self._teardown_quietly()
 
     async def close(self, *, timeout_s: float = 20.0) -> None:
         """Send ``session.close`` and wait for the server to confirm."""
@@ -723,6 +724,12 @@ async def close(self, *, timeout_s: float = 20.0) -> None:
         except asyncio.TimeoutError:
             self._finalize("close timed out", expected=True)
 
+    async def _teardown_quietly(self) -> None:
+        self._closing = True
+        if not self._closed.is_set():
+            self._finalize("closed", expected=True)
+        await self._teardown()
+
     # -- input ----------------------------------------------------------------
 
     async def append_audio(
@@ -925,53 +932,25 @@ async def send(self, event: dict[str, object]) -> str:
         payload = dict(event)
         payload.setdefault("event_id", f"evt_{uuid4().hex}")
         try:
-            await self._ws.send(json.dumps(payload))
+            await self._send_command(payload)
         except asyncio.CancelledError:
             raise
+        except DuplexClientError:
+            raise
         except Exception as exc:
             raise DuplexConnectionError(f"send failed: {exc}") from exc
         return payload["event_id"]
 
     # -- internals ---------------------------------------------------------------
 
-    def _target_url(self) -> str:
-        parts = urlsplit(self.url)
-        path = parts.path if parts.path not in ("", "/") else "/v1/realtime"
-        query = dict(parse_qsl(parts.query, keep_blank_values=True))
-        query.setdefault("duplex", "1")
-        query.setdefault("model", self.model)
-        # The client always opens with an explicit session.update (and resumes
-        # with an explicit session.resume). Autostart would race that handshake:
-        # with a model query param, the server creates a bare default session
-        # before reading the first client event, silently dropping ref_audio
-        # and the model-specific extra_body. Force it off even when the caller's
-        # URL carries autostart=1 — this client cannot operate over it.
-        query["autostart"] = "0"
-        return urlunsplit((parts.scheme or "ws", parts.netloc, path, urlencode(query), parts.fragment))
-
-    async def _default_connect(self, url: str) -> WebSocketTransport:
-        try:
-            import websockets
-        except ImportError as exc:  # pragma: no cover - websockets is a pinned dep
-            raise DuplexConnectionError("The duplex client requires the 'websockets' package") from exc
-        try:
-            return await websockets.connect(url, max_size=_MAX_FRAME_BYTES)
-        except asyncio.CancelledError:
-            raise
-        except Exception as exc:
-            raise DuplexConnectionError(f"connect to {url} failed: {exc}") from exc
-
     def _adopt_session(self, event: SessionCreated) -> None:
-        # A resume activation carries no nested session object; keep the
-        # session_info captured at the original handshake in that case.
+        # session.created and session.resumed both carry the engine's current
+        # session object; keep the last one seen.
         if event.session:
             self.session_info = event.session
         session_id = event.session.get("session_id") or event.session.get("id") or event.session_id
         if isinstance(session_id, str) and session_id:
             self.session_id = session_id
-        self.incarnation = event.incarnation
-        if event.resume_token:
-            self.resume_token = event.resume_token
 
     def _announce(self, handle: ResponseHandle) -> None:
         """Deliver a handle to responses() exactly once, decision known."""
@@ -1013,36 +992,18 @@ async def _wait_on_queue(
             if item.type in types:
                 return item
 
-    async def _read_loop(self) -> None:
-        while True:
-            try:
-                while True:
-                    raw = await self._ws.recv()
-                    if isinstance(raw, (bytes, bytearray)):
-                        continue
-                    try:
-                        data = json.loads(raw)
-                    except json.JSONDecodeError:
-                        continue
-                    if isinstance(data, dict):
-                        await self._dispatch(data)
-            except asyncio.CancelledError:
-                raise
-            except Exception as exc:
-                if self._closing or self._closed.is_set():
-                    self._finalize("closed", expected=True)
-                    return
-                if await self._attempt_resume():
-                    continue
-                self._finalize(f"connection lost: {exc}", expected=False)
-                return
+    def _accept_event(self, data: dict[str, object]) -> bool:
+        """Transport hook: return False to drop ``data`` before dispatch (duplicates)."""
+        del data
+        return True
+
+    async def _after_dispatch(self, event: DuplexEvent, data: dict[str, object]) -> None:
+        """Transport hook run after an event was delivered to subscribers."""
+        del event, data
 
     async def _dispatch(self, data: dict[str, object]) -> None:
-        seq = data.get("server_event_seq")
-        if isinstance(seq, int):
-            if self._last_server_event_seq is not None and seq <= self._last_server_event_seq:
-                return  # duplicate delivered by resume replay
-            self._last_server_event_seq = seq
+        if not self._accept_event(data):
+            return
         event = wrap_event(data)
 
         if isinstance(event, SessionResumed):
@@ -1109,14 +1070,130 @@ async def _dispatch(self, data: dict[str, object]) -> None:
         elif isinstance(event, SessionExpired):
             reason = data.get("reason")
             self._finalize(f"expired: {reason}" if reason else "expired", expected=False)
-        elif event.type == "session.resync_required":
+
+        await self._after_dispatch(event, data)
+
+    def _finalize(self, reason: str, *, expected: bool) -> None:
+        if self._closed.is_set():
+            return
+        marker = _ClosedMarker(reason=reason, expected=expected)
+        self._closed_marker = marker
+        self._closed.set()
+        for handle in self._responses.values():
+            handle._finish(None)
+        self._responses.clear()
+        for queue in (*self._subscribers, self._response_queue):
+            _put_drop_oldest(queue, marker)
+
+
+class DuplexClient(DuplexClientBase):
+    """Async client for one duplex session over ``/v1/realtime?duplex=1``."""
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        model: str,
+        config: SessionConfig | None = None,
+        reconnect: ReconnectPolicy | None = ReconnectPolicy(),
+        heartbeat_interval_s: float | None = 30.0,
+        handshake_timeout_s: float = 30.0,
+        connect: ConnectFn | None = None,
+    ) -> None:
+        super().__init__(model=model, config=config, handshake_timeout_s=handshake_timeout_s)
+        self.url = url
+        self.resume_token: str | None = None
+        self._reconnect = reconnect
+        self._heartbeat_interval_s = heartbeat_interval_s
+        self._connect_fn: ConnectFn = connect or self._default_connect
+        self._ws: WebSocketTransport | None = None
+        self._reader_task: asyncio.Task[None] | None = None
+        self._heartbeat_task: asyncio.Task[None] | None = None
+        self._last_server_event_seq: int | None = None
+
+    # -- transport hooks ------------------------------------------------------
+
+    async def _open(self) -> None:
+        self._ws = await self._connect_fn(self._target_url())
+        self._reader_task = asyncio.create_task(self._read_loop(), name="duplex-client-reader")
+
+    async def __aenter__(self) -> DuplexClient:
+        await super().__aenter__()
+        if self._heartbeat_interval_s is not None:
+            self._heartbeat_task = asyncio.create_task(self._heartbeat_loop(), name="duplex-client-heartbeat")
+        return self
+
+    async def _send_command(self, payload: dict[str, object]) -> None:
+        if self._ws is None:
+            raise DuplexConnectionError("send failed: transport is not connected")
+        await self._ws.send(json.dumps(payload))
+
+    async def _teardown(self) -> None:
+        for task in (self._heartbeat_task, self._reader_task):
+            if task is not None and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                    pass
+        if self._ws is not None:
+            try:
+                await self._ws.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    # -- internals ---------------------------------------------------------------
+
+    def _target_url(self) -> str:
+        parts = urlsplit(self.url)
+        path = parts.path if parts.path not in ("", "/") else "/v1/realtime"
+        query = dict(parse_qsl(parts.query, keep_blank_values=True))
+        query.setdefault("duplex", "1")
+        query.setdefault("model", self.model)
+        # The client always opens with an explicit session.update (and resumes
+        # with an explicit session.resume). Autostart would race that handshake:
+        # with a model query param, the server creates a bare default session
+        # before reading the first client event, silently dropping ref_audio
+        # and the model-specific extra_body. Force it off even when the caller's
+        # URL carries autostart=1 — this client cannot operate over it.
+        query["autostart"] = "0"
+        return urlunsplit((parts.scheme or "ws", parts.netloc, path, urlencode(query), parts.fragment))
+
+    async def _default_connect(self, url: str) -> WebSocketTransport:
+        try:
+            import websockets
+        except ImportError as exc:  # pragma: no cover - websockets is a pinned dep
+            raise DuplexConnectionError("The duplex client requires the 'websockets' package") from exc
+        try:
+            return await websockets.connect(url, max_size=_MAX_FRAME_BYTES)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            raise DuplexConnectionError(f"connect to {url} failed: {exc}") from exc
+
+    def _adopt_session(self, event: SessionCreated) -> None:
+        super()._adopt_session(event)
+        if event.resume_token:
+            self.resume_token = event.resume_token
+
+    def _accept_event(self, data: dict[str, object]) -> bool:
+        seq = data.get("server_event_seq")
+        if isinstance(seq, int):
+            if self._last_server_event_seq is not None and seq <= self._last_server_event_seq:
+                return False  # duplicate delivered by resume replay
+            self._last_server_event_seq = seq
+        return True
+
+    async def _after_dispatch(self, event: DuplexEvent, data: dict[str, object]) -> None:
+        if event.type == "session.resync_required":
             # The server stopped journaling this session's events, so any
             # retained resume credential will be refused on the next
             # session.resume. Drop it now: a later transport failure then
             # finalizes immediately instead of burning reconnect attempts.
             self.resume_token = None
 
-        if isinstance(seq, int) and not self._closed.is_set():
+        seq = data.get("server_event_seq")
+        if isinstance(seq, int) and not self._closed.is_set() and self._ws is not None:
             try:
                 await self._ws.send(json.dumps({"type": "session.event_ack", "server_event_seq": seq}))
             except asyncio.CancelledError:
@@ -1124,6 +1201,30 @@ async def _dispatch(self, data: dict[str, object]) -> None:
             except Exception:
                 pass  # the reader will observe the transport failure itself
 
+    async def _read_loop(self) -> None:
+        while True:
+            try:
+                while True:
+                    raw = await self._ws.recv()
+                    if isinstance(raw, (bytes, bytearray)):
+                        continue
+                    try:
+                        data = json.loads(raw)
+                    except json.JSONDecodeError:
+                        continue
+                    if isinstance(data, dict):
+                        await self._dispatch(data)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                if self._closing or self._closed.is_set():
+                    self._finalize("closed", expected=True)
+                    return
+                if await self._attempt_resume():
+                    continue
+                self._finalize(f"connection lost: {exc}", expected=False)
+                return
+
     async def _attempt_resume(self) -> bool:
         policy = self._reconnect
         if policy is None or not self.resume_token or not self.session_id:
@@ -1142,7 +1243,6 @@ async def _attempt_resume(self) -> bool:
                         {
                             "type": "session.resume",
                             "session_id": self.session_id,
-                            "incarnation": self.incarnation,
                             "resume_token": self.resume_token,
                             "last_received_server_event_seq": self._last_server_event_seq or 0,
                         }
@@ -1162,7 +1262,10 @@ async def _attempt_resume(self) -> bool:
                         continue
                     event_type = data.get("type")
                     if event_type == "session.resumed":
+                        previous = self._ws
                         self._ws = ws
+                        if previous is not None and previous is not ws:
+                            await self._close_quietly(previous)
                         await self._dispatch({"type": "connection.resumed", "attempt": attempt})
                         await self._dispatch(data)
                         for entry in pending:
@@ -1212,35 +1315,6 @@ async def _heartbeat_loop(self) -> None:
             except DuplexClientError:
                 return
 
-    def _finalize(self, reason: str, *, expected: bool) -> None:
-        if self._closed.is_set():
-            return
-        marker = _ClosedMarker(reason=reason, expected=expected)
-        self._closed_marker = marker
-        self._closed.set()
-        for handle in self._responses.values():
-            handle._finish(None)
-        self._responses.clear()
-        for queue in (*self._subscribers, self._response_queue):
-            _put_drop_oldest(queue, marker)
-
-    async def _teardown(self) -> None:
-        self._closing = True
-        if not self._closed.is_set():
-            self._finalize("closed", expected=True)
-        for task in (self._heartbeat_task, self._reader_task):
-            if task is not None and not task.done():
-                task.cancel()
-                try:
-                    await task
-                except (asyncio.CancelledError, Exception):  # noqa: BLE001
-                    pass
-        if self._ws is not None:
-            try:
-                await self._ws.close()
-            except Exception:  # noqa: BLE001
-                pass
-
 
 # ---------------------------------------------------------------------------
 # Test/benchmark collector
@@ -1368,7 +1442,7 @@ def __init__(self) -> None:
         self.response_ids: list[str] = []
         self.output_sample_rate_hz = 24_000
 
-    async def consume(self, client: DuplexClient) -> None:
+    async def consume(self, client: DuplexClientBase) -> None:
         """Subscribe to ``client`` and collect until the session ends."""
         try:
             async for event in client.events():
@@ -1795,15 +1869,12 @@ def build_realtime_url(
     model: str | None,
     *,
     autostart: bool | None = None,
-    native_duplex: bool | None = None,
-    session_id: str | None = None,
     extra_query: dict[str, str] | None = None,
 ) -> str:
     """Add explicit duplex query parameters to a Realtime URL.
 
     :class:`DuplexClient` builds its own URL; this helper is for drivers that
-    speak the wire protocol directly. ``native_duplex`` sets the per-session
-    model-native opt-in query flag; other model-specific query flags ride in
+    speak the wire protocol directly. Model-specific query flags ride in
     ``extra_query``. ``http(s)`` URLs are rewritten to ``ws(s)``.
     """
     parts = urlsplit(url)
@@ -1815,14 +1886,10 @@ def build_realtime_url(
     query.setdefault("duplex", "1")
     if model:
         query.setdefault("model", model)
-    if native_duplex is not None:
-        query["native_duplex"] = "1" if native_duplex else "0"
     for key, value in (extra_query or {}).items():
         query.setdefault(key, value)
     if autostart is not None:
         query.setdefault("autostart", "1" if autostart else "0")
-    if session_id:
-        query.setdefault("session_id", session_id)
     return urlunsplit((parts.scheme, parts.netloc, parts.path, urlencode(query), parts.fragment))
 
 
@@ -1880,7 +1947,7 @@ def values(metric: str, *, positive: bool = False) -> list[float]:
     return summary
 
 
-async def acknowledge_collected_playback(client: DuplexClient, collector: EventCollector) -> None:
+async def acknowledge_collected_playback(client: DuplexClientBase, collector: EventCollector) -> None:
     """Ack playback of every collected response's audio (probe shorthand).
 
     A response that has produced no audio yet is still acked (0 ms) unless it
diff --git a/vllm_omni/clients/inline_duplex.py b/vllm_omni/clients/inline_duplex.py
new file mode 100644
index 00000000000..79c09e014fe
--- /dev/null
+++ b/vllm_omni/clients/inline_duplex.py
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""In-process duplex client: the :class:`DuplexClient` usage over a ``DuplexOmni``.
+
+Example::
+
+    from vllm_omni.clients.inline_duplex import InlineDuplexClient
+    from vllm_omni.clients.minicpmo_4_5 import create_duplex_session_config
+    from vllm_omni.entrypoints.duplex_omni import DuplexOmni
+
+    omni = DuplexOmni(model="openbmb/MiniCPM-o-4_5", trust_remote_code=True)
+    cfg = create_duplex_session_config(ref_audio=audio_data_url(wav_bytes))
+    async with InlineDuplexClient(omni, model="openbmb/MiniCPM-o-4_5", config=cfg) as client:
+        await client.stream_pcm(pcm16)
+        await client.commit()
+        async for response in client.responses():
+            async for chunk in response.audio():
+                play(chunk)
+            break
+
+There is no transport to drop, so this client has no reconnect, resume,
+heartbeat or event-acknowledgement machinery. The ``DuplexOmni`` instance is
+passed in by the caller; this module never imports server runtime code at
+import time.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from vllm_omni.clients.duplex import DuplexClientBase, DuplexConnectionError, SessionConfig
+
+if TYPE_CHECKING:
+    from vllm_omni.engine.duplex.realtime_commands import RealtimeInputDefaults
+    from vllm_omni.entrypoints.duplex_omni import DuplexOmni, DuplexSessionHandle
+
+__all__ = ["InlineDuplexClient"]
+
+#: Acknowledgements are a websocket-journal concern; heartbeats are lease touches and go through.
+_TRANSPORT_ONLY_EVENTS = frozenset({"session.event_ack"})
+
+
+class InlineDuplexClient(DuplexClientBase):
+    """Async client for one duplex session on an in-process :class:`DuplexOmni`."""
+
+    def __init__(
+        self,
+        omni: DuplexOmni,
+        *,
+        model: str,
+        config: SessionConfig | None = None,
+        handshake_timeout_s: float = 30.0,
+    ) -> None:
+        super().__init__(model=model, config=config, handshake_timeout_s=handshake_timeout_s)
+        self.omni = omni
+        self._handle: DuplexSessionHandle | None = None
+        self._pump_task: asyncio.Task[None] | None = None
+        self._handshake_pending = False
+
+    # -- transport hooks ------------------------------------------------------
+
+    async def _open(self) -> None:
+        # The handle's first event is ``session.created``; the pump delivers
+        # it through ``_dispatch`` where the base handshake is waiting.
+        self._handle = await self.omni.open_session(self.config.to_session_payload(model=self.model))
+        # The base class follows up with the ``session.update`` handshake; the
+        # open above already carried that session object, so it is not resent.
+        self._handshake_pending = True
+        self._pump_task = asyncio.create_task(self._pump_events(), name="inline-duplex-client-pump")
+
+    def _input_defaults(self) -> RealtimeInputDefaults:
+        """Audio format / sample-rate / VAD defaults declared by this session's object."""
+        from vllm_omni.engine.duplex.realtime_commands import RealtimeInputDefaults
+
+        session_payload = self.session_info or self.config.to_session_payload(model=self.model)
+        return RealtimeInputDefaults().with_session_payload(session_payload)
+
+    async def _send_command(self, payload: dict[str, object]) -> None:
+        handle = self._handle
+        if handle is None or handle.closed:
+            raise DuplexConnectionError("send failed: session is not open")
+        event_type = payload.get("type")
+        if event_type == "session.update" and self._handshake_pending:
+            self._handshake_pending = False
+            return
+        if event_type == "session.close":
+            await handle.close()
+            return
+        if event_type in _TRANSPORT_ONLY_EVENTS:
+            return
+        # Lazy import keeps ``vllm_omni.clients`` free of runtime imports at
+        # module load; the caller already holds a live DuplexOmni.
+        from vllm_omni.engine.duplex.commands import DuplexCommandError, command_from_realtime
+        from vllm_omni.engine.duplex.events import error_event
+
+        try:
+            command = command_from_realtime(payload, defaults=self._input_defaults())
+        except DuplexCommandError as exc:
+            await self._dispatch(
+                error_event(exc.code, str(exc), event_id=exc.event_id or payload.get("event_id")).to_realtime()
+            )
+            return
+        await handle.submit(command)
+
+    async def _teardown(self) -> None:
+        pump = self._pump_task
+        if pump is not None and not pump.done():
+            pump.cancel()
+            try:
+                await pump
+            except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                pass
+        handle = self._handle
+        if handle is not None and not handle.closed:
+            try:
+                await handle.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    # -- internals ---------------------------------------------------------------
+
+    async def _pump_events(self) -> None:
+        handle = self._handle
+        assert handle is not None
+        reason = "closed"
+        try:
+            async for event in handle.events():
+                await self._dispatch(event.to_realtime())
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            reason = f"session failed: {exc}"
+            self._finalize(reason, expected=False)
+            return
+        self._finalize(reason, expected=True)
diff --git a/vllm_omni/clients/minicpmo_4_5.py b/vllm_omni/clients/minicpmo_4_5.py
index 4b25346d487..b433463247e 100644
--- a/vllm_omni/clients/minicpmo_4_5.py
+++ b/vllm_omni/clients/minicpmo_4_5.py
@@ -13,7 +13,7 @@
 
 def create_duplex_session_config(*, ref_audio: str | None = None, **overrides: object) -> SessionConfig:
     """Session preset matching the MiniCPM-o 4.5 native duplex deployment."""
-    extra_body: dict[str, object] = {"native_duplex": True, "force_listen_count": 0}
+    extra_body: dict[str, object] = {"force_listen_count": 0}
     extra_body.update(overrides.pop("extra_body", {}))
     config = SessionConfig(
         ref_audio=ref_audio,
diff --git a/vllm_omni/config/stage_config.py b/vllm_omni/config/stage_config.py
index 9c9186c1647..c96f514e81a 100644
--- a/vllm_omni/config/stage_config.py
+++ b/vllm_omni/config/stage_config.py
@@ -309,14 +309,17 @@ class PipelineConfig:
     diffusers_class_name: str | None = None
     diffusers_class_aliases: tuple[str, ...] = ()
     endpoint_restrictions: tuple[EndpointRestriction, ...] = ()
-    # Optional model-owned duplex planner loaded by the stable engine runtime.
+    # Dotted path of the model's ``DuplexModelPlugin``. A pipeline is a duplex
+    # model iff this is set: ``vllm-omni serve`` then always runs it through
+    # ``DuplexOmni`` (every served surface runs on a duplex session) and the engine hosts one
+    # ``DuplexOrchestrator`` with the plugin loaded.
+    duplex_plugin: str | None = None
+    # Legacy duplex wiring of the models that are not ported to the plugin
+    # framework yet (PersonaPlex, Nemotron VoiceChat). Nothing reads them: a
+    # pipeline that only declares these is served turn-based. Each field goes
+    # away with the follow-up PR that ports its model to ``duplex_plugin``.
     duplex_runtime_extension: str | None = None
-    # Optional model-owned Serving adapter loaded only when the Realtime duplex
-    # endpoint is enabled. Generic OpenAI modules must not select a model.
     duplex_serving_adapter: str | None = None
-    # Explicitly enable the stable duplex control mechanism. This is separate
-    # from the optional model extension because turn-commit-only deployments
-    # do not require a model planner.
     duplex_control_enabled: bool = False
     # Bundled deploy defaults for this concrete pipeline topology. The file is
     # loaded from vllm_omni/deploy; None uses DeployConfig defaults.
@@ -510,6 +513,12 @@ class DuplexSessionRuntimeConfig:
     max_pending_input_bytes_per_session: int = 16 * 1024 * 1024
     max_pending_turns_per_session: int = 4
     max_sessions: int = 1
+    # Unread by the plugin framework. It used to bound the per-session
+    # completed-append table that made a retried append RPC submit once; the
+    # framework carries appends as one-way commands on the runner's ordered
+    # mailbox, so there is no client-visible retry to deduplicate. The field
+    # stays so the deploy configs of the models that are not ported yet still
+    # parse, and goes away with the PR that ports the last of them.
     completed_append_cache_size: int = 256
     server_vad_model_path: str | None = None
     # Startup warmup: run this many silent 80 ms-style frames through a
diff --git a/vllm_omni/deploy/minicpmo_4_5.yaml b/vllm_omni/deploy/minicpmo_4_5.yaml
index 4e9fd5a77c3..ca772afbd4e 100644
--- a/vllm_omni/deploy/minicpmo_4_5.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5.yaml
@@ -1,8 +1,8 @@
 # MiniCPM-o 4.5 three-stage deploy on one large-memory GPU.
 pipeline: minicpmo_4_5
 async_chunk: true
-# Native full-duplex shares this profile with /v1/chat/completions. Every other
-# duplex_session knob keeps its runtime default.
+# session_mode: duplex makes vllm-omni serve run this model duplex-only
+# (/v1/realtime?duplex=1); every other duplex_session knob keeps its runtime default.
 session_mode: duplex
 # Keep the active window aligned with the session and stage capacities below.
 # A smaller window serializes first-packet generation for concurrent chat turns.
diff --git a/vllm_omni/deploy/minicpmo_4_5_2gpu.yaml b/vllm_omni/deploy/minicpmo_4_5_2gpu.yaml
index 9c381881303..9600e595972 100644
--- a/vllm_omni/deploy/minicpmo_4_5_2gpu.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5_2gpu.yaml
@@ -4,8 +4,8 @@
 # isolated from codec/vocoder contention while preserving stage-2 batching.
 pipeline: minicpmo_4_5
 async_chunk: true
-# Native full-duplex shares this profile with /v1/chat/completions. Every other
-# duplex_session knob keeps its runtime default.
+# session_mode: duplex makes vllm-omni serve run this model duplex-only
+# (/v1/realtime?duplex=1); every other duplex_session knob keeps its runtime default.
 session_mode: duplex
 # Keep the active window aligned with the session and stage capacities below.
 # A smaller window serializes first-packet generation for concurrent chat turns.
diff --git a/vllm_omni/deploy/minicpmo_4_5_3gpu.yaml b/vllm_omni/deploy/minicpmo_4_5_3gpu.yaml
index 5eddbb6f4eb..aae5312183a 100644
--- a/vllm_omni/deploy/minicpmo_4_5_3gpu.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5_3gpu.yaml
@@ -4,8 +4,8 @@
 # Code2Wav run independently on GPUs 0, 1, and 2.
 pipeline: minicpmo_4_5
 async_chunk: true
-# Native full-duplex shares this profile with /v1/chat/completions. Every other
-# duplex_session knob keeps its runtime default.
+# session_mode: duplex makes vllm-omni serve run this model duplex-only
+# (/v1/realtime?duplex=1); every other duplex_session knob keeps its runtime default.
 session_mode: duplex
 # Keep the active window aligned with the session and stage capacities below.
 # A smaller window serializes first-packet generation for concurrent chat turns.
diff --git a/vllm_omni/deploy/minicpmo_4_5_8x4090.yaml b/vllm_omni/deploy/minicpmo_4_5_8x4090.yaml
index eacc069d1fc..00b1090f898 100644
--- a/vllm_omni/deploy/minicpmo_4_5_8x4090.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5_8x4090.yaml
@@ -15,8 +15,9 @@
 # so 4096 is the empirically-verified safe ceiling.
 pipeline: minicpmo_4_5
 async_chunk: true
-# Native full-duplex shares this profile with /v1/chat/completions. The default
-# duplex_session caps sessions at 1, matching Stage 0/1 max_num_seqs below.
+# session_mode: duplex makes vllm-omni serve run this model duplex-only
+# (/v1/realtime?duplex=1). The default duplex_session caps sessions at 1,
+# matching Stage 0/1 max_num_seqs below.
 session_mode: duplex
 active_stream_window: 1
 
diff --git a/vllm_omni/engine/async_omni_engine.py b/vllm_omni/engine/async_omni_engine.py
index 6850e6b29f6..3469d8fee5b 100644
--- a/vllm_omni/engine/async_omni_engine.py
+++ b/vllm_omni/engine/async_omni_engine.py
@@ -1,498 +1,45 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-"""
-Async Omni Engine for vLLM-Omni multi-stage runtime.
-
-AsyncOmniEngine in the caller's thread is a thin proxy that communicates
-with the Orchestrator (running in a background thread) via janus queues.
-"""
+"""AsyncOmniEngine: the turn-based engine (add_request / streaming updates / CFG companions / interaction)."""
 
 from __future__ import annotations
 
-import asyncio
-import concurrent.futures
 import copy
-import queue
 import shutil
-import threading
 import time
-import uuid
-import weakref
 from collections.abc import Mapping, Sequence
 from typing import Any, Literal, cast
 
-import janus
-from vllm import envs as vllm_envs
 from vllm.inputs import PromptType
 from vllm.logger import init_logger
 from vllm.v1.engine import EngineCoreRequest
-from vllm.v1.engine.input_processor import InputProcessor
-
-from vllm_omni.config.config_factory import StageConfigFactory
-from vllm_omni.config.resolver import OmniConfigResolution, resolve_omni_config
-from vllm_omni.config.stage_config import (
-    DuplexSessionRuntimeConfig,
-    PipelineConfig,
-    load_deploy_config,
-)
+
 from vllm_omni.data_entry_keys import REQUEST_ARTIFACT_DIRS_KEY, TRANSFORM_OWNED_META_KEYS
 from vllm_omni.engine import OmniEngineCoreRequest
 from vllm_omni.engine.async_engine_utils import (
-    SHUTDOWN_ENQUEUE_TIMEOUT_S,
-    SHUTDOWN_JOIN_TIMEOUT_S,
     apply_omni_final_stage_metadata,
-    enqueue_orchestrator_shutdown,
     inject_global_id,
-    is_abort_transport_shutdown,
-    is_janus_sync_queue_shutdown,
-    shutdown_runtime_after_orchestrator,
     upgrade_to_omni_request,
-    weak_shutdown_async_omni_engine,
-)
-from vllm_omni.engine.duplex.control_client import DuplexControlClient
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.runtime import (
-    load_duplex_runtime_extension,
-    validate_duplex_runtime_extension,
 )
 from vllm_omni.engine.messages import (
-    AbortRequestMessage,
-    AbortResultMessage,
     AddCompanionRequestMessage,
-    CollectiveRPCRequestMessage,
-    CollectiveRPCResultMessage,
-    EngineQueueMessage,
-    ErrorMessage,
     InteractionMessage,
-    OutputMessage,
     StageSubmissionMessage,
 )
-from vllm_omni.engine.orchestrator import Orchestrator
-from vllm_omni.engine.rpc_result_router import CorrelatedRpcClient
+from vllm_omni.engine.omni_engine_base import OmniEngineBase, StageRuntimeInfo
+from vllm_omni.engine.orchestrator import Orchestrator, OrchestratorBase
 from vllm_omni.engine.serialization import deserialize_additional_information
-from vllm_omni.engine.stage_client import StageClient
-from vllm_omni.engine.stage_init_utils import build_stage0_input_processor
-from vllm_omni.engine.stage_pool import StagePool
-from vllm_omni.engine.stage_runtime import (
-    StageRuntimeInfo,
-    create_stage_runtime,
-)
-from vllm_omni.entrypoints.pd_utils import PDDisaggregationMixin
-from vllm_omni.entrypoints.utils import parse_stage_overrides
 from vllm_omni.inputs.data import OmniInteractionPrompt, OmniSamplingParams
-from vllm_omni.metrics.prometheus import OmniRequestCounter
 
 logger = init_logger(__name__)
 
-_STARTUP_POLL_INTERVAL_S = 1.0
-_REQUEST_QUEUE_MAXSIZE = 256
-_ConfigResolutionResult = OmniConfigResolution | tuple[str | None, list[Any], str | None]
-
-
-def load_and_resolve_stage_configs(
-    model: str,
-    kwargs: dict[str, Any],
-    *,
-    trust_remote_code: bool | None,
-    deploy_config_path: str | None,
-    stage_overrides: Mapping[str, Mapping[str, Any]] | None,
-    strategy_config_path: str | None,
-) -> OmniConfigResolution:
-    """Compatibility seam delegating to the single config resolver."""
-    return resolve_omni_config(
-        model,
-        trust_remote_code=trust_remote_code,
-        cli_overrides=kwargs,
-        deploy_config_path=deploy_config_path,
-        stage_overrides=stage_overrides,
-        strategy_config_path=strategy_config_path,
-    )
-
-
-class AsyncOmniEngine:
-    """Thin proxy that launches an Orchestrator in a background thread.
-
-    All stage clients, input/output processors, and stage-to-stage transfer
-    logic live inside the Orchestrator coroutine (running in its own thread
-    with a dedicated asyncio event loop). This class communicates with it
-    via janus queues (sync side for callers, async side for orchestrator).
-
-    Args:
-        model: Model name or path
-        init_timeout: Total timeout waiting for orchestrator startup (seconds).
-        stage_init_timeout: Timeout for stage initialization (seconds)
-        **kwargs: Additional arguments
-    """
-
-    # Class-level defaults so tests that bypass __init__ via object.__new__
-    # don't AttributeError when stage-init / forward paths touch these attrs.
-    _log_stats: bool = False
-    _coordinator_runtime: Any = None
-    _transfer_emitter: Any = None
-    _prom_metrics: Any = None
-    _enable_orch_monitor: bool = False
-    # Lazily created by get_output_blocking_async().
-    _output_drain_executor: concurrent.futures.ThreadPoolExecutor | None = None
-
-    def __init__(
-        self,
-        model: str,
-        stage_init_timeout: int = 300,
-        init_timeout: int = 600,
-        single_stage_mode: bool = False,
-        transfer_emitter: Any = None,
-        prom_metrics: Any = None,
-        log_stats: bool = False,
-        tokenizer: str | None = None,
-        trust_remote_code: bool | None = None,
-        **kwargs: Any,
-    ) -> None:
-        self.model = model
-        self.tokenizer = tokenizer
-        # Cached by get_diffusion_od_config().
-        self._diffusion_od_config_view: Any = None
-        startup_timeout = int(init_timeout)
-        # Forwarded into Orchestrator so its _forward_to_next_stage path can
-        # emit per-edge transfer_tx_s / transfer_size_bytes histograms.
-        # Optional: when None, Orchestrator silently skips TX emit (existing
-        # RX path still works via OrchestratorAggregator).
-        self._transfer_emitter = transfer_emitter
-        self._prom_metrics = prom_metrics
-        # Drives upstream EngineCore + scheduler stats production. When False
-        # the engine skips SchedulerStats / IterationStats; the per-(stage,
-        # replica) vllm:* wrap stays registered but reads zero. Respects the
-        # --log-stats CLI flag set by the user via OmniBase.
-        self._log_stats = log_stats
-        self._enable_orch_monitor = bool(kwargs.pop("enable_orch_monitor", False))
-
-        logger.info(f"[AsyncOmniEngine] Initializing with model {model}")
-
-        # ------------------------------------------------------------------ #
-        # Single-stage mode detection                                        #
-        # ------------------------------------------------------------------ #
-        # Single-stage mode is enabled when the caller explicitly passes      #
-        # single_stage_mode=True, or when a stage_id is provided in the args. #
-        _stage_id_kwarg = kwargs.get("stage_id")
-        if isinstance(_stage_id_kwarg, int) and not single_stage_mode:
-            single_stage_mode = True
-
-        self.single_stage_mode: bool = single_stage_mode
-        self._single_stage_id_filter: int | None = (
-            int(_stage_id_kwarg) if single_stage_mode and isinstance(_stage_id_kwarg, int) else None
-        )
-        self._omni_master_address: str | None = kwargs.get("omni_master_address")
-        self._omni_master_port: int | None = kwargs.get("omni_master_port")
-
-        # New omni-coordinator flags. Consumed only in single_stage_mode.
-        # ``omni_dp_size_local`` is process-local: each invocation (head and
-        # every headless) launches that many replicas for its own stage.
-        self._omni_dp_size_local: int = int(kwargs.get("omni_dp_size_local") or 1)
-        if self._omni_dp_size_local < 1:
-            raise ValueError(f"--omni-dp-size-local must be >= 1, got {self._omni_dp_size_local}")
-        self._omni_lb_policy: str = str(kwargs.get("omni_lb_policy") or "random")
-        self._omni_heartbeat_timeout: float = float(kwargs.get("omni_heartbeat_timeout") or 30.0)
-        if self._omni_heartbeat_timeout <= 0:
-            raise ValueError(f"--omni-heartbeat-timeout must be > 0, got {self._omni_heartbeat_timeout}")
-        # Concurrent same-device stage init (admission + SH/EX phase locks).
-        # Sourced from the parallel_stage_init orchestrator/CLI arg (config,
-        # not an env var); default False preserves serial init.
-        self._parallel_stage_init: bool = bool(kwargs.get("parallel_stage_init") or False)
-
-        if single_stage_mode:
-            logger.info(
-                "[AsyncOmniEngine] Single-stage mode enabled (stage_id_filter=%s, master=%s:%s)",
-                self._single_stage_id_filter,
-                self._omni_master_address,
-                self._omni_master_port,
-            )
-
-        # Keep the historical tuple return from _resolve_stage_configs while
-        # retaining the richer resolver result for pipeline-wide settings.
-        # Overrides of that private seam fall back to the factory below.
-        deploy_config_path = kwargs.get("deploy_config")
-        self._config_resolution: OmniConfigResolution | None = None
-        self.config_path, self.stage_configs = self._resolve_stage_configs(
-            model,
-            kwargs,
-            trust_remote_code=trust_remote_code,
-        )
-        if self._config_resolution is None:
-            pipeline_config = StageConfigFactory.get_pipeline_config(
-                model=model,
-                trust_remote_code=bool(trust_remote_code),
-                deploy_config_path=deploy_config_path,
-            )
-            self._set_pipeline_runtime_config(pipeline_config, self.config_path)
-        else:
-            self._set_pipeline_runtime_config(
-                self._config_resolution.pipeline_config,
-                self._config_resolution.config_path,
-            )
-
-        self.num_stages = len(self.stage_configs)
-        stage0_args = getattr(self.stage_configs[0], "engine_args", None) if self.num_stages > 0 else None
-        self.async_chunk = bool(getattr(stage0_args, "async_chunk", False))
-        self.stage_pools: list[StagePool] = []
-        self.stage_clients: list[StageClient] = []  # logical-stage view for external readers
-        self.input_processor: InputProcessor | None = None
-        self.prompt_transform_func: Any | None = None
-        self.prompt_expand_func: Any | None = None
-        self.supported_tasks: tuple[str, ...] = ("generate",)
-        self.default_sampling_params_list: list[OmniSamplingParams] = []
-        self.stage_metadata: list[StageRuntimeInfo] = []
-        # Janus queues are constructed eagerly here (not deferred to the
-        # orchestrator thread) so the master server's ROUTER thread always
-        # sees a non-None ``self.request_queue`` when on_register fires.
-        # ``async_q`` lazily binds to whatever event loop first awaits on
-        # it (the orchestrator loop), so cross-thread use stays correct.
-        self.request_queue: janus.Queue[EngineQueueMessage] = janus.Queue(maxsize=_REQUEST_QUEUE_MAXSIZE)
-        self.output_queue: janus.Queue[EngineQueueMessage] = janus.Queue()
-        self.rpc_output_queue: janus.Queue[EngineQueueMessage] = janus.Queue()
-        self._shutdown_called = False
-        self._weak_finalizer: weakref.finalize | None = None
-        self._correlated_rpc_client: CorrelatedRpcClient | None = None
-        self._duplex_control_client: DuplexControlClient | None = None
-        self._running_counter = OmniRequestCounter()
-        self._engines_waiting_counter = OmniRequestCounter()
-
-        logger.info(f"[AsyncOmniEngine] Launching Orchestrator thread with {self.num_stages} stages")
-
-        # Launch orchestrator background thread
-        startup_future: concurrent.futures.Future = concurrent.futures.Future()
-
-        self.orchestrator_thread = threading.Thread(
-            target=self._bootstrap_orchestrator,
-            args=(
-                stage_init_timeout,
-                startup_future,
-            ),
-            daemon=True,
-            name="orchestrator",
-        )
-        self.orchestrator_thread.start()
-        self._wait_for_orchestrator_init(startup_future, startup_timeout)
-        self._correlated_rpc_client = CorrelatedRpcClient(
-            self.request_queue.sync_q,
-            self.rpc_output_queue.sync_q,
-        )
-
-        # Stage runtime fields are assigned directly on self by the bootstrap thread.
-        self._weak_finalizer = weakref.finalize(
-            self,
-            weak_shutdown_async_omni_engine,
-            self.orchestrator_thread,
-            self.request_queue,
-            self.output_queue,
-            self.rpc_output_queue,
-            self._correlated_rpc_client,
-        )
-
-        logger.info(f"[AsyncOmniEngine] Orchestrator ready with {self.num_stages} stages")
-
-    def get_diffusion_od_config(self) -> Any:
-        """Expose the diffusion ``model_class_name`` to client-side model-extras.
-
-        The worker holds the full config; here we just resolve the pipeline class
-        name from the model config (cached). ``model_class_name`` may be ``None``.
-        """
-        if self._diffusion_od_config_view is None:
-            from types import SimpleNamespace
-
-            from vllm_omni.diffusion.data import resolve_model_class_name
-            from vllm_omni.diffusion.model_metadata import get_diffusion_model_metadata
-
-            model_class_name = resolve_model_class_name(self.model)
-            metadata = get_diffusion_model_metadata(model_class_name)
-            self._diffusion_od_config_view = SimpleNamespace(
-                model_class_name=model_class_name,
-                supports_multimodal_inputs=metadata.supports_multimodal_inputs,
-                max_multimodal_image_inputs=metadata.max_multimodal_image_inputs,
-                supports_mixed_reference_inputs=metadata.supports_mixed_reference_inputs,
-            )
-        return self._diffusion_od_config_view
-
-    def _initialize_stages(self, stage_init_timeout: int) -> None:
-        """Initialize stage clients/processors via StageRuntime and assign to self."""
-        self._runtime = create_stage_runtime(
-            stage_configs=self.stage_configs,
-            model=self.model,
-            config_path=self.config_path,
-            single_stage_mode=self.single_stage_mode,
-            stage_init_timeout=stage_init_timeout,
-            async_chunk=self.async_chunk,
-            tokenizer=self.tokenizer,
-            parallel_stage_init=self._parallel_stage_init,
-            single_stage_id_filter=self._single_stage_id_filter,
-            omni_master_address=self._omni_master_address,
-            omni_master_port=self._omni_master_port,
-            omni_dp_size_local=self._omni_dp_size_local,
-            omni_heartbeat_timeout=self._omni_heartbeat_timeout,
-            omni_lb_policy=self._omni_lb_policy,
-            request_queue=self.request_queue,
-            log_stats=self._log_stats,
-        )
-        self._runtime.initialize()
-
-        self.num_stages = len(self.stage_configs)
-        self.stage_pools = self._runtime.stage_pools
-        self.stage_clients = [
-            cast(StageClient, pool.stage_client) for pool in self.stage_pools if pool.stage_client is not None
-        ]
-        self.stage_vllm_configs = [pool.stage_vllm_config for pool in self.stage_pools]
-        self.output_processors = [pool.output_processor for pool in self.stage_pools]
-        self.input_processor = (
-            build_stage0_input_processor(self.stage_vllm_configs[0])
-            if self.stage_vllm_configs and self.stage_vllm_configs[0] is not None
-            else None
-        )
-        self.prompt_transform_func = (
-            getattr(self.stage_clients[0], "prompt_transform_func", None) if self.stage_clients else None
-        )
-        self.prompt_expand_func = next(
-            (
-                getattr(client, "prompt_expand_func", None)
-                for client in self.stage_clients
-                if getattr(client, "prompt_expand_func", None) is not None
-            ),
-            None,
-        )
-        self.default_sampling_params_list = [client.default_sampling_params for client in self.stage_clients]
-        self.stage_metadata = [
-            StageRuntimeInfo(
-                final_output=client.final_output,
-                final_output_type=client.final_output_type,
-                stage_type=client.stage_type,
-                model_stage=getattr(client, "model_stage", None),
-            )
-            for client in self.stage_clients
-        ]
-        supported_tasks: set[str] = set()
-        if any(getattr(client, "is_comprehension", False) for client in self.stage_clients):
-            supported_tasks.add("generate")
-        if any(meta.final_output_type == "audio" for meta in self.stage_metadata):
-            supported_tasks.add("speech")
-        self.supported_tasks = tuple(supported_tasks) if supported_tasks else ("generate",)
-
-    def _bootstrap_orchestrator(
-        self,
-        stage_init_timeout: int,
-        startup_future: concurrent.futures.Future,
-    ) -> None:
-        """Create loop, initialize stages, then run Orchestrator."""
-
-        loop = asyncio.new_event_loop()
-        asyncio.set_event_loop(loop)
 
-        async def _run_orchestrator() -> None:
-            self._initialize_stages(stage_init_timeout)
-
-            pd_config = self._detect_pd_config()
-
-            membership_controller = self._runtime.create_membership_controller()
-            duplex_runtime_extension = None
-            if self._duplex_control_enabled:
-                duplex_runtime_extension = load_duplex_runtime_extension(
-                    getattr(self, "_duplex_runtime_extension_path", None)
-                )
-                if duplex_runtime_extension is not None:
-                    stage_clients = []
-                    for pool in self.stage_pools:
-                        assert pool.stage_client is not None
-                        stage_clients.append(pool.stage_client)
-                    validate_duplex_runtime_extension(
-                        duplex_runtime_extension,
-                        sampling_defaults=tuple(client.default_sampling_params for client in stage_clients),
-                    )
-
-            orchestrator = Orchestrator(
-                request_async_queue=self.request_queue.async_q,
-                output_async_queue=self.output_queue.async_q,
-                rpc_async_queue=self.rpc_output_queue.async_q,
-                stage_pools=self.stage_pools,
-                async_chunk=self.async_chunk,
-                pd_config=pd_config,
-                membership_controller=membership_controller,
-                running_counter=self._running_counter,
-                engines_waiting_counter=self._engines_waiting_counter,
-                transfer_emitter=self._transfer_emitter,
-                prom_metrics=self._prom_metrics,
-                log_stats=self._log_stats,
-                enable_orch_monitor=self._enable_orch_monitor,
-                duplex_runtime_extension=duplex_runtime_extension,
-                enable_duplex_control=self._duplex_control_enabled,
-                duplex_session_config=self.duplex_session_config,
-            )
-            if not startup_future.done():
-                startup_future.set_result(asyncio.get_running_loop())
-            await orchestrator.run()
+class AsyncOmniEngine(OmniEngineBase):
+    """Turn-based engine used by ``Omni`` / ``AsyncOmni``."""
 
-        try:
-            loop.run_until_complete(_run_orchestrator())
-        except Exception as e:
-            if not startup_future.done():
-                wrapped = RuntimeError(f"Orchestrator initialization failed: {e}")
-                wrapped.__cause__ = e
-                startup_future.set_exception(wrapped)
-            logger.exception("[AsyncOmniEngine] Orchestrator thread crashed")
-            error_text = str(e) or "Orchestrator thread crashed"
-            try:
-                error_msg = ErrorMessage(error=error_text, fatal=True)
-                if self.output_queue is not None:
-                    self.output_queue.sync_q.put_nowait(error_msg)
-                if self.rpc_output_queue is not None:
-                    self.rpc_output_queue.sync_q.put_nowait(error_msg)
-            except Exception:
-                pass
-            raise
-        finally:
-            try:
-                pending = [task for task in asyncio.all_tasks(loop) if not task.done()]
-                for task in pending:
-                    task.cancel()
-                if pending:
-                    loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
-                loop.run_until_complete(loop.shutdown_asyncgens())
-                if hasattr(loop, "shutdown_default_executor"):
-                    loop.run_until_complete(loop.shutdown_default_executor())
-            except Exception:
-                logger.exception("[AsyncOmniEngine] Failed during orchestrator loop cleanup")
-            finally:
-                asyncio.set_event_loop(None)
-                loop.close()
-
-    def _wait_for_orchestrator_init(self, startup_future: concurrent.futures.Future, startup_timeout: int) -> None:
-        """
-        Wait for orchestrator startup future to return ready. Raises exception on any failures to the init process.
-        """
-        deadline = time.monotonic() + startup_timeout
-        while True:
-            remaining = deadline - time.monotonic()
-            if remaining <= 0:
-                logger.warning(
-                    "[AsyncOmniEngine] Orchestrator startup timed out after %ss. "
-                    "Multi-stage deployments that initialize stages sequentially on one device "
-                    "or load checkpoints from slow storage may need larger --init-timeout and "
-                    "--stage-init-timeout values.",
-                    startup_timeout,
-                )
-                self._try_shutdown("[AsyncOmniEngine] Failed to cleanup after orchestrator startup timeout")
-                raise TimeoutError(f"Orchestrator did not become ready within {startup_timeout}s")
-            try:
-                startup_future.result(
-                    timeout=min(remaining, _STARTUP_POLL_INTERVAL_S),
-                )
-                break
-            except concurrent.futures.TimeoutError:
-                if not self.orchestrator_thread.is_alive():
-                    self._try_shutdown("[AsyncOmniEngine] Failed to cleanup after orchestrator startup failure")
-                    if startup_future.done():
-                        startup_future.result()  # re-raises the real exception
-                    raise RuntimeError("Orchestrator thread died during startup")
-            except Exception:
-                self._try_shutdown("[AsyncOmniEngine] Failed to cleanup after orchestrator startup failure")
-                raise
+    def _create_orchestrator(self, **orchestrator_kwargs: Any) -> OrchestratorBase:
+        return Orchestrator(**orchestrator_kwargs)
 
     # ---- request helpers ----
 
@@ -918,158 +465,6 @@ def _enqueue_cfg_companions(
             len(companions),
         )
 
-    def _detect_pd_config(self) -> dict[str, Any] | None:
-        """Detect PD (Prefill-Decode) disaggregation config from stage_configs.
-        Returns a dict with 'pd_pair' and 'bootstrap_addr', or None.
-        """
-        pd_pair = PDDisaggregationMixin.detect_pd_separation_from_stage_configs(self.stage_configs)
-        if pd_pair is None:
-            return None
-        prefill_idx, decode_idx = pd_pair
-
-        # Extract bootstrap address from prefill stage engine_args
-        bootstrap_addr: str | None = None
-        try:
-            prefill_cfg = self.stage_configs[prefill_idx]
-            ea = getattr(prefill_cfg, "engine_args", None)
-            kv_cfg = getattr(ea, "kv_transfer_config", None) if ea is not None else None
-            if kv_cfg is not None:
-                port = vllm_envs.VLLM_MOONCAKE_BOOTSTRAP_PORT
-                kv_ip = getattr(kv_cfg, "kv_ip", None) or "127.0.0.1"
-                bootstrap_addr = f"http://{kv_ip}:{port}"
-        except Exception as exc:
-            logger.warning("[AsyncOmniEngine] Could not extract PD bootstrap address: %s", exc)
-
-        logger.info(
-            "[AsyncOmniEngine] PD disaggregation detected: prefill=stage-%d, decode=stage-%d, bootstrap=%s",
-            prefill_idx,
-            decode_idx,
-            bootstrap_addr,
-        )
-        prefill_engine_id: str | None = None
-        try:
-            prefill_client = self.stage_clients[prefill_idx]
-            kv_cfg = getattr(getattr(prefill_client, "vllm_config", None), "kv_transfer_config", None)
-            prefill_engine_id = getattr(kv_cfg, "engine_id", None)
-        except Exception as exc:
-            logger.warning("[AsyncOmniEngine] Could not extract prefill engine_id: %s", exc)
-
-        return {
-            "pd_pair": (prefill_idx, decode_idx),
-            "bootstrap_addr": bootstrap_addr,
-            "prefill_engine_id": prefill_engine_id,
-        }
-
-    def _apply_strategy_lb_policy(self, derived: str | None, kwargs: dict[str, Any]) -> None:
-        """Apply a strategy-derived ``omni_lb_policy`` to the engine.
-
-        Precedence: an explicit ``--omni-lb-policy`` always wins. ``"random"`` is
-        the engine default and is treated as "unset" (indistinguishable from no
-        flag), so a strategy value overrides it. If the user explicitly passed a
-        non-default policy that conflicts with the strategy-derived one, raise so
-        the mismatch is not silently ignored.
-        """
-        if not derived:
-            return
-        explicit = kwargs.get("omni_lb_policy")
-        user_set = explicit is not None and str(explicit) != "random"
-        if user_set:
-            if str(explicit) != str(derived):
-                raise ValueError(
-                    f"Conflicting load-balancer policy: --omni-lb-policy={explicit!r} was given "
-                    f"but the composable-parallel strategy derived omni_lb_policy={derived!r}. "
-                    "Drop --omni-lb-policy to use the strategy value, or make them match."
-                )
-            return
-        if self._omni_lb_policy != str(derived):
-            logger.info(
-                "[composable_parallel] applying strategy-derived omni_lb_policy=%r (was %r).",
-                derived,
-                self._omni_lb_policy,
-            )
-            self._omni_lb_policy = str(derived)
-
-    @staticmethod
-    def _create_default_diffusion_stage_cfg(kwargs: dict[str, Any]) -> list[dict[str, Any]]:
-        """Compatibility seam for the factory-owned diffusion fallback."""
-        return StageConfigFactory.create_default_diffusion(kwargs)
-
-    def _set_pipeline_runtime_config(
-        self,
-        pipeline_config: PipelineConfig | None,
-        config_path: str | None,
-    ) -> None:
-        """Initialize engine-wide settings resolved from pipeline metadata."""
-        self.endpoint_restrictions = pipeline_config.endpoint_restrictions if pipeline_config is not None else ()
-        self._duplex_runtime_extension_path = (
-            pipeline_config.duplex_runtime_extension if pipeline_config is not None else None
-        )
-        self.duplex_serving_adapter_path = (
-            pipeline_config.duplex_serving_adapter if pipeline_config is not None else None
-        )
-        self._duplex_control_enabled = bool(pipeline_config and pipeline_config.duplex_control_enabled)
-        self.duplex_session_config = DuplexSessionRuntimeConfig()
-        if config_path is not None:
-            self.duplex_session_config = load_deploy_config(config_path).duplex_session
-
-    def _resolve_stage_configs(
-        self,
-        model: str,
-        kwargs: dict[str, Any],
-        *,
-        trust_remote_code: bool | None,
-    ) -> tuple[str, list[Any]]:
-        """Resolve stage configs and inject defaults shared by orchestrator/headless."""
-
-        for legacy_arg in ("stage_configs_path", "stage_configs"):
-            if legacy_arg in kwargs:
-                raise ValueError(f"`{legacy_arg}` is no longer supported; use `deploy_config` instead.")
-
-        # log_stats is captured by __init__; its CLI-only negative alias must
-        # not cross into per-stage structured config ownership validation.
-        kwargs.pop("disable_log_stats", None)
-        deploy_config_path = kwargs.pop("deploy_config", None)
-        strategy_config_path = kwargs.pop("strategy_config", None)
-        # CLI callers arrive pre-parsed; offline Python callers may use the
-        # JSON-string form documented in recipes.
-        stage_overrides = parse_stage_overrides(kwargs.pop("stage_overrides", None))
-
-        # ``diffusion_streaming_output`` is the public AsyncOmni/serve kwarg;
-        # stage configs know the field as ``streaming_output``. Mirror only a
-        # truthy value so the CLI's False default does not override deploy YAML.
-        if kwargs.get("diffusion_streaming_output") and kwargs.get("streaming_output") is None:
-            kwargs["streaming_output"] = True
-
-        resolution = cast(
-            _ConfigResolutionResult,
-            load_and_resolve_stage_configs(
-                model,
-                kwargs,
-                trust_remote_code=trust_remote_code,
-                deploy_config_path=deploy_config_path,
-                stage_overrides=stage_overrides,
-                strategy_config_path=strategy_config_path,
-            ),
-        )
-        if isinstance(resolution, OmniConfigResolution):
-            self._config_resolution = resolution
-            config_path = resolution.config_path
-            stage_configs = list(resolution.stage_configs)
-            strategy_lb_policy = resolution.omni_lb_policy
-        else:
-            # Compatibility for overrides of the historical tuple-returning
-            # seam. Production always receives OmniConfigResolution above.
-            config_path, stage_configs, strategy_lb_policy = resolution
-
-        # A strategy.yaml may derive a pipeline-wide load-balancer policy. It is
-        # an orchestrator-level knob (read once at construction), so apply it here
-        # rather than as a per-stage config field.
-        self._apply_strategy_lb_policy(strategy_lb_policy, kwargs)
-
-        return cast(str, config_path), stage_configs
-
-    # ==================== Public API ====================
-
     def add_request(
         self,
         request_id: str,
@@ -1241,390 +636,6 @@ async def add_streaming_update_async(
             resumable=resumable,
         )
 
-    def open_duplex_session(
-        self,
-        session_id: str,
-        *,
-        session_mode: str = "duplex",
-        capabilities: dict[str, object] | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Open an engine-level duplex session."""
-        return self._get_duplex_control_client().open(
-            session_id,
-            session_mode=session_mode,
-            capabilities=capabilities,
-            session_config=session_config,
-            runtime_config=runtime_config,
-            fence=fence,
-            timeout=timeout,
-        )
-
-    async def open_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        session_mode: str = "duplex",
-        capabilities: dict[str, object] | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Async wrapper for opening an engine-level duplex session."""
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(
-            None,
-            lambda: self.open_duplex_session(
-                session_id,
-                session_mode=session_mode,
-                capabilities=capabilities,
-                session_config=session_config,
-                runtime_config=runtime_config,
-                fence=fence,
-                timeout=timeout,
-            ),
-        )
-
-    def append_duplex_input(
-        self,
-        session_id: str,
-        *,
-        mode: str,
-        payload: object,
-        operation_id: str | None = None,
-        final: bool = False,
-        expected_epoch: int | None = None,
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Append input to an engine-level duplex session."""
-        return self._get_duplex_control_client().append(
-            session_id,
-            mode=mode,
-            payload=payload,
-            operation_id=operation_id,
-            final=final,
-            expected_epoch=expected_epoch,
-            fence=fence,
-            timeout=timeout,
-        )
-
-    async def append_duplex_input_async(
-        self,
-        session_id: str,
-        *,
-        mode: str,
-        payload: object,
-        operation_id: str | None = None,
-        final: bool = False,
-        expected_epoch: int | None = None,
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Async wrapper for appending duplex input."""
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(
-            None,
-            lambda: self.append_duplex_input(
-                session_id,
-                mode=mode,
-                payload=payload,
-                operation_id=operation_id,
-                final=final,
-                expected_epoch=expected_epoch,
-                fence=fence,
-                timeout=timeout,
-            ),
-        )
-
-    def signal_duplex_turn(
-        self,
-        session_id: str,
-        *,
-        event: str,
-        fence: DuplexFence,
-        next_fence: DuplexFence | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Signal an engine-level duplex turn."""
-        return self._get_duplex_control_client().signal(
-            session_id,
-            event=event,
-            fence=fence,
-            next_fence=next_fence,
-            session_config=session_config,
-            runtime_config=runtime_config,
-            timeout=timeout,
-        )
-
-    async def signal_duplex_turn_async(
-        self,
-        session_id: str,
-        *,
-        event: str,
-        fence: DuplexFence,
-        next_fence: DuplexFence | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Async wrapper for signaling a duplex turn."""
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(
-            None,
-            lambda: self.signal_duplex_turn(
-                session_id,
-                event=event,
-                fence=fence,
-                next_fence=next_fence,
-                session_config=session_config,
-                runtime_config=runtime_config,
-                timeout=timeout,
-            ),
-        )
-
-    def close_duplex_session(
-        self,
-        session_id: str,
-        *,
-        reason: str = "client_close",
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Close an engine-level duplex session."""
-        return self._get_duplex_control_client().close(
-            session_id,
-            reason=reason,
-            fence=fence,
-            timeout=timeout,
-        )
-
-    def touch_duplex_session(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        activity: DuplexLeaseActivity,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        return self._get_duplex_control_client().touch(
-            session_id,
-            fence=fence,
-            activity=activity,
-            timeout=timeout,
-        )
-
-    async def touch_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        activity: DuplexLeaseActivity,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(
-            None,
-            lambda: self.touch_duplex_session(
-                session_id,
-                fence=fence,
-                activity=activity,
-                timeout=timeout,
-            ),
-        )
-
-    def resume_duplex_session(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        expected_lease_generation: int,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        return self._get_duplex_control_client().resume(
-            session_id,
-            fence=fence,
-            expected_lease_generation=expected_lease_generation,
-            timeout=timeout,
-        )
-
-    async def resume_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        expected_lease_generation: int,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(
-            None,
-            lambda: self.resume_duplex_session(
-                session_id,
-                fence=fence,
-                expected_lease_generation=expected_lease_generation,
-                timeout=timeout,
-            ),
-        )
-
-    def _get_duplex_control_client(self) -> DuplexControlClient:
-        client = getattr(self, "_duplex_control_client", None)
-        if client is None:
-            transport = getattr(self, "_correlated_rpc_client", None)
-            if transport is None:
-                raise RuntimeError("correlated RPC client is not initialized")
-            client = DuplexControlClient(
-                transport,
-                control_id_factory=lambda: uuid.uuid4().hex,
-            )
-            self._duplex_control_client = client
-        return client
-
-    async def close_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        reason: str = "client_close",
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Async wrapper for closing an engine-level duplex session."""
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(
-            None,
-            lambda: self.close_duplex_session(session_id, reason=reason, fence=fence, timeout=timeout),
-        )
-
-    def try_get_output(self, timeout: float = 0.001) -> EngineQueueMessage | None:
-        """Read one output message from the Orchestrator output queue."""
-        try:
-            return self.output_queue.sync_q.get(timeout=timeout)
-        except queue.Empty:
-            if not self.is_alive():
-                raise RuntimeError("Orchestrator died unexpectedly. See logs above.")
-            return None
-
-    async def try_get_output_async(self) -> EngineQueueMessage | None:
-        """Async read from the Orchestrator output queue."""
-        try:
-            return self.output_queue.sync_q.get_nowait()
-        except queue.Empty:
-            if not self.is_alive():
-                raise RuntimeError("Orchestrator died unexpectedly. See logs above.")
-            return None
-
-    async def get_output_blocking_async(self, timeout: float = 1.0) -> EngineQueueMessage | None:
-        """Blocking-wait read from the Orchestrator output queue.
-
-        Waits up to ``timeout`` seconds in a dedicated drain thread for the
-        next message (condition-variable wakeup instead of a poll cadence);
-        returns ``None`` on timeout so the caller keeps its liveness check,
-        mirroring ``try_get_output_async``'s contract. Used by the serving
-        final-output drain when ``VLLM_OMNI_EVENT_DRIVEN_ORCH`` is on.
-        """
-        executor = self._output_drain_executor
-        if executor is None:
-            executor = concurrent.futures.ThreadPoolExecutor(
-                max_workers=1,
-                thread_name_prefix="omni-output-drain",
-            )
-            self._output_drain_executor = executor
-
-        sync_q = self.output_queue.sync_q
-
-        def _drain_get() -> EngineQueueMessage | None:
-            # Exceptions are swallowed to a None sentinel: the queue may be
-            # closed mid-shutdown, and an exception left on an executor future
-            # after task cancellation would warn as never-retrieved.
-            try:
-                return sync_q.get(timeout=timeout)
-            except queue.Empty:
-                return None
-            except Exception:
-                return None
-
-        loop = asyncio.get_running_loop()
-        msg = await loop.run_in_executor(executor, _drain_get)
-        if msg is None and not self.is_alive():
-            raise RuntimeError("Orchestrator died unexpectedly. See logs above.")
-        return msg
-
-    def get_stage_metadata(self, stage_id: int) -> StageRuntimeInfo:
-        """Get cached metadata for a stage."""
-        return self.stage_metadata[stage_id]
-
-    def abort(self, request_ids: list[str]) -> None:
-        """Fire-and-forget abort: enqueue and return without waiting.
-
-        Prefer :meth:`abort_async` when the caller needs acknowledgment that
-        stage aborts, binding release, and orchestrator request cleanup finished.
-        """
-        if not request_ids or getattr(self, "_shutdown_called", False):
-            return
-        if self.request_queue is None:
-            raise RuntimeError("request_queue is not initialized")
-        try:
-            self.request_queue.sync_q.put(AbortRequestMessage(request_ids=request_ids))
-        except Exception as exc:
-            if getattr(self, "_shutdown_called", False) and is_janus_sync_queue_shutdown(exc):
-                return
-            raise
-
-    async def abort_async(
-        self,
-        request_ids: list[str],
-        timeout: float | None = None,
-    ) -> list[OutputMessage]:
-        """Abort requests and wait for orchestrator acknowledgment.
-
-        Unlike :meth:`abort`, this generates an ``rpc_id``, correlates the
-        :class:`AbortResultMessage` via :class:`CorrelatedRpcClient`, and
-        raises if the orchestrator reports failure or times out.
-
-        Returns:
-            Final-stage AR abort ``OutputMessage`` list carrying partial
-            tokens generated before abort (empty for diffusion / no OP state).
-        """
-        if not request_ids or getattr(self, "_shutdown_called", False):
-            return []
-        if self.request_queue is None:
-            raise RuntimeError("request_queue is not initialized")
-        transport = self._correlated_rpc_client
-        if transport is None:
-            raise RuntimeError("correlated RPC client is not initialized")
-
-        rpc_id = uuid.uuid4().hex
-        msg = AbortRequestMessage(request_ids=request_ids, rpc_id=rpc_id)
-
-        def _wait() -> AbortResultMessage:
-            result_msg = transport.execute(
-                ("abort", rpc_id),
-                msg,
-                timeout=timeout,
-                timeout_message=f"abort timed out after {timeout} seconds",
-                block_on_submit=True,
-            )
-            if not isinstance(result_msg, AbortResultMessage):
-                raise RuntimeError(f"unexpected abort result type: {type(result_msg).__name__}")
-            return result_msg
-
-        loop = asyncio.get_running_loop()
-        try:
-            result_msg = await loop.run_in_executor(None, _wait)
-        except Exception as exc:
-            if getattr(self, "_shutdown_called", False) and is_abort_transport_shutdown(exc):
-                return []
-            raise
-        if not result_msg.success:
-            raise RuntimeError(result_msg.error or "abort failed")
-        return list(result_msg.abort_outputs or [])
-
     def submit_interaction(
         self,
         request_id: str,
@@ -1649,166 +660,6 @@ async def submit_interaction_async(
         """Async interaction API."""
         self.submit_interaction(request_id, interaction)
 
-    def collective_rpc(
-        self,
-        method: str,
-        timeout: float | None = None,
-        args: tuple[Any, ...] = (),
-        kwargs: dict[str, Any] | None = None,
-        stage_ids: list[int] | None = None,
-    ) -> list[Any]:
-        """Send a control RPC to the Orchestrator and wait for aggregated results.
-
-        This uses a dedicated RPC output queue so control-plane messages do not
-        race with the normal request output polling loop.
-        """
-        rpc_id = uuid.uuid4().hex
-        msg = CollectiveRPCRequestMessage(
-            rpc_id=rpc_id,
-            method=method,
-            timeout=timeout,
-            args=tuple(args),
-            kwargs=kwargs or {},
-            stage_ids=stage_ids,
-        )
 
-        transport = self._correlated_rpc_client
-        if transport is None:
-            raise RuntimeError("correlated RPC client is not initialized")
-        result_msg = transport.execute(
-            ("collective", rpc_id),
-            msg,
-            timeout=timeout,
-            timeout_message=f"collective_rpc timed out after {timeout} seconds",
-            block_on_submit=True,
-        )
-        if not isinstance(result_msg, CollectiveRPCResultMessage):
-            raise RuntimeError(f"unexpected collective RPC result type: {type(result_msg).__name__}")
-        return list(result_msg.results)
-
-    async def collective_rpc_async(
-        self,
-        method: str,
-        timeout: float | None = None,
-        args: tuple[Any, ...] = (),
-        kwargs: dict[str, Any] | None = None,
-        stage_ids: list[int] | None = None,
-    ) -> list[Any]:
-        """Async wrapper around collective_rpc()."""
-        loop = asyncio.get_running_loop()
-        return await loop.run_in_executor(
-            None,
-            lambda: self.collective_rpc(
-                method=method,
-                timeout=timeout,
-                args=args,
-                kwargs=kwargs,
-                stage_ids=stage_ids,
-            ),
-        )
-
-    def is_alive(self) -> bool:
-        """Whether the orchestrator thread is alive."""
-        return bool(self.orchestrator_thread.is_alive())
-
-    def shutdown(self) -> None:
-        """Send shutdown message and wait for the Orchestrator thread to exit."""
-        if getattr(self, "_shutdown_called", False):
-            return
-        self._shutdown_called = True
-        finalizer = getattr(self, "_weak_finalizer", None)
-        if finalizer is not None and finalizer.alive:
-            finalizer.detach()
-
-        logger.info("[AsyncOmniEngine] Shutting down Orchestrator")
-        request_queue_closed = False
-        shutdown_enqueued = enqueue_orchestrator_shutdown(
-            self.request_queue,
-            timeout=SHUTDOWN_ENQUEUE_TIMEOUT_S,
-        )
-        if self.request_queue is not None and not shutdown_enqueued:
-            logger.error(
-                "[AsyncOmniEngine] Failed to enqueue orchestrator shutdown; "
-                "closing the request queue to wake the request handler"
-            )
-            try:
-                self.request_queue.close()
-                request_queue_closed = True
-            except Exception:
-                logger.exception("[AsyncOmniEngine] Failed to close the request queue")
-
-        if self._correlated_rpc_client is not None:
-            try:
-                self._correlated_rpc_client.close()
-            except Exception:
-                logger.exception("[AsyncOmniEngine] Failed to close correlated RPC client")
-
-        orchestrator_stopped = False
-        try:
-            if self.is_alive():
-                self.orchestrator_thread.join(timeout=SHUTDOWN_JOIN_TIMEOUT_S)
-            orchestrator_stopped = not self.is_alive()
-            if not orchestrator_stopped:
-                logger.error(
-                    "[AsyncOmniEngine] Orchestrator did not stop within %.1f seconds; continuing cleanup",
-                    SHUTDOWN_JOIN_TIMEOUT_S,
-                )
-        except Exception:
-            logger.exception("[AsyncOmniEngine] Failed to join Orchestrator thread")
-
-        for q in (self.request_queue, self.output_queue, self.rpc_output_queue):
-            try:
-                if not (q is self.request_queue and request_queue_closed):
-                    q.close()
-            except Exception:
-                pass
-
-        if self._output_drain_executor is not None:
-            # Any in-flight blocking get bails out within its ≤1 s timeout
-            # (or immediately via the queue close above), so don't wait.
-            self._output_drain_executor.shutdown(wait=False)
-            self._output_drain_executor = None
-
-        if hasattr(self, "_runtime") and self._runtime is not None and orchestrator_stopped:
-            try:
-                self._runtime.shutdown()
-            except Exception:
-                logger.exception("[AsyncOmniEngine] Failed to shutdown StageRuntime")
-        elif hasattr(self, "_runtime") and self._runtime is not None:
-            logger.warning("[AsyncOmniEngine] Deferring StageRuntime shutdown until the Orchestrator exits")
-            threading.Thread(
-                target=shutdown_runtime_after_orchestrator,
-                args=(self.orchestrator_thread, self._runtime),
-                daemon=True,
-                name="omni-stage-runtime-shutdown",
-            ).start()
-
-        # ── Release CuMem allocator memory pool ──────────────────────────────
-        # When enable_sleep_mode is in use, the CuMem (CUDA Virtual Memory
-        # Management) allocator holds model weights in a singleton memory pool
-        # that lives in the parent process.  Killing the engine-core subprocess
-        # does NOT release this pool — the weights stay resident on the GPU
-        # and can cause CUDA OOM for subsequent engine instances (especially
-        # large models like BAGEL-7B-MoT whose weights alone consume ~134 GiB).
-        #
-        # CuMemAllocator.sleep() is NOT idempotent — calling it on already-
-        # slept entries causes CUDA_ERROR_INVALID_VALUE at cumem_allocator
-        # cuMemRelease (double-free of the memory handle).  Use release_pools()
-        # instead, which is the designed cleanup path: it drops MemPool refs
-        # and lets the destructor/free path handle asleep entries correctly
-        # (returns a null handle so the C extension skips unmap/release).
-        try:
-            from vllm.device_allocator.cumem import CuMemAllocator, cumem_available
-
-            if cumem_available:
-                allocator = CuMemAllocator.get_instance()
-                allocator.release_pools()
-                logger.debug("[AsyncOmniEngine] Released CuMem memory pool during shutdown")
-        except Exception:
-            pass
-
-    def _try_shutdown(self, *args, **kwargs) -> None:
-        try:
-            self.shutdown()
-        except Exception:
-            logger.exception(*args, **kwargs)
+# ``StageRuntimeInfo`` moved to ``omni_engine_base``; keep the historical import path.
+__all__ = ["AsyncOmniEngine", "StageRuntimeInfo"]
diff --git a/vllm_omni/engine/duplex/__init__.py b/vllm_omni/engine/duplex/__init__.py
index bd5ae0b3ff9..533e31e23c5 100644
--- a/vllm_omni/engine/duplex/__init__.py
+++ b/vllm_omni/engine/duplex/__init__.py
@@ -1,4 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-"""Engine-side helpers for the full-duplex runtime."""
+"""Engine-resident full-duplex sessions: typed commands/events, the merged session
+state, the per-session runner, the session manager and the model plugin contract."""
diff --git a/vllm_omni/entrypoints/duplex/audio.py b/vllm_omni/engine/duplex/audio.py
similarity index 96%
rename from vllm_omni/entrypoints/duplex/audio.py
rename to vllm_omni/engine/duplex/audio.py
index 747293a1a05..5f163826a6a 100644
--- a/vllm_omni/entrypoints/duplex/audio.py
+++ b/vllm_omni/engine/duplex/audio.py
@@ -11,6 +11,8 @@
 
 import numpy as np
 
+from vllm_omni.utils.audio_resample import StreamingAudioResampler
+
 try:
     from audioop import alaw2lin, lin2alaw, lin2ulaw, ulaw2lin
 except ImportError:  # pragma: no cover - audioop is removed in newer Python.
@@ -39,14 +41,10 @@ def validate_input_sample_rate_hz(sample_rate_hz: object) -> int:
 def resample_pcm16_mono(raw: bytes, *, source_rate_hz: int, target_rate_hz: int) -> bytes:
     if source_rate_hz <= 0 or target_rate_hz <= 0 or source_rate_hz == target_rate_hz:
         return raw
-    # Import lazily so the generic Duplex audio module does not pull in the
-    # OpenAI API server while the Duplex stack itself is being imported.
-    from vllm_omni.entrypoints.openai.audio_utils_mixin import StreamingAudioResampler
-
     samples = np.frombuffer(raw, dtype="<i2")
     rate_gcd = math.gcd(source_rate_hz, target_rate_hz)
     reduced_factor = max(source_rate_hz // rate_gcd, target_rate_hz // rate_gcd)
-    if reduced_factor > StreamingAudioResampler._max_polyphase_factor:
+    if reduced_factor > StreamingAudioResampler.max_polyphase_factor:
         # The FIR size scales with the reduced ratio. Keep unusual client
         # rates bounded while common audio rates use the high-quality path.
         if samples.size <= 1:
diff --git a/vllm_omni/engine/duplex/commands.py b/vllm_omni/engine/duplex/commands.py
new file mode 100644
index 00000000000..90d48d05055
--- /dev/null
+++ b/vllm_omni/engine/duplex/commands.py
@@ -0,0 +1,324 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Typed commands accepted by a duplex session.
+
+``DuplexSessionHandle.submit()`` takes one of these; the websocket handler and
+``InlineDuplexClient`` build them with :func:`command_from_realtime` from the
+OpenAI Realtime client event vocabulary. Every command can also render the
+session-internal mailbox payload (``payload()``), which is the dictionary
+vocabulary the session runner bodies were written against.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Mapping
+from dataclasses import dataclass, field, fields
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from vllm_omni.engine.duplex.realtime_commands import RealtimeInputDefaults
+
+
+class DuplexCommandError(ValueError):
+    """A client payload could not be turned into a command."""
+
+    def __init__(self, message: str, *, code: str = "bad_event", event_id: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.event_id = event_id
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DuplexCommand:
+    #: Mailbox event type this command renders to (see ``payload()``).
+    type: ClassVar[str] = ""
+    #: Client correlation id (OpenAI ``event_id``), echoed on error events.
+    event_id: str | None = None
+
+    def payload(self) -> dict[str, object]:
+        """Render the session-internal mailbox dictionary."""
+        data: dict[str, object] = {"type": self.type}
+        for f in fields(self):
+            if f.name == "event_id":
+                if self.event_id is not None:
+                    data["realtime_event_id"] = self.event_id
+                continue
+            value = getattr(self, f.name)
+            if value is None:
+                continue
+            if isinstance(value, tuple):
+                value = list(value)
+            elif isinstance(value, Mapping):
+                value = dict(value)
+            data[f.name] = value
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppendAudio(DuplexCommand):
+    type: ClassVar[str] = "input_audio_buffer.append"
+    #: Raw audio bytes in ``format`` at ``sample_rate_hz`` (base64 only on the wire).
+    audio: bytes
+    format: str = "pcm16"
+    sample_rate_hz: int | None = None
+    is_speech: bool | None = None
+    video_frames: tuple[str, ...] = ()
+    duration_ms: int | None = None
+    audio_end_ms: int | None = None
+    #: Model-neutral hints carried through from the wire (rms, vad, transcript hints ...).
+    hints: Mapping[str, object] = field(default_factory=dict)
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        hints = data.pop("hints", None)
+        if isinstance(hints, Mapping):
+            # Hints are raw wire values; the typed fields went through
+            # ``build_append_audio``'s normalization, so they have to win. An
+            # unset typed field is simply absent here (``payload`` skips None),
+            # which is what lets a hint still carry it. Merging the other way
+            # round let a client's ``"is_speech": 0`` override the computed
+            # ``bool | None`` and silently miss the runner's silent-commit path.
+            merged: dict[str, object] = dict(hints)
+            merged.update(data)
+            data = merged
+        data["audio"] = base64.b64encode(self.audio).decode("ascii")
+        if not data.get("video_frames"):
+            data.pop("video_frames", None)
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppendText(DuplexCommand):
+    type: ClassVar[str] = "input.text.append"
+    text: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Commit(DuplexCommand):
+    type: ClassVar[str] = "input_audio_buffer.commit"
+    final: bool = True
+    #: ``None`` means "no explicit request": the runner decides on commit (auto-response
+    #: sessions answer on their own); ``True`` / ``False`` force it.
+    create_response: bool | None = None
+    is_speech: bool | None = None
+    #: Realtime conversation item created for this commit (wire correlation only).
+    realtime_item_id: str | None = None
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        if self.create_response is not None:
+            data["response_create"] = data.pop("create_response")
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CreateResponse(DuplexCommand):
+    type: ClassVar[str] = "response.create"
+    #: Raw Realtime ``response`` object (instructions, voice, modalities, ...).
+    options: Mapping[str, object] = field(default_factory=dict)
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        options = data.pop("options", None)
+        if isinstance(options, Mapping):
+            data["response"] = dict(options)
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClearInput(DuplexCommand):
+    type: ClassVar[str] = "input_audio_buffer.clear"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CancelInput(DuplexCommand):
+    type: ClassVar[str] = "input.cancel"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CancelResponse(DuplexCommand):
+    type: ClassVar[str] = "response.cancel"
+    response_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BargeIn(DuplexCommand):
+    type: ClassVar[str] = "barge_in"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClearOutputAudio(DuplexCommand):
+    type: ClassVar[str] = "output_audio_buffer.clear"
+    #: Explicit response to clear; ``None`` targets the active/last response.
+    response_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SignalTurn(DuplexCommand):
+    """Generic ``turn.signal`` (local turn transitions such as ``user_started``)."""
+
+    type: ClassVar[str] = "turn.signal"
+    event: str
+    signal_payload: Mapping[str, object] = field(default_factory=dict)
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        signal_payload = data.pop("signal_payload", None)
+        if isinstance(signal_payload, Mapping) and signal_payload:
+            data["payload"] = dict(signal_payload)
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UpdateSession(DuplexCommand):
+    """``session.update``: a Realtime ``session`` object patch."""
+
+    type: ClassVar[str] = "turn.signal"
+    patch: Mapping[str, object] = field(default_factory=dict)
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        data["event"] = "session.update"
+        data["payload"] = dict(data.pop("patch", {}) or {})
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AckPlayback(DuplexCommand):
+    type: ClassVar[str] = "playback.ack"
+    played_ms: int
+    committed_ms: int | None = None
+    response_id: str | None = None
+    item_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Heartbeat(DuplexCommand):
+    type: ClassVar[str] = "session.heartbeat"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CreateItem(DuplexCommand):
+    """``conversation.item.create`` (history injection or function-call output)."""
+
+    type: ClassVar[str] = "turn.signal"
+    item: Mapping[str, object]
+    previous_item_id: str | None = None
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        data["event"] = "conversation.item.create"
+        payload: dict[str, object] = {"item": dict(data.pop("item"))}
+        previous = data.pop("previous_item_id", None)
+        if previous is not None:
+            payload["previous_item_id"] = previous
+        data["payload"] = payload
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DeleteItem(DuplexCommand):
+    type: ClassVar[str] = "turn.signal"
+    item_id: str
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        data["event"] = "conversation.item.delete"
+        data["payload"] = {"item_id": data.pop("item_id")}
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TruncateItem(DuplexCommand):
+    type: ClassVar[str] = "turn.signal"
+    item_id: str
+    audio_end_ms: int
+    content_index: int = 0
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        data["event"] = "conversation.item.truncate"
+        data["payload"] = {
+            "item_id": data.pop("item_id"),
+            "audio_end_ms": data.pop("audio_end_ms"),
+            "content_index": data.pop("content_index", 0),
+        }
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CloseSession(DuplexCommand):
+    """Graceful close requested through the command stream (``session.close``)."""
+
+    type: ClassVar[str] = "session.close"
+    reason: str = "client_close"
+
+
+#: Realtime client event types that map onto commands (wire vocabulary).
+REALTIME_COMMAND_TYPES: frozenset[str] = frozenset(
+    {
+        "input_audio_buffer.append",
+        "input_audio_buffer.commit",
+        "input_audio_buffer.clear",
+        "output_audio_buffer.clear",
+        "response.create",
+        "response.cancel",
+        "conversation.item.create",
+        "conversation.item.delete",
+        "conversation.item.truncate",
+        "session.update",
+        "playback.ack",
+        "session.heartbeat",
+        "session.close",
+        "turn.signal",
+        "input.text.append",
+        "input.cancel",
+        "barge_in",
+    }
+)
+
+
+def command_from_realtime(
+    payload: Mapping[str, object],
+    *,
+    defaults: RealtimeInputDefaults | None = None,
+) -> DuplexCommand:
+    """Translate one OpenAI Realtime client event into a command.
+
+    Envelope concerns (``event_id`` acknowledgements, resume bookkeeping) are
+    handled by the transport; this function only validates and maps the
+    payload shape. ``defaults`` carries the audio format / sample rate / VAD
+    defaults the session declared, so every transport decodes an append the
+    same way. Raises :class:`DuplexCommandError` for malformed or unsupported
+    payloads.
+    """
+    from vllm_omni.engine.duplex.realtime_commands import translate_realtime_command
+
+    return translate_realtime_command(payload, defaults=defaults)
+
+
+__all__ = [
+    "REALTIME_COMMAND_TYPES",
+    "AckPlayback",
+    "AppendAudio",
+    "AppendText",
+    "BargeIn",
+    "CancelInput",
+    "CancelResponse",
+    "ClearInput",
+    "ClearOutputAudio",
+    "CloseSession",
+    "Commit",
+    "CreateItem",
+    "CreateResponse",
+    "DeleteItem",
+    "DuplexCommand",
+    "DuplexCommandError",
+    "Heartbeat",
+    "SignalTurn",
+    "TruncateItem",
+    "UpdateSession",
+    "command_from_realtime",
+]
diff --git a/vllm_omni/engine/duplex/config.py b/vllm_omni/engine/duplex/config.py
new file mode 100644
index 00000000000..aab0fb1c5b6
--- /dev/null
+++ b/vllm_omni/engine/duplex/config.py
@@ -0,0 +1,815 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Session configuration, capabilities and value types of the duplex session model.
+
+These classes are the typed half of the public contract: ``DuplexOmni``
+accepts a ``DuplexSessionConfig`` (or the equivalent OpenAI Realtime
+``session`` object via :meth:`DuplexSessionConfig.from_realtime`) and reports
+``DuplexCapabilities``. They used to live in ``entrypoints/duplex/protocol.py``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, cast
+
+
+class DuplexConfigError(ValueError):
+    """A Realtime session/response object was rejected while mapping it onto the duplex config."""
+
+    def __init__(self, message: str, *, code: str = "bad_event", param: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.param = param
+
+
+class DuplexOverlapPolicy(str, Enum):
+    LISTEN_ONLY = "listen_only"
+    BARGE_IN_ON_SPEECH = "barge_in_on_speech"
+
+
+class DuplexPlaybackCommitPolicy(str, Enum):
+    COMMIT_ALL_ON_DONE = "commit_all_on_done"
+    ACK_ONLY = "ack_only"
+
+
+class DuplexSessionState(str, Enum):
+    OPEN = "open"
+    CLOSING = "closing"
+    CLOSED = "closed"
+
+
+class DuplexTurnState(str, Enum):
+    IDLE = "idle"
+    USER_SPEAKING = "user_speaking"
+    USER_COMMITTED = "user_committed"
+    ASSISTANT_GENERATING = "assistant_generating"
+    ASSISTANT_PLAYING = "assistant_playing"
+    BARGE_IN = "barge_in"
+
+
+class DuplexTurnEventType(str, Enum):
+    USER_STARTED = "user_started"
+    USER_COMMITTED = "user_committed"
+    ASSISTANT_STARTED = "assistant_started"
+    ASSISTANT_DONE = "assistant_done"
+    BARGE_IN = "barge_in"
+    PLAYBACK_ACK = "playback_ack"
+    TIMEOUT = "timeout"
+    CLOSE = "close"
+
+
+@dataclass
+class DuplexCapabilities:
+    """Runtime/model capabilities exposed by the duplex serving protocol.
+
+    These are intentionally explicit so the serving layer does not assume all
+    duplex models support the same input append, rollback, or turn policy.
+    ``supports_core_kv_lease`` is reserved for scheduler-owned KV lifecycle;
+    model-owned decoder/TTS state must use ``supports_model_internal_state``.
+    ``supports_core_resumable_request`` means the scheduler can resume the
+    same request id across streaming updates, but it is not a KV lease by
+    itself. Realtime support means this endpoint can speak the native Realtime
+    event schema for the supported audio duplex paths while keeping model- or
+    scheduler-specific limits explicit in the capability payload.
+    """
+
+    supports_session_adapter: bool = True
+    supports_model_native_turn_policy: bool = False
+    supports_external_turn_signal: bool = True
+    supports_client_commit: bool = True
+    supports_barge_in: bool = True
+    supports_playback_ack: bool = True
+    supports_input_append: bool = False
+    supports_replace_latest_chunk: bool = True
+    supports_reencode_context: bool = True
+    supports_rollback_to_checkpoint: bool = False
+    supports_turn_commit_only: bool = True
+    supports_kv_lease: bool = False
+    supports_core_kv_lease: bool = False
+    supports_model_internal_state: bool = False
+    supports_stage_resumption: bool = False
+    supports_scheduler_native_append: bool = False
+    supports_core_resumable_request: bool = False
+    supports_stage_connector_handoff: bool = False
+    supports_independent_io_streams: bool = False
+    supports_realtime_endpoint: bool = False
+    supports_multi_session: bool = False
+    supports_multi_session_same_replica: bool = False
+    supports_session_lease: bool = False
+    supports_session_resume: bool = False
+    session_admission_mode: str = "serving_managed"
+    supports_audio_truncate: bool = False
+    #: Whether this model can serve ``/v1/chat/completions`` on a duplex
+    #: session. That needs one thing the protocol cannot assume: the model
+    #: honours ``DuplexSessionConfig.initial_user_text``, so a turn can be
+    #: seeded from text. A model-native model decides to speak from the audio
+    #: it hears, and silence is its signal *not* to take a turn, so without
+    #: seeding a text prompt has no representation and the turn never
+    #: completes. ``text_turn_priming_units`` is how many silence units such a
+    #: seeded turn must be given to generate on -- it still speaks per unit.
+    supports_chat_completions: bool = False
+    text_turn_priming_units: int = 0
+    requires_model_runner_kv: bool = False
+    requires_native_stage_role: bool = False
+    adapter_patterns: list[str] = field(default_factory=lambda: ["chunk_group_append"])
+    signal_sources: list[str] = field(default_factory=lambda: ["client_event", "server_policy", "model_native"])
+    stage_handoff_transport: str | None = None
+    chunk_period_ms: int | None = 1000
+    target_barge_in_latency_ms: int | None = 1000
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "supports_session_adapter": self.supports_session_adapter,
+            "supports_model_native_turn_policy": self.supports_model_native_turn_policy,
+            "supports_external_turn_signal": self.supports_external_turn_signal,
+            "supports_client_commit": self.supports_client_commit,
+            "supports_barge_in": self.supports_barge_in,
+            "supports_playback_ack": self.supports_playback_ack,
+            "supports_input_append": self.supports_input_append,
+            "supports_replace_latest_chunk": self.supports_replace_latest_chunk,
+            "supports_reencode_context": self.supports_reencode_context,
+            "supports_rollback_to_checkpoint": self.supports_rollback_to_checkpoint,
+            "supports_turn_commit_only": self.supports_turn_commit_only,
+            "supports_kv_lease": self.supports_kv_lease,
+            "supports_core_kv_lease": self.supports_core_kv_lease,
+            "supports_model_internal_state": self.supports_model_internal_state,
+            "supports_stage_resumption": self.supports_stage_resumption,
+            "supports_scheduler_native_append": self.supports_scheduler_native_append,
+            "supports_core_resumable_request": self.supports_core_resumable_request,
+            "supports_stage_connector_handoff": self.supports_stage_connector_handoff,
+            "supports_independent_io_streams": self.supports_independent_io_streams,
+            "supports_realtime_endpoint": self.supports_realtime_endpoint,
+            "supports_multi_session": self.supports_multi_session,
+            "supports_multi_session_same_replica": self.supports_multi_session_same_replica,
+            "supports_session_lease": self.supports_session_lease,
+            "supports_session_resume": self.supports_session_resume,
+            "session_admission_mode": self.session_admission_mode,
+            "supports_audio_truncate": self.supports_audio_truncate,
+            "requires_model_runner_kv": self.requires_model_runner_kv,
+            "requires_native_stage_role": self.requires_native_stage_role,
+            # Every duplex model is model-native and appends audio chunks (§7 D4);
+            # kept on the wire as constants for clients that still read them.
+            "implementation_level": "model_native_duplex",
+            "adapter_patterns": self.adapter_patterns,
+            "input_modes": ["append_audio_chunk"],
+            "signal_sources": self.signal_sources,
+            "stage_handoff_transport": self.stage_handoff_transport,
+            "chunk_period_ms": self.chunk_period_ms,
+            "target_barge_in_latency_ms": self.target_barge_in_latency_ms,
+        }
+
+
+@dataclass
+class DuplexPlaybackCursor:
+    generated_ms: int = 0
+    sent_ms: int = 0
+    played_ms: int = 0
+    committed_ms: int = 0
+
+    def acknowledge(self, played_ms: int, committed_ms: int | None = None) -> None:
+        self.played_ms = max(self.played_ms, max(0, int(played_ms)))
+        if committed_ms is None:
+            committed_ms = self.played_ms
+        self.committed_ms = max(self.committed_ms, max(0, int(committed_ms)))
+
+    def truncate_committed(self, committed_ms: int) -> None:
+        self.committed_ms = max(0, min(max(self.sent_ms, self.generated_ms), int(committed_ms)))
+
+    def as_dict(self) -> dict[str, int]:
+        return {
+            "generated_ms": self.generated_ms,
+            "sent_ms": self.sent_ms,
+            "played_ms": self.played_ms,
+            "committed_ms": self.committed_ms,
+        }
+
+    def snapshot(self) -> DuplexPlaybackView:
+        return DuplexPlaybackView(**self.as_dict())
+
+
+@dataclass(frozen=True, slots=True)
+class DuplexPlaybackView:
+    generated_ms: int = 0
+    sent_ms: int = 0
+    played_ms: int = 0
+    committed_ms: int = 0
+
+    def as_dict(self) -> dict[str, int]:
+        return {
+            "generated_ms": self.generated_ms,
+            "sent_ms": self.sent_ms,
+            "played_ms": self.played_ms,
+            "committed_ms": self.committed_ms,
+        }
+
+
+@dataclass
+class DuplexAudioChunk:
+    data: str
+    format: str = "wav"
+    sample_rate_hz: int | None = None
+
+
+@dataclass
+class DuplexSessionConfig:
+    model: str | None = None
+    modalities: list[str] = field(default_factory=lambda: ["text", "audio"])
+    instructions: str | None = None
+    #: Text the session treats as the user's opening turn. A caller that cannot
+    #: reach the model by speech (an HTTP request, a batch job) puts its prompt
+    #: here; ``supports_text_only_turn`` says whether the model can answer it.
+    initial_user_text: str | None = None
+    voice: str | None = None
+    ref_audio: str | None = None
+    response_format: str = "wav"
+    temperature: float | None = None
+    max_tokens: int | None = None
+    speed: float | None = None
+    use_tts_template: bool = True
+    idle_timeout_s: float = 300.0
+    overlap_policy: str = DuplexOverlapPolicy.LISTEN_ONLY.value
+    overlap_short_ack_ms: int = 700
+    overlap_barge_in_ms: int = 1200
+    overlap_silence_rms: float = 0.003
+    playback_commit_policy: str = DuplexPlaybackCommitPolicy.COMMIT_ALL_ON_DONE.value
+    extra_body: dict[str, object] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "model": self.model,
+            "modalities": list(self.modalities),
+            "instructions": self.instructions,
+            "initial_user_text": self.initial_user_text,
+            "voice": self.voice,
+            "ref_audio": self.ref_audio,
+            "response_format": self.response_format,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            "speed": self.speed,
+            "use_tts_template": self.use_tts_template,
+            "idle_timeout_s": self.idle_timeout_s,
+            "overlap_policy": self.overlap_policy,
+            "overlap_short_ack_ms": self.overlap_short_ack_ms,
+            "overlap_barge_in_ms": self.overlap_barge_in_ms,
+            "overlap_silence_rms": self.overlap_silence_rms,
+            "playback_commit_policy": self.playback_commit_policy,
+            "extra_body": dict(self.extra_body),
+        }
+
+    def normalized(self) -> DuplexSessionConfig:
+        """Apply the clamps / defaults ``from_event`` applies to a wire object (typed configs skip them)."""
+        return DuplexSessionConfig.from_event({"session": self.as_dict()})
+
+    @classmethod
+    def from_event(cls, event: dict[str, object]) -> DuplexSessionConfig:
+        payload = event.get("session")
+        if isinstance(payload, dict):
+            source = payload
+        else:
+            source = event
+
+        config = cls()
+        if isinstance(source.get("model"), str):
+            config.model = source["model"]
+        if isinstance(source.get("instructions"), str):
+            config.instructions = source["instructions"]
+        if isinstance(source.get("initial_user_text"), str):
+            config.initial_user_text = source["initial_user_text"]
+        if isinstance(source.get("voice"), str):
+            config.voice = source["voice"]
+        if isinstance(source.get("ref_audio"), str):
+            config.ref_audio = source["ref_audio"]
+        if isinstance(source.get("response_format"), str):
+            config.response_format = source["response_format"]
+        if isinstance(source.get("use_tts_template"), bool):
+            config.use_tts_template = bool(source["use_tts_template"])
+        if isinstance(source.get("temperature"), int | float):
+            config.temperature = float(source["temperature"])
+        if isinstance(source.get("max_tokens"), int):
+            config.max_tokens = int(source["max_tokens"])
+        if isinstance(source.get("speed"), int | float):
+            config.speed = float(source["speed"])
+        if isinstance(source.get("idle_timeout_s"), int | float):
+            config.idle_timeout_s = float(source["idle_timeout_s"])
+        if isinstance(source.get("overlap_policy"), str):
+            config.overlap_policy = cls._normalize_overlap_policy(source["overlap_policy"])
+        if isinstance(source.get("overlap_short_ack_ms"), int | float):
+            config.overlap_short_ack_ms = max(0, int(source["overlap_short_ack_ms"]))
+        if isinstance(source.get("overlap_barge_in_ms"), int | float):
+            config.overlap_barge_in_ms = max(0, int(source["overlap_barge_in_ms"]))
+        if isinstance(source.get("overlap_silence_rms"), int | float):
+            config.overlap_silence_rms = max(0.0, float(source["overlap_silence_rms"]))
+        if isinstance(source.get("playback_commit_policy"), str):
+            config.playback_commit_policy = cls._normalize_playback_commit_policy(source["playback_commit_policy"])
+        if isinstance(source.get("modalities"), list) and all(isinstance(x, str) for x in source["modalities"]):
+            config.modalities = list(source["modalities"])
+        if isinstance(source.get("extra_body"), dict):
+            config.extra_body = dict(source["extra_body"])
+            extra = config.extra_body
+            if isinstance(extra.get("overlap_policy"), str):
+                config.overlap_policy = cls._normalize_overlap_policy(extra["overlap_policy"])
+            if isinstance(extra.get("overlap_short_ack_ms"), int | float):
+                config.overlap_short_ack_ms = max(0, int(extra["overlap_short_ack_ms"]))
+            if isinstance(extra.get("overlap_barge_in_ms"), int | float):
+                config.overlap_barge_in_ms = max(0, int(extra["overlap_barge_in_ms"]))
+            if isinstance(extra.get("overlap_silence_rms"), int | float):
+                config.overlap_silence_rms = max(0.0, float(extra["overlap_silence_rms"]))
+            if isinstance(extra.get("playback_commit_policy"), str):
+                config.playback_commit_policy = cls._normalize_playback_commit_policy(extra["playback_commit_policy"])
+        return config
+
+    @classmethod
+    def from_realtime(
+        cls,
+        session_payload: Mapping[str, object],
+        *,
+        model: str | None = None,
+    ) -> DuplexSessionConfig:
+        """Build a config from an OpenAI Realtime ``session`` object (session.update / open_session).
+
+        Applies the wire defaults, validates audio formats and turn detection
+        (raising :class:`DuplexConfigError` with the same codes the Realtime
+        translator used), fills ``turn_detection`` defaults / derives
+        ``overlap_policy``, and stores the Realtime-only fields under the
+        ``realtime_*`` keys of ``extra_body`` exactly like the old
+        ``_session_create_from_realtime``.
+        """
+        from vllm_omni.engine.duplex.realtime_commands import (
+            RealtimeInputDefaults,
+            duplex_response_format,
+            input_audio_transcription_config,
+            json_safe_realtime_payload,
+            realtime_max_output_tokens,
+            realtime_overlap_fields,
+            validate_realtime_session_audio_formats,
+        )
+        from vllm_omni.engine.duplex.turn_detection import (
+            normalize_turn_detection_session_payload,
+            validate_realtime_turn_detection,
+        )
+
+        payload: dict[str, object] = dict(session_payload)
+        format_error = validate_realtime_session_audio_formats(payload)
+        if format_error is not None:
+            raise DuplexConfigError(format_error, code="unsupported_audio_format")
+        turn_detection_error = validate_realtime_turn_detection(payload)
+        if turn_detection_error is not None:
+            raise DuplexConfigError(turn_detection_error, code="unsupported_turn_detection", param="turn_detection")
+        normalize_turn_detection_session_payload(payload)
+        defaults = RealtimeInputDefaults().with_session_payload(payload)
+        payload.update(realtime_overlap_fields(payload))
+
+        audio_config = payload.get("audio")
+        audio_input = audio_config.get("input") if isinstance(audio_config, dict) else None
+        audio_output = audio_config.get("output") if isinstance(audio_config, dict) else None
+        extra_body_payload = payload.get("extra_body")
+        extra_body: dict[str, object] = dict(extra_body_payload) if isinstance(extra_body_payload, dict) else {}
+        extra_body["realtime_session_payload"] = json_safe_realtime_payload(payload)
+        if isinstance(payload.get("tools"), list):
+            extra_body["realtime_tools"] = payload["tools"]
+        if isinstance(payload.get("tool_choice"), str | dict):
+            extra_body["realtime_tool_choice"] = payload["tool_choice"]
+        metadata = payload.get("metadata")
+        if isinstance(metadata, dict):
+            extra_body["realtime_metadata"] = dict(metadata)
+        include = payload.get("include")
+        if isinstance(include, list):
+            extra_body["realtime_include"] = list(include)
+        prompt = payload.get("prompt")
+        if isinstance(prompt, dict):
+            extra_body["realtime_prompt"] = dict(prompt)
+        transcription = input_audio_transcription_config(payload)
+        if isinstance(transcription, dict):
+            extra_body["realtime_input_audio_transcription"] = dict(transcription)
+        noise_reduction = payload.get("input_audio_noise_reduction")
+        if isinstance(noise_reduction, dict):
+            extra_body["realtime_input_audio_noise_reduction"] = dict(noise_reduction)
+        audio_noise_reduction = audio_input.get("noise_reduction") if isinstance(audio_input, dict) else None
+        if isinstance(audio_noise_reduction, dict):
+            extra_body["realtime_input_audio_noise_reduction"] = dict(audio_noise_reduction)
+        if isinstance(audio_config, dict):
+            extra_body["realtime_audio"] = dict(audio_config)
+        if isinstance(payload.get("tracing"), str | dict):
+            extra_body["realtime_tracing"] = payload["tracing"]
+        if isinstance(payload.get("turn_detection"), dict):
+            extra_body["realtime_turn_detection"] = dict(cast("Mapping[str, object]", payload["turn_detection"]))
+        elif "turn_detection" in payload and payload.get("turn_detection") is None:
+            extra_body["realtime_turn_detection"] = None
+        extra_body.setdefault("realtime_output_audio_format", defaults.output_audio_format)
+        voice = payload.get("voice")
+        if not isinstance(voice, str) and isinstance(audio_output, dict):
+            voice = audio_output.get("voice")
+        speed = payload.get("speed")
+        if not isinstance(speed, int | float) and isinstance(audio_output, dict):
+            speed = audio_output.get("speed")
+        resolved_model = payload.get("model") if isinstance(payload.get("model"), str) else model
+        session: dict[str, object] = {
+            "model": resolved_model,
+            "modalities": payload.get("modalities") or payload.get("output_modalities") or ["text", "audio"],
+            "instructions": payload.get("instructions"),
+            # Not a Realtime field, but a session one: a client that cannot
+            # reach the model by speech seeds its opening turn here. Without
+            # this a websocket client could only use the older
+            # ``extra_body.duplex_initial_user_text`` spelling.
+            "initial_user_text": payload.get("initial_user_text"),
+            "voice": voice,
+            "ref_audio": payload.get("ref_audio"),
+            "response_format": duplex_response_format(defaults.output_audio_format),
+            "temperature": payload.get("temperature"),
+            "max_tokens": realtime_max_output_tokens(
+                payload.get("max_response_output_tokens")
+                or payload.get("max_output_tokens")
+                or payload.get("max_tokens")
+            ),
+            "speed": speed,
+            "idle_timeout_s": payload.get("idle_timeout_s") or 300.0,
+            **realtime_overlap_fields(payload),
+            "extra_body": extra_body,
+        }
+        return cls.from_event({"session": session})
+
+    def apply_realtime_update(
+        self,
+        patch: Mapping[str, object],
+        *,
+        session_id: str | None = None,
+        audio_started: bool = False,
+    ) -> None:
+        """Apply a Realtime ``session.update`` patch in place.
+
+        Raises :class:`DuplexConfigError` (``code`` in ``model_update_unsupported``,
+        ``voice_update_after_audio_unsupported``, ``ref_audio_update_unsupported``)
+        when the patch changes something a live session cannot change.
+        ``audio_started`` is ``playback.generated_ms > 0 or playback.sent_ms > 0``.
+        """
+        from vllm_omni.engine.duplex.realtime_commands import (
+            REALTIME_OUTPUT_AUDIO_FORMATS,
+            duplex_response_format,
+            input_audio_transcription_config,
+            json_safe_realtime_payload,
+            parse_realtime_audio_format,
+            realtime_max_output_tokens,
+        )
+
+        # Any: the patch is read with ``isinstance(payload.get(...))`` guards and consumed
+        # through ``payload[...]``; typing the values ``object`` would need a cast per read.
+        payload: dict[str, Any] = dict(patch)
+        model = payload.get("model")
+        audio_config = payload.get("audio")
+        audio_input = audio_config.get("input") if isinstance(audio_config, dict) else None
+        audio_output = audio_config.get("output") if isinstance(audio_config, dict) else None
+        voice = payload.get("voice")
+        if not isinstance(voice, str) and isinstance(audio_output, dict):
+            voice = audio_output.get("voice")
+        if isinstance(model, str) and self.model is not None and model != self.model:
+            raise DuplexConfigError(
+                "session.update cannot change model for an open realtime duplex session",
+                code="model_update_unsupported",
+            )
+        if isinstance(model, str) and self.model is None:
+            self.model = model
+        if isinstance(voice, str) and audio_started:
+            raise DuplexConfigError(
+                "session.update cannot change voice after audio output has started",
+                code="voice_update_after_audio_unsupported",
+            )
+        if isinstance(payload.get("ref_audio"), str):
+            raise DuplexConfigError(
+                "session.update cannot change ref_audio after the session is open", code="ref_audio_update_unsupported"
+            )
+        if isinstance(payload.get("instructions"), str):
+            self.instructions = str(payload["instructions"])
+        elif "instructions" in payload and payload.get("instructions") is None:
+            self.instructions = None
+        if isinstance(voice, str):
+            self.voice = str(voice)
+        elif "voice" in payload and payload.get("voice") is None:
+            self.voice = None
+        response_format = payload.get("output_audio_format") or payload.get("response_format")
+        if response_format is None and isinstance(audio_output, dict):
+            response_format = audio_output.get("format")
+        response_format, _ = parse_realtime_audio_format(response_format)
+        if isinstance(response_format, str) and response_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
+            self.response_format = duplex_response_format(response_format)
+        if isinstance(payload.get("temperature"), int | float):
+            self.temperature = float(payload["temperature"])
+        speed = payload.get("speed")
+        if not isinstance(speed, int | float) and isinstance(audio_output, dict):
+            speed = audio_output.get("speed")
+        if isinstance(speed, int | float):
+            self.speed = float(speed)
+        max_tokens = (
+            payload.get("max_response_output_tokens")
+            if "max_response_output_tokens" in payload
+            else payload.get("max_output_tokens")
+            if "max_output_tokens" in payload
+            else payload.get("max_tokens")
+        )
+        if "max_response_output_tokens" in payload or "max_output_tokens" in payload or "max_tokens" in payload:
+            self.max_tokens = realtime_max_output_tokens(max_tokens)
+        if isinstance(payload.get("overlap_policy"), str):
+            self.overlap_policy = self._normalize_overlap_policy(str(payload["overlap_policy"]))
+        if isinstance(payload.get("overlap_short_ack_ms"), int | float):
+            self.overlap_short_ack_ms = max(0, int(payload["overlap_short_ack_ms"]))
+        if isinstance(payload.get("overlap_barge_in_ms"), int | float):
+            self.overlap_barge_in_ms = max(0, int(payload["overlap_barge_in_ms"]))
+        if isinstance(payload.get("overlap_silence_rms"), int | float):
+            self.overlap_silence_rms = max(0.0, float(payload["overlap_silence_rms"]))
+        if isinstance(payload.get("playback_commit_policy"), str):
+            self.playback_commit_policy = self._normalize_playback_commit_policy(str(payload["playback_commit_policy"]))
+        modalities = payload.get("modalities") or payload.get("output_modalities")
+        if isinstance(modalities, list) and all(isinstance(item, str) for item in modalities):
+            self.modalities = list(modalities)
+        if isinstance(payload.get("extra_body"), dict):
+            self.extra_body.update(payload["extra_body"])
+            extra = payload["extra_body"]
+            if isinstance(extra.get("overlap_policy"), str):
+                self.overlap_policy = self._normalize_overlap_policy(str(extra["overlap_policy"]))
+            if isinstance(extra.get("playback_commit_policy"), str):
+                self.playback_commit_policy = self._normalize_playback_commit_policy(
+                    str(extra["playback_commit_policy"])
+                )
+        if isinstance(payload.get("tools"), list):
+            self.extra_body["realtime_tools"] = payload["tools"]
+        elif "tools" in payload and payload.get("tools") is None:
+            self.extra_body.pop("realtime_tools", None)
+        if isinstance(payload.get("tool_choice"), str | dict):
+            self.extra_body["realtime_tool_choice"] = payload["tool_choice"]
+        elif "tool_choice" in payload and payload.get("tool_choice") is None:
+            self.extra_body.pop("realtime_tool_choice", None)
+        if isinstance(payload.get("metadata"), dict):
+            self.extra_body["realtime_metadata"] = dict(payload["metadata"])
+        elif "metadata" in payload and payload.get("metadata") is None:
+            self.extra_body.pop("realtime_metadata", None)
+        if isinstance(payload.get("include"), list):
+            self.extra_body["realtime_include"] = list(payload["include"])
+        elif "include" in payload and payload.get("include") is None:
+            self.extra_body.pop("realtime_include", None)
+        if isinstance(payload.get("prompt"), dict):
+            self.extra_body["realtime_prompt"] = dict(payload["prompt"])
+        elif "prompt" in payload and payload.get("prompt") is None:
+            self.extra_body.pop("realtime_prompt", None)
+        transcription = input_audio_transcription_config(payload)
+        if isinstance(transcription, dict):
+            self.extra_body["realtime_input_audio_transcription"] = dict(transcription)
+        elif "input_audio_transcription" in payload and payload.get("input_audio_transcription") is None:
+            self.extra_body.pop("realtime_input_audio_transcription", None)
+        if isinstance(payload.get("input_audio_noise_reduction"), dict):
+            self.extra_body["realtime_input_audio_noise_reduction"] = dict(payload["input_audio_noise_reduction"])
+        elif "input_audio_noise_reduction" in payload and payload.get("input_audio_noise_reduction") is None:
+            self.extra_body.pop("realtime_input_audio_noise_reduction", None)
+        if isinstance(audio_input, dict) and isinstance(audio_input.get("noise_reduction"), dict):
+            self.extra_body["realtime_input_audio_noise_reduction"] = dict(audio_input["noise_reduction"])
+        elif isinstance(audio_input, dict) and audio_input.get("noise_reduction") is None:
+            self.extra_body.pop("realtime_input_audio_noise_reduction", None)
+        if isinstance(payload.get("audio"), dict):
+            self.extra_body["realtime_audio"] = dict(payload["audio"])
+        elif "audio" in payload and payload.get("audio") is None:
+            self.extra_body.pop("realtime_audio", None)
+        if isinstance(payload.get("tracing"), str | dict):
+            self.extra_body["realtime_tracing"] = payload["tracing"]
+        elif "tracing" in payload and payload.get("tracing") is None:
+            self.extra_body.pop("realtime_tracing", None)
+        if isinstance(payload.get("turn_detection"), dict):
+            self.extra_body["realtime_turn_detection"] = dict(payload["turn_detection"])
+        elif "turn_detection" in payload and payload.get("turn_detection") is None:
+            self.extra_body["realtime_turn_detection"] = None
+        self.extra_body["realtime_session_payload"] = json_safe_realtime_payload(payload)
+        return None
+
+    @staticmethod
+    def _normalize_overlap_policy(value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized in {policy.value for policy in DuplexOverlapPolicy}:
+            return normalized
+        return DuplexOverlapPolicy.LISTEN_ONLY.value
+
+    @staticmethod
+    def _normalize_playback_commit_policy(value: str) -> str:
+        normalized = value.strip().lower()
+        if normalized in {policy.value for policy in DuplexPlaybackCommitPolicy}:
+            return normalized
+        return DuplexPlaybackCommitPolicy.COMMIT_ALL_ON_DONE.value
+
+
+@dataclass(frozen=True)
+class ResponseCreateOptions:
+    instructions: str | None = None
+    voice: str | None = None
+    response_format: str | None = None
+    temperature: float | None = None
+    max_tokens: int | None = None
+    speed: float | None = None
+    modalities: tuple[str, ...] | None = None
+    extra_body: Mapping[str, object] = field(default_factory=dict)
+
+    def apply_to(self, config: DuplexSessionConfig) -> None:
+        for field_name in ("instructions", "voice", "response_format", "temperature", "max_tokens", "speed"):
+            value = getattr(self, field_name)
+            if value is not None:
+                setattr(config, field_name, value)
+        if self.modalities is not None:
+            config.modalities = list(self.modalities)
+        config.extra_body.update(self.extra_body)
+
+    @classmethod
+    def from_realtime(
+        cls,
+        response_payload: Mapping[str, object],
+        *,
+        private_runtime_config_keys: frozenset[str] = frozenset(),
+    ) -> ResponseCreateOptions:
+        """Parse an OpenAI Realtime ``response`` object into response-scoped options.
+
+        Raises :class:`DuplexConfigError` (``code="unsupported_native_response_options"``)
+        for options a model-native duplex session cannot apply per response.
+        Private runtime keys in ``extra_body`` are dropped.
+        """
+        from vllm_omni.engine.duplex.realtime_commands import (
+            REALTIME_OUTPUT_AUDIO_FORMATS,
+            duplex_response_format,
+            parse_realtime_audio_format,
+            realtime_max_output_tokens,
+        )
+
+        payload: dict[str, object] = dict(response_payload)
+        audio_config = payload.get("audio")
+        audio_output = audio_config.get("output") if isinstance(audio_config, dict) else None
+        nested_voice = audio_output.get("voice") if isinstance(audio_output, dict) else None
+        unsupported = (
+            payload.get("instructions") is not None
+            or payload.get("voice") is not None
+            or nested_voice is not None
+            or payload.get("temperature") is not None
+            or any(
+                payload.get(field_name) is not None
+                for field_name in ("max_response_output_tokens", "max_output_tokens", "max_tokens")
+            )
+            or payload.get("tools") is not None
+            or payload.get("tool_choice") is not None
+        )
+        if unsupported:
+            raise DuplexConfigError(
+                "response.create options are not supported by a model-native duplex session",
+                code="unsupported_native_response_options",
+            )
+        instructions = str(payload["instructions"]) if isinstance(payload.get("instructions"), str) else None
+        voice = payload.get("voice")
+        if not isinstance(voice, str) and isinstance(audio_output, dict):
+            voice = audio_output.get("voice")
+        voice = str(voice) if isinstance(voice, str) else None
+        response_format = payload.get("output_audio_format") or payload.get("response_format")
+        if response_format is None and isinstance(audio_output, dict):
+            response_format = audio_output.get("format")
+        response_format, _ = parse_realtime_audio_format(response_format)
+        if isinstance(response_format, str) and response_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
+            response_format = duplex_response_format(response_format)
+        else:
+            response_format = None
+        temperature = (
+            float(cast("int | float", payload["temperature"]))
+            if isinstance(payload.get("temperature"), int | float)
+            else None
+        )
+        speed = payload.get("speed")
+        if not isinstance(speed, int | float) and isinstance(audio_output, dict):
+            speed = audio_output.get("speed")
+        speed = float(speed) if isinstance(speed, int | float) else None
+        max_tokens = (
+            payload.get("max_response_output_tokens")
+            if "max_response_output_tokens" in payload
+            else payload.get("max_output_tokens")
+            if "max_output_tokens" in payload
+            else payload.get("max_tokens")
+        )
+        if "max_response_output_tokens" in payload or "max_output_tokens" in payload or "max_tokens" in payload:
+            max_tokens = realtime_max_output_tokens(max_tokens)
+        else:
+            max_tokens = None
+        modalities = payload.get("modalities") or payload.get("output_modalities")
+        if isinstance(modalities, list) and all(isinstance(item, str) for item in modalities):
+            modalities = tuple(modalities)
+        else:
+            modalities = None
+        response_extra: dict[str, object] = {}
+        conversation = payload.get("conversation")
+        if isinstance(conversation, str):
+            response_extra["realtime_response_conversation"] = conversation
+        metadata = payload.get("metadata")
+        if isinstance(metadata, dict):
+            response_extra["realtime_response_metadata"] = dict(metadata)
+        prompt = payload.get("prompt")
+        if isinstance(prompt, dict):
+            response_extra["realtime_response_prompt"] = dict(prompt)
+        if isinstance(payload.get("tools"), list):
+            response_extra["realtime_response_tools"] = payload["tools"]
+        if isinstance(payload.get("tool_choice"), str | dict):
+            response_extra["realtime_response_tool_choice"] = payload["tool_choice"]
+        extra_body = payload.get("extra_body")
+        if isinstance(extra_body, dict):
+            response_extra.update(
+                (key, value) for key, value in extra_body.items() if key not in private_runtime_config_keys
+            )
+        return cls(
+            instructions=instructions,
+            voice=voice,
+            response_format=response_format,
+            temperature=temperature,
+            max_tokens=max_tokens,
+            speed=speed,
+            modalities=modalities,
+            extra_body=response_extra,
+        )
+
+
+@dataclass
+class DuplexCommittedInput:
+    message: dict[str, object]
+    turn_id: int
+    epoch: int
+    input_commit_seq: int
+
+
+@dataclass
+class DuplexAssistantAudioTextMark:
+    text_chars: int
+    audio_end_ms: int
+
+
+def realtime_item_to_history_message(item: object) -> dict[str, object] | None:
+    """Convert a Realtime conversation item into a chat history message (None when empty)."""
+    if not isinstance(item, dict):
+        return None
+    role = item.get("role")
+    if role not in {"system", "user", "assistant"}:
+        return None
+    content = item.get("content")
+    if isinstance(content, str):
+        text = content.strip()
+        return {"role": role, "content": text} if text else None
+    if not isinstance(content, list):
+        return None
+    text_chunks: list[str] = []
+    audio_chunks: list[dict[str, object]] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        part_type = part.get("type")
+        if part_type in {"input_text", "text", "output_text"} and isinstance(part.get("text"), str):
+            text_chunks.append(str(part["text"]))
+        elif part_type in {"input_audio", "audio"}:
+            audio = part.get("audio") or part.get("data")
+            fmt = part.get("format") if isinstance(part.get("format"), str) else "wav"
+            if isinstance(audio, str) and audio:
+                audio_chunks.append({"type": "audio_url", "audio_url": {"url": f"data:audio/{fmt};base64,{audio}"}})
+        elif part_type in {"audio_transcript", "transcript"} and isinstance(part.get("text"), str):
+            text_chunks.append(str(part["text"]))
+    text = "".join(text_chunks).strip()
+    if audio_chunks:
+        content_items: list[dict[str, object]] = []
+        if text:
+            content_items.append({"type": "text", "text": text})
+        content_items.extend(audio_chunks)
+        return {"role": role, "content": content_items}
+    if text:
+        return {"role": role, "content": text}
+    return None
+
+
+def realtime_max_output_tokens(value: object) -> int | None:
+    """Normalize Realtime max output tokens (``"inf"`` -> ``None``)."""
+    from vllm_omni.engine.duplex.realtime_commands import realtime_max_output_tokens as _impl
+
+    return _impl(value)
+
+
+def input_audio_transcription_config(session_payload: Mapping[str, object]) -> dict[str, object] | None:
+    """Return the ``input_audio_transcription`` object of a Realtime session payload."""
+    from vllm_omni.engine.duplex.realtime_commands import input_audio_transcription_config as _impl
+
+    return _impl(session_payload)
+
+
+__all__ = [
+    "DuplexAssistantAudioTextMark",
+    "DuplexAudioChunk",
+    "DuplexCapabilities",
+    "DuplexCommittedInput",
+    "DuplexConfigError",
+    "DuplexOverlapPolicy",
+    "DuplexPlaybackCommitPolicy",
+    "DuplexPlaybackCursor",
+    "DuplexPlaybackView",
+    "DuplexSessionConfig",
+    "DuplexSessionState",
+    "DuplexTurnEventType",
+    "DuplexTurnState",
+    "ResponseCreateOptions",
+    "input_audio_transcription_config",
+    "realtime_item_to_history_message",
+    "realtime_max_output_tokens",
+]
diff --git a/vllm_omni/engine/duplex/contracts.py b/vllm_omni/engine/duplex/contracts.py
index 6af4fdea59c..ed14f5fb818 100644
--- a/vllm_omni/engine/duplex/contracts.py
+++ b/vllm_omni/engine/duplex/contracts.py
@@ -1,102 +1,50 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-"""Model-neutral contracts for the experimental duplex engine plugin.
+"""Model-neutral value types shared by the duplex engine components.
 
-This module contains only immutable data transfer objects and narrow protocols.
-Duplex control algorithms, session implementations, model policy, and Realtime
-serving remain in sibling experimental modules.
+Immutable DTOs plus the ``DuplexStagePort`` base class that ``DuplexOrchestrator``
+implements for the session manager/runner.
 """
 
 from __future__ import annotations
 
 import base64
-from collections.abc import Iterable, Mapping
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
 from dataclasses import dataclass, field
 from enum import Enum
 from types import MappingProxyType
-from typing import Any, Protocol
 
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.messages import EngineQueueMessage
 
+@dataclass(frozen=True, slots=True)
+class DuplexFence:
+    """Engine-internal session identity used for stage request ids and stale filtering."""
 
-class SessionMode(str, Enum):
-    TURN = "turn"
-    DUPLEX = "duplex"
-
-
-class DuplexInputMode(str, Enum):
-    APPEND_TOKENS = "append_tokens"
-    APPEND_AUDIO_CHUNK = "append_audio_chunk"
-    REPLACE_LATEST_CHUNK = "replace_latest_chunk"
-    REENCODE_CONTEXT = "reencode_context"
-    ROLLBACK_TO_CHECKPOINT = "rollback_to_checkpoint"
-    TURN_COMMIT_ONLY = "turn_commit_only"
+    session_id: str
+    epoch: int = 0
+    turn_id: int = 0
 
 
 class DuplexOutputAction(str, Enum):
     DIRECT_RESPONSE = "direct_response"
 
 
-@dataclass
-class DuplexRuntimeCapabilities:
-    input_modes: set[DuplexInputMode] = field(default_factory=lambda: {DuplexInputMode.TURN_COMMIT_ONLY})
-    implementation_level: str = "serving_session_adapter"
-
-
 @dataclass(frozen=True)
 class DuplexAppendPlan:
-    prompt: dict[str, Any]
+    prompt: dict[str, object]
 
 
 @dataclass(frozen=True)
 class DuplexOutputDecision:
     action: DuplexOutputAction
-    metadata: Mapping[str, Any] = field(default_factory=dict)
+    metadata: Mapping[str, object] = field(default_factory=dict)
     final_output_type: str = "text"
 
     def __post_init__(self) -> None:
         object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))
 
 
-class DuplexRuntimeExtension(Protocol):
-    """Pure model policy invoked by the experimental duplex control plane."""
-
-    def configure_sampling_params(
-        self,
-        *,
-        runtime_config: dict[str, Any],
-        defaults: tuple[object, ...],
-    ) -> tuple[object, ...]: ...
-
-    def plan_append(
-        self,
-        *,
-        request_id: str,
-        fence: DuplexFence,
-        session_config: dict[str, Any],
-        runtime_config: dict[str, Any],
-        seq: int,
-        turn_seq: int,
-        mode: DuplexInputMode,
-        payload: object,
-        final: bool,
-        sampling_params: object,
-    ) -> DuplexAppendPlan: ...
-
-    def decide_output(
-        self,
-        *,
-        stage_id: int,
-        final_stage_id: int,
-        segment_finished: bool,
-        segment_token_ids: tuple[int, ...],
-        segment_output_metadata: dict[str, Any],
-        output: object,
-    ) -> DuplexOutputDecision | None: ...
-
-
 @dataclass(frozen=True)
 class DuplexRequestIdentity:
     session_id: str
@@ -112,8 +60,8 @@ class DuplexStageRequestContext:
     final_stage_id: int
     config_generation: int
     sampling_params: tuple[object, ...]
-    session_config: Mapping[str, Any] = field(default_factory=dict)
-    runtime_config: Mapping[str, Any] = field(default_factory=dict)
+    session_config: Mapping[str, object] = field(default_factory=dict)
+    runtime_config: Mapping[str, object] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
         object.__setattr__(self, "sampling_params", tuple(self.sampling_params))
@@ -128,7 +76,7 @@ def stage_sampling_params(self) -> object:
 @dataclass(frozen=True)
 class DuplexStageSubmission:
     context: DuplexStageRequestContext
-    prompt: Mapping[str, Any]
+    prompt: Mapping[str, object]
     already_submitted: bool
 
     def __post_init__(self) -> None:
@@ -148,7 +96,7 @@ class DuplexOutputContext:
     final_stage_id: int
     segment_finished: bool
     segment_token_ids: tuple[int, ...] = ()
-    segment_output_metadata: Mapping[str, Any] = field(default_factory=dict)
+    segment_output_metadata: Mapping[str, object] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
         object.__setattr__(self, "segment_token_ids", tuple(self.segment_token_ids))
@@ -159,53 +107,27 @@ def __post_init__(self) -> None:
         )
 
 
-class DuplexStagePort(Protocol):
+class DuplexStagePort(ABC):
+    """Narrow stage-management surface the session runner/manager use (implemented by DuplexOrchestrator)."""
+
     @property
+    @abstractmethod
     def stage_count(self) -> int: ...
 
+    @abstractmethod
     def sampling_defaults(self) -> tuple[object, ...]: ...
 
+    @abstractmethod
     def ensure_request(self, context: DuplexStageRequestContext) -> None: ...
 
+    @abstractmethod
     async def submit(self, submission: DuplexStageSubmission) -> DuplexStageSubmissionResult: ...
 
+    @abstractmethod
     async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None: ...
 
-
-class DuplexControlPlanePort(Protocol):
-    @property
-    def sessions(self) -> object: ...
-
-    def accepts(self, message: object) -> bool: ...
-
-    def dispatch(self, message: object) -> None: ...
-
-    async def shutdown(self) -> None: ...
-
-    def close_sessions_for_request_ids(self, request_ids: list[str]) -> dict[str, list[str]]: ...
-
-    def finalize_closed_sessions(self, session_ids: Iterable[str]) -> None: ...
-
-    def session_for_identity(self, identity: DuplexRequestIdentity | None) -> object | None: ...
-
-    def decide_output(
-        self,
-        stage_id: int,
-        output: object,
-        context: DuplexOutputContext | None,
-    ) -> DuplexOutputDecision | None: ...
-
-
-class CorrelatedRpcTransport(Protocol):
-    def execute(
-        self,
-        key: tuple[str, str],
-        message: EngineQueueMessage,
-        *,
-        timeout: float | None,
-        timeout_message: str,
-        block_on_submit: bool = False,
-    ) -> EngineQueueMessage: ...
+    @abstractmethod
+    async def abort_requests(self, request_ids: list[str]) -> None: ...
 
 
 def duplex_data_plane_request_info(result: dict[str, object]) -> tuple[str | None, int | None]:
@@ -232,20 +154,19 @@ def duplex_resource_request_id(fence: DuplexFence, role: str) -> str:
     ):
         raise ValueError(f"invalid duplex resource role: {role!r}")
     encoded_session_id = base64.urlsafe_b64encode(fence.session_id.encode("utf-8")).decode("ascii").rstrip("=")
-    return f"duplex-s.{encoded_session_id}.i.{fence.incarnation}.e.{fence.epoch}.r.{role}"
+    return f"duplex-s.{encoded_session_id}.e.{fence.epoch}.r.{role}"
 
 
 def duplex_resource_request_belongs_to_session(request_id: str, session_id: str) -> bool:
     """Return whether a current-format resource request belongs to a session."""
     parts = request_id.split(".")
-    if len(parts) != 8 or parts[0] != "duplex-s" or parts[2] != "i" or parts[4] != "e" or parts[6] != "r":
+    if len(parts) != 6 or parts[0] != "duplex-s" or parts[2] != "e" or parts[4] != "r":
         return False
     try:
         int(parts[3])
-        int(parts[5])
     except ValueError:
         return False
-    role = parts[7]
+    role = parts[5]
     if not role or any(
         character not in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_-" for character in role
     ):
@@ -255,21 +176,16 @@ def duplex_resource_request_belongs_to_session(request_id: str, session_id: str)
 
 
 __all__ = [
-    "CorrelatedRpcTransport",
+    "DuplexFence",
     "DuplexAppendPlan",
-    "DuplexControlPlanePort",
-    "DuplexInputMode",
     "DuplexOutputAction",
     "DuplexOutputContext",
     "DuplexOutputDecision",
     "DuplexRequestIdentity",
-    "DuplexRuntimeCapabilities",
-    "DuplexRuntimeExtension",
     "DuplexStagePort",
     "DuplexStageRequestContext",
     "DuplexStageSubmission",
     "DuplexStageSubmissionResult",
-    "SessionMode",
     "duplex_data_plane_request_info",
     "duplex_resource_request_belongs_to_session",
     "duplex_resource_request_id",
diff --git a/vllm_omni/engine/duplex/control_client.py b/vllm_omni/engine/duplex/control_client.py
deleted file mode 100644
index 05ec46e499d..00000000000
--- a/vllm_omni/engine/duplex/control_client.py
+++ /dev/null
@@ -1,228 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import uuid
-from collections.abc import Callable
-
-from vllm_omni.engine.duplex.contracts import CorrelatedRpcTransport
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity
-from vllm_omni.engine.duplex.messages import (
-    AppendDuplexInputMessage,
-    CloseDuplexSessionMessage,
-    DuplexControlResultMessage,
-    DuplexFence,
-    OpenDuplexSessionMessage,
-    ResumeDuplexSessionMessage,
-    SignalDuplexTurnMessage,
-    TouchDuplexSessionMessage,
-)
-
-DuplexControlMessage = (
-    OpenDuplexSessionMessage
-    | AppendDuplexInputMessage
-    | SignalDuplexTurnMessage
-    | CloseDuplexSessionMessage
-    | TouchDuplexSessionMessage
-    | ResumeDuplexSessionMessage
-)
-
-
-class DuplexControlRequestError(RuntimeError):
-    """Typed client-side failure returned by the duplex control plane."""
-
-    def __init__(self, result: dict[str, object]) -> None:
-        error = result.get("error")
-        error_data = error if isinstance(error, dict) else {}
-        self.result = result
-        self.code = str(error_data.get("code") or "internal_error")
-        self.retryable = bool(error_data.get("retryable", False))
-        accepted_fence = result.get("accepted_fence")
-        self.accepted_fence = accepted_fence if isinstance(accepted_fence, DuplexFence) else None
-        lease_generation = result.get("lease_generation")
-        self.lease_generation = lease_generation if isinstance(lease_generation, int) else None
-        super().__init__(f"duplex {result.get('operation')} failed: {result}")
-
-
-class DuplexControlClient:
-    """Builds duplex commands on top of an engine-owned RPC transport."""
-
-    def __init__(
-        self,
-        transport: CorrelatedRpcTransport,
-        *,
-        control_id_factory: Callable[[], str] | None = None,
-    ) -> None:
-        self._transport = transport
-        self._control_id_factory = control_id_factory or (lambda: uuid.uuid4().hex)
-
-    def execute(self, message: DuplexControlMessage, *, timeout: float | None) -> dict[str, object]:
-        result_message = self._transport.execute(
-            ("duplex", message.control_id),
-            message,
-            timeout=timeout,
-            timeout_message=f"duplex control timed out after {timeout} seconds",
-        )
-        if not isinstance(result_message, DuplexControlResultMessage):
-            raise RuntimeError(f"unexpected duplex control result type: {type(result_message).__name__}")
-        if result_message.fence != message.fence:
-            raise RuntimeError(
-                f"duplex control fence mismatch: expected {message.fence!r}, got {result_message.fence!r}"
-            )
-        result = {
-            "fence": result_message.fence,
-            "operation": result_message.operation,
-            "session_id": result_message.session_id,
-            "ok": result_message.ok,
-            "stage_results": list(result_message.stage_results),
-            "unsupported_count": result_message.unsupported_count,
-            "error_count": result_message.error_count,
-            "accepted_fence": result_message.accepted_fence,
-            "lease_generation": result_message.lease_generation,
-            "error": (
-                {
-                    "code": result_message.error.code,
-                    "message": result_message.error.message,
-                    "retryable": result_message.error.retryable,
-                }
-                if result_message.error is not None
-                else None
-            ),
-        }
-        if not result_message.ok:
-            raise DuplexControlRequestError(result)
-        return result
-
-    def open(
-        self,
-        session_id: str,
-        *,
-        session_mode: str,
-        capabilities: dict[str, object] | None,
-        session_config: dict[str, object] | None,
-        runtime_config: dict[str, object] | None,
-        fence: DuplexFence,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        return self.execute(
-            OpenDuplexSessionMessage(
-                control_id=self._control_id_factory(),
-                fence=fence,
-                session_id=session_id,
-                session_mode=session_mode,
-                capabilities=dict(capabilities or {}),
-                session_config=dict(session_config or {}),
-                runtime_config=dict(runtime_config or {}),
-            ),
-            timeout=timeout,
-        )
-
-    def append(
-        self,
-        session_id: str,
-        *,
-        mode: str,
-        payload: object,
-        operation_id: str | None,
-        final: bool,
-        expected_epoch: int | None,
-        fence: DuplexFence,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        if expected_epoch is not None and expected_epoch != fence.epoch:
-            raise ValueError("expected_epoch must match fence.epoch")
-        return self.execute(
-            AppendDuplexInputMessage(
-                control_id=self._control_id_factory(),
-                operation_id=operation_id,
-                fence=fence,
-                session_id=session_id,
-                expected_epoch=expected_epoch,
-                mode=mode,
-                payload=payload,
-                final=final,
-            ),
-            timeout=timeout,
-        )
-
-    def signal(
-        self,
-        session_id: str,
-        *,
-        event: str,
-        fence: DuplexFence,
-        next_fence: DuplexFence | None,
-        session_config: dict[str, object] | None,
-        runtime_config: dict[str, object] | None,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        return self.execute(
-            SignalDuplexTurnMessage(
-                control_id=self._control_id_factory(),
-                fence=fence,
-                session_id=session_id,
-                event=event,
-                next_fence=next_fence,
-                session_config=dict(session_config) if session_config is not None else None,
-                runtime_config=dict(runtime_config) if runtime_config is not None else None,
-            ),
-            timeout=timeout,
-        )
-
-    def close(
-        self,
-        session_id: str,
-        *,
-        reason: str,
-        fence: DuplexFence,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        return self.execute(
-            CloseDuplexSessionMessage(
-                control_id=self._control_id_factory(),
-                fence=fence,
-                session_id=session_id,
-                reason=reason,
-            ),
-            timeout=timeout,
-        )
-
-    def touch(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        activity: DuplexLeaseActivity,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        return self.execute(
-            TouchDuplexSessionMessage(
-                control_id=self._control_id_factory(),
-                fence=fence,
-                session_id=session_id,
-                activity=activity.value,
-            ),
-            timeout=timeout,
-        )
-
-    def resume(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        expected_lease_generation: int,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        return self.execute(
-            ResumeDuplexSessionMessage(
-                control_id=self._control_id_factory(),
-                fence=fence,
-                session_id=session_id,
-                expected_lease_generation=expected_lease_generation,
-            ),
-            timeout=timeout,
-        )
-
-
-__all__ = ["CorrelatedRpcTransport", "DuplexControlClient", "DuplexControlMessage"]
diff --git a/vllm_omni/engine/duplex/control_plane.py b/vllm_omni/engine/duplex/control_plane.py
deleted file mode 100644
index b425542b896..00000000000
--- a/vllm_omni/engine/duplex/control_plane.py
+++ /dev/null
@@ -1,1063 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-"""Orchestrator-side control plane for experimental duplex sessions.
-
-``Orchestrator`` creates this component only when duplex control is enabled
-and supplies a narrow :class:`DuplexStagePort` implementation. Queue messages
-are routed through :meth:`DuplexControlPlane.handle`; stage outputs are passed
-to :meth:`DuplexControlPlane.decide_output`; request cleanup is reported back
-through the control plane so session leases and stage bindings stay coherent.
-
-The module owns duplex session/control algorithms. It deliberately does not
-own stage pools, request queues, or OpenAI Realtime protocol state.
-"""
-
-from __future__ import annotations
-
-import asyncio
-from collections.abc import Callable, Iterable
-from dataclasses import dataclass
-from typing import Any, Protocol
-
-from vllm.logger import init_logger
-
-from vllm_omni.engine.duplex.contracts import (
-    DuplexAppendPlan,
-    DuplexInputMode,
-    DuplexOutputContext,
-    DuplexOutputDecision,
-    DuplexRequestIdentity,
-    DuplexRuntimeCapabilities,
-    DuplexRuntimeExtension,
-    DuplexStagePort,
-    DuplexStageRequestContext,
-    DuplexStageSubmission,
-    DuplexStageSubmissionResult,
-    SessionMode,
-    duplex_resource_request_id,
-)
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity, DuplexLeaseConfig
-from vllm_omni.engine.duplex.messages import (
-    AppendDuplexInputMessage,
-    CloseDuplexSessionMessage,
-    DuplexControlError,
-    DuplexControlResultMessage,
-    DuplexFence,
-    DuplexSessionLifecycleMessage,
-    OpenDuplexSessionMessage,
-    ResumeDuplexSessionMessage,
-    SignalDuplexTurnMessage,
-    TouchDuplexSessionMessage,
-)
-from vllm_omni.engine.duplex.session import (
-    DuplexAppendReservation,
-    DuplexFenceMismatchError,
-    DuplexSessionExpiry,
-    DuplexSessionRuntimeManager,
-    DuplexSessionRuntimeState,
-)
-
-logger = init_logger(__name__)
-
-
-@dataclass(frozen=True)
-class _PendingControlCleanup:
-    kind: str
-    session_id: str
-    fence: DuplexFence
-    submitted_request_ids: tuple[str, ...]
-    reserved_request_ids: tuple[str, ...] = ()
-
-
-@dataclass(frozen=True)
-class _PendingSubmissionCleanup:
-    session_id: str
-    request_ids: tuple[str, ...]
-
-
-@dataclass(frozen=True)
-class _PendingRequestCleanup:
-    session_id: str
-    fence: DuplexFence
-    lease_generation: int
-    request_ids: tuple[str, ...]
-    abort: bool
-
-
-class DuplexResultSink(Protocol):
-    async def put(self, message: DuplexControlResultMessage) -> None: ...
-
-
-class DuplexLifecycleSink(Protocol):
-    async def put(self, message: DuplexSessionLifecycleMessage) -> None: ...
-
-
-class DuplexControlPlane:
-    _MESSAGE_TYPES = (
-        OpenDuplexSessionMessage,
-        AppendDuplexInputMessage,
-        SignalDuplexTurnMessage,
-        CloseDuplexSessionMessage,
-        TouchDuplexSessionMessage,
-        ResumeDuplexSessionMessage,
-    )
-
-    def __init__(
-        self,
-        *,
-        extension: DuplexRuntimeExtension | None,
-        stage_port: DuplexStagePort,
-        result_sink: DuplexResultSink,
-        lifecycle_sink: DuplexLifecycleSink | None = None,
-        lease_config: DuplexLeaseConfig | None = None,
-        clock: Callable[[], float] | None = None,
-        max_sessions: int | None = None,
-        completed_append_limit: int = 256,
-    ) -> None:
-        self._extension = extension
-        self._stage_port = stage_port
-        self._result_sink = result_sink
-        self._lifecycle_sink = lifecycle_sink
-        self._lease_config = lease_config or DuplexLeaseConfig()
-        self._sessions = DuplexSessionRuntimeManager(
-            clock=clock,
-            max_sessions=max_sessions,
-            completed_append_limit=completed_append_limit,
-        )
-        self._pending_expirations: dict[tuple[str, int], DuplexSessionExpiry] = {}
-        self._pending_control_cleanups: dict[tuple[str, str, int, int, int, int], _PendingControlCleanup] = {}
-        self._control_cleanup_tasks: dict[
-            tuple[str, str, int, int, int, int],
-            asyncio.Task[None],
-        ] = {}
-        self._pending_submission_cleanups: dict[str, _PendingSubmissionCleanup] = {}
-        self._submission_cleanup_tasks: dict[str, asyncio.Task[None]] = {}
-        self._pending_request_cleanups: dict[tuple[str, int, int], _PendingRequestCleanup] = {}
-        self._request_cleanup_tasks: dict[tuple[str, int, int], asyncio.Task[None]] = {}
-        self._request_cleanups_in_progress: set[tuple[str, int, int]] = set()
-        self._session_control_tails: dict[str, asyncio.Task[None]] = {}
-        self._dispatched_control_tasks: set[asyncio.Task[None]] = set()
-
-    @property
-    def sessions(self) -> DuplexSessionRuntimeManager:
-        return self._sessions
-
-    @property
-    def pending_submission_cleanup_count(self) -> int:
-        return len(self._pending_submission_cleanups)
-
-    def accepts(self, message: object) -> bool:
-        return isinstance(message, self._MESSAGE_TYPES)
-
-    async def handle(self, message: object) -> None:
-        if isinstance(message, OpenDuplexSessionMessage):
-            await self.handle_open(message)
-        elif isinstance(message, AppendDuplexInputMessage):
-            await self.handle_append(message)
-        elif isinstance(message, SignalDuplexTurnMessage):
-            await self.handle_signal(message)
-        elif isinstance(message, CloseDuplexSessionMessage):
-            await self.handle_close(message)
-        elif isinstance(message, TouchDuplexSessionMessage):
-            await self.handle_touch(message)
-        elif isinstance(message, ResumeDuplexSessionMessage):
-            await self.handle_resume(message)
-        else:
-            raise TypeError(f"Unsupported duplex control message: {type(message).__name__}")
-
-    def dispatch(self, message: object) -> None:
-        """Schedule one control command without blocking unrelated sessions."""
-        if not self.accepts(message):
-            raise TypeError(f"Unsupported duplex control message: {type(message).__name__}")
-        session_id = message.session_id
-        predecessor = self._session_control_tails.get(session_id)
-
-        async def run_ordered() -> None:
-            if predecessor is not None:
-                await predecessor
-            await self.handle(message)
-
-        task = asyncio.create_task(
-            run_ordered(),
-            name=f"duplex-control-{session_id}-{message.control_id}",
-        )
-        self._session_control_tails[session_id] = task
-        self._dispatched_control_tasks.add(task)
-
-        def discard(completed: asyncio.Task[None]) -> None:
-            self._dispatched_control_tasks.discard(completed)
-            if self._session_control_tails.get(session_id) is completed:
-                self._session_control_tails.pop(session_id, None)
-            if not completed.cancelled():
-                completed.exception()
-
-        task.add_done_callback(discard)
-
-    async def drain(self) -> None:
-        while self._dispatched_control_tasks:
-            await asyncio.gather(*tuple(self._dispatched_control_tasks))
-
-    async def shutdown(self) -> None:
-        tasks = tuple(
-            self._dispatched_control_tasks
-            | set(self._control_cleanup_tasks.values())
-            | set(self._submission_cleanup_tasks.values())
-            | set(self._request_cleanup_tasks.values())
-        )
-        for task in tasks:
-            task.cancel()
-        if tasks:
-            await asyncio.gather(*tasks, return_exceptions=True)
-
-    @staticmethod
-    def coerce_capabilities(raw: dict[str, object]) -> DuplexRuntimeCapabilities:
-        input_modes: set[DuplexInputMode] = set()
-        values = raw.get("input_modes")
-        if values is not None and not isinstance(values, list):
-            raise TypeError("duplex input_modes capability must be a list")
-        if isinstance(values, list):
-            for value in values:
-                try:
-                    input_modes.add(DuplexInputMode(value))
-                except (TypeError, ValueError) as exc:
-                    raise ValueError(f"unknown duplex input mode: {value!r}") from exc
-        return DuplexRuntimeCapabilities(
-            input_modes=input_modes or {DuplexInputMode.TURN_COMMIT_ONLY},
-            implementation_level=str(raw.get("implementation_level") or "serving_session_adapter"),
-        )
-
-    def sampling_params_for_config(self, runtime_config: dict[str, Any]) -> list[object]:
-        defaults = self._stage_port.sampling_defaults()
-        if self._extension is None:
-            return list(defaults)
-        configured = self._extension.configure_sampling_params(
-            runtime_config=runtime_config,
-            defaults=defaults,
-        )
-        if not isinstance(configured, tuple):
-            raise TypeError("duplex runtime extension must return sampling parameters as a tuple")
-        if len(configured) != len(defaults):
-            raise ValueError("duplex runtime extension must return one sampling parameter per stage")
-        return list(configured)
-
-    @staticmethod
-    def stage_request_id(fence: DuplexFence, *, stage_id: int) -> str:
-        return duplex_resource_request_id(fence, f"stage{stage_id}")
-
-    def ensure_stage_request(
-        self,
-        session: DuplexSessionRuntimeState,
-        *,
-        stage_id: int,
-        fence: DuplexFence | None = None,
-    ) -> DuplexStageRequestContext | None:
-        if stage_id >= self._stage_port.stage_count:
-            return None
-        effective_fence = fence or session.fence
-        request_id = self.stage_request_id(effective_fence, stage_id=stage_id)
-        session.reserve_stage_request(stage_id, request_id, fence=effective_fence)
-        context = DuplexStageRequestContext(
-            request_id=request_id,
-            session_id=session.session_id,
-            fence=effective_fence,
-            stage_id=stage_id,
-            final_stage_id=self._stage_port.stage_count - 1,
-            config_generation=session.config_generation,
-            sampling_params=tuple(self.sampling_params_for_config(session.runtime_config)),
-            session_config=session.session_config,
-            runtime_config=session.runtime_config,
-        )
-        self._stage_port.ensure_request(context)
-        return context
-
-    async def handle_open(self, message: OpenDuplexSessionMessage) -> None:
-        session: DuplexSessionRuntimeState | None = None
-        try:
-            session_mode = SessionMode(message.session_mode)
-            capabilities = self.coerce_capabilities(message.capabilities)
-            native_append_modes = capabilities.input_modes - {DuplexInputMode.TURN_COMMIT_ONLY}
-            if native_append_modes and self._extension is None:
-                raise RuntimeError("duplex_runtime_extension_not_configured")
-            session = self.sessions.open_session(
-                message.fence,
-                capabilities=capabilities,
-                session_config=message.session_config,
-                runtime_config=message.runtime_config,
-                lease_config=self._lease_config,
-            )
-            request_context = self.ensure_stage_request(session, stage_id=0) if self._extension is not None else None
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="open",
-                session_id=message.session_id,
-                stage_results=[
-                    {
-                        "stage_id": -1,
-                        "replica_id": -1,
-                        "result": {
-                            "supported": True,
-                            "implementation_level": capabilities.implementation_level,
-                            "data_plane_session": True,
-                            "session_mode": session_mode.value,
-                            "scheduler_request_context": request_context is not None,
-                            "request_id": request_context.request_id if request_context is not None else None,
-                        },
-                    }
-                ],
-            )
-        except Exception as exc:
-            if self._control_error(exc).code == "resource_exhausted":
-                logger.info("open_duplex_session rejected: %s", exc)
-            else:
-                logger.exception("open_duplex_session failed: %s", exc)
-            if session is not None and self.sessions.get(message.session_id) is session:
-                reserved_request_ids = tuple(session.resource_request_ids())
-                self.sessions.begin_close_session(session.fence, reason="open_rollback")
-                cleanup_key = self._cleanup_key("open_rollback", session.fence)
-                pending = _PendingControlCleanup(
-                    kind="open_rollback",
-                    session_id=session.session_id,
-                    fence=session.fence,
-                    reserved_request_ids=reserved_request_ids,
-                    submitted_request_ids=(),
-                )
-                self._pending_control_cleanups[cleanup_key] = pending
-                try:
-                    await self._complete_control_cleanup(cleanup_key, pending)
-                except Exception as cleanup_exc:
-                    logger.warning(
-                        "duplex open rollback remains pending for session %s: %s",
-                        session.session_id,
-                        cleanup_exc,
-                    )
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="open",
-                session_id=message.session_id,
-                stage_results=[],
-                error=exc,
-            )
-
-    async def handle_append(self, message: AppendDuplexInputMessage) -> None:
-        session: DuplexSessionRuntimeState | None = None
-        lease_operation_id = f"append:{message.control_id}"
-        operation_started = False
-        try:
-            session = self.sessions.require(message.session_id)
-            await self._complete_pending_submission_cleanup(message.session_id)
-            if message.expected_epoch is not None and message.expected_epoch != message.fence.epoch:
-                raise ValueError("expected_epoch must match fence.epoch")
-            mode = DuplexInputMode(message.mode)
-            if message.operation_id is not None:
-                completed = session.completed_append(
-                    message.operation_id,
-                    fence=message.fence,
-                    mode=mode,
-                    final=message.final,
-                )
-                if completed is not None:
-                    session.touch(message.fence, DuplexLeaseActivity.APPEND)
-                    await self.put_result(
-                        message.control_id,
-                        fence=message.fence,
-                        operation="append",
-                        session_id=message.session_id,
-                        stage_results=completed,
-                    )
-                    return
-            session.begin_operation(message.fence, lease_operation_id)
-            operation_started = True
-            reservation = session.prepare_append(mode=mode, fence=message.fence)
-            stage_results = await self.append_via_data_plane(
-                message,
-                session=session,
-                reservation=reservation,
-                mode=mode,
-            )
-            if message.operation_id is not None:
-                session.record_completed_append(
-                    message.operation_id,
-                    fence=message.fence,
-                    mode=mode,
-                    final=message.final,
-                    stage_results=stage_results,
-                )
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="append",
-                session_id=message.session_id,
-                stage_results=stage_results,
-            )
-        except Exception as exc:
-            logger.exception("append_duplex_input failed: %s", exc)
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="append",
-                session_id=message.session_id,
-                stage_results=[],
-                error=exc,
-            )
-        finally:
-            if session is not None and operation_started and lease_operation_id in session.lease.active_operations:
-                session.end_operation(session.fence, lease_operation_id)
-
-    async def append_via_data_plane(
-        self,
-        message: AppendDuplexInputMessage,
-        *,
-        session: DuplexSessionRuntimeState,
-        reservation: DuplexAppendReservation,
-        mode: DuplexInputMode,
-    ) -> list[dict[str, object]]:
-        if self._extension is None and mode is DuplexInputMode.TURN_COMMIT_ONLY:
-            update = session.commit_append(reservation)
-            return [
-                {
-                    "stage_id": -1,
-                    "replica_id": -1,
-                    "result": {
-                        "supported": True,
-                        "data_plane_append": False,
-                        "seq": update.seq,
-                        "turn_id": update.turn_id,
-                        "turn_seq": update.turn_seq,
-                        "mode": mode.value,
-                    },
-                }
-            ]
-        if self._stage_port.stage_count == 0:
-            return [
-                {
-                    "stage_id": -1,
-                    "replica_id": -1,
-                    "result": {"supported": False, "error": "duplex_data_plane_has_no_stage"},
-                }
-            ]
-        if self._extension is None:
-            raise RuntimeError("duplex_runtime_extension_not_configured")
-
-        stage_id = 0
-        request_id = self.stage_request_id(message.fence, stage_id=stage_id)
-        existing_binding = session.stage_bindings.get(stage_id)
-        already_submitted = existing_binding is not None and existing_binding.request_id == request_id
-        request_context = self.ensure_stage_request(
-            session,
-            stage_id=stage_id,
-            fence=message.fence,
-        )
-        if request_context is None:
-            raise RuntimeError("duplex_data_plane_has_no_stage")
-        append_plan = self._extension.plan_append(
-            request_id=request_id,
-            fence=message.fence,
-            session_config=dict(request_context.session_config),
-            runtime_config=dict(request_context.runtime_config),
-            seq=reservation.update.seq,
-            turn_seq=reservation.update.turn_seq,
-            mode=mode,
-            payload=message.payload,
-            final=message.final,
-            sampling_params=request_context.stage_sampling_params,
-        )
-        if not isinstance(append_plan, DuplexAppendPlan):
-            raise TypeError("duplex runtime extension plan_append() must return DuplexAppendPlan")
-        submission = DuplexStageSubmission(
-            context=request_context,
-            prompt=append_plan.prompt,
-            already_submitted=already_submitted,
-        )
-        submission_result = await self._stage_port.submit(submission)
-        try:
-            if submission_result.request_id != request_id or submission_result.stage_id != stage_id:
-                raise RuntimeError("duplex stage adapter returned a mismatched submission result")
-            update = session.commit_append(reservation)
-            session.bind_stage_request(stage_id, request_id, fence=message.fence)
-        except BaseException:
-            self._pending_submission_cleanups[session.session_id] = _PendingSubmissionCleanup(
-                session_id=session.session_id,
-                request_ids=(request_id,),
-            )
-            try:
-                await self._complete_pending_submission_cleanup(session.session_id)
-            except Exception as cleanup_exc:
-                logger.warning(
-                    "duplex append compensation remains pending for session %s: %s",
-                    session.session_id,
-                    cleanup_exc,
-                )
-            raise
-        return [
-            {
-                "stage_id": stage_id,
-                "replica_id": submission_result.replica_id,
-                "result": {
-                    "supported": True,
-                    "implementation_level": session.capabilities.implementation_level,
-                    "data_plane_append": True,
-                    "request_id": request_id,
-                    "response_stage_id": request_context.final_stage_id,
-                    "seq": update.seq,
-                    "turn_id": update.turn_id,
-                    "response_seq": message.fence.response_seq,
-                    "turn_seq": update.turn_seq,
-                    "mode": mode.value,
-                    "resumable": True,
-                },
-            }
-        ]
-
-    async def handle_signal(self, message: SignalDuplexTurnMessage) -> None:
-        try:
-            cancel_events = {"barge_in", "input.cancel", "response.cancel"}
-            if message.event not in {*cancel_events, "session.update"}:
-                raise ValueError(f"unsupported duplex runtime signal: {message.event}")
-            session = self.sessions.require(message.session_id)
-            await self._complete_pending_submission_cleanup(message.session_id)
-            effective_next_fence = message.next_fence
-            if message.event in cancel_events:
-                if effective_next_fence is None:
-                    raise ValueError(f"{message.event} requires next_fence")
-                cleanup_key = self._cleanup_key("cancel", message.fence)
-                pending = self._pending_control_cleanups.get(cleanup_key)
-                if pending is None:
-                    stale_request_ids = session.prepare_cancel_fence(message.fence, effective_next_fence)
-                    pending = _PendingControlCleanup(
-                        kind="cancel",
-                        session_id=message.session_id,
-                        fence=message.fence,
-                        submitted_request_ids=tuple(stale_request_ids),
-                    )
-                    self._pending_control_cleanups[cleanup_key] = pending
-                await self._complete_control_cleanup(cleanup_key, pending)
-            else:
-                session.accept_fence(message.fence)
-            if message.runtime_config is not None:
-                self.sampling_params_for_config(message.runtime_config)
-            session.replace_configs(
-                session_config=message.session_config,
-                runtime_config=message.runtime_config,
-            )
-            session.touch(session.fence, DuplexLeaseActivity.SIGNAL)
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="signal",
-                session_id=message.session_id,
-                stage_results=[
-                    {
-                        "stage_id": -1,
-                        "replica_id": -1,
-                        "result": {
-                            "supported": True,
-                            "data_plane_signal": True,
-                            "event": message.event,
-                            "fence": message.fence,
-                            "next_fence": effective_next_fence,
-                        },
-                    }
-                ],
-            )
-        except Exception as exc:
-            logger.exception("signal_duplex_turn failed: %s", exc)
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="signal",
-                session_id=message.session_id,
-                stage_results=[],
-                error=exc,
-            )
-
-    async def handle_close(self, message: CloseDuplexSessionMessage) -> None:
-        try:
-            await self._complete_pending_submission_cleanup(message.session_id)
-            session = self.sessions.get(message.session_id)
-            if session is None:
-                await self.put_result(
-                    message.control_id,
-                    fence=message.fence,
-                    operation="close",
-                    session_id=message.session_id,
-                    stage_results=[],
-                )
-                return
-            cleanup_key = self._cleanup_key("close", message.fence)
-            pending = self._pending_control_cleanups.get(cleanup_key)
-            if pending is None:
-                submitted = tuple(session.resource_request_ids(submitted=True))
-                reserved = tuple(session.resource_request_ids(submitted=False))
-                self.sessions.begin_close_session(message.fence, reason=message.reason)
-                pending = _PendingControlCleanup(
-                    kind="close",
-                    session_id=message.session_id,
-                    fence=message.fence,
-                    submitted_request_ids=submitted,
-                    reserved_request_ids=reserved,
-                )
-                self._pending_control_cleanups[cleanup_key] = pending
-            await self._complete_control_cleanup(cleanup_key, pending)
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="close",
-                session_id=message.session_id,
-                stage_results=[
-                    {
-                        "stage_id": -1,
-                        "replica_id": -1,
-                        "result": {
-                            "supported": True,
-                            "data_plane_close": True,
-                            "reason": message.reason,
-                        },
-                    }
-                ],
-            )
-        except Exception as exc:
-            logger.exception("close_duplex_session failed: %s", exc)
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="close",
-                session_id=message.session_id,
-                stage_results=[],
-                error=exc,
-            )
-
-    async def handle_touch(self, message: TouchDuplexSessionMessage) -> None:
-        try:
-            session = self.sessions.require(message.session_id)
-            activity = DuplexLeaseActivity(message.activity)
-            if activity is DuplexLeaseActivity.DETACH:
-                session.detach(message.fence)
-            else:
-                session.touch(message.fence, activity)
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="touch",
-                session_id=message.session_id,
-                stage_results=[
-                    {
-                        "stage_id": -1,
-                        "replica_id": -1,
-                        "result": {
-                            "supported": True,
-                            "activity": activity.value,
-                            "lease_generation": session.lease.generation,
-                        },
-                    }
-                ],
-            )
-        except Exception as exc:
-            logger.exception("touch_duplex_session failed: %s", exc)
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="touch",
-                session_id=message.session_id,
-                stage_results=[],
-                error=exc,
-            )
-
-    async def handle_resume(self, message: ResumeDuplexSessionMessage) -> None:
-        try:
-            session = self.sessions.require(message.session_id)
-            generation = session.resume(
-                message.fence,
-                expected_lease_generation=message.expected_lease_generation,
-            )
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="resume",
-                session_id=message.session_id,
-                stage_results=[
-                    {
-                        "stage_id": -1,
-                        "replica_id": -1,
-                        "result": {
-                            "supported": True,
-                            "lease_generation": generation,
-                        },
-                    }
-                ],
-            )
-        except Exception as exc:
-            logger.exception("resume_duplex_session failed: %s", exc)
-            await self.put_result(
-                message.control_id,
-                fence=message.fence,
-                operation="resume",
-                session_id=message.session_id,
-                stage_results=[],
-                error=exc,
-            )
-
-    async def reap_expired(self, now: float | None = None) -> int:
-        completed = 0
-        for session_id in list(self._pending_submission_cleanups):
-            try:
-                await self._complete_pending_submission_cleanup(session_id)
-            except Exception as exc:
-                logger.warning(
-                    "duplex append compensation remains pending for session %s: %s",
-                    session_id,
-                    exc,
-                )
-        for key, pending in list(self._pending_control_cleanups.items()):
-            try:
-                await self._complete_control_cleanup(key, pending)
-            except Exception as exc:
-                logger.warning(
-                    "duplex %s cleanup remains pending for session %s: %s",
-                    pending.kind,
-                    pending.session_id,
-                    exc,
-                )
-        for key, pending in list(self._pending_request_cleanups.items()):
-            if key in self._request_cleanups_in_progress:
-                continue
-            try:
-                await self._complete_request_cleanup(key, pending)
-            except Exception as exc:
-                logger.warning(
-                    "duplex request cleanup remains pending for session %s: %s",
-                    pending.session_id,
-                    exc,
-                )
-                continue
-            completed += 1
-        for item in self.sessions.collect_expired(
-            now,
-            excluded_session_ids=set(self._pending_submission_cleanups),
-        ):
-            self._pending_expirations.setdefault(
-                (item.session_id, item.lease_generation),
-                item,
-            )
-        for key, item in list(self._pending_expirations.items()):
-            try:
-                if item.submitted_request_ids:
-                    await self._stage_port.cleanup(list(item.submitted_request_ids), abort=True)
-                if item.reserved_request_ids:
-                    await self._stage_port.cleanup(list(item.reserved_request_ids))
-                if self._lifecycle_sink is not None:
-                    await self._lifecycle_sink.put(
-                        DuplexSessionLifecycleMessage(
-                            fence=item.fence,
-                            session_id=item.session_id,
-                            event="expired",
-                            reason=item.reason,
-                            lease_generation=item.lease_generation,
-                            submitted_request_ids=list(item.submitted_request_ids),
-                            reserved_request_ids=list(item.reserved_request_ids),
-                        )
-                    )
-            except Exception as exc:
-                logger.warning(
-                    "duplex expiry cleanup remains pending for session %s: %s",
-                    item.session_id,
-                    exc,
-                )
-                continue
-            session = self.sessions.get(item.session_id)
-            if session is not None and session.lease.generation == item.lease_generation:
-                self.sessions.finalize_close_session(session)
-            self._pending_expirations.pop(key, None)
-            completed += 1
-        return completed
-
-    async def _complete_pending_submission_cleanup(self, session_id: str) -> None:
-        pending = self._pending_submission_cleanups.get(session_id)
-        if pending is None:
-            return
-        task = self._submission_cleanup_tasks.get(session_id)
-        if task is not None and task.done():
-            self._submission_cleanup_tasks.pop(session_id, None)
-            task = None
-        if task is None:
-            task = asyncio.create_task(
-                self._run_submission_cleanup(pending),
-                name=f"duplex-append-compensation-{session_id}",
-            )
-            self._submission_cleanup_tasks[session_id] = task
-
-            def discard(completed: asyncio.Task[None]) -> None:
-                if self._submission_cleanup_tasks.get(session_id) is completed:
-                    self._submission_cleanup_tasks.pop(session_id, None)
-
-            task.add_done_callback(discard)
-        await asyncio.shield(task)
-
-    async def _run_submission_cleanup(self, pending: _PendingSubmissionCleanup) -> None:
-        await self._stage_port.cleanup(list(pending.request_ids), abort=True)
-        session = self.sessions.get(pending.session_id)
-        if session is not None:
-            session.release_request_ids(list(pending.request_ids))
-        if self._pending_submission_cleanups.get(pending.session_id) is pending:
-            self._pending_submission_cleanups.pop(pending.session_id, None)
-
-    async def _complete_request_cleanup(
-        self,
-        key: tuple[str, int, int],
-        pending: _PendingRequestCleanup,
-    ) -> None:
-        task = self._request_cleanup_tasks.get(key)
-        if task is not None and task.done():
-            self._request_cleanup_tasks.pop(key, None)
-            task = None
-        if task is None:
-            task = asyncio.create_task(
-                self._run_request_cleanup(key, pending),
-                name=f"duplex-request-cleanup-{pending.session_id}",
-            )
-            self._request_cleanup_tasks[key] = task
-
-            def discard(completed: asyncio.Task[None]) -> None:
-                if self._request_cleanup_tasks.get(key) is completed:
-                    self._request_cleanup_tasks.pop(key, None)
-
-            task.add_done_callback(discard)
-        await asyncio.shield(task)
-
-    async def _run_request_cleanup(
-        self,
-        key: tuple[str, int, int],
-        pending: _PendingRequestCleanup,
-    ) -> None:
-        await self._stage_port.cleanup(list(pending.request_ids), abort=pending.abort)
-        session = self.sessions.get(pending.session_id)
-        if (
-            session is not None
-            and session.fence.incarnation == pending.fence.incarnation
-            and session.lease.generation == pending.lease_generation
-        ):
-            self.sessions.finalize_close_session(session)
-        if self._pending_request_cleanups.get(key) is pending:
-            self._pending_request_cleanups.pop(key, None)
-            self._request_cleanups_in_progress.discard(key)
-
-    @staticmethod
-    def _cleanup_key(kind: str, fence: DuplexFence) -> tuple[str, str, int, int, int, int]:
-        return (kind, fence.session_id, fence.incarnation, fence.epoch, fence.turn_id, fence.response_seq)
-
-    async def _complete_control_cleanup(
-        self,
-        key: tuple[str, str, int, int, int, int],
-        pending: _PendingControlCleanup,
-    ) -> None:
-        task = self._control_cleanup_tasks.get(key)
-        if task is not None and task.done():
-            self._control_cleanup_tasks.pop(key, None)
-            task = None
-        if task is None:
-            task = asyncio.create_task(
-                self._run_control_cleanup(key, pending),
-                name=f"duplex-{pending.kind}-cleanup-{pending.session_id}",
-            )
-            self._control_cleanup_tasks[key] = task
-
-            def discard(completed: asyncio.Task[None]) -> None:
-                if self._control_cleanup_tasks.get(key) is completed:
-                    self._control_cleanup_tasks.pop(key, None)
-
-            task.add_done_callback(discard)
-        await asyncio.shield(task)
-
-    async def _run_control_cleanup(
-        self,
-        key: tuple[str, str, int, int, int, int],
-        pending: _PendingControlCleanup,
-    ) -> None:
-        if pending.submitted_request_ids:
-            await self._stage_port.cleanup(list(pending.submitted_request_ids), abort=True)
-        if pending.reserved_request_ids:
-            await self._stage_port.cleanup(list(pending.reserved_request_ids))
-        session = self.sessions.get(pending.session_id)
-        if session is not None:
-            if pending.kind == "cancel":
-                session.release_fence(pending.fence)
-            elif pending.kind in {"close", "open_rollback"}:
-                self.sessions.finalize_close_session(session)
-        self._pending_control_cleanups.pop(key, None)
-
-    @classmethod
-    def _iter_result_dicts(cls, result: object):
-        if isinstance(result, dict):
-            yield result
-        elif isinstance(result, list | tuple):
-            for item in result:
-                yield from cls._iter_result_dicts(item)
-
-    @classmethod
-    def _result_counts(cls, stage_results: list[dict[str, object]]) -> tuple[int, int]:
-        unsupported_count = 0
-        error_count = 0
-        for item in stage_results:
-            for result in cls._iter_result_dicts(item.get("result")):
-                if result.get("supported") is False:
-                    unsupported_count += 1
-                if result.get("error"):
-                    error_count += 1
-        return unsupported_count, error_count
-
-    async def put_result(
-        self,
-        control_id: str,
-        *,
-        fence: DuplexFence,
-        operation: str,
-        session_id: str,
-        stage_results: list[dict[str, object]],
-        error: BaseException | str | None = None,
-    ) -> None:
-        control_error = self._control_error(error) if error is not None else None
-        if error is not None:
-            stage_results = [
-                {
-                    "stage_id": -1,
-                    "replica_id": -1,
-                    "result": {"supported": False, "error": control_error.message},
-                }
-            ]
-        unsupported_count, error_count = self._result_counts(stage_results)
-        session = self.sessions.get(session_id)
-        await self._result_sink.put(
-            DuplexControlResultMessage(
-                control_id=control_id,
-                fence=fence,
-                operation=operation,
-                session_id=session_id,
-                ok=error_count == 0 and unsupported_count == 0,
-                stage_results=stage_results,
-                unsupported_count=unsupported_count,
-                error_count=error_count,
-                error=control_error,
-                accepted_fence=session.fence if session is not None else None,
-                lease_generation=session.lease.generation if session is not None else None,
-            )
-        )
-
-    @staticmethod
-    def _control_error(error: BaseException | str) -> DuplexControlError:
-        message = str(error)
-        if isinstance(error, DuplexFenceMismatchError):
-            code = "stale_fence"
-            retryable = False
-        elif "unknown duplex input mode" in message:
-            code = "invalid_capability"
-            retryable = False
-        elif "duplex_session_capacity_exhausted" in message:
-            code = "resource_exhausted"
-            retryable = True
-        elif isinstance(error, KeyError):
-            code = "not_found"
-            retryable = False
-        elif isinstance(error, (TypeError, ValueError)):
-            code = "invalid_argument"
-            retryable = False
-        elif isinstance(error, TimeoutError):
-            code = "timeout"
-            retryable = True
-        else:
-            code = "failed_precondition"
-            retryable = False
-        return DuplexControlError(code=code, message=message, retryable=retryable)
-
-    def decide_output(
-        self,
-        stage_id: int,
-        output: object,
-        context: DuplexOutputContext | None,
-    ) -> DuplexOutputDecision | None:
-        if context is None or self._extension is None:
-            return None
-        session = self._sessions.get(context.identity.session_id)
-        if session is None:
-            return None
-        try:
-            session.touch(context.identity.fence, DuplexLeaseActivity.MODEL_OUTPUT)
-        except RuntimeError:
-            return None
-        decision = self._extension.decide_output(
-            stage_id=stage_id,
-            final_stage_id=context.final_stage_id,
-            segment_finished=context.segment_finished,
-            segment_token_ids=context.segment_token_ids,
-            segment_output_metadata=dict(context.segment_output_metadata),
-            output=output,
-        )
-        if decision is not None and not isinstance(decision, DuplexOutputDecision):
-            raise TypeError("duplex runtime extension decide_output() must return DuplexOutputDecision or None")
-        return decision
-
-    def session_for_identity(self, identity: DuplexRequestIdentity | None) -> DuplexSessionRuntimeState | None:
-        if identity is None:
-            return None
-        return self._sessions.get(identity.session_id)
-
-    def close_sessions_for_request_ids(
-        self,
-        request_ids: list[str],
-        *,
-        abort: bool = False,
-        cleanup_in_progress: bool = False,
-    ) -> dict[str, list[str]]:
-        closed = self._sessions.close_sessions_for_request_ids(request_ids)
-        for session_id, stale_request_ids in closed.items():
-            session = self._sessions.get(session_id)
-            if session is None:
-                continue
-            key = (session_id, session.fence.incarnation, session.lease.generation)
-            existing = self._pending_request_cleanups.get(key)
-            merged_request_ids = tuple(
-                dict.fromkeys(
-                    [
-                        *(existing.request_ids if existing is not None else ()),
-                        *stale_request_ids,
-                    ]
-                )
-            )
-            self._pending_request_cleanups[key] = _PendingRequestCleanup(
-                session_id=session_id,
-                fence=session.fence,
-                lease_generation=session.lease.generation,
-                request_ids=merged_request_ids,
-                abort=abort or (existing.abort if existing is not None else False),
-            )
-            if cleanup_in_progress:
-                self._request_cleanups_in_progress.add(key)
-        return closed
-
-    def defer_request_cleanups(self, session_ids: Iterable[str]) -> None:
-        session_id_set = set(session_ids)
-        active_keys = {key for key in self._request_cleanups_in_progress if key[0] in session_id_set}
-        self._request_cleanups_in_progress.difference_update(active_keys)
-
-    def finalize_closed_sessions(self, session_ids: Iterable[str]) -> None:
-        session_id_set = set(session_ids)
-        for key in list(self._pending_request_cleanups):
-            if key[0] not in session_id_set:
-                continue
-            self._pending_request_cleanups.pop(key, None)
-            self._request_cleanups_in_progress.discard(key)
-        self._sessions.finalize_closed_sessions(session_ids)
-
-
-__all__ = [
-    "DuplexControlPlane",
-    "DuplexOutputContext",
-    "DuplexRequestIdentity",
-    "DuplexResultSink",
-    "DuplexLifecycleSink",
-    "DuplexStagePort",
-    "DuplexStageRequestContext",
-    "DuplexStageSubmission",
-    "DuplexStageSubmissionResult",
-]
diff --git a/vllm_omni/engine/duplex/events.py b/vllm_omni/engine/duplex/events.py
new file mode 100644
index 00000000000..9c131a893e2
--- /dev/null
+++ b/vllm_omni/engine/duplex/events.py
@@ -0,0 +1,756 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Typed events emitted by a duplex session.
+
+Every public event is a frozen dataclass with explicit fields. The Realtime
+wire JSON is *derived* from those fields by :meth:`DuplexEvent.to_realtime`,
+which is pure: it never consults session state. The stateful part (response /
+item ids, content-part bookkeeping) lives in
+``vllm_omni.engine.duplex.realtime_events`` on the session runner and is
+consumed when the events are *constructed*.
+
+``session_id`` / ``epoch`` are bound by
+``DuplexSessionManager.emit`` when an event leaves the runner; producers
+(projector, serving handshake helpers) build events with the defaults.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Mapping
+from dataclasses import dataclass, field, fields
+from typing import ClassVar, cast
+from uuid import uuid4
+
+
+def new_event_id() -> str:
+    return f"event_{uuid4().hex}"
+
+
+#: OpenAI Realtime ``error.type`` for each internal error code.
+REALTIME_ERROR_TYPES_BY_CODE: dict[str, str] = {
+    "bad_event": "invalid_request_error",
+    "bad_audio": "invalid_request_error",
+    "config_timeout": "invalid_request_error",
+    "invalid_json": "invalid_request_error",
+    "event_too_large": "invalid_request_error",
+    "unknown_event": "invalid_request_error",
+    "internal_error": "server_error",
+    "runtime_append_failed": "server_error",
+    "runtime_append_task_failed": "server_error",
+    "runtime_signal_failed": "server_error",
+    "runtime_abort_failed": "server_error",
+    "runtime_data_plane_stream_failed": "server_error",
+    "runtime_data_plane_text_without_audio": "server_error",
+    "resource_exhausted": "rate_limit_error",
+    "session_exists": "invalid_request_error",
+    "session_closed": "invalid_request_error",
+    "unknown_session": "invalid_request_error",
+    "invalid_duplex_runtime_config": "invalid_request_error",
+    "instructions_update_unsupported": "invalid_request_error",
+    "persona_update_unsupported": "invalid_request_error",
+    "voice_update_unsupported": "invalid_request_error",
+    "unsupported_nemotron_duplex_mode": "invalid_request_error",
+    "unsupported_native_response_options": "invalid_request_error",
+    "runtime_touch_failed": "server_error",
+    "engine_error": "server_error",
+    "input_backpressure": "rate_limit_error",
+    "response_already_active": "invalid_request_error",
+    "response_not_active": "invalid_request_error",
+    "response_create_without_input": "invalid_request_error",
+    "text_only_turn_unsupported": "invalid_request_error",
+    "commit_aborted": "server_error",
+    "input_audio_buffer_empty": "invalid_request_error",
+    "missing_item_id": "invalid_request_error",
+    "item_not_found": "invalid_request_error",
+    "playback_item_mismatch": "invalid_request_error",
+    "playback_item_not_found": "invalid_request_error",
+    "playback_ack_too_late": "invalid_request_error",
+    "unsupported_audio_format": "invalid_request_error",
+    "unsupported_turn_detection": "invalid_request_error",
+    "unsupported_ref_audio_path": "invalid_request_error",
+    "ref_audio_required": "invalid_request_error",
+    "model_update_unsupported": "invalid_request_error",
+    "voice_update_after_audio_unsupported": "invalid_request_error",
+    "ref_audio_update_unsupported": "invalid_request_error",
+    "native_text_append_unsupported": "invalid_request_error",
+    "invalid_video_frames": "invalid_request_error",
+    "invalid_function_call_output": "invalid_request_error",
+    "server_vad_unavailable": "server_error",
+}
+
+_IDENTITY_FIELDS = frozenset({"session_id", "epoch", "event_id"})
+
+
+def _wire_value(value: object) -> object:
+    if isinstance(value, Mapping):
+        return {str(k): _wire_value(v) for k, v in value.items()}
+    if isinstance(value, tuple | list):
+        return [_wire_value(v) for v in value]
+    return value
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DuplexEvent:
+    """Base of every public session event."""
+
+    #: Realtime ``type`` this class renders to.
+    wire_type: ClassVar[str] = ""
+    #: Fields that are omitted from the wire object when ``None``.
+    optional_wire_fields: ClassVar[frozenset[str]] = frozenset()
+
+    session_id: str = ""
+    epoch: int | None = None
+    #: Server event id (OpenAI ``event_id``); generated at construction.
+    event_id: str = field(default_factory=new_event_id)
+
+    # ---- identity ----
+
+    @property
+    def type(self) -> str:
+        return self.wire_type
+
+    @property
+    def is_terminal(self) -> bool:
+        return False
+
+    # ---- generic accessors (None when the class has no such field) ----
+
+    @property
+    def response_id(self) -> str | None:
+        return None
+
+    @property
+    def item_id(self) -> str | None:
+        return None
+
+    @property
+    def text(self) -> str | None:
+        return None
+
+    @property
+    def audio(self) -> bytes | None:
+        return None
+
+    # ---- wire rendering (pure) ----
+
+    def _wire_fields(self) -> dict[str, object]:
+        data: dict[str, object] = {}
+        for f in fields(self):
+            if f.name in _IDENTITY_FIELDS:
+                continue
+            value = getattr(self, f.name)
+            if value is None and f.name in self.optional_wire_fields:
+                continue
+            data[f.name] = _wire_value(value)
+        return data
+
+    def to_realtime(self) -> dict[str, object]:
+        """The Realtime wire JSON object for this event (derived from the fields)."""
+        return {"type": self.wire_type, "event_id": self.event_id, **self._wire_fields()}
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"{type(self).__name__}(type={self.wire_type!r}, session_id={self.session_id!r}, epoch={self.epoch!r})"
+
+
+# ---- session lifecycle ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionCreated(DuplexEvent):
+    wire_type = "session.created"
+    optional_wire_fields = frozenset({"attachment_generation", "resume_token"})
+
+    session: Mapping[str, object] = field(default_factory=dict)
+    #: Transport resume credentials (set by the websocket handler when resume is supported).
+    attachment_generation: int | None = None
+    resume_token: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionUpdated(DuplexEvent):
+    wire_type = "session.updated"
+
+    session: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionResumed(SessionCreated):
+    wire_type = "session.resumed"
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, **DuplexEvent._wire_fields(self)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionReplaced(DuplexEvent):
+    """A newer connection took the session over (sent to the replaced socket)."""
+
+    wire_type = "session.replaced"
+
+    attachment_generation: int = 0
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, **DuplexEvent._wire_fields(self)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionResyncRequired(DuplexEvent):
+    """The replay journal cannot bridge the gap; the client must start over."""
+
+    wire_type = "session.resync_required"
+
+    reason: str = "journal_gap"
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, **DuplexEvent._wire_fields(self)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionClosed(DuplexEvent):
+    wire_type = "session.closed"
+
+    reason: str = "closed"
+    #: The session-internal close event (kept for clients that inspect it).
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def is_terminal(self) -> bool:
+        return True
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, "reason": self.reason, "event": _wire_value(self.details)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionExpired(SessionClosed):
+    wire_type = "session.expired"
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, "reason": self.reason}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionHeartbeatAck(DuplexEvent):
+    wire_type = "session.heartbeat_ack"
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TurnEvent(DuplexEvent):
+    """Turn-state transition (``turn.event``)."""
+
+    wire_type = "turn.event"
+
+    event: str = ""
+    turn_state: str = ""
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, "event": self.event, "turn_state": self.turn_state, "epoch": self.epoch}
+
+
+# ---- response lifecycle ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _ResponseEvent(DuplexEvent):
+    """Events addressed to one response (and usually one output item / content part)."""
+
+    response_id: str | None = None  # type: ignore[assignment]
+    item_id: str | None = None  # type: ignore[assignment]
+    output_index: int = 0
+    content_index: int = 0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResponseCreated(DuplexEvent):
+    wire_type = "response.created"
+
+    response_id: str | None = None  # type: ignore[assignment]
+    response: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Listen(DuplexEvent):
+    """The model decided to keep listening (no spoken response for this turn)."""
+
+    wire_type = "response.listen"
+    optional_wire_fields = frozenset({"response_id"})
+
+    response_id: str | None = None  # type: ignore[assignment]
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        response: dict[str, object] = {
+            "object": "realtime.response",
+            "status": "listening",
+            "metadata": _wire_value(self.details),
+        }
+        data: dict[str, object] = {"session_id": self.session_id, "epoch": self.epoch, "response": response}
+        if self.response_id:
+            response["id"] = self.response_id
+            data["response_id"] = self.response_id
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Speak(_ResponseEvent):
+    wire_type = "response.speak"
+
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OverlapDecision(DuplexEvent):
+    wire_type = "overlap.decision"
+
+    policy: str | None = None
+    action: str | None = None
+    reason: str | None = None
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {
+            "session_id": self.session_id,
+            "epoch": self.epoch,
+            "policy": self.policy,
+            "action": self.action,
+            "reason": self.reason,
+            "metadata": _wire_value(self.details),
+        }
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OutputItemAdded(DuplexEvent):
+    wire_type = "response.output_item.added"
+
+    response_id: str | None = None  # type: ignore[assignment]
+    output_index: int = 0
+    item: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def item_id(self) -> str | None:
+        value = self.item.get("id")
+        return value if isinstance(value, str) else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OutputItemDone(OutputItemAdded):
+    wire_type = "response.output_item.done"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ContentPartAdded(_ResponseEvent):
+    wire_type = "response.content_part.added"
+
+    part: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ContentPartDone(ContentPartAdded):
+    wire_type = "response.content_part.done"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AudioDelta(_ResponseEvent):
+    wire_type = "response.output_audio.delta"
+    optional_wire_fields = frozenset({"sample_rate_hz", "metadata"})
+
+    #: Base64 audio in ``format``.
+    delta: str = ""
+    format: str = "pcm16"
+    sample_rate_hz: int | None = None
+    metadata: Mapping[str, object] | None = None
+
+    @property
+    def audio(self) -> bytes | None:
+        try:
+            return base64.b64decode(self.delta)
+        except (ValueError, TypeError):
+            return None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AudioDone(_ResponseEvent):
+    wire_type = "response.output_audio.done"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TranscriptDelta(_ResponseEvent):
+    wire_type = "response.output_audio_transcript.delta"
+
+    delta: str = ""
+
+    @property
+    def text(self) -> str | None:
+        return self.delta
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TranscriptDone(_ResponseEvent):
+    wire_type = "response.output_audio_transcript.done"
+
+    transcript: str = ""
+
+    @property
+    def text(self) -> str | None:
+        return self.transcript
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TextDelta(_ResponseEvent):
+    wire_type = "response.output_text.delta"
+
+    delta: str = ""
+
+    @property
+    def text(self) -> str | None:
+        return self.delta
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TextDone(_ResponseEvent):
+    wire_type = "response.output_text.done"
+
+    text: str = ""  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FunctionCallArgumentsDelta(DuplexEvent):
+    wire_type = "response.function_call_arguments.delta"
+
+    response_id: str | None = None  # type: ignore[assignment]
+    item_id: str | None = None  # type: ignore[assignment]
+    output_index: int = 0
+    call_id: str = ""
+    delta: str = ""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FunctionCallArgumentsDone(DuplexEvent):
+    wire_type = "response.function_call_arguments.done"
+
+    response_id: str | None = None  # type: ignore[assignment]
+    item_id: str | None = None  # type: ignore[assignment]
+    output_index: int = 0
+    call_id: str = ""
+    arguments: str = ""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResponseDone(DuplexEvent):
+    wire_type = "response.done"
+
+    response_id: str | None = None  # type: ignore[assignment]
+    response: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def status(self) -> str | None:
+        value = self.response.get("status")
+        return value if isinstance(value, str) else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RateLimitsUpdated(DuplexEvent):
+    wire_type = "rate_limits.updated"
+
+    rate_limits: tuple[Mapping[str, object], ...] = ()
+
+
+# ---- input buffer / conversation ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InputCommitted(DuplexEvent):
+    wire_type = "input_audio_buffer.committed"
+
+    previous_item_id: str | None = None
+    item_id: str | None = None  # type: ignore[assignment]
+    #: The session-internal ``input.committed`` event.
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {
+            "previous_item_id": self.previous_item_id,
+            "item_id": self.item_id,
+            "event": _wire_value(self.details),
+        }
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InputCleared(DuplexEvent):
+    wire_type = "input_audio_buffer.cleared"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SpeechStarted(DuplexEvent):
+    wire_type = "input_audio_buffer.speech_started"
+
+    audio_start_ms: int = 0
+    item_id: str | None = None  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SpeechStopped(DuplexEvent):
+    wire_type = "input_audio_buffer.speech_stopped"
+
+    audio_end_ms: int = 0
+    item_id: str | None = None  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _ItemEvent(DuplexEvent):
+    previous_item_id: str | None = None
+    item: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def item_id(self) -> str | None:
+        value = self.item.get("id")
+        return value if isinstance(value, str) else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemAdded(_ItemEvent):
+    wire_type = "conversation.item.added"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemCreated(_ItemEvent):
+    wire_type = "conversation.item.created"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemDone(_ItemEvent):
+    wire_type = "conversation.item.done"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemRetrieved(DuplexEvent):
+    wire_type = "conversation.item.retrieved"
+
+    item: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def item_id(self) -> str | None:
+        value = self.item.get("id")
+        return value if isinstance(value, str) else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemDeleted(DuplexEvent):
+    wire_type = "conversation.item.deleted"
+
+    item_id: str | None = None  # type: ignore[assignment]
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"item_id": self.item_id, "event": _wire_value(self.details)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemTruncated(DuplexEvent):
+    wire_type = "conversation.item.truncated"
+
+    item_id: str | None = None  # type: ignore[assignment]
+    content_index: int = 0
+    audio_end_ms: int = 0
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {
+            "item_id": self.item_id,
+            "content_index": self.content_index,
+            "audio_end_ms": self.audio_end_ms,
+            "event": _wire_value(self.details),
+        }
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InputTranscriptionCompleted(DuplexEvent):
+    wire_type = "conversation.item.input_audio_transcription.completed"
+
+    item_id: str | None = None  # type: ignore[assignment]
+    content_index: int = 0
+    transcript: str = ""
+
+    @property
+    def text(self) -> str | None:
+        return self.transcript
+
+
+# ---- playback / control ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OutputAudioCleared(DuplexEvent):
+    wire_type = "output_audio_buffer.cleared"
+
+    response_id: str | None = None  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PlaybackAcknowledged(DuplexEvent):
+    wire_type = "playback.acknowledged"
+
+    #: The session-internal ``playback.acknowledged`` event (cursor, committed_ms ...).
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"event": _wire_value(self.details)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ErrorEvent(DuplexEvent):
+    wire_type = "error"
+
+    code: str = "internal_error"
+    message: str = ""
+    #: Client ``event_id`` this error answers (OpenAI ``error.event_id``).
+    related_event_id: str | None = None
+    param: str | None = None
+    #: Extra keys merged into the wire ``error`` object (``retryable`` ...).
+    extra: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def error_type(self) -> str:
+        return REALTIME_ERROR_TYPES_BY_CODE.get(self.code, "invalid_request_error")
+
+    @property
+    def error(self) -> dict[str, object]:
+        error: dict[str, object] = {"type": self.error_type, "code": self.code, "message": self.message}
+        if self.related_event_id:
+            error["event_id"] = self.related_event_id
+        if self.param:
+            error["param"] = self.param
+        error.update(cast("Mapping[str, object]", _wire_value(self.extra)))
+        return error
+
+    @property
+    def text(self) -> str | None:
+        return self.message
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"error": self.error}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DuplexRawEvent(DuplexEvent):
+    """A session-internal event with no dedicated Realtime type (``duplex.<internal type>``)."""
+
+    wire_type = "duplex.raw"
+
+    internal_type: str = ""
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def type(self) -> str:
+        return f"duplex.{self.internal_type}"
+
+    def to_realtime(self) -> dict[str, object]:
+        return {"type": self.type, "event_id": self.event_id, "event": _wire_value(self.details)}
+
+
+def error_event(
+    code: str,
+    message: str,
+    *,
+    event_id: object | None = None,
+    param: object | None = None,
+    extra: Mapping[str, object] | None = None,
+) -> ErrorEvent:
+    """Build the error event for an internal code; ``event_id`` is the *client* event id."""
+    return ErrorEvent(
+        code=code,
+        message=message,
+        related_event_id=event_id if isinstance(event_id, str) and event_id else None,
+        param=param if isinstance(param, str) and param else None,
+        extra=dict(extra or {}),
+    )
+
+
+#: Internal events that terminate a response/session and must never be dropped as stale.
+DOMAIN_TERMINAL_EVENTS = frozenset(
+    {
+        "response.done",
+        "response.listen",
+        "audio.cancelled",
+        "input.cancelled",
+        "session.closed",
+    }
+)
+
+#: Internal streaming model-output events subject to epoch/close stale filtering.
+MODEL_OUTPUT_EVENTS = frozenset(
+    {
+        "response.created",
+        "response.listen",
+        "response.speak",
+        "response.output_item.added",
+        "response.content_part.added",
+        "response.output_audio.delta",
+        "response.output_audio.done",
+        "response.output_text.delta",
+        "response.output_text.done",
+        "response.text.delta",
+        "response.text.done",
+        "response.message",
+        "response.output_item.done",
+        "response.content_part.done",
+        "response.done",
+    }
+)
+
+
+__all__ = [
+    "DOMAIN_TERMINAL_EVENTS",
+    "MODEL_OUTPUT_EVENTS",
+    "REALTIME_ERROR_TYPES_BY_CODE",
+    "AudioDelta",
+    "AudioDone",
+    "ContentPartAdded",
+    "ContentPartDone",
+    "DuplexEvent",
+    "DuplexRawEvent",
+    "ErrorEvent",
+    "FunctionCallArgumentsDelta",
+    "FunctionCallArgumentsDone",
+    "InputCleared",
+    "InputCommitted",
+    "InputTranscriptionCompleted",
+    "ItemAdded",
+    "ItemCreated",
+    "ItemDeleted",
+    "ItemDone",
+    "ItemRetrieved",
+    "ItemTruncated",
+    "Listen",
+    "OutputAudioCleared",
+    "OutputItemAdded",
+    "OutputItemDone",
+    "OverlapDecision",
+    "PlaybackAcknowledged",
+    "RateLimitsUpdated",
+    "ResponseCreated",
+    "ResponseDone",
+    "SessionClosed",
+    "SessionCreated",
+    "SessionExpired",
+    "SessionHeartbeatAck",
+    "SessionReplaced",
+    "SessionResumed",
+    "SessionResyncRequired",
+    "SessionUpdated",
+    "Speak",
+    "SpeechStarted",
+    "SpeechStopped",
+    "TextDelta",
+    "TextDone",
+    "TranscriptDelta",
+    "TranscriptDone",
+    "TurnEvent",
+    "error_event",
+    "new_event_id",
+]
diff --git a/vllm_omni/engine/duplex/messages.py b/vllm_omni/engine/duplex/messages.py
index 2c49d573fa2..ad264e0c534 100644
--- a/vllm_omni/engine/duplex/messages.py
+++ b/vllm_omni/engine/duplex/messages.py
@@ -1,130 +1,114 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-"""Queue contracts owned by the experimental duplex control plane."""
+"""Queue envelopes exchanged between ``DuplexOmniEngine`` and ``DuplexOrchestrator``.
+
+Sessions live inside the engine (``DuplexSessionRunner`` on the orchestrator
+loop). The API layer only opens/closes/resumes/touches sessions through
+correlated RPC and pushes ``DuplexCommand`` objects one-way; every session
+output travels back as a ``DuplexSessionEventMessage``.
+"""
 
 from __future__ import annotations
 
-from dataclasses import dataclass
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 
 from vllm_omni.engine.messages import EngineQueueMessage
 
+if TYPE_CHECKING:
+    from vllm_omni.engine.duplex.commands import DuplexCommand
+    from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig
+    from vllm_omni.engine.duplex.events import DuplexEvent
 
-@dataclass(frozen=True, slots=True)
-class DuplexFence:
-    """Identity fence carried by experimental duplex control messages."""
 
-    session_id: str
-    epoch: int = 0
-    turn_id: int = 0
-    response_seq: int = 0
-    incarnation: int = 0
+class DuplexSessionError(RuntimeError):
+    """A session control operation was rejected by the engine."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str = "internal_error",
+        retryable: bool = False,
+        session_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.retryable = retryable
+        self.session_id = session_id
 
 
 class OpenDuplexSessionMessage(EngineQueueMessage, kw_only=True):
     type: Literal["open_duplex_session"] = "open_duplex_session"
     control_id: str
-    fence: DuplexFence
-    session_id: str
-    session_mode: str = "duplex"
-    capabilities: dict[str, object]
-    session_config: dict[str, object] | None = None
-    runtime_config: dict[str, object] | None = None
-
-
-class AppendDuplexInputMessage(EngineQueueMessage, kw_only=True):
-    type: Literal["append_duplex_input"] = "append_duplex_input"
-    control_id: str
-    operation_id: str | None = None
-    fence: DuplexFence
     session_id: str
-    expected_epoch: int | None = None
-    mode: str
-    payload: object
-    final: bool = False
-
-
-class SignalDuplexTurnMessage(EngineQueueMessage, kw_only=True):
-    type: Literal["signal_duplex_turn"] = "signal_duplex_turn"
-    control_id: str
-    fence: DuplexFence
-    session_id: str
-    event: str
-    next_fence: DuplexFence | None = None
-    session_config: dict[str, object] | None = None
-    runtime_config: dict[str, object] | None = None
+    #: Already normalized by ``DuplexOmni``; the queue is in-process, so the object crosses as is.
+    session_config: DuplexSessionConfig
 
 
 class CloseDuplexSessionMessage(EngineQueueMessage, kw_only=True):
     type: Literal["close_duplex_session"] = "close_duplex_session"
     control_id: str
-    fence: DuplexFence
     session_id: str
     reason: str = "client_close"
 
 
-class TouchDuplexSessionMessage(EngineQueueMessage, kw_only=True):
-    type: Literal["touch_duplex_session"] = "touch_duplex_session"
-    control_id: str
-    fence: DuplexFence
-    session_id: str
-    activity: str
-
-
 class ResumeDuplexSessionMessage(EngineQueueMessage, kw_only=True):
     type: Literal["resume_duplex_session"] = "resume_duplex_session"
     control_id: str
-    fence: DuplexFence
     session_id: str
     expected_lease_generation: int
 
 
-class DuplexSessionLifecycleMessage(EngineQueueMessage, kw_only=True):
-    type: Literal["duplex_session_lifecycle"] = "duplex_session_lifecycle"
-    fence: DuplexFence
+class TouchDuplexSessionMessage(EngineQueueMessage, kw_only=True):
+    type: Literal["touch_duplex_session"] = "touch_duplex_session"
+    control_id: str
     session_id: str
-    event: str
-    reason: str
-    lease_generation: int
-    submitted_request_ids: list[str]
-    reserved_request_ids: list[str]
+    activity: str
+
 
+class DuplexSessionCommandMessage(EngineQueueMessage, kw_only=True):
+    """One-way session command; rejections come back as ``ErrorEvent``."""
 
-class DuplexControlError(EngineQueueMessage, kw_only=True):
-    code: str
-    message: str
-    retryable: bool = False
+    type: Literal["duplex_session_command"] = "duplex_session_command"
+    session_id: str
+    command: DuplexCommand
 
 
 class DuplexControlResultMessage(EngineQueueMessage, kw_only=True):
     type: Literal["duplex_control_result"] = "duplex_control_result"
     control_id: str
-    fence: DuplexFence
     operation: str
     session_id: str
     ok: bool
-    stage_results: list[dict[str, object]]
-    unsupported_count: int = 0
-    error_count: int = 0
-    error: DuplexControlError | None = None
-    accepted_fence: DuplexFence | None = None
     lease_generation: int | None = None
+    capabilities: DuplexCapabilities | None = None
+    #: The Realtime ``session`` object of the session (wire payload, already a dict).
+    public_session: dict[str, object] | None = None
+    error_code: str | None = None
+    error_message: str | None = None
+    error_retryable: bool = False
 
     @property
     def rpc_correlation_key(self) -> tuple[str, str]:
         return ("duplex", self.control_id)
 
 
+class DuplexSessionEventMessage(EngineQueueMessage, kw_only=True):
+    """A typed session event on the engine output queue."""
+
+    type: Literal["duplex_session_event"] = "duplex_session_event"
+    session_id: str
+    event: DuplexEvent
+
+
 __all__ = [
-    "AppendDuplexInputMessage",
     "CloseDuplexSessionMessage",
-    "DuplexControlError",
     "DuplexControlResultMessage",
-    "DuplexFence",
-    "DuplexSessionLifecycleMessage",
+    "DuplexSessionCommandMessage",
+    "DuplexSessionError",
+    "DuplexSessionEventMessage",
     "OpenDuplexSessionMessage",
     "ResumeDuplexSessionMessage",
-    "SignalDuplexTurnMessage",
     "TouchDuplexSessionMessage",
 ]
diff --git a/vllm_omni/engine/duplex/plugin.py b/vllm_omni/engine/duplex/plugin.py
new file mode 100644
index 00000000000..130d5204d6a
--- /dev/null
+++ b/vllm_omni/engine/duplex/plugin.py
@@ -0,0 +1,329 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Model plugin contract for full-duplex models.
+
+One ``DuplexModelPlugin`` subclass per model binds what used to be two dotted
+paths (the engine ``DuplexRuntimeExtension`` and the serving
+``ServingRuntimeAdapter``). Everything runs engine-side now, so the plugin is
+loaded once by ``DuplexOmniEngine`` and handed to ``DuplexOrchestrator`` /
+``DuplexSessionManager``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from collections.abc import Callable, Iterable, Mapping
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig
+from vllm_omni.engine.duplex.contracts import (
+    DuplexAppendPlan,
+    DuplexFence,
+    DuplexOutputDecision,
+)
+
+if TYPE_CHECKING:
+    from vllm.config import ModelConfig
+
+
+class DuplexRuntimeConfigError(ValueError):
+    """A model plugin rejected client-visible runtime configuration."""
+
+    def __init__(self, message: str, *, code: str = "invalid_duplex_runtime_config") -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def reject_changed_runtime_value(
+    new_value: object,
+    current_value: object,
+    *,
+    message: str,
+    code: str,
+    error_cls: type[DuplexRuntimeConfigError] = DuplexRuntimeConfigError,
+) -> None:
+    if new_value != current_value:
+        raise error_cls(message, code=code)
+
+
+class PcmAppendReservation(ABC):
+    operation_id: str
+    payload: dict[str, object] | None
+
+    @property
+    @abstractmethod
+    def active(self) -> bool: ...
+
+    @property
+    @abstractmethod
+    def byte_count(self) -> int: ...
+
+    @abstractmethod
+    def commit(self) -> None: ...
+
+    @abstractmethod
+    def rollback(self) -> None: ...
+
+
+class PcmAppendBuffer(ABC):
+    @property
+    @abstractmethod
+    def pending_byte_count(self) -> int: ...
+
+    @abstractmethod
+    def clear(self) -> None: ...
+
+    @abstractmethod
+    def clear_force_listen(self) -> None: ...
+
+    @abstractmethod
+    def has_pending(self) -> bool: ...
+
+    @abstractmethod
+    def has_reserved(self) -> bool: ...
+
+    @abstractmethod
+    def prepare_append(
+        self,
+        payload: dict[str, object],
+        *,
+        operation_id: str,
+        chunk_period_ms: int,
+        allow_emit: bool,
+    ) -> PcmAppendReservation | None: ...
+
+    @abstractmethod
+    def prepare_commit(
+        self,
+        *,
+        operation_id: str,
+        chunk_period_ms: int,
+    ) -> PcmAppendReservation: ...
+
+    @abstractmethod
+    def flush(self, *, chunk_period_ms: int) -> dict[str, object] | None: ...
+
+
+class DuplexModelSessionState(ABC):
+    """Model-owned per-session state; owned by the session runner (one per session)."""
+
+    audio_buffer: PcmAppendBuffer
+    input_since_commit: bool
+    speech_since_commit: bool
+    context_locked: bool
+    committed_audio_payload: dict[str, object] | None
+    committed_audio_operation_id: str | None
+    committed_audio_reserved_bytes: int
+    deferred_response_create: bool
+    deferred_precreate_response: bool
+    continuation_owner_id: str | None
+    continuation_units: int
+    pending_silence_task: asyncio.Task[bool] | None
+    pending_silence_owner_id: str | None
+
+    @abstractmethod
+    def retain_committed_audio(
+        self,
+        payload: dict[str, object],
+        *,
+        operation_id: str | None,
+        reserved_bytes: int = 0,
+    ) -> None: ...
+
+    @abstractmethod
+    def clear_committed_audio(self) -> int: ...
+
+    @abstractmethod
+    def clear_continuation(self) -> None: ...
+
+
+class DuplexDataPlane(ABC):
+    """Projects raw stage outputs of one model into internal duplex events."""
+
+    @abstractmethod
+    def begin_request(self, request_id: str) -> None: ...
+
+    @abstractmethod
+    def is_terminal(self, request_id: str | None) -> bool: ...
+
+    @abstractmethod
+    def mark_terminal(self, request_id: str) -> None: ...
+
+    @abstractmethod
+    def close_stream(self, request_id: str) -> None: ...
+
+    @abstractmethod
+    def close_session(self, session_id: str, *, active_request_id: str | None = None) -> None: ...
+
+    @abstractmethod
+    def project(self, result: object, *, context: object | None = None) -> Iterable[dict[str, object]]: ...
+
+
+EncodeAudio = Callable[[object, int, str, float | None], str | None]
+
+
+class DuplexModelPlugin(ABC):
+    """Everything vLLM-Omni needs to know about one full-duplex model.
+
+    Engine policy (sampling params, append planning, output decisions) and
+    session policy (capabilities, runtime configuration, per-session state,
+    data-plane projection) live on the same object so a mismatch between the
+    two halves is impossible by construction.
+    """
+
+    plugin_id: str = ""
+    private_runtime_config_keys: frozenset[str] = frozenset()
+    #: Samples per silence unit the runner appends to keep a model turn going.
+    silence_continuation_samples: int = 16000
+    data_plane: DuplexDataPlane
+
+    def __init__(self, encode_audio: EncodeAudio) -> None:
+        # Constructor-only: concrete plugins hand the encoder to their data plane.
+        del encode_audio
+
+    # ---- engine policy (was DuplexRuntimeExtension) ----
+
+    @abstractmethod
+    def configure_sampling_params(
+        self,
+        *,
+        runtime_config: dict[str, object],
+        defaults: tuple[object, ...],
+    ) -> tuple[object, ...]: ...
+
+    @abstractmethod
+    def plan_append(
+        self,
+        *,
+        request_id: str,
+        fence: DuplexFence,
+        session_config: dict[str, object],
+        runtime_config: dict[str, object],
+        seq: int,
+        turn_seq: int,
+        payload: object,
+        final: bool,
+        sampling_params: object,
+    ) -> DuplexAppendPlan: ...
+
+    @abstractmethod
+    def decide_output(
+        self,
+        *,
+        stage_id: int,
+        final_stage_id: int,
+        segment_finished: bool,
+        segment_token_ids: tuple[int, ...],
+        segment_output_metadata: dict[str, object],
+        output: object,
+    ) -> DuplexOutputDecision | None: ...
+
+    # ---- session policy (was ServingRuntimeAdapter) ----
+
+    @abstractmethod
+    def create_session_state(self) -> DuplexModelSessionState: ...
+
+    @abstractmethod
+    def capabilities(self, *, max_sessions: int) -> DuplexCapabilities: ...
+
+    @abstractmethod
+    def validate_client_extra_body(self, extra_body: object) -> None: ...
+
+    @abstractmethod
+    async def prepare_runtime_config(
+        self, config: DuplexSessionConfig, *, model_config: ModelConfig | None
+    ) -> dict[str, object]: ...
+
+    @abstractmethod
+    def runtime_config_for_update(
+        self,
+        config: DuplexSessionConfig,
+        current: Mapping[str, object],
+    ) -> dict[str, object]: ...
+
+    @abstractmethod
+    def data_plane_context(
+        self,
+        *,
+        epoch: int,
+        turn_id: int,
+        active_response_turn_id: int | None,
+        active_response_id: str | None,
+        auto_responds: bool,
+        response_format: str,
+        speed: float | None,
+        modalities: tuple[str, ...],
+    ) -> object: ...
+
+    # Optional hook: build the runtime config patch for a function-call output
+    # item. Plugins without tools keep the default (no change).
+    def runtime_config_for_function_output(
+        self,
+        config: DuplexSessionConfig,
+        current: Mapping[str, object],
+        item: Mapping[str, object],
+    ) -> dict[str, object] | None:
+        del config, current, item
+        return None
+
+
+def load_duplex_plugin(path: str, encode_audio: EncodeAudio) -> DuplexModelPlugin:
+    module_name, separator, attribute_name = path.rpartition(".")
+    if not separator:
+        raise ValueError(f"Invalid duplex plugin path: {path!r}")
+    plugin_type = getattr(import_module(module_name), attribute_name)
+    plugin = plugin_type(encode_audio)
+    if not isinstance(plugin, DuplexModelPlugin):
+        raise TypeError(f"{path!r} is not a DuplexModelPlugin")
+    if not plugin.plugin_id:
+        raise TypeError("Duplex plugin must declare plugin_id")
+    if not isinstance(getattr(plugin, "data_plane", None), DuplexDataPlane):
+        raise TypeError("Duplex plugin must declare a DuplexDataPlane as data_plane")
+    return plugin
+
+
+def validate_duplex_plugin_sampling(plugin: DuplexModelPlugin, *, sampling_defaults: tuple[object, ...]) -> None:
+    """Fail fast when the plugin cannot produce one sampling parameter per stage."""
+    configured = plugin.configure_sampling_params(runtime_config={}, defaults=sampling_defaults)
+    if not isinstance(configured, tuple):
+        raise TypeError("Duplex plugin must return sampling parameters as a tuple")
+    if len(configured) != len(sampling_defaults):
+        raise ValueError("Duplex plugin must return one sampling parameter per stage")
+    for stage_id, (value, default) in enumerate(zip(configured, sampling_defaults, strict=True)):
+        if default is not None and not isinstance(value, type(default)):
+            raise TypeError(
+                "Duplex plugin sampling parameter type mismatch "
+                f"for stage {stage_id}: expected {type(default).__name__}, got {type(value).__name__}"
+            )
+
+
+def payload_turn_id(payload: object) -> int | None:
+    if not isinstance(payload, Mapping):
+        return None
+    return coerce_int(payload.get("duplex_turn_id", payload.get("model_turn_id")))
+
+
+def coerce_int(value: object) -> int | None:
+    try:
+        return int(value) if value is not None else None
+    except (TypeError, ValueError):
+        return None
+
+
+__all__ = [
+    "DuplexDataPlane",
+    "DuplexModelPlugin",
+    "DuplexModelSessionState",
+    "DuplexRuntimeConfigError",
+    "EncodeAudio",
+    "PcmAppendBuffer",
+    "PcmAppendReservation",
+    "coerce_int",
+    "load_duplex_plugin",
+    "payload_turn_id",
+    "reject_changed_runtime_value",
+    "validate_duplex_plugin_sampling",
+]
diff --git a/vllm_omni/engine/duplex/realtime_commands.py b/vllm_omni/engine/duplex/realtime_commands.py
new file mode 100644
index 00000000000..37036401779
--- /dev/null
+++ b/vllm_omni/engine/duplex/realtime_commands.py
@@ -0,0 +1,887 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""OpenAI Realtime client events -> :class:`DuplexCommand` (stateless).
+
+This is the mapping half of the former ``entrypoints/duplex/realtime_input.py``
+translator. Everything that needed per-session state in the old translator
+(input-buffer emptiness for commits, response-id fallbacks for cancels,
+conversation-item lookups, VAD) is resolved by the session runner through the
+helpers on :class:`~vllm_omni.engine.duplex.realtime_events.RealtimeProjectionState`;
+the commands produced here carry the raw client intent only.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any, cast
+from uuid import uuid4
+
+import numpy as np
+
+from vllm_omni.engine.duplex.audio import convert_input_audio_with_rate
+from vllm_omni.engine.duplex.commands import (
+    AckPlayback,
+    AppendAudio,
+    AppendText,
+    BargeIn,
+    CancelInput,
+    CancelResponse,
+    ClearInput,
+    ClearOutputAudio,
+    CloseSession,
+    Commit,
+    CreateItem,
+    CreateResponse,
+    DeleteItem,
+    DuplexCommand,
+    DuplexCommandError,
+    Heartbeat,
+    SignalTurn,
+    TruncateItem,
+    UpdateSession,
+)
+
+REALTIME_INPUT_AUDIO_FORMATS = {
+    "pcm16",
+    "pcm_s16le",
+    "s16le",
+    "pcm_f32le",
+    "g711_ulaw",
+    "g711_alaw",
+}
+REALTIME_OUTPUT_AUDIO_FORMATS = {
+    "pcm16",
+    "pcm_s16le",
+    "s16le",
+    "wav",
+    "pcm",
+    "g711_ulaw",
+    "g711_alaw",
+}
+
+#: Wire hint keys copied verbatim from a client append onto the internal payload.
+REALTIME_INPUT_HINT_KEYS = (
+    "duration_ms",
+    "audio_duration_ms",
+    "audio_start_ms",
+    "audio_end_ms",
+    "is_speech",
+    "speech",
+    "speech_probability",
+    "vad",
+    "overlap_action",
+    "overlap",
+    "force_barge_in",
+    "force_listen",
+    "text",
+    "transcript",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RealtimeInputDefaults:
+    """Session-level wire defaults an append may omit (derived from the session object)."""
+
+    input_audio_format: str = "pcm16"
+    input_sample_rate_hz: int = 16000
+    output_audio_format: str = "pcm16"
+    output_sample_rate_hz: int | None = None
+    overlap_silence_rms: float = 0.003
+
+    def with_session_payload(self, session_payload: Mapping[str, object]) -> RealtimeInputDefaults:
+        """Return defaults updated from a Realtime ``session`` object (session.update)."""
+        values = apply_realtime_session_defaults(self, session_payload)
+        return values
+
+
+# ---- audio format helpers ----
+
+
+def parse_realtime_audio_format(raw_format: object) -> tuple[object, int | None]:
+    def normalize_format(fmt: str) -> str:
+        normalized = fmt.lower()
+        if normalized in {"audio/pcm", "pcm"}:
+            return "pcm16"
+        if normalized in {"audio/wav", "wav"}:
+            return "wav"
+        if normalized in {"audio/pcm16", "pcm16", "pcm_s16le", "s16le"}:
+            return "pcm16"
+        if normalized in {"audio/pcm_f32le", "pcm_f32le", "f32le"}:
+            return "pcm_f32le"
+        if normalized in {"audio/g711_ulaw", "g711_ulaw", "g711-ulaw", "ulaw", "mulaw"}:
+            return "g711_ulaw"
+        if normalized in {"audio/g711_alaw", "g711_alaw", "g711-alaw", "alaw"}:
+            return "g711_alaw"
+        return fmt
+
+    if isinstance(raw_format, str):
+        return normalize_format(raw_format), None
+    if not isinstance(raw_format, dict):
+        return raw_format, None
+    rate = raw_format.get("rate") or raw_format.get("sample_rate_hz") or raw_format.get("sample_rate")
+    sample_rate_hz = int(rate) if isinstance(rate, int | float) and rate > 0 else None
+    fmt = raw_format.get("type") or raw_format.get("format")
+    if not isinstance(fmt, str):
+        return raw_format, sample_rate_hz
+    return normalize_format(fmt), sample_rate_hz
+
+
+def duplex_response_format(realtime_format: str) -> str:
+    normalized = realtime_format.lower()
+    if normalized in {"pcm16", "pcm_s16le", "s16le"}:
+        return "pcm"
+    if normalized in {"g711_ulaw", "g711_alaw"}:
+        return "pcm"
+    if normalized in {"wav", "pcm"}:
+        return normalized
+    return "wav"
+
+
+def realtime_output_format(duplex_format: object) -> str:
+    if isinstance(duplex_format, str) and duplex_format.lower() in {"g711_ulaw", "g711_alaw"}:
+        return duplex_format.lower()
+    if isinstance(duplex_format, str) and duplex_format.lower() == "pcm":
+        return "pcm16"
+    return str(duplex_format or "wav")
+
+
+def is_supported_realtime_input_format(fmt: object) -> bool:
+    return isinstance(fmt, str) and fmt.lower() in REALTIME_INPUT_AUDIO_FORMATS
+
+
+def realtime_audio_format_object(fmt: object, *, sample_rate_hz: int | None = None) -> dict[str, object]:
+    if isinstance(fmt, str) and fmt.lower() in {"pcm16", "pcm_s16le", "s16le", "pcm"}:
+        payload: dict[str, object] = {"type": "audio/pcm"}
+    elif isinstance(fmt, str) and fmt.lower() == "pcm_f32le":
+        payload = {"type": "audio/pcm_f32le"}
+    elif isinstance(fmt, str) and fmt.lower() == "g711_ulaw":
+        payload = {"type": "audio/g711_ulaw"}
+    elif isinstance(fmt, str) and fmt.lower() == "g711_alaw":
+        payload = {"type": "audio/g711_alaw"}
+    else:
+        payload = {"type": "audio/wav"}
+    if sample_rate_hz is not None:
+        payload["rate"] = int(sample_rate_hz)
+    return payload
+
+
+def validate_realtime_session_audio_formats(session_payload: Mapping[str, object]) -> str | None:
+    audio_config = session_payload.get("audio")
+    input_format: object = session_payload.get("input_audio_format")
+    if input_format is None and isinstance(audio_config, dict):
+        audio_input = audio_config.get("input")
+        if isinstance(audio_input, dict):
+            input_format = audio_input.get("format")
+    parsed_input, _ = parse_realtime_audio_format(input_format)
+    if input_format is not None and not (
+        isinstance(parsed_input, str) and parsed_input.lower() in REALTIME_INPUT_AUDIO_FORMATS
+    ):
+        return f"Unsupported input_audio_format: {input_format}"
+
+    output_format: object = session_payload.get("output_audio_format") or session_payload.get("response_format")
+    if output_format is None and isinstance(audio_config, dict):
+        audio_output = audio_config.get("output")
+        if isinstance(audio_output, dict):
+            output_format = audio_output.get("format")
+    parsed_output, _ = parse_realtime_audio_format(output_format)
+    if output_format is not None and not (
+        isinstance(parsed_output, str) and parsed_output.lower() in REALTIME_OUTPUT_AUDIO_FORMATS
+    ):
+        return f"Unsupported output_audio_format: {output_format}"
+    return None
+
+
+def validate_realtime_response_audio_formats(response_payload: Mapping[str, object]) -> str | None:
+    output_format: object = response_payload.get("output_audio_format") or response_payload.get("response_format")
+    audio_config = response_payload.get("audio")
+    if output_format is None and isinstance(audio_config, dict):
+        audio_output = audio_config.get("output")
+        if isinstance(audio_output, dict):
+            output_format = audio_output.get("format")
+    parsed_output, _ = parse_realtime_audio_format(output_format)
+    if output_format is not None and not (
+        isinstance(parsed_output, str) and parsed_output.lower() in REALTIME_OUTPUT_AUDIO_FORMATS
+    ):
+        return f"Unsupported output_audio_format: {output_format}"
+    return None
+
+
+def validate_conversation_item_audio_formats(item: object) -> str | None:
+    if not isinstance(item, dict):
+        return None
+    content = item.get("content")
+    if not isinstance(content, list):
+        return None
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        if part.get("type") not in {"input_audio", "audio"}:
+            continue
+        raw_format = part.get("format")
+        parsed_format, _ = parse_realtime_audio_format(raw_format)
+        if raw_format is not None and not (
+            isinstance(parsed_format, str) and parsed_format.lower() in REALTIME_INPUT_AUDIO_FORMATS
+        ):
+            return f"Unsupported input_audio format in conversation.item.create: {raw_format}"
+    return None
+
+
+def apply_realtime_session_defaults(
+    defaults: RealtimeInputDefaults,
+    session_payload: Mapping[str, object],
+) -> RealtimeInputDefaults:
+    """Derive the wire defaults a Realtime ``session`` object declares."""
+    input_format: object = session_payload.get("input_audio_format")
+    audio_config = session_payload.get("audio")
+    if input_format is None and isinstance(audio_config, dict):
+        audio_input = audio_config.get("input")
+        if isinstance(audio_input, dict):
+            input_format = audio_input.get("format")
+    input_format, input_rate = parse_realtime_audio_format(input_format)
+    # Any: heterogeneous field values splatted into ``dataclasses.replace`` below.
+    updates: dict[str, Any] = {}
+    if isinstance(input_format, str) and input_format.lower() in REALTIME_INPUT_AUDIO_FORMATS:
+        updates["input_audio_format"] = input_format
+    output_format: object = session_payload.get("output_audio_format") or session_payload.get("response_format")
+    output_rate_raw: object | None = None
+    if output_format is None and isinstance(audio_config, dict):
+        audio_output = audio_config.get("output")
+        if isinstance(audio_output, dict):
+            output_format = audio_output.get("format")
+            output_rate_raw = audio_output.get("sample_rate_hz") or audio_output.get("sample_rate")
+    output_format, output_rate = parse_realtime_audio_format(output_format)
+    if output_rate is None and isinstance(output_rate_raw, int | float) and output_rate_raw > 0:
+        output_rate = int(output_rate_raw)
+    if isinstance(output_format, str) and output_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
+        updates["output_audio_format"] = realtime_output_format(output_format)
+    sample_rate = session_payload.get("sample_rate_hz") or session_payload.get("sample_rate")
+    if sample_rate is None and isinstance(audio_config, dict):
+        audio_input = audio_config.get("input")
+        if isinstance(audio_input, dict):
+            sample_rate = audio_input.get("sample_rate_hz") or audio_input.get("sample_rate")
+    if sample_rate is None:
+        sample_rate = input_rate
+    if isinstance(sample_rate, int | float) and sample_rate > 0:
+        updates["input_sample_rate_hz"] = int(sample_rate)
+    if isinstance(output_rate, int | float) and output_rate > 0:
+        updates["output_sample_rate_hz"] = int(output_rate)
+    overlap_fields = realtime_overlap_fields(session_payload)
+    overlap_silence_rms = overlap_fields.get("overlap_silence_rms")
+    if isinstance(overlap_silence_rms, int | float):
+        updates["overlap_silence_rms"] = max(0.0, float(overlap_silence_rms))
+    return replace(defaults, **updates) if updates else defaults
+
+
+def realtime_overlap_fields(session_payload: Mapping[str, object]) -> dict[str, object]:
+    fields: dict[str, object] = {}
+    if isinstance(session_payload.get("overlap_policy"), str):
+        fields["overlap_policy"] = session_payload["overlap_policy"]
+    for key in ("overlap_short_ack_ms", "overlap_barge_in_ms", "overlap_silence_rms"):
+        value = session_payload.get(key)
+        if isinstance(value, int | float):
+            fields[key] = value
+    if isinstance(session_payload.get("playback_commit_policy"), str):
+        fields["playback_commit_policy"] = session_payload["playback_commit_policy"]
+    return fields
+
+
+def json_safe_realtime_payload(payload: Mapping[str, object]) -> dict[str, object]:
+    clean: dict[str, object] = {}
+    for key, value in payload.items():
+        if key == "extra_body":
+            continue
+        if isinstance(value, str | int | float | bool) or value is None:
+            clean[key] = value
+        elif isinstance(value, dict):
+            clean[key] = json_safe_realtime_payload(value)
+        elif isinstance(value, list):
+            clean[key] = [
+                (json_safe_realtime_payload(item) if isinstance(item, dict) else item)
+                for item in value
+                if isinstance(item, str | int | float | bool | dict) or item is None
+            ]
+    return clean
+
+
+def input_audio_transcription_config(session_payload: Mapping[str, object]) -> dict[str, object] | None:
+    transcription = session_payload.get("input_audio_transcription")
+    if isinstance(transcription, dict):
+        return transcription
+    audio_config = session_payload.get("audio")
+    if not isinstance(audio_config, dict):
+        return None
+    audio_input = audio_config.get("input")
+    if not isinstance(audio_input, dict):
+        return None
+    transcription = audio_input.get("transcription")
+    return transcription if isinstance(transcription, dict) else None
+
+
+def realtime_max_output_tokens(value: object) -> int | None:
+    """Normalize Realtime max output tokens (``"inf"`` -> ``None``)."""
+    if value is None:
+        return None
+    if isinstance(value, str) and value.strip().lower() in {"inf", "infinity", "unlimited"}:
+        return None
+    if isinstance(value, int) and value > 0:
+        return int(value)
+    return None
+
+
+# ---- speech hints ----
+
+
+def input_explicitly_non_speech(event: Mapping[str, object]) -> bool:
+    for key in ("is_speech", "speech"):
+        value = event.get(key)
+        if isinstance(value, bool):
+            return not value
+    vad = event.get("vad")
+    if isinstance(vad, dict):
+        value = vad.get("is_speech")
+        if isinstance(value, bool):
+            return not value
+        probability = vad.get("speech_probability", vad.get("probability"))
+        if isinstance(probability, int | float):
+            return float(probability) < 0.5
+    probability = event.get("speech_probability")
+    return isinstance(probability, int | float) and float(probability) < 0.5
+
+
+def input_looks_like_speech(
+    event: Mapping[str, object],
+    *,
+    audio: object,
+    fmt: object,
+    overlap_silence_rms: float,
+) -> bool:
+    if input_explicitly_non_speech(event):
+        return False
+    for key in ("is_speech", "speech"):
+        value = event.get(key)
+        if isinstance(value, bool):
+            return value
+    vad = event.get("vad")
+    if isinstance(vad, dict):
+        probability = vad.get("speech_probability", vad.get("probability"))
+        if isinstance(probability, int | float):
+            return float(probability) >= 0.5
+    probability = event.get("speech_probability")
+    if isinstance(probability, int | float):
+        return float(probability) >= 0.5
+    if fmt != "pcm_f32le":
+        return True
+    if isinstance(audio, bytes | bytearray):
+        raw = bytes(audio)
+    elif isinstance(audio, str):
+        try:
+            raw = base64.b64decode(audio, validate=True)
+        except (binascii.Error, ValueError):
+            return True
+    else:
+        return True
+    if len(raw) < 4 or len(raw) % 4 != 0:
+        return True
+    samples = np.frombuffer(raw, dtype=np.float32)
+    if samples.size == 0:
+        return False
+    rms = float(np.sqrt(np.mean(np.square(samples.astype(np.float32)))))
+    threshold = event.get("overlap_silence_rms")
+    if not isinstance(threshold, int | float):
+        vad = event.get("vad")
+        if isinstance(vad, dict):
+            threshold = vad.get("silence_rms")
+    silence_rms = float(threshold) if isinstance(threshold, int | float) else overlap_silence_rms
+    return rms >= max(0.0, silence_rms)
+
+
+def copy_realtime_input_hints(source: Mapping[str, object], target: dict[str, object]) -> None:
+    for key in REALTIME_INPUT_HINT_KEYS:
+        if key in source:
+            target[key] = source[key]
+
+
+def validate_realtime_video_frames(video_frames: object, max_slice_nums: object) -> str | None:
+    """Validate omni-duplex camera frames on input_audio_buffer.append.
+
+    Wire contract matches the official MiniCPM-o duplex loop: one base
+    base64 JPEG per ~1 s audio chunk, optionally followed by that unit's
+    stacked composite tiling the sub-frames captured inside it (at most 2
+    images either way). A caller-supplied ``max_slice_nums`` is rejected rather
+    than silently ignored: slicing is Stage 0's decision here, and Stage 0
+    already applies the official HD suggestion for a stacked unit
+    (``max_slice_nums=[2, 1]``). The wire simply does not let the client choose
+    it.
+    """
+    if max_slice_nums not in (None, 1):
+        return "max_slice_nums is not selectable on the wire; Stage0 slices stacked units itself"
+    if not isinstance(video_frames, list):
+        return "video_frames must be a list of base64-encoded images"
+    frames = [frame for frame in video_frames if frame is not None]
+    if len(frames) > 2:
+        return "video_frames carries more than 2 frames for one append; send ~1 frame per 1 s chunk"
+    for frame in frames:
+        if not isinstance(frame, str) or not frame:
+            return "video_frames entries must be non-empty base64 strings"
+        if len(frame) > 4_000_000:
+            return "video_frames entry exceeds 4MB base64; reduce capture resolution or JPEG quality"
+        try:
+            header = base64.b64decode(frame[:64] + "=" * (-len(frame[:64]) % 4))
+        except (binascii.Error, ValueError):
+            return "video_frames entries must be valid base64"
+        if not (header.startswith(b"\xff\xd8") or header.startswith(b"\x89PNG")):
+            return "video_frames entries must be JPEG or PNG images"
+    return None
+
+
+# ---- conversation items ----
+
+
+def normalize_conversation_item(item: Mapping[str, object]) -> dict[str, object]:
+    normalized = dict(item)
+    normalized.setdefault("id", f"item_{uuid4().hex}")
+    normalized.setdefault("object", "realtime.item")
+    normalized.setdefault("type", "message")
+    normalized.setdefault("status", "completed")
+    if "role" not in normalized and normalized.get("type") == "message":
+        normalized["role"] = "user"
+    if not isinstance(normalized.get("content"), list):
+        normalized["content"] = []
+    return normalized
+
+
+def text_chars_for_audio_ms_from_marks(
+    audio_end_ms: int,
+    text_len: int,
+    marks: list[object],
+    *,
+    final_ms: object | None = None,
+) -> int:
+    if text_len <= 0:
+        return 0
+    clean_marks: list[tuple[int, int]] = []
+    for mark in marks:
+        if not isinstance(mark, dict):
+            continue
+        raw_text_chars = mark.get("text_chars")
+        raw_audio_end_ms = mark.get("audio_end_ms", mark.get("audio_ms"))
+        if not isinstance(raw_text_chars, int | float) or not isinstance(raw_audio_end_ms, int | float):
+            continue
+        clean_marks.append((max(0, int(raw_audio_end_ms)), min(text_len, max(0, int(raw_text_chars)))))
+    if not clean_marks:
+        return 0 if audio_end_ms <= 0 else text_len
+    clean_marks.sort(key=lambda item: item[0])
+    audio_end_ms = max(0, int(audio_end_ms))
+    if audio_end_ms <= 0:
+        return 0
+    previous_ms = 0
+    previous_chars = 0
+    for mark_ms, mark_chars in clean_marks:
+        mark_ms = max(previous_ms, mark_ms)
+        mark_chars = max(previous_chars, min(text_len, mark_chars))
+        if audio_end_ms <= mark_ms:
+            if mark_ms <= previous_ms:
+                return mark_chars
+            ratio = (audio_end_ms - previous_ms) / max(1, mark_ms - previous_ms)
+            return int(previous_chars + (mark_chars - previous_chars) * max(0.0, min(1.0, ratio)))
+        previous_ms = mark_ms
+        previous_chars = mark_chars
+    if isinstance(final_ms, int | float) and int(final_ms) > previous_ms:
+        if audio_end_ms >= int(final_ms):
+            return text_len
+        ratio = (audio_end_ms - previous_ms) / max(1, int(final_ms) - previous_ms)
+        return int(previous_chars + (text_len - previous_chars) * max(0.0, min(1.0, ratio)))
+    return text_len if audio_end_ms >= previous_ms else previous_chars
+
+
+def truncate_realtime_item_content(item: dict[str, object], *, content_index: int, audio_end_ms: int) -> None:
+    content = item.get("content")
+    if not isinstance(content, list) or not content:
+        return
+    index = max(0, int(content_index))
+    if index >= len(content):
+        return
+    part = content[index]
+    if not isinstance(part, dict):
+        return
+    transcript = part.get("transcript")
+    if not isinstance(transcript, str) or not transcript:
+        return
+    marks = part.get("audio_text_marks")
+    if isinstance(marks, list):
+        keep_chars = text_chars_for_audio_ms_from_marks(
+            audio_end_ms,
+            len(transcript),
+            marks,
+            final_ms=part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms"),
+        )
+        part["transcript"] = transcript[:keep_chars].rstrip()
+        return
+    duration_ms = part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms")
+    if isinstance(duration_ms, int | float) and duration_ms > 0:
+        keep_chars = int(len(transcript) * max(0.0, min(1.0, int(audio_end_ms) / float(duration_ms))))
+        part["transcript"] = transcript[:keep_chars].rstrip()
+    elif audio_end_ms <= 0:
+        part["transcript"] = ""
+
+
+def validate_realtime_item_truncate(item: Mapping[str, object], *, content_index: int, audio_end_ms: int) -> str | None:
+    if item.get("type") != "message" or item.get("role") != "assistant":
+        return "conversation.item.truncate only supports assistant message items"
+    if audio_end_ms < 0:
+        return "conversation.item.truncate requires non-negative audio_end_ms"
+    content = item.get("content")
+    if not isinstance(content, list) or not content:
+        return None
+    index = max(0, int(content_index))
+    if index >= len(content):
+        return f"conversation.item.truncate content_index out of range: {content_index}"
+    part = content[index]
+    if not isinstance(part, dict):
+        return "conversation.item.truncate target content part is invalid"
+    if part.get("type") not in {"audio", "output_audio"}:
+        return "conversation.item.truncate target content part must be audio"
+    duration_ms = part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms")
+    if isinstance(duration_ms, int | float) and int(duration_ms) >= 0 and audio_end_ms > int(duration_ms):
+        return "conversation.item.truncate audio_end_ms exceeds item audio duration"
+    return None
+
+
+def input_transcript_from_item(item: Mapping[str, object]) -> str:
+    content = item.get("content")
+    if not isinstance(content, list):
+        return ""
+    parts: list[str] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        for key in ("transcript", "text"):
+            value = part.get(key)
+            if isinstance(value, str) and value:
+                if part.get("type") in {"input_audio", "audio", "audio_transcript", "transcript"}:
+                    parts.append(value)
+                    break
+    return "".join(parts).strip()
+
+
+# ---- append / item audio conversion ----
+
+
+def build_append_audio(
+    event: Mapping[str, object],
+    *,
+    defaults: RealtimeInputDefaults,
+    hints_source: Mapping[str, object] | None = None,
+) -> AppendAudio:
+    """Validate, convert (to 16 kHz ``pcm_f32le`` base64) and pack one audio append.
+
+    Speech classification without VAD (``is_speech`` on the command) uses the
+    explicit wire hints and the RMS fallback exactly like the old translator.
+    """
+    event_id = cast("str", event.get("event_id")) if isinstance(event.get("event_id"), str) else None
+    audio = event.get("audio") or event.get("delta")
+    fmt, format_rate = parse_realtime_audio_format(
+        event.get("format") or event.get("input_audio_format") or defaults.input_audio_format
+    )
+    sample_rate_hz = (
+        event.get("sample_rate_hz") or event.get("sample_rate") or format_rate or defaults.input_sample_rate_hz
+    )
+    if not is_supported_realtime_input_format(fmt):
+        raise DuplexCommandError(
+            f"Unsupported input_audio_format: {fmt}",
+            code="unsupported_audio_format",
+            event_id=event_id,
+        )
+    try:
+        audio, fmt, sample_rate_hz = convert_input_audio_with_rate(
+            audio,
+            fmt,
+            sample_rate_hz=sample_rate_hz if isinstance(sample_rate_hz, int | float) else None,
+        )
+    except ValueError as exc:
+        raise DuplexCommandError(str(exc), code="bad_event", event_id=event_id) from exc
+    hints: dict[str, object] = {}
+    if hints_source is not None:
+        copy_realtime_input_hints(hints_source, hints)
+    copy_realtime_input_hints(event, hints)
+    looks_like_speech = input_looks_like_speech(
+        {**(hints_source or {}), **event},
+        audio=audio,
+        fmt=fmt,
+        overlap_silence_rms=defaults.overlap_silence_rms,
+    )
+    video_frames: tuple[str, ...] = ()
+    raw_frames = event.get("video_frames")
+    if raw_frames is not None:
+        frames_error = validate_realtime_video_frames(raw_frames, event.get("max_slice_nums"))
+        if frames_error is not None:
+            raise DuplexCommandError(frames_error, code="invalid_video_frames", event_id=event_id)
+        if isinstance(raw_frames, list):
+            video_frames = tuple(frame for frame in raw_frames if isinstance(frame, str) and frame)
+    duration_ms = hints.get("duration_ms", hints.get("audio_duration_ms"))
+    audio_end_ms = hints.get("audio_end_ms")
+    try:
+        audio_bytes = base64.b64decode(audio, validate=True) if isinstance(audio, str) and audio else b""
+    except (binascii.Error, ValueError) as exc:
+        raise DuplexCommandError("input audio is not valid base64", code="bad_audio", event_id=event_id) from exc
+    return AppendAudio(
+        event_id=event_id,
+        audio=audio_bytes,
+        format=str(fmt),
+        sample_rate_hz=int(sample_rate_hz) if isinstance(sample_rate_hz, int | float) else None,
+        is_speech=looks_like_speech,
+        video_frames=video_frames,
+        duration_ms=int(duration_ms) if isinstance(duration_ms, int | float) else None,
+        audio_end_ms=int(audio_end_ms) if isinstance(audio_end_ms, int | float) else None,
+        hints=hints,
+    )
+
+
+# ---- translation ----
+
+
+def translate_realtime_command(
+    payload: Mapping[str, object],
+    *,
+    defaults: RealtimeInputDefaults | None = None,
+) -> DuplexCommand:
+    """Map one OpenAI Realtime client event onto a :class:`DuplexCommand`.
+
+    Raises :class:`DuplexCommandError` for malformed or unsupported payloads.
+    ``session.resume`` and ``session.event_ack`` are transport concerns and are
+    rejected with ``code="unknown_event"``.
+    """
+    defaults = defaults or RealtimeInputDefaults()
+    event_type = payload.get("type")
+    event_id = cast("str", payload.get("event_id")) if isinstance(payload.get("event_id"), str) else None
+    if not isinstance(event_type, str):
+        raise DuplexCommandError("Duplex event missing string type", code="bad_event", event_id=event_id)
+
+    if event_type == "session.update":
+        session = payload.get("session")
+        session_payload: Mapping[str, object] = session if isinstance(session, dict) else payload
+        format_error = validate_realtime_session_audio_formats(session_payload)
+        if format_error is not None:
+            raise DuplexCommandError(format_error, code="unsupported_audio_format", event_id=event_id)
+        from vllm_omni.engine.duplex.turn_detection import validate_realtime_turn_detection
+
+        turn_detection_error = validate_realtime_turn_detection(session_payload)
+        if turn_detection_error is not None:
+            raise DuplexCommandError(turn_detection_error, code="unsupported_turn_detection", event_id=event_id)
+        return UpdateSession(event_id=event_id, patch=dict(session_payload))
+
+    if event_type == "conversation.item.create":
+        item = payload.get("item")
+        format_error = validate_conversation_item_audio_formats(item)
+        if format_error is not None:
+            raise DuplexCommandError(format_error, code="unsupported_audio_format", event_id=event_id)
+        if not isinstance(item, dict):
+            raise DuplexCommandError("conversation.item.create requires item", code="bad_event", event_id=event_id)
+        previous_item_id = payload.get("previous_item_id")
+        return CreateItem(
+            event_id=event_id,
+            item=normalize_conversation_item(item),
+            previous_item_id=previous_item_id if isinstance(previous_item_id, str) else None,
+        )
+
+    if event_type == "conversation.item.delete":
+        item_id = payload.get("item_id")
+        if not isinstance(item_id, str) or not item_id:
+            raise DuplexCommandError(
+                "conversation.item.delete requires item_id", code="missing_item_id", event_id=event_id
+            )
+        return DeleteItem(event_id=event_id, item_id=item_id)
+
+    if event_type == "conversation.item.truncate":
+        item_id = payload.get("item_id")
+        audio_end_ms = payload.get("audio_end_ms")
+        content_index = payload.get("content_index", 0)
+        if not isinstance(item_id, str) or not item_id:
+            raise DuplexCommandError(
+                "conversation.item.truncate requires item_id", code="missing_item_id", event_id=event_id
+            )
+        if not isinstance(audio_end_ms, int | float):
+            raise DuplexCommandError(
+                "conversation.item.truncate requires numeric audio_end_ms", code="bad_event", event_id=event_id
+            )
+        return TruncateItem(
+            event_id=event_id,
+            item_id=item_id,
+            audio_end_ms=int(audio_end_ms),
+            content_index=int(content_index) if isinstance(content_index, int | float) else 0,
+        )
+
+    if event_type == "input_audio_buffer.append":
+        return build_append_audio(dict(payload), defaults=defaults)
+
+    if event_type in {"input_audio_buffer.commit", "input.commit"}:
+        final = payload.get("final", True)
+        create_response = payload.get("response_create", payload.get("create_response"))
+        is_speech = payload.get("is_speech")
+        return Commit(
+            event_id=event_id,
+            final=bool(final) if isinstance(final, bool) else True,
+            create_response=(
+                bool(create_response)
+                if isinstance(create_response, bool)
+                else (True if event_type == "input.commit" and create_response is None else None)
+            ),
+            is_speech=is_speech if isinstance(is_speech, bool) else None,
+        )
+
+    if event_type == "input_audio_buffer.clear":
+        return ClearInput(event_id=event_id)
+
+    if event_type == "output_audio_buffer.clear":
+        response_id = payload.get("response_id")
+        return ClearOutputAudio(
+            event_id=event_id,
+            response_id=response_id if isinstance(response_id, str) and response_id else None,
+        )
+
+    if event_type == "response.cancel":
+        response_id = payload.get("response_id")
+        return CancelResponse(
+            event_id=event_id,
+            response_id=response_id if isinstance(response_id, str) and response_id else None,
+        )
+
+    if event_type == "response.create":
+        response_payload = payload.get("response")
+        if isinstance(response_payload, dict):
+            format_error = validate_realtime_response_audio_formats(response_payload)
+            if format_error is not None:
+                raise DuplexCommandError(format_error, code="unsupported_audio_format", event_id=event_id)
+        return CreateResponse(
+            event_id=event_id,
+            options=dict(response_payload) if isinstance(response_payload, dict) else {},
+        )
+
+    if event_type in {"playback.ack", "audio.playback_ack"}:
+        played_ms = payload.get("played_ms")
+        if not isinstance(played_ms, int | float):
+            raise DuplexCommandError("playback.ack requires numeric played_ms", code="bad_event", event_id=event_id)
+        committed_ms = payload.get("committed_ms")
+        response_id = payload.get("response_id")
+        item_id = payload.get("item_id")
+        return AckPlayback(
+            event_id=event_id,
+            played_ms=int(played_ms),
+            committed_ms=int(committed_ms) if isinstance(committed_ms, int | float) else None,
+            response_id=response_id if isinstance(response_id, str) and response_id else None,
+            item_id=item_id if isinstance(item_id, str) and item_id else None,
+        )
+
+    if event_type == "session.heartbeat":
+        return Heartbeat(event_id=event_id)
+
+    if event_type == "conversation.item.retrieve":
+        # The projected conversation items live engine-side; the runner answers.
+        return SignalTurn(event_id=event_id, event="conversation.item.retrieve", signal_payload=dict(payload))
+
+    if event_type in {"session.close", "close", "close_session"}:
+        reason = payload.get("reason")
+        return CloseSession(event_id=event_id, reason=reason if isinstance(reason, str) and reason else "client_close")
+
+    if event_type in {"input.text.append", "input_text.append", "push_text"}:
+        text = payload.get("text")
+        if not isinstance(text, str):
+            raise DuplexCommandError("input.text.append requires text", code="bad_event", event_id=event_id)
+        return AppendText(event_id=event_id, text=text)
+
+    if event_type == "input.cancel":
+        return CancelInput(event_id=event_id)
+
+    if event_type == "barge_in":
+        return BargeIn(event_id=event_id)
+
+    if event_type in {"turn.signal", "signal_turn"}:
+        signal_event = payload.get("event")
+        if not isinstance(signal_event, str) or not signal_event:
+            raise DuplexCommandError("turn.signal requires event", code="bad_event", event_id=event_id)
+        signal_payload = payload.get("payload")
+        signal_payload = dict(signal_payload) if isinstance(signal_payload, dict) else {}
+        if signal_event == "input.cancel":
+            return CancelInput(event_id=event_id)
+        if signal_event == "barge_in":
+            return BargeIn(event_id=event_id)
+        if signal_event == "response.cancel":
+            response_id = signal_payload.get("response_id", payload.get("response_id"))
+            return CancelResponse(
+                event_id=event_id,
+                response_id=response_id if isinstance(response_id, str) and response_id else None,
+            )
+        if signal_event == "session.update":
+            return UpdateSession(event_id=event_id, patch=signal_payload)
+        if signal_event == "conversation.item.create":
+            item = signal_payload.get("item")
+            if not isinstance(item, dict):
+                raise DuplexCommandError("conversation.item.create requires item", code="bad_event", event_id=event_id)
+            previous_item_id = signal_payload.get("previous_item_id")
+            return CreateItem(
+                event_id=event_id,
+                item=normalize_conversation_item(item),
+                previous_item_id=previous_item_id if isinstance(previous_item_id, str) else None,
+            )
+        if signal_event == "conversation.item.delete":
+            item_id = signal_payload.get("item_id")
+            if not isinstance(item_id, str) or not item_id:
+                raise DuplexCommandError(
+                    "conversation.item.delete requires item_id", code="missing_item_id", event_id=event_id
+                )
+            return DeleteItem(event_id=event_id, item_id=item_id)
+        if signal_event == "conversation.item.truncate":
+            item_id = signal_payload.get("item_id")
+            audio_end_ms = signal_payload.get("audio_end_ms")
+            content_index = signal_payload.get("content_index", 0)
+            if not isinstance(item_id, str) or not item_id or not isinstance(audio_end_ms, int | float):
+                raise DuplexCommandError(
+                    "conversation.item.truncate requires item_id and numeric audio_end_ms",
+                    code="bad_event",
+                    event_id=event_id,
+                )
+            return TruncateItem(
+                event_id=event_id,
+                item_id=item_id,
+                audio_end_ms=int(audio_end_ms),
+                content_index=int(content_index) if isinstance(content_index, int | float) else 0,
+            )
+        return SignalTurn(event_id=event_id, event=signal_event, signal_payload=signal_payload)
+
+    raise DuplexCommandError(f"Unknown duplex event type: {event_type}", code="unknown_event", event_id=event_id)
+
+
+__all__ = [
+    "REALTIME_INPUT_AUDIO_FORMATS",
+    "REALTIME_INPUT_HINT_KEYS",
+    "REALTIME_OUTPUT_AUDIO_FORMATS",
+    "RealtimeInputDefaults",
+    "apply_realtime_session_defaults",
+    "build_append_audio",
+    "copy_realtime_input_hints",
+    "duplex_response_format",
+    "input_audio_transcription_config",
+    "input_explicitly_non_speech",
+    "input_looks_like_speech",
+    "input_transcript_from_item",
+    "is_supported_realtime_input_format",
+    "json_safe_realtime_payload",
+    "normalize_conversation_item",
+    "parse_realtime_audio_format",
+    "realtime_audio_format_object",
+    "realtime_max_output_tokens",
+    "realtime_output_format",
+    "realtime_overlap_fields",
+    "text_chars_for_audio_ms_from_marks",
+    "translate_realtime_command",
+    "truncate_realtime_item_content",
+    "validate_conversation_item_audio_formats",
+    "validate_realtime_item_truncate",
+    "validate_realtime_response_audio_formats",
+    "validate_realtime_session_audio_formats",
+    "validate_realtime_video_frames",
+]
diff --git a/vllm_omni/engine/duplex/realtime_events.py b/vllm_omni/engine/duplex/realtime_events.py
new file mode 100644
index 00000000000..91359f297e5
--- /dev/null
+++ b/vllm_omni/engine/duplex/realtime_events.py
@@ -0,0 +1,1526 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Session-internal duplex events -> typed :class:`DuplexEvent` objects (stateful projection).
+
+This is the former ``entrypoints/duplex/realtime_output.py`` projector plus the
+projection-relevant fields of ``realtime_state.py``, now owned by the session
+runner through :class:`RealtimeProjectionState`. The projection consumes the
+state (response / item ids, content-part bookkeeping) when it *constructs*
+events; rendering an event to wire JSON (``event.to_realtime()``) is pure and
+lives on the event classes in ``vllm_omni.engine.duplex.events``.
+
+Besides the output projection (:func:`project_internal_event`) the state also
+carries the input-side bookkeeping the old input translator kept (input buffer
+flags, conversation items, response-id fallbacks); the ``resolve_*`` /
+``note_*`` helpers give the runner the same behaviour for the corresponding
+commands.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, cast
+from uuid import uuid4
+
+from vllm_omni.engine.duplex.audio import convert_output_audio
+from vllm_omni.engine.duplex.commands import (
+    AppendAudio,
+    CancelResponse,
+    ClearOutputAudio,
+    Commit,
+    CreateItem,
+    DeleteItem,
+    TruncateItem,
+)
+from vllm_omni.engine.duplex.events import (
+    AudioDelta,
+    AudioDone,
+    ContentPartAdded,
+    ContentPartDone,
+    DuplexEvent,
+    DuplexRawEvent,
+    FunctionCallArgumentsDelta,
+    FunctionCallArgumentsDone,
+    InputCleared,
+    InputCommitted,
+    InputTranscriptionCompleted,
+    ItemAdded,
+    ItemCreated,
+    ItemDeleted,
+    ItemDone,
+    ItemRetrieved,
+    ItemTruncated,
+    Listen,
+    OutputAudioCleared,
+    OutputItemAdded,
+    OutputItemDone,
+    RateLimitsUpdated,
+    ResponseCreated,
+    ResponseDone,
+    SessionClosed,
+    SessionCreated,
+    SessionReplaced,
+    SessionResumed,
+    SessionResyncRequired,
+    SessionUpdated,
+    Speak,
+    SpeechStarted,
+    SpeechStopped,
+    TextDelta,
+    TextDone,
+    TranscriptDelta,
+    TranscriptDone,
+    error_event,
+)
+from vllm_omni.engine.duplex.realtime_commands import (
+    RealtimeInputDefaults,
+    apply_realtime_session_defaults,
+    build_append_audio,
+    copy_realtime_input_hints,
+    input_looks_like_speech,
+    input_transcript_from_item,
+    parse_realtime_audio_format,
+    realtime_audio_format_object,
+    realtime_output_format,
+    truncate_realtime_item_content,
+    validate_realtime_item_truncate,
+)
+
+if TYPE_CHECKING:
+    # Runtime import pulls in the VAD backend; the projection only needs the type.
+    from vllm_omni.engine.duplex.turn_detection import TurnDetectionResult
+
+
+def _str_or_none(value: object) -> str | None:
+    return value if isinstance(value, str) and value else None
+
+
+def _int_or(value: object, default: int = 0) -> int:
+    return int(value) if isinstance(value, int | float) else default
+
+
+@dataclass(slots=True)
+class _ResponseProjection:
+    item_id: str
+    transcript_parts: list[str] = field(default_factory=list)
+    text_parts: list[str] = field(default_factory=list)
+    audio_duration_ms: int | None = None
+    audio_text_marks: list[dict[str, int]] = field(default_factory=list)
+    audio_delta_emitted: bool = False
+    audio_done_emitted: bool = False
+    audio_part_added: bool = False
+    audio_part_done: bool = False
+    text_part_added: bool = False
+    text_part_done: bool = False
+    output_text_done: bool = False
+    output_item_done: bool = False
+    conversation_item_done: bool = False
+    speak_emitted: bool = False
+    done_emitted: bool = False
+
+    @property
+    def transcript(self) -> str:
+        return "".join(self.transcript_parts)
+
+    @property
+    def text(self) -> str:
+        return "".join(self.text_parts)
+
+
+@dataclass(slots=True)
+class RealtimeProjectionState:
+    """Per-session Realtime projection state (lives on the engine-side runner)."""
+
+    session_id: str
+    model: str | None = None
+    default_payload: Mapping[str, object] | None = None
+    #: Wire defaults (input/output formats, rates, silence rms) declared by the session object.
+    defaults: RealtimeInputDefaults = field(default_factory=RealtimeInputDefaults)
+    #: The first ``session.created`` also emits ``session.updated`` (client sent session.update to open).
+    initial_session_update: bool = False
+    # ---- response / item projection ----
+    response_states: dict[str | int, _ResponseProjection] = field(default_factory=dict)
+    item_truncation_cursors: dict[str, tuple[int, int]] = field(default_factory=dict)
+    active_response_id: str | None = None
+    last_response_id: str | None = None
+    conversation_items: dict[str, dict[str, object]] = field(default_factory=dict)
+    last_conversation_item_id: str | None = None
+    pending_commit_item_ids: list[str] = field(default_factory=list)
+    # ---- input buffer projection (was on the input translator) ----
+    input_speech_started: bool = False
+    active_input_item_id: str | None = None
+    input_audio_buffer_has_audio: bool = False
+    input_audio_buffer_had_non_speech: bool = False
+    input_audio_buffer_transcript_parts: list[str] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if self.default_payload is not None:
+            self.apply_session_defaults(self.default_payload)
+
+    # ---- session defaults ----
+
+    def apply_session_defaults(self, session_payload: Mapping[str, object]) -> None:
+        self.defaults = apply_realtime_session_defaults(self.defaults, session_payload)
+
+    @property
+    def input_audio_format(self) -> str:
+        return self.defaults.input_audio_format
+
+    @property
+    def input_sample_rate_hz(self) -> int:
+        return self.defaults.input_sample_rate_hz
+
+    @property
+    def output_audio_format(self) -> str:
+        return self.defaults.output_audio_format
+
+    @property
+    def output_sample_rate_hz(self) -> int | None:
+        return self.defaults.output_sample_rate_hz
+
+    @property
+    def overlap_silence_rms(self) -> float:
+        return self.defaults.overlap_silence_rms
+
+
+# ---- response projection helpers ----
+
+
+def _response_state(
+    state: RealtimeProjectionState,
+    response_id: object,
+    *,
+    event: Mapping[str, object] | None = None,
+    create: bool = True,
+) -> _ResponseProjection | None:
+    if not (isinstance(response_id, str) and response_id):
+        # An event without a response id has no projection to attach to; a
+        # key derived from the transient event object would alias later
+        # anonymous events (and leak an entry per terminal).
+        return None
+    key = response_id
+    item_id = f"item_{response_id}"
+    projection = state.response_states.get(key)
+    if projection is None and create:
+        projection = _ResponseProjection(item_id=item_id)
+        state.response_states[key] = projection
+    return projection
+
+
+def response_is_done(state: RealtimeProjectionState, response_id: object) -> bool:
+    projection = _response_state(state, response_id, create=False)
+    return projection is not None and projection.done_emitted
+
+
+def _response_item_id(state: RealtimeProjectionState, response_id: object) -> str:
+    projection = _response_state(state, response_id)
+    if projection is not None:
+        return projection.item_id
+    return f"item_{uuid4().hex}"
+
+
+def _response_content_part(*, transcript: str = "") -> dict[str, object]:
+    return {"type": "audio", "transcript": transcript}
+
+
+def _response_text_content_part(*, text: str = "") -> dict[str, object]:
+    return {"type": "text", "text": text}
+
+
+def _response_item_content_part(
+    *,
+    transcript: str = "",
+    audio_duration_ms: int | None = None,
+    audio_text_marks: list[dict[str, int]] | None = None,
+) -> dict[str, object]:
+    part: dict[str, object] = {"type": "output_audio", "transcript": transcript}
+    if audio_duration_ms is not None:
+        part["audio_duration_ms"] = int(audio_duration_ms)
+    if audio_text_marks:
+        part["audio_text_marks"] = [dict(mark) for mark in audio_text_marks]
+    return part
+
+
+def _response_item_text_content_part(*, text: str = "") -> dict[str, object]:
+    return {"type": "output_text", "text": text}
+
+
+def _previous_item_id(state: RealtimeProjectionState, item_id: str) -> str | None:
+    previous: str | None = None
+    for known_id in state.conversation_items:
+        if known_id == item_id:
+            return previous
+        previous = known_id
+    if state.last_conversation_item_id == item_id:
+        return previous
+    return state.last_conversation_item_id
+
+
+def _conversation_item_added_events(state: RealtimeProjectionState, item: dict[str, object]) -> list[DuplexEvent]:
+    item_id = item.get("id")
+    explicit_previous_item_id = item.pop("_previous_item_id", None)
+    previous_item_id = (
+        explicit_previous_item_id if isinstance(explicit_previous_item_id, str) else state.last_conversation_item_id
+    )
+    if isinstance(item_id, str) and item_id:
+        state.last_conversation_item_id = item_id
+    return [
+        ItemAdded(previous_item_id=previous_item_id, item=item),
+        ItemCreated(previous_item_id=previous_item_id, item=item),
+    ]
+
+
+def _conversation_item_done_event(state: RealtimeProjectionState, item: dict[str, object]) -> ItemDone:
+    item_id = item.get("id")
+    previous_item_id = _previous_item_id(state, item_id) if isinstance(item_id, str) else None
+    if isinstance(item_id, str) and item_id:
+        state.conversation_items[item_id] = item
+        state.last_conversation_item_id = item_id
+    return ItemDone(previous_item_id=previous_item_id, item=item)
+
+
+def _remove_conversation_item(state: RealtimeProjectionState, item_id: str) -> bool:
+    removed = state.conversation_items.pop(item_id, None) is not None
+    if state.last_conversation_item_id == item_id:
+        remaining_ids = list(state.conversation_items)
+        state.last_conversation_item_id = remaining_ids[-1] if remaining_ids else None
+    state.item_truncation_cursors.pop(item_id, None)
+    return removed
+
+
+def _apply_pending_item_truncation(state: RealtimeProjectionState, item: dict[str, object]) -> None:
+    item_id = item.get("id")
+    if not isinstance(item_id, str) or not item_id:
+        return
+    cursor = state.item_truncation_cursors.get(item_id)
+    if cursor is None:
+        return
+    content_index, audio_end_ms = cursor
+    truncate_realtime_item_content(item, content_index=content_index, audio_end_ms=audio_end_ms)
+
+
+def _response_done_output_item(
+    state: RealtimeProjectionState, response_id: object, *, status: str
+) -> dict[str, object]:
+    item_id = _response_item_id(state, response_id)
+    projection = _response_state(state, response_id)
+    transcript = projection.transcript if projection is not None else ""
+    text = projection.text if projection is not None else ""
+    audio_duration_ms = projection.audio_duration_ms if projection is not None else None
+    audio_text_marks = projection.audio_text_marks if projection is not None else None
+    content: list[dict[str, object]] = []
+    if (projection is not None and projection.audio_part_added) or transcript or audio_duration_ms is not None:
+        content.append(
+            _response_item_content_part(
+                transcript=transcript,
+                audio_duration_ms=audio_duration_ms,
+                audio_text_marks=audio_text_marks,
+            )
+        )
+    if text:
+        content.append(_response_item_text_content_part(text=text))
+    item = {
+        "id": item_id,
+        "object": "realtime.item",
+        "type": "message",
+        "role": "assistant",
+        "status": status,
+        "content": content,
+    }
+    _apply_pending_item_truncation(state, item)
+    return item
+
+
+def _refresh_in_progress_response_item(state: RealtimeProjectionState, response_id: object) -> None:
+    if not isinstance(response_id, str) or not response_id:
+        return
+    item_id = _response_item_id(state, response_id)
+    item = state.conversation_items.get(item_id)
+    if not isinstance(item, dict):
+        return
+    content = item.get("content")
+    if not isinstance(content, list):
+        content = []
+        item["content"] = content
+    projection = _response_state(state, response_id)
+    if projection is None:
+        return
+    transcript = projection.transcript
+    audio_duration_ms = projection.audio_duration_ms
+    audio_text_marks = projection.audio_text_marks
+    has_audio = projection.audio_part_added or bool(transcript) or audio_duration_ms is not None
+    if has_audio:
+        audio_part = _response_item_content_part(
+            transcript=transcript,
+            audio_duration_ms=audio_duration_ms,
+            audio_text_marks=audio_text_marks,
+        )
+        if content and isinstance(content[0], dict) and content[0].get("type") in {"audio", "output_audio"}:
+            content[0] = audio_part
+        else:
+            content.insert(0, audio_part)
+    text = projection.text
+    if text:
+        text_index = (
+            1 if content and isinstance(content[0], dict) and content[0].get("type") in {"audio", "output_audio"} else 0
+        )
+        text_part = _response_item_text_content_part(text=text)
+        if (
+            len(content) > text_index
+            and isinstance(content[text_index], dict)
+            and content[text_index].get("type") in {"text", "output_text"}
+        ):
+            content[text_index] = text_part
+        else:
+            content.insert(text_index, text_part)
+    _apply_pending_item_truncation(state, item)
+
+
+def _append_response_transcript(state: RealtimeProjectionState, response_id: object, text: str) -> None:
+    projection = _response_state(state, response_id)
+    if projection is None or not text:
+        return
+    projection.transcript_parts.append(text)
+
+
+def _ensure_response_text_part_added(state: RealtimeProjectionState, response_id: object) -> list[DuplexEvent]:
+    projection = _response_state(state, response_id)
+    if projection is None or projection.text_part_added:
+        return []
+    projection.text_part_added = True
+    return [
+        ContentPartAdded(
+            response_id=_str_or_none(response_id),
+            item_id=_response_item_id(state, response_id),
+            content_index=1 if projection.audio_part_added else 0,
+            part=_response_text_content_part(),
+        )
+    ]
+
+
+def _ensure_response_audio_part_added(state: RealtimeProjectionState, response_id: object) -> list[DuplexEvent]:
+    projection = _response_state(state, response_id)
+    if projection is None or projection.audio_part_added:
+        return []
+    projection.audio_part_added = True
+    return [
+        ContentPartAdded(
+            response_id=_str_or_none(response_id),
+            item_id=_response_item_id(state, response_id),
+            part=_response_content_part(),
+        )
+    ]
+
+
+def _remember_response_audio_metadata(
+    state: RealtimeProjectionState, response_id: object, event: Mapping[str, object]
+) -> None:
+    projection = _response_state(state, response_id)
+    if projection is None:
+        return
+    duration = event.get("audio_duration_ms")
+    playback = event.get("playback")
+    if not isinstance(duration, int | float) and isinstance(playback, dict):
+        duration = playback.get("sent_ms") or playback.get("generated_ms")
+    if isinstance(duration, int | float):
+        projection.audio_duration_ms = max(projection.audio_duration_ms or 0, int(duration))
+    marks = event.get("audio_text_marks")
+    if not isinstance(marks, list):
+        return
+    clean_marks: list[dict[str, int]] = []
+    for mark in marks:
+        if not isinstance(mark, dict):
+            continue
+        text_chars = mark.get("text_chars")
+        audio_end_ms = mark.get("audio_end_ms", mark.get("audio_ms"))
+        if not isinstance(text_chars, int | float) or not isinstance(audio_end_ms, int | float):
+            continue
+        clean_marks.append({"text_chars": max(0, int(text_chars)), "audio_end_ms": max(0, int(audio_end_ms))})
+    if clean_marks:
+        merged = list(projection.audio_text_marks)
+        merged.extend(clean_marks)
+        deduped: dict[tuple[int, int], dict[str, int]] = {}
+        for mark in merged:
+            deduped[(int(mark["audio_end_ms"]), int(mark["text_chars"]))] = mark
+        projection.audio_text_marks = sorted(
+            deduped.values(), key=lambda mark: (mark["audio_end_ms"], mark["text_chars"])
+        )
+
+
+def _response_created_event(event: Mapping[str, object]) -> ResponseCreated:
+    response_id = event.get("response_id")
+    metadata = event.get("metadata")
+    if not isinstance(metadata, dict):
+        metadata = {}
+    metadata = {**metadata, "duplex_event": dict(event)}
+    return ResponseCreated(
+        response_id=_str_or_none(response_id),
+        response={
+            "id": response_id,
+            "object": "realtime.response",
+            "status": "in_progress",
+            "status_details": None,
+            "output": [],
+            "modalities": event.get("modalities") or ["audio", "text"],
+            "metadata": metadata,
+        },
+    )
+
+
+def _response_speak_metadata(event: Mapping[str, object]) -> dict[str, object]:
+    return {key: event[key] for key in ("session_id", "epoch", "model_speak") if key in event}
+
+
+def _realtime_audio_delta_events(
+    state: RealtimeProjectionState,
+    event: Mapping[str, object],
+    response_id: object,
+    audio: str,
+) -> list[DuplexEvent]:
+    item_id = _response_item_id(state, response_id)
+    fmt, format_rate = parse_realtime_audio_format(event.get("format", "wav"))
+    source_fmt = realtime_output_format(fmt)
+    source_sample_rate_hz = event.get("sample_rate_hz") or format_rate
+    target_sample_rate_hz = (
+        state.output_sample_rate_hz if state.output_audio_format in {"g711_ulaw", "g711_alaw"} else None
+    )
+    audio, fmt, converted_sample_rate_hz = convert_output_audio(
+        audio,
+        source_fmt=source_fmt,
+        target_fmt=state.output_audio_format,
+        source_sample_rate_hz=(int(source_sample_rate_hz) if isinstance(source_sample_rate_hz, int | float) else None),
+        target_sample_rate_hz=target_sample_rate_hz,
+    )
+    sample_rate_hz = (
+        converted_sample_rate_hz
+        if fmt in {"g711_ulaw", "g711_alaw"}
+        else event.get("sample_rate_hz") or format_rate or state.output_sample_rate_hz
+    )
+    metadata: dict[str, object] = {}
+    for key in ("session_id", "epoch", "model_speak", "end_of_turn", "playback", "vllm_omni"):
+        if key in event:
+            metadata[key] = event[key]
+    duration_ms = event.get("audio_duration_ms")
+    if isinstance(duration_ms, int | float):
+        metadata["audio_duration_ms"] = int(duration_ms)
+    marks = event.get("audio_text_marks")
+    if isinstance(marks, list):
+        metadata["audio_text_marks"] = marks
+    projection = _response_state(state, response_id)
+    if projection is not None:
+        projection.audio_delta_emitted = True
+        _remember_response_audio_metadata(state, response_id, event)
+    events: list[DuplexEvent] = []
+    if projection is not None and not projection.speak_emitted and metadata.get("model_speak") is True:
+        projection.speak_emitted = True
+        events.append(
+            Speak(response_id=_str_or_none(response_id), item_id=item_id, metadata=_response_speak_metadata(event))
+        )
+    events.append(
+        AudioDelta(
+            response_id=_str_or_none(response_id),
+            item_id=item_id,
+            delta=str(audio),
+            format=str(fmt),
+            sample_rate_hz=int(sample_rate_hz) if isinstance(sample_rate_hz, int | float) else None,
+            metadata=metadata or None,
+        )
+    )
+    return events
+
+
+def _realtime_audio_done_events(
+    state: RealtimeProjectionState, event: Mapping[str, object], response_id: object
+) -> list[DuplexEvent]:
+    item_id = _response_item_id(state, response_id)
+    projection = _response_state(state, response_id, event=event)
+    transcript = projection.transcript if projection is not None else ""
+    events: list[DuplexEvent] = []
+    if (
+        isinstance(response_id, str)
+        and projection is not None
+        and not projection.audio_delta_emitted
+        and not transcript
+    ):
+        return events
+    if projection is None or not projection.audio_done_emitted:
+        if projection is not None:
+            projection.audio_done_emitted = True
+        events.append(AudioDone(response_id=_str_or_none(response_id), item_id=item_id))
+        if transcript:
+            events.append(TranscriptDone(response_id=_str_or_none(response_id), item_id=item_id, transcript=transcript))
+    return events
+
+
+def _realtime_response_done_event(
+    state: RealtimeProjectionState,
+    event: Mapping[str, object],
+    *,
+    projection: _ResponseProjection | None = None,
+    status: str = "completed",
+    status_details: dict[str, object] | None = None,
+) -> ResponseDone | None:
+    response_id = event.get("response_id")
+    if projection is None:
+        projection = _response_state(state, response_id, event=event)
+    if projection is not None:
+        if projection.done_emitted:
+            return None
+        projection.done_emitted = True
+    return ResponseDone(
+        response_id=_str_or_none(response_id),
+        response={
+            "id": response_id,
+            "object": "realtime.response",
+            "status": status,
+            "status_details": status_details,
+            "output": [_response_done_output_item(state, response_id, status=status)],
+            "metadata": dict(event),
+        },
+    )
+
+
+def _realtime_response_terminal_events(
+    state: RealtimeProjectionState,
+    event: Mapping[str, object],
+    response_id: object,
+    *,
+    status: str = "completed",
+    status_details: dict[str, object] | None = None,
+) -> list[DuplexEvent]:
+    item_id = _response_item_id(state, response_id)
+    projection = _response_state(state, response_id, event=event)
+    transcript = projection.transcript if projection is not None else ""
+    rid = _str_or_none(response_id)
+    events: list[DuplexEvent] = []
+    if projection is not None and projection.audio_part_added and not projection.audio_part_done:
+        projection.audio_part_done = True
+        events.append(
+            ContentPartDone(response_id=rid, item_id=item_id, part=_response_content_part(transcript=transcript))
+        )
+    if projection is not None and projection.text_parts and not projection.output_text_done:
+        projection.output_text_done = True
+        events.append(
+            TextDone(
+                response_id=rid,
+                item_id=item_id,
+                content_index=1 if projection.audio_part_added else 0,
+                text=projection.text,
+            )
+        )
+    if projection is not None and projection.text_parts and not projection.text_part_done:
+        projection.text_part_done = True
+        events.append(
+            ContentPartDone(
+                response_id=rid,
+                item_id=item_id,
+                content_index=1 if projection.audio_part_added else 0,
+                part=_response_text_content_part(text=projection.text),
+            )
+        )
+    if projection is None or not projection.output_item_done:
+        if projection is not None:
+            projection.output_item_done = True
+        item = _response_done_output_item(state, response_id, status=status)
+        events.append(OutputItemDone(response_id=rid, item=item))
+        if projection is None or not projection.conversation_item_done:
+            if projection is not None:
+                projection.conversation_item_done = True
+            events.append(_conversation_item_done_event(state, item))
+    done_event = _realtime_response_done_event(
+        state,
+        {**event, "response_id": response_id},
+        projection=projection,
+        status=status,
+        status_details=status_details,
+    )
+    if done_event is not None:
+        events.append(done_event)
+        # vLLM-Omni does not expose a Realtime-specific quota budget; emit the
+        # terminal event with an empty list so clients that sequence on it work.
+        events.append(RateLimitsUpdated())
+        if isinstance(response_id, str) and response_id == state.active_response_id:
+            state.active_response_id = None
+    return events
+
+
+def _user_item_content_from_duplex_message(message: object) -> list[dict[str, object]]:
+    if not isinstance(message, dict):
+        return [{"type": "input_audio", "transcript": ""}]
+    message_transcript = message.get("transcript")
+    content = message.get("content")
+    if isinstance(content, str):
+        return [{"type": "input_text", "text": content}]
+    if not isinstance(content, list):
+        return [
+            {"type": "input_audio", "transcript": message_transcript if isinstance(message_transcript, str) else ""}
+        ]
+    parts: list[dict[str, object]] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        part_type = part.get("type")
+        if part_type in {"text", "input_text"} and isinstance(part.get("text"), str):
+            parts.append({"type": "input_text", "text": part["text"]})
+            continue
+        if part_type == "audio_url":
+            transcript = (
+                part.get("transcript")
+                if isinstance(part.get("transcript"), str)
+                else message_transcript
+                if isinstance(message_transcript, str)
+                else ""
+            )
+            parts.append({"type": "input_audio", "transcript": transcript})
+            continue
+        if part_type in {"audio", "input_audio"}:
+            transcript = part.get("transcript") if isinstance(part.get("transcript"), str) else ""
+            parts.append({"type": "input_audio", "transcript": transcript})
+    return parts or [{"type": "input_audio", "transcript": ""}]
+
+
+def _input_audio_transcription_completed_event(
+    item_id: str, item: Mapping[str, object]
+) -> InputTranscriptionCompleted | None:
+    content = item.get("content")
+    if not isinstance(content, list):
+        return None
+    for index, part in enumerate(content):
+        if not isinstance(part, dict) or part.get("type") != "input_audio":
+            continue
+        transcript = part.get("transcript")
+        if isinstance(transcript, str) and transcript:
+            return InputTranscriptionCompleted(item_id=item_id, content_index=index, transcript=transcript)
+    return None
+
+
+def _pop_pending_commit_item_id(state: RealtimeProjectionState) -> str:
+    if state.pending_commit_item_ids:
+        return state.pending_commit_item_ids.pop(0)
+    return f"item_{uuid4().hex}"
+
+
+def realtime_session_payload(state: RealtimeProjectionState, session: object) -> dict[str, object]:
+    """Fill the Realtime ``session`` object defaults for session.created/updated."""
+    payload = dict(session) if isinstance(session, Mapping) else {}
+    payload.setdefault("object", "realtime.session")
+    payload.setdefault("type", "realtime")
+    payload.setdefault("id", payload.get("id") or state.session_id)
+    payload.setdefault("model", payload.get("model") or state.model)
+    payload.setdefault("input_audio_format", state.input_audio_format)
+    payload.setdefault("output_audio_format", state.output_audio_format)
+    payload.setdefault("modalities", payload.get("modalities") or ["text", "audio"])
+    payload.setdefault("output_modalities", payload.get("output_modalities") or payload.get("modalities"))
+    payload.setdefault(
+        "audio",
+        {
+            "input": {
+                "format": realtime_audio_format_object(
+                    state.input_audio_format, sample_rate_hz=state.input_sample_rate_hz
+                ),
+                "sample_rate_hz": state.input_sample_rate_hz,
+            },
+            "output": {
+                "format": realtime_audio_format_object(
+                    state.output_audio_format, sample_rate_hz=state.output_sample_rate_hz
+                ),
+            },
+        },
+    )
+    payload.setdefault("turn_detection", payload.get("turn_detection"))
+    payload.setdefault("input_audio_transcription", payload.get("input_audio_transcription"))
+    payload.setdefault("tracing", payload.get("tracing"))
+    return payload
+
+
+# ---- main projection ----
+
+
+def project_internal_event(state: RealtimeProjectionState, event: Mapping[str, object]) -> list[DuplexEvent]:
+    """Project one session-internal event onto 0..n typed public events."""
+    return _project(state, dict(event))
+
+
+def _project(state: RealtimeProjectionState, event: dict[str, object]) -> list[DuplexEvent]:
+    event_type = event.get("type")
+    if event_type == "session.created":
+        session = realtime_session_payload(state, event.get("session"))
+        events: list[DuplexEvent] = [
+            SessionCreated(
+                session=session,
+                attachment_generation=(
+                    cast("int", event["attachment_generation"])
+                    if isinstance(event.get("attachment_generation"), int)
+                    else None
+                ),
+                resume_token=_str_or_none(event.get("resume_token")),
+            )
+        ]
+        if state.initial_session_update:
+            events.append(SessionUpdated(session=session))
+            state.initial_session_update = False
+        return events
+    if event_type == "session.updated":
+        return [SessionUpdated(session=realtime_session_payload(state, event.get("session")))]
+    if event_type == "session.resumed":
+        return [
+            SessionResumed(
+                session=realtime_session_payload(state, event.get("session")),
+                attachment_generation=(
+                    cast("int", event["attachment_generation"])
+                    if isinstance(event.get("attachment_generation"), int)
+                    else None
+                ),
+                resume_token=_str_or_none(event.get("resume_token")),
+            )
+        ]
+    if event_type == "session.replaced":
+        return [SessionReplaced(attachment_generation=_int_or(event.get("attachment_generation")))]
+    if event_type == "session.resync_required":
+        return [SessionResyncRequired(reason=str(event.get("reason") or "journal_gap"))]
+    if event_type == "session.closed":
+        return [SessionClosed(reason=str(event.get("reason") or "closed"), details=event)]
+    if event_type == "response.created":
+        response_id = event.get("response_id")
+        if isinstance(response_id, str) and response_id:
+            state.active_response_id = response_id
+            state.last_response_id = response_id
+        item_id = _response_item_id(state, response_id)
+        modalities = event.get("modalities")
+        has_audio_modality = not isinstance(modalities, list) or "audio" in modalities
+        item = {
+            "id": item_id,
+            "object": "realtime.item",
+            "type": "message",
+            "role": "assistant",
+            "status": "in_progress",
+            "content": [],
+        }
+        state.conversation_items[item_id] = item
+        events = [
+            _response_created_event(event),
+            *_conversation_item_added_events(state, item),
+            OutputItemAdded(response_id=_str_or_none(response_id), item=item),
+        ]
+        if has_audio_modality:
+            events.extend(_ensure_response_audio_part_added(state, response_id))
+        return events
+    if event_type == "response.listen":
+        return [Listen(response_id=_str_or_none(event.get("response_id")), details=event)]
+    if event_type == "response.speak":
+        response_id = event.get("response_id")
+        projection = _response_state(state, response_id)
+        if projection is not None:
+            if projection.speak_emitted:
+                return []
+            projection.speak_emitted = True
+        return [
+            Speak(
+                response_id=_str_or_none(response_id),
+                item_id=_response_item_id(state, response_id),
+                metadata=_response_speak_metadata(event),
+            )
+        ]
+    if event_type == "response.output_audio.delta":
+        response_id = event.get("response_id")
+        audio = event.get("audio", "")
+        events = []
+        if isinstance(audio, str) and audio:
+            events.extend(_ensure_response_audio_part_added(state, response_id))
+            events.extend(_realtime_audio_delta_events(state, event, response_id, audio))
+            _refresh_in_progress_response_item(state, response_id)
+        text = event.get("text")
+        has_text = isinstance(text, str) and bool(text)
+        if has_text:
+            _append_response_transcript(state, response_id, cast("str", text))
+            _refresh_in_progress_response_item(state, response_id)
+        # Keep the audio.delta + transcript.delta pair invariant even for
+        # text-less units so clients that treat the pair as unit-complete work.
+        if has_text or (isinstance(audio, str) and bool(audio)):
+            events.append(
+                TranscriptDelta(
+                    response_id=_str_or_none(response_id),
+                    item_id=_response_item_id(state, response_id),
+                    delta=cast("str", text) if has_text else "",
+                )
+            )
+        if event.get("end_of_turn") is True:
+            events.extend(_realtime_audio_done_events(state, event, response_id))
+            events.extend(
+                _realtime_response_terminal_events(
+                    state,
+                    event,
+                    response_id,
+                    status="completed",
+                    status_details={"type": "completed", "reason": event.get("finish_reason") or "stop"},
+                )
+            )
+        return events
+    if event_type == "response.text.delta":
+        response_id = event.get("response_id")
+        text = event.get("delta", "")
+        projection = _response_state(state, response_id)
+        if projection is not None and isinstance(text, str) and text:
+            projection.text_parts.append(text)
+            _refresh_in_progress_response_item(state, response_id)
+        events = _ensure_response_text_part_added(state, response_id)
+        events.append(
+            TextDelta(
+                response_id=_str_or_none(response_id),
+                item_id=_response_item_id(state, response_id),
+                content_index=1 if projection is not None and projection.audio_part_added else 0,
+                delta=str(text) if isinstance(text, str) else "",
+            )
+        )
+        return events
+    if event_type == "response.done":
+        response_id = event.get("response_id")
+        status = cast("str", event.get("status")) if isinstance(event.get("status"), str) else "completed"
+        status_details = (
+            cast("dict[str, object]", event.get("status_details"))
+            if isinstance(event.get("status_details"), dict)
+            else None
+        )
+        return [
+            *_realtime_audio_done_events(state, event, response_id),
+            *_realtime_response_terminal_events(
+                state, event, response_id, status=status, status_details=status_details
+            ),
+        ]
+    if event_type == "input.committed":
+        event_item_id = event.get("realtime_item_id")
+        item_id = (
+            event_item_id if isinstance(event_item_id, str) and event_item_id else _pop_pending_commit_item_id(state)
+        )
+        item = state.conversation_items.get(item_id)
+        events = []
+        if item is None:
+            message = event.get("message")
+            no_response = event.get("no_response") is True
+            is_speech = event.get("is_speech")
+            item = {
+                "id": item_id,
+                "object": "realtime.item",
+                "type": "message",
+                "role": "user",
+                "status": "completed",
+                "content": (
+                    [{"type": "input_audio", "transcript": "", "is_speech": False}]
+                    if no_response and is_speech is False
+                    else _user_item_content_from_duplex_message(message)
+                ),
+            }
+            state.conversation_items[item_id] = item
+            events.extend(_conversation_item_added_events(state, item))
+        item["status"] = "completed"
+        events.append(
+            InputCommitted(previous_item_id=_previous_item_id(state, item_id), item_id=item_id, details=event)
+        )
+        transcription_event = _input_audio_transcription_completed_event(item_id, item)
+        if transcription_event is not None:
+            events.append(transcription_event)
+        events.append(_conversation_item_done_event(state, item))
+        return events
+    if event_type == "input.cancelled":
+        return [InputCleared()]
+    if event_type == "audio.cancelled":
+        response_id = event.get("response_id")
+        events = []
+        if event.get("reason") == "output_audio_buffer_clear":
+            if not isinstance(response_id, str) or not response_id:
+                response_id = state.active_response_id or state.last_response_id
+            events.append(OutputAudioCleared(response_id=_str_or_none(response_id)))
+            if not isinstance(response_id, str) or not response_id:
+                return events
+        elif not isinstance(response_id, str) or not response_id:
+            response_id = state.active_response_id
+        if not isinstance(response_id, str) or not response_id:
+            return events
+        if response_is_done(state, response_id):
+            return events
+        committed_ms = event.get("committed_ms")
+        if isinstance(committed_ms, int | float):
+            item_id = _response_item_id(state, response_id)
+            committed_audio_ms = max(0, int(committed_ms))
+            state.item_truncation_cursors[item_id] = (0, committed_audio_ms)
+            item = state.conversation_items.get(item_id)
+            if item is not None:
+                truncate_realtime_item_content(item, content_index=0, audio_end_ms=committed_audio_ms)
+        events.extend(_realtime_audio_done_events(state, event, response_id))
+        events.extend(
+            _realtime_response_terminal_events(
+                state,
+                event,
+                response_id,
+                status="cancelled",
+                status_details={"type": "cancelled", "reason": event.get("reason") or "client_cancelled"},
+            )
+        )
+        if isinstance(response_id, str) and response_id == state.active_response_id:
+            state.active_response_id = None
+        return events
+    if event_type == "conversation.item.created":
+        item = event.get("item")
+        if isinstance(item, dict) and isinstance(item.get("id"), str):
+            item_id = str(item["id"])
+            already_known = item_id in state.conversation_items
+            state.conversation_items[item_id] = item
+            if already_known:
+                if item.get("status") == "completed":
+                    return [_conversation_item_done_event(state, item)]
+                return []
+            events = _conversation_item_added_events(state, item)
+            if item.get("status") == "completed":
+                events.append(_conversation_item_done_event(state, item))
+            return events
+        return [ItemCreated(item=item if isinstance(item, Mapping) else {})]
+    if event_type == "conversation.item.deleted":
+        item_id = event.get("item_id")
+        if isinstance(item_id, str):
+            _remove_conversation_item(state, item_id)
+        return [ItemDeleted(item_id=_str_or_none(item_id), details=event)]
+    if event_type == "conversation.item.truncated":
+        item_id = event.get("item_id")
+        audio_end_ms = event.get("audio_end_ms")
+        content_index = event.get("content_index", 0)
+        if isinstance(item_id, str):
+            item = state.conversation_items.get(item_id)
+            if item is not None:
+                truncate_realtime_item_content(
+                    item,
+                    content_index=_int_or(content_index),
+                    audio_end_ms=_int_or(audio_end_ms),
+                )
+        return [
+            ItemTruncated(
+                item_id=_str_or_none(item_id),
+                content_index=_int_or(content_index),
+                audio_end_ms=_int_or(audio_end_ms),
+                details=event,
+            )
+        ]
+    if event_type == "conversation.item.retrieved":
+        item = event.get("item")
+        return [ItemRetrieved(item=item if isinstance(item, Mapping) else {})]
+    if event_type == "response.output_item.done":
+        response_id = event.get("response_id")
+        return _realtime_response_terminal_events(
+            state,
+            event,
+            response_id,
+            status="completed",
+            status_details={"type": "completed", "reason": event.get("finish_reason") or "stop"},
+        )
+    if event_type == "function_call.done":
+        return _function_call_done_events(state, event)
+    if event_type == "input_audio_buffer.speech_started":
+        return [
+            SpeechStarted(
+                audio_start_ms=_int_or(event.get("audio_start_ms")), item_id=_str_or_none(event.get("item_id"))
+            )
+        ]
+    if event_type == "input_audio_buffer.speech_stopped":
+        return [
+            SpeechStopped(audio_end_ms=_int_or(event.get("audio_end_ms")), item_id=_str_or_none(event.get("item_id")))
+        ]
+    return [DuplexRawEvent(internal_type=str(event_type), details=event)]
+
+
+def _function_call_done_events(state: RealtimeProjectionState, event: dict[str, object]) -> list[DuplexEvent]:
+    call_id = event.get("call_id")
+    name = event.get("name")
+    arguments = event.get("arguments", "")
+    if not isinstance(call_id, str) or not call_id or not isinstance(name, str) or not name:
+        return [DuplexRawEvent(internal_type="function_call.done", details=event)]
+    if not isinstance(arguments, str):
+        arguments = str(arguments)
+    response_id = f"resp_{uuid4().hex}"
+    item_id = f"item_{uuid4().hex}"
+    item = {
+        "id": item_id,
+        "object": "realtime.item",
+        "type": "function_call",
+        "status": "completed",
+        "name": name,
+        "call_id": call_id,
+        "arguments": arguments,
+    }
+    state.conversation_items[item_id] = item
+    response = {
+        "id": response_id,
+        "object": "realtime.response",
+        "status": "completed",
+        "status_details": {"type": "completed", "reason": "completed"},
+        "output": [dict(item)],
+        "metadata": {},
+    }
+    return [
+        ResponseCreated(response_id=response_id, response={**response, "status": "in_progress", "output": []}),
+        *_conversation_item_added_events(state, item),
+        OutputItemAdded(response_id=response_id, item=dict(item)),
+        FunctionCallArgumentsDelta(response_id=response_id, item_id=item_id, call_id=call_id, delta=arguments),
+        FunctionCallArgumentsDone(response_id=response_id, item_id=item_id, call_id=call_id, arguments=arguments),
+        OutputItemDone(response_id=response_id, item=dict(item)),
+        _conversation_item_done_event(state, item),
+        ResponseDone(response_id=response_id, response=response),
+    ]
+
+
+# ---- input-side helpers for the runner (were on the input translator) ----
+
+
+def register_user_item(
+    state: RealtimeProjectionState,
+    item: Mapping[str, object],
+    *,
+    previous_item_id: str | None = None,
+) -> list[DuplexEvent]:
+    """Record a client-created user message item and return its ack events.
+
+    Replaces the old translator's ``_send_realtime_input_ack``: call it when
+    handling a ``CreateItem`` whose item role is ``user`` (before the internal
+    ``conversation.item.created`` is emitted, which then projects to ``done``).
+    """
+    normalized = dict(item)
+    if isinstance(previous_item_id, str):
+        normalized["_previous_item_id"] = previous_item_id
+    if normalized.get("role") != "user":
+        return []
+    state.conversation_items[str(normalized["id"])] = normalized
+    return _conversation_item_added_events(state, normalized)
+
+
+def retrieve_item_events(state: RealtimeProjectionState, payload: Mapping[str, object]) -> list[DuplexEvent]:
+    """Answer ``conversation.item.retrieve`` from the projected conversation items."""
+    event_id = payload.get("event_id")
+    item_id = payload.get("item_id")
+    if not isinstance(item_id, str) or not item_id:
+        return [error_event("missing_item_id", "conversation.item.retrieve requires item_id", event_id=event_id)]
+    item = state.conversation_items.get(item_id)
+    if item is None:
+        return [error_event("item_not_found", f"Conversation item not found: {item_id}", event_id=event_id)]
+    return [ItemRetrieved(item=item)]
+
+
+def emit_input_speech_started(state: RealtimeProjectionState, audio_start_ms: object = 0) -> list[DuplexEvent]:
+    if state.input_speech_started:
+        return []
+    state.input_speech_started = True
+    if state.active_input_item_id is None:
+        state.active_input_item_id = f"item_{uuid4().hex}"
+    return [SpeechStarted(audio_start_ms=_int_or(audio_start_ms), item_id=state.active_input_item_id)]
+
+
+def emit_input_speech_stopped(
+    state: RealtimeProjectionState, *, item_id: str, audio_end_ms: object = 0
+) -> list[DuplexEvent]:
+    if not state.input_speech_started:
+        return []
+    state.input_speech_started = False
+    return [SpeechStopped(audio_end_ms=_int_or(audio_end_ms), item_id=item_id)]
+
+
+def _remember_input_transcript_hint(state: RealtimeProjectionState, event: Mapping[str, object]) -> None:
+    transcript = event.get("transcript")
+    if not isinstance(transcript, str):
+        transcript = event.get("text") if isinstance(event.get("text"), str) else None
+    if not isinstance(transcript, str):
+        hints = event.get("hints")
+        if isinstance(hints, dict):
+            transcript = hints.get("transcript")
+            if not isinstance(transcript, str):
+                transcript = hints.get("text") if isinstance(hints.get("text"), str) else None
+    if isinstance(transcript, str) and transcript:
+        parts = state.input_audio_buffer_transcript_parts
+        if parts and parts[-1] == transcript:
+            return
+        parts.append(transcript)
+
+
+def _consume_input_transcript_hint(state: RealtimeProjectionState) -> str:
+    transcript = "".join(state.input_audio_buffer_transcript_parts).strip()
+    state.input_audio_buffer_transcript_parts.clear()
+    return transcript
+
+
+def note_input_append(
+    state: RealtimeProjectionState,
+    payload: dict[str, object],
+    *,
+    vad_result: TurnDetectionResult | None = None,
+) -> list[DuplexEvent]:
+    """Update the input-buffer projection for one appended chunk; returns typed events.
+
+    ``payload`` is the internal ``input_audio_buffer.append`` dictionary
+    (``AppendAudio.payload()``), optionally after ``apply_turn_detection_result``;
+    ``vad_result`` is the ``TurnDetectionResult`` when server VAD is active. The
+    returned events are ``input_audio_buffer.speech_started`` /
+    ``speech_stopped`` exactly as the old translator produced them.
+    """
+    audio = payload.get("audio")
+    looks_like_speech = bool(vad_result.is_speech) if vad_result is not None else payload.get("is_speech") is not False
+    has_audio = isinstance(audio, str) and bool(audio)
+    state.input_audio_buffer_has_audio = state.input_audio_buffer_has_audio or (looks_like_speech and has_audio)
+    state.input_audio_buffer_had_non_speech = state.input_audio_buffer_had_non_speech or (
+        not looks_like_speech and has_audio
+    )
+    events: list[DuplexEvent] = []
+    stop_ms: object = payload.get("audio_end_ms", payload.get("audio_ms", 0))
+    if vad_result is not None:
+        if vad_result.speech_stopped and vad_result.audio_end_ms is not None:
+            stop_ms = vad_result.audio_end_ms
+        if vad_result.speech_stopped and vad_result.speech_active:
+            events.extend(
+                emit_input_speech_stopped(
+                    state,
+                    item_id=state.active_input_item_id or f"item_{uuid4().hex}",
+                    audio_end_ms=stop_ms,
+                )
+            )
+        if vad_result.speech_started:
+            start_ms = (
+                vad_result.audio_start_ms if vad_result.audio_start_ms is not None else payload.get("audio_start_ms", 0)
+            )
+            events.extend(emit_input_speech_started(state, start_ms))
+        if vad_result.speech_stopped and not vad_result.speech_active:
+            events.extend(
+                emit_input_speech_stopped(
+                    state,
+                    item_id=state.active_input_item_id or f"item_{uuid4().hex}",
+                    audio_end_ms=stop_ms,
+                )
+            )
+    elif looks_like_speech:
+        events.extend(emit_input_speech_started(state, payload.get("audio_start_ms", 0)))
+    if looks_like_speech:
+        _remember_input_transcript_hint(state, payload)
+    return events
+
+
+def discard_pending_input_audio(state: RealtimeProjectionState, audio_end_ms: int | None = None) -> list[DuplexEvent]:
+    """Drop Realtime input-buffer state that was consumed as overlap (returns typed events)."""
+    events: list[DuplexEvent] = []
+    if state.input_speech_started and state.active_input_item_id is not None:
+        events.append(SpeechStopped(audio_end_ms=max(0, int(audio_end_ms or 0)), item_id=state.active_input_item_id))
+    state.input_speech_started = False
+    state.active_input_item_id = None
+    state.input_audio_buffer_has_audio = False
+    state.input_audio_buffer_had_non_speech = False
+    state.input_audio_buffer_transcript_parts.clear()
+    return events
+
+
+def clear_input_buffer(state: RealtimeProjectionState) -> None:
+    """Input-buffer projection reset for ``input_audio_buffer.clear``."""
+    state.input_speech_started = False
+    state.active_input_item_id = None
+    state.input_audio_buffer_has_audio = False
+    state.input_audio_buffer_had_non_speech = False
+    state.input_audio_buffer_transcript_parts.clear()
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedCommit:
+    """What a ``Commit`` means given the projected input buffer."""
+
+    #: Internal ``input_audio_buffer.commit`` payload to run, or None when rejected.
+    payload: dict[str, object] | None
+    #: Events to emit before running (speech_stopped) or instead (error).
+    events: list[DuplexEvent]
+    #: True when the VAD detector should be reset.
+    reset_vad: bool = False
+
+
+def resolve_commit(state: RealtimeProjectionState, command: Commit) -> ResolvedCommit:
+    """Apply the old translator's commit rules (empty buffer, non-speech commit, item id)."""
+    if command.realtime_item_id is None and not state.input_audio_buffer_has_audio:
+        if state.input_audio_buffer_had_non_speech:
+            state.input_audio_buffer_had_non_speech = False
+            state.active_input_item_id = None
+            payload: dict[str, object] = {
+                "type": "input_audio_buffer.commit",
+                "final": command.final,
+                "response_create": False,
+                "is_speech": False,
+            }
+            if command.event_id is not None:
+                payload["realtime_event_id"] = command.event_id
+            return ResolvedCommit(payload=payload, events=[], reset_vad=True)
+        return ResolvedCommit(
+            payload=None,
+            events=[
+                error_event(
+                    "input_audio_buffer_empty",
+                    "input_audio_buffer.commit requires a non-empty input audio buffer",
+                    event_id=command.event_id,
+                )
+            ],
+        )
+    item_id = command.realtime_item_id or state.active_input_item_id or f"item_{uuid4().hex}"
+    state.pending_commit_item_ids.append(item_id)
+    events = emit_input_speech_stopped(state, item_id=item_id, audio_end_ms=0)
+    transcript = _consume_input_transcript_hint(state)
+    state.active_input_item_id = None
+    state.input_audio_buffer_has_audio = False
+    state.input_audio_buffer_had_non_speech = False
+    payload = {
+        "type": "input_audio_buffer.commit",
+        "final": command.final,
+        "realtime_item_id": item_id,
+        "response_create": bool(command.create_response) if command.create_response is not None else False,
+    }
+    if command.is_speech is not None:
+        payload["is_speech"] = command.is_speech
+    if transcript:
+        payload["transcript"] = transcript
+    if command.event_id is not None:
+        payload["realtime_event_id"] = command.event_id
+    return ResolvedCommit(payload=payload, events=events, reset_vad=True)
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedControl:
+    """Result of resolving a cancel/clear/delete/truncate against the projection."""
+
+    #: Internal payload(s) to run in order (empty when nothing to do).
+    payloads: list[dict[str, object]]
+    #: Events to emit instead (already-done response ack, errors).
+    events: list[DuplexEvent]
+
+
+def resolve_cancel_response(state: RealtimeProjectionState, command: CancelResponse) -> ResolvedControl:
+    payload: dict[str, object] = {"type": "response.cancel", "reason": "response.cancel"}
+    response_id = command.response_id or state.active_response_id or state.last_response_id
+    if response_is_done(state, response_id):
+        return ResolvedControl(
+            payloads=[],
+            events=[
+                error_event(
+                    "response_not_active", f"Response is already complete: {response_id}", event_id=command.event_id
+                )
+            ],
+        )
+    if isinstance(response_id, str) and response_id:
+        payload["response_id"] = response_id
+    if command.event_id is not None:
+        payload["realtime_event_id"] = command.event_id
+    return ResolvedControl(payloads=[payload], events=[])
+
+
+def resolve_clear_output_audio(state: RealtimeProjectionState, command: ClearOutputAudio) -> ResolvedControl:
+    payload: dict[str, object] = {"type": "output_audio_buffer.clear", "reason": "output_audio_buffer.clear"}
+    response_id = command.response_id or state.active_response_id or state.last_response_id
+    if response_is_done(state, response_id):
+        return ResolvedControl(payloads=[], events=[OutputAudioCleared(response_id=_str_or_none(response_id))])
+    if isinstance(response_id, str) and response_id:
+        payload["response_id"] = response_id
+    if command.event_id is not None:
+        payload["realtime_event_id"] = command.event_id
+    return ResolvedControl(payloads=[payload], events=[])
+
+
+def resolve_delete_item(state: RealtimeProjectionState, command: DeleteItem) -> ResolvedControl:
+    if command.item_id not in state.conversation_items:
+        return ResolvedControl(
+            payloads=[],
+            events=[
+                error_event(
+                    "item_not_found", f"Conversation item not found: {command.item_id}", event_id=command.event_id
+                )
+            ],
+        )
+    _remove_conversation_item(state, command.item_id)
+    return ResolvedControl(payloads=[command.payload()], events=[])
+
+
+def resolve_truncate_item(state: RealtimeProjectionState, command: TruncateItem) -> ResolvedControl:
+    item = state.conversation_items.get(command.item_id)
+    if not isinstance(item, dict):
+        return ResolvedControl(
+            payloads=[],
+            events=[
+                error_event(
+                    "item_not_found", f"Conversation item not found: {command.item_id}", event_id=command.event_id
+                )
+            ],
+        )
+    truncate_error = validate_realtime_item_truncate(
+        item, content_index=command.content_index, audio_end_ms=command.audio_end_ms
+    )
+    if truncate_error is not None:
+        return ResolvedControl(
+            payloads=[], events=[error_event("bad_event", truncate_error, event_id=command.event_id)]
+        )
+    state.item_truncation_cursors[command.item_id] = (command.content_index, command.audio_end_ms)
+    truncate_realtime_item_content(item, content_index=command.content_index, audio_end_ms=command.audio_end_ms)
+    ack_payload: dict[str, object] = {
+        "type": "playback.ack",
+        "item_id": command.item_id,
+        "committed_ms": int(command.audio_end_ms),
+        "played_ms": int(command.audio_end_ms),
+        "truncate": True,
+    }
+    return ResolvedControl(payloads=[command.payload(), ack_payload], events=[])
+
+
+def _duplicate_function_call_output(state: RealtimeProjectionState, call_id: object) -> tuple[bool, bool]:
+    matching_call = any(
+        known.get("type") == "function_call" and known.get("call_id") == call_id
+        for known in state.conversation_items.values()
+    )
+    duplicate_output = any(
+        known.get("type") == "function_call_output" and known.get("call_id") == call_id
+        for known in state.conversation_items.values()
+    )
+    return matching_call, duplicate_output
+
+
+def resolve_create_item(state: RealtimeProjectionState, command: CreateItem) -> ResolvedControl:
+    """Expand ``conversation.item.create`` the way the old translator did.
+
+    Assistant/system/function items and text-only user items become one
+    ``turn.signal conversation.item.create`` payload. User items carrying audio
+    become one ``input_audio_buffer.append`` per audio part followed by an
+    ``input_audio_buffer.commit`` (no response). The user-item ack events are
+    returned in ``events`` and must be emitted *before* running the payloads.
+    """
+    item = dict(command.item)
+    if isinstance(command.previous_item_id, str):
+        item["_previous_item_id"] = command.previous_item_id
+    item_id = str(item["id"])
+    item_type = item.get("type")
+    role = item.get("role")
+    if item_type == "function_call_output":
+        call_id = item.get("call_id")
+        output = item.get("output")
+        matching_call, duplicate_output = _duplicate_function_call_output(state, call_id)
+        if not isinstance(call_id, str) or not call_id or not matching_call:
+            return ResolvedControl(
+                payloads=[],
+                events=[
+                    error_event(
+                        "invalid_function_call_output",
+                        "function_call_output requires the call_id of a completed function call",
+                        event_id=command.event_id,
+                        param="item.call_id",
+                    )
+                ],
+            )
+        if not isinstance(output, str) or duplicate_output:
+            return ResolvedControl(
+                payloads=[],
+                events=[
+                    error_event(
+                        "invalid_function_call_output",
+                        (
+                            "function_call_output requires a string output"
+                            if not isinstance(output, str)
+                            else f"function_call_output already exists for call_id {call_id}"
+                        ),
+                        event_id=command.event_id,
+                        param="item.output",
+                    )
+                ],
+            )
+    ack_events = register_user_item(state, item) if item_type == "message" and role == "user" else []
+    signal_payload = {
+        "type": "turn.signal",
+        "event": "conversation.item.create",
+        "payload": {"item": item},
+    }
+    if command.event_id is not None:
+        signal_payload["realtime_event_id"] = command.event_id
+    if item_type != "message" or role in {"assistant", "system"}:
+        return ResolvedControl(payloads=[signal_payload], events=ack_events)
+    content = item.get("content")
+    if not isinstance(content, list):
+        return ResolvedControl(payloads=[], events=ack_events)
+    text_chunks: list[str] = []
+    audio_payloads: list[dict[str, object]] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        if part.get("type") in {"input_text", "text"} and isinstance(part.get("text"), str):
+            text_chunks.append(str(part["text"]))
+        if part.get("type") in {"input_audio", "audio"}:
+            audio = part.get("audio") or part.get("data")
+            if not isinstance(audio, str) or not audio:
+                continue
+            try:
+                append = build_append_audio(
+                    {
+                        "audio": audio,
+                        "format": part.get("format"),
+                        "sample_rate_hz": part.get("sample_rate_hz") or part.get("sample_rate"),
+                        "event_id": command.event_id,
+                    },
+                    defaults=state.defaults,
+                    hints_source={**item, **part},
+                )
+            except Exception as exc:  # DuplexCommandError from validation/conversion
+                code = getattr(exc, "code", "bad_event")
+                if code == "unsupported_audio_format":
+                    continue
+                return ResolvedControl(
+                    payloads=[],
+                    events=[error_event(code, str(exc), event_id=command.event_id, param="sample_rate_hz")],
+                )
+            speech_hints = {**item, **part}
+            if not input_looks_like_speech(
+                speech_hints, audio=append.audio, fmt=append.format, overlap_silence_rms=state.overlap_silence_rms
+            ):
+                continue
+            state.input_speech_started = True
+            payload = append.payload()
+            copy_realtime_input_hints(part, payload)
+            copy_realtime_input_hints(item, payload)
+            audio_payloads.append(payload)
+    if audio_payloads:
+        state.input_audio_buffer_has_audio = True
+        transcript = input_transcript_from_item(item)
+        commit_payload: dict[str, object] = {
+            "type": "input_audio_buffer.commit",
+            "final": True,
+            "realtime_item_id": item_id,
+            "response_create": False,
+        }
+        if transcript:
+            commit_payload["transcript"] = transcript
+        return ResolvedControl(payloads=[*audio_payloads, commit_payload], events=ack_events)
+    if not text_chunks:
+        return ResolvedControl(payloads=[], events=ack_events)
+    text_item = dict(item)
+    text_item["status"] = "completed"
+    signal_payload["payload"] = {"item": text_item}
+    return ResolvedControl(payloads=[signal_payload], events=ack_events)
+
+
+def append_audio_payload(command: AppendAudio) -> dict[str, object]:
+    """Internal ``input_audio_buffer.append`` payload for a command (convenience for the runner)."""
+    return command.payload()
+
+
+__all__ = [
+    "RealtimeProjectionState",
+    "ResolvedCommit",
+    "ResolvedControl",
+    "append_audio_payload",
+    "clear_input_buffer",
+    "discard_pending_input_audio",
+    "emit_input_speech_started",
+    "emit_input_speech_stopped",
+    "note_input_append",
+    "project_internal_event",
+    "realtime_session_payload",
+    "register_user_item",
+    "resolve_cancel_response",
+    "resolve_clear_output_audio",
+    "resolve_commit",
+    "resolve_create_item",
+    "resolve_delete_item",
+    "resolve_truncate_item",
+    "response_is_done",
+    "retrieve_item_events",
+]
diff --git a/vllm_omni/engine/duplex/runtime.py b/vllm_omni/engine/duplex/runtime.py
deleted file mode 100644
index dede0e0a643..00000000000
--- a/vllm_omni/engine/duplex/runtime.py
+++ /dev/null
@@ -1,108 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-"""Experimental duplex runtime loading and compatibility exports."""
-
-from __future__ import annotations
-
-from importlib import import_module
-
-from vllm_omni.engine.duplex.contracts import (
-    DuplexAppendPlan,
-    DuplexInputMode,
-    DuplexOutputAction,
-    DuplexOutputDecision,
-    DuplexRuntimeCapabilities,
-    DuplexRuntimeExtension,
-    SessionMode,
-    duplex_data_plane_request_info,
-    duplex_resource_request_belongs_to_session,
-    duplex_resource_request_id,
-)
-
-
-def load_duplex_runtime_extension(path: str | None) -> DuplexRuntimeExtension | None:
-    if not path:
-        return None
-    module_name, separator, attribute_name = path.rpartition(".")
-    if not separator:
-        raise ValueError(f"Invalid duplex runtime extension path: {path!r}")
-    extension_type = getattr(import_module(module_name), attribute_name)
-    return validate_duplex_runtime_extension(extension_type())
-
-
-def validate_duplex_runtime_extension(
-    extension: object,
-    *,
-    sampling_defaults: tuple[object, ...] | None = None,
-) -> DuplexRuntimeExtension:
-    required_methods = (
-        "configure_sampling_params",
-        "plan_append",
-        "decide_output",
-    )
-    missing = [name for name in required_methods if not callable(getattr(extension, name, None))]
-    if missing:
-        raise TypeError(f"Duplex runtime extension is missing callable method(s): {', '.join(missing)}")
-    typed_extension = extension  # type: ignore[assignment]
-    if sampling_defaults is not None:
-        configured = typed_extension.configure_sampling_params(
-            runtime_config={},
-            defaults=sampling_defaults,
-        )
-        if not isinstance(configured, tuple):
-            raise TypeError("Duplex runtime extension must return sampling parameters as a tuple")
-        if len(configured) != len(sampling_defaults):
-            raise ValueError("Duplex runtime extension must return one sampling parameter per stage")
-        for stage_id, (value, default) in enumerate(zip(configured, sampling_defaults, strict=True)):
-            if default is not None and not isinstance(value, type(default)):
-                raise TypeError(
-                    "Duplex runtime extension sampling parameter type mismatch "
-                    f"for stage {stage_id}: expected {type(default).__name__}, got {type(value).__name__}"
-                )
-    return typed_extension
-
-
-from vllm_omni.engine.duplex.lease import (  # noqa: E402, F401
-    DuplexLeaseActivity,
-    DuplexLeaseConfig,
-    DuplexLeaseState,
-    DuplexSessionExpiry,
-)
-from vllm_omni.engine.duplex.session import (  # noqa: E402, F401
-    DuplexAppendReservation,
-    DuplexCompletedAppend,
-    DuplexFenceMismatchError,
-    DuplexInputAppend,
-    DuplexRequestResource,
-    DuplexSessionRuntimeManager,
-    DuplexSessionRuntimeState,
-    DuplexStageBinding,
-)
-
-__all__ = [
-    "DuplexAppendPlan",
-    "DuplexAppendReservation",
-    "DuplexCompletedAppend",
-    "DuplexFenceMismatchError",
-    "DuplexInputAppend",
-    "DuplexInputMode",
-    "DuplexLeaseActivity",
-    "DuplexLeaseConfig",
-    "DuplexLeaseState",
-    "DuplexOutputAction",
-    "DuplexOutputDecision",
-    "DuplexRequestResource",
-    "DuplexRuntimeCapabilities",
-    "DuplexRuntimeExtension",
-    "DuplexSessionExpiry",
-    "DuplexSessionRuntimeManager",
-    "DuplexSessionRuntimeState",
-    "DuplexStageBinding",
-    "SessionMode",
-    "duplex_data_plane_request_info",
-    "duplex_resource_request_belongs_to_session",
-    "duplex_resource_request_id",
-    "load_duplex_runtime_extension",
-    "validate_duplex_runtime_extension",
-]
diff --git a/vllm_omni/engine/duplex/session.py b/vllm_omni/engine/duplex/session.py
deleted file mode 100644
index b7ad51504bb..00000000000
--- a/vllm_omni/engine/duplex/session.py
+++ /dev/null
@@ -1,534 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import time
-from collections import OrderedDict
-from collections.abc import Callable, Iterable
-from dataclasses import dataclass, field
-from typing import Any
-
-from vllm_omni.engine.duplex.contracts import (
-    DuplexInputMode,
-    DuplexRuntimeCapabilities,
-)
-from vllm_omni.engine.duplex.lease import (
-    DuplexLeaseActivity,
-    DuplexLeaseConfig,
-    DuplexLeaseState,
-    DuplexSessionExpiry,
-)
-from vllm_omni.engine.duplex.messages import DuplexFence
-
-
-def _default_capabilities() -> DuplexRuntimeCapabilities:
-    return DuplexRuntimeCapabilities()
-
-
-class DuplexFenceMismatchError(RuntimeError):
-    def __init__(self, expected: DuplexFence, actual: DuplexFence) -> None:
-        super().__init__(f"duplex fence mismatch: expected {expected!r}, got {actual!r}")
-        self.expected = expected
-        self.actual = actual
-
-
-@dataclass
-class DuplexStageBinding:
-    request_id: str
-    fence: DuplexFence
-
-
-@dataclass
-class DuplexRequestResource:
-    stage_id: int
-    request_id: str
-    fence: DuplexFence
-    submitted: bool = False
-
-
-@dataclass
-class DuplexInputAppend:
-    seq: int
-    turn_seq: int
-    turn_id: int
-
-
-@dataclass(frozen=True)
-class DuplexAppendReservation:
-    fence: DuplexFence
-    mode: DuplexInputMode
-    base_fence: DuplexFence
-    base_input_seq: int
-    base_input_turn_seq: int
-    base_append_turn_key: tuple[int, int, int] | None
-    update: DuplexInputAppend
-
-
-@dataclass(frozen=True)
-class DuplexCompletedAppend:
-    fence: DuplexFence
-    mode: DuplexInputMode
-    final: bool
-    stage_results: tuple[dict[str, object], ...]
-
-
-@dataclass
-class DuplexSessionRuntimeState:
-    """Engine resource handles associated with a core-owned identity fence."""
-
-    fence: DuplexFence
-    lease: DuplexLeaseState
-    _clock: Callable[[], float] = field(repr=False)
-    capabilities: DuplexRuntimeCapabilities = field(default_factory=_default_capabilities)
-    session_config: dict[str, Any] = field(default_factory=dict)
-    runtime_config: dict[str, Any] = field(default_factory=dict)
-    config_generation: int = 0
-    stage_bindings: dict[int, DuplexStageBinding] = field(default_factory=dict)
-    request_resources: dict[tuple[int, str], DuplexRequestResource] = field(default_factory=dict)
-    input_seq: int = 0
-    input_turn_seq: int = 0
-    _append_turn_key: tuple[int, int, int] | None = None
-    completed_append_limit: int = 256
-    completed_appends: OrderedDict[str, DuplexCompletedAppend] = field(default_factory=OrderedDict)
-
-    def __post_init__(self) -> None:
-        if self.completed_append_limit <= 0:
-            raise ValueError("completed_append_limit must be positive")
-
-    @property
-    def session_id(self) -> str:
-        return self.fence.session_id
-
-    @property
-    def epoch(self) -> int:
-        return self.fence.epoch
-
-    @property
-    def turn_id(self) -> int:
-        return self.fence.turn_id
-
-    def _validate_fence(self, fence: DuplexFence) -> None:
-        if fence.session_id != self.session_id or fence.incarnation != self.fence.incarnation:
-            raise DuplexFenceMismatchError(self.fence, fence)
-        current = self.fence
-        if fence.epoch < current.epoch or (
-            fence.epoch == current.epoch
-            and (fence.turn_id < current.turn_id or fence.response_seq < current.response_seq)
-        ):
-            raise DuplexFenceMismatchError(current, fence)
-
-    def accept_fence(self, fence: DuplexFence) -> None:
-        self._validate_fence(fence)
-        if fence.epoch != self.fence.epoch:
-            self.input_seq = 0
-            self.input_turn_seq = 0
-            self._append_turn_key = None
-            self.completed_appends.clear()
-        self.fence = fence
-
-    def touch(self, fence: DuplexFence, activity: DuplexLeaseActivity) -> None:
-        self._validate_fence(fence)
-        self.lease.touch(self._clock(), activity)
-
-    def detach(self, fence: DuplexFence) -> None:
-        self._validate_fence(fence)
-        self.lease.detach(self._clock())
-
-    def resume(self, fence: DuplexFence, *, expected_lease_generation: int) -> int:
-        self._validate_fence(fence)
-        return self.lease.resume(
-            self._clock(),
-            expected_generation=expected_lease_generation,
-        )
-
-    def begin_operation(self, fence: DuplexFence, operation_id: str) -> None:
-        self._validate_fence(fence)
-        self.lease.begin_operation(self._clock(), operation_id)
-
-    def end_operation(self, fence: DuplexFence, operation_id: str) -> None:
-        self._validate_fence(fence)
-        self.lease.end_operation(self._clock(), operation_id)
-
-    def replace_session_config(self, session_config: dict[str, Any]) -> None:
-        self.session_config = dict(session_config)
-        self.config_generation += 1
-
-    def replace_runtime_config(self, runtime_config: dict[str, Any]) -> None:
-        self.runtime_config = dict(runtime_config)
-        self.config_generation += 1
-
-    def replace_configs(
-        self,
-        *,
-        session_config: dict[str, Any] | None = None,
-        runtime_config: dict[str, Any] | None = None,
-    ) -> None:
-        """Atomically publish one validated configuration generation."""
-        if session_config is None and runtime_config is None:
-            return
-        next_session_config = self.session_config if session_config is None else dict(session_config)
-        next_runtime_config = self.runtime_config if runtime_config is None else dict(runtime_config)
-        self.session_config = next_session_config
-        self.runtime_config = next_runtime_config
-        self.config_generation += 1
-
-    def reserve_stage_request(self, stage_id: int, request_id: str, *, fence: DuplexFence) -> None:
-        self._validate_fence(fence)
-        resource_key = (stage_id, request_id)
-        existing = self.request_resources.get(resource_key)
-        if existing is not None:
-            if (
-                existing.fence.session_id != fence.session_id
-                or existing.fence.incarnation != fence.incarnation
-                or existing.fence.epoch != fence.epoch
-            ):
-                raise ValueError(f"Duplex request resource already reserved with different identity: {request_id}")
-            return
-        self.request_resources[resource_key] = DuplexRequestResource(
-            stage_id=stage_id,
-            request_id=request_id,
-            fence=fence,
-        )
-
-    def bind_stage_request(self, stage_id: int, request_id: str, *, fence: DuplexFence) -> None:
-        self.reserve_stage_request(stage_id, request_id, fence=fence)
-        self.accept_fence(fence)
-        resource = self.request_resources[(stage_id, request_id)]
-        resource.fence = fence
-        resource.submitted = True
-        self.stage_bindings[stage_id] = DuplexStageBinding(request_id=request_id, fence=fence)
-
-    def stage_request_ids(self, fence: DuplexFence | None = None) -> list[str]:
-        return [
-            binding.request_id for binding in self.stage_bindings.values() if fence is None or binding.fence == fence
-        ]
-
-    def resource_request_ids(
-        self,
-        fence: DuplexFence | None = None,
-        *,
-        submitted: bool | None = None,
-    ) -> list[str]:
-        return list(
-            dict.fromkeys(
-                resource.request_id
-                for resource in self.request_resources.values()
-                if (fence is None or resource.fence == fence) and (submitted is None or resource.submitted is submitted)
-            )
-        )
-
-    def release_request_ids(self, request_ids: list[str]) -> None:
-        released = set(request_ids)
-        if not released:
-            return
-        self.stage_bindings = {
-            stage_id: binding for stage_id, binding in self.stage_bindings.items() if binding.request_id not in released
-        }
-        self.request_resources = {
-            resource_key: resource
-            for resource_key, resource in self.request_resources.items()
-            if resource.request_id not in released
-        }
-
-    def prepare_append(self, *, mode: DuplexInputMode, fence: DuplexFence) -> DuplexAppendReservation:
-        if mode not in self.capabilities.input_modes:
-            raise ValueError(f"Duplex input mode {mode.value!r} is not supported by session {self.session_id}")
-        self._validate_fence(fence)
-        input_seq = 0 if fence.epoch != self.fence.epoch else self.input_seq
-        input_turn_seq = 0 if fence.epoch != self.fence.epoch else self.input_turn_seq
-        append_turn_key = None if fence.epoch != self.fence.epoch else self._append_turn_key
-        turn_key = (fence.epoch, fence.turn_id, fence.response_seq)
-        turn_seq = input_turn_seq + 1 if turn_key == append_turn_key else 1
-        return DuplexAppendReservation(
-            fence=fence,
-            mode=mode,
-            base_fence=self.fence,
-            base_input_seq=self.input_seq,
-            base_input_turn_seq=self.input_turn_seq,
-            base_append_turn_key=self._append_turn_key,
-            update=DuplexInputAppend(
-                seq=input_seq + 1,
-                turn_seq=turn_seq,
-                turn_id=fence.turn_id,
-            ),
-        )
-
-    def commit_append(self, reservation: DuplexAppendReservation) -> DuplexInputAppend:
-        if (
-            self.fence != reservation.base_fence
-            or self.input_seq != reservation.base_input_seq
-            or self.input_turn_seq != reservation.base_input_turn_seq
-            or self._append_turn_key != reservation.base_append_turn_key
-        ):
-            raise RuntimeError("duplex append reservation is stale")
-        self.accept_fence(reservation.fence)
-        self.input_seq = reservation.update.seq
-        self.input_turn_seq = reservation.update.turn_seq
-        self._append_turn_key = (
-            reservation.fence.epoch,
-            reservation.fence.turn_id,
-            reservation.fence.response_seq,
-        )
-        return reservation.update
-
-    def completed_append(
-        self,
-        operation_id: str,
-        *,
-        fence: DuplexFence,
-        mode: DuplexInputMode,
-        final: bool,
-    ) -> list[dict[str, object]] | None:
-        self._validate_fence(fence)
-        completed = self.completed_appends.get(operation_id)
-        if completed is None:
-            return None
-        if completed.fence != fence or completed.mode != mode or completed.final != final:
-            raise ValueError(f"duplex append operation {operation_id!r} was reused with different metadata")
-        return [dict(result) for result in completed.stage_results]
-
-    def record_completed_append(
-        self,
-        operation_id: str,
-        *,
-        fence: DuplexFence,
-        mode: DuplexInputMode,
-        final: bool,
-        stage_results: list[dict[str, object]],
-    ) -> None:
-        self.completed_appends[operation_id] = DuplexCompletedAppend(
-            fence=fence,
-            mode=mode,
-            final=final,
-            stage_results=tuple(dict(result) for result in stage_results),
-        )
-        self.completed_appends.move_to_end(operation_id)
-        while len(self.completed_appends) > self.completed_append_limit:
-            self.completed_appends.popitem(last=False)
-
-    def append_input(self, *, mode: DuplexInputMode, fence: DuplexFence) -> DuplexInputAppend:
-        return self.commit_append(self.prepare_append(mode=mode, fence=fence))
-
-    def release_fence(self, fence: DuplexFence) -> list[str]:
-        stale = self.resource_request_ids(fence)
-        self.stage_bindings = {
-            stage_id: binding for stage_id, binding in self.stage_bindings.items() if binding.fence != fence
-        }
-        self.request_resources = {
-            resource_key: resource
-            for resource_key, resource in self.request_resources.items()
-            if resource.fence != fence
-        }
-        return stale
-
-    def cancel_fence(self, cancelled_fence: DuplexFence, next_fence: DuplexFence) -> list[str]:
-        stale = self.prepare_cancel_fence(cancelled_fence, next_fence)
-        self.release_fence(cancelled_fence)
-        return stale
-
-    def prepare_cancel_fence(self, cancelled_fence: DuplexFence, next_fence: DuplexFence) -> list[str]:
-        """Advance the cancellation fence without dropping cleanup records."""
-        if cancelled_fence.session_id != self.session_id or cancelled_fence.incarnation != self.fence.incarnation:
-            raise DuplexFenceMismatchError(self.fence, cancelled_fence)
-        if (
-            next_fence.session_id != self.session_id
-            or next_fence.incarnation != self.fence.incarnation
-            or next_fence.epoch <= cancelled_fence.epoch
-        ):
-            raise DuplexFenceMismatchError(cancelled_fence, next_fence)
-        current_key = (self.fence.epoch, self.fence.turn_id, self.fence.response_seq)
-        cancelled_key = (cancelled_fence.epoch, cancelled_fence.turn_id, cancelled_fence.response_seq)
-        next_key = (next_fence.epoch, next_fence.turn_id, next_fence.response_seq)
-        if cancelled_key > current_key:
-            raise DuplexFenceMismatchError(self.fence, cancelled_fence)
-        if next_key > current_key:
-            self.accept_fence(next_fence)
-        return self.resource_request_ids(cancelled_fence)
-
-    def begin_close(self, fence: DuplexFence, *, reason: str) -> bool:
-        """Make close irreversible while retaining resources for cleanup retry."""
-        self.accept_fence(fence)
-        if self.lease.terminal_reason is not None:
-            return True
-        return self.lease.mark_terminal(reason)
-
-    def finalize_close(self) -> list[str]:
-        return self.close()
-
-    def close(self, fence: DuplexFence | None = None) -> list[str]:
-        if fence is not None:
-            self.accept_fence(fence)
-        stale = self.resource_request_ids()
-        self.stage_bindings.clear()
-        self.request_resources.clear()
-        return stale
-
-    def terminate(self, fence: DuplexFence, *, reason: str) -> bool:
-        if not self.begin_close(fence, reason=reason):
-            return False
-        self.finalize_close()
-        return True
-
-
-class DuplexSessionRuntimeManager:
-    def __init__(
-        self,
-        *,
-        clock: Callable[[], float] | None = None,
-        max_sessions: int | None = None,
-        completed_append_limit: int = 256,
-    ) -> None:
-        if max_sessions is not None and max_sessions <= 0:
-            raise ValueError("max_sessions must be positive or null")
-        if completed_append_limit <= 0:
-            raise ValueError("completed_append_limit must be positive")
-        self._sessions: dict[str, DuplexSessionRuntimeState] = {}
-        self._clock = clock or time.monotonic
-        self._max_sessions = max_sessions
-        self._completed_append_limit = completed_append_limit
-
-    def open_session(
-        self,
-        fence: DuplexFence,
-        *,
-        capabilities: DuplexRuntimeCapabilities | None = None,
-        session_config: dict[str, Any] | None = None,
-        runtime_config: dict[str, Any] | None = None,
-        lease_config: DuplexLeaseConfig | None = None,
-    ) -> DuplexSessionRuntimeState:
-        if not isinstance(fence, DuplexFence):
-            raise TypeError("open_session requires DuplexFence")
-        if fence.session_id in self._sessions:
-            raise ValueError(f"Duplex session already exists: {fence.session_id}")
-        if self._max_sessions is not None and len(self._sessions) >= self._max_sessions:
-            raise RuntimeError(f"duplex_session_capacity_exhausted: limit={self._max_sessions}")
-        session = DuplexSessionRuntimeState(
-            fence=fence,
-            lease=DuplexLeaseState(
-                config=lease_config or DuplexLeaseConfig(),
-                generation=0,
-                last_activity=self._clock(),
-            ),
-            _clock=self._clock,
-            capabilities=capabilities or _default_capabilities(),
-            session_config=dict(session_config or {}),
-            runtime_config=dict(runtime_config or {}),
-            completed_append_limit=self._completed_append_limit,
-        )
-        self._sessions[fence.session_id] = session
-        return session
-
-    def get(self, session_id: str) -> DuplexSessionRuntimeState | None:
-        return self._sessions.get(session_id)
-
-    def require(self, session_id: str) -> DuplexSessionRuntimeState:
-        session = self.get(session_id)
-        if session is None:
-            raise KeyError(f"Unknown duplex session: {session_id}")
-        return session
-
-    def close_session(
-        self,
-        fence: DuplexFence,
-        *,
-        reason: str = "explicit_close",
-    ) -> DuplexSessionRuntimeState | None:
-        if not isinstance(fence, DuplexFence):
-            raise TypeError("close_session requires DuplexFence")
-        session = self._sessions.get(fence.session_id)
-        if session is not None:
-            if session.lease.terminal_reason is not None:
-                return None
-            if not session.terminate(fence, reason=reason):
-                return None
-            if self._sessions.get(fence.session_id) is session:
-                self._sessions.pop(fence.session_id)
-        return session
-
-    def begin_close_session(
-        self,
-        fence: DuplexFence,
-        *,
-        reason: str = "explicit_close",
-    ) -> DuplexSessionRuntimeState | None:
-        if not isinstance(fence, DuplexFence):
-            raise TypeError("begin_close_session requires DuplexFence")
-        session = self._sessions.get(fence.session_id)
-        if session is not None:
-            session.begin_close(fence, reason=reason)
-        return session
-
-    def finalize_close_session(self, session: DuplexSessionRuntimeState) -> None:
-        session.finalize_close()
-        if self._sessions.get(session.session_id) is session:
-            self._sessions.pop(session.session_id, None)
-
-    def collect_expired(
-        self,
-        now: float | None = None,
-        *,
-        excluded_session_ids: set[str] | None = None,
-    ) -> list[DuplexSessionExpiry]:
-        effective_now = self._clock() if now is None else now
-        excluded = excluded_session_ids or set()
-        expired: list[DuplexSessionExpiry] = []
-        for session_id, session in list(self._sessions.items()):
-            if session_id in excluded:
-                continue
-            if session.lease.disconnect_grace_expired(effective_now):
-                reason = "disconnect_grace_expired"
-            elif session.lease.idle_expired(effective_now):
-                reason = "idle_ttl_expired"
-            else:
-                continue
-            submitted = tuple(session.resource_request_ids(submitted=True))
-            reserved = tuple(session.resource_request_ids(submitted=False))
-            if not session.begin_close(session.fence, reason=reason):
-                continue
-            expired.append(
-                DuplexSessionExpiry(
-                    session_id=session_id,
-                    fence=session.fence,
-                    lease_generation=session.lease.generation,
-                    reason=reason,
-                    submitted_request_ids=submitted,
-                    reserved_request_ids=reserved,
-                )
-            )
-        return expired
-
-    def close_sessions_for_request_ids(self, request_ids: list[str]) -> dict[str, list[str]]:
-        request_id_set = set(request_ids)
-        closed: dict[str, list[str]] = {}
-        for session_id, session in list(self._sessions.items()):
-            stale = session.resource_request_ids()
-            if request_id_set.isdisjoint(stale):
-                continue
-            if not session.begin_close(session.fence, reason="request_cleanup"):
-                continue
-            closed[session_id] = stale
-        return closed
-
-    def finalize_closed_sessions(self, session_ids: Iterable[str]) -> None:
-        for session_id in session_ids:
-            session = self._sessions.get(session_id)
-            if session is None or session.lease.terminal_reason is None:
-                continue
-            self.finalize_close_session(session)
-
-
-__all__ = [
-    "DuplexAppendReservation",
-    "DuplexCompletedAppend",
-    "DuplexFenceMismatchError",
-    "DuplexInputAppend",
-    "DuplexLeaseActivity",
-    "DuplexLeaseConfig",
-    "DuplexLeaseState",
-    "DuplexRequestResource",
-    "DuplexSessionExpiry",
-    "DuplexSessionRuntimeManager",
-    "DuplexSessionRuntimeState",
-    "DuplexStageBinding",
-]
diff --git a/vllm_omni/engine/duplex/session/__init__.py b/vllm_omni/engine/duplex/session/__init__.py
new file mode 100644
index 00000000000..a062ebf0eef
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/__init__.py
@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""One engine-resident duplex session, and everything that runs it.
+
+``DuplexEngineSession`` (``engine_session``) is the state -- the input,
+response, playback and conversation ledgers, the lease and the identity fence.
+``DuplexSessionRunner`` (``runner``) owns one of those on the orchestrator loop
+and is the only writer of it; ``DuplexSessionManager`` (``manager``) owns the
+runners and the admission slots.
+
+The rest of the package is what the runner was split into, and each module
+names the thing it owns rather than a layer:
+
+* ``context``  -- the state a runner and its components share, and the only
+  services a component may ask the runner for.
+* ``emitter``  -- everything the session sends: the Realtime projection, the
+  epoch filter, the domain effects a terminal event applies.
+* ``model_channel`` -- the model side: submitting an append, projecting the
+  stage output that comes back, continuing a turn with silence.
+* ``control``  -- server VAD and the events that reconfigure the session.
+* ``append_task`` -- one append in flight, and the rollback its failure owes.
+* ``helpers``  -- the small pure reads and payload builders over a session.
+* ``overlap_policy`` / ``commit_policy`` / ``playback_ledger`` -- the decisions
+  a session makes about speech that arrives while the model is speaking, what a
+  commit should do, and what the client has actually played.
+* ``lease`` -- the idle/activity lease that decides when a session expires.
+
+Imports here are the package's public surface; a module of this package is fair
+game for anything inside it, but code outside ``engine.duplex`` should reach for
+these three names.
+"""
+
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession
+from vllm_omni.engine.duplex.session.manager import DuplexSessionManager
+from vllm_omni.engine.duplex.session.runner import DuplexSessionRunner
+
+__all__ = ["DuplexEngineSession", "DuplexSessionManager", "DuplexSessionRunner"]
diff --git a/vllm_omni/engine/duplex/session/append_task.py b/vllm_omni/engine/duplex/session/append_task.py
new file mode 100644
index 00000000000..724dc7f8224
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/append_task.py
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""One append in flight, and what its failure owes the session.
+
+An append is not a call: it is a task queued behind the previous append, which
+may be cancelled, may find the session closed before it starts, and on any of
+those paths has to give back what it reserved --- the PCM bytes it took from the
+input budget, the committed audio it was going to consume, and the response it
+precreated.
+
+That compensation is the reason this is an object. The five steps of an append
+all need the same eleven values, so as closures over ``_start_append`` they read
+as one function with five entry points and no way to test any of them. Named
+fields make the captured state explicit and the compensation a method.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from vllm.logger import init_logger
+
+from vllm_omni.engine.duplex.config import DuplexSessionState, DuplexTurnEventType
+from vllm_omni.engine.duplex.plugin import PcmAppendReservation
+from vllm_omni.engine.duplex.session import helpers
+from vllm_omni.engine.duplex.session.context import DuplexSessionContext
+from vllm_omni.engine.duplex.session.emitter import SessionEmitter
+from vllm_omni.engine.duplex.session.model_channel import ModelChannel
+
+logger = init_logger(__name__)
+
+
+@dataclass(slots=True)
+class AppendAttempt:
+    """One queued append to the model, with the rollback each failure path owes."""
+
+    ctx: DuplexSessionContext
+    out: SessionEmitter
+    model: ModelChannel
+    #: Marks the session closing before the close coroutine gets to run.
+    fail_session: Callable[[str], None]
+
+    payload: dict[str, object]
+    epoch: int
+    request_id: str
+    final: bool
+    pcm_reservation: PcmAppendReservation | None
+    operation_id: str | None
+    #: Committed audio this append consumes; released once it is safely submitted.
+    retained_committed_payload: dict[str, object] | None
+    #: Response reserved before submission, to be failed if submission does not happen.
+    precreated_response_id: str | None
+    #: Last chance to call the append off, checked once the predecessor is done.
+    before_append: Callable[[], bool] | None
+
+    # ------------------------------------------------------------------ #
+    # Compensation                                                       #
+    # ------------------------------------------------------------------ #
+
+    def discard_retained_audio(self) -> None:
+        """Release the committed audio this append was going to consume.
+
+        Only if it is still the session's: a later commit may have replaced it,
+        and that one belongs to the append that will carry it.
+        """
+        model_state = self.ctx.model_state
+        if self.retained_committed_payload is not None and (
+            model_state.committed_audio_payload is self.retained_committed_payload
+        ):
+            self.ctx.session.release_input_bytes(model_state.clear_committed_audio())
+
+    def abandon(self) -> None:
+        """Give back everything this append reserved but never used."""
+        if self.pcm_reservation is not None:
+            self.pcm_reservation.rollback()
+        self.discard_retained_audio()
+
+    def release_on_failure(self, done: asyncio.Task[bool]) -> None:
+        """Done-callback: a cancelled or failed append must not hold the audio."""
+        if done.cancelled():
+            self.discard_retained_audio()
+            return
+        try:
+            append_ok = done.result()
+        except Exception:
+            append_ok = False
+        if not append_ok:
+            self.discard_retained_audio()
+
+    def clear_pending_silence(self, done: asyncio.Task[bool]) -> None:
+        """Done-callback of a silence continuation: it is no longer pending."""
+        model_state = self.ctx.model_state
+        if model_state.pending_silence_task is done:
+            model_state.pending_silence_task = None
+            model_state.pending_silence_owner_id = None
+
+    # ------------------------------------------------------------------ #
+    # Running                                                            #
+    # ------------------------------------------------------------------ #
+
+    async def run_in_wire_order(self, predecessor: asyncio.Task[bool] | None) -> bool:
+        """Wait for the previous append, then submit this one if it still applies."""
+        if predecessor is not None:
+            try:
+                predecessor_ok = await predecessor
+            except asyncio.CancelledError:
+                current = asyncio.current_task()
+                if current is not None and current.cancelling():
+                    raise
+                predecessor_ok = False
+            except Exception:
+                predecessor_ok = False
+            if not predecessor_ok:
+                self.abandon()
+                return False
+        run = self.ctx.run
+        if run.closing or run.runtime_closed or self.ctx.session.state != DuplexSessionState.OPEN:
+            self.abandon()
+            return False
+        if self.before_append is not None and not self.before_append():
+            self.abandon()
+            # Called off, not failed: the chain behind it still runs.
+            return True
+        if self.pcm_reservation is not None and not self.pcm_reservation.active:
+            self.discard_retained_audio()
+            return False
+        return await self._submit()
+
+    async def _submit(self) -> bool:
+        session = self.ctx.session
+        model_state = self.ctx.model_state
+        try:
+            append_ok, emitted_response = await self.model.append_runtime_input(
+                self.payload,
+                operation_id=(
+                    self.pcm_reservation.operation_id if self.pcm_reservation is not None else self.operation_id
+                ),
+                final=self.final,
+                expected_epoch=self.epoch,
+            )
+            if append_ok:
+                model_state.context_locked = True
+                if self.pcm_reservation is not None:
+                    self.pcm_reservation.commit()
+                    session.release_input_bytes(self.pcm_reservation.byte_count)
+                self.discard_retained_audio()
+            else:
+                self.abandon()
+            if not append_ok and self._precreated_response_still_active():
+                self._fail_precreated_response()
+            if not append_ok and session.state == DuplexSessionState.CLOSED:
+                self.ctx.run.runtime_closed = True
+                return False
+            if not emitted_response and session.epoch == self.epoch:
+                if session.active_request_id == helpers.stage0_request_id(session, self.epoch):
+                    session.clear_request(self.request_id)
+                if self.final:
+                    self.out.emit_events([session.signal_turn(DuplexTurnEventType.USER_STARTED.value)])
+            return append_ok
+        except asyncio.CancelledError:
+            if self.pcm_reservation is not None:
+                self.pcm_reservation.rollback()
+            raise
+        except Exception as exc:
+            self.abandon()
+            logger.exception("Native duplex append task failed: %s", exc)
+            self.model.send_runtime_error("runtime_append_task_failed", exc)
+            if session.state != DuplexSessionState.CLOSED:
+                self.fail_session("runtime_append_task_failed")
+            return False
+
+    def _precreated_response_still_active(self) -> bool:
+        return (
+            self.precreated_response_id is not None
+            and self.ctx.session.active_response_id == self.precreated_response_id
+        )
+
+    def _fail_precreated_response(self) -> None:
+        session = self.ctx.session
+        session.end_response(commit_text=False)
+        self.out.emit(
+            {
+                "type": "response.done",
+                "session_id": session.session_id,
+                "response_id": self.precreated_response_id,
+                "epoch": session.epoch,
+                "committed": False,
+                "status": "failed",
+                "status_details": {"type": "failed", "reason": "runtime_append_failed"},
+                "playback": session.playback.as_dict(),
+            }
+        )
diff --git a/vllm_omni/entrypoints/duplex/commit_policy.py b/vllm_omni/engine/duplex/session/commit_policy.py
similarity index 91%
rename from vllm_omni/entrypoints/duplex/commit_policy.py
rename to vllm_omni/engine/duplex/session/commit_policy.py
index 868b98c9896..0c07a6fa3b9 100644
--- a/vllm_omni/entrypoints/duplex/commit_policy.py
+++ b/vllm_omni/engine/duplex/session/commit_policy.py
@@ -21,7 +21,7 @@ class CommitSnapshot:
     speech_since_commit: bool
     active_response_id: str | None
     overlap_speech_ms: int
-    native_response_in_progress: bool
+    response_in_progress: bool
     playback_active: bool
 
 
@@ -31,7 +31,7 @@ def decide_commit_action(snapshot: CommitSnapshot) -> CommitAction:
         if snapshot.speech_since_commit:
             return CommitAction.START_AUTO_RESPONSE
         return CommitAction.COMMIT_ONLY
-    if snapshot.native_response_in_progress and snapshot.overlap_speech_ms > 0:
+    if snapshot.response_in_progress and snapshot.overlap_speech_ms > 0:
         return CommitAction.DEFER_ACTIVE_RESPONSE
     if snapshot.playback_active and snapshot.overlap_speech_ms > 0:
         return CommitAction.DEFER_ACTIVE_RESPONSE
diff --git a/vllm_omni/engine/duplex/session/context.py b/vllm_omni/engine/duplex/session/context.py
new file mode 100644
index 00000000000..1e7b861bcae
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/context.py
@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Shared state for :class:`DuplexSessionRunner` and its components.
+
+The runner is a state machine that several components read and write. Splitting
+it into modules only helps if the shared part stops being implicit: a component
+holding a back-reference to the runner is a mixin with extra steps, and one
+holding its own copy of a flag diverges from the others.
+
+So the mutable part is named. ``DuplexRunState`` is the small set of flags that
+more than one component touches -- ``grep "\\.run\\."`` finds every mutation --
+and ``DuplexSessionContext`` is the read-mostly collaborator bundle everything
+is constructed with. Anything a component needs from the runner that is neither
+of those is infrastructure, and goes through :class:`RunnerServices`.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Protocol, TypeVar
+
+if TYPE_CHECKING:
+    from vllm.outputs import RequestOutput
+
+    from vllm_omni.engine.duplex.contracts import (
+        DuplexOutputContext,
+        DuplexOutputDecision,
+        DuplexStagePort,
+    )
+    from vllm_omni.engine.duplex.plugin import DuplexModelPlugin, DuplexModelSessionState
+    from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession
+    from vllm_omni.engine.duplex.session.manager import DuplexSessionManager
+    from vllm_omni.metrics.stats import StageRequestStats
+
+_OffloadT = TypeVar("_OffloadT")
+
+
+@dataclass(slots=True)
+class DuplexRunState:
+    """Mutable per-run flags shared by the runner and its components.
+
+    Every field here is written by one component and read by another; that is
+    the criterion for being in this object rather than private to a component.
+    """
+
+    #: An irreversible close has begun: commands and control ops are refused.
+    closing: bool = False
+    #: ``session.closed`` / ``session.expired`` already left the runner.
+    closed_emitted: bool = False
+    #: The terminal event is deferred to the manager, which emits it after the
+    #: stage cleanup so it also means "the admission slot is free again".
+    closed_deferred: bool = False
+    close_reason: str | None = None
+    #: The model runtime reported a close; further data-plane work is pointless.
+    runtime_closed: bool = False
+    #: Request id of the resumable data-plane stream currently bound to the session.
+    stream_request_id: str | None = None
+
+
+class RunnerServices(Protocol):
+    """The only things a component may ask the runner for.
+
+    Deliberately two methods. A component that needs more than task scheduling
+    from the runner is reaching for orchestration that belongs in the runner.
+    """
+
+    def spawn(self, coro: Awaitable[None], *, name: str) -> None:
+        """Run ``coro`` as a tracked background task on the session's loop."""
+        ...
+
+    async def offload(self, fn: Callable[..., _OffloadT], *args: object, **kwargs: object) -> _OffloadT:
+        """Run a blocking call off the orchestrator loop."""
+        ...
+
+
+@dataclass(slots=True)
+class DuplexSessionContext:
+    """Collaborators one session's components are built with.
+
+    Read-mostly: the session and the model state are mutated through their own
+    APIs, not by rebinding these fields. The mutable flags live in ``run``.
+    """
+
+    session: DuplexEngineSession
+    model_state: DuplexModelSessionState
+    plugin: DuplexModelPlugin
+    stage_port: DuplexStagePort
+    manager: DuplexSessionManager
+    tasks: DuplexSessionTasks
+    run: DuplexRunState
+    services: RunnerServices
+
+
+# --------------------------------------------------------------------------- #
+# Task bookkeeping                                                            #
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True, slots=True)
+class DuplexAppendTaskMeta:
+    epoch: int
+    final: bool
+    response_bound: bool
+
+
+@dataclass
+class DuplexSessionTasks:
+    """Tracked task handles of one session (append tail, active response, pending silence)."""
+
+    append_tasks: dict[asyncio.Task[bool], DuplexAppendTaskMeta] = field(default_factory=dict)
+    append_tail: asyncio.Task[bool] | None = None
+    active_response_task: asyncio.Task[None] | None = None
+
+    def track_append_task(
+        self,
+        task: asyncio.Task[bool],
+        *,
+        epoch: int,
+        final: bool,
+        response_bound: bool,
+    ) -> None:
+        self.append_tasks[task] = DuplexAppendTaskMeta(epoch, final, response_bound)
+        task.add_done_callback(self.append_tasks.pop)
+
+    def has_response_bound_append_tasks(self) -> bool:
+        return any(meta.response_bound for meta in self.append_tasks.values())
+
+    async def cancel_append_tasks(self, timeout_s: float = 0.25, *, response_bound_only: bool = False) -> bool:
+        tasks = [task for task, meta in self.append_tasks.items() if not response_bound_only or meta.response_bound]
+        if not tasks:
+            return False
+        cancelled_tail = self.append_tail if self.append_tail in tasks else None
+        for task in tasks:
+            task.cancel()
+        try:
+            await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), timeout=timeout_s)
+        except TimeoutError:
+            pass
+        if cancelled_tail is not None and self.append_tail is cancelled_tail:
+            self.append_tail = None
+        return True
+
+
+# --------------------------------------------------------------------------- #
+# Stage output (the mailbox item the orchestrator hands the runner)           #
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True, slots=True)
+class StageOutput:
+    """One stage result, queued for the session that owns the request."""
+
+    stage_id: int
+    output: RequestOutput
+    metrics: StageRequestStats | None
+    request_id: str
+    context: DuplexOutputContext
+    decision: DuplexOutputDecision | None
diff --git a/vllm_omni/engine/duplex/session/control.py b/vllm_omni/engine/duplex/session/control.py
new file mode 100644
index 00000000000..2d46154fe49
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/control.py
@@ -0,0 +1,328 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Control of one duplex session: server VAD, and the events that reconfigure it.
+
+Server turn detection and ``session.update`` are the same concern seen from two
+sides. The detector is per-session mutable state, and ``session.update`` is the
+event that replaces it mid-flight -- along with the session config, the runtime
+config and the sampling policy, each of which has to be validated against a
+candidate before the live session adopts it. The rest of ``turn.signal``
+(conversation items, local turn markers) travels the same path and is small, so
+it lives here rather than in a module of its own.
+
+The one thing this does not own is ordering against the data plane: a
+``session.update`` must not overtake an append still in flight, so the runner
+supplies ``wait_for_append_tail``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from copy import deepcopy
+
+from vllm.logger import init_logger
+
+from vllm_omni.engine.duplex.config import DuplexConfigError, realtime_item_to_history_message
+from vllm_omni.engine.duplex.plugin import DuplexRuntimeConfigError
+from vllm_omni.engine.duplex.session import helpers
+from vllm_omni.engine.duplex.session.context import DuplexSessionContext
+from vllm_omni.engine.duplex.session.emitter import SessionEmitter
+from vllm_omni.engine.duplex.session.lease import DuplexLeaseActivity
+from vllm_omni.engine.duplex.session.model_channel import ModelChannel
+from vllm_omni.engine.duplex.turn_detection import (
+    PendingTurnDetectionUpdate,
+    ServerTurnDetector,
+    ServerVADUnavailableError,
+    SileroVADBackendProvider,
+    TurnDetectionConfig,
+    TurnDetectionResult,
+    apply_turn_detection_result,
+)
+
+logger = init_logger(__name__)
+
+
+class SessionControl:
+    """Server VAD and the control events that reconfigure one session."""
+
+    def __init__(
+        self,
+        ctx: DuplexSessionContext,
+        out: SessionEmitter,
+        model: ModelChannel,
+        *,
+        wait_for_append_tail: Callable[[], Awaitable[bool]],
+    ) -> None:
+        self._ctx = ctx
+        self._out = out
+        self._model = model
+        self._wait_for_append_tail = wait_for_append_tail
+        self._config: TurnDetectionConfig | None = None
+        self._detector: ServerTurnDetector | None = None
+
+    def init_turn_detection(self) -> None:
+        turn_detection = self._ctx.session.config.extra_body.get("realtime_turn_detection")
+        if not isinstance(turn_detection, dict) or turn_detection.get("type") != "server_vad":
+            self._config = None
+            self._detector = None
+            return
+        try:
+            config = TurnDetectionConfig.from_realtime(turn_detection)
+            self._config = config
+            self._detector = config.build_detector(self._vad_backend_provider())
+        except Exception as exc:
+            logger.warning("Duplex session %s: turn detection disabled: %s", self._ctx.session.session_id, exc)
+            self._config = None
+            self._detector = None
+
+    def _vad_backend_provider(self) -> SileroVADBackendProvider | None:
+        """The engine-wide Silero backend, so one model serves every session.
+
+        Held by the manager rather than built here: the ONNX backend is shared,
+        and ``duplex_session.server_vad_model_path`` is a deploy-level setting.
+        """
+        return getattr(self._ctx.manager, "vad_backend_provider", None)
+
+    def reset_vad(self) -> None:
+        """Drop the detector's speech state (a barge-in or a clear starts a new turn)."""
+        if self._detector is not None:
+            self._detector.reset()
+
+    async def run_turn_detection(self, event: dict[str, object]) -> TurnDetectionResult | None:
+        detector = self._detector
+        if detector is None:
+            return None
+        audio = event.get("audio")
+        if not isinstance(audio, str) or not audio:
+            return None
+        fmt = event.get("format") if isinstance(event.get("format"), str) else "pcm_f32le"
+        sample_rate_hz = event.get("sample_rate_hz")
+        try:
+            result = await self._ctx.services.offload(
+                detector.process,
+                audio,
+                fmt=fmt,
+                sample_rate_hz=sample_rate_hz if isinstance(sample_rate_hz, int) else None,
+                audio_end_ms=event.get("audio_end_ms") if isinstance(event.get("audio_end_ms"), int) else None,
+            )
+        except ServerVADUnavailableError as exc:
+            self._out.emit_error("server_vad_unavailable", str(exc))
+            self._detector = None
+            return None
+        except ValueError as exc:
+            self._out.emit_error("bad_audio", str(exc))
+            return None
+        apply_turn_detection_result(event, result)
+        return result
+
+    # ------------------------------------------------------------------ #
+    # Control events                                                     #
+    # ------------------------------------------------------------------ #
+
+    async def on_turn_signal(self, event: dict[str, object]) -> None:
+        session = self._ctx.session
+        turn_event = event.get("event")
+        realtime_event_id = event.get("realtime_event_id")
+        if not isinstance(turn_event, str):
+            self._out.emit_error("bad_event", "turn.signal requires event")
+            return
+        if turn_event == "barge_in" and not session.capabilities.supports_barge_in:
+            self._out.emit_events([helpers.barge_in_unsupported_error()])
+            return
+        if turn_event == "session.update":
+            payload = event.get("payload")
+            if not isinstance(payload, dict):
+                self._out.emit_error(
+                    "bad_event", "session.update requires a session payload", event_id=realtime_event_id
+                )
+                return
+            await self.on_session_update(
+                payload,
+                realtime_event_id=realtime_event_id if isinstance(realtime_event_id, str) else None,
+            )
+            return
+        if turn_event == "conversation.item.create":
+            await self._on_conversation_item_create(event)
+            return
+        if turn_event == "conversation.item.delete":
+            payload = event.get("payload")
+            item_id = payload.get("item_id") if isinstance(payload, dict) else None
+            deleted = session.delete_history_item(item_id) if isinstance(item_id, str) else False
+            self._out.emit(
+                {
+                    "type": "conversation.item.deleted",
+                    "session_id": session.session_id,
+                    "item_id": item_id,
+                    "deleted": deleted,
+                }
+            )
+            return
+        if turn_event == "conversation.item.truncate":
+            payload = event.get("payload")
+            item_id = payload.get("item_id") if isinstance(payload, dict) else None
+            audio_end_ms = payload.get("audio_end_ms") if isinstance(payload, dict) else None
+            truncated = (
+                session.truncate_history_item(
+                    item_id,
+                    audio_end_ms=int(audio_end_ms) if isinstance(audio_end_ms, int | float) else 0,
+                    hard=True,
+                )
+                if isinstance(item_id, str)
+                else False
+            )
+            self._out.emit(
+                {
+                    "type": "conversation.item.truncated",
+                    "session_id": session.session_id,
+                    "item_id": item_id,
+                    "content_index": (payload.get("content_index", 0) if isinstance(payload, dict) else 0),
+                    "audio_end_ms": audio_end_ms,
+                    "truncated": truncated,
+                }
+            )
+            return
+        self._out.emit_events([session.signal_turn(turn_event, event)])
+
+    async def on_session_update(self, payload: dict[str, object], *, realtime_event_id: str | None) -> None:
+        session = self._ctx.session
+        model_state = self._ctx.model_state
+        pending_turn_detection: PendingTurnDetectionUpdate | None = None
+
+        def reject_update() -> None:
+            if pending_turn_detection is not None:
+                pending_turn_detection.reject()
+
+        try:
+            pending_turn_detection = PendingTurnDetectionUpdate.prepare(
+                payload, backend_provider=self._vad_backend_provider()
+            )
+        except Exception as exc:
+            self._out.emit_error("unsupported_turn_detection", str(exc), event_id=realtime_event_id)
+            return
+        if not await self._wait_for_append_tail():
+            self._out.emit_error(
+                "session_update_aborted",
+                "session.update was not applied because the preceding append failed",
+                event_id=realtime_event_id,
+            )
+            reject_update()
+            return
+        try:
+            self._ctx.plugin.validate_client_extra_body(payload.get("extra_body"))
+        except DuplexRuntimeConfigError as exc:
+            self._out.emit_error(exc.code, str(exc), event_id=realtime_event_id)
+            reject_update()
+            return
+        candidate_config = deepcopy(session.config)
+        audio_started = session.playback.generated_ms > 0 or session.playback.sent_ms > 0
+        try:
+            candidate_config.apply_realtime_update(
+                payload,
+                session_id=session.session_id,
+                audio_started=audio_started,
+            )
+        except DuplexConfigError as exc:
+            self._out.emit_error(exc.code, str(exc) or "session.update was rejected", event_id=realtime_event_id)
+            reject_update()
+            return
+        if candidate_config.instructions != session.config.instructions and model_state.context_locked:
+            self._out.emit_error(
+                "instructions_update_unsupported",
+                "session.update cannot change instructions after the native duplex context is initialized",
+                event_id=realtime_event_id,
+            )
+            reject_update()
+            return
+        requests_audio = any(str(modality).lower() == "audio" for modality in candidate_config.modalities)
+        if (
+            requests_audio
+            and "ref_audio_data" not in session.runtime_config
+            and getattr(self._ctx.plugin, "requires_ref_audio", False)
+        ):
+            self._out.emit_error(
+                "ref_audio_required", "Native duplex audio output requires ref_audio", event_id=realtime_event_id
+            )
+            reject_update()
+            return
+        try:
+            candidate_runtime_config = self._ctx.plugin.runtime_config_for_update(
+                candidate_config,
+                dict(session.runtime_config),
+            )
+            # Validate the sampling policy for the candidate before adopting it.
+            self._ctx.plugin.configure_sampling_params(
+                runtime_config=dict(candidate_runtime_config),
+                defaults=tuple(self._ctx.stage_port.sampling_defaults()),
+            )
+        except (DuplexRuntimeConfigError, DuplexConfigError) as exc:
+            self._out.emit_error(exc.code, str(exc), event_id=realtime_event_id)
+            reject_update()
+            return
+        except Exception as exc:
+            self._out.emit_error("runtime_signal_failed", str(exc), event_id=realtime_event_id)
+            reject_update()
+            return
+        session.replace_config(candidate_config)
+        session.replace_runtime_config(candidate_runtime_config)
+        try:
+            session.touch_lease(DuplexLeaseActivity.SIGNAL)
+        except Exception:
+            pass
+        if pending_turn_detection is not None:
+            self._config, self._detector = pending_turn_detection.commit(self._detector)
+        projector = self._out.require_projector()
+        projector.apply_session_defaults(payload)
+        self._out.emit({"type": "session.updated", "session": session.as_public_dict()})
+
+    async def _on_conversation_item_create(self, event: dict[str, object]) -> None:
+        session = self._ctx.session
+        payload = event.get("payload")
+        item = payload.get("item") if isinstance(payload, dict) else None
+        item_type = item.get("type") if isinstance(item, dict) else None
+        if item_type == "function_call_output" and isinstance(item, dict):
+            if not await self._wait_for_append_tail():
+                return
+            try:
+                candidate_runtime_config = self._ctx.plugin.runtime_config_for_function_output(
+                    session.config,
+                    dict(session.runtime_config),
+                    item,
+                )
+            except DuplexRuntimeConfigError as exc:
+                self._out.emit_error(exc.code, str(exc))
+                return
+            if candidate_runtime_config is not None:
+                session.replace_runtime_config(candidate_runtime_config)
+            self._out.emit(
+                {
+                    "type": "conversation.item.created",
+                    "session_id": session.session_id,
+                    "item": item,
+                    "created": True,
+                }
+            )
+            self._ctx.services.spawn(
+                self._model.maybe_continue_response(
+                    expected_epoch=session.epoch,
+                    expected_model_turn_id=session.turn_id,
+                ),
+                name="duplex-continue",
+            )
+            return
+        message = realtime_item_to_history_message(item)
+        item_id = item.get("id") if isinstance(item, dict) else None
+        if message is not None:
+            session.append_history_message(message)
+            session.register_history_item(item_id if isinstance(item_id, str) else None, message)
+            if message.get("role") == "user":
+                # A later response.create may answer this without any audio.
+                session.notify_new_user_item()
+        self._out.emit(
+            {
+                "type": "conversation.item.created",
+                "session_id": session.session_id,
+                "item": item,
+                "created": message is not None,
+            }
+        )
diff --git a/vllm_omni/engine/duplex/session/emitter.py b/vllm_omni/engine/duplex/session/emitter.py
new file mode 100644
index 00000000000..508bc7ef1ce
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/emitter.py
@@ -0,0 +1,249 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Everything one duplex session sends to its client.
+
+Emission is the hub of the session runner: near enough every path through the
+runner ends in an event, which is why this is a collaborator rather than a
+module of functions. It owns three things the rest of the runner should not
+have to think about --- the Realtime projection state, the epoch filter that
+drops output from a superseded turn, and the domain transitions an outbound
+terminal event applies to the session before it is projected.
+
+The one thing it cannot own is what happens *after* a terminal promotes
+deferred overlap audio: that re-enters the mailbox of the runner, so the
+runner injects it as ``promote_deferred_overlap``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from vllm_omni.engine.duplex.config import DuplexSessionState
+from vllm_omni.engine.duplex.events import (
+    DOMAIN_TERMINAL_EVENTS,
+    MODEL_OUTPUT_EVENTS,
+    DuplexEvent,
+    error_event,
+)
+from vllm_omni.engine.duplex.realtime_events import (
+    RealtimeProjectionState,
+    discard_pending_input_audio,
+    project_internal_event,
+)
+from vllm_omni.engine.duplex.session import overlap_policy
+from vllm_omni.engine.duplex.session.context import DuplexSessionContext
+
+
+class SessionEmitter:
+    """Outbound events for one session."""
+
+    def __init__(
+        self,
+        ctx: DuplexSessionContext,
+        *,
+        promote_deferred_overlap: Callable[[dict[str, object], bool], None],
+    ) -> None:
+        self._ctx = ctx
+        self._promote_deferred_overlap = promote_deferred_overlap
+        self._projector: RealtimeProjectionState | None = ctx.session.projector
+
+    # ------------------------------------------------------------------ #
+    # Projection state                                                   #
+    # ------------------------------------------------------------------ #
+
+    @property
+    def projector(self) -> RealtimeProjectionState | None:
+        """The Realtime projection state, or ``None`` before anything needs it."""
+        return self._projector
+
+    @projector.setter
+    def projector(self, value: RealtimeProjectionState | None) -> None:
+        self._projector = value
+        self._ctx.session.projector = value
+
+    def require_projector(self) -> RealtimeProjectionState:
+        """The projection state, created on first use.
+
+        A session torn down before ``start()`` never builds one, so the lazy
+        path here is reachable rather than defensive.
+        """
+        projector = self._projector
+        if projector is None:
+            session = self._ctx.session
+            projector = RealtimeProjectionState(
+                session_id=session.session_id,
+                model=session.config.model,
+                initial_session_update=True,
+            )
+            self.projector = projector
+        return projector
+
+    # ------------------------------------------------------------------ #
+    # Sending                                                            #
+    # ------------------------------------------------------------------ #
+
+    def emit_events(self, events: list[DuplexEvent]) -> None:
+        for event in events:
+            self._ctx.manager.emit(self._ctx.session, event)
+
+    def emit_error(
+        self,
+        code: str,
+        message: str,
+        *,
+        event_id: object | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        """Send one typed ``error`` event (``event_id`` is the client event it answers)."""
+        extra = {} if retryable is None else {"retryable": retryable}
+        self.emit_events([error_event(code, message, event_id=event_id, extra=extra)])
+
+    def emit(self, payload: dict[str, object]) -> None:
+        """Apply the domain effects of an internal event, then project it to typed events and send them.
+
+        Only events with domain effects (response / cancel / close terminals) or
+        Realtime projection state (response items, content parts) still travel as
+        internal dictionaries; stateless events are constructed typed at the
+        emit site.
+        """
+        accepted, deferred_overlap_payload = self._apply_outbound_session_event(payload)
+        if not accepted:
+            return
+        self.emit_events(project_internal_event(self.require_projector(), payload))
+        if deferred_overlap_payload is not None and not self._ctx.run.closing:
+            precreate_response = self._ctx.model_state.deferred_precreate_response
+            self._ctx.model_state.deferred_precreate_response = False
+            self._promote_deferred_overlap(deferred_overlap_payload, precreate_response)
+
+    # ------------------------------------------------------------------ #
+    # Filtering and domain effects                                       #
+    # ------------------------------------------------------------------ #
+
+    def auto_responds(self) -> bool:
+        """Whether the session answers committed input without a ``response.create``."""
+        extra = getattr(self._ctx.session.config, "extra_body", None)
+        if not isinstance(extra, dict):
+            return False
+        return extra.get("auto_response") is True or extra.get("full_duplex") is True
+
+    def is_stale_model_output(self, payload: dict[str, object]) -> bool:
+        """Whether ``payload`` belongs to a turn the session has already moved past."""
+        session = self._ctx.session
+        event_type = payload.get("type")
+        if event_type in DOMAIN_TERMINAL_EVENTS:
+            return False
+        if event_type not in MODEL_OUTPUT_EVENTS:
+            return False
+        if self._ctx.run.closing and event_type != "response.listen":
+            return True
+        if session.state == DuplexSessionState.CLOSED and event_type != "response.listen":
+            return True
+        epoch = payload.get("epoch")
+        return isinstance(epoch, int) and epoch != session.epoch
+
+    def _apply_outbound_session_event(self, payload: dict[str, object]) -> tuple[bool, dict[str, object] | None]:
+        """Apply domain transitions before an event is projected (moved from serving)."""
+        session = self._ctx.session
+        model_state = self._ctx.model_state
+        payload_type = payload.get("type")
+        is_terminal = payload_type in DOMAIN_TERMINAL_EVENTS
+        if is_terminal:
+            payload_epoch = payload.get("epoch")
+            if isinstance(payload_epoch, int) and payload_epoch != session.epoch:
+                return False, None
+            if payload_type in {"response.done", "response.listen"} and (
+                self._ctx.run.closing or session.state == DuplexSessionState.CLOSED
+            ):
+                return False, None
+        elif self.is_stale_model_output(payload):
+            return False, None
+
+        if payload_type == "session.closed":
+            self._ctx.run.close_reason = self._ctx.run.close_reason or str(payload.get("reason") or "closed")
+            session.mark_closing()
+
+        if not is_terminal:
+            return True, None
+
+        terminal_status = payload.get("status")
+        terminal_status_details = payload.get("status_details")
+        if terminal_status is None and isinstance(terminal_status_details, dict):
+            terminal_status = terminal_status_details.get("type")
+        response_terminal = payload_type == "response.done" or (
+            payload_type == "response.listen" and session.active_response_id is not None
+        )
+        can_promote_overlap = response_terminal and terminal_status not in {"cancelled", "failed"}
+        deferred_overlap_payload: dict[str, object] | None = None
+        continuous_input_crosses_terminal = (
+            can_promote_overlap
+            and self.auto_responds()
+            and model_state.input_since_commit
+            and not model_state.deferred_response_create
+        )
+        if continuous_input_crosses_terminal:
+            session.reset_overlap_speech()
+            return True, None
+        realtime_input_still_open = (
+            can_promote_overlap and model_state.input_since_commit and not model_state.deferred_response_create
+        )
+        if realtime_input_still_open:
+            session.reset_overlap_speech()
+            return True, None
+        if can_promote_overlap and session.overlap_speech_ms > 0:
+            has_deferred_overlap = (
+                model_state.audio_buffer.has_pending() or model_state.committed_audio_payload is not None
+            )
+            should_promote_overlap = (
+                session.state == DuplexSessionState.OPEN
+                and has_deferred_overlap
+                and session.overlap_speech_ms > session.config.overlap_short_ack_ms
+            )
+            if should_promote_overlap:
+                flushed_reserved_bytes = model_state.audio_buffer.pending_byte_count
+                deferred_overlap_payload = model_state.audio_buffer.flush(
+                    chunk_period_ms=session.capabilities.chunk_period_ms or 1000
+                )
+                if model_state.committed_audio_payload is not None:
+                    if deferred_overlap_payload is not None:
+                        deferred_overlap_payload = overlap_policy.merge_audio_payloads(
+                            model_state.committed_audio_payload,
+                            deferred_overlap_payload,
+                        )
+                    else:
+                        deferred_overlap_payload = model_state.committed_audio_payload
+                if self.auto_responds() and deferred_overlap_payload is not None:
+                    deferred_overlap_payload = dict(deferred_overlap_payload)
+                    deferred_overlap_payload["force_listen"] = False
+                if deferred_overlap_payload is not None:
+                    model_state.retain_committed_audio(
+                        deferred_overlap_payload,
+                        operation_id=model_state.committed_audio_operation_id,
+                        reserved_bytes=flushed_reserved_bytes,
+                    )
+                model_state.input_since_commit = deferred_overlap_payload is not None
+                # Realtime path: defer the promoted response to the next terminal.
+                model_state.deferred_response_create = True
+                model_state.deferred_precreate_response = False
+                deferred_overlap_payload = None
+            else:
+                had_pending_overlap_audio = model_state.audio_buffer.has_pending()
+                model_state.audio_buffer.clear()
+                model_state.input_since_commit = False
+                model_state.speech_since_commit = False
+                if had_pending_overlap_audio and self._projector is not None:
+                    self.emit_events(discard_pending_input_audio(self._projector, session.overlap_speech_ms))
+                if payload_type in {"audio.cancelled", "input.cancelled", "session.closed"}:
+                    session.release_input_bytes(model_state.clear_committed_audio())
+
+        session.reset_overlap_speech()
+        if (
+            can_promote_overlap
+            and model_state.deferred_response_create
+            and model_state.committed_audio_payload is not None
+        ):
+            deferred_overlap_payload = model_state.committed_audio_payload
+            model_state.deferred_response_create = False
+            model_state.input_since_commit = False
+            model_state.speech_since_commit = False
+        return True, deferred_overlap_payload
diff --git a/vllm_omni/entrypoints/duplex/protocol.py b/vllm_omni/engine/duplex/session/engine_session.py
similarity index 56%
rename from vllm_omni/entrypoints/duplex/protocol.py
rename to vllm_omni/engine/duplex/session/engine_session.py
index 04218083818..bb5c3851594 100644
--- a/vllm_omni/entrypoints/duplex/protocol.py
+++ b/vllm_omni/engine/duplex/session/engine_session.py
@@ -1,411 +1,64 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
+"""The one duplex session state, owned by the engine-side ``DuplexSessionRunner``.
+
+``DuplexEngineSession`` is the single session object: the input / response /
+playback / conversation ledgers, the lease, the identity fence, the stage
+request resources, the append sequencing, the model plugin's per-session state
+(``model_state``) and the Realtime projection state (``projector``). There is
+no cross-boundary fence protocol; ``session.fence`` is derived from the
+session's own epoch/turn and ``accepted_fence`` is the monotonic high-water
+mark of fences accepted for stage requests (``sync_fence()`` publishes the
+current identity there).
+"""
+
 from __future__ import annotations
 
 import copy
-from collections.abc import Mapping
+import time
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
-from enum import Enum
 from types import MappingProxyType
+from typing import TYPE_CHECKING
 from uuid import uuid4
 
-import numpy as np
-
-from vllm_omni.entrypoints.duplex.audio import (
-    encode_float32_mono_wav_base64,
+from vllm_omni.engine.duplex.config import (
+    DuplexAssistantAudioTextMark,
+    DuplexCapabilities,
+    DuplexCommittedInput,
+    DuplexPlaybackCommitPolicy,
+    DuplexPlaybackCursor,
+    DuplexPlaybackView,
+    DuplexSessionConfig,
+    DuplexSessionState,
+    DuplexTurnEventType,
+    DuplexTurnState,
+    ResponseCreateOptions,
 )
-from vllm_omni.entrypoints.duplex.server_vad import (
-    ServerVADConfig,
-    parse_session_turn_detection,
+from vllm_omni.engine.duplex.contracts import DuplexFence
+from vllm_omni.engine.duplex.events import TurnEvent
+from vllm_omni.engine.duplex.session.lease import (
+    DuplexLeaseActivity,
+    DuplexLeaseConfig,
+    DuplexLeaseState,
 )
 
+if TYPE_CHECKING:
+    from vllm_omni.engine.duplex.plugin import DuplexModelSessionState
+    from vllm_omni.engine.duplex.realtime_events import RealtimeProjectionState
 
-class DuplexOverlapPolicy(str, Enum):
-    LISTEN_ONLY = "listen_only"
-    BARGE_IN_ON_SPEECH = "barge_in_on_speech"
-
-
-class DuplexPlaybackCommitPolicy(str, Enum):
-    COMMIT_ALL_ON_DONE = "commit_all_on_done"
-    ACK_ONLY = "ack_only"
-
-
-class DuplexSessionState(str, Enum):
-    OPEN = "open"
-    CLOSING = "closing"
-    CLOSED = "closed"
-
-
-# Canonical extra_body key for the per-session opt-in to a model-native
-# duplex runtime, plus the deprecated model-prefixed spelling it replaced.
-# Client payloads may still use the legacy key; it is folded into the
-# canonical one at ingestion so everything downstream (and every echo in
-# session.created/session.updated) sees only NATIVE_DUPLEX_KEY.
-NATIVE_DUPLEX_KEY = "native_duplex"
-LEGACY_NATIVE_DUPLEX_KEY = "minicpmo45_native_duplex"
-
-
-def normalize_native_duplex_key(extra_body: dict[str, object]) -> dict[str, object]:
-    """Fold the deprecated alias into the canonical key (canonical wins)."""
-    if LEGACY_NATIVE_DUPLEX_KEY in extra_body:
-        legacy = extra_body.pop(LEGACY_NATIVE_DUPLEX_KEY)
-        extra_body.setdefault(NATIVE_DUPLEX_KEY, legacy)
-    return extra_body
-
-
-def native_duplex_opt_in(extra_body: Mapping[str, object]) -> object:
-    """Read the opt-in flag, accepting the deprecated alias for raw dicts."""
-    if NATIVE_DUPLEX_KEY in extra_body:
-        return extra_body[NATIVE_DUPLEX_KEY]
-    return extra_body.get(LEGACY_NATIVE_DUPLEX_KEY)
-
-
-class DuplexTurnState(str, Enum):
-    IDLE = "idle"
-    USER_SPEAKING = "user_speaking"
-    USER_COMMITTED = "user_committed"
-    ASSISTANT_GENERATING = "assistant_generating"
-    ASSISTANT_PLAYING = "assistant_playing"
-    BARGE_IN = "barge_in"
-
-
-class DuplexTurnEventType(str, Enum):
-    USER_STARTED = "user_started"
-    USER_COMMITTED = "user_committed"
-    ASSISTANT_STARTED = "assistant_started"
-    ASSISTANT_DONE = "assistant_done"
-    BARGE_IN = "barge_in"
-    PLAYBACK_ACK = "playback_ack"
-    TIMEOUT = "timeout"
-    CLOSE = "close"
 
-
-@dataclass
-class DuplexCapabilities:
-    """Runtime/model capabilities exposed by the duplex serving protocol.
-
-    These are intentionally explicit so the serving layer does not assume all
-    duplex models support the same input append, rollback, or turn policy.
-    ``supports_core_kv_lease`` is reserved for scheduler-owned KV lifecycle;
-    model-owned decoder/TTS state must use ``supports_model_internal_state``.
-    ``supports_core_resumable_request`` means the scheduler can resume the
-    same request id across streaming updates, but it is not a KV lease by
-    itself. Realtime support means this endpoint can speak the native Realtime
-    event schema for the supported audio duplex paths while keeping model- or
-    scheduler-specific limits explicit in the capability payload.
-    """
-
-    supports_session_adapter: bool = True
-    supports_model_native_turn_policy: bool = False
-    supports_external_turn_signal: bool = True
-    supports_client_commit: bool = True
-    supports_barge_in: bool = True
-    supports_playback_ack: bool = True
-    supports_input_append: bool = False
-    supports_replace_latest_chunk: bool = True
-    supports_reencode_context: bool = True
-    supports_rollback_to_checkpoint: bool = False
-    supports_turn_commit_only: bool = True
-    supports_kv_lease: bool = False
-    supports_core_kv_lease: bool = False
-    supports_model_internal_state: bool = False
-    supports_stage_resumption: bool = False
-    supports_scheduler_native_append: bool = False
-    supports_core_resumable_request: bool = False
-    supports_stage_connector_handoff: bool = False
-    supports_independent_io_streams: bool = False
-    supports_realtime_endpoint: bool = False
-    supports_multi_session: bool = False
-    supports_multi_session_same_replica: bool = False
-    supports_session_lease: bool = False
-    supports_session_resume: bool = False
-    session_admission_mode: str = "serving_managed"
-    supports_audio_truncate: bool = False
-    requires_model_runner_kv: bool = False
-    requires_native_stage_role: bool = False
-    implementation_level: str = "serving_session_adapter"
-    adapter_patterns: list[str] = field(default_factory=lambda: ["chunk_group_append"])
-    input_modes: list[str] = field(default_factory=lambda: ["turn_commit_only", "reencode_context"])
-    signal_sources: list[str] = field(default_factory=lambda: ["client_event", "server_policy", "model_native"])
-    stage_handoff_transport: str | None = None
-    chunk_period_ms: int | None = 1000
-    target_barge_in_latency_ms: int | None = 1000
-
-    def as_dict(self) -> dict[str, object]:
-        return {
-            "supports_session_adapter": self.supports_session_adapter,
-            "supports_model_native_turn_policy": self.supports_model_native_turn_policy,
-            "supports_external_turn_signal": self.supports_external_turn_signal,
-            "supports_client_commit": self.supports_client_commit,
-            "supports_barge_in": self.supports_barge_in,
-            "supports_playback_ack": self.supports_playback_ack,
-            "supports_input_append": self.supports_input_append,
-            "supports_replace_latest_chunk": self.supports_replace_latest_chunk,
-            "supports_reencode_context": self.supports_reencode_context,
-            "supports_rollback_to_checkpoint": self.supports_rollback_to_checkpoint,
-            "supports_turn_commit_only": self.supports_turn_commit_only,
-            "supports_kv_lease": self.supports_kv_lease,
-            "supports_core_kv_lease": self.supports_core_kv_lease,
-            "supports_model_internal_state": self.supports_model_internal_state,
-            "supports_stage_resumption": self.supports_stage_resumption,
-            "supports_scheduler_native_append": self.supports_scheduler_native_append,
-            "supports_core_resumable_request": self.supports_core_resumable_request,
-            "supports_stage_connector_handoff": self.supports_stage_connector_handoff,
-            "supports_independent_io_streams": self.supports_independent_io_streams,
-            "supports_realtime_endpoint": self.supports_realtime_endpoint,
-            "supports_multi_session": self.supports_multi_session,
-            "supports_multi_session_same_replica": self.supports_multi_session_same_replica,
-            "supports_session_lease": self.supports_session_lease,
-            "supports_session_resume": self.supports_session_resume,
-            "session_admission_mode": self.session_admission_mode,
-            "supports_audio_truncate": self.supports_audio_truncate,
-            "requires_model_runner_kv": self.requires_model_runner_kv,
-            "requires_native_stage_role": self.requires_native_stage_role,
-            "implementation_level": self.implementation_level,
-            "adapter_patterns": self.adapter_patterns,
-            "input_modes": self.input_modes,
-            "signal_sources": self.signal_sources,
-            "stage_handoff_transport": self.stage_handoff_transport,
-            "chunk_period_ms": self.chunk_period_ms,
-            "target_barge_in_latency_ms": self.target_barge_in_latency_ms,
-        }
-
-
-@dataclass
-class DuplexPlaybackCursor:
-    generated_ms: int = 0
-    sent_ms: int = 0
-    played_ms: int = 0
-    committed_ms: int = 0
-    generated_frames: int = 0
-    sample_rate_hz: int | None = None
-
-    def acknowledge(self, played_ms: int, committed_ms: int | None = None) -> None:
-        self.played_ms = max(self.played_ms, max(0, int(played_ms)))
-        if committed_ms is None:
-            committed_ms = self.played_ms
-        self.committed_ms = max(self.committed_ms, max(0, int(committed_ms)))
-
-    def truncate_committed(self, committed_ms: int) -> None:
-        self.committed_ms = max(0, min(max(self.sent_ms, self.generated_ms), int(committed_ms)))
-
-    def as_dict(self) -> dict[str, int]:
-        return {
-            "generated_ms": self.generated_ms,
-            "sent_ms": self.sent_ms,
-            "played_ms": self.played_ms,
-            "committed_ms": self.committed_ms,
-        }
-
-    def snapshot(self) -> DuplexPlaybackView:
-        return DuplexPlaybackView(**self.as_dict())
-
-
-@dataclass(frozen=True, slots=True)
-class DuplexPlaybackView:
-    generated_ms: int = 0
-    sent_ms: int = 0
-    played_ms: int = 0
-    committed_ms: int = 0
-
-    def as_dict(self) -> dict[str, int]:
-        return {
-            "generated_ms": self.generated_ms,
-            "sent_ms": self.sent_ms,
-            "played_ms": self.played_ms,
-            "committed_ms": self.committed_ms,
-        }
-
-
-@dataclass
-class DuplexAudioChunk:
-    data: str
-    format: str = "wav"
-    sample_rate_hz: int | None = None
-
-
-@dataclass
-class DuplexSessionConfig:
-    model: str | None = None
-    modalities: list[str] = field(default_factory=lambda: ["text", "audio"])
-    instructions: str | None = None
-    voice: str | None = None
-    ref_audio: str | None = None
-    response_format: str = "wav"
-    temperature: float | None = None
-    max_tokens: int | None = None
-    speed: float | None = None
-    use_tts_template: bool = True
-    idle_timeout_s: float = 300.0
-    overlap_policy: str = DuplexOverlapPolicy.LISTEN_ONLY.value
-    overlap_short_ack_ms: int = 700
-    overlap_barge_in_ms: int = 1200
-    overlap_silence_rms: float = 0.003
-    playback_commit_policy: str = DuplexPlaybackCommitPolicy.COMMIT_ALL_ON_DONE.value
-    turn_detection_configured: bool = False
-    server_vad: ServerVADConfig | None = None
-    extra_body: dict[str, object] = field(default_factory=dict)
-
-    def as_dict(self) -> dict[str, object]:
-        payload: dict[str, object] = {
-            "model": self.model,
-            "modalities": list(self.modalities),
-            "instructions": self.instructions,
-            "voice": self.voice,
-            "ref_audio": self.ref_audio,
-            "response_format": self.response_format,
-            "temperature": self.temperature,
-            "max_tokens": self.max_tokens,
-            "speed": self.speed,
-            "use_tts_template": self.use_tts_template,
-            "idle_timeout_s": self.idle_timeout_s,
-            "overlap_policy": self.overlap_policy,
-            "overlap_short_ack_ms": self.overlap_short_ack_ms,
-            "overlap_barge_in_ms": self.overlap_barge_in_ms,
-            "overlap_silence_rms": self.overlap_silence_rms,
-            "playback_commit_policy": self.playback_commit_policy,
-            "extra_body": dict(self.extra_body),
-        }
-        if self.turn_detection_configured:
-            payload["turn_detection"] = self.server_vad.as_dict() if self.server_vad is not None else None
-        return payload
-
-    @classmethod
-    def from_event(cls, event: dict[str, object]) -> DuplexSessionConfig:
-        payload = event.get("session")
-        if isinstance(payload, dict):
-            source = payload
-        else:
-            source = event
-
-        config = cls()
-        if isinstance(source.get("model"), str):
-            config.model = source["model"]
-        if isinstance(source.get("instructions"), str):
-            config.instructions = source["instructions"]
-        if isinstance(source.get("voice"), str):
-            config.voice = source["voice"]
-        if isinstance(source.get("ref_audio"), str):
-            config.ref_audio = source["ref_audio"]
-        if isinstance(source.get("response_format"), str):
-            config.response_format = source["response_format"]
-        if isinstance(source.get("use_tts_template"), bool):
-            config.use_tts_template = bool(source["use_tts_template"])
-        if isinstance(source.get("temperature"), int | float):
-            config.temperature = float(source["temperature"])
-        if isinstance(source.get("max_tokens"), int):
-            config.max_tokens = int(source["max_tokens"])
-        if isinstance(source.get("speed"), int | float):
-            config.speed = float(source["speed"])
-        if isinstance(source.get("idle_timeout_s"), int | float):
-            config.idle_timeout_s = float(source["idle_timeout_s"])
-        if isinstance(source.get("overlap_policy"), str):
-            config.overlap_policy = cls._normalize_overlap_policy(source["overlap_policy"])
-        if isinstance(source.get("overlap_short_ack_ms"), int | float):
-            config.overlap_short_ack_ms = max(0, int(source["overlap_short_ack_ms"]))
-        if isinstance(source.get("overlap_barge_in_ms"), int | float):
-            config.overlap_barge_in_ms = max(0, int(source["overlap_barge_in_ms"]))
-        if isinstance(source.get("overlap_silence_rms"), int | float):
-            config.overlap_silence_rms = max(0.0, float(source["overlap_silence_rms"]))
-        if isinstance(source.get("playback_commit_policy"), str):
-            config.playback_commit_policy = cls._normalize_playback_commit_policy(source["playback_commit_policy"])
-        if isinstance(source.get("modalities"), list) and all(isinstance(x, str) for x in source["modalities"]):
-            config.modalities = list(source["modalities"])
-        turn_detection_configured, server_vad = parse_session_turn_detection(source)
-        if isinstance(source.get("extra_body"), dict):
-            config.extra_body = normalize_native_duplex_key(dict(source["extra_body"]))
-            extra = config.extra_body
-            raw_realtime_session = extra.get("realtime_session_payload")
-            if not turn_detection_configured and isinstance(raw_realtime_session, dict):
-                turn_detection_configured, server_vad = parse_session_turn_detection(raw_realtime_session)
-            if isinstance(extra.get("overlap_policy"), str):
-                config.overlap_policy = cls._normalize_overlap_policy(extra["overlap_policy"])
-            if isinstance(extra.get("overlap_short_ack_ms"), int | float):
-                config.overlap_short_ack_ms = max(0, int(extra["overlap_short_ack_ms"]))
-            if isinstance(extra.get("overlap_barge_in_ms"), int | float):
-                config.overlap_barge_in_ms = max(0, int(extra["overlap_barge_in_ms"]))
-            if isinstance(extra.get("overlap_silence_rms"), int | float):
-                config.overlap_silence_rms = max(0.0, float(extra["overlap_silence_rms"]))
-            if isinstance(extra.get("playback_commit_policy"), str):
-                config.playback_commit_policy = cls._normalize_playback_commit_policy(extra["playback_commit_policy"])
-        if turn_detection_configured:
-            config.turn_detection_configured = True
-            config.server_vad = server_vad
-        return config
-
-    @staticmethod
-    def _normalize_overlap_policy(value: str) -> str:
-        normalized = value.strip().lower()
-        if normalized in {policy.value for policy in DuplexOverlapPolicy}:
-            return normalized
-        return DuplexOverlapPolicy.LISTEN_ONLY.value
-
-    @staticmethod
-    def _normalize_playback_commit_policy(value: str) -> str:
-        normalized = value.strip().lower()
-        if normalized in {policy.value for policy in DuplexPlaybackCommitPolicy}:
-            return normalized
-        return DuplexPlaybackCommitPolicy.COMMIT_ALL_ON_DONE.value
-
-
-@dataclass(frozen=True)
-class ResponseCreateOptions:
-    instructions: str | None = None
-    voice: str | None = None
-    response_format: str | None = None
-    temperature: float | None = None
-    max_tokens: int | None = None
-    speed: float | None = None
-    modalities: tuple[str, ...] | None = None
-    extra_body: Mapping[str, object] = field(default_factory=dict)
-
-    def apply_to(self, config: DuplexSessionConfig) -> None:
-        for field_name in ("instructions", "voice", "response_format", "temperature", "max_tokens", "speed"):
-            value = getattr(self, field_name)
-            if value is not None:
-                setattr(config, field_name, value)
-        if self.modalities is not None:
-            config.modalities = list(self.modalities)
-        config.extra_body.update(self.extra_body)
-
-
-@dataclass
-class DuplexCommittedInput:
-    message: dict[str, object]
-    turn_id: int
-    epoch: int
-    input_commit_seq: int
-
-
-@dataclass
-class PendingServerVADTurn:
-    committed: DuplexCommittedInput
-    create_response: bool
-    item_id: str
-
-
-@dataclass
-class DuplexAssistantAudioTextMark:
-    text_chars: int
-    audio_end_ms: int
+def _default_lease() -> DuplexLeaseState:
+    return DuplexLeaseState(config=DuplexLeaseConfig(), generation=0, last_activity=time.monotonic())
 
 
 @dataclass
 class InputBufferState:
     commit_seq: int = 0
-    pending_text: list[str] = field(default_factory=list)
-    pending_audio: list[DuplexAudioChunk] = field(default_factory=list)
     overlap_speech_ms: int = 0
     reserved_input_bytes: int = 0
     pending_turns: int = 0
-    turn_detection_config_locked: bool = False
-    vad_prefix_audio: list[np.ndarray] = field(default_factory=list)
-    vad_prefix_samples: int = 0
-    vad_utterance_audio: list[np.ndarray] = field(default_factory=list)
-    vad_speech_active: bool = False
-    active_server_vad_item_id: str | None = None
-    pending_server_vad_turn: PendingServerVADTurn | None = None
 
 
 @dataclass
@@ -413,10 +66,6 @@ class ResponseState:
     active_request_id: str | None = None
     active_response_id: str | None = None
     active_response_turn_id: int | None = None
-    request_started_at_s_by_turn: dict[int, float] = field(default_factory=dict)
-    active_response_request_started_at_s: float | None = None
-    active_response_ttft_ms: float | None = None
-    active_response_ttfp_ms: float | None = None
     active_response_input_commit_seq: int | None = None
     active_response_awaits_input_commit: bool = False
     last_response_id: str | None = None
@@ -439,6 +88,10 @@ class PlaybackLedger:
 @dataclass
 class ConversationHistory:
     messages: list[dict[str, object]] = field(default_factory=list)
+    #: User items added by ``conversation.item.create`` that no response has
+    #: answered yet. A turn can start from these alone, the way the Realtime
+    #: protocol allows, without any audio having been committed.
+    unanswered_user_items: int = 0
     item_ids: dict[str, dict[str, object]] = field(default_factory=dict)
     history_item_placeholders: dict[str, dict[str, object]] = field(default_factory=dict)
     item_audio_text_marks: dict[str, list[DuplexAssistantAudioTextMark]] = field(default_factory=dict)
@@ -454,21 +107,264 @@ class ConversationHistory:
     )
 
 
+class DuplexFenceMismatchError(RuntimeError):
+    def __init__(self, expected: DuplexFence, actual: DuplexFence) -> None:
+        super().__init__(f"duplex fence mismatch: expected {expected!r}, got {actual!r}")
+        self.expected = expected
+        self.actual = actual
+
+
+@dataclass
+class DuplexRequestResource:
+    stage_id: int
+    request_id: str
+    fence: DuplexFence
+    submitted: bool = False
+
+
 @dataclass
-class DuplexSession:
+class DuplexInputAppend:
+    seq: int
+    turn_seq: int
+    turn_id: int
+
+
+@dataclass(frozen=True)
+class DuplexAppendReservation:
+    fence: DuplexFence
+    base_fence: DuplexFence
+    base_input_seq: int
+    base_input_turn_seq: int
+    base_append_turn_key: tuple[int, int, int] | None
+    update: DuplexInputAppend
+
+
+@dataclass
+class DuplexEngineSession:
+    """The one session state (see module docstring).
+
+    Owned and mutated only by its ``DuplexSessionRunner`` on the orchestrator loop.
+    """
+
     session_id: str
     config: DuplexSessionConfig
     capabilities: DuplexCapabilities = field(default_factory=DuplexCapabilities)
-    incarnation: int = 0
     state: DuplexSessionState = DuplexSessionState.OPEN
     turn_state: DuplexTurnState = DuplexTurnState.IDLE
     epoch: int = 0
     turn_id: int = 0
+    lease: DuplexLeaseState = field(default_factory=_default_lease, repr=False)
+    _clock: Callable[[], float] = field(default=time.monotonic, repr=False)
+    _runtime_config: dict[str, object] = field(default_factory=dict, repr=False)
+    #: Bumped on every published session / runtime config change.
+    config_generation: int = 0
+    #: Stage request ids reserved or submitted for this session, keyed by ``(stage_id, request_id)``.
+    request_resources: dict[tuple[int, str], DuplexRequestResource] = field(default_factory=dict, repr=False)
+    #: Highest fence accepted for a stage request (monotonic; reset of the append
+    #: sequence happens when its epoch advances).
+    accepted_fence: DuplexFence = field(default=None, repr=False)  # type: ignore[assignment]
+    input_seq: int = 0
+    input_turn_seq: int = 0
+    _append_turn_key: tuple[int, int, int] | None = field(default=None, repr=False)
     _input: InputBufferState = field(default_factory=InputBufferState, repr=False)
     _response: ResponseState = field(default_factory=ResponseState, repr=False)
+    #: Stage snapshots that arrived while no response was open. A stage whose
+    #: output feeds the next stage rather than the client reports its metrics
+    #: before the response those tokens end up in exists, so they are held here
+    #: and folded into the first response that opens after them.
+    _pending_stage_metrics: list[dict[str, dict[str, object]]] = field(default_factory=list, repr=False)
     _playback: PlaybackLedger = field(default_factory=PlaybackLedger, repr=False)
     _conversation: ConversationHistory = field(default_factory=ConversationHistory, repr=False)
-    _runtime_config: dict[str, object] = field(default_factory=dict, repr=False)
+    model_state: DuplexModelSessionState | None = field(default=None, repr=False)
+    projector: RealtimeProjectionState | None = field(default=None, repr=False)
+    created_monotonic: float = field(default_factory=time.monotonic)
+
+    def __post_init__(self) -> None:
+        if self.accepted_fence is None:
+            self.accepted_fence = self.fence
+        else:
+            self.accept_fence(self.fence)
+        if self.config.initial_user_text:
+            # Seeded text is user input like any other: it waits for a response.
+            self.notify_new_user_item()
+
+    # ---- identity / fence ----
+
+    @property
+    def fence(self) -> DuplexFence:
+        return DuplexFence(self.session_id, epoch=self.epoch, turn_id=self.turn_id)
+
+    def sync_fence(self) -> DuplexFence:
+        """Publish the current (epoch, turn_id) identity as the accepted fence."""
+        fence = self.fence
+        self.accept_fence(fence)
+        return fence
+
+    def _validate_fence(self, fence: DuplexFence) -> None:
+        current = self.accepted_fence
+        if fence.session_id != self.session_id:
+            raise DuplexFenceMismatchError(current, fence)
+        if fence.epoch < current.epoch or (fence.epoch == current.epoch and fence.turn_id < current.turn_id):
+            raise DuplexFenceMismatchError(current, fence)
+
+    def accept_fence(self, fence: DuplexFence) -> None:
+        self._validate_fence(fence)
+        if fence.epoch != self.accepted_fence.epoch:
+            self.input_seq = 0
+            self.input_turn_seq = 0
+            self._append_turn_key = None
+        self.accepted_fence = fence
+
+    # ---- lease ----
+
+    @property
+    def lease_generation(self) -> int:
+        return self.lease.generation
+
+    def touch_lease(self, activity: DuplexLeaseActivity) -> None:
+        self._validate_fence(self.fence)
+        self.lease.touch(self._clock(), activity)
+
+    def detach_lease(self) -> None:
+        self._validate_fence(self.fence)
+        self.lease.detach(self._clock())
+
+    def resume_lease(self, *, expected_lease_generation: int) -> int:
+        self._validate_fence(self.fence)
+        return self.lease.resume(self._clock(), expected_generation=expected_lease_generation)
+
+    def begin_lease_operation(self, fence: DuplexFence, operation_id: str) -> None:
+        self._validate_fence(fence)
+        self.lease.begin_operation(self._clock(), operation_id)
+
+    def end_lease_operation(self, operation_id: str) -> None:
+        self._validate_fence(self.fence)
+        self.lease.end_operation(self._clock(), operation_id)
+
+    # ---- stage request resources ----
+
+    def reserve_stage_request(self, stage_id: int, request_id: str, *, fence: DuplexFence) -> None:
+        self._validate_fence(fence)
+        resource_key = (stage_id, request_id)
+        existing = self.request_resources.get(resource_key)
+        if existing is not None:
+            if existing.fence.session_id != fence.session_id or existing.fence.epoch != fence.epoch:
+                raise ValueError(f"Duplex request resource already reserved with different identity: {request_id}")
+            return
+        self.request_resources[resource_key] = DuplexRequestResource(
+            stage_id=stage_id,
+            request_id=request_id,
+            fence=fence,
+        )
+
+    def bind_stage_request(self, stage_id: int, request_id: str, *, fence: DuplexFence) -> None:
+        self.reserve_stage_request(stage_id, request_id, fence=fence)
+        self.accept_fence(fence)
+        resource = self.request_resources[(stage_id, request_id)]
+        resource.fence = fence
+        resource.submitted = True
+
+    def stage_request_submitted(self, stage_id: int, request_id: str) -> bool:
+        resource = self.request_resources.get((stage_id, request_id))
+        return resource is not None and resource.submitted
+
+    def resource_request_ids(
+        self,
+        fence: DuplexFence | None = None,
+        *,
+        submitted: bool | None = None,
+    ) -> list[str]:
+        return list(
+            dict.fromkeys(
+                resource.request_id
+                for resource in self.request_resources.values()
+                if (fence is None or resource.fence == fence) and (submitted is None or resource.submitted is submitted)
+            )
+        )
+
+    def release_all_requests(self) -> list[str]:
+        """Drop every reserved/submitted stage request; returns their ids for stage cleanup."""
+        stale = self.resource_request_ids()
+        self.request_resources.clear()
+        return stale
+
+    # ---- append sequencing ----
+
+    def prepare_append(self, fence: DuplexFence) -> DuplexAppendReservation:
+        self._validate_fence(fence)
+        same_epoch = fence.epoch == self.accepted_fence.epoch
+        input_seq = self.input_seq if same_epoch else 0
+        input_turn_seq = self.input_turn_seq if same_epoch else 0
+        append_turn_key = self._append_turn_key if same_epoch else None
+        turn_key = (fence.epoch, fence.turn_id, 0)
+        turn_seq = input_turn_seq + 1 if turn_key == append_turn_key else 1
+        return DuplexAppendReservation(
+            fence=fence,
+            base_fence=self.accepted_fence,
+            base_input_seq=self.input_seq,
+            base_input_turn_seq=self.input_turn_seq,
+            base_append_turn_key=self._append_turn_key,
+            update=DuplexInputAppend(
+                seq=input_seq + 1,
+                turn_seq=turn_seq,
+                turn_id=fence.turn_id,
+            ),
+        )
+
+    def commit_append(self, reservation: DuplexAppendReservation) -> DuplexInputAppend:
+        if (
+            self.accepted_fence != reservation.base_fence
+            or self.input_seq != reservation.base_input_seq
+            or self.input_turn_seq != reservation.base_input_turn_seq
+            or self._append_turn_key != reservation.base_append_turn_key
+        ):
+            raise RuntimeError("duplex append reservation is stale")
+        self.accept_fence(reservation.fence)
+        self.input_seq = reservation.update.seq
+        self.input_turn_seq = reservation.update.turn_seq
+        self._append_turn_key = (reservation.fence.epoch, reservation.fence.turn_id, 0)
+        return reservation.update
+
+    # ---- cancel / close of stage resources ----
+
+    def release_fence(self, fence: DuplexFence) -> list[str]:
+        stale = self.resource_request_ids(fence)
+        self.request_resources = {
+            resource_key: resource
+            for resource_key, resource in self.request_resources.items()
+            if resource.fence != fence
+        }
+        return stale
+
+    def cancel_fence(self, cancelled_fence: DuplexFence, next_fence: DuplexFence) -> list[str]:
+        stale = self.prepare_cancel_fence(cancelled_fence, next_fence)
+        self.release_fence(cancelled_fence)
+        return stale
+
+    def prepare_cancel_fence(self, cancelled_fence: DuplexFence, next_fence: DuplexFence) -> list[str]:
+        """Advance the cancellation fence without dropping cleanup records."""
+        current = self.accepted_fence
+        if cancelled_fence.session_id != self.session_id:
+            raise DuplexFenceMismatchError(current, cancelled_fence)
+        if next_fence.session_id != self.session_id or next_fence.epoch <= cancelled_fence.epoch:
+            raise DuplexFenceMismatchError(cancelled_fence, next_fence)
+        current_key = (current.epoch, current.turn_id)
+        cancelled_key = (cancelled_fence.epoch, cancelled_fence.turn_id)
+        next_key = (next_fence.epoch, next_fence.turn_id)
+        if cancelled_key > current_key:
+            raise DuplexFenceMismatchError(current, cancelled_fence)
+        if next_key > current_key:
+            self.accept_fence(next_fence)
+        return self.resource_request_ids(cancelled_fence)
+
+    def begin_close(self, *, reason: str) -> bool:
+        """Make close irreversible while retaining stage resources for cleanup retry."""
+        self.accept_fence(self.fence)
+        if self.lease.terminal_reason is not None:
+            return True
+        return self.lease.mark_terminal(reason)
+
+    # ---- configuration ----
 
     @property
     def response_config(self) -> DuplexSessionConfig:
@@ -486,19 +382,12 @@ def runtime_config(self) -> Mapping[str, object]:
 
     def replace_runtime_config(self, runtime_config: Mapping[str, object]) -> None:
         self._runtime_config = dict(runtime_config)
+        self.config_generation += 1
 
     @property
     def input_commit_seq(self) -> int:
         return self._input.commit_seq
 
-    @property
-    def pending_text(self) -> tuple[str, ...]:
-        return tuple(self._input.pending_text)
-
-    @property
-    def pending_audio(self) -> tuple[DuplexAudioChunk, ...]:
-        return tuple(self._input.pending_audio)
-
     @property
     def history(self) -> tuple[dict[str, object], ...]:
         placeholders = {id(message) for message in self._conversation.history_item_placeholders.values()}
@@ -620,10 +509,6 @@ def release_response_history_snapshot(self, response_id: str | None) -> None:
     def playback(self) -> DuplexPlaybackView:
         return self._playback.current.snapshot()
 
-    @property
-    def response_playbacks(self) -> Mapping[str, DuplexPlaybackView]:
-        return MappingProxyType({key: value.snapshot() for key, value in self._playback.by_response.items()})
-
     @property
     def history_item_ids(self) -> Mapping[str, dict[str, object]]:
         return MappingProxyType({key: dict(value) for key, value in self._conversation.item_ids.items()})
@@ -637,10 +522,11 @@ def pending_history_truncations_ms(self) -> Mapping[str, int]:
         return MappingProxyType(dict(self._conversation.pending_truncations_ms))
 
     def replace_config(self, config: DuplexSessionConfig) -> None:
+        previous_seed = self.config.initial_user_text
         self.config = config
-
-    def replace_capabilities(self, capabilities: DuplexCapabilities) -> None:
-        self.capabilities = capabilities
+        self.config_generation += 1
+        if config.initial_user_text and config.initial_user_text != previous_seed:
+            self.notify_new_user_item()
 
     def transition_turn(self, state: DuplexTurnState) -> None:
         self.turn_state = state
@@ -660,45 +546,6 @@ def clear_request(self, expected_request_id: str | None = None) -> bool:
     def bind_response_turn(self, turn_id: int | None) -> None:
         self._response.active_response_turn_id = turn_id
 
-    def mark_model_turn_request_started(self, turn_id: int, started_at_s: float) -> None:
-        """Record the latest native request start that can own one model turn."""
-        turn_id = int(turn_id)
-        started_at_s = float(started_at_s)
-        if self.active_response_turn_id == turn_id:
-            if self._response.active_response_request_started_at_s is None:
-                self._response.active_response_request_started_at_s = started_at_s
-            return
-        self._response.request_started_at_s_by_turn[turn_id] = started_at_s
-
-    def mark_response_first_outputs(
-        self,
-        *,
-        observed_at_s: float,
-        has_text: bool,
-        has_audio: bool,
-    ) -> dict[str, object]:
-        """Return server-monotonic TTF metrics observed for the active response."""
-        started_at_s = self._response.active_response_request_started_at_s
-        if started_at_s is None:
-            return {}
-        elapsed_ms = max(0.0, (float(observed_at_s) - started_at_s) * 1000.0)
-        if has_text and self._response.active_response_ttft_ms is None:
-            self._response.active_response_ttft_ms = elapsed_ms
-        if has_audio and self._response.active_response_ttfp_ms is None:
-            self._response.active_response_ttfp_ms = elapsed_ms
-        metrics: dict[str, object] = {
-            "source": "server_monotonic_request_start",
-            "measurement_origin": {
-                "ttft": "native model-turn request execution start to first non-empty text output",
-                "ttfp": "native model-turn request execution start to first audio output",
-            },
-        }
-        if self._response.active_response_ttft_ms is not None:
-            metrics["ttft_ms"] = self._response.active_response_ttft_ms
-        if self._response.active_response_ttfp_ms is not None:
-            metrics["ttfp_ms"] = self._response.active_response_ttfp_ms
-        return metrics
-
     def active_response_accepts_model_turn(self, turn_id: int | None) -> bool:
         if self._response.active_response_id is None:
             return False
@@ -708,19 +555,19 @@ def active_response_accepts_model_turn(self, turn_id: int | None) -> bool:
         return active_turn_id is None or int(turn_id) == active_turn_id
 
     def append_history_message(self, message: dict[str, object]) -> None:
-        response_id = self.active_response_id
-        if response_id is not None:
-            self.reserve_history_item(f"item_{response_id}")
         self._conversation.messages.append(message)
 
-    def stage_pending_history_item(self, item_id: str, message: dict[str, object]) -> None:
-        self._conversation.pending_item_ids[item_id] = dict(message)
+    def notify_new_user_item(self) -> None:
+        """Record a user item that a later ``response.create`` may answer."""
+        self._conversation.unanswered_user_items += 1
 
-    def append_text(self, text: str) -> None:
-        if not text:
-            return
-        self._input.pending_text.append(text)
-        self.turn_state = DuplexTurnState.USER_SPEAKING
+    def unanswered_user_items(self) -> int:
+        """How many user items are waiting for a response."""
+        return self._conversation.unanswered_user_items
+
+    def reset_unanswered_user_items(self) -> None:
+        """A turn has started: the pending items are now its input."""
+        self._conversation.unanswered_user_items = 0
 
     @property
     def pending_input_bytes(self) -> int:
@@ -737,13 +584,6 @@ def reserve_input_bytes(self, size: int, *, limit: int) -> bool:
         self._input.reserved_input_bytes += size
         return True
 
-    @property
-    def turn_detection_config_locked(self) -> bool:
-        return self._input.turn_detection_config_locked
-
-    def lock_turn_detection_config(self) -> None:
-        self._input.turn_detection_config_locked = True
-
     def release_input_bytes(self, size: int) -> None:
         self._input.reserved_input_bytes = max(0, self._input.reserved_input_bytes - max(0, int(size)))
 
@@ -759,200 +599,18 @@ def reserve_pending_turn(self, *, limit: int) -> bool:
     def release_pending_turn(self) -> None:
         self._input.pending_turns = max(0, self._input.pending_turns - 1)
 
-    def clear_pending_turn_reservations(self) -> None:
-        self._input.pending_turns = 0
-
-    def append_audio(self, data: str, *, fmt: str = "wav", sample_rate_hz: int | None = None) -> None:
-        if not data:
-            return
-        self._input.pending_audio.append(DuplexAudioChunk(data=data, format=fmt, sample_rate_hz=sample_rate_hz))
-        self.turn_state = DuplexTurnState.USER_SPEAKING
-
-    def append_server_vad_frame(
-        self,
-        samples: np.ndarray,
-        *,
-        speech_started: bool,
-        speech_stopped: bool,
-        prefix_samples: int,
-    ) -> int:
-        """Store one detector frame while keeping commit-eligible audio session-owned.
-
-        Returns the number of raw float32 bytes released when the rolling
-        pre-speech prefix is trimmed.
-        """
-        # Session-owned audio must not retain the batch backing a detector frame.
-        frame = np.array(samples, dtype=np.float32, copy=True).reshape(-1)
-        released_samples = 0
-        if not self._input.vad_speech_active:
-            if speech_started:
-                self._input.vad_utterance_audio = [*self._input.vad_prefix_audio, frame]
-                self._input.vad_prefix_audio = []
-                self._input.vad_prefix_samples = 0
-                self._input.vad_speech_active = True
-            else:
-                self._input.vad_prefix_audio.append(frame)
-                self._input.vad_prefix_samples += frame.size
-                while self._input.vad_prefix_samples > prefix_samples and self._input.vad_prefix_audio:
-                    overflow = self._input.vad_prefix_samples - prefix_samples
-                    first = self._input.vad_prefix_audio[0]
-                    if first.size <= overflow:
-                        self._input.vad_prefix_audio.pop(0)
-                        self._input.vad_prefix_samples -= first.size
-                        released_samples += first.size
-                    else:
-                        self._input.vad_prefix_audio[0] = first[overflow:].copy()
-                        self._input.vad_prefix_samples -= overflow
-                        released_samples += overflow
-        else:
-            self._input.vad_utterance_audio.append(frame)
-
-        if speech_stopped:
-            self._input.vad_speech_active = False
-        if self._input.vad_speech_active or speech_started:
-            self.turn_state = DuplexTurnState.USER_SPEAKING
-        return released_samples * np.dtype(np.float32).itemsize
-
-    def stage_server_vad_audio_for_commit(self) -> bool:
-        if not self._input.vad_utterance_audio:
-            return False
-        samples = np.concatenate(self._input.vad_utterance_audio)
-        encoded = encode_float32_mono_wav_base64(samples, sample_rate_hz=16_000)
-        self._input.pending_audio.append(DuplexAudioChunk(data=encoded, format="wav", sample_rate_hz=16_000))
-        self._input.vad_utterance_audio.clear()
-        self._input.vad_speech_active = False
-        return True
-
-    def clear_server_vad_audio(self) -> None:
-        self._input.vad_prefix_audio.clear()
-        self._input.vad_prefix_samples = 0
-        self._input.vad_utterance_audio.clear()
-        self._input.vad_speech_active = False
-        self._input.active_server_vad_item_id = None
-
-    @property
-    def active_server_vad_item_id(self) -> str | None:
-        return self._input.active_server_vad_item_id
-
-    @property
-    def server_vad_utterance_bytes(self) -> int:
-        return sum(frame.nbytes for frame in self._input.vad_utterance_audio)
-
-    def discard_uncommitted_server_vad_utterance(self) -> int:
-        released = self.server_vad_utterance_bytes
-        self._input.vad_utterance_audio.clear()
-        self._input.vad_speech_active = False
-        self._input.active_server_vad_item_id = None
-        self._input.pending_text.clear()
-        return released
-
-    def begin_server_vad_speech(self, item_id: str) -> None:
-        self._input.active_server_vad_item_id = item_id
-
-    def finish_server_vad_speech(self) -> str | None:
-        item_id = self._input.active_server_vad_item_id
-        self._input.active_server_vad_item_id = None
-        return item_id
-
     def mark_user_input_activity(self) -> None:
         self.turn_state = DuplexTurnState.USER_SPEAKING
 
-    def mark_assistant_generating(self) -> None:
-        self.turn_state = DuplexTurnState.ASSISTANT_GENERATING
-
     def cancel_pending_input(self) -> dict[str, int]:
-        cancelled = {
-            "text_chunks": len(self._input.pending_text),
-            "audio_chunks": len(self._input.pending_audio),
-        }
-        self._input.pending_text.clear()
-        self._input.pending_audio.clear()
+        """Drop every pending reservation; the PCM buffer itself is model state cleared by the runner."""
+        cancelled = {"text_chunks": 0, "audio_chunks": 0}
         self._input.reserved_input_bytes = 0
         self._input.pending_turns = 0
-        self.clear_server_vad_audio()
         self.turn_state = DuplexTurnState.IDLE
         return cancelled
 
-    def commit_user_input(
-        self,
-        *,
-        append_history: bool = True,
-        retain_input_bytes: int = 0,
-    ) -> DuplexCommittedInput | None:
-        text = "".join(self._input.pending_text).strip()
-        audio_chunks = list(self._input.pending_audio)
-        if not text and not audio_chunks:
-            return None
-
-        content: str | list[dict[str, object]]
-        if audio_chunks:
-            content_items: list[dict[str, object]] = []
-            if text:
-                content_items.append({"type": "text", "text": text})
-            for chunk in audio_chunks:
-                content_items.append(
-                    {
-                        "type": "audio_url",
-                        "audio_url": {
-                            "url": f"data:audio/{chunk.format};base64,{chunk.data}",
-                        },
-                    }
-                )
-            content = content_items
-        else:
-            content = text
-
-        self._bind_active_response_to_input_commit(self._input.commit_seq + 1)
-        self._input.commit_seq += 1
-        message = {"role": "user", "content": content}
-        if append_history:
-            self._conversation.messages.append(message)
-        self._input.pending_text.clear()
-        self._input.pending_audio.clear()
-        self._input.reserved_input_bytes = max(0, int(retain_input_bytes))
-        self.turn_state = DuplexTurnState.USER_COMMITTED
-        return DuplexCommittedInput(
-            message=message,
-            turn_id=self.turn_id,
-            epoch=self.epoch,
-            input_commit_seq=self._input.commit_seq,
-        )
-
-    @property
-    def pending_server_vad_turn(self) -> PendingServerVADTurn | None:
-        return self._input.pending_server_vad_turn
-
-    def stage_server_vad_turn(
-        self,
-        committed: DuplexCommittedInput,
-        *,
-        create_response: bool,
-        item_id: str,
-    ) -> None:
-        if self._input.pending_server_vad_turn is not None:
-            raise RuntimeError("A Server VAD turn is already pending")
-        response_id = self.active_response_id
-        if response_id is not None:
-            # A pending user turn advances input_commit_seq before the active
-            # response completes. Reserve its current history position first.
-            self.reserve_history_item(f"item_{response_id}")
-        self._input.pending_server_vad_turn = PendingServerVADTurn(
-            committed=committed,
-            create_response=create_response,
-            item_id=item_id,
-        )
-
-    def activate_server_vad_turn(self) -> PendingServerVADTurn | None:
-        pending = self._input.pending_server_vad_turn
-        if pending is None:
-            return None
-        self._input.pending_server_vad_turn = None
-        self._conversation.messages.append(pending.committed.message)
-        self.register_history_item(pending.item_id, pending.committed.message)
-        self.turn_state = DuplexTurnState.USER_COMMITTED
-        return pending
-
-    def commit_native_audio_input(
+    def commit_audio_input(
         self,
         *,
         transcript: str | None = None,
@@ -970,8 +628,6 @@ def commit_native_audio_input(
         if transcript:
             message["transcript"] = transcript
         self._conversation.messages.append(message)
-        self._input.pending_text.clear()
-        self._input.pending_audio.clear()
         self.turn_state = DuplexTurnState.USER_COMMITTED
         return DuplexCommittedInput(
             message=message,
@@ -983,13 +639,9 @@ def commit_native_audio_input(
     def complete_model_turn(self, turn_id: int) -> None:
         """Advance the model-owned output identity after its terminal signal."""
         completed_turn_id = int(turn_id)
-        self._response.request_started_at_s_by_turn = {
-            pending_turn_id: started_at_s
-            for pending_turn_id, started_at_s in self._response.request_started_at_s_by_turn.items()
-            if pending_turn_id > completed_turn_id
-        }
         if completed_turn_id >= self.turn_id:
             self.turn_id = completed_turn_id + 1
+            self.sync_fence()
 
     def _bind_active_response_to_input_commit(self, input_commit_seq: int) -> None:
         if self.active_response_id is not None and self._response.active_response_awaits_input_commit:
@@ -1024,12 +676,6 @@ def begin_response(self, *, turn_id: int | None = None) -> str:
         response_id = f"resp-{self.session_id}-{self.epoch}-{uuid4().hex[:8]}"
         self._response.active_response_id = response_id
         self._response.active_response_turn_id = self.turn_id if turn_id is None else int(turn_id)
-        self._response.active_response_request_started_at_s = self._response.request_started_at_s_by_turn.pop(
-            self._response.active_response_turn_id,
-            None,
-        )
-        self._response.active_response_ttft_ms = None
-        self._response.active_response_ttfp_ms = None
         self._response.active_response_input_commit_seq = self.input_commit_seq
         self._response.active_response_awaits_input_commit = self.turn_state == DuplexTurnState.USER_SPEAKING
         self._response.last_response_id = response_id
@@ -1048,11 +694,39 @@ def _clear_response_metrics(self) -> None:
         self._response.stage_metric_tpot_weighted_ms.clear()
         self._response.stage_metric_tpot_weight.clear()
 
+    def stash_stage_metrics(self, stage_metrics: Mapping[object, object] | None) -> None:
+        """Hold a stage snapshot until a response exists to attribute it to.
+
+        A stage that hands its output to the next stage instead of the client
+        (stage 0 feeding the TTS stage) reports its token metrics before the
+        response carrying those tokens is created. Dropping them would leave
+        every response without an engine-side token count; holding them keeps
+        the count whole, at the cost of attributing a turn the model never
+        spoke to the next response it does speak.
+        """
+        if not isinstance(stage_metrics, Mapping):
+            return
+        snapshot = {
+            str(stage_id): dict(values) for stage_id, values in stage_metrics.items() if isinstance(values, Mapping)
+        }
+        if not snapshot:
+            return
+        if self.active_response_id is not None:
+            self.accumulate_response_stage_metrics(snapshot)
+            return
+        self._pending_stage_metrics.append(snapshot)
+
     def accumulate_response_stage_metrics(
         self,
         stage_metrics: Mapping[object, object] | None,
     ) -> dict[str, dict[str, object]]:
-        if self.active_response_id is None or not isinstance(stage_metrics, Mapping):
+        if self.active_response_id is None:
+            return copy.deepcopy(self._response.stage_metrics)
+        if self._pending_stage_metrics:
+            pending, self._pending_stage_metrics = self._pending_stage_metrics, []
+            for held in pending:
+                self.accumulate_response_stage_metrics(held)
+        if not isinstance(stage_metrics, Mapping):
             return copy.deepcopy(self._response.stage_metrics)
 
         additive_fields = (
@@ -1111,22 +785,17 @@ def accumulate_response_stage_metrics(
 
             tpot_ms = raw_values.get("vllm_tpot_ms")
             token_count = raw_values.get("num_tokens_out")
-            if isinstance(tpot_ms, int | float) and not isinstance(tpot_ms, bool) and tpot_ms > 0:
-                weight = (
-                    max(int(token_count) - 1, 0)
-                    if isinstance(token_count, int | float) and not isinstance(token_count, bool)
-                    else 1
+            if isinstance(tpot_ms, int | float) and tpot_ms > 0:
+                weight = max(int(token_count) - 1, 1) if isinstance(token_count, int | float) else 1
+                self._response.stage_metric_tpot_weighted_ms[stage_id] = (
+                    self._response.stage_metric_tpot_weighted_ms.get(stage_id, 0.0) + float(tpot_ms) * weight
+                )
+                self._response.stage_metric_tpot_weight[stage_id] = (
+                    self._response.stage_metric_tpot_weight.get(stage_id, 0) + weight
+                )
+                current["vllm_tpot_ms"] = self._response.stage_metric_tpot_weighted_ms[stage_id] / float(
+                    self._response.stage_metric_tpot_weight[stage_id]
                 )
-                if weight > 0:
-                    self._response.stage_metric_tpot_weighted_ms[stage_id] = (
-                        self._response.stage_metric_tpot_weighted_ms.get(stage_id, 0.0) + float(tpot_ms) * weight
-                    )
-                    self._response.stage_metric_tpot_weight[stage_id] = (
-                        self._response.stage_metric_tpot_weight.get(stage_id, 0) + weight
-                    )
-                    current["vllm_tpot_ms"] = self._response.stage_metric_tpot_weighted_ms[stage_id] / float(
-                        self._response.stage_metric_tpot_weight[stage_id]
-                    )
 
             for name, value in raw_values.items():
                 if name not in handled_fields:
@@ -1164,54 +833,25 @@ def append_assistant_text(self, text: str) -> None:
         if text:
             self._response.assistant_text_buffer.append(text)
 
-    def record_generated_audio(self, response_id: str, *, frame_count: int, sample_rate_hz: int) -> int | None:
-        """Accumulate source frames, rounding only the cumulative duration.
-
-        A late chunk cannot change a different response's playback cursor.
-        This records encoded audio, not transport delivery or client playback.
-        """
-        if response_id != self.active_response_id:
-            return None
-        if type(frame_count) is not int or frame_count < 0:
-            raise ValueError("Audio frame_count must be a non-negative integer")
-        if type(sample_rate_hz) is not int or sample_rate_hz <= 0:
-            raise ValueError("Audio sample_rate_hz must be a positive integer")
-        playback = self._playback.current
-        if playback.sample_rate_hz is not None and playback.sample_rate_hz != sample_rate_hz:
-            raise ValueError("Audio sample rate changed within a response")
-        playback.sample_rate_hz = sample_rate_hz
-        playback.generated_frames += frame_count
-        playback.generated_ms = playback.generated_frames * 1000 // sample_rate_hz
-        return playback.generated_ms
-
     def mark_audio_sent(
         self,
         duration_ms: int | None = None,
         *,
-        response_id: str | None = None,
         text_chars: int | None = None,
         audio_text_marks: list[dict[str, object]] | None = None,
     ) -> None:
-        """Record cumulative audio accepted by the output path.
-
-        ``sent_ms`` includes queued/journaled output; only client acknowledgements
-        establish ``played_ms``. It is not confirmation of socket delivery.
-        """
-        playback = self._playback.current if response_id is None else self._playback.by_response.get(response_id)
-        if playback is None:
-            return
-        is_current = response_id is None or response_id == self.active_response_id
+        playback = self._playback.current
         if duration_ms is not None:
             playback.generated_ms = max(playback.generated_ms, duration_ms)
             playback.sent_ms = max(playback.sent_ms, duration_ms)
-            if is_current and text_chars is not None and text_chars >= 0:
+            if text_chars is not None and text_chars >= 0:
                 self._response.assistant_audio_text_marks.append(
                     DuplexAssistantAudioTextMark(
                         text_chars=int(text_chars),
                         audio_end_ms=max(0, int(duration_ms)),
                     )
                 )
-        if is_current and audio_text_marks:
+        if audio_text_marks:
             for raw_mark in audio_text_marks:
                 if not isinstance(raw_mark, dict):
                     continue
@@ -1225,8 +865,7 @@ def mark_audio_sent(
                         audio_end_ms=max(0, int(raw_audio_end_ms)),
                     )
                 )
-        if is_current:
-            self.turn_state = DuplexTurnState.ASSISTANT_PLAYING
+        self.turn_state = DuplexTurnState.ASSISTANT_PLAYING
 
     def _playback_cursor_for_response(self, response_id: str | None = None) -> DuplexPlaybackCursor:
         if response_id is None:
@@ -1284,14 +923,7 @@ def end_response(
         response_input_commit_seq = self._response.active_response_input_commit_seq
         if response_input_commit_seq is None:
             response_input_commit_seq = self.input_commit_seq
-        response_item_id = f"item_{response_id}" if response_id is not None else None
-        response_history_is_reserved = response_item_id is not None and (
-            response_item_id in self._conversation.item_ids
-            or response_item_id in self._conversation.history_item_placeholders
-        )
-        response_history_is_late = (
-            self.input_commit_seq > response_input_commit_seq and not response_history_is_reserved
-        )
+        response_history_is_late = self.input_commit_seq > response_input_commit_seq
         assistant_text = "".join(self._response.assistant_text_buffer).strip()
         message = None
         if assistant_text:
@@ -1312,8 +944,9 @@ def end_response(
             committed_text = ""
         if commit_text and committed_text:
             message = {"role": "assistant", "content": committed_text}
-            if response_item_id is not None and response_history_is_reserved:
-                self._store_history_item_message(response_item_id, message)
+            item_id = f"item_{response_id}" if response_id is not None else None
+            if item_id is not None and item_id in self._conversation.history_item_placeholders:
+                self._store_history_item_message(item_id, message)
             else:
                 self._conversation.messages.append(message)
         effective_playback_policy = playback_commit_policy or self.config.playback_commit_policy
@@ -1324,16 +957,13 @@ def end_response(
             and effective_playback_policy == DuplexPlaybackCommitPolicy.ACK_ONLY.value
         ):
             self.register_history_item(f"item_{response_id}", None)
-        elif response_id is not None and (not assistant_text or not commit_text):
+        elif response_id is not None and not assistant_text:
             self._discard_history_item_placeholder(f"item_{response_id}")
         self._response.assistant_text_buffer.clear()
         if not preserve_request:
             self._response.active_request_id = None
         self._response.active_response_id = None
         self._response.active_response_turn_id = None
-        self._response.active_response_request_started_at_s = None
-        self._response.active_response_ttft_ms = None
-        self._response.active_response_ttfp_ms = None
         self._response.active_response_input_commit_seq = None
         self._response.active_response_awaits_input_commit = False
         self._clear_response_metrics()
@@ -1386,11 +1016,6 @@ def register_history_item(self, item_id: str | None, message: dict[str, object]
             )
 
     def delete_history_item(self, item_id: str) -> bool:
-        removed_pending_turn = False
-        pending_server_vad_turn = self._input.pending_server_vad_turn
-        if pending_server_vad_turn is not None and pending_server_vad_turn.item_id == item_id:
-            self._input.pending_server_vad_turn = None
-            removed_pending_turn = True
         response_id = item_id.removeprefix("item_") if item_id.startswith("item_") else None
         message = self._conversation.item_ids.pop(item_id, None)
         self._conversation.item_audio_text_marks.pop(item_id, None)
@@ -1403,7 +1028,7 @@ def delete_history_item(self, item_id: str) -> bool:
         if response_id is not None:
             self._conversation.assistant_response_snapshots.pop(response_id, None)
         if message is None:
-            return removed_pending_turn or pending is not None or removed_placeholder
+            return pending is not None or removed_placeholder
         try:
             self._conversation.messages.remove(message)
         except ValueError:
@@ -1644,17 +1269,12 @@ def _playback_cursor_for_item_id(self, item_id: str) -> DuplexPlaybackCursor | N
 
     def barge_in(self) -> int:
         self.epoch += 1
-        self._input.pending_text.clear()
-        self._input.pending_audio.clear()
+        self.sync_fence()
         self._response.assistant_text_buffer.clear()
         self._response.assistant_audio_text_marks.clear()
         self._response.active_request_id = None
         self._response.active_response_id = None
         self._response.active_response_turn_id = None
-        self._response.request_started_at_s_by_turn.clear()
-        self._response.active_response_request_started_at_s = None
-        self._response.active_response_ttft_ms = None
-        self._response.active_response_ttfp_ms = None
         self._response.active_response_input_commit_seq = None
         self._response.active_response_awaits_input_commit = False
         self._clear_response_metrics()
@@ -1670,17 +1290,35 @@ def close(self) -> None:
         self.state = DuplexSessionState.CLOSED
         self.turn_state = DuplexTurnState.IDLE
         self._response.active_response_turn_id = None
-        self._response.request_started_at_s_by_turn.clear()
-        self._response.active_response_request_started_at_s = None
-        self._response.active_response_ttft_ms = None
-        self._response.active_response_ttfp_ms = None
         self._response.active_response_input_commit_seq = None
         self._response.active_response_awaits_input_commit = False
-        self.clear_server_vad_audio()
-        self._input.pending_server_vad_turn = None
         self._clear_response_metrics()
         self._restore_response_config()
 
+    def signal_turn(self, event_type: str, payload: Mapping[str, object] | None = None) -> TurnEvent:
+        """Apply one external turn signal and return the typed ``turn.event``."""
+        payload = payload or {}
+        if event_type == DuplexTurnEventType.USER_STARTED.value:
+            self.transition_turn(DuplexTurnState.USER_SPEAKING)
+        elif event_type == DuplexTurnEventType.USER_COMMITTED.value:
+            self.transition_turn(DuplexTurnState.USER_COMMITTED)
+        elif event_type == DuplexTurnEventType.ASSISTANT_STARTED.value:
+            self.transition_turn(DuplexTurnState.ASSISTANT_GENERATING)
+        elif event_type == DuplexTurnEventType.ASSISTANT_DONE.value:
+            self.transition_turn(DuplexTurnState.IDLE)
+        elif event_type == DuplexTurnEventType.PLAYBACK_ACK.value:
+            played_ms = int(payload.get("played_ms", 0) or 0)
+            committed_ms = payload.get("committed_ms")
+            self.acknowledge_playback(
+                played_ms,
+                int(committed_ms) if isinstance(committed_ms, int | float) else None,
+            )
+        elif event_type == DuplexTurnEventType.BARGE_IN.value:
+            self.transition_turn(DuplexTurnState.BARGE_IN)
+        elif event_type in {DuplexTurnEventType.CLOSE.value, DuplexTurnEventType.TIMEOUT.value}:
+            self.transition_session(DuplexSessionState.CLOSING)
+        return TurnEvent(event=event_type, turn_state=self.turn_state.value)
+
     def as_public_dict(self) -> dict[str, object]:
         payload: dict[str, object] = {
             "id": self.session_id,
@@ -1708,8 +1346,6 @@ def as_public_dict(self) -> dict[str, object]:
             "playback": self.playback.as_dict(),
             "capabilities": self.capabilities.as_dict(),
         }
-        if self.config.turn_detection_configured:
-            payload["turn_detection"] = self.config.server_vad.as_dict() if self.config.server_vad is not None else None
         if isinstance(self.config.extra_body.get("realtime_tools"), list):
             payload["tools"] = self.config.extra_body["realtime_tools"]
         if isinstance(self.config.extra_body.get("realtime_tool_choice"), str | dict):
@@ -1738,73 +1374,14 @@ def as_public_dict(self) -> dict[str, object]:
         return payload
 
 
-class DuplexTurnController:
-    """Interaction controller that accepts signals from multiple sources."""
-
-    def signal(
-        self,
-        session: DuplexSession,
-        event_type: str,
-        payload: dict[str, object] | None = None,
-    ) -> dict[str, object]:
-        payload = payload or {}
-        if event_type == DuplexTurnEventType.USER_STARTED.value:
-            session.transition_turn(DuplexTurnState.USER_SPEAKING)
-        elif event_type == DuplexTurnEventType.USER_COMMITTED.value:
-            session.transition_turn(DuplexTurnState.USER_COMMITTED)
-        elif event_type == DuplexTurnEventType.ASSISTANT_STARTED.value:
-            session.transition_turn(DuplexTurnState.ASSISTANT_GENERATING)
-        elif event_type == DuplexTurnEventType.ASSISTANT_DONE.value:
-            session.transition_turn(DuplexTurnState.IDLE)
-        elif event_type == DuplexTurnEventType.PLAYBACK_ACK.value:
-            played_ms = int(payload.get("played_ms", 0) or 0)
-            committed_ms = payload.get("committed_ms")
-            session.acknowledge_playback(
-                played_ms,
-                int(committed_ms) if isinstance(committed_ms, int | float) else None,
-            )
-        elif event_type == DuplexTurnEventType.BARGE_IN.value:
-            session.transition_turn(DuplexTurnState.BARGE_IN)
-        elif event_type in {DuplexTurnEventType.CLOSE.value, DuplexTurnEventType.TIMEOUT.value}:
-            session.transition_session(DuplexSessionState.CLOSING)
-        return {
-            "type": "turn.event",
-            "session_id": session.session_id,
-            "event": event_type,
-            "turn_state": session.turn_state.value,
-            "epoch": session.epoch,
-        }
-
-
-class DuplexSessionRegistry:
-    def __init__(self, capabilities: DuplexCapabilities | None = None) -> None:
-        self._capabilities = capabilities or DuplexCapabilities()
-        self._sessions: dict[str, DuplexSession] = {}
-        self._next_incarnation_by_session_id: dict[str, int] = {}
-
-    def create(self, config: DuplexSessionConfig | None = None, session_id: str | None = None) -> DuplexSession:
-        sid = session_id or f"duplex-{uuid4().hex}"
-        if sid in self._sessions:
-            raise ValueError(f"Duplex session already exists: {sid}")
-        incarnation = self._next_incarnation_by_session_id.get(sid, 0)
-        self._next_incarnation_by_session_id[sid] = incarnation + 1
-        session = DuplexSession(
-            session_id=sid,
-            config=config or DuplexSessionConfig(),
-            capabilities=self._capabilities,
-            incarnation=incarnation,
-        )
-        self._sessions[sid] = session
-        return session
-
-    def active_count(self) -> int:
-        return len(self._sessions)
-
-    def get(self, session_id: str) -> DuplexSession | None:
-        return self._sessions.get(session_id)
-
-    def close(self, session_id: str) -> DuplexSession | None:
-        session = self._sessions.pop(session_id, None)
-        if session is not None:
-            session.close()
-        return session
+__all__ = [
+    "ConversationHistory",
+    "DuplexAppendReservation",
+    "DuplexEngineSession",
+    "DuplexFenceMismatchError",
+    "DuplexInputAppend",
+    "DuplexRequestResource",
+    "InputBufferState",
+    "PlaybackLedger",
+    "ResponseState",
+]
diff --git a/vllm_omni/engine/duplex/session/helpers.py b/vllm_omni/engine/duplex/session/helpers.py
new file mode 100644
index 00000000000..f8b705e6d2e
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/helpers.py
@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Small reads and payload builders over one duplex session.
+
+None of these hold state or decide anything: they answer a question about the
+session, or shape one of the wire payloads its events carry. They were methods
+on the runner only because that is where the session reference lived, which
+made every component that needed one a reason to reach back into the runner.
+
+Functions, not a component, because there is nothing here to own.
+"""
+
+from __future__ import annotations
+
+import binascii
+from typing import TYPE_CHECKING
+
+import pybase64 as base64
+
+from vllm_omni.engine.duplex.config import DuplexPlaybackCommitPolicy
+from vllm_omni.engine.duplex.contracts import DuplexFence, duplex_resource_request_id
+from vllm_omni.engine.duplex.events import ErrorEvent, OverlapDecision, error_event
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from vllm_omni.engine.duplex.session.context import DuplexSessionTasks
+    from vllm_omni.engine.duplex.session.engine_session import DuplexCommittedInput, DuplexEngineSession
+
+
+# --------------------------------------------------------------------------- #
+# Questions about the session                                                 #
+# --------------------------------------------------------------------------- #
+
+
+def stage0_request_id(session: DuplexEngineSession, epoch: int) -> str:
+    return duplex_resource_request_id(DuplexFence(session.session_id, epoch=epoch), "stage0")
+
+
+def response_in_progress(session: DuplexEngineSession, tasks: DuplexSessionTasks) -> bool:
+    """Whether the model still owns the turn.
+
+    Broader than ``active_response_id``: audio already sent but not yet played
+    back, and an append still in flight, both mean the turn is not free.
+    """
+    if session.active_response_id is not None:
+        return True
+    if assistant_playback_active(session):
+        return True
+    active_task = tasks.active_response_task
+    if active_task is not None and not active_task.done():
+        return True
+    return tasks.has_response_bound_append_tasks()
+
+
+def assistant_playback_active(session: DuplexEngineSession) -> bool:
+    """Whether the client is still playing audio the session has sent."""
+    return (
+        session.config.playback_commit_policy == DuplexPlaybackCommitPolicy.ACK_ONLY.value
+        and session.playback.sent_ms > session.playback.committed_ms
+    )
+
+
+def audio_payload_size_bytes(payload: Mapping[str, object]) -> int:
+    audio = payload.get("audio") or payload.get("data")
+    if not isinstance(audio, str):
+        return 0
+    try:
+        return len(base64.b64decode(audio, validate=True))
+    except (ValueError, binascii.Error):
+        return 0
+
+
+# --------------------------------------------------------------------------- #
+# Turn transitions                                                            #
+# --------------------------------------------------------------------------- #
+
+
+def advance_barge_in_epoch(session: DuplexEngineSession) -> tuple[int, dict[str, int]]:
+    """Start a new epoch for a barge-in, returning it with the playback it cut off."""
+    old_playback = session.playback.as_dict()
+    new_epoch = session.barge_in()
+    session.clear_playback_cursor()
+    return new_epoch, old_playback
+
+
+def commit_played_response_history(
+    session: DuplexEngineSession,
+    response_id: str | None,
+    committed_ms: int,
+) -> None:
+    """Truncate an interrupted response in history to what the client actually heard."""
+    if not response_id or committed_ms < 0:
+        return
+    session.truncate_history_item(
+        f"item_{response_id}",
+        audio_end_ms=committed_ms,
+        playback=session.playback_for_response(response_id),
+    )
+
+
+def commit_audio_input(
+    session: DuplexEngineSession,
+    *,
+    realtime_item_id: object | None = None,
+    transcript: object | None = None,
+    turn_id: int | None = None,
+) -> DuplexCommittedInput:
+    clean_transcript = transcript.strip() if isinstance(transcript, str) else None
+    committed = session.commit_audio_input(
+        transcript=clean_transcript or None,
+        turn_id=turn_id,
+    )
+    if isinstance(realtime_item_id, str) and realtime_item_id:
+        session.register_history_item(realtime_item_id, committed.message)
+    return committed
+
+
+# --------------------------------------------------------------------------- #
+# Payloads                                                                    #
+# --------------------------------------------------------------------------- #
+
+
+def barge_in_unsupported_error() -> ErrorEvent:
+    return error_event("barge_in_unsupported", "Barge-in is not supported by this duplex model")
+
+
+def overlap_decision_event(session: DuplexEngineSession, decision: dict[str, object]) -> OverlapDecision:
+    details: dict[str, object] = {
+        "type": "overlap.decision",
+        "session_id": session.session_id,
+        "epoch": session.epoch,
+        "policy": session.config.overlap_policy,
+        **decision,
+    }
+    action = decision.get("action")
+    reason = decision.get("reason")
+    return OverlapDecision(
+        policy=session.config.overlap_policy,
+        action=action if isinstance(action, str) else None,
+        reason=reason if isinstance(reason, str) else None,
+        details=details,
+    )
+
+
+def input_committed_payload(
+    session: DuplexEngineSession,
+    committed: DuplexCommittedInput,
+    *,
+    realtime_item_id: object | None = None,
+) -> dict[str, object]:
+    payload: dict[str, object] = {
+        "type": "input.committed",
+        "session_id": session.session_id,
+        "turn_id": committed.turn_id,
+        "epoch": committed.epoch,
+        "history_len": len(session.history),
+        "message": committed.message,
+    }
+    if isinstance(realtime_item_id, str) and realtime_item_id:
+        payload["realtime_item_id"] = realtime_item_id
+    return payload
+
+
+def audio_committed_payload(
+    session: DuplexEngineSession,
+    *,
+    committed: DuplexCommittedInput | None = None,
+    realtime_item_id: object | None = None,
+    transcript: object | None = None,
+) -> dict[str, object]:
+    message = committed.message if committed is not None else None
+    if not isinstance(message, dict):
+        input_audio_part: dict[str, object] = {
+            "type": "audio_url",
+            "audio_url": {"url": "native-duplex:input-audio"},
+        }
+        if isinstance(transcript, str) and transcript:
+            input_audio_part["transcript"] = transcript
+        message = {"role": "user", "content": [input_audio_part]}
+    payload: dict[str, object] = {
+        "type": "input.committed",
+        "session_id": session.session_id,
+        "turn_id": committed.turn_id if committed is not None else session.turn_id,
+        "epoch": committed.epoch if committed is not None else session.epoch,
+        "history_len": len(session.history),
+        "native_audio": True,
+        "message": message,
+    }
+    if isinstance(transcript, str) and transcript:
+        payload["transcript"] = transcript
+    if isinstance(realtime_item_id, str) and realtime_item_id:
+        payload["realtime_item_id"] = realtime_item_id
+    return payload
diff --git a/vllm_omni/engine/duplex/lease.py b/vllm_omni/engine/duplex/session/lease.py
similarity index 92%
rename from vllm_omni/engine/duplex/lease.py
rename to vllm_omni/engine/duplex/session/lease.py
index c38faacd1ba..aea2040392d 100644
--- a/vllm_omni/engine/duplex/lease.py
+++ b/vllm_omni/engine/duplex/session/lease.py
@@ -8,8 +8,6 @@
 from dataclasses import dataclass, field
 from enum import Enum
 
-from vllm_omni.engine.duplex.messages import DuplexFence
-
 
 class DuplexLeaseActivity(str, Enum):
     APPEND = "append"
@@ -111,19 +109,8 @@ def mark_terminal(self, reason: str) -> bool:
         return True
 
 
-@dataclass(frozen=True)
-class DuplexSessionExpiry:
-    session_id: str
-    fence: DuplexFence
-    lease_generation: int
-    reason: str
-    submitted_request_ids: tuple[str, ...]
-    reserved_request_ids: tuple[str, ...]
-
-
 __all__ = [
     "DuplexLeaseActivity",
     "DuplexLeaseConfig",
     "DuplexLeaseState",
-    "DuplexSessionExpiry",
 ]
diff --git a/vllm_omni/engine/duplex/session/manager.py b/vllm_omni/engine/duplex/session/manager.py
new file mode 100644
index 00000000000..0b7a7a07ea0
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/manager.py
@@ -0,0 +1,872 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Engine-side owner of duplex sessions: admission, lease reaping, command dispatch.
+
+``DuplexOrchestrator`` hosts exactly one manager. The whole session
+(``DuplexEngineSession``) lives here, owned by one ``DuplexSessionRunner`` per
+session on the orchestrator loop; nothing outside the engine holds session
+state.
+
+Control operations (open / close / resume / touch) arrive as correlated RPC
+messages and answer through ``result_sink``; session commands arrive one-way
+as ``DuplexSessionCommandMessage`` and are pushed onto the runner's ordered
+mailbox after backpressure admission; everything a session emits leaves
+through ``output_sink`` as ``DuplexSessionEventMessage``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import time
+from collections.abc import Awaitable, Callable, Iterable
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+
+from vllm.logger import init_logger
+
+from vllm_omni.engine.duplex.commands import AppendAudio, Commit, DuplexCommand
+from vllm_omni.engine.duplex.contracts import (
+    DuplexFence,
+    DuplexStagePort,
+    DuplexStageRequestContext,
+    duplex_resource_request_belongs_to_session,
+    duplex_resource_request_id,
+)
+from vllm_omni.engine.duplex.events import DuplexEvent, ErrorEvent, SessionClosed, SessionExpired, error_event
+from vllm_omni.engine.duplex.messages import (
+    CloseDuplexSessionMessage,
+    DuplexControlResultMessage,
+    DuplexSessionCommandMessage,
+    DuplexSessionError,
+    DuplexSessionEventMessage,
+    OpenDuplexSessionMessage,
+    ResumeDuplexSessionMessage,
+    TouchDuplexSessionMessage,
+)
+from vllm_omni.engine.duplex.plugin import DuplexModelPlugin, DuplexRuntimeConfigError, validate_duplex_plugin_sampling
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession, DuplexFenceMismatchError
+from vllm_omni.engine.duplex.session.lease import DuplexLeaseActivity, DuplexLeaseConfig, DuplexLeaseState
+from vllm_omni.engine.duplex.turn_detection import SileroVADBackendProvider
+
+if TYPE_CHECKING:
+    import janus
+    from vllm.config import ModelConfig
+
+    from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+    from vllm_omni.engine.duplex.session.runner import DuplexSessionRunner
+    from vllm_omni.engine.messages import EngineQueueMessage
+
+logger = init_logger(__name__)
+
+
+@dataclass(frozen=True)
+class _PendingRequestCleanup:
+    session_id: str
+    lease_generation: int
+    request_ids: tuple[str, ...]
+    abort: bool
+
+
+@dataclass(frozen=True)
+class _PendingSessionCleanup:
+    """A close/expiry whose stage cleanup has not succeeded yet (retried by the reaper)."""
+
+    kind: str
+    session_id: str
+    lease_generation: int
+    reason: str
+    submitted_request_ids: tuple[str, ...]
+    reserved_request_ids: tuple[str, ...]
+
+
+class DuplexSessionManager:
+    _CONTROL_TYPES = (
+        OpenDuplexSessionMessage,
+        CloseDuplexSessionMessage,
+        ResumeDuplexSessionMessage,
+        TouchDuplexSessionMessage,
+    )
+    _MESSAGE_TYPES = (*_CONTROL_TYPES, DuplexSessionCommandMessage)
+
+    def __init__(
+        self,
+        *,
+        plugin: DuplexModelPlugin,
+        stage_port: DuplexStagePort,
+        output_sink: janus.AsyncQueue[EngineQueueMessage],
+        result_sink: janus.AsyncQueue[EngineQueueMessage],
+        runtime_config: DuplexSessionRuntimeConfig,
+        model_config: ModelConfig | None,
+        clock: Callable[[], float] | None = None,
+        executor: concurrent.futures.ThreadPoolExecutor | None = None,
+    ) -> None:
+        validate_duplex_plugin_sampling(plugin, sampling_defaults=tuple(stage_port.sampling_defaults()))
+        self.plugin = plugin
+        self.stage_port = stage_port
+        self.model_config = model_config
+        self.runtime_config = runtime_config
+        self._output_sink = output_sink
+        self._result_sink = result_sink
+        self._clock = clock or time.monotonic
+        self.executor = executor or concurrent.futures.ThreadPoolExecutor(
+            max_workers=4,
+            thread_name_prefix="duplex-session",
+        )
+        self._owns_executor = executor is None
+        self._lease_config = DuplexLeaseConfig(
+            idle_ttl_s=runtime_config.idle_ttl_s,
+            disconnect_grace_s=runtime_config.disconnect_grace_s,
+        )
+        #: One Silero backend for the whole engine: the ONNX graph is stateless
+        #: per call, so every session's detector can share it. Resolved lazily,
+        #: on the first session that actually turns server VAD on.
+        self.vad_backend_provider = SileroVADBackendProvider(
+            model_path=getattr(runtime_config, "server_vad_model_path", None)
+        )
+        self.runners: dict[str, DuplexSessionRunner] = {}
+        #: Sessions whose close/expiry began but whose stage cleanup has not finalized;
+        #: they keep their admission slot until finalized.
+        self._closing: dict[str, _PendingSessionCleanup] = {}
+        #: Session ids whose ``open`` passed the capacity check and is still awaiting the plugin.
+        self._admitting: set[str] = set()
+        #: Opens whose caller gave up (control RPC timeout / cancellation) before
+        #: admission finished. The open completes anyway -- it is already past
+        #: the capacity check -- so it must tear itself down on arrival instead
+        #: of holding a slot and a stage resource until idle expiry.
+        self._abandoned_opens: set[str] = set()
+        self._request_index: dict[str, str] = {}
+        self._session_control_tails: dict[str, asyncio.Task[None]] = {}
+        self._dispatched_control_tasks: set[asyncio.Task[None]] = set()
+        self._pending_request_cleanups: dict[tuple[str, int], _PendingRequestCleanup] = {}
+        self._request_cleanup_tasks: dict[tuple[str, int], asyncio.Task[None]] = {}
+        self._request_cleanups_in_progress: set[tuple[str, int]] = set()
+        #: Sessions retained for cleanup retry after their runner is gone.
+        self._session_snapshots: dict[str, DuplexEngineSession] = {}
+
+    # ------------------------------------------------------------------ #
+    # Views                                                              #
+    # ------------------------------------------------------------------ #
+
+    def active_count(self) -> int:
+        return len(self.runners)
+
+    def get(self, session_id: str) -> DuplexEngineSession | None:
+        runner = self.runners.get(session_id)
+        return runner.session if runner is not None else None
+
+    def sessions(self) -> dict[str, DuplexEngineSession]:
+        return {session_id: runner.session for session_id, runner in self.runners.items()}
+
+    def runner_for_request_id(self, request_id: str) -> DuplexSessionRunner | None:
+        session_id = self._request_index.get(request_id)
+        if session_id is None:
+            for candidate_id in self.runners:
+                if duplex_resource_request_belongs_to_session(request_id, candidate_id):
+                    session_id = candidate_id
+                    break
+        if session_id is None:
+            return None
+        return self.runners.get(session_id)
+
+    def register_request(self, request_id: str, session_id: str) -> None:
+        self._request_index[request_id] = session_id
+
+    def unregister_request(self, request_id: str) -> None:
+        self._request_index.pop(request_id, None)
+
+    def _unregister_session_requests(self, session_id: str) -> None:
+        for request_id in [rid for rid, sid in self._request_index.items() if sid == session_id]:
+            self._request_index.pop(request_id, None)
+
+    # ------------------------------------------------------------------ #
+    # Message routing                                                    #
+    # ------------------------------------------------------------------ #
+
+    def accepts(self, message: object) -> bool:
+        return isinstance(message, self._MESSAGE_TYPES)
+
+    def dispatch(self, message: object) -> None:
+        """Route one engine request-queue message without blocking the request handler."""
+        if isinstance(message, DuplexSessionCommandMessage):
+            self._dispatch_command(message)
+            return
+        if not isinstance(message, self._CONTROL_TYPES):
+            raise TypeError(f"Unsupported duplex control message: {type(message).__name__}")
+        session_id = message.session_id
+
+        async def handle_message() -> None:
+            await self.handle(message)
+
+        self._run_control(session_id, f"duplex-control-{session_id}-{message.control_id}", handle_message)
+
+    def _run_control(
+        self,
+        session_id: str,
+        name: str,
+        operation: Callable[[], Awaitable[None]],
+    ) -> asyncio.Task[None]:
+        """Run one control operation after the session's previous one (per-session order)."""
+        predecessor = self._session_control_tails.get(session_id)
+
+        async def run_ordered() -> None:
+            if predecessor is not None:
+                try:
+                    await predecessor
+                except BaseException:
+                    pass
+            await operation()
+
+        task = asyncio.create_task(run_ordered(), name=name)
+        self._session_control_tails[session_id] = task
+        self._track_task(task)
+
+        def discard(completed: asyncio.Task[None]) -> None:
+            if self._session_control_tails.get(session_id) is completed:
+                self._session_control_tails.pop(session_id, None)
+
+        task.add_done_callback(discard)
+        return task
+
+    def _track_task(self, task: asyncio.Task[None]) -> None:
+        """Keep a background task alive until it finishes and log an escaped exception."""
+        self._dispatched_control_tasks.add(task)
+
+        def done(completed: asyncio.Task[None]) -> None:
+            self._dispatched_control_tasks.discard(completed)
+            if not completed.cancelled() and completed.exception() is not None:
+                logger.error("duplex control task %s failed: %r", completed.get_name(), completed.exception())
+
+        task.add_done_callback(done)
+
+    async def handle(self, message: object) -> None:
+        if isinstance(message, OpenDuplexSessionMessage):
+            await self.open(message)
+        elif isinstance(message, CloseDuplexSessionMessage):
+            await self.close(message)
+        elif isinstance(message, ResumeDuplexSessionMessage):
+            await self.resume(message)
+        elif isinstance(message, TouchDuplexSessionMessage):
+            await self.touch(message)
+        elif isinstance(message, DuplexSessionCommandMessage):
+            self._dispatch_command(message)
+        else:
+            raise TypeError(f"Unsupported duplex control message: {type(message).__name__}")
+
+    def _dispatch_command(self, message: DuplexSessionCommandMessage) -> None:
+        """Admit one command: identity check, backpressure, then the runner's ordered mailbox.
+
+        Backpressure contract shared with the runner: a ``Commit`` that passes
+        admission holds one pending-turn reservation and an ``AppendAudio``
+        holds its wire-size byte reservation until the runner dequeues the
+        command (the runner then re-reserves the decoded size around its PCM
+        reservation), so the mailbox never holds more bytes than the session
+        limit even while the worker is busy.
+        """
+        runner = self.runners.get(message.session_id)
+        command = message.command
+        if runner is None:
+            self._emit_raw(
+                message.session_id,
+                self._error_event(
+                    "unknown_session",
+                    f"Unknown or closed duplex session: {message.session_id}",
+                    command=command,
+                ),
+            )
+            return
+        session = runner.session
+        if runner.closing:
+            self.emit(
+                session,
+                self._error_event(
+                    "session_closed", f"Duplex session is closing: {session.session_id}", command=command
+                ),
+            )
+            return
+        if isinstance(command, AppendAudio):
+            limit = int(self.runtime_config.max_pending_input_bytes_per_session)
+            if not session.reserve_input_bytes(len(command.audio), limit=limit):
+                self.emit(
+                    session,
+                    self._error_event(
+                        "input_backpressure",
+                        "Duplex session has too many pending input bytes",
+                        command=command,
+                    ),
+                )
+                return
+        elif isinstance(command, Commit):
+            if not session.reserve_pending_turn(limit=int(self.runtime_config.max_pending_turns_per_session)):
+                self.emit(
+                    session,
+                    self._error_event(
+                        "input_backpressure",
+                        "Duplex session has too many pending input turns",
+                        command=command,
+                    ),
+                )
+                return
+        runner.submit(command)
+
+    @staticmethod
+    def _error_event(code: str, message: str, *, command: DuplexCommand | None = None) -> ErrorEvent:
+        return error_event(code, message, event_id=command.event_id if command is not None else None)
+
+    # ------------------------------------------------------------------ #
+    # Emission                                                           #
+    # ------------------------------------------------------------------ #
+
+    def emit(self, session: DuplexEngineSession, event: DuplexEvent) -> None:
+        """Bind the session identity to one typed event and push it to the engine output queue."""
+        self._emit_raw(session.session_id, event, epoch=session.epoch)
+
+    def _emit_raw(
+        self,
+        session_id: str,
+        event: DuplexEvent,
+        *,
+        epoch: int | None = None,
+    ) -> None:
+        event = replace(event, session_id=session_id, epoch=epoch)
+        message = DuplexSessionEventMessage(session_id=session_id, event=event)
+        put_nowait = getattr(self._output_sink, "put_nowait", None)
+        if callable(put_nowait):
+            put_nowait(message)
+        else:  # pragma: no cover - sink without put_nowait
+            asyncio.ensure_future(self._output_sink.put(message))
+
+    async def _put_result(
+        self,
+        message: (
+            OpenDuplexSessionMessage
+            | CloseDuplexSessionMessage
+            | ResumeDuplexSessionMessage
+            | TouchDuplexSessionMessage
+        ),
+        *,
+        operation: str,
+        ok: bool,
+        session: DuplexEngineSession | None = None,
+        error: BaseException | None = None,
+    ) -> None:
+        error_code, error_message, error_retryable = (
+            self._control_error(error) if error is not None else (None, None, False)
+        )
+        result = DuplexControlResultMessage(
+            control_id=message.control_id,
+            operation=operation,
+            session_id=message.session_id,
+            ok=ok,
+            lease_generation=session.lease_generation if session is not None else None,
+            capabilities=session.capabilities if session is not None and ok else None,
+            public_session=session.as_public_dict() if session is not None and ok else None,
+            error_code=error_code,
+            error_message=error_message,
+            error_retryable=error_retryable,
+        )
+        await self._result_sink.put(result)
+
+    @staticmethod
+    def _control_error(error: BaseException) -> tuple[str, str, bool]:
+        """Map an exception to ``(code, message, retryable)`` for a control result."""
+        message = str(error)
+        retryable = False
+        if isinstance(error, DuplexSessionError):
+            code = error.code
+            retryable = error.retryable
+        elif isinstance(error, DuplexRuntimeConfigError):
+            code = error.code
+        elif isinstance(error, DuplexFenceMismatchError):
+            code = "stale_fence"
+        elif isinstance(error, KeyError):
+            code = "not_found"
+        elif isinstance(error, TypeError | ValueError):
+            code = "invalid_argument"
+        elif isinstance(error, TimeoutError):
+            code = "timeout"
+            retryable = True
+        else:
+            code = "failed_precondition"
+        return code, message, retryable
+
+    # ------------------------------------------------------------------ #
+    # Sampling / stage request helpers shared with the runner            #
+    # ------------------------------------------------------------------ #
+
+    def sampling_params_for(self, session: DuplexEngineSession) -> tuple[object, ...]:
+        defaults = tuple(self.stage_port.sampling_defaults())
+        configured = self.plugin.configure_sampling_params(
+            runtime_config=dict(session.runtime_config),
+            defaults=defaults,
+        )
+        if not isinstance(configured, tuple):
+            raise TypeError("duplex plugin must return sampling parameters as a tuple")
+        if len(configured) != len(defaults):
+            raise ValueError("duplex plugin must return one sampling parameter per stage")
+        return configured
+
+    @staticmethod
+    def stage_request_id(fence: DuplexFence, *, stage_id: int) -> str:
+        return duplex_resource_request_id(fence, f"stage{stage_id}")
+
+    def ensure_stage_request(
+        self,
+        session: DuplexEngineSession,
+        *,
+        stage_id: int,
+        fence: DuplexFence | None = None,
+    ) -> DuplexStageRequestContext | None:
+        """Reserve the session's stage request id and register it with the stage port."""
+        if stage_id >= self.stage_port.stage_count:
+            return None
+        effective_fence = fence or session.fence
+        request_id = self.stage_request_id(effective_fence, stage_id=stage_id)
+        session.reserve_stage_request(stage_id, request_id, fence=effective_fence)
+        context = DuplexStageRequestContext(
+            request_id=request_id,
+            session_id=session.session_id,
+            fence=effective_fence,
+            stage_id=stage_id,
+            final_stage_id=self.stage_port.stage_count - 1,
+            config_generation=session.config_generation,
+            sampling_params=self.sampling_params_for(session),
+            session_config=session.config.as_dict(),
+            runtime_config=session.runtime_config,
+        )
+        self.stage_port.ensure_request(context)
+        self.register_request(request_id, session.session_id)
+        return context
+
+    # ------------------------------------------------------------------ #
+    # Control operations                                                 #
+    # ------------------------------------------------------------------ #
+
+    def _admission_count(self) -> int:
+        return len(set(self.runners) | set(self._closing) | self._admitting)
+
+    async def open(self, message: OpenDuplexSessionMessage) -> None:
+        from vllm_omni.engine.duplex.session.runner import DuplexSessionRunner
+
+        session_id = message.session_id
+        session: DuplexEngineSession | None = None
+        runner: DuplexSessionRunner | None = None
+        # Only the open that put the id in ``_admitting`` may take it out again:
+        # a duplicate open must not release the slot the first one is holding.
+        holds_admission_slot = False
+        try:
+            if session_id in self.runners or session_id in self._closing or session_id in self._admitting:
+                raise DuplexSessionError(f"Duplex session already exists: {session_id}", code="session_exists")
+            max_sessions = int(self.runtime_config.max_sessions)
+            if self._admission_count() >= max_sessions:
+                raise DuplexSessionError(
+                    f"duplex_session_capacity_exhausted: limit={max_sessions}",
+                    code="resource_exhausted",
+                    retryable=True,
+                )
+            # Hold the slot across the plugin await: opens of different
+            # sessions run concurrently and must not all pass the check above.
+            self._admitting.add(session_id)
+            holds_admission_slot = True
+            config = message.session_config
+            self.plugin.validate_client_extra_body(config.extra_body)
+            try:
+                runtime_config = await self.plugin.prepare_runtime_config(config, model_config=self.model_config)
+            except DuplexRuntimeConfigError:
+                raise
+            except ValueError as exc:
+                raise DuplexRuntimeConfigError(str(exc)) from exc
+            capabilities = self.plugin.capabilities(max_sessions=max_sessions)
+            session = DuplexEngineSession(
+                session_id=session_id,
+                config=config,
+                capabilities=capabilities,
+                lease=DuplexLeaseState(config=self._lease_config, generation=0, last_activity=self._clock()),
+                _clock=self._clock,
+                _runtime_config=dict(runtime_config),
+            )
+            # Validates the plugin's sampling policy for this runtime config before admission.
+            self.sampling_params_for(session)
+            session.model_state = self.plugin.create_session_state()
+            runner = DuplexSessionRunner(
+                session=session,
+                plugin=self.plugin,
+                stage_port=self.stage_port,
+                manager=self,
+                model_config=self.model_config,
+            )
+            self.runners[session_id] = runner
+            # Reserve the Stage0 request resource atomically with admission.
+            self.ensure_stage_request(session, stage_id=0)
+            runner.start()
+            await self._put_result(message, operation="open", ok=True, session=session)
+            if session_id in self._abandoned_opens:
+                # The caller timed out while we were admitting; hand the slot
+                # and the stage resource straight back.
+                self._abandoned_opens.discard(session_id)
+                await self._close_runner(runner, kind="close", reason="open_abandoned")
+        except Exception as exc:
+            error_code, _, _ = self._control_error(exc)
+            if error_code in {"resource_exhausted", "session_exists"}:
+                logger.info("open_duplex_session rejected: %s", exc)
+            else:
+                logger.exception("open_duplex_session failed: %s", exc)
+            if runner is not None and self.runners.get(session_id) is runner:
+                self.runners.pop(session_id, None)
+                try:
+                    await runner.shutdown()
+                except Exception:
+                    logger.exception("duplex open rollback: runner shutdown failed for %s", session_id)
+            if session is not None:
+                reserved = session.release_all_requests()
+                if reserved:
+                    try:
+                        await self.stage_port.cleanup(list(reserved))
+                    except Exception:
+                        logger.warning("duplex open rollback: request cleanup pending for %s", session_id)
+                self._unregister_session_requests(session_id)
+            await self._put_result(message, operation="open", ok=False, error=exc)
+        finally:
+            if holds_admission_slot:
+                self._admitting.discard(session_id)
+            self._abandoned_opens.discard(session_id)
+
+    def _require_runner(self, session_id: str) -> DuplexSessionRunner:
+        runner = self.runners.get(session_id)
+        if runner is None:
+            raise DuplexSessionError(f"Unknown duplex session: {session_id}", code="unknown_session")
+        if runner.closing:
+            raise DuplexSessionError(f"Duplex session is closing: {session_id}", code="session_closed")
+        return runner
+
+    async def close(self, message: CloseDuplexSessionMessage) -> None:
+        session_id = message.session_id
+        runner = self.runners.get(session_id)
+        if runner is None:
+            if session_id in self._admitting:
+                # The open is still awaiting the plugin. It cannot be cancelled
+                # from here, so leave a note it checks before returning.
+                self._abandoned_opens.add(session_id)
+            # Already closing, or closed and forgotten: ids are never reused
+            # (D16), so a repeated close is idempotent rather than an error.
+            await self._put_result(message, operation="close", ok=True)
+            return
+        session = runner.session
+        try:
+            await self._close_runner(runner, kind="close", reason=message.reason)
+        except Exception as exc:
+            # The session is closed either way; only the stage cleanup is
+            # outstanding and the reaper retries it while the slot stays held.
+            logger.warning("close_duplex_session: stage cleanup for %s remains pending: %s", session_id, exc)
+        await self._put_result(message, operation="close", ok=True, session=session)
+
+    def close_from_runner(self, runner: DuplexSessionRunner, reason: str) -> None:
+        """Finish a close the runner started from its command stream (``session.close``).
+
+        Runs on the orchestrator loop as a tracked task (the runner's worker
+        cannot await its own teardown): stage requests are aborted, the
+        admission slot is released and ``session.closed`` is emitted last.
+        """
+        session_id = runner.session.session_id
+        if self.runners.get(session_id) is not runner:
+            return
+
+        async def close_runner() -> None:
+            if self.runners.get(session_id) is runner:
+                await self._close_runner(runner, kind="close", reason=reason)
+
+        # Chained on the session's control tail so a control RPC issued after
+        # the wire close observes the closed session, never a half-torn one.
+        self._run_control(session_id, f"duplex-close-{session_id}", close_runner)
+
+    async def _close_runner(self, runner: DuplexSessionRunner, *, kind: str, reason: str) -> None:
+        """Begin an irreversible close, tear down the runner, then release stage resources.
+
+        The session keeps its admission slot (``_closing``) until stage cleanup
+        succeeded; a failed cleanup is retried by the reaper. For an explicit
+        close the ``session.closed`` event is emitted only after the cleanup
+        attempt, so a client that sees it can open a replacement session at
+        once (the runner used to emit it before the stage requests were
+        aborted, which let a prompt reopen hit ``resource_exhausted``).
+        """
+        session = runner.session
+        submitted = tuple(session.resource_request_ids(submitted=True))
+        reserved = tuple(session.resource_request_ids(submitted=False))
+        session.begin_close(reason=reason)
+        pending = _PendingSessionCleanup(
+            kind=kind,
+            session_id=session.session_id,
+            lease_generation=session.lease_generation,
+            reason=reason,
+            submitted_request_ids=submitted,
+            reserved_request_ids=reserved,
+        )
+        self._closing[session.session_id] = pending
+        if self.runners.get(session.session_id) is runner:
+            self.runners.pop(session.session_id, None)
+        emit_after_cleanup = kind in {"close", "expired"} and not runner.closed_emitted
+        try:
+            if kind == "expired":
+                await runner.expire(reason, emit_expired=not emit_after_cleanup)
+            else:
+                await runner.close(reason, emit_closed=not emit_after_cleanup)
+        except Exception:
+            logger.exception("duplex runner %s failed for session %s", kind, session.session_id)
+        session.close()
+        try:
+            await self._finalize_pending_cleanup(pending, session)
+        finally:
+            # ``emit_after_cleanup`` was decided before the teardown awaits; a
+            # runtime close racing them may have emitted the terminal already.
+            if emit_after_cleanup and not runner.closed_emitted:
+                runner.mark_closed_emitted()
+                terminal: DuplexEvent = (
+                    SessionExpired(reason=reason) if kind == "expired" else SessionClosed(reason=reason)
+                )
+                self.emit(session, terminal)
+
+    async def _finalize_pending_cleanup(
+        self,
+        pending: _PendingSessionCleanup,
+        session: DuplexEngineSession | None,
+    ) -> None:
+        if pending.submitted_request_ids:
+            await self.stage_port.cleanup(list(pending.submitted_request_ids), abort=True)
+        if pending.reserved_request_ids:
+            await self.stage_port.cleanup(list(pending.reserved_request_ids))
+        if session is not None:
+            session.release_all_requests()
+        self._unregister_session_requests(pending.session_id)
+        if self._closing.get(pending.session_id) is pending:
+            self._closing.pop(pending.session_id, None)
+        self._session_snapshots.pop(pending.session_id, None)
+
+    async def resume(self, message: ResumeDuplexSessionMessage) -> None:
+        session: DuplexEngineSession | None = None
+        try:
+            runner = self._require_runner(message.session_id)
+            session = runner.session
+            try:
+                session.resume_lease(expected_lease_generation=message.expected_lease_generation)
+            except ValueError as exc:
+                raise DuplexSessionError(str(exc), code="session_resume_conflict") from exc
+            await self._put_result(message, operation="resume", ok=True, session=session)
+        except Exception as exc:
+            logger.exception("resume_duplex_session failed: %s", exc)
+            await self._put_result(message, operation="resume", ok=False, session=session, error=exc)
+
+    async def touch(self, message: TouchDuplexSessionMessage) -> None:
+        session: DuplexEngineSession | None = None
+        try:
+            runner = self._require_runner(message.session_id)
+            session = runner.session
+            activity = DuplexLeaseActivity(message.activity)
+            if activity is DuplexLeaseActivity.DETACH:
+                session.detach_lease()
+            else:
+                session.touch_lease(activity)
+            await self._put_result(message, operation="touch", ok=True, session=session)
+        except DuplexSessionError as exc:
+            # A lease touch racing the session's own close is routine: the
+            # caller learns the session is gone from the result, not a fault.
+            logger.debug("touch_duplex_session skipped: %s", exc)
+            await self._put_result(message, operation="touch", ok=False, session=session, error=exc)
+        except Exception as exc:
+            logger.exception("touch_duplex_session failed: %s", exc)
+            await self._put_result(message, operation="touch", ok=False, session=session, error=exc)
+
+    # ------------------------------------------------------------------ #
+    # Lease expiry / reaper                                              #
+    # ------------------------------------------------------------------ #
+
+    async def reaper_loop(self, shutdown_event: asyncio.Event) -> None:
+        interval = float(self.runtime_config.reaper_interval_s)
+        while not shutdown_event.is_set():
+            try:
+                await asyncio.wait_for(shutdown_event.wait(), timeout=interval)
+            except TimeoutError:
+                try:
+                    await self.reap_expired()
+                except Exception:
+                    logger.exception("[DuplexSessionManager] expiry cleanup failed; retrying on next tick")
+
+    async def reap_expired(self, now: float | None = None) -> int:
+        completed = 0
+        effective_now = self._clock() if now is None else now
+        # Retry request cleanups recorded by the orchestrator error paths.
+        for key, request_cleanup in list(self._pending_request_cleanups.items()):
+            if key in self._request_cleanups_in_progress:
+                continue
+            try:
+                await self._complete_request_cleanup(key, request_cleanup)
+            except Exception as exc:
+                logger.warning(
+                    "duplex request cleanup remains pending for session %s: %s",
+                    request_cleanup.session_id,
+                    exc,
+                )
+                continue
+            completed += 1
+        # Retry closes/expiries whose stage cleanup failed.
+        for session_id, session_cleanup in list(self._closing.items()):
+            if session_id in self.runners:
+                continue
+            if session_cleanup.kind == "request_cleanup" and any(
+                key[0] == session_id for key in self._pending_request_cleanups
+            ):
+                # The stage cleanup is owned by the request-cleanup path (orchestrator
+                # or the retry above); ``finalize_closed_sessions`` releases the slot.
+                continue
+            try:
+                await self._finalize_pending_cleanup(session_cleanup, self._session_snapshots.get(session_id))
+            except Exception as exc:
+                logger.warning(
+                    "duplex %s cleanup remains pending for session %s: %s",
+                    session_cleanup.kind,
+                    session_id,
+                    exc,
+                )
+                continue
+            completed += 1
+        # Expire leases.
+        for session_id, runner in list(self.runners.items()):
+            lease = runner.session.lease
+            if lease.disconnect_grace_expired(effective_now):
+                reason = "disconnect_grace_expired"
+            elif lease.idle_expired(effective_now):
+                reason = "idle_ttl_expired"
+            else:
+                continue
+            self._session_snapshots[session_id] = runner.session
+            try:
+                await self._close_runner(runner, kind="expired", reason=reason)
+            except Exception as exc:
+                logger.warning("duplex expiry cleanup remains pending for session %s: %s", session_id, exc)
+                continue
+            completed += 1
+        return completed
+
+    # ------------------------------------------------------------------ #
+    # Request-triggered cleanup (orchestrator error paths)               #
+    # ------------------------------------------------------------------ #
+
+    def close_sessions_for_request_ids(
+        self,
+        request_ids: list[str],
+        *,
+        abort: bool = False,
+        cleanup_in_progress: bool = False,
+    ) -> dict[str, list[str]]:
+        request_id_set = set(request_ids)
+        closed: dict[str, list[str]] = {}
+        for session_id, runner in list(self.runners.items()):
+            session = runner.session
+            stale = session.resource_request_ids()
+            if request_id_set.isdisjoint(stale):
+                continue
+            if not session.begin_close(reason="request_cleanup"):
+                continue
+            closed[session_id] = stale
+            key = (session_id, session.lease_generation)
+            existing = self._pending_request_cleanups.get(key)
+            merged = tuple(dict.fromkeys([*(existing.request_ids if existing is not None else ()), *stale]))
+            self._pending_request_cleanups[key] = _PendingRequestCleanup(
+                session_id=session_id,
+                lease_generation=session.lease_generation,
+                request_ids=merged,
+                abort=abort or (existing.abort if existing is not None else False),
+            )
+            if cleanup_in_progress:
+                self._request_cleanups_in_progress.add(key)
+            # Tear the runner down in the background; the orchestrator owns the stage cleanup.
+            self._session_snapshots[session_id] = session
+            self._closing[session_id] = _PendingSessionCleanup(
+                kind="request_cleanup",
+                session_id=session_id,
+                lease_generation=session.lease_generation,
+                reason="request_cleanup",
+                submitted_request_ids=(),
+                reserved_request_ids=(),
+            )
+            self.runners.pop(session_id, None)
+            task = asyncio.create_task(runner.expire("request_cleanup"), name=f"duplex-request-cleanup-{session_id}")
+            self._track_task(task)
+        return closed
+
+    def defer_request_cleanups(self, session_ids: Iterable[str]) -> None:
+        session_id_set = set(session_ids)
+        active_keys = {key for key in self._request_cleanups_in_progress if key[0] in session_id_set}
+        self._request_cleanups_in_progress.difference_update(active_keys)
+
+    def finalize_closed_sessions(self, session_ids: Iterable[str]) -> None:
+        session_id_set = set(session_ids)
+        for key in list(self._pending_request_cleanups):
+            if key[0] not in session_id_set:
+                continue
+            self._pending_request_cleanups.pop(key, None)
+            self._request_cleanups_in_progress.discard(key)
+        for session_id in session_id_set:
+            session = self._session_snapshots.pop(session_id, None)
+            if session is not None and session.lease.terminal_reason is not None:
+                session.release_all_requests()
+                session.close()
+            self._closing.pop(session_id, None)
+            self._unregister_session_requests(session_id)
+
+    async def _complete_request_cleanup(
+        self,
+        key: tuple[str, int],
+        pending: _PendingRequestCleanup,
+    ) -> None:
+        task = self._request_cleanup_tasks.get(key)
+        if task is not None and task.done():
+            self._request_cleanup_tasks.pop(key, None)
+            task = None
+        if task is None:
+            task = asyncio.create_task(
+                self._run_request_cleanup(key, pending),
+                name=f"duplex-request-cleanup-{pending.session_id}",
+            )
+            self._request_cleanup_tasks[key] = task
+
+            def discard(completed: asyncio.Task[None]) -> None:
+                if self._request_cleanup_tasks.get(key) is completed:
+                    self._request_cleanup_tasks.pop(key, None)
+
+            task.add_done_callback(discard)
+        await asyncio.shield(task)
+
+    async def _run_request_cleanup(self, key: tuple[str, int], pending: _PendingRequestCleanup) -> None:
+        await self.stage_port.cleanup(list(pending.request_ids), abort=pending.abort)
+        if self._pending_request_cleanups.get(key) is pending:
+            self._pending_request_cleanups.pop(key, None)
+            self._request_cleanups_in_progress.discard(key)
+        self.finalize_closed_sessions([pending.session_id])
+
+    # ------------------------------------------------------------------ #
+    # Shutdown                                                           #
+    # ------------------------------------------------------------------ #
+
+    async def shutdown(self) -> None:
+        runners = list(self.runners.values())
+        self.runners.clear()
+        for runner in runners:
+            try:
+                await runner.shutdown()
+            except Exception:
+                logger.exception("duplex runner shutdown failed for %s", runner.session.session_id)
+        tasks = tuple(self._dispatched_control_tasks | set(self._request_cleanup_tasks.values()))
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        self._session_control_tails.clear()
+        self._closing.clear()
+        self._session_snapshots.clear()
+        self._request_index.clear()
+        if self._owns_executor:
+            self.executor.shutdown(wait=False, cancel_futures=True)
+
+
+__all__ = ["DuplexSessionManager"]
diff --git a/vllm_omni/engine/duplex/session/model_channel.py b/vllm_omni/engine/duplex/session/model_channel.py
new file mode 100644
index 00000000000..322db7edeaf
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/model_channel.py
@@ -0,0 +1,1100 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The model side of one duplex session.
+
+Everything between the session and the model runtime: planning an append with
+the plugin and submitting it to the stage port, turning the stage output that
+comes back into session events, and -- when the model chooses to keep listening
+-- offering it another unit of silence so the turn can continue.
+
+Those three read as separate concerns but they call each other in a cycle. An
+append submits and immediately projects its own first outputs; a projected
+output can schedule a continuation; a continuation is another append. Splitting
+them into three modules would mean three mutual imports and no fewer edges, so
+they are one component whose seam with the runner is narrow instead.
+
+That seam is three callbacks, for the three things this component triggers but
+does not own: closing the session, scheduling the continuation append as a
+tracked task, and aborting a stage request in the background.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import replace
+from typing import TYPE_CHECKING, Protocol
+
+import pybase64 as base64
+from vllm.logger import init_logger
+
+from vllm_omni.engine.duplex.config import DuplexSessionState
+from vllm_omni.engine.duplex.contracts import (
+    DuplexAppendPlan,
+    DuplexFence,
+    DuplexOutputContext,
+    DuplexOutputDecision,
+    DuplexStageSubmission,
+    duplex_data_plane_request_info,
+)
+from vllm_omni.engine.duplex.plugin import (
+    DuplexRuntimeConfigError,
+    coerce_int,
+    payload_turn_id,
+)
+from vllm_omni.engine.duplex.session.context import DuplexSessionContext, StageOutput
+from vllm_omni.engine.duplex.session.emitter import SessionEmitter
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession, DuplexFenceMismatchError
+from vllm_omni.engine.duplex.session.lease import DuplexLeaseActivity
+from vllm_omni.metrics.stats import OrchestratorAggregator, StageRequestStats
+from vllm_omni.outputs import OmniRequestOutput
+from vllm_omni.outputs.duplex import attach_duplex_output_decision
+
+if TYPE_CHECKING:
+    from vllm.outputs import RequestOutput
+
+logger = init_logger(__name__)
+
+
+class SilenceContinuationScheduler(Protocol):
+    """Runs one continuation append as a tracked task (see ``_schedule_silence_continuation``)."""
+
+    async def __call__(
+        self,
+        payload: dict[str, object],
+        *,
+        request_id: str,
+        owner_id: str,
+        response_id: str | None,
+        response_owned: bool,
+        expected_epoch: int | None,
+        expected_model_turn_id: int | None,
+    ) -> bool: ...
+
+
+class ModelChannel:
+    """Appends out to the model, events back from it, for one session."""
+
+    # One MiniCPM model unit (1 s at 16 kHz) is the compatibility default.
+    _SILENCE_UNIT_PAYLOAD_AUDIO = base64.b64encode(bytes(16000 * 4)).decode("ascii")
+    _RESPONSE_MAX_CONTINUATION_UNITS = 8
+    _AUTO_RESPONSE_MAX_CONTINUATION_UNITS = 64
+
+    def __init__(
+        self,
+        ctx: DuplexSessionContext,
+        out: SessionEmitter,
+        *,
+        close_from_runtime: Callable[[str], Awaitable[None]],
+        schedule_silence_continuation: SilenceContinuationScheduler,
+        abort_request: Callable[..., Awaitable[None]],
+    ) -> None:
+        self._ctx = ctx
+        self._out = out
+        self._close_from_runtime = close_from_runtime
+        self._schedule_silence_continuation = schedule_silence_continuation
+        self._abort_request = abort_request
+
+    @staticmethod
+    def should_commit_response_to_history(session: DuplexEngineSession, response_id: str | None) -> bool:
+        if response_id is not None and response_id != session.active_response_id:
+            return True
+        mode = session.response_config.extra_body.get("realtime_response_conversation")
+        return not isinstance(mode, str) or mode.strip().lower() != "none"
+
+    def response_created_payload(
+        self,
+        response_id: str,
+        *,
+        epoch: int,
+        request_id: str | None = None,
+    ) -> dict[str, object]:
+        session = self._ctx.session
+        response_config = session.response_config
+        payload: dict[str, object] = {
+            "type": "response.created",
+            "session_id": session.session_id,
+            "response_id": response_id,
+            "epoch": epoch,
+            "modalities": list(response_config.modalities),
+        }
+        if request_id is not None:
+            payload["request_id"] = request_id
+        metadata = response_config.extra_body.get("realtime_response_metadata")
+        if not isinstance(metadata, dict):
+            metadata = response_config.extra_body.get("realtime_metadata")
+        if isinstance(metadata, dict):
+            payload["metadata"] = dict(metadata)
+        conversation = response_config.extra_body.get("realtime_response_conversation")
+        if isinstance(conversation, str):
+            payload["conversation"] = conversation
+        prompt = response_config.extra_body.get("realtime_response_prompt")
+        if isinstance(prompt, dict):
+            payload["prompt"] = dict(prompt)
+        return payload
+
+    # ------------------------------------------------------------------ #
+    # Submitting an append                                               #
+    # ------------------------------------------------------------------ #
+
+    async def append_runtime_input(
+        self,
+        payload: object,
+        *,
+        operation_id: str | None = None,
+        final: bool,
+        expected_epoch: int | None = None,
+    ) -> tuple[bool, bool]:
+        session = self._ctx.session
+        if not session.capabilities.supports_input_append:
+            return True, False
+        if expected_epoch is not None and session.epoch != expected_epoch:
+            return True, False
+        try:
+            result = await self._append_via_data_plane(
+                payload,
+                final=final,
+                operation_id=operation_id,
+                expected_epoch=expected_epoch,
+            )
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.exception("Failed to append duplex runtime input: %s", exc)
+            self.send_runtime_error("runtime_append_failed", exc)
+            return False, False
+        if result is None:
+            return True, False
+        if expected_epoch is not None and session.epoch != expected_epoch:
+            return True, False
+        request_id, _ = duplex_data_plane_request_info(result)
+        if request_id is not None:
+            self._ctx.plugin.data_plane.begin_request(request_id)
+        close_reason, emitted_response = await self._send_model_output_events(result, expected_epoch=expected_epoch)
+        emitted_response = emitted_response or request_id is not None
+        if close_reason is None and self._start_data_plane_stream(result):
+            emitted_response = True
+        if close_reason is not None:
+            await self._close_from_runtime(close_reason)
+            return False, emitted_response
+        return True, emitted_response
+
+    async def _append_via_data_plane(
+        self,
+        payload: object,
+        *,
+        final: bool,
+        operation_id: str | None,
+        expected_epoch: int | None,
+    ) -> dict[str, object] | None:
+        """Submit one planned append to the stage port and bind the resulting stage request."""
+        session = self._ctx.session
+        if self._ctx.stage_port.stage_count == 0:
+            raise RuntimeError("duplex_data_plane_has_no_stage")
+        payload_turn = payload_turn_id(payload)
+        fence = DuplexFence(
+            session.session_id,
+            epoch=session.epoch,
+            turn_id=(
+                payload_turn
+                if payload_turn is not None
+                else (
+                    session.active_response_turn_id if session.active_response_turn_id is not None else session.turn_id
+                )
+            ),
+        )
+        lease_operation_id = f"append:{operation_id or uuid.uuid4().hex}"
+        operation_started = False
+        stage_id = 0
+        request_id = self._ctx.manager.stage_request_id(fence, stage_id=stage_id)
+        try:
+            session.begin_lease_operation(fence, lease_operation_id)
+            operation_started = True
+            reservation = session.prepare_append(fence)
+            already_submitted = session.stage_request_submitted(stage_id, request_id)
+            request_context = self._ctx.manager.ensure_stage_request(session, stage_id=stage_id, fence=fence)
+            if request_context is None:
+                raise RuntimeError("duplex_data_plane_has_no_stage")
+            append_plan = self._ctx.plugin.plan_append(
+                request_id=request_id,
+                fence=fence,
+                session_config=dict(request_context.session_config),
+                runtime_config=dict(request_context.runtime_config),
+                seq=reservation.update.seq,
+                turn_seq=reservation.update.turn_seq,
+                payload=payload,
+                final=final,
+                sampling_params=request_context.stage_sampling_params,
+            )
+            if not isinstance(append_plan, DuplexAppendPlan):
+                raise TypeError("duplex plugin plan_append() must return DuplexAppendPlan")
+            submission = DuplexStageSubmission(
+                context=request_context,
+                prompt=append_plan.prompt,
+                already_submitted=already_submitted,
+            )
+            submission_result = await self._ctx.stage_port.submit(submission)
+            try:
+                if submission_result.request_id != request_id or submission_result.stage_id != stage_id:
+                    raise RuntimeError("duplex stage adapter returned a mismatched submission result")
+                if expected_epoch is not None and session.epoch != expected_epoch:
+                    raise DuplexFenceMismatchError(session.fence, fence)
+                update = session.commit_append(reservation)
+                session.bind_stage_request(stage_id, request_id, fence=fence)
+            except BaseException:
+                try:
+                    await self._ctx.stage_port.cleanup([request_id])
+                except Exception as cleanup_exc:
+                    logger.warning(
+                        "duplex append compensation remains pending for session %s: %s",
+                        session.session_id,
+                        cleanup_exc,
+                    )
+                raise
+            session.touch_lease(DuplexLeaseActivity.APPEND)
+            return {
+                "ok": True,
+                "operation": "append",
+                "session_id": session.session_id,
+                "stage_results": [
+                    {
+                        "stage_id": stage_id,
+                        "replica_id": submission_result.replica_id,
+                        "result": {
+                            "supported": True,
+                            "data_plane_append": True,
+                            "request_id": request_id,
+                            "response_stage_id": request_context.final_stage_id,
+                            "seq": update.seq,
+                            "turn_id": update.turn_id,
+                            "turn_seq": update.turn_seq,
+                            "resumable": True,
+                        },
+                    }
+                ],
+            }
+        finally:
+            if operation_started and lease_operation_id in session.lease.active_operations:
+                try:
+                    session.end_lease_operation(lease_operation_id)
+                except Exception:
+                    session.lease.active_operations.discard(lease_operation_id)
+
+    def _start_data_plane_stream(self, result: object) -> bool:
+        """Bind the resumable stage request as the session's active data-plane stream."""
+        request_id, _ = duplex_data_plane_request_info(result) if isinstance(result, dict) else (None, None)
+        if request_id is None or self._data_plane_outputs_finished(result):
+            return False
+        session = self._ctx.session
+        session.bind_request(request_id)
+        if self._ctx.run.stream_request_id == request_id:
+            return False
+        self._ctx.run.stream_request_id = request_id
+        return True
+
+    def cancel_data_plane_stream(self) -> bool:
+        had_stream = self._ctx.run.stream_request_id is not None
+        self._ctx.run.stream_request_id = None
+        return had_stream
+
+    async def signal_cancel_fence(self, cancelled_fence: DuplexFence) -> bool:
+        """In-process equivalent of the old ``barge_in`` control signal."""
+        session = self._ctx.session
+        try:
+            next_fence = session.sync_fence()
+            if next_fence.epoch > cancelled_fence.epoch:
+                stale_request_ids = session.cancel_fence(cancelled_fence, next_fence)
+            else:
+                stale_request_ids = []
+            if stale_request_ids:
+                await self._ctx.stage_port.cleanup(list(stale_request_ids), abort=True)
+            session.touch_lease(DuplexLeaseActivity.SIGNAL)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.exception("Failed to signal duplex runtime session: %s", exc)
+            self.send_runtime_error("runtime_signal_failed", exc)
+            return False
+        return True
+
+    def send_runtime_error(self, code: str, exc: BaseException) -> None:
+        if isinstance(exc, DuplexRuntimeConfigError):
+            code = exc.code
+        self._out.emit_error(code, str(exc), retryable=False)
+
+    @staticmethod
+    def _data_plane_outputs_finished(result: object) -> bool:
+        if not isinstance(result, dict):
+            return False
+        outputs = result.get("data_plane_outputs")
+        if not isinstance(outputs, list) or not outputs:
+            return False
+        return bool(getattr(outputs[-1], "finished", False))
+
+    def _runtime_data_plane_context(self) -> object:
+        session = self._ctx.session
+        response_config = session.response_config
+        return self._ctx.plugin.data_plane_context(
+            epoch=session.epoch,
+            turn_id=session.turn_id,
+            active_response_turn_id=session.active_response_turn_id,
+            active_response_id=session.active_response_id,
+            auto_responds=self._out.auto_responds(),
+            response_format=response_config.response_format,
+            speed=response_config.speed,
+            modalities=tuple(response_config.modalities),
+        )
+
+    # ------------------------------------------------------------------ #
+    # Stage outputs                                                      #
+    # ------------------------------------------------------------------ #
+
+    def decide_output(
+        self, stage_id: int, output: RequestOutput, context: DuplexOutputContext
+    ) -> DuplexOutputDecision | None:
+        """Pure plugin decision (no session mutation: this runs inline on the orchestrator loop)."""
+        decision = self._ctx.plugin.decide_output(
+            stage_id=stage_id,
+            final_stage_id=context.final_stage_id,
+            segment_finished=context.segment_finished,
+            segment_token_ids=context.segment_token_ids,
+            segment_output_metadata=dict(context.segment_output_metadata),
+            output=output,
+        )
+        if decision is not None and not isinstance(decision, DuplexOutputDecision):
+            raise TypeError("duplex plugin decide_output() must return DuplexOutputDecision or None")
+        return decision
+
+    @staticmethod
+    def stage_metrics_snapshot(stage_id: int, metrics: object, output: object) -> dict[str, dict[str, object]] | None:
+        if not isinstance(metrics, StageRequestStats):
+            return None
+        event = metrics
+        if event.stage_id is None:
+            event = replace(event, stage_id=stage_id)
+        if event.final_output_type is None:
+            final_output_type = getattr(output, "final_output_type", None)
+            if isinstance(final_output_type, str):
+                event = replace(event, final_output_type=final_output_type)
+        try:
+            merged = OrchestratorAggregator._merge_stage_metric_event(None, event)
+        except Exception:
+            return None
+        return {str(stage_id): merged}
+
+    def _build_stage_output(self, item: StageOutput) -> OmniRequestOutput:
+        output = item.output
+        finished = bool(getattr(output, "finished", False)) or item.context.segment_finished
+        if item.decision is not None:
+            engine_output = OmniRequestOutput.from_stage_output(
+                output,
+                request_id=item.request_id,
+                stage_id=item.stage_id,
+                final_output_type=item.decision.final_output_type,
+            )
+            # Set after construction, not as a keyword: ``from_stage_output``
+            # copies ``finished`` from the source last, and a resumable stage
+            # request never finishes -- only its segment does. The decision
+            # closes that segment, and the projector recognises a listen only
+            # on a finished output. The orchestrator queue used to re-assert
+            # ``finished`` on every direct-response message; the mailbox hands
+            # the raw stage output over, so it has to happen here.
+            engine_output.finished = True
+            engine_output = attach_duplex_output_decision(engine_output, item.decision)
+        elif isinstance(output, OmniRequestOutput):
+            engine_output = output
+            if finished:
+                engine_output.finished = True
+        else:
+            final_output_type = getattr(output, "final_output_type", None)
+            engine_output = OmniRequestOutput.from_stage_output(
+                output,
+                request_id=item.request_id,
+                finished=finished,
+                stage_id=item.stage_id,
+                final_output_type=final_output_type if isinstance(final_output_type, str) else "audio",
+            )
+        snapshot = self.stage_metrics_snapshot(item.stage_id, item.metrics, output)
+        if snapshot is not None:
+            existing = engine_output.metrics if isinstance(engine_output.metrics, dict) else {}
+            existing_stage_metrics = existing.get("stage_metrics")
+            merged_stage_metrics = (
+                {**existing_stage_metrics, **snapshot} if isinstance(existing_stage_metrics, dict) else snapshot
+            )
+            engine_output.metrics = {**existing, "stage_metrics": merged_stage_metrics}
+        return engine_output
+
+    async def on_stage_output_item(self, item: StageOutput) -> None:
+        session = self._ctx.session
+        if session.state == DuplexSessionState.CLOSED or self._ctx.run.closing:
+            return
+        expected_epoch = item.context.identity.fence.epoch
+        if session.epoch != expected_epoch:
+            return
+        if session.lease.terminal_reason is not None:
+            # Lease already closed/expired: the output belongs to a dead session.
+            return
+        session.touch_lease(DuplexLeaseActivity.MODEL_OUTPUT)
+        if self._ctx.plugin.data_plane.is_terminal(item.request_id):
+            return
+        if self._out.auto_responds():
+            active_request_id = session.active_request_id
+            if active_request_id is not None and active_request_id != item.request_id:
+                return
+        engine_output = self._build_stage_output(item)
+        drain_result = {"data_plane_outputs": [engine_output]}
+        close_reason, emitted_response = await self._send_model_output_events(
+            drain_result, expected_epoch=expected_epoch
+        )
+        if close_reason is not None:
+            await self._close_from_runtime(close_reason)
+            return
+        finished = self._data_plane_outputs_finished(drain_result)
+        if finished and emitted_response and not self._out.auto_responds():
+            # A finished, emitted response releases the per-request projector
+            # cursor on its way out and offers the model another
+            # silence unit.
+            self._ctx.plugin.data_plane.close_stream(item.request_id)
+            if self._ctx.run.stream_request_id == item.request_id:
+                self._ctx.run.stream_request_id = None
+            self._ctx.services.spawn(
+                self.maybe_continue_response(expected_epoch=expected_epoch),
+                name="duplex-continue",
+            )
+
+    async def _send_model_output_events(
+        self,
+        result: object,
+        *,
+        expected_epoch: int | None = None,
+    ) -> tuple[str | None, bool]:
+        session = self._ctx.session
+        if expected_epoch is not None and session.epoch != expected_epoch:
+            return None, False
+        close_reason: str | None = None
+        emitted_response = False
+        request_id, _ = duplex_data_plane_request_info(result) if isinstance(result, dict) else (None, None)
+        if self._ctx.plugin.data_plane.is_terminal(request_id):
+            return None, False
+        if request_id is not None and session.active_request_id is None:
+            session.bind_request(request_id)
+        context = self._runtime_data_plane_context()
+        for model_result in self._ctx.plugin.data_plane.project(result, context=context):
+            close_reason_for_result, did_emit = await self._send_one_model_output_event(
+                model_result,
+                expected_epoch=expected_epoch,
+            )
+            emitted_response = emitted_response or did_emit
+            close_reason = close_reason or close_reason_for_result
+            if expected_epoch is not None and session.epoch != expected_epoch:
+                return None, emitted_response
+        return close_reason, emitted_response
+
+    def _fail_response_from_model_error(self, model_result: dict[str, object]) -> None:
+        """Report a data-plane error and fail the response it interrupted."""
+        session = self._ctx.session
+        response_id = session.active_response_id
+        self._out.emit_error(
+            str(model_result.get("error_code")),
+            str(model_result.get("error") or "Duplex native data-plane error"),
+        )
+        if response_id is None:
+            return
+        session.end_response(commit_text=False)
+        self._out.emit(
+            {
+                "type": "response.done",
+                "session_id": session.session_id,
+                "response_id": response_id,
+                "epoch": session.epoch,
+                "committed": False,
+                "status": "failed",
+                "status_details": {"type": "failed", "reason": model_result.get("error_code")},
+                "playback": session.playback.as_dict(),
+            }
+        )
+
+    def _complete_model_turn_without_output(
+        self,
+        model_result: dict[str, object],
+        *,
+        model_turn_id: int | None,
+        data_plane_request_id: object,
+    ) -> bool:
+        """The model ended its turn with nothing to say.
+
+        Returns whether an event was emitted: an auto-response session reports
+        the decision as a listen, a turn-based one simply releases the request.
+        """
+        session = self._ctx.session
+        data_plane = self._ctx.plugin.data_plane
+        auto_response = self._out.auto_responds()
+        if isinstance(data_plane_request_id, str):
+            if not auto_response and data_plane_request_id == session.active_request_id:
+                session.clear_request()
+            if not auto_response:
+                data_plane.mark_terminal(data_plane_request_id)
+        if model_turn_id is not None:
+            session.complete_model_turn(model_turn_id)
+        if not auto_response:
+            return False
+        self._ctx.model_state.clear_continuation()
+        payload = {
+            "type": "response.listen",
+            "session_id": session.session_id,
+            "epoch": session.epoch,
+            "reason": "model_turn_completed_without_output",
+            "model_listen": True,
+        }
+        self._attach_runtime_metadata(payload, model_result)
+        self._out.emit(payload)
+        return True
+
+    async def _on_model_listen(
+        self,
+        model_result: dict[str, object],
+        *,
+        model_turn_id: int | None,
+        data_plane_request_id: object,
+        expected_epoch: int | None,
+    ) -> tuple[str | None, bool]:
+        """The model chose to keep listening rather than speak.
+
+        Either it continues the current response with another unit, or the
+        response ends here: an auto-response session that has continuations
+        left schedules one, and anything else closes the turn out.
+        """
+        session = self._ctx.session
+        model_state = self._ctx.model_state
+        data_plane = self._ctx.plugin.data_plane
+        auto_response = self._out.auto_responds()
+        close_reason: str | None = None
+        emitted_response = False
+        self._end_active_response_before_future_model_turn(model_turn_id=model_turn_id)
+        if (
+            session.active_response_id is not None
+            and model_turn_id is not None
+            and not session.active_response_accepts_model_turn(model_turn_id)
+        ):
+            return close_reason, emitted_response
+        active_response_id = session.active_response_id
+        auto_continuations_remaining = active_response_id is None or self.response_continuations_remaining(
+            active_response_id
+        )
+        non_terminal_auto_listen = (
+            auto_response
+            and active_response_id is not None
+            and session.active_request_id is not None
+            and model_result.get("end_of_turn") is not True
+            and auto_continuations_remaining
+        )
+        if non_terminal_auto_listen:
+            self._ctx.services.spawn(
+                self.maybe_continue_response(expected_epoch=expected_epoch), name="duplex-continue"
+            )
+            return close_reason, emitted_response
+        if not auto_response and data_plane_request_id == session.active_request_id:
+            session.clear_request()
+        model_listen = model_result.get("model_listen")
+        if not isinstance(model_listen, bool):
+            model_listen = model_result.get("reason") in {None, "", "model_listen"}
+        response_id = session.active_response_id
+        if isinstance(data_plane_request_id, str) and not auto_response:
+            data_plane.mark_terminal(data_plane_request_id)
+        emitted_response = True
+        payload = {
+            "type": "response.listen",
+            "session_id": session.session_id,
+            "epoch": session.epoch,
+            "reason": model_result.get("reason") or "model_listen",
+            "model_listen": model_listen,
+        }
+        if response_id is not None:
+            payload["response_id"] = response_id
+        self._attach_runtime_metadata(payload, model_result)
+        self._out.emit(payload)
+        if model_result.get("abort_data_plane_request") is True and isinstance(data_plane_request_id, str):
+            await self._abort_request(data_plane_request_id, notify=False)
+        if response_id is not None:
+            if not auto_response and self.response_continuations_remaining(response_id):
+                self._ctx.services.spawn(
+                    self.maybe_continue_response(expected_epoch=expected_epoch), name="duplex-continue"
+                )
+                return close_reason, emitted_response
+            if auto_response:
+                model_state.clear_continuation()
+                if not auto_continuations_remaining:
+                    completed_turn_id = model_turn_id
+                    if completed_turn_id is None:
+                        completed_turn_id = session.active_response_turn_id
+                    if completed_turn_id is not None:
+                        session.complete_model_turn(completed_turn_id)
+            session.end_response(commit_text=False, preserve_request=auto_response)
+            self._out.emit(
+                {
+                    "type": "response.done",
+                    "session_id": session.session_id,
+                    "response_id": response_id,
+                    "epoch": session.epoch,
+                    "committed": False,
+                    "playback": session.playback.as_dict(),
+                }
+            )
+        return close_reason, emitted_response
+
+    async def _send_one_model_output_event(
+        self,
+        model_result: dict[str, object],
+        *,
+        expected_epoch: int | None = None,
+    ) -> tuple[str | None, bool]:
+        session = self._ctx.session
+        data_plane = self._ctx.plugin.data_plane
+        close_reason: str | None = None
+        emitted_response = False
+        if expected_epoch is not None and session.epoch != expected_epoch:
+            return close_reason, emitted_response
+        data_plane_request_id = model_result.get("data_plane_request_id")
+        if isinstance(data_plane_request_id, str) and data_plane.is_terminal(data_plane_request_id):
+            return close_reason, emitted_response
+        auto_response = self._out.auto_responds()
+        active_request_matches = session.active_request_id == data_plane_request_id or (
+            auto_response and session.active_request_id is None
+        )
+        if isinstance(data_plane_request_id, str) and not active_request_matches:
+            return close_reason, emitted_response
+        if isinstance(model_result.get("error_code"), str):
+            self._fail_response_from_model_error(model_result)
+            return close_reason, True
+        if model_result.get("function_call") is True:
+            self._out.emit(
+                {
+                    "type": "function_call.done",
+                    "session_id": session.session_id,
+                    "epoch": session.epoch,
+                    "call_id": model_result.get("call_id"),
+                    "name": model_result.get("name"),
+                    "arguments": model_result.get("arguments", ""),
+                }
+            )
+            return close_reason, True
+        if model_result.get("requires_stage_handoff") is True or model_result.get("requires_tts_stage") is True:
+            # Reserve the protocol response only when Stage1 emits text/audio.
+            return close_reason, False
+        is_listen = model_result.get("is_listen")
+        model_turn_id = coerce_int(model_result.get("model_turn_id"))
+        if model_result.get("is_buffering") is True or model_result.get("prefill_success") is False:
+            if model_result.get("data_plane_request_id") == session.active_request_id:
+                session.clear_request()
+            payload = {
+                "type": "response.listen",
+                "session_id": session.session_id,
+                "epoch": session.epoch,
+                "reason": model_result.get("reason") or "buffering",
+                "model_listen": False,
+                "buffering": True,
+            }
+            self._attach_runtime_metadata(payload, model_result)
+            self._out.emit(payload)
+            return close_reason, emitted_response
+        if is_listen is True:
+            return await self._on_model_listen(
+                model_result,
+                model_turn_id=model_turn_id,
+                data_plane_request_id=data_plane_request_id,
+                expected_epoch=expected_epoch,
+            )
+
+        text = model_result.get("text")
+        audio = model_result.get("audio_data", model_result.get("audio"))
+        end_of_turn = bool(model_result.get("end_of_turn", False))
+        has_text = isinstance(text, str) and bool(text)
+        has_audio = isinstance(audio, str) and bool(audio)
+        if not has_text and not has_audio and not end_of_turn:
+            tts_segment_ended = (
+                model_result.get("stage_role") == "tts" and model_result.get("abort_data_plane_request") is True
+            )
+            if (
+                tts_segment_ended
+                and auto_response
+                and (model_turn_id is not None or session.active_response_id is not None)
+            ):
+                self._ctx.services.spawn(
+                    self.maybe_continue_response(expected_epoch=expected_epoch, expected_model_turn_id=model_turn_id),
+                    name="duplex-continue",
+                )
+            return close_reason, emitted_response
+        if end_of_turn and not has_text and not has_audio and session.active_response_id is None:
+            emitted_response = self._complete_model_turn_without_output(
+                model_result,
+                model_turn_id=model_turn_id,
+                data_plane_request_id=data_plane_request_id,
+            )
+            return close_reason, emitted_response
+        if session.active_response_id is None and model_turn_id is not None and model_turn_id < session.turn_id:
+            # Late audio of a completed model turn must not reserve a second response.
+            return close_reason, emitted_response
+        self._end_active_response_before_future_model_turn(model_turn_id=model_turn_id)
+        if (
+            session.active_response_id is not None
+            and model_turn_id is not None
+            and not session.active_response_accepts_model_turn(model_turn_id)
+        ):
+            return close_reason, emitted_response
+        emitted_response = True
+        response_created = False
+        response_id = session.active_response_id
+        if response_id is None:
+            response_id = session.begin_response(turn_id=model_turn_id)
+            response_created = True
+            self._out.emit(self.response_created_payload(response_id, epoch=session.epoch))
+        response_stage_metrics = session.accumulate_response_stage_metrics(
+            model_result.get("stage_metrics") if isinstance(model_result.get("stage_metrics"), Mapping) else None
+        )
+        if response_created:
+            speak_payload = {
+                "type": "response.speak",
+                "session_id": session.session_id,
+                "response_id": response_id,
+                "epoch": session.epoch,
+                "text": text if isinstance(text, str) else "",
+                "end_of_turn": end_of_turn,
+                "model_speak": True,
+            }
+            self._attach_runtime_metadata(speak_payload, model_result, stage_metrics=response_stage_metrics)
+            self._out.emit(speak_payload)
+        previous_sent_ms = session.playback.sent_ms
+        text_chars_before_append = len("".join(session.assistant_text_buffer))
+        if isinstance(text, str):
+            session.append_assistant_text(text)
+        duration_ms = model_result.get("audio_duration_ms")
+        text_chars = len("".join(session.assistant_text_buffer))
+        mark_duration_ms = None
+        mark_text_chars: int | None = text_chars
+        if model_result.get("audio_text_mark") is False:
+            mark_text_chars = None
+        if isinstance(duration_ms, int | float):
+            mark_duration_ms = int(duration_ms)
+            if model_result.get("audio_duration_is_cumulative") is not True:
+                mark_duration_ms += session.playback.sent_ms
+        audio_text_marks = model_result.get("audio_text_marks")
+        audio_text_marks = self._normalize_audio_text_marks(
+            audio_text_marks if isinstance(audio_text_marks, list) else None,
+            audio_offset_ms=(
+                0
+                if model_result.get("audio_text_marks_are_cumulative") is True
+                or model_result.get("audio_duration_is_cumulative") is True
+                else previous_sent_ms
+            ),
+            text_offset_chars=(
+                0 if model_result.get("audio_text_marks_are_cumulative") is True else text_chars_before_append
+            ),
+        )
+        session.mark_audio_sent(
+            mark_duration_ms,
+            text_chars=mark_text_chars if mark_duration_ms is not None else None,
+            audio_text_marks=audio_text_marks,
+        )
+        payload = {
+            "type": "response.output_audio.delta",
+            "session_id": session.session_id,
+            "response_id": response_id,
+            "epoch": session.epoch,
+            "text": text if isinstance(text, str) else "",
+            "audio": audio if isinstance(audio, str) else "",
+            "format": (
+                model_result.get("audio_format")
+                if isinstance(model_result.get("audio_format"), str)
+                else session.response_config.response_format
+            ),
+            "end_of_turn": end_of_turn,
+            "model_speak": True,
+        }
+        if mark_duration_ms is not None:
+            payload["audio_duration_ms"] = mark_duration_ms
+        if audio_text_marks:
+            payload["audio_text_marks"] = audio_text_marks
+        elif mark_duration_ms is not None and mark_text_chars is not None:
+            payload["audio_text_marks"] = [
+                {"text_chars": max(0, int(mark_text_chars)), "audio_end_ms": max(0, int(mark_duration_ms))}
+            ]
+        payload["playback"] = session.playback.as_dict()
+        sample_rate_hz = model_result.get("sample_rate_hz") or model_result.get("audio_sample_rate_hz")
+        if isinstance(sample_rate_hz, int | float) and int(sample_rate_hz) > 0:
+            payload["sample_rate_hz"] = int(sample_rate_hz)
+        self._attach_runtime_metadata(payload, model_result, stage_metrics=response_stage_metrics)
+        self._out.emit(payload)
+        if (
+            not end_of_turn
+            and model_result.get("stage_role") == "tts"
+            and model_result.get("abort_data_plane_request") is True
+            and auto_response
+        ):
+            self._ctx.services.spawn(
+                self.maybe_continue_response(expected_epoch=expected_epoch), name="duplex-continue"
+            )
+        if end_of_turn:
+            data_plane_request_id = model_result.get("data_plane_request_id")
+            if isinstance(data_plane_request_id, str) and not auto_response:
+                data_plane.close_stream(data_plane_request_id)
+            if isinstance(data_plane_request_id, str):
+                if not auto_response and data_plane_request_id == session.active_request_id:
+                    session.clear_request()
+                if not auto_response:
+                    data_plane.mark_terminal(data_plane_request_id)
+            should_commit = self.should_commit_response_to_history(session, response_id)
+            committed_message = session.end_response(commit_text=should_commit, preserve_request=auto_response)
+            model_turn_id = coerce_int(model_result.get("model_turn_id"))
+            if model_turn_id is not None:
+                session.complete_model_turn(model_turn_id)
+            if should_commit:
+                session.register_history_item(f"item_{response_id}", committed_message)
+            self._out.emit(
+                {
+                    "type": "response.done",
+                    "session_id": session.session_id,
+                    "response_id": response_id,
+                    "epoch": session.epoch,
+                    "committed": committed_message is not None,
+                    "playback": session.playback.as_dict(),
+                }
+            )
+        return close_reason, emitted_response
+
+    def _end_active_response_before_future_model_turn(self, *, model_turn_id: int | None) -> None:
+        session = self._ctx.session
+        if not self._out.auto_responds():
+            return
+        response_id = session.active_response_id
+        active_turn_id = session.active_response_turn_id
+        if response_id is None or model_turn_id is None or active_turn_id is None:
+            return
+        if int(model_turn_id) <= int(active_turn_id):
+            return
+        session.complete_model_turn(int(model_turn_id) - 1)
+        should_commit = self.should_commit_response_to_history(session, response_id)
+        committed_message = session.end_response(commit_text=should_commit, preserve_request=True)
+        if should_commit:
+            session.register_history_item(f"item_{response_id}", committed_message)
+        self._out.emit(
+            {
+                "type": "response.done",
+                "session_id": session.session_id,
+                "response_id": response_id,
+                "epoch": session.epoch,
+                "committed": committed_message is not None,
+                "playback": session.playback.as_dict(),
+            }
+        )
+
+    @staticmethod
+    def _normalize_audio_text_marks(
+        audio_text_marks: list[object] | None,
+        *,
+        audio_offset_ms: int,
+        text_offset_chars: int,
+    ) -> list[dict[str, int]] | None:
+        if not audio_text_marks:
+            return None
+        normalized: list[dict[str, int]] = []
+        for raw_mark in audio_text_marks:
+            if not isinstance(raw_mark, dict):
+                continue
+            raw_text_chars = raw_mark.get("text_chars")
+            raw_audio_end_ms = raw_mark.get("audio_end_ms", raw_mark.get("audio_ms"))
+            if not isinstance(raw_text_chars, int | float) or not isinstance(raw_audio_end_ms, int | float):
+                continue
+            normalized.append(
+                {
+                    "text_chars": max(0, int(raw_text_chars) + int(text_offset_chars)),
+                    "audio_end_ms": max(0, int(raw_audio_end_ms) + int(audio_offset_ms)),
+                }
+            )
+        return normalized or None
+
+    @staticmethod
+    def _attach_runtime_metadata(
+        payload: dict[str, object],
+        model_result: dict[str, object],
+        *,
+        stage_metrics: Mapping[str, object] | None = None,
+    ) -> None:
+        metadata: dict[str, object] = {}
+        runtime_impl = model_result.get("runtime_impl")
+        if isinstance(runtime_impl, str) and runtime_impl:
+            metadata["runtime_impl"] = runtime_impl
+        owned_runtime = model_result.get("owned_runtime")
+        if isinstance(owned_runtime, bool):
+            metadata["owned_runtime"] = owned_runtime
+        model_turn_id = coerce_int(model_result.get("model_turn_id"))
+        if model_turn_id is not None:
+            metadata["model_turn_id"] = model_turn_id
+        for name in ("uses_model_runner_scheduler", "runner_kv_backed"):
+            value = model_result.get(name)
+            if isinstance(value, bool):
+                metadata[name] = value
+        effective_stage_metrics = stage_metrics if stage_metrics is not None else model_result.get("stage_metrics")
+        if isinstance(effective_stage_metrics, Mapping):
+            metadata["stage_metrics"] = {
+                str(stage_id): dict(values)
+                for stage_id, values in effective_stage_metrics.items()
+                if isinstance(values, Mapping)
+            }
+        if metadata:
+            payload["vllm_omni"] = metadata
+
+    # ------------------------------------------------------------------ #
+    # Silence continuation                                               #
+    # ------------------------------------------------------------------ #
+
+    def silence_unit_payload(self) -> dict[str, object]:
+        samples = int(self._ctx.plugin.silence_continuation_samples)
+        audio = (
+            self._SILENCE_UNIT_PAYLOAD_AUDIO
+            if samples == 16000
+            else base64.b64encode(bytes(samples * 4)).decode("ascii")
+        )
+        return {"type": "audio", "audio": audio, "format": "pcm_f32le", "sample_rate_hz": 16000}
+
+    def response_continuations_remaining(self, response_id: str) -> bool:
+        model_state = self._ctx.model_state
+        owner_id = f"response:{response_id}"
+        count = model_state.continuation_units if model_state.continuation_owner_id == owner_id else 0
+        limit = (
+            self._AUTO_RESPONSE_MAX_CONTINUATION_UNITS
+            if self._out.auto_responds()
+            else self._RESPONSE_MAX_CONTINUATION_UNITS
+        )
+        return count < limit
+
+    async def _finish_bounded_auto_response(
+        self,
+        *,
+        expected_epoch: int | None,
+        model_turn_id: int | None = None,
+    ) -> None:
+        session = self._ctx.session
+        model_state = self._ctx.model_state
+        response_id = session.active_response_id
+        response_epoch = session.epoch
+        response_turn_id = model_turn_id if model_turn_id is not None else session.active_response_turn_id
+        if expected_epoch is not None and response_epoch != expected_epoch:
+            return
+        model_state.clear_continuation()
+        payload: dict[str, object] = {
+            "type": "response.listen",
+            "session_id": session.session_id,
+            "epoch": response_epoch,
+            "reason": "continuation_limit",
+            "model_listen": False,
+        }
+        if response_id is not None:
+            payload["response_id"] = response_id
+        self._out.emit(payload)
+        if response_id is None:
+            if session.epoch == response_epoch and response_turn_id is not None:
+                session.complete_model_turn(response_turn_id)
+            return
+        if session.epoch != response_epoch or session.active_response_id != response_id:
+            return
+        if response_turn_id is not None:
+            session.complete_model_turn(response_turn_id)
+        session.end_response(commit_text=False, preserve_request=True)
+        self._out.emit(
+            {
+                "type": "response.done",
+                "session_id": session.session_id,
+                "response_id": response_id,
+                "epoch": response_epoch,
+                "committed": False,
+                "playback": session.playback.as_dict(),
+            }
+        )
+
+    def silence_continuation_is_stale(
+        self,
+        *,
+        request_id: str,
+        response_id: str | None,
+        response_owned: bool,
+        expected_epoch: int | None,
+        expected_model_turn_id: int | None,
+    ) -> bool:
+        session = self._ctx.session
+        stale_common_owner = (
+            session.state == DuplexSessionState.CLOSED
+            or session.active_request_id != request_id
+            or (expected_epoch is not None and session.epoch != expected_epoch)
+        )
+        stale_response_owner = response_owned and session.active_response_id != response_id
+        stale_model_turn_owner = not response_owned and (
+            session.active_response_id is not None or session.turn_id != expected_model_turn_id
+        )
+        return stale_common_owner or stale_response_owner or stale_model_turn_owner
+
+    async def maybe_continue_response(
+        self,
+        *,
+        expected_epoch: int | None,
+        expected_model_turn_id: int | None = None,
+    ) -> None:
+        session = self._ctx.session
+        model_state = self._ctx.model_state
+        response_id = session.active_response_id
+        if session.state == DuplexSessionState.CLOSED or self._ctx.run.closing:
+            model_state.clear_continuation()
+            return
+        request_id = session.active_request_id
+        if request_id is None:
+            model_state.clear_continuation()
+            return
+        if expected_epoch is not None and session.epoch != expected_epoch:
+            return
+        auto_response = self._out.auto_responds()
+        response_owned = response_id is not None
+        if response_owned:
+            owner_id = f"response:{response_id}"
+            payload_turn_id_value = (
+                session.active_response_turn_id if session.active_response_turn_id is not None else session.turn_id
+            )
+        else:
+            if not auto_response or expected_model_turn_id is None or session.turn_id != expected_model_turn_id:
+                model_state.clear_continuation()
+                return
+            owner_id = f"model-turn:{expected_model_turn_id}"
+            payload_turn_id_value = expected_model_turn_id
+        count = model_state.continuation_units if model_state.continuation_owner_id == owner_id else 0
+        continuation_limit = (
+            self._AUTO_RESPONSE_MAX_CONTINUATION_UNITS if auto_response else self._RESPONSE_MAX_CONTINUATION_UNITS
+        )
+        if count >= continuation_limit:
+            if auto_response:
+                await self._finish_bounded_auto_response(
+                    expected_epoch=expected_epoch,
+                    model_turn_id=payload_turn_id_value,
+                )
+            return
+        payload = self.silence_unit_payload()
+        if auto_response and count + 1 == continuation_limit:
+            payload["force_listen"] = True
+        payload["duplex_turn_id"] = payload_turn_id_value
+        try:
+            scheduled = await self._schedule_silence_continuation(
+                payload,
+                request_id=request_id,
+                owner_id=owner_id,
+                response_id=response_id,
+                response_owned=response_owned,
+                expected_epoch=expected_epoch,
+                expected_model_turn_id=expected_model_turn_id,
+            )
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.exception("Failed to schedule duplex native response continuation: %s", exc)
+            scheduled = False
+        if scheduled:
+            model_state.continuation_owner_id = owner_id
+            model_state.continuation_units = count + 1
diff --git a/vllm_omni/engine/duplex/session/overlap_policy.py b/vllm_omni/engine/duplex/session/overlap_policy.py
new file mode 100644
index 00000000000..0aad0436872
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/overlap_policy.py
@@ -0,0 +1,388 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""How one duplex session reacts to input that arrives while it is speaking.
+
+Short acknowledgement, barge-in, or keep listening: the rules read the session
+config and the incoming append, and nothing else. Extracted from
+``DuplexSessionRunner`` because they were a decision function wearing a
+method's clothes -- the only runner state they ever touched was ``session`` --
+and because reaching them previously meant driving a whole append through the
+runner.
+"""
+
+from __future__ import annotations
+
+import binascii
+from collections.abc import Mapping
+
+import numpy as np
+import pybase64 as base64
+
+from vllm_omni.engine.duplex.config import DuplexOverlapPolicy
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession
+
+
+def decide(
+    session: DuplexEngineSession,
+    event: dict[str, object],
+    payload: dict[str, object],
+    *,
+    auto_responds: bool,
+) -> dict[str, object]:
+    duration_ms = input_audio_duration_ms(event, payload)
+    is_speech = input_looks_like_speech(session, event, payload)
+    if not session.capabilities.supports_barge_in and event_requests_barge_in(event):
+        return defer_unsupported_barge_in(session, duration_ms=duration_ms, is_speech=is_speech)
+    explicit = event.get("overlap_action") or event.get("overlap")
+    if isinstance(explicit, str):
+        normalized = explicit.strip().lower()
+        if normalized in {"barge_in", "interrupt", "cancel"}:
+            return {
+                "action": "barge_in",
+                "reason": "client_overlap_action",
+                "duration_ms": duration_ms,
+                "buffer_audio": True,
+            }
+        if normalized in {"listen", "continue", "continue_output", "ack"}:
+            session.reset_overlap_speech()
+            return {
+                "action": "listen",
+                "reason": "client_overlap_action",
+                "duration_ms": duration_ms,
+                "buffer_audio": (
+                    normalized == "listen" and is_speech and duration_ms > session.config.overlap_short_ack_ms
+                ),
+                "defer_runtime_append": True,
+            }
+        if normalized in {"drop", "ignore", "silence"}:
+            session.reset_overlap_speech()
+            return {
+                "action": "drop",
+                "reason": "client_overlap_action",
+                "duration_ms": duration_ms,
+                "buffer_audio": False,
+            }
+
+    if bool(event.get("force_barge_in", False)):
+        return {
+            "action": "barge_in",
+            "reason": "client_force_barge_in",
+            "duration_ms": duration_ms,
+            "buffer_audio": True,
+        }
+    if auto_responds:
+        if is_speech:
+            session.accumulate_overlap_speech(duration_ms)
+        speech_started = vad_speech_started(event, payload)
+        if (
+            session.capabilities.supports_barge_in
+            and is_speech
+            and session.config.overlap_policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value
+            and speech_started is not False
+        ):
+            return {
+                "action": "barge_in",
+                "reason": ("server_vad_speech_started" if speech_started is True else "barge_in_on_speech"),
+                "cancel_reason": "turn_detected" if speech_started is True else "barge_in",
+                "duration_ms": duration_ms,
+                "overlap_speech_ms": session.overlap_speech_ms,
+                "buffer_audio": True,
+            }
+        return {
+            "action": "listen",
+            "reason": "auto_response_continuous",
+            "duration_ms": duration_ms,
+            "overlap_speech_ms": session.overlap_speech_ms,
+            "buffer_audio": True,
+            "defer_runtime_append": False,
+            "force_listen": event.get("force_listen") is True or payload.get("force_listen") is True,
+            "preserve_realtime_input": True,
+        }
+    if bool(event.get("force_listen", False)):
+        session.reset_overlap_speech()
+        return {
+            "action": "listen",
+            "reason": "client_force_listen",
+            "duration_ms": duration_ms,
+            "buffer_audio": is_speech,
+            "defer_runtime_append": True,
+        }
+
+    policy = session.config.overlap_policy
+    if not is_speech:
+        if session.overlap_speech_ms <= 0:
+            session.reset_overlap_speech()
+        return {
+            "action": "drop",
+            "reason": "silence_or_noise",
+            "duration_ms": duration_ms,
+            "overlap_speech_ms": session.overlap_speech_ms,
+            "buffer_audio": False,
+        }
+
+    if is_short_ack_transcript_hint(event, payload):
+        session.reset_overlap_speech()
+        return {
+            "action": "listen",
+            "reason": "short_ack_transcript",
+            "duration_ms": duration_ms,
+            "overlap_speech_ms": session.overlap_speech_ms,
+            "buffer_audio": False,
+            "defer_runtime_append": True,
+        }
+
+    if policy == DuplexOverlapPolicy.LISTEN_ONLY.value:
+        session.accumulate_overlap_speech(duration_ms)
+        return {
+            "action": "listen",
+            "reason": "policy_listen_only",
+            "duration_ms": duration_ms,
+            "overlap_speech_ms": session.overlap_speech_ms,
+            "buffer_audio": True,
+            "defer_runtime_append": True,
+        }
+
+    if policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value and not session.capabilities.supports_barge_in:
+        return defer_unsupported_barge_in(session, duration_ms=duration_ms, is_speech=True)
+
+    session.accumulate_overlap_speech(duration_ms)
+    if policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value:
+        speech_started = vad_speech_started(event, payload)
+        if speech_started is False:
+            return {
+                "action": "listen",
+                "reason": "server_vad_utterance_active",
+                "duration_ms": duration_ms,
+                "overlap_speech_ms": session.overlap_speech_ms,
+                "buffer_audio": True,
+                "defer_runtime_append": False,
+                "force_listen": True,
+                "preserve_realtime_input": True,
+            }
+        return {
+            "action": "barge_in",
+            "reason": ("server_vad_speech_started" if speech_started is True else "policy_barge_in_on_speech"),
+            "cancel_reason": "turn_detected" if speech_started is True else "barge_in",
+            "duration_ms": duration_ms,
+            "overlap_speech_ms": session.overlap_speech_ms,
+            "buffer_audio": True,
+        }
+
+    if (
+        duration_ms <= session.config.overlap_short_ack_ms
+        and session.overlap_speech_ms <= session.config.overlap_short_ack_ms
+    ):
+        return {
+            "action": "listen",
+            "reason": "short_ack",
+            "duration_ms": duration_ms,
+            "overlap_speech_ms": session.overlap_speech_ms,
+            "buffer_audio": True,
+            "defer_runtime_append": True,
+        }
+    if session.overlap_speech_ms >= session.config.overlap_barge_in_ms:
+        if not session.capabilities.supports_barge_in:
+            return {
+                "action": "listen",
+                "reason": "barge_in_unsupported",
+                "duration_ms": duration_ms,
+                "overlap_speech_ms": session.overlap_speech_ms,
+                "buffer_audio": True,
+                "defer_runtime_append": True,
+            }
+        return {
+            "action": "barge_in",
+            "reason": "long_overlap_speech",
+            "duration_ms": duration_ms,
+            "overlap_speech_ms": session.overlap_speech_ms,
+            "buffer_audio": True,
+        }
+    return {
+        "action": "listen",
+        "reason": "accumulating_overlap_speech",
+        "duration_ms": duration_ms,
+        "overlap_speech_ms": session.overlap_speech_ms,
+        "buffer_audio": True,
+        "defer_runtime_append": True,
+    }
+
+
+def vad_speech_started(event: Mapping[str, object], payload: Mapping[str, object]) -> bool | None:
+    for source in (event, payload):
+        vad = source.get("vad")
+        if isinstance(vad, Mapping) and isinstance(vad.get("speech_started"), bool):
+            return bool(vad["speech_started"])
+    return None
+
+
+def event_requests_barge_in(event: Mapping[str, object]) -> bool:
+    if event.get("force_barge_in") is True:
+        return True
+    explicit = event.get("overlap_action") or event.get("overlap")
+    return isinstance(explicit, str) and explicit.strip().lower() in {"barge_in", "interrupt", "cancel"}
+
+
+def defer_unsupported_barge_in(
+    session: DuplexEngineSession,
+    *,
+    duration_ms: int,
+    is_speech: bool,
+) -> dict[str, object]:
+    if is_speech:
+        session.accumulate_overlap_speech(duration_ms)
+    return {
+        "action": "listen",
+        "reason": "barge_in_unsupported",
+        "duration_ms": duration_ms,
+        "overlap_speech_ms": session.overlap_speech_ms,
+        "buffer_audio": is_speech,
+        "defer_runtime_append": True,
+    }
+
+
+def is_short_ack_transcript_hint(event: dict[str, object], payload: dict[str, object]) -> bool:
+    raw_text = event.get("transcript") or event.get("text") or payload.get("transcript") or payload.get("text")
+    if not isinstance(raw_text, str):
+        return False
+    normalized = raw_text.strip().lower()
+    if not normalized:
+        return False
+    compact = "".join(ch for ch in normalized if ch.isalnum() or "一" <= ch <= "鿿")
+    if compact in {
+        "嗯",
+        "嗯嗯",
+        "对",
+        "对的",
+        "好",
+        "好的",
+        "继续",
+        "继续说",
+        "可以",
+        "是的",
+        "yes",
+        "yeah",
+        "yep",
+        "ok",
+        "okay",
+        "continue",
+        "goon",
+        "right",
+    }:
+        return True
+    return normalized in {"go on", "keep going", "please continue"}
+
+
+def input_audio_duration_ms(event: dict[str, object], payload: dict[str, object]) -> int:
+    for key in ("duration_ms", "audio_duration_ms"):
+        value = event.get(key)
+        if isinstance(value, int | float):
+            return max(0, int(value))
+    fmt = payload.get("format")
+    sample_rate_hz = payload.get("sample_rate_hz")
+    audio = payload.get("audio")
+    if fmt == "pcm_f32le" and isinstance(sample_rate_hz, int) and sample_rate_hz > 0 and isinstance(audio, str):
+        try:
+            raw = base64.b64decode(audio, validate=True)
+        except (binascii.Error, ValueError):
+            return 0
+        return int((len(raw) // 4) * 1000 / sample_rate_hz)
+    return 0
+
+
+def merge_audio_payloads(first: dict[str, object], second: dict[str, object]) -> dict[str, object]:
+    if first.get("format") != "pcm_f32le" or second.get("format") != "pcm_f32le":
+        return second
+    first_rate = first.get("sample_rate_hz")
+    second_rate = second.get("sample_rate_hz")
+    if not isinstance(first_rate, int) or not isinstance(second_rate, int) or first_rate != second_rate:
+        return second
+    first_audio = first.get("audio")
+    second_audio = second.get("audio")
+    if not isinstance(first_audio, str) or not isinstance(second_audio, str):
+        return second
+    try:
+        first_raw = base64.b64decode(first_audio, validate=True)
+        second_raw = base64.b64decode(second_audio, validate=True)
+    except (binascii.Error, ValueError):
+        return second
+    merged = dict(second)
+    merged["audio"] = base64.b64encode(first_raw + second_raw).decode("ascii")
+    merged["sample_rate_hz"] = first_rate
+    merged_frames = [
+        frame
+        for source in (first.get("video_frames"), second.get("video_frames"))
+        if isinstance(source, list)
+        for frame in source
+        if isinstance(frame, str) and frame
+    ]
+    if merged_frames:
+        merged["video_frames"] = merged_frames
+    else:
+        merged.pop("video_frames", None)
+    merged["force_listen"] = bool(first.get("force_listen", False)) or bool(second.get("force_listen", False))
+    merged.pop("force_speak", None)
+    merged["is_speech"] = bool(first.get("is_speech", False)) or bool(second.get("is_speech", False))
+    return merged
+
+
+def should_force_listen_for_short_commit(
+    session: DuplexEngineSession, event: dict[str, object], payload: dict[str, object]
+) -> bool:
+    if event.get("force_listen") is True or payload.get("force_listen") is True:
+        return True
+    if event.get("force_barge_in") is True:
+        return False
+    if event.get("response_create") is not True:
+        return False
+    duration_ms = input_audio_duration_ms(event, payload)
+    return 0 < duration_ms <= session.config.overlap_short_ack_ms
+
+
+def should_force_listen_for_auto_response_overlap(
+    event: dict[str, object], payload: dict[str, object], *, auto_responds: bool
+) -> bool:
+    if not auto_responds:
+        return False
+    if event.get("force_barge_in") is True:
+        return False
+    return event.get("force_listen") is True or payload.get("force_listen") is True
+
+
+def input_looks_like_speech(session: DuplexEngineSession, event: dict[str, object], payload: dict[str, object]) -> bool:
+    for key in ("is_speech", "speech"):
+        value = event.get(key)
+        if isinstance(value, bool):
+            return value
+    vad = event.get("vad")
+    if isinstance(vad, dict):
+        value = vad.get("is_speech")
+        if isinstance(value, bool):
+            return value
+        probability = vad.get("speech_probability", vad.get("probability"))
+        if isinstance(probability, int | float):
+            return float(probability) >= 0.5
+    probability = event.get("speech_probability")
+    if isinstance(probability, int | float):
+        return float(probability) >= 0.5
+
+    fmt = payload.get("format")
+    audio = payload.get("audio")
+    if fmt in {"pcm_f32le", "pcm16"} and isinstance(audio, str):
+        try:
+            raw = base64.b64decode(audio, validate=True)
+        except (binascii.Error, ValueError):
+            return True
+        if fmt == "pcm_f32le":
+            if len(raw) < 4 or len(raw) % 4 != 0:
+                return True
+            samples = np.frombuffer(raw, dtype=np.float32)
+        else:
+            if len(raw) < 2 or len(raw) % 2 != 0:
+                return True
+            samples = np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
+        if samples.size == 0:
+            return False
+        rms = float(np.sqrt(np.mean(np.square(samples.astype(np.float32)))))
+        return rms >= session.config.overlap_silence_rms
+    return True
diff --git a/vllm_omni/engine/duplex/session/playback_ledger.py b/vllm_omni/engine/duplex/session/playback_ledger.py
new file mode 100644
index 00000000000..c6843f64b00
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/playback_ledger.py
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Applying one ``playback.ack`` to a duplex session.
+
+The client reports how much of a response it has actually played; the session
+uses that to commit or truncate the assistant item in conversation history, and
+to release the response's playback state once it is fully played.
+
+Extracted from ``DuplexSessionRunner`` because the only runner state it touched
+was ``session``. It returns the events it produces rather than emitting them,
+so the rules can be exercised without a runner.
+"""
+
+from __future__ import annotations
+
+from vllm_omni.engine.duplex.events import DuplexEvent, PlaybackAcknowledged, error_event
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession
+from vllm_omni.engine.duplex.session.lease import DuplexLeaseActivity
+
+
+def apply_playback_ack(session: DuplexEngineSession, event: dict[str, object]) -> list[DuplexEvent]:
+    """Apply one ``playback.ack`` and return the events it produces."""
+    played_ms = event.get("played_ms", event.get("audio_ms", 0))
+    committed_ms = event.get("committed_ms")
+    if not isinstance(played_ms, int | float):
+        return [error_event("bad_event", "playback.ack requires played_ms")]
+    try:
+        session.touch_lease(DuplexLeaseActivity.PLAYBACK_ACK)
+    except Exception:
+        pass
+    committed_cursor = int(committed_ms) if isinstance(committed_ms, int | float) else int(played_ms)
+    item_id = event.get("item_id")
+    response_id = event.get("response_id")
+    response_id = response_id if isinstance(response_id, str) and response_id else None
+    if not isinstance(item_id, str) or not item_id:
+        item_id = f"item_{response_id}" if response_id is not None else None
+    elif response_id is None and item_id.startswith("item_"):
+        response_id = item_id.removeprefix("item_")
+    if response_id is None and item_id is None and len(session.pending_history_item_ids) == 1:
+        item_id = next(iter(session.pending_history_item_ids))
+        if item_id.startswith("item_"):
+            response_id = item_id.removeprefix("item_")
+    if response_id is None and item_id is None and session.active_response_id is not None:
+        response_id = session.active_response_id
+        item_id = f"item_{response_id}"
+    if response_id is not None:
+        expected_item_id = f"item_{response_id}"
+        if item_id is None:
+            item_id = expected_item_id
+        elif item_id != expected_item_id:
+            return [error_event("playback_item_mismatch", "playback.ack item_id must match item_<response_id>.")]
+        if not session.has_assistant_response_item(response_id, item_id):
+            return [
+                error_event("playback_item_not_found", f"No assistant response item is registered for {response_id}.")
+            ]
+        if session.playback_ack_is_too_late(response_id, item_id):
+            return [
+                error_event("playback_ack_too_late", "playback.ack arrived after a later user input was committed.")
+            ]
+        session.reserve_history_item(item_id)
+    elif item_id is not None:
+        return [error_event("playback_item_not_found", "playback.ack requires a response-owned assistant item.")]
+    hard_truncate = event.get("truncate") is True
+    if hard_truncate:
+        playback = session.acknowledge_playback(int(played_ms), committed_cursor, response_id=response_id)
+        playback = session.truncate_playback_commit(committed_cursor, response_id=response_id)
+    else:
+        playback = session.acknowledge_playback(int(played_ms), committed_cursor, response_id=response_id)
+    committed_history = False
+    if isinstance(item_id, str) and item_id:
+        expected_item_id = f"item_{response_id}" if response_id is not None else None
+        if (
+            expected_item_id == item_id
+            and item_id not in session.history_item_ids
+            and item_id not in session.pending_history_item_ids
+        ):
+            session.register_history_item(item_id, None)
+        committed_history = session.truncate_history_item(
+            item_id,
+            audio_end_ms=committed_cursor,
+            playback=playback,
+            hard=hard_truncate,
+        )
+    elif session.pending_history_item_ids:
+        pending_ids = list(session.pending_history_item_ids)
+        if len(pending_ids) == 1:
+            item_id = pending_ids[0]
+            committed_history = session.truncate_history_item(
+                item_id,
+                audio_end_ms=committed_cursor,
+                playback=playback,
+                hard=hard_truncate,
+            )
+    elif session.active_response_id is not None:
+        item_id = f"item_{session.active_response_id}"
+        committed_history = session.truncate_history_item(
+            item_id,
+            audio_end_ms=committed_cursor,
+            playback=playback,
+            hard=hard_truncate,
+        )
+    elif session.last_assistant_full_message is not None:
+        if item_id is None and session.history_item_ids:
+            assistant_item_ids = [
+                known_item_id
+                for known_item_id, message in session.history_item_ids.items()
+                if message.get("role") == "assistant"
+            ]
+            if len(assistant_item_ids) == 1:
+                item_id = assistant_item_ids[0]
+        if isinstance(item_id, str) and item_id:
+            committed_history = session.truncate_history_item(
+                item_id,
+                audio_end_ms=committed_cursor,
+                playback=playback,
+                hard=hard_truncate,
+            )
+    events: list[DuplexEvent] = [
+        PlaybackAcknowledged(
+            details={
+                "type": "playback.acknowledged",
+                "session_id": session.session_id,
+                "epoch": session.epoch,
+                "item_id": item_id,
+                "played_ms": int(played_ms),
+                "committed_ms": committed_cursor,
+                "truncate": event.get("truncate") is True,
+                "playback": playback.as_dict(),
+                "history_committed": committed_history,
+            }
+        )
+    ]
+    if committed_history and committed_cursor >= max(playback.sent_ms, playback.generated_ms):
+        session.release_response_playback(response_id)
+        session.release_response_history_snapshot(response_id)
+    return events
diff --git a/vllm_omni/engine/duplex/session/runner.py b/vllm_omni/engine/duplex/session/runner.py
new file mode 100644
index 00000000000..7915500b739
--- /dev/null
+++ b/vllm_omni/engine/duplex/session/runner.py
@@ -0,0 +1,1772 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Engine-resident session runner: one ordered mailbox and one session state per duplex session.
+
+``DuplexSessionRunner`` owns the whole lifecycle of one session on the
+orchestrator loop (the session is never touched from another thread):
+
+* every mutation of ``DuplexEngineSession`` happens on this loop, through the
+  mailbox worker (commands, stage outputs, internal items) or through tracked
+  tasks that re-validate ``(epoch, turn_id)`` after each ``await``;
+* appends are planned with the model plugin and submitted to the stage port
+  in wire order on the per-session append tail (no RPC hop);
+* stage outputs are pushed in by ``DuplexOrchestrator._intercept_stage_output``
+  instead of being polled through request queues;
+* everything the session says leaves as typed events through
+  ``DuplexSessionManager.emit`` after terminal-acceptance / stale-epoch
+  filtering, so a cancelled epoch can never speak again.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, TypeVar
+
+from vllm.logger import init_logger
+
+from vllm_omni.engine.duplex.audio import convert_input_audio_with_rate
+from vllm_omni.engine.duplex.commands import (
+    AckPlayback,
+    AppendAudio,
+    AppendText,
+    BargeIn,
+    CancelInput,
+    CancelResponse,
+    ClearInput,
+    ClearOutputAudio,
+    CloseSession,
+    Commit,
+    CreateItem,
+    CreateResponse,
+    DeleteItem,
+    DuplexCommand,
+    Heartbeat,
+    SignalTurn,
+    TruncateItem,
+    UpdateSession,
+)
+from vllm_omni.engine.duplex.config import (
+    DuplexConfigError,
+    DuplexOverlapPolicy,
+    DuplexPlaybackCommitPolicy,
+    DuplexSessionState,
+    ResponseCreateOptions,
+)
+from vllm_omni.engine.duplex.contracts import (
+    DuplexOutputContext,
+    DuplexOutputDecision,
+    DuplexStagePort,
+)
+from vllm_omni.engine.duplex.events import (
+    DuplexEvent,
+    InputCleared,
+    SessionExpired,
+    SessionHeartbeatAck,
+)
+from vllm_omni.engine.duplex.plugin import (
+    DuplexModelPlugin,
+    DuplexModelSessionState,
+    PcmAppendReservation,
+    payload_turn_id,
+)
+from vllm_omni.engine.duplex.realtime_events import (
+    RealtimeProjectionState,
+    discard_pending_input_audio,
+    note_input_append,
+    resolve_cancel_response,
+    resolve_clear_output_audio,
+    resolve_commit,
+    resolve_create_item,
+    resolve_delete_item,
+    resolve_truncate_item,
+    retrieve_item_events,
+)
+from vllm_omni.engine.duplex.session import helpers, overlap_policy, playback_ledger
+from vllm_omni.engine.duplex.session.append_task import AppendAttempt
+from vllm_omni.engine.duplex.session.commit_policy import CommitAction, CommitSnapshot, decide_commit_action
+from vllm_omni.engine.duplex.session.context import (
+    DuplexRunState,
+    DuplexSessionContext,
+    DuplexSessionTasks,
+    StageOutput,
+)
+from vllm_omni.engine.duplex.session.control import SessionControl
+from vllm_omni.engine.duplex.session.emitter import SessionEmitter
+from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession
+from vllm_omni.engine.duplex.session.lease import DuplexLeaseActivity
+from vllm_omni.engine.duplex.session.model_channel import ModelChannel
+from vllm_omni.engine.duplex.turn_detection import (
+    TurnDetectionResult,
+)
+from vllm_omni.metrics.stats import StageRequestStats
+
+if TYPE_CHECKING:
+    from vllm.config import ModelConfig
+    from vllm.outputs import RequestOutput
+
+    from vllm_omni.engine.duplex.session.manager import DuplexSessionManager
+
+logger = init_logger(__name__)
+
+_OffloadT = TypeVar("_OffloadT")
+
+
+@dataclass(frozen=True, slots=True)
+class _Internal:
+    """Runner-internal mailbox item (its payload runs through the dict-based handlers)."""
+
+    kind: str
+    payload: dict[str, object] = field(default_factory=dict)
+
+
+_CANCEL_EVENTS = frozenset({"input.cancel", "response.cancel", "barge_in", "output_audio_buffer.clear"})
+
+
+class DuplexSessionRunner:
+    """Owns one ``DuplexEngineSession`` on the orchestrator loop (see module docstring)."""
+
+    def __init__(
+        self,
+        *,
+        session: DuplexEngineSession,
+        plugin: DuplexModelPlugin,
+        stage_port: DuplexStagePort,
+        manager: DuplexSessionManager,
+        model_config: ModelConfig | None,
+    ) -> None:
+        self.session = session
+        self.plugin = plugin
+        self.stage_port = stage_port
+        self.manager = manager
+        self.model_config = model_config
+        if session.model_state is None:
+            session.model_state = plugin.create_session_state()
+        self.model_state: DuplexModelSessionState = session.model_state
+        self.tasks = DuplexSessionTasks()
+        self._mailbox: asyncio.Queue[DuplexCommand | StageOutput | _Internal] = asyncio.Queue()
+        self._worker: asyncio.Task[None] | None = None
+        self._worker_stopped = False
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._background_tasks: set[asyncio.Task[None]] = set()
+        #: Flags more than one component reads and writes (see session_context).
+        self.run = DuplexRunState()
+        self.ctx = DuplexSessionContext(
+            session=session,
+            model_state=self.model_state,
+            plugin=plugin,
+            stage_port=stage_port,
+            manager=manager,
+            tasks=self.tasks,
+            run=self.run,
+            services=self,
+        )
+        self.out = SessionEmitter(self.ctx, promote_deferred_overlap=self._promote_deferred_overlap_later)
+        self.model = ModelChannel(
+            self.ctx,
+            self.out,
+            close_from_runtime=self._close_from_runtime,
+            schedule_silence_continuation=self._schedule_silence_continuation,
+            abort_request=self._abort_request_background,
+        )
+        self.control = SessionControl(
+            self.ctx,
+            self.out,
+            self.model,
+            wait_for_append_tail=self._wait_for_append_tail,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Public interface                                                   #
+    # ------------------------------------------------------------------ #
+
+    def start(self) -> None:
+        self._loop = asyncio.get_running_loop()
+        session = self.session
+        if self.out.projector is None:
+            default_payload = session.config.extra_body.get("realtime_session_payload")
+            self.out.projector = RealtimeProjectionState(
+                session_id=session.session_id,
+                model=session.config.model,
+                default_payload=default_payload if isinstance(default_payload, Mapping) else None,
+                initial_session_update=True,
+            )
+        # Every client speaks the Realtime protocol now; the old runner forced
+        # the ACK-only playback ledger for that path.
+        session.config.playback_commit_policy = DuplexPlaybackCommitPolicy.ACK_ONLY.value
+        self.control.init_turn_detection()
+        self._worker = self._loop.create_task(self._run(), name=f"duplex-session-{session.session_id}")
+        self.emit({"type": "session.created", "session": session.as_public_dict()})
+
+    def submit(self, command: DuplexCommand) -> None:
+        self._mailbox.put_nowait(command)
+
+    def on_stage_output(
+        self,
+        stage_id: int,
+        output: RequestOutput,
+        metrics: StageRequestStats | None,
+        *,
+        request_id: str,
+        context: DuplexOutputContext,
+    ) -> bool:
+        """Accept one stage output (orchestrator loop); return True when it must not be forwarded."""
+        decision: DuplexOutputDecision | None = None
+        if stage_id < context.final_stage_id:
+            decision = self.model.decide_output(stage_id, output, context)
+        consume = decision is not None or stage_id >= context.final_stage_id
+        if not consume:
+            # Stage0 text without a direct decision feeds the TTS stage as before.
+            # Its metrics still have to reach the client: before sessions moved
+            # into the engine the orchestrator published them as a standalone
+            # ``StageMetricsMessage``, a path session-owned requests no longer
+            # take. Hand them to the session instead of dropping them, on the
+            # mailbox so they stay ordered with this session's other work.
+            snapshot = self.model.stage_metrics_snapshot(stage_id, metrics, output)
+            if snapshot is not None and not self.run.closing and self.session.state != DuplexSessionState.CLOSED:
+                self._mailbox.put_nowait(_Internal("stage_metrics", {"stage_metrics": snapshot}))
+            return False
+        if self.run.closing or self.session.state == DuplexSessionState.CLOSED:
+            return True
+        self._mailbox.put_nowait(
+            StageOutput(
+                stage_id=stage_id,
+                output=output,
+                metrics=metrics,
+                request_id=request_id,
+                context=context,
+                decision=decision,
+            )
+        )
+        return True
+
+    def on_stage_failure(self, stage_id: int, exc: BaseException) -> None:
+        """A stage rejected this session's request: fail the active response now.
+
+        Runs synchronously on the loop (no mailbox hop): the orchestrator
+        expires the session right after this call, so a queued item could be
+        cancelled with the worker and the client would only see
+        ``session.expired``. Emitting here keeps the order
+        ``error`` -> failed ``response.done`` -> ``session.expired``.
+        """
+        session = self.session
+        if session.state == DuplexSessionState.CLOSED:
+            return
+        self._emit_error(
+            "runtime_data_plane_stream_failed",
+            f"Stage-{stage_id} input processor failed: {type(exc).__name__}: {exc}",
+        )
+        response_id = session.active_response_id
+        if response_id is not None:
+            session.end_response(commit_text=False)
+            self.emit(
+                {
+                    "type": "response.done",
+                    "session_id": session.session_id,
+                    "response_id": response_id,
+                    "epoch": session.epoch,
+                    "committed": False,
+                    "status": "failed",
+                    "status_details": {"type": "failed", "reason": "runtime_data_plane_stream_failed"},
+                    "playback": session.playback.as_dict(),
+                }
+            )
+
+    @property
+    def closed_emitted(self) -> bool:
+        """Whether ``session.closed`` / ``session.expired`` already left this runner."""
+        return self.run.closed_emitted
+
+    def mark_closed_emitted(self) -> None:
+        """Claim the session's one terminal event for the caller.
+
+        The manager emits the deferred terminal itself, after the stage cleanup;
+        recording it here stops a late runtime close emitting a second one.
+        """
+        self.run.closed_emitted = True
+        self.run.closed_deferred = False
+
+    @property
+    def closing(self) -> bool:
+        """Whether an irreversible close has begun (commands and control ops are refused)."""
+        return self.run.closing or self.session.state != DuplexSessionState.OPEN
+
+    async def close(self, reason: str, *, emit_closed: bool = True) -> None:
+        """Graceful close: cancel work, release the data plane, emit ``session.closed``.
+
+        With ``emit_closed=False`` the manager emits ``session.closed`` itself
+        once the stage resources are released, so the event also means "the
+        admission slot is free again".
+        """
+        session = self.session
+        if session.state == DuplexSessionState.CLOSED and (self.run.closed_emitted or self.run.closed_deferred):
+            await self._stop_worker()
+            return
+        self._begin_close(reason)
+        self.model_state.audio_buffer.clear()
+        session.release_all_input_bytes()
+        self.model_state.input_since_commit = False
+        self.model_state.speech_since_commit = False
+        self.model_state.clear_committed_audio()
+        await self.tasks.cancel_append_tasks()
+        self.model.cancel_data_plane_stream()
+        await self._cancel_active_response(self.tasks.active_response_task, reason=reason, notify=False)
+        self.tasks.active_response_task = None
+        self._cleanup_duplex_session_state()
+        if not self.run.closed_emitted and not self.run.closed_deferred:
+            self.run.close_reason = self.run.close_reason or reason
+            if emit_closed:
+                self.run.closed_emitted = True
+                self.emit({"type": "session.closed", "session_id": session.session_id, "reason": reason})
+            else:
+                self.run.closed_deferred = True
+        session.close()
+        await self._stop_worker()
+
+    async def expire(self, reason: str, *, emit_expired: bool = True) -> None:
+        """Lease expiry / runtime cleanup: emit ``session.expired`` and tear down.
+
+        With ``emit_expired=False`` the manager emits the event after the stage
+        cleanup (see ``close``).
+        """
+        session = self.session
+        self._begin_close(reason)
+        if not self.run.closed_emitted:
+            if emit_expired:
+                # Also when the event was deferred: the manager only emits a
+                # deferred terminal for the teardown it drives itself, and an
+                # expiry that arrives first (a stage failure racing a wire
+                # ``session.close``) takes the runner away from it. Emitting
+                # here keeps "every session ends with one terminal event".
+                self.run.closed_emitted = True
+                self._emit_events([SessionExpired(reason=reason)])
+            else:
+                self.run.closed_deferred = True
+        await self.tasks.cancel_append_tasks()
+        self.model.cancel_data_plane_stream()
+        active_response_task = self.tasks.active_response_task
+        if active_response_task is not None and not active_response_task.done():
+            active_response_task.cancel()
+            await asyncio.gather(active_response_task, return_exceptions=True)
+        self.tasks.active_response_task = None
+        if session.active_response_id is not None:
+            session.end_response(commit_text=False)
+        self._cleanup_duplex_session_state()
+        session.close()
+        await self._stop_worker()
+
+    async def shutdown(self) -> None:
+        self.run.closing = True
+        self.run.closed_emitted = True
+        await self.tasks.cancel_append_tasks()
+        self.model.cancel_data_plane_stream()
+        active_response_task = self.tasks.active_response_task
+        if active_response_task is not None and not active_response_task.done():
+            active_response_task.cancel()
+            await asyncio.gather(active_response_task, return_exceptions=True)
+        self.session.close()
+        await self._stop_worker()
+
+    # ------------------------------------------------------------------ #
+    # Worker                                                             #
+    # ------------------------------------------------------------------ #
+
+    async def _run(self) -> None:
+        while not self._worker_stopped:
+            item = await self._mailbox.get()
+            try:
+                await self._handle_item(item)
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                logger.exception("Duplex session %s failed handling %r: %s", self.session.session_id, item, exc)
+                self._emit_error("internal_error", str(exc))
+
+    async def _stop_worker(self) -> None:
+        worker = self._worker
+        self._worker = None
+        # Set even when the worker itself is stopping (a wire ``session.close``
+        # runs inside it): its loop exits after the current item instead of
+        # parking on the mailbox forever.
+        self._worker_stopped = True
+        for task in list(self._background_tasks):
+            task.cancel()
+        if self._background_tasks:
+            await asyncio.gather(*self._background_tasks, return_exceptions=True)
+        self._background_tasks.clear()
+        if worker is not None and worker is not asyncio.current_task() and not worker.done():
+            worker.cancel()
+            await asyncio.gather(worker, return_exceptions=True)
+
+    def spawn(self, coro: Awaitable[None], *, name: str) -> asyncio.Task[None]:
+        task = asyncio.ensure_future(coro)
+        task.set_name(name)
+        self._background_tasks.add(task)
+        task.add_done_callback(self._background_tasks.discard)
+        return task
+
+    async def offload(self, fn: Callable[..., _OffloadT], *args: object, **kwargs: object) -> _OffloadT:
+        loop = self._loop or asyncio.get_running_loop()
+        if kwargs:
+            return await loop.run_in_executor(self.manager.executor, lambda: fn(*args, **kwargs))
+        return await loop.run_in_executor(self.manager.executor, fn, *args)
+
+    async def _handle_item(self, item: DuplexCommand | StageOutput | _Internal) -> None:
+        session = self.session
+        if isinstance(item, StageOutput):
+            await self.model.on_stage_output_item(item)
+            return
+        if isinstance(item, _Internal):
+            await self._on_internal(item)
+            return
+        if self.run.closing or session.state == DuplexSessionState.CLOSED:
+            if isinstance(item, Commit):
+                session.release_pending_turn()
+            elif isinstance(item, AppendAudio):
+                session.release_input_bytes(len(item.audio))
+            return
+        await self._on_command(item)
+
+    async def _on_internal(self, item: _Internal) -> None:
+        if item.kind == "stage_metrics":
+            stage_metrics = item.payload.get("stage_metrics")
+            if isinstance(stage_metrics, Mapping):
+                self.session.stash_stage_metrics(stage_metrics)
+            return
+        if item.kind == "promote_deferred_overlap":
+            if self.run.closing or self.session.state != DuplexSessionState.OPEN:
+                return
+            payload = item.payload.get("payload")
+            if not isinstance(payload, dict):
+                return
+            await self._start_append(
+                payload,
+                final=True,
+                precreate_response=bool(item.payload.get("precreate_response", False)),
+                operation_id=self.model_state.committed_audio_operation_id,
+                retained_committed_payload=(payload if self.model_state.committed_audio_payload is payload else None),
+            )
+            return
+        if item.kind == "commit":
+            await self._on_commit(dict(item.payload))
+            return
+        if item.kind == "run_payload":
+            await self._run_internal_payload(dict(item.payload))
+            return
+        logger.warning("Unknown duplex runner internal item: %s", item.kind)
+
+    async def _run_internal_payload(self, payload: dict[str, object]) -> None:
+        """Run one internal event dictionary through the matching handler."""
+        event_type = payload.get("type")
+        if event_type == "input_audio_buffer.append":
+            await self._on_append_audio(payload)
+        elif event_type in {"input_audio_buffer.commit", "input.commit", "response.create"}:
+            await self._on_commit(payload)
+        elif event_type == "playback.ack":
+            self._emit_events(playback_ledger.apply_playback_ack(self.session, payload))
+        elif event_type in _CANCEL_EVENTS:
+            await self._on_cancel(payload)
+        elif event_type == "turn.signal":
+            await self.control.on_turn_signal(payload)
+        else:
+            self._emit_error("unknown_event", f"Unknown duplex event: {event_type}")
+
+    # ------------------------------------------------------------------ #
+    # Commands                                                           #
+    # ------------------------------------------------------------------ #
+
+    async def _on_command(self, command: DuplexCommand) -> None:
+        session = self.session
+        projector = self._require_projector()
+        if isinstance(command, AppendAudio):
+            # The manager reserved the wire size at admission; the handler
+            # re-reserves the decoded size around its PCM reservation.
+            session.release_input_bytes(len(command.audio))
+            await self._on_append_audio(command.payload())
+        elif isinstance(command, AppendText):
+            session.mark_user_input_activity()
+            self._emit_error(
+                "native_text_append_unsupported",
+                "The selected native duplex runtime accepts audio append only",
+                event_id=command.event_id,
+            )
+        elif isinstance(command, Commit):
+            session.release_pending_turn()
+            resolved = resolve_commit(projector, command)
+            self._emit_events(resolved.events)
+            if resolved.reset_vad:
+                self.control.reset_vad()
+            if resolved.payload is not None:
+                await self._on_commit(resolved.payload)
+        elif isinstance(command, CreateResponse):
+            await self._on_commit(command.payload())
+        elif isinstance(command, ClearInput):
+            self._on_clear_input()
+        elif isinstance(command, CancelResponse):
+            resolved = resolve_cancel_response(projector, command)
+            self._emit_events(resolved.events)
+            for payload in resolved.payloads:
+                await self._on_cancel(payload)
+        elif isinstance(command, ClearOutputAudio):
+            resolved = resolve_clear_output_audio(projector, command)
+            self._emit_events(resolved.events)
+            for payload in resolved.payloads:
+                await self._on_cancel(payload)
+        elif isinstance(command, CancelInput | BargeIn):
+            await self._on_cancel(command.payload())
+        elif isinstance(command, SignalTurn):
+            if command.event == "conversation.item.retrieve":
+                self._emit_events(
+                    retrieve_item_events(
+                        projector,
+                        {
+                            **dict(command.signal_payload),
+                            **({"event_id": command.event_id} if command.event_id else {}),
+                        },
+                    )
+                )
+                return
+            payload = command.payload()
+            if command.event in _CANCEL_EVENTS:
+                normalized = dict(payload.get("payload") or {})
+                normalized.update(payload)
+                normalized["type"] = command.event
+                await self._on_cancel(normalized)
+            else:
+                await self.control.on_turn_signal(payload)
+        elif isinstance(command, UpdateSession):
+            await self.control.on_session_update(dict(command.patch), realtime_event_id=command.event_id)
+        elif isinstance(command, AckPlayback):
+            self._emit_events(playback_ledger.apply_playback_ack(self.session, command.payload()))
+        elif isinstance(command, Heartbeat):
+            self._on_heartbeat(command)
+        elif isinstance(command, CreateItem):
+            resolved = resolve_create_item(projector, command)
+            self._emit_events(resolved.events)
+            for payload in resolved.payloads:
+                await self._run_internal_payload(payload)
+        elif isinstance(command, DeleteItem):
+            resolved = resolve_delete_item(projector, command)
+            self._emit_events(resolved.events)
+            for payload in resolved.payloads:
+                await self.control.on_turn_signal(payload)
+        elif isinstance(command, TruncateItem):
+            resolved = resolve_truncate_item(projector, command)
+            self._emit_events(resolved.events)
+            for payload in resolved.payloads:
+                await self._run_internal_payload(payload)
+        elif isinstance(command, CloseSession):
+            await self._on_close_command(command.reason)
+        else:
+            self._emit_error("unknown_event", f"Unknown duplex command: {type(command).__name__}")
+
+    async def _on_close_command(self, reason: str) -> None:
+        # A close requested through the ordered command stream (the client's
+        # ``session.close``) tears the runner down here; the manager then
+        # aborts the stage requests, frees the admission slot and emits
+        # ``session.closed`` exactly like a close through the control RPC.
+        # Mark the session closing before the first await so a concurrent
+        # resume / touch / command is refused instead of racing the teardown.
+        self._begin_close(reason)
+        await self.close(reason, emit_closed=False)
+        self.manager.close_from_runner(self, reason)
+
+    def _on_heartbeat(self, command: Heartbeat) -> None:
+        try:
+            self.session.touch_lease(DuplexLeaseActivity.HEARTBEAT)
+        except Exception as exc:
+            self._emit_error("runtime_touch_failed", str(exc), event_id=command.event_id)
+            return
+        self._emit_events([SessionHeartbeatAck()])
+
+    def _on_clear_input(self) -> None:
+        session = self.session
+        model_state = self.model_state
+        model_state.audio_buffer.clear()
+        session.release_all_input_bytes()
+        model_state.input_since_commit = False
+        model_state.speech_since_commit = False
+        model_state.clear_committed_audio()
+        session.cancel_pending_input()
+        projector = self.out.projector
+        if projector is not None:
+            from vllm_omni.engine.duplex.realtime_events import clear_input_buffer
+
+            clear_input_buffer(projector)
+        self._emit_events([InputCleared()])
+
+    # ------------------------------------------------------------------ #
+    # Emission (delegated to SessionEmitter)                             #
+    # ------------------------------------------------------------------ #
+
+    def emit(self, payload: dict[str, object]) -> None:
+        """Apply an internal event to the session, project it, and send it."""
+        self.out.emit(payload)
+
+    def _emit_events(self, events: list[DuplexEvent]) -> None:
+        self.out.emit_events(events)
+
+    def _emit_error(
+        self,
+        code: str,
+        message: str,
+        *,
+        event_id: object | None = None,
+        retryable: bool | None = None,
+    ) -> None:
+        self.out.emit_error(code, message, event_id=event_id, retryable=retryable)
+
+    def _require_projector(self) -> RealtimeProjectionState:
+        return self.out.require_projector()
+
+    def _is_stale_model_output(self, payload: dict[str, object]) -> bool:
+        return self.out.is_stale_model_output(payload)
+
+    def _promote_deferred_overlap_later(self, payload: dict[str, object], precreate_response: bool) -> None:
+        """Re-enter the mailbox so the promoted turn is handled in command order."""
+        self._mailbox.put_nowait(
+            _Internal(
+                "promote_deferred_overlap",
+                {"payload": payload, "precreate_response": precreate_response},
+            )
+        )
+
+    # ------------------------------------------------------------------ #
+    # Session lifecycle helpers                                          #
+    # ------------------------------------------------------------------ #
+
+    def _begin_close(self, reason: str) -> None:
+        self.run.closing = True
+        self.run.close_reason = self.run.close_reason or reason
+        self.session.mark_closing()
+
+    def _session_auto_responds(self) -> bool:
+        return self.out.auto_responds()
+
+    def _cleanup_duplex_session_state(self) -> None:
+        session = self.session
+        self.plugin.data_plane.close_session(session.session_id, active_request_id=session.active_request_id)
+        self.run.stream_request_id = None
+
+    # ------------------------------------------------------------------ #
+    # Append path (was the audio-append branch + start_native_append)    #
+    # ------------------------------------------------------------------ #
+
+    async def _barge_in_for_overlap(self, event: dict[str, object], decision: dict[str, object]) -> bool:
+        """Interrupt the model so the user's overlapping speech becomes the turn.
+
+        Cancels the active response and the data-plane stream, advances the
+        barge-in epoch so stale output is dropped, and reports what was cut.
+        Returns whether the append should continue: losing the fence race
+        means this append belongs to a superseded epoch and is abandoned.
+        """
+        session = self.session
+        model_state = self.model_state
+        event["force_barge_in"] = True
+        cancelled_fence = session.fence
+        playback_was_active = helpers.assistant_playback_active(self.session)
+        model_state.audio_buffer.clear_force_listen()
+        session.reset_overlap_speech()
+        model_state.input_since_commit = False
+        model_state.speech_since_commit = False
+        await self.tasks.cancel_append_tasks()
+        had_stream = self.run.stream_request_id is not None
+        cancel_reason = str(decision.get("cancel_reason") or "barge_in")
+        cancelled = await self._cancel_active_response(
+            self.tasks.active_response_task,
+            reason=cancel_reason,
+        )
+        had_stream = self.model.cancel_data_plane_stream() or had_stream
+        if not cancelled and had_stream:
+            old_epoch = session.epoch
+            old_response_id = session.active_response_id
+            committed_ms = session.playback.committed_ms
+            helpers.commit_played_response_history(session, old_response_id, committed_ms)
+            new_epoch, old_playback = helpers.advance_barge_in_epoch(session)
+            self.emit(
+                {
+                    "type": "audio.cancelled",
+                    "session_id": session.session_id,
+                    "response_id": old_response_id,
+                    "reason": cancel_reason,
+                    "cancelled_epoch": old_epoch,
+                    "epoch": new_epoch,
+                    "committed_ms": committed_ms,
+                    "playback": old_playback,
+                }
+            )
+            cancelled = True
+        if not cancelled and playback_was_active:
+            old_epoch = session.epoch
+            committed_ms = session.playback.committed_ms
+            helpers.commit_played_response_history(session, session.last_response_id, committed_ms)
+            new_epoch, old_playback = helpers.advance_barge_in_epoch(session)
+            self.emit(
+                {
+                    "type": "audio.cancelled",
+                    "session_id": session.session_id,
+                    "response_id": session.last_response_id,
+                    "reason": cancel_reason,
+                    "cancelled_epoch": old_epoch,
+                    "epoch": new_epoch,
+                    "committed_ms": committed_ms,
+                    "playback": old_playback,
+                }
+            )
+            cancelled = True
+        if session.epoch > cancelled_fence.epoch:
+            if not await self.model.signal_cancel_fence(cancelled_fence):
+                return False
+        self.tasks.active_response_task = None
+        return True
+
+    async def _on_append_audio(self, event: dict[str, object]) -> None:
+        session = self.session
+        model_state = self.model_state
+        session.mark_user_input_activity()
+        audio = event.get("audio") or event.get("data")
+        if not isinstance(audio, str):
+            self._emit_error("bad_event", "input_audio_buffer.append requires audio")
+            return
+        if not session.capabilities.supports_barge_in and overlap_policy.event_requests_barge_in(event):
+            self._emit_events([helpers.barge_in_unsupported_error()])
+            event = dict(event)
+            event.pop("force_barge_in", None)
+            for key in ("overlap_action", "overlap"):
+                value = event.get(key)
+                if isinstance(value, str) and value.strip().lower() in {"barge_in", "interrupt", "cancel"}:
+                    event.pop(key, None)
+        fmt = event.get("format") if isinstance(event.get("format"), str) else "pcm16"
+        sr_raw = event.get("sample_rate_hz") or event.get("sample_rate")
+        sample_rate_hz = sr_raw if isinstance(sr_raw, int | float) else 16000
+        try:
+            audio, fmt, sample_rate_hz = await self.offload(
+                convert_input_audio_with_rate,
+                audio,
+                fmt,
+                sample_rate_hz=sample_rate_hz,
+            )
+        except ValueError as exc:
+            self._emit_error("bad_event", str(exc))
+            return
+        if isinstance(fmt, str) and fmt.lower() in {"pcm16", "pcm_s16le", "s16le"}:
+            self._emit_error("bad_audio", "input_audio_buffer.append pcm16 audio could not be decoded")
+            return
+        event["audio"] = audio
+        event["format"] = fmt
+        event["sample_rate_hz"] = sample_rate_hz
+        vad_result = await self.control.run_turn_detection(event)
+        projector = self._require_projector()
+        self._emit_events(note_input_append(projector, event, vad_result=vad_result))
+        if self.run.closing or session.state != DuplexSessionState.OPEN:
+            return
+
+        force_listen = bool(event.get("force_listen", False))
+        payload: dict[str, object] = {
+            "type": "audio",
+            "audio": audio,
+            "format": fmt,
+            "sample_rate_hz": sample_rate_hz,
+            "force_listen": force_listen,
+        }
+        video_frames = event.get("video_frames")
+        if isinstance(video_frames, list):
+            frames = [frame for frame in video_frames if isinstance(frame, str) and frame]
+            if frames:
+                payload["video_frames"] = frames
+        payload["is_speech"] = overlap_policy.input_looks_like_speech(self.session, event, payload)
+        auto_responds = self._session_auto_responds()
+        defer_append = False
+        buffer_overlap_audio = True
+        self._mark_pending_silence_superseded()
+        overlap_active = helpers.response_in_progress(self.session, self.tasks) and (
+            not auto_responds
+            or (
+                session.capabilities.supports_barge_in
+                and (
+                    session.config.overlap_policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value
+                    or overlap_policy.event_requests_barge_in(event)
+                )
+            )
+        )
+        if overlap_active:
+            decision = overlap_policy.decide(self.session, event, payload, auto_responds=auto_responds)
+            self._emit_events([helpers.overlap_decision_event(self.session, decision)])
+            action = decision.get("action")
+            if action == "drop":
+                duration_ms = overlap_policy.input_audio_duration_ms(event, payload)
+                self._emit_events(discard_pending_input_audio(projector, duration_ms))
+                self._maybe_schedule_vad_commit(vad_result)
+                return
+            if action == "listen":
+                buffer_overlap_audio = bool(decision.get("buffer_audio", True))
+                defer_append = bool(decision.get("defer_runtime_append", True))
+                if not buffer_overlap_audio and decision.get("preserve_realtime_input") is not True:
+                    self._emit_events(
+                        discard_pending_input_audio(projector, overlap_policy.input_audio_duration_ms(event, payload))
+                    )
+                if decision.get("force_listen", True) is True:
+                    payload["force_listen"] = True
+            else:
+                if not await self._barge_in_for_overlap(event, decision):
+                    return
+                buffer_overlap_audio = True
+                defer_append = False
+        elif not auto_responds and not overlap_policy.input_looks_like_speech(self.session, event, payload):
+            # Turn-mode only: skip silent chunks so they don't open a response.
+            self.emit(
+                {
+                    "type": "response.listen",
+                    "session_id": session.session_id,
+                    "epoch": session.epoch,
+                    "reason": "silence_or_noise",
+                }
+            )
+            self._maybe_schedule_vad_commit(vad_result)
+            return
+        if overlap_policy.should_force_listen_for_auto_response_overlap(event, payload, auto_responds=auto_responds):
+            payload["force_listen"] = True
+        if not buffer_overlap_audio:
+            self._maybe_schedule_vad_commit(vad_result)
+            return
+        session.mark_user_input_activity()
+        model_state.input_since_commit = True
+        model_state.speech_since_commit = model_state.speech_since_commit or overlap_policy.input_looks_like_speech(
+            self.session, event, payload
+        )
+        raw_audio_bytes = helpers.audio_payload_size_bytes(payload)
+        try:
+            if not session.reserve_input_bytes(
+                raw_audio_bytes,
+                limit=int(self.manager.runtime_config.max_pending_input_bytes_per_session),
+            ):
+                self._emit_error("input_backpressure", "Duplex session pending input exceeds server limit")
+                return
+            # Full-duplex: emit each ~chunk_period of audio so the model runs
+            # per-chunk generation without an explicit response.create.
+            allow_emit = not defer_append and self._session_auto_responds()
+            pcm_reservation = model_state.audio_buffer.prepare_append(
+                payload,
+                operation_id=uuid.uuid4().hex,
+                chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
+                allow_emit=allow_emit,
+            )
+        except ValueError as exc:
+            session.release_input_bytes(raw_audio_bytes)
+            self._emit_error("bad_event", str(exc))
+            return
+        if pcm_reservation is None:
+            self._maybe_schedule_vad_commit(vad_result)
+            return
+        if pcm_reservation.byte_count == 0:
+            session.release_input_bytes(raw_audio_bytes)
+        payload = pcm_reservation.payload
+        await self._start_append(payload, final=False, pcm_reservation=pcm_reservation)
+        self._maybe_schedule_vad_commit(vad_result)
+
+    def _maybe_schedule_vad_commit(self, vad_result: TurnDetectionResult | None) -> None:
+        """Server VAD ended the user turn: run the same commit the old translator synthesized."""
+        if vad_result is None or not vad_result.should_commit:
+            return
+        if self._session_auto_responds():
+            # A model-native session decides its own turns; server VAD is there
+            # to hear the user (speech_started / speech_stopped, barge-in), not
+            # to end the turn. Committing at the detector's stop cuts the
+            # utterance short: the model listens on that early final unit, the
+            # trailing silence lands in a second, near-empty turn, and the
+            # client's own commit then has nothing left to answer. The old
+            # translator synthesized this commit for turn-based server VAD only.
+            return
+        command = Commit(final=True, create_response=vad_result.create_response)
+        resolved = resolve_commit(self._require_projector(), command)
+        self._emit_events(resolved.events)
+        if resolved.reset_vad:
+            self.control.reset_vad()
+        if resolved.payload is not None:
+            self._mailbox.put_nowait(_Internal("commit", resolved.payload))
+
+    def _clear_completed_pending_silence(self) -> None:
+        task = self.model_state.pending_silence_task
+        if task is not None and task.done():
+            self.model_state.pending_silence_task = None
+            self.model_state.pending_silence_owner_id = None
+
+    def _mark_pending_silence_superseded(self) -> None:
+        task = self.model_state.pending_silence_task
+        if task is None:
+            return
+        if task.done():
+            self.model_state.pending_silence_task = None
+        # Do not cancel the task here: a silence append may already have
+        # reached the stage; before_append skips silence that has not started.
+        self.model_state.pending_silence_owner_id = None
+
+    def _real_input_waiting(self) -> bool:
+        self._clear_completed_pending_silence()
+        return self.model_state.audio_buffer.has_pending() or self.model_state.audio_buffer.has_reserved()
+
+    async def _start_append(
+        self,
+        payload: dict[str, object],
+        *,
+        final: bool,
+        precreate_response: bool = False,
+        pcm_reservation: PcmAppendReservation | None = None,
+        operation_id: str | None = None,
+        retained_committed_payload: dict[str, object] | None = None,
+        silence_continuation: bool = False,
+        before_append: Callable[[], bool] | None = None,
+    ) -> asyncio.Task[bool]:
+        session = self.session
+        model_state = self.model_state
+        if not silence_continuation:
+            self._mark_pending_silence_superseded()
+        append_epoch = session.epoch
+        append_turn_id = payload_turn_id(payload)
+        if append_turn_id is None:
+            append_turn_id = session.turn_id
+        request_id = helpers.stage0_request_id(self.session, append_epoch)
+        if final or precreate_response:
+            session.bind_request(request_id)
+        if precreate_response:
+            session.bind_response_turn(append_turn_id)
+        if precreate_response and session.active_response_id is None:
+            response_id = session.begin_response(turn_id=append_turn_id)
+            self.emit(self.model.response_created_payload(response_id, epoch=append_epoch))
+        attempt = AppendAttempt(
+            ctx=self.ctx,
+            out=self.out,
+            model=self.model,
+            fail_session=self._fail_session_from_append,
+            payload=payload,
+            epoch=append_epoch,
+            request_id=request_id,
+            final=final,
+            pcm_reservation=pcm_reservation,
+            operation_id=operation_id,
+            retained_committed_payload=retained_committed_payload,
+            precreated_response_id=session.active_response_id if precreate_response else None,
+            before_append=before_append,
+        )
+
+        predecessor = self.tasks.append_tail
+        if predecessor is not None and predecessor.done():
+            try:
+                predecessor_ok = predecessor.result()
+            except (asyncio.CancelledError, Exception):
+                predecessor_ok = False
+            if not predecessor_ok:
+                # Appends queued behind a failed predecessor stop; a later
+                # command is an explicit retry and starts a new chain.
+                predecessor = None
+        task = asyncio.create_task(attempt.run_in_wire_order(predecessor))
+        task.add_done_callback(attempt.release_on_failure)
+        self.tasks.append_tail = task
+        self.tasks.track_append_task(
+            task,
+            epoch=append_epoch,
+            final=final,
+            response_bound=final or precreate_response,
+        )
+        if silence_continuation:
+            model_state.pending_silence_task = task
+            task.add_done_callback(attempt.clear_pending_silence)
+        # Let this wire-order effect start before the next mailbox item can cancel it.
+        await asyncio.sleep(0)
+        return task
+
+    def _fail_session_from_append(self, reason: str) -> None:
+        """An append task died: mark the session closing now, close it out next."""
+        self._begin_close(reason)
+        self.spawn(self._close_from_runtime(reason), name="duplex-runtime-close")
+
+    async def _wait_for_append_tail(self) -> bool:
+        predecessor = self.tasks.append_tail
+        if predecessor is None:
+            return True
+        try:
+            return await predecessor
+        except asyncio.CancelledError:
+            current = asyncio.current_task()
+            if current is not None and current.cancelling():
+                raise
+            return False
+        except Exception:
+            return False
+
+    async def _schedule_silence_continuation(
+        self,
+        payload: object,
+        *,
+        request_id: str,
+        owner_id: str,
+        response_id: str | None,
+        response_owned: bool,
+        expected_epoch: int | None,
+        expected_model_turn_id: int | None,
+    ) -> bool:
+        session = self.session
+        model_state = self.model_state
+        self._clear_completed_pending_silence()
+        pending_silence = model_state.pending_silence_task
+        if pending_silence is not None and not pending_silence.done():
+            if pending_silence is asyncio.current_task():
+                return False
+            try:
+                if not await pending_silence:
+                    return False
+            except asyncio.CancelledError:
+                current = asyncio.current_task()
+                if current is not None and current.cancelling():
+                    raise
+                return False
+            except Exception:
+                return False
+            self._clear_completed_pending_silence()
+            pending_silence = model_state.pending_silence_task
+            if pending_silence is not None and not pending_silence.done():
+                return False
+        append_tail = self.tasks.append_tail
+        if (append_tail is None or append_tail.done()) and self._real_input_waiting():
+            return False
+        continuation_delay_s = max(0.0, float(session.capabilities.chunk_period_ms or 1000) / 1000.0)
+        if continuation_delay_s > 0:
+            await asyncio.sleep(continuation_delay_s)
+            if (
+                self.tasks.append_tail is not append_tail
+                or ((append_tail is None or append_tail.done()) and self._real_input_waiting())
+                or self.model.silence_continuation_is_stale(
+                    request_id=request_id,
+                    response_id=response_id,
+                    response_owned=response_owned,
+                    expected_epoch=expected_epoch,
+                    expected_model_turn_id=expected_model_turn_id,
+                )
+            ):
+                return False
+
+        def _still_valid() -> bool:
+            return not self._real_input_waiting() and not self.model.silence_continuation_is_stale(
+                request_id=request_id,
+                response_id=response_id,
+                response_owned=response_owned,
+                expected_epoch=expected_epoch,
+                expected_model_turn_id=expected_model_turn_id,
+            )
+
+        model_state.pending_silence_owner_id = owner_id
+        task = await self._start_append(
+            dict(payload) if isinstance(payload, dict) else {},
+            final=False,
+            silence_continuation=True,
+            before_append=_still_valid,
+        )
+        return task is not None
+
+    # ------------------------------------------------------------------ #
+    # Runtime-initiated close                                             #
+    # ------------------------------------------------------------------ #
+
+    async def _close_from_runtime(self, reason: str) -> None:
+        """A runtime failure closed the session from inside the engine."""
+        session = self.session
+        if session.state == DuplexSessionState.CLOSED:
+            return
+        self.run.runtime_closed = True
+        self._begin_close(reason)
+        self._cleanup_duplex_session_state()
+        # ``closed_deferred`` means a manager-driven close already promised the
+        # terminal after its stage cleanup. Emitting here too would give the
+        # session two terminal events: this path can run concurrently, when an
+        # append task abandoned by that close fails and calls back in.
+        if not self.run.closed_emitted and not self.run.closed_deferred:
+            self.run.closed_emitted = True
+            self.emit({"type": "session.closed", "session_id": session.session_id, "reason": reason})
+        session.close()
+        # The manager aborts the stage requests (if any) and frees the
+        # admission slot; a session without stage requests must not stay
+        # registered until its idle TTL.
+        self.manager.close_from_runner(self, reason)
+
+    # ------------------------------------------------------------------ #
+    # Cancel / barge-in                                                  #
+    # ------------------------------------------------------------------ #
+
+    async def _on_cancel(self, event: dict[str, object]) -> None:
+        session = self.session
+        model_state = self.model_state
+        event_type = str(event.get("type"))
+        if event_type == "barge_in" and not session.capabilities.supports_barge_in:
+            self._emit_events([helpers.barge_in_unsupported_error()])
+            return
+        cancel_reason = (
+            "output_audio_buffer_clear"
+            if event_type == "output_audio_buffer.clear"
+            else "client_cancelled"
+            if event_type == "response.cancel"
+            else "barge_in"
+        )
+        cancelled_fence = session.fence
+        if event_type == "response.cancel":
+            requested_response_id = event.get("response_id")
+            has_active_response_work = helpers.response_in_progress(self.session, self.tasks)
+            if (
+                isinstance(requested_response_id, str)
+                and session.active_response_id is not None
+                and requested_response_id != session.active_response_id
+            ):
+                self._emit_error(
+                    "response_not_active",
+                    f"Response is not active: {requested_response_id}",
+                    event_id=event.get("realtime_event_id"),
+                )
+                return
+            if not has_active_response_work:
+                if isinstance(requested_response_id, str):
+                    return
+                self._emit_error(
+                    "response_not_active",
+                    "response.cancel requires an active response",
+                    event_id=event.get("realtime_event_id"),
+                )
+                return
+        had_unbuffered_append = model_state.input_since_commit and not model_state.audio_buffer.has_pending()
+        playback_was_active = helpers.assistant_playback_active(self.session)
+        if event_type in {"input.cancel", "barge_in"}:
+            model_state.audio_buffer.clear()
+            session.release_all_input_bytes()
+            model_state.input_since_commit = False
+            model_state.speech_since_commit = False
+            model_state.clear_committed_audio()
+        had_append = await self.tasks.cancel_append_tasks(
+            response_bound_only=event_type in {"response.cancel", "output_audio_buffer.clear"},
+        )
+        if event_type == "response.cancel":
+            session.release_input_bytes(model_state.clear_committed_audio())
+        had_stream = self.run.stream_request_id is not None
+        cancelled = await self._cancel_active_response(self.tasks.active_response_task, reason=cancel_reason)
+        had_stream = self.model.cancel_data_plane_stream() or had_stream
+        if not cancelled and (had_stream or had_append or had_unbuffered_append):
+            old_epoch = session.epoch
+            old_response_id = session.active_response_id
+            committed_ms = session.playback.committed_ms
+            helpers.commit_played_response_history(session, old_response_id, committed_ms)
+            new_epoch, old_playback = helpers.advance_barge_in_epoch(session)
+            self.emit(
+                {
+                    "type": "audio.cancelled",
+                    "session_id": session.session_id,
+                    "response_id": old_response_id,
+                    "reason": cancel_reason,
+                    "cancelled_epoch": old_epoch,
+                    "epoch": new_epoch,
+                    "committed_ms": committed_ms,
+                    "playback": old_playback,
+                }
+            )
+            cancelled = True
+        if not cancelled and playback_was_active:
+            old_epoch = session.epoch
+            committed_ms = session.playback.committed_ms
+            helpers.commit_played_response_history(session, session.last_response_id, committed_ms)
+            new_epoch, old_playback = helpers.advance_barge_in_epoch(session)
+            self.emit(
+                {
+                    "type": "audio.cancelled",
+                    "session_id": session.session_id,
+                    "response_id": session.last_response_id,
+                    "reason": cancel_reason,
+                    "cancelled_epoch": old_epoch,
+                    "epoch": new_epoch,
+                    "committed_ms": committed_ms,
+                    "playback": old_playback,
+                }
+            )
+            cancelled = True
+        if not cancelled and event_type == "response.cancel":
+            old_epoch = session.epoch
+            old_response_id = session.active_response_id
+            committed_ms = session.playback.committed_ms
+            helpers.commit_played_response_history(session, old_response_id, committed_ms)
+            new_epoch, old_playback = helpers.advance_barge_in_epoch(session)
+            self.emit(
+                {
+                    "type": "audio.cancelled",
+                    "session_id": session.session_id,
+                    "response_id": old_response_id,
+                    "reason": cancel_reason,
+                    "cancelled_epoch": old_epoch,
+                    "epoch": new_epoch,
+                    "committed_ms": committed_ms,
+                    "playback": old_playback,
+                }
+            )
+            cancelled = True
+        if not cancelled and event_type == "output_audio_buffer.clear":
+            old_playback = session.playback.as_dict()
+            committed_ms = session.playback.committed_ms
+            session.clear_playback_cursor()
+            self.emit(
+                {
+                    "type": "audio.cancelled",
+                    "session_id": session.session_id,
+                    "response_id": session.active_response_id,
+                    "reason": cancel_reason,
+                    "cancelled_epoch": session.epoch,
+                    "epoch": session.epoch,
+                    "committed_ms": committed_ms,
+                    "playback": old_playback,
+                }
+            )
+            self.tasks.active_response_task = None
+            return
+        if not cancelled:
+            self._cancel_pending_input(reason="barge_in")
+        if not await self.model.signal_cancel_fence(cancelled_fence):
+            return
+        self.tasks.active_response_task = None
+
+    async def _cancel_active_response(
+        self,
+        active_task: asyncio.Task[None] | None,
+        *,
+        reason: str,
+        notify: bool = True,
+    ) -> bool:
+        session = self.session
+        has_running_task = active_task is not None and not active_task.done()
+        if not has_running_task and session.active_request_id is None and session.active_response_id is None:
+            return False
+
+        old_epoch = session.epoch
+        old_request_id = session.active_request_id
+        old_response_id = session.active_response_id
+        committed_ms = session.playback.committed_ms
+        committed_message = session.end_response(
+            commit_text=self.model.should_commit_response_to_history(session, old_response_id),
+            playback_commit_policy=DuplexPlaybackCommitPolicy.ACK_ONLY.value,
+        )
+        if old_response_id is not None:
+            item_id = f"item_{old_response_id}"
+            if committed_message is not None:
+                session.register_history_item(item_id, committed_message)
+            elif committed_ms > 0 and not session.playback_ack_is_too_late(old_response_id, item_id):
+                session.truncate_history_item(item_id, audio_end_ms=committed_ms)
+        # The epoch bump is the atomic part: from here on every model output
+        # and append of the old epoch is dropped by the stale-epoch filter in
+        # ``emit`` / the append tail, whatever the awaits below interleave with.
+        new_epoch, old_playback = helpers.advance_barge_in_epoch(session)
+        if old_request_id is not None:
+            # Release projector/parser cursors so cancelled epochs do not
+            # accumulate until the whole session closes.
+            self.plugin.data_plane.close_stream(old_request_id)
+            await self._abort_request_background(old_request_id, notify=notify)
+        if has_running_task and active_task is not None:
+            active_task.cancel()
+            try:
+                await asyncio.wait_for(asyncio.gather(active_task, return_exceptions=True), timeout=0.25)
+            except TimeoutError:
+                pass
+        if notify:
+            self.emit(
+                {
+                    "type": "audio.cancelled",
+                    "session_id": session.session_id,
+                    "response_id": old_response_id,
+                    "reason": reason,
+                    "cancelled_epoch": old_epoch,
+                    "epoch": new_epoch,
+                    "committed_ms": committed_ms,
+                    "playback": old_playback,
+                }
+            )
+        return True
+
+    async def _abort_request_background(self, request_id: str, *, notify: bool) -> None:
+        try:
+            await self.stage_port.abort_requests([request_id])
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.exception("Failed to abort duplex request %s: %s", request_id, exc)
+            if notify and self.session.state != DuplexSessionState.CLOSED:
+                self.model.send_runtime_error("runtime_abort_failed", exc)
+
+    def _cancel_pending_input(self, *, reason: str) -> None:
+        session = self.session
+        cancelled = session.cancel_pending_input()
+        helpers.advance_barge_in_epoch(session)
+        self.emit(
+            {
+                "type": "input.cancelled",
+                "session_id": session.session_id,
+                "reason": reason,
+                "epoch": session.epoch,
+                "cancelled": cancelled,
+            }
+        )
+
+    # ------------------------------------------------------------------ #
+    # Commit / response.create                                           #
+    # ------------------------------------------------------------------ #
+
+    def _apply_response_create_options(self, response_payload: dict[str, object]) -> str | None:
+        session = self.session
+        try:
+            options = ResponseCreateOptions.from_realtime(
+                response_payload,
+                private_runtime_config_keys=self.plugin.private_runtime_config_keys,
+            )
+        except DuplexConfigError as exc:
+            return exc.code
+        try:
+            session.reserve_response_options(options)
+        except Exception:
+            return "response_already_active"
+        return None
+
+    async def _flush_and_submit_committed_turn(
+        self,
+        event: dict[str, object],
+        *,
+        event_type: str,
+        realtime_item_id: object,
+        should_create_response: bool,
+    ) -> bool:
+        """Flush the buffered turn and submit it, with no response yet running.
+
+        Returns whether the turn was flushed. An empty buffer falls through to
+        the bare acknowledgement at the end of ``_on_commit``.
+        """
+        session = self.session
+        model_state = self.model_state
+        commit_reservation = (
+            model_state.audio_buffer.prepare_commit(
+                operation_id=uuid.uuid4().hex,
+                chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
+            )
+            if event_type in {"input.commit", "input_audio_buffer.commit"}
+            else None
+        )
+        flushed_buffer_reserved_bytes = model_state.audio_buffer.pending_byte_count if commit_reservation is None else 0
+        flushed = (
+            commit_reservation.payload
+            if commit_reservation is not None
+            else model_state.audio_buffer.flush(chunk_period_ms=session.capabilities.chunk_period_ms or 1000)
+        )
+        if model_state.committed_audio_payload is not None:
+            if flushed is not None:
+                flushed = overlap_policy.merge_audio_payloads(model_state.committed_audio_payload, flushed)
+            else:
+                flushed = model_state.committed_audio_payload
+        if commit_reservation is not None:
+            commit_reservation.commit()
+        if flushed is None:
+            return False
+        if overlap_policy.should_force_listen_for_short_commit(self.session, event, flushed):
+            flushed = dict(flushed)
+            flushed["force_listen"] = True
+        model_state.input_since_commit = False
+        committed = helpers.commit_audio_input(
+            session,
+            realtime_item_id=realtime_item_id,
+            transcript=event.get("transcript"),
+        )
+        self.emit(
+            helpers.audio_committed_payload(
+                session,
+                committed=committed,
+                realtime_item_id=realtime_item_id,
+                transcript=event.get("transcript"),
+            )
+        )
+        operation_id = commit_reservation.operation_id if commit_reservation is not None else uuid.uuid4().hex
+        reserved_bytes = (
+            commit_reservation.byte_count if commit_reservation is not None else flushed_buffer_reserved_bytes
+        )
+        model_state.retain_committed_audio(flushed, operation_id=operation_id, reserved_bytes=reserved_bytes)
+        if should_create_response:
+            await self._start_append(
+                flushed,
+                final=True,
+                precreate_response=True,
+                operation_id=model_state.committed_audio_operation_id,
+                retained_committed_payload=flushed,
+            )
+        else:
+            model_state.deferred_response_create = False
+        return True
+
+    async def _start_response_from_committed_audio(self) -> None:
+        """Answer a client ``response.create``.
+
+        A turn starts from committed input. Audio is the usual kind, but the
+        Realtime protocol also lets a client build the turn out of
+        ``conversation.item.create`` and ask for a response with no audio at
+        all; those items are input too. A model-native session still generates
+        per audio unit, so an item-only turn is primed with the model's own
+        silence unit -- the one continuations already use -- rather than with
+        anything this layer invents.
+
+        Refused only when nothing is waiting, or a response is already running,
+        rather than silently producing an empty turn.
+        """
+        session = self.session
+        model_state = self.model_state
+        if (
+            helpers.response_in_progress(self.session, self.tasks)
+            or self.tasks.append_tasks
+            or self.run.stream_request_id is not None
+        ):
+            if session.active_response_id is None and (
+                session.active_request_id is not None
+                or self.tasks.append_tasks
+                or self.run.stream_request_id is not None
+            ):
+                return
+            self._emit_error(
+                "response_already_active", "response.create cannot start while another response is active."
+            )
+            session.discard_response_options()
+            return
+        if model_state.committed_audio_payload is not None:
+            committed_payload = model_state.committed_audio_payload
+            operation_id = model_state.committed_audio_operation_id
+            if operation_id is None:
+                operation_id = uuid.uuid4().hex
+                model_state.committed_audio_operation_id = operation_id
+            session.reset_unanswered_user_items()
+            await self._start_append(
+                committed_payload,
+                final=True,
+                precreate_response=True,
+                operation_id=operation_id,
+                retained_committed_payload=committed_payload,
+            )
+            return
+        if session.unanswered_user_items():
+            # Conversation items are context, not a turn. A model-native model
+            # decides to speak from the audio it hears, and there is no audio
+            # here: opening a response anyway produces one the model never
+            # fills, which the caller only discovers when the session idles
+            # out. Text reaches such a model through the seeded opening turn
+            # (``DuplexSessionConfig.initial_user_text``) instead.
+            self._emit_error(
+                "text_only_turn_unsupported",
+                "This duplex model answers speech input only. Seed the session with "
+                "initial_user_text to ask it in text."
+                if session.capabilities.supports_chat_completions
+                else "This duplex model answers speech input only.",
+            )
+            session.reset_unanswered_user_items()
+            session.discard_response_options()
+            return
+        self._emit_error(
+            "response_create_without_input",
+            "Duplex response.create requires committed audio to answer.",
+        )
+        session.discard_response_options()
+
+    def _discard_short_overlap_ack(self) -> None:
+        """Drop a sub-threshold interjection made while the model is speaking.
+
+        Too short to be a turn, so it neither interrupts the response nor
+        becomes one: the buffered audio is discarded and the turn stays with
+        the model.
+        """
+        session = self.session
+        model_state = self.model_state
+        model_state.audio_buffer.clear()
+        session.release_all_input_bytes()
+        model_state.input_since_commit = False
+        model_state.speech_since_commit = False
+        model_state.clear_committed_audio()
+        self._emit_events(discard_pending_input_audio(self._require_projector(), session.overlap_speech_ms))
+        self.emit(
+            {
+                "type": "input.committed",
+                "session_id": session.session_id,
+                "turn_id": session.turn_id,
+                "epoch": session.epoch,
+                "empty": True,
+                "is_speech": False,
+                "overlap_ack": True,
+                "no_response": True,
+            }
+        )
+        session.reset_overlap_speech()
+        session.discard_response_options()
+
+    def _defer_commit_behind_active_response(
+        self,
+        event: dict[str, object],
+        *,
+        realtime_item_id: object,
+        should_create_response: bool,
+        precreate_response_requested: bool,
+    ) -> bool:
+        """Retain a commit that arrived while a response is still running.
+
+        The audio is kept so the turn is not lost, and the response it should
+        start is remembered; ``_maybe_promote_deferred_overlap`` replays it once
+        the active response ends. Returns whether the commit was deferred --
+        an empty buffer has nothing to retain and falls through.
+        """
+        session = self.session
+        model_state = self.model_state
+        commit_reservation = model_state.audio_buffer.prepare_commit(
+            operation_id=uuid.uuid4().hex,
+            chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
+        )
+        deferred_payload = commit_reservation.payload
+        if deferred_payload is None:
+            commit_reservation.commit()
+            return False
+        if model_state.committed_audio_payload is not None:
+            deferred_payload = overlap_policy.merge_audio_payloads(
+                model_state.committed_audio_payload,
+                deferred_payload,
+            )
+        model_state.retain_committed_audio(
+            deferred_payload,
+            operation_id=commit_reservation.operation_id,
+            reserved_bytes=commit_reservation.byte_count,
+        )
+        commit_reservation.commit()
+        model_state.deferred_response_create = should_create_response
+        model_state.deferred_precreate_response = precreate_response_requested
+        model_state.input_since_commit = False
+        model_state.speech_since_commit = False
+        committed = helpers.commit_audio_input(
+            session,
+            realtime_item_id=realtime_item_id,
+            transcript=event.get("transcript"),
+        )
+        committed_payload = helpers.audio_committed_payload(
+            session,
+            committed=committed,
+            realtime_item_id=realtime_item_id,
+            transcript=event.get("transcript"),
+        )
+        committed_payload["overlap_deferred"] = True
+        committed_payload["response_create_deferred"] = should_create_response
+        self.emit(committed_payload)
+        return True
+
+    async def _commit_and_start_auto_response(self, event: dict[str, object], *, realtime_item_id: object) -> None:
+        """Commit the buffered turn and submit it, letting the model answer it."""
+        session = self.session
+        model_state = self.model_state
+        commit_reservation = model_state.audio_buffer.prepare_commit(
+            operation_id=uuid.uuid4().hex,
+            chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
+        )
+        final_payload = commit_reservation.payload
+        if model_state.committed_audio_payload is not None:
+            if final_payload is not None:
+                final_payload = overlap_policy.merge_audio_payloads(model_state.committed_audio_payload, final_payload)
+            else:
+                final_payload = model_state.committed_audio_payload
+        commit_reservation.commit()
+        if final_payload is not None:
+            model_state.retain_committed_audio(
+                final_payload,
+                operation_id=commit_reservation.operation_id,
+                reserved_bytes=commit_reservation.byte_count,
+            )
+        model_state.deferred_response_create = False
+        model_state.input_since_commit = False
+        model_state.speech_since_commit = False
+        data_plane_turn_id = session.turn_id
+        committed = helpers.commit_audio_input(
+            session,
+            realtime_item_id=realtime_item_id,
+            transcript=event.get("transcript"),
+            turn_id=data_plane_turn_id,
+        )
+        self.emit(
+            helpers.audio_committed_payload(
+                session,
+                committed=committed,
+                realtime_item_id=realtime_item_id,
+                transcript=event.get("transcript"),
+            )
+        )
+        if final_payload is not None:
+            await self._start_append(
+                {**final_payload, "duplex_turn_id": data_plane_turn_id},
+                final=True,
+                precreate_response=False,
+                operation_id=commit_reservation.operation_id,
+                retained_committed_payload=final_payload,
+            )
+
+    def _commit_silent_input(self) -> None:
+        """Commit a turn the client itself marked as silence: drop it and keep listening."""
+        session = self.session
+        model_state = self.model_state
+        model_state.input_since_commit = False
+        model_state.speech_since_commit = False
+        model_state.audio_buffer.clear()
+        session.release_all_input_bytes()
+        model_state.clear_committed_audio()
+        self.emit(
+            {
+                "type": "input.committed",
+                "session_id": session.session_id,
+                "turn_id": session.turn_id,
+                "epoch": session.epoch,
+                "empty": True,
+                "is_speech": False,
+                "no_response": True,
+            }
+        )
+        self.emit(
+            {
+                "type": "response.listen",
+                "session_id": session.session_id,
+                "epoch": session.epoch,
+                "reason": "silence_or_noise",
+            }
+        )
+
+    async def _on_commit(self, event: dict[str, object]) -> None:
+        session = self.session
+        model_state = self.model_state
+        event_type = str(event.get("type"))
+        realtime_item_id = event.get("realtime_item_id")
+        realtime_validated_audio_commit = (
+            event_type == "input_audio_buffer.commit" and isinstance(realtime_item_id, str) and bool(realtime_item_id)
+        )
+        if event_type in {"input.commit", "input_audio_buffer.commit"} and not await self._wait_for_append_tail():
+            # resolve_commit has already applied this commit's side effects
+            # (speech_stopped emitted, input flags cleared), so returning
+            # silently leaves the client with those effects, no
+            # input_audio_buffer.committed and no error. The session.update
+            # path says so explicitly; this one now does too.
+            self._emit_error(
+                "commit_aborted",
+                "the commit was not applied because the preceding append failed",
+                event_id=event.get("realtime_event_id"),
+            )
+            return
+        if event_type == "input_audio_buffer.commit" and event.get("is_speech") is False:
+            self._commit_silent_input()
+            return
+        should_create_response = (
+            event_type == "response.create"
+            or bool(event.get("response_create", event_type == "input.commit"))
+            or (event_type == "input_audio_buffer.commit" and self._session_auto_responds())
+        )
+        precreate_response_requested = event_type == "response.create" or bool(
+            event.get("response_create", event_type == "input.commit")
+        )
+        if event_type == "response.create":
+            response_payload = event.get("response")
+            if isinstance(response_payload, dict):
+                response_options_error = self._apply_response_create_options(response_payload)
+                if response_options_error is not None:
+                    error_message = (
+                        "The selected native duplex runtime does not support generation "
+                        "overrides for instructions, voice, temperature, max tokens, tools, or "
+                        "tool_choice."
+                        if response_options_error == "unsupported_native_response_options"
+                        else "response.create cannot reserve options while another response is active."
+                    )
+                    self._emit_error(response_options_error, error_message, event_id=event.get("realtime_event_id"))
+                    return
+        if event_type == "input_audio_buffer.commit":
+            has_pending_audio = (
+                model_state.input_since_commit
+                or model_state.audio_buffer.has_pending()
+                or model_state.committed_audio_payload is not None
+                or realtime_validated_audio_commit
+            )
+            if not has_pending_audio and not self.tasks.append_tasks and self.run.stream_request_id is None:
+                self._emit_error(
+                    "input_audio_buffer_empty", "input_audio_buffer.commit requires a non-empty input audio buffer."
+                )
+                return
+            commit_action = decide_commit_action(
+                CommitSnapshot(
+                    auto_responds=self._session_auto_responds(),
+                    speech_since_commit=model_state.speech_since_commit,
+                    active_response_id=session.active_response_id,
+                    overlap_speech_ms=session.overlap_speech_ms,
+                    response_in_progress=helpers.response_in_progress(self.session, self.tasks),
+                    playback_active=helpers.assistant_playback_active(self.session),
+                )
+            )
+            if commit_action is CommitAction.DEFER_ACTIVE_RESPONSE:
+                if session.overlap_speech_ms <= session.config.overlap_short_ack_ms:
+                    self._discard_short_overlap_ack()
+                    return
+
+                if self._defer_commit_behind_active_response(
+                    event,
+                    realtime_item_id=realtime_item_id,
+                    should_create_response=should_create_response,
+                    precreate_response_requested=precreate_response_requested,
+                ):
+                    return
+            if commit_action is CommitAction.START_AUTO_RESPONSE:
+                await self._commit_and_start_auto_response(event, realtime_item_id=realtime_item_id)
+                return
+        if event_type == "response.create":
+            await self._start_response_from_committed_audio()
+            return
+        if not helpers.response_in_progress(self.session, self.tasks) and await self._flush_and_submit_committed_turn(
+            event,
+            event_type=event_type,
+            realtime_item_id=realtime_item_id,
+            should_create_response=should_create_response,
+        ):
+            return
+        # Nothing flushed (or a response is still in progress): acknowledge the
+        # commit without starting a new response.
+        had_uncommitted_audio = (
+            model_state.input_since_commit
+            or model_state.audio_buffer.has_pending()
+            or model_state.committed_audio_payload is not None
+            or realtime_validated_audio_commit
+        )
+        committed = None
+        if event_type in {"input_audio_buffer.commit", "input.commit"}:
+            model_state.input_since_commit = False
+            model_state.speech_since_commit = False
+        if event_type != "response.create":
+            committed = (
+                helpers.commit_audio_input(
+                    session,
+                    realtime_item_id=realtime_item_id,
+                    transcript=event.get("transcript"),
+                )
+                if had_uncommitted_audio
+                else None
+            )
+            self.emit(
+                helpers.audio_committed_payload(
+                    session,
+                    committed=committed,
+                    realtime_item_id=realtime_item_id,
+                    transcript=event.get("transcript"),
+                )
+            )
+            return
+        if committed is not None:
+            if isinstance(realtime_item_id, str):
+                session.register_history_item(realtime_item_id, committed.message)
+            self.emit(helpers.input_committed_payload(session, committed, realtime_item_id=realtime_item_id))
+        # NOTE(refactor): the old generic chat-completion fallback response
+        # (`_run_response`) is gone; a native session with a response already in
+        # progress only acknowledges the commit here.
+
+    # ------------------------------------------------------------------ #
+    # playback.ack (moved from OmniDuplexSessionHandler)                 #
+    # ------------------------------------------------------------------ #
+
+
+__all__ = ["DuplexSessionRunner"]
diff --git a/vllm_omni/engine/duplex/turn_detection.py b/vllm_omni/engine/duplex/turn_detection.py
new file mode 100644
index 00000000000..6c5c84f8ab4
--- /dev/null
+++ b/vllm_omni/engine/duplex/turn_detection.py
@@ -0,0 +1,301 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Server-side turn detection (``turn_detection: server_vad``) for the session runner.
+
+Moved from the Realtime input translator: the runner owns one
+``ServerTurnDetector`` per session, feeds each appended chunk to it and emits
+``input_audio_buffer.speech_started`` / ``speech_stopped`` from the result.
+The two-phase ``session.update`` commit (prepare / commit / reject) that used
+to live on the translator is expressed by :class:`PendingTurnDetectionUpdate`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+import numpy as np
+
+from vllm_omni.engine.duplex.vad import (
+    SILERO_VAD_MIN_THRESHOLD,
+    ServerVADUnavailableError,
+    SileroStreamingVAD,
+    SileroVADBackendProvider,
+    SileroVADConfig,
+    StreamingVADResult,
+)
+
+__all__ = [
+    "PendingTurnDetectionUpdate",
+    "SileroVADBackendProvider",
+    "ServerTurnDetector",
+    "ServerVADUnavailableError",
+    "TurnDetectionConfig",
+    "TurnDetectionResult",
+    "apply_turn_detection_result",
+    "configured_realtime_turn_detection",
+    "normalize_turn_detection_session_payload",
+    "validate_realtime_turn_detection",
+]
+
+
+def configured_realtime_turn_detection(session_payload: Mapping[str, object]) -> tuple[str | None, object]:
+    """Return ``(field_path, value)`` for the turn detection setting present in the payload."""
+    field = "turn_detection" if "turn_detection" in session_payload else None
+    selected = session_payload.get("turn_detection")
+    audio_config = session_payload.get("audio")
+    if isinstance(audio_config, dict):
+        audio_input = audio_config.get("input")
+        if isinstance(audio_input, dict) and "turn_detection" in audio_input:
+            field, selected = "audio.input.turn_detection", audio_input["turn_detection"]
+    return field, selected
+
+
+def _valid_vad_number(value: object, *, minimum: float, maximum: float | None = None, strict: bool = False) -> bool:
+    return (
+        isinstance(value, int | float)
+        and not isinstance(value, bool)
+        and np.isfinite(float(value))
+        and (float(value) > minimum if strict else float(value) >= minimum)
+        and (maximum is None or float(value) <= maximum)
+    )
+
+
+#: Every field a ``server_vad`` object may carry. Unknown keys are refused
+#: rather than ignored: a misspelled tuning knob that silently does nothing is
+#: worse than a rejected session, because the endpointing still *looks* applied.
+_SERVER_VAD_FIELDS = frozenset(
+    {
+        "type",
+        "threshold",
+        "prefix_padding_ms",
+        "silence_duration_ms",
+        "create_response",
+        "interrupt_response",
+        "min_speech_duration_ms",
+    }
+)
+
+
+def validate_realtime_turn_detection(session_payload: Mapping[str, object]) -> str | None:
+    """Validate the ``turn_detection`` object of a Realtime session payload (None when valid)."""
+    field, turn_detection = configured_realtime_turn_detection(session_payload)
+    if field is None:
+        if session_payload.get("overlap_policy") == "barge_in_on_speech":
+            return (
+                "overlap_policy='barge_in_on_speech' requires turn_detection.type='server_vad' on the Realtime endpoint"
+            )
+        return None
+    if turn_detection is not None and not isinstance(turn_detection, dict):
+        return f"{field} must be null or an object with type='server_vad'"
+    if isinstance(turn_detection, dict):
+        if turn_detection.get("type") != "server_vad":
+            return f"{field}.type must be 'server_vad'"
+        unknown = sorted(set(turn_detection) - _SERVER_VAD_FIELDS)
+        if unknown:
+            return f"Unknown {field} field(s): {', '.join(unknown)}"
+        threshold = turn_detection.get("threshold", 0.5)
+        if not _valid_vad_number(threshold, minimum=SILERO_VAD_MIN_THRESHOLD, strict=True, maximum=1):
+            return f"{field}.threshold must be greater than {SILERO_VAD_MIN_THRESHOLD} and at most 1"
+        for name in ("prefix_padding_ms", "silence_duration_ms", "min_speech_duration_ms"):
+            value = turn_detection.get(name)
+            if value is not None and not _valid_vad_number(value, minimum=0):
+                return f"{field}.{name} must be a non-negative number"
+        if turn_detection.get("interrupt_response", True) is not True:
+            return (
+                f"{field}.interrupt_response=false is unsupported; use turn_detection=null for model-owned listen/speak"
+            )
+    desired_policy = "barge_in_on_speech" if turn_detection is not None else "listen_only"
+    overlap_policy = session_payload.get("overlap_policy")
+    if isinstance(overlap_policy, str) and overlap_policy != desired_policy:
+        return f"overlap_policy={overlap_policy!r} conflicts with turn_detection; expected {desired_policy!r}"
+    return None
+
+
+@dataclass(frozen=True, slots=True)
+class TurnDetectionConfig:
+    """Normalized ``server_vad`` configuration (all fields filled with defaults)."""
+
+    threshold: float = 0.5
+    prefix_padding_ms: int = 300
+    silence_duration_ms: int = 500
+    min_speech_duration_ms: int = 96
+    create_response: bool = True
+    interrupt_response: bool = True
+
+    @classmethod
+    def from_realtime(cls, turn_detection: Mapping[str, object]) -> TurnDetectionConfig:
+        return cls(
+            threshold=float(turn_detection.get("threshold", 0.5)),
+            prefix_padding_ms=int(turn_detection.get("prefix_padding_ms", 300)),
+            silence_duration_ms=int(turn_detection.get("silence_duration_ms", 500)),
+            min_speech_duration_ms=int(turn_detection.get("min_speech_duration_ms", 96)),
+            create_response=bool(turn_detection.get("create_response", True)),
+            interrupt_response=bool(turn_detection.get("interrupt_response", True)),
+        )
+
+    @property
+    def overlap_policy(self) -> str:
+        return "barge_in_on_speech"
+
+    def build_detector(self, backend_provider: SileroVADBackendProvider | None = None) -> ServerTurnDetector:
+        return ServerTurnDetector(self, backend_provider=backend_provider)
+
+
+def normalize_turn_detection_session_payload(
+    session_payload: dict[str, object],
+) -> tuple[bool, TurnDetectionConfig | None]:
+    """Fill ``turn_detection`` defaults and derive ``overlap_policy`` in place.
+
+    Returns ``(configured, config)`` where ``configured`` is False when the
+    payload does not mention turn detection at all (nothing changes), and
+    ``config`` is ``None`` for ``turn_detection: null`` (model-owned turns,
+    ``overlap_policy`` forced to ``listen_only``).
+    """
+    field, configured = configured_realtime_turn_detection(session_payload)
+    if field is None:
+        return False, None
+    if configured is None:
+        session_payload["overlap_policy"] = "listen_only"
+        return True, None
+    assert isinstance(configured, dict)
+    merged = {
+        "type": "server_vad",
+        "interrupt_response": True,
+        "threshold": 0.5,
+        "prefix_padding_ms": 300,
+        "silence_duration_ms": 500,
+        "min_speech_duration_ms": 96,
+        **configured,
+    }
+    config = TurnDetectionConfig.from_realtime(merged)
+    session_payload["turn_detection"] = dict(merged)
+    session_payload["overlap_policy"] = config.overlap_policy
+    return True, config
+
+
+@dataclass(frozen=True, slots=True)
+class TurnDetectionResult:
+    is_speech: bool
+    speech_active: bool
+    speech_started: bool = False
+    speech_stopped: bool = False
+    speech_probability: float = 0.0
+    audio_start_ms: int | None = None
+    audio_end_ms: int | None = None
+    #: A ``speech_stopped`` under ``server_vad`` ends the user turn.
+    should_commit: bool = False
+    #: Whether the auto-commit should also request a response (``create_response``).
+    create_response: bool = True
+
+    def as_payload(self) -> dict[str, object]:
+        return {
+            "backend": "silero",
+            "is_speech": self.is_speech,
+            "speech_active": self.speech_active,
+            "speech_started": self.speech_started,
+            "speech_stopped": self.speech_stopped,
+            "speech_probability": self.speech_probability,
+        }
+
+
+class ServerTurnDetector:
+    """One Silero-backed streaming detector per session."""
+
+    def __init__(
+        self,
+        config: TurnDetectionConfig,
+        *,
+        backend_provider: SileroVADBackendProvider | None = None,
+    ) -> None:
+        self.config = config
+        self._vad = SileroStreamingVAD(
+            SileroVADConfig(
+                threshold=float(config.threshold),
+                prefix_padding_ms=int(config.prefix_padding_ms),
+                silence_duration_ms=int(config.silence_duration_ms),
+                min_speech_duration_ms=max(32, int(config.min_speech_duration_ms)),
+            ),
+            backend_provider=backend_provider,
+        )
+
+    @property
+    def vad(self) -> SileroStreamingVAD:
+        return self._vad
+
+    def reset(self) -> None:
+        self._vad.reset()
+
+    def process(
+        self,
+        base64_audio: str,
+        *,
+        fmt: str,
+        sample_rate_hz: int | None,
+        audio_end_ms: int | None = None,
+    ) -> TurnDetectionResult:
+        """Score one appended chunk. Raises ``ServerVADUnavailableError`` / ``ValueError`` like the VAD."""
+        result: StreamingVADResult = self._vad.process_base64(base64_audio, fmt=fmt, sample_rate_hz=sample_rate_hz)
+        stop_ms = result.speech_end_ms if result.speech_end_ms is not None else audio_end_ms
+        return TurnDetectionResult(
+            is_speech=result.is_speech,
+            speech_active=result.speech_active,
+            speech_started=result.speech_started,
+            speech_stopped=result.speech_stopped,
+            speech_probability=result.speech_probability,
+            audio_start_ms=result.speech_start_ms,
+            audio_end_ms=stop_ms,
+            should_commit=bool(result.speech_stopped and not result.speech_active),
+            create_response=self.config.create_response,
+        )
+
+
+def apply_turn_detection_result(payload: dict[str, object], result: TurnDetectionResult) -> None:
+    """Merge a detector result onto an internal ``input_audio_buffer.append`` payload.
+
+    Mirrors what the old translator attached: ``is_speech`` from the detector,
+    the ``vad`` hint block, and ``force_listen`` while speech is active.
+    """
+    payload["is_speech"] = result.is_speech
+    payload["vad"] = result.as_payload()
+    if result.speech_active:
+        payload["force_listen"] = True
+    if result.audio_start_ms is not None and result.speech_started:
+        payload["audio_start_ms"] = result.audio_start_ms
+    if result.audio_end_ms is not None and result.speech_stopped:
+        payload["audio_end_ms"] = result.audio_end_ms
+
+
+@dataclass
+class PendingTurnDetectionUpdate:
+    """A ``session.update`` turn-detection change awaiting the engine ACK (two-phase)."""
+
+    config: TurnDetectionConfig | None
+    detector: ServerTurnDetector | None
+
+    @classmethod
+    def prepare(
+        cls,
+        session_payload: dict[str, object],
+        *,
+        backend_provider: SileroVADBackendProvider | None = None,
+    ) -> PendingTurnDetectionUpdate | None:
+        """Normalize the payload in place and stage the new detector; None when not configured."""
+        configured, config = normalize_turn_detection_session_payload(session_payload)
+        if not configured:
+            return None
+        detector = config.build_detector(backend_provider) if config is not None else None
+        return cls(config=config, detector=detector)
+
+    def commit(
+        self, current: ServerTurnDetector | None
+    ) -> tuple[TurnDetectionConfig | None, ServerTurnDetector | None]:
+        """Adopt the staged detector; the replaced one is reset. Returns the new (config, detector)."""
+        if current is not None:
+            current.reset()
+        return self.config, self.detector
+
+    def reject(self) -> None:
+        if self.detector is not None:
+            self.detector.reset()
diff --git a/vllm_omni/engine/duplex/vad.py b/vllm_omni/engine/duplex/vad.py
new file mode 100644
index 00000000000..ad3c2682015
--- /dev/null
+++ b/vllm_omni/engine/duplex/vad.py
@@ -0,0 +1,488 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Silero server VAD for the engine-resident duplex session.
+
+The detector keeps the split upstream's serving-side ``server_vad`` module
+used, because the split is what makes one model serve many sessions: a
+**backend** scores one 512-sample frame and is otherwise stateless, and the
+per-stream state -- the partial frame, the model state, the endpoint counters --
+belongs to :class:`SileroStreamingVAD`, one per session.
+
+Two backends. :class:`SileroVADBackend` runs the pinned Silero v6.2 ONNX graph on
+CPU and is shared process-wide, which is why its state is passed in and out
+rather than held on the session object. :class:`TorchSileroBackend` loads the
+same model through the ``silero-vad`` package for environments that have no
+local ONNX artifact; torch keeps its state inside the module, so that one is per
+session.
+
+Endpointing follows Silero v6.2's streaming hysteresis: activation uses the
+configured threshold, while a turn can only *end* on frames below
+``max(threshold - 0.15, 0.01)``. Once a silence candidate exists, louder frames
+keep the elapsed-silence clock running but cannot themselves close the turn.
+"""
+
+from __future__ import annotations
+
+import binascii
+import hashlib
+import threading
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+import numpy as np
+import pybase64 as base64
+from vllm.logger import init_logger
+
+logger = init_logger(__name__)
+
+SILERO_VAD_REPO_ID = "istupakov/silero-vad-onnx"
+SILERO_VAD_REVISION = "8b14476858ef240c50b3884bb38cc67290c1cc70"
+SILERO_VAD_FILENAME = "silero_vad.onnx"
+SILERO_VAD_SHA256 = "1a153a22f4509e292a94e67d6f9b85e8deb25b4988682b7e174c65279d8788e3"
+SILERO_VAD_MIN_THRESHOLD = 0.15
+
+_SAMPLE_RATE_HZ = 16_000
+_FRAME_SAMPLES = 512
+
+
+class ServerVADUnavailableError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class SileroVADConfig:
+    threshold: float = 0.5
+    prefix_padding_ms: int = 300
+    silence_duration_ms: int = 500
+    min_speech_duration_ms: int = 96
+
+
+@dataclass(frozen=True, slots=True)
+class StreamingVADResult:
+    is_speech: bool
+    speech_active: bool
+    speech_started: bool = False
+    speech_stopped: bool = False
+    speech_probability: float = 0.0
+    speech_start_ms: int | None = None
+    speech_end_ms: int | None = None
+
+
+# --------------------------------------------------------------------------- #
+# Backends                                                                    #
+# --------------------------------------------------------------------------- #
+
+
+class SpeechDetectorBackend(Protocol):
+    """Scores one frame. Per-stream state is created here but owned by the caller."""
+
+    frame_samples: int
+
+    def new_state(self) -> object: ...
+
+    def infer(self, frame: np.ndarray, state: object) -> tuple[float, object]: ...
+
+
+@dataclass(frozen=True, slots=True)
+class _SileroVADState:
+    model_state: np.ndarray
+    context: np.ndarray
+
+
+class SileroVADBackend:
+    """Shared ONNX Runtime Silero v6.2 detector running on CPU."""
+
+    sample_rate_hz = _SAMPLE_RATE_HZ
+    frame_samples = _FRAME_SAMPLES
+    context_samples = 64
+    model_state_shape = (2, 1, 128)
+
+    def __init__(self, model_path: str | Path) -> None:
+        try:
+            import onnxruntime as ort
+        except ImportError as exc:  # pragma: no cover - platform packaging supplies ORT.
+            raise ServerVADUnavailableError("server_vad requires ONNX Runtime") from exc
+
+        session_options = ort.SessionOptions()
+        session_options.inter_op_num_threads = 1
+        session_options.intra_op_num_threads = 1
+
+        self.model_path = Path(model_path)
+        self._session = ort.InferenceSession(
+            str(self.model_path),
+            providers=["CPUExecutionProvider"],
+            sess_options=session_options,
+        )
+        input_names = {item.name for item in self._session.get_inputs()}
+        if not {"input", "sr", "state"} <= input_names:
+            raise ServerVADUnavailableError(f"Unsupported Silero ONNX input contract: {sorted(input_names)}")
+        self._warm_up()
+
+    def _warm_up(self) -> None:
+        self.infer(np.zeros(self.frame_samples, dtype=np.float32), self.new_state())
+
+    def new_state(self) -> _SileroVADState:
+        return _SileroVADState(
+            model_state=np.zeros(self.model_state_shape, dtype=np.float32),
+            context=np.zeros((1, self.context_samples), dtype=np.float32),
+        )
+
+    def infer(self, frame: np.ndarray, state: object) -> tuple[float, object]:
+        if not isinstance(state, _SileroVADState):
+            raise TypeError("Silero detector state must be created by SileroVADBackend.new_state()")
+        model_state = np.ascontiguousarray(state.model_state, dtype=np.float32)
+        context = np.ascontiguousarray(state.context, dtype=np.float32)
+        if model_state.shape != self.model_state_shape:
+            raise ValueError(f"Silero model state must have shape {self.model_state_shape}, got {model_state.shape}")
+        expected_context_shape = (1, self.context_samples)
+        if context.shape != expected_context_shape:
+            raise ValueError(f"Silero context must have shape {expected_context_shape}, got {context.shape}")
+
+        audio = np.ascontiguousarray(frame, dtype=np.float32).reshape(1, -1)
+        if audio.shape[1] != self.frame_samples:
+            raise ValueError(
+                f"Silero detector frame must contain exactly {self.frame_samples} samples, got {audio.shape[1]}"
+            )
+        model_input = np.concatenate((context, audio), axis=1)
+        # ONNX Runtime permits concurrent Run calls on one CPU session. Stream
+        # state is explicit, so independent sessions can safely share this one.
+        output = self._session.run(
+            None,
+            {
+                "input": model_input,
+                "state": model_state,
+                "sr": np.asarray(self.sample_rate_hz, dtype=np.int64),
+            },
+        )
+        if len(output) < 2:
+            raise ServerVADUnavailableError("Silero ONNX model did not return probability and model state")
+        probability = float(np.asarray(output[0]).reshape(-1)[0])
+        next_state = _SileroVADState(
+            model_state=np.ascontiguousarray(output[1], dtype=np.float32),
+            context=np.ascontiguousarray(model_input[:, -self.context_samples :], dtype=np.float32),
+        )
+        return probability, next_state
+
+
+class TorchSileroBackend:
+    """The same model through the ``silero-vad`` package, for hosts with no ONNX artifact.
+
+    Torch keeps the recurrent state inside the module, so unlike the ONNX
+    backend this one cannot be shared: each session gets its own instance and
+    ``new_state`` only resets it.
+    """
+
+    sample_rate_hz = _SAMPLE_RATE_HZ
+    frame_samples = _FRAME_SAMPLES
+
+    def __init__(self) -> None:
+        try:
+            import torch
+            from silero_vad import load_silero_vad
+        except ImportError as exc:
+            raise ServerVADUnavailableError(
+                "server_vad needs either a local Silero ONNX artifact (see "
+                "duplex_session.server_vad_model_path) or the optional 'silero-vad' "
+                "package; install vllm-omni[server-vad]"
+            ) from exc
+        self._torch = torch
+        self._model = load_silero_vad(onnx=False)
+
+    def new_state(self) -> object:
+        reset_states = getattr(self._model, "reset_states", None)
+        if callable(reset_states):
+            reset_states()
+        return None
+
+    def infer(self, frame: np.ndarray, state: object) -> tuple[float, object]:
+        tensor = self._torch.from_numpy(np.ascontiguousarray(frame, dtype=np.float32))
+        return float(self._model(tensor, self.sample_rate_hz).item()), state
+
+
+class SileroVADBackendProvider:
+    """Resolve, verify and load one detector backend per engine process.
+
+    ONNX is preferred and shared; the torch package is the fallback and is built
+    per call because its state is internal.
+    """
+
+    def __init__(self, *, model_path: str | None = None) -> None:
+        self.model_path = model_path
+        self._backend: SileroVADBackend | None = None
+        self._lock = threading.Lock()
+
+    def get(self) -> SpeechDetectorBackend:
+        """The shared ONNX backend, or a per-session torch one when it cannot be built.
+
+        An explicitly configured ``server_vad_model_path`` never falls back: the
+        operator named that artifact, so a missing file or a missing ONNX Runtime
+        is their error, not something to paper over with a different model.
+        """
+        if self._backend is not None:
+            return self._backend
+        with self._lock:
+            if self._backend is not None:
+                return self._backend
+            path = self._resolve_local_artifact()
+            if path is None:
+                # No pinned artifact: the torch package keeps state internally,
+                # so this instance belongs to one session only.
+                return TorchSileroBackend()
+            self._verify_checksum(path)
+            try:
+                self._backend = SileroVADBackend(path)
+            except ServerVADUnavailableError:
+                if self.model_path:
+                    raise
+                logger.warning(
+                    "Silero ONNX artifact %s found but ONNX Runtime is unavailable; "
+                    "falling back to the torch 'silero-vad' package (one model per session)",
+                    path,
+                )
+                return TorchSileroBackend()
+        return self._backend
+
+    def _resolve_local_artifact(self) -> Path | None:
+        if self.model_path:
+            path = Path(self.model_path).expanduser()
+            if path.is_file():
+                return path
+            # Explicitly configured: a missing file is an error, not a fallback.
+            raise ServerVADUnavailableError(f"Configured Silero VAD model does not exist: {path}")
+        try:
+            from vllm.transformers_utils.repo_utils import try_get_local_file
+
+            cached = try_get_local_file(
+                model=SILERO_VAD_REPO_ID,
+                file_name=SILERO_VAD_FILENAME,
+                revision=SILERO_VAD_REVISION,
+            )
+        except Exception:
+            return None
+        return cached if isinstance(cached, Path) and cached.is_file() else None
+
+    def _verify_checksum(self, path: Path) -> None:
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        if digest != SILERO_VAD_SHA256:
+            raise ServerVADUnavailableError(
+                f"Silero VAD checksum mismatch for {path}: expected {SILERO_VAD_SHA256}, got {digest}"
+            )
+
+
+# --------------------------------------------------------------------------- #
+# Per-session streaming detector                                              #
+# --------------------------------------------------------------------------- #
+
+
+class SileroStreamingVAD:
+    _SAMPLE_RATE_HZ = _SAMPLE_RATE_HZ
+    _WINDOW_SAMPLES = _FRAME_SAMPLES
+
+    def __init__(
+        self,
+        config: SileroVADConfig,
+        *,
+        backend: SpeechDetectorBackend | None = None,
+        backend_provider: SileroVADBackendProvider | None = None,
+        frame_scorer: Callable[[np.ndarray], float] | None = None,
+    ) -> None:
+        self.config = config
+        self._explicit_backend = backend
+        self._provider = backend_provider
+        self._frame_scorer = frame_scorer
+        self._backend: SpeechDetectorBackend | None = backend
+        self._detector_state: object = None
+        self._clear_stream_state()
+
+    def _clear_stream_state(self) -> None:
+        self._pending = np.empty(0, dtype=np.float32)
+        self._speech_active = False
+        self._candidate_samples = 0
+        self._candidate_start_sample: int | None = None
+        self._silence_samples = 0
+        self._processed_samples = 0
+        self._stream_start_ms = 0
+        self._resample_rate_hz: int | None = None
+        self._resample_remainder = 0
+
+    @property
+    def scratch_bytes(self) -> int:
+        """Bytes this detector holds between chunks (the partial frame only)."""
+        return int(self._pending.nbytes)
+
+    @property
+    def speech_active(self) -> bool:
+        return self._speech_active
+
+    def reset(self) -> None:
+        """Drop stream state while preserving the session-relative audio clock.
+
+        The clock survives so ``speech_start_ms`` after a barge-in still refers
+        to the session's timeline; ``_stream_start_ms`` then stops the prefix
+        padding reaching back into audio that was discarded.
+        """
+        stream_start_ms = round(self._processed_samples * 1000 / self._SAMPLE_RATE_HZ)
+        processed = self._processed_samples
+        self._clear_stream_state()
+        self._processed_samples = processed
+        self._stream_start_ms = stream_start_ms
+        if self._backend is not None:
+            self._detector_state = self._backend.new_state()
+
+    # ------------------------------------------------------------------ #
+    # Input                                                              #
+    # ------------------------------------------------------------------ #
+
+    def process_base64(
+        self,
+        audio: object,
+        *,
+        fmt: object,
+        sample_rate_hz: object,
+    ) -> StreamingVADResult:
+        if not isinstance(audio, str):
+            raise ValueError("Silero server VAD requires base64 audio")
+        try:
+            raw = base64.b64decode(audio, validate=True)
+        except (binascii.Error, ValueError) as exc:
+            raise ValueError("Silero server VAD received invalid base64 audio") from exc
+        rate = int(sample_rate_hz) if isinstance(sample_rate_hz, int | float) else self._SAMPLE_RATE_HZ
+        if rate <= 0:
+            raise ValueError("Silero server VAD requires a positive sample rate")
+
+        if fmt == "pcm_f32le":
+            if len(raw) % 4:
+                raise ValueError("Silero server VAD received an incomplete pcm_f32le frame")
+            samples = np.frombuffer(raw, dtype="<f4").astype(np.float32, copy=False)
+        elif fmt == "pcm16":
+            if len(raw) % 2:
+                raise ValueError("Silero server VAD received an incomplete pcm16 sample")
+            samples = np.frombuffer(raw, dtype="<i2").astype(np.float32) * np.float32(1.0 / 32768.0)
+        else:
+            raise ValueError("Silero server VAD requires pcm_f32le or pcm16 audio")
+
+        return self.process(self._to_16k(samples, rate))
+
+    def _to_16k(self, samples: np.ndarray, rate: int) -> np.ndarray:
+        """Resample to 16 kHz, carrying the fractional sample-count remainder.
+
+        A fallback path: the session runner already normalises input to 16 kHz
+        through ``convert_input_audio_with_rate`` before the detector sees it,
+        so this runs only for callers that feed the VAD directly.
+
+        Carrying the remainder keeps the *number* of output samples exact, so
+        frame boundaries cannot drift over a long stream. The interpolation
+        itself is per chunk and has no filter state, so sample values near a
+        chunk edge differ slightly from resampling the same audio in one go --
+        enough for the frame grid to stay put, not enough to call it a
+        streaming resampler.
+        """
+        if rate == self._SAMPLE_RATE_HZ:
+            self._resample_rate_hz = None
+            self._resample_remainder = 0
+            return samples
+        if self._resample_rate_hz is not None and rate != self._resample_rate_hz:
+            raise ValueError("server_vad input sample rate cannot change within a continuous audio stream")
+        self._resample_rate_hz = rate
+        numerator = samples.size * self._SAMPLE_RATE_HZ + self._resample_remainder
+        target_size, self._resample_remainder = divmod(numerator, rate)
+        if target_size == 0:
+            return np.empty(0, dtype=np.float32)
+        if samples.size == 1:
+            return np.full(target_size, samples[0], dtype=np.float32)
+        source_x = np.linspace(0.0, 1.0, num=samples.size, endpoint=True)
+        target_x = np.linspace(0.0, 1.0, num=target_size, endpoint=True)
+        return np.interp(target_x, source_x, samples).astype(np.float32)
+
+    # ------------------------------------------------------------------ #
+    # Endpointing                                                        #
+    # ------------------------------------------------------------------ #
+
+    def process(self, samples: np.ndarray) -> StreamingVADResult:
+        samples = np.asarray(samples, dtype=np.float32).reshape(-1)
+        if samples.size:
+            self._pending = np.concatenate((self._pending, samples))
+
+        started = False
+        stopped = False
+        start_ms: int | None = None
+        end_ms: int | None = None
+        max_probability = 0.0
+        contained_speech = self._speech_active
+        min_speech_samples = max(1, round(self.config.min_speech_duration_ms * self._SAMPLE_RATE_HZ / 1000))
+        min_silence_samples = max(1, round(self.config.silence_duration_ms * self._SAMPLE_RATE_HZ / 1000))
+        negative_threshold = max(self.config.threshold - SILERO_VAD_MIN_THRESHOLD, 0.01)
+
+        pending = self._pending
+        offset = 0
+        while pending.size - offset >= self._WINDOW_SAMPLES:
+            frame = np.ascontiguousarray(pending[offset : offset + self._WINDOW_SAMPLES], dtype=np.float32)
+            offset += self._WINDOW_SAMPLES
+            frame_start = self._processed_samples
+            self._processed_samples += self._WINDOW_SAMPLES
+            probability = min(1.0, max(0.0, self._score_frame(frame)))
+            max_probability = max(max_probability, probability)
+
+            if self._speech_active:
+                contained_speech = True
+                below_negative_threshold = probability < negative_threshold
+                if not below_negative_threshold and self._silence_samples == 0:
+                    continue
+                # A silence candidate is running: louder frames keep its clock
+                # moving but cannot themselves close the turn.
+                self._silence_samples += self._WINDOW_SAMPLES
+                if not below_negative_threshold or self._silence_samples < min_silence_samples:
+                    continue
+                self._speech_active = False
+                self._silence_samples = 0
+                stopped = True
+                # OpenAI defines audio_end_ms as the end of the audio sent to
+                # the model, trailing silence included.
+                end_ms = max(0, round(self._processed_samples * 1000 / self._SAMPLE_RATE_HZ))
+                continue
+
+            if probability >= self.config.threshold:
+                if self._candidate_samples == 0:
+                    self._candidate_start_sample = frame_start
+                self._candidate_samples += self._WINDOW_SAMPLES
+                if self._candidate_samples >= min_speech_samples:
+                    candidate_start = self._candidate_start_sample or 0
+                    detected_start_ms = round(candidate_start * 1000 / self._SAMPLE_RATE_HZ)
+                    self._speech_active = True
+                    self._candidate_samples = self._silence_samples = 0
+                    self._candidate_start_sample = None
+                    contained_speech = True
+                    started = True
+                    # Prefix audio from before the last reset is gone.
+                    start_ms = max(
+                        self._stream_start_ms,
+                        max(0, detected_start_ms - self.config.prefix_padding_ms),
+                    )
+            else:
+                self._candidate_samples = 0
+                self._candidate_start_sample = None
+
+        # Copy the residual once, after the frames are scored, so a large input
+        # chunk is neither pinned by a view nor re-copied for every frame.
+        self._pending = pending[offset:].copy()
+
+        return StreamingVADResult(
+            contained_speech, self._speech_active, started, stopped, max_probability, start_ms, end_ms
+        )
+
+    def _score_frame(self, frame: np.ndarray) -> float:
+        if self._frame_scorer is not None:
+            return float(self._frame_scorer(frame))
+        backend = self._require_backend()
+        probability, self._detector_state = backend.infer(frame, self._detector_state)
+        return float(probability)
+
+    def _require_backend(self) -> SpeechDetectorBackend:
+        if self._backend is None:
+            provider = self._provider or SileroVADBackendProvider()
+            self._backend = provider.get()
+            self._detector_state = self._backend.new_state()
+        return self._backend
diff --git a/vllm_omni/engine/duplex_omni_engine.py b/vllm_omni/engine/duplex_omni_engine.py
new file mode 100644
index 00000000000..56ca3e352a0
--- /dev/null
+++ b/vllm_omni/engine/duplex_omni_engine.py
@@ -0,0 +1,299 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""DuplexOmniEngine: the duplex engine sibling of ``AsyncOmniEngine``.
+
+It is deliberately small. The engine base owns the stage processes, the
+orchestrator thread and the correlated RPC transport; this class only knows
+how duplex session messages enter the engine (open/close/resume/touch through
+correlated RPC, session commands one-way) and which orchestrator to build
+(``DuplexOrchestrator`` with the model plugin loaded).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import queue
+import uuid
+from typing import TYPE_CHECKING, Any
+
+from vllm.logger import init_logger
+
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
+from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig
+from vllm_omni.engine.duplex.messages import (
+    CloseDuplexSessionMessage,
+    DuplexControlResultMessage,
+    DuplexSessionCommandMessage,
+    DuplexSessionError,
+    OpenDuplexSessionMessage,
+    ResumeDuplexSessionMessage,
+    TouchDuplexSessionMessage,
+)
+from vllm_omni.engine.duplex.plugin import DuplexModelPlugin, EncodeAudio, load_duplex_plugin
+from vllm_omni.engine.messages import EngineQueueMessage
+from vllm_omni.engine.orchestrator import OrchestratorBase
+
+if TYPE_CHECKING:
+    from vllm_omni.engine.duplex.commands import DuplexCommand
+
+logger = init_logger(__name__)
+
+_DEFAULT_CONTROL_TIMEOUT_S = 10.0
+_COMMAND_PUT_TIMEOUT_S = 30.0
+
+
+class DuplexOmniEngine(AsyncOmniEngine):
+    """Engine for full-duplex models; sessions run inside ``DuplexOrchestrator``."""
+
+    plugin: DuplexModelPlugin | None = None
+    #: Set by ``_validate_deployment`` from the deploy config before any stage starts.
+    duplex_session_config: DuplexSessionRuntimeConfig
+
+    # Any: **kwargs is forwarded verbatim to ``OmniEngineBase.__init__``.
+    def __init__(self, model: str, *, duplex_audio_encoder: EncodeAudio, **kwargs: Any) -> None:
+        # Injected by ``DuplexOmni`` (entrypoint layer): the engine package
+        # knows how to hand model audio to the plugin, not how to encode it.
+        self._audio_encoder = duplex_audio_encoder
+        super().__init__(model, **kwargs)
+
+    # ---- orchestrator construction (orchestrator thread) ----
+
+    def _validate_deployment(self) -> None:
+        """Load the plugin and check the scheduler contract before any stage process starts."""
+        pipeline_config = self.pipeline_config
+        plugin_path = getattr(pipeline_config, "duplex_plugin", None) if pipeline_config is not None else None
+        if pipeline_config is None:
+            raise ValueError(
+                f"{self.model!r}: the model pipeline could not be resolved (models with custom HF code "
+                "such as MiniCPM-o need trust_remote_code=True)"
+            )
+        if not plugin_path:
+            raise ValueError(f"{self.model!r} is not a duplex model: the pipeline declares no duplex_plugin")
+        deploy_config = self.deploy_config
+        if deploy_config is None:
+            raise ValueError("DuplexOmniEngine requires a deploy config with session_mode: duplex (none resolved)")
+        if getattr(deploy_config, "session_mode", "turn") != "duplex":
+            raise ValueError(
+                "DuplexOmniEngine requires a deploy config with session_mode: duplex "
+                f"(got {getattr(deploy_config, 'session_mode', None)!r})"
+            )
+        self.duplex_session_config = deploy_config.duplex_session
+        self.plugin = load_duplex_plugin(plugin_path, self._audio_encoder)
+
+    # Any: signature of the ``OmniEngineBase._create_orchestrator`` seam it overrides.
+    def _create_orchestrator(self, **orchestrator_kwargs: Any) -> OrchestratorBase:
+        from vllm_omni.engine.duplex_orchestrator import DuplexOrchestrator
+
+        assert self.plugin is not None, "_validate_deployment() must run before the orchestrator is created"
+        stage0_vllm_config = self.stage_pools[0].stage_vllm_config if self.stage_pools else None
+        model_config = getattr(stage0_vllm_config, "model_config", None)
+        return DuplexOrchestrator(
+            plugin=self.plugin,
+            duplex_session_config=self.duplex_session_config,
+            model_config=model_config,
+            **orchestrator_kwargs,
+        )
+
+    # ---- deployment facts ----
+
+    @property
+    def duplex_capabilities(self) -> DuplexCapabilities:
+        if self.plugin is None:
+            raise RuntimeError("duplex plugin is not loaded")
+        return self.plugin.capabilities(max_sessions=self.duplex_session_config.max_sessions)
+
+    # ---- session message surface ----
+
+    def _execute_control(
+        self,
+        message: EngineQueueMessage,
+        *,
+        control_id: str,
+        operation: str,
+        session_id: str,
+        timeout: float | None,
+    ) -> DuplexControlResultMessage:
+        try:
+            result = self.rpc_client.execute(
+                ("duplex", control_id),
+                message,
+                timeout=timeout,
+                timeout_message=f"duplex {operation} timed out for session {session_id}",
+                # Block rather than surface a raw queue.Full: the handlers below
+                # promise a typed DuplexSessionError, and a momentarily full
+                # request queue is backpressure, not a failed control op.
+                block_on_submit=True,
+            )
+        except TimeoutError as exc:
+            raise DuplexSessionError(str(exc), code="timeout", retryable=True, session_id=session_id) from exc
+        except RuntimeError as exc:
+            # The RPC router is closed or the orchestrator reported a terminal error.
+            raise DuplexSessionError(str(exc), code="engine_error", session_id=session_id) from exc
+        if not isinstance(result, DuplexControlResultMessage):
+            raise DuplexSessionError(
+                f"unexpected duplex control result: {type(result).__name__}",
+                code="internal_error",
+                session_id=session_id,
+            )
+        if not result.ok:
+            raise DuplexSessionError(
+                result.error_message or f"duplex {operation} failed",
+                code=result.error_code or "internal_error",
+                retryable=result.error_retryable,
+                session_id=session_id,
+            )
+        return result
+
+    def _open_session(
+        self,
+        session_id: str,
+        session_config: DuplexSessionConfig,
+        *,
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexControlResultMessage:
+        control_id = uuid.uuid4().hex
+        return self._execute_control(
+            OpenDuplexSessionMessage(
+                control_id=control_id,
+                session_id=session_id,
+                session_config=session_config,
+            ),
+            control_id=control_id,
+            operation="open",
+            session_id=session_id,
+            timeout=timeout,
+        )
+
+    async def open_session_async(
+        self,
+        session_id: str,
+        session_config: DuplexSessionConfig,
+        *,
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexControlResultMessage:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, lambda: self._open_session(session_id, session_config, timeout=timeout))
+
+    def _close_session(
+        self,
+        session_id: str,
+        *,
+        reason: str = "client_close",
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexControlResultMessage:
+        control_id = uuid.uuid4().hex
+        return self._execute_control(
+            CloseDuplexSessionMessage(
+                control_id=control_id,
+                session_id=session_id,
+                reason=reason,
+            ),
+            control_id=control_id,
+            operation="close",
+            session_id=session_id,
+            timeout=timeout,
+        )
+
+    async def close_session_async(
+        self,
+        session_id: str,
+        *,
+        reason: str = "client_close",
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexControlResultMessage:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self._close_session(session_id, reason=reason, timeout=timeout),
+        )
+
+    def _resume_session(
+        self,
+        session_id: str,
+        *,
+        expected_lease_generation: int,
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexControlResultMessage:
+        control_id = uuid.uuid4().hex
+        return self._execute_control(
+            ResumeDuplexSessionMessage(
+                control_id=control_id,
+                session_id=session_id,
+                expected_lease_generation=expected_lease_generation,
+            ),
+            control_id=control_id,
+            operation="resume",
+            session_id=session_id,
+            timeout=timeout,
+        )
+
+    async def resume_session_async(
+        self,
+        session_id: str,
+        *,
+        expected_lease_generation: int,
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexControlResultMessage:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self._resume_session(
+                session_id,
+                expected_lease_generation=expected_lease_generation,
+                timeout=timeout,
+            ),
+        )
+
+    def _touch_session(
+        self,
+        session_id: str,
+        *,
+        activity: str,
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexControlResultMessage:
+        control_id = uuid.uuid4().hex
+        return self._execute_control(
+            TouchDuplexSessionMessage(
+                control_id=control_id,
+                session_id=session_id,
+                activity=activity,
+            ),
+            control_id=control_id,
+            operation="touch",
+            session_id=session_id,
+            timeout=timeout,
+        )
+
+    async def touch_session_async(
+        self,
+        session_id: str,
+        *,
+        activity: str,
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexControlResultMessage:
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self._touch_session(session_id, activity=activity, timeout=timeout),
+        )
+
+    def _submit_command(self, session_id: str, command: DuplexCommand) -> None:
+        """One-way: enqueue a session command in caller order (blocks only on queue backpressure)."""
+        if not self.is_alive():
+            raise DuplexSessionError("engine is not alive", code="engine_dead", session_id=session_id)
+        message = DuplexSessionCommandMessage(session_id=session_id, command=command)
+        try:
+            self.request_queue.sync_q.put(message, timeout=_COMMAND_PUT_TIMEOUT_S)
+        except queue.Full as exc:
+            raise DuplexSessionError(
+                "engine request queue is full", code="engine_backpressure", retryable=True, session_id=session_id
+            ) from exc
+
+    async def submit_command_async(self, session_id: str, command: DuplexCommand) -> None:
+        loop = asyncio.get_running_loop()
+        await loop.run_in_executor(None, lambda: self._submit_command(session_id, command))
+
+
+__all__ = ["DuplexOmniEngine"]
diff --git a/vllm_omni/engine/duplex_orchestrator.py b/vllm_omni/engine/duplex_orchestrator.py
new file mode 100644
index 00000000000..09a767fb135
--- /dev/null
+++ b/vllm_omni/engine/duplex_orchestrator.py
@@ -0,0 +1,352 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""DuplexOrchestrator: the duplex sibling of ``Orchestrator``.
+
+It hosts the ``DuplexSessionManager`` (admission, leases, session runners) on
+the orchestrator loop and implements the ``DuplexStagePort`` the runners use
+to submit resumable Stage0 requests. Generic stage forwarding, prewarm and
+cleanup stay in ``OrchestratorBase``; this class only fills the template seams
+and applies the session-owned policy.
+"""
+
+from __future__ import annotations
+
+import time as _time
+from collections.abc import Coroutine
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from vllm.logger import init_logger
+
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex.contracts import (
+    DuplexFence,
+    DuplexOutputContext,
+    DuplexRequestIdentity,
+    DuplexStagePort,
+    DuplexStageRequestContext,
+    DuplexStageSubmission,
+    DuplexStageSubmissionResult,
+)
+from vllm_omni.engine.duplex.plugin import DuplexModelPlugin
+from vllm_omni.engine.duplex.session.engine_session import DuplexFenceMismatchError
+from vllm_omni.engine.duplex.session.manager import DuplexSessionManager
+from vllm_omni.engine.messages import EngineQueueMessage, OutputMessage
+from vllm_omni.engine.orchestrator import (
+    Orchestrator,
+    OrchestratorRequestState,
+    build_engine_core_request_from_tokens,
+)
+
+if TYPE_CHECKING:
+    from vllm.config import ModelConfig
+    from vllm.outputs import RequestOutput
+
+    from vllm_omni.metrics.stats import StageRequestStats
+
+logger = init_logger(__name__)
+
+
+@dataclass
+class DuplexOrchestratorRequestState(OrchestratorRequestState):
+    """Request bookkeeping for a session-owned (resumable duplex) stage request."""
+
+    session_id: str = ""
+    fence: DuplexFence | None = None
+    stage_fences: dict[int, DuplexFence] = field(default_factory=dict)
+    config_generation: int = -1
+
+
+class DuplexOrchestrator(Orchestrator, DuplexStagePort):
+    """Stage management for a duplex deployment; owns one ``DuplexSessionManager``.
+
+    Extends the turn-based orchestrator rather than sitting beside it, so one
+    engine serves both a duplex session and an ordinary request. The
+    dependency runs duplex -> turn-based and never the reverse, which is what
+    keeps ``Orchestrator`` free of duplex code.
+    """
+
+    def __init__(
+        self,
+        # Any: ``*args`` / ``**kwargs`` are forwarded verbatim to ``OrchestratorBase.__init__``.
+        *args: Any,
+        plugin: DuplexModelPlugin,
+        duplex_session_config: DuplexSessionRuntimeConfig,
+        model_config: ModelConfig | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self.plugin = plugin
+        self.duplex_session_config = duplex_session_config
+        self.session_manager = DuplexSessionManager(
+            plugin=plugin,
+            stage_port=self,
+            output_sink=self.output_async_queue,
+            result_sink=self.rpc_async_queue,
+            runtime_config=self.duplex_session_config,
+            model_config=model_config,
+        )
+
+    # ------------------------------------------------------------------ #
+    # Template seams                                                     #
+    # ------------------------------------------------------------------ #
+
+    async def _dispatch_message(self, msg: EngineQueueMessage) -> bool:
+        if self.session_manager.accepts(msg):
+            self.session_manager.dispatch(msg)
+            return True
+        # Not a session message: it is an ordinary turn-based request.
+        return await super()._dispatch_message(msg)
+
+    # Any: ``Coroutine``'s send/yield parameters, as in the ``OrchestratorBase`` seam.
+    def _background_tasks(self) -> list[Coroutine[Any, Any, None]]:
+        return [self.session_manager.reaper_loop(self._shutdown_event)]
+
+    async def _shutdown_extensions(self) -> None:
+        await self.session_manager.shutdown()
+
+    def _on_stage_submitted(
+        self,
+        stage_id: int,
+        request_id: str,
+        replica_id: int,
+        req_state: OrchestratorRequestState,
+    ) -> None:
+        del replica_id
+        if not isinstance(req_state, DuplexOrchestratorRequestState) or req_state.fence is None:
+            return
+        runner = self.session_manager.runner_for_request_id(request_id)
+        if runner is None:
+            return
+        fence = req_state.fence
+        req_state.stage_fences[stage_id] = fence
+        try:
+            runner.session.bind_stage_request(stage_id, request_id, fence=fence)
+        except DuplexFenceMismatchError:
+            # The session already advanced past this request's epoch (cancel
+            # raced the submit); the cancel path aborts the stale request id.
+            logger.debug("[DuplexOrchestrator] stale stage binding ignored for %s stage-%s", request_id, stage_id)
+            return
+        req_state.stage_submit_ts[stage_id] = _time.time()
+        self._register_running_request(req_state)
+        self.session_manager.register_request(request_id, req_state.session_id)
+
+    async def _intercept_stage_output(
+        self,
+        stage_id: int,
+        replica_id: int,
+        output: RequestOutput,
+        req_state: OrchestratorRequestState,
+        stage_metrics: StageRequestStats | None,
+        submit_ts: float | None,
+    ) -> bool:
+        del replica_id, submit_ts
+        if not isinstance(req_state, DuplexOrchestratorRequestState) or req_state.fence is None:
+            return False
+        request_id = output.request_id
+        runner = self.session_manager.runner_for_request_id(request_id)
+        if runner is None:
+            # Session gone: nothing may forward or reach a client.
+            return True
+        segment = req_state.streaming.segment(stage_id)
+        context = DuplexOutputContext(
+            identity=DuplexRequestIdentity(
+                session_id=req_state.session_id,
+                fence=req_state.stage_fences.get(stage_id, req_state.fence),
+            ),
+            final_stage_id=req_state.final_stage_id,
+            segment_finished=req_state.streaming.enabled and segment.finished,
+            segment_token_ids=tuple(segment.token_ids),
+            segment_output_metadata=segment.output_metadata,
+        )
+        return runner.on_stage_output(
+            stage_id,
+            output,
+            stage_metrics,
+            request_id=request_id,
+            context=context,
+        )
+
+    async def _handle_forward_failure(
+        self,
+        req_id: str,
+        next_stage_id: int,
+        req_state: OrchestratorRequestState,
+        exc: BaseException,
+    ) -> bool:
+        if not req_state.session_owned:
+            return False
+        runner = self.session_manager.runner_for_request_id(req_id)
+        if runner is not None:
+            runner.on_stage_failure(next_stage_id, exc)
+        await self._cleanup_request_ids(
+            [req_id, *self._cfg_tracker.cleanup_parent(req_id)],
+            abort=True,
+            release_owners=True,
+        )
+        return True
+
+    async def _cleanup_request_ids(
+        self,
+        request_ids: list[str],
+        *,
+        abort: bool = False,
+        release_owners: bool = False,
+    ) -> list[OutputMessage]:
+        if not request_ids:
+            return []
+        cleanup_ids = list(dict.fromkeys(request_ids))
+        closing_session_ids: list[str] = []
+        if release_owners:
+            closed_sessions = self.session_manager.close_sessions_for_request_ids(
+                cleanup_ids,
+                abort=abort,
+                cleanup_in_progress=True,
+            )
+            closing_session_ids.extend(closed_sessions)
+            for session_id, stale_request_ids in closed_sessions.items():
+                logger.info(
+                    "[DuplexOrchestrator] closed duplex session %s while cleaning failed request ids %s",
+                    session_id,
+                    stale_request_ids,
+                )
+                cleanup_ids.extend(stale_request_ids)
+            cleanup_ids = list(dict.fromkeys(cleanup_ids))
+        try:
+            outputs = await super()._cleanup_request_ids(cleanup_ids, abort=abort)
+        except BaseException:
+            if closing_session_ids:
+                self.session_manager.defer_request_cleanups(closing_session_ids)
+            raise
+        if closing_session_ids:
+            self.session_manager.finalize_closed_sessions(closing_session_ids)
+        for request_id in cleanup_ids:
+            self.session_manager.unregister_request(request_id)
+        return outputs
+
+    # ------------------------------------------------------------------ #
+    # DuplexStagePort                                                    #
+    # ------------------------------------------------------------------ #
+
+    @property
+    def stage_count(self) -> int:
+        return len(self.stage_pools)
+
+    def sampling_defaults(self) -> tuple[object, ...]:
+        defaults = []
+        for pool in self.stage_pools:
+            client = pool.stage_client
+            if client is None:
+                # Every replica of this stage was evicted (engine core died); a
+                # session cannot be admitted until the deployment is restarted.
+                raise RuntimeError(f"stage {pool.stage_id} has no live replica")
+            defaults.append(client.default_sampling_params)
+        return tuple(defaults)
+
+    @staticmethod
+    def _sync_bridge_state(
+        request_state: OrchestratorRequestState,
+        context: DuplexStageRequestContext,
+    ) -> None:
+        duplex_state = request_state.streaming.bridge_states.setdefault("duplex", {})
+        if not isinstance(duplex_state, dict):
+            duplex_state = {}
+            request_state.streaming.bridge_states["duplex"] = duplex_state
+        previous_epoch = duplex_state.get("epoch")
+        current_model_turn_id = duplex_state.get("model_turn_id")
+        if (
+            not isinstance(current_model_turn_id, int)
+            or previous_epoch != context.fence.epoch
+            or current_model_turn_id < context.fence.turn_id
+        ):
+            # A safety boundary can close a response before the model emits
+            # its normal turn_eos. Catch up the engine-owned identity when the
+            # next fenced append starts.
+            duplex_state["model_turn_id"] = context.fence.turn_id
+        duplex_state.update(
+            {
+                "session_id": context.session_id,
+                "fence": context.fence,
+                "epoch": context.fence.epoch,
+                "turn_id": context.fence.turn_id,
+                "session_config": dict(context.session_config),
+                "runtime_config": dict(context.runtime_config),
+            }
+        )
+
+    def ensure_request(self, context: DuplexStageRequestContext) -> None:
+        request_state = self.request_states.get(context.request_id)
+        if request_state is None:
+            request_state = DuplexOrchestratorRequestState(
+                request_id=context.request_id,
+                prompt=None,
+                sampling_params_list=list(context.sampling_params),
+                final_stage_id=context.final_stage_id,
+                session_owned=True,
+                session_id=context.session_id,
+                fence=context.fence,
+                config_generation=context.config_generation,
+            )
+            request_state.streaming.enabled = True
+            self.request_states[context.request_id] = request_state
+        elif isinstance(request_state, DuplexOrchestratorRequestState):
+            if request_state.config_generation != context.config_generation:
+                request_state.sampling_params_list = list(context.sampling_params)
+                request_state.config_generation = context.config_generation
+            request_state.session_id = context.session_id
+            request_state.fence = context.fence
+        else:
+            raise RuntimeError(f"request {context.request_id} is not session-owned")
+        self._sync_bridge_state(request_state, context)
+        self.session_manager.register_request(context.request_id, context.session_id)
+
+    async def submit(self, submission: DuplexStageSubmission) -> DuplexStageSubmissionResult:
+        context = submission.context
+        request_state = self.request_states.get(context.request_id)
+        if not isinstance(request_state, DuplexOrchestratorRequestState):
+            raise RuntimeError(f"duplex request was not preregistered: {context.request_id}")
+        request = build_engine_core_request_from_tokens(
+            request_id=context.request_id,
+            prompt=dict(submission.prompt),
+            params=context.stage_sampling_params,
+            model_config=self.stage_pools[context.stage_id].stage_vllm_config.model_config,
+            resumable=True,
+        )
+        request.external_req_id = request.request_id
+        pool = self.stage_pools[context.stage_id]
+        if submission.already_submitted:
+            replica_id = await pool.submit_update(context.request_id, request_state, request)
+        else:
+            replica_id = await pool.submit_initial(context.request_id, request_state, request, prompt_text=None)
+            if self.async_chunk and context.stage_id == 0:
+                prewarmed = await self._prewarm_async_chunk_stages(
+                    context.request_id,
+                    request,
+                    request_state,
+                )
+                if not prewarmed:
+                    # The prewarm already failed the request, aborted it and
+                    # popped its state; the runner turns this into an append
+                    # error instead of writing onto an orphaned object.
+                    raise RuntimeError(
+                        f"async-chunk prewarm failed for duplex request {context.request_id}; the request was aborted"
+                    )
+        request_state.stage_fences[context.stage_id] = context.fence
+        request_state.stage_submit_ts[context.stage_id] = _time.time()
+        self._register_running_request(request_state)
+        return DuplexStageSubmissionResult(
+            request_id=context.request_id,
+            stage_id=context.stage_id,
+            replica_id=replica_id,
+        )
+
+    async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
+        await self._cleanup_request_ids(request_ids, abort=abort)
+
+    async def abort_requests(self, request_ids: list[str]) -> None:
+        if request_ids:
+            await self._abort_request_ids(list(dict.fromkeys(request_ids)))
+
+
+__all__ = ["DuplexOrchestrator", "DuplexOrchestratorRequestState"]
diff --git a/vllm_omni/engine/omni_engine_base.py b/vllm_omni/engine/omni_engine_base.py
new file mode 100644
index 00000000000..87ef8d5e6e6
--- /dev/null
+++ b/vllm_omni/engine/omni_engine_base.py
@@ -0,0 +1,1229 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""OmniEngineBase: process/thread ownership and transport shared by every Omni engine."""
+
+from __future__ import annotations
+
+import asyncio
+import concurrent.futures
+import json
+import queue
+import threading
+import time
+import uuid
+import weakref
+from collections.abc import Mapping
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any, cast
+
+import janus
+import torch
+from vllm import envs as vllm_envs
+from vllm.logger import init_logger
+from vllm.v1.engine.input_processor import InputProcessor
+
+from vllm_omni.config.config_factory import StageConfigFactory, with_trust_remote_code_override
+from vllm_omni.config.resolver import OmniConfigResolution, resolve_omni_config
+from vllm_omni.config.stage_config import (
+    _DEPLOY_DIR,
+    DuplexSessionRuntimeConfig,
+    PipelineConfig,
+    load_deploy_config,
+)
+from vllm_omni.diffusion.data import (
+    DiffusionParallelConfig,
+    parse_attention_config,
+)
+from vllm_omni.diffusion.io_support import get_diffusion_output_type
+from vllm_omni.engine.async_engine_utils import (
+    SHUTDOWN_ENQUEUE_TIMEOUT_S,
+    SHUTDOWN_JOIN_TIMEOUT_S,
+    enqueue_orchestrator_shutdown,
+    is_abort_transport_shutdown,
+    is_janus_sync_queue_shutdown,
+    shutdown_runtime_after_orchestrator,
+    weak_shutdown_async_omni_engine,
+)
+from vllm_omni.engine.messages import (
+    AbortRequestMessage,
+    AbortResultMessage,
+    CollectiveRPCRequestMessage,
+    CollectiveRPCResultMessage,
+    EngineQueueMessage,
+    ErrorMessage,
+    OutputMessage,
+)
+from vllm_omni.engine.orchestrator import OrchestratorBase
+from vllm_omni.engine.rpc_result_router import CorrelatedRpcClient
+from vllm_omni.engine.stage_client import StageClient
+from vllm_omni.engine.stage_init_utils import build_stage0_input_processor
+from vllm_omni.engine.stage_pool import StagePool
+from vllm_omni.engine.stage_runtime import (
+    StageRuntimeInfo,
+    create_stage_runtime,
+)
+from vllm_omni.entrypoints.pd_utils import PDDisaggregationMixin
+from vllm_omni.entrypoints.utils import parse_stage_overrides
+from vllm_omni.inputs.data import OmniSamplingParams
+from vllm_omni.metrics.prometheus import OmniRequestCounter
+
+logger = init_logger(__name__)
+
+_STARTUP_POLL_INTERVAL_S = 1.0
+_REQUEST_QUEUE_MAXSIZE = 256
+_ConfigResolutionResult = OmniConfigResolution | tuple[str | None, list[Any], str | None]
+
+
+def load_and_resolve_stage_configs(
+    model: str,
+    kwargs: dict[str, Any],
+    *,
+    trust_remote_code: bool | None,
+    deploy_config_path: str | None,
+    stage_overrides: Mapping[str, Mapping[str, Any]] | None,
+    strategy_config_path: str | None,
+) -> OmniConfigResolution:
+    """Compatibility seam delegating to the single config resolver."""
+    return resolve_omni_config(
+        model,
+        trust_remote_code=trust_remote_code,
+        cli_overrides=kwargs,
+        deploy_config_path=deploy_config_path,
+        stage_overrides=stage_overrides,
+        strategy_config_path=strategy_config_path,
+    )
+
+
+class OmniEngineBase:
+    """Generic engine: launches an orchestrator in a background thread.
+
+    Shared by ``AsyncOmniEngine`` (turn-based requests) and ``DuplexOmniEngine``
+    (duplex sessions). Subclasses construct their orchestrator in
+    ``_create_orchestrator``.
+
+    All stage clients, input/output processors, and stage-to-stage transfer
+    logic live inside the Orchestrator coroutine (running in its own thread
+    with a dedicated asyncio event loop). This class communicates with it
+    via janus queues (sync side for callers, async side for orchestrator).
+
+    Args:
+        model: Model name or path
+        init_timeout: Total timeout waiting for orchestrator startup (seconds).
+        stage_init_timeout: Timeout for stage initialization (seconds)
+        **kwargs: Additional arguments
+    """
+
+    # Class-level defaults so tests that bypass __init__ via object.__new__
+    # don't AttributeError when stage-init / forward paths touch these attrs.
+    _log_stats: bool = False
+    _coordinator_runtime: Any = None
+    _transfer_emitter: Any = None
+    _prom_metrics: Any = None
+    _enable_orch_monitor: bool = False
+    # Lazily created by get_output_blocking_async().
+    _output_drain_executor: concurrent.futures.ThreadPoolExecutor | None = None
+
+    def __init__(
+        self,
+        model: str,
+        stage_init_timeout: int = 300,
+        init_timeout: int = 600,
+        single_stage_mode: bool = False,
+        transfer_emitter: Any = None,
+        prom_metrics: Any = None,
+        log_stats: bool = False,
+        tokenizer: str | None = None,
+        trust_remote_code: bool | None = None,
+        **kwargs: Any,
+    ) -> None:
+        self.model = model
+        self.tokenizer = tokenizer
+        # Cached by get_diffusion_od_config().
+        self._diffusion_od_config_view: Any = None
+        startup_timeout = int(init_timeout)
+        # Forwarded into Orchestrator so its _forward_to_next_stage path can
+        # emit per-edge transfer_tx_s / transfer_size_bytes histograms.
+        # Optional: when None, Orchestrator silently skips TX emit (existing
+        # RX path still works via OrchestratorAggregator).
+        self._transfer_emitter = transfer_emitter
+        self._prom_metrics = prom_metrics
+        # Drives upstream EngineCore + scheduler stats production. When False
+        # the engine skips SchedulerStats / IterationStats; the per-(stage,
+        # replica) vllm:* wrap stays registered but reads zero. Respects the
+        # --log-stats CLI flag set by the user via OmniBase.
+        self._log_stats = log_stats
+        self._enable_orch_monitor = bool(kwargs.pop("enable_orch_monitor", False))
+
+        logger.info(f"[OmniEngine] Initializing with model {model}")
+
+        # ------------------------------------------------------------------ #
+        # Single-stage mode detection                                        #
+        # ------------------------------------------------------------------ #
+        # Single-stage mode is enabled when the caller explicitly passes      #
+        # single_stage_mode=True, or when a stage_id is provided in the args. #
+        _stage_id_kwarg = kwargs.get("stage_id")
+        if isinstance(_stage_id_kwarg, int) and not single_stage_mode:
+            single_stage_mode = True
+
+        self.single_stage_mode: bool = single_stage_mode
+        self._single_stage_id_filter: int | None = (
+            int(_stage_id_kwarg) if single_stage_mode and isinstance(_stage_id_kwarg, int) else None
+        )
+        self._omni_master_address: str | None = kwargs.get("omni_master_address")
+        self._omni_master_port: int | None = kwargs.get("omni_master_port")
+
+        # New omni-coordinator flags. Consumed only in single_stage_mode.
+        # ``omni_dp_size_local`` is process-local: each invocation (head and
+        # every headless) launches that many replicas for its own stage.
+        self._omni_dp_size_local: int = int(kwargs.get("omni_dp_size_local") or 1)
+        if self._omni_dp_size_local < 1:
+            raise ValueError(f"--omni-dp-size-local must be >= 1, got {self._omni_dp_size_local}")
+        self._omni_lb_policy: str = str(kwargs.get("omni_lb_policy") or "random")
+        self._omni_heartbeat_timeout: float = float(kwargs.get("omni_heartbeat_timeout") or 30.0)
+        if self._omni_heartbeat_timeout <= 0:
+            raise ValueError(f"--omni-heartbeat-timeout must be > 0, got {self._omni_heartbeat_timeout}")
+        # Concurrent same-device stage init (admission + SH/EX phase locks).
+        # Sourced from the parallel_stage_init orchestrator/CLI arg (config,
+        # not an env var); default False preserves serial init.
+        self._parallel_stage_init: bool = bool(kwargs.get("parallel_stage_init") or False)
+
+        if single_stage_mode:
+            logger.info(
+                "[OmniEngine] Single-stage mode enabled (stage_id_filter=%s, master=%s:%s)",
+                self._single_stage_id_filter,
+                self._omni_master_address,
+                self._omni_master_port,
+            )
+
+        # Keep the historical tuple return from _resolve_stage_configs while
+        # retaining the richer resolver result for pipeline-wide settings.
+        # Overrides of that private seam fall back to the factory below.
+        deploy_config_path = kwargs.get("deploy_config")
+        # ``trust_remote_code`` is tri-state (bool | None): ``None`` means "not
+        # specified" so stage-config resolution can defer to the deploy yaml's
+        # per-stage value (see ``with_trust_remote_code_override``). The
+        # restriction path below loads the top-level HF config via vLLM's
+        # ``get_config``, which needs a real bool, so collapse ``None`` to the
+        # default ``False`` here (#5495).
+        pipeline_config = StageConfigFactory.get_pipeline_config(
+            model=model,
+            trust_remote_code=bool(trust_remote_code),
+            deploy_config_path=deploy_config_path,
+        )
+        self.pipeline_config = pipeline_config
+        self.endpoint_restrictions = pipeline_config.endpoint_restrictions if pipeline_config is not None else ()
+        # The resolved deploy profile (explicit --deploy-config or the pipeline
+        # default). Duplex engines read ``deploy_config.duplex_session`` and
+        # ``session_mode`` from it; the turn-based engine only keeps it for
+        # introspection.
+        self.deploy_config = None
+        #: Path ``self.deploy_config`` was parsed from, so the duplex runtime
+        #: config below can reuse it instead of re-reading the same yaml.
+        self._deploy_config_source: str | None = None
+        deploy_config_source: str | Path | None = deploy_config_path
+        if deploy_config_source is None and pipeline_config is not None:
+            default_name = getattr(pipeline_config, "default_deploy_config_name", None)
+            if default_name:
+                deploy_config_source = _DEPLOY_DIR / default_name
+        elif isinstance(deploy_config_source, str) and not Path(deploy_config_source).exists():
+            candidate = _DEPLOY_DIR / deploy_config_source
+            if candidate.exists():
+                deploy_config_source = candidate
+        if deploy_config_source is not None:
+            try:
+                self.deploy_config = load_deploy_config(deploy_config_source)
+                self._deploy_config_source = str(deploy_config_source)
+            except Exception:
+                if deploy_config_path is not None:
+                    # The caller named this file: failing to load it is their error.
+                    raise
+                logger.warning(
+                    "[OmniEngine] Could not load the pipeline's default deploy config %s",
+                    deploy_config_source,
+                    exc_info=True,
+                )
+
+        # Subclasses check deployment invariants here, before any stage
+        # process is launched (a failure is cheap at this point).
+        self._validate_deployment()
+
+        # Tri-state: None means "not specified" — the deploy yaml's per-stage
+        # trust_remote_code stays in effect. An explicit True/False here is a
+        # global override (precedence: caller > deploy yaml > default False);
+        # the merge rule lives in with_trust_remote_code_override.
+        kwargs = with_trust_remote_code_override(kwargs, trust_remote_code)
+        self._config_resolution: OmniConfigResolution | None = None
+        self.config_path, self.stage_configs = self._resolve_stage_configs(
+            model,
+            kwargs,
+            trust_remote_code=trust_remote_code,
+        )
+        if self._config_resolution is None:
+            # Same model, trust_remote_code and deploy path as the resolution
+            # above, so reuse it rather than paying for the HF config again.
+            self._set_pipeline_runtime_config(self.pipeline_config, self.config_path)
+        else:
+            self._set_pipeline_runtime_config(
+                self._config_resolution.pipeline_config,
+                self._config_resolution.config_path,
+            )
+
+        self.num_stages = len(self.stage_configs)
+        stage0_args = getattr(self.stage_configs[0], "engine_args", None) if self.num_stages > 0 else None
+        self.async_chunk = bool(getattr(stage0_args, "async_chunk", False))
+        self.stage_pools: list[StagePool] = []
+        self.stage_clients: list[StageClient] = []  # logical-stage view for external readers
+        self.input_processor: InputProcessor | None = None
+        self.prompt_transform_func: Any | None = None
+        self.prompt_expand_func: Any | None = None
+        self.supported_tasks: tuple[str, ...] = ("generate",)
+        self.default_sampling_params_list: list[OmniSamplingParams] = []
+        self.stage_metadata: list[StageRuntimeInfo] = []
+        # Janus queues are constructed eagerly here (not deferred to the
+        # orchestrator thread) so the master server's ROUTER thread always
+        # sees a non-None ``self.request_queue`` when on_register fires.
+        # ``async_q`` lazily binds to whatever event loop first awaits on
+        # it (the orchestrator loop), so cross-thread use stays correct.
+        self.request_queue: janus.Queue[EngineQueueMessage] = janus.Queue(maxsize=_REQUEST_QUEUE_MAXSIZE)
+        self.output_queue: janus.Queue[EngineQueueMessage] = janus.Queue()
+        self.rpc_output_queue: janus.Queue[EngineQueueMessage] = janus.Queue()
+        self._shutdown_called = False
+        self._weak_finalizer: weakref.finalize | None = None
+        self._correlated_rpc_client: CorrelatedRpcClient | None = None
+        self._running_counter = OmniRequestCounter()
+        self._engines_waiting_counter = OmniRequestCounter()
+
+        logger.info(f"[OmniEngine] Launching Orchestrator thread with {self.num_stages} stages")
+
+        # Launch orchestrator background thread
+        startup_future: concurrent.futures.Future = concurrent.futures.Future()
+
+        self.orchestrator_thread = threading.Thread(
+            target=self._bootstrap_orchestrator,
+            args=(
+                stage_init_timeout,
+                startup_future,
+            ),
+            daemon=True,
+            name="orchestrator",
+        )
+        self.orchestrator_thread.start()
+        self._wait_for_orchestrator_init(startup_future, startup_timeout)
+        self._correlated_rpc_client = CorrelatedRpcClient(
+            self.request_queue.sync_q,
+            self.rpc_output_queue.sync_q,
+        )
+
+        # Stage runtime fields are assigned directly on self by the bootstrap thread.
+        self._weak_finalizer = weakref.finalize(
+            self,
+            weak_shutdown_async_omni_engine,
+            self.orchestrator_thread,
+            self.request_queue,
+            self.output_queue,
+            self.rpc_output_queue,
+            self._correlated_rpc_client,
+        )
+
+        logger.info(f"[OmniEngine] Orchestrator ready with {self.num_stages} stages")
+
+    def get_diffusion_od_config(self) -> Any:
+        """Expose the diffusion ``model_class_name`` to client-side model-extras.
+
+        The worker holds the full config; here we just resolve the pipeline class
+        name from the model config (cached). ``model_class_name`` may be ``None``.
+        """
+        if self._diffusion_od_config_view is None:
+            from types import SimpleNamespace
+
+            from vllm_omni.diffusion.data import resolve_model_class_name
+            from vllm_omni.diffusion.model_metadata import get_diffusion_model_metadata
+
+            model_class_name = resolve_model_class_name(self.model)
+            metadata = get_diffusion_model_metadata(model_class_name)
+            self._diffusion_od_config_view = SimpleNamespace(
+                model_class_name=model_class_name,
+                supports_multimodal_inputs=metadata.supports_multimodal_inputs,
+                max_multimodal_image_inputs=metadata.max_multimodal_image_inputs,
+                supports_mixed_reference_inputs=metadata.supports_mixed_reference_inputs,
+            )
+        return self._diffusion_od_config_view
+
+    def _initialize_stages(self, stage_init_timeout: int) -> None:
+        """Initialize stage clients/processors via StageRuntime and assign to self."""
+        self._runtime = create_stage_runtime(
+            stage_configs=self.stage_configs,
+            model=self.model,
+            config_path=self.config_path,
+            single_stage_mode=self.single_stage_mode,
+            stage_init_timeout=stage_init_timeout,
+            async_chunk=self.async_chunk,
+            tokenizer=self.tokenizer,
+            parallel_stage_init=self._parallel_stage_init,
+            single_stage_id_filter=self._single_stage_id_filter,
+            omni_master_address=self._omni_master_address,
+            omni_master_port=self._omni_master_port,
+            omni_dp_size_local=self._omni_dp_size_local,
+            omni_heartbeat_timeout=self._omni_heartbeat_timeout,
+            omni_lb_policy=self._omni_lb_policy,
+            request_queue=self.request_queue,
+            log_stats=self._log_stats,
+        )
+        self._runtime.initialize()
+
+        self.num_stages = len(self.stage_configs)
+        self.stage_pools = self._runtime.stage_pools
+        self.stage_clients = [
+            cast(StageClient, pool.stage_client) for pool in self.stage_pools if pool.stage_client is not None
+        ]
+        self.stage_vllm_configs = [pool.stage_vllm_config for pool in self.stage_pools]
+        self.output_processors = [pool.output_processor for pool in self.stage_pools]
+        self.input_processor = (
+            build_stage0_input_processor(self.stage_vllm_configs[0])
+            if self.stage_vllm_configs and self.stage_vllm_configs[0] is not None
+            else None
+        )
+        self.prompt_transform_func = (
+            getattr(self.stage_clients[0], "prompt_transform_func", None) if self.stage_clients else None
+        )
+        self.prompt_expand_func = next(
+            (
+                getattr(client, "prompt_expand_func", None)
+                for client in self.stage_clients
+                if getattr(client, "prompt_expand_func", None) is not None
+            ),
+            None,
+        )
+        self.default_sampling_params_list = [client.default_sampling_params for client in self.stage_clients]
+        self.stage_metadata = [
+            StageRuntimeInfo(
+                final_output=client.final_output,
+                final_output_type=client.final_output_type,
+                stage_type=client.stage_type,
+                model_stage=getattr(client, "model_stage", None),
+            )
+            for client in self.stage_clients
+        ]
+        supported_tasks: set[str] = set()
+        if any(getattr(client, "is_comprehension", False) for client in self.stage_clients):
+            supported_tasks.add("generate")
+        if any(meta.final_output_type == "audio" for meta in self.stage_metadata):
+            supported_tasks.add("speech")
+        self.supported_tasks = tuple(supported_tasks) if supported_tasks else ("generate",)
+
+    def _bootstrap_orchestrator(
+        self,
+        stage_init_timeout: int,
+        startup_future: concurrent.futures.Future,
+    ) -> None:
+        """Create loop, initialize stages, then run Orchestrator."""
+
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+
+        async def _run_orchestrator() -> None:
+            self._initialize_stages(stage_init_timeout)
+
+            pd_config = self._detect_pd_config()
+
+            membership_controller = self._runtime.create_membership_controller()
+
+            orchestrator = self._create_orchestrator(
+                request_async_queue=self.request_queue.async_q,
+                output_async_queue=self.output_queue.async_q,
+                rpc_async_queue=self.rpc_output_queue.async_q,
+                stage_pools=self.stage_pools,
+                async_chunk=self.async_chunk,
+                pd_config=pd_config,
+                membership_controller=membership_controller,
+                running_counter=self._running_counter,
+                engines_waiting_counter=self._engines_waiting_counter,
+                transfer_emitter=self._transfer_emitter,
+                prom_metrics=self._prom_metrics,
+                log_stats=self._log_stats,
+                enable_orch_monitor=self._enable_orch_monitor,
+            )
+            if not startup_future.done():
+                startup_future.set_result(asyncio.get_running_loop())
+            await orchestrator.run()
+
+        try:
+            loop.run_until_complete(_run_orchestrator())
+        except Exception as e:
+            if not startup_future.done():
+                wrapped = RuntimeError(f"Orchestrator initialization failed: {e}")
+                wrapped.__cause__ = e
+                startup_future.set_exception(wrapped)
+            logger.exception("[OmniEngine] Orchestrator thread crashed")
+            error_text = str(e) or "Orchestrator thread crashed"
+            try:
+                error_msg = ErrorMessage(error=error_text, fatal=True)
+                if self.output_queue is not None:
+                    self.output_queue.sync_q.put_nowait(error_msg)
+                if self.rpc_output_queue is not None:
+                    self.rpc_output_queue.sync_q.put_nowait(error_msg)
+            except Exception:
+                pass
+            raise
+        finally:
+            try:
+                pending = [task for task in asyncio.all_tasks(loop) if not task.done()]
+                for task in pending:
+                    task.cancel()
+                if pending:
+                    loop.run_until_complete(asyncio.gather(*pending, return_exceptions=True))
+                loop.run_until_complete(loop.shutdown_asyncgens())
+                if hasattr(loop, "shutdown_default_executor"):
+                    loop.run_until_complete(loop.shutdown_default_executor())
+            except Exception:
+                logger.exception("[OmniEngine] Failed during orchestrator loop cleanup")
+            finally:
+                asyncio.set_event_loop(None)
+                loop.close()
+
+    def _validate_deployment(self) -> None:
+        """Seam: check ``pipeline_config`` / ``deploy_config`` before stages start (default: nothing)."""
+
+    def _create_orchestrator(self, **orchestrator_kwargs: Any) -> OrchestratorBase:
+        """Construct this engine's orchestrator (runs on the orchestrator thread after stage init)."""
+        raise NotImplementedError
+
+    def _wait_for_orchestrator_init(self, startup_future: concurrent.futures.Future, startup_timeout: int) -> None:
+        """
+        Wait for orchestrator startup future to return ready. Raises exception on any failures to the init process.
+        """
+        deadline = time.monotonic() + startup_timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                logger.warning(
+                    "[OmniEngine] Orchestrator startup timed out after %ss. "
+                    "Multi-stage deployments that initialize stages sequentially on one device "
+                    "or load checkpoints from slow storage may need larger --init-timeout and "
+                    "--stage-init-timeout values.",
+                    startup_timeout,
+                )
+                self._try_shutdown("[OmniEngine] Failed to cleanup after orchestrator startup timeout")
+                raise TimeoutError(f"Orchestrator did not become ready within {startup_timeout}s")
+            try:
+                startup_future.result(
+                    timeout=min(remaining, _STARTUP_POLL_INTERVAL_S),
+                )
+                break
+            except concurrent.futures.TimeoutError:
+                if not self.orchestrator_thread.is_alive():
+                    self._try_shutdown("[OmniEngine] Failed to cleanup after orchestrator startup failure")
+                    if startup_future.done():
+                        startup_future.result()  # re-raises the real exception
+                    raise RuntimeError("Orchestrator thread died during startup")
+            except Exception:
+                self._try_shutdown("[OmniEngine] Failed to cleanup after orchestrator startup failure")
+                raise
+
+    @staticmethod
+    def _get_default_cache_config(cache_backend: str | None) -> dict[str, Any] | None:
+        if cache_backend == "cache_dit":
+            return {
+                "Fn_compute_blocks": 1,
+                "Bn_compute_blocks": 0,
+                "max_warmup_steps": 4,
+                "residual_diff_threshold": 0.24,
+                "max_continuous_cached_steps": 3,
+                "enable_taylorseer": False,
+                "taylorseer_order": 1,
+                "scm_steps_mask_policy": None,
+                "scm_steps_policy": "dynamic",
+            }
+        if cache_backend == "tea_cache":
+            return {
+                "rel_l1_thresh": 0.2,
+            }
+        if cache_backend == "mag_cache":
+            return {
+                "mag_threshold": 0.24,
+                "mag_max_skip_steps": 5,
+                "mag_retention_ratio": 0.1,
+            }
+        if cache_backend == "step_cache":
+            return {
+                "step_cache_dit_enabled": True,
+                "velocity_sim_thresholds": [0.95, 0.93],
+                "velocity_skip_countdowns": [4, 2],
+                "step_cache_dit_min_history": 2,
+                "step_cache_dit_max_history": 2,
+            }
+        return None
+
+    @staticmethod
+    def _normalize_cache_config(cache_backend: str | None, cache_config: Any | None) -> Any | None:
+        if isinstance(cache_config, str):
+            try:
+                cache_config = json.loads(cache_config)
+            except json.JSONDecodeError:
+                logger.warning("Invalid cache_config JSON, using defaults.")
+                cache_config = None
+        if cache_config is None and cache_backend not in (None, "", "none"):
+            cache_config = OmniEngineBase._get_default_cache_config(cache_backend)
+        return cache_config
+
+    def _detect_pd_config(self) -> dict[str, Any] | None:
+        """Detect PD (Prefill-Decode) disaggregation config from stage_configs.
+        Returns a dict with 'pd_pair' and 'bootstrap_addr', or None.
+        """
+        pd_pair = PDDisaggregationMixin.detect_pd_separation_from_stage_configs(self.stage_configs)
+        if pd_pair is None:
+            return None
+        prefill_idx, decode_idx = pd_pair
+
+        # Extract bootstrap address from prefill stage engine_args
+        bootstrap_addr: str | None = None
+        try:
+            prefill_cfg = self.stage_configs[prefill_idx]
+            ea = getattr(prefill_cfg, "engine_args", None)
+            kv_cfg = getattr(ea, "kv_transfer_config", None) if ea is not None else None
+            if kv_cfg is not None:
+                port = vllm_envs.VLLM_MOONCAKE_BOOTSTRAP_PORT
+                kv_ip = getattr(kv_cfg, "kv_ip", None) or "127.0.0.1"
+                bootstrap_addr = f"http://{kv_ip}:{port}"
+        except Exception as exc:
+            logger.warning("[OmniEngine] Could not extract PD bootstrap address: %s", exc)
+
+        logger.info(
+            "[OmniEngine] PD disaggregation detected: prefill=stage-%d, decode=stage-%d, bootstrap=%s",
+            prefill_idx,
+            decode_idx,
+            bootstrap_addr,
+        )
+        prefill_engine_id: str | None = None
+        try:
+            prefill_client = self.stage_clients[prefill_idx]
+            kv_cfg = getattr(getattr(prefill_client, "vllm_config", None), "kv_transfer_config", None)
+            prefill_engine_id = getattr(kv_cfg, "engine_id", None)
+        except Exception as exc:
+            logger.warning("[OmniEngine] Could not extract prefill engine_id: %s", exc)
+
+        return {
+            "pd_pair": (prefill_idx, decode_idx),
+            "bootstrap_addr": bootstrap_addr,
+            "prefill_engine_id": prefill_engine_id,
+        }
+
+    @staticmethod
+    def _create_default_diffusion_stage_cfg(kwargs: dict[str, Any]) -> list:
+        """Create a default single-stage diffusion config from kwargs."""
+        # We temporally create a default config for diffusion stage.
+        # In the future, we should merge the default config with the user-provided config.
+        normalized_kwargs = dict(kwargs)
+        default_sampling_params = normalized_kwargs.get("default_sampling_params")
+        if isinstance(default_sampling_params, str):
+            try:
+                default_sampling_params = json.loads(default_sampling_params)
+            except json.JSONDecodeError:
+                logger.warning("Invalid default_sampling_params JSON, ignoring stage defaults.")
+                default_sampling_params = None
+        if not isinstance(default_sampling_params, dict):
+            default_sampling_params = None
+        stage_default_sampling_params = default_sampling_params.get("0", {}) if default_sampling_params else {}
+        if normalized_kwargs.get("dtype") is None:
+            normalized_kwargs["dtype"] = "auto"
+
+        # TODO: hack, convert dtype to string to avoid non-premitive omegaconf create error.
+        if "dtype" in normalized_kwargs and not isinstance(normalized_kwargs["dtype"], str):
+            if not isinstance(normalized_kwargs["dtype"], torch.dtype):
+                raise TypeError(
+                    f"Provided dtype must be a string or torch.dtype, got {type(normalized_kwargs['dtype']).__name__}"
+                )
+            normalized_kwargs["dtype"] = str(normalized_kwargs["dtype"]).removeprefix("torch.")
+
+        cache_backend = normalized_kwargs.get("cache_backend", "none")
+        cache_config = OmniEngineBase._normalize_cache_config(
+            cache_backend,
+            normalized_kwargs.get("cache_config", None),
+        )
+
+        parallel_config = normalized_kwargs.get("parallel_config")
+        if isinstance(parallel_config, dict):
+            parallel_config = DiffusionParallelConfig.from_dict(parallel_config)
+        if parallel_config is None:
+            ulysses_degree = normalized_kwargs.get("ulysses_degree") or 1
+            ring_degree = normalized_kwargs.get("ring_degree") or 1
+            allgather_degree = normalized_kwargs.get("allgather_degree") or 1
+            ulysses_mode = normalized_kwargs.get("ulysses_mode") or "strict"
+            ulysses_a2a_permute = bool(normalized_kwargs.get("ulysses_a2a_permute", False))
+            sequence_parallel_size = normalized_kwargs.get("sequence_parallel_size")
+            pipeline_parallel_size = normalized_kwargs.get("pipeline_parallel_size") or 1
+            data_parallel_size = normalized_kwargs.get("data_parallel_size")
+            tensor_parallel_size = normalized_kwargs.get("tensor_parallel_size") or 1
+            cfg_parallel_size = normalized_kwargs.get("cfg_parallel_size") or 1
+            pipeline_parallel_size = normalized_kwargs.get("pipeline_parallel_size") or 1
+            vae_patch_parallel_size = normalized_kwargs.get("vae_patch_parallel_size") or 1
+            vae_parallel_mode = normalized_kwargs.get("vae_parallel_mode") or "tile"
+            text_encoder_tp_size = normalized_kwargs.get("text_encoder_tp_size") or 1
+            enable_expert_parallel = normalized_kwargs.get("enable_expert_parallel") or False
+            use_hsdp = normalized_kwargs.get("use_hsdp", False)
+            hsdp_shard_size = normalized_kwargs.get("hsdp_shard_size", -1)
+            hsdp_replicate_size = normalized_kwargs.get("hsdp_replicate_size", 1)
+            if sequence_parallel_size is None:
+                sequence_parallel_size = allgather_degree if allgather_degree > 1 else ulysses_degree * ring_degree
+
+            parallel_config = DiffusionParallelConfig(
+                pipeline_parallel_size=pipeline_parallel_size,
+                data_parallel_size=data_parallel_size,
+                tensor_parallel_size=tensor_parallel_size,
+                enable_expert_parallel=enable_expert_parallel,
+                sequence_parallel_size=sequence_parallel_size,
+                ulysses_degree=ulysses_degree,
+                ring_degree=ring_degree,
+                allgather_degree=allgather_degree,
+                ulysses_mode=ulysses_mode,
+                ulysses_a2a_permute=ulysses_a2a_permute,
+                cfg_parallel_size=cfg_parallel_size,
+                vae_patch_parallel_size=vae_patch_parallel_size,
+                vae_parallel_mode=vae_parallel_mode,
+                text_encoder_tp_size=text_encoder_tp_size,
+                use_hsdp=use_hsdp,
+                hsdp_shard_size=hsdp_shard_size,
+                hsdp_replicate_size=hsdp_replicate_size,
+            )
+
+        num_gpus = normalized_kwargs.get("num_gpus")
+        if num_gpus is not None:
+            num_gpus = int(num_gpus)
+            parallel_config.resolve_data_parallel_size(num_gpus)
+
+        num_devices = max(1, int(parallel_config.world_size))
+        devices = ",".join(str(i) for i in range(num_devices))
+        model_class_name = kwargs.get("model_class_name", None)
+        final_output_type = get_diffusion_output_type(model_class_name)
+
+        attention_config = None
+        if (
+            kwargs.get("diffusion_attention_config") is not None
+            or kwargs.get("diffusion_attention_backend") is not None
+            or kwargs.get("fastvideo_vsa_topk") is not None
+        ):
+            attention_config = parse_attention_config(
+                kwargs.get("diffusion_attention_config"),
+                attention_backend=kwargs.get("diffusion_attention_backend"),
+                fastvideo_vsa_topk=kwargs.get("fastvideo_vsa_topk"),
+            )
+
+        extras = dict(kwargs.get("extras") or {})
+        for key, default in (
+            ("auxiliary_text_encoder", None),
+            ("default_llama_model_id", "meta-llama/Meta-Llama-3.1-8B-Instruct"),
+        ):
+            top_level_value = kwargs.get(key)
+            if top_level_value is not None:
+                extras[key] = top_level_value
+            else:
+                extras.setdefault(key, default)
+
+        stage_engine_args = {
+            "max_num_seqs": kwargs.get("max_num_seqs") or 1,
+            "parallel_config": parallel_config,
+            # Default-stage construction bypasses the structured projection.
+            # Runner selection remains owned by the selected engine/platform.
+            "engine_backend": kwargs.get("engine_backend", "default"),
+            "model_class_name": kwargs.get("model_class_name", None),
+            "task_type": kwargs.get("task_type", None),
+            "model_config": kwargs.get("model_config", None),
+            "additional_config": kwargs.get("additional_config", None),
+            "step_execution": kwargs.get("step_execution", False),
+            "request_batch_max_wait_ms": kwargs.get("request_batch_max_wait_ms", 0.0),
+            "vae_use_slicing": kwargs.get("vae_use_slicing", False),
+            "vae_use_tiling": kwargs.get("vae_use_tiling", False),
+            "cache_backend": cache_backend,
+            "cache_config": cache_config,
+            "enable_cache_dit_summary": kwargs.get("enable_cache_dit_summary", False),
+            "diffusion_offload_config": kwargs.get("diffusion_offload_config", None),
+            "enable_cpu_offload": kwargs.get("enable_cpu_offload", False),
+            "enable_layerwise_offload": kwargs.get("enable_layerwise_offload", False),
+            "enable_distributed_layerwise_offload": kwargs.get("enable_distributed_layerwise_offload", False),
+            "dlo_use_allgather": kwargs.get("dlo_use_allgather", True),
+            "dlo_resident_layers": kwargs.get("dlo_resident_layers", 0),
+            "host_weight_runtime_mode": kwargs.get("host_weight_runtime_mode", "disabled"),
+            "host_weight_runtime_root": kwargs.get("host_weight_runtime_root"),
+            "dlo_host_registration_limit_gib": kwargs.get("dlo_host_registration_limit_gib", 0.0),
+            "enforce_eager": False if kwargs.get("enforce_eager") is None else kwargs.get("enforce_eager"),
+            "diffusion_compile_granularity": (
+                "regional"
+                if kwargs.get("diffusion_compile_granularity") is None
+                else kwargs["diffusion_compile_granularity"]
+            ),
+            "diffusion_compile_dynamic": (
+                True if kwargs.get("diffusion_compile_dynamic") is None else kwargs["diffusion_compile_dynamic"]
+            ),
+            "fa_deterministic": bool(kwargs.get("fa_deterministic", False)),
+            "boundary_ratio": kwargs.get("boundary_ratio", None),
+            "flow_shift": kwargs.get("flow_shift", None),
+            "diffusion_load_format": kwargs.get("diffusion_load_format", "default"),
+            "lora_path": kwargs.get("lora_path", None),
+            "lora_scale": kwargs.get("lora_scale", 1.0),
+            "lora_backend": kwargs.get("lora_backend", "peft"),
+            "custom_pipeline_args": kwargs.get("custom_pipeline_args", None),
+            "worker_extension_cls": kwargs.get("worker_extension_cls", None),
+            "trust_remote_code": (False if kwargs.get("trust_remote_code") is None else kwargs["trust_remote_code"]),
+            "distributed_executor_backend": kwargs.get("distributed_executor_backend"),
+            "enable_sleep_mode": kwargs.get("enable_sleep_mode", False),
+            "enable_prompt_embed_cache": kwargs.get("enable_prompt_embed_cache", False),
+            "prompt_embed_cache_size": kwargs.get("prompt_embed_cache_size", 32),
+            "enable_multithread_weight_load": kwargs.get("enable_multithread_weight_load", True),
+            "num_weight_load_threads": kwargs.get("num_weight_load_threads", 4),
+            "quantization": kwargs.get("quantization", None),
+            "quantization_config": kwargs.get("quantization_config", None),
+            "diffusion_kv_cache_dtype": kwargs.get("diffusion_kv_cache_dtype", None),
+            "diffusion_kv_cache_skip_steps": kwargs.get("diffusion_kv_cache_skip_steps", None),
+            "diffusion_kv_cache_skip_layers": kwargs.get("diffusion_kv_cache_skip_layers", None),
+            **({"diffusion_attention_config": attention_config} if attention_config is not None else {}),
+            "force_cutlass_fp8": bool(kwargs.get("force_cutlass_fp8", False)),
+            "enable_diffusion_pipeline_profiler": kwargs.get("enable_diffusion_pipeline_profiler", False),
+            "streaming_output": kwargs.get("diffusion_streaming_output", False),
+            "enable_ar_profiler": kwargs.get("enable_ar_profiler", False),
+            "extras": extras,
+            **(
+                {
+                    "profiler_config": asdict(kwargs["profiler_config"])
+                    if hasattr(kwargs["profiler_config"], "__dataclass_fields__")
+                    else kwargs["profiler_config"]
+                }
+                if kwargs.get("profiler_config") is not None
+                else {}
+            ),
+        }
+        if num_gpus is not None:
+            stage_engine_args["num_gpus"] = num_gpus
+        # Only set dtype if it was already explicitly passed and normalized
+        if "dtype" in normalized_kwargs:
+            stage_engine_args["dtype"] = normalized_kwargs["dtype"]
+
+        # New split fields for diffusers adapter kwargs.
+        if kwargs.get("diffusers_load_kwargs") is not None:
+            stage_engine_args["diffusers_load_kwargs"] = kwargs["diffusers_load_kwargs"]
+        if kwargs.get("diffusers_call_kwargs") is not None:
+            stage_engine_args["diffusers_call_kwargs"] = kwargs["diffusers_call_kwargs"]
+
+        default_stage_cfg = [
+            {
+                "stage_id": 0,
+                "stage_type": "diffusion",
+                "runtime": {
+                    "process": True,
+                    "devices": devices,
+                },
+                "engine_args": stage_engine_args,
+                "engine_input_source": [],
+                "default_sampling_params": stage_default_sampling_params,
+                "final_output": True,
+                "final_output_type": final_output_type,
+            }
+        ]
+        default_stage_cfg[0]["engine_args"]["model_stage"] = "diffusion"
+        return default_stage_cfg
+
+    def _apply_strategy_lb_policy(self, derived: str | None, kwargs: dict[str, Any]) -> None:
+        """Apply a strategy-derived ``omni_lb_policy`` to the engine.
+
+        Precedence: an explicit ``--omni-lb-policy`` always wins. ``"random"`` is
+        the engine default and is treated as "unset" (indistinguishable from no
+        flag), so a strategy value overrides it. If the user explicitly passed a
+        non-default policy that conflicts with the strategy-derived one, raise so
+        the mismatch is not silently ignored.
+        """
+        if not derived:
+            return
+        explicit = kwargs.get("omni_lb_policy")
+        user_set = explicit is not None and str(explicit) != "random"
+        if user_set:
+            if str(explicit) != str(derived):
+                raise ValueError(
+                    f"Conflicting load-balancer policy: --omni-lb-policy={explicit!r} was given "
+                    f"but the composable-parallel strategy derived omni_lb_policy={derived!r}. "
+                    "Drop --omni-lb-policy to use the strategy value, or make them match."
+                )
+            return
+        if self._omni_lb_policy != str(derived):
+            logger.info(
+                "[composable_parallel] applying strategy-derived omni_lb_policy=%r (was %r).",
+                derived,
+                self._omni_lb_policy,
+            )
+            self._omni_lb_policy = str(derived)
+
+    @staticmethod
+    def _create_default_diffusion_stage_cfg(kwargs: dict[str, Any]) -> list[dict[str, Any]]:
+        """Compatibility seam for the factory-owned diffusion fallback."""
+        return StageConfigFactory.create_default_diffusion(kwargs)
+
+    def _set_pipeline_runtime_config(
+        self,
+        pipeline_config: PipelineConfig | None,
+        config_path: str | None,
+    ) -> None:
+        """Initialize engine-wide settings resolved from pipeline metadata."""
+        self.endpoint_restrictions = pipeline_config.endpoint_restrictions if pipeline_config is not None else ()
+        # No duplex_runtime_extension / duplex_serving_adapter / duplex_control
+        # here: the pre-framework wiring they named is gone, and design rule 3
+        # in docs/design/fullduplex.md keeps duplex vocabulary out of the base.
+        self.duplex_session_config = DuplexSessionRuntimeConfig()
+        if config_path is not None:
+            if self.deploy_config is not None and self._deploy_config_source == str(config_path):
+                # Already parsed in __init__; the same yaml twice is pure cost.
+                self.duplex_session_config = self.deploy_config.duplex_session
+            else:
+                self.duplex_session_config = load_deploy_config(config_path).duplex_session
+
+    def _resolve_stage_configs(
+        self,
+        model: str,
+        kwargs: dict[str, Any],
+        *,
+        trust_remote_code: bool | None,
+    ) -> tuple[str, list[Any]]:
+        """Resolve stage configs and inject defaults shared by orchestrator/headless."""
+
+        for legacy_arg in ("stage_configs_path", "stage_configs"):
+            if legacy_arg in kwargs:
+                raise ValueError(f"`{legacy_arg}` is no longer supported; use `deploy_config` instead.")
+
+        # log_stats is captured by __init__; its CLI-only negative alias must
+        # not cross into per-stage structured config ownership validation.
+        kwargs.pop("disable_log_stats", None)
+        deploy_config_path = kwargs.pop("deploy_config", None)
+        strategy_config_path = kwargs.pop("strategy_config", None)
+        # CLI callers arrive pre-parsed; offline Python callers may use the
+        # JSON-string form documented in recipes.
+        stage_overrides = parse_stage_overrides(kwargs.pop("stage_overrides", None))
+
+        # ``diffusion_streaming_output`` is the public AsyncOmni/serve kwarg;
+        # stage configs know the field as ``streaming_output``. Mirror only a
+        # truthy value so the CLI's False default does not override deploy YAML.
+        if kwargs.get("diffusion_streaming_output") and kwargs.get("streaming_output") is None:
+            kwargs["streaming_output"] = True
+
+        resolution = cast(
+            _ConfigResolutionResult,
+            load_and_resolve_stage_configs(
+                model,
+                kwargs,
+                trust_remote_code=trust_remote_code,
+                deploy_config_path=deploy_config_path,
+                stage_overrides=stage_overrides,
+                strategy_config_path=strategy_config_path,
+            ),
+        )
+        if isinstance(resolution, OmniConfigResolution):
+            self._config_resolution = resolution
+            config_path = resolution.config_path
+            stage_configs = list(resolution.stage_configs)
+            strategy_lb_policy = resolution.omni_lb_policy
+        else:
+            # Compatibility for overrides of the historical tuple-returning
+            # seam. Production always receives OmniConfigResolution above.
+            config_path, stage_configs, strategy_lb_policy = resolution
+
+        # A strategy.yaml may derive a pipeline-wide load-balancer policy. It is
+        # an orchestrator-level knob (read once at construction), so apply it here
+        # rather than as a per-stage config field.
+        self._apply_strategy_lb_policy(strategy_lb_policy, kwargs)
+
+        return cast(str, config_path), stage_configs
+
+    # ==================== Public API ====================
+
+    def try_get_output(self, timeout: float = 0.001) -> EngineQueueMessage | None:
+        """Read one output message from the Orchestrator output queue."""
+        try:
+            return self.output_queue.sync_q.get(timeout=timeout)
+        except queue.Empty:
+            if not self.is_alive():
+                raise RuntimeError("Orchestrator died unexpectedly. See logs above.")
+            return None
+
+    async def try_get_output_async(self) -> EngineQueueMessage | None:
+        """Async read from the Orchestrator output queue."""
+        try:
+            return self.output_queue.sync_q.get_nowait()
+        except queue.Empty:
+            if not self.is_alive():
+                raise RuntimeError("Orchestrator died unexpectedly. See logs above.")
+            return None
+
+    async def get_output_blocking_async(self, timeout: float = 1.0) -> EngineQueueMessage | None:
+        """Blocking-wait read from the Orchestrator output queue.
+
+        Waits up to ``timeout`` seconds in a dedicated drain thread for the
+        next message (condition-variable wakeup instead of a poll cadence);
+        returns ``None`` on timeout so the caller keeps its liveness check,
+        mirroring ``try_get_output_async``'s contract. Used by the serving
+        final-output drain when ``VLLM_OMNI_EVENT_DRIVEN_ORCH`` is on.
+        """
+        executor = self._output_drain_executor
+        if executor is None:
+            executor = concurrent.futures.ThreadPoolExecutor(
+                max_workers=1,
+                thread_name_prefix="omni-output-drain",
+            )
+            self._output_drain_executor = executor
+
+        sync_q = self.output_queue.sync_q
+
+        def _drain_get() -> EngineQueueMessage | None:
+            # Exceptions are swallowed to a None sentinel: the queue may be
+            # closed mid-shutdown, and an exception left on an executor future
+            # after task cancellation would warn as never-retrieved.
+            try:
+                return sync_q.get(timeout=timeout)
+            except queue.Empty:
+                return None
+            except Exception:
+                return None
+
+        loop = asyncio.get_running_loop()
+        msg = await loop.run_in_executor(executor, _drain_get)
+        if msg is None and not self.is_alive():
+            raise RuntimeError("Orchestrator died unexpectedly. See logs above.")
+        return msg
+
+    def get_stage_metadata(self, stage_id: int) -> StageRuntimeInfo:
+        """Get cached metadata for a stage."""
+        return self.stage_metadata[stage_id]
+
+    def abort(self, request_ids: list[str]) -> None:
+        """Fire-and-forget abort: enqueue and return without waiting.
+
+        Prefer :meth:`abort_async` when the caller needs acknowledgment that
+        stage aborts, binding release, and orchestrator request cleanup finished.
+        """
+        if not request_ids or getattr(self, "_shutdown_called", False):
+            return
+        if self.request_queue is None:
+            raise RuntimeError("request_queue is not initialized")
+        try:
+            self.request_queue.sync_q.put(AbortRequestMessage(request_ids=request_ids))
+        except Exception as exc:
+            if getattr(self, "_shutdown_called", False) and is_janus_sync_queue_shutdown(exc):
+                return
+            raise
+
+    async def abort_async(
+        self,
+        request_ids: list[str],
+        timeout: float | None = None,
+    ) -> list[OutputMessage]:
+        """Abort requests and wait for orchestrator acknowledgment.
+
+        Unlike :meth:`abort`, this generates an ``rpc_id``, correlates the
+        :class:`AbortResultMessage` via :class:`CorrelatedRpcClient`, and
+        raises if the orchestrator reports failure or times out.
+
+        Returns:
+            Final-stage AR abort ``OutputMessage`` list carrying partial
+            tokens generated before abort (empty for diffusion / no OP state).
+        """
+        if not request_ids or getattr(self, "_shutdown_called", False):
+            return []
+        if self.request_queue is None:
+            raise RuntimeError("request_queue is not initialized")
+        transport = self._correlated_rpc_client
+        if transport is None:
+            raise RuntimeError("correlated RPC client is not initialized")
+
+        rpc_id = uuid.uuid4().hex
+        msg = AbortRequestMessage(request_ids=request_ids, rpc_id=rpc_id)
+
+        def _wait() -> AbortResultMessage:
+            result_msg = transport.execute(
+                ("abort", rpc_id),
+                msg,
+                timeout=timeout,
+                timeout_message=f"abort timed out after {timeout} seconds",
+                block_on_submit=True,
+            )
+            if not isinstance(result_msg, AbortResultMessage):
+                raise RuntimeError(f"unexpected abort result type: {type(result_msg).__name__}")
+            return result_msg
+
+        loop = asyncio.get_running_loop()
+        try:
+            result_msg = await loop.run_in_executor(None, _wait)
+        except Exception as exc:
+            if getattr(self, "_shutdown_called", False) and is_abort_transport_shutdown(exc):
+                return []
+            raise
+        if not result_msg.success:
+            raise RuntimeError(result_msg.error or "abort failed")
+        return list(result_msg.abort_outputs or [])
+
+    def collective_rpc(
+        self,
+        method: str,
+        timeout: float | None = None,
+        args: tuple[Any, ...] = (),
+        kwargs: dict[str, Any] | None = None,
+        stage_ids: list[int] | None = None,
+    ) -> list[Any]:
+        """Send a control RPC to the Orchestrator and wait for aggregated results.
+
+        This uses a dedicated RPC output queue so control-plane messages do not
+        race with the normal request output polling loop.
+        """
+        rpc_id = uuid.uuid4().hex
+        msg = CollectiveRPCRequestMessage(
+            rpc_id=rpc_id,
+            method=method,
+            timeout=timeout,
+            args=tuple(args),
+            kwargs=kwargs or {},
+            stage_ids=stage_ids,
+        )
+
+        transport = self._correlated_rpc_client
+        if transport is None:
+            raise RuntimeError("correlated RPC client is not initialized")
+        result_msg = transport.execute(
+            ("collective", rpc_id),
+            msg,
+            timeout=timeout,
+            timeout_message=f"collective_rpc timed out after {timeout} seconds",
+            block_on_submit=True,
+        )
+        if not isinstance(result_msg, CollectiveRPCResultMessage):
+            raise RuntimeError(f"unexpected collective RPC result type: {type(result_msg).__name__}")
+        return list(result_msg.results)
+
+    async def collective_rpc_async(
+        self,
+        method: str,
+        timeout: float | None = None,
+        args: tuple[Any, ...] = (),
+        kwargs: dict[str, Any] | None = None,
+        stage_ids: list[int] | None = None,
+    ) -> list[Any]:
+        """Async wrapper around collective_rpc()."""
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.collective_rpc(
+                method=method,
+                timeout=timeout,
+                args=args,
+                kwargs=kwargs,
+                stage_ids=stage_ids,
+            ),
+        )
+
+    @property
+    def rpc_client(self) -> CorrelatedRpcClient:
+        """The correlated RPC transport (available once the orchestrator is up)."""
+        if self._correlated_rpc_client is None:
+            raise RuntimeError("engine RPC transport is not initialized")
+        return self._correlated_rpc_client
+
+    def is_alive(self) -> bool:
+        """Whether the orchestrator thread is alive."""
+        return bool(self.orchestrator_thread.is_alive())
+
+    def shutdown(self) -> None:
+        """Send shutdown message and wait for the Orchestrator thread to exit."""
+        if getattr(self, "_shutdown_called", False):
+            return
+        self._shutdown_called = True
+        finalizer = getattr(self, "_weak_finalizer", None)
+        if finalizer is not None and finalizer.alive:
+            finalizer.detach()
+
+        logger.info("[OmniEngine] Shutting down Orchestrator")
+        request_queue_closed = False
+        shutdown_enqueued = enqueue_orchestrator_shutdown(
+            self.request_queue,
+            timeout=SHUTDOWN_ENQUEUE_TIMEOUT_S,
+        )
+        if self.request_queue is not None and not shutdown_enqueued:
+            logger.error(
+                "[OmniEngine] Failed to enqueue orchestrator shutdown; "
+                "closing the request queue to wake the request handler"
+            )
+            try:
+                self.request_queue.close()
+                request_queue_closed = True
+            except Exception:
+                logger.exception("[OmniEngine] Failed to close the request queue")
+
+        if self._correlated_rpc_client is not None:
+            try:
+                self._correlated_rpc_client.close()
+            except Exception:
+                logger.exception("[OmniEngine] Failed to close correlated RPC client")
+
+        orchestrator_stopped = False
+        try:
+            if self.is_alive():
+                self.orchestrator_thread.join(timeout=SHUTDOWN_JOIN_TIMEOUT_S)
+            orchestrator_stopped = not self.is_alive()
+            if not orchestrator_stopped:
+                logger.error(
+                    "[OmniEngine] Orchestrator did not stop within %.1f seconds; continuing cleanup",
+                    SHUTDOWN_JOIN_TIMEOUT_S,
+                )
+        except Exception:
+            logger.exception("[OmniEngine] Failed to join Orchestrator thread")
+
+        for q in (self.request_queue, self.output_queue, self.rpc_output_queue):
+            try:
+                if not (q is self.request_queue and request_queue_closed):
+                    q.close()
+            except Exception:
+                pass
+
+        if self._output_drain_executor is not None:
+            # Any in-flight blocking get bails out within its ≤1 s timeout
+            # (or immediately via the queue close above), so don't wait.
+            self._output_drain_executor.shutdown(wait=False)
+            self._output_drain_executor = None
+
+        if hasattr(self, "_runtime") and self._runtime is not None and orchestrator_stopped:
+            try:
+                self._runtime.shutdown()
+            except Exception:
+                logger.exception("[OmniEngine] Failed to shutdown StageRuntime")
+        elif hasattr(self, "_runtime") and self._runtime is not None:
+            logger.warning("[OmniEngine] Deferring StageRuntime shutdown until the Orchestrator exits")
+            threading.Thread(
+                target=shutdown_runtime_after_orchestrator,
+                args=(self.orchestrator_thread, self._runtime),
+                daemon=True,
+                name="omni-stage-runtime-shutdown",
+            ).start()
+
+        # ── Release CuMem allocator memory pool ──────────────────────────────
+        # When enable_sleep_mode is in use, the CuMem (CUDA Virtual Memory
+        # Management) allocator holds model weights in a singleton memory pool
+        # that lives in the parent process.  Killing the engine-core subprocess
+        # does NOT release this pool — the weights stay resident on the GPU
+        # and can cause CUDA OOM for subsequent engine instances (especially
+        # large models like BAGEL-7B-MoT whose weights alone consume ~134 GiB).
+        #
+        # CuMemAllocator.sleep() is NOT idempotent — calling it on already-
+        # slept entries causes CUDA_ERROR_INVALID_VALUE at cumem_allocator
+        # cuMemRelease (double-free of the memory handle).  Use release_pools()
+        # instead, which is the designed cleanup path: it drops MemPool refs
+        # and lets the destructor/free path handle asleep entries correctly
+        # (returns a null handle so the C extension skips unmap/release).
+        try:
+            from vllm.device_allocator.cumem import CuMemAllocator, cumem_available
+
+            if cumem_available:
+                allocator = CuMemAllocator.get_instance()
+                allocator.release_pools()
+                logger.debug("[OmniEngine] Released CuMem memory pool during shutdown")
+        except Exception:
+            pass
+
+    def _try_shutdown(self, *args, **kwargs) -> None:
+        try:
+            self.shutdown()
+        except Exception:
+            logger.exception(*args, **kwargs)
diff --git a/vllm_omni/engine/orchestrator.py b/vllm_omni/engine/orchestrator.py
index 75620bec9a2..aced2c1b36f 100644
--- a/vllm_omni/engine/orchestrator.py
+++ b/vllm_omni/engine/orchestrator.py
@@ -18,7 +18,7 @@
 import os
 import shutil
 import time as _time
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Coroutine
 from dataclasses import dataclass, field
 from http import HTTPStatus
 from typing import Any
@@ -34,28 +34,10 @@
 from vllm.v1.engine.exceptions import EngineDeadError
 from vllm.v1.metrics.stats import IterationStats
 
-from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
 from vllm_omni.diffusion.data import is_diffusion_request_started_output
 from vllm_omni.distributed.omni_connectors.utils.config import stage_receives_chunks
 from vllm_omni.engine import OmniEngineCoreRequest
 from vllm_omni.engine.cfg_companion_tracker import CfgCompanionTracker
-from vllm_omni.engine.duplex.contracts import (
-    DuplexControlPlanePort,
-    DuplexOutputContext,
-    DuplexOutputDecision,
-    DuplexRequestIdentity,
-    DuplexRuntimeExtension,
-    DuplexStageRequestContext,
-    DuplexStageSubmission,
-    DuplexStageSubmissionResult,
-)
-from vllm_omni.engine.duplex.control_plane import DuplexControlPlane
-from vllm_omni.engine.duplex.lease import DuplexLeaseConfig
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.session import (
-    DuplexSessionRuntimeManager,
-    DuplexSessionRuntimeState,
-)
 from vllm_omni.engine.membership_controller import MembershipController
 from vllm_omni.engine.messages import (
     AbortRequestMessage,
@@ -82,7 +64,6 @@
 from vllm_omni.metrics.stat_logger import OmniPrometheusStatLogger
 from vllm_omni.metrics.utils import DIFFUSION_METRICS_ONLY_REQUEST_ID
 from vllm_omni.outputs import OmniRequestOutput
-from vllm_omni.outputs.duplex import attach_duplex_output_decision
 
 logger = init_logger(__name__)
 
@@ -224,9 +205,10 @@ class OrchestratorRequestState:
 
     # Per-request pipeline timing accumulator (milliseconds)
     pipeline_timings: dict[str, float] = field(default_factory=dict)
-    duplex_identity: DuplexRequestIdentity | None = None
-    duplex_stage_fences: dict[int, DuplexFence] = field(default_factory=dict)
-    duplex_config_generation: int = -1
+    # A session-owned request's lifetime belongs to a session (duplex), not to
+    # its own ``finished`` flag: no synthetic terminal, no client emission of
+    # stage-0 segment ends, no terminal re-forward, no cleanup on finish.
+    session_owned: bool = False
     running_counter_registered: bool = False
     request_artifact_dirs: set[str] = field(default_factory=set)
 
@@ -279,143 +261,14 @@ def segment(self, stage_id: int | None) -> StreamingSegmentState:
         return segment if segment is not None else StreamingSegmentState()
 
 
-class _OrchestratorDuplexStagePort:
-    """Adapts generic stage pools to the model-neutral duplex control plane."""
-
-    def __init__(
-        self,
-        *,
-        stage_pools: list[StagePool],
-        request_states: dict[str, OrchestratorRequestState],
-        running_counter: OmniRequestCounter | None,
-        cleanup_request_ids: Callable[..., Any],
-        async_chunk: bool,
-        prewarm_async_chunk_stages: Callable[
-            [str, Any, OrchestratorRequestState],
-            Awaitable[bool],
-        ],
-    ) -> None:
-        self._stage_pools = stage_pools
-        self._request_states = request_states
-        self._running_counter = running_counter
-        self._cleanup_request_ids = cleanup_request_ids
-        self._async_chunk = async_chunk
-        self._prewarm_async_chunk_stages = prewarm_async_chunk_stages
-
-    @property
-    def stage_count(self) -> int:
-        return len(self._stage_pools)
-
-    def sampling_defaults(self) -> tuple[object, ...]:
-        return tuple(pool.stage_client.default_sampling_params for pool in self._stage_pools)
-
-    @staticmethod
-    def _sync_bridge_state(
-        request_state: OrchestratorRequestState,
-        context: DuplexStageRequestContext,
-    ) -> None:
-        duplex_state = request_state.streaming.bridge_states.setdefault("duplex", {})
-        if not isinstance(duplex_state, dict):
-            duplex_state = {}
-            request_state.streaming.bridge_states["duplex"] = duplex_state
-        previous_epoch = duplex_state.get("epoch")
-        current_model_turn_id = duplex_state.get("model_turn_id")
-        if (
-            not isinstance(current_model_turn_id, int)
-            or previous_epoch != context.fence.epoch
-            or current_model_turn_id < context.fence.turn_id
-        ):
-            # A serving-side safety boundary can close a Realtime response
-            # before the model emits its normal turn_eos. Catch up the
-            # engine-owned identity when the next fenced append starts.
-            duplex_state["model_turn_id"] = context.fence.turn_id
-        duplex_state.update(
-            {
-                "session_id": context.session_id,
-                "fence": context.fence,
-                "incarnation": context.fence.incarnation,
-                "epoch": context.fence.epoch,
-                "turn_id": context.fence.turn_id,
-                "response_seq": context.fence.response_seq,
-                "session_config": dict(context.session_config),
-                "runtime_config": dict(context.runtime_config),
-            }
-        )
-
-    def ensure_request(self, context: DuplexStageRequestContext) -> None:
-        request_state = self._request_states.get(context.request_id)
-        if request_state is None:
-            request_state = OrchestratorRequestState(
-                request_id=context.request_id,
-                prompt=None,
-                sampling_params_list=list(context.sampling_params),
-                final_stage_id=context.final_stage_id,
-                duplex_config_generation=context.config_generation,
-            )
-            request_state.streaming.enabled = True
-            self._request_states[context.request_id] = request_state
-        elif request_state.duplex_config_generation != context.config_generation:
-            request_state.sampling_params_list = list(context.sampling_params)
-            request_state.duplex_config_generation = context.config_generation
-        request_state.duplex_identity = DuplexRequestIdentity(
-            session_id=context.session_id,
-            fence=context.fence,
-        )
-        self._sync_bridge_state(request_state, context)
-
-    async def submit(self, submission: DuplexStageSubmission) -> DuplexStageSubmissionResult:
-        context = submission.context
-        request_state = self._request_states.get(context.request_id)
-        if request_state is None:
-            raise RuntimeError(f"duplex request was not preregistered: {context.request_id}")
-        request = build_engine_core_request_from_tokens(
-            request_id=context.request_id,
-            prompt=dict(submission.prompt),
-            params=context.stage_sampling_params,
-            model_config=self._stage_pools[context.stage_id].stage_vllm_config.model_config,
-            resumable=True,
-        )
-        request.external_req_id = request.request_id
-        pool = self._stage_pools[context.stage_id]
-        if submission.already_submitted:
-            replica_id = await pool.submit_update(context.request_id, request_state, request)
-        else:
-            replica_id = await pool.submit_initial(context.request_id, request_state, request, prompt_text=None)
-            if self._async_chunk and context.stage_id == 0:
-                prewarmed = await self._prewarm_async_chunk_stages(
-                    context.request_id,
-                    request,
-                    request_state,
-                )
-                if not prewarmed:
-                    # The prewarm already failed the request, aborted it, and
-                    # popped its state. Falling through would write fences and
-                    # a submit timestamp onto that orphaned object and
-                    # re-increment the running counter the cleanup just
-                    # released, then hand the control plane a success result
-                    # for a request that no longer exists. Raise instead:
-                    # ``DuplexControlPlane.handle_append`` turns this into an
-                    # error result for the append.
-                    raise RuntimeError(
-                        f"async-chunk prewarm failed for duplex request {context.request_id}; the request was aborted"
-                    )
-        request_state.duplex_stage_fences[context.stage_id] = context.fence
-        request_state.stage_submit_ts[context.stage_id] = _time.time()
-        if not request_state.running_counter_registered and self._running_counter is not None:
-            self._running_counter.increment()
-            request_state.running_counter_registered = True
-        return DuplexStageSubmissionResult(
-            request_id=context.request_id,
-            stage_id=context.stage_id,
-            replica_id=replica_id,
-        )
-
-    async def cleanup(self, request_ids: list[str], *, abort: bool = False) -> None:
-        await self._cleanup_request_ids(request_ids, abort=abort)
-
+class OrchestratorBase:
+    """Stage-management loop shared by the turn-based and duplex orchestrators.
 
-class Orchestrator:
-    """Runs inside a background thread's asyncio event loop."""
+    Runs inside a background thread's asyncio event loop. Subclasses fill the
+    template seams (``_dispatch_message``, ``_background_tasks``,
+    ``_shutdown_extensions``, ``_on_stage_submitted``, ``_intercept_stage_output``,
+    ``_handle_forward_failure``, ``_cleanup_request_ids``).
+    """
 
     # Class-level defaults so tests that bypass __init__ via object.__new__
     # don't AttributeError when transfer / counter emit paths access them.
@@ -424,7 +277,6 @@ class Orchestrator:
     _transfer_emitter: Any = None
     _prom_metrics: Any = None
     _stat_logger: OmniPrometheusStatLogger | None = None
-    duplex_control_plane: DuplexControlPlanePort | None = None
 
     def __init__(
         self,
@@ -442,9 +294,6 @@ def __init__(
         prom_metrics: Any = None,
         log_stats: bool = False,
         enable_orch_monitor: bool = False,
-        duplex_runtime_extension: DuplexRuntimeExtension | None = None,
-        enable_duplex_control: bool = False,
-        duplex_session_config: DuplexSessionRuntimeConfig | None = None,
     ) -> None:
         self.request_async_queue = request_async_queue
         self.output_async_queue = output_async_queue
@@ -485,32 +334,6 @@ def __init__(
         self._cfg_tracker = CfgCompanionTracker()
         self._stage_input_processors: dict[int, Any] = {}
 
-        self.duplex_control_plane: DuplexControlPlanePort | None = None
-        self._duplex_reaper_interval_s = 1.0
-        if enable_duplex_control:
-            runtime_session_config = duplex_session_config or DuplexSessionRuntimeConfig()
-            self._duplex_reaper_interval_s = runtime_session_config.reaper_interval_s
-
-            self.duplex_control_plane = DuplexControlPlane(
-                extension=duplex_runtime_extension,
-                stage_port=_OrchestratorDuplexStagePort(
-                    stage_pools=self.stage_pools,
-                    request_states=self.request_states,
-                    running_counter=self._running_counter,
-                    cleanup_request_ids=self._cleanup_request_ids,
-                    async_chunk=self.async_chunk,
-                    prewarm_async_chunk_stages=self._prewarm_async_chunk_stages,
-                ),
-                result_sink=self.rpc_async_queue,
-                lifecycle_sink=self.output_async_queue,
-                lease_config=DuplexLeaseConfig(
-                    idle_ttl_s=runtime_session_config.idle_ttl_s,
-                    disconnect_grace_s=runtime_session_config.disconnect_grace_s,
-                ),
-                max_sessions=runtime_session_config.max_sessions,
-                completed_append_limit=runtime_session_config.completed_append_cache_size,
-            )
-
         self._shutdown_event = asyncio.Event()
         self._stages_shutdown = False
         self._event_driven_orch = _event_driven_orch_enabled()
@@ -588,17 +411,6 @@ def _init_metrics_state(
             logger.exception("[Orchestrator] OmniPrometheusStatLogger init failed; metrics wrap disabled")
             self._stat_logger = None
 
-    @property
-    def duplex_sessions(self) -> DuplexSessionRuntimeManager:
-        if self.duplex_control_plane is None:
-            raise RuntimeError("duplex control plane is disabled")
-        return self.duplex_control_plane.sessions
-
-    def _require_duplex_control_plane(self) -> DuplexControlPlanePort:
-        if self.duplex_control_plane is None:
-            raise RuntimeError("duplex control plane is disabled")
-        return self.duplex_control_plane
-
     async def run(self) -> None:
         """Main entry point for the Orchestrator event loop."""
         logger.info("[Orchestrator] Starting event loop")
@@ -620,8 +432,8 @@ async def run(self) -> None:
             membership_watcher = self._membership.start()
 
         tasks = [request_task, output_task]
-        if self.duplex_control_plane is not None:
-            tasks.append(asyncio.create_task(self._duplex_reaper_loop(), name="orchestrator-duplex-reaper"))
+        for index, coro in enumerate(self._background_tasks()):
+            tasks.append(asyncio.create_task(coro, name=f"orchestrator-background-{index}"))
         if membership_watcher is not None:
             tasks.append(membership_watcher)
 
@@ -655,8 +467,7 @@ async def run(self) -> None:
                 await asyncio.gather(*tasks, return_exceptions=True)
             except Exception:
                 pass
-            if self.duplex_control_plane is not None:
-                await self.duplex_control_plane.shutdown()
+            await self._shutdown_extensions()
 
             if self._membership is not None:
                 await self._membership.drain_tasks(timeout=10.0)
@@ -680,18 +491,10 @@ async def _request_handler(self) -> None:
             msg = await self.request_async_queue.get()
             msg_type = msg.type
 
-            if msg_type == "add_request":
-                await self._handle_add_request(msg)
-            elif msg_type == "streaming_update":
-                await self._handle_streaming_update(msg)
-            elif msg_type == "add_companion_request":
-                await self._handle_add_companion(msg)
-            elif self.duplex_control_plane is not None and self.duplex_control_plane.accepts(msg):
-                self.duplex_control_plane.dispatch(msg)
-            elif msg_type == "abort":
+            if await self._dispatch_message(msg):
+                continue
+            if msg_type == "abort":
                 await self._handle_abort(msg)
-            elif msg_type == "interaction":
-                await self._handle_interaction(msg)
             elif msg_type == "collective_rpc":
                 await self._handle_collective_rpc(msg)
             elif isinstance(msg, RegisterRemoteReplicaMessage):
@@ -717,183 +520,58 @@ async def _request_handler(self) -> None:
             else:
                 logger.warning("[Orchestrator] Unknown message type: %s", msg_type)
 
-    async def _duplex_reaper_loop(self) -> None:
-        while not self._shutdown_event.is_set():
-            try:
-                await asyncio.wait_for(
-                    self._shutdown_event.wait(),
-                    timeout=self._duplex_reaper_interval_s,
-                )
-            except TimeoutError:
-                plane = self.duplex_control_plane
-                if plane is not None:
-                    try:
-                        await plane.reap_expired()
-                    except Exception:
-                        logger.exception("[Orchestrator] Duplex expiry cleanup failed; retrying on next tick")
-
-    async def _handle_add_request(self, msg: StageSubmissionMessage) -> None:
-        """Handle an add_request message from the main thread."""
-        stage_id = 0
-        request_id = msg.request_id
-        prompt = msg.prompt
-        original_prompt = msg.original_prompt
-        sampling_params_list = msg.sampling_params_list
-        if not sampling_params_list:
-            raise ValueError(f"Missing sampling params for stage 0. Got {len(sampling_params_list)} stage params.")
-        final_stage_id = msg.final_stage_id
-        final_output_stage_ids = set(msg.final_output_stage_ids or [final_stage_id])
-
-        if not self.stage_pools[stage_id].live_replica_ids():
-            # Stage 0 lost all replicas between the HTTP-layer errored check and
-            # dispatch. Runs before request state / running counter registration,
-            # so the helper's cleanup is a no-op here.
-            await self._fail_request_dead_stage(request_id, stage_id)
-            return
-
-        logger.debug(
-            "[Orchestrator] _handle_add_request: stage=%s req=%s "
-            "prompt_type=%s original_prompt_type=%s final_stage=%s "
-            "num_sampling_params=%d",
-            stage_id,
-            request_id,
-            type(prompt).__name__,
-            type(original_prompt).__name__,
-            final_stage_id,
-            len(sampling_params_list),
-        )
-
-        req_state = OrchestratorRequestState(
-            request_id=request_id,
-            prompt=original_prompt,
-            sampling_params_list=sampling_params_list,
-            final_stage_id=final_stage_id,
-            final_output_stage_ids=final_output_stage_ids,
-            request_timestamp=float(msg.request_timestamp or _time.time()),
-            mm_features=getattr(prompt, "mm_features", None),
-            request_artifact_dirs=set(msg.request_artifact_dirs or ()),
-        )
-        self.request_states[request_id] = req_state
-        self._register_running_request(req_state)
-        req_state.streaming.enabled = bool(getattr(prompt, "resumable", False))
-        req_state.stage_submit_ts[stage_id] = _time.time()
-        enqueue_ts = msg.enqueue_ts
-        if enqueue_ts > 0:
-            req_state.pipeline_timings["queue_wait_ms"] = (_time.perf_counter() - enqueue_ts) * 1000.0
-        preprocess_ms = msg.preprocess_ms
-        if preprocess_ms > 0:
-            req_state.pipeline_timings["preprocess_ms"] = preprocess_ms
-        if not await self._dispatch_or_fail_request(
-            lambda: self.stage_pools[stage_id].submit_initial(
-                request_id,
-                req_state,
-                prompt,
-                prompt_text=msg.output_prompt_text,
-            ),
-            req_id=request_id,
-            stage_id=stage_id,
-            operation="add_request",
-        ):
-            return
-
-        if self.async_chunk and stage_id == 0 and final_stage_id > 0:
-            await self._prewarm_async_chunk_stages(request_id, prompt, req_state)
-
-    async def _handle_streaming_update(self, msg: StageSubmissionMessage) -> None:
-        """Handle a streaming_update message for an existing request."""
-        stage_id = 0
-        request_id = msg.request_id
-        request = msg.prompt
-        final_stage_id = msg.final_stage_id
-        req_state = self.request_states.get(request_id)
-        if req_state is None:
-            # Streaming updates always follow the first-chunk add_request
-            # through the same ordered submission queue, so an unknown id
-            # here can only mean the request already finished or was
-            # aborted (e.g. the client disconnected). Re-adding it would
-            # resurrect a headless session that keeps cycling through the
-            # stages with nobody consuming its outputs (issue #4271).
-            logger.warning(
-                "[Orchestrator] streaming_update for unknown req=%s; dropping (request finished or aborted)",
-                request_id,
-            )
-            return
-
-        if msg.sampling_params_list:
-            req_state.sampling_params_list = msg.sampling_params_list
+    # ---- Template seams filled by the turn-based / duplex subclasses ----
 
-        req_state.streaming.enabled = True
-        req_state.stage_submit_ts[stage_id] = _time.time()
-        if not await self._dispatch_or_fail_request(
-            lambda: self.stage_pools[stage_id].submit_update(
-                request_id,
-                req_state,
-                request,
-                prompt_text=msg.output_prompt_text,
-            ),
-            req_id=request_id,
-            stage_id=stage_id,
-            operation="streaming_update",
-        ):
-            return
+    async def _dispatch_message(self, msg: EngineQueueMessage) -> bool:
+        """Handle a subclass-specific request-queue message; return True when consumed."""
+        del msg
+        return False
 
-        if self.async_chunk and stage_id == 0 and final_stage_id > 0:
-            await self._prewarm_async_chunk_stages(request_id, request, req_state)
+    def _background_tasks(self) -> list[Coroutine[Any, Any, None]]:
+        """Extra coroutines gathered with the request/output handlers in ``run()``."""
+        return []
 
-    async def _handle_add_companion(self, msg: AddCompanionRequestMessage) -> None:
-        """Handle an add_companion_request message: submit companion to stage 0."""
-        companion_id = msg.companion_id
-        parent_id = msg.parent_id
-        role = msg.role
-        companion_prompt = msg.prompt
-        sampling_params_list = msg.sampling_params_list
+    async def _shutdown_extensions(self) -> None:
+        """Runs in ``run()``'s ``finally`` after task cancellation, before membership drain."""
 
-        parent_state = self.request_states.get(parent_id)
-        if parent_state is None:
-            logger.info(
-                "[Orchestrator] Dropping CFG companion %s (role=%s): parent %s is no longer active",
-                companion_id,
-                role,
-                parent_id,
-            )
-            return
+    def _on_stage_submitted(
+        self,
+        stage_id: int,
+        request_id: str,
+        replica_id: int,
+        req_state: OrchestratorRequestState,
+    ) -> None:
+        """Called after every successful ``submit_initial`` / ``submit_update``."""
+        del stage_id, request_id, replica_id, req_state
 
-        self._cfg_tracker.register_companion(parent_id, role, companion_id)
+    async def _intercept_stage_output(
+        self,
+        stage_id: int,
+        replica_id: int,
+        output: Any,
+        req_state: OrchestratorRequestState,
+        stage_metrics: Any,
+        submit_ts: float | None,
+    ) -> bool:
+        """Offer a processed output to the subclass before forwarding.
 
-        companion_state = OrchestratorRequestState(
-            request_id=companion_id,
-            prompt=companion_prompt,
-            sampling_params_list=sampling_params_list,
-            final_stage_id=0,
-            final_output_stage_ids={0},
-            request_timestamp=parent_state.request_timestamp,
-        )
-        self.request_states[companion_id] = companion_state
-        companion_state.stage_submit_ts[0] = _time.time()
-        # A dead-stage failure is attributed to the parent request; its cleanup
-        # also releases this companion.
-        if not await self._dispatch_or_fail_request(
-            lambda: self.stage_pools[0].submit_initial(
-                companion_id,
-                companion_state,
-                companion_prompt,
-                prompt_text=msg.companion_prompt_text,
-                affinity_request_id=parent_id,
-            ),
-            req_id=parent_id,
-            stage_id=0,
-            operation=f"companion {companion_id}",
-            dispatch_req_id=companion_id,
-        ):
-            return
+        Return True when the output must not be forwarded to the next stage
+        (the subclass consumed it). Client emission for session-owned requests
+        is already suppressed by ``OrchestratorRequestState.session_owned``.
+        """
+        del stage_id, replica_id, output, req_state, stage_metrics, submit_ts
+        return False
 
-        logger.info(
-            "[Orchestrator] CFG companion submitted: %s (role=%s, parent=%s, stage-0 replica-%s)",
-            companion_id,
-            role,
-            parent_id,
-            self.stage_pools[0].get_bound_replica_id(companion_id),
-        )
+    async def _handle_forward_failure(
+        self,
+        req_id: str,
+        next_stage_id: int,
+        req_state: OrchestratorRequestState,
+        exc: BaseException,
+    ) -> bool:
+        """Return True when a next-stage input-processing failure was absorbed (else it re-raises)."""
+        del req_id, next_stage_id, req_state, exc
+        return False
 
     async def _handle_abort(self, msg: AbortRequestMessage) -> None:
         """Handle an abort message from the main thread.
@@ -935,44 +613,6 @@ async def _handle_abort(self, msg: AbortRequestMessage) -> None:
             for output_msg in abort_outputs:
                 await self.output_async_queue.put(output_msg)
 
-    async def _handle_interaction(self, msg: InteractionMessage) -> None:
-        """Handle a midway interaction for an active streaming diffusion request."""
-        stage_id = 0
-        request_id = msg.request_id
-        event_id = msg.interaction.get("event_id")
-        req_state = self.request_states.get(request_id)
-        if req_state is None:
-            logger.info("[Orchestrator] Dropping interaction for inactive req %s", request_id)
-            await self.output_async_queue.put(
-                ErrorMessage(
-                    error=f"No active request for interaction: {request_id}",
-                    fatal=False,
-                    request_id=request_id,
-                    event_id=event_id,
-                    stage_id=stage_id,
-                )
-            )
-            return
-
-        try:
-            await self.stage_pools[stage_id].submit_interaction(request_id, msg.interaction)
-        except Exception as exc:
-            logger.info(
-                "[Orchestrator] Failed interaction for req %s: %s",
-                request_id,
-                exc,
-                exc_info=True,
-            )
-            await self.output_async_queue.put(
-                ErrorMessage(
-                    error=f"Failed interaction for request {request_id}: {exc}",
-                    fatal=False,
-                    request_id=request_id,
-                    event_id=event_id,
-                    stage_id=stage_id,
-                )
-            )
-
     async def _abort_request_ids(self, request_ids: list[str]) -> list[OutputMessage]:
         """Forward abort requests to all stage pools.
 
@@ -1539,7 +1179,7 @@ async def _handle_stage_error(self, stage_id: int, output: Any) -> None:
         await self._cleanup_request_ids(
             [parent_id, *self._cfg_tracker.cleanup_parent(parent_id)],
             abort=True,
-            close_duplex_sessions=True,
+            release_owners=True,
         )
 
     def _update_stage_replica_waiting(self, stage_id: int, replica_id: int, n_waiting: int) -> None:
@@ -1615,6 +1255,13 @@ async def _handle_dead_replica(self, stage_id: int, replica_id: int, error: Engi
             await self._cleanup_request_ids(
                 [req_id, *self._cfg_tracker.cleanup_parent(req_id)],
                 abort=True,
+                # A session-owned request has an owner that outlives the stage
+                # request: without this the runner and its admission slot
+                # survive the replica that was serving them, and the client is
+                # told nothing -- the request-scoped ErrorMessage has no
+                # frontend request_states entry to land in. No-op for
+                # turn-based requests, which have no owner.
+                release_owners=True,
             )
 
     async def _fail_request_dead_stage(self, req_id: str, stage_id: int) -> None:
@@ -1642,6 +1289,7 @@ async def _fail_request_dead_stage(self, req_id: str, stage_id: int) -> None:
         await self._cleanup_request_ids(
             [req_id, *self._cfg_tracker.cleanup_parent(req_id)],
             abort=True,
+            release_owners=True,
         )
 
     async def _fail_request_client_error(
@@ -1652,7 +1300,7 @@ async def _fail_request_client_error(
         *,
         status_code: int = HTTPStatus.BAD_REQUEST.value,
         error_type: str = DEFAULT_CLIENT_ERROR_TYPE,
-        close_duplex_sessions: bool = False,
+        release_owners: bool = False,
     ) -> None:
         """Fail one request with a non-fatal client error (400 by default).
 
@@ -1672,7 +1320,7 @@ async def _fail_request_client_error(
         await self._cleanup_request_ids(
             [req_id, *self._cfg_tracker.cleanup_parent(req_id)],
             abort=True,
-            close_duplex_sessions=close_duplex_sessions,
+            release_owners=release_owners,
         )
 
     async def _dispatch_or_fail_request(
@@ -1767,7 +1415,7 @@ async def _cleanup_request_ids(
         request_ids: list[str],
         *,
         abort: bool = False,
-        close_duplex_sessions: bool = False,
+        release_owners: bool = False,
     ) -> list[OutputMessage]:
         """Release pool bindings and logical request state for the given ids.
 
@@ -1778,10 +1426,14 @@ async def _cleanup_request_ids(
         loss, membership unregister) funnels through here, so tracker state
         cannot outlive its requests.
 
+        ``release_owners`` asks the subclass to also release any session that
+        owns these requests (error paths pass True); the base ignores it.
+
         Returns:
             Final-stage AR abort ``OutputMessage`` list when ``abort=True``;
             otherwise an empty list.
         """
+        del release_owners
         if not request_ids:
             return []
 
@@ -1808,42 +1460,18 @@ async def _cleanup_request_ids(
                 if cid not in batch:
                     batch.add(cid)
                     cleanup_ids.append(cid)
-        closing_session_ids: list[str] = []
-        if close_duplex_sessions and self.duplex_control_plane is not None:
-            closed_sessions = self.duplex_control_plane.close_sessions_for_request_ids(
-                cleanup_ids,
-                abort=abort,
-                cleanup_in_progress=True,
-            )
-            closing_session_ids.extend(closed_sessions)
-            for session_id, stale_request_ids in closed_sessions.items():
-                logger.info(
-                    "[Orchestrator] closed duplex session %s while cleaning failed request ids %s",
-                    session_id,
-                    stale_request_ids,
-                )
-                cleanup_ids.extend(stale_request_ids)
-            cleanup_ids = list(dict.fromkeys(cleanup_ids))
-
         abort_outputs: list[OutputMessage] = []
-        try:
-            if abort:
-                abort_outputs = await self._abort_request_ids(cleanup_ids)
-            self._release_request_bindings(cleanup_ids)
-            for request_id in cleanup_ids:
-                self._pd_kv_params.pop(request_id, None)
-                req_state = self.request_states.pop(request_id, None)
-                if req_state is not None:
-                    cleanup_request_artifact_dirs(getattr(req_state, "request_artifact_dirs", ()))
-                if req_state is not None and req_state.running_counter_registered and self._running_counter is not None:
-                    self._running_counter.decrement()
-                    req_state.running_counter_registered = False
-        except BaseException:
-            if closing_session_ids and self.duplex_control_plane is not None:
-                self.duplex_control_plane.defer_request_cleanups(closing_session_ids)
-            raise
-        if closing_session_ids and self.duplex_control_plane is not None:
-            self.duplex_control_plane.finalize_closed_sessions(closing_session_ids)
+        if abort:
+            abort_outputs = await self._abort_request_ids(cleanup_ids)
+        self._release_request_bindings(cleanup_ids)
+        for request_id in cleanup_ids:
+            self._pd_kv_params.pop(request_id, None)
+            req_state = self.request_states.pop(request_id, None)
+            if req_state is not None:
+                cleanup_request_artifact_dirs(getattr(req_state, "request_artifact_dirs", ()))
+            if req_state is not None and req_state.running_counter_registered and self._running_counter is not None:
+                self._running_counter.decrement()
+                req_state.running_counter_registered = False
         return abort_outputs
 
     async def _apply_raw_terminal_stage_finish(
@@ -1888,7 +1516,7 @@ async def _finish_raw_terminal_requests(
 
         for request_id in request_ids:
             req_state = self.request_states.get(request_id)
-            if req_state is None or self._is_duplex_session_request(req_state):
+            if req_state is None or req_state.session_owned:
                 continue
 
             final_output_stage_ids = req_state.final_output_stage_ids or {req_state.final_stage_id}
@@ -1937,28 +1565,6 @@ def _maybe_clone_diffusion_params_for_cfg(self, request_id: str, params: Any) ->
         params.cfg_kv_request_ids = companion_request_ids
         return params
 
-    def _duplex_session_for_req_state(self, req_state: OrchestratorRequestState) -> DuplexSessionRuntimeState | None:
-        if self.duplex_control_plane is None:
-            return None
-        return self.duplex_control_plane.session_for_identity(req_state.duplex_identity)
-
-    def _record_duplex_stage_submission(
-        self,
-        stage_id: int,
-        request_id: str,
-        replica_id: int,
-        req_state: OrchestratorRequestState,
-    ) -> None:
-        del replica_id
-        identity = req_state.duplex_identity
-        session = self._duplex_session_for_req_state(req_state)
-        if identity is None or session is None:
-            return
-        req_state.duplex_stage_fences[stage_id] = identity.fence
-        session.bind_stage_request(stage_id, request_id, fence=identity.fence)
-        req_state.stage_submit_ts[stage_id] = _time.time()
-        self._register_running_request(req_state)
-
     def _register_running_request(self, req_state: OrchestratorRequestState) -> None:
         if req_state.running_counter_registered or self._running_counter is None:
             return
@@ -1991,17 +1597,11 @@ async def _route_output(
             req_state.finished_final_output_stage_ids.add(stage_id)
             final_output_stage_ids = req_state.final_output_stage_ids or {req_state.final_stage_id}
             request_finished = final_output_stage_ids.issubset(req_state.finished_final_output_stage_ids)
-        # Duplex stage-0 segment boundaries are not client-visible outputs:
-        # direct decisions are emitted by the model runtime extension below,
-        # while spoken content flows through the next stage. Forwarding
-        # the raw stage-0 output as well injects one cumulative-text,
-        # no-audio message per unit that every downstream consumer must
-        # filter out again (the official implementation returns exactly one
-        # result per audio chunk).
-        is_duplex_stage0_segment = (
-            stage_id == 0 and self._is_duplex_session_request(req_state) and req_state.streaming.segment(0).finished
-        )
-        if self.stage_pools[stage_id].final_output and not is_duplex_stage0_segment:
+        if req_state.session_owned:
+            # Session-owned outputs are delivered to their session through
+            # ``_intercept_stage_output`` below, never to a request queue.
+            pass
+        elif self.stage_pools[stage_id].final_output:
             await self.output_async_queue.put(
                 OutputMessage(
                     request_id=req_id,
@@ -2009,13 +1609,7 @@ async def _route_output(
                     replica_id=replica_id,
                     engine_outputs=output,
                     metrics=stage_metrics,
-                    finished=(
-                        request_finished
-                        or (
-                            self._is_duplex_session_request(req_state)
-                            and req_state.streaming.segment(stage_id).finished
-                        )
-                    ),
+                    finished=request_finished,
                     stage_submit_ts=submit_ts,
                 )
             )
@@ -2036,16 +1630,7 @@ async def _route_output(
                 self._pd_kv_params[req_id] = kv_params if isinstance(kv_params, dict) else dict(kv_params)
             req_state.pd_prefill_multimodal_output = getattr(output, "multimodal_output", None)
 
-        duplex_output_decision = self._duplex_output_decision(stage_id, output, req_state)
-        if duplex_output_decision is not None:
-            await self._emit_duplex_direct_output(
-                stage_id,
-                req_id,
-                output,
-                duplex_output_decision,
-                stage_metrics,
-                submit_ts,
-            )
+        if await self._intercept_stage_output(stage_id, replica_id, output, req_state, stage_metrics, submit_ts):
             return
 
         if (
@@ -2082,7 +1667,7 @@ async def _route_output(
                     and self.request_states.get(req_id) is req_state
                     and finished
                     and not final_only_finished
-                    and not self._is_duplex_session_request(req_state)
+                    and not req_state.session_owned
                 ):
                     # For streaming sessions, send the terminal (resumable=False) update only on a finish
                     await self._forward_to_next_stage(
@@ -2095,7 +1680,7 @@ async def _route_output(
                         is_final_update=True,
                     )
 
-        if request_finished and not self._is_duplex_session_request(req_state):
+        if request_finished and not req_state.session_owned:
             await self._cleanup_request_ids([req_id, *self._cfg_tracker.cleanup_parent(req_id)])
 
     def _next_stage_already_submitted(self, stage_id: int, req_state: OrchestratorRequestState) -> bool:
@@ -2189,92 +1774,6 @@ def _build_next_stage_request(
         request.payload_sender_info = payload_sender_info
         return request
 
-    @staticmethod
-    def _duplex_output_context(
-        req_state: OrchestratorRequestState,
-        *,
-        # Required: segment state is stage-keyed, so a caller that omitted this
-        # would silently read "no boundary" rather than the intended stage's.
-        stage_id: int | None,
-    ) -> DuplexOutputContext | None:
-        identity = req_state.duplex_identity
-        if identity is None:
-            return None
-        fence = req_state.duplex_stage_fences.get(stage_id, identity.fence) if stage_id is not None else identity.fence
-        segment = req_state.streaming.segment(stage_id)
-        return DuplexOutputContext(
-            identity=DuplexRequestIdentity(
-                session_id=identity.session_id,
-                fence=fence,
-            ),
-            final_stage_id=req_state.final_stage_id,
-            segment_finished=req_state.streaming.enabled and segment.finished,
-            segment_token_ids=tuple(segment.token_ids),
-            segment_output_metadata=segment.output_metadata,
-        )
-
-    @staticmethod
-    def _is_duplex_session_request(req_state: OrchestratorRequestState) -> bool:
-        return req_state.duplex_identity is not None
-
-    @staticmethod
-    def _duplex_fence_for_req_state(
-        req_state: OrchestratorRequestState,
-        *,
-        stage_id: int | None = None,
-    ) -> DuplexFence | None:
-        context = Orchestrator._duplex_output_context(req_state, stage_id=stage_id)
-        return context.identity.fence if context is not None else None
-
-    def _duplex_output_decision(
-        self,
-        stage_id: int,
-        output: Any,
-        req_state: OrchestratorRequestState,
-    ) -> DuplexOutputDecision | None:
-        if self.duplex_control_plane is None:
-            return None
-        context = self._duplex_output_context(req_state, stage_id=stage_id)
-        decision = self.duplex_control_plane.decide_output(
-            stage_id,
-            output,
-            context,
-        )
-        return decision
-
-    async def _emit_duplex_direct_output(
-        self,
-        stage_id: int,
-        req_id: str,
-        output: Any,
-        decision: DuplexOutputDecision,
-        stage_metrics: Any,
-        submit_ts: float | None,
-    ) -> None:
-        action = getattr(decision.action, "value", decision.action)
-        if action != "direct_response":
-            raise ValueError(f"Unsupported duplex output action: {action}")
-        engine_output = attach_duplex_output_decision(
-            OmniRequestOutput.from_stage_output(
-                output,
-                request_id=req_id,
-                finished=True,
-                stage_id=stage_id,
-                final_output_type=decision.final_output_type,
-            ),
-            decision,
-        )
-        await self.output_async_queue.put(
-            OutputMessage(
-                request_id=req_id,
-                stage_id=stage_id,
-                engine_outputs=engine_output,
-                metrics=stage_metrics,
-                finished=True,
-                stage_submit_ts=submit_ts,
-            )
-        )
-
     @staticmethod
     def _completion_multimodal_output(output: Any, completion: Any) -> dict[str, Any]:
         mm_output = getattr(output, "multimodal_output", None)
@@ -2653,7 +2152,7 @@ async def _forward_to_next_stage_unguarded(
                     },
                     params_override=self._maybe_clone_diffusion_params_for_cfg(req_id, params),
                 )
-            self._record_duplex_stage_submission(
+            self._on_stage_submitted(
                 next_logical,
                 req_id,
                 replica_id,
@@ -2706,7 +2205,7 @@ async def _forward_to_next_stage_unguarded(
                     replica_id = await next_pool.submit_update(req_id, req_state, request)
                 else:
                     replica_id = await next_pool.submit_initial(req_id, req_state, request, prompt_text=None)
-                self._record_duplex_stage_submission(
+                self._on_stage_submitted(
                     next_logical,
                     req_id,
                     replica_id,
@@ -2751,7 +2250,7 @@ async def _forward_to_next_stage_unguarded(
                 str(exc),
                 status_code=exc.status_code,
                 error_type=exc.error_type,
-                close_duplex_sessions=self._is_duplex_session_request(req_state),
+                release_owners=req_state.session_owned,
             )
             return
         except Exception as exc:
@@ -2760,21 +2259,8 @@ async def _forward_to_next_stage_unguarded(
                 req_id,
                 next_logical,
             )
-            if not self._is_duplex_session_request(req_state):
+            if not await self._handle_forward_failure(req_id, next_logical, req_state, exc):
                 raise
-            await self.output_async_queue.put(
-                ErrorMessage(
-                    request_id=req_id,
-                    stage_id=next_logical,
-                    error=f"Stage-{next_logical} input processor failed: {type(exc).__name__}: {exc}",
-                    error_type=type(exc).__name__,
-                )
-            )
-            await self._cleanup_request_ids(
-                [req_id, *self._cfg_tracker.cleanup_parent(req_id)],
-                abort=True,
-                close_duplex_sessions=True,
-            )
             return
         finally:
             req_state.streaming.source_token_decoder = previous_decoder
@@ -2842,7 +2328,7 @@ async def _forward_to_next_stage_unguarded(
                 replica_id = await next_pool.submit_update(req_id, req_state, request)
             else:
                 replica_id = await next_pool.submit_initial(req_id, req_state, request, prompt_text=None)
-            self._record_duplex_stage_submission(
+            self._on_stage_submitted(
                 next_logical,
                 req_id,
                 replica_id,
@@ -2900,7 +2386,7 @@ async def _prewarm_async_chunk_stages(
                 0,
                 "async_chunk requires prompt_token_ids on the stage-0 request; "
                 "an embeds-only prompt cannot prewarm downstream stages",
-                close_duplex_sessions=True,
+                release_owners=True,
             )
             return False
 
@@ -2996,7 +2482,7 @@ async def _prewarm_async_chunk_stages(
             # The guard swallows submit_initial's return value; the pool binding
             # it recorded carries the same replica.
             bound_replica_id = next_pool.get_bound_replica_id(request_id)
-            self._record_duplex_stage_submission(
+            self._on_stage_submitted(
                 next_stage_id,
                 request_id,
                 bound_replica_id if bound_replica_id is not None else 0,
@@ -3081,3 +2567,222 @@ def _shutdown_stages(self) -> None:
         for pool in self.stage_pools:
             for replica_id in pool.live_replica_ids():
                 pool.shutdown_replica(replica_id)
+
+
+class Orchestrator(OrchestratorBase):
+    """Turn-based orchestrator: admits ``add_request`` / streaming / companion / interaction messages."""
+
+    async def _dispatch_message(self, msg: EngineQueueMessage) -> bool:
+        msg_type = msg.type
+        if msg_type == "add_request":
+            await self._handle_add_request(msg)
+        elif msg_type == "streaming_update":
+            await self._handle_streaming_update(msg)
+        elif msg_type == "add_companion_request":
+            await self._handle_add_companion(msg)
+        elif msg_type == "interaction":
+            await self._handle_interaction(msg)
+        else:
+            return False
+        return True
+
+    async def _handle_add_request(self, msg: StageSubmissionMessage) -> None:
+        """Handle an add_request message from the main thread."""
+        stage_id = 0
+        request_id = msg.request_id
+        prompt = msg.prompt
+        original_prompt = msg.original_prompt
+        sampling_params_list = msg.sampling_params_list
+        if not sampling_params_list:
+            raise ValueError(f"Missing sampling params for stage 0. Got {len(sampling_params_list)} stage params.")
+        final_stage_id = msg.final_stage_id
+        final_output_stage_ids = set(msg.final_output_stage_ids or [final_stage_id])
+
+        if not self.stage_pools[stage_id].live_replica_ids():
+            # Stage 0 lost all replicas between the HTTP-layer errored check and
+            # dispatch. Runs before request state / running counter registration,
+            # so the helper's cleanup is a no-op here.
+            await self._fail_request_dead_stage(request_id, stage_id)
+            return
+
+        logger.debug(
+            "[Orchestrator] _handle_add_request: stage=%s req=%s "
+            "prompt_type=%s original_prompt_type=%s final_stage=%s "
+            "num_sampling_params=%d",
+            stage_id,
+            request_id,
+            type(prompt).__name__,
+            type(original_prompt).__name__,
+            final_stage_id,
+            len(sampling_params_list),
+        )
+
+        req_state = OrchestratorRequestState(
+            request_id=request_id,
+            prompt=original_prompt,
+            sampling_params_list=sampling_params_list,
+            final_stage_id=final_stage_id,
+            final_output_stage_ids=final_output_stage_ids,
+            request_timestamp=float(msg.request_timestamp or _time.time()),
+            mm_features=getattr(prompt, "mm_features", None),
+            request_artifact_dirs=set(msg.request_artifact_dirs or ()),
+        )
+        self.request_states[request_id] = req_state
+        self._register_running_request(req_state)
+        req_state.streaming.enabled = bool(getattr(prompt, "resumable", False))
+        req_state.stage_submit_ts[stage_id] = _time.time()
+        enqueue_ts = msg.enqueue_ts
+        if enqueue_ts > 0:
+            req_state.pipeline_timings["queue_wait_ms"] = (_time.perf_counter() - enqueue_ts) * 1000.0
+        preprocess_ms = msg.preprocess_ms
+        if preprocess_ms > 0:
+            req_state.pipeline_timings["preprocess_ms"] = preprocess_ms
+        if not await self._dispatch_or_fail_request(
+            lambda: self.stage_pools[stage_id].submit_initial(
+                request_id,
+                req_state,
+                prompt,
+                prompt_text=msg.output_prompt_text,
+            ),
+            req_id=request_id,
+            stage_id=stage_id,
+            operation="add_request",
+        ):
+            return
+
+        if self.async_chunk and stage_id == 0 and final_stage_id > 0:
+            await self._prewarm_async_chunk_stages(request_id, prompt, req_state)
+
+    async def _handle_streaming_update(self, msg: StageSubmissionMessage) -> None:
+        """Handle a streaming_update message for an existing request."""
+        stage_id = 0
+        request_id = msg.request_id
+        request = msg.prompt
+        final_stage_id = msg.final_stage_id
+        req_state = self.request_states.get(request_id)
+        if req_state is None:
+            # Streaming updates always follow the first-chunk add_request
+            # through the same ordered submission queue, so an unknown id
+            # here can only mean the request already finished or was
+            # aborted (e.g. the client disconnected). Re-adding it would
+            # resurrect a headless session that keeps cycling through the
+            # stages with nobody consuming its outputs (issue #4271).
+            logger.warning(
+                "[Orchestrator] streaming_update for unknown req=%s; dropping (request finished or aborted)",
+                request_id,
+            )
+            return
+
+        if msg.sampling_params_list:
+            req_state.sampling_params_list = msg.sampling_params_list
+
+        req_state.streaming.enabled = True
+        req_state.stage_submit_ts[stage_id] = _time.time()
+        if not await self._dispatch_or_fail_request(
+            lambda: self.stage_pools[stage_id].submit_update(
+                request_id,
+                req_state,
+                request,
+                prompt_text=msg.output_prompt_text,
+            ),
+            req_id=request_id,
+            stage_id=stage_id,
+            operation="streaming_update",
+        ):
+            return
+
+        if self.async_chunk and stage_id == 0 and final_stage_id > 0:
+            await self._prewarm_async_chunk_stages(request_id, request, req_state)
+
+    async def _handle_add_companion(self, msg: AddCompanionRequestMessage) -> None:
+        """Handle an add_companion_request message: submit companion to stage 0."""
+        companion_id = msg.companion_id
+        parent_id = msg.parent_id
+        role = msg.role
+        companion_prompt = msg.prompt
+        sampling_params_list = msg.sampling_params_list
+
+        parent_state = self.request_states.get(parent_id)
+        if parent_state is None:
+            logger.info(
+                "[Orchestrator] Dropping CFG companion %s (role=%s): parent %s is no longer active",
+                companion_id,
+                role,
+                parent_id,
+            )
+            return
+
+        self._cfg_tracker.register_companion(parent_id, role, companion_id)
+
+        companion_state = OrchestratorRequestState(
+            request_id=companion_id,
+            prompt=companion_prompt,
+            sampling_params_list=sampling_params_list,
+            final_stage_id=0,
+            final_output_stage_ids={0},
+            request_timestamp=parent_state.request_timestamp,
+        )
+        self.request_states[companion_id] = companion_state
+        companion_state.stage_submit_ts[0] = _time.time()
+        # A dead-stage failure is attributed to the parent request; its cleanup
+        # also releases this companion.
+        if not await self._dispatch_or_fail_request(
+            lambda: self.stage_pools[0].submit_initial(
+                companion_id,
+                companion_state,
+                companion_prompt,
+                prompt_text=msg.companion_prompt_text,
+                affinity_request_id=parent_id,
+            ),
+            req_id=parent_id,
+            stage_id=0,
+            operation=f"companion {companion_id}",
+            dispatch_req_id=companion_id,
+        ):
+            return
+
+        logger.info(
+            "[Orchestrator] CFG companion submitted: %s (role=%s, parent=%s, stage-0 replica-%s)",
+            companion_id,
+            role,
+            parent_id,
+            self.stage_pools[0].get_bound_replica_id(companion_id),
+        )
+
+    async def _handle_interaction(self, msg: InteractionMessage) -> None:
+        """Handle a midway interaction for an active streaming diffusion request."""
+        stage_id = 0
+        request_id = msg.request_id
+        event_id = msg.interaction.get("event_id")
+        req_state = self.request_states.get(request_id)
+        if req_state is None:
+            logger.info("[Orchestrator] Dropping interaction for inactive req %s", request_id)
+            await self.output_async_queue.put(
+                ErrorMessage(
+                    error=f"No active request for interaction: {request_id}",
+                    fatal=False,
+                    request_id=request_id,
+                    event_id=event_id,
+                    stage_id=stage_id,
+                )
+            )
+            return
+
+        try:
+            await self.stage_pools[stage_id].submit_interaction(request_id, msg.interaction)
+        except Exception as exc:
+            logger.info(
+                "[Orchestrator] Failed interaction for req %s: %s",
+                request_id,
+                exc,
+                exc_info=True,
+            )
+            await self.output_async_queue.put(
+                ErrorMessage(
+                    error=f"Failed interaction for request {request_id}: {exc}",
+                    fatal=False,
+                    request_id=request_id,
+                    event_id=event_id,
+                    stage_id=stage_id,
+                )
+            )
diff --git a/vllm_omni/entrypoints/async_omni.py b/vllm_omni/entrypoints/async_omni.py
index 993f0ca1edf..6114bbea271 100644
--- a/vllm_omni/entrypoints/async_omni.py
+++ b/vllm_omni/entrypoints/async_omni.py
@@ -11,7 +11,6 @@
 from __future__ import annotations
 
 import asyncio
-import os
 import time
 import uuid
 from collections.abc import AsyncGenerator, Iterable, Mapping, Sequence
@@ -21,31 +20,17 @@
 from vllm.engine.protocol import EngineClient, StreamingInput
 from vllm.logger import init_logger
 from vllm.lora.request import LoRARequest
-from vllm.outputs import CompletionOutput, PoolingRequestOutput
-from vllm.plugins.io_processors import get_io_processor
+from vllm.outputs import PoolingRequestOutput
 from vllm.pooling_params import PoolingParams
 from vllm.renderers.inputs.preprocess import extract_prompt_components
 from vllm.sampling_params import RequestOutputKind, SamplingParams
 from vllm.tasks import SupportedTask
-from vllm.utils import random_uuid
-from vllm.v1.engine.exceptions import EngineDeadError
 
 from vllm_omni.diffusion.data import CuMemTag, OmniACK, OmniSleepTask, OmniWakeTask
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity
-from vllm_omni.engine.duplex.messages import (
-    DuplexFence,
-    DuplexSessionLifecycleMessage,
-)
-from vllm_omni.engine.messages import ErrorMessage, OutputMessage
+from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
+from vllm_omni.engine.messages import ErrorMessage
+from vllm_omni.entrypoints.async_omni_base import ABORT_TIMEOUT_S, AsyncOmniBase
 from vllm_omni.entrypoints.client_request_state import ClientRequestState
-from vllm_omni.entrypoints.duplex_request_client import (
-    DuplexRequestClient,
-    DuplexRequestOutputPort,
-)
-from vllm_omni.entrypoints.omni_base import (
-    OmniBase,
-    OmniEngineDeadError,
-)
 from vllm_omni.errors import client_error_metadata
 from vllm_omni.inputs.data import OmniSamplingParams
 from vllm_omni.metrics.stats import OrchestratorAggregator as OrchestratorMetrics
@@ -59,74 +44,9 @@
     from vllm_omni.inputs.data import OmniInteractionPrompt, OmniPromptType
 
 logger = init_logger(__name__)
-_FINAL_OUTPUT_IDLE_SLEEP_S = 0.001
-# Blocking-wait interval for the event-driven final-output drain
-# (VLLM_OMNI_EVENT_DRIVEN_ORCH=1): a message wakes the drain immediately via
-# the janus queue's condition variable; this timeout only bounds how often the
-# orchestrator liveness check runs while the pipeline is idle.
-_FINAL_OUTPUT_BLOCKING_WAIT_S = 1.0
-# Shared DELETE / generate() cleanup abort bound. Env is the documented knob.
-ABORT_TIMEOUT_S = float(os.environ.get("VLLM_OMNI_ABORT_TIMEOUT", 2.0))
 
 
-class AsyncEventResolver:
-    """
-    A generic signal aggregator designed for synchronized handshakes in
-    distributed or multi-stage environments. Supports waiting for a specified
-    number (expected_count) of worker signals in both inline and multiprocess modes.
-    """
-
-    def __init__(self, orchestrator=None):
-        self._pending_tasks: dict[str, dict] = {}
-        self.orchestrator = orchestrator
-        self._lock = asyncio.Lock()
-
-    def watch_task(self, task_id: str, expected_count: int = 1) -> asyncio.Future:
-        loop = asyncio.get_running_loop()
-        fut = loop.create_future()
-        self._pending_tasks[task_id] = {
-            "future": fut,
-            "expected_count": expected_count,
-            "received": [],
-            "start_time": time.time(),
-        }
-        return fut
-
-    async def resolve(self, ack: OmniACK):
-        tid = getattr(ack, "task_id", None)
-
-        if tid is None and isinstance(ack, dict):
-            tid = ack.get("task_id")
-
-        async with self._lock:
-            task_info = self._pending_tasks.get(tid)
-            if task_info is None:
-                logger.warning(f"Received stray ACK for task_id {tid}. Task might have timed out.")
-                return
-
-            task_info["received"].append(ack)
-            current_count = len(task_info["received"])
-            expected = task_info["expected_count"]
-
-            orchestrator = self.orchestrator
-            if orchestrator and hasattr(orchestrator, "metrics") and orchestrator.metrics:
-                freed = getattr(ack, "freed_bytes", 0)
-                if freed == 0 and isinstance(ack, dict):
-                    freed = ack.get("freed_bytes", 0)
-                orchestrator.metrics.record_vram_reclaimed(freed)
-
-            logger.info(f"[Resolver] Task {tid} progress: {current_count}/{expected} ACKs received.")
-
-            if current_count >= expected:
-                self._pending_tasks.pop(tid)
-                fut = task_info["future"]
-                if not fut.done():
-                    elapsed = time.time() - task_info["start_time"]
-                    logger.info(f"[Resolver] Task {tid} completed successfully in {elapsed:.2f}s.")
-                    fut.set_result(task_info["received"])
-
-
-class AsyncOmni(EngineClient, OmniBase):
+class AsyncOmni(AsyncOmniBase, EngineClient):
     """Asynchronous unified entry point for multi-stage pipelines using AsyncOmniEngine.
 
     This is the refactored version that uses AsyncOmniEngine instead of
@@ -155,8 +75,13 @@ class AsyncOmni(EngineClient, OmniBase):
         ...     print(output)
     """
 
-    def __init__(self, *args: Any, model: str = "", **kwargs: Any) -> None:
-        OmniBase.__init__(self, model=model, **kwargs)
+    def _create_engine(self, **engine_kwargs: Any) -> AsyncOmniEngine:
+        return AsyncOmniEngine(**engine_kwargs)
+
+    def __init__(self, model: str = "", *args: Any, **kwargs: Any) -> None:
+        tts_max_instructions_length = kwargs.get("tts_max_instructions_length", None)
+        AsyncOmniBase.__init__(self, *args, model=model, **kwargs)
+        self.tts_max_instructions_length = tts_max_instructions_length
         self._pause_cond: asyncio.Condition = asyncio.Condition()
         self._paused: bool = False
         # In-flight EngineCore submits (non-streaming add_request, or each
@@ -173,294 +98,6 @@ def __init__(self, *args: Any, model: str = "", **kwargs: Any) -> None:
         self._sleeping_tags: set[str] = set()
         self._stage_sleeping_tags: dict[int, set[str]] = {}
         self._level2_sleeping: bool = False
-        self._duplex_request_client: DuplexRequestClient | None = None
-        self.duplex_lifecycle_events: asyncio.Queue[DuplexSessionLifecycleMessage] = asyncio.Queue()
-        self.final_output_task: asyncio.Task | None = None
-        self.event_resolver = AsyncEventResolver(orchestrator=self)
-        self.config_path = self.engine.config_path
-        self.tts_max_instructions_length = kwargs.get("tts_max_instructions_length", None)
-        self.input_processor = self.engine.input_processor
-        self.endpoint_restrictions = self.engine.endpoint_restrictions
-        self.duplex_session_config = self.engine.duplex_session_config
-        self.duplex_serving_adapter_path = self.engine.duplex_serving_adapter_path
-
-        stage_index = self._get_comprehension_stage_index()
-        if stage_index is None:
-            self.io_processor = None
-        else:
-            vllm_config = self.engine.stage_vllm_configs[stage_index]
-            io_processor_plugin = vllm_config.model_config.io_processor_plugin
-            renderer = self.renderer
-            if renderer is None:
-                from vllm.renderers import renderer_from_config
-
-                renderer = renderer_from_config(vllm_config)
-            self.io_processor = get_io_processor(vllm_config, renderer, io_processor_plugin)
-
-    def _resolve_transfer_replica(self, stage_id: int, request_id: str) -> int | None:
-        """Look up the sticky-routed replica for (stage_id, request_id).
-
-        Used as the ``replica_resolver`` callback by ``OrchestratorAggregator``
-        to label transfer_* metrics without plumbing replica ids through
-        ``TransferEdgeStats`` / ``StageRequestStats`` / connector adapters.
-        Returns None when stage_id is out of range or the request hasn't been
-        bound to a replica yet — the metric emit then defensive-skips.
-        """
-        pools = getattr(self.engine, "stage_pools", None)
-        if pools is None or not (0 <= stage_id < len(pools)):
-            return None
-        return pools[stage_id].get_bound_replica_id(request_id)
-
-    def _get_comprehension_stage_index(self) -> int | None:
-        fallback_idx: int | None = None
-        for idx, stage_client in enumerate(self.engine.stage_clients):
-            stage_vllm_config = self.engine.stage_vllm_configs[idx]
-            if stage_vllm_config is None:
-                continue
-            if fallback_idx is None:
-                fallback_idx = idx
-            if stage_client.is_comprehension:
-                return idx
-        return fallback_idx
-
-    @property
-    def renderer(self):
-        """Return the renderer from the engine input processor when available."""
-        if self.input_processor is None:
-            return None
-        return self.input_processor.renderer
-
-    @property
-    def vllm_config(self):
-        """Return the vLLM config for the comprehension stage when present."""
-        stage_index = self._get_comprehension_stage_index()
-        if stage_index is None:
-            return None
-        return self.engine.stage_vllm_configs[stage_index]
-
-    async def get_vllm_config(self) -> Any:
-        """Compatibility helper for call sites expecting async vllm config access."""
-        return self.vllm_config
-
-    def get_diffusion_od_config(self) -> Any | None:
-        """Return the diffusion-stage config when the pipeline has one."""
-        saw_diffusion_stage = False
-        for stage_client in self.engine.stage_clients:
-            if getattr(stage_client, "stage_type", None) != "diffusion":
-                continue
-
-            saw_diffusion_stage = True
-
-            od_config = getattr(stage_client, "od_config", None)
-            if od_config is not None:
-                return od_config
-
-            inner_engine = getattr(stage_client, "_engine", None)
-            od_config = getattr(inner_engine, "od_config", None)
-            if od_config is not None:
-                return od_config
-
-        # Out-of-process diffusion clients don't carry od_config (it lives in the
-        # worker); fall back to the engine's model_class_name resolution.
-        if saw_diffusion_stage:
-            return self.engine.get_diffusion_od_config()
-
-        return None
-
-    @property
-    def model_config(self):
-        """Return the model config for the comprehension stage when present."""
-        vllm_config = self.vllm_config
-        if vllm_config is None:
-            return None
-        return vllm_config.model_config
-
-    @staticmethod
-    def _get_unique_request_id(external_request_id: str):
-        """Get a random new request ID for this request; at the server level,
-        this is usually set by the calling entrypoint, but in direct calls, we
-        need to set it explicitly since we do not allow empty IDs.
-
-        NOTE: in the upstream vLLM, this is done in the InputProcessor's
-        `assign_request_id`.
-        """
-        uuid = random_uuid()
-        prefix = "" if not external_request_id else f"{external_request_id}-"
-        return f"{prefix}{uuid:.8}"
-
-    async def open_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        session_mode: str = "duplex",
-        capabilities: dict[str, object] | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Open an engine-level duplex session when the backend supports it."""
-        return await self._get_duplex_request_client().open(
-            session_id,
-            session_mode=session_mode,
-            capabilities=capabilities,
-            session_config=session_config,
-            runtime_config=runtime_config,
-            fence=fence,
-            timeout=timeout,
-        )
-
-    async def append_duplex_input_async(
-        self,
-        session_id: str,
-        *,
-        mode: str,
-        payload: object,
-        operation_id: str | None = None,
-        final: bool = False,
-        expected_epoch: int | None = None,
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-        collect_outputs: bool = True,
-    ) -> dict[str, object]:
-        """Append input to an engine-level duplex session."""
-        return await self._get_duplex_request_client().append(
-            session_id,
-            mode=mode,
-            payload=payload,
-            operation_id=operation_id,
-            final=final,
-            expected_epoch=expected_epoch,
-            fence=fence,
-            timeout=timeout,
-            collect_outputs=collect_outputs,
-        )
-
-    async def collect_duplex_data_plane_outputs_async(
-        self,
-        request_id: str,
-        *,
-        response_stage_id: int | None = None,
-        timeout: float | None = 10.0,
-    ) -> list[OmniRequestOutput]:
-        """Collect the next duplex data-plane output batch for a live request."""
-        return await self._get_duplex_request_client().collect_registered_outputs(
-            request_id,
-            response_stage_id=response_stage_id,
-            timeout=timeout,
-        )
-
-    async def signal_duplex_turn_async(
-        self,
-        session_id: str,
-        *,
-        event: str,
-        fence: DuplexFence,
-        next_fence: DuplexFence | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Send a turn/control signal to an engine-level duplex session."""
-        return await self._get_duplex_request_client().signal(
-            session_id,
-            event=event,
-            fence=fence,
-            next_fence=next_fence,
-            session_config=session_config,
-            runtime_config=runtime_config,
-            timeout=timeout,
-        )
-
-    async def close_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        reason: str = "client_close",
-        fence: DuplexFence,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        """Close an engine-level duplex session."""
-        return await self._get_duplex_request_client().close(
-            session_id,
-            reason=reason,
-            fence=fence,
-            timeout=timeout,
-        )
-
-    async def touch_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        activity: DuplexLeaseActivity,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        return await self._get_duplex_request_client().touch(
-            session_id,
-            fence=fence,
-            activity=activity,
-            timeout=timeout,
-        )
-
-    async def resume_duplex_session_async(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        expected_lease_generation: int,
-        timeout: float | None = 10.0,
-    ) -> dict[str, object]:
-        return await self._get_duplex_request_client().resume(
-            session_id,
-            fence=fence,
-            expected_lease_generation=expected_lease_generation,
-            timeout=timeout,
-        )
-
-    def _get_duplex_request_client(self) -> DuplexRequestClient:
-        client = getattr(self, "_duplex_request_client", None)
-        if client is None:
-            engine = getattr(self, "engine", None)
-            client = DuplexRequestClient(
-                engine,
-                DuplexRequestOutputPort(
-                    request_states=getattr(self, "request_states", {}),
-                    num_stages=getattr(engine, "num_stages", 1),
-                    log_stats=getattr(self, "log_stats", False),
-                    start_output_handler=self._final_output_handler,
-                    process_single_result=self._process_single_result,
-                ),
-            )
-            self._duplex_request_client = client
-        return client
-
-    @staticmethod
-    def _duplex_data_plane_request_info(result: dict[str, object]) -> tuple[str | None, int | None]:
-        return DuplexRequestClient.request_info(result)
-
-    async def _collect_duplex_data_plane_outputs(
-        self,
-        request_id: str,
-        req_state: ClientRequestState,
-        *,
-        response_stage_id: int | None,
-        timeout: float | None,
-    ) -> list[OmniRequestOutput]:
-        return await self._get_duplex_request_client().collect_outputs(
-            request_id,
-            req_state,
-            response_stage_id=response_stage_id,
-            timeout=timeout,
-        )
-
-    @classmethod
-    def _is_direct_duplex_data_plane_response(cls, output: object) -> bool:
-        return DuplexRequestClient.is_direct_response(output)
-
-    @classmethod
-    def _duplex_multimodal_output(cls, output: object) -> dict[str, object]:
-        return DuplexRequestClient.multimodal_output(output)
 
     # ==================== Generate Method ====================
 
@@ -857,198 +494,6 @@ async def encode(
         """
         raise NotImplementedError("AsyncOmni.encode is not implemented.")
 
-    # ==================== Processing Methods ====================
-
-    async def _process_orchestrator_results(
-        self,
-        request_id: str,
-        metrics: OrchestratorMetrics,
-        final_stage_id_for_e2e: int,
-        req_start_ts: dict[str, float],
-        wall_start_ts: float,
-    ) -> AsyncGenerator[OmniRequestOutput, None]:
-        """Read results from the Orchestrator (via the request's asyncio.Queue)
-        and yield OmniRequestOutput objects.
-
-        The Orchestrator handles all stage-to-stage transfers. This method
-        only processes final outputs that arrive on the per-request queue.
-        """
-        req_state = self.request_states.get(request_id)
-        if req_state is None:
-            return
-
-        while True:
-            result = await req_state.queue.get()
-
-            if isinstance(result, ErrorMessage):
-                logger.error(
-                    "[AsyncOmni] Orchestrator error for req=%s stage-%s: %s",
-                    request_id,
-                    result.stage_id,
-                    result.error,
-                )
-                if result.fatal:
-                    raise OmniEngineDeadError(
-                        result.error,
-                        error_stage_id=result.stage_id,
-                    )
-                self._raise_nonfatal_error_message(result)
-
-            if not isinstance(result, OutputMessage):
-                logger.warning("[AsyncOmni] Dropping unexpected per-request message %r", result)
-                continue
-
-            stage_id = result.stage_id
-
-            self._check_engine_output_error(result, request_id, stage_id)
-
-            # Process the result (constructs OmniRequestOutput)
-            output_to_yield = self._process_single_result(
-                result,
-                stage_id,
-                metrics,
-                req_start_ts,
-                wall_start_ts,
-                final_stage_id_for_e2e,
-            )
-
-            if output_to_yield:
-                # Set the external request ID back to the user yielded input
-                output_to_yield.request_id = req_state.external_request_id or output_to_yield.request_id
-                logger.debug(
-                    "[AsyncOmni] req=%s stage-%s yielding final_output_type=%s",
-                    request_id,
-                    stage_id,
-                    getattr(output_to_yield, "final_output_type", None),
-                )
-                yield output_to_yield
-
-            # The Orchestrator sets "finished" when the final stage is done
-            if result.finished:
-                break
-
-    # ==================== Output Handler ====================
-
-    def _final_output_handler(self) -> None:
-        """Start the final output handler if not already running.
-
-        This handler reads messages from the Orchestrator output queue and
-        routes them to per-request asyncio.Queues.
-        """
-        if self.final_output_task is not None:
-            return
-
-        engine = self.engine
-
-        # Event-driven drain (VLLM_OMNI_EVENT_DRIVEN_ORCH=1): block on the
-        # queue's condition variable in a dedicated thread instead of the
-        # get_nowait + 1 ms sleep cadence. Same flag as the orchestrator-side
-        # event-driven loop (vllm_omni/engine/orchestrator.py).
-        from vllm_omni.engine.orchestrator import _event_driven_orch_enabled
-
-        event_driven_drain = _event_driven_orch_enabled() and hasattr(engine, "get_output_blocking_async")
-
-        async def _final_output_loop():
-            """Background coroutine that dispatches final outputs to request queues."""
-            try:
-                while True:
-                    if event_driven_drain:
-                        msg = await engine.get_output_blocking_async(timeout=_FINAL_OUTPUT_BLOCKING_WAIT_S)
-                        if msg is None:
-                            # Timed out with the orchestrator alive; loop for
-                            # the periodic liveness check.
-                            continue
-                    else:
-                        msg = await engine.try_get_output_async()
-                        if msg is None:
-                            await asyncio.sleep(_FINAL_OUTPUT_IDLE_SLEEP_S)
-                            continue
-
-                    if isinstance(msg, dict) and msg.get("type") == "ack":
-                        ack_data = msg.get("ack")
-                        tid = getattr(ack_data, "task_id", "unknown")
-                        logger.info(f"[{self._name}] Intercepted wrapped ACK for task {tid}")
-                        await self.event_resolver.resolve(ack_data)
-                        continue
-                    if isinstance(msg, OmniACK):
-                        logger.info(f"[{self._name}] Intercepted raw ACK object: {msg.task_id}")
-                        await self.event_resolver.resolve(msg)
-                        continue
-                    if hasattr(msg, "task_id"):
-                        tid = getattr(msg, "task_id")
-                        logger.info(f"[{self._name}] Intercepted task-ID object: {tid}")
-                        await self.event_resolver.resolve(msg)
-                        continue
-
-                    if getattr(msg, "type", None) == "duplex_session_lifecycle":
-                        await self.duplex_lifecycle_events.put(msg)
-                        continue
-
-                    if isinstance(msg, ErrorMessage):
-                        # Route request-scoped errors to that request's queue and
-                        # keep the loop alive. A request whose stage replica died
-                        # and was evicted gets a fatal error delivered here; only
-                        # that request fails (its consumer raises), the server
-                        # stays up for other stages/requests (#4285). A fatal
-                        # error without a request_id is a genuine engine-wide
-                        # death and falls through to the except handler below.
-                        if msg.request_id is not None:
-                            req_state = self.request_states.get(msg.request_id)
-                            if req_state is not None:
-                                await req_state.queue.put(msg)
-                            else:
-                                logger.warning(
-                                    "[%s] dropping error for unknown req %s",
-                                    self._name,
-                                    msg.request_id,
-                                )
-                            continue
-                        if not msg.fatal:
-                            continue
-
-                    should_continue, _, stage_id, req_state = self._handle_output_message(msg)
-                    if should_continue:
-                        continue
-
-                    req_state.stage_id = stage_id
-
-                    # Route to the per-request queue
-                    await req_state.queue.put(msg)
-
-            except asyncio.CancelledError:
-                raise
-            except OmniEngineDeadError as e:
-                logger.error("[AsyncOmni] Engine dead: %s", e)
-                for req_state in list(self.request_states.values()):
-                    error_msg = ErrorMessage(
-                        error=str(e),
-                        fatal=True,
-                        request_id=req_state.request_id,
-                        stage_id=e.error_stage_id,
-                    )
-                    await req_state.queue.put(error_msg)
-            except EngineDeadError as e:
-                logger.error("[AsyncOmni] Engine dead: %s", e)
-                for req_state in list(self.request_states.values()):
-                    error_msg = ErrorMessage(
-                        error=str(e),
-                        fatal=True,
-                        request_id=req_state.request_id,
-                    )
-                    await req_state.queue.put(error_msg)
-            except Exception as e:
-                logger.exception("[AsyncOmni] final_output_loop failed.")
-                for req_state in list(self.request_states.values()):
-                    error_msg = ErrorMessage(
-                        request_id=req_state.request_id,
-                        error=str(e),
-                    )
-                    await req_state.queue.put(error_msg)
-                self.final_output_task = None
-
-        self.final_output_task = asyncio.create_task(_final_output_loop())
-        logger.debug("[AsyncOmni] Final output handler started")
-
     # ==================== Control Methods ====================
 
     async def collective_rpc(
@@ -1172,102 +617,6 @@ async def submit_interaction_async(
         if self.log_stats:
             logger.info("[AsyncOmni] Queued interaction for request %s", request_id)
 
-    async def _abort_internal_requests(
-        self,
-        request_id: str | Iterable[str],
-        *,
-        timeout: float = ABORT_TIMEOUT_S,
-    ):
-        """Abort request(s) via the Orchestrator given internal request IDs,
-        which take the format <external_request_id>-<UUID>.
-        """
-        request_ids = [request_id] if isinstance(request_id, str) else list(request_id)
-        # Request IDs are already internal, so we just need to get the matching states.
-        internal_req_ids = [rid for rid in request_ids if rid in self.request_states]
-        try:
-            # Unbind generate() if abort_async blocks in the executor.
-            await asyncio.wait_for(self._abort(internal_req_ids, timeout=timeout), timeout=timeout)
-        except TimeoutError:
-            logger.warning(
-                "[AsyncOmni] Timed out aborting %s after %.1fs; "
-                "engine abort is best-effort until the current batch drains",
-                ",".join(internal_req_ids),
-                timeout,
-            )
-        except Exception:
-            logger.exception("[AsyncOmni] Cleanup abort failed for %s", ",".join(internal_req_ids))
-
-    async def _abort(self, request_ids: list[str], *, timeout: float | None = None) -> None:
-        """Abort request IDs via the engine and enqueue terminal abort outputs.
-
-        Waits for orchestrator abort acknowledgment, enqueues any AR terminal
-        abort outputs (partial tokens) into each request's asyncio queue, then
-        cancels the input pump. Frontend ``request_states`` stay registered so
-        ``generate()`` can consume the terminal message in
-        ``_process_orchestrator_results`` and run normal cleanup.
-
-        When ``abort_async`` returns no output for an active request (OP not
-        registered yet, unbound replica, or orchestrator id drop), enqueue a
-        synthetic finished abort so ``generate()`` cannot hang on ``queue.get``.
-        """
-        abort_outputs = await self.engine.abort_async(request_ids, timeout=timeout) or []
-        delivered: set[str] = set()
-        for output_msg in abort_outputs:
-            req_id = getattr(output_msg, "request_id", None)
-            if req_id is None:
-                continue
-            state = self.request_states.get(req_id)
-            if state is None:
-                logger.debug("[AsyncOmni] Dropping abort output for unknown req %s", req_id)
-                continue
-            await state.queue.put(output_msg)
-            delivered.add(req_id)
-        for rid in request_ids:
-            state = self.request_states.get(rid)
-            if state is not None and rid not in delivered:
-                queue = getattr(state, "queue", None)
-                if queue is not None:
-                    await state.queue.put(self._synthetic_abort_output_message(rid))
-                    delivered.add(rid)
-        for rid in request_ids:
-            self._record_request_failure_once(rid, reason="client_abort")
-            state = self.request_states.get(rid)
-            input_stream_task = getattr(state, "input_stream_task", None)
-            if input_stream_task is not None and not input_stream_task.done():
-                input_stream_task.cancel()
-        if self.log_stats:
-            logger.info("[AsyncOmni] Aborted request(s) %s", ",".join(request_ids))
-
-    @staticmethod
-    def _synthetic_abort_output_message(request_id: str) -> OutputMessage:
-        """Terminal abort OutputMessage used when the engine returned none."""
-        engine_output = OmniRequestOutput(
-            request_id=request_id,
-            finished=True,
-            stage_id=0,
-            final_output_type="text",
-            outputs=[
-                CompletionOutput(
-                    index=0,
-                    text="",
-                    token_ids=[],
-                    cumulative_logprob=None,
-                    logprobs=None,
-                    finish_reason="abort",
-                    stop_reason=None,
-                )
-            ],
-        )
-        return OutputMessage(
-            request_id=request_id,
-            stage_id=0,
-            replica_id=None,
-            engine_outputs=engine_output,
-            metrics=None,
-            finished=True,
-            stage_submit_ts=None,
-        )
-
     def _split_stage_ids_by_type(self, stage_ids: list[int] | None = None) -> tuple[list[int], list[int]]:
         """Split stage ids into AR/LLM (EngineCore) vs diffusion (worker RPC)."""
         n_stages = len(self.engine.stage_clients)
@@ -1697,42 +1046,6 @@ async def pin_lora(self, adapter_id: int) -> bool:
 
     # ==================== Properties ====================
 
-    @property
-    def is_running(self) -> bool:
-        """Check if the engine is running."""
-        orchestrator_alive = self.engine.is_alive()
-        task_alive = self.final_output_task is not None and not self.final_output_task.done()
-        return orchestrator_alive and task_alive
-
-    @property
-    def errored(self) -> bool:
-        """Whether the engine is in a process-fatal error state.
-
-        Delegates to ``OmniBase.errored``, which is true only when the
-        orchestrator thread is dead; per-stage liveness is reported via
-        ``check_health`` instead.  Redeclared here to satisfy the
-        ``EngineClient`` abstract-property requirement (Python's ABC
-        mechanism does not resolve abstract methods from sibling MRO
-        entries).
-        """
-        return OmniBase.errored.fget(self)  # type: ignore[union-attr]
-
-    @property
-    def _name(self) -> str:
-        return "AsyncOrchestrator"
-
-    @property
-    def is_stopped(self) -> bool:
-        """EngineClient abstract property implementation."""
-        return self.errored
-
-    @property
-    def dead_error(self) -> BaseException:
-        """EngineClient abstract property implementation."""
-        return OmniEngineDeadError()
-
-    # ==================== EngineClient Interface ====================
-
     async def get_input_preprocessor(self) -> InputProcessor:
         """Get input preprocessor."""
         return self.input_processor
@@ -1793,16 +1106,3 @@ async def do_log_stats(self) -> None:
     async def get_supported_tasks(self) -> tuple[SupportedTask, ...]:
         """Return the task set exposed by the orchestrator-backed engine."""
         return tuple(self.engine.supported_tasks)
-
-    async def check_health(self) -> None:
-        """Check engine health by verifying the Orchestrator process is alive."""
-        OmniBase.check_health(self)
-
-    # ==================== Shutdown ====================
-
-    def shutdown(self, timeout: float | None = None) -> None:
-        """Shutdown the engine."""
-        if self.final_output_task is not None:
-            self.final_output_task.cancel()
-            self.final_output_task = None
-        OmniBase.shutdown(self)
diff --git a/vllm_omni/entrypoints/async_omni_base.py b/vllm_omni/entrypoints/async_omni_base.py
new file mode 100644
index 00000000000..e7c86de978c
--- /dev/null
+++ b/vllm_omni/entrypoints/async_omni_base.py
@@ -0,0 +1,557 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""AsyncOmniBase: the asyncio-side foundation shared by ``AsyncOmni`` and ``DuplexOmni``.
+
+Owns the engine output pump (one consumer of the engine output queue that
+routes messages to per-request queues, ACK resolvers, or a subclass hook),
+engine-dead fan-out, health/shutdown, and the config accessors. Turn-based
+request handling lives in ``AsyncOmni``; duplex sessions in ``DuplexOmni``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from collections.abc import AsyncGenerator, Iterable
+from typing import Any
+
+from vllm.logger import init_logger
+from vllm.outputs import CompletionOutput
+from vllm.plugins.io_processors import get_io_processor
+from vllm.utils import random_uuid
+from vllm.v1.engine.exceptions import EngineDeadError
+
+from vllm_omni.diffusion.data import OmniACK
+from vllm_omni.engine.messages import ErrorMessage, OutputMessage
+from vllm_omni.entrypoints.omni_base import (
+    OmniBase,
+    OmniEngineDeadError,
+)
+from vllm_omni.metrics.stats import OrchestratorAggregator as OrchestratorMetrics
+from vllm_omni.outputs import OmniRequestOutput
+
+logger = init_logger(__name__)
+_FINAL_OUTPUT_IDLE_SLEEP_S = 0.001
+# Blocking-wait interval for the event-driven final-output drain
+# (VLLM_OMNI_EVENT_DRIVEN_ORCH=1): a message wakes the drain immediately via
+# the janus queue's condition variable; this timeout only bounds how often the
+# orchestrator liveness check runs while the pipeline is idle.
+_FINAL_OUTPUT_BLOCKING_WAIT_S = 1.0
+# Shared DELETE / generate() cleanup abort bound. Env is the documented knob.
+ABORT_TIMEOUT_S = float(os.environ.get("VLLM_OMNI_ABORT_TIMEOUT", 2.0))
+
+
+class AsyncEventResolver:
+    """
+    A generic signal aggregator designed for synchronized handshakes in
+    distributed or multi-stage environments. Supports waiting for a specified
+    number (expected_count) of worker signals in both inline and multiprocess modes.
+    """
+
+    def __init__(self, orchestrator=None):
+        self._pending_tasks: dict[str, dict] = {}
+        self.orchestrator = orchestrator
+        self._lock = asyncio.Lock()
+
+    def watch_task(self, task_id: str, expected_count: int = 1) -> asyncio.Future:
+        loop = asyncio.get_running_loop()
+        fut = loop.create_future()
+        self._pending_tasks[task_id] = {
+            "future": fut,
+            "expected_count": expected_count,
+            "received": [],
+            "start_time": time.time(),
+        }
+        return fut
+
+    async def resolve(self, ack: OmniACK):
+        tid = getattr(ack, "task_id", None)
+
+        if tid is None and isinstance(ack, dict):
+            tid = ack.get("task_id")
+
+        async with self._lock:
+            task_info = self._pending_tasks.get(tid)
+            if task_info is None:
+                logger.warning(f"Received stray ACK for task_id {tid}. Task might have timed out.")
+                return
+
+            task_info["received"].append(ack)
+            current_count = len(task_info["received"])
+            expected = task_info["expected_count"]
+
+            orchestrator = self.orchestrator
+            if orchestrator and hasattr(orchestrator, "metrics") and orchestrator.metrics:
+                freed = getattr(ack, "freed_bytes", 0)
+                if freed == 0 and isinstance(ack, dict):
+                    freed = ack.get("freed_bytes", 0)
+                orchestrator.metrics.record_vram_reclaimed(freed)
+
+            logger.info(f"[Resolver] Task {tid} progress: {current_count}/{expected} ACKs received.")
+
+            if current_count >= expected:
+                self._pending_tasks.pop(tid)
+                fut = task_info["future"]
+                if not fut.done():
+                    elapsed = time.time() - task_info["start_time"]
+                    logger.info(f"[Resolver] Task {tid} completed successfully in {elapsed:.2f}s.")
+                    fut.set_result(task_info["received"])
+
+
+class AsyncOmniBase(OmniBase):
+    """Shared asyncio foundation of the async entrypoints (see module docstring)."""
+
+    def __init__(self, *args: Any, model: str = "", **kwargs: Any) -> None:
+        OmniBase.__init__(self, model=model, **kwargs)
+        self.final_output_task: asyncio.Task | None = None
+        self.event_resolver = AsyncEventResolver(orchestrator=self)
+        self.config_path = self.engine.config_path
+        self.input_processor = self.engine.input_processor
+        self.endpoint_restrictions = self.engine.endpoint_restrictions
+
+        stage_index = self._get_comprehension_stage_index()
+        if stage_index is None:
+            self.io_processor = None
+        else:
+            vllm_config = self.engine.stage_vllm_configs[stage_index]
+            io_processor_plugin = vllm_config.model_config.io_processor_plugin
+            renderer = self.renderer
+            if renderer is None:
+                from vllm.renderers import renderer_from_config
+
+                renderer = renderer_from_config(vllm_config)
+            self.io_processor = get_io_processor(vllm_config, renderer, io_processor_plugin)
+
+    # ==================== Subclass seam ====================
+
+    def _route_engine_message(self, msg: Any) -> bool:
+        """Consume an engine output message the subclass owns (return True when consumed)."""
+        del msg
+        return False
+
+    def _on_engine_dead(self, error: str) -> None:
+        """Seam: the output pump is ending because the engine died (default: nothing).
+
+        ``DuplexOmni`` ends every session handle here; turn-based requests are
+        already failed through their per-request queues.
+        """
+        del error
+
+    def _resolve_transfer_replica(self, stage_id: int, request_id: str) -> int | None:
+        """Look up the sticky-routed replica for (stage_id, request_id).
+
+        Used as the ``replica_resolver`` callback by ``OrchestratorAggregator``
+        to label transfer_* metrics without plumbing replica ids through
+        ``TransferEdgeStats`` / ``StageRequestStats`` / connector adapters.
+        Returns None when stage_id is out of range or the request hasn't been
+        bound to a replica yet — the metric emit then defensive-skips.
+        """
+        pools = getattr(self.engine, "stage_pools", None)
+        if pools is None or not (0 <= stage_id < len(pools)):
+            return None
+        return pools[stage_id].get_bound_replica_id(request_id)
+
+    def _get_comprehension_stage_index(self) -> int | None:
+        fallback_idx: int | None = None
+        for idx, stage_client in enumerate(self.engine.stage_clients):
+            stage_vllm_config = self.engine.stage_vllm_configs[idx]
+            if stage_vllm_config is None:
+                continue
+            if fallback_idx is None:
+                fallback_idx = idx
+            if stage_client.is_comprehension:
+                return idx
+        return fallback_idx
+
+    @property
+    def renderer(self):
+        """Return the renderer from the engine input processor when available."""
+        if self.input_processor is None:
+            return None
+        return self.input_processor.renderer
+
+    @property
+    def vllm_config(self):
+        """Return the vLLM config for the comprehension stage when present."""
+        stage_index = self._get_comprehension_stage_index()
+        if stage_index is None:
+            return None
+        return self.engine.stage_vllm_configs[stage_index]
+
+    async def get_vllm_config(self) -> Any:
+        """Compatibility helper for call sites expecting async vllm config access."""
+        return self.vllm_config
+
+    def get_diffusion_od_config(self) -> Any | None:
+        """Return the diffusion-stage config when the pipeline has one."""
+        saw_diffusion_stage = False
+        for stage_client in self.engine.stage_clients:
+            if getattr(stage_client, "stage_type", None) != "diffusion":
+                continue
+
+            saw_diffusion_stage = True
+
+            od_config = getattr(stage_client, "od_config", None)
+            if od_config is not None:
+                return od_config
+
+            inner_engine = getattr(stage_client, "_engine", None)
+            od_config = getattr(inner_engine, "od_config", None)
+            if od_config is not None:
+                return od_config
+
+        # Out-of-process diffusion clients don't carry od_config (it lives in the
+        # worker); fall back to the engine's model_class_name resolution.
+        if saw_diffusion_stage:
+            return self.engine.get_diffusion_od_config()
+
+        return None
+
+    @property
+    def model_config(self):
+        """Return the model config for the comprehension stage when present."""
+        vllm_config = self.vllm_config
+        if vllm_config is None:
+            return None
+        return vllm_config.model_config
+
+    @staticmethod
+    def _get_unique_request_id(external_request_id: str):
+        """Get a random new request ID for this request; at the server level,
+        this is usually set by the calling entrypoint, but in direct calls, we
+        need to set it explicitly since we do not allow empty IDs.
+
+        NOTE: in the upstream vLLM, this is done in the InputProcessor's
+        `assign_request_id`.
+        """
+        uuid = random_uuid()
+        prefix = "" if not external_request_id else f"{external_request_id}-"
+        return f"{prefix}{uuid:.8}"
+
+    # ==================== Processing Methods ====================
+
+    async def _process_orchestrator_results(
+        self,
+        request_id: str,
+        metrics: OrchestratorMetrics,
+        final_stage_id_for_e2e: int,
+        req_start_ts: dict[str, float],
+        wall_start_ts: float,
+    ) -> AsyncGenerator[OmniRequestOutput, None]:
+        """Read results from the Orchestrator (via the request's asyncio.Queue)
+        and yield OmniRequestOutput objects.
+
+        The Orchestrator handles all stage-to-stage transfers. This method
+        only processes final outputs that arrive on the per-request queue.
+        """
+        req_state = self.request_states.get(request_id)
+        if req_state is None:
+            return
+
+        while True:
+            result = await req_state.queue.get()
+
+            if isinstance(result, ErrorMessage):
+                logger.error(
+                    "[AsyncOmni] Orchestrator error for req=%s stage-%s: %s",
+                    request_id,
+                    result.stage_id,
+                    result.error,
+                )
+                if result.fatal:
+                    raise OmniEngineDeadError(
+                        result.error,
+                        error_stage_id=result.stage_id,
+                    )
+                self._raise_nonfatal_error_message(result)
+
+            if not isinstance(result, OutputMessage):
+                logger.warning("[AsyncOmni] Dropping unexpected per-request message %r", result)
+                continue
+
+            stage_id = result.stage_id
+
+            self._check_engine_output_error(result, request_id, stage_id)
+
+            # Process the result (constructs OmniRequestOutput)
+            output_to_yield = self._process_single_result(
+                result,
+                stage_id,
+                metrics,
+                req_start_ts,
+                wall_start_ts,
+                final_stage_id_for_e2e,
+            )
+
+            if output_to_yield:
+                # Set the external request ID back to the user yielded input
+                output_to_yield.request_id = req_state.external_request_id or output_to_yield.request_id
+                logger.debug(
+                    "[AsyncOmni] req=%s stage-%s yielding final_output_type=%s",
+                    request_id,
+                    stage_id,
+                    getattr(output_to_yield, "final_output_type", None),
+                )
+                yield output_to_yield
+
+            # The Orchestrator sets "finished" when the final stage is done
+            if result.finished:
+                break
+
+    # ==================== Output Handler ====================
+
+    def _final_output_handler(self) -> None:
+        """Start the final output handler if not already running.
+
+        This handler reads messages from the Orchestrator output queue and
+        routes them to per-request asyncio.Queues.
+        """
+        if self.final_output_task is not None:
+            return
+
+        engine = self.engine
+
+        # Event-driven drain (VLLM_OMNI_EVENT_DRIVEN_ORCH=1): block on the
+        # queue's condition variable in a dedicated thread instead of the
+        # get_nowait + 1 ms sleep cadence. Same flag as the orchestrator-side
+        # event-driven loop (vllm_omni/engine/orchestrator.py).
+        from vllm_omni.engine.orchestrator import _event_driven_orch_enabled
+
+        event_driven_drain = _event_driven_orch_enabled() and hasattr(engine, "get_output_blocking_async")
+
+        async def _final_output_loop():
+            """Background coroutine that dispatches final outputs to request queues."""
+            try:
+                while True:
+                    if event_driven_drain:
+                        msg = await engine.get_output_blocking_async(timeout=_FINAL_OUTPUT_BLOCKING_WAIT_S)
+                        if msg is None:
+                            # Timed out with the orchestrator alive; loop for
+                            # the periodic liveness check.
+                            continue
+                    else:
+                        msg = await engine.try_get_output_async()
+                        if msg is None:
+                            await asyncio.sleep(_FINAL_OUTPUT_IDLE_SLEEP_S)
+                            continue
+
+                    if self._route_engine_message(msg):
+                        continue
+
+                    if isinstance(msg, dict) and msg.get("type") == "ack":
+                        ack_data = msg.get("ack")
+                        tid = getattr(ack_data, "task_id", "unknown")
+                        logger.info(f"[{self._name}] Intercepted wrapped ACK for task {tid}")
+                        await self.event_resolver.resolve(ack_data)
+                        continue
+                    if isinstance(msg, OmniACK):
+                        logger.info(f"[{self._name}] Intercepted raw ACK object: {msg.task_id}")
+                        await self.event_resolver.resolve(msg)
+                        continue
+                    if hasattr(msg, "task_id"):
+                        tid = getattr(msg, "task_id")
+                        logger.info(f"[{self._name}] Intercepted task-ID object: {tid}")
+                        await self.event_resolver.resolve(msg)
+                        continue
+
+                    if isinstance(msg, ErrorMessage):
+                        # Route request-scoped errors to that request's queue and
+                        # keep the loop alive. A request whose stage replica died
+                        # and was evicted gets a fatal error delivered here; only
+                        # that request fails (its consumer raises), the server
+                        # stays up for other stages/requests (#4285). A fatal
+                        # error without a request_id is a genuine engine-wide
+                        # death and falls through to the except handler below.
+                        if msg.request_id is not None:
+                            req_state = self.request_states.get(msg.request_id)
+                            if req_state is not None:
+                                await req_state.queue.put(msg)
+                            else:
+                                logger.warning(
+                                    "[%s] dropping error for unknown req %s",
+                                    self._name,
+                                    msg.request_id,
+                                )
+                            continue
+                        if not msg.fatal:
+                            continue
+
+                    should_continue, _, stage_id, req_state = self._handle_output_message(msg)
+                    if should_continue:
+                        continue
+
+                    req_state.stage_id = stage_id
+
+                    # Route to the per-request queue
+                    await req_state.queue.put(msg)
+
+            except asyncio.CancelledError:
+                raise
+            except OmniEngineDeadError as e:
+                logger.error("[%s] Engine dead: %s", self._name, e)
+                for req_state in list(self.request_states.values()):
+                    error_msg = ErrorMessage(
+                        error=str(e),
+                        fatal=True,
+                        request_id=req_state.request_id,
+                        stage_id=e.error_stage_id,
+                    )
+                    await req_state.queue.put(error_msg)
+                self._on_engine_dead(str(e))
+            except EngineDeadError as e:
+                logger.error("[%s] Engine dead: %s", self._name, e)
+                for req_state in list(self.request_states.values()):
+                    error_msg = ErrorMessage(
+                        error=str(e),
+                        fatal=True,
+                        request_id=req_state.request_id,
+                    )
+                    await req_state.queue.put(error_msg)
+                self._on_engine_dead(str(e))
+            except Exception as e:
+                logger.exception("[%s] final_output_loop failed.", self._name)
+                for req_state in list(self.request_states.values()):
+                    error_msg = ErrorMessage(
+                        request_id=req_state.request_id,
+                        error=str(e),
+                    )
+                    await req_state.queue.put(error_msg)
+                self.final_output_task = None
+                self._on_engine_dead(str(e))
+
+        self.final_output_task = asyncio.create_task(_final_output_loop())
+        logger.debug("[AsyncOmni] Final output handler started")
+
+    async def _abort_internal_requests(
+        self,
+        request_id: str | Iterable[str],
+        *,
+        timeout: float = ABORT_TIMEOUT_S,
+    ):
+        """Abort request(s) via the Orchestrator given internal request IDs,
+        which take the format <external_request_id>-<UUID>.
+        """
+        request_ids = [request_id] if isinstance(request_id, str) else list(request_id)
+        # Request IDs are already internal, so we just need to get the matching states.
+        internal_req_ids = [rid for rid in request_ids if rid in self.request_states]
+        try:
+            # Unbind generate() if abort_async blocks in the executor.
+            await asyncio.wait_for(self._abort(internal_req_ids, timeout=timeout), timeout=timeout)
+        except TimeoutError:
+            logger.warning(
+                "[AsyncOmni] Timed out aborting %s after %.1fs; "
+                "engine abort is best-effort until the current batch drains",
+                ",".join(internal_req_ids),
+                timeout,
+            )
+        except Exception:
+            logger.exception("[AsyncOmni] Cleanup abort failed for %s", ",".join(internal_req_ids))
+
+    async def _abort(self, request_ids: list[str], *, timeout: float | None = None) -> None:
+        """Abort request IDs via the engine and enqueue terminal abort outputs.
+
+        Waits for orchestrator abort acknowledgment, enqueues any AR terminal
+        abort outputs (partial tokens) into each request's asyncio queue, then
+        cancels the input pump. Frontend ``request_states`` stay registered so
+        ``generate()`` can consume the terminal message in
+        ``_process_orchestrator_results`` and run normal cleanup.
+
+        When ``abort_async`` returns no output for an active request (OP not
+        registered yet, unbound replica, or orchestrator id drop), enqueue a
+        synthetic finished abort so ``generate()`` cannot hang on ``queue.get``.
+        """
+        abort_outputs = await self.engine.abort_async(request_ids, timeout=timeout) or []
+        delivered: set[str] = set()
+        for output_msg in abort_outputs:
+            req_id = getattr(output_msg, "request_id", None)
+            if req_id is None:
+                continue
+            state = self.request_states.get(req_id)
+            if state is None:
+                logger.debug("[AsyncOmni] Dropping abort output for unknown req %s", req_id)
+                continue
+            await state.queue.put(output_msg)
+            delivered.add(req_id)
+        for rid in request_ids:
+            state = self.request_states.get(rid)
+            if state is not None and rid not in delivered:
+                queue = getattr(state, "queue", None)
+                if queue is not None:
+                    await state.queue.put(self._synthetic_abort_output_message(rid))
+                    delivered.add(rid)
+        for rid in request_ids:
+            self._record_request_failure_once(rid, reason="client_abort")
+            state = self.request_states.get(rid)
+            input_stream_task = getattr(state, "input_stream_task", None)
+            if input_stream_task is not None and not input_stream_task.done():
+                input_stream_task.cancel()
+        if self.log_stats:
+            logger.info("[AsyncOmni] Aborted request(s) %s", ",".join(request_ids))
+
+    @staticmethod
+    def _synthetic_abort_output_message(request_id: str) -> OutputMessage:
+        """Terminal abort OutputMessage used when the engine returned none."""
+        engine_output = OmniRequestOutput(
+            request_id=request_id,
+            finished=True,
+            stage_id=0,
+            final_output_type="text",
+            outputs=[
+                CompletionOutput(
+                    index=0,
+                    text="",
+                    token_ids=[],
+                    cumulative_logprob=None,
+                    logprobs=None,
+                    finish_reason="abort",
+                    stop_reason=None,
+                )
+            ],
+        )
+        return OutputMessage(
+            request_id=request_id,
+            stage_id=0,
+            replica_id=None,
+            engine_outputs=engine_output,
+            metrics=None,
+            finished=True,
+            stage_submit_ts=None,
+        )
+
+    @property
+    def is_running(self) -> bool:
+        """Check if the engine is running."""
+        orchestrator_alive = self.engine.is_alive()
+        task_alive = self.final_output_task is not None and not self.final_output_task.done()
+        return orchestrator_alive and task_alive
+
+    @property
+    def _name(self) -> str:
+        return type(self).__name__
+
+    @property
+    def is_stopped(self) -> bool:
+        """EngineClient abstract property implementation."""
+        return self.errored
+
+    @property
+    def dead_error(self) -> BaseException:
+        """EngineClient abstract property implementation."""
+        return OmniEngineDeadError()
+
+    # ==================== EngineClient Interface ====================
+
+    async def check_health(self) -> None:
+        """Check engine health by verifying the Orchestrator process is alive."""
+        OmniBase.check_health(self)
+
+    # ==================== Shutdown ====================
+
+    def shutdown(self, timeout: float | None = None) -> None:
+        """Shutdown the engine."""
+        if self.final_output_task is not None:
+            self.final_output_task.cancel()
+            self.final_output_task = None
+        OmniBase.shutdown(self)
diff --git a/vllm_omni/entrypoints/cli/benchmark/cli_args.py b/vllm_omni/entrypoints/cli/benchmark/cli_args.py
index 21f52895456..62695129816 100644
--- a/vllm_omni/entrypoints/cli/benchmark/cli_args.py
+++ b/vllm_omni/entrypoints/cli/benchmark/cli_args.py
@@ -206,8 +206,10 @@ def add_seed_tts_cli_args(parser: argparse.ArgumentParser) -> None:
         "--seed-tts-turns-per-session",
         type=int,
         default=1,
-        help="Group this many Seed-TTS target texts into one Realtime session. "
-        "The first row's reference audio and transcript are reused for every turn.",
+        help="Group this many Seed-TTS target texts into one benchmark request. "
+        "The first row's reference audio and transcript are reused for every turn. "
+        "A model-native duplex session takes its target text once, in the session "
+        "context, so each turn runs in its own session.",
     )
     group.add_argument(
         "--seed-tts-root",
diff --git a/vllm_omni/entrypoints/duplex/__init__.py b/vllm_omni/entrypoints/duplex/__init__.py
index 736e98a6aae..327eab07fbe 100644
--- a/vllm_omni/entrypoints/duplex/__init__.py
+++ b/vllm_omni/entrypoints/duplex/__init__.py
@@ -1,6 +1,13 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-from .websocket import DuplexWebSocketActor
+"""Thin websocket serving for engine-resident duplex sessions.
 
-__all__ = ["DuplexWebSocketActor"]
+The session logic lives in ``vllm_omni.engine.duplex`` and is reached through
+``vllm_omni.entrypoints.duplex_omni.DuplexOmni``; this package only speaks the
+OpenAI Realtime wire protocol over ``/v1/realtime?duplex=1``.
+"""
+
+from .serving import OmniDuplexSessionHandler
+
+__all__ = ["OmniDuplexSessionHandler"]
diff --git a/vllm_omni/entrypoints/duplex/audio_encoding.py b/vllm_omni/entrypoints/duplex/audio_encoding.py
new file mode 100644
index 00000000000..f790b029b0c
--- /dev/null
+++ b/vllm_omni/entrypoints/duplex/audio_encoding.py
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Audio encoding for duplex model output (entrypoint layer, injected into ``DuplexOmniEngine``)."""
+
+from __future__ import annotations
+
+import numpy as np
+from vllm.logger import init_logger
+
+logger = init_logger(__name__)
+
+
+def encode_audio(
+    audio_data: object,
+    sample_rate_hz: int,
+    response_format: str,
+    speed: float | None,
+) -> str | None:
+    """Encode a model audio tensor/array into base64 in ``response_format``.
+
+    Moved from the serving runtime bridge; uses the shared ``AudioMixin``
+    encoder directly instead of going through the chat service.
+    """
+    if audio_data is None:
+        return None
+    try:
+        import torch
+
+        from vllm_omni.entrypoints.openai.audio_utils_mixin import AudioMixin
+        from vllm_omni.entrypoints.openai.protocol.audio import CreateAudio
+
+        if isinstance(audio_data, torch.Tensor):
+            audio_tensor = audio_data.detach().cpu().float().numpy()
+        else:
+            audio_tensor = np.asarray(audio_data, dtype=np.float32)
+        if audio_tensor.ndim > 1:
+            audio_tensor = audio_tensor.reshape(-1)
+        audio_response = AudioMixin().create_audio(
+            CreateAudio(
+                audio_tensor=audio_tensor,
+                sample_rate=sample_rate_hz,
+                response_format=response_format,
+                speed=float(speed) if isinstance(speed, int | float) and speed > 0 else 1.0,
+                stream_format="audio",
+                base64_encode=True,
+            )
+        )
+        return str(audio_response.audio_data)
+    except Exception:
+        logger.exception("Failed to encode duplex data-plane audio output")
+        return None
+
+
+__all__ = ["encode_audio"]
diff --git a/vllm_omni/entrypoints/duplex/capability.py b/vllm_omni/entrypoints/duplex/capability.py
deleted file mode 100644
index 50126886be4..00000000000
--- a/vllm_omni/entrypoints/duplex/capability.py
+++ /dev/null
@@ -1,34 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from vllm.logger import init_logger
-
-logger = init_logger(__name__)
-
-
-def should_enable_duplex_endpoint(
-    stage_configs: list | None,
-    *,
-    config_path: str | None = None,
-) -> bool:
-    """Enable the realtime session handler for explicitly configured deployments."""
-    if stage_configs:
-        for stage in stage_configs:
-            session_mode = (
-                stage.get("session_mode") if isinstance(stage, dict) else getattr(stage, "session_mode", None)
-            )
-            if session_mode == "duplex":
-                return True
-    if config_path:
-        try:
-            from vllm_omni.config.stage_config import resolve_deploy_yaml
-
-            raw_config = resolve_deploy_yaml(config_path)
-            if raw_config.get("session_mode") == "duplex" or isinstance(raw_config.get("duplex_session"), dict):
-                return True
-        except Exception as exc:
-            logger.warning("Failed to inspect realtime session configuration from %s: %s", config_path, exc)
-    return False
-
-
-__all__ = ["should_enable_duplex_endpoint"]
diff --git a/vllm_omni/entrypoints/duplex/chat_fallback.py b/vllm_omni/entrypoints/duplex/chat_fallback.py
deleted file mode 100644
index bd682c4f34f..00000000000
--- a/vllm_omni/entrypoints/duplex/chat_fallback.py
+++ /dev/null
@@ -1,302 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-import json
-from collections.abc import AsyncGenerator
-from functools import partial
-from typing import Any
-
-from vllm.entrypoints.openai.chat_completion.protocol import ChatCompletionRequest
-from vllm.entrypoints.serve.engine.protocol import ErrorResponse
-from vllm.logger import init_logger
-
-from vllm_omni.entrypoints.duplex.protocol import DuplexSession
-
-logger = init_logger(__name__)
-
-
-class ChatFallbackProjectorMixin:
-    """Project generic chat completion output into duplex response events."""
-
-    async def _run_response(self, session: DuplexSession, send_json) -> None:
-        response_id = session.begin_response()
-        epoch = session.epoch
-        request_id = f"duplex-{session.session_id}-{epoch}-{session.input_commit_seq}"
-        session.bind_request(f"chatcmpl-{request_id}")
-        await send_json(
-            self._response_created_payload(
-                session,
-                response_id,
-                epoch=epoch,
-                request_id=session.active_request_id,
-            )
-        )
-
-        try:
-            request = self._build_chat_request(session, request_id)
-            result = await self._chat_service.create_chat_completion(request, raw_request=None)
-            if isinstance(result, ErrorResponse):
-                error = result.error
-                await send_json(
-                    {
-                        "type": "error",
-                        "error": error.message if error else "Chat request failed",
-                        "code": error.type if error else "chat_error",
-                    }
-                )
-                session.end_response(commit_text=False)
-                return
-            if hasattr(result, "__aiter__"):
-                await self._drain_streaming_response(session, result, epoch, response_id, send_json)
-            else:
-                await self._emit_full_response(session, result, epoch, response_id, send_json)
-            if session.epoch == epoch:
-                final_stage_metrics = session.accumulate_response_stage_metrics(None)
-                should_commit = self._should_commit_response_to_history(session, response_id)
-                committed_message = session.end_response(commit_text=should_commit)
-                if should_commit:
-                    session.register_history_item(f"item_{response_id}", committed_message)
-                done_payload: dict[str, object] = {
-                    "type": "response.done",
-                    "session_id": session.session_id,
-                    "response_id": response_id,
-                    "epoch": epoch,
-                    "committed": committed_message is not None,
-                    "playback": session.playback.as_dict(),
-                }
-                if final_stage_metrics:
-                    done_payload["vllm_omni"] = {"stage_metrics": final_stage_metrics}
-                await send_json(done_payload)
-        except asyncio.CancelledError:
-            raise
-        except Exception as exc:
-            logger.exception("Duplex response failed: %s", exc)
-            session.end_response(commit_text=False)
-            await send_json(
-                {
-                    "type": "error",
-                    "session_id": session.session_id,
-                    "response_id": response_id,
-                    "error": str(exc),
-                    "code": "response_error",
-                }
-            )
-
-    def _build_chat_request(self, session: DuplexSession, request_id: str) -> ChatCompletionRequest:
-        response_config = session.response_config
-        messages: list[dict[str, object]] = []
-        if response_config.instructions:
-            messages.append({"role": "system", "content": response_config.instructions})
-        messages.extend(session.history)
-
-        kwargs: dict[str, Any] = {
-            "model": response_config.model or self._chat_service.model_config.model,
-            "messages": messages,
-            "stream": True,
-        }
-        if response_config.temperature is not None:
-            kwargs["temperature"] = response_config.temperature
-        if response_config.max_tokens is not None:
-            kwargs["max_tokens"] = response_config.max_tokens
-        model_extra = dict(response_config.extra_body)
-        model_extra.pop("native_duplex", None)
-        model_extra.pop("minicpmo45_native_duplex", None)
-        tools = model_extra.pop("realtime_response_tools", model_extra.pop("realtime_tools", None))
-        tool_choice = model_extra.pop(
-            "realtime_response_tool_choice",
-            model_extra.pop("realtime_tool_choice", None),
-        )
-        for protocol_key in (
-            "realtime_response_conversation",
-            "realtime_response_metadata",
-            "realtime_response_prompt",
-        ):
-            model_extra.pop(protocol_key, None)
-        kwargs.update(model_extra)
-        if "audio" in response_config.modalities:
-            audio_options = kwargs.get("audio")
-            audio_options = dict(audio_options) if isinstance(audio_options, dict) else {}
-            # Chat defaults to WAV. Request the session's internal output format
-            # explicitly rather than relabeling the returned bytes as PCM.
-            audio_options["format"] = response_config.response_format
-            kwargs["audio"] = audio_options
-        if isinstance(tools, list):
-            kwargs["tools"] = tools
-        if isinstance(tool_choice, str | dict):
-            kwargs["tool_choice"] = tool_choice
-
-        request = ChatCompletionRequest(**kwargs)
-        object.__setattr__(request, "modalities", response_config.modalities)
-        object.__setattr__(request, "request_id", request_id)
-        object.__setattr__(
-            request,
-            "chat_template_kwargs",
-            {"use_tts_template": response_config.use_tts_template},
-        )
-        return request
-
-    async def _drain_streaming_response(
-        self,
-        session: DuplexSession,
-        result: AsyncGenerator[str, None],
-        epoch: int,
-        response_id: str,
-        send_json,
-    ) -> None:
-        async for raw_chunk in result:
-            if session.epoch != epoch:
-                return
-            for payload in self._parse_sse_payloads(raw_chunk):
-                if payload == "[DONE]":
-                    continue
-                if isinstance(payload, dict):
-                    await self._emit_chat_payload(session, payload, epoch, response_id, send_json)
-
-    async def _emit_full_response(
-        self,
-        session: DuplexSession,
-        result: Any,
-        epoch: int,
-        response_id: str,
-        send_json,
-    ) -> None:
-        if hasattr(result, "model_dump"):
-            payload = result.model_dump(mode="json", exclude_unset=True)
-        else:
-            payload = {"response": str(result)}
-        await self._emit_chat_payload(session, payload, epoch, response_id, send_json)
-
-    def _parse_sse_payloads(self, raw_chunk: str) -> list[dict[str, object] | str]:
-        payloads: list[dict[str, object] | str] = []
-        for line in raw_chunk.splitlines():
-            line = line.strip()
-            if not line.startswith("data:"):
-                continue
-            data = line[5:].strip()
-            if not data:
-                continue
-            if data == "[DONE]":
-                payloads.append(data)
-                continue
-            try:
-                parsed = json.loads(data)
-            except json.JSONDecodeError:
-                logger.debug("Skipping non-JSON duplex stream payload: %s", data)
-                continue
-            if isinstance(parsed, dict):
-                payloads.append(parsed)
-        return payloads
-
-    async def _emit_chat_payload(
-        self,
-        session: DuplexSession,
-        payload: dict[str, object],
-        epoch: int,
-        response_id: str,
-        send_json,
-    ) -> None:
-        if session.epoch != epoch or session.active_response_id != response_id:
-            return
-        metrics = payload.get("metrics")
-        stage_metrics = metrics.get("stage_metrics") if isinstance(metrics, dict) else None
-        if isinstance(stage_metrics, dict):
-            session.replace_response_stage_metric_snapshots(stage_metrics)
-
-        modality = payload.get("modality")
-        if modality not in {None, "text", "audio"}:
-            await send_json(
-                {
-                    "type": "error",
-                    "session_id": session.session_id,
-                    "response_id": response_id,
-                    "epoch": epoch,
-                    "code": "unsupported_response_modality",
-                    "error": f"Unsupported chat response modality: {modality}",
-                }
-            )
-            return
-        choices = payload.get("choices")
-        if not isinstance(choices, list):
-            await send_json(
-                {
-                    "type": "response.message",
-                    "session_id": session.session_id,
-                    "response_id": response_id,
-                    "epoch": epoch,
-                    "payload": payload,
-                }
-            )
-            return
-
-        for choice in choices:
-            if not isinstance(choice, dict):
-                continue
-            delta = choice.get("delta")
-            message = choice.get("message")
-            content = None
-            if isinstance(delta, dict):
-                content = delta.get("content")
-            elif isinstance(message, dict):
-                content = message.get("content")
-
-            if isinstance(content, str) and content:
-                if modality != "audio":
-                    session.append_assistant_text(content)
-                    await send_json(
-                        {
-                            "type": "response.text.delta",
-                            "session_id": session.session_id,
-                            "response_id": response_id,
-                            "epoch": epoch,
-                            "delta": content,
-                        }
-                    )
-
-            audio_content = content if modality == "audio" else None
-            if isinstance(message, dict):
-                message_audio = message.get("audio")
-                if isinstance(message_audio, dict):
-                    audio_content = message_audio.get("data")
-            if isinstance(audio_content, str) and audio_content:
-                # The OpenAI package imports duplex serving during initialization.
-                # Defer this import until chat fallback has finished loading.
-                from vllm_omni.entrypoints.openai.protocol.audio import AudioChunkMetadata
-
-                audio_metadata = AudioChunkMetadata.model_validate(choice.get("audio_metadata"))
-                duration_ms = session.record_generated_audio(
-                    response_id,
-                    frame_count=audio_metadata.frame_count,
-                    sample_rate_hz=audio_metadata.sample_rate_hz,
-                )
-                if duration_ms is None:
-                    return
-                await send_json(
-                    {
-                        "type": "response.output_audio.delta",
-                        "session_id": session.session_id,
-                        "response_id": response_id,
-                        "epoch": epoch,
-                        "audio": audio_content,
-                        "format": audio_metadata.format,
-                        "sample_rate_hz": audio_metadata.sample_rate_hz,
-                        "channels": audio_metadata.channels,
-                        "audio_duration_ms": duration_ms,
-                    },
-                    on_accepted=partial(session.mark_audio_sent, duration_ms, response_id=response_id),
-                )
-
-            finish_reason = choice.get("finish_reason")
-            if finish_reason is not None and modality != "audio":
-                await send_json(
-                    {
-                        "type": "response.output_item.done",
-                        "session_id": session.session_id,
-                        "response_id": response_id,
-                        "epoch": epoch,
-                        "finish_reason": finish_reason,
-                        "modality": modality,
-                    }
-                )
diff --git a/vllm_omni/entrypoints/duplex/realtime_input.py b/vllm_omni/entrypoints/duplex/realtime_input.py
index 386b4cfc3d2..be700ef6279 100644
--- a/vllm_omni/entrypoints/duplex/realtime_input.py
+++ b/vllm_omni/entrypoints/duplex/realtime_input.py
@@ -1,1584 +1,179 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-from __future__ import annotations
+"""Thin OpenAI Realtime wire envelope for one websocket connection.
+
+Everything that needed session state now lives engine-side
+(``vllm_omni.engine.duplex.realtime_commands`` for the command mapping,
+``vllm_omni.engine.duplex.realtime_events`` for the projection state). What is
+left here is the per-connection handshake policy (query-param defaults,
+autostart / resume-only rules, ``session.resume`` parsing), the wire defaults
+used to translate appends, and error rendering through the typed
+:class:`~vllm_omni.engine.duplex.events.ErrorEvent`.
+"""
 
-import asyncio
-import base64
-import binascii
-from collections.abc import Callable
-from uuid import uuid4
+from __future__ import annotations
 
-import numpy as np
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
 
-from vllm_omni.entrypoints.duplex.audio import (
-    convert_input_audio_with_rate,
-    encode_float32_mono_wav_base64,
-    validate_input_sample_rate_hz,
-)
-from vllm_omni.entrypoints.duplex.protocol import normalize_native_duplex_key
-from vllm_omni.entrypoints.duplex.realtime_state import (
-    REALTIME_INPUT_AUDIO_FORMATS,
-    REALTIME_OUTPUT_AUDIO_FORMATS,
-    RealtimeStateOwner,
-    realtime_default_sample_rate_hz,
+from vllm_omni.engine.duplex.commands import DuplexCommand, DuplexCommandError
+from vllm_omni.engine.duplex.events import error_event
+from vllm_omni.engine.duplex.realtime_commands import (
+    RealtimeInputDefaults,
+    translate_realtime_command,
 )
-from vllm_omni.entrypoints.duplex.server_vad import ServerVADConfig, parse_session_turn_detection
 
+if TYPE_CHECKING:
+    from starlette.websockets import WebSocket
 
-class RealtimeInputTranslator(RealtimeStateOwner):
-    """Translate and validate client Realtime events for the duplex core."""
+__all__ = ["RealtimeEnvelope", "RealtimeHandshake", "ResumeRequest", "parse_resume_request"]
 
-    _opened: bool
-    _initial_session_update: bool
-    _input_speech_started: bool
-    _input_audio_buffer_has_audio: bool
-    _input_audio_buffer_had_non_speech: bool
-    _input_audio_buffer_transcript_parts: list[str]
-    _active_input_item_id: str | None
-    _last_conversation_item_id: str | None
-    _active_response_id: str | None
-    _last_response_id: str | None
-    _input_audio_format: str
-    _output_audio_format: str
-    _input_sample_rate_hz: int
-    _conversation_items: dict[str, dict[str, object]]
-    _item_truncation_cursors: dict[str, tuple[int, int]]
-    _pending_outbound: asyncio.Queue[dict[str, object]]
+_TRUE_VALUES = {"1", "true", "yes", "on"}
+_FALSE_VALUES = {"0", "false", "no", "off"}
 
-    async def _send_realtime_payload(self, payload: dict[str, object]) -> None:
-        raise NotImplementedError
+#: Client events the envelope handles itself (never translated into commands).
+#: ``conversation.item.retrieve`` is deliberately absent: the conversation items
+#: it reads live engine-side, so it travels as a command like any other event.
+ENVELOPE_EVENT_TYPES = frozenset({"session.resume", "session.event_ack"})
 
-    def _realtime_error_payload(
-        self,
-        code: str,
-        message: str,
-        *,
-        event_id: object | None = None,
-        param: object | None = None,
-    ) -> dict[str, object]:
-        raise NotImplementedError
 
-    _response_is_done: Callable[[object], bool]
+@dataclass(frozen=True, slots=True)
+class RealtimeHandshake:
+    """What the first client message asks for."""
 
-    @property
-    def _turn_based_server_vad(self) -> bool:
-        return self._turn_detection is not None and not self._native_input_append
+    #: ``"open"`` (session object in ``session_payload``) or ``"resume"`` (resume payload).
+    kind: str
+    session_payload: dict[str, object] = field(default_factory=dict)
+    resume_payload: dict[str, object] = field(default_factory=dict)
+    #: A client event that arrived before the session existed and must run right after opening.
+    pending_command_payload: dict[str, object] | None = None
 
-    def _reset_realtime_input_buffer_state(self) -> None:
-        self._input_speech_started = False
-        self._active_input_item_id = None
-        self._input_audio_buffer_has_audio = False
-        self._input_audio_buffer_had_non_speech = False
-        self._input_audio_buffer_transcript_parts.clear()
 
-    async def discard_pending_input_audio(
-        self,
-        *,
-        audio_end_ms: int | None = None,
-    ) -> None:
-        """Drop Realtime input-buffer state that was consumed as overlap.
+@dataclass(frozen=True, slots=True)
+class ResumeRequest:
+    """A validated ``session.resume`` client event."""
 
-        The serving overlap policy may classify a short acknowledgement such
-        as "continue" as a side-channel signal instead of user turn input. The
-        Realtime protocol has already observed the append and may have emitted
-        ``speech_started``; reset that transient buffer so a later commit does
-        not accidentally attach the acknowledgement transcript/audio to the
-        next real user turn.
-        """
-        if self._input_speech_started and self._active_input_item_id is not None:
-            await self._send_realtime_payload(
-                {
-                    "type": "input_audio_buffer.speech_stopped",
-                    "audio_end_ms": max(0, int(audio_end_ms or 0)),
-                    "item_id": self._active_input_item_id,
-                }
-            )
-        self._reset_realtime_input_buffer_state()
+    session_id: str
+    resume_token: str
+    last_received_server_event_seq: int
 
-    async def _send_realtime_input_ack(self, event: dict[str, object]) -> None:
-        if event.get("type") != "conversation.item.create":
-            return
-        item = event.get("item")
-        if not isinstance(item, dict):
-            return
-        previous_item_id = event.get("previous_item_id")
-        if isinstance(previous_item_id, str):
-            item["_previous_item_id"] = previous_item_id
-        if item.get("role") != "user":
-            return
-        self._conversation_items[str(item["id"])] = item
-        for payload in self._conversation_item_added_events(item):
-            await self._send_realtime_payload(payload)
 
-    async def _to_duplex_event(self, event: dict[str, object]) -> dict[str, object] | None:
-        event_type = event.get("type")
-        if event_type == "session.update":
-            session = event.get("session")
-            session_payload: dict[str, object] = session if isinstance(session, dict) else event
-            try:
-                turn_detection_configured, server_vad = parse_session_turn_detection(session_payload)
-            except ValueError as exc:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "unsupported_turn_detection",
-                        str(exc),
-                        event_id=event.get("event_id"),
-                        param="turn_detection",
-                    )
-                )
-                return None
-            normalized_turn_detection = server_vad.as_dict() if server_vad is not None else None
-            previous_protocol_config = self._realtime_protocol_config()
-            try:
-                self._apply_realtime_session_defaults(session_payload)
-            except ValueError as exc:
-                self._set_realtime_protocol_config(previous_protocol_config)
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "unsupported_audio_format",
-                        str(exc),
-                        event_id=event.get("event_id"),
-                        param="audio.input.format",
-                    )
-                )
-                return None
-            turn_detection_error = self._validate_realtime_turn_detection(
-                session_payload,
-                configured=turn_detection_configured,
-                normalized=normalized_turn_detection,
-            )
-            if turn_detection_error is not None:
-                self._set_realtime_protocol_config(previous_protocol_config)
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "unsupported_turn_detection",
-                        turn_detection_error,
-                        event_id=event.get("event_id"),
-                        param="turn_detection",
-                    )
-                )
-                return None
-            turn_detection_candidate = self._prepare_realtime_turn_detection_update(
-                session_payload,
-                configured=turn_detection_configured,
-                normalized=normalized_turn_detection,
-            )
-            try:
-                session_payload.update(self._realtime_overlap_fields(session_payload))
-                if not self._opened:
-                    self._opened = True
-                    self._initial_session_update = True
-                    translated = self._session_create_from_realtime(session_payload)
-                    event_id = event.get("event_id")
-                    if isinstance(event_id, str) and event_id:
-                        translated["_realtime_event_id"] = event_id
-                else:
-                    translated = {
-                        "type": "turn.signal",
-                        "event": "session.update",
-                        "payload": session_payload,
-                        "realtime_event_id": event.get("event_id"),
-                    }
-                candidate_protocol_config = self._realtime_protocol_config()
-            finally:
-                self._set_realtime_protocol_config(previous_protocol_config)
-            if turn_detection_candidate[0] or candidate_protocol_config != previous_protocol_config:
-                self._pending_turn_detection_update = (
-                    *turn_detection_candidate,
-                    asyncio.Event(),
-                    candidate_protocol_config,
-                )
-            return translated
-        if event_type == "conversation.item.create":
-            return await self._conversation_item_to_duplex(event)
-        if event_type == "conversation.item.delete":
-            item_id = event.get("item_id")
-            if not isinstance(item_id, str) or not item_id:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "missing_item_id",
-                        "conversation.item.delete requires item_id",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            if item_id not in self._conversation_items:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "item_not_found",
-                        f"Conversation item not found: {item_id}",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            self._remove_conversation_item(item_id)
-            await self._pending_outbound.put(
-                {
-                    "type": "turn.signal",
-                    "event": "conversation.item.delete",
-                    "payload": {"item_id": item_id},
-                }
-            )
-            return None
-        if event_type == "conversation.item.retrieve":
-            item_id = event.get("item_id")
-            if not isinstance(item_id, str) or not item_id:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "missing_item_id",
-                        "conversation.item.retrieve requires item_id",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            item = self._conversation_items.get(item_id)
-            if item is None:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "item_not_found",
-                        f"Conversation item not found: {item_id}",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            await self._send_realtime_payload({"type": "conversation.item.retrieved", "item": item})
-            return None
-        if event_type == "conversation.item.truncate":
-            item_id = event.get("item_id")
-            audio_end_ms = event.get("audio_end_ms")
-            content_index = event.get("content_index", 0)
-            if not isinstance(item_id, str) or not item_id:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "missing_item_id",
-                        "conversation.item.truncate requires item_id",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            if not isinstance(audio_end_ms, int | float):
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "bad_event",
-                        "conversation.item.truncate requires numeric audio_end_ms",
-                        event_id=event.get("event_id"),
-                        param="audio_end_ms",
-                    )
-                )
-                return None
-            item = self._conversation_items.get(item_id)
-            if not isinstance(item, dict):
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "item_not_found",
-                        f"Conversation item not found: {item_id}",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            truncate_error = self._validate_realtime_item_truncate(
-                item,
-                content_index=int(content_index) if isinstance(content_index, int | float) else 0,
-                audio_end_ms=int(audio_end_ms),
-            )
-            if truncate_error is not None:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "bad_event",
-                        truncate_error,
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            self._item_truncation_cursors[item_id] = (
-                int(content_index) if isinstance(content_index, int | float) else 0,
-                int(audio_end_ms),
-            )
-            self._truncate_realtime_item_content(
-                item,
-                content_index=int(content_index) if isinstance(content_index, int | float) else 0,
-                audio_end_ms=int(audio_end_ms),
-            )
-            await self._pending_outbound.put(
-                {
-                    "type": "turn.signal",
-                    "event": "conversation.item.truncate",
-                    "payload": {
-                        "item_id": item_id,
-                        "content_index": content_index,
-                        "audio_end_ms": audio_end_ms,
-                    },
-                }
-            )
-            await self._pending_outbound.put(
-                {
-                    "type": "playback.ack",
-                    "item_id": item_id,
-                    "committed_ms": int(audio_end_ms),
-                    "played_ms": int(audio_end_ms),
-                    "truncate": True,
-                }
-            )
-            return None
-        if event_type == "input_audio_buffer.append":
-            audio = event.get("audio") or event.get("delta")
-            event_format = event.get("format") or event.get("input_audio_format")
-            native_server_vad = self._turn_detection is not None and self._native_input_append
-            turn_based_server_vad = self._turn_based_server_vad
-            try:
-                fmt, format_rate = self._parse_realtime_audio_format(event_format or self._input_audio_format)
-                sample_rate_hz = event.get("sample_rate_hz") or event.get("sample_rate") or format_rate
-                if sample_rate_hz is None:
-                    sample_rate_hz = (
-                        realtime_default_sample_rate_hz(fmt)
-                        if event_format is not None and fmt != self._input_audio_format
-                        else self._input_sample_rate_hz
-                    )
-                if turn_based_server_vad:
-                    sample_rate_hz = validate_input_sample_rate_hz(sample_rate_hz)
-            except ValueError as exc:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "bad_event",
-                        str(exc),
-                        event_id=event.get("event_id"),
-                        param="sample_rate_hz",
-                    )
-                )
-                return None
-            channels = event.get("channels", 1)
-            if not self._is_supported_realtime_input_format(fmt):
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "unsupported_audio_format",
-                        f"Unsupported input_audio_format: {fmt}",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            if turn_based_server_vad and (fmt != "pcm16" or channels != 1 or sample_rate_hz not in {16_000, 24_000}):
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "unsupported_audio_format",
-                        "server_vad requires mono PCM16 input at 16 kHz or 24 kHz",
-                        event_id=event.get("event_id"),
-                        param="audio.input.format",
-                    )
-                )
-                return None
-            looks_like_speech: bool | None = None
-            if not turn_based_server_vad:
-                try:
-                    audio, fmt, sample_rate_hz = convert_input_audio_with_rate(
-                        audio,
-                        fmt,
-                        sample_rate_hz=sample_rate_hz if isinstance(sample_rate_hz, int | float) else None,
-                    )
-                except ValueError as exc:
-                    await self._send_realtime_payload(
-                        self._realtime_error_payload(
-                            "bad_event",
-                            str(exc),
-                            event_id=event.get("event_id"),
-                            param="sample_rate_hz",
-                        )
-                    )
-                    return None
-            if not turn_based_server_vad and not native_server_vad:
-                looks_like_speech = self._input_looks_like_speech(event, audio=audio, fmt=fmt)
-                has_audio_payload = isinstance(audio, str) and bool(audio)
-                self._input_audio_buffer_has_audio = self._input_audio_buffer_has_audio or (
-                    looks_like_speech and has_audio_payload
-                )
-                self._input_audio_buffer_had_non_speech = self._input_audio_buffer_had_non_speech or (
-                    not looks_like_speech and has_audio_payload
-                )
-                if looks_like_speech:
-                    await self._emit_input_speech_started(event)
-                    self._remember_input_transcript_hint(event)
-            payload = {
-                "type": "input_audio_buffer.append",
-                "audio": audio,
-                "format": fmt,
-                "sample_rate_hz": sample_rate_hz,
-            }
-            event_id = event.get("event_id")
-            if self._turn_detection is not None and isinstance(event_id, str) and event_id:
-                payload["_realtime_event_id"] = event_id
-            video_frames = event.get("video_frames")
-            if video_frames is not None:
-                frames_error = self._validate_realtime_video_frames(video_frames, event.get("max_slice_nums"))
-                if frames_error is not None:
-                    await self._send_realtime_payload(
-                        self._realtime_error_payload(
-                            "invalid_video_frames",
-                            frames_error,
-                            event_id=event.get("event_id"),
-                            param="video_frames",
-                        )
-                    )
-                    return None
-                if isinstance(video_frames, list):
-                    payload["video_frames"] = [frame for frame in video_frames if isinstance(frame, str) and frame]
-            self._copy_realtime_input_hints(event, payload)
-            if looks_like_speech is not None:
-                payload["is_speech"] = looks_like_speech
-            return payload
-        if event_type == "input_audio_buffer.commit":
-            if self._turn_based_server_vad:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "server_vad_manual_commit_unsupported",
-                        (
-                            "input_audio_buffer.commit is not supported while server_vad is enabled; "
-                            "wait for server endpointing, or start a session with turn_detection=null "
-                            "to use manual commit"
-                        ),
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            if not self._input_audio_buffer_has_audio:
-                if self._input_audio_buffer_had_non_speech:
-                    self._input_audio_buffer_had_non_speech = False
-                    self._active_input_item_id = None
-                    return {
-                        "type": "input_audio_buffer.commit",
-                        "final": event.get("final", True),
-                        "response_create": False,
-                        "is_speech": False,
-                    }
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "input_audio_buffer_empty",
-                        "input_audio_buffer.commit requires a non-empty input audio buffer",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            item_id = self._active_input_item_id or f"item_{uuid4().hex}"
-            await self._emit_input_speech_stopped(event, item_id=item_id)
-            transcript = self._consume_input_transcript_hint()
-            self._active_input_item_id = None
-            self._input_audio_buffer_has_audio = False
-            self._input_audio_buffer_had_non_speech = False
-            payload = {
-                "type": "input_audio_buffer.commit",
-                "final": event.get("final", True),
-                "item_id": item_id,
-                "response_create": bool(event.get("response_create", False)),
-            }
-            if transcript:
-                payload["transcript"] = transcript
-            return payload
-        if event_type == "input_audio_buffer.clear":
-            self._reset_realtime_input_buffer_state()
-            return {"type": "input_audio_buffer.clear", "reason": event_type}
-        if event_type == "output_audio_buffer.clear":
-            payload = {"type": "output_audio_buffer.clear", "reason": event_type}
-            response_id = event.get("response_id")
-            if not isinstance(response_id, str) or not response_id:
-                response_id = self._active_response_id or self._last_response_id
-            if self._response_is_done(response_id):
-                await self._send_realtime_payload(
-                    {
-                        "type": "output_audio_buffer.cleared",
-                        "response_id": response_id,
-                    }
-                )
-                return None
-            if isinstance(response_id, str) and response_id:
-                payload["response_id"] = response_id
-            return payload
-        if event_type == "response.cancel":
-            payload = {"type": "response.cancel", "reason": event_type}
-            response_id = event.get("response_id")
-            if not isinstance(response_id, str) or not response_id:
-                response_id = self._active_response_id or self._last_response_id
-            if self._response_is_done(response_id):
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "response_not_active",
-                        f"Response is already complete: {response_id}",
-                        event_id=event.get("event_id"),
-                    )
-                )
-                return None
-            if isinstance(response_id, str) and response_id:
-                payload["response_id"] = response_id
-            return payload
-        if event_type == "response.create":
-            response_payload = event.get("response")
-            if isinstance(response_payload, dict):
-                format_error = self._validate_realtime_response_audio_formats(response_payload)
-                if format_error is not None:
-                    await self._send_realtime_payload(
-                        self._realtime_error_payload(
-                            "unsupported_audio_format",
-                            format_error,
-                            event_id=event.get("event_id"),
-                        )
-                    )
-                    return None
-            return {
-                "type": "response.create",
-                "response": response_payload if isinstance(response_payload, dict) else {},
-            }
-        if event_type in {"session.close", "close"}:
-            return {"type": "session.close"}
-        return event
-
-    @staticmethod
-    def _normalize_conversation_item(item: dict[str, object]) -> dict[str, object]:
-        normalized = dict(item)
-        normalized.setdefault("id", f"item_{uuid4().hex}")
-        normalized.setdefault("object", "realtime.item")
-        normalized.setdefault("type", "message")
-        normalized.setdefault("status", "completed")
-        if "role" not in normalized and normalized.get("type") == "message":
-            normalized["role"] = "user"
-        if not isinstance(normalized.get("content"), list):
-            normalized["content"] = []
-        return normalized
-
-    @staticmethod
-    def _truncate_realtime_item_content(
-        item: dict[str, object],
-        *,
-        content_index: int,
-        audio_end_ms: int,
-    ) -> None:
-        content = item.get("content")
-        if not isinstance(content, list) or not content:
-            return
-        index = max(0, int(content_index))
-        if index >= len(content):
-            return
-        part = content[index]
-        if not isinstance(part, dict):
-            return
-        transcript = part.get("transcript")
-        if not isinstance(transcript, str) or not transcript:
-            return
-        marks = part.get("audio_text_marks")
-        if isinstance(marks, list):
-            keep_chars = RealtimeInputTranslator._text_chars_for_audio_ms_from_marks(
-                audio_end_ms,
-                len(transcript),
-                marks,
-                final_ms=part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms"),
-            )
-            part["transcript"] = transcript[:keep_chars].rstrip()
-            return
-        duration_ms = part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms")
-        if isinstance(duration_ms, int | float) and duration_ms > 0:
-            keep_chars = int(len(transcript) * max(0.0, min(1.0, int(audio_end_ms) / float(duration_ms))))
-            part["transcript"] = transcript[:keep_chars].rstrip()
-        elif audio_end_ms <= 0:
-            part["transcript"] = ""
-
-    @staticmethod
-    def _validate_realtime_item_truncate(
-        item: dict[str, object],
-        *,
-        content_index: int,
-        audio_end_ms: int,
-    ) -> str | None:
-        if item.get("type") != "message" or item.get("role") != "assistant":
-            return "conversation.item.truncate only supports assistant message items"
-        if audio_end_ms < 0:
-            return "conversation.item.truncate requires non-negative audio_end_ms"
-        content = item.get("content")
-        if not isinstance(content, list) or not content:
-            return None
-        index = max(0, int(content_index))
-        if index >= len(content):
-            return f"conversation.item.truncate content_index out of range: {content_index}"
-        part = content[index]
-        if not isinstance(part, dict):
-            return "conversation.item.truncate target content part is invalid"
-        if part.get("type") not in {"audio", "output_audio"}:
-            return "conversation.item.truncate target content part must be audio"
-        duration_ms = part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms")
-        if isinstance(duration_ms, int | float) and int(duration_ms) >= 0 and audio_end_ms > int(duration_ms):
-            return "conversation.item.truncate audio_end_ms exceeds item audio duration"
+def parse_resume_request(event: Mapping[str, object]) -> ResumeRequest | None:
+    """Validate the shape of ``session.resume``; ``None`` when any field is missing or malformed."""
+    session_id = event.get("session_id")
+    resume_token = event.get("resume_token")
+    last_received = event.get("last_received_server_event_seq", 0)
+    if (
+        not isinstance(session_id, str)
+        or not session_id
+        or not isinstance(resume_token, str)
+        or not resume_token
+        or not isinstance(last_received, int)
+        or last_received < 0
+    ):
         return None
+    return ResumeRequest(
+        session_id=session_id,
+        resume_token=resume_token,
+        last_received_server_event_seq=last_received,
+    )
 
-    @staticmethod
-    def _text_chars_for_audio_ms_from_marks(
-        audio_end_ms: int,
-        text_len: int,
-        marks: list[object],
-        *,
-        final_ms: object | None = None,
-    ) -> int:
-        if text_len <= 0:
-            return 0
-        clean_marks: list[tuple[int, int]] = []
-        for mark in marks:
-            if not isinstance(mark, dict):
-                continue
-            raw_text_chars = mark.get("text_chars")
-            raw_audio_end_ms = mark.get("audio_end_ms", mark.get("audio_ms"))
-            if not isinstance(raw_text_chars, int | float) or not isinstance(raw_audio_end_ms, int | float):
-                continue
-            clean_marks.append((max(0, int(raw_audio_end_ms)), min(text_len, max(0, int(raw_text_chars)))))
-        if not clean_marks:
-            return 0 if audio_end_ms <= 0 else text_len
-        clean_marks.sort(key=lambda item: item[0])
-        audio_end_ms = max(0, int(audio_end_ms))
-        if audio_end_ms <= 0:
-            return 0
-        previous_ms = 0
-        previous_chars = 0
-        for mark_ms, mark_chars in clean_marks:
-            mark_ms = max(previous_ms, mark_ms)
-            mark_chars = max(previous_chars, min(text_len, mark_chars))
-            if audio_end_ms <= mark_ms:
-                if mark_ms <= previous_ms:
-                    return mark_chars
-                ratio = (audio_end_ms - previous_ms) / max(1, mark_ms - previous_ms)
-                return int(previous_chars + (mark_chars - previous_chars) * max(0.0, min(1.0, ratio)))
-            previous_ms = mark_ms
-            previous_chars = mark_chars
-        if isinstance(final_ms, int | float) and int(final_ms) > previous_ms:
-            if audio_end_ms >= int(final_ms):
-                return text_len
-            ratio = (audio_end_ms - previous_ms) / max(1, int(final_ms) - previous_ms)
-            return int(previous_chars + (text_len - previous_chars) * max(0.0, min(1.0, ratio)))
-        return text_len if audio_end_ms >= previous_ms else previous_chars
-
-    def _conversation_item_added_events(self, item: dict[str, object]) -> list[dict[str, object]]:
-        item_id = item.get("id")
-        explicit_previous_item_id = item.pop("_previous_item_id", None)
-        previous_item_id = (
-            explicit_previous_item_id if isinstance(explicit_previous_item_id, str) else self._last_conversation_item_id
-        )
-        if isinstance(item_id, str) and item_id:
-            self._last_conversation_item_id = item_id
-        return [
-            {
-                "type": "conversation.item.added",
-                "previous_item_id": previous_item_id,
-                "item": item,
-            },
-        ]
 
-    def _conversation_item_done_event(self, item: dict[str, object]) -> dict[str, object]:
-        item_id = item.get("id")
-        previous_item_id = self._previous_item_id(item_id) if isinstance(item_id, str) else None
-        if isinstance(item_id, str) and item_id:
-            already_known = item_id in self._conversation_items
-            self._conversation_items[item_id] = item
-            # Completing an item that was already added must not move it to the
-            # end of the conversation. A later user item may have been added
-            # while this response was still in progress.
-            if not already_known:
-                self._last_conversation_item_id = item_id
-        return {
-            "type": "conversation.item.done",
-            "previous_item_id": previous_item_id,
-            "item": item,
-        }
+@dataclass
+class RealtimeEnvelope:
+    """Per-connection Realtime wire policy (no session state)."""
 
-    def _remove_conversation_item(self, item_id: str) -> bool:
-        removed = self._conversation_items.pop(item_id, None) is not None
-        if self._last_conversation_item_id == item_id:
-            remaining_ids = list(self._conversation_items)
-            self._last_conversation_item_id = remaining_ids[-1] if remaining_ids else None
-        self._item_truncation_cursors.pop(item_id, None)
-        return removed
-
-    def _response_output_item_added_events(
-        self,
-        *,
-        response_id: object,
-        item: dict[str, object],
-    ) -> list[dict[str, object]]:
-        return [
-            {
-                "type": "response.output_item.added",
-                "response_id": response_id,
-                "output_index": 0,
-                "item": item,
-            },
-        ]
-
-    @staticmethod
-    def _response_content_part(*, transcript: str = "") -> dict[str, object]:
-        return {
-            "type": "audio",
-            "transcript": transcript,
-        }
-
-    @staticmethod
-    def _response_text_content_part(*, text: str = "") -> dict[str, object]:
-        return {
-            "type": "text",
-            "text": text,
-        }
-
-    @staticmethod
-    def _response_item_content_part(
-        *,
-        transcript: str = "",
-        audio_duration_ms: int | None = None,
-        audio_text_marks: list[dict[str, int]] | None = None,
-    ) -> dict[str, object]:
-        part: dict[str, object] = {
-            "type": "output_audio",
-            "transcript": transcript,
-        }
-        if audio_duration_ms is not None:
-            part["audio_duration_ms"] = int(audio_duration_ms)
-        if audio_text_marks:
-            part["audio_text_marks"] = [dict(mark) for mark in audio_text_marks]
-        return part
-
-    @staticmethod
-    def _response_item_text_content_part(*, text: str = "") -> dict[str, object]:
-        return {
-            "type": "output_text",
-            "text": text,
-        }
-
-    def _previous_item_id(self, item_id: str) -> str | None:
-        previous: str | None = None
-        for known_id in self._conversation_items:
-            if known_id == item_id:
-                return previous
-            previous = known_id
-        if self._last_conversation_item_id == item_id:
-            return previous
-        return self._last_conversation_item_id
-
-    def _input_audio_buffer_committed_event(
-        self,
-        *,
-        item_id: str,
-    ) -> dict[str, object]:
-        return {
-            "type": "input_audio_buffer.committed",
-            "previous_item_id": self._previous_item_id(item_id),
-            "item_id": item_id,
-        }
-
-    def _session_create_from_realtime(self, session_payload: dict[str, object]) -> dict[str, object]:
-        model = session_payload.get("model")
-        audio_config = session_payload.get("audio")
-        audio_input = audio_config.get("input") if isinstance(audio_config, dict) else None
-        audio_output = audio_config.get("output") if isinstance(audio_config, dict) else None
-        extra_body_payload = session_payload.get("extra_body")
-        extra_body = (
-            normalize_native_duplex_key(dict(extra_body_payload)) if isinstance(extra_body_payload, dict) else {}
-        )
-        extra_body["realtime_session_payload"] = self._json_safe_realtime_payload(session_payload)
-        if isinstance(session_payload.get("tools"), list):
-            extra_body["realtime_tools"] = session_payload["tools"]
-        if isinstance(session_payload.get("tool_choice"), str | dict):
-            extra_body["realtime_tool_choice"] = session_payload["tool_choice"]
-        metadata = session_payload.get("metadata")
-        if isinstance(metadata, dict):
-            extra_body["realtime_metadata"] = dict(metadata)
-        include = session_payload.get("include")
-        if isinstance(include, list):
-            extra_body["realtime_include"] = list(include)
-        prompt = session_payload.get("prompt")
-        if isinstance(prompt, dict):
-            extra_body["realtime_prompt"] = dict(prompt)
-        input_audio_transcription = self._input_audio_transcription_config(session_payload)
-        if isinstance(input_audio_transcription, dict):
-            extra_body["realtime_input_audio_transcription"] = dict(input_audio_transcription)
-        noise_reduction = session_payload.get("input_audio_noise_reduction")
-        if isinstance(noise_reduction, dict):
-            extra_body["realtime_input_audio_noise_reduction"] = dict(noise_reduction)
-        audio_noise_reduction = audio_input.get("noise_reduction") if isinstance(audio_input, dict) else None
-        if isinstance(audio_noise_reduction, dict):
-            extra_body["realtime_input_audio_noise_reduction"] = dict(audio_noise_reduction)
-        audio = session_payload.get("audio")
-        if isinstance(audio, dict):
-            extra_body["realtime_audio"] = dict(audio)
-        if isinstance(session_payload.get("tracing"), str | dict):
-            extra_body["realtime_tracing"] = session_payload["tracing"]
-        response_format = self._duplex_response_format(self._output_audio_format)
-        extra_body.setdefault("realtime_output_audio_format", self._output_audio_format)
-        overlap_fields = self._realtime_overlap_fields(session_payload)
-        voice = session_payload.get("voice")
-        if not isinstance(voice, str) and isinstance(audio_output, dict):
-            voice = audio_output.get("voice")
-        speed = session_payload.get("speed")
-        if not isinstance(speed, int | float) and isinstance(audio_output, dict):
-            speed = audio_output.get("speed")
-        return {
-            "type": "session.create",
-            "session_id": session_payload.get("session_id") or session_payload.get("id"),
-            "session": {
-                "model": model,
-                "modalities": (
-                    session_payload.get("modalities") or session_payload.get("output_modalities") or ["text", "audio"]
-                ),
-                "instructions": session_payload.get("instructions"),
-                "voice": voice,
-                "ref_audio": session_payload.get("ref_audio"),
-                "response_format": response_format,
-                "temperature": session_payload.get("temperature"),
-                "max_tokens": self.realtime_max_output_tokens(
-                    session_payload.get("max_response_output_tokens")
-                    or session_payload.get("max_output_tokens")
-                    or session_payload.get("max_tokens")
-                ),
-                "speed": speed,
-                "idle_timeout_s": session_payload.get("idle_timeout_s") or 300.0,
-                **overlap_fields,
-                "extra_body": extra_body,
-            },
-        }
-
-    def _apply_realtime_session_defaults(self, session_payload: dict[str, object]) -> None:
-        input_format: object = session_payload.get("input_audio_format")
-        audio_config = session_payload.get("audio")
-        if input_format is None and isinstance(audio_config, dict):
-            audio_input = audio_config.get("input")
-            if isinstance(audio_input, dict):
-                input_format = audio_input.get("format")
-        input_format_configured = input_format is not None
-        input_format, input_rate = self._parse_realtime_audio_format(input_format)
-        if input_format is not None and not (
-            isinstance(input_format, str) and input_format.lower() in REALTIME_INPUT_AUDIO_FORMATS
-        ):
-            raise ValueError(f"Unsupported input_audio_format: {input_format}")
-        if isinstance(input_format, str):
-            self._input_audio_format = input_format
-        output_format: object = session_payload.get("output_audio_format") or session_payload.get("response_format")
-        output_rate_raw: object | None = None
-        if output_format is None and isinstance(audio_config, dict):
-            audio_output = audio_config.get("output")
-            if isinstance(audio_output, dict):
-                output_format = audio_output.get("format")
-                output_rate_raw = audio_output.get("sample_rate_hz") or audio_output.get("sample_rate")
-        output_format, output_rate = self._parse_realtime_audio_format(output_format)
-        if output_rate is None and output_rate_raw is not None:
-            output_rate = validate_input_sample_rate_hz(output_rate_raw)
-        if output_format is not None and not (
-            isinstance(output_format, str) and output_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS
-        ):
-            raise ValueError(f"Unsupported output_audio_format: {output_format}")
-        if isinstance(output_format, str):
-            self._output_audio_format = self._realtime_output_format(output_format)
-        sample_rate = session_payload.get("sample_rate_hz") or session_payload.get("sample_rate")
-        if sample_rate is None and isinstance(audio_config, dict):
-            audio_input = audio_config.get("input")
-            if isinstance(audio_input, dict):
-                sample_rate = audio_input.get("sample_rate_hz") or audio_input.get("sample_rate")
-        if sample_rate is None:
-            sample_rate = input_rate
-        if sample_rate is not None:
-            self._input_sample_rate_hz = validate_input_sample_rate_hz(sample_rate)
-        elif input_format_configured:
-            default_input_rate = realtime_default_sample_rate_hz(input_format)
-            if default_input_rate is not None:
-                self._input_sample_rate_hz = default_input_rate
-        if output_rate is not None:
-            self._output_sample_rate_hz = output_rate
-        overlap_fields = self._realtime_overlap_fields(session_payload)
-        overlap_silence_rms = overlap_fields.get("overlap_silence_rms")
-        if isinstance(overlap_silence_rms, int | float):
-            self._overlap_silence_rms = max(0.0, float(overlap_silence_rms))
+    default_model: str | None = None
+    #: ``?resume=1`` / ``?autostart=0``: the first message must be ``session.resume``/``session.update``.
+    resume_only: bool = False
+    opened: bool = False
+    autostarted_default_session: bool = False
+    defaults: RealtimeInputDefaults = field(default_factory=RealtimeInputDefaults)
 
     @classmethod
-    def _validate_realtime_response_audio_formats(cls, response_payload: dict[str, object]) -> str | None:
-        output_format: object = response_payload.get("output_audio_format") or response_payload.get("response_format")
-        audio_config = response_payload.get("audio")
-        if output_format is None and isinstance(audio_config, dict):
-            audio_output = audio_config.get("output")
-            if isinstance(audio_output, dict):
-                output_format = audio_output.get("format")
-        try:
-            parsed_output, _ = cls._parse_realtime_audio_format(output_format)
-        except ValueError as exc:
-            return str(exc)
-        if output_format is not None and not (
-            isinstance(parsed_output, str) and parsed_output.lower() in REALTIME_OUTPUT_AUDIO_FORMATS
-        ):
-            return f"Unsupported output_audio_format: {output_format}"
-        return None
-
-    @staticmethod
-    def _json_safe_realtime_payload(payload: dict[str, object]) -> dict[str, object]:
-        clean: dict[str, object] = {}
-        for key, value in payload.items():
-            if key == "extra_body":
-                continue
-            if isinstance(value, str | int | float | bool) or value is None:
-                clean[key] = value
-            elif isinstance(value, dict):
-                clean[key] = RealtimeInputTranslator._json_safe_realtime_payload(value)
-            elif isinstance(value, list):
-                clean[key] = [
-                    (RealtimeInputTranslator._json_safe_realtime_payload(item) if isinstance(item, dict) else item)
-                    for item in value
-                    if isinstance(item, str | int | float | bool | dict) or item is None
-                ]
-        return clean
-
-    @staticmethod
-    def _parse_realtime_audio_format(raw_format: object) -> tuple[object, int | None]:
-        def normalize_format(fmt: str) -> str:
-            normalized = fmt.lower()
-            if normalized in {"audio/pcm", "pcm"}:
-                return "pcm16"
-            if normalized in {"audio/wav", "wav"}:
-                return "wav"
-            if normalized in {"audio/pcm16", "pcm16", "pcm_s16le", "s16le"}:
-                return "pcm16"
-            if normalized in {"audio/pcm_f32le", "pcm_f32le", "f32le"}:
-                return "pcm_f32le"
-            if normalized in {"audio/g711_ulaw", "g711_ulaw", "g711-ulaw", "ulaw", "mulaw"}:
-                return "g711_ulaw"
-            if normalized in {"audio/g711_alaw", "g711_alaw", "g711-alaw", "alaw"}:
-                return "g711_alaw"
-            return fmt
-
-        if isinstance(raw_format, str):
-            return normalize_format(raw_format), None
-        if not isinstance(raw_format, dict):
-            return raw_format, None
-        rate = raw_format.get("rate") or raw_format.get("sample_rate_hz") or raw_format.get("sample_rate")
-        sample_rate_hz = validate_input_sample_rate_hz(rate) if rate is not None else None
-        fmt = raw_format.get("type") or raw_format.get("format")
-        if not isinstance(fmt, str):
-            return raw_format, sample_rate_hz
-        return normalize_format(fmt), sample_rate_hz
-
-    @staticmethod
-    def _duplex_response_format(realtime_format: str) -> str:
-        normalized = realtime_format.lower()
-        if normalized in {"pcm16", "pcm_s16le", "s16le"}:
-            return "pcm"
-        if normalized in {"g711_ulaw", "g711_alaw"}:
-            return "pcm"
-        if normalized in {"wav", "pcm"}:
-            return normalized
-        return "wav"
-
-    @staticmethod
-    def _realtime_output_format(duplex_format: object) -> str:
-        if isinstance(duplex_format, str) and duplex_format.lower() in {"g711_ulaw", "g711_alaw"}:
-            return duplex_format.lower()
-        if isinstance(duplex_format, str) and duplex_format.lower() == "pcm":
-            return "pcm16"
-        return str(duplex_format or "wav")
-
-    @staticmethod
-    def _is_supported_realtime_input_format(fmt: object) -> bool:
-        return isinstance(fmt, str) and fmt.lower() in REALTIME_INPUT_AUDIO_FORMATS
-
-    @staticmethod
-    def _input_explicitly_non_speech(event: dict[str, object]) -> bool:
-        for key in ("is_speech", "speech"):
-            value = event.get(key)
-            if isinstance(value, bool):
-                return not value
-        vad = event.get("vad")
-        if isinstance(vad, dict):
-            value = vad.get("is_speech")
-            if isinstance(value, bool):
-                return not value
-            probability = vad.get("speech_probability", vad.get("probability"))
-            if isinstance(probability, int | float):
-                return float(probability) < 0.5
-        probability = event.get("speech_probability")
-        return isinstance(probability, int | float) and float(probability) < 0.5
-
-    def _input_looks_like_speech(self, event: dict[str, object], *, audio: object, fmt: object) -> bool:
-        if RealtimeInputTranslator._input_explicitly_non_speech(event):
-            return False
-        for key in ("is_speech", "speech"):
-            value = event.get(key)
-            if isinstance(value, bool):
-                return value
-        vad = event.get("vad")
-        if isinstance(vad, dict):
-            probability = vad.get("speech_probability", vad.get("probability"))
-            if isinstance(probability, int | float):
-                return float(probability) >= 0.5
-        probability = event.get("speech_probability")
-        if isinstance(probability, int | float):
-            return float(probability) >= 0.5
-        if fmt != "pcm_f32le" or not isinstance(audio, str):
-            return True
-        try:
-            raw = base64.b64decode(audio, validate=True)
-        except (binascii.Error, ValueError):
-            return True
-        if len(raw) < 4 or len(raw) % 4 != 0:
-            return True
-        samples = np.frombuffer(raw, dtype=np.float32)
-        if samples.size == 0:
-            return False
-        rms = float(np.sqrt(np.mean(np.square(samples.astype(np.float32)))))
-        threshold = event.get("overlap_silence_rms")
-        if not isinstance(threshold, int | float):
-            vad = event.get("vad")
-            if isinstance(vad, dict):
-                threshold = vad.get("silence_rms")
-        silence_rms = float(threshold) if isinstance(threshold, int | float) else self._overlap_silence_rms
-        return rms >= max(0.0, silence_rms)
-
-    @staticmethod
-    def _copy_realtime_input_hints(source: dict[str, object], target: dict[str, object]) -> None:
-        for key in (
-            "duration_ms",
-            "audio_duration_ms",
-            "audio_start_ms",
-            "audio_end_ms",
-            "is_speech",
-            "speech",
-            "speech_probability",
-            "vad",
-            "overlap_action",
-            "overlap",
-            "force_barge_in",
-            "force_listen",
-            "text",
-            "transcript",
-        ):
-            if key in source:
-                target[key] = source[key]
-
-    @classmethod
-    def _realtime_overlap_fields(cls, session_payload: dict[str, object]) -> dict[str, object]:
-        fields: dict[str, object] = {}
-        if isinstance(session_payload.get("overlap_policy"), str):
-            fields["overlap_policy"] = session_payload["overlap_policy"]
-        for key in ("overlap_short_ack_ms", "overlap_barge_in_ms", "overlap_silence_rms"):
-            value = session_payload.get(key)
-            if isinstance(value, int | float):
-                fields[key] = value
-
-        if isinstance(session_payload.get("playback_commit_policy"), str):
-            fields["playback_commit_policy"] = session_payload["playback_commit_policy"]
-        return fields
-
-    @staticmethod
-    def _validate_realtime_video_frames(video_frames: object, max_slice_nums: object) -> str | None:
-        """Validate omni-duplex camera frames on input_audio_buffer.append.
-
-        Wire contract matches the official MiniCPM-o duplex loop: one base
-        base64 JPEG per ~1 s audio chunk, optionally followed by that unit's
-        stacked composite tiling the sub-frames captured inside it (at most 2
-        images either way). A caller-supplied ``max_slice_nums`` is rejected
-        rather than silently ignored: slicing is Stage 0's decision here, and
-        Stage 0 already applies the official HD suggestion for a stacked unit
-        (``max_slice_nums=[2, 1]``). The wire simply does not let the client
-        choose it.
-        """
-        if max_slice_nums not in (None, 1):
-            return "max_slice_nums is not selectable on the wire; Stage0 slices stacked units itself"
-        if not isinstance(video_frames, list):
-            return "video_frames must be a list of base64-encoded images"
-        frames = [frame for frame in video_frames if frame is not None]
-        if len(frames) > 2:
-            return "video_frames carries more than 2 frames for one append; send ~1 frame per 1 s chunk"
-        for frame in frames:
-            if not isinstance(frame, str) or not frame:
-                return "video_frames entries must be non-empty base64 strings"
-            if len(frame) > 4_000_000:
-                return "video_frames entry exceeds 4MB base64; reduce capture resolution or JPEG quality"
-            try:
-                header = base64.b64decode(frame[:64] + "=" * (-len(frame[:64]) % 4))
-            except (binascii.Error, ValueError):
-                return "video_frames entries must be valid base64"
-            if not (header.startswith(b"\xff\xd8") or header.startswith(b"\x89PNG")):
-                return "video_frames entries must be JPEG or PNG images"
-        return None
-
-    def _validate_realtime_turn_detection(
-        self,
-        session_payload: dict[str, object],
-        *,
-        configured: bool,
-        normalized: dict[str, object] | None,
-    ) -> str | None:
-        effective_turn_detection = normalized if configured else self._turn_detection
-        if effective_turn_detection is None:
-            if session_payload.get("overlap_policy") == "barge_in_on_speech":
-                return "overlap_policy='barge_in_on_speech' requires turn_detection.type='server_vad'"
-            return None
-
-        interrupt_response = effective_turn_detection.get("interrupt_response")
-        if interrupt_response is None:
-            # Serving resolves the default and validates overlap policy once
-            # the session's runtime capabilities are known.
-            return None
-        desired_policy = "barge_in_on_speech" if interrupt_response else "listen_only"
-        overlap_policy = session_payload.get("overlap_policy")
-        if isinstance(overlap_policy, str) and overlap_policy != desired_policy:
-            return f"overlap_policy={overlap_policy!r} conflicts with turn_detection; expected {desired_policy!r}"
-        return None
-
-    def validate_server_vad_input_audio(self, session_payload: dict[str, object]) -> str | None:
-        """Validate turn-based VAD audio after serving resolves runtime capabilities."""
-        candidate = self._pending_turn_detection_update
-        input_format, input_rate, *_ = candidate[3] if candidate is not None else self._realtime_protocol_config()
-        audio_config = session_payload.get("audio")
-        audio_input = audio_config.get("input") if isinstance(audio_config, dict) else None
-        channels = audio_input.get("channels") if isinstance(audio_input, dict) else None
-        raw_format = session_payload.get("input_audio_format")
-        if raw_format is None and isinstance(audio_input, dict):
-            raw_format = audio_input.get("format")
-        if channels is None and isinstance(raw_format, dict):
-            channels = raw_format.get("channels")
-        if channels is None:
-            channels = 1
-        if input_format != "pcm16" or channels != 1 or input_rate not in {16_000, 24_000}:
-            return "server_vad requires mono PCM16 input at 16 kHz or 24 kHz"
-        return None
-
-    def _prepare_realtime_turn_detection_update(
-        self,
-        session_payload: dict[str, object],
-        *,
-        configured: bool,
-        normalized: dict[str, object] | None,
-    ) -> tuple[bool, dict[str, object] | None]:
-        if self._pending_turn_detection_update is not None:
-            raise RuntimeError("A Realtime session update is already pending")
-
-        turn_detection = dict(normalized) if configured and normalized is not None else None
-        if configured:
-            if turn_detection is None:
-                session_payload.setdefault("overlap_policy", "listen_only")
-            elif "interrupt_response" in turn_detection:
-                session_payload.setdefault(
-                    "overlap_policy", "barge_in_on_speech" if turn_detection["interrupt_response"] else "listen_only"
-                )
-            session_payload["turn_detection"] = turn_detection
-        return configured, turn_detection
-
-    def _realtime_protocol_config(self) -> tuple[str, int, str, int | None, float]:
-        return (
-            self._input_audio_format,
-            self._input_sample_rate_hz,
-            self._output_audio_format,
-            self._output_sample_rate_hz,
-            self._overlap_silence_rms,
+    def from_query_params(cls, query_params: Mapping[str, str] | WebSocket) -> RealtimeEnvelope:
+        if hasattr(query_params, "query_params"):
+            query_params = query_params.query_params
+        getter = query_params.get if hasattr(query_params, "get") else None
+        resume_only = getter("resume") if getter is not None else None
+        autostart = getter("autostart") if getter is not None else None
+        model = getter("model") if getter is not None else None
+        return cls(
+            default_model=model if isinstance(model, str) and model else None,
+            resume_only=(
+                str(resume_only).strip().lower() in _TRUE_VALUES or str(autostart).strip().lower() in _FALSE_VALUES
+            ),
         )
 
-    def _set_realtime_protocol_config(
-        self,
-        config: tuple[str, int, str, int | None, float],
-    ) -> None:
-        (
-            self._input_audio_format,
-            self._input_sample_rate_hz,
-            self._output_audio_format,
-            self._output_sample_rate_hz,
-            self._overlap_silence_rms,
-        ) = config
+    # ---- handshake ----
 
-    def pending_realtime_input_audio_config_changed(self) -> bool:
-        candidate = self._pending_turn_detection_update
-        if candidate is None:
-            return False
-        candidate_protocol_config = candidate[3]
-        return candidate_protocol_config[:2] != self._realtime_protocol_config()[:2]
+    def default_session_payload(self) -> dict[str, object]:
+        return {"model": self.default_model}
 
-    async def wait_for_realtime_turn_detection_update(self) -> None:
-        candidate = self._pending_turn_detection_update
-        if candidate is not None:
-            await candidate[2].wait()
-
-    def commit_realtime_turn_detection_update(self, server_vad: ServerVADConfig | None = None) -> None:
-        self._resolve_realtime_turn_detection_update(commit=True, server_vad=server_vad)
-
-    def reject_realtime_turn_detection_update(self) -> None:
-        self._resolve_realtime_turn_detection_update(commit=False)
-
-    def _resolve_realtime_turn_detection_update(
-        self, *, commit: bool, server_vad: ServerVADConfig | None = None
-    ) -> None:
-        candidate = self._pending_turn_detection_update
-        if candidate is None:
-            return
-        configured, turn_detection, resolved, protocol_config = candidate
-        if commit:
-            self._set_realtime_protocol_config(protocol_config)
-            if configured:
-                self._turn_detection = server_vad.as_dict() if server_vad is not None else turn_detection
-                self._turn_detection_configured = True
-        self._pending_turn_detection_update = None
-        resolved.set()
-
-    @staticmethod
-    def _input_audio_transcription_config(session_payload: dict[str, object]) -> dict[str, object] | None:
-        transcription = session_payload.get("input_audio_transcription")
-        if isinstance(transcription, dict):
-            return transcription
-        audio_config = session_payload.get("audio")
-        if not isinstance(audio_config, dict):
-            return None
-        audio_input = audio_config.get("input")
-        if not isinstance(audio_input, dict):
+    def initial_open_payload(self) -> dict[str, object] | None:
+        """Session object to open with *before* any client message (``?model=`` autostart), else None."""
+        if self.opened or self.resume_only or self.autostarted_default_session or not self.default_model:
             return None
-        transcription = audio_input.get("transcription")
-        return transcription if isinstance(transcription, dict) else None
+        self.opened = True
+        self.autostarted_default_session = True
+        return self.default_session_payload()
 
-    @staticmethod
-    def realtime_max_output_tokens(value: object) -> int | None:
-        """Normalize Realtime max output tokens.
+    def first_message(self, payload: Mapping[str, object]) -> RealtimeHandshake:
+        """Classify the first client message (call only while ``not opened``).
 
-        OpenAI Realtime clients commonly send ``"inf"`` for unbounded output.
-        The duplex core represents that as ``None`` because model-specific
-        defaults remain in force.
+        ``session.update`` opens with its session object; ``session.resume``
+        resumes; any other event autostarts the default session and is then
+        treated as a command (``pending_command_payload``).
         """
-        if value is None:
-            return None
-        if isinstance(value, str) and value.strip().lower() in {"inf", "infinity", "unlimited"}:
-            return None
-        if isinstance(value, int) and value > 0:
-            return int(value)
-        return None
+        event_type = payload.get("type")
+        self.opened = True
+        if event_type == "session.resume":
+            return RealtimeHandshake(kind="resume", resume_payload=dict(payload))
+        if event_type == "session.update":
+            session = payload.get("session")
+            session_payload = dict(session) if isinstance(session, dict) else dict(payload)
+            session_payload.pop("type", None)
+            self.note_session_payload(session_payload)
+            return RealtimeHandshake(kind="open", session_payload=session_payload)
+        self.autostarted_default_session = True
+        return RealtimeHandshake(
+            kind="open",
+            session_payload=self.default_session_payload(),
+            pending_command_payload=dict(payload),
+        )
 
-    async def _conversation_item_to_duplex(self, event: dict[str, object]) -> dict[str, object] | None:
-        raw_item = event.get("item")
-        if not isinstance(raw_item, dict):
-            return None
-        public_item = self._normalize_conversation_item(raw_item)
-        previous_item_id = event.get("previous_item_id")
-        if isinstance(previous_item_id, str):
-            public_item["_previous_item_id"] = previous_item_id
-        item_id = str(public_item["id"])
-        item_type = public_item.get("type")
-        role = public_item.get("role")
-        if item_type == "function_call_output":
-            call_id = public_item.get("call_id")
-            output = public_item.get("output")
-            matching_call = any(
-                known.get("type") == "function_call" and known.get("call_id") == call_id
-                for known in self._conversation_items.values()
-            )
-            duplicate_output = any(
-                known.get("type") == "function_call_output" and known.get("call_id") == call_id
-                for known in self._conversation_items.values()
-            )
-            if not isinstance(call_id, str) or not call_id or not matching_call:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "invalid_function_call_output",
-                        "function_call_output requires the call_id of a completed function call",
-                        event_id=event.get("event_id"),
-                        param="item.call_id",
-                    )
-                )
-                return None
-            if not isinstance(output, str) or duplicate_output:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "invalid_function_call_output",
-                        (
-                            "function_call_output requires a string output"
-                            if not isinstance(output, str)
-                            else f"function_call_output already exists for call_id {call_id}"
-                        ),
-                        event_id=event.get("event_id"),
-                        param="item.output",
-                    )
-                )
-                return None
-            # Do not retain the result until SessionRunner has delivered its
-            # runtime update. On success, the resulting
-            # ``conversation.item.created`` event records it in the shared
-            # input/output protocol state; on failure the client may retry the
-            # same call_id instead of being rejected by provisional history.
-        content = public_item.get("content")
-        if not isinstance(content, list):
-            return None
-        parsed_audio_formats: dict[int, tuple[object, int | None]] = {}
-        for index, part in enumerate(content):
-            if not isinstance(part, dict) or part.get("type") not in {"input_audio", "audio"}:
-                continue
-            raw_format = part.get("format")
-            try:
-                parsed_format = self._parse_realtime_audio_format(raw_format or self._input_audio_format)
-            except ValueError as exc:
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "unsupported_audio_format",
-                        str(exc),
-                        event_id=event.get("event_id"),
-                        param="item.content.audio",
-                    )
-                )
-                return None
-            if not self._is_supported_realtime_input_format(parsed_format[0]):
-                await self._send_realtime_payload(
-                    self._realtime_error_payload(
-                        "unsupported_audio_format",
-                        f"Unsupported input_audio format in conversation.item.create: {raw_format}",
-                        event_id=event.get("event_id"),
-                        param="item.content.audio",
-                    )
-                )
-                return None
-            parsed_audio_formats[index] = parsed_format
-        if item_type != "message" or role in {"assistant", "system"}:
-            event["item"] = public_item
-            return {
-                "type": "turn.signal",
-                "event": "conversation.item.create",
-                "payload": {"item": public_item},
-            }
-        server_vad_full_audio_item = self._turn_based_server_vad
-        text_chunks: list[str] = []
-        audio_events: list[dict[str, object]] = []
-        normalized_content: list[object] = []
-        normalized_full_audio = False
-        for index, part in enumerate(content):
-            if not isinstance(part, dict):
-                normalized_content.append(part)
-                continue
-            if part.get("type") in {"input_text", "text"} and isinstance(part.get("text"), str):
-                text_chunks.append(str(part["text"]))
-            if part.get("type") in {"input_audio", "audio"}:
-                audio = part.get("audio") or part.get("data")
-                if not isinstance(audio, str) or not audio:
-                    await self._send_realtime_payload(
-                        self._realtime_error_payload(
-                            "bad_audio",
-                            "conversation.item.create input_audio must not be empty",
-                            event_id=event.get("event_id"),
-                            param="item.content.audio",
-                        )
-                    )
-                    return None
-                raw_part_format = part.get("format")
-                fmt, format_rate = parsed_audio_formats[index]
-                explicit_sample_rate_hz = part.get("sample_rate_hz")
-                if explicit_sample_rate_hz is None:
-                    explicit_sample_rate_hz = part.get("sample_rate")
-                if explicit_sample_rate_hz is None and isinstance(raw_part_format, dict):
-                    explicit_sample_rate_hz = (
-                        raw_part_format.get("rate")
-                        if "rate" in raw_part_format
-                        else raw_part_format.get("sample_rate_hz", raw_part_format.get("sample_rate"))
-                    )
-                sample_rate_hz = explicit_sample_rate_hz or format_rate or self._input_sample_rate_hz
-                if server_vad_full_audio_item and (
-                    fmt != self._input_audio_format
-                    or (explicit_sample_rate_hz is not None and explicit_sample_rate_hz != self._input_sample_rate_hz)
-                ):
-                    await self._send_realtime_payload(
-                        self._realtime_error_payload(
-                            "bad_audio",
-                            "conversation.item.create input_audio must use the Session input format and sample rate",
-                            event_id=event.get("event_id"),
-                            param="item.content.audio",
-                        )
-                    )
-                    return None
-                if server_vad_full_audio_item:
-                    try:
-                        normalized_audio = self._normalize_complete_audio_item_part(audio, self._input_sample_rate_hz)
-                    except ValueError as exc:
-                        await self._send_realtime_payload(
-                            self._realtime_error_payload(
-                                "bad_audio",
-                                str(exc),
-                                event_id=event.get("event_id"),
-                                param="item.content.audio",
-                            )
-                        )
-                        return None
-                    normalized_part = dict(part)
-                    normalized_part.pop("data", None)
-                    normalized_part.update(audio=normalized_audio, format="wav", sample_rate_hz=16_000)
-                    normalized_content.append(normalized_part)
-                    normalized_full_audio = True
-                    continue
-                try:
-                    audio, fmt, sample_rate_hz = convert_input_audio_with_rate(
-                        audio,
-                        fmt,
-                        sample_rate_hz=sample_rate_hz if isinstance(sample_rate_hz, int | float) else None,
-                    )
-                except ValueError as exc:
-                    await self._send_realtime_payload(
-                        self._realtime_error_payload(
-                            "bad_audio",
-                            str(exc),
-                            event_id=event.get("event_id"),
-                            param="item.content.audio",
-                        )
-                    )
-                    return None
-                speech_hints = dict(event)
-                speech_hints.update(part)
-                if not self._input_looks_like_speech(speech_hints, audio=audio, fmt=fmt):
-                    continue
-                self._input_speech_started = True
-                payload = {
-                    "type": "input_audio_buffer.append",
-                    "audio": audio,
-                    "format": fmt,
-                    "sample_rate_hz": sample_rate_hz,
-                }
-                self._copy_realtime_input_hints(part, payload)
-                self._copy_realtime_input_hints(event, payload)
-                audio_events.append(payload)
-                continue
-            normalized_content.append(part)
-        if server_vad_full_audio_item and normalized_full_audio:
-            history_item = dict(public_item)
-            history_item["content"] = normalized_content
-            history_item["status"] = "completed"
-            event["item"] = public_item
-            return {
-                "type": "turn.signal",
-                "event": "conversation.item.create",
-                "payload": {
-                    "item": public_item,
-                    "history_item": history_item,
-                },
-            }
-        if audio_events:
-            transcript = self._input_transcript_from_item(public_item)
-            for extra_event in audio_events[1:]:
-                self._pending_outbound.put_nowait(extra_event)
-            commit_payload: dict[str, object] = {
-                "type": "input_audio_buffer.commit",
-                "final": True,
-                "item_id": item_id,
-                "response_create": False,
-            }
-            if transcript:
-                commit_payload["transcript"] = transcript
-            self._pending_outbound.put_nowait(commit_payload)
-            # This complete item is already committed locally; a later ack
-            # must not be needed to start accepting the next input turn.
-            self._reset_realtime_input_buffer_state()
-            event["item"] = public_item
-            return audio_events[0]
-        if not text_chunks:
-            return None
-        text_item = dict(public_item)
-        text_item["status"] = "completed"
-        event["item"] = text_item
-        return {
-            "type": "turn.signal",
-            "event": "conversation.item.create",
-            "payload": {"item": text_item},
-        }
+    def note_session_payload(self, session_payload: Mapping[str, object]) -> None:
+        """Track wire defaults declared by a session object (open or session.update)."""
+        self.defaults = self.defaults.with_session_payload(session_payload)
 
-    @staticmethod
-    def _normalize_complete_audio_item_part(
-        audio: str,
-        sample_rate_hz: int,
-    ) -> str:
-        """Package a complete Realtime audio item for the chat fallback path."""
-        try:
-            raw = base64.b64decode(audio.strip(), validate=True)
-        except (binascii.Error, ValueError) as exc:
-            raise ValueError("conversation.item.create input_audio is not valid Base64") from exc
-        if not raw or len(raw) % np.dtype("<i2").itemsize:
-            raise ValueError("conversation.item.create input_audio must contain complete PCM16 samples")
-        samples = np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768.0
-        if sample_rate_hz != 16_000:
-            from vllm_omni.entrypoints.openai.audio_utils_mixin import StreamingAudioResampler
+    # ---- commands ----
 
-            samples = StreamingAudioResampler(sample_rate_hz, 16_000).process(samples, final=True)
-        return encode_float32_mono_wav_base64(samples, sample_rate_hz=16_000)
+    def is_envelope_event(self, payload: Mapping[str, object]) -> bool:
+        return payload.get("type") in ENVELOPE_EVENT_TYPES
 
-    def _remember_input_transcript_hint(self, event: dict[str, object]) -> None:
-        transcript = event.get("transcript")
-        if not isinstance(transcript, str):
-            transcript = event.get("text") if isinstance(event.get("text"), str) else None
-        if not isinstance(transcript, str):
-            hints = event.get("hints")
-            if isinstance(hints, dict):
-                transcript = hints.get("transcript")
-                if not isinstance(transcript, str):
-                    transcript = hints.get("text") if isinstance(hints.get("text"), str) else None
-        if isinstance(transcript, str) and transcript:
-            if (
-                self._input_audio_buffer_transcript_parts
-                and self._input_audio_buffer_transcript_parts[-1] == transcript
-            ):
-                return
-            self._input_audio_buffer_transcript_parts.append(transcript)
+    def translate(self, payload: Mapping[str, object]) -> DuplexCommand:
+        """Wire event -> command (raises :class:`DuplexCommandError`)."""
+        if payload.get("type") == "session.update":
+            session = payload.get("session")
+            if isinstance(session, dict):
+                self.note_session_payload(session)
+        return translate_realtime_command(payload, defaults=self.defaults)
 
-    def _consume_input_transcript_hint(self) -> str:
-        transcript = "".join(self._input_audio_buffer_transcript_parts).strip()
-        self._input_audio_buffer_transcript_parts.clear()
-        return transcript
+    # ---- outbound helpers ----
 
     @staticmethod
-    def _input_transcript_from_item(item: dict[str, object]) -> str:
-        content = item.get("content")
-        if not isinstance(content, list):
-            return ""
-        parts: list[str] = []
-        for part in content:
-            if not isinstance(part, dict):
-                continue
-            for key in ("transcript", "text"):
-                value = part.get(key)
-                if isinstance(value, str) and value:
-                    if part.get("type") in {"input_audio", "audio", "audio_transcript", "transcript"}:
-                        parts.append(value)
-                        break
-        return "".join(parts).strip()
+    def error_payload(
+        code: str,
+        message: str,
+        *,
+        event_id: object | None = None,
+        param: object | None = None,
+    ) -> dict[str, object]:
+        """Wire JSON of a transport-level error (derived from the typed ``ErrorEvent``)."""
+        return error_event(code, message, event_id=event_id, param=param).to_realtime()
 
     @staticmethod
-    def _input_audio_transcription_completed_event(
-        item_id: str,
-        item: dict[str, object],
-    ) -> dict[str, object] | None:
-        content = item.get("content")
-        if not isinstance(content, list):
-            return None
-        transcript_parts: list[str] = []
-        for index, part in enumerate(content):
-            if not isinstance(part, dict):
-                continue
-            if part.get("type") != "input_audio":
-                continue
-            transcript = part.get("transcript")
-            if isinstance(transcript, str) and transcript:
-                transcript_parts.append(transcript)
-                return {
-                    "type": "conversation.item.input_audio_transcription.completed",
-                    "item_id": item_id,
-                    "content_index": index,
-                    "transcript": "".join(transcript_parts),
-                }
-        return None
-
-    async def _emit_input_speech_started(self, event: dict[str, object]) -> None:
-        if self._input_speech_started:
-            return
-        self._input_speech_started = True
-        if self._active_input_item_id is None:
-            self._active_input_item_id = f"item_{uuid4().hex}"
-        audio_start_ms = event.get("audio_start_ms", 0)
-        await self._send_realtime_payload(
-            {
-                "type": "input_audio_buffer.speech_started",
-                "audio_start_ms": int(audio_start_ms) if isinstance(audio_start_ms, int | float) else 0,
-                "item_id": self._active_input_item_id,
-            }
-        )
-
-    async def _emit_input_speech_stopped(self, event: dict[str, object], *, item_id: str) -> None:
-        if not self._input_speech_started:
-            return
-        self._input_speech_started = False
-        audio_end_ms = event.get("audio_end_ms", event.get("audio_ms", 0))
-        await self._send_realtime_payload(
-            {
-                "type": "input_audio_buffer.speech_stopped",
-                "audio_end_ms": int(audio_end_ms) if isinstance(audio_end_ms, int | float) else 0,
-                "item_id": item_id,
-            }
-        )
+    def command_error_payload(exc: DuplexCommandError) -> dict[str, object]:
+        return error_event(exc.code, str(exc), event_id=exc.event_id).to_realtime()
diff --git a/vllm_omni/entrypoints/duplex/realtime_output.py b/vllm_omni/entrypoints/duplex/realtime_output.py
deleted file mode 100644
index fcbdf87d7da..00000000000
--- a/vllm_omni/entrypoints/duplex/realtime_output.py
+++ /dev/null
@@ -1,1007 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-from typing import Any
-from uuid import uuid4
-
-from vllm_omni.entrypoints.duplex.audio import convert_output_audio
-from vllm_omni.entrypoints.duplex.realtime_state import (
-    _RealtimeResponseState,
-)
-
-
-class RealtimeOutputProjector:
-    """Project internal duplex events onto the OpenAI Realtime schema."""
-
-    def _from_duplex_event(self, event: dict[str, Any]) -> list[dict[str, object]]:
-        event_type = event.get("type")
-        if event_type == "session.created":
-            session = self._realtime_session_payload(event.get("session"))
-            created: dict[str, object] = {"type": "session.created", "session": session}
-            for key in (
-                "incarnation",
-                "attachment_generation",
-                "resume_token",
-            ):
-                if key in event:
-                    created[key] = event[key]
-            payloads: list[dict[str, object]] = [created]
-            if self._initial_session_update:
-                payloads.append({"type": "session.updated", "session": session})
-                self._initial_session_update = False
-            self._hold_realtime_output_until_session_created = False
-            if self._held_realtime_payloads:
-                payloads.extend(self._held_realtime_payloads)
-                self._held_realtime_payloads = []
-            return payloads
-        if event_type == "session.updated":
-            session = self._realtime_session_payload(event.get("session"))
-            return [{"type": "session.updated", "session": session}]
-        if event_type == "input_audio_buffer.speech_started":
-            item_id = event.get("item_id")
-            if isinstance(item_id, str):
-                self._active_input_item_id = item_id
-            self._input_speech_started = True
-            self._input_audio_buffer_has_audio = True
-            return [
-                {
-                    "type": "input_audio_buffer.speech_started",
-                    "audio_start_ms": max(0, int(event.get("audio_start_ms", 0) or 0)),
-                    "item_id": item_id,
-                }
-            ]
-        if event_type == "input_audio_buffer.speech_stopped":
-            self._input_speech_started = False
-            return [
-                {
-                    "type": "input_audio_buffer.speech_stopped",
-                    "audio_end_ms": max(0, int(event.get("audio_end_ms", 0) or 0)),
-                    "item_id": event.get("item_id") or self._active_input_item_id,
-                }
-            ]
-        if event_type in {
-            "session.resumed",
-            "session.heartbeat_ack",
-            "session.replaced",
-            "session.expired",
-            "session.resync_required",
-        }:
-            if event_type == "session.resumed":
-                self._hold_realtime_output_until_session_created = False
-            return [dict(event)]
-        if event_type == "response.created":
-            response_id = event.get("response_id")
-            if isinstance(response_id, str) and response_id:
-                self._active_response_id = response_id
-                self._last_response_id = response_id
-            item_id = self._response_item_id(response_id)
-            modalities = event.get("modalities")
-            has_audio_modality = not isinstance(modalities, list) or "audio" in modalities
-            item = {
-                "id": item_id,
-                "object": "realtime.item",
-                "type": "message",
-                "role": "assistant",
-                "status": "in_progress",
-                "content": [],
-            }
-            self._conversation_items[item_id] = item
-            payloads = [
-                self._response_created_event(event),
-                *self._conversation_item_added_events(item),
-                *self._response_output_item_added_events(response_id=response_id, item=item),
-            ]
-            if has_audio_modality:
-                payloads.extend(self._ensure_response_audio_part_added(response_id))
-            return payloads
-        if event_type == "response.listen":
-            listen_response: dict[str, object] = {
-                "object": "realtime.response",
-                "status": "listening",
-                "metadata": event,
-            }
-            listen_payload: dict[str, object] = {
-                "type": "response.listen",
-                "session_id": event.get("session_id"),
-                "epoch": event.get("epoch"),
-                "response": listen_response,
-            }
-            listen_response_id = event.get("response_id")
-            if isinstance(listen_response_id, str) and listen_response_id:
-                # Keep the response identity visible on the Realtime dialect:
-                # a listen that terminates a precreated response is matched to
-                # it by this id (clients demultiplex on response_id).
-                listen_response["id"] = listen_response_id
-                listen_payload["response_id"] = listen_response_id
-            return [listen_payload]
-        if event_type == "response.speak":
-            response_id = event.get("response_id")
-            state = self._response_state(response_id)
-            if state is not None:
-                if state.speak_emitted:
-                    return []
-                state.speak_emitted = True
-            return [
-                {
-                    "type": "response.speak",
-                    "response_id": response_id,
-                    "item_id": self._response_item_id(response_id),
-                    "output_index": 0,
-                    "content_index": 0,
-                    "metadata": self._response_speak_metadata(event),
-                }
-            ]
-        if event_type == "overlap.decision":
-            return [
-                {
-                    "type": "overlap.decision",
-                    "session_id": event.get("session_id"),
-                    "epoch": event.get("epoch"),
-                    "policy": event.get("policy"),
-                    "action": event.get("action"),
-                    "reason": event.get("reason"),
-                    "metadata": event,
-                }
-            ]
-        if event_type == "response.output_audio.delta":
-            response_id = event.get("response_id")
-            audio = event.get("audio", "")
-            payloads: list[dict[str, object]] = []
-            if isinstance(audio, str) and audio:
-                payloads.extend(self._ensure_response_audio_part_added(response_id))
-                payloads.extend(self._realtime_audio_delta_events(event, response_id, audio))
-                self._refresh_in_progress_response_item(response_id)
-            text = event.get("text")
-            has_text = isinstance(text, str) and bool(text)
-            if has_text:
-                self._append_response_transcript(response_id, text)
-                self._refresh_in_progress_response_item(response_id)
-            # Keep the audio.delta + transcript.delta pair invariant even for
-            # text-less units (deduplicated continuations, turn-end flush):
-            # clients that treat the pair as unit-complete would otherwise
-            # wait on a transcript that never comes.
-            emit_transcript = has_text or (isinstance(audio, str) and bool(audio))
-            if emit_transcript:
-                if not has_text:
-                    text = ""
-                payloads.append(
-                    {
-                        "type": "response.output_audio_transcript.delta",
-                        "response_id": response_id,
-                        "item_id": self._response_item_id(response_id),
-                        "output_index": 0,
-                        "content_index": 0,
-                        "delta": text,
-                    }
-                )
-            if event.get("end_of_turn") is True:
-                payloads.extend(self._realtime_audio_done_events(event, response_id))
-                payloads.extend(
-                    self._realtime_response_terminal_events(
-                        event,
-                        response_id,
-                        status="completed",
-                        status_details={
-                            "type": "completed",
-                            "reason": event.get("finish_reason") or "stop",
-                        },
-                    )
-                )
-            return payloads
-        if event_type == "response.text.delta":
-            response_id = event.get("response_id")
-            text = event.get("delta", "")
-            state = self._response_state(response_id)
-            if state is not None and isinstance(text, str) and text:
-                state.text_parts.append(text)
-                self._refresh_in_progress_response_item(response_id)
-            payloads = self._ensure_response_text_part_added(response_id)
-            payloads.append(
-                {
-                    "type": "response.output_text.delta",
-                    "response_id": response_id,
-                    "item_id": self._response_item_id(response_id),
-                    "output_index": 0,
-                    "content_index": 1 if state is not None and state.audio_part_added else 0,
-                    "delta": text,
-                }
-            )
-            return payloads
-        if event_type == "response.done":
-            response_id = event.get("response_id")
-            status = event.get("status") if isinstance(event.get("status"), str) else "completed"
-            status_details = event.get("status_details") if isinstance(event.get("status_details"), dict) else None
-            return [
-                *self._realtime_audio_done_events(event, response_id),
-                *self._realtime_response_terminal_events(
-                    event,
-                    response_id,
-                    status=status,
-                    status_details=status_details,
-                ),
-            ]
-        if event_type == "input.committed":
-            event_item_id = event.get("item_id")
-            # Acknowledgements carry their own identity; untracked silence
-            # commits must not consume another turn's item ID.
-            item_id = event_item_id if isinstance(event_item_id, str) and event_item_id else f"item_{uuid4().hex}"
-            # The reader may already have accepted audio for the next turn.
-            if self._active_input_item_id == item_id:
-                self._reset_realtime_input_buffer_state()
-            item = self._conversation_items.get(item_id)
-            payloads = [self._input_audio_buffer_committed_event(item_id=item_id)]
-            if item is None:
-                message = event.get("message")
-                no_response = event.get("no_response") is True
-                is_speech = event.get("is_speech")
-                item = {
-                    "id": item_id,
-                    "object": "realtime.item",
-                    "type": "message",
-                    "role": "user",
-                    "status": "completed",
-                    "content": (
-                        [{"type": "input_audio", "transcript": "", "is_speech": False}]
-                        if no_response and is_speech is False
-                        else self._user_item_content_from_duplex_message(message)
-                    ),
-                }
-                self._conversation_items[item_id] = item
-                payloads.extend(self._conversation_item_added_events(item))
-            item["status"] = "completed"
-            transcription_event = self._input_audio_transcription_completed_event(item_id, item)
-            if transcription_event is not None:
-                payloads.append(transcription_event)
-            payloads.append(self._conversation_item_done_event(item))
-            return payloads
-        if event_type == "input.cancelled":
-            self._reset_realtime_input_buffer_state()
-            return [{"type": "input_audio_buffer.cleared"}]
-        if event_type == "input_audio_buffer.cleared":
-            self._reset_realtime_input_buffer_state()
-            return [{"type": "input_audio_buffer.cleared"}]
-        if event_type == "audio.cancelled":
-            response_id = event.get("response_id")
-            payloads: list[dict[str, object]] = []
-            if event.get("reason") == "output_audio_buffer_clear":
-                if not isinstance(response_id, str) or not response_id:
-                    response_id = self._active_response_id or self._last_response_id
-                payloads.append(
-                    {
-                        "type": "output_audio_buffer.cleared",
-                        "response_id": response_id,
-                    }
-                )
-                if not isinstance(response_id, str) or not response_id:
-                    return payloads
-            elif not isinstance(response_id, str) or not response_id:
-                response_id = self._active_response_id
-            if not isinstance(response_id, str) or not response_id:
-                return payloads
-            if self._response_is_done(response_id):
-                return payloads
-            committed_ms = event.get("committed_ms")
-            if isinstance(committed_ms, int | float):
-                item_id = self._response_item_id(response_id)
-                committed_audio_ms = max(0, int(committed_ms))
-                self._item_truncation_cursors[item_id] = (0, committed_audio_ms)
-                item = self._conversation_items.get(item_id)
-                if item is not None:
-                    self._truncate_realtime_item_content(
-                        item,
-                        content_index=0,
-                        audio_end_ms=committed_audio_ms,
-                    )
-                # Align server history with acknowledged playback; only explicit
-                # client truncation emits ``conversation.item.truncated``.
-            payloads.extend(self._realtime_audio_done_events(event, response_id))
-            payloads.extend(
-                self._realtime_response_terminal_events(
-                    event,
-                    response_id,
-                    status="cancelled",
-                    status_details={
-                        "type": "cancelled",
-                        "reason": event.get("reason") or "client_cancelled",
-                    },
-                )
-            )
-            if isinstance(response_id, str) and response_id == self._active_response_id:
-                self._active_response_id = None
-            return payloads
-        if event_type == "playback.acknowledged":
-            return [{"type": "playback.acknowledged", "event": event}]
-        if event_type == "conversation.item.created":
-            item = event.get("item")
-            if isinstance(item, dict) and isinstance(item.get("id"), str):
-                item_id = str(item["id"])
-                already_known = item_id in self._conversation_items
-                self._conversation_items[item_id] = item
-                if already_known:
-                    if item.get("status") == "completed":
-                        return [self._conversation_item_done_event(item)]
-                    return []
-                payloads = self._conversation_item_added_events(item)
-                if item.get("status") == "completed":
-                    payloads.append(self._conversation_item_done_event(item))
-                return payloads
-            return [{"type": "conversation.item.created", "item": item, "event": event}]
-        if event_type == "conversation.item.deleted":
-            item_id = event.get("item_id")
-            if isinstance(item_id, str):
-                self._remove_conversation_item(item_id)
-            return [
-                {
-                    "type": "conversation.item.deleted",
-                    "item_id": item_id,
-                    "event": event,
-                }
-            ]
-        if event_type == "conversation.item.truncated":
-            item_id = event.get("item_id")
-            audio_end_ms = event.get("audio_end_ms")
-            content_index = event.get("content_index", 0)
-            if isinstance(item_id, str):
-                item = self._conversation_items.get(item_id)
-                if item is not None:
-                    self._truncate_realtime_item_content(
-                        item,
-                        content_index=int(content_index) if isinstance(content_index, int | float) else 0,
-                        audio_end_ms=int(audio_end_ms) if isinstance(audio_end_ms, int | float) else 0,
-                    )
-            return [
-                {
-                    "type": "conversation.item.truncated",
-                    "item_id": item_id,
-                    "content_index": content_index,
-                    "audio_end_ms": audio_end_ms,
-                    "event": event,
-                }
-            ]
-        if event_type == "response.output_item.done":
-            response_id = event.get("response_id")
-            return self._realtime_response_terminal_events(
-                event,
-                response_id,
-                status="completed",
-                status_details={
-                    "type": "completed",
-                    "reason": event.get("finish_reason") or "stop",
-                },
-            )
-        if event_type == "function_call.done":
-            call_id = event.get("call_id")
-            name = event.get("name")
-            arguments = event.get("arguments", "")
-            if not isinstance(call_id, str) or not call_id or not isinstance(name, str) or not name:
-                return [{"type": "duplex.function_call.done", "event": event}]
-            if not isinstance(arguments, str):
-                arguments = str(arguments)
-            response_id = f"resp_{uuid4().hex}"
-            item = {
-                "id": f"item_{uuid4().hex}",
-                "object": "realtime.item",
-                "type": "function_call",
-                "status": "completed",
-                "name": name,
-                "call_id": call_id,
-                "arguments": arguments,
-            }
-            self._conversation_items[str(item["id"])] = item
-            response = {
-                "id": response_id,
-                "object": "realtime.response",
-                "status": "completed",
-                "status_details": {"type": "completed", "reason": "completed"},
-                "output": [dict(item)],
-                "metadata": {},
-            }
-            return [
-                {"type": "response.created", "response": {**response, "status": "in_progress", "output": []}},
-                *self._conversation_item_added_events(item),
-                {
-                    "type": "response.output_item.added",
-                    "response_id": response_id,
-                    "output_index": 0,
-                    "item": dict(item),
-                },
-                {
-                    "type": "response.function_call_arguments.delta",
-                    "response_id": response_id,
-                    "item_id": item["id"],
-                    "output_index": 0,
-                    "call_id": call_id,
-                    "delta": arguments,
-                },
-                {
-                    "type": "response.function_call_arguments.done",
-                    "response_id": response_id,
-                    "item_id": item["id"],
-                    "output_index": 0,
-                    "call_id": call_id,
-                    "arguments": arguments,
-                },
-                {
-                    "type": "response.output_item.done",
-                    "response_id": response_id,
-                    "output_index": 0,
-                    "item": dict(item),
-                },
-                self._conversation_item_done_event(item),
-                {"type": "response.done", "response": response},
-            ]
-        if event_type == "error":
-            raw_error = event.get("error")
-            if isinstance(raw_error, dict):
-                return [event]
-            message = str(raw_error or event.get("message") or "Duplex runtime error")
-            code = str(event.get("code") or "duplex_error")
-            return [
-                self._realtime_error_payload(
-                    code,
-                    message,
-                    event_id=event.get("realtime_event_id") or event.get("event_id"),
-                    param=event.get("param"),
-                )
-            ]
-        if event_type == "session.closed":
-            return [{"type": "session.closed", "event": event}]
-        return [{"type": f"duplex.{event_type}", "event": event}]
-
-    @staticmethod
-    def _user_item_content_from_duplex_message(message: object) -> list[dict[str, object]]:
-        if not isinstance(message, dict):
-            return [{"type": "input_audio", "transcript": ""}]
-        message_transcript = message.get("transcript")
-        content = message.get("content")
-        if isinstance(content, str):
-            return [{"type": "input_text", "text": content}]
-        if not isinstance(content, list):
-            return [
-                {
-                    "type": "input_audio",
-                    "transcript": message_transcript if isinstance(message_transcript, str) else "",
-                }
-            ]
-        parts: list[dict[str, object]] = []
-        for part in content:
-            if not isinstance(part, dict):
-                continue
-            part_type = part.get("type")
-            if part_type in {"text", "input_text"} and isinstance(part.get("text"), str):
-                parts.append({"type": "input_text", "text": part["text"]})
-                continue
-            if part_type == "audio_url":
-                transcript = (
-                    part.get("transcript")
-                    if isinstance(part.get("transcript"), str)
-                    else message_transcript
-                    if isinstance(message_transcript, str)
-                    else ""
-                )
-                parts.append({"type": "input_audio", "transcript": transcript})
-                continue
-            if part_type in {"audio", "input_audio"}:
-                transcript = part.get("transcript") if isinstance(part.get("transcript"), str) else ""
-                parts.append({"type": "input_audio", "transcript": transcript})
-        return parts or [{"type": "input_audio", "transcript": ""}]
-
-    def _realtime_session_payload(self, session: object) -> object:
-        if not isinstance(session, dict):
-            return session
-        payload = dict(session)
-        payload.setdefault("object", "realtime.session")
-        payload.setdefault("type", "realtime")
-        payload.setdefault("id", payload.get("id") or self._default_session_id)
-        payload.setdefault("model", payload.get("model") or self._default_model)
-        payload.setdefault("input_audio_format", self._input_audio_format)
-        payload.setdefault("output_audio_format", self._output_audio_format)
-        payload.setdefault("modalities", payload.get("modalities") or ["text", "audio"])
-        payload.setdefault("output_modalities", payload.get("output_modalities") or payload.get("modalities"))
-        payload.setdefault("object", "realtime.session")
-        payload.setdefault(
-            "audio",
-            {
-                "input": {
-                    "format": self._realtime_audio_format_object(
-                        self._input_audio_format,
-                        sample_rate_hz=self._input_sample_rate_hz,
-                    ),
-                    "sample_rate_hz": self._input_sample_rate_hz,
-                },
-                "output": {
-                    "format": self._realtime_audio_format_object(
-                        self._output_audio_format,
-                        sample_rate_hz=self._output_sample_rate_hz,
-                    ),
-                },
-            },
-        )
-        if self._turn_detection_configured or "turn_detection" in payload:
-            turn_detection = payload.get("turn_detection", self._turn_detection)
-            audio = dict(payload["audio"]) if isinstance(payload.get("audio"), dict) else {}
-            audio_input = dict(audio["input"]) if isinstance(audio.get("input"), dict) else {}
-            audio_input["turn_detection"] = turn_detection
-            audio["input"] = audio_input
-            payload["audio"] = audio
-            payload["turn_detection"] = turn_detection
-        payload.setdefault("input_audio_transcription", payload.get("input_audio_transcription"))
-        payload.setdefault("tracing", payload.get("tracing"))
-        return payload
-
-    @staticmethod
-    def _realtime_audio_format_object(fmt: object, *, sample_rate_hz: int | None = None) -> dict[str, object]:
-        if isinstance(fmt, str) and fmt.lower() in {"pcm16", "pcm_s16le", "s16le", "pcm"}:
-            payload: dict[str, object] = {"type": "audio/pcm"}
-        elif isinstance(fmt, str) and fmt.lower() == "pcm_f32le":
-            payload = {"type": "audio/pcm_f32le"}
-        elif isinstance(fmt, str) and fmt.lower() == "g711_ulaw":
-            payload = {"type": "audio/g711_ulaw"}
-        elif isinstance(fmt, str) and fmt.lower() == "g711_alaw":
-            payload = {"type": "audio/g711_alaw"}
-        else:
-            payload = {"type": "audio/wav"}
-        if sample_rate_hz is not None:
-            payload["rate"] = int(sample_rate_hz)
-        return payload
-
-    def _response_state(
-        self,
-        response_id: object,
-        *,
-        event: dict[str, Any] | None = None,
-        create: bool = True,
-    ) -> _RealtimeResponseState | None:
-        if isinstance(response_id, str) and response_id:
-            key: str | int = response_id
-            item_id = f"item_{response_id}"
-        elif event is not None:
-            key = id(event)
-            item_id = f"item_{uuid4().hex}"
-        else:
-            return None
-        state = self._response_states.get(key)
-        if state is None and create:
-            state = _RealtimeResponseState(item_id=item_id)
-            self._response_states[key] = state
-        return state
-
-    def _response_is_done(self, response_id: object) -> bool:
-        state = self._response_state(response_id, create=False)
-        return state is not None and state.done_emitted
-
-    def _response_item_id(self, response_id: object) -> str:
-        state = self._response_state(response_id)
-        if state is not None:
-            return state.item_id
-        return f"item_{uuid4().hex}"
-
-    def _response_done_output_item(
-        self,
-        response_id: object,
-        *,
-        status: str,
-    ) -> dict[str, object]:
-        item_id = self._response_item_id(response_id)
-        state = self._response_state(response_id)
-        transcript = state.transcript if state is not None else ""
-        text = state.text if state is not None else ""
-        audio_duration_ms = state.audio_duration_ms if state is not None else None
-        audio_text_marks = state.audio_text_marks if state is not None else None
-        content: list[dict[str, object]] = []
-        if (state is not None and state.audio_part_added) or transcript or audio_duration_ms is not None:
-            content.append(
-                self._response_item_content_part(
-                    transcript=transcript,
-                    audio_duration_ms=audio_duration_ms,
-                    audio_text_marks=audio_text_marks,
-                )
-            )
-        if text:
-            content.append(self._response_item_text_content_part(text=text))
-        item = {
-            "id": item_id,
-            "object": "realtime.item",
-            "type": "message",
-            "role": "assistant",
-            "status": status,
-            "content": content,
-        }
-        self._apply_pending_item_truncation(item)
-        return item
-
-    def _apply_pending_item_truncation(self, item: dict[str, object]) -> None:
-        item_id = item.get("id")
-        if not isinstance(item_id, str) or not item_id:
-            return
-        cursor = self._item_truncation_cursors.get(item_id)
-        if cursor is None:
-            return
-        content_index, audio_end_ms = cursor
-        self._truncate_realtime_item_content(
-            item,
-            content_index=content_index,
-            audio_end_ms=audio_end_ms,
-        )
-
-    def _refresh_in_progress_response_item(self, response_id: object) -> None:
-        if not isinstance(response_id, str) or not response_id:
-            return
-        item_id = self._response_item_id(response_id)
-        item = self._conversation_items.get(item_id)
-        if not isinstance(item, dict):
-            return
-        content = item.get("content")
-        if not isinstance(content, list):
-            content = []
-            item["content"] = content
-
-        state = self._response_state(response_id)
-        if state is None:
-            return
-        transcript = state.transcript
-        audio_duration_ms = state.audio_duration_ms
-        audio_text_marks = state.audio_text_marks
-        has_audio = state.audio_part_added or bool(transcript) or audio_duration_ms is not None
-        if has_audio:
-            audio_part = self._response_item_content_part(
-                transcript=transcript,
-                audio_duration_ms=audio_duration_ms,
-                audio_text_marks=audio_text_marks,
-            )
-            if content and isinstance(content[0], dict) and content[0].get("type") in {"audio", "output_audio"}:
-                content[0] = audio_part
-            else:
-                content.insert(0, audio_part)
-
-        text = state.text
-        if text:
-            text_index = (
-                1
-                if content
-                and isinstance(content[0], dict)
-                and content[0].get("type")
-                in {
-                    "audio",
-                    "output_audio",
-                }
-                else 0
-            )
-            text_part = self._response_item_text_content_part(text=text)
-            if (
-                len(content) > text_index
-                and isinstance(content[text_index], dict)
-                and content[text_index].get("type") in {"text", "output_text"}
-            ):
-                content[text_index] = text_part
-            else:
-                content.insert(text_index, text_part)
-
-        self._apply_pending_item_truncation(item)
-
-    def _append_response_transcript(self, response_id: object, text: str) -> None:
-        state = self._response_state(response_id)
-        if state is None or not text:
-            return
-        state.transcript_parts.append(text)
-
-    def _ensure_response_text_part_added(self, response_id: object) -> list[dict[str, object]]:
-        state = self._response_state(response_id)
-        if state is None:
-            return []
-        if state.text_part_added:
-            return []
-        state.text_part_added = True
-        content_index = 1 if state.audio_part_added else 0
-        return [
-            {
-                "type": "response.content_part.added",
-                "response_id": response_id,
-                "item_id": self._response_item_id(response_id),
-                "output_index": 0,
-                "content_index": content_index,
-                "part": self._response_text_content_part(),
-            }
-        ]
-
-    def _ensure_response_audio_part_added(self, response_id: object) -> list[dict[str, object]]:
-        state = self._response_state(response_id)
-        if state is None:
-            return []
-        if state.audio_part_added:
-            return []
-        state.audio_part_added = True
-        return [
-            {
-                "type": "response.content_part.added",
-                "response_id": response_id,
-                "item_id": self._response_item_id(response_id),
-                "output_index": 0,
-                "content_index": 0,
-                "part": self._response_content_part(),
-            }
-        ]
-
-    def _remember_response_audio_metadata(self, response_id: object, event: dict[str, Any]) -> None:
-        state = self._response_state(response_id)
-        if state is None:
-            return
-        duration = event.get("audio_duration_ms")
-        playback = event.get("playback")
-        if not isinstance(duration, int | float) and isinstance(playback, dict):
-            duration = playback.get("sent_ms") or playback.get("generated_ms")
-        if isinstance(duration, int | float):
-            state.audio_duration_ms = max(state.audio_duration_ms or 0, int(duration))
-        marks = event.get("audio_text_marks")
-        if not isinstance(marks, list):
-            return
-        clean_marks: list[dict[str, int]] = []
-        for mark in marks:
-            if not isinstance(mark, dict):
-                continue
-            text_chars = mark.get("text_chars")
-            audio_end_ms = mark.get("audio_end_ms", mark.get("audio_ms"))
-            if not isinstance(text_chars, int | float) or not isinstance(audio_end_ms, int | float):
-                continue
-            clean_marks.append(
-                {
-                    "text_chars": max(0, int(text_chars)),
-                    "audio_end_ms": max(0, int(audio_end_ms)),
-                }
-            )
-        if clean_marks:
-            merged = list(state.audio_text_marks)
-            merged.extend(clean_marks)
-            deduped: dict[tuple[int, int], dict[str, int]] = {}
-            for mark in merged:
-                deduped[(int(mark["audio_end_ms"]), int(mark["text_chars"]))] = mark
-            state.audio_text_marks = sorted(
-                deduped.values(),
-                key=lambda mark: (mark["audio_end_ms"], mark["text_chars"]),
-            )
-
-    def _response_created_event(self, event: dict[str, Any]) -> dict[str, object]:
-        response_id = event.get("response_id")
-        metadata = event.get("metadata")
-        if not isinstance(metadata, dict):
-            metadata = {}
-        metadata = {**metadata, "duplex_event": event}
-        return {
-            "type": "response.created",
-            "response_id": response_id,
-            "response": {
-                "id": response_id,
-                "object": "realtime.response",
-                "status": "in_progress",
-                "status_details": None,
-                "output": [],
-                "modalities": event.get("modalities") or ["audio", "text"],
-                "metadata": metadata,
-            },
-        }
-
-    def _realtime_audio_delta_events(
-        self,
-        event: dict[str, Any],
-        response_id: object,
-        audio: str,
-    ) -> list[dict[str, object]]:
-        item_id = self._response_item_id(response_id)
-        fmt, format_rate = self._parse_realtime_audio_format(event.get("format", "wav"))
-        source_fmt = self._realtime_output_format(fmt)
-        source_sample_rate_hz = event.get("sample_rate_hz") or format_rate
-        target_sample_rate_hz = (
-            self._output_sample_rate_hz if self._output_audio_format in {"g711_ulaw", "g711_alaw"} else None
-        )
-        audio, fmt, converted_sample_rate_hz = convert_output_audio(
-            audio,
-            source_fmt=source_fmt,
-            target_fmt=self._output_audio_format,
-            source_sample_rate_hz=(
-                int(source_sample_rate_hz) if isinstance(source_sample_rate_hz, int | float) else None
-            ),
-            target_sample_rate_hz=target_sample_rate_hz,
-        )
-        sample_rate_hz = (
-            converted_sample_rate_hz
-            if fmt in {"g711_ulaw", "g711_alaw"}
-            else event.get("sample_rate_hz") or format_rate or self._output_sample_rate_hz
-        )
-        metadata: dict[str, object] = {}
-        for key in ("session_id", "epoch", "model_speak", "end_of_turn", "playback", "vllm_omni"):
-            if key in event:
-                metadata[key] = event[key]
-        duration_ms = event.get("audio_duration_ms")
-        if isinstance(duration_ms, int | float):
-            metadata["audio_duration_ms"] = int(duration_ms)
-        marks = event.get("audio_text_marks")
-        if isinstance(marks, list):
-            metadata["audio_text_marks"] = marks
-        state = self._response_state(response_id)
-        if state is not None:
-            state.audio_delta_emitted = True
-            self._remember_response_audio_metadata(response_id, event)
-        payloads: list[dict[str, object]] = []
-        if state is not None and not state.speak_emitted and metadata.get("model_speak") is True:
-            state.speak_emitted = True
-            payloads.insert(
-                0,
-                {
-                    "type": "response.speak",
-                    "response_id": response_id,
-                    "item_id": item_id,
-                    "output_index": 0,
-                    "content_index": 0,
-                    "metadata": self._response_speak_metadata(event),
-                },
-            )
-        payloads.append(
-            {
-                "type": "response.output_audio.delta",
-                "response_id": response_id,
-                "item_id": item_id,
-                "output_index": 0,
-                "content_index": 0,
-                "delta": audio,
-                "format": fmt,
-                **({"sample_rate_hz": int(sample_rate_hz)} if isinstance(sample_rate_hz, int | float) else {}),
-                **({"metadata": metadata} if metadata else {}),
-            }
-        )
-        return payloads
-
-    @staticmethod
-    def _response_speak_metadata(event: dict[str, Any]) -> dict[str, object]:
-        return {key: event[key] for key in ("session_id", "epoch", "model_speak") if key in event}
-
-    def _realtime_audio_done_events(
-        self,
-        event: dict[str, Any],
-        response_id: object,
-    ) -> list[dict[str, object]]:
-        item_id = self._response_item_id(response_id)
-        state = self._response_state(response_id, event=event)
-        transcript = state.transcript if state is not None else ""
-        payloads: list[dict[str, object]] = []
-        if isinstance(response_id, str) and state is not None and not state.audio_delta_emitted and not transcript:
-            return payloads
-        if state is None or not state.audio_done_emitted:
-            if state is not None:
-                state.audio_done_emitted = True
-            payloads.append(
-                {
-                    "type": "response.output_audio.done",
-                    "response_id": response_id,
-                    "item_id": item_id,
-                    "output_index": 0,
-                    "content_index": 0,
-                }
-            )
-            if transcript:
-                payloads.append(
-                    {
-                        "type": "response.output_audio_transcript.done",
-                        "response_id": response_id,
-                        "item_id": item_id,
-                        "output_index": 0,
-                        "content_index": 0,
-                        "transcript": transcript,
-                    }
-                )
-        return payloads
-
-    def _realtime_response_terminal_events(
-        self,
-        event: dict[str, Any],
-        response_id: object,
-        *,
-        status: str = "completed",
-        status_details: dict[str, object] | None = None,
-    ) -> list[dict[str, object]]:
-        item_id = self._response_item_id(response_id)
-        state = self._response_state(response_id, event=event)
-        transcript = state.transcript if state is not None else ""
-        payloads: list[dict[str, object]] = []
-        if state is not None and state.audio_part_added and not state.audio_part_done:
-            state.audio_part_done = True
-            payloads.append(
-                {
-                    "type": "response.content_part.done",
-                    "response_id": response_id,
-                    "item_id": item_id,
-                    "output_index": 0,
-                    "content_index": 0,
-                    "part": self._response_content_part(transcript=transcript),
-                }
-            )
-        if state is not None and state.text_parts and not state.output_text_done:
-            state.output_text_done = True
-            content_index = 1 if state.audio_part_added else 0
-            payloads.append(
-                {
-                    "type": "response.output_text.done",
-                    "response_id": response_id,
-                    "item_id": item_id,
-                    "output_index": 0,
-                    "content_index": content_index,
-                    "text": state.text,
-                }
-            )
-        if state is not None and state.text_parts and not state.text_part_done:
-            state.text_part_done = True
-            content_index = 1 if state.audio_part_added else 0
-            payloads.append(
-                {
-                    "type": "response.content_part.done",
-                    "response_id": response_id,
-                    "item_id": item_id,
-                    "output_index": 0,
-                    "content_index": content_index,
-                    "part": self._response_text_content_part(text=state.text),
-                }
-            )
-        if state is None or not state.output_item_done:
-            if state is not None:
-                state.output_item_done = True
-            item = self._response_done_output_item(response_id, status=status)
-            payloads.append(
-                {
-                    "type": "response.output_item.done",
-                    "response_id": response_id,
-                    "output_index": 0,
-                    "item": item,
-                }
-            )
-            if state is None or not state.conversation_item_done:
-                if state is not None:
-                    state.conversation_item_done = True
-                payloads.append(self._conversation_item_done_event(item))
-        done_event = self._realtime_response_done_event(
-            {**event, "response_id": response_id},
-            state=state,
-            status=status,
-            status_details=status_details,
-        )
-        if done_event is not None:
-            payloads.append(done_event)
-            payloads.append(self._rate_limits_updated_event())
-            if isinstance(response_id, str) and response_id == self._active_response_id:
-                self._active_response_id = None
-        return payloads
-
-    def _realtime_response_done_event(
-        self,
-        event: dict[str, Any],
-        *,
-        state: _RealtimeResponseState | None = None,
-        status: str = "completed",
-        status_details: dict[str, object] | None = None,
-    ) -> dict[str, object] | None:
-        response_id = event.get("response_id")
-        if state is None:
-            state = self._response_state(response_id, event=event)
-        if state is not None:
-            if state.done_emitted:
-                return None
-            state.done_emitted = True
-        return {
-            "type": "response.done",
-            "response_id": response_id,
-            "response": {
-                "id": response_id,
-                "object": "realtime.response",
-                "status": status,
-                "status_details": status_details,
-                "output": [self._response_done_output_item(response_id, status=status)],
-                "metadata": event,
-            },
-        }
-
-    @staticmethod
-    def _rate_limits_updated_event() -> dict[str, object]:
-        # vLLM-Omni does not yet expose a Realtime-specific quota budget. Emit
-        # the terminal event with an empty list so clients that sequence on
-        # rate_limits.updated do not need a private vLLM branch.
-        return {"type": "rate_limits.updated", "rate_limits": []}
diff --git a/vllm_omni/entrypoints/duplex/realtime_session.py b/vllm_omni/entrypoints/duplex/realtime_session.py
deleted file mode 100644
index 122a7ab52ce..00000000000
--- a/vllm_omni/entrypoints/duplex/realtime_session.py
+++ /dev/null
@@ -1,147 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import json
-from typing import Any
-from uuid import uuid4
-
-from fastapi import WebSocket
-
-from vllm_omni.entrypoints.duplex import realtime_state as _state
-from vllm_omni.entrypoints.duplex.realtime_input import (
-    RealtimeInputTranslator,
-)
-from vllm_omni.entrypoints.duplex.realtime_output import (
-    RealtimeOutputProjector,
-)
-
-REALTIME_ERROR_TYPES_BY_CODE = _state.REALTIME_ERROR_TYPES_BY_CODE
-REALTIME_INPUT_AUDIO_FORMATS = _state.REALTIME_INPUT_AUDIO_FORMATS
-REALTIME_OUTPUT_AUDIO_FORMATS = _state.REALTIME_OUTPUT_AUDIO_FORMATS
-RealtimeSessionState = _state.RealtimeSessionState
-_RealtimeResponseState = _state._RealtimeResponseState
-
-
-class NativeRealtimeSessionProtocol(
-    RealtimeInputTranslator,
-    RealtimeOutputProjector,
-    _state.RealtimeStateOwner,
-):
-    """Compatibility facade for one native Realtime protocol session.
-
-    Input translation, output projection, and mutable state have separate
-    owners. The facade retains the established import path and private helper
-    surface used by serving and protocol contract tests.
-    """
-
-    def __init__(self, query_params: Any) -> None:
-        self._state = RealtimeSessionState.from_query_params(query_params)
-
-    def bind_sender(self, send_realtime_json) -> None:
-        self._send_realtime_json = send_realtime_json
-
-    def bind_native_input_append(self, enabled: bool) -> None:
-        """Use the serving-selected input path, independent of interruption policy."""
-        self._native_input_append = enabled
-
-    def _default_session_payload(self) -> dict[str, object]:
-        payload: dict[str, object] = {
-            "model": self._default_model,
-            "session_id": self._default_session_id,
-        }
-        if self._default_extra_body:
-            payload["extra_body"] = dict(self._default_extra_body)
-        return payload
-
-    async def receive_internal_event_text(self, websocket: WebSocket) -> str:
-        if not self._pending_outbound.empty():
-            return json.dumps(await self._pending_outbound.get())
-        if not self._opened and not self._resume_only and not self._autostarted_default_session and self._default_model:
-            self._opened = True
-            self._autostarted_default_session = True
-            return json.dumps(self._session_create_from_realtime(self._default_session_payload()))
-        while True:
-            if not self._pending_outbound.empty():
-                return json.dumps(await self._pending_outbound.get())
-            await self.wait_for_realtime_turn_detection_update()
-            raw = await websocket.receive_text()
-            try:
-                event = json.loads(raw)
-            except json.JSONDecodeError:
-                return raw
-            if not isinstance(event, dict):
-                return raw
-            if not self._opened and event.get("type") == "session.resume":
-                self._opened = True
-                translated = await self._to_duplex_event(event)
-                if translated is None:
-                    if not self._pending_outbound.empty():
-                        return json.dumps(await self._pending_outbound.get())
-                    continue
-                return json.dumps(translated)
-            if not self._opened and self._resume_only:
-                translated = await self._to_duplex_event(event)
-                if translated is None:
-                    if not self._pending_outbound.empty():
-                        return json.dumps(await self._pending_outbound.get())
-                    continue
-                return json.dumps(translated)
-            if not self._opened and event.get("type") != "session.update":
-                self._opened = True
-                await self._pending_outbound.put(self._session_create_from_realtime(self._default_session_payload()))
-                translated = await self._to_duplex_event(event)
-                if translated is not None:
-                    await self._send_realtime_input_ack(event)
-                    await self._pending_outbound.put(translated)
-                return json.dumps(await self._pending_outbound.get())
-            translated = await self._to_duplex_event(event)
-            if translated is None:
-                if not self._pending_outbound.empty():
-                    return json.dumps(await self._pending_outbound.get())
-                continue
-            await self._send_realtime_input_ack(event)
-            return json.dumps(translated)
-
-    def encode_outbound_event(self, data: dict[str, Any]) -> list[dict[str, object]]:
-        payloads = self._from_duplex_event(data)
-        for payload in payloads:
-            self._attach_event_id(payload)
-        return payloads
-
-    @staticmethod
-    def _attach_event_id(payload: dict[str, object]) -> None:
-        payload.setdefault("event_id", f"event_{uuid4().hex}")
-
-    async def _send_realtime_payload(self, payload: dict[str, object]) -> None:
-        self._attach_event_id(payload)
-        if (
-            self._hold_realtime_output_until_session_created
-            and payload.get("type") != "error"
-            and payload.get("type") != "session.created"
-        ):
-            self._held_realtime_payloads.append(payload)
-            return
-        if self._send_realtime_json is None:
-            raise RuntimeError("Native Realtime sender is not bound")
-        await self._send_realtime_json(payload)
-
-    @staticmethod
-    def _realtime_error_payload(
-        code: str,
-        message: str,
-        *,
-        event_id: object | None = None,
-        param: object | None = None,
-    ) -> dict[str, object]:
-        error: dict[str, object] = {
-            "type": REALTIME_ERROR_TYPES_BY_CODE.get(code, "invalid_request_error"),
-            "code": code,
-            "message": message,
-        }
-        if isinstance(event_id, str) and event_id:
-            error["event_id"] = event_id
-        if isinstance(param, str) and param:
-            error["param"] = param
-        return {"type": "error", "error": error}
diff --git a/vllm_omni/entrypoints/duplex/realtime_state.py b/vllm_omni/entrypoints/duplex/realtime_state.py
deleted file mode 100644
index babb470a5df..00000000000
--- a/vllm_omni/entrypoints/duplex/realtime_state.py
+++ /dev/null
@@ -1,245 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-from dataclasses import dataclass, field
-from typing import Any, Generic, TypeVar
-
-REALTIME_INPUT_AUDIO_FORMATS = {
-    "pcm16",
-    "pcm_s16le",
-    "s16le",
-    "pcm_f32le",
-    "g711_ulaw",
-    "g711_alaw",
-}
-REALTIME_OUTPUT_AUDIO_FORMATS = {
-    "pcm16",
-    "pcm_s16le",
-    "s16le",
-    "wav",
-    "pcm",
-    "g711_ulaw",
-    "g711_alaw",
-}
-REALTIME_PCM_DEFAULT_SAMPLE_RATE_HZ = 24_000
-REALTIME_PCM_F32_DEFAULT_SAMPLE_RATE_HZ = 16_000
-REALTIME_G711_DEFAULT_SAMPLE_RATE_HZ = 8_000
-
-_RealtimeProtocolConfig = tuple[str, int, str, int | None, float]
-_PendingTurnDetectionUpdate = tuple[
-    bool,
-    dict[str, object] | None,
-    asyncio.Event,
-    _RealtimeProtocolConfig,
-]
-
-
-def realtime_default_sample_rate_hz(fmt: object) -> int | None:
-    if not isinstance(fmt, str):
-        return None
-    normalized = fmt.lower()
-    if normalized in {"pcm16", "pcm_s16le", "s16le", "pcm", "audio/pcm"}:
-        return REALTIME_PCM_DEFAULT_SAMPLE_RATE_HZ
-    if normalized in {"pcm_f32le", "audio/pcm_f32le"}:
-        return REALTIME_PCM_F32_DEFAULT_SAMPLE_RATE_HZ
-    if normalized in {"g711_ulaw", "g711_alaw", "audio/g711_ulaw", "audio/g711_alaw"}:
-        return REALTIME_G711_DEFAULT_SAMPLE_RATE_HZ
-    return None
-
-
-REALTIME_ERROR_TYPES_BY_CODE = {
-    "bad_event": "invalid_request_error",
-    "bad_audio": "invalid_request_error",
-    "config_timeout": "invalid_request_error",
-    "invalid_json": "invalid_request_error",
-    "event_too_large": "invalid_request_error",
-    "unknown_event": "invalid_request_error",
-    "internal_error": "server_error",
-    "runtime_open_failed": "server_error",
-    "runtime_open_unsupported": "server_error",
-    "runtime_append_failed": "server_error",
-    "runtime_append_task_failed": "server_error",
-    "runtime_signal_failed": "server_error",
-    "runtime_close_failed": "server_error",
-    "runtime_abort_failed": "server_error",
-    "runtime_data_plane_stream_failed": "server_error",
-    "runtime_data_plane_text_without_audio": "server_error",
-    "response_error": "server_error",
-    "chat_error": "server_error",
-    "server_vad_initialization_failed": "server_error",
-    "server_vad_inference_failed": "server_error",
-    "duplex_session_busy": "rate_limit_error",
-    "resource_exhausted": "rate_limit_error",
-    "input_backpressure": "rate_limit_error",
-    "response_already_active": "invalid_request_error",
-    "response_not_active": "invalid_request_error",
-    "response_create_without_input": "invalid_request_error",
-    "input_audio_buffer_empty": "invalid_request_error",
-    "server_vad_manual_commit_unsupported": "invalid_request_error",
-    "missing_item_id": "invalid_request_error",
-    "item_not_found": "invalid_request_error",
-    "playback_item_mismatch": "invalid_request_error",
-    "playback_item_not_found": "invalid_request_error",
-    "playback_ack_too_late": "invalid_request_error",
-    "unsupported_audio_format": "invalid_request_error",
-    "unsupported_ref_audio_path": "invalid_request_error",
-    "ref_audio_required": "invalid_request_error",
-    "model_update_unsupported": "invalid_request_error",
-    "voice_update_after_audio_unsupported": "invalid_request_error",
-    "ref_audio_update_unsupported": "invalid_request_error",
-    "native_text_append_unsupported": "invalid_request_error",
-    "runtime_native_stage_role_required": "server_error",
-    "runtime_native_runner_kv_required": "server_error",
-}
-
-
-@dataclass(slots=True)
-class _RealtimeResponseState:
-    item_id: str
-    transcript_parts: list[str] = field(default_factory=list)
-    text_parts: list[str] = field(default_factory=list)
-    audio_duration_ms: int | None = None
-    audio_text_marks: list[dict[str, int]] = field(default_factory=list)
-    audio_delta_emitted: bool = False
-    audio_done_emitted: bool = False
-    audio_part_added: bool = False
-    audio_part_done: bool = False
-    text_part_added: bool = False
-    text_part_done: bool = False
-    output_text_done: bool = False
-    output_item_done: bool = False
-    conversation_item_done: bool = False
-    speak_emitted: bool = False
-    done_emitted: bool = False
-
-    @property
-    def transcript(self) -> str:
-        return "".join(self.transcript_parts)
-
-    @property
-    def text(self) -> str:
-        return "".join(self.text_parts)
-
-
-@dataclass(slots=True)
-class RealtimeSessionState:
-    """Single mutable authority for one Realtime protocol session."""
-
-    _opened: bool = False
-    _autostarted_default_session: bool = False
-    _resume_only: bool = False
-    _pending_outbound: asyncio.Queue[dict[str, object]] = field(default_factory=asyncio.Queue)
-    _held_realtime_payloads: list[dict[str, object]] = field(default_factory=list)
-    _hold_realtime_output_until_session_created: bool = True
-    _default_model: object | None = None
-    _default_session_id: object | None = None
-    _default_extra_body: dict[str, object] = field(default_factory=dict)
-    _input_audio_format: str = "pcm16"
-    _input_sample_rate_hz: int = REALTIME_PCM_DEFAULT_SAMPLE_RATE_HZ
-    _output_audio_format: str = "pcm16"
-    _overlap_silence_rms: float = 0.003
-    _turn_detection: dict[str, object] | None = None
-    _native_input_append: bool = False
-    _pending_turn_detection_update: _PendingTurnDetectionUpdate | None = None
-    _send_realtime_json: Any = None
-    _initial_session_update: bool = False
-    _input_speech_started: bool = False
-    _response_states: dict[str | int, _RealtimeResponseState] = field(default_factory=dict)
-    _item_truncation_cursors: dict[str, tuple[int, int]] = field(default_factory=dict)
-    _active_response_id: str | None = None
-    _last_response_id: str | None = None
-    _conversation_items: dict[str, dict[str, object]] = field(default_factory=dict)
-    _last_conversation_item_id: str | None = None
-    _output_sample_rate_hz: int | None = None
-    _active_input_item_id: str | None = None
-    _input_audio_buffer_has_audio: bool = False
-    _input_audio_buffer_had_non_speech: bool = False
-    _input_audio_buffer_transcript_parts: list[str] = field(default_factory=list)
-    _turn_detection_configured: bool = False
-
-    @classmethod
-    def from_query_params(cls, query_params: Any) -> RealtimeSessionState:
-        if hasattr(query_params, "query_params"):
-            query_params = query_params.query_params
-        getter = query_params.get if hasattr(query_params, "get") else None
-        # Canonical query param plus the deprecated model-prefixed alias;
-        # both seed the canonical extra_body key.
-        native_duplex = None
-        if getter is not None:
-            native_duplex = getter("native_duplex")
-            if native_duplex is None:
-                native_duplex = getter("minicpmo45_native_duplex")
-        resume_only = getter("resume") if getter is not None else None
-        autostart = getter("autostart") if getter is not None else None
-        default_extra_body = {}
-        if str(native_duplex).strip().lower() in {"1", "true", "yes", "on"}:
-            default_extra_body["native_duplex"] = True
-        return cls(
-            _resume_only=(
-                str(resume_only).strip().lower() in {"1", "true", "yes", "on"}
-                or str(autostart).strip().lower() in {"0", "false", "no", "off"}
-            ),
-            _default_model=getter("model") if getter is not None else None,
-            _default_session_id=(getter("session_id") if getter is not None else None),
-            _default_extra_body=default_extra_body,
-        )
-
-
-_StateValue = TypeVar("_StateValue")
-
-
-class _RealtimeStateField(Generic[_StateValue]):
-    """Explicit descriptor binding one protocol attribute to session state."""
-
-    def __set_name__(self, owner: type, name: str) -> None:
-        del owner
-        self._name = name
-
-    def __get__(self, instance: Any, owner: type | None = None) -> _StateValue | _RealtimeStateField[_StateValue]:
-        del owner
-        if instance is None:
-            return self
-        return getattr(instance._state, self._name)
-
-    def __set__(self, instance: Any, value: _StateValue) -> None:
-        setattr(instance._state, self._name, value)
-
-
-class RealtimeStateOwner:
-    """Declare the mutable state surface shared by input/output projectors."""
-
-    _state: RealtimeSessionState
-    _opened: bool = _RealtimeStateField()
-    _autostarted_default_session: bool = _RealtimeStateField()
-    _resume_only: bool = _RealtimeStateField()
-    _pending_outbound: asyncio.Queue[dict[str, object]] = _RealtimeStateField()
-    _held_realtime_payloads: list[dict[str, object]] = _RealtimeStateField()
-    _hold_realtime_output_until_session_created: bool = _RealtimeStateField()
-    _default_model: object | None = _RealtimeStateField()
-    _default_session_id: object | None = _RealtimeStateField()
-    _default_extra_body: dict[str, object] = _RealtimeStateField()
-    _input_audio_format: str = _RealtimeStateField()
-    _input_sample_rate_hz: int = _RealtimeStateField()
-    _output_audio_format: str = _RealtimeStateField()
-    _overlap_silence_rms: float = _RealtimeStateField()
-    _turn_detection: dict[str, object] | None = _RealtimeStateField()
-    _native_input_append: bool = _RealtimeStateField()
-    _pending_turn_detection_update: _PendingTurnDetectionUpdate | None = _RealtimeStateField()
-    _send_realtime_json: Any = _RealtimeStateField()
-    _initial_session_update: bool = _RealtimeStateField()
-    _input_speech_started: bool = _RealtimeStateField()
-    _response_states: dict[str | int, _RealtimeResponseState] = _RealtimeStateField()
-    _item_truncation_cursors: dict[str, tuple[int, int]] = _RealtimeStateField()
-    _active_response_id: str | None = _RealtimeStateField()
-    _last_response_id: str | None = _RealtimeStateField()
-    _conversation_items: dict[str, dict[str, object]] = _RealtimeStateField()
-    _last_conversation_item_id: str | None = _RealtimeStateField()
-    _output_sample_rate_hz: int | None = _RealtimeStateField()
-    _active_input_item_id: str | None = _RealtimeStateField()
-    _input_audio_buffer_has_audio: bool = _RealtimeStateField()
-    _input_audio_buffer_had_non_speech: bool = _RealtimeStateField()
-    _input_audio_buffer_transcript_parts: list[str] = _RealtimeStateField()
-    _turn_detection_configured: bool = _RealtimeStateField()
diff --git a/vllm_omni/entrypoints/duplex/runtime_adapter.py b/vllm_omni/entrypoints/duplex/runtime_adapter.py
deleted file mode 100644
index a873f33a876..00000000000
--- a/vllm_omni/entrypoints/duplex/runtime_adapter.py
+++ /dev/null
@@ -1,331 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-from collections.abc import Awaitable, Callable, Iterable, Mapping, MutableMapping
-from dataclasses import dataclass, field
-from importlib import import_module
-from typing import Any, Protocol
-
-
-class ServingRuntimeConfigError(ValueError):
-    """A model serving plugin rejected client-visible runtime configuration."""
-
-    def __init__(self, message: str, *, code: str = "invalid_duplex_runtime_config") -> None:
-        super().__init__(message)
-        self.code = code
-
-
-def reject_changed_runtime_value(
-    new_value: object,
-    current_value: object,
-    *,
-    message: str,
-    code: str,
-    error_cls: type[ServingRuntimeConfigError] = ServingRuntimeConfigError,
-) -> None:
-    if new_value != current_value:
-        raise error_cls(message, code=code)
-
-
-class PcmAppendReservation(Protocol):
-    operation_id: str
-    payload: dict[str, object] | None
-
-    @property
-    def active(self) -> bool: ...
-
-    @property
-    def byte_count(self) -> int: ...
-
-    def commit(self) -> None: ...
-
-    def rollback(self) -> None: ...
-
-
-class PcmAppendBuffer(Protocol):
-    @property
-    def pending_byte_count(self) -> int: ...
-
-    def clear(self) -> None: ...
-
-    def clear_force_listen(self) -> None: ...
-
-    def has_pending(self) -> bool: ...
-
-    def has_reserved(self) -> bool: ...
-
-    def prepare_append(
-        self,
-        payload: dict[str, object],
-        *,
-        operation_id: str,
-        chunk_period_ms: int,
-        allow_emit: bool,
-    ) -> PcmAppendReservation | None: ...
-
-    def prepare_commit(
-        self,
-        *,
-        operation_id: str,
-        chunk_period_ms: int,
-    ) -> PcmAppendReservation: ...
-
-    def flush(self, *, chunk_period_ms: int) -> dict[str, object] | None: ...
-
-
-class ServingRuntimeSessionState(Protocol):
-    audio_buffer: PcmAppendBuffer
-    input_since_commit: bool
-    speech_since_commit: bool
-    native_context_locked: bool
-    committed_audio_payload: dict[str, object] | None
-    committed_audio_operation_id: str | None
-    committed_audio_reserved_bytes: int
-    deferred_response_create: bool
-    deferred_precreate_response: bool
-    data_plane_task: asyncio.Task[None] | None
-    data_plane_restart_requested: bool
-    continuation_owner_id: str | None
-    continuation_units: int
-    pending_silence_task: asyncio.Task[bool] | None
-    pending_silence_owner_id: str | None
-    silence_continuation_scheduler: Callable[..., Awaitable[bool]] | None
-
-    def retain_committed_audio(
-        self,
-        payload: dict[str, object],
-        *,
-        operation_id: str | None,
-        reserved_bytes: int = 0,
-    ) -> None: ...
-
-    def clear_committed_audio(self) -> int: ...
-
-    def clear_continuation(self) -> None: ...
-
-
-class _TurnBasedPcmAppendBuffer:
-    """Empty native-audio buffer for chat-fallback sessions.
-
-    Turn-based sessions keep input audio in ``DuplexSession`` and never use
-    the model-native append path.  The runner still shares lifecycle and
-    cancellation code with native sessions, so it needs an inert buffer for
-    those common operations.
-    """
-
-    @property
-    def pending_byte_count(self) -> int:
-        return 0
-
-    def clear(self) -> None:
-        return None
-
-    def clear_force_listen(self) -> None:
-        return None
-
-    def has_pending(self) -> bool:
-        return False
-
-    def has_reserved(self) -> bool:
-        return False
-
-    def prepare_append(
-        self,
-        payload: dict[str, object],
-        *,
-        operation_id: str,
-        chunk_period_ms: int,
-        allow_emit: bool,
-    ) -> PcmAppendReservation | None:
-        del payload, operation_id, chunk_period_ms, allow_emit
-        raise RuntimeError("Model-native audio append is not enabled for this session")
-
-    def prepare_commit(
-        self,
-        *,
-        operation_id: str,
-        chunk_period_ms: int,
-    ) -> PcmAppendReservation:
-        del operation_id, chunk_period_ms
-        raise RuntimeError("Model-native audio append is not enabled for this session")
-
-    def flush(self, *, chunk_period_ms: int) -> dict[str, object] | None:
-        del chunk_period_ms
-        return None
-
-
-@dataclass(slots=True)
-class TurnBasedServingSessionState:
-    """Runner-local state for sessions served through chat fallback."""
-
-    audio_buffer: PcmAppendBuffer = field(default_factory=_TurnBasedPcmAppendBuffer)
-    input_since_commit: bool = False
-    speech_since_commit: bool = False
-    native_context_locked: bool = False
-    committed_audio_payload: dict[str, object] | None = None
-    committed_audio_operation_id: str | None = None
-    committed_audio_reserved_bytes: int = 0
-    deferred_response_create: bool = False
-    deferred_precreate_response: bool = False
-    data_plane_task: asyncio.Task[None] | None = None
-    data_plane_restart_requested: bool = False
-    continuation_owner_id: str | None = None
-    continuation_units: int = 0
-    pending_silence_task: asyncio.Task[bool] | None = None
-    pending_silence_owner_id: str | None = None
-    silence_continuation_scheduler: Callable[..., Awaitable[bool]] | None = None
-
-    def retain_committed_audio(
-        self,
-        payload: dict[str, object],
-        *,
-        operation_id: str | None,
-        reserved_bytes: int = 0,
-    ) -> None:
-        self.committed_audio_payload = payload
-        self.committed_audio_operation_id = operation_id
-        self.committed_audio_reserved_bytes += max(0, int(reserved_bytes))
-
-    def clear_committed_audio(self) -> int:
-        reserved_bytes = self.committed_audio_reserved_bytes
-        self.committed_audio_payload = None
-        self.committed_audio_operation_id = None
-        self.committed_audio_reserved_bytes = 0
-        self.deferred_response_create = False
-        self.deferred_precreate_response = False
-        return reserved_bytes
-
-    def clear_continuation(self) -> None:
-        self.continuation_owner_id = None
-        self.continuation_units = 0
-        self.pending_silence_task = None
-        self.pending_silence_owner_id = None
-
-
-class RuntimeDataPlane(Protocol):
-    def begin_request(self, request_id: str) -> None: ...
-
-    def is_terminal(self, request_id: str | None) -> bool: ...
-
-    def mark_terminal(self, request_id: str) -> None: ...
-
-    def close_stream(self, request_id: str) -> None: ...
-
-    def close_session(self, session_id: str, *, active_request_id: str | None = None) -> None: ...
-
-    def project(self, result: object, *, context: object | None = None) -> Iterable[dict[str, object]]: ...
-
-
-class ServingRuntimeAdapter(Protocol):
-    adapter_id: str
-    session_states: MutableMapping[str, ServingRuntimeSessionState]
-    data_plane: RuntimeDataPlane
-    clean_response_done_prefix: str
-    interrupted_tts_prefix: str
-    private_runtime_config_keys: frozenset[str]
-    collect_outputs_on_append: bool
-
-    def create_session_state(self) -> ServingRuntimeSessionState: ...
-
-    def session_state(self, session_id: str) -> ServingRuntimeSessionState: ...
-
-    def remove_session_state(self, session_id: str) -> None: ...
-
-    def is_enabled(self, config: object) -> bool: ...
-
-    def capabilities(self, *, max_sessions: int) -> object: ...
-
-    def validate_client_extra_body(self, extra_body: object) -> None: ...
-
-    async def prepare_runtime_config(self, config: object, *, model_config: Any) -> dict[str, object]: ...
-
-    def runtime_config_for_update(
-        self,
-        config: object,
-        current: Mapping[str, object],
-    ) -> dict[str, object]: ...
-
-    def data_plane_context(
-        self,
-        *,
-        epoch: int,
-        turn_id: int,
-        active_response_turn_id: int | None,
-        active_response_id: str | None,
-        auto_responds: bool,
-        response_format: str,
-        speed: float | None,
-        modalities: tuple[str, ...],
-    ) -> object: ...
-
-
-def load_serving_runtime_adapter(
-    path: str,
-    encode_audio,
-) -> ServingRuntimeAdapter:
-    module_name, separator, attribute_name = path.rpartition(".")
-    if not separator:
-        raise ValueError(f"Invalid duplex serving runtime adapter path: {path!r}")
-    adapter_type = getattr(import_module(module_name), attribute_name)
-    return validate_serving_runtime_adapter(adapter_type(encode_audio))
-
-
-def validate_serving_runtime_adapter(adapter: object) -> ServingRuntimeAdapter:
-    required_methods = (
-        "create_session_state",
-        "session_state",
-        "remove_session_state",
-        "is_enabled",
-        "capabilities",
-        "validate_client_extra_body",
-        "prepare_runtime_config",
-        "runtime_config_for_update",
-        "data_plane_context",
-    )
-    missing = [name for name in required_methods if not callable(getattr(adapter, name, None))]
-    if missing:
-        raise TypeError(f"Duplex serving runtime adapter is missing callable method(s): {', '.join(missing)}")
-    if not isinstance(getattr(adapter, "adapter_id", None), str) or not adapter.adapter_id:
-        raise TypeError("Duplex serving runtime adapter must declare adapter_id")
-    if not isinstance(getattr(adapter, "session_states", None), MutableMapping):
-        raise TypeError("Duplex serving runtime adapter must declare mutable session_states")
-    for prefix_name in ("clean_response_done_prefix", "interrupted_tts_prefix"):
-        if not isinstance(getattr(adapter, prefix_name, None), str):
-            raise TypeError(f"Duplex serving runtime adapter must declare {prefix_name}")
-    private_keys = getattr(adapter, "private_runtime_config_keys", None)
-    if not isinstance(private_keys, frozenset) or any(not isinstance(key, str) for key in private_keys):
-        raise TypeError("Duplex serving runtime adapter must declare private_runtime_config_keys as frozenset[str]")
-    data_plane = getattr(adapter, "data_plane", None)
-    if data_plane is None:
-        raise TypeError("Duplex serving runtime adapter must declare data_plane")
-    data_plane_methods = (
-        "begin_request",
-        "is_terminal",
-        "mark_terminal",
-        "close_stream",
-        "close_session",
-        "project",
-    )
-    missing_data_plane_methods = [name for name in data_plane_methods if not callable(getattr(data_plane, name, None))]
-    if missing_data_plane_methods:
-        raise TypeError(
-            "Duplex serving runtime adapter data_plane is missing callable method(s): "
-            + ", ".join(missing_data_plane_methods)
-        )
-    return adapter  # type: ignore[return-value]
-
-
-def payload_turn_id(payload: object) -> int | None:
-    if not isinstance(payload, Mapping):
-        return None
-    return coerce_int(payload.get("duplex_turn_id", payload.get("model_turn_id")))
-
-
-def coerce_int(value: object) -> int | None:
-    try:
-        return int(value) if value is not None else None
-    except (TypeError, ValueError):
-        return None
diff --git a/vllm_omni/entrypoints/duplex/runtime_bridge.py b/vllm_omni/entrypoints/duplex/runtime_bridge.py
deleted file mode 100644
index 96a82c06191..00000000000
--- a/vllm_omni/entrypoints/duplex/runtime_bridge.py
+++ /dev/null
@@ -1,1454 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-import base64
-import inspect
-import time
-from collections.abc import Mapping
-from dataclasses import asdict, is_dataclass
-from enum import Enum
-
-import numpy as np
-from vllm.logger import init_logger
-
-from vllm_omni.engine.duplex.control_client import DuplexControlRequestError
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.runtime import duplex_data_plane_request_info
-from vllm_omni.entrypoints.duplex.protocol import (
-    DuplexSession,
-    DuplexSessionState,
-)
-from vllm_omni.entrypoints.duplex.runtime_adapter import (
-    coerce_int,
-    payload_turn_id,
-)
-
-logger = init_logger(__name__)
-
-
-class NativeRuntimeBridgeMixin:
-    """Bridge serving sessions to native runtime control and data-plane APIs."""
-
-    _NATIVE_RUNTIME_FENCE_CONTRACT = {
-        "open_duplex_session_async": ("fence",),
-        "append_duplex_input_async": ("fence",),
-        "signal_duplex_turn_async": ("fence", "next_fence"),
-        "close_duplex_session_async": ("fence",),
-    }
-
-    async def _open_runtime_session(self, session: DuplexSession, send_json) -> dict[str, object] | bool:
-        # Turn-based sessions use the chat-fallback path and do not own a
-        # model-native duplex runtime.  Do not send control messages merely
-        # because the shared engine client exposes the duplex RPC methods.
-        if not self._uses_serving_runtime_adapter(session.config):
-            return True
-        contract_error = self._native_runtime_contract_error(session)
-        if contract_error is not None:
-            await send_json(
-                {
-                    "type": "error",
-                    "code": "runtime_contract_invalid",
-                    "error": contract_error,
-                }
-            )
-            return False
-        open_session = getattr(self._chat_service.engine_client, "open_duplex_session_async", None)
-        if not callable(open_session):
-            return True
-        try:
-            open_kwargs = {
-                "session_mode": "duplex",
-                "capabilities": session.capabilities.as_dict(),
-                "session_config": session.config.as_dict(),
-                "timeout": self._runtime_control_timeout_s(session),
-            }
-            if self._callable_accepts_keyword(open_session, "runtime_config"):
-                open_kwargs["runtime_config"] = dict(session.runtime_config)
-            if self._callable_accepts_keyword(open_session, "fence"):
-                open_kwargs["fence"] = DuplexFence(
-                    session.session_id,
-                    epoch=session.epoch,
-                    turn_id=session.turn_id,
-                    incarnation=session.incarnation,
-                )
-            result = await open_session(session.session_id, **open_kwargs)
-        except Exception as exc:
-            if isinstance(exc, DuplexControlRequestError) and exc.code == "resource_exhausted":
-                logger.info("Duplex runtime session admission rejected: %s", exc)
-            else:
-                logger.exception("Failed to open duplex runtime session: %s", exc)
-            await self._send_runtime_error(send_json, "runtime_open_failed", exc, session=session)
-            return False
-        if (
-            isinstance(result, dict)
-            and session.capabilities.implementation_level == "model_native_duplex"
-            and self._runtime_control_failed(result)
-        ):
-            await send_json(
-                {
-                    "type": "error",
-                    "error": "Native duplex runtime is not available for this session",
-                    "code": ("runtime_open_unsupported" if result.get("unsupported_count") else "runtime_open_failed"),
-                    "runtime_control": self._redact_runtime_control_result(result),
-                }
-            )
-            return False
-        return result if isinstance(result, dict) else True
-
-    async def _append_runtime_input(
-        self,
-        session: DuplexSession,
-        payload: object,
-        *,
-        operation_id: str | None = None,
-        final: bool,
-        send_json,
-        mode: str = "append_tokens",
-        expected_epoch: int | None = None,
-    ) -> tuple[bool, bool]:
-        if not session.capabilities.supports_input_append:
-            return True, False
-        append_input = getattr(self._chat_service.engine_client, "append_duplex_input_async", None)
-        if not callable(append_input):
-            return True, False
-        if expected_epoch is not None and session.epoch != expected_epoch:
-            return True, False
-        try:
-            append_kwargs = {
-                "mode": mode,
-                "payload": payload,
-                "final": final,
-                "timeout": self._runtime_control_timeout_s(session),
-            }
-            if operation_id is not None and self._callable_accepts_keyword(append_input, "operation_id"):
-                append_kwargs["operation_id"] = operation_id
-            if expected_epoch is not None and self._callable_accepts_keyword(append_input, "expected_epoch"):
-                append_kwargs["expected_epoch"] = expected_epoch
-            if self._callable_accepts_keyword(append_input, "fence"):
-                payload_turn = payload_turn_id(payload)
-                append_kwargs["fence"] = DuplexFence(
-                    session.session_id,
-                    epoch=session.epoch,
-                    turn_id=(
-                        payload_turn
-                        if payload_turn is not None
-                        else (
-                            session.active_response_turn_id
-                            if session.active_response_turn_id is not None
-                            else session.turn_id
-                        )
-                    ),
-                    incarnation=session.incarnation,
-                )
-            if self._callable_accepts_keyword(append_input, "collect_outputs"):
-                append_kwargs["collect_outputs"] = bool(
-                    getattr(self._serving_runtime_adapter, "collect_outputs_on_append", False)
-                )
-            result = await append_input(session.session_id, **append_kwargs)
-        except Exception as exc:
-            logger.exception("Failed to append duplex runtime input: %s", exc)
-            await self._send_runtime_error(send_json, "runtime_append_failed", exc, session=session)
-            return False, False
-        if isinstance(result, dict) and self._runtime_control_failed(result):
-            await self._send_runtime_control_error(
-                send_json,
-                "runtime_append_failed",
-                "Duplex runtime append failed",
-                result,
-                session=session,
-            )
-            return False, False
-        if expected_epoch is not None and session.epoch != expected_epoch:
-            return True, False
-        await self._send_runtime_control_if_needed(send_json, result, session=session)
-        request_id, _ = self._data_plane_request_info(result) if isinstance(result, dict) else (None, None)
-        if request_id is not None:
-            self._serving_runtime_adapter.data_plane.begin_request(request_id)
-        close_reason, emitted_response = await self._send_native_duplex_events(
-            send_json,
-            result,
-            session=session,
-            expected_epoch=expected_epoch,
-        )
-        # A resumable data-plane append remains active even when its persistent
-        # drain task already exists. Treating only a newly-created drain as
-        # activity clears active_request_id after later appends and prevents a
-        # terminal TTS segment from scheduling the next model decision.
-        emitted_response = emitted_response or request_id is not None
-        if close_reason is None and await self._start_native_data_plane_stream_task(
-            send_json,
-            result,
-            session=session,
-            expected_epoch=expected_epoch,
-        ):
-            emitted_response = True
-        if close_reason is not None:
-            if not await self._close_runtime_session(session, reason=close_reason, send_json=send_json):
-                return False, emitted_response
-            session.close()
-            await send_json(
-                {
-                    "type": "session.closed",
-                    "session_id": session.session_id,
-                    "reason": close_reason,
-                }
-            )
-            return False, emitted_response
-        return True, emitted_response
-
-    @staticmethod
-    def _callable_accepts_keyword(fn, name: str) -> bool:
-        try:
-            params = inspect.signature(fn).parameters.values()
-        except (TypeError, ValueError):
-            return True
-        return any(param.kind == inspect.Parameter.VAR_KEYWORD or param.name == name for param in params)
-
-    def _native_runtime_contract_error(self, session: DuplexSession) -> str | None:
-        if session.capabilities.implementation_level != "model_native_duplex":
-            return None
-        engine_client = self._chat_service.engine_client
-        invalid: list[str] = []
-        for method_name, required_keywords in self._NATIVE_RUNTIME_FENCE_CONTRACT.items():
-            method = getattr(engine_client, method_name, None)
-            if not callable(method):
-                invalid.append(f"{method_name} is missing")
-                continue
-            try:
-                parameters = tuple(inspect.signature(method).parameters.values())
-            except (TypeError, ValueError):
-                invalid.append(f"{method_name} signature is not inspectable")
-                continue
-            accepts_kwargs = any(parameter.kind == inspect.Parameter.VAR_KEYWORD for parameter in parameters)
-            declared = {parameter.name for parameter in parameters}
-            missing = [name for name in required_keywords if not accepts_kwargs and name not in declared]
-            if missing:
-                invalid.append(f"{method_name} is missing keyword(s): {', '.join(missing)}")
-        if not invalid:
-            return None
-        return "Native duplex runtime requires the fenced control contract: " + "; ".join(invalid)
-
-    async def _start_native_data_plane_stream_task(
-        self,
-        send_json,
-        result: object,
-        *,
-        session: DuplexSession,
-        expected_epoch: int | None = None,
-    ) -> bool:
-        request_id, _ = self._data_plane_request_info(result)
-        if request_id is None or self._data_plane_outputs_finished(result):
-            return False
-        session.bind_request(request_id)
-
-        native = self._runtime_session_state(session)
-        old_task = native.data_plane_task
-        if old_task is not None and not old_task.done():
-            if self._session_auto_responds(session):
-                # One persistent drain per session, like the official worker's
-                # single synchronous loop: the resumable data-plane request id
-                # is stable, and cancel/restart on every append orphans any
-                # decision that lands in the swap window.
-                native.data_plane_restart_requested = True
-                return False
-            old_task.cancel()
-            try:
-                await asyncio.wait_for(asyncio.gather(old_task, return_exceptions=True), timeout=0.25)
-            except asyncio.TimeoutError:
-                pass
-
-        async def _run() -> None:
-            close_reason: str | None = None
-            try:
-                close_reason = await self._drain_native_data_plane_stream(
-                    send_json,
-                    result,
-                    session=session,
-                    expected_epoch=expected_epoch,
-                )
-                if close_reason is not None:
-                    if await self._close_runtime_session(session, reason=close_reason, send_json=send_json):
-                        session.close()
-                        await send_json(
-                            {
-                                "type": "session.closed",
-                                "session_id": session.session_id,
-                                "reason": close_reason,
-                            }
-                        )
-            except asyncio.CancelledError:
-                raise
-            except Exception as exc:
-                logger.exception("Failed to drain duplex data-plane stream: %s", exc)
-                await self._send_runtime_error(send_json, "runtime_data_plane_stream_failed", exc, session=session)
-                if session.state != DuplexSessionState.CLOSED:
-                    close_reason = "runtime_data_plane_stream_failed"
-                    if await self._close_runtime_session(session, reason=close_reason, send_json=send_json):
-                        session.close()
-                        await send_json(
-                            {
-                                "type": "session.closed",
-                                "session_id": session.session_id,
-                                "reason": close_reason,
-                            }
-                        )
-            finally:
-                if native.data_plane_task is task:
-                    native.data_plane_task = None
-                restart_requested = (
-                    native.data_plane_restart_requested
-                    and close_reason is None
-                    and session.state != DuplexSessionState.CLOSED
-                    and session.active_request_id == request_id
-                    and (expected_epoch is None or session.epoch == expected_epoch)
-                )
-                native.data_plane_restart_requested = False
-                if close_reason is None and not self._session_auto_responds(session):
-                    # Auto-respond sessions keep one resumable stage-1 stream
-                    # whose audio accumulates across speak units; the offset
-                    # must survive drain-task turnover or every unit re-sends
-                    # the reply audio from the start.
-                    self._serving_runtime_adapter.data_plane.close_stream(request_id)
-            if restart_requested:
-                await self._start_native_data_plane_stream_task(
-                    send_json,
-                    result,
-                    session=session,
-                    expected_epoch=expected_epoch,
-                )
-            elif close_reason is None:
-                await self._maybe_continue_native_response(send_json, session=session, expected_epoch=expected_epoch)
-
-        task = asyncio.create_task(_run())
-        native.data_plane_task = task
-        return True
-
-    # One MiniCPM model unit (1 s at 16 kHz) is the compatibility default.
-    # Other native-duplex adapters may use a different frame-locked unit.
-    _NATIVE_SILENCE_UNIT_PAYLOAD_AUDIO = base64.b64encode(bytes(16000 * 4)).decode("ascii")
-    _NATIVE_RESPONSE_MAX_CONTINUATION_UNITS = 8
-    # Each unit is one second of silence. Auto-response needs substantially
-    # more room than the eight decision beats above, but must still terminate
-    # well before the 300-second benchmark playback horizon. The final unit
-    # asks the model to LISTEN; a protocol fallback closes the response if that
-    # logit hint is ignored.
-    _NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS = 64
-
-    def _native_silence_unit_payload(self) -> dict[str, object]:
-        samples = int(getattr(self._serving_runtime_adapter, "silence_continuation_samples", 16000))
-        audio = (
-            self._NATIVE_SILENCE_UNIT_PAYLOAD_AUDIO
-            if samples == 16000
-            else base64.b64encode(bytes(samples * 4)).decode("ascii")
-        )
-        return {
-            "type": "audio",
-            "audio": audio,
-            "format": "pcm_f32le",
-            "sample_rate_hz": 16000,
-        }
-
-    def _native_response_continuations_remaining(self, session: DuplexSession, response_id: str) -> bool:
-        native = self._runtime_session_state(session)
-        owner_id = f"response:{response_id}"
-        count = native.continuation_units if native.continuation_owner_id == owner_id else 0
-        limit = (
-            self._NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS
-            if self._session_auto_responds(session)
-            else self._NATIVE_RESPONSE_MAX_CONTINUATION_UNITS
-        )
-        return count < limit
-
-    async def _finish_bounded_native_auto_response(
-        self,
-        send_json,
-        *,
-        session: DuplexSession,
-        expected_epoch: int | None,
-        model_turn_id: int | None = None,
-    ) -> None:
-        """Close an auto-response whose final silence unit did not end it."""
-        native = self._runtime_session_state(session)
-        response_id = session.active_response_id
-        response_epoch = session.epoch
-        response_turn_id = model_turn_id if model_turn_id is not None else session.active_response_turn_id
-        if expected_epoch is not None and response_epoch != expected_epoch:
-            return
-        native.clear_continuation()
-        payload = {
-            "type": "response.listen",
-            "session_id": session.session_id,
-            "epoch": response_epoch,
-            "reason": "continuation_limit",
-            "model_listen": False,
-        }
-        if response_id is not None:
-            # Clients demultiplex a listen against a precreated response by
-            # its id; every listen that terminates a response must carry it.
-            payload["response_id"] = response_id
-        await send_json(payload)
-        if response_id is None:
-            if session.epoch == response_epoch and response_turn_id is not None:
-                session.complete_model_turn(response_turn_id)
-            return
-        if session.epoch != response_epoch or session.active_response_id != response_id:
-            return
-        if response_turn_id is not None:
-            session.complete_model_turn(response_turn_id)
-        session.end_response(commit_text=False, preserve_request=True)
-        await send_json(
-            {
-                "type": "response.done",
-                "session_id": session.session_id,
-                "response_id": response_id,
-                "epoch": response_epoch,
-                "committed": False,
-                "playback": session.playback.as_dict(),
-            }
-        )
-
-    def _native_silence_continuation_is_stale(
-        self,
-        session: DuplexSession,
-        *,
-        request_id: str,
-        response_id: str | None,
-        response_owned: bool,
-        expected_epoch: int | None,
-        expected_incarnation: int,
-        expected_model_turn_id: int | None,
-    ) -> bool:
-        stale_common_owner = (
-            session.state == DuplexSessionState.CLOSED
-            or session.incarnation != expected_incarnation
-            or session.active_request_id != request_id
-            or (expected_epoch is not None and session.epoch != expected_epoch)
-        )
-        stale_response_owner = response_owned and session.active_response_id != response_id
-        stale_model_turn_owner = not response_owned and (
-            session.active_response_id is not None or session.turn_id != expected_model_turn_id
-        )
-        return stale_common_owner or stale_response_owner or stale_model_turn_owner
-
-    async def _maybe_continue_native_response(
-        self,
-        send_json,
-        *,
-        session: DuplexSession,
-        expected_epoch: int | None,
-        expected_model_turn_id: int | None = None,
-    ) -> None:
-        """Give an active model turn another silence unit.
-
-        A model turn can need another unit before it has emitted visible
-        text/audio and therefore before a Realtime response exists. Bind that
-        continuation to the model-turn identity; once a response exists, its
-        response/turn ownership remains the continuation fence.
-        """
-        response_id = session.active_response_id
-        native = self._runtime_session_state(session)
-        if session.state == DuplexSessionState.CLOSED:
-            native.clear_continuation()
-            return
-        request_id = session.active_request_id
-        if request_id is None:
-            native.clear_continuation()
-            return
-        if expected_epoch is not None and session.epoch != expected_epoch:
-            return
-        auto_response = self._session_auto_responds(session)
-        response_owned = response_id is not None
-        if response_owned:
-            owner_id = f"response:{response_id}"
-            payload_turn_id = (
-                session.active_response_turn_id if session.active_response_turn_id is not None else session.turn_id
-            )
-        else:
-            if not auto_response or expected_model_turn_id is None or session.turn_id != expected_model_turn_id:
-                native.clear_continuation()
-                return
-            owner_id = f"model-turn:{expected_model_turn_id}"
-            payload_turn_id = expected_model_turn_id
-        count = native.continuation_units if native.continuation_owner_id == owner_id else 0
-        continuation_limit = (
-            self._NATIVE_AUTO_RESPONSE_MAX_CONTINUATION_UNITS
-            if auto_response
-            else self._NATIVE_RESPONSE_MAX_CONTINUATION_UNITS
-        )
-        if count >= continuation_limit:
-            if auto_response:
-                await self._finish_bounded_native_auto_response(
-                    send_json,
-                    session=session,
-                    expected_epoch=expected_epoch,
-                    model_turn_id=payload_turn_id,
-                )
-            return
-        payload = self._native_silence_unit_payload()
-        if auto_response and count + 1 == continuation_limit:
-            payload["force_listen"] = True
-        payload["duplex_turn_id"] = payload_turn_id
-
-        scheduler = native.silence_continuation_scheduler
-        if scheduler is None:
-            return
-        try:
-            scheduled = await scheduler(
-                payload,
-                request_id=request_id,
-                owner_id=owner_id,
-                response_id=response_id,
-                response_owned=response_owned,
-                expected_epoch=expected_epoch,
-                expected_incarnation=session.incarnation,
-                expected_model_turn_id=expected_model_turn_id,
-                send_json=send_json,
-            )
-        except Exception as exc:
-            logger.exception("Failed to schedule duplex native response continuation: %s", exc)
-            scheduled = False
-        if scheduled:
-            native.continuation_owner_id = owner_id
-            native.continuation_units = count + 1
-
-    async def _cancel_native_data_plane_stream(self, session: DuplexSession) -> bool:
-        native = self._runtime_session_state(session)
-        task = native.data_plane_task
-        native.data_plane_task = None
-        native.data_plane_restart_requested = False
-        if task is None or task.done():
-            return False
-        task.cancel()
-        try:
-            await asyncio.wait_for(asyncio.gather(task, return_exceptions=True), timeout=0.25)
-        except asyncio.TimeoutError:
-            # Keep barge-in/cancel responsive. The task still carries the old
-            # expected_epoch and late model output is filtered by the writer.
-            pass
-        return True
-
-    async def _signal_runtime_session(
-        self,
-        session: DuplexSession,
-        event: str,
-        send_json=None,
-        *,
-        fence: DuplexFence | None = None,
-        next_fence: DuplexFence | None = None,
-        session_config: dict[str, object] | None = None,
-        runtime_config: dict[str, object] | None = None,
-    ) -> bool:
-        if not self._uses_serving_runtime_adapter(session.config):
-            return True
-        signal_turn = getattr(self._chat_service.engine_client, "signal_duplex_turn_async", None)
-        if not callable(signal_turn):
-            return True
-        try:
-            signal_kwargs = {
-                "event": event,
-                "timeout": self._runtime_control_timeout_s(session),
-            }
-            if self._callable_accepts_keyword(signal_turn, "fence"):
-                signal_kwargs["fence"] = fence or DuplexFence(
-                    session.session_id,
-                    epoch=session.epoch,
-                    turn_id=session.turn_id,
-                    incarnation=session.incarnation,
-                )
-            if next_fence is not None and self._callable_accepts_keyword(signal_turn, "next_fence"):
-                signal_kwargs["next_fence"] = next_fence
-            if session_config is not None and self._callable_accepts_keyword(signal_turn, "session_config"):
-                signal_kwargs["session_config"] = session_config
-            if runtime_config is not None and self._callable_accepts_keyword(signal_turn, "runtime_config"):
-                signal_kwargs["runtime_config"] = runtime_config
-            result = await signal_turn(session.session_id, **signal_kwargs)
-        except Exception as exc:
-            logger.exception("Failed to signal duplex runtime session: %s", exc)
-            if send_json is not None:
-                await self._send_runtime_error(send_json, "runtime_signal_failed", exc, session=session)
-            return False
-        if isinstance(result, dict) and self._runtime_signal_failed(result):
-            logger.warning(
-                "Duplex runtime signal failed: session=%s event=%s result=%s",
-                session.session_id,
-                event,
-                self._redact_runtime_control_result(result),
-            )
-            if send_json is not None:
-                await self._send_runtime_control_error(
-                    send_json,
-                    "runtime_signal_failed",
-                    "Duplex runtime signal failed",
-                    result,
-                    session=session,
-                )
-            return False
-        await self._send_runtime_control_if_needed(send_json, result, session=session)
-        return True
-
-    async def _close_runtime_session(self, session: DuplexSession, *, reason: str, send_json=None) -> bool:
-        if not self._uses_serving_runtime_adapter(session.config):
-            return True
-        close_session = getattr(self._chat_service.engine_client, "close_duplex_session_async", None)
-        if not callable(close_session):
-            return True
-        try:
-            close_kwargs = {
-                "reason": reason,
-                "timeout": self._runtime_control_timeout_s(session),
-            }
-            if self._callable_accepts_keyword(close_session, "fence"):
-                close_kwargs["fence"] = DuplexFence(
-                    session.session_id,
-                    epoch=session.epoch,
-                    turn_id=session.turn_id,
-                    incarnation=session.incarnation,
-                )
-            result = await close_session(session.session_id, **close_kwargs)
-        except Exception as exc:
-            logger.exception("Failed to close duplex runtime session: %s", exc)
-            if send_json is not None:
-                await self._send_runtime_error(send_json, "runtime_close_failed", exc, session=session)
-            return False
-        if isinstance(result, dict) and self._runtime_control_failed(result):
-            if send_json is not None:
-                await self._send_runtime_control_error(
-                    send_json,
-                    "runtime_close_failed",
-                    "Duplex runtime close failed",
-                    result,
-                    session=session,
-                )
-            return False
-        await self._send_runtime_control_if_needed(send_json, result, session=session)
-        return True
-
-    @staticmethod
-    def _runtime_control_timeout_s(session: DuplexSession) -> float:
-        raw = session.config.extra_body.get("duplex_control_timeout_s") or session.config.extra_body.get(
-            "runtime_control_timeout_s"
-        )
-        if isinstance(raw, int | float) and raw > 0:
-            return float(raw)
-        if session.capabilities.implementation_level == "model_native_duplex":
-            return 60.0
-        return 10.0
-
-    async def _send_runtime_control_if_needed(
-        self,
-        send_json,
-        result: object,
-        *,
-        session: DuplexSession,
-    ) -> None:
-        if send_json is None:
-            return
-        if not isinstance(result, dict):
-            return
-        if not result.get("unsupported_count") and not result.get("error_count"):
-            return
-        await send_json(
-            {
-                "type": "runtime.control",
-                "session_id": session.session_id,
-                "epoch": session.epoch,
-                "result": self._redact_runtime_control_result(result),
-            }
-        )
-
-    @staticmethod
-    def _runtime_control_failed(result: dict[str, object]) -> bool:
-        if result.get("ok") is False:
-            return True
-        for key in ("unsupported_count", "error_count"):
-            value = result.get(key)
-            if isinstance(value, int | float) and value > 0:
-                return True
-        return False
-
-    @classmethod
-    def _runtime_signal_failed(cls, result: dict[str, object]) -> bool:
-        error_count = result.get("error_count")
-        if isinstance(error_count, int | float) and error_count > 0:
-            return True
-        if result.get("ok") is not False:
-            return False
-        return not cls._runtime_signal_has_data_plane_ack(result)
-
-    @classmethod
-    def _runtime_signal_has_data_plane_ack(cls, value: object) -> bool:
-        if isinstance(value, dict):
-            if value.get("data_plane_signal") is True and value.get("supported") is True:
-                return True
-            return any(cls._runtime_signal_has_data_plane_ack(child) for child in value.values())
-        if isinstance(value, list | tuple):
-            return any(cls._runtime_signal_has_data_plane_ack(item) for item in value)
-        return False
-
-    @classmethod
-    def _redact_runtime_control_result(cls, value: object) -> object:
-        if isinstance(value, dict):
-            redacted = {
-                key: cls._redact_runtime_control_result(child)
-                for key, child in value.items()
-                if key
-                not in {
-                    "stage_handoff",
-                    "tts_handoff",
-                    "omni_payload",
-                    "tts_hidden_states",
-                    "tts_token_ids",
-                    "traceback",
-                }
-            }
-            native_result = redacted.get("native_result")
-            if isinstance(native_result, dict):
-                if native_result.get("requires_stage_handoff") is True:
-                    native_result.pop("requires_stage_handoff", None)
-                if native_result.get("requires_tts_stage") is True:
-                    native_result.pop("requires_tts_stage", None)
-            return redacted
-        if isinstance(value, list | tuple):
-            return [cls._redact_runtime_control_result(item) for item in value]
-        if is_dataclass(value) and not isinstance(value, type):
-            # Control results carry typed values straight from the engine:
-            # `fence` and `accepted_fence` are `DuplexFence` instances added by
-            # `DuplexControlClient.execute`. This redacted value is emitted on
-            # the wire (for example `session.created.runtime_control` in
-            # `session_runner`), where `WebSocket.send_json` would raise
-            # `TypeError: Object of type DuplexFence is not JSON serializable`
-            # and kill the session during the handshake.
-            return {key: cls._redact_runtime_control_result(child) for key, child in asdict(value).items()}
-        if isinstance(value, Enum):
-            return value.value
-        return value
-
-    async def _send_native_duplex_events(
-        self,
-        send_json,
-        result: object,
-        *,
-        session: DuplexSession,
-        expected_epoch: int | None = None,
-    ) -> tuple[str | None, bool]:
-        if send_json is None:
-            return None, False
-        if expected_epoch is not None and session.epoch != expected_epoch:
-            return None, False
-        close_reason: str | None = None
-        emitted_response = False
-        request_id, _ = self._data_plane_request_info(result)
-        if self._serving_runtime_adapter.data_plane.is_terminal(request_id):
-            return None, False
-        if request_id is not None and session.active_request_id is None:
-            session.bind_request(request_id)
-        context = self._runtime_data_plane_context(session)
-        for native_result in self._serving_runtime_adapter.data_plane.project(result, context=context):
-            close_reason_for_result, did_emit = await self._send_one_native_duplex_event(
-                send_json,
-                native_result,
-                session=session,
-                expected_epoch=expected_epoch,
-            )
-            emitted_response = emitted_response or did_emit
-            close_reason = close_reason or close_reason_for_result
-            if expected_epoch is not None and session.epoch != expected_epoch:
-                return None, emitted_response
-        return close_reason, emitted_response
-
-    async def _drain_native_data_plane_stream(
-        self,
-        send_json,
-        result: object,
-        *,
-        session: DuplexSession,
-        expected_epoch: int | None = None,
-    ) -> str | None:
-        request_id, response_stage_id = self._data_plane_request_info(result)
-        if request_id is None:
-            return None
-        if self._data_plane_outputs_finished(result):
-            return None
-        collect_outputs = getattr(
-            self._chat_service.engine_client,
-            "collect_duplex_data_plane_outputs_async",
-            None,
-        )
-        if not callable(collect_outputs):
-            return None
-
-        close_reason: str | None = None
-        empty_polls = 0
-        while close_reason is None:
-            if self._serving_runtime_adapter.data_plane.is_terminal(request_id):
-                return None
-            if self._session_auto_responds(session):
-                active_request_id = session.active_request_id
-                if active_request_id is not None and active_request_id != request_id:
-                    return None
-            if expected_epoch is not None and session.epoch != expected_epoch:
-                return None
-            if session.state == DuplexSessionState.CLOSED:
-                return None
-            outputs = await collect_outputs(
-                request_id,
-                response_stage_id=response_stage_id,
-                timeout=self._runtime_control_timeout_s(session),
-            )
-            if expected_epoch is not None and session.epoch != expected_epoch:
-                return None
-            if not outputs:
-                # An empty poll means no output arrived within one control
-                # window, not that the stream is over. Exiting here orphans a
-                # decision that lands moments later: it would sit queued until
-                # the NEXT append starts a fresh drain task, adding one full
-                # chunk of latency to every model decision.
-                empty_polls += 1
-                if empty_polls >= 3:
-                    return None
-                continue
-            empty_polls = 0
-            drain_result = {
-                "data_plane_outputs": outputs,
-            }
-            close_reason, emitted_response = await self._send_native_duplex_events(
-                send_json,
-                drain_result,
-                session=session,
-                expected_epoch=expected_epoch,
-            )
-            if (
-                self._data_plane_outputs_finished(drain_result)
-                and emitted_response
-                and not self._session_auto_responds(session)
-            ):
-                # Auto-respond sessions are resumable: every segment ends
-                # with finished=True but the stream continues with the next
-                # audio chunk. Exiting here would make each decision wait for
-                # the next append to start a fresh drain task (one full chunk
-                # of added latency); keep draining until epoch change,
-                # session close, or cancellation by a newer drain task.
-                return close_reason
-            # A batch without a client-visible event (e.g. the generic
-            # stage-0 final-output message that precedes the listen/speak
-            # decision in the same segment) must not terminate the drain;
-            # the real decision is still in flight.
-        return close_reason
-
-    @staticmethod
-    def _data_plane_outputs_finished(result: object) -> bool:
-        if not isinstance(result, dict):
-            return False
-        outputs = result.get("data_plane_outputs")
-        if not isinstance(outputs, list) or not outputs:
-            return False
-        return bool(getattr(outputs[-1], "finished", False))
-
-    @staticmethod
-    def _data_plane_request_info(result: object) -> tuple[str | None, int | None]:
-        if not isinstance(result, dict):
-            return None, None
-        return duplex_data_plane_request_info(result)
-
-    def _runtime_data_plane_context(self, session: DuplexSession) -> object:
-        response_config = session.response_config
-        return self._serving_runtime_adapter.data_plane_context(
-            epoch=session.epoch,
-            turn_id=session.turn_id,
-            active_response_turn_id=session.active_response_turn_id,
-            active_response_id=session.active_response_id,
-            auto_responds=self._session_auto_responds(session),
-            response_format=response_config.response_format,
-            speed=response_config.speed,
-            modalities=tuple(response_config.modalities),
-        )
-
-    async def _send_one_native_duplex_event(
-        self,
-        send_json,
-        native_result: dict[str, object],
-        *,
-        session: DuplexSession,
-        expected_epoch: int | None = None,
-    ) -> tuple[str | None, bool]:
-        close_reason: str | None = None
-        emitted_response = False
-        if expected_epoch is not None and session.epoch != expected_epoch:
-            return close_reason, emitted_response
-        data_plane_request_id = native_result.get("data_plane_request_id")
-        if isinstance(data_plane_request_id, str) and self._serving_runtime_adapter.data_plane.is_terminal(
-            data_plane_request_id
-        ):
-            return close_reason, emitted_response
-        active_request_matches = session.active_request_id == data_plane_request_id or (
-            self._session_auto_responds(session) and session.active_request_id is None
-        )
-        if isinstance(data_plane_request_id, str) and not active_request_matches:
-            return close_reason, emitted_response
-        if isinstance(native_result.get("error_code"), str):
-            response_id = session.active_response_id
-            await send_json(
-                {
-                    "type": "error",
-                    "code": native_result.get("error_code"),
-                    "session_id": session.session_id,
-                    "epoch": session.epoch,
-                    "error": str(native_result.get("error") or "Duplex native data-plane error"),
-                }
-            )
-            if response_id is not None:
-                session.end_response(commit_text=False)
-                await send_json(
-                    {
-                        "type": "response.done",
-                        "session_id": session.session_id,
-                        "response_id": response_id,
-                        "epoch": session.epoch,
-                        "committed": False,
-                        "status": "failed",
-                        "status_details": {
-                            "type": "failed",
-                            "reason": native_result.get("error_code"),
-                        },
-                        "playback": session.playback.as_dict(),
-                    }
-                )
-            return close_reason, True
-        if native_result.get("function_call") is True:
-            await send_json(
-                {
-                    "type": "function_call.done",
-                    "session_id": session.session_id,
-                    "epoch": session.epoch,
-                    "call_id": native_result.get("call_id"),
-                    "name": native_result.get("name"),
-                    "arguments": native_result.get("arguments", ""),
-                }
-            )
-            return close_reason, True
-        if native_result.get("requires_stage_handoff") is True or native_result.get("requires_tts_stage") is True:
-            # Stage0 announces a talker handoff before Stage1 has produced
-            # client-visible audio. A single client input stream may contain
-            # several model turns, including terminal-only turns. Reserve the
-            # protocol response only when Stage1 emits text/audio so empty
-            # model turns cannot create empty responses or steal later audio.
-            return close_reason, False
-        is_listen = native_result.get("is_listen")
-        model_turn_id = coerce_int(native_result.get("model_turn_id"))
-        if native_result.get("is_buffering") is True or native_result.get("prefill_success") is False:
-            if native_result.get("data_plane_request_id") == session.active_request_id:
-                session.clear_request()
-            # No response_id here: a buffering listen is informational, not a
-            # response terminal — clients must not close a handle over it.
-            payload = {
-                "type": "response.listen",
-                "session_id": session.session_id,
-                "epoch": session.epoch,
-                "reason": native_result.get("reason") or "buffering",
-                "model_listen": False,
-                "buffering": True,
-            }
-            self._attach_native_runtime_metadata(payload, native_result)
-            await send_json(payload)
-            return close_reason, emitted_response
-        if is_listen is True:
-            await self._end_active_response_before_future_model_turn(
-                send_json,
-                session=session,
-                model_turn_id=model_turn_id,
-            )
-            if (
-                session.active_response_id is not None
-                and model_turn_id is not None
-                and not session.active_response_accepts_model_turn(model_turn_id)
-            ):
-                return close_reason, emitted_response
-            auto_response = self._session_auto_responds(session)
-            active_response_id = session.active_response_id
-            auto_continuations_remaining = active_response_id is None or self._native_response_continuations_remaining(
-                session, active_response_id
-            )
-            non_terminal_auto_listen = (
-                auto_response
-                and active_response_id is not None
-                and session.active_request_id is not None
-                and native_result.get("end_of_turn") is not True
-                and auto_continuations_remaining
-            )
-            if non_terminal_auto_listen:
-                await self._maybe_continue_native_response(
-                    send_json,
-                    session=session,
-                    expected_epoch=expected_epoch,
-                )
-                return close_reason, emitted_response
-            if not auto_response and data_plane_request_id == session.active_request_id:
-                session.clear_request()
-            model_listen = native_result.get("model_listen")
-            if not isinstance(model_listen, bool):
-                model_listen = native_result.get("reason") in {None, "", "model_listen"}
-            response_id = session.active_response_id
-            if isinstance(data_plane_request_id, str) and not auto_response:
-                self._serving_runtime_adapter.data_plane.mark_terminal(data_plane_request_id)
-            emitted_response = True
-            payload = {
-                "type": "response.listen",
-                "session_id": session.session_id,
-                "epoch": session.epoch,
-                "reason": native_result.get("reason") or "model_listen",
-                "model_listen": model_listen,
-            }
-            if response_id is not None:
-                # The listen is this response's terminal decision (a
-                # response.done follows below with the same id); carry the id
-                # so clients can bind the decision to the precreated response.
-                payload["response_id"] = response_id
-            self._attach_native_runtime_metadata(payload, native_result)
-            await send_json(payload)
-            if native_result.get("abort_data_plane_request") is True and isinstance(data_plane_request_id, str):
-                await self._abort_request_background(
-                    session,
-                    data_plane_request_id,
-                    send_json,
-                    notify=False,
-                )
-            if response_id is not None:
-                if not self._session_auto_responds(session) and self._native_response_continuations_remaining(
-                    session, response_id
-                ):
-                    # The official model often listens for a silence beat or
-                    # two before answering; keep the response open and give it
-                    # the next silence unit as a decision point.
-                    await self._maybe_continue_native_response(
-                        send_json,
-                        session=session,
-                        expected_epoch=expected_epoch,
-                    )
-                    return close_reason, emitted_response
-                if auto_response:
-                    self._runtime_session_state(session).clear_continuation()
-                    if not auto_continuations_remaining:
-                        completed_turn_id = model_turn_id
-                        if completed_turn_id is None:
-                            completed_turn_id = session.active_response_turn_id
-                        if completed_turn_id is not None:
-                            session.complete_model_turn(completed_turn_id)
-                session.end_response(commit_text=False, preserve_request=auto_response)
-                await send_json(
-                    {
-                        "type": "response.done",
-                        "session_id": session.session_id,
-                        "response_id": response_id,
-                        "epoch": session.epoch,
-                        "committed": False,
-                        "playback": session.playback.as_dict(),
-                    }
-                )
-            return close_reason, emitted_response
-
-        text = native_result.get("text")
-        audio = native_result.get("audio_data", native_result.get("audio"))
-        end_of_turn = bool(native_result.get("end_of_turn", False))
-        has_text = isinstance(text, str) and bool(text)
-        has_audio = isinstance(audio, str) and bool(audio)
-        if not has_text and not has_audio and not end_of_turn:
-            tts_segment_ended = (
-                native_result.get("stage_role") == "tts" and native_result.get("abort_data_plane_request") is True
-            )
-            if (
-                tts_segment_ended
-                and self._session_auto_responds(session)
-                and (model_turn_id is not None or session.active_response_id is not None)
-            ):
-                await self._maybe_continue_native_response(
-                    send_json,
-                    session=session,
-                    expected_epoch=expected_epoch,
-                    expected_model_turn_id=model_turn_id,
-                )
-            return close_reason, emitted_response
-        if end_of_turn and not has_text and not has_audio and session.active_response_id is None:
-            if isinstance(data_plane_request_id, str):
-                if not self._session_auto_responds(session) and data_plane_request_id == session.active_request_id:
-                    session.clear_request()
-                if not self._session_auto_responds(session):
-                    self._serving_runtime_adapter.data_plane.mark_terminal(data_plane_request_id)
-            if model_turn_id is not None:
-                session.complete_model_turn(model_turn_id)
-            if self._session_auto_responds(session):
-                self._runtime_session_state(session).clear_continuation()
-                emitted_response = True
-                payload = {
-                    "type": "response.listen",
-                    "session_id": session.session_id,
-                    "epoch": session.epoch,
-                    "reason": "model_turn_completed_without_output",
-                    "model_listen": True,
-                }
-                self._attach_native_runtime_metadata(payload, native_result)
-                await send_json(payload)
-            return close_reason, emitted_response
-        if session.active_response_id is None and model_turn_id is not None and model_turn_id < session.turn_id:
-            # A continuation append can already be in flight when the prior
-            # response reaches turn EOS.  Its late audio still carries the
-            # completed model turn, so it must not reserve a second Realtime
-            # response for that turn.
-            return close_reason, emitted_response
-        await self._end_active_response_before_future_model_turn(
-            send_json,
-            session=session,
-            model_turn_id=model_turn_id,
-        )
-        if (
-            session.active_response_id is not None
-            and model_turn_id is not None
-            and not session.active_response_accepts_model_turn(model_turn_id)
-        ):
-            return close_reason, emitted_response
-        emitted_response = True
-        response_created = False
-        response_id = session.active_response_id
-        if response_id is None:
-            response_id = session.begin_response(turn_id=model_turn_id)
-            response_created = True
-        response_request_metrics = session.mark_response_first_outputs(
-            observed_at_s=time.monotonic(),
-            has_text=has_text,
-            has_audio=has_audio,
-        )
-        if response_created:
-            response_created_payload = self._response_created_payload(
-                session,
-                response_id,
-                epoch=session.epoch,
-            )
-            if response_request_metrics:
-                response_created_payload["response_request_metrics"] = response_request_metrics
-            await send_json(response_created_payload)
-        response_stage_metrics = session.accumulate_response_stage_metrics(
-            native_result.get("stage_metrics") if isinstance(native_result.get("stage_metrics"), Mapping) else None
-        )
-        if response_created:
-            speak_payload = {
-                "type": "response.speak",
-                "session_id": session.session_id,
-                "response_id": response_id,
-                "epoch": session.epoch,
-                "text": text if isinstance(text, str) else "",
-                "end_of_turn": end_of_turn,
-                "model_speak": True,
-            }
-            self._attach_native_runtime_metadata(
-                speak_payload,
-                native_result,
-                stage_metrics=response_stage_metrics,
-                response_request_metrics=response_request_metrics,
-            )
-            await send_json(speak_payload)
-        previous_sent_ms = session.playback.sent_ms
-        text_chars_before_append = len("".join(session.assistant_text_buffer))
-        if isinstance(text, str):
-            session.append_assistant_text(text)
-        duration_ms = native_result.get("audio_duration_ms")
-        text_chars = len("".join(session.assistant_text_buffer))
-        mark_duration_ms = None
-        mark_text_chars: int | None = text_chars
-        if native_result.get("audio_text_mark") is False:
-            mark_text_chars = None
-        if isinstance(duration_ms, int | float):
-            mark_duration_ms = int(duration_ms)
-            if native_result.get("audio_duration_is_cumulative") is not True:
-                mark_duration_ms += session.playback.sent_ms
-        audio_text_marks = native_result.get("audio_text_marks")
-        audio_text_marks = self._normalize_native_audio_text_marks(
-            audio_text_marks if isinstance(audio_text_marks, list) else None,
-            audio_offset_ms=(
-                0
-                if native_result.get("audio_text_marks_are_cumulative") is True
-                or native_result.get("audio_duration_is_cumulative") is True
-                else previous_sent_ms
-            ),
-            text_offset_chars=(
-                0 if native_result.get("audio_text_marks_are_cumulative") is True else text_chars_before_append
-            ),
-        )
-        session.mark_audio_sent(
-            mark_duration_ms,
-            text_chars=mark_text_chars if mark_duration_ms is not None else None,
-            audio_text_marks=audio_text_marks,
-        )
-        payload = {
-            "type": "response.output_audio.delta",
-            "session_id": session.session_id,
-            "response_id": response_id,
-            "epoch": session.epoch,
-            "text": text if isinstance(text, str) else "",
-            "audio": audio if isinstance(audio, str) else "",
-            "format": (
-                native_result.get("audio_format")
-                if isinstance(native_result.get("audio_format"), str)
-                else session.response_config.response_format
-            ),
-            "end_of_turn": end_of_turn,
-            "model_speak": True,
-        }
-        if mark_duration_ms is not None:
-            payload["audio_duration_ms"] = mark_duration_ms
-        if audio_text_marks:
-            payload["audio_text_marks"] = audio_text_marks
-        elif mark_duration_ms is not None and mark_text_chars is not None:
-            payload["audio_text_marks"] = [
-                {
-                    "text_chars": max(0, int(mark_text_chars)),
-                    "audio_end_ms": max(0, int(mark_duration_ms)),
-                }
-            ]
-        payload["playback"] = session.playback.as_dict()
-        sample_rate_hz = native_result.get("sample_rate_hz") or native_result.get("audio_sample_rate_hz")
-        if isinstance(sample_rate_hz, int | float) and int(sample_rate_hz) > 0:
-            payload["sample_rate_hz"] = int(sample_rate_hz)
-        self._attach_native_runtime_metadata(
-            payload,
-            native_result,
-            stage_metrics=response_stage_metrics,
-            response_request_metrics=response_request_metrics,
-        )
-        await send_json(payload)
-        if (
-            not end_of_turn
-            and native_result.get("stage_role") == "tts"
-            and native_result.get("abort_data_plane_request") is True
-            and self._session_auto_responds(session)
-        ):
-            await self._maybe_continue_native_response(
-                send_json,
-                session=session,
-                expected_epoch=expected_epoch,
-            )
-        if end_of_turn:
-            data_plane_request_id = native_result.get("data_plane_request_id")
-            if isinstance(data_plane_request_id, str) and not self._session_auto_responds(session):
-                self._serving_runtime_adapter.data_plane.close_stream(data_plane_request_id)
-            if isinstance(data_plane_request_id, str):
-                if not self._session_auto_responds(session) and data_plane_request_id == session.active_request_id:
-                    session.clear_request()
-                if not self._session_auto_responds(session):
-                    self._serving_runtime_adapter.data_plane.mark_terminal(data_plane_request_id)
-            should_commit = self._should_commit_response_to_history(session, response_id)
-            committed_message = session.end_response(
-                commit_text=should_commit,
-                preserve_request=self._session_auto_responds(session),
-            )
-            model_turn_id = coerce_int(native_result.get("model_turn_id"))
-            if model_turn_id is not None:
-                session.complete_model_turn(model_turn_id)
-            if should_commit:
-                session.register_history_item(f"item_{response_id}", committed_message)
-            await send_json(
-                {
-                    "type": "response.done",
-                    "session_id": session.session_id,
-                    "response_id": response_id,
-                    "epoch": session.epoch,
-                    "committed": committed_message is not None,
-                    "playback": session.playback.as_dict(),
-                }
-            )
-        return close_reason, emitted_response
-
-    async def _end_active_response_before_future_model_turn(
-        self,
-        send_json,
-        *,
-        session: DuplexSession,
-        model_turn_id: int | None,
-    ) -> None:
-        if not self._session_auto_responds(session):
-            return
-        response_id = session.active_response_id
-        active_turn_id = session.active_response_turn_id
-        if response_id is None or model_turn_id is None or active_turn_id is None:
-            return
-        if int(model_turn_id) <= int(active_turn_id):
-            return
-        session.complete_model_turn(int(model_turn_id) - 1)
-        should_commit = self._should_commit_response_to_history(session, response_id)
-        committed_message = session.end_response(
-            commit_text=should_commit,
-            preserve_request=True,
-        )
-        if should_commit:
-            session.register_history_item(f"item_{response_id}", committed_message)
-        await send_json(
-            {
-                "type": "response.done",
-                "session_id": session.session_id,
-                "response_id": response_id,
-                "epoch": session.epoch,
-                "committed": committed_message is not None,
-                "playback": session.playback.as_dict(),
-            }
-        )
-
-    @staticmethod
-    def _normalize_native_audio_text_marks(
-        audio_text_marks: list[object] | None,
-        *,
-        audio_offset_ms: int,
-        text_offset_chars: int,
-    ) -> list[dict[str, int]] | None:
-        if not audio_text_marks:
-            return None
-        normalized: list[dict[str, int]] = []
-        for raw_mark in audio_text_marks:
-            if not isinstance(raw_mark, dict):
-                continue
-            raw_text_chars = raw_mark.get("text_chars")
-            raw_audio_end_ms = raw_mark.get("audio_end_ms", raw_mark.get("audio_ms"))
-            if not isinstance(raw_text_chars, int | float) or not isinstance(raw_audio_end_ms, int | float):
-                continue
-            normalized.append(
-                {
-                    "text_chars": max(0, int(raw_text_chars) + int(text_offset_chars)),
-                    "audio_end_ms": max(0, int(raw_audio_end_ms) + int(audio_offset_ms)),
-                }
-            )
-        return normalized or None
-
-    def _cleanup_duplex_session_state(self, session: DuplexSession) -> None:
-        session_id = session.session_id
-        pipeline = self._server_vad_pipelines.pop(session_id, None)
-        if pipeline is not None:
-            pipeline.reset()
-            self._realtime_vad_metrics.session_finished()
-        adapter = self._serving_runtime_adapter
-        if adapter is None:
-            self._serving_session_states.pop(session_id, None)
-        else:
-            adapter.remove_session_state(session_id)
-            adapter.data_plane.close_session(
-                session_id,
-                active_request_id=session.active_request_id,
-            )
-
-    def _encode_native_data_plane_audio(
-        self,
-        audio_data: object,
-        sample_rate_hz: int,
-        response_format: str,
-        speed: float | None,
-    ) -> str | None:
-        if audio_data is None:
-            return None
-        try:
-            import torch
-
-            from vllm_omni.entrypoints.openai.protocol.audio import CreateAudio
-
-            if isinstance(audio_data, torch.Tensor):
-                audio_tensor = audio_data.detach().cpu().float().numpy()
-            else:
-                audio_tensor = np.asarray(audio_data, dtype=np.float32)
-            if audio_tensor.ndim > 1:
-                audio_tensor = audio_tensor.reshape(-1)
-            audio_response = self._chat_service.create_audio(
-                CreateAudio(
-                    audio_tensor=audio_tensor,
-                    sample_rate=sample_rate_hz,
-                    response_format=response_format,
-                    speed=float(speed) if isinstance(speed, int | float) and speed > 0 else 1.0,
-                    stream_format="audio",
-                    base64_encode=True,
-                )
-            )
-            return str(audio_response.audio_data)
-        except Exception:
-            logger.exception("Failed to encode duplex data-plane audio output")
-            return None
-
-    @staticmethod
-    def _attach_native_runtime_metadata(
-        payload: dict[str, object],
-        native_result: dict[str, object],
-        *,
-        stage_metrics: Mapping[str, object] | None = None,
-        response_request_metrics: Mapping[str, object] | None = None,
-    ) -> None:
-        metadata: dict[str, object] = {}
-        runtime_impl = native_result.get("runtime_impl")
-        if isinstance(runtime_impl, str) and runtime_impl:
-            metadata["runtime_impl"] = runtime_impl
-        owned_runtime = native_result.get("owned_runtime")
-        if isinstance(owned_runtime, bool):
-            metadata["owned_runtime"] = owned_runtime
-        model_turn_id = coerce_int(native_result.get("model_turn_id"))
-        if model_turn_id is not None:
-            metadata["model_turn_id"] = model_turn_id
-        for name in (
-            "uses_model_runner_scheduler",
-            "runner_kv_backed",
-        ):
-            value = native_result.get(name)
-            if isinstance(value, bool):
-                metadata[name] = value
-        effective_stage_metrics = stage_metrics if stage_metrics is not None else native_result.get("stage_metrics")
-        if isinstance(effective_stage_metrics, Mapping):
-            metadata["stage_metrics"] = {
-                str(stage_id): dict(values)
-                for stage_id, values in effective_stage_metrics.items()
-                if isinstance(values, Mapping)
-            }
-        if response_request_metrics:
-            metadata["response_request_metrics"] = dict(response_request_metrics)
-        if metadata:
-            payload["vllm_omni"] = metadata
-
-    async def _send_runtime_error(
-        self,
-        send_json,
-        code: str,
-        exc: Exception,
-        *,
-        session: DuplexSession | None = None,
-    ) -> None:
-        retryable = False
-        message = str(exc)
-        if isinstance(exc, DuplexControlRequestError):
-            code = exc.code
-            retryable = exc.retryable
-            error_data = exc.result.get("error")
-            if isinstance(error_data, dict) and isinstance(error_data.get("message"), str):
-                message = error_data["message"]
-        payload: dict[str, object] = {
-            "type": "error",
-            "code": code,
-            "error": message,
-            "retryable": retryable,
-        }
-        if session is not None:
-            payload["session_id"] = session.session_id
-            payload["epoch"] = session.epoch
-        await send_json(payload)
-
-    async def _send_runtime_control_error(
-        self,
-        send_json,
-        code: str,
-        message: str,
-        result: dict[str, object],
-        *,
-        session: DuplexSession,
-    ) -> None:
-        await send_json(
-            {
-                "type": "error",
-                "code": code,
-                "error": message,
-                "session_id": session.session_id,
-                "epoch": session.epoch,
-                "runtime_control": self._redact_runtime_control_result(result),
-            }
-        )
diff --git a/vllm_omni/entrypoints/duplex/server_vad.py b/vllm_omni/entrypoints/duplex/server_vad.py
deleted file mode 100644
index 610e51c8c68..00000000000
--- a/vllm_omni/entrypoints/duplex/server_vad.py
+++ /dev/null
@@ -1,528 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-import hashlib
-import threading
-import time
-from collections.abc import Mapping
-from dataclasses import dataclass, replace
-from pathlib import Path
-from typing import TYPE_CHECKING, Literal, Protocol
-
-import numpy as np
-from vllm.transformers_utils.repo_utils import try_get_local_file
-
-if TYPE_CHECKING:
-    from vllm_omni.entrypoints.openai.audio_utils_mixin import StreamingAudioResampler
-
-SILERO_VAD_REPO_ID = "istupakov/silero-vad-onnx"
-SILERO_VAD_REVISION = "8b14476858ef240c50b3884bb38cc67290c1cc70"
-SILERO_VAD_FILENAME = "silero_vad.onnx"
-SILERO_VAD_SHA256 = "1a153a22f4509e292a94e67d6f9b85e8deb25b4988682b7e174c65279d8788e3"
-SILERO_VAD_MIN_THRESHOLD = 0.15
-SILERO_VAD_DEFAULT_MIN_SPEECH_DURATION_MS = 96
-
-_SERVER_VAD_FIELDS = {
-    "type",
-    "threshold",
-    "prefix_padding_ms",
-    "silence_duration_ms",
-    "create_response",
-    "interrupt_response",
-    "min_speech_duration_ms",
-}
-
-
-@dataclass(frozen=True, slots=True)
-class ServerVADConfig:
-    """Validated OpenAI-compatible ``server_vad`` session configuration."""
-
-    type: Literal["server_vad"] = "server_vad"
-    threshold: float = 0.5
-    prefix_padding_ms: int = 300
-    silence_duration_ms: int = 500
-    create_response: bool = True
-    # Omission is resolved from runtime capabilities before the session is opened.
-    interrupt_response: bool | None = None
-    min_speech_duration_ms: int | None = None
-
-    @classmethod
-    def from_value(cls, value: object) -> ServerVADConfig:
-        if not isinstance(value, dict):
-            raise ValueError("turn_detection must be null or an object")
-        unknown = sorted(set(value) - _SERVER_VAD_FIELDS)
-        if unknown:
-            raise ValueError(f"Unknown server_vad field(s): {', '.join(unknown)}")
-        vad_type = value.get("type")
-        if vad_type != "server_vad":
-            raise ValueError("turn_detection.type must be 'server_vad'")
-
-        threshold = value.get("threshold", 0.5)
-        if isinstance(threshold, bool) or not isinstance(threshold, int | float) or not 0 <= threshold <= 1:
-            raise ValueError("server_vad.threshold must be a number between 0 and 1")
-
-        prefix_padding_ms = value.get("prefix_padding_ms", 300)
-        if isinstance(prefix_padding_ms, bool) or not isinstance(prefix_padding_ms, int) or prefix_padding_ms < 0:
-            raise ValueError("server_vad.prefix_padding_ms must be a non-negative integer")
-
-        silence_duration_ms = value.get("silence_duration_ms", 500)
-        if (
-            isinstance(silence_duration_ms, bool)
-            or not isinstance(silence_duration_ms, int)
-            or silence_duration_ms <= 0
-        ):
-            raise ValueError("server_vad.silence_duration_ms must be a positive integer")
-
-        create_response = value.get("create_response", True)
-        if not isinstance(create_response, bool):
-            raise ValueError("server_vad.create_response must be a boolean")
-
-        interrupt_response = value.get("interrupt_response")
-        if "interrupt_response" in value and not isinstance(interrupt_response, bool):
-            raise ValueError("server_vad.interrupt_response must be a boolean")
-
-        min_speech_duration_ms = value.get("min_speech_duration_ms")
-        if min_speech_duration_ms is not None and (
-            isinstance(min_speech_duration_ms, bool)
-            or not isinstance(min_speech_duration_ms, int | float)
-            or not np.isfinite(float(min_speech_duration_ms))
-            or min_speech_duration_ms < 0
-        ):
-            raise ValueError("server_vad.min_speech_duration_ms must be a non-negative number")
-
-        return cls(
-            type=vad_type,
-            threshold=float(threshold),
-            prefix_padding_ms=prefix_padding_ms,
-            silence_duration_ms=silence_duration_ms,
-            create_response=create_response,
-            interrupt_response=interrupt_response,
-            min_speech_duration_ms=(int(min_speech_duration_ms) if min_speech_duration_ms is not None else None),
-        )
-
-    def as_dict(self) -> dict[str, object]:
-        result: dict[str, object] = {
-            "type": self.type,
-            "threshold": self.threshold,
-            "prefix_padding_ms": self.prefix_padding_ms,
-            "silence_duration_ms": self.silence_duration_ms,
-            "create_response": self.create_response,
-        }
-        if self.interrupt_response is not None:
-            result["interrupt_response"] = self.interrupt_response
-        if self.min_speech_duration_ms is not None:
-            result["min_speech_duration_ms"] = self.min_speech_duration_ms
-        return result
-
-
-def parse_session_turn_detection(
-    payload: Mapping[str, object],
-) -> tuple[bool, ServerVADConfig | None]:
-    """Extract and validate OpenAI-compatible turn detection aliases."""
-    configured_values: list[tuple[str, object]] = []
-    if "turn_detection" in payload:
-        configured_values.append(("turn_detection", payload["turn_detection"]))
-    audio = payload.get("audio")
-    if isinstance(audio, Mapping):
-        audio_input = audio.get("input")
-        if isinstance(audio_input, Mapping) and "turn_detection" in audio_input:
-            configured_values.append(("audio.input.turn_detection", audio_input["turn_detection"]))
-    if not configured_values:
-        return False, None
-
-    first_path, first_value = configured_values[0]
-    first_config = None if first_value is None else ServerVADConfig.from_value(first_value)
-    for field_path, value in configured_values[1:]:
-        config = None if value is None else ServerVADConfig.from_value(value)
-        if first_config is not None and config is not None:
-            # An omitted option must not conflict with an explicit alias value.
-            if first_config.interrupt_response is None:
-                first_config = replace(first_config, interrupt_response=config.interrupt_response)
-            if config.interrupt_response is None:
-                config = replace(config, interrupt_response=first_config.interrupt_response)
-        if config != first_config:
-            raise ValueError(f"{first_path} and {field_path} must not specify conflicting values")
-    return True, first_config
-
-
-class SpeechDetectorBackend(Protocol):
-    """Detector contract; per-stream state is owned by the pipeline."""
-
-    frame_samples: int
-
-    def new_state(self) -> object: ...
-
-    def infer(self, frame: np.ndarray, state: object) -> tuple[float, object]: ...
-
-
-class SpeechDetectorBackendProvider(Protocol):
-    def get(self) -> SpeechDetectorBackend: ...
-
-
-@dataclass(frozen=True, slots=True)
-class SpeechEndpointDecision:
-    speech_started: bool = False
-    speech_stopped: bool = False
-    audio_start_ms: int | None = None
-    audio_end_ms: int | None = None
-    endpoint_delay_ms: int | None = None
-
-
-class SpeechEndpointPolicy(Protocol):
-    @property
-    def speech_active(self) -> bool: ...
-
-    def update(
-        self,
-        probability: float,
-        *,
-        frame_start_sample: int,
-        frame_samples: int,
-    ) -> SpeechEndpointDecision: ...
-
-    def reset(self) -> None: ...
-
-
-class ThresholdEndpointPolicy:
-    """Apply threshold and trailing-silence endpoint rules."""
-
-    def __init__(self, config: ServerVADConfig, *, sample_rate_hz: int) -> None:
-        self.config = config
-        self.sample_rate_hz = sample_rate_hz
-        self._speech_active = False
-        self._candidate_samples = 0
-        self._candidate_start_sample: int | None = None
-        self._silence_samples = 0
-
-    @property
-    def speech_active(self) -> bool:
-        return self._speech_active
-
-    def update(
-        self,
-        probability: float,
-        *,
-        frame_start_sample: int,
-        frame_samples: int,
-    ) -> SpeechEndpointDecision:
-        if probability >= self.config.threshold:
-            self._silence_samples = 0
-            if not self._speech_active:
-                if self._candidate_samples == 0:
-                    self._candidate_start_sample = frame_start_sample
-                self._candidate_samples += frame_samples
-                min_speech_duration_ms = self.config.min_speech_duration_ms or 0
-                min_speech_samples = max(1, round(min_speech_duration_ms * self.sample_rate_hz / 1000))
-                if self._candidate_samples < min_speech_samples:
-                    return SpeechEndpointDecision()
-                self._speech_active = True
-                detected_start_sample = (
-                    self._candidate_start_sample if self._candidate_start_sample is not None else frame_start_sample
-                )
-                detected_start_ms = round(detected_start_sample * 1000 / self.sample_rate_hz)
-                self._candidate_samples = 0
-                self._candidate_start_sample = None
-                return SpeechEndpointDecision(
-                    speech_started=True,
-                    audio_start_ms=max(0, detected_start_ms - self.config.prefix_padding_ms),
-                )
-            return SpeechEndpointDecision()
-
-        if not self._speech_active:
-            self._candidate_samples = 0
-            self._candidate_start_sample = None
-            return SpeechEndpointDecision()
-
-        # Match Silero v6.2's streaming VAD hysteresis: activation uses the
-        # configured threshold, while potential speech end starts only below
-        # ``max(threshold - 0.15, 0.01)``. Once a silence candidate exists,
-        # intermediate frames keep elapsed time moving but cannot themselves
-        # close the turn.
-        negative_threshold = max(self.config.threshold - SILERO_VAD_MIN_THRESHOLD, 0.01)
-        below_negative_threshold = probability < negative_threshold
-        if not below_negative_threshold and self._silence_samples == 0:
-            return SpeechEndpointDecision()
-
-        self._silence_samples += frame_samples
-        if not below_negative_threshold:
-            return SpeechEndpointDecision()
-        silence_limit = max(1, round(self.config.silence_duration_ms * self.sample_rate_hz / 1000))
-        if self._silence_samples < silence_limit:
-            return SpeechEndpointDecision()
-
-        # OpenAI defines ``audio_end_ms`` as the end of the audio sent to the
-        # model, including the trailing silence used for endpoint detection.
-        audio_end_sample = frame_start_sample + frame_samples
-        endpoint_delay_ms = round(self._silence_samples * 1000 / self.sample_rate_hz)
-        self.reset()
-        return SpeechEndpointDecision(
-            speech_stopped=True,
-            audio_end_ms=max(0, round(audio_end_sample * 1000 / self.sample_rate_hz)),
-            endpoint_delay_ms=endpoint_delay_ms,
-        )
-
-    def reset(self) -> None:
-        self._speech_active = False
-        self._candidate_samples = 0
-        self._candidate_start_sample = None
-        self._silence_samples = 0
-
-
-@dataclass(frozen=True, slots=True)
-class ServerVADFrame:
-    samples: np.ndarray
-    decision: SpeechEndpointDecision
-
-
-@dataclass(frozen=True, slots=True)
-class ServerVADBatch:
-    frames: tuple[ServerVADFrame, ...]
-    inference_ms: float
-
-
-class ServerVADPipeline:
-    """Frame continuous 16 kHz audio and apply acoustic endpointing.
-
-    The pipeline retains only input-resampling residuals, a partial frame,
-    detector state, and timing counters. Commit-eligible prefix and utterance
-    audio remain session-owned.
-    """
-
-    sample_rate_hz = 16_000
-
-    def __init__(
-        self,
-        backend: SpeechDetectorBackend,
-        config: ServerVADConfig,
-        *,
-        endpoint_policy: SpeechEndpointPolicy | None = None,
-    ) -> None:
-        self.backend = backend
-        self.config = config
-        self.endpoint_policy = endpoint_policy or ThresholdEndpointPolicy(
-            config,
-            sample_rate_hz=self.sample_rate_hz,
-        )
-        self._input_resampler: StreamingAudioResampler | None = None
-        self._source_sample_rate_hz: int | None = None
-        self._scratch = np.empty(0, dtype=np.float32)
-        self._detector_state = backend.new_state()
-        self._processed_samples = 0
-        self._stream_start_ms = 0
-
-    @property
-    def speech_active(self) -> bool:
-        return self.endpoint_policy.speech_active
-
-    @property
-    def source_sample_rate_hz(self) -> int | None:
-        return self._source_sample_rate_hz
-
-    @property
-    def scratch_bytes(self) -> int:
-        resampler_bytes = self._input_resampler.scratch_bytes if self._input_resampler is not None else 0
-        return int(self._scratch.nbytes) + resampler_bytes
-
-    async def push_pcm16(
-        self,
-        samples: bytes,
-        *,
-        source_sample_rate_hz: int,
-    ) -> ServerVADBatch:
-        """Normalize chunked mono PCM16 input and run endpoint detection."""
-        if isinstance(source_sample_rate_hz, bool) or source_sample_rate_hz not in {16_000, 24_000}:
-            raise ValueError("server_vad PCM16 input sample rate must be 16000 or 24000 Hz")
-
-        if len(samples) % np.dtype("<i2").itemsize:
-            raise ValueError("server_vad PCM16 input contains an incomplete sample")
-        pcm16 = np.frombuffer(samples, dtype="<i2")
-
-        if self._source_sample_rate_hz is not None and source_sample_rate_hz != self._source_sample_rate_hz:
-            raise ValueError("server_vad input sample rate cannot change within a continuous audio stream")
-        if pcm16.size and self._source_sample_rate_hz is None:
-            from vllm_omni.entrypoints.openai.audio_utils_mixin import StreamingAudioResampler
-
-            self._input_resampler = (
-                None
-                if source_sample_rate_hz == self.sample_rate_hz
-                else StreamingAudioResampler(source_sample_rate_hz, self.sample_rate_hz)
-            )
-            self._source_sample_rate_hz = source_sample_rate_hz
-
-        normalized = np.ascontiguousarray(pcm16, dtype=np.float32) * np.float32(1.0 / 32768.0)
-        if self._input_resampler is not None:
-            normalized = self._input_resampler.process(normalized)
-        return await self.push(normalized)
-
-    async def push(self, samples: np.ndarray) -> ServerVADBatch:
-        normalized = np.ascontiguousarray(samples, dtype=np.float32).reshape(-1)
-        return await asyncio.to_thread(self._push_sync, normalized)
-
-    def _push_sync(self, samples: np.ndarray) -> ServerVADBatch:
-        started_at = time.perf_counter()
-        if self._scratch.size:
-            samples = np.concatenate((self._scratch, samples))
-        frame_samples = int(self.backend.frame_samples)
-        complete_samples = samples.size - samples.size % frame_samples
-        # Retained state must not keep the whole input chunk alive through a view.
-        self._scratch = samples[complete_samples:].copy()
-
-        results: list[ServerVADFrame] = []
-        for offset in range(0, complete_samples, frame_samples):
-            frame = np.ascontiguousarray(samples[offset : offset + frame_samples], dtype=np.float32)
-            frame_start = self._processed_samples
-            probability, self._detector_state = self.backend.infer(frame, self._detector_state)
-            probability = min(1.0, max(0.0, float(probability)))
-            decision = self.endpoint_policy.update(
-                probability,
-                frame_start_sample=frame_start,
-                frame_samples=frame_samples,
-            )
-            if decision.speech_started and decision.audio_start_ms is not None:
-                # Prefix audio before the most recent reset is no longer available.
-                decision = replace(decision, audio_start_ms=max(self._stream_start_ms, decision.audio_start_ms))
-
-            self._processed_samples += frame_samples
-            results.append(
-                ServerVADFrame(
-                    samples=frame,
-                    decision=decision,
-                )
-            )
-        return ServerVADBatch(
-            frames=tuple(results),
-            inference_ms=(time.perf_counter() - started_at) * 1000,
-        )
-
-    def reset(self) -> None:
-        """Discard stream state while preserving the session-relative audio clock."""
-        self._stream_start_ms = round(self._processed_samples * 1000 / self.sample_rate_hz)
-        self._input_resampler = None
-        self._source_sample_rate_hz = None
-        self._scratch = np.empty(0, dtype=np.float32)
-        self._detector_state = self.backend.new_state()
-        self.endpoint_policy.reset()
-
-
-@dataclass(frozen=True, slots=True)
-class _SileroVADState:
-    model_state: np.ndarray
-    context: np.ndarray
-
-
-class SileroVADBackend:
-    """Shared ONNX Runtime Silero v6.2 detector running on CPU."""
-
-    sample_rate_hz = 16_000
-    frame_samples = 512
-    context_samples = 64
-    model_state_shape = (2, 1, 128)
-
-    def __init__(self, model_path: str | Path) -> None:
-        try:
-            import onnxruntime as ort
-        except ImportError as exc:  # pragma: no cover - platform packaging supplies ORT.
-            raise RuntimeError("server_vad requires ONNX Runtime") from exc
-
-        session_options = ort.SessionOptions()
-        session_options.inter_op_num_threads = 1
-        session_options.intra_op_num_threads = 1
-
-        self.model_path = Path(model_path)
-        self._session = ort.InferenceSession(
-            str(self.model_path),
-            providers=["CPUExecutionProvider"],
-            sess_options=session_options,
-        )
-        input_names = {item.name for item in self._session.get_inputs()}
-        if "input" not in input_names or "sr" not in input_names or "state" not in input_names:
-            raise RuntimeError(f"Unsupported Silero ONNX input contract: {sorted(input_names)}")
-        self._warm_up()
-
-    def _warm_up(self) -> None:
-        self.infer(np.zeros(self.frame_samples, dtype=np.float32), self.new_state())
-
-    def new_state(self) -> _SileroVADState:
-        return _SileroVADState(
-            model_state=np.zeros(self.model_state_shape, dtype=np.float32),
-            context=np.zeros((1, self.context_samples), dtype=np.float32),
-        )
-
-    def infer(self, frame: np.ndarray, state: object) -> tuple[float, object]:
-        if not isinstance(state, _SileroVADState):
-            raise TypeError("Silero detector state must be created by SileroVADBackend.new_state()")
-        model_state = np.ascontiguousarray(state.model_state, dtype=np.float32)
-        context = np.ascontiguousarray(state.context, dtype=np.float32)
-        if model_state.shape != self.model_state_shape:
-            raise ValueError(f"Silero model state must have shape {self.model_state_shape}, got {model_state.shape}")
-        expected_context_shape = (1, self.context_samples)
-        if context.shape != expected_context_shape:
-            raise ValueError(f"Silero context must have shape {expected_context_shape}, got {context.shape}")
-
-        audio = np.ascontiguousarray(frame, dtype=np.float32).reshape(1, -1)
-        if audio.shape[1] != self.frame_samples:
-            raise ValueError(
-                f"Silero detector frame must contain exactly {self.frame_samples} samples, got {audio.shape[1]}"
-            )
-        model_input = np.concatenate((context, audio), axis=1)
-        inputs = {
-            "input": model_input,
-            "state": model_state,
-            "sr": np.asarray(self.sample_rate_hz, dtype=np.int64),
-        }
-        # ONNX Runtime permits concurrent Run calls on one CPU session. Stream
-        # state is explicit, so independent pipelines can safely share the session.
-        output = self._session.run(None, inputs)
-        if len(output) < 2:
-            raise RuntimeError("Silero ONNX model did not return probability and model state")
-        probability = float(np.asarray(output[0]).reshape(-1)[0])
-        next_state = _SileroVADState(
-            model_state=np.ascontiguousarray(output[1], dtype=np.float32),
-            context=np.ascontiguousarray(model_input[:, -self.context_samples :], dtype=np.float32),
-        )
-        return probability, next_state
-
-
-class SileroVADBackendProvider:
-    """Resolve, verify, and load one Silero model instance per process."""
-
-    def __init__(self, *, model_path: str | None = None) -> None:
-        self.model_path = model_path
-        self._backend: SileroVADBackend | None = None
-        self._lock = threading.Lock()
-
-    def get(self) -> SileroVADBackend:
-        if self._backend is not None:
-            return self._backend
-        with self._lock:
-            if self._backend is None:
-                path = self._resolve_local_artifact()
-                self._verify_checksum(path)
-                self._backend = SileroVADBackend(path)
-        return self._backend
-
-    def _resolve_local_artifact(self) -> Path:
-        if self.model_path:
-            path = Path(self.model_path).expanduser()
-            if path.is_file():
-                return path
-            raise RuntimeError(f"Configured Silero VAD model does not exist: {path}")
-        cached = try_get_local_file(
-            model=SILERO_VAD_REPO_ID,
-            file_name=SILERO_VAD_FILENAME,
-            revision=SILERO_VAD_REVISION,
-        )
-        if isinstance(cached, Path) and cached.is_file():
-            return cached
-        raise RuntimeError(
-            "Silero VAD artifact is not available locally. Pre-download the pinned artifact "
-            "or configure duplex_session.server_vad_model_path."
-        )
-
-    def _verify_checksum(self, path: Path) -> None:
-        digest = hashlib.sha256(path.read_bytes()).hexdigest()
-        if digest != SILERO_VAD_SHA256:
-            raise RuntimeError(f"Silero VAD checksum mismatch for {path}: expected {SILERO_VAD_SHA256}, got {digest}")
diff --git a/vllm_omni/entrypoints/duplex/serving.py b/vllm_omni/entrypoints/duplex/serving.py
index 7bd690841c3..364f715c057 100644
--- a/vllm_omni/entrypoints/duplex/serving.py
+++ b/vllm_omni/entrypoints/duplex/serving.py
@@ -1,2130 +1,543 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
+"""Thin websocket serving for ``/v1/realtime?duplex=1``.
+
+Everything about a duplex *session* lives inside the engine (see
+``vllm_omni.entrypoints.duplex_omni``). This handler only does transport:
+
+* accept the socket and run the Realtime handshake (``session.update`` opens a
+  session through ``DuplexOmni.open_session``; ``session.resume`` re-attaches
+  to an existing one);
+* translate each client JSON event into a ``DuplexCommand`` and submit it in
+  arrival order;
+* pump the session's typed events to the wire, journaling them for resume;
+* manage attachments: resume tokens, replay, takeover, detach on disconnect.
+"""
+
 from __future__ import annotations
 
 import asyncio
-import base64
-import binascii
-import inspect
 import json
-from collections.abc import Mapping, MutableMapping
+from collections.abc import Mapping
 from contextlib import suppress
 from dataclasses import dataclass, replace
-from typing import TYPE_CHECKING
 
-import numpy as np
-from fastapi import WebSocket
+from fastapi import WebSocket, WebSocketDisconnect
 from vllm.logger import init_logger
 
-from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
-from vllm_omni.engine.duplex.messages import DuplexFence, DuplexSessionLifecycleMessage
-from vllm_omni.engine.duplex.runtime import duplex_resource_request_id
-from vllm_omni.entrypoints.duplex.capability import (
-    should_enable_duplex_endpoint,
-)
-from vllm_omni.entrypoints.duplex.chat_fallback import (
-    ChatFallbackProjectorMixin,
-)
-from vllm_omni.entrypoints.duplex.protocol import (
-    NATIVE_DUPLEX_KEY,
-    DuplexCapabilities,
-    DuplexCommittedInput,
-    DuplexOverlapPolicy,
-    DuplexPlaybackCommitPolicy,
-    DuplexSession,
-    DuplexSessionConfig,
-    DuplexSessionRegistry,
-    DuplexSessionState,
-    DuplexTurnController,
-    ResponseCreateOptions,
-    native_duplex_opt_in,
-    normalize_native_duplex_key,
-)
-from vllm_omni.entrypoints.duplex.realtime_session import (
-    REALTIME_OUTPUT_AUDIO_FORMATS,
-    NativeRealtimeSessionProtocol,
-)
-from vllm_omni.entrypoints.duplex.runtime_adapter import (
-    ServingRuntimeAdapter,
-    ServingRuntimeConfigError,
-    ServingRuntimeSessionState,
-    TurnBasedServingSessionState,
-    load_serving_runtime_adapter,
-    validate_serving_runtime_adapter,
-)
-from vllm_omni.entrypoints.duplex.runtime_bridge import (
-    NativeRuntimeBridgeMixin,
-)
-from vllm_omni.entrypoints.duplex.server_vad import (
-    SILERO_VAD_DEFAULT_MIN_SPEECH_DURATION_MS,
-    SILERO_VAD_MIN_THRESHOLD,
-    ServerVADPipeline,
-    SileroVADBackendProvider,
-    SpeechDetectorBackendProvider,
-    parse_session_turn_detection,
+from vllm_omni.engine.duplex.commands import DuplexCommand, DuplexCommandError
+from vllm_omni.engine.duplex.events import (
+    DuplexEvent,
+    SessionClosed,
+    SessionCreated,
+    SessionReplaced,
+    SessionResumed,
+    SessionResyncRequired,
 )
+from vllm_omni.engine.duplex.messages import DuplexSessionError
+from vllm_omni.engine.duplex.realtime_commands import RealtimeInputDefaults
+from vllm_omni.entrypoints.duplex.realtime_input import RealtimeEnvelope, parse_resume_request
 from vllm_omni.entrypoints.duplex.session_attachment import (
     DuplexJournalGapError,
+    DuplexJournalOverflowError,
     DuplexSessionAttachmentRegistry,
     InvalidResumeTokenError,
-)
-from vllm_omni.entrypoints.duplex.session_runner import (
-    DuplexSessionRunnerMixin,
+    ResumeToken,
 )
 from vllm_omni.entrypoints.duplex.websocket import (
-    DOMAIN_TERMINAL_EVENTS,
-    DuplexSessionTasks,
-    DuplexWebSocketActor,
+    MAX_EVENT_BYTES,
+    SendJson,
+    attachment_callbacks,
+    receive_text_with_timeout,
 )
-from vllm_omni.metrics.realtime import RealtimeVADMetrics
-
-if TYPE_CHECKING:
-    from vllm_omni.entrypoints.openai.serving_chat import OmniOpenAIServingChat
+from vllm_omni.entrypoints.duplex_omni import DuplexOmni, DuplexSessionHandle
 
 logger = init_logger(__name__)
 
-__all__ = ["OmniDuplexSessionHandler", "should_enable_duplex_endpoint"]
+__all__ = ["OmniDuplexSessionHandler"]
 
 _DEFAULT_CONFIG_TIMEOUT_S = 10.0
 _DEFAULT_IDLE_TIMEOUT_S = 300.0
+#: How long the endpoint waits for the session pump to deliver its terminal
+#: event once the session is closed. Bounded so a wedged pump cannot pin the
+#: connection open; the pump itself closes the socket on its way out.
+_PUMP_DRAIN_TIMEOUT_S = 5.0
+#: session.created is journaled by the registry when it hands out the resume credential.
+_UNJOURNALED_EVENTS = (SessionCreated,)
+
+
+@dataclass
+class _Attachment:
+    """What one websocket connection knows about the session it is attached to."""
+
+    handle: DuplexSessionHandle
+    generation: int
 
 
 @dataclass(frozen=True)
-class _DuplexSessionHandshake:
-    session: DuplexSession
-    resumed: bool = False
-    attachment_generation: int | None = None
-    event_id: str | None = None
+class _ResumeCredentials:
+    """Transport credentials stamped onto ``session.created`` for a resumable session."""
 
+    attachment_generation: int
+    resume_token: str
 
-class OmniDuplexSessionHandler(
-    DuplexSessionRunnerMixin,
-    NativeRuntimeBridgeMixin,
-    ChatFallbackProjectorMixin,
-):
-    """WebSocket handler for RFC-style full-duplex session control.
 
-    This owns the serving-side session actor, ordered inbound mailbox,
-    barge-in epoch, turn controller, and playback commit state. Generic sessions
-    can still fall back to chat requests, while MiniCPM-o 4.5 native sessions
-    route audio appends through scheduler data-plane stage requests. It
-    deliberately does not claim core persistent KV lease support.
-    """
+class OmniDuplexSessionHandler:
+    """WebSocket transport for engine-resident duplex sessions."""
 
     def __init__(
         self,
         *,
-        chat_service: OmniOpenAIServingChat,
-        served_model_name: str | None = None,
+        duplex_omni: DuplexOmni,
         config_timeout_s: float = _DEFAULT_CONFIG_TIMEOUT_S,
         idle_timeout_s: float = _DEFAULT_IDLE_TIMEOUT_S,
-        log_stats: bool = True,
-        duplex_session_config: DuplexSessionRuntimeConfig | None = None,
-        serving_runtime_adapter: ServingRuntimeAdapter | None = None,
-        serving_runtime_adapter_path: str | None = None,
-        server_vad_backend_provider: SpeechDetectorBackendProvider | None = None,
     ) -> None:
-        self._chat_service = chat_service
+        self._omni = duplex_omni
         self._config_timeout_s = config_timeout_s
         self._idle_timeout_s = idle_timeout_s
-        self._duplex_session_config = duplex_session_config or DuplexSessionRuntimeConfig()
-        self._server_vad_backend_provider = server_vad_backend_provider or SileroVADBackendProvider(
-            model_path=self._duplex_session_config.server_vad_model_path,
-        )
-        self._server_vad_pipelines: dict[str, ServerVADPipeline] = {}
-        self._realtime_vad_metrics = RealtimeVADMetrics(
-            served_model_name or chat_service.model_config.model,
-            log_stats=log_stats,
-        )
-        self._registry = DuplexSessionRegistry(
-            DuplexCapabilities(
-                supports_model_native_turn_policy=False,
-                supports_input_append=False,
-                supports_replace_latest_chunk=True,
-                supports_reencode_context=True,
-                supports_turn_commit_only=True,
-                supports_kv_lease=False,
-            )
-        )
-        self._turn_controller = DuplexTurnController()
-        adapter_path = serving_runtime_adapter_path or getattr(
-            chat_service,
-            "duplex_serving_adapter_path",
-            None,
-        )
-        self._serving_runtime_adapter: ServingRuntimeAdapter | None
-        if serving_runtime_adapter is not None:
-            self._serving_runtime_adapter = validate_serving_runtime_adapter(serving_runtime_adapter)
-        elif isinstance(adapter_path, str) and adapter_path:
-            self._serving_runtime_adapter = load_serving_runtime_adapter(
-                adapter_path,
-                self._encode_native_data_plane_audio,
-            )
-        else:
-            self._serving_runtime_adapter = None
-        self._serving_session_states: MutableMapping[str, ServingRuntimeSessionState] = (
-            self._serving_runtime_adapter.session_states if self._serving_runtime_adapter is not None else {}
-        )
-        self._session_tasks: dict[str, DuplexSessionTasks] = {}
-        self._realtime_protocols: dict[str, NativeRealtimeSessionProtocol] = {}
-        self._lease_generations: dict[str, int] = {}
-        self._resync_required_sessions: set[str] = set()
-        self._lifecycle_queue = getattr(self._chat_service.engine_client, "duplex_lifecycle_events", None)
-        self._lifecycle_task: asyncio.Task[None] | None = None
+        runtime_config = duplex_omni.duplex_session_config
         self._attachment_registry = DuplexSessionAttachmentRegistry(
-            replay_ttl_s=self._duplex_session_config.resume_replay_ttl_s,
-            replay_max_bytes_per_session=self._duplex_session_config.resume_replay_max_bytes_per_session,
-            disconnect_grace_s=self._duplex_session_config.disconnect_grace_s,
+            replay_ttl_s=runtime_config.resume_replay_ttl_s,
+            replay_max_bytes_per_session=runtime_config.resume_replay_max_bytes_per_session,
         )
+        self._resync_required_sessions: set[str] = set()
+        #: Wire defaults (input/output audio format and rate) per session. They
+        #: are negotiated on the session but live on the per-connection
+        #: envelope, so a reconnect has to be handed them back.
+        self._input_defaults: dict[str, RealtimeInputDefaults] = {}
+        self._pumps: dict[str, asyncio.Task[None]] = {}
+
+    # ------------------------------------------------------------------ #
+    # Entry point                                                         #
+    # ------------------------------------------------------------------ #
 
     async def handle_realtime_session(self, websocket: WebSocket) -> None:
-        await self.handle_session(
-            websocket,
-            realtime_protocol=NativeRealtimeSessionProtocol(websocket.query_params),
-        )
+        await websocket.accept()
+        envelope = RealtimeEnvelope.from_query_params(websocket.query_params)
 
-    def _ensure_lifecycle_listener(self) -> None:
-        if not isinstance(self._lifecycle_queue, asyncio.Queue):
-            return
-        if self._lifecycle_task is None or self._lifecycle_task.done():
-            self._lifecycle_task = asyncio.create_task(
-                self._run_lifecycle_listener(),
-                name="duplex-serving-lifecycle",
-            )
+        async def send_json(payload: Mapping[str, object]) -> None:
+            await websocket.send_json(dict(payload))
 
-    async def _run_lifecycle_listener(self) -> None:
-        queue = self._lifecycle_queue
-        if not isinstance(queue, asyncio.Queue):
-            return
+        attachment: _Attachment | None = None
+        pending_command: dict[str, object] | None = None
         try:
-            while True:
-                message = await queue.get()
-                try:
-                    if isinstance(message, DuplexSessionLifecycleMessage):
-                        await self._apply_runtime_lifecycle(message)
-                finally:
-                    queue.task_done()
-                if self._registry.active_count() == 0:
+            open_payload = envelope.initial_open_payload()
+            if open_payload is None:
+                first = await self._receive_first_message(websocket, envelope, send_json)
+                if first is None:
                     return
-        finally:
-            if self._lifecycle_task is asyncio.current_task():
-                self._lifecycle_task = None
-
-    async def _apply_runtime_lifecycle(self, message: DuplexSessionLifecycleMessage) -> None:
-        session = self._registry.get(message.session_id)
-        if session is None:
-            return
-        fence = message.fence
-        if (
-            fence.session_id != session.session_id
-            or fence.incarnation != session.incarnation
-            or fence.epoch < session.epoch
-        ):
-            return
-        current_generation = self._lease_generations.get(session.session_id, 0)
-        if message.lease_generation < current_generation:
-            return
-        protocol = self._realtime_protocols.get(session.session_id)
-        expired_payload: dict[str, object] = {
-            "type": "session.expired",
-            "session_id": session.session_id,
-            "incarnation": session.incarnation,
-            "reason": message.reason,
-        }
-        if protocol is not None:
-            expired_payload = protocol.encode_outbound_event(expired_payload)[0]
-        with suppress(Exception):
-            await self._attachment_registry.send_event(
-                session.session_id,
-                expired_payload,
-                journal=False,
-            )
-
-        tasks = self._session_tasks.pop(session.session_id, None)
-        if tasks is not None:
-            await tasks.cancel_append_tasks()
-            active_response_task = tasks.active_response_task
-            if active_response_task is not None and not active_response_task.done():
-                active_response_task.cancel()
-                with suppress(asyncio.CancelledError):
-                    await active_response_task
-        native = self._serving_session_states.get(session.session_id)
-        if native is not None and native.data_plane_task is not None:
-            data_plane_task = native.data_plane_task
-            native.data_plane_task = None
-            data_plane_task.cancel()
-            with suppress(asyncio.CancelledError):
-                await data_plane_task
-        if session.active_response_id is not None:
-            session.end_response(commit_text=False)
-        self._cleanup_duplex_session_state(session)
-        self._registry.close(session.session_id)
-        self._realtime_protocols.pop(session.session_id, None)
-        self._lease_generations.pop(session.session_id, None)
-        self._resync_required_sessions.discard(session.session_id)
-        attachment = await self._attachment_registry.close(session.session_id)
-        if attachment is not None:
-            with suppress(Exception):
-                await attachment.close("session_expired")
-
-    def _stop_lifecycle_listener_if_idle(self) -> None:
-        task = self._lifecycle_task
-        if self._registry.active_count() != 0 or task is None or task.done():
-            return
-        if task is not asyncio.current_task():
-            task.cancel()
-            self._lifecycle_task = None
-
-    @staticmethod
-    def _native_audio_payload_size_bytes(payload: Mapping[str, object]) -> int:
-        audio = payload.get("audio") or payload.get("data")
-        if not isinstance(audio, str):
-            return 0
-        try:
-            return len(base64.b64decode(audio, validate=True))
-        except (ValueError, binascii.Error):
-            return 0
-
-    async def _apply_outbound_session_event(
-        self,
-        payload: dict[str, object],
-        *,
-        session: DuplexSession | None,
-        actor: DuplexWebSocketActor,
-        native: ServingRuntimeSessionState,
-        realtime_protocol: NativeRealtimeSessionProtocol | None,
-    ) -> tuple[bool, dict[str, object] | None]:
-        """Apply domain transitions before an event is queued for transport."""
-        payload_type = payload.get("type")
-        is_terminal = payload_type in DOMAIN_TERMINAL_EVENTS
-        if is_terminal and session is not None:
-            payload_epoch = payload.get("epoch")
-            if isinstance(payload_epoch, int) and payload_epoch != session.epoch:
-                return False, None
-            if payload_type in {"response.done", "response.listen"} and (
-                actor.closing or session.state == DuplexSessionState.CLOSED
-            ):
-                return False, None
-        elif actor._is_stale_model_output(payload):
-            return False, None
-
-        if payload_type == "session.closed":
-            actor.close_reason = actor.close_reason or str(payload.get("reason") or "closed")
-            if session is not None:
-                session.mark_closing()
-
-        if not is_terminal or session is None:
-            return True, None
-
-        terminal_status = payload.get("status")
-        terminal_status_details = payload.get("status_details")
-        if terminal_status is None and isinstance(terminal_status_details, dict):
-            terminal_status = terminal_status_details.get("type")
-        response_terminal = payload_type == "response.done" or (
-            payload_type == "response.listen" and session.active_response_id is not None
-        )
-        can_promote_overlap = response_terminal and terminal_status not in {"cancelled", "failed"}
-        deferred_overlap_payload: dict[str, object] | None = None
-        continuous_input_crosses_terminal = (
-            can_promote_overlap
-            and realtime_protocol is not None
-            and self._session_auto_responds(session)
-            and native.input_since_commit
-            and not native.deferred_response_create
-        )
-        if continuous_input_crosses_terminal:
-            # Auto-response is a model-owned continuous stream. A response
-            # terminal advances the model turn without requiring the browser
-            # to close its Realtime input item. Keep any partial model unit so
-            # later PCM can complete it. Serving does not create or promote a
-            # new model generation here; Stage0 advances generation identity
-            # only after the model's terminal token.
-            session.reset_overlap_speech()
-            return True, None
-        realtime_input_still_open = (
-            can_promote_overlap
-            and realtime_protocol is not None
-            and native.input_since_commit
-            and not native.deferred_response_create
-        )
-        if realtime_input_still_open:
-            # response.done only closes the assistant response. It does not
-            # close the current Realtime input item, and it does not reserve
-            # or advance a model generation.
-            session.reset_overlap_speech()
-            return True, None
-        if can_promote_overlap and session.overlap_speech_ms > 0:
-            has_deferred_overlap = native.audio_buffer.has_pending() or native.committed_audio_payload is not None
-            should_promote_overlap = (
-                session.state == DuplexSessionState.OPEN
-                and self._uses_native_input_append(session)
-                and has_deferred_overlap
-                and session.overlap_speech_ms > session.config.overlap_short_ack_ms
-            )
-            if should_promote_overlap:
-                flushed_reserved_bytes = native.audio_buffer.pending_byte_count
-                deferred_overlap_payload = native.audio_buffer.flush(
-                    chunk_period_ms=session.capabilities.chunk_period_ms or 1000
-                )
-                if native.committed_audio_payload is not None:
-                    if deferred_overlap_payload is not None:
-                        deferred_overlap_payload = self._merge_native_audio_payloads(
-                            native.committed_audio_payload,
-                            deferred_overlap_payload,
-                        )
-                    else:
-                        deferred_overlap_payload = native.committed_audio_payload
-                if self._session_auto_responds(session) and deferred_overlap_payload is not None:
-                    deferred_overlap_payload = dict(deferred_overlap_payload)
-                    deferred_overlap_payload["force_listen"] = False
-                if deferred_overlap_payload is not None:
-                    native.retain_committed_audio(
-                        deferred_overlap_payload,
-                        operation_id=native.committed_audio_operation_id,
-                        reserved_bytes=flushed_reserved_bytes,
-                    )
-                native.input_since_commit = deferred_overlap_payload is not None
-                if realtime_protocol is not None:
-                    native.deferred_response_create = True
-                    native.deferred_precreate_response = False
-                    deferred_overlap_payload = None
-            else:
-                had_pending_overlap_audio = native.audio_buffer.has_pending()
-                native.audio_buffer.clear()
-                native.input_since_commit = False
-                native.speech_since_commit = False
-                if had_pending_overlap_audio and realtime_protocol is not None:
-                    await realtime_protocol.discard_pending_input_audio(audio_end_ms=session.overlap_speech_ms)
-                if payload_type in {"audio.cancelled", "input.cancelled", "session.closed"}:
-                    session.release_input_bytes(native.clear_committed_audio())
-
-        session.reset_overlap_speech()
-        if can_promote_overlap and native.deferred_response_create and native.committed_audio_payload is not None:
-            deferred_overlap_payload = native.committed_audio_payload
-            native.deferred_response_create = False
-            native.input_since_commit = False
-            native.speech_since_commit = False
-        return True, deferred_overlap_payload
-
-    @staticmethod
-    def _advance_barge_in_epoch(session: DuplexSession) -> tuple[int, dict[str, int]]:
-        old_playback = session.playback.as_dict()
-        new_epoch = session.barge_in()
-        session.clear_playback_cursor()
-        return new_epoch, old_playback
-
-    @staticmethod
-    def _commit_played_response_history(
-        session: DuplexSession,
-        response_id: str | None,
-        committed_ms: int,
-    ) -> None:
-        if not response_id or committed_ms < 0:
-            return
-        session.truncate_history_item(
-            f"item_{response_id}",
-            audio_end_ms=committed_ms,
-            playback=session.playback_for_response(response_id),
-        )
-
-    @staticmethod
-    def _should_commit_response_to_history(session: DuplexSession, response_id: str | None) -> bool:
-        if response_id is not None and response_id != session.active_response_id:
-            return True
-        mode = session.response_config.extra_body.get("realtime_response_conversation")
-        return not isinstance(mode, str) or mode.strip().lower() != "none"
-
-    def _response_created_payload(
-        self,
-        session: DuplexSession,
-        response_id: str,
-        *,
-        epoch: int,
-        request_id: str | None = None,
-    ) -> dict[str, object]:
-        response_config = session.response_config
-        payload: dict[str, object] = {
-            "type": "response.created",
-            "session_id": session.session_id,
-            "response_id": response_id,
-            "epoch": epoch,
-            "modalities": list(response_config.modalities),
-        }
-        if request_id is not None:
-            payload["request_id"] = request_id
-        metadata = response_config.extra_body.get("realtime_response_metadata")
-        if not isinstance(metadata, dict):
-            metadata = response_config.extra_body.get("realtime_metadata")
-        if isinstance(metadata, dict):
-            payload["metadata"] = dict(metadata)
-        conversation = response_config.extra_body.get("realtime_response_conversation")
-        if isinstance(conversation, str):
-            payload["conversation"] = conversation
-        prompt = response_config.extra_body.get("realtime_response_prompt")
-        if isinstance(prompt, dict):
-            payload["prompt"] = dict(prompt)
-        return payload
-
-    def _overlap_decision(
-        self,
-        session: DuplexSession,
-        event: dict[str, object],
-        payload: dict[str, object],
-    ) -> dict[str, object]:
-        """Classify input that arrives while assistant audio is active.
-
-        This is a serving-side policy. The model still owns listen/speak
-        decisions for normal chunks; overlap policy only decides whether the
-        current assistant response should be interrupted before the new audio is
-        appended.
-        """
-        duration_ms = self._input_audio_duration_ms(event, payload)
-        is_speech = self._input_looks_like_speech(event, payload, session=session)
-        if not session.capabilities.supports_barge_in and self._event_requests_barge_in(event):
-            return self._defer_unsupported_barge_in(session, duration_ms=duration_ms, is_speech=is_speech)
-        explicit = event.get("overlap_action") or event.get("overlap")
-        if isinstance(explicit, str):
-            normalized = explicit.strip().lower()
-            if normalized in {"barge_in", "interrupt", "cancel"}:
-                return {
-                    "action": "barge_in",
-                    "reason": "client_overlap_action",
-                    "duration_ms": duration_ms,
-                    "buffer_audio": True,
-                }
-            if normalized in {"listen", "continue", "continue_output", "ack"}:
-                session.reset_overlap_speech()
-                return {
-                    "action": "listen",
-                    "reason": "client_overlap_action",
-                    "duration_ms": duration_ms,
-                    "buffer_audio": (
-                        normalized == "listen" and is_speech and duration_ms > session.config.overlap_short_ack_ms
-                    ),
-                    "defer_runtime_append": True,
-                }
-            if normalized in {"drop", "ignore", "silence"}:
-                session.reset_overlap_speech()
-                return {
-                    "action": "drop",
-                    "reason": "client_overlap_action",
-                    "duration_ms": duration_ms,
-                    "buffer_audio": False,
-                }
-
-        if bool(event.get("force_barge_in", False)):
-            return {
-                "action": "barge_in",
-                "reason": "client_force_barge_in",
-                "duration_ms": duration_ms,
-                "buffer_audio": True,
-            }
-        if self._session_auto_responds(session):
-            # Full-duplex input remains model-owned while output is active. Feed
-            # complete model units into the existing Stage0 stream immediately;
-            # playback only controls history ACKs, not model admission.
-            if is_speech:
-                session.accumulate_overlap_speech(duration_ms)
-            vad_speech_started = self._vad_speech_started(event, payload)
-            if (
-                self._uses_native_input_append(session)
-                and session.capabilities.supports_barge_in
-                and is_speech
-                and session.config.overlap_policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value
-                and vad_speech_started is not False
+                handshake = envelope.first_message(first)
+                if handshake.kind == "resume":
+                    attachment = await self._resume(websocket, envelope, handshake.resume_payload, send_json)
+                    if attachment is None:
+                        return
+                else:
+                    open_payload = handshake.session_payload
+                    pending_command = handshake.pending_command_payload
+            if attachment is None:
+                assert open_payload is not None
+                attachment = await self._open(websocket, envelope, open_payload, send_json)
+                if attachment is None:
+                    return
+            if pending_command is not None:
+                await self._submit_wire_event(attachment, envelope, pending_command, send_json)
+            self._input_defaults[attachment.handle.session_id] = envelope.defaults
+            await self._read_loop(websocket, envelope, attachment, send_json)
+            await self._drain_terminal_pump(attachment)
+        except WebSocketDisconnect:
+            if attachment is not None:
+                await self._on_disconnect(attachment)
+        except Exception as exc:
+            logger.exception("Duplex websocket session failed: %s", exc)
+            if attachment is not None and await self._attachment_registry.is_current_attachment(
+                attachment.handle.session_id, attachment.generation
             ):
-                return {
-                    "action": "barge_in",
-                    "reason": ("server_vad_speech_started" if vad_speech_started is True else "barge_in_on_speech"),
-                    "cancel_reason": "turn_detected" if vad_speech_started is True else "barge_in",
-                    "duration_ms": duration_ms,
-                    "overlap_speech_ms": session.overlap_speech_ms,
-                    "buffer_audio": True,
-                }
-            return {
-                "action": "listen",
-                "reason": "auto_response_continuous",
-                "duration_ms": duration_ms,
-                "overlap_speech_ms": session.overlap_speech_ms,
-                "buffer_audio": True,
-                "defer_runtime_append": False,
-                "force_listen": event.get("force_listen") is True or payload.get("force_listen") is True,
-                "preserve_realtime_input": True,
-            }
-        if bool(event.get("force_listen", False)):
-            session.reset_overlap_speech()
-            return {
-                "action": "listen",
-                "reason": "client_force_listen",
-                "duration_ms": duration_ms,
-                "buffer_audio": is_speech,
-                "defer_runtime_append": True,
-            }
-
-        policy = session.config.overlap_policy
-        if not is_speech:
-            if session.overlap_speech_ms <= 0:
-                session.reset_overlap_speech()
-            return {
-                "action": "drop",
-                "reason": "silence_or_noise",
-                "duration_ms": duration_ms,
-                "overlap_speech_ms": session.overlap_speech_ms,
-                "buffer_audio": False,
-            }
-
-        if self._is_short_ack_transcript_hint(event, payload):
-            session.reset_overlap_speech()
-            return {
-                "action": "listen",
-                "reason": "short_ack_transcript",
-                "duration_ms": duration_ms,
-                "overlap_speech_ms": session.overlap_speech_ms,
-                "buffer_audio": False,
-                "defer_runtime_append": True,
-            }
-
-        if policy == DuplexOverlapPolicy.LISTEN_ONLY.value:
-            session.accumulate_overlap_speech(duration_ms)
-            return {
-                "action": "listen",
-                "reason": "policy_listen_only",
-                "duration_ms": duration_ms,
-                "overlap_speech_ms": session.overlap_speech_ms,
-                "buffer_audio": True,
-                "defer_runtime_append": True,
-            }
-
-        if policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value and not session.capabilities.supports_barge_in:
-            return self._defer_unsupported_barge_in(session, duration_ms=duration_ms, is_speech=True)
-
-        session.accumulate_overlap_speech(duration_ms)
-        if policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value:
-            vad_speech_started = self._vad_speech_started(event, payload)
-            if vad_speech_started is False:
-                return {
-                    "action": "listen",
-                    "reason": "server_vad_utterance_active",
-                    "duration_ms": duration_ms,
-                    "overlap_speech_ms": session.overlap_speech_ms,
-                    "buffer_audio": True,
-                    "defer_runtime_append": False,
-                    "force_listen": True,
-                    "preserve_realtime_input": True,
-                }
-            return {
-                "action": "barge_in",
-                "reason": ("server_vad_speech_started" if vad_speech_started is True else "policy_barge_in_on_speech"),
-                "cancel_reason": "turn_detected" if vad_speech_started is True else "barge_in",
-                "duration_ms": duration_ms,
-                "overlap_speech_ms": session.overlap_speech_ms,
-                "buffer_audio": True,
-            }
-
-        if (
-            duration_ms <= session.config.overlap_short_ack_ms
-            and session.overlap_speech_ms <= session.config.overlap_short_ack_ms
-        ):
-            return {
-                "action": "listen",
-                "reason": "short_ack",
-                "duration_ms": duration_ms,
-                "overlap_speech_ms": session.overlap_speech_ms,
-                "buffer_audio": True,
-                "defer_runtime_append": True,
-            }
-        if session.overlap_speech_ms >= session.config.overlap_barge_in_ms:
-            if not session.capabilities.supports_barge_in:
-                return {
-                    "action": "listen",
-                    "reason": "barge_in_unsupported",
-                    "duration_ms": duration_ms,
-                    "overlap_speech_ms": session.overlap_speech_ms,
-                    "buffer_audio": True,
-                    "defer_runtime_append": True,
-                }
-            return {
-                "action": "barge_in",
-                "reason": "long_overlap_speech",
-                "duration_ms": duration_ms,
-                "overlap_speech_ms": session.overlap_speech_ms,
-                "buffer_audio": True,
-            }
-        return {
-            "action": "listen",
-            "reason": "accumulating_overlap_speech",
-            "duration_ms": duration_ms,
-            "overlap_speech_ms": session.overlap_speech_ms,
-            "buffer_audio": True,
-            "defer_runtime_append": True,
-        }
-
-    @staticmethod
-    def _vad_speech_started(
-        event: Mapping[str, object],
-        payload: Mapping[str, object],
-    ) -> bool | None:
-        for source in (event, payload):
-            vad = source.get("vad")
-            if isinstance(vad, Mapping) and isinstance(vad.get("speech_started"), bool):
-                return bool(vad["speech_started"])
-        return None
-
-    @staticmethod
-    def _event_requests_barge_in(event: Mapping[str, object]) -> bool:
-        if event.get("force_barge_in") is True:
-            return True
-        explicit = event.get("overlap_action") or event.get("overlap")
-        return isinstance(explicit, str) and explicit.strip().lower() in {
-            "barge_in",
-            "interrupt",
-            "cancel",
-        }
-
-    @staticmethod
-    def _defer_unsupported_barge_in(
-        session: DuplexSession,
-        *,
-        duration_ms: int,
-        is_speech: bool,
-    ) -> dict[str, object]:
-        if is_speech:
-            session.accumulate_overlap_speech(duration_ms)
-        return {
-            "action": "listen",
-            "reason": "barge_in_unsupported",
-            "duration_ms": duration_ms,
-            "overlap_speech_ms": session.overlap_speech_ms,
-            "buffer_audio": is_speech,
-            "defer_runtime_append": True,
-        }
-
-    @staticmethod
-    def _barge_in_unsupported_error(session: DuplexSession) -> dict[str, object]:
-        return {
-            "type": "error",
-            "session_id": session.session_id,
-            "code": "barge_in_unsupported",
-            "error": "Barge-in is not supported by this duplex model",
-        }
-
-    @staticmethod
-    def _is_short_ack_transcript_hint(event: dict[str, object], payload: dict[str, object]) -> bool:
-        raw_text = event.get("transcript") or event.get("text") or payload.get("transcript") or payload.get("text")
-        if not isinstance(raw_text, str):
-            return False
-        normalized = raw_text.strip().lower()
-        if not normalized:
-            return False
-        compact = "".join(ch for ch in normalized if ch.isalnum() or "\u4e00" <= ch <= "\u9fff")
-        if compact in {
-            "嗯",
-            "嗯嗯",
-            "对",
-            "对的",
-            "好",
-            "好的",
-            "继续",
-            "继续说",
-            "可以",
-            "是的",
-            "yes",
-            "yeah",
-            "yep",
-            "ok",
-            "okay",
-            "continue",
-            "goon",
-            "right",
-        }:
-            return True
-        return normalized in {"go on", "keep going", "please continue"}
-
-    @staticmethod
-    def _input_audio_duration_ms(event: dict[str, object], payload: dict[str, object]) -> int:
-        for key in ("duration_ms", "audio_duration_ms"):
-            value = event.get(key)
-            if isinstance(value, int | float):
-                return max(0, int(value))
-        fmt = payload.get("format")
-        sample_rate_hz = payload.get("sample_rate_hz")
-        audio = payload.get("audio")
-        if fmt == "pcm_f32le" and isinstance(sample_rate_hz, int) and sample_rate_hz > 0 and isinstance(audio, str):
-            try:
-                raw = base64.b64decode(audio, validate=True)
-            except (binascii.Error, ValueError):
-                return 0
-            return int((len(raw) // 4) * 1000 / sample_rate_hz)
-        return 0
-
-    @staticmethod
-    def _merge_native_audio_payloads(
-        first: dict[str, object],
-        second: dict[str, object],
-    ) -> dict[str, object]:
-        if first.get("format") != "pcm_f32le" or second.get("format") != "pcm_f32le":
-            return second
-        first_rate = first.get("sample_rate_hz")
-        second_rate = second.get("sample_rate_hz")
-        if not isinstance(first_rate, int) or not isinstance(second_rate, int) or first_rate != second_rate:
-            return second
-        first_audio = first.get("audio")
-        second_audio = second.get("audio")
-        if not isinstance(first_audio, str) or not isinstance(second_audio, str):
-            return second
-        try:
-            first_raw = base64.b64decode(first_audio, validate=True)
-            second_raw = base64.b64decode(second_audio, validate=True)
-        except (binascii.Error, ValueError):
-            return second
-        merged = dict(second)
-        merged["audio"] = base64.b64encode(first_raw + second_raw).decode("ascii")
-        merged["sample_rate_hz"] = first_rate
-        merged_frames = [
-            frame
-            for source in (first.get("video_frames"), second.get("video_frames"))
-            if isinstance(source, list)
-            for frame in source
-            if isinstance(frame, str) and frame
-        ]
-        if merged_frames:
-            merged["video_frames"] = merged_frames
-        else:
-            merged.pop("video_frames", None)
-        merged["force_listen"] = bool(first.get("force_listen", False)) or bool(second.get("force_listen", False))
-        merged.pop("force_speak", None)
-        merged["is_speech"] = bool(first.get("is_speech", False)) or bool(second.get("is_speech", False))
-        return merged
-
-    @classmethod
-    def _should_force_listen_for_short_commit(
-        cls,
-        session: DuplexSession,
-        event: dict[str, object],
-        payload: dict[str, object],
-    ) -> bool:
-        """Keep very short committed Realtime chunks in listen mode.
-
-        Realtime VAD can emit a commit for a short pause even when the user has
-        not actually yielded the turn. For MiniCPM-o native duplex, make that
-        policy explicit by steering the scheduler path to the model listen
-        token instead of letting a sub-second chunk start a response.
-        """
-        if event.get("force_listen") is True or payload.get("force_listen") is True:
-            return True
-        if event.get("force_barge_in") is True:
-            return False
-        if event.get("response_create") is not True:
-            return False
-        duration_ms = cls._input_audio_duration_ms(event, payload)
-        return 0 < duration_ms <= session.config.overlap_short_ack_ms
-
-    def _create_runtime_session_state(self) -> ServingRuntimeSessionState:
-        adapter = self._serving_runtime_adapter
-        if adapter is not None:
-            return adapter.create_session_state()
-        return TurnBasedServingSessionState()
-
-    def _runtime_session_state(self, session: DuplexSession) -> ServingRuntimeSessionState:
-        adapter = self._serving_runtime_adapter
-        if adapter is not None:
-            return adapter.session_state(session.session_id)
-        state = self._serving_session_states.get(session.session_id)
-        if state is None:
-            state = TurnBasedServingSessionState()
-            self._serving_session_states[session.session_id] = state
-        return state
-
-    def _require_serving_runtime_adapter(self) -> ServingRuntimeAdapter:
-        adapter = self._serving_runtime_adapter
-        if adapter is None:
-            raise RuntimeError("Model-native duplex runtime is not configured for this session")
-        return adapter
-
-    def _should_force_listen_for_auto_response_overlap(
-        self,
-        session: DuplexSession,
-        event: dict[str, object],
-        payload: dict[str, object],
-    ) -> bool:
-        if not self._session_auto_responds(session):
-            return False
-        if event.get("force_barge_in") is True:
-            return False
-        return event.get("force_listen") is True or payload.get("force_listen") is True
-
-    @staticmethod
-    def _assistant_playback_active(session: DuplexSession) -> bool:
-        return (
-            session.config.playback_commit_policy == DuplexPlaybackCommitPolicy.ACK_ONLY.value
-            and session.playback.sent_ms > session.playback.committed_ms
-        )
-
-    @staticmethod
-    def _input_looks_like_speech(
-        event: dict[str, object],
-        payload: dict[str, object],
-        *,
-        session: DuplexSession,
-    ) -> bool:
-        # Prefer serving-derived fields in ``payload`` over optional client
-        # hints retained in ``event``. In server-VAD mode the pipeline, rather
-        # than the client or the RMS fallback below, owns speech classification.
-        for source in (payload, event):
-            for key in ("is_speech", "speech"):
-                value = source.get(key)
-                if isinstance(value, bool):
-                    return value
-            vad = source.get("vad")
-            if isinstance(vad, dict):
-                value = vad.get("is_speech")
-                if isinstance(value, bool):
-                    return value
-                probability = vad.get("speech_probability", vad.get("probability"))
-                if isinstance(probability, int | float):
-                    return float(probability) >= 0.5
-            probability = source.get("speech_probability")
-            if isinstance(probability, int | float):
-                return float(probability) >= 0.5
-
-        fmt = payload.get("format")
-        audio = payload.get("audio")
-        if fmt in {"pcm_f32le", "pcm16"} and isinstance(audio, str):
-            try:
-                raw = base64.b64decode(audio, validate=True)
-            except (binascii.Error, ValueError):
-                return True
-            if fmt == "pcm_f32le":
-                if len(raw) < 4 or len(raw) % 4 != 0:
-                    return True
-                samples = np.frombuffer(raw, dtype=np.float32)
-            else:
-                if len(raw) < 2 or len(raw) % 2 != 0:
-                    return True
-                samples = np.frombuffer(raw, dtype=np.int16).astype(np.float32) / 32768.0
-            if samples.size == 0:
-                return False
-            rms = float(np.sqrt(np.mean(np.square(samples.astype(np.float32)))))
-            return rms >= session.config.overlap_silence_rms
-        return True
-
-    async def _emit_overlap_decision(
-        self,
-        send_json,
-        session: DuplexSession,
-        decision: dict[str, object],
-    ) -> None:
-        await send_json(
-            {
-                "type": "overlap.decision",
-                "session_id": session.session_id,
-                "epoch": session.epoch,
-                "policy": session.config.overlap_policy,
-                **decision,
-            }
-        )
+                with suppress(Exception):
+                    await self._attachment_registry.close(attachment.handle.session_id)
+                with suppress(Exception):
+                    await attachment.handle.close(reason="transport_error")
+            with suppress(Exception):
+                await send_json(envelope.error_payload("realtime_input_failed", str(exc)))
 
-    async def _open_session(
-        self,
-        websocket: WebSocket,
-        send_json,
-        *,
-        realtime_protocol: NativeRealtimeSessionProtocol | None = None,
-        attachment_send=None,
-        attachment_close=None,
-    ) -> _DuplexSessionHandshake | None:
-        raw = await self._receive_text(
-            websocket,
-            self._config_timeout_s,
-            realtime_protocol=realtime_protocol,
-        )
+    async def _receive_first_message(
+        self, websocket: WebSocket, envelope: RealtimeEnvelope, send_json: SendJson
+    ) -> dict[str, object] | None:
+        raw = await receive_text_with_timeout(websocket, self._config_timeout_s)
         if raw is None:
-            await send_json({"type": "error", "error": "Timeout waiting for session.create", "code": "config_timeout"})
+            await send_json(envelope.error_payload("config_timeout", "Timeout waiting for session.update"))
             return None
         try:
-            event = json.loads(raw)
+            first = json.loads(raw)
         except json.JSONDecodeError:
-            await send_json({"type": "error", "error": "Invalid JSON in session.create", "code": "invalid_json"})
+            await send_json(envelope.error_payload("invalid_json", "Invalid JSON in session.update"))
             return None
-        if isinstance(event, dict) and event.get("type") == "session.resume":
-            if realtime_protocol is None:
-                await send_json(
-                    {
-                        "type": "error",
-                        "error": "session.resume requires the Realtime protocol",
-                        "code": "unsupported_session_resume",
-                    }
-                )
-                return None
-            return await self._resume_session_handshake(
-                event,
-                send_json=send_json,
-                realtime_protocol=realtime_protocol,
-                attachment_send=attachment_send,
-                attachment_close=attachment_close,
-            )
-        if not isinstance(event, dict) or event.get("type") not in {"session.create", "open_session", "session.config"}:
-            await send_json(
-                {
-                    "type": "error",
-                    "error": f"Expected session.create, got: {event.get('type') if isinstance(event, dict) else None}",
-                    "code": "bad_event",
-                }
-            )
+        if not isinstance(first, dict):
+            await send_json(envelope.error_payload("bad_event", "Realtime event must be a JSON object"))
             return None
+        return first
+
+    # ------------------------------------------------------------------ #
+    # Handshake                                                           #
+    # ------------------------------------------------------------------ #
 
+    async def _open(
+        self,
+        websocket: WebSocket,
+        envelope: RealtimeEnvelope,
+        session_payload: Mapping[str, object],
+        send_json: SendJson,
+    ) -> _Attachment | None:
+        # Any ``session_id`` / ``id`` in the payload is ignored: the server
+        # allocates the id and announces it in ``session.created``.
         try:
-            config = DuplexSessionConfig.from_event(event)
-        except ValueError as exc:
-            error: dict[str, object] = {
-                "type": "error",
-                "error": str(exc),
-                "code": "invalid_request_error",
-            }
-            event_id = event.get("_realtime_event_id")
-            if isinstance(event_id, str) and event_id:
-                error["event_id"] = event_id
-            await send_json(error)
+            handle = await self._omni.open_session(session_payload)
+        except DuplexSessionError as exc:
+            await send_json(envelope.error_payload(exc.code, str(exc)))
             return None
-        if config.idle_timeout_s == _DEFAULT_IDLE_TIMEOUT_S:
-            config.idle_timeout_s = self._idle_timeout_s
-        runtime_adapter = self._serving_runtime_adapter if self._uses_serving_runtime_adapter(config) else None
-        runtime_config: dict[str, object] = {}
-        if runtime_adapter is not None:
-            try:
-                runtime_config = await runtime_adapter.prepare_runtime_config(
-                    config,
-                    model_config=getattr(self._chat_service, "model_config", None),
-                )
-            except ServingRuntimeConfigError as exc:
-                await send_json({"type": "error", "error": str(exc), "code": exc.code})
-                return None
-            except ValueError as exc:
-                await send_json({"type": "error", "error": str(exc), "code": "unsupported_ref_audio_path"})
-                return None
-        session_id = event.get("session_id") if isinstance(event.get("session_id"), str) else None
-        session = self._registry.create(config=config, session_id=session_id)
-        if runtime_adapter is not None:
-            session.replace_capabilities(
-                runtime_adapter.capabilities(max_sessions=self._duplex_session_config.max_sessions)
-            )
-            session.replace_runtime_config(runtime_config)
-        session_payload = event.get("session")
-        self._resolve_server_vad_defaults(
-            session, config, session_payload if isinstance(session_payload, dict) else event
-        )
-        event_id = event.get("_realtime_event_id")
-        return _DuplexSessionHandshake(
-            session=session,
-            event_id=event_id if isinstance(event_id, str) and event_id else None,
+        except (TypeError, ValueError) as exc:
+            await send_json(envelope.error_payload("invalid_session_config", str(exc)))
+            return None
+        attachment_send, attachment_close = attachment_callbacks(websocket)
+        created = await self._attachment_registry.create(
+            handle.session_id,
+            send=attachment_send,
+            close=attachment_close,
         )
-
-    async def _resume_session_handshake(
+        resume_supported = bool(handle.capabilities.supports_session_resume)
+        attachment = _Attachment(handle=handle, generation=created.attachment_generation)
+        credentials: _ResumeCredentials | None = None
+        if resume_supported:
+            credentials = _ResumeCredentials(
+                attachment_generation=created.attachment_generation,
+                resume_token=created.resume_token.plaintext,
+            )
+        self._start_pump(handle, credentials)
+        return attachment
+
+    async def _resume(
         self,
-        event: dict[str, object],
-        *,
-        send_json,
-        realtime_protocol: NativeRealtimeSessionProtocol,
-        attachment_send,
-        attachment_close,
-    ) -> _DuplexSessionHandshake | None:
-        session_id = event.get("session_id")
-        incarnation = event.get("incarnation")
-        resume_token = event.get("resume_token")
-        last_received = event.get("last_received_server_event_seq", 0)
-        if (
-            not isinstance(session_id, str)
-            or not session_id
-            or not isinstance(incarnation, int)
-            or incarnation < 0
-            or not isinstance(resume_token, str)
-            or not resume_token
-            or not isinstance(last_received, int)
-            or last_received < 0
-        ):
+        websocket: WebSocket,
+        envelope: RealtimeEnvelope,
+        event: Mapping[str, object],
+        send_json: SendJson,
+    ) -> _Attachment | None:
+        request = parse_resume_request(event)
+        if request is None:
             await send_json(
-                {
-                    "type": "error",
-                    "error": (
-                        "session.resume requires session_id, incarnation, resume_token, "
-                        "and a non-negative event sequence"
-                    ),
-                    "code": "invalid_session_resume",
-                }
+                envelope.error_payload(
+                    "invalid_session_resume",
+                    "session.resume requires session_id, resume_token, and a non-negative event sequence",
+                )
             )
             return None
-        session = self._registry.get(session_id)
-        if session is None or session.state != DuplexSessionState.OPEN:
+        session_id = request.session_id
+        handle = self._omni.get_session(session_id)
+        if handle is None or handle.closed:
             await send_json(
-                {
-                    "type": "error",
-                    "error": f"Unknown or expired duplex session: {session_id}",
-                    "code": "session_resume_expired",
-                }
+                envelope.error_payload("session_resume_expired", f"Unknown or expired duplex session: {session_id}")
             )
             return None
-        if not session.capabilities.supports_session_resume:
+        if not handle.capabilities.supports_session_resume:
             await send_json(
-                {
-                    "type": "error",
-                    "error": f"Session does not support resume: {session_id}",
-                    "code": "unsupported_session_resume",
-                }
+                envelope.error_payload("unsupported_session_resume", f"Session does not support resume: {session_id}")
             )
             return None
         try:
             await self._attachment_registry.authenticate_resume(
                 session_id,
-                incarnation=incarnation,
-                resume_token=resume_token,
-                last_received_server_event_seq=last_received,
+                resume_token=request.resume_token,
+                last_received_server_event_seq=request.last_received_server_event_seq,
             )
         except InvalidResumeTokenError:
-            await send_json(
-                {
-                    "type": "error",
-                    "error": "Invalid duplex session resume token",
-                    "code": "invalid_resume_token",
-                }
-            )
+            await send_json(envelope.error_payload("invalid_resume_token", "Invalid duplex session resume token"))
             return None
         except DuplexJournalGapError:
-            await send_json(
-                {
-                    "type": "session.resync_required",
-                    "session_id": session_id,
-                    "reason": "journal_gap",
-                }
-            )
+            await send_json(SessionResyncRequired(session_id=session_id, reason="journal_gap").to_realtime())
             return None
         except (KeyError, ValueError) as exc:
-            await send_json(
-                {
-                    "type": "error",
-                    "error": str(exc),
-                    "code": "session_resume_conflict",
-                }
-            )
+            await send_json(envelope.error_payload("session_resume_conflict", str(exc)))
             return None
-
-        resume_runtime = getattr(self._chat_service.engine_client, "resume_duplex_session_async", None)
-        if not callable(resume_runtime):
-            await send_json(
-                {
-                    "type": "error",
-                    "error": "Duplex runtime does not expose session resume control",
-                    "code": "runtime_resume_unsupported",
-                }
-            )
-            return None
-        expected_generation = self._lease_generations.get(session_id, 0)
         try:
-            runtime_result = await resume_runtime(
+            await self._omni.resume_session(
                 session_id,
-                fence=DuplexFence(
-                    session.session_id,
-                    epoch=session.epoch,
-                    turn_id=session.turn_id,
-                    incarnation=session.incarnation,
-                ),
-                expected_lease_generation=expected_generation,
-            )
-            lease_generation = self._runtime_lease_generation(runtime_result)
-            if lease_generation is None:
-                raise RuntimeError("runtime resume result omitted lease_generation")
-        except Exception as exc:
-            await send_json(
-                {
-                    "type": "error",
-                    "error": str(exc),
-                    "code": "runtime_resume_failed",
-                }
+                expected_lease_generation=handle.lease_generation,
             )
+        except DuplexSessionError as exc:
+            await send_json(envelope.error_payload("runtime_resume_failed", str(exc)))
             return None
 
-        if not callable(attachment_send) or not callable(attachment_close):
-            raise RuntimeError("session.resume requires transport attachment callbacks")
+        attachment_send, attachment_close = attachment_callbacks(websocket)
 
-        def activation_payload_factory(token, generation: int) -> dict[str, object]:
-            internal = {
-                "type": "session.resumed",
-                "session_id": session_id,
-                "incarnation": incarnation,
-                "attachment_generation": generation,
-                "resume_token": token.plaintext,
-            }
-            return realtime_protocol.encode_outbound_event(internal)[0]
+        def activation_payload_factory(token: ResumeToken, generation: int) -> dict[str, object]:
+            return SessionResumed(
+                session_id=session_id,
+                session=dict(handle.public_session),
+                attachment_generation=generation,
+                resume_token=token.plaintext,
+            ).to_realtime()
 
         try:
             resumed = await self._attachment_registry.resume(
                 session_id,
-                incarnation=incarnation,
-                resume_token=resume_token,
-                last_received_server_event_seq=last_received,
+                resume_token=request.resume_token,
+                last_received_server_event_seq=request.last_received_server_event_seq,
                 send=attachment_send,
                 close=attachment_close,
                 activation_payload_factory=activation_payload_factory,
             )
         except Exception as exc:
-            # The engine-side CAS already advanced even if the transport
-            # vanished before it received the rotated token. Keep that
-            # generation so the registry's one-shot recovery token can retry.
-            self._lease_generations[session_id] = lease_generation
-            await send_json(
-                {
-                    "type": "error",
-                    "error": str(exc),
-                    "code": "session_resume_conflict",
-                }
-            )
+            # The engine lease was already resumed above, so a failed activation
+            # would leave the session attached to nothing -- unless another
+            # connection won the race and is attached right now. Detaching then
+            # would start the disconnect grace for the *winner*, which ordinary
+            # heartbeats do not clear. Roll back only what this attempt owns.
+            if not await self._attachment_registry.has_attachment(session_id):
+                with suppress(DuplexSessionError):
+                    await self._omni.detach_session(session_id)
+            await send_json(envelope.error_payload("session_resume_conflict", str(exc)))
             return None
-        self._lease_generations[session_id] = lease_generation
         replaced = resumed.replaced_attachment
         if replaced is not None:
-            replaced_payload = realtime_protocol.encode_outbound_event(
-                {
-                    "type": "session.replaced",
-                    "session_id": session_id,
-                    "attachment_generation": replaced.generation,
-                }
-            )[0]
             with suppress(Exception):
-                await replaced.send(replaced_payload)
+                await replaced.send(
+                    SessionReplaced(session_id=session_id, attachment_generation=replaced.generation).to_realtime()
+                )
             with suppress(Exception):
                 await replaced.close("session_replaced")
-        return _DuplexSessionHandshake(
-            session=session,
-            resumed=True,
-            attachment_generation=resumed.attachment_generation,
+        # A reconnect brings a fresh envelope carrying pcm16/16 kHz wire
+        # defaults. The negotiated input format is a wire default, not part of
+        # the public session object, so it has to be carried over explicitly:
+        # otherwise the first append that omits format/rate is decoded as pcm16.
+        remembered = self._input_defaults.get(session_id)
+        if remembered is not None:
+            envelope.defaults = remembered
+        self._start_pump(handle, None)
+        return _Attachment(handle=handle, generation=resumed.attachment_generation)
+
+    # ------------------------------------------------------------------ #
+    # Outbound pump (session-scoped, survives reconnects)                #
+    # ------------------------------------------------------------------ #
+
+    def _start_pump(self, handle: DuplexSessionHandle, credentials: _ResumeCredentials | None) -> None:
+        existing = self._pumps.get(handle.session_id)
+        if existing is not None and not existing.done():
+            return
+        self._pumps[handle.session_id] = asyncio.create_task(
+            self._pump_events(handle, credentials),
+            name=f"duplex-session-pump-{handle.session_id}",
         )
 
-    @classmethod
-    def _runtime_lease_generation(cls, result: object) -> int | None:
-        if isinstance(result, dict):
-            generation = result.get("lease_generation")
-            if isinstance(generation, int):
-                return generation
-            for key in ("stage_results", "result"):
-                generation = cls._runtime_lease_generation(result.get(key))
-                if generation is not None:
-                    return generation
-            return None
-        if isinstance(result, list | tuple):
-            for item in result:
-                generation = cls._runtime_lease_generation(item)
-                if generation is not None:
-                    return generation
-        return None
-
-    def _uses_serving_runtime_adapter(self, config: DuplexSessionConfig) -> bool:
-        adapter = self._serving_runtime_adapter
-        return adapter is not None and adapter.is_enabled(config)
-
-    def _runtime_session_update_error(
-        self,
-        session: DuplexSession,
-        payload: dict[str, object],
-    ) -> dict[str, object] | None:
-        if not self._uses_native_input_append(session):
-            return None
+    async def _pump_events(self, handle: DuplexSessionHandle, credentials: _ResumeCredentials | None) -> None:
+        session_id = handle.session_id
+        close_reason = "session_closed"
         try:
-            self._require_serving_runtime_adapter().validate_client_extra_body(payload.get("extra_body"))
-        except ServingRuntimeConfigError as exc:
-            return {
-                "type": "error",
-                "session_id": session.session_id,
-                "code": exc.code,
-                "error": str(exc),
-            }
-        return None
-
-    def _runtime_config_for_session_update(
-        self,
-        session: DuplexSession,
-        candidate_config: DuplexSessionConfig,
-    ) -> dict[str, object]:
-        if not self._uses_native_input_append(session):
-            return dict(session.runtime_config)
-        return self._require_serving_runtime_adapter().runtime_config_for_update(
-            candidate_config,
-            dict(session.runtime_config),
-        )
-
-    def _resolve_server_vad_defaults(
-        self,
-        session: DuplexSession,
-        config: DuplexSessionConfig,
-        payload: dict[str, object],
-    ) -> None:
-        """Resolve omitted options without overriding explicit client policies."""
-        if config.server_vad is None:
+            async for event in handle.events():
+                if isinstance(event, SessionCreated) and credentials is not None:
+                    event = replace(
+                        event,
+                        attachment_generation=credentials.attachment_generation,
+                        resume_token=credentials.resume_token,
+                    )
+                await self._send_event(session_id, event)
+                if isinstance(event, SessionClosed):
+                    close_reason = event.reason or event.type
+                    break
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.exception("Duplex event pump failed for %s: %s", session_id, exc)
+        finally:
+            self._pumps.pop(session_id, None)
+            self._resync_required_sessions.discard(session_id)
+            self._input_defaults.pop(session_id, None)
+            attachment = None
+            with suppress(Exception):
+                attachment = await self._attachment_registry.close(session_id)
+            if attachment is not None:
+                with suppress(Exception):
+                    await attachment.close(close_reason)
+
+    async def _drain_terminal_pump(self, attachment: _Attachment) -> None:
+        """Let the pump deliver ``session.closed`` before the endpoint returns.
+
+        ``DuplexSessionHandle._deliver`` queues ``SessionClosed`` on the outbox
+        and marks the handle closed in the same synchronous step, so
+        ``handle.closed`` is already true while that event is still sitting in
+        the queue. ``_read_loop`` stops on exactly that flag: if the engine
+        closes the session between two reads, the loop returns, this endpoint
+        returns, and the ASGI server tears the socket down with the terminal
+        event unsent -- the client sees an abrupt close instead of
+        ``session.closed``. Waiting for the pump keeps the two in order; it is
+        the pump that sends the event and then closes with code 1000.
+
+        Only for a closed session. A takeover or a resumable disconnect leaves
+        the pump running for the next attachment, and must not be waited on.
+        """
+        if not attachment.handle.closed:
             return
-        if config.server_vad.interrupt_response is None:
-            config.server_vad = replace(config.server_vad, interrupt_response=self._uses_native_input_append(session))
-        extra = payload.get("extra_body")
-        overlap_policy = extra.get("overlap_policy") if isinstance(extra, dict) else None
-        if not isinstance(overlap_policy, str):
-            overlap_policy = payload.get("overlap_policy")
-        config.overlap_policy = (
-            overlap_policy
-            if isinstance(overlap_policy, str)
-            else "barge_in_on_speech"
-            if config.server_vad.interrupt_response
-            else "listen_only"
-        )
-
-    def _runtime_session_candidate_update_error(
-        self,
-        session: DuplexSession,
-        candidate_config: DuplexSessionConfig,
-        *,
-        realtime_protocol: NativeRealtimeSessionProtocol | None = None,
-    ) -> dict[str, object] | None:
-        if candidate_config.server_vad is not None:
-            desired_policy = "barge_in_on_speech" if candidate_config.server_vad.interrupt_response else "listen_only"
-            if candidate_config.overlap_policy != desired_policy:
-                return {
-                    "type": "error",
-                    "code": "unsupported_turn_detection",
-                    "error": f"overlap_policy conflicts with turn_detection; expected {desired_policy!r}",
-                    "param": "overlap_policy",
-                }
-        if not self._uses_native_input_append(session):
-            if (
-                candidate_config.server_vad is not None
-                and candidate_config.server_vad.min_speech_duration_ms is not None
-            ):
-                return {
-                    "type": "error",
-                    "code": "unsupported_turn_detection",
-                    "error": "server_vad.min_speech_duration_ms is only supported by model-native duplex runtimes",
-                }
-            requests_interruption = (
-                candidate_config.server_vad is not None and candidate_config.server_vad.interrupt_response
-            ) or candidate_config.overlap_policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value
-            if requests_interruption:
-                return {
-                    "type": "error",
-                    "code": "server_vad_requires_native_duplex",
-                    "error": (
-                        "Realtime server_vad interruption requires a model-native duplex runtime; "
-                        "set interrupt_response=false for turn-based models"
-                    ),
-                }
-            if candidate_config.server_vad is not None and realtime_protocol is not None:
-                session_payload = candidate_config.extra_body.get("realtime_session_payload")
-                audio_error = realtime_protocol.validate_server_vad_input_audio(
-                    session_payload if isinstance(session_payload, dict) else {}
-                )
-                if audio_error is not None:
-                    return {
-                        "type": "error",
-                        "code": "unsupported_turn_detection",
-                        "error": audio_error,
-                        "param": "audio.input.format",
-                    }
-            return None
-        if candidate_config.server_vad is not None:
-            if not candidate_config.server_vad.interrupt_response:
-                return {
-                    "type": "error",
-                    "session_id": session.session_id,
-                    "code": "unsupported_turn_detection",
-                    "error": "Model-native duplex server_vad requires interrupt_response=true",
-                }
-            if candidate_config.server_vad.threshold <= SILERO_VAD_MIN_THRESHOLD:
-                return {
-                    "type": "error",
-                    "session_id": session.session_id,
-                    "code": "unsupported_turn_detection",
-                    "error": (
-                        f"Model-native duplex server_vad.threshold must be greater than {SILERO_VAD_MIN_THRESHOLD}"
-                    ),
-                }
-            if not candidate_config.server_vad.create_response:
-                return {
-                    "type": "error",
-                    "session_id": session.session_id,
-                    "code": "unsupported_turn_detection",
-                    "error": "Model-native duplex server_vad requires create_response=true",
-                }
-        if (
-            candidate_config.instructions != session.config.instructions
-            and self._runtime_session_state(session).native_context_locked
-        ):
-            return {
-                "type": "error",
-                "session_id": session.session_id,
-                "code": "instructions_update_unsupported",
-                "error": "session.update cannot change instructions after the native duplex context is initialized",
-            }
-        if native_duplex_opt_in(session.config.extra_body) is not True:
-            return None
-        if not self._config_requests_audio_output(candidate_config):
-            return None
-        if "ref_audio_data" in session.runtime_config:
-            return None
-        return {
-            "type": "error",
-            "session_id": session.session_id,
-            "code": "ref_audio_required",
-            "error": "MiniCPM-o native duplex audio output requires ref_audio",
-        }
-
-    @staticmethod
-    def _uses_native_input_append(session: DuplexSession) -> bool:
-        return (
-            session.capabilities.implementation_level == "model_native_duplex"
-            and session.capabilities.supports_input_append
-            and native_duplex_opt_in(session.config.extra_body) is not False
-        )
-
-    @staticmethod
-    def _config_requests_audio_output(config: DuplexSessionConfig) -> bool:
-        return any(str(modality).lower() == "audio" for modality in config.modalities)
-
-    @staticmethod
-    def _native_stage0_request_id(session: DuplexSession, epoch: int) -> str:
-        return duplex_resource_request_id(
-            DuplexFence(
-                session.session_id,
-                epoch=epoch,
-                incarnation=session.incarnation,
-            ),
-            "stage0",
-        )
-
-    @staticmethod
-    def _session_auto_responds(session: DuplexSession) -> bool:
-        """Full-duplex / model-driven mode.
+        pump = self._pumps.get(attachment.handle.session_id)
+        if pump is None or pump.done():
+            return
+        # shield: a drain timeout must not cancel a pump that is still the
+        # session's only writer.
+        with suppress(Exception):
+            await asyncio.wait_for(asyncio.shield(pump), _PUMP_DRAIN_TIMEOUT_S)
 
-        When set, the server runs per-chunk speak-generation continuously (like
-        the official MiniCPM-o ``duplex_generate`` loop) instead of waiting for an
-        explicit ``response.create``: each ~chunk_period of appended audio is
-        emitted and fed to the stage0 stream so the model itself decides to speak
-        or listen. Signaled by the client via ``extra_body.auto_response`` (or
-        ``extra_body.full_duplex``).
+    async def _send_event(self, session_id: str, event: DuplexEvent) -> None:
+        payload = event.to_realtime()
+        journal = not isinstance(event, _UNJOURNALED_EVENTS) and session_id not in self._resync_required_sessions
+        try:
+            try:
+                await self._attachment_registry.send_event(session_id, payload, journal=journal)
+            except DuplexJournalOverflowError:
+                first_overflow = session_id not in self._resync_required_sessions
+                self._resync_required_sessions.add(session_id)
+                if first_overflow:
+                    resync = SessionResyncRequired(session_id=session_id, reason="journal_overflow")
+                    await self._attachment_registry.send_event(session_id, resync.to_realtime(), journal=False)
+                await self._attachment_registry.send_event(session_id, payload, journal=False)
+        except KeyError:
+            # Attachment already closed (takeover or teardown); the journal is gone.
+            pass
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            # The socket died mid-send. The session is alive in the engine:
+            # treat it as a disconnect of the current attachment (the pump
+            # keeps journaling for a resume) instead of tearing the session down.
+            logger.info("Duplex transport send failed for %s: %s", session_id, exc)
+            await self._detach_current_attachment(session_id)
+
+    async def _detach_current_attachment(self, session_id: str) -> None:
+        """Disconnect semantics for the socket currently attached to ``session_id``.
+
+        The pump is session-scoped and outlives any one connection, so it can
+        only name the session: the registry detaches whichever socket is
+        attached, which is the one whose send just failed.
         """
-        extra = getattr(session.config, "extra_body", None)
-        if not isinstance(extra, dict):
-            return False
-        return extra.get("auto_response") is True or extra.get("full_duplex") is True
+        handle = self._omni.get_session(session_id)
+        if handle is None or handle.closed:
+            return
+        if handle.capabilities.supports_session_resume:
+            if await self._attachment_registry.detach(session_id, attachment_generation=None):
+                with suppress(DuplexSessionError):
+                    await self._omni.detach_session(session_id)
+            return
+        with suppress(DuplexSessionError):
+            await handle.close(reason="disconnect")
 
-    async def _receive_text(
+    # ------------------------------------------------------------------ #
+    # Inbound                                                             #
+    # ------------------------------------------------------------------ #
+
+    async def _read_loop(
         self,
         websocket: WebSocket,
-        timeout_s: float,
-        *,
-        realtime_protocol: NativeRealtimeSessionProtocol | None = None,
-    ) -> str | None:
-        try:
-            if realtime_protocol is not None:
-                return await asyncio.wait_for(
-                    realtime_protocol.receive_internal_event_text(websocket),
-                    timeout=max(0.1, timeout_s),
-                )
-            return await asyncio.wait_for(websocket.receive_text(), timeout=max(0.1, timeout_s))
-        except asyncio.TimeoutError:
-            return None
-
-    @staticmethod
-    def _input_committed_payload(
-        session: DuplexSession,
-        committed: DuplexCommittedInput,
-        *,
-        item_id: object | None = None,
-    ) -> dict[str, object]:
-        payload: dict[str, object] = {
-            "type": "input.committed",
-            "session_id": session.session_id,
-            "turn_id": committed.turn_id,
-            "epoch": committed.epoch,
-            "history_len": len(session.history),
-            "message": committed.message,
-        }
-        if isinstance(item_id, str) and item_id:
-            payload["item_id"] = item_id
-        return payload
-
-    @staticmethod
-    def _commit_native_audio_input(
-        session: DuplexSession,
-        *,
-        item_id: object | None = None,
-        transcript: object | None = None,
-        turn_id: int | None = None,
-    ) -> DuplexCommittedInput:
-        clean_transcript = transcript.strip() if isinstance(transcript, str) else None
-        committed = session.commit_native_audio_input(
-            transcript=clean_transcript or None,
-            turn_id=turn_id,
-        )
-        if isinstance(item_id, str) and item_id:
-            session.register_history_item(item_id, committed.message)
-        return committed
-
-    @staticmethod
-    def _native_audio_committed_payload(
-        session: DuplexSession,
-        *,
-        committed: DuplexCommittedInput | None = None,
-        item_id: object | None = None,
-        transcript: object | None = None,
-    ) -> dict[str, object]:
-        message = committed.message if committed is not None else None
-        if not isinstance(message, dict):
-            input_audio_part: dict[str, object] = {
-                "type": "audio_url",
-                "audio_url": {"url": "native-duplex:input-audio"},
-            }
-            if isinstance(transcript, str) and transcript:
-                input_audio_part["transcript"] = transcript
-            message = {
-                "role": "user",
-                "content": [input_audio_part],
-            }
-        payload: dict[str, object] = {
-            "type": "input.committed",
-            "session_id": session.session_id,
-            "turn_id": committed.turn_id if committed is not None else session.turn_id,
-            "epoch": committed.epoch if committed is not None else session.epoch,
-            "history_len": len(session.history),
-            "native_audio": True,
-            "message": message,
-        }
-        if isinstance(transcript, str) and transcript:
-            payload["transcript"] = transcript
-        if isinstance(item_id, str) and item_id:
-            payload["item_id"] = item_id
-        return payload
+        envelope: RealtimeEnvelope,
+        attachment: _Attachment,
+        send_json: SendJson,
+    ) -> None:
+        handle = attachment.handle
+        idle_timeout_s = self._idle_timeout_s
+        config_timeout = handle.public_session.get("idle_timeout_s") if handle.public_session else None
+        if isinstance(config_timeout, int | float) and config_timeout > 0:
+            idle_timeout_s = float(config_timeout)
+        while not handle.closed:
+            raw = await receive_text_with_timeout(websocket, idle_timeout_s)
+            if not await self._attachment_registry.is_current_attachment(handle.session_id, attachment.generation):
+                # A newer connection took the session over; this socket is done.
+                return
+            if raw is None:
+                # Nothing from this socket for the idle window: same as a
+                # disconnect (engine grace for resumable sessions); the engine
+                # lease decides whether the session itself expires.
+                await self._on_disconnect(attachment)
+                return
+            if len(raw.encode("utf-8")) > MAX_EVENT_BYTES:
+                await send_json(envelope.error_payload("event_too_large", "Duplex event too large"))
+                continue
+            try:
+                payload = json.loads(raw)
+            except json.JSONDecodeError:
+                await send_json(envelope.error_payload("invalid_json", "Invalid JSON event"))
+                continue
+            if not isinstance(payload, dict) or not isinstance(payload.get("type"), str):
+                await send_json(envelope.error_payload("bad_event", "Duplex event must be a JSON object with a type"))
+                continue
+            if envelope.is_envelope_event(payload):
+                await self._handle_envelope_event(attachment, envelope, payload, send_json)
+                continue
+            await self._submit_wire_event(attachment, envelope, payload, send_json)
 
-    def _apply_session_update(
+    async def _handle_envelope_event(
         self,
-        session: DuplexSession,
+        attachment: _Attachment,
+        envelope: RealtimeEnvelope,
         payload: dict[str, object],
-    ) -> dict[str, object] | None:
-        model = payload.get("model")
-        audio_config = payload.get("audio")
-        audio_input = audio_config.get("input") if isinstance(audio_config, dict) else None
-        audio_output = audio_config.get("output") if isinstance(audio_config, dict) else None
-        voice = payload.get("voice")
-        if not isinstance(voice, str) and isinstance(audio_output, dict):
-            voice = audio_output.get("voice")
-        if isinstance(model, str) and session.config.model is not None and model != session.config.model:
-            return {
-                "type": "error",
-                "session_id": session.session_id,
-                "code": "model_update_unsupported",
-                "error": "session.update cannot change model for an open realtime duplex session",
-            }
-        if isinstance(model, str) and session.config.model is None:
-            session.config.model = model
-        if isinstance(voice, str) and (session.playback.generated_ms > 0 or session.playback.sent_ms > 0):
-            return {
-                "type": "error",
-                "session_id": session.session_id,
-                "code": "voice_update_after_audio_unsupported",
-                "error": "session.update cannot change voice after audio output has started",
-            }
-        if isinstance(payload.get("ref_audio"), str):
-            return {
-                "type": "error",
-                "session_id": session.session_id,
-                "code": "ref_audio_update_unsupported",
-                "error": "session.update cannot change ref_audio after the native duplex runtime is open",
-            }
-        extra_body_payload = payload.get("extra_body")
-        if isinstance(extra_body_payload, dict):
-            # Fold the deprecated model-prefixed alias into the canonical
-            # native_duplex key before comparing or merging.
-            extra_body_payload = normalize_native_duplex_key(dict(extra_body_payload))
-            payload = {**payload, "extra_body": extra_body_payload}
-        if isinstance(extra_body_payload, dict) and NATIVE_DUPLEX_KEY in extra_body_payload:
-            requested_native_duplex = extra_body_payload[NATIVE_DUPLEX_KEY]
-            if not isinstance(requested_native_duplex, bool):
-                return {
-                    "type": "error",
-                    "session_id": session.session_id,
-                    "code": "invalid_request_error",
-                    "error": "extra_body.native_duplex must be a boolean",
-                }
-            current_native_duplex = native_duplex_opt_in(session.config.extra_body)
-            if current_native_duplex is not None and extra_body_payload[NATIVE_DUPLEX_KEY] != current_native_duplex:
-                return {
-                    "type": "error",
-                    "session_id": session.session_id,
-                    "code": "native_duplex_mode_update_unsupported",
-                    "error": "session.update cannot change native_duplex after the session is created",
-                }
-        if isinstance(payload.get("instructions"), str):
-            session.config.instructions = str(payload["instructions"])
-        elif "instructions" in payload and payload.get("instructions") is None:
-            session.config.instructions = None
-        if isinstance(voice, str):
-            session.config.voice = str(voice)
-        elif "voice" in payload and payload.get("voice") is None:
-            session.config.voice = None
-        response_format = payload.get("output_audio_format") or payload.get("response_format")
-        if response_format is None and isinstance(audio_config, dict):
-            if isinstance(audio_output, dict):
-                response_format = audio_output.get("format")
-        response_format, _ = NativeRealtimeSessionProtocol._parse_realtime_audio_format(response_format)
-        if isinstance(response_format, str) and response_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
-            session.config.response_format = NativeRealtimeSessionProtocol._duplex_response_format(response_format)
-        if isinstance(payload.get("temperature"), int | float):
-            session.config.temperature = float(payload["temperature"])
-        speed = payload.get("speed")
-        if not isinstance(speed, int | float) and isinstance(audio_output, dict):
-            speed = audio_output.get("speed")
-        if isinstance(speed, int | float):
-            session.config.speed = float(speed)
-        max_tokens = (
-            payload.get("max_response_output_tokens")
-            if "max_response_output_tokens" in payload
-            else payload.get("max_output_tokens")
-            if "max_output_tokens" in payload
-            else payload.get("max_tokens")
-        )
-        if "max_response_output_tokens" in payload or "max_output_tokens" in payload or "max_tokens" in payload:
-            session.config.max_tokens = NativeRealtimeSessionProtocol.realtime_max_output_tokens(max_tokens)
-        if isinstance(payload.get("overlap_policy"), str):
-            session.config.overlap_policy = DuplexSessionConfig._normalize_overlap_policy(
-                str(payload["overlap_policy"])
-            )
-        if isinstance(payload.get("overlap_short_ack_ms"), int | float):
-            session.config.overlap_short_ack_ms = max(0, int(payload["overlap_short_ack_ms"]))
-        if isinstance(payload.get("overlap_barge_in_ms"), int | float):
-            session.config.overlap_barge_in_ms = max(0, int(payload["overlap_barge_in_ms"]))
-        if isinstance(payload.get("overlap_silence_rms"), int | float):
-            session.config.overlap_silence_rms = max(0.0, float(payload["overlap_silence_rms"]))
-        if isinstance(payload.get("playback_commit_policy"), str):
-            session.config.playback_commit_policy = DuplexSessionConfig._normalize_playback_commit_policy(
-                str(payload["playback_commit_policy"])
-            )
-        modalities = payload.get("modalities") or payload.get("output_modalities")
-        if isinstance(modalities, list) and all(isinstance(item, str) for item in modalities):
-            session.config.modalities = list(modalities)
-        if isinstance(payload.get("extra_body"), dict):
-            session.config.extra_body.update(payload["extra_body"])
-            extra = payload["extra_body"]
-            if isinstance(extra.get("overlap_policy"), str):
-                session.config.overlap_policy = DuplexSessionConfig._normalize_overlap_policy(
-                    str(extra["overlap_policy"])
-                )
-            if isinstance(extra.get("playback_commit_policy"), str):
-                session.config.playback_commit_policy = DuplexSessionConfig._normalize_playback_commit_policy(
-                    str(extra["playback_commit_policy"])
-                )
-        if isinstance(payload.get("tools"), list):
-            session.config.extra_body["realtime_tools"] = payload["tools"]
-        elif "tools" in payload and payload.get("tools") is None:
-            session.config.extra_body.pop("realtime_tools", None)
-        if isinstance(payload.get("tool_choice"), str | dict):
-            session.config.extra_body["realtime_tool_choice"] = payload["tool_choice"]
-        elif "tool_choice" in payload and payload.get("tool_choice") is None:
-            session.config.extra_body.pop("realtime_tool_choice", None)
-        if isinstance(payload.get("metadata"), dict):
-            session.config.extra_body["realtime_metadata"] = dict(payload["metadata"])
-        elif "metadata" in payload and payload.get("metadata") is None:
-            session.config.extra_body.pop("realtime_metadata", None)
-        if isinstance(payload.get("include"), list):
-            session.config.extra_body["realtime_include"] = list(payload["include"])
-        elif "include" in payload and payload.get("include") is None:
-            session.config.extra_body.pop("realtime_include", None)
-        if isinstance(payload.get("prompt"), dict):
-            session.config.extra_body["realtime_prompt"] = dict(payload["prompt"])
-        elif "prompt" in payload and payload.get("prompt") is None:
-            session.config.extra_body.pop("realtime_prompt", None)
-        input_audio_transcription = NativeRealtimeSessionProtocol._input_audio_transcription_config(payload)
-        if isinstance(input_audio_transcription, dict):
-            session.config.extra_body["realtime_input_audio_transcription"] = dict(input_audio_transcription)
-        elif "input_audio_transcription" in payload and payload.get("input_audio_transcription") is None:
-            session.config.extra_body.pop("realtime_input_audio_transcription", None)
-        if isinstance(payload.get("input_audio_noise_reduction"), dict):
-            session.config.extra_body["realtime_input_audio_noise_reduction"] = dict(
-                payload["input_audio_noise_reduction"]
-            )
-        elif "input_audio_noise_reduction" in payload and payload.get("input_audio_noise_reduction") is None:
-            session.config.extra_body.pop("realtime_input_audio_noise_reduction", None)
-        if isinstance(audio_input, dict) and isinstance(audio_input.get("noise_reduction"), dict):
-            session.config.extra_body["realtime_input_audio_noise_reduction"] = dict(audio_input["noise_reduction"])
-        elif isinstance(audio_input, dict) and audio_input.get("noise_reduction") is None:
-            session.config.extra_body.pop("realtime_input_audio_noise_reduction", None)
-        if isinstance(payload.get("audio"), dict):
-            session.config.extra_body["realtime_audio"] = dict(payload["audio"])
-        elif "audio" in payload and payload.get("audio") is None:
-            session.config.extra_body.pop("realtime_audio", None)
-        if isinstance(payload.get("tracing"), str | dict):
-            session.config.extra_body["realtime_tracing"] = payload["tracing"]
-        elif "tracing" in payload and payload.get("tracing") is None:
-            session.config.extra_body.pop("realtime_tracing", None)
-        session.config.extra_body["realtime_session_payload"] = (
-            NativeRealtimeSessionProtocol._json_safe_realtime_payload(payload)
-        )
-        try:
-            turn_detection_configured, server_vad = parse_session_turn_detection(payload)
-            if turn_detection_configured:
-                vad_config = replace(session.config, server_vad=server_vad)
-                self._resolve_server_vad_defaults(session, vad_config, payload)
-                server_vad = vad_config.server_vad
-                if (
-                    not self._uses_native_input_append(session)
-                    and session.turn_detection_config_locked
-                    and (not session.config.turn_detection_configured or server_vad != session.config.server_vad)
-                ):
-                    return {
-                        "type": "error",
-                        "session_id": session.session_id,
-                        "code": "unsupported_turn_detection",
-                        "error": "turn_detection cannot be changed after the first audio append",
-                    }
-                session.config.turn_detection_configured = True
-                session.config.server_vad = server_vad
-                session.config.overlap_policy = vad_config.overlap_policy
-        except ValueError as exc:
-            return {
-                "type": "error",
-                "session_id": session.session_id,
-                "code": "invalid_request_error",
-                "error": str(exc),
-            }
-        return None
-
-    async def _configure_server_vad(self, session: DuplexSession) -> None:
-        pipeline = await self._prepare_server_vad_pipeline(session, session.config)
-        self._install_server_vad_pipeline(session, pipeline)
-
-    def _install_server_vad_pipeline(
-        self,
-        session: DuplexSession,
-        pipeline: ServerVADPipeline | None,
+        send_json: SendJson,
     ) -> None:
-        existing = self._server_vad_pipelines.pop(session.session_id, None)
-        if existing is not None:
-            existing.reset()
-            self._realtime_vad_metrics.session_finished()
-        if pipeline is None:
+        handle = attachment.handle
+        event_type = payload.get("type")
+        event_id = payload.get("event_id")
+        if event_type == "session.event_ack":
+            acknowledged = payload.get("server_event_seq")
+            if not isinstance(acknowledged, int) or acknowledged < 0:
+                message = "session.event_ack requires a non-negative server_event_seq"
+                await send_json(envelope.error_payload("invalid_event_ack", message, event_id=event_id))
+                return
+            try:
+                await self._attachment_registry.acknowledge(handle.session_id, acknowledged)
+            except ValueError as exc:
+                await send_json(envelope.error_payload("invalid_event_ack", str(exc), event_id=event_id))
             return
-        self._server_vad_pipelines[session.session_id] = pipeline
-        self._realtime_vad_metrics.session_started()
+        message = "session.resume must be the first message of a new connection"
+        await send_json(envelope.error_payload("unsupported_session_resume", message, event_id=event_id))
 
-    async def _prepare_server_vad_pipeline(
+    async def _submit_wire_event(
         self,
-        session: DuplexSession,
-        config: DuplexSessionConfig,
-    ) -> ServerVADPipeline | None:
-        if config.server_vad is None:
-            return None
-        backend = await asyncio.to_thread(self._server_vad_backend_provider.get)
-        pipeline_config = config.server_vad
-        if self._uses_native_input_append(session) and pipeline_config.min_speech_duration_ms is None:
-            pipeline_config = replace(
-                pipeline_config,
-                min_speech_duration_ms=SILERO_VAD_DEFAULT_MIN_SPEECH_DURATION_MS,
-            )
-        return ServerVADPipeline(backend, pipeline_config)
-
-    def _apply_response_create_options(
-        self,
-        session: DuplexSession,
+        attachment: _Attachment,
+        envelope: RealtimeEnvelope,
         payload: dict[str, object],
-    ) -> str | None:
-        """Reserve options that apply only to the next response lifecycle."""
-        audio_config = payload.get("audio")
-        audio_output = audio_config.get("output") if isinstance(audio_config, dict) else None
-        if session.capabilities.implementation_level == "model_native_duplex":
-            nested_voice = audio_output.get("voice") if isinstance(audio_output, dict) else None
-            unsupported = (
-                payload.get("instructions") is not None
-                or payload.get("voice") is not None
-                or nested_voice is not None
-                or payload.get("temperature") is not None
-                or any(
-                    payload.get(field_name) is not None
-                    for field_name in ("max_response_output_tokens", "max_output_tokens", "max_tokens")
-                )
-                or payload.get("tools") is not None
-                or payload.get("tool_choice") is not None
-            )
-            if unsupported:
-                return "unsupported_native_response_options"
-
-        instructions = str(payload["instructions"]) if isinstance(payload.get("instructions"), str) else None
-        voice = payload.get("voice")
-        if not isinstance(voice, str) and isinstance(audio_output, dict):
-            voice = audio_output.get("voice")
-        voice = str(voice) if isinstance(voice, str) else None
-        response_format = payload.get("output_audio_format") or payload.get("response_format")
-        if response_format is None and isinstance(audio_config, dict):
-            if isinstance(audio_output, dict):
-                response_format = audio_output.get("format")
-        response_format, _ = NativeRealtimeSessionProtocol._parse_realtime_audio_format(response_format)
-        if isinstance(response_format, str) and response_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
-            response_format = NativeRealtimeSessionProtocol._duplex_response_format(response_format)
-        else:
-            response_format = None
-        temperature = float(payload["temperature"]) if isinstance(payload.get("temperature"), int | float) else None
-        speed = payload.get("speed")
-        if not isinstance(speed, int | float) and isinstance(audio_output, dict):
-            speed = audio_output.get("speed")
-        speed = float(speed) if isinstance(speed, int | float) else None
-        max_tokens = (
-            payload.get("max_response_output_tokens")
-            if "max_response_output_tokens" in payload
-            else payload.get("max_output_tokens")
-            if "max_output_tokens" in payload
-            else payload.get("max_tokens")
-        )
-        if "max_response_output_tokens" in payload or "max_output_tokens" in payload or "max_tokens" in payload:
-            max_tokens = NativeRealtimeSessionProtocol.realtime_max_output_tokens(max_tokens)
-        else:
-            max_tokens = None
-        modalities = payload.get("modalities") or payload.get("output_modalities")
-        if isinstance(modalities, list) and all(isinstance(item, str) for item in modalities):
-            modalities = tuple(modalities)
-        else:
-            modalities = None
-        response_extra: dict[str, object] = {}
-        conversation = payload.get("conversation")
-        if isinstance(conversation, str):
-            response_extra["realtime_response_conversation"] = conversation
-        metadata = payload.get("metadata")
-        if isinstance(metadata, dict):
-            response_extra["realtime_response_metadata"] = dict(metadata)
-        prompt = payload.get("prompt")
-        if isinstance(prompt, dict):
-            response_extra["realtime_response_prompt"] = dict(prompt)
-        if isinstance(payload.get("tools"), list):
-            response_extra["realtime_response_tools"] = payload["tools"]
-        if isinstance(payload.get("tool_choice"), str | dict):
-            response_extra["realtime_response_tool_choice"] = payload["tool_choice"]
-        extra_body = payload.get("extra_body")
-        if isinstance(extra_body, dict):
-            if session.capabilities.implementation_level == "model_native_duplex":
-                response_extra.update(
-                    (key, value)
-                    for key, value in extra_body.items()
-                    if key not in self._require_serving_runtime_adapter().private_runtime_config_keys
-                )
-            else:
-                response_extra.update(extra_body)
+        send_json: SendJson,
+    ) -> None:
         try:
-            session.reserve_response_options(
-                ResponseCreateOptions(
-                    instructions=instructions,
-                    voice=voice,
-                    response_format=response_format,
-                    temperature=temperature,
-                    max_tokens=max_tokens,
-                    speed=speed,
-                    modalities=modalities,
-                    extra_body=response_extra,
-                )
-            )
-        except RuntimeError:
-            return "response_already_active"
-        return None
-
-    @staticmethod
-    def _realtime_item_to_history_message(item: object) -> dict[str, object] | None:
-        if not isinstance(item, dict):
-            return None
-        role = item.get("role")
-        if role not in {"system", "user", "assistant"}:
-            return None
-        content = item.get("content")
-        if isinstance(content, str):
-            text = content.strip()
-            return {"role": role, "content": text} if text else None
-        if not isinstance(content, list):
-            return None
-        text_chunks: list[str] = []
-        audio_chunks: list[dict[str, object]] = []
-        for part in content:
-            if not isinstance(part, dict):
-                continue
-            part_type = part.get("type")
-            if part_type in {"input_text", "text", "output_text"} and isinstance(part.get("text"), str):
-                text_chunks.append(str(part["text"]))
-            elif part_type in {"input_audio", "audio"}:
-                audio = part.get("audio") or part.get("data")
-                fmt = part.get("format") if isinstance(part.get("format"), str) else "wav"
-                if isinstance(audio, str) and audio:
-                    audio_chunks.append(
-                        {
-                            "type": "audio_url",
-                            "audio_url": {
-                                "url": f"data:audio/{fmt};base64,{audio}",
-                            },
-                        }
-                    )
-            elif part_type in {"audio_transcript", "transcript"} and isinstance(part.get("text"), str):
-                text_chunks.append(str(part["text"]))
-        text = "".join(text_chunks).strip()
-        if audio_chunks:
-            content_items: list[dict[str, object]] = []
-            if text:
-                content_items.append({"type": "text", "text": text})
-            content_items.extend(audio_chunks)
-            return {"role": role, "content": content_items}
-        if text:
-            return {"role": role, "content": text}
-        return None
-
-    async def _handle_playback_ack(self, session: DuplexSession, event: dict[str, object], send_json) -> None:
-        played_ms = event.get("played_ms", event.get("audio_ms", 0))
-        committed_ms = event.get("committed_ms")
-        if not isinstance(played_ms, int | float):
-            await send_json({"type": "error", "error": "playback.ack requires played_ms", "code": "bad_event"})
-            return
-        committed_cursor = int(committed_ms) if isinstance(committed_ms, int | float) else int(played_ms)
-        item_id = event.get("item_id")
-        response_id = event.get("response_id")
-        response_id = response_id if isinstance(response_id, str) and response_id else None
-        if not isinstance(item_id, str) or not item_id:
-            item_id = f"item_{response_id}" if response_id is not None else None
-        elif response_id is None and item_id.startswith("item_"):
-            response_id = item_id.removeprefix("item_")
-        if response_id is None and item_id is None and len(session.pending_history_item_ids) == 1:
-            item_id = next(iter(session.pending_history_item_ids))
-            if item_id.startswith("item_"):
-                response_id = item_id.removeprefix("item_")
-        if response_id is None and item_id is None and session.active_response_id is not None:
-            response_id = session.active_response_id
-            item_id = f"item_{response_id}"
-        if response_id is not None:
-            expected_item_id = f"item_{response_id}"
-            if item_id is None:
-                item_id = expected_item_id
-            elif item_id != expected_item_id:
-                await send_json(
-                    {
-                        "type": "error",
-                        "session_id": session.session_id,
-                        "epoch": session.epoch,
-                        "code": "playback_item_mismatch",
-                        "error": "playback.ack item_id must match item_<response_id>.",
-                    }
-                )
-                return
-            if not session.has_assistant_response_item(response_id, item_id):
-                await send_json(
-                    {
-                        "type": "error",
-                        "session_id": session.session_id,
-                        "epoch": session.epoch,
-                        "code": "playback_item_not_found",
-                        "error": f"No assistant response item is registered for {response_id}.",
-                    }
-                )
-                return
-            if session.playback_ack_is_too_late(response_id, item_id):
-                await send_json(
-                    {
-                        "type": "error",
-                        "session_id": session.session_id,
-                        "epoch": session.epoch,
-                        "code": "playback_ack_too_late",
-                        "error": "playback.ack arrived after a later user input was committed.",
-                    }
-                )
-                return
-            # Reserve the response's current history position before any later
-            # input commit can append a user item.  A 0 ms ACK is intentional:
-            # the response may be active but have no audio delta yet.
-            session.reserve_history_item(item_id)
-        elif item_id is not None:
-            await send_json(
-                {
-                    "type": "error",
-                    "session_id": session.session_id,
-                    "epoch": session.epoch,
-                    "code": "playback_item_not_found",
-                    "error": "playback.ack requires a response-owned assistant item.",
-                }
-            )
+            command = envelope.translate(payload)
+        except DuplexCommandError as exc:
+            await send_json(envelope.command_error_payload(exc))
             return
-        hard_truncate = event.get("truncate") is True
-        if hard_truncate:
-            playback = session.acknowledge_playback(
-                int(played_ms),
-                committed_cursor,
-                response_id=response_id,
-            )
-            playback = session.truncate_playback_commit(
-                committed_cursor,
-                response_id=response_id,
-            )
-        else:
-            playback = session.acknowledge_playback(
-                int(played_ms),
-                committed_cursor,
-                response_id=response_id,
-            )
-        committed_history = False
-        if isinstance(item_id, str) and item_id:
-            expected_item_id = f"item_{response_id}" if response_id is not None else None
-            if (
-                expected_item_id == item_id
-                and item_id not in session.history_item_ids
-                and item_id not in session.pending_history_item_ids
-            ):
-                # ACK_ONLY responses are normally registered as pending when
-                # the response ends. Recover the response-local item if that
-                # registration was lost across the response/ack boundary.
-                session.register_history_item(item_id, None)
-            committed_history = session.truncate_history_item(
-                item_id,
-                audio_end_ms=committed_cursor,
-                playback=playback,
-                hard=hard_truncate,
-            )
-        elif session.pending_history_item_ids:
-            # A plain playback ack has no OpenAI item id. Commit the only
-            # uncommitted assistant candidate if the session has an unambiguous
-            # pending response; otherwise wait for conversation.item.truncate.
-            pending_ids = list(session.pending_history_item_ids)
-            if len(pending_ids) == 1:
-                item_id = pending_ids[0]
-                committed_history = session.truncate_history_item(
-                    item_id,
-                    audio_end_ms=committed_cursor,
-                    playback=playback,
-                    hard=hard_truncate,
-                )
-        elif session.active_response_id is not None:
-            item_id = f"item_{session.active_response_id}"
-            committed_history = session.truncate_history_item(
-                item_id,
-                audio_end_ms=committed_cursor,
-                playback=playback,
-                hard=hard_truncate,
-            )
-        elif session.last_assistant_full_message is not None:
-            if item_id is None and session.history_item_ids:
-                assistant_item_ids = [
-                    known_item_id
-                    for known_item_id, message in session.history_item_ids.items()
-                    if message.get("role") == "assistant"
-                ]
-                if len(assistant_item_ids) == 1:
-                    item_id = assistant_item_ids[0]
-            if isinstance(item_id, str) and item_id:
-                committed_history = session.truncate_history_item(
-                    item_id,
-                    audio_end_ms=committed_cursor,
-                    playback=playback,
-                    hard=hard_truncate,
-                )
-        await send_json(
-            {
-                "type": "playback.acknowledged",
-                "session_id": session.session_id,
-                "epoch": session.epoch,
-                "item_id": item_id,
-                "played_ms": int(played_ms),
-                "committed_ms": committed_cursor,
-                "truncate": event.get("truncate") is True,
-                "playback": playback.as_dict(),
-                "history_committed": committed_history,
-            }
-        )
-        if committed_history and committed_cursor >= max(playback.sent_ms, playback.generated_ms):
-            session.release_response_playback(response_id)
-            session.release_response_history_snapshot(response_id)
+        # ``translate`` folds a session.update's audio settings into the
+        # envelope; remember them so a later reconnect starts where this left off.
+        self._input_defaults[attachment.handle.session_id] = envelope.defaults
+        await self._submit_command(attachment, envelope, command, send_json)
 
-    async def _cancel_active_response(
+    async def _submit_command(
         self,
-        session: DuplexSession,
-        active_task: asyncio.Task[None] | None,
-        send_json,
-        *,
-        reason: str,
-        notify: bool = True,
-    ) -> bool:
-        has_running_task = active_task is not None and not active_task.done()
-        if not has_running_task and session.active_request_id is None and session.active_response_id is None:
-            return False
-
-        old_epoch = session.epoch
-        old_request_id = session.active_request_id
-        old_response_id = session.active_response_id
-        committed_ms = session.playback.committed_ms
-        committed_message = session.end_response(
-            commit_text=self._should_commit_response_to_history(session, old_response_id),
-            playback_commit_policy=DuplexPlaybackCommitPolicy.ACK_ONLY.value,
-        )
-        if old_response_id is not None:
-            item_id = f"item_{old_response_id}"
-            if committed_message is not None:
-                session.register_history_item(item_id, committed_message)
-            elif committed_ms > 0 and not session.playback_ack_is_too_late(old_response_id, item_id):
-                session.truncate_history_item(item_id, audio_end_ms=committed_ms)
-        new_epoch, old_playback = self._advance_barge_in_epoch(session)
-        if old_request_id is not None:
-            # Epoch-scoped request ids prevent state reuse, but explicitly
-            # release projector/parser cursors so cancelled epochs do not
-            # accumulate until the whole session closes.
-            if self._serving_runtime_adapter is not None:
-                self._serving_runtime_adapter.data_plane.close_stream(old_request_id)
-            await self._abort_request_background(
-                session,
-                old_request_id,
-                send_json,
-                notify=notify,
-            )
-        if has_running_task and active_task is not None:
-            active_task.cancel()
-            try:
-                await asyncio.wait_for(asyncio.gather(active_task, return_exceptions=True), timeout=0.25)
-            except asyncio.TimeoutError:
-                pass
-        if notify:
-            await send_json(
-                {
-                    "type": "audio.cancelled",
-                    "session_id": session.session_id,
-                    "response_id": old_response_id,
-                    "reason": reason,
-                    "cancelled_epoch": old_epoch,
-                    "epoch": new_epoch,
-                    "committed_ms": committed_ms,
-                    "playback": old_playback,
-                }
-            )
-        return True
-
-    async def _abort_request_background(
-        self,
-        session: DuplexSession,
-        request_id: str,
-        send_json,
-        *,
-        notify: bool,
+        attachment: _Attachment,
+        envelope: RealtimeEnvelope,
+        command: DuplexCommand,
+        send_json: SendJson,
     ) -> None:
         try:
-            abort_internal = getattr(self._chat_service.engine_client, "_abort_internal_requests", None)
-            if callable(abort_internal):
-                result = abort_internal([request_id])
-            else:
-                result = self._chat_service.engine_client.abort([request_id])
-            if inspect.isawaitable(result):
-                await result
-        except Exception as exc:
-            logger.exception("Failed to abort duplex request %s: %s", request_id, exc)
-            if notify and session.state != DuplexSessionState.CLOSED:
-                await self._send_runtime_error(send_json, "runtime_abort_failed", exc, session=session)
+            await attachment.handle.submit(command)
+        except DuplexSessionError as exc:
+            await send_json(envelope.error_payload(exc.code, str(exc), event_id=command.event_id))
 
-    async def _cancel_pending_input(self, session: DuplexSession, send_json, *, reason: str) -> None:
-        cancelled = session.cancel_pending_input()
-        self._advance_barge_in_epoch(session)
-        await send_json(
-            {
-                "type": "input.cancelled",
-                "session_id": session.session_id,
-                "reason": reason,
-                "epoch": session.epoch,
-                "cancelled": cancelled,
-            }
-        )
+    # ------------------------------------------------------------------ #
+    # Disconnect                                                          #
+    # ------------------------------------------------------------------ #
+
+    async def _on_disconnect(self, attachment: _Attachment) -> None:
+        handle = attachment.handle
+        if handle.closed:
+            return
+        if handle.capabilities.supports_session_resume:
+            if await self._attachment_registry.detach(handle.session_id, attachment_generation=attachment.generation):
+                # Engine-owned disconnect grace: expiry arrives as session.expired.
+                with suppress(DuplexSessionError):
+                    await self._omni.detach_session(handle.session_id)
+            # Otherwise a newer connection already took the session over; the
+            # replaced socket's disconnect must not touch it.
+            return
+        with suppress(DuplexSessionError):
+            await handle.close(reason="disconnect")
diff --git a/vllm_omni/entrypoints/duplex/session_attachment.py b/vllm_omni/entrypoints/duplex/session_attachment.py
index 242169a6f8d..f2dc09f1cda 100644
--- a/vllm_omni/entrypoints/duplex/session_attachment.py
+++ b/vllm_omni/entrypoints/duplex/session_attachment.py
@@ -180,7 +180,6 @@ def replay_after(self, sequence: int) -> tuple[JournalEntry, ...]:
 @dataclass(frozen=True)
 class DuplexSessionAttachmentCreated:
     session_id: str
-    incarnation: int
     attachment_generation: int
     resume_token: ResumeToken = field(repr=False)
 
@@ -188,7 +187,6 @@ class DuplexSessionAttachmentCreated:
 @dataclass(frozen=True)
 class DuplexSessionResumeResult:
     session_id: str
-    incarnation: int
     attachment_generation: int
     resume_token: ResumeToken = field(repr=False)
     replay_entries: tuple[JournalEntry, ...] = ()
@@ -198,14 +196,12 @@ class DuplexSessionResumeResult:
 @dataclass
 class _DuplexSessionAttachmentState:
     session_id: str
-    incarnation: int
     credential: DuplexResumeCredential
     journal: DuplexEventJournal
     attachment: DuplexTransportAttachment | None
     attachment_generation: int
     outbound_lock: asyncio.Lock = field(default_factory=asyncio.Lock, repr=False)
     recovery_token_digest: bytes | None = field(default=None, repr=False)
-    grace_task: asyncio.Task[None] | None = field(default=None, repr=False)
 
 
 class DuplexSessionAttachmentRegistry:
@@ -214,18 +210,14 @@ def __init__(
         *,
         replay_ttl_s: float,
         replay_max_bytes_per_session: int,
-        disconnect_grace_s: float = 30.0,
         clock: Callable[[], float] | None = None,
     ) -> None:
         if replay_ttl_s <= 0:
             raise ValueError("replay_ttl_s must be positive")
         if replay_max_bytes_per_session <= 0:
             raise ValueError("replay_max_bytes_per_session must be positive")
-        if disconnect_grace_s <= 0:
-            raise ValueError("disconnect_grace_s must be positive")
         self._replay_ttl_s = replay_ttl_s
         self._replay_max_bytes_per_session = replay_max_bytes_per_session
-        self._disconnect_grace_s = disconnect_grace_s
         self._clock = clock or time.monotonic
         self._sessions: dict[str, _DuplexSessionAttachmentState] = {}
         self._lock = asyncio.Lock()
@@ -237,7 +229,6 @@ async def create(
         self,
         session_id: str,
         *,
-        incarnation: int,
         send: Callable[[dict[str, object]], Awaitable[None]],
         close: Callable[[str], Awaitable[None]],
     ) -> DuplexSessionAttachmentCreated:
@@ -248,7 +239,6 @@ async def create(
             generation = 1
             self._sessions[session_id] = _DuplexSessionAttachmentState(
                 session_id=session_id,
-                incarnation=incarnation,
                 credential=DuplexResumeCredential.from_token(token),
                 journal=DuplexEventJournal(
                     max_bytes=self._replay_max_bytes_per_session,
@@ -264,7 +254,6 @@ async def create(
             )
             return DuplexSessionAttachmentCreated(
                 session_id=session_id,
-                incarnation=incarnation,
                 attachment_generation=generation,
                 resume_token=token,
             )
@@ -309,33 +298,39 @@ async def acknowledge(self, session_id: str, sequence: int) -> int:
         async with self._lock:
             return self._require(session_id).journal.acknowledge(sequence)
 
-    async def detach(
-        self,
-        session_id: str,
-        *,
-        attachment_generation: int,
-        on_grace_expired: Callable[[], Awaitable[None]] | None = None,
-    ) -> bool:
+    async def detach(self, session_id: str, *, attachment_generation: int | None = None) -> bool:
+        """Drop the current transport; the engine lease owns the disconnect grace.
+
+        ``attachment_generation`` names the connection asking to detach, so a
+        socket that already lost a takeover cannot detach the winner. ``None``
+        means "whichever connection is attached right now" and is for callers
+        that only know the session (the outbound pump, whose send just failed).
+
+        Returns whether this call is the one that detached: an already-detached
+        session answers ``False`` so a second disconnect signal for the same
+        socket cannot restart the engine's disconnect grace window.
+        """
         async with self._lock:
             state = self._sessions.get(session_id)
-            if state is None or state.attachment_generation != attachment_generation:
+            if state is None or state.attachment is None:
+                return False
+            if attachment_generation is not None and state.attachment_generation != attachment_generation:
                 return False
             state.attachment = None
-            if state.grace_task is not None:
-                state.grace_task.cancel()
-            state.grace_task = (
-                asyncio.create_task(
-                    self._run_disconnect_grace(
-                        state,
-                        attachment_generation=attachment_generation,
-                        callback=on_grace_expired,
-                    )
-                )
-                if on_grace_expired is not None
-                else None
-            )
             return True
 
+    async def has_attachment(self, session_id: str) -> bool:
+        """Whether some connection is attached right now, whoever it is.
+
+        A resume that failed to activate has no generation of its own, so it
+        cannot ask ``is_current_attachment``. What it needs to know before
+        rolling the engine lease back into its disconnect grace is only whether
+        it would be rolling back somebody else's live attachment.
+        """
+        async with self._lock:
+            state = self._sessions.get(session_id)
+            return state is not None and state.attachment is not None
+
     async def is_current_attachment(self, session_id: str, attachment_generation: int) -> bool:
         async with self._lock:
             state = self._sessions.get(session_id)
@@ -349,25 +344,19 @@ async def authenticate_resume(
         self,
         session_id: str,
         *,
-        incarnation: int,
         resume_token: str,
         last_received_server_event_seq: int,
     ) -> None:
         """Validate transport credentials before any engine resume control."""
         async with self._lock:
             state = self._require(session_id)
-            self._validate_resume_identity(
-                state,
-                incarnation=incarnation,
-                resume_token=resume_token,
-            )
+            self._validate_resume_identity(state, resume_token=resume_token)
             state.journal.replay_after(last_received_server_event_seq)
 
     async def resume(
         self,
         session_id: str,
         *,
-        incarnation: int,
         resume_token: str,
         last_received_server_event_seq: int,
         send: Callable[[dict[str, object]], Awaitable[None]],
@@ -380,18 +369,11 @@ async def resume(
             async with self._lock:
                 if self._sessions.get(session_id) is not state:
                     raise KeyError(f"unknown duplex attachment session: {session_id}")
-                used_recovery = self._validate_resume_identity(
-                    state,
-                    incarnation=incarnation,
-                    resume_token=resume_token,
-                )
+                used_recovery = self._validate_resume_identity(state, resume_token=resume_token)
                 replay_entries = state.journal.replay_after(last_received_server_event_seq)
                 accepted_token_digest = (
                     state.recovery_token_digest if used_recovery else bytes(state.credential.token_digest)
                 )
-                if state.grace_task is not None:
-                    state.grace_task.cancel()
-                    state.grace_task = None
                 state.recovery_token_digest = None
                 rotated_token = state.credential.rotate()
                 replaced = state.attachment
@@ -407,52 +389,52 @@ async def resume(
                     await send(dict(activation_payload_factory(rotated_token, attachment_generation)))
                     for entry in replay_entries:
                         await send(dict(entry.payload))
-                except Exception:
-                    async with self._lock:
-                        if (
-                            self._sessions.get(session_id) is state
-                            and state.attachment_generation == attachment_generation
-                        ):
-                            state.attachment = None
-                            state.recovery_token_digest = accepted_token_digest
+                except (Exception, asyncio.CancelledError):
+                    # CancelledError derives from BaseException, so an
+                    # ``except Exception`` here would let a cancellation during
+                    # activation or replay skip the rollback: the dead
+                    # attachment would stay current while the token it rotated
+                    # past is gone, leaving the session attached to an unusable
+                    # transport with no way back. Both failures take the same
+                    # path deliberately, so they cannot drift apart.
+                    await self._rollback_resume(
+                        session_id,
+                        state=state,
+                        attachment_generation=attachment_generation,
+                        accepted_token_digest=accepted_token_digest,
+                    )
                     raise
             return DuplexSessionResumeResult(
                 session_id=session_id,
-                incarnation=incarnation,
                 attachment_generation=attachment_generation,
                 resume_token=rotated_token,
                 replay_entries=replay_entries,
                 replaced_attachment=replaced,
             )
 
-    async def close(self, session_id: str) -> DuplexTransportAttachment | None:
-        async with self._lock:
-            state = self._sessions.pop(session_id, None)
-            if state is not None and state.grace_task is not None:
-                state.grace_task.cancel()
-            return state.attachment if state is not None else None
-
-    async def _run_disconnect_grace(
+    async def _rollback_resume(
         self,
-        state: _DuplexSessionAttachmentState,
+        session_id: str,
         *,
+        state: _DuplexSessionAttachmentState,
         attachment_generation: int,
-        callback: Callable[[], Awaitable[None]] | None,
+        accepted_token_digest: bytes,
     ) -> None:
-        try:
-            await asyncio.sleep(self._disconnect_grace_s)
-        except asyncio.CancelledError:
-            return
+        """Undo a resume whose activation never reached the client.
+
+        Generation-checked: a later resume that already took over must keep its
+        attachment. Restoring ``recovery_token_digest`` is what lets the caller
+        retry with the token it presented, which ``resume`` had rotated past.
+        """
         async with self._lock:
-            if (
-                self._sessions.get(state.session_id) is not state
-                or state.attachment is not None
-                or state.attachment_generation != attachment_generation
-            ):
-                return
-            state.grace_task = None
-        if callback is not None:
-            await callback()
+            if self._sessions.get(session_id) is state and state.attachment_generation == attachment_generation:
+                state.attachment = None
+                state.recovery_token_digest = accepted_token_digest
+
+    async def close(self, session_id: str) -> DuplexTransportAttachment | None:
+        async with self._lock:
+            state = self._sessions.pop(session_id, None)
+            return state.attachment if state is not None else None
 
     def _require(self, session_id: str) -> _DuplexSessionAttachmentState:
         state = self._sessions.get(session_id)
@@ -461,14 +443,7 @@ def _require(self, session_id: str) -> _DuplexSessionAttachmentState:
         return state
 
     @staticmethod
-    def _validate_resume_identity(
-        state: _DuplexSessionAttachmentState,
-        *,
-        incarnation: int,
-        resume_token: str,
-    ) -> bool:
-        if incarnation != state.incarnation:
-            raise ValueError(f"duplex attachment incarnation mismatch: expected {state.incarnation}, got {incarnation}")
+    def _validate_resume_identity(state: _DuplexSessionAttachmentState, *, resume_token: str) -> bool:
         if state.credential.verify(resume_token):
             return False
         recovery_digest = state.recovery_token_digest
diff --git a/vllm_omni/entrypoints/duplex/session_runner.py b/vllm_omni/entrypoints/duplex/session_runner.py
deleted file mode 100644
index 90251e99831..00000000000
--- a/vllm_omni/entrypoints/duplex/session_runner.py
+++ /dev/null
@@ -1,2520 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-import binascii
-import json
-import time
-import uuid
-from collections.abc import Callable
-from contextlib import suppress
-from copy import deepcopy
-
-import numpy as np
-import pybase64 as base64
-from fastapi import WebSocket, WebSocketDisconnect
-from vllm.logger import init_logger
-
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.entrypoints.duplex.audio import (
-    convert_input_audio_with_rate,
-    validate_input_sample_rate_hz,
-)
-from vllm_omni.entrypoints.duplex.commit_policy import (
-    CommitAction,
-    CommitSnapshot,
-    decide_commit_action,
-)
-from vllm_omni.entrypoints.duplex.protocol import (
-    DuplexOverlapPolicy,
-    DuplexPlaybackCommitPolicy,
-    DuplexSession,
-    DuplexSessionState,
-    DuplexTurnEventType,
-)
-from vllm_omni.entrypoints.duplex.realtime_session import (
-    NativeRealtimeSessionProtocol,
-)
-from vllm_omni.entrypoints.duplex.runtime_adapter import (
-    PcmAppendReservation,
-    ServingRuntimeConfigError,
-    ServingRuntimeSessionState,
-    payload_turn_id,
-)
-from vllm_omni.entrypoints.duplex.server_vad import ServerVADPipeline
-from vllm_omni.entrypoints.duplex.session_attachment import (
-    DuplexJournalOverflowError,
-)
-from vllm_omni.entrypoints.duplex.websocket import (
-    DuplexWebSocketActor,
-    is_input_event,
-    normalize_duplex_input_event,
-)
-
-logger = init_logger(__name__)
-
-_MAX_EVENT_BYTES = 15 * 1024 * 1024
-
-
-class DuplexSessionRunnerMixin:
-    """Run one ordered WebSocket mailbox for a duplex session."""
-
-    async def handle_session(
-        self,
-        websocket: WebSocket,
-        *,
-        realtime_protocol: NativeRealtimeSessionProtocol | None = None,
-    ) -> None:
-        await websocket.accept()
-        session: DuplexSession | None = None
-        actor = DuplexWebSocketActor(
-            websocket,
-            current_epoch=lambda: session.epoch if session is not None else None,
-            session_closed=lambda: session is not None and session.state == DuplexSessionState.CLOSED,
-            outbound_protocol=realtime_protocol,
-        )
-        runtime_opened = False
-        runtime_closed = False
-        attachment_ready = False
-        attachment_generation: int | None = None
-        resume_credential_delivered = False
-        transport_detached = False
-        pending_turn_reservations = 0
-
-        async def attachment_send(payload: dict[str, object]) -> None:
-            nonlocal resume_credential_delivered
-            try:
-                await websocket.send_json(payload)
-            except RuntimeError as exc:
-                message = str(exc)
-                if "after sending 'websocket.close'" in message or "response already completed" in message:
-                    raise WebSocketDisconnect(code=1006) from exc
-                raise
-            if payload.get("type") == "session.created" and isinstance(payload.get("resume_token"), str):
-                resume_credential_delivered = True
-
-        async def attachment_close(reason: str) -> None:
-            close = getattr(websocket, "close", None)
-            if callable(close):
-                await close(code=1000, reason=reason)
-
-        async def send_attachment_payload(
-            payload: dict[str, object], *, journal: bool, on_accepted: Callable[[], None] | None = None
-        ) -> None:
-            assert session is not None
-            session_id = session.session_id
-            should_journal = journal and session_id not in self._resync_required_sessions
-            try:
-                await self._attachment_registry.send_event(
-                    session_id,
-                    payload,
-                    journal=should_journal,
-                    on_accepted=on_accepted,
-                )
-            except DuplexJournalOverflowError:
-                first_overflow = session_id not in self._resync_required_sessions
-                self._resync_required_sessions.add(session_id)
-                if first_overflow:
-                    resync_payload: dict[str, object] = {
-                        "type": "session.resync_required",
-                        "session_id": session_id,
-                        "reason": "journal_overflow",
-                    }
-                    if realtime_protocol is not None:
-                        resync_payload = realtime_protocol.encode_outbound_event(resync_payload)[0]
-                    await self._attachment_registry.send_event(
-                        session_id,
-                        resync_payload,
-                        journal=False,
-                    )
-                await self._attachment_registry.send_event(
-                    session_id,
-                    payload,
-                    journal=False,
-                    on_accepted=on_accepted,
-                )
-
-        if realtime_protocol is not None:
-
-            async def send_realtime_raw(payload: dict[str, object]) -> None:
-                if attachment_ready and session is not None:
-                    await send_attachment_payload(
-                        payload,
-                        journal=payload.get("type") not in {"session.created", "session.resumed"},
-                    )
-                    return
-                raw_payload = dict(payload)
-                raw_payload["_realtime_raw"] = True
-                await actor.send_json(raw_payload)
-
-            realtime_protocol.bind_sender(send_realtime_raw)
-        native: ServingRuntimeSessionState = self._create_runtime_session_state()
-
-        def begin_close(reason: str) -> None:
-            actor.closing = True
-            actor.close_reason = reason
-            if session is not None:
-                session.mark_closing()
-
-        event_emit_lock = asyncio.Lock()
-
-        async def send_outbound(payload: dict[str, object], *, on_accepted: Callable[[], None] | None = None) -> None:
-            if not attachment_ready or session is None:
-                await actor.send_json(dict(payload))
-                if on_accepted is not None:
-                    on_accepted()
-                return
-            if realtime_protocol is None:
-                await send_attachment_payload(
-                    payload,
-                    journal=payload.get("type") not in {"session.created", "session.resumed"},
-                    on_accepted=on_accepted,
-                )
-                return
-            for projected in realtime_protocol.encode_outbound_event(payload):
-                await send_attachment_payload(
-                    projected,
-                    journal=projected.get("type") not in {"session.created", "session.resumed"},
-                    # Item/part announcements may precede the audio. Only the
-                    # actual audio event establishes acceptance of this chunk.
-                    on_accepted=on_accepted if projected.get("type") == "response.audio.delta" else None,
-                )
-
-        async def emit_event(payload: dict[str, object], *, on_accepted: Callable[[], None] | None = None) -> None:
-            deferred_precreate_response = False
-            async with event_emit_lock:
-                accepted, deferred_overlap_payload = await self._apply_outbound_session_event(
-                    payload,
-                    session=session,
-                    actor=actor,
-                    native=native,
-                    realtime_protocol=realtime_protocol,
-                )
-                if not accepted:
-                    return
-                await send_outbound(payload, on_accepted=on_accepted)
-                if deferred_overlap_payload is not None:
-                    deferred_precreate_response = native.deferred_precreate_response
-                    native.deferred_precreate_response = False
-            if deferred_overlap_payload is not None and session is not None and not actor.closing:
-                await start_native_append(
-                    deferred_overlap_payload,
-                    final=True,
-                    precreate_response=deferred_precreate_response,
-                    operation_id=native.committed_audio_operation_id,
-                    retained_committed_payload=(
-                        deferred_overlap_payload if native.committed_audio_payload is deferred_overlap_payload else None
-                    ),
-                )
-
-        writer_task = asyncio.create_task(actor.writer_loop(), name="duplex-session-writer")
-        reader_task: asyncio.Task[None] | None = None
-
-        async def read_event_loop() -> None:
-            nonlocal pending_turn_reservations
-            assert session is not None
-            try:
-                while not actor.closing:
-                    raw = await self._receive_text(
-                        websocket,
-                        session.config.idle_timeout_s,
-                        realtime_protocol=realtime_protocol,
-                    )
-                    if raw is None:
-                        await actor.enqueue_event({"type": "__timeout__"})
-                        return
-                    if len(raw.encode("utf-8")) > _MAX_EVENT_BYTES:
-                        await emit_event(
-                            {"type": "error", "error": "Duplex event too large", "code": "event_too_large"}
-                        )
-                        continue
-                    try:
-                        event = json.loads(raw)
-                    except json.JSONDecodeError:
-                        await emit_event({"type": "error", "error": "Invalid JSON event", "code": "invalid_json"})
-                        continue
-                    if not isinstance(event, dict):
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "error": "Duplex event must be a JSON object",
-                                "code": "bad_event",
-                            }
-                        )
-                        continue
-                    event = normalize_duplex_input_event(event)
-                    event_type = event.get("type")
-                    if not isinstance(event_type, str):
-                        await emit_event(
-                            {"type": "error", "error": "Duplex event missing string type", "code": "bad_event"}
-                        )
-                        continue
-                    if event_type in {"input.commit", "input_audio_buffer.commit"}:
-                        if not session.reserve_pending_turn(
-                            limit=self._duplex_session_config.max_pending_turns_per_session
-                        ):
-                            await emit_event(
-                                {
-                                    "type": "error",
-                                    "error": "Duplex session has too many pending input turns",
-                                    "code": "input_backpressure",
-                                }
-                            )
-                            continue
-                        event["_duplex_pending_turn_reserved"] = True
-                        pending_turn_reservations += 1
-                    if is_input_event(event_type) and native_response_in_progress():
-                        event["_duplex_overlap_candidate"] = True
-                    await actor.enqueue_event(event)
-            except WebSocketDisconnect:
-                await actor.enqueue_event({"type": "__disconnect__"})
-            except Exception as exc:
-                await emit_event({"type": "error", "error": str(exc), "code": "realtime_input_failed"})
-                await actor.enqueue_event({"type": "__disconnect__"})
-
-        async def next_actor_event() -> dict[str, object]:
-            nonlocal pending_turn_reservations, transport_detached
-            event = await actor.next_event()
-            if event.pop("_duplex_pending_turn_reserved", False) and session is not None:
-                session.release_pending_turn()
-                pending_turn_reservations = max(0, pending_turn_reservations - 1)
-            if (
-                attachment_ready
-                and attachment_generation is not None
-                and session is not None
-                and not await self._attachment_registry.is_current_attachment(
-                    session.session_id,
-                    attachment_generation,
-                )
-            ):
-                transport_detached = True
-                return {"type": "__replaced_attachment__"}
-            return event
-
-        def native_response_in_progress() -> bool:
-            if session is None:
-                return False
-            if session.active_response_id is not None:
-                return True
-            if (
-                session.config.playback_commit_policy == DuplexPlaybackCommitPolicy.ACK_ONLY.value
-                and session.playback.sent_ms > session.playback.committed_ms
-            ):
-                return True
-            if actor.active_response_task is not None and not actor.active_response_task.done():
-                return True
-            if actor.has_response_bound_append_tasks():
-                return True
-            return False
-
-        def start_chat_response() -> None:
-            assert session is not None
-
-            async def run_and_notify() -> None:
-                task = asyncio.current_task()
-                try:
-                    await self._run_response(session, emit_event)
-                finally:
-                    await actor.enqueue_event(
-                        {
-                            "type": "__chat_response_finished__",
-                            "_response_task": task,
-                        }
-                    )
-
-            actor.active_response_task = asyncio.create_task(run_and_notify())
-
-        def activate_waiting_server_vad_turn() -> None:
-            assert session is not None
-            pending_turn = session.activate_server_vad_turn()
-            if pending_turn is not None and pending_turn.create_response:
-                start_chat_response()
-
-        def correlate_realtime_error(
-            payload: dict[str, object],
-            event_id: object,
-        ) -> dict[str, object]:
-            if isinstance(event_id, str) and event_id:
-                payload["event_id"] = event_id
-            return payload
-
-        async def reject_and_clear_server_vad_input(
-            pipeline: ServerVADPipeline,
-            *,
-            code: str,
-            error: str,
-            metric_reason: str,
-            event_id: object,
-        ) -> None:
-            assert session is not None
-            session.cancel_pending_input()
-            pipeline.reset()
-            self._realtime_vad_metrics.error(metric_reason)
-            await emit_event(
-                correlate_realtime_error(
-                    {
-                        "type": "error",
-                        "session_id": session.session_id,
-                        "code": code,
-                        "error": error,
-                    },
-                    event_id,
-                )
-            )
-            await emit_event(
-                {
-                    "type": "input_audio_buffer.cleared",
-                    "session_id": session.session_id,
-                }
-            )
-
-        async def commit_server_vad_turn(
-            *,
-            item_id: str,
-            create_response: bool,
-            retain_input_bytes: int,
-            event_id: object = None,
-        ) -> None:
-            assert session is not None
-            # Retain ownership until the actor consumes the terminal event so
-            # queued audio cannot overtake pending-turn activation.
-            active_response = actor.active_response_task is not None
-            if active_response and session.pending_server_vad_turn is not None:
-                released = session.discard_uncommitted_server_vad_utterance()
-                session.release_input_bytes(released)
-                self._realtime_vad_metrics.error("pending_turn_backpressure")
-                await emit_event(
-                    correlate_realtime_error(
-                        {
-                            "type": "error",
-                            "session_id": session.session_id,
-                            "code": "input_backpressure",
-                            "error": "Only one committed Server VAD turn may wait for the active response",
-                        },
-                        event_id,
-                    )
-                )
-                return
-            if not session.stage_server_vad_audio_for_commit():
-                return
-            committed = session.commit_user_input(
-                append_history=not active_response,
-                retain_input_bytes=retain_input_bytes,
-            )
-            if committed is None:
-                return
-            if active_response:
-                session.stage_server_vad_turn(
-                    committed,
-                    create_response=create_response,
-                    item_id=item_id,
-                )
-            else:
-                session.register_history_item(item_id, committed.message)
-            await emit_event(
-                self._input_committed_payload(
-                    session,
-                    committed,
-                    item_id=item_id,
-                )
-            )
-            if create_response and not active_response:
-                start_chat_response()
-
-        def clear_completed_pending_silence() -> None:
-            task = native.pending_silence_task
-            if task is not None and task.done():
-                native.pending_silence_task = None
-                native.pending_silence_owner_id = None
-
-        def mark_pending_silence_superseded() -> None:
-            task = native.pending_silence_task
-            if task is None:
-                return
-            if task.done():
-                native.pending_silence_task = None
-            # Do not cancel the task or clear native_append_tail here. A
-            # silence append may already have reached the Engine, and local
-            # cancellation cannot retract that RPC. The sequencer preserves
-            # wire order; before_append will skip silence that has not started.
-            native.pending_silence_owner_id = None
-
-        def real_native_input_waiting() -> bool:
-            clear_completed_pending_silence()
-            return (
-                native.audio_buffer.has_pending()
-                or native.audio_buffer.has_reserved()
-                or actor.has_queued_input_events()
-            )
-
-        async def start_native_append(
-            payload: object,
-            *,
-            final: bool,
-            precreate_response: bool = False,
-            pcm_reservation: PcmAppendReservation | None = None,
-            operation_id: str | None = None,
-            retained_committed_payload: dict[str, object] | None = None,
-            silence_continuation: bool = False,
-            before_append=None,
-        ) -> asyncio.Task[bool] | None:
-            if session is None:
-                return
-            if not silence_continuation:
-                mark_pending_silence_superseded()
-            append_epoch = session.epoch
-            append_turn_id = payload_turn_id(payload)
-            if append_turn_id is None:
-                append_turn_id = session.turn_id
-            request_id = self._native_stage0_request_id(session, append_epoch)
-            if final or precreate_response:
-                session.bind_request(request_id)
-            if precreate_response:
-                session.bind_response_turn(append_turn_id)
-            if precreate_response and session.active_response_id is None:
-                response_id = session.begin_response(turn_id=append_turn_id)
-                await emit_event(
-                    self._response_created_payload(
-                        session,
-                        response_id,
-                        epoch=append_epoch,
-                    )
-                )
-            precreated_response_id = session.active_response_id if precreate_response else None
-
-            def _discard_retained_committed_audio() -> None:
-                if (
-                    retained_committed_payload is not None
-                    and native.committed_audio_payload is retained_committed_payload
-                ):
-                    session.release_input_bytes(native.clear_committed_audio())
-
-            async def _run() -> bool:
-                nonlocal runtime_closed
-                try:
-                    session.mark_model_turn_request_started(append_turn_id, time.monotonic())
-                    append_ok, emitted_response = await self._append_runtime_input(
-                        session,
-                        payload,
-                        operation_id=(pcm_reservation.operation_id if pcm_reservation is not None else operation_id),
-                        final=final,
-                        send_json=emit_event,
-                        mode="append_audio_chunk",
-                        expected_epoch=append_epoch,
-                    )
-                    if append_ok:
-                        native.native_context_locked = True
-                        if pcm_reservation is not None:
-                            pcm_reservation.commit()
-                            session.release_input_bytes(pcm_reservation.byte_count)
-                        if (
-                            retained_committed_payload is not None
-                            and native.committed_audio_payload is retained_committed_payload
-                        ):
-                            session.release_input_bytes(native.clear_committed_audio())
-                    else:
-                        if pcm_reservation is not None:
-                            pcm_reservation.rollback()
-                        _discard_retained_committed_audio()
-                    if (
-                        not append_ok
-                        and precreated_response_id is not None
-                        and session.active_response_id == precreated_response_id
-                    ):
-                        session.end_response(commit_text=False)
-                        await emit_event(
-                            {
-                                "type": "response.done",
-                                "session_id": session.session_id,
-                                "response_id": precreated_response_id,
-                                "epoch": session.epoch,
-                                "committed": False,
-                                "status": "failed",
-                                "status_details": {
-                                    "type": "failed",
-                                    "reason": "runtime_append_failed",
-                                },
-                                "playback": session.playback.as_dict(),
-                            }
-                        )
-                    if not append_ok and session.state == DuplexSessionState.CLOSED:
-                        runtime_closed = True
-                        return False
-                    if not emitted_response and session.epoch == append_epoch:
-                        if session.active_request_id == self._native_stage0_request_id(session, append_epoch):
-                            session.clear_request(request_id)
-                        if final:
-                            await emit_event(
-                                self._turn_controller.signal(session, DuplexTurnEventType.USER_STARTED.value)
-                            )
-                    return append_ok
-                except asyncio.CancelledError:
-                    if pcm_reservation is not None:
-                        pcm_reservation.rollback()
-                    raise
-                except Exception as exc:
-                    if pcm_reservation is not None:
-                        pcm_reservation.rollback()
-                    _discard_retained_committed_audio()
-                    logger.exception("Native duplex append task failed: %s", exc)
-                    await self._send_runtime_error(emit_event, "runtime_append_task_failed", exc, session=session)
-                    if session.state != DuplexSessionState.CLOSED:
-                        begin_close("runtime_append_task_failed")
-                        if await self._close_runtime_session(
-                            session,
-                            reason="runtime_append_task_failed",
-                            send_json=emit_event,
-                        ):
-                            runtime_closed = True
-                            session.close()
-                            await emit_event(
-                                {
-                                    "type": "session.closed",
-                                    "session_id": session.session_id,
-                                    "reason": "runtime_append_task_failed",
-                                }
-                            )
-                    return False
-
-            async def _run_in_wire_order(predecessor: asyncio.Task[bool] | None) -> bool:
-                if predecessor is not None:
-                    try:
-                        predecessor_ok = await predecessor
-                    except asyncio.CancelledError:
-                        current = asyncio.current_task()
-                        if current is not None and current.cancelling():
-                            raise
-                        predecessor_ok = False
-                    except Exception:
-                        predecessor_ok = False
-                    if not predecessor_ok:
-                        if pcm_reservation is not None:
-                            pcm_reservation.rollback()
-                        _discard_retained_committed_audio()
-                        return False
-                if actor.closing or runtime_closed or session.state != DuplexSessionState.OPEN:
-                    if pcm_reservation is not None:
-                        pcm_reservation.rollback()
-                    _discard_retained_committed_audio()
-                    return False
-                if before_append is not None and not before_append():
-                    if pcm_reservation is not None:
-                        pcm_reservation.rollback()
-                    _discard_retained_committed_audio()
-                    return True
-                if pcm_reservation is not None and not pcm_reservation.active:
-                    _discard_retained_committed_audio()
-                    return False
-                return await _run()
-
-            def _release_cancelled_retained_audio(done: asyncio.Task[bool]) -> None:
-                if done.cancelled():
-                    _discard_retained_committed_audio()
-                    return
-                try:
-                    append_ok = done.result()
-                except Exception:
-                    append_ok = False
-                if not append_ok:
-                    _discard_retained_committed_audio()
-
-            predecessor = actor.native_append_tail
-            if predecessor is not None and predecessor.done():
-                try:
-                    predecessor_ok = predecessor.result()
-                except (asyncio.CancelledError, Exception):
-                    predecessor_ok = False
-                if not predecessor_ok:
-                    # Appends already queued behind a failed predecessor keep
-                    # their captured dependency and stop. A later wire command
-                    # is an explicit retry and starts a new chain.
-                    predecessor = None
-            task = asyncio.create_task(_run_in_wire_order(predecessor))
-            task.add_done_callback(_release_cancelled_retained_audio)
-            actor.native_append_tail = task
-            actor.track_append_task(
-                task,
-                epoch=append_epoch,
-                mode="append_audio_chunk",
-                final=final,
-                response_bound=final or precreate_response,
-            )
-            if silence_continuation:
-                native.pending_silence_task = task
-
-                def _clear_done_pending_silence(done: asyncio.Task[bool]) -> None:
-                    if native.pending_silence_task is done:
-                        native.pending_silence_task = None
-                        native.pending_silence_owner_id = None
-
-                task.add_done_callback(_clear_done_pending_silence)
-            # Let this wire-order effect start before the next mailbox event can
-            # cancel it. Later native appends still serialize on predecessor.
-            await asyncio.sleep(0)
-            return task
-
-        async def schedule_native_silence_continuation(
-            payload: object,
-            *,
-            request_id: str,
-            owner_id: str,
-            response_id: str | None,
-            response_owned: bool,
-            expected_epoch: int | None,
-            expected_incarnation: int,
-            expected_model_turn_id: int | None,
-            send_json,
-        ) -> bool:
-            del send_json
-            if session is None:
-                return False
-            clear_completed_pending_silence()
-            pending_silence = native.pending_silence_task
-            if pending_silence is not None and not pending_silence.done():
-                if pending_silence is asyncio.current_task():
-                    return False
-                try:
-                    if not await pending_silence:
-                        return False
-                except asyncio.CancelledError:
-                    current = asyncio.current_task()
-                    if current is not None and current.cancelling():
-                        raise
-                    return False
-                except Exception:
-                    return False
-                clear_completed_pending_silence()
-                pending_silence = native.pending_silence_task
-                if pending_silence is not None and not pending_silence.done():
-                    return False
-            append_tail = actor.native_append_tail
-            if (append_tail is None or append_tail.done()) and real_native_input_waiting():
-                return False
-            continuation_delay_s = max(
-                0.0,
-                float(session.capabilities.chunk_period_ms or 1000) / 1000.0,
-            )
-            if continuation_delay_s > 0:
-                await asyncio.sleep(continuation_delay_s)
-                if (
-                    actor.native_append_tail is not append_tail
-                    or ((append_tail is None or append_tail.done()) and real_native_input_waiting())
-                    or self._native_silence_continuation_is_stale(
-                        session,
-                        request_id=request_id,
-                        response_id=response_id,
-                        response_owned=response_owned,
-                        expected_epoch=expected_epoch,
-                        expected_incarnation=expected_incarnation,
-                        expected_model_turn_id=expected_model_turn_id,
-                    )
-                ):
-                    return False
-
-            def _still_valid() -> bool:
-                return not real_native_input_waiting() and not self._native_silence_continuation_is_stale(
-                    session,
-                    request_id=request_id,
-                    response_id=response_id,
-                    response_owned=response_owned,
-                    expected_epoch=expected_epoch,
-                    expected_incarnation=expected_incarnation,
-                    expected_model_turn_id=expected_model_turn_id,
-                )
-
-            native.pending_silence_owner_id = owner_id
-            task = await start_native_append(
-                payload,
-                final=False,
-                silence_continuation=True,
-                before_append=_still_valid,
-            )
-            if task is None:
-                native.pending_silence_owner_id = None
-                return False
-            return True
-
-        async def wait_for_native_append_tail() -> bool:
-            predecessor = actor.native_append_tail
-            if predecessor is None:
-                return True
-            try:
-                return await predecessor
-            except asyncio.CancelledError:
-                current = asyncio.current_task()
-                if current is not None and current.cancelling():
-                    raise
-                return False
-            except Exception:
-                # The append task already emitted its runtime error. Preserve
-                # wire order before the update path decides whether to continue.
-                return False
-
-        async def start_runtime_append(
-            payload: object,
-            *,
-            final: bool,
-            mode: str = "append_tokens",
-        ) -> None:
-            """Schedule non-native runtime appends without blocking WS input.
-
-            Model-native appends use ``start_native_append`` because they can
-            create data-plane response streams. Generic runtime appends still
-            need the same control-plane isolation so cancel/close can preempt a
-            slow engine append.
-            """
-            if session is None:
-                return
-            append_epoch = session.epoch
-
-            async def _run() -> None:
-                nonlocal runtime_closed
-                try:
-                    append_ok, emitted_response = await self._append_runtime_input(
-                        session,
-                        payload,
-                        final=final,
-                        send_json=emit_event,
-                        mode=mode,
-                        expected_epoch=append_epoch,
-                    )
-                    if not append_ok:
-                        if session.state == DuplexSessionState.CLOSED:
-                            runtime_closed = True
-                        return
-                    if not emitted_response and session.epoch == append_epoch:
-                        await emit_event(self._turn_controller.signal(session, DuplexTurnEventType.USER_STARTED.value))
-                except asyncio.CancelledError:
-                    raise
-                except Exception as exc:
-                    logger.exception("Duplex runtime append task failed: %s", exc)
-                    await self._send_runtime_error(emit_event, "runtime_append_task_failed", exc, session=session)
-
-            task = asyncio.create_task(_run())
-            actor.track_append_task(
-                task,
-                epoch=append_epoch,
-                mode=mode,
-                final=final,
-                response_bound=final,
-            )
-
-        try:
-            handshake = await self._open_session(
-                websocket,
-                emit_event,
-                realtime_protocol=realtime_protocol,
-                attachment_send=attachment_send,
-                attachment_close=attachment_close,
-            )
-            if handshake is None:
-                return
-            session = handshake.session
-            if initial_update_error := self._runtime_session_candidate_update_error(
-                session, session.config, realtime_protocol=realtime_protocol
-            ):
-                await emit_event(
-                    correlate_realtime_error(
-                        initial_update_error,
-                        handshake.event_id,
-                    )
-                )
-                return
-            if handshake.resumed:
-                native = self._serving_session_states[session.session_id]
-                actor.tasks = self._session_tasks[session.session_id]
-                persisted_protocol = self._realtime_protocols.get(session.session_id)
-                if persisted_protocol is None:
-                    raise RuntimeError(f"Missing Realtime protocol state for resumed session {session.session_id}")
-                realtime_protocol = persisted_protocol
-                realtime_protocol.bind_sender(send_realtime_raw)
-                attachment_generation = handshake.attachment_generation
-                attachment_ready = True
-                resume_credential_delivered = True
-                runtime_opened = True
-                self._ensure_lifecycle_listener()
-                reader_task = asyncio.create_task(read_event_loop(), name="duplex-session-reader")
-            else:
-                self._serving_session_states[session.session_id] = native
-                self._session_tasks[session.session_id] = actor.tasks
-                if realtime_protocol is not None:
-                    self._realtime_protocols[session.session_id] = realtime_protocol
-            native.silence_continuation_scheduler = schedule_native_silence_continuation
-            if realtime_protocol is not None:
-                realtime_protocol.bind_native_input_append(self._uses_native_input_append(session))
-                session.config.playback_commit_policy = DuplexPlaybackCommitPolicy.ACK_ONLY.value
-            if not handshake.resumed:
-                open_result = await self._open_runtime_session(session, emit_event)
-                if open_result is False:
-                    return
-                runtime_opened = True
-                try:
-                    await self._configure_server_vad(session)
-                except Exception as exc:
-                    logger.exception("Server VAD initialization failed: %s", exc)
-                    self._realtime_vad_metrics.error("initialization")
-                    await emit_event(
-                        correlate_realtime_error(
-                            {
-                                "type": "error",
-                                "session_id": session.session_id,
-                                "code": "server_vad_initialization_failed",
-                                "error": str(exc),
-                            },
-                            handshake.event_id,
-                        )
-                    )
-                    return
-                created_attachment = await self._attachment_registry.create(
-                    session.session_id,
-                    incarnation=session.incarnation,
-                    send=attachment_send,
-                    close=attachment_close,
-                )
-                attachment_generation = created_attachment.attachment_generation
-                attachment_ready = True
-                self._lease_generations[session.session_id] = 0
-                self._ensure_lifecycle_listener()
-                created_payload: dict[str, object] = {
-                    "type": "session.created",
-                    "session": session.as_public_dict(),
-                }
-                if session.capabilities.supports_session_resume:
-                    created_payload.update(
-                        {
-                            "incarnation": session.incarnation,
-                            "attachment_generation": attachment_generation,
-                            "resume_token": created_attachment.resume_token.plaintext,
-                        }
-                    )
-                if isinstance(open_result, dict):
-                    created_payload["runtime_control"] = self._redact_runtime_control_result(open_result)
-                if realtime_protocol is not None:
-                    realtime_protocol.commit_realtime_turn_detection_update(session.config.server_vad)
-                await emit_event(created_payload)
-                resume_credential_delivered = session.capabilities.supports_session_resume
-                reader_task = asyncio.create_task(read_event_loop(), name="duplex-session-reader")
-
-            while True:
-                event = await next_actor_event()
-                event_type = event.get("type")
-
-                if event_type == "__replaced_attachment__":
-                    return
-
-                if event_type == "__chat_response_finished__":
-                    completed_task = event.get("_response_task")
-                    if completed_task is not actor.active_response_task:
-                        continue
-                    actor.active_response_task = None
-                    activate_waiting_server_vad_turn()
-                    continue
-
-                if event_type == "__timeout__":
-                    begin_close("timeout")
-                    native.audio_buffer.clear()
-                    session.release_all_input_bytes()
-                    native.input_since_commit = False
-                    native.speech_since_commit = False
-                    native.clear_committed_audio()
-                    await actor.cancel_append_tasks()
-                    await self._cancel_native_data_plane_stream(session)
-                    await self._cancel_active_response(
-                        session,
-                        actor.active_response_task,
-                        emit_event,
-                        reason="timeout",
-                        notify=True,
-                    )
-                    actor.active_response_task = None
-                    runtime_closed = await self._close_runtime_session(
-                        session,
-                        reason="timeout",
-                        send_json=emit_event,
-                    )
-                    if not runtime_closed:
-                        return
-                    session.close()
-                    await emit_event(
-                        {
-                            "type": "session.closed",
-                            "session_id": session.session_id,
-                            "reason": "timeout",
-                        }
-                    )
-                    return
-
-                if event_type == "__disconnect__":
-                    transport_detached = True
-                    return
-
-                if not isinstance(event_type, str):
-                    continue
-
-                if event_type == "session.heartbeat":
-                    touch_session = getattr(self._chat_service.engine_client, "touch_duplex_session_async", None)
-                    if not callable(touch_session):
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "error": "Duplex runtime does not expose heartbeat control",
-                                "code": "runtime_touch_unsupported",
-                            }
-                        )
-                        continue
-                    try:
-                        await touch_session(
-                            session.session_id,
-                            fence=DuplexFence(
-                                session.session_id,
-                                epoch=session.epoch,
-                                turn_id=session.turn_id,
-                                incarnation=session.incarnation,
-                            ),
-                            activity=DuplexLeaseActivity.HEARTBEAT,
-                        )
-                    except Exception as exc:
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "error": str(exc),
-                                "code": "runtime_touch_failed",
-                            }
-                        )
-                        continue
-                    await emit_event(
-                        {
-                            "type": "session.heartbeat_ack",
-                            "session_id": session.session_id,
-                        }
-                    )
-                    continue
-
-                if event_type == "session.event_ack":
-                    acknowledged = event.get("server_event_seq")
-                    if not isinstance(acknowledged, int) or acknowledged < 0:
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "error": "session.event_ack requires a non-negative server_event_seq",
-                                "code": "invalid_event_ack",
-                            }
-                        )
-                        continue
-                    try:
-                        await self._attachment_registry.acknowledge(session.session_id, acknowledged)
-                    except ValueError as exc:
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "error": str(exc),
-                                "code": "invalid_event_ack",
-                            }
-                        )
-                    continue
-
-                if event_type == "turn.signal" and event.get("event") in {
-                    "input.cancel",
-                    "response.cancel",
-                    "barge_in",
-                }:
-                    payload = event.get("payload")
-                    normalized_event = dict(payload) if isinstance(payload, dict) else {}
-                    normalized_event.update(event)
-                    normalized_event["type"] = event["event"]
-                    event = normalized_event
-                    event_type = str(event["type"])
-
-                if event_type == "session.close":
-                    with suppress(asyncio.TimeoutError):
-                        await asyncio.wait_for(actor.output_queue.join(), timeout=1.0)
-                    begin_close("session_close")
-                    if session.state == DuplexSessionState.CLOSED:
-                        runtime_closed = True
-                        return
-                    native.audio_buffer.clear()
-                    session.release_all_input_bytes()
-                    native.input_since_commit = False
-                    native.speech_since_commit = False
-                    native.clear_committed_audio()
-                    await actor.cancel_append_tasks()
-                    await self._cancel_native_data_plane_stream(session)
-                    await self._cancel_active_response(
-                        session,
-                        actor.active_response_task,
-                        emit_event,
-                        reason="session_close",
-                    )
-                    runtime_closed = await self._close_runtime_session(
-                        session,
-                        reason="session_close",
-                        send_json=emit_event,
-                    )
-                    actor.active_response_task = None
-                    if not runtime_closed:
-                        return
-                    await emit_event({"type": "session.closed", "session_id": session.session_id})
-                    session.close()
-                    return
-
-                if event_type == "input_audio_buffer.clear":
-                    native.audio_buffer.clear()
-                    session.release_all_input_bytes()
-                    server_vad_pipeline = self._server_vad_pipelines.get(session.session_id)
-                    if server_vad_pipeline is not None:
-                        server_vad_pipeline.reset()
-                    native.input_since_commit = False
-                    native.speech_since_commit = False
-                    native.clear_committed_audio()
-                    cancelled = session.cancel_pending_input()
-                    await emit_event(
-                        {
-                            "type": "input_audio_buffer.cleared",
-                            "session_id": session.session_id,
-                            "epoch": session.epoch,
-                            "drained_input_events": 0,
-                            "cancelled": cancelled,
-                        }
-                    )
-                    continue
-
-                if event_type == "barge_in" and not session.capabilities.supports_barge_in:
-                    await emit_event(self._barge_in_unsupported_error(session))
-                    continue
-
-                if event_type in {"input.cancel", "response.cancel", "barge_in", "output_audio_buffer.clear"}:
-                    cancel_reason = (
-                        "output_audio_buffer_clear"
-                        if event_type == "output_audio_buffer.clear"
-                        else "client_cancelled"
-                        if event_type == "response.cancel"
-                        else "barge_in"
-                    )
-                    cancelled_fence = DuplexFence(
-                        session.session_id,
-                        epoch=session.epoch,
-                        turn_id=session.turn_id,
-                        incarnation=session.incarnation,
-                    )
-                    if event_type == "response.cancel":
-                        requested_response_id = event.get("response_id")
-                        has_active_response_work = native_response_in_progress()
-                        if isinstance(requested_response_id, str) and (
-                            session.active_response_id is None or requested_response_id != session.active_response_id
-                        ):
-                            await emit_event(
-                                {
-                                    "type": "error",
-                                    "session_id": session.session_id,
-                                    "code": "response_not_active",
-                                    "error": f"Response is not active: {requested_response_id}",
-                                }
-                            )
-                            continue
-                    if event_type == "response.cancel":
-                        if not has_active_response_work:
-                            if realtime_protocol is not None and isinstance(requested_response_id, str):
-                                continue
-                            await emit_event(
-                                {
-                                    "type": "error",
-                                    "session_id": session.session_id,
-                                    "code": "response_not_active",
-                                    "error": "response.cancel requires an active response",
-                                }
-                            )
-                            continue
-                    had_native_unbuffered_append = (
-                        self._uses_native_input_append(session)
-                        and native.input_since_commit
-                        and not native.audio_buffer.has_pending()
-                    )
-                    playback_was_active = self._assistant_playback_active(session)
-                    if event_type in {"input.cancel", "barge_in"}:
-                        native.audio_buffer.clear()
-                        session.release_all_input_bytes()
-                        native.input_since_commit = False
-                        native.speech_since_commit = False
-                        native.clear_committed_audio()
-                    had_native_append = await actor.cancel_append_tasks(
-                        response_bound_only=event_type in {"response.cancel", "output_audio_buffer.clear"},
-                    )
-                    if event_type == "response.cancel":
-                        session.release_input_bytes(native.clear_committed_audio())
-                    had_native_stream = native.data_plane_task is not None
-                    cancelled = await self._cancel_active_response(
-                        session,
-                        actor.active_response_task,
-                        emit_event,
-                        reason=cancel_reason,
-                    )
-                    had_native_stream = await self._cancel_native_data_plane_stream(session) or had_native_stream
-                    if not cancelled and (had_native_stream or had_native_append or had_native_unbuffered_append):
-                        old_epoch = session.epoch
-                        old_response_id = session.active_response_id
-                        committed_ms = session.playback.committed_ms
-                        self._commit_played_response_history(session, old_response_id, committed_ms)
-                        new_epoch, old_playback = self._advance_barge_in_epoch(session)
-                        await emit_event(
-                            {
-                                "type": "audio.cancelled",
-                                "session_id": session.session_id,
-                                "response_id": old_response_id,
-                                "reason": cancel_reason,
-                                "cancelled_epoch": old_epoch,
-                                "epoch": new_epoch,
-                                "committed_ms": committed_ms,
-                                "playback": old_playback,
-                            }
-                        )
-                        cancelled = True
-                    if not cancelled and playback_was_active:
-                        old_epoch = session.epoch
-                        committed_ms = session.playback.committed_ms
-                        self._commit_played_response_history(session, session.last_response_id, committed_ms)
-                        new_epoch, old_playback = self._advance_barge_in_epoch(session)
-                        await emit_event(
-                            {
-                                "type": "audio.cancelled",
-                                "session_id": session.session_id,
-                                "response_id": session.last_response_id,
-                                "reason": cancel_reason,
-                                "cancelled_epoch": old_epoch,
-                                "epoch": new_epoch,
-                                "committed_ms": committed_ms,
-                                "playback": old_playback,
-                            }
-                        )
-                        cancelled = True
-                    if not cancelled and event_type == "response.cancel":
-                        old_epoch = session.epoch
-                        old_response_id = session.active_response_id
-                        committed_ms = session.playback.committed_ms
-                        self._commit_played_response_history(session, old_response_id, committed_ms)
-                        new_epoch, old_playback = self._advance_barge_in_epoch(session)
-                        await emit_event(
-                            {
-                                "type": "audio.cancelled",
-                                "session_id": session.session_id,
-                                "response_id": old_response_id,
-                                "reason": cancel_reason,
-                                "cancelled_epoch": old_epoch,
-                                "epoch": new_epoch,
-                                "committed_ms": committed_ms,
-                                "playback": old_playback,
-                            }
-                        )
-                        cancelled = True
-                    if not cancelled and event_type == "output_audio_buffer.clear":
-                        old_playback = session.playback.as_dict()
-                        committed_ms = session.playback.committed_ms
-                        session.clear_playback_cursor()
-                        await emit_event(
-                            {
-                                "type": "audio.cancelled",
-                                "session_id": session.session_id,
-                                "response_id": session.active_response_id,
-                                "reason": cancel_reason,
-                                "cancelled_epoch": session.epoch,
-                                "epoch": session.epoch,
-                                "committed_ms": committed_ms,
-                                "playback": old_playback,
-                            }
-                        )
-                        actor.active_response_task = None
-                        activate_waiting_server_vad_turn()
-                        continue
-                    if not cancelled:
-                        await self._cancel_pending_input(session, emit_event, reason="barge_in")
-                    if not await self._signal_runtime_session(
-                        session,
-                        "barge_in",
-                        emit_event,
-                        fence=cancelled_fence,
-                        next_fence=(
-                            DuplexFence(
-                                session.session_id,
-                                epoch=session.epoch,
-                                turn_id=session.turn_id,
-                                incarnation=session.incarnation,
-                            )
-                            if session.epoch > cancelled_fence.epoch
-                            else None
-                        ),
-                    ):
-                        continue
-                    actor.active_response_task = None
-                    activate_waiting_server_vad_turn()
-                    continue
-
-                if event_type == "turn.signal":
-                    turn_event = event.get("event")
-                    if isinstance(turn_event, str):
-                        if turn_event == "barge_in" and not session.capabilities.supports_barge_in:
-                            await emit_event(self._barge_in_unsupported_error(session))
-                            continue
-                        if turn_event == "session.update":
-                            realtime_event_id = event.get("realtime_event_id")
-
-                            async def emit_update_event(update_event: dict[str, object]) -> None:
-                                if isinstance(realtime_event_id, str) and realtime_event_id:
-                                    update_event = {**update_event, "realtime_event_id": realtime_event_id}
-                                await emit_event(update_event)
-
-                            def reject_update() -> None:
-                                if realtime_protocol is not None:
-                                    realtime_protocol.reject_realtime_turn_detection_update()
-
-                            payload = event.get("payload")
-                            if not isinstance(payload, dict):
-                                await emit_update_event(
-                                    {
-                                        "type": "error",
-                                        "session_id": session.session_id,
-                                        "code": "bad_event",
-                                        "error": "session.update requires a session payload",
-                                    }
-                                )
-                                reject_update()
-                                continue
-                            if not await wait_for_native_append_tail():
-                                await emit_update_event(
-                                    {
-                                        "type": "error",
-                                        "code": "session_update_aborted",
-                                        "error": "session.update was not applied because the preceding append failed",
-                                    }
-                                )
-                                reject_update()
-                                continue
-                            if (
-                                realtime_protocol is not None
-                                and not self._uses_native_input_append(session)
-                                and session.config.server_vad is not None
-                                and session.turn_detection_config_locked
-                                and realtime_protocol.pending_realtime_input_audio_config_changed()
-                            ):
-                                await emit_update_event(
-                                    {
-                                        "type": "error",
-                                        "session_id": session.session_id,
-                                        "code": "unsupported_audio_format",
-                                        "error": (
-                                            "session.update cannot change Server VAD input format or sample rate "
-                                            "after the first audio append"
-                                        ),
-                                        "param": "audio.input.format",
-                                    }
-                                )
-                                reject_update()
-                                continue
-                            runtime_update_error = self._runtime_session_update_error(session, payload)
-                            if runtime_update_error is not None:
-                                await emit_update_event(runtime_update_error)
-                                reject_update()
-                                continue
-                            previous_config = session.config
-                            candidate_config = deepcopy(previous_config)
-                            session.replace_config(candidate_config)
-                            try:
-                                update_error = self._apply_session_update(session, payload)
-                            finally:
-                                session.replace_config(previous_config)
-                            server_vad_changed = candidate_config.server_vad != previous_config.server_vad
-                            if update_error is not None:
-                                await emit_update_event(update_error)
-                                reject_update()
-                                continue
-                            runtime_update_error = self._runtime_session_candidate_update_error(
-                                session,
-                                candidate_config,
-                                realtime_protocol=realtime_protocol,
-                            )
-                            if runtime_update_error is not None:
-                                await emit_update_event(runtime_update_error)
-                                reject_update()
-                                continue
-                            try:
-                                candidate_runtime_config = self._runtime_config_for_session_update(
-                                    session,
-                                    candidate_config,
-                                )
-                            except ServingRuntimeConfigError as exc:
-                                await emit_update_event(
-                                    {
-                                        "type": "error",
-                                        "session_id": session.session_id,
-                                        "code": exc.code,
-                                        "error": str(exc),
-                                    }
-                                )
-                                reject_update()
-                                continue
-                            candidate_server_vad_pipeline = None
-                            if server_vad_changed:
-                                try:
-                                    candidate_server_vad_pipeline = await self._prepare_server_vad_pipeline(
-                                        session,
-                                        candidate_config,
-                                    )
-                                except Exception as exc:
-                                    logger.exception("Server VAD session update failed: %s", exc)
-                                    self._realtime_vad_metrics.error("initialization")
-                                    await emit_update_event(
-                                        {
-                                            "type": "error",
-                                            "session_id": session.session_id,
-                                            "code": "server_vad_initialization_failed",
-                                            "error": str(exc),
-                                        }
-                                    )
-                                    reject_update()
-                                    continue
-                            runtime_updated = await self._signal_runtime_session(
-                                session,
-                                turn_event,
-                                emit_update_event,
-                                session_config=candidate_config.as_dict(),
-                                runtime_config=candidate_runtime_config,
-                            )
-                            if not runtime_updated:
-                                reject_update()
-                                continue
-                            session.replace_config(candidate_config)
-                            session.replace_runtime_config(candidate_runtime_config)
-                            if server_vad_changed:
-                                self._install_server_vad_pipeline(
-                                    session,
-                                    candidate_server_vad_pipeline,
-                                )
-                            if realtime_protocol is not None:
-                                realtime_protocol.bind_native_input_append(self._uses_native_input_append(session))
-                                realtime_protocol.commit_realtime_turn_detection_update(session.config.server_vad)
-                            await emit_update_event(
-                                {
-                                    "type": "session.updated",
-                                    "session": session.as_public_dict(),
-                                }
-                            )
-                            continue
-                        if turn_event == "conversation.item.create":
-                            payload = event.get("payload")
-                            item = payload.get("item") if isinstance(payload, dict) else None
-                            item_type = item.get("type") if isinstance(item, dict) else None
-                            prepare_function_output = getattr(
-                                self._serving_runtime_adapter,
-                                "runtime_config_for_function_output",
-                                None,
-                            )
-                            if item_type == "function_call_output" and callable(prepare_function_output):
-                                if not await wait_for_native_append_tail():
-                                    continue
-                                try:
-                                    candidate_runtime_config = prepare_function_output(
-                                        item,
-                                        dict(session.runtime_config),
-                                    )
-                                except ServingRuntimeConfigError as exc:
-                                    await emit_event(
-                                        {
-                                            "type": "error",
-                                            "session_id": session.session_id,
-                                            "code": exc.code,
-                                            "error": str(exc),
-                                        }
-                                    )
-                                    continue
-                                if not await self._signal_runtime_session(
-                                    session,
-                                    "session.update",
-                                    emit_event,
-                                    runtime_config=candidate_runtime_config,
-                                ):
-                                    continue
-                                session.replace_runtime_config(candidate_runtime_config)
-                                await emit_event(
-                                    {
-                                        "type": "conversation.item.created",
-                                        "session_id": session.session_id,
-                                        "item": item,
-                                        "created": True,
-                                    }
-                                )
-                                await self._maybe_continue_native_response(
-                                    emit_event,
-                                    session=session,
-                                    expected_epoch=session.epoch,
-                                    expected_model_turn_id=session.turn_id,
-                                )
-                                continue
-                            history_item = payload.get("history_item") if isinstance(payload, dict) else None
-                            if not isinstance(history_item, dict):
-                                history_item = item
-                            message = self._realtime_item_to_history_message(history_item)
-                            item_id = item.get("id") if isinstance(item, dict) else None
-                            if message is not None:
-                                session.append_history_message(message)
-                                session.register_history_item(item_id if isinstance(item_id, str) else None, message)
-                            await emit_event(
-                                {
-                                    "type": "conversation.item.created",
-                                    "session_id": session.session_id,
-                                    "item": item,
-                                    "created": message is not None,
-                                }
-                            )
-                            continue
-                        if turn_event == "conversation.item.delete":
-                            payload = event.get("payload")
-                            item_id = payload.get("item_id") if isinstance(payload, dict) else None
-                            deleted = session.delete_history_item(item_id) if isinstance(item_id, str) else False
-                            await emit_event(
-                                {
-                                    "type": "conversation.item.deleted",
-                                    "session_id": session.session_id,
-                                    "item_id": item_id,
-                                    "deleted": deleted,
-                                }
-                            )
-                            continue
-                        if turn_event == "conversation.item.truncate":
-                            payload = event.get("payload")
-                            item_id = payload.get("item_id") if isinstance(payload, dict) else None
-                            audio_end_ms = payload.get("audio_end_ms") if isinstance(payload, dict) else None
-                            truncated = (
-                                session.truncate_history_item(
-                                    item_id,
-                                    audio_end_ms=int(audio_end_ms) if isinstance(audio_end_ms, int | float) else 0,
-                                    hard=True,
-                                )
-                                if isinstance(item_id, str)
-                                else False
-                            )
-                            await emit_event(
-                                {
-                                    "type": "conversation.item.truncated",
-                                    "session_id": session.session_id,
-                                    "item_id": item_id,
-                                    "content_index": (
-                                        payload.get("content_index", 0) if isinstance(payload, dict) else 0
-                                    ),
-                                    "audio_end_ms": audio_end_ms,
-                                    "truncated": truncated,
-                                }
-                            )
-                            continue
-                        await emit_event(self._turn_controller.signal(session, turn_event, event))
-                    else:
-                        await emit_event({"type": "error", "error": "turn.signal requires event", "code": "bad_event"})
-                    continue
-
-                if event_type == "playback.ack":
-                    await self._handle_playback_ack(session, event, emit_event)
-                    continue
-
-                if event_type == "input.text.append":
-                    session.mark_user_input_activity()
-                    text = event.get("text")
-                    if not isinstance(text, str):
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "error": "input.text.append requires text",
-                                "code": "bad_event",
-                            }
-                        )
-                        continue
-                    if self._uses_native_input_append(session):
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "error": "The selected native duplex runtime accepts audio append only",
-                                "code": "native_text_append_unsupported",
-                            }
-                        )
-                        continue
-                    else:
-                        session.append_text(text)
-                    if session.capabilities.supports_input_append:
-                        await start_runtime_append(text, final=False, mode="append_tokens")
-                    continue
-
-                if event_type == "input_audio_buffer.append":
-                    session.mark_user_input_activity()
-                    audio = event.get("audio") or event.get("data")
-                    if not isinstance(audio, str):
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "error": "input.audio.append requires audio",
-                                "code": "bad_event",
-                            }
-                        )
-                        continue
-                    if not session.capabilities.supports_barge_in and self._event_requests_barge_in(event):
-                        await emit_event(self._barge_in_unsupported_error(session))
-                        event = dict(event)
-                        event.pop("force_barge_in", None)
-                        for key in ("overlap_action", "overlap"):
-                            value = event.get(key)
-                            if isinstance(value, str) and value.strip().lower() in {
-                                "barge_in",
-                                "interrupt",
-                                "cancel",
-                            }:
-                                event.pop(key, None)
-                    fmt = event.get("format") if isinstance(event.get("format"), str) else "pcm16"
-                    default_sample_rate_hz = 16000
-                    sr_raw = event.get("sample_rate_hz") or event.get("sample_rate")
-                    sample_rate_hz = sr_raw if isinstance(sr_raw, int | float) else default_sample_rate_hz
-                    native_input = self._uses_native_input_append(session)
-                    server_vad_config = session.config.server_vad
-                    turn_based_server_vad = server_vad_config is not None and not native_input
-                    if not turn_based_server_vad:
-                        try:
-                            audio, fmt, sample_rate_hz = convert_input_audio_with_rate(
-                                audio,
-                                fmt,
-                                sample_rate_hz=sample_rate_hz,
-                            )
-                        except ValueError as exc:
-                            await emit_event({"type": "error", "error": str(exc), "code": "bad_event"})
-                            continue
-                        if isinstance(fmt, str) and fmt.lower() in {"pcm16", "pcm_s16le", "s16le"}:
-                            await emit_event(
-                                {
-                                    "type": "error",
-                                    "error": "input_audio_buffer.append pcm16 audio could not be decoded",
-                                    "code": "bad_audio",
-                                }
-                            )
-                            continue
-                        if server_vad_config is None:
-                            session.lock_turn_detection_config()
-                    force_listen = bool(event.get("force_listen", False))
-                    payload = {
-                        "type": "audio",
-                        "audio": audio,
-                        "format": fmt,
-                        "sample_rate_hz": sample_rate_hz,
-                        "force_listen": force_listen,
-                    }
-                    video_frames = event.get("video_frames")
-                    if isinstance(video_frames, list):
-                        frames = [frame for frame in video_frames if isinstance(frame, str) and frame]
-                        if frames:
-                            payload["video_frames"] = frames
-                    if server_vad_config is not None:
-                        realtime_event_id = event.get("_realtime_event_id")
-                        pipeline = self._server_vad_pipelines.get(session.session_id)
-                        if pipeline is None:
-                            await emit_event(
-                                correlate_realtime_error(
-                                    {
-                                        "type": "error",
-                                        "session_id": session.session_id,
-                                        "code": "internal_error",
-                                        "error": "server_vad is configured but its detector pipeline is unavailable",
-                                    },
-                                    realtime_event_id,
-                                )
-                            )
-                            continue
-                        speech_was_active = pipeline.speech_active
-                        reserved_bytes = 0
-                        previous_scratch_bytes = pipeline.scratch_bytes
-                        try:
-                            if native_input:
-                                if fmt != "pcm_f32le" or sample_rate_hz != pipeline.sample_rate_hz:
-                                    raise ValueError("native server_vad input must be mono PCM float32 at 16000 Hz")
-                                raw_audio = base64.b64decode(audio, validate=True)
-                                if len(raw_audio) % np.dtype("<f4").itemsize:
-                                    raise ValueError("native server_vad input contains an incomplete float32 sample")
-                                normalized_audio = np.frombuffer(raw_audio, dtype="<f4")
-                                accepted_audio = normalized_audio.size > 0
-                            else:
-                                if fmt != "pcm16":
-                                    raise ValueError("server_vad input must be mono PCM16")
-                                source_sample_rate_hz = validate_input_sample_rate_hz(sample_rate_hz)
-                                if source_sample_rate_hz not in {16_000, 24_000}:
-                                    raise ValueError("server_vad PCM16 input sample rate must be 16000 or 24000 Hz")
-                                if (
-                                    pipeline.source_sample_rate_hz is not None
-                                    and source_sample_rate_hz != pipeline.source_sample_rate_hz
-                                ):
-                                    raise ValueError(
-                                        "server_vad input sample rate cannot change within a continuous audio stream"
-                                    )
-                                try:
-                                    raw_audio = base64.b64decode(audio, validate=True)
-                                except (binascii.Error, ValueError) as exc:
-                                    raise ValueError(
-                                        "server_vad input audio must be valid base64-encoded PCM16"
-                                    ) from exc
-                                if len(raw_audio) % np.dtype("<i2").itemsize:
-                                    raise ValueError("server_vad PCM16 input contains an incomplete sample")
-                                source_samples = len(raw_audio) // np.dtype("<i2").itemsize
-                                accepted_audio = source_samples > 0
-                        except (binascii.Error, ValueError) as exc:
-                            await emit_event(
-                                correlate_realtime_error(
-                                    {
-                                        "type": "error",
-                                        "session_id": session.session_id,
-                                        "code": "bad_audio",
-                                        "error": str(exc),
-                                        "param": "audio",
-                                    },
-                                    realtime_event_id,
-                                )
-                            )
-                            continue
-                        if not native_input:
-                            normalized_sample_upper_bound = (
-                                source_samples
-                                if source_sample_rate_hz == pipeline.sample_rate_hz
-                                else ((source_samples + 2) // 3) * 2
-                            )
-                            reserved_bytes = normalized_sample_upper_bound * np.dtype(np.float32).itemsize
-                            if not session.reserve_input_bytes(
-                                reserved_bytes,
-                                limit=self._duplex_session_config.max_pending_input_bytes_per_session,
-                            ):
-                                await reject_and_clear_server_vad_input(
-                                    pipeline,
-                                    code="input_backpressure",
-                                    error="Server VAD input exceeds the per-session input limit",
-                                    metric_reason="input_backpressure",
-                                    event_id=realtime_event_id,
-                                )
-                                continue
-                        try:
-                            vad_batch = (
-                                await pipeline.push(normalized_audio)
-                                if native_input
-                                else await pipeline.push_pcm16(
-                                    raw_audio,
-                                    source_sample_rate_hz=source_sample_rate_hz,
-                                )
-                            )
-                        except Exception as exc:
-                            logger.exception("Server VAD inference failed: %s", exc)
-                            await reject_and_clear_server_vad_input(
-                                pipeline,
-                                code="server_vad_inference_failed",
-                                error=str(exc),
-                                metric_reason="inference",
-                                event_id=realtime_event_id,
-                            )
-                            continue
-                        if not native_input:
-                            retained_delta = (
-                                sum(frame.samples.nbytes for frame in vad_batch.frames)
-                                + pipeline.scratch_bytes
-                                - previous_scratch_bytes
-                            )
-                            session.release_input_bytes(max(0, reserved_bytes - retained_delta))
-                        self._realtime_vad_metrics.observe_inference(vad_batch.inference_ms)
-                        prefix_samples = round(server_vad_config.prefix_padding_ms * pipeline.sample_rate_hz / 1000)
-                        speech_started = False
-                        speech_stopped = False
-                        for frame_index, vad_frame in enumerate(vad_batch.frames):
-                            decision = vad_frame.decision
-                            if not native_input:
-                                released_bytes = session.append_server_vad_frame(
-                                    vad_frame.samples,
-                                    speech_started=decision.speech_started,
-                                    speech_stopped=decision.speech_stopped,
-                                    prefix_samples=prefix_samples,
-                                )
-                                session.release_input_bytes(released_bytes)
-                            if decision.speech_started:
-                                speech_started = True
-                                item_id = f"item_{uuid.uuid4().hex}"
-                                session.begin_server_vad_speech(item_id)
-                                await emit_event(
-                                    {
-                                        "type": "input_audio_buffer.speech_started",
-                                        "session_id": session.session_id,
-                                        "item_id": item_id,
-                                        "audio_start_ms": decision.audio_start_ms or 0,
-                                    }
-                                )
-                            if decision.speech_stopped:
-                                speech_stopped = True
-                                item_id = session.finish_server_vad_speech() or f"item_{uuid.uuid4().hex}"
-                                await emit_event(
-                                    {
-                                        "type": "input_audio_buffer.speech_stopped",
-                                        "session_id": session.session_id,
-                                        "item_id": item_id,
-                                        "audio_end_ms": decision.audio_end_ms or 0,
-                                    }
-                                )
-                                if decision.endpoint_delay_ms is not None:
-                                    self._realtime_vad_metrics.observe_endpoint_delay(decision.endpoint_delay_ms)
-                                if not native_input:
-                                    remaining_frame_bytes = sum(
-                                        frame.samples.nbytes for frame in vad_batch.frames[frame_index + 1 :]
-                                    )
-                                    await commit_server_vad_turn(
-                                        item_id=item_id,
-                                        create_response=server_vad_config.create_response,
-                                        retain_input_bytes=remaining_frame_bytes + pipeline.scratch_bytes,
-                                        event_id=realtime_event_id,
-                                    )
-                        if accepted_audio:
-                            session.lock_turn_detection_config()
-                        if not native_input:
-                            continue
-                        speech_active = pipeline.speech_active
-                        contained_speech = speech_was_active or speech_started or speech_stopped or speech_active
-                        payload["is_speech"] = contained_speech
-                        payload["vad"] = {
-                            "backend": "silero",
-                            "is_speech": contained_speech,
-                            "speech_active": speech_active,
-                            "speech_started": speech_started,
-                            "speech_stopped": speech_stopped,
-                        }
-                        if speech_active:
-                            payload["force_listen"] = True
-                    # Speech/silence tag for the Stage0 turn-ended latch.
-                    payload["is_speech"] = self._input_looks_like_speech(event, payload, session=session)
-                    defer_native_append = False
-                    buffer_overlap_audio = True
-                    if native_input:
-                        mark_pending_silence_superseded()
-                        overlap_active = native_response_in_progress() and (
-                            not self._session_auto_responds(session)
-                            or (
-                                session.capabilities.supports_barge_in
-                                and (
-                                    session.config.overlap_policy == DuplexOverlapPolicy.BARGE_IN_ON_SPEECH.value
-                                    or self._event_requests_barge_in(event)
-                                )
-                            )
-                        )
-                        if overlap_active:
-                            decision = self._overlap_decision(session, event, payload)
-                            await self._emit_overlap_decision(emit_event, session, decision)
-                            action = decision.get("action")
-                            if action == "drop":
-                                if realtime_protocol is not None:
-                                    await realtime_protocol.discard_pending_input_audio(
-                                        audio_end_ms=self._input_audio_duration_ms(event, payload)
-                                    )
-                                continue
-                            if action == "listen":
-                                buffer_overlap_audio = bool(decision.get("buffer_audio", True))
-                                defer_native_append = bool(decision.get("defer_runtime_append", True))
-                                if (
-                                    not buffer_overlap_audio
-                                    and realtime_protocol is not None
-                                    and decision.get("preserve_realtime_input") is not True
-                                ):
-                                    await realtime_protocol.discard_pending_input_audio(
-                                        audio_end_ms=self._input_audio_duration_ms(event, payload)
-                                    )
-                                if decision.get("force_listen", True) is True:
-                                    payload["force_listen"] = True
-                            else:
-                                event["force_barge_in"] = True
-                                cancelled_fence = DuplexFence(
-                                    session.session_id,
-                                    epoch=session.epoch,
-                                    turn_id=session.turn_id,
-                                    incarnation=session.incarnation,
-                                )
-                                playback_was_active = self._assistant_playback_active(session)
-                                buffer_overlap_audio = True
-                                defer_native_append = False
-                                native.audio_buffer.clear_force_listen()
-                                session.reset_overlap_speech()
-                                native.input_since_commit = False
-                                native.speech_since_commit = False
-                                await actor.cancel_append_tasks()
-                                had_native_stream = native.data_plane_task is not None
-                                cancel_reason = str(decision.get("cancel_reason") or "barge_in")
-                                cancelled = await self._cancel_active_response(
-                                    session,
-                                    actor.active_response_task,
-                                    emit_event,
-                                    reason=cancel_reason,
-                                )
-                                had_native_stream = (
-                                    await self._cancel_native_data_plane_stream(session) or had_native_stream
-                                )
-                                if not cancelled and had_native_stream:
-                                    old_epoch = session.epoch
-                                    old_response_id = session.active_response_id
-                                    committed_ms = session.playback.committed_ms
-                                    self._commit_played_response_history(session, old_response_id, committed_ms)
-                                    new_epoch, old_playback = self._advance_barge_in_epoch(session)
-                                    await emit_event(
-                                        {
-                                            "type": "audio.cancelled",
-                                            "session_id": session.session_id,
-                                            "response_id": old_response_id,
-                                            "reason": cancel_reason,
-                                            "cancelled_epoch": old_epoch,
-                                            "epoch": new_epoch,
-                                            "committed_ms": committed_ms,
-                                            "playback": old_playback,
-                                        }
-                                    )
-                                    cancelled = True
-                                if not cancelled and playback_was_active:
-                                    old_epoch = session.epoch
-                                    committed_ms = session.playback.committed_ms
-                                    self._commit_played_response_history(
-                                        session, session.last_response_id, committed_ms
-                                    )
-                                    new_epoch, old_playback = self._advance_barge_in_epoch(session)
-                                    await emit_event(
-                                        {
-                                            "type": "audio.cancelled",
-                                            "session_id": session.session_id,
-                                            "response_id": session.last_response_id,
-                                            "reason": cancel_reason,
-                                            "cancelled_epoch": old_epoch,
-                                            "epoch": new_epoch,
-                                            "committed_ms": committed_ms,
-                                            "playback": old_playback,
-                                        }
-                                    )
-                                    cancelled = True
-                                if session.epoch > cancelled_fence.epoch:
-                                    if not await self._signal_runtime_session(
-                                        session,
-                                        "barge_in",
-                                        emit_event,
-                                        fence=cancelled_fence,
-                                        next_fence=DuplexFence(
-                                            session.session_id,
-                                            epoch=session.epoch,
-                                            turn_id=session.turn_id,
-                                            incarnation=session.incarnation,
-                                        ),
-                                    ):
-                                        continue
-                                actor.active_response_task = None
-                        elif not self._session_auto_responds(session) and not self._input_looks_like_speech(
-                            event, payload, session=session
-                        ):
-                            # Turn-mode only: skip silent chunks so they don't open a
-                            # response. In auto-respond (full-duplex) mode the model owns
-                            # the speak/listen decision and MUST receive silence units --
-                            # the official model typically starts speaking during the
-                            # silence after a question.
-                            # No response_id: a silence-skip listen can arrive
-                            # while a response is still streaming and must not
-                            # read as that response's terminal decision.
-                            await emit_event(
-                                {
-                                    "type": "response.listen",
-                                    "session_id": session.session_id,
-                                    "epoch": session.epoch,
-                                    "reason": "silence_or_noise",
-                                }
-                            )
-                            continue
-                        if self._should_force_listen_for_auto_response_overlap(session, event, payload):
-                            # Auto-response keeps a long-lived native Stage0 stream.
-                            # While assistant audio is still active, silence from the
-                            # browser should advance the model in listen mode rather
-                            # than letting the same stream start another assistant
-                            # segment. Speech/barge-in chunks remain model-owned.
-                            payload["force_listen"] = True
-                        if not buffer_overlap_audio:
-                            continue
-                        session.mark_user_input_activity()
-                        native.input_since_commit = True
-                        native.speech_since_commit = native.speech_since_commit or self._input_looks_like_speech(
-                            event, payload, session=session
-                        )
-                        try:
-                            raw_audio_bytes = self._native_audio_payload_size_bytes(payload)
-                            if not session.reserve_input_bytes(
-                                raw_audio_bytes,
-                                limit=self._duplex_session_config.max_pending_input_bytes_per_session,
-                            ):
-                                await emit_event(
-                                    {
-                                        "type": "error",
-                                        "error": "Duplex session pending input exceeds server limit",
-                                        "code": "input_backpressure",
-                                    }
-                                )
-                                continue
-                            allow_emit = not defer_native_append and (
-                                realtime_protocol is None
-                                or event_type != "input_audio_buffer.append"
-                                # Full-duplex: emit each ~chunk_period of audio so the model
-                                # runs per-chunk generation (speak/listen) without an explicit
-                                # response.create, matching the official duplex_generate loop.
-                                or self._session_auto_responds(session)
-                            )
-                            pcm_reservation = native.audio_buffer.prepare_append(
-                                payload,
-                                operation_id=uuid.uuid4().hex,
-                                chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
-                                allow_emit=allow_emit,
-                            )
-                        except ValueError as exc:
-                            session.release_input_bytes(raw_audio_bytes)
-                            await emit_event({"type": "error", "error": str(exc), "code": "bad_event"})
-                            continue
-                        if pcm_reservation is None:
-                            continue
-                        if pcm_reservation.byte_count == 0:
-                            session.release_input_bytes(raw_audio_bytes)
-                        payload = pcm_reservation.payload
-                    else:
-                        session.append_audio(audio, fmt=fmt, sample_rate_hz=sample_rate_hz)
-                    if native_input:
-                        await start_native_append(
-                            payload,
-                            final=False,
-                            pcm_reservation=pcm_reservation,
-                        )
-                        continue
-                    if session.capabilities.supports_input_append:
-                        await start_runtime_append(payload, final=False, mode="append_audio_chunk")
-                    continue
-
-                if event_type in {"input.commit", "input_audio_buffer.commit", "response.create"}:
-                    if (
-                        event_type == "response.create"
-                        and session.config.server_vad is not None
-                        and actor.active_response_task is not None
-                    ):
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "session_id": session.session_id,
-                                "code": "response_already_active",
-                                "error": "response.create must wait for the active response to complete",
-                            }
-                        )
-                        continue
-                    item_id = event.get("item_id")
-                    realtime_validated_audio_commit = (
-                        event_type == "input_audio_buffer.commit" and isinstance(item_id, str) and bool(item_id)
-                    )
-                    if (
-                        self._uses_native_input_append(session)
-                        and event_type in {"input.commit", "input_audio_buffer.commit"}
-                        and not await wait_for_native_append_tail()
-                    ):
-                        continue
-                    if event_type == "input_audio_buffer.commit" and event.get("is_speech") is False:
-                        native.input_since_commit = False
-                        native.speech_since_commit = False
-                        native.audio_buffer.clear()
-                        session.release_all_input_bytes()
-                        native.clear_committed_audio()
-                        await emit_event(
-                            {
-                                "type": "input.committed",
-                                "session_id": session.session_id,
-                                "item_id": item_id,
-                                "turn_id": session.turn_id,
-                                "epoch": session.epoch,
-                                "empty": True,
-                                "is_speech": False,
-                                "no_response": True,
-                            }
-                        )
-                        # No response_id: this silence listen answers an empty
-                        # commit, it is not a response terminal.
-                        await emit_event(
-                            {
-                                "type": "response.listen",
-                                "session_id": session.session_id,
-                                "epoch": session.epoch,
-                                "reason": "silence_or_noise",
-                            }
-                        )
-                        continue
-                    should_create_response = (
-                        event_type == "response.create"
-                        or bool(event.get("response_create", event_type == "input.commit"))
-                        or (event_type == "input_audio_buffer.commit" and self._session_auto_responds(session))
-                    )
-                    precreate_response_requested = event_type == "response.create" or bool(
-                        event.get("response_create", event_type == "input.commit")
-                    )
-                    if event_type == "response.create":
-                        response_payload = event.get("response")
-                        if isinstance(response_payload, dict):
-                            response_options_error = self._apply_response_create_options(session, response_payload)
-                            if response_options_error is not None:
-                                error_message = (
-                                    "The selected native duplex runtime does not support generation "
-                                    "overrides for instructions, voice, temperature, max tokens, tools, or "
-                                    "tool_choice."
-                                    if response_options_error == "unsupported_native_response_options"
-                                    else "response.create cannot reserve options while another response is active."
-                                )
-                                await emit_event(
-                                    {
-                                        "type": "error",
-                                        "session_id": session.session_id,
-                                        "epoch": session.epoch,
-                                        "code": response_options_error,
-                                        "error": error_message,
-                                    }
-                                )
-                                continue
-                    if self._uses_native_input_append(session) and event_type == "input_audio_buffer.commit":
-                        has_pending_native_audio = (
-                            native.input_since_commit
-                            or native.audio_buffer.has_pending()
-                            or native.committed_audio_payload is not None
-                            or realtime_validated_audio_commit
-                        )
-                        if (
-                            not has_pending_native_audio
-                            and not actor.native_append_tasks
-                            and native.data_plane_task is None
-                        ):
-                            await emit_event(
-                                {
-                                    "type": "error",
-                                    "session_id": session.session_id,
-                                    "epoch": session.epoch,
-                                    "code": "input_audio_buffer_empty",
-                                    "error": "input_audio_buffer.commit requires a non-empty input audio buffer.",
-                                }
-                            )
-                            continue
-                        commit_action = decide_commit_action(
-                            CommitSnapshot(
-                                auto_responds=self._session_auto_responds(session),
-                                speech_since_commit=native.speech_since_commit,
-                                active_response_id=session.active_response_id,
-                                overlap_speech_ms=session.overlap_speech_ms,
-                                native_response_in_progress=native_response_in_progress(),
-                                playback_active=self._assistant_playback_active(session),
-                            )
-                        )
-                        if commit_action is CommitAction.DEFER_ACTIVE_RESPONSE:
-                            if session.overlap_speech_ms <= session.config.overlap_short_ack_ms:
-                                native.audio_buffer.clear()
-                                session.release_all_input_bytes()
-                                native.input_since_commit = False
-                                native.speech_since_commit = False
-                                native.clear_committed_audio()
-                                if realtime_protocol is not None:
-                                    await realtime_protocol.discard_pending_input_audio(
-                                        audio_end_ms=session.overlap_speech_ms
-                                    )
-                                await emit_event(
-                                    {
-                                        "type": "input.committed",
-                                        "session_id": session.session_id,
-                                        "item_id": item_id,
-                                        "turn_id": session.turn_id,
-                                        "epoch": session.epoch,
-                                        "empty": True,
-                                        "is_speech": False,
-                                        "overlap_ack": True,
-                                        "no_response": True,
-                                    }
-                                )
-                                session.reset_overlap_speech()
-                                session.discard_response_options()
-                                continue
-
-                            commit_reservation = native.audio_buffer.prepare_commit(
-                                operation_id=uuid.uuid4().hex,
-                                chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
-                            )
-                            deferred_payload = commit_reservation.payload
-                            if deferred_payload is None:
-                                commit_reservation.commit()
-                            else:
-                                if native.committed_audio_payload is not None:
-                                    deferred_payload = self._merge_native_audio_payloads(
-                                        native.committed_audio_payload,
-                                        deferred_payload,
-                                    )
-                                native.retain_committed_audio(
-                                    deferred_payload,
-                                    operation_id=commit_reservation.operation_id,
-                                    reserved_bytes=commit_reservation.byte_count,
-                                )
-                                commit_reservation.commit()
-                                native.deferred_response_create = should_create_response
-                                native.deferred_precreate_response = precreate_response_requested
-                                native.input_since_commit = False
-                                native.speech_since_commit = False
-                                committed = self._commit_native_audio_input(
-                                    session,
-                                    item_id=event.get("item_id"),
-                                    transcript=event.get("transcript"),
-                                )
-                                committed_payload = self._native_audio_committed_payload(
-                                    session,
-                                    committed=committed,
-                                    item_id=event.get("item_id"),
-                                    transcript=event.get("transcript"),
-                                )
-                                committed_payload["overlap_deferred"] = True
-                                committed_payload["response_create_deferred"] = should_create_response
-                                await emit_event(committed_payload)
-                                continue
-                        if commit_action is CommitAction.START_AUTO_RESPONSE:
-                            commit_reservation = native.audio_buffer.prepare_commit(
-                                operation_id=uuid.uuid4().hex,
-                                chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
-                            )
-                            committed_input = commit_reservation.payload
-                            final_payload = committed_input
-                            if native.committed_audio_payload is not None:
-                                if final_payload is not None:
-                                    final_payload = self._merge_native_audio_payloads(
-                                        native.committed_audio_payload,
-                                        final_payload,
-                                    )
-                                else:
-                                    final_payload = native.committed_audio_payload
-                            commit_reservation.commit()
-                            if final_payload is not None:
-                                native.retain_committed_audio(
-                                    final_payload,
-                                    operation_id=commit_reservation.operation_id,
-                                    reserved_bytes=commit_reservation.byte_count,
-                                )
-                            native.deferred_response_create = False
-                            native.input_since_commit = False
-                            native.speech_since_commit = False
-                            data_plane_turn_id = session.turn_id
-                            committed = self._commit_native_audio_input(
-                                session,
-                                item_id=event.get("item_id"),
-                                transcript=event.get("transcript"),
-                                turn_id=data_plane_turn_id,
-                            )
-                            await emit_event(
-                                self._native_audio_committed_payload(
-                                    session,
-                                    committed=committed,
-                                    item_id=event.get("item_id"),
-                                    transcript=event.get("transcript"),
-                                )
-                            )
-                            if final_payload is not None:
-                                await start_native_append(
-                                    {
-                                        **final_payload,
-                                        "duplex_turn_id": data_plane_turn_id,
-                                    },
-                                    final=True,
-                                    precreate_response=False,
-                                    operation_id=commit_reservation.operation_id,
-                                    retained_committed_payload=final_payload,
-                                )
-                            continue
-                    if self._uses_native_input_append(session) and event_type == "response.create":
-                        if (
-                            native_response_in_progress()
-                            or actor.native_append_tasks
-                            or native.data_plane_task is not None
-                        ):
-                            if session.active_response_id is None and (
-                                session.active_request_id is not None
-                                or actor.native_append_tasks
-                                or native.data_plane_task is not None
-                            ):
-                                continue
-                            await emit_event(
-                                {
-                                    "type": "error",
-                                    "session_id": session.session_id,
-                                    "epoch": session.epoch,
-                                    "code": "response_already_active",
-                                    "error": "response.create cannot start while another response is active.",
-                                }
-                            )
-                            session.discard_response_options()
-                            continue
-                        if native.committed_audio_payload is not None:
-                            committed_payload = native.committed_audio_payload
-                            operation_id = native.committed_audio_operation_id
-                            if operation_id is None:
-                                operation_id = uuid.uuid4().hex
-                                native.committed_audio_operation_id = operation_id
-                            await start_native_append(
-                                committed_payload,
-                                final=True,
-                                precreate_response=True,
-                                operation_id=operation_id,
-                                retained_committed_payload=committed_payload,
-                            )
-                            continue
-                        await emit_event(
-                            {
-                                "type": "error",
-                                "session_id": session.session_id,
-                                "epoch": session.epoch,
-                                "code": "response_create_without_input",
-                                "error": "Native duplex response.create requires committed audio input.",
-                            }
-                        )
-                        session.discard_response_options()
-                        continue
-                    if self._uses_native_input_append(session) and not native_response_in_progress():
-                        commit_reservation = (
-                            native.audio_buffer.prepare_commit(
-                                operation_id=uuid.uuid4().hex,
-                                chunk_period_ms=session.capabilities.chunk_period_ms or 1000,
-                            )
-                            if event_type in {"input.commit", "input_audio_buffer.commit"}
-                            else None
-                        )
-                        flushed_buffer_reserved_bytes = (
-                            native.audio_buffer.pending_byte_count if commit_reservation is None else 0
-                        )
-                        flushed = (
-                            commit_reservation.payload
-                            if commit_reservation is not None
-                            else native.audio_buffer.flush(chunk_period_ms=session.capabilities.chunk_period_ms or 1000)
-                        )
-                        if native.committed_audio_payload is not None:
-                            if flushed is not None:
-                                flushed = self._merge_native_audio_payloads(
-                                    native.committed_audio_payload,
-                                    flushed,
-                                )
-                            else:
-                                flushed = native.committed_audio_payload
-                        if commit_reservation is not None:
-                            commit_reservation.commit()
-                        if flushed is not None:
-                            if self._should_force_listen_for_short_commit(session, event, flushed):
-                                flushed = dict(flushed)
-                                flushed["force_listen"] = True
-                            native.input_since_commit = False
-                            committed = self._commit_native_audio_input(
-                                session,
-                                item_id=event.get("item_id"),
-                                transcript=event.get("transcript"),
-                            )
-                            await emit_event(
-                                self._native_audio_committed_payload(
-                                    session,
-                                    committed=committed,
-                                    item_id=event.get("item_id"),
-                                    transcript=event.get("transcript"),
-                                )
-                            )
-                            if should_create_response:
-                                native.retain_committed_audio(
-                                    flushed,
-                                    operation_id=(
-                                        commit_reservation.operation_id
-                                        if commit_reservation is not None
-                                        else uuid.uuid4().hex
-                                    ),
-                                    reserved_bytes=(
-                                        commit_reservation.byte_count
-                                        if commit_reservation is not None
-                                        else flushed_buffer_reserved_bytes
-                                    ),
-                                )
-                                await start_native_append(
-                                    flushed,
-                                    final=True,
-                                    precreate_response=True,
-                                    operation_id=native.committed_audio_operation_id,
-                                    retained_committed_payload=flushed,
-                                )
-                            else:
-                                native.retain_committed_audio(
-                                    flushed,
-                                    operation_id=(
-                                        commit_reservation.operation_id
-                                        if commit_reservation is not None
-                                        else uuid.uuid4().hex
-                                    ),
-                                    reserved_bytes=(
-                                        commit_reservation.byte_count
-                                        if commit_reservation is not None
-                                        else flushed_buffer_reserved_bytes
-                                    ),
-                                )
-                                native.deferred_response_create = False
-                            continue
-                    native_had_uncommitted_audio = self._uses_native_input_append(session) and (
-                        native.input_since_commit
-                        or native.audio_buffer.has_pending()
-                        or native.committed_audio_payload is not None
-                        or realtime_validated_audio_commit
-                    )
-                    committed = session.commit_user_input()
-                    if self._uses_native_input_append(session) and event_type in {
-                        "input_audio_buffer.commit",
-                        "input.commit",
-                    }:
-                        native.input_since_commit = False
-                        native.speech_since_commit = False
-                    if committed is None and event_type != "response.create":
-                        if self._uses_native_input_append(session):
-                            committed = (
-                                self._commit_native_audio_input(
-                                    session,
-                                    item_id=event.get("item_id"),
-                                    transcript=event.get("transcript"),
-                                )
-                                if native_had_uncommitted_audio
-                                else None
-                            )
-                            await emit_event(
-                                self._native_audio_committed_payload(
-                                    session,
-                                    committed=committed,
-                                    item_id=event.get("item_id"),
-                                    transcript=event.get("transcript"),
-                                )
-                            )
-                        else:
-                            await emit_event(
-                                {
-                                    "type": "input.committed",
-                                    "session_id": session.session_id,
-                                    "item_id": item_id,
-                                    "empty": True,
-                                }
-                            )
-                        continue
-                    if committed is not None:
-                        item_id = event.get("item_id")
-                        if isinstance(item_id, str):
-                            session.register_history_item(item_id, committed.message)
-                        await emit_event(
-                            self._input_committed_payload(
-                                session,
-                                committed,
-                                item_id=item_id,
-                            )
-                        )
-                    if not should_create_response:
-                        continue
-                    if actor.active_response_task is not None and not actor.active_response_task.done():
-                        await self._cancel_active_response(
-                            session,
-                            actor.active_response_task,
-                            emit_event,
-                            reason="new_response",
-                        )
-                    if session.config.server_vad is not None and not self._uses_native_input_append(session):
-                        start_chat_response()
-                    else:
-                        actor.active_response_task = asyncio.create_task(self._run_response(session, emit_event))
-                    continue
-
-                await emit_event(
-                    {
-                        "type": "error",
-                        "error": f"Unknown duplex event: {event_type}",
-                        "code": "unknown_event",
-                    }
-                )
-
-        except WebSocketDisconnect:
-            logger.info("Duplex session disconnected")
-            transport_detached = True
-        except Exception as exc:
-            logger.exception("Duplex session failed: %s", exc)
-            with suppress(Exception):
-                await emit_event({"type": "error", "error": str(exc), "code": "internal_error"})
-        finally:
-            if realtime_protocol is not None:
-                realtime_protocol.reject_realtime_turn_detection_update()
-            if session is not None:
-                if reader_task is not None and not reader_task.done():
-                    reader_task.cancel()
-                    with suppress(asyncio.CancelledError):
-                        await reader_task
-                while pending_turn_reservations > 0:
-                    session.release_pending_turn()
-                    pending_turn_reservations -= 1
-                resumable_detach = (
-                    transport_detached
-                    and runtime_opened
-                    and not runtime_closed
-                    and session.state == DuplexSessionState.OPEN
-                    and session.capabilities.supports_session_resume
-                    and attachment_generation is not None
-                    and resume_credential_delivered
-                )
-                if resumable_detach:
-
-                    async def cancel_orphan_response_after_grace() -> None:
-                        tasks = self._session_tasks.get(session.session_id)
-                        current_session = self._registry.get(session.session_id)
-                        if tasks is None or current_session is not session or session.state != DuplexSessionState.OPEN:
-                            return
-                        await tasks.cancel_append_tasks(response_bound_only=True)
-                        await self._cancel_native_data_plane_stream(session)
-                        await self._cancel_active_response(
-                            session,
-                            tasks.active_response_task,
-                            emit_event,
-                            reason="disconnect_grace_expired",
-                            notify=False,
-                        )
-                        tasks.active_response_task = None
-
-                    detached = await self._attachment_registry.detach(
-                        session.session_id,
-                        attachment_generation=attachment_generation,
-                        on_grace_expired=cancel_orphan_response_after_grace,
-                    )
-                    touch_session = getattr(self._chat_service.engine_client, "touch_duplex_session_async", None)
-                    if detached and callable(touch_session):
-                        with suppress(Exception):
-                            await touch_session(
-                                session.session_id,
-                                fence=DuplexFence(
-                                    session.session_id,
-                                    epoch=session.epoch,
-                                    turn_id=session.turn_id,
-                                    incarnation=session.incarnation,
-                                ),
-                                activity=DuplexLeaseActivity.DETACH,
-                            )
-                else:
-                    begin_close(actor.close_reason or "disconnect")
-                    await actor.cancel_append_tasks()
-                    await self._cancel_native_data_plane_stream(session)
-                    await self._cancel_active_response(
-                        session,
-                        actor.active_response_task,
-                        emit_event,
-                        reason="disconnect",
-                        notify=False,
-                    )
-                    if runtime_opened and not runtime_closed and session.state != DuplexSessionState.CLOSED:
-                        await self._close_runtime_session(session, reason="disconnect")
-                    self._cleanup_duplex_session_state(session)
-                    self._registry.close(session.session_id)
-                    self._session_tasks.pop(session.session_id, None)
-                    self._realtime_protocols.pop(session.session_id, None)
-                    self._lease_generations.pop(session.session_id, None)
-                    self._resync_required_sessions.discard(session.session_id)
-                    with suppress(Exception):
-                        await self._attachment_registry.close(session.session_id)
-                    self._stop_lifecycle_listener_if_idle()
-            await actor.close_writer()
-            with suppress(Exception):
-                await asyncio.wait_for(actor.output_queue.join(), timeout=2.0)
-            if not writer_task.done():
-                writer_task.cancel()
-            with suppress(asyncio.CancelledError):
-                await writer_task
diff --git a/vllm_omni/entrypoints/duplex/warmup.py b/vllm_omni/entrypoints/duplex/warmup.py
index 5051a1d318c..2c138096d8f 100644
--- a/vllm_omni/entrypoints/duplex/warmup.py
+++ b/vllm_omni/entrypoints/duplex/warmup.py
@@ -43,10 +43,11 @@ async def _warmup_duplex_realtime(app, args, warmup_frames: int) -> None:
             model_name = served
         else:
             model_name = args.model
-        adapter = getattr(getattr(app.state, "openai_serving_duplex", None), "_serving_runtime_adapter", None)
-        frame_samples = int(getattr(adapter, "silence_continuation_samples", 16000))
+        # One silence unit as the engine-side plugin defines it (DuplexOmniEngine.plugin).
+        plugin = getattr(getattr(app.state.engine_client, "engine", None), "plugin", None)
+        frame_samples = int(getattr(plugin, "silence_continuation_samples", 16000))
         silence = base64.b64encode(bytes(frame_samples * 4)).decode("ascii")
-        from vllm_omni.experimental.fullduplex.client import build_realtime_url
+        from vllm_omni.clients.duplex import build_realtime_url
 
         url = (
             build_realtime_url(f"ws://127.0.0.1:{args.port}/v1/realtime", model_name, autostart=False)
diff --git a/vllm_omni/entrypoints/duplex/websocket.py b/vllm_omni/entrypoints/duplex/websocket.py
index d51a7ed57bc..8ec9cc7809a 100644
--- a/vllm_omni/entrypoints/duplex/websocket.py
+++ b/vllm_omni/entrypoints/duplex/websocket.py
@@ -1,266 +1,60 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-from __future__ import annotations
-
-import asyncio
-from collections.abc import Callable
-from dataclasses import dataclass, field
-from typing import Any
-
-from fastapi import WebSocketDisconnect
-
-INPUT_EVENTS = frozenset(
-    {
-        "input.text.append",
-        "input_audio_buffer.append",
-        "input.commit",
-        "input_audio_buffer.commit",
-        "response.create",
-    }
-)
-
-_INPUT_EVENT_ALIASES = {
-    "signal_turn": "turn.signal",
-    "close_session": "session.close",
-    "audio.playback_ack": "playback.ack",
-    "input_text.append": "input.text.append",
-    "push_text": "input.text.append",
-    "input.audio.append": "input_audio_buffer.append",
-    "push_chunk": "input_audio_buffer.append",
-}
-_WAV_AUDIO_ALIASES = frozenset({"input.audio.append", "push_chunk"})
-
+"""WebSocket transport helpers for the duplex Realtime handler.
 
-def normalize_duplex_input_event(event: dict[str, object]) -> dict[str, object]:
-    """Normalize compatibility aliases before an event enters the mailbox."""
-    event_type = event.get("type")
-    if not isinstance(event_type, str):
-        return event
-    canonical_type = _INPUT_EVENT_ALIASES.get(event_type)
-    if canonical_type is None:
-        return event
-    normalized = dict(event)
-    normalized["type"] = canonical_type
-    if event_type in _WAV_AUDIO_ALIASES:
-        normalized.setdefault("format", "wav")
-    return normalized
+The ordered session mailbox and the per-session task handles that used to be
+defined here now live engine-side (``vllm_omni.engine.duplex.session.runner``).
+"""
 
+from __future__ import annotations
 
-MODEL_OUTPUT_EVENTS = frozenset(
-    {
-        "response.created",
-        "response.listen",
-        "response.speak",
-        "response.output_item.added",
-        "response.content_part.added",
-        "response.output_audio.delta",
-        "response.output_audio.done",
-        "response.output_text.delta",
-        "response.output_text.done",
-        "response.text.delta",
-        "response.text.done",
-        "response.message",
-        "response.output_item.done",
-        "response.content_part.done",
-        "response.done",
-        "runtime.control",
-    }
-)
-DOMAIN_TERMINAL_EVENTS = frozenset(
-    {
-        "response.done",
-        "response.listen",
-        "audio.cancelled",
-        "input.cancelled",
-        "session.closed",
-    }
-)
-
+import asyncio
+from collections.abc import Awaitable, Callable
+from contextlib import suppress
 
-def is_input_event(event_type: object) -> bool:
-    return isinstance(event_type, str) and event_type in INPUT_EVENTS
+from fastapi import WebSocket, WebSocketDisconnect
 
+#: Largest client frame accepted before it is parsed (base64 audio + video frames).
+MAX_EVENT_BYTES = 15 * 1024 * 1024
 
-@dataclass(frozen=True, slots=True)
-class DuplexAppendTaskMeta:
-    epoch: int
-    mode: str
-    final: bool
-    response_bound: bool
+SendJson = Callable[[dict[str, object]], Awaitable[None]]
+CloseFn = Callable[[str], Awaitable[None]]
 
 
-@dataclass
-class DuplexSessionTasks:
-    """Connection-independent task handles for one resumable session."""
+async def receive_text_with_timeout(websocket: WebSocket, timeout_s: float | None) -> str | None:
+    """Receive one text frame; ``None`` on idle timeout. Disconnects propagate."""
+    if timeout_s is None or timeout_s <= 0:
+        return await websocket.receive_text()
+    try:
+        return await asyncio.wait_for(websocket.receive_text(), timeout=timeout_s)
+    except TimeoutError:
+        return None
 
-    native_append_tasks: dict[asyncio.Task[bool], DuplexAppendTaskMeta] = field(default_factory=dict)
-    native_append_tail: asyncio.Task[bool] | None = None
-    active_response_task: asyncio.Task[None] | None = None
 
-    def track_append_task(
-        self,
-        task: asyncio.Task[bool],
-        *,
-        epoch: int,
-        mode: str,
-        final: bool,
-        response_bound: bool,
-    ) -> None:
-        self.native_append_tasks[task] = DuplexAppendTaskMeta(epoch, mode, final, response_bound)
-        task.add_done_callback(self.native_append_tasks.pop)
+def attachment_callbacks(websocket: WebSocket) -> tuple[SendJson, CloseFn]:
+    """``send`` / ``close`` callables for a ``DuplexSessionAttachmentRegistry`` attachment.
 
-    def has_response_bound_append_tasks(self) -> bool:
-        return any(meta.response_bound for meta in self.native_append_tasks.values())
+    A send on a socket that already closed surfaces as ``WebSocketDisconnect``
+    so the caller's disconnect path runs instead of a generic failure.
+    """
 
-    async def cancel_append_tasks(self, timeout_s: float = 0.25, *, response_bound_only: bool = False) -> bool:
-        tasks = [
-            task for task, meta in self.native_append_tasks.items() if not response_bound_only or meta.response_bound
-        ]
-        if not tasks:
-            return False
-        cancelled_tail = self.native_append_tail if self.native_append_tail in tasks else None
-        for task in tasks:
-            task.cancel()
+    async def attachment_send(payload: dict[str, object]) -> None:
         try:
-            await asyncio.wait_for(asyncio.gather(*tasks, return_exceptions=True), timeout=timeout_s)
-        except TimeoutError:
-            pass
-        if cancelled_tail is not None and self.native_append_tail is cancelled_tail:
-            self.native_append_tail = None
-        return True
-
-
-@dataclass
-class DuplexWebSocketActor:
-    """Own ordered WebSocket I/O queues, but no domain identity."""
-
-    websocket: Any
-    current_epoch: Callable[[], int | None] | None = None
-    session_closed: Callable[[], bool] | None = None
-    output_queue: asyncio.Queue[dict[str, object] | None] = field(default_factory=asyncio.Queue)
-    mailbox: asyncio.Queue[dict[str, object]] = field(default_factory=asyncio.Queue)
-    outbound_protocol: Any | None = None
-    tasks: DuplexSessionTasks = field(default_factory=DuplexSessionTasks)
-    closing: bool = False
-    close_reason: str | None = None
-    stale_output_dropped: int = 0
-    _queued_input_events: int = 0
-
-    @property
-    def native_append_tasks(self) -> dict[asyncio.Task[bool], DuplexAppendTaskMeta]:
-        return self.tasks.native_append_tasks
-
-    @property
-    def active_response_task(self) -> asyncio.Task[None] | None:
-        return self.tasks.active_response_task
-
-    @active_response_task.setter
-    def active_response_task(self, task: asyncio.Task[None] | None) -> None:
-        self.tasks.active_response_task = task
-
-    @property
-    def native_append_tail(self) -> asyncio.Task[bool] | None:
-        return self.tasks.native_append_tail
-
-    @native_append_tail.setter
-    def native_append_tail(self, task: asyncio.Task[bool] | None) -> None:
-        self.tasks.native_append_tail = task
-
-    async def enqueue_event(self, event: dict[str, object]) -> None:
-        if is_input_event(event.get("type")):
-            self._queued_input_events += 1
-        await self.mailbox.put(event)
-
-    async def next_event(self) -> dict[str, object]:
-        event = await self.mailbox.get()
-        if is_input_event(event.get("type")):
-            self._queued_input_events = max(0, self._queued_input_events - 1)
-        self.mailbox.task_done()
-        return event
-
-    def has_queued_input_events(self) -> bool:
-        return self._queued_input_events > 0
-
-    async def send_json(self, payload: dict[str, object]) -> None:
-        await self.output_queue.put(payload)
-
-    async def close_writer(self) -> None:
-        await self.output_queue.put(None)
-
-    async def writer_loop(self) -> None:
-        while True:
-            payload = await self.output_queue.get()
-            try:
-                if payload is None:
-                    return
-                raw_realtime = payload.pop("_realtime_raw", False) is True
-                if not raw_realtime and self._is_stale_model_output(payload):
-                    self.stale_output_dropped += 1
-                    continue
-                try:
-                    if raw_realtime:
-                        await self.websocket.send_json(payload)
-                    elif self.outbound_protocol is not None:
-                        for projected in self.outbound_protocol.encode_outbound_event(payload):
-                            await self.websocket.send_json(projected)
-                    else:
-                        await self.websocket.send_json(payload)
-                except (WebSocketDisconnect, RuntimeError):
-                    return
-            finally:
-                self.output_queue.task_done()
-
-    def _is_stale_model_output(self, payload: dict[str, object]) -> bool:
-        event_type = payload.get("type")
-        if event_type in DOMAIN_TERMINAL_EVENTS:
-            return False
-        if event_type not in MODEL_OUTPUT_EVENTS:
-            return False
-        if self.closing and event_type not in {"response.listen", "runtime.control"}:
-            return True
-        expected_epoch = self.current_epoch() if self.current_epoch is not None else None
-        if (
-            self.session_closed is not None
-            and self.session_closed()
-            and event_type
-            not in {
-                "response.listen",
-                "runtime.control",
-            }
-        ):
-            return True
-        epoch = payload.get("epoch")
-        return isinstance(epoch, int) and isinstance(expected_epoch, int) and epoch != expected_epoch
-
-    def track_append_task(
-        self,
-        task: asyncio.Task[bool],
-        *,
-        epoch: int,
-        mode: str,
-        final: bool,
-        response_bound: bool,
-    ) -> None:
-        self.tasks.track_append_task(
-            task,
-            epoch=epoch,
-            mode=mode,
-            final=final,
-            response_bound=response_bound,
-        )
+            await websocket.send_json(payload)
+        except RuntimeError as exc:
+            message = str(exc)
+            if "after sending 'websocket.close'" in message or "response already completed" in message:
+                raise WebSocketDisconnect(code=1006) from exc
+            raise
 
-    def has_response_bound_append_tasks(self) -> bool:
-        return self.tasks.has_response_bound_append_tasks()
+    async def attachment_close(reason: str) -> None:
+        close = getattr(websocket, "close", None)
+        if callable(close):
+            with suppress(Exception):
+                await close(code=1000, reason=reason)
 
-    async def cancel_append_tasks(self, timeout_s: float = 0.25, *, response_bound_only: bool = False) -> bool:
-        return await self.tasks.cancel_append_tasks(timeout_s, response_bound_only=response_bound_only)
+    return attachment_send, attachment_close
 
 
-__all__ = [
-    "DOMAIN_TERMINAL_EVENTS",
-    "DuplexAppendTaskMeta",
-    "DuplexSessionTasks",
-    "DuplexWebSocketActor",
-    "is_input_event",
-]
+__all__ = ["MAX_EVENT_BYTES", "CloseFn", "SendJson", "attachment_callbacks", "receive_text_with_timeout"]
diff --git a/vllm_omni/entrypoints/duplex_omni.py b/vllm_omni/entrypoints/duplex_omni.py
new file mode 100644
index 00000000000..968b69f74e3
--- /dev/null
+++ b/vllm_omni/entrypoints/duplex_omni.py
@@ -0,0 +1,476 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""DuplexOmni: the Python API for full-duplex models.
+
+Sessions run inside the engine (``DuplexSessionRunner`` on the orchestrator
+loop of ``DuplexOrchestrator``). This class opens / resumes / closes them and
+pipes typed ``DuplexCommand`` objects in and typed ``DuplexEvent`` objects out
+through a ``DuplexSessionHandle``. It holds no session state beyond the
+handle registry, so the websocket handler and ``InlineDuplexClient`` are both
+thin consumers of the same surface.
+
+Example::
+
+    omni = DuplexOmni(model="openbmb/MiniCPM-o-4_5", trust_remote_code=True)
+    async with await omni.open_session({"modalities": ["audio", "text"]}) as session:
+        async def consume():
+            async for event in session.events():
+                if isinstance(event, AudioDelta):
+                    play(event.audio)
+        task = asyncio.create_task(consume())
+        await session.submit(AppendAudio(audio=pcm_bytes, format="pcm16", sample_rate_hz=16000))
+        await session.submit(Commit())
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Mapping, Sequence
+from contextlib import suppress
+from typing import Any
+from uuid import uuid4
+
+from vllm.logger import init_logger
+
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex import commands as duplex_commands
+from vllm_omni.engine.duplex.commands import DuplexCommand
+from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig, ResponseCreateOptions
+from vllm_omni.engine.duplex.events import DuplexEvent, SessionClosed
+from vllm_omni.engine.duplex.messages import (
+    DuplexControlResultMessage,
+    DuplexSessionError,
+    DuplexSessionEventMessage,
+)
+from vllm_omni.engine.duplex_omni_engine import DuplexOmniEngine
+from vllm_omni.entrypoints.async_omni import AsyncOmni
+
+logger = init_logger(__name__)
+
+_DEFAULT_CONTROL_TIMEOUT_S = 10.0
+
+
+class DuplexSessionHandle:
+    """Client-side view of one engine-resident duplex session.
+
+    Connection-independent: a websocket may detach and a later one resume the
+    same handle. ``events()`` is single-consumer at any given time but may be
+    re-entered after the previous iterator was closed (resume).
+    """
+
+    def __init__(self, omni: DuplexOmni, session_id: str) -> None:
+        self._omni = omni
+        #: Allocated by ``DuplexOmni.open_session``; unique for the engine's lifetime.
+        self.session_id = session_id
+        self.capabilities: DuplexCapabilities = DuplexCapabilities()
+        self.public_session: dict[str, object] = {}
+        self.lease_generation: int = 0
+        self._outbox: asyncio.Queue[DuplexEvent | None] = asyncio.Queue()
+        self._closed = False
+        self._close_reason: str | None = None
+        self._closed_event = asyncio.Event()
+        self._consumer_active = False
+
+    # ---- state ----
+
+    @property
+    def closed(self) -> bool:
+        return self._closed
+
+    @property
+    def close_reason(self) -> str | None:
+        return self._close_reason
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"DuplexSessionHandle(session_id={self.session_id!r}, closed={self._closed})"
+
+    # ---- input ----
+
+    async def submit(self, command: DuplexCommand) -> None:
+        """Enqueue one command in caller order; rejections arrive as ``ErrorEvent`` on ``events()``."""
+        if self._closed:
+            raise DuplexSessionError(
+                f"duplex session {self.session_id} is closed", code="session_closed", session_id=self.session_id
+            )
+        await self._omni.engine.submit_command_async(self.session_id, command)
+
+    async def append_audio(
+        self,
+        audio: bytes,
+        *,
+        format: str = "pcm16",
+        sample_rate_hz: int | None = None,
+        is_speech: bool | None = None,
+        video_frames: Sequence[str] | None = None,
+        duration_ms: int | None = None,
+        audio_end_ms: int | None = None,
+        hints: Mapping[str, object] | None = None,
+    ) -> None:
+        await self.submit(
+            duplex_commands.AppendAudio(
+                audio=audio,
+                format=format,
+                sample_rate_hz=sample_rate_hz,
+                is_speech=is_speech,
+                video_frames=tuple(video_frames or ()),
+                duration_ms=duration_ms,
+                audio_end_ms=audio_end_ms,
+                hints=dict(hints or {}),
+            )
+        )
+
+    async def append_text(self, text: str) -> None:
+        await self.submit(duplex_commands.AppendText(text=text))
+
+    async def commit(
+        self,
+        *,
+        final: bool = True,
+        create_response: bool | None = None,
+        is_speech: bool | None = None,
+    ) -> None:
+        await self.submit(duplex_commands.Commit(final=final, create_response=create_response, is_speech=is_speech))
+
+    async def create_response(self, options: ResponseCreateOptions | Mapping[str, object] | None = None) -> None:
+        if isinstance(options, ResponseCreateOptions):
+            payload: dict[str, object] = {
+                key: value
+                for key, value in (
+                    ("instructions", options.instructions),
+                    ("voice", options.voice),
+                    ("output_audio_format", options.response_format),
+                    ("temperature", options.temperature),
+                    ("max_output_tokens", options.max_tokens),
+                    ("speed", options.speed),
+                    ("modalities", list(options.modalities) if options.modalities is not None else None),
+                )
+                if value is not None
+            }
+            if options.extra_body:
+                payload["extra_body"] = dict(options.extra_body)
+        else:
+            payload = dict(options or {})
+        await self.submit(duplex_commands.CreateResponse(options=payload))
+
+    async def clear_input(self) -> None:
+        await self.submit(duplex_commands.ClearInput())
+
+    async def cancel_input(self) -> None:
+        await self.submit(duplex_commands.CancelInput())
+
+    async def cancel_response(self, response_id: str | None = None) -> None:
+        await self.submit(duplex_commands.CancelResponse(response_id=response_id))
+
+    async def barge_in(self) -> None:
+        await self.submit(duplex_commands.BargeIn())
+
+    async def clear_output_audio(self, response_id: str | None = None) -> None:
+        await self.submit(duplex_commands.ClearOutputAudio(response_id=response_id))
+
+    async def signal_turn(self, event: str, payload: Mapping[str, object] | None = None) -> None:
+        await self.submit(duplex_commands.SignalTurn(event=event, signal_payload=dict(payload or {})))
+
+    async def update(self, session_patch: Mapping[str, object]) -> None:
+        await self.submit(duplex_commands.UpdateSession(patch=dict(session_patch)))
+
+    async def ack_playback(
+        self,
+        played_ms: int,
+        *,
+        response_id: str | None = None,
+        item_id: str | None = None,
+        committed_ms: int | None = None,
+    ) -> None:
+        await self.submit(
+            duplex_commands.AckPlayback(
+                played_ms=int(played_ms),
+                committed_ms=int(committed_ms) if committed_ms is not None else None,
+                response_id=response_id,
+                item_id=item_id,
+            )
+        )
+
+    async def heartbeat(self) -> None:
+        await self.submit(duplex_commands.Heartbeat())
+
+    async def create_item(self, item: Mapping[str, object], *, previous_item_id: str | None = None) -> None:
+        await self.submit(duplex_commands.CreateItem(item=dict(item), previous_item_id=previous_item_id))
+
+    async def delete_item(self, item_id: str) -> None:
+        await self.submit(duplex_commands.DeleteItem(item_id=item_id))
+
+    async def truncate_item(self, item_id: str, *, audio_end_ms: int, content_index: int = 0) -> None:
+        await self.submit(
+            duplex_commands.TruncateItem(item_id=item_id, audio_end_ms=int(audio_end_ms), content_index=content_index)
+        )
+
+    async def close(self, *, reason: str = "client_close", timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S) -> None:
+        if self._closed:
+            return
+        await self._omni.close_session(self.session_id, reason=reason, timeout=timeout)
+
+    # ---- output ----
+
+    async def events(self) -> AsyncIterator[DuplexEvent]:
+        """Ordered public events; ends after ``session.closed`` / ``session.expired``."""
+        if self._consumer_active:
+            raise RuntimeError(f"duplex session {self.session_id} already has an active events() consumer")
+        self._consumer_active = True
+        try:
+            while True:
+                if self._closed and self._outbox.empty():
+                    return
+                event = await self._outbox.get()
+                if event is None:
+                    if self._closed and self._outbox.empty():
+                        return
+                    continue
+                yield event
+                if event.is_terminal:
+                    return
+        finally:
+            self._consumer_active = False
+
+    async def wait_closed(self) -> str:
+        await self._closed_event.wait()
+        return self._close_reason or "closed"
+
+    async def __aenter__(self) -> DuplexSessionHandle:
+        return self
+
+    async def __aexit__(self, exc_type, exc, traceback) -> None:
+        try:
+            await self.close()
+        except DuplexSessionError:
+            pass
+
+    # ---- internals used by DuplexOmni ----
+
+    def _adopt(self, result: DuplexControlResultMessage) -> None:
+        if result.capabilities is not None:
+            self.capabilities = result.capabilities
+        if result.public_session:
+            self.public_session = dict(result.public_session)
+        if result.lease_generation is not None:
+            self.lease_generation = int(result.lease_generation)
+
+    def _deliver(self, event: DuplexEvent) -> None:
+        self._outbox.put_nowait(event)
+        if isinstance(event, SessionClosed):  # SessionExpired is a SessionClosed
+            self._mark_closed(event.reason or event.type)
+
+    def _mark_closed(self, reason: str) -> None:
+        if self._closed:
+            return
+        self._closed = True
+        self._close_reason = reason
+        self._closed_event.set()
+        self._outbox.put_nowait(None)
+
+
+class DuplexOmni(AsyncOmni):
+    """Async Python API for full-duplex models (see module docstring).
+
+    Construct it like ``AsyncOmni``. The pipeline must declare
+    ``duplex_plugin`` and the deploy config ``session_mode: duplex``; the
+    engine raises at startup otherwise. There is no ``generate()``: duplex
+    serving is session-only.
+    """
+
+    engine: DuplexOmniEngine
+
+    def _create_engine(self, **engine_kwargs: Any) -> DuplexOmniEngine:
+        from vllm_omni.entrypoints.duplex.audio_encoding import encode_audio
+
+        return DuplexOmniEngine(duplex_audio_encoder=encode_audio, **engine_kwargs)
+
+    def __init__(self, model: str = "", *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, model=model, **kwargs)
+        self._handles: dict[str, DuplexSessionHandle] = {}
+
+    # ---- deployment facts ----
+
+    @property
+    def duplex_session_config(self) -> DuplexSessionRuntimeConfig:
+        return self.engine.duplex_session_config
+
+    @property
+    def duplex_capabilities(self) -> DuplexCapabilities:
+        return self.engine.duplex_capabilities
+
+    @property
+    def sessions(self) -> Mapping[str, DuplexSessionHandle]:
+        return dict(self._handles)
+
+    def active_session_count(self) -> int:
+        return sum(1 for handle in self._handles.values() if not handle.closed)
+
+    # ---- session lifecycle ----
+
+    @staticmethod
+    def _resolve_session_config(
+        config: DuplexSessionConfig | Mapping[str, object] | None,
+        *,
+        model: str,
+    ) -> DuplexSessionConfig:
+        """Build the normalized session config the engine will own (the one parse/normalize site).
+
+        A ``session_id`` / ``id`` key inside a Realtime session object is
+        ignored: Realtime clients echo the session object back, and the server
+        allocates every session id.
+        """
+        if config is None:
+            resolved = DuplexSessionConfig(model=model)
+        elif isinstance(config, DuplexSessionConfig):
+            resolved = config
+        elif isinstance(config, Mapping):
+            resolved = DuplexSessionConfig.from_realtime(config, model=model)
+        else:
+            raise TypeError(f"unsupported duplex session config: {type(config).__name__}")
+        if resolved.model is None:
+            resolved.model = model
+        return resolved.normalized()
+
+    async def open_session(
+        self,
+        config: DuplexSessionConfig | Mapping[str, object] | None = None,
+        *,
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexSessionHandle:
+        """Open an engine-resident session and return its handle.
+
+        The session id is always allocated here (``duplex-<uuid4 hex>``; never
+        reused, so the id alone identifies a session) and the handle is
+        registered before the open RPC, so the first event (``session.created``,
+        which announces the id) can never arrive before it exists.
+        """
+        session_id = f"duplex-{uuid4().hex}"
+        session_config = self._resolve_session_config(config, model=self.model)
+        handle = DuplexSessionHandle(self, session_id)
+        self._handles[session_id] = handle
+        self._final_output_handler()
+        try:
+            result = await self.engine.open_session_async(session_id, session_config, timeout=timeout)
+        except BaseException:
+            if self._handles.get(session_id) is handle:
+                self._handles.pop(session_id, None)
+            # Dropping the handle only forgets the id here. The engine may still
+            # be admitting this session -- a control timeout unregisters the RPC
+            # waiter but cannot cancel the manager's open -- so a late admission
+            # would hold an admission slot and a Stage0 reservation until idle
+            # expiry. Send the compensating close; the manager applies it
+            # immediately if the session already landed, and records it for the
+            # open to honour on arrival if not.
+            with suppress(Exception):
+                await self.engine.close_session_async(session_id, reason="open_abandoned", timeout=timeout)
+            raise
+        handle._adopt(result)
+        return handle
+
+    def get_session(self, session_id: str) -> DuplexSessionHandle | None:
+        return self._handles.get(session_id)
+
+    async def resume_session(
+        self,
+        session_id: str,
+        *,
+        expected_lease_generation: int,
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> DuplexSessionHandle:
+        """Engine lease resume (CAS on the lease generation); returns the existing handle."""
+        handle = self._require_handle(session_id)
+        result = await self.engine.resume_session_async(
+            session_id,
+            expected_lease_generation=expected_lease_generation,
+            timeout=timeout,
+        )
+        # The result carries the engine's current public session (state,
+        # epoch, turn ...), which a resumed client must see, not the open-time snapshot.
+        handle._adopt(result)
+        return handle
+
+    async def touch_session(
+        self,
+        session_id: str,
+        *,
+        activity: str = "heartbeat",
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> None:
+        self._require_handle(session_id)
+        await self.engine.touch_session_async(session_id, activity=activity, timeout=timeout)
+
+    async def detach_session(self, session_id: str, *, timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S) -> None:
+        """Start the engine-owned disconnect grace; expiry arrives as ``session.expired``."""
+        await self.touch_session(session_id, activity="detach", timeout=timeout)
+
+    async def close_session(
+        self,
+        session_id: str,
+        *,
+        reason: str = "client_close",
+        timeout: float | None = _DEFAULT_CONTROL_TIMEOUT_S,
+    ) -> None:
+        handle = self._handles.get(session_id)
+        if handle is None or handle.closed:
+            return
+        try:
+            await self.engine.close_session_async(session_id, reason=reason, timeout=timeout)
+        except Exception:
+            # The engine refused or lost the close: the handle is unusable
+            # either way, and it must not shadow the id in ``sessions``.
+            handle._mark_closed(reason)
+            self._handles.pop(session_id, None)
+            raise
+        # The manager emits session.closed after the stage cleanup, but the
+        # event travels on the output queue: wait for it so ``events()`` ends
+        # with the typed SessionClosed rather than an abrupt stop.
+        try:
+            await asyncio.wait_for(handle.wait_closed(), timeout=timeout)
+        except asyncio.TimeoutError:
+            logger.warning("[DuplexOmni] session.closed for %s did not arrive in time", session_id)
+            handle._mark_closed(reason)
+            self._handles.pop(session_id, None)
+
+    async def close_all_sessions(self, *, reason: str = "shutdown") -> None:
+        for session_id in list(self._handles):
+            try:
+                await self.close_session(session_id, reason=reason)
+            except Exception:
+                logger.exception("[DuplexOmni] failed to close session %s", session_id)
+
+    def _require_handle(self, session_id: str) -> DuplexSessionHandle:
+        handle = self._handles.get(session_id)
+        if handle is None or handle.closed:
+            raise DuplexSessionError(
+                f"unknown or closed duplex session: {session_id}", code="unknown_session", session_id=session_id
+            )
+        return handle
+
+    # ---- engine output routing ----
+
+    def _route_engine_message(self, msg: object) -> bool:
+        if not isinstance(msg, DuplexSessionEventMessage):
+            return False
+        handle = self._handles.get(msg.session_id)
+        if handle is None:
+            logger.debug("[DuplexOmni] dropping event for unknown session %s", msg.session_id)
+            return True
+        handle._deliver(msg.event)
+        if handle.closed:
+            self._handles.pop(msg.session_id, None)
+        return True
+
+    def _on_engine_dead(self, error: str) -> None:
+        for handle in list(self._handles.values()):
+            handle._mark_closed(f"engine_dead: {error}")
+        self._handles.clear()
+
+    def shutdown(self, timeout: float | None = None) -> None:
+        for handle in list(self._handles.values()):
+            handle._mark_closed("shutdown")
+        self._handles.clear()
+        super().shutdown(timeout)
+
+
+__all__ = ["DuplexOmni", "DuplexSessionHandle"]
diff --git a/vllm_omni/entrypoints/duplex_request_client.py b/vllm_omni/entrypoints/duplex_request_client.py
deleted file mode 100644
index d9e70f67213..00000000000
--- a/vllm_omni/entrypoints/duplex_request_client.py
+++ /dev/null
@@ -1,383 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import asyncio
-import time
-from collections.abc import Callable, MutableMapping
-from typing import Protocol
-
-from vllm_omni.engine.duplex.contracts import (
-    duplex_data_plane_request_info,
-    duplex_resource_request_id,
-)
-from vllm_omni.engine.duplex.lease import DuplexLeaseActivity
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.messages import ErrorMessage, OutputMessage
-from vllm_omni.entrypoints.client_request_state import ClientRequestState
-from vllm_omni.metrics.stats import OrchestratorAggregator as OrchestratorMetrics
-from vllm_omni.outputs import OmniRequestOutput
-from vllm_omni.outputs.duplex import get_duplex_output_decision
-
-
-class DuplexEnginePort(Protocol):
-    """Engine control methods required by the experimental request client.
-
-    The protocol keeps request preregistration and output collection testable
-    without coupling this component to ``AsyncOmniEngine``.
-    """
-
-    async def open_duplex_session_async(self, session_id: str, **kwargs) -> dict[str, object]: ...
-
-    async def append_duplex_input_async(self, session_id: str, **kwargs) -> dict[str, object]: ...
-
-    async def signal_duplex_turn_async(self, session_id: str, **kwargs) -> dict[str, object]: ...
-
-    async def close_duplex_session_async(self, session_id: str, **kwargs) -> dict[str, object]: ...
-
-    async def touch_duplex_session_async(self, session_id: str, **kwargs) -> dict[str, object]: ...
-
-    async def resume_duplex_session_async(self, session_id: str, **kwargs) -> dict[str, object]: ...
-
-
-class DuplexRequestOutputPort:
-    """Narrow output-processing surface owned by the AsyncOmni entrypoint."""
-
-    def __init__(
-        self,
-        *,
-        request_states: MutableMapping[str, ClientRequestState],
-        num_stages: int,
-        log_stats: bool,
-        start_output_handler: Callable[[], object],
-        process_single_result: Callable[..., OmniRequestOutput | None],
-    ) -> None:
-        self.request_states = request_states
-        self.num_stages = num_stages
-        self.log_stats = log_stats
-        self._start_output_handler = start_output_handler
-        self._process_single_result = process_single_result
-
-    def start_output_handler(self) -> None:
-        self._start_output_handler()
-
-    def process_single_result(self, *args, **kwargs) -> OmniRequestOutput | None:
-        return self._process_single_result(*args, **kwargs)
-
-
-class DuplexRequestClient:
-    """Owns duplex request identity, preregistration and output collection."""
-
-    def __init__(self, engine: DuplexEnginePort, output_port: DuplexRequestOutputPort) -> None:
-        self.engine = engine
-        self.output_port = output_port
-
-    @staticmethod
-    def request_info(result: dict[str, object]) -> tuple[str | None, int | None]:
-        return duplex_data_plane_request_info(result)
-
-    async def open(
-        self,
-        session_id: str,
-        *,
-        session_mode: str,
-        capabilities: dict[str, object] | None,
-        session_config: dict[str, object] | None,
-        runtime_config: dict[str, object] | None,
-        fence: DuplexFence,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        # Lifecycle expiry messages share the engine output channel. Start its
-        # sole dispatcher before open so an idle session can be reaped even if
-        # it never submits an append request.
-        self.output_port.start_output_handler()
-        kwargs: dict[str, object] = {
-            "session_mode": session_mode,
-            "capabilities": capabilities,
-            "session_config": session_config,
-            "fence": fence,
-            "timeout": timeout,
-        }
-        if runtime_config is not None:
-            kwargs["runtime_config"] = runtime_config
-        return await self.engine.open_duplex_session_async(session_id, **kwargs)
-
-    async def append(
-        self,
-        session_id: str,
-        *,
-        mode: str,
-        payload: object,
-        operation_id: str | None,
-        final: bool,
-        expected_epoch: int | None,
-        fence: DuplexFence,
-        timeout: float | None,
-        collect_outputs: bool,
-    ) -> dict[str, object]:
-        kwargs: dict[str, object] = {
-            "mode": mode,
-            "payload": payload,
-            "final": final,
-            "expected_epoch": expected_epoch,
-            "timeout": timeout,
-            "fence": fence,
-        }
-        if operation_id is not None:
-            kwargs["operation_id"] = operation_id
-
-        expected_request_id = duplex_resource_request_id(fence, "stage0")
-        request_state = self.output_port.request_states.get(expected_request_id)
-        created_request_state = request_state is None
-        if request_state is None:
-            request_state = ClientRequestState(expected_request_id)
-            self.output_port.request_states[expected_request_id] = request_state
-        if request_state.metrics is None:
-            wall_start_ts = time.time()
-            request_state.metrics = OrchestratorMetrics(
-                self.output_port.num_stages,
-                self.output_port.log_stats,
-                wall_start_ts,
-                max(0, self.output_port.num_stages - 1),
-            )
-            request_state.request_arrival_ts = wall_start_ts
-        self.output_port.start_output_handler()
-        try:
-            result = await self.engine.append_duplex_input_async(session_id, **kwargs)
-        except BaseException:
-            if created_request_state and request_state.queue.empty():
-                self.output_port.request_states.pop(expected_request_id, None)
-            raise
-
-        request_id, response_stage_id = duplex_data_plane_request_info(result)
-        if request_id is None:
-            if created_request_state and request_state.queue.empty():
-                self.output_port.request_states.pop(expected_request_id, None)
-            return result
-        if request_id != expected_request_id:
-            if created_request_state and request_state.queue.empty():
-                self.output_port.request_states.pop(expected_request_id, None)
-            raise RuntimeError(
-                f"duplex data-plane request id mismatch: expected {expected_request_id!r}, got {request_id!r}"
-            )
-        if not collect_outputs:
-            return result
-        outputs = await self.collect_outputs(
-            request_id,
-            request_state,
-            response_stage_id=response_stage_id,
-            timeout=timeout,
-        )
-        if outputs:
-            result = dict(result)
-            result["data_plane_outputs"] = outputs
-        return result
-
-    async def collect_registered_outputs(
-        self,
-        request_id: str,
-        *,
-        response_stage_id: int | None,
-        timeout: float | None,
-    ) -> list[OmniRequestOutput]:
-        self.output_port.start_output_handler()
-        request_state = self.output_port.request_states.get(request_id)
-        if request_state is None:
-            return []
-        return await self.collect_outputs(
-            request_id,
-            request_state,
-            response_stage_id=response_stage_id,
-            timeout=timeout,
-        )
-
-    async def signal(
-        self,
-        session_id: str,
-        *,
-        event: str,
-        fence: DuplexFence,
-        next_fence: DuplexFence | None,
-        session_config: dict[str, object] | None,
-        runtime_config: dict[str, object] | None,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        kwargs: dict[str, object] = {"event": event, "fence": fence, "timeout": timeout}
-        if next_fence is not None:
-            kwargs["next_fence"] = next_fence
-        if session_config is not None:
-            kwargs["session_config"] = session_config
-        if runtime_config is not None:
-            kwargs["runtime_config"] = runtime_config
-        result = await self.engine.signal_duplex_turn_async(session_id, **kwargs)
-        if event in {"barge_in", "input.cancel", "response.cancel"}:
-            self.output_port.request_states.pop(duplex_resource_request_id(fence, "stage0"), None)
-        return result
-
-    async def close(
-        self,
-        session_id: str,
-        *,
-        reason: str,
-        fence: DuplexFence,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        result = await self.engine.close_duplex_session_async(
-            session_id,
-            reason=reason,
-            fence=fence,
-            timeout=timeout,
-        )
-        self.output_port.request_states.pop(duplex_resource_request_id(fence, "stage0"), None)
-        return result
-
-    async def touch(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        activity: DuplexLeaseActivity,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        return await self.engine.touch_duplex_session_async(
-            session_id,
-            fence=fence,
-            activity=activity,
-            timeout=timeout,
-        )
-
-    async def resume(
-        self,
-        session_id: str,
-        *,
-        fence: DuplexFence,
-        expected_lease_generation: int,
-        timeout: float | None,
-    ) -> dict[str, object]:
-        return await self.engine.resume_duplex_session_async(
-            session_id,
-            fence=fence,
-            expected_lease_generation=expected_lease_generation,
-            timeout=timeout,
-        )
-
-    async def collect_outputs(
-        self,
-        request_id: str,
-        request_state: ClientRequestState,
-        *,
-        response_stage_id: int | None,
-        timeout: float | None,
-    ) -> list[OmniRequestOutput]:
-        deadline = None if timeout is None else time.monotonic() + timeout
-        wall_start_ts = request_state.request_arrival_ts or time.time()
-        final_stage_id = response_stage_id if response_stage_id is not None else max(0, self.output_port.num_stages - 1)
-        num_stages = max(self.output_port.num_stages, final_stage_id + 1)
-        metrics = getattr(request_state, "metrics", None) or OrchestratorMetrics(
-            num_stages,
-            self.output_port.log_stats,
-            wall_start_ts,
-            final_stage_id,
-        )
-        stage_event_cursor = metrics.stage_event_cursor(request_id)
-        request_start_ts = {request_id: wall_start_ts}
-        outputs: list[OmniRequestOutput] = []
-        while True:
-            remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
-            if remaining == 0.0:
-                break
-            try:
-                message = await asyncio.wait_for(request_state.queue.get(), timeout=remaining)
-            except asyncio.TimeoutError:
-                break
-            if isinstance(message, ErrorMessage):
-                raise RuntimeError(message.error)
-            if not isinstance(message, OutputMessage):
-                continue
-            engine_outputs = message.engine_outputs
-            is_response_stage = response_stage_id is None or message.stage_id >= response_stage_id
-            is_direct_response = self.is_direct_response(engine_outputs)
-            output_to_collect = None
-            if isinstance(engine_outputs, OmniRequestOutput):
-                output_to_collect = engine_outputs
-                if message.metrics is not None:
-                    existing_metrics = dict(output_to_collect.metrics)
-                    metrics.process_stage_metrics(
-                        result={"metrics": message.metrics},
-                        stage_type="",
-                        stage_id=message.stage_id,
-                        req_id=request_id,
-                        engine_outputs=engine_outputs,
-                        finished=message.finished,
-                        final_output_type=engine_outputs.final_output_type,
-                        output_to_yield=output_to_collect,
-                        event_cursor=stage_event_cursor,
-                    )
-                    generated_metrics = dict(output_to_collect.metrics)
-                    existing_stage_metrics = existing_metrics.get("stage_metrics")
-                    generated_stage_metrics = generated_metrics.get("stage_metrics")
-                    if isinstance(existing_stage_metrics, dict) and isinstance(generated_stage_metrics, dict):
-                        generated_metrics["stage_metrics"] = {
-                            **existing_stage_metrics,
-                            **generated_stage_metrics,
-                        }
-                    output_to_collect.metrics = {
-                        **existing_metrics,
-                        **generated_metrics,
-                    }
-            elif is_response_stage:
-                output_to_collect = self.output_port.process_single_result(
-                    message,
-                    message.stage_id,
-                    metrics,
-                    request_start_ts,
-                    wall_start_ts,
-                    final_stage_id,
-                    stage_event_cursor,
-                )
-            if output_to_collect is not None and (is_response_stage or is_direct_response):
-                if message.finished:
-                    output_to_collect.finished = True
-                outputs.append(output_to_collect)
-            if message.finished or outputs:
-                break
-        return outputs
-
-    @classmethod
-    def is_direct_response(cls, output: object) -> bool:
-        multimodal_output = cls.multimodal_output(output)
-        if not multimodal_output:
-            return False
-        return multimodal_output.get("duplex_direct_response") is True or multimodal_output.get(
-            "duplex_native_decision"
-        ) in {"listen", "speak"}
-
-    @classmethod
-    def multimodal_output(cls, output: object) -> dict[str, object]:
-        if isinstance(output, OmniRequestOutput):
-            decision = get_duplex_output_decision(output)
-            if decision is not None:
-                return dict(decision.metadata)
-            private_output = getattr(output, "_multimodal_output", None)
-            multimodal_output = output.multimodal_output
-            if isinstance(multimodal_output, dict) and multimodal_output:
-                return multimodal_output
-            inner_output = getattr(output, "request_output", None)
-            if inner_output is not None and inner_output is not output:
-                inner_multimodal_output = cls.multimodal_output(inner_output)
-                if inner_multimodal_output:
-                    return inner_multimodal_output
-            if isinstance(private_output, dict):
-                return private_output
-            return multimodal_output if isinstance(multimodal_output, dict) else {}
-        multimodal_output = getattr(output, "multimodal_output", None)
-        if isinstance(multimodal_output, dict):
-            return multimodal_output
-        outputs = getattr(output, "outputs", None)
-        completion = outputs[0] if isinstance(outputs, list) and outputs else None
-        multimodal_output = getattr(completion, "multimodal_output", None) if completion is not None else None
-        return multimodal_output if isinstance(multimodal_output, dict) else {}
-
-
-__all__ = ["DuplexEnginePort", "DuplexRequestClient", "DuplexRequestOutputPort"]
diff --git a/vllm_omni/entrypoints/omni.py b/vllm_omni/entrypoints/omni.py
index cf4da3b7a82..ca9fc01962b 100644
--- a/vllm_omni/entrypoints/omni.py
+++ b/vllm_omni/entrypoints/omni.py
@@ -7,12 +7,13 @@
 import time
 import uuid
 from collections.abc import Callable, Generator, Iterable, Sequence
-from typing import TYPE_CHECKING, Literal, overload
+from typing import TYPE_CHECKING, Any, Literal, overload
 
 from tqdm.auto import tqdm
 from vllm.logger import init_logger
 from vllm.sampling_params import RequestOutputKind
 
+from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
 from vllm_omni.engine.messages import OutputMessage
 from vllm_omni.entrypoints.client_request_state import ClientRequestState
 from vllm_omni.entrypoints.omni_base import OmniBase
@@ -28,6 +29,9 @@
 class Omni(OmniBase):
     """Synchronous entrypoint for offline generation."""
 
+    def _create_engine(self, **engine_kwargs: Any) -> AsyncOmniEngine:
+        return AsyncOmniEngine(**engine_kwargs)
+
     def _maybe_force_final_only_for_llm_stages(
         self,
         sampling_params_list: Sequence[OmniSamplingParams],
diff --git a/vllm_omni/entrypoints/omni_base.py b/vllm_omni/entrypoints/omni_base.py
index ead0e6f1d1a..79217ca8bb9 100644
--- a/vllm_omni/entrypoints/omni_base.py
+++ b/vllm_omni/entrypoints/omni_base.py
@@ -19,13 +19,13 @@
 from vllm.v1.engine.exceptions import EngineDeadError, EngineGenerateError
 
 from vllm_omni.config.stage_config import merge_sampling_constraints
-from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
 from vllm_omni.engine.messages import (
     EngineQueueMessage,
     ErrorMessage,
     OutputMessage,
     StageMetricsMessage,
 )
+from vllm_omni.engine.omni_engine_base import OmniEngineBase
 from vllm_omni.entrypoints.client_request_state import ClientRequestState
 from vllm_omni.entrypoints.pd_utils import PDDisaggregationMixin
 from vllm_omni.entrypoints.utils import coerce_param_message_types, get_final_stage_id_for_e2e
@@ -66,7 +66,7 @@ def __init__(
         self.error_stage_id = error_stage_id
 
 
-def _weak_shutdown_engine(engine: AsyncOmniEngine) -> None:
+def _weak_shutdown_engine(engine: OmniEngineBase) -> None:
     """Best-effort engine cleanup for GC finalization."""
     try:
         engine.shutdown()
@@ -206,13 +206,13 @@ def __init__(
         self.tts_batch_max_items: int = kwargs.pop("tts_batch_max_items", 32)
 
         logger.info("[%s] Initializing with model %s", self.__class__.__name__, model)
-        # Construct transfer_metrics first so we can hand it to AsyncOmniEngine
+        # Construct transfer_metrics first so we can hand it to the engine
         # (which forwards it to the Orchestrator background thread for
-        # TX-side emit; see Orchestrator._forward_to_next_stage).
+        # TX-side emit; see OrchestratorBase._forward_to_next_stage).
         self.transfer_metrics = OmniTransferMetrics(model_name=model, log_stats=log_stats)
         self.prom_metrics = OmniPrometheusMetrics(model_name=model, log_stats=log_stats)
         st = time.time()
-        self.engine = AsyncOmniEngine(
+        self.engine = self._create_engine(
             model=model,
             init_timeout=init_timeout,
             stage_init_timeout=stage_init_timeout,
@@ -224,8 +224,8 @@ def __init__(
         self._shutdown_called = False
         self._weak_finalizer = weakref.finalize(self, _weak_shutdown_engine, self.engine)
         et = time.time()
-        logger.info("[%s] AsyncOmniEngine initialized in %.2f seconds", self.__class__.__name__, et - st)
-        # Authoritative: ``AsyncOmniEngine`` resolves (pipeline + deploy YAML +
+        logger.info("[%s] %s initialized in %.2f seconds", self.__class__.__name__, type(self.engine).__name__, et - st)
+        # Authoritative: the engine resolves (pipeline + deploy YAML +
         # CLI overrides) through ``StageConfigFactory`` and stores the final
         # value on ``engine.async_chunk``; mirror it here so ``--no-async-chunk``
         # (explicit ``False``) is not fallen-back-through by ``or``.
@@ -253,6 +253,10 @@ def __init__(
         # PD disaggregation state (detects if a prefill/decode stage pair is configured)
         self._init_pd_state()
 
+    def _create_engine(self, **engine_kwargs: Any) -> OmniEngineBase:
+        """Construct this entrypoint's engine (``AsyncOmniEngine`` for turn-based use)."""
+        raise NotImplementedError
+
     @property
     def num_stages(self) -> int:
         return self.engine.num_stages
diff --git a/vllm_omni/entrypoints/openai/api_server.py b/vllm_omni/entrypoints/openai/api_server.py
index 36b7544ee4e..376a9ccd28d 100644
--- a/vllm_omni/entrypoints/openai/api_server.py
+++ b/vllm_omni/entrypoints/openai/api_server.py
@@ -87,9 +87,9 @@
     shutdown_unsupported_routes,
 )
 from vllm_omni.entrypoints.async_omni import ABORT_TIMEOUT_S, AsyncOmni
-from vllm_omni.entrypoints.duplex.capability import should_enable_duplex_endpoint
 from vllm_omni.entrypoints.duplex.serving import OmniDuplexSessionHandler
 from vllm_omni.entrypoints.duplex.warmup import _warmup_duplex_realtime
+from vllm_omni.entrypoints.duplex_omni import DuplexOmni
 from vllm_omni.entrypoints.openai import app_state as openai_app_state
 from vllm_omni.entrypoints.openai.app_state import (
     ENDPOINT_LOAD_METRICS_FORMAT_HEADER_LABEL,
@@ -440,6 +440,23 @@ async def build_async_omni(
         yield async_omni
 
 
+def _is_duplex_model(model: str, kwargs: dict[str, Any]) -> bool:
+    """Whether ``model``'s pipeline declares a ``duplex_plugin`` (served by ``DuplexOmni``).
+
+    Resolution errors propagate: a duplex model whose pipeline or deploy
+    config cannot be resolved must fail startup rather than silently start a
+    turn-based server.
+    """
+    from vllm_omni.config.config_factory import StageConfigFactory
+
+    pipeline_config = StageConfigFactory.get_pipeline_config(
+        model=model,
+        trust_remote_code=bool(kwargs.get("trust_remote_code")),
+        deploy_config_path=kwargs.get("deploy_config"),
+    )
+    return bool(pipeline_config is not None and getattr(pipeline_config, "duplex_plugin", None))
+
+
 @asynccontextmanager
 async def build_async_omni_from_stage_config(
     args: TrackingNamespace,
@@ -501,7 +518,12 @@ async def build_async_omni_from_stage_config(
         kwargs.pop("robot_openpi_idle_timeout", None)
         model = kwargs.pop("model", None) or args.model
         kwargs.setdefault("log_stats", not args.disable_log_stats)
-        async_omni = AsyncOmni(model=model, **kwargs)
+        if _is_duplex_model(model, kwargs):
+            # A duplex model is always served in duplex mode: sessions over
+            # /v1/realtime?duplex=1, no turn-based HTTP routes.
+            async_omni = DuplexOmni(model=model, **kwargs)
+        else:
+            async_omni = AsyncOmni(model=model, **kwargs)
 
         # # Don't keep the dummy data in memory
         # await async_llm.reset_mm_cache()
@@ -512,6 +534,134 @@ async def build_async_omni_from_stage_config(
             async_omni.shutdown()
 
 
+async def _init_duplex_app_state(
+    engine_client: DuplexOmni,
+    state: State,
+    args: Namespace,
+    base_model_paths: list[BaseModelPath],
+    vllm_config: Any,
+    request_logger: RequestLogger | None,
+) -> None:
+    """Minimal app state for a duplex server: only the surfaces a duplex session backs."""
+    state.vllm_config = vllm_config
+    state.diffusion_engine = None
+    state.openai_serving_models = OpenAIServingModels(
+        engine_client=engine_client,  # type: ignore[arg-type]
+        base_model_paths=base_model_paths,
+        lora_modules=None,
+    )
+    state.serving_tokenization = None
+    state.serving_tokens = None
+    # Replaced by the chat init below when the model serves chat.
+    state.online_renderer = None
+    for attribute in (
+        "openai_serving_chat_batch",
+        "openai_serving_completion",
+        "openai_serving_responses",
+        "openai_serving_embedding",
+        "openai_serving_pooling",
+        "openai_serving_classification",
+        "openai_serving_scores",
+        "openai_serving_transcription",
+        "openai_serving_translation",
+        "openai_serving_speech",
+        "openai_serving_audio_generate",
+        "openai_serving_video",
+        "openai_streaming_speech",
+        "openai_streaming_video",
+        "openai_streaming_video_output",
+        "openai_serving_realtime",
+        "openai_serving_realtime_robot",
+        "anthropic_serving_messages",
+    ):
+        setattr(state, attribute, None)
+    state.openai_serving_duplex = OmniDuplexSessionHandler(duplex_omni=engine_client)
+    # One engine, both surfaces. ``DuplexOmni`` extends ``AsyncOmni``, so the
+    # ordinary chat service runs on it unchanged: a chat request is a turn-based
+    # request on the same pipeline, not a session, and costs no admission slot.
+    state.openai_serving_chat = await _init_duplex_chat(engine_client, state, args, request_logger)
+    state.enable_server_load_tracking = getattr(args, "enable_server_load_tracking", False)
+    state.server_load_metrics = 0
+    if state.openai_serving_chat is not None:
+        logger.info(
+            "Duplex mode: serving %s over /v1/realtime?duplex=1 and /v1/chat/completions",
+            engine_client.model,
+        )
+    else:
+        logger.info(
+            "Duplex mode: serving %s over /v1/realtime?duplex=1 only "
+            "(/v1/chat/completions unavailable: the model does not declare supports_chat_completions)",
+            engine_client.model,
+        )
+
+
+async def _init_duplex_chat(
+    engine_client: DuplexOmni,
+    state: State,
+    args: Namespace,
+    request_logger: RequestLogger | None,
+) -> OmniOpenAIServingChat | None:
+    """The ordinary chat service, on a duplex engine, when the model allows it.
+
+    Gated on ``DuplexCapabilities.supports_chat_completions`` so the decision
+    stays the model's: a duplex model that should not answer chat requests says
+    so in its plugin, and the route reports "not available" rather than
+    answering badly. ``endpoint_restrictions`` remains the per-deployment
+    opt-out on top of this.
+    """
+    if not engine_client.duplex_capabilities.supports_chat_completions:
+        return None
+    supported_tasks: set[str] = {"generate"}
+    if hasattr(engine_client, "get_supported_tasks"):
+        supported_tasks = set(await engine_client.get_supported_tasks())
+    if "generate" not in supported_tasks:
+        return None
+
+    resolved_chat_template = load_chat_template(args.chat_template)
+    if resolved_chat_template is None:
+        try:
+            tokenizer = await engine_client.get_tokenizer()
+        except Exception as exc:
+            logger.debug("Could not inspect tokenizer chat_template before duplex chat init: %s", exc)
+            tokenizer = None
+        if tokenizer is None or getattr(tokenizer, "chat_template", None) is None:
+            resolved_chat_template = _load_model_chat_template_json(args.model)
+
+    state.online_renderer = OnlineRenderer(
+        model_config=engine_client.model_config,
+        renderer=engine_client.renderer,
+        request_logger=request_logger,
+        chat_template=resolved_chat_template,
+        chat_template_content_format=args.chat_template_content_format,
+        trust_request_chat_template=args.trust_request_chat_template,
+        enable_auto_tools=args.enable_auto_tool_choice,
+        exclude_tools_when_tool_choice_none=args.exclude_tools_when_tool_choice_none,
+        tool_parser=args.tool_call_parser,
+        reasoning_parser=args.structured_outputs_config.reasoning_parser,
+        default_chat_template_kwargs=args.default_chat_template_kwargs,
+    )
+    return OmniOpenAIServingChat(
+        engine_client=engine_client,
+        models=state.openai_serving_models,
+        response_role=args.response_role,
+        online_renderer=state.online_renderer,
+        request_logger=request_logger,
+        chat_template=resolved_chat_template,
+        chat_template_content_format=args.chat_template_content_format,
+        default_chat_template_kwargs=args.default_chat_template_kwargs,
+        trust_request_chat_template=args.trust_request_chat_template,
+        return_tokens_as_token_ids=args.return_tokens_as_token_ids,
+        enable_auto_tools=args.enable_auto_tool_choice,
+        exclude_tools_when_tool_choice_none=args.exclude_tools_when_tool_choice_none,
+        tool_parser=args.tool_call_parser,
+        reasoning_parser=args.structured_outputs_config.reasoning_parser,
+        enable_prompt_tokens_details=args.enable_prompt_tokens_details,
+        enable_force_include_usage=args.enable_force_include_usage,
+        enable_log_outputs=args.enable_log_outputs,
+        enable_log_deltas=args.enable_log_deltas,
+    )
+
+
 async def omni_init_app_state(
     engine_client: EngineClient,
     state: State,
@@ -562,6 +712,13 @@ async def omni_init_app_state(
     state.stage_configs = engine_client.stage_configs if hasattr(engine_client, "stage_configs") else None
     model_name = served_model_names[0] if served_model_names else args.model
 
+    # Duplex mode: a duplex model is served through DuplexOmni only. Sessions
+    # run over /v1/realtime?duplex=1; every turn-based HTTP route reports
+    # "not available".
+    if isinstance(engine_client, DuplexOmni):
+        await _init_duplex_app_state(engine_client, state, args, base_model_paths, vllm_config, request_logger)
+        return
+
     # Pure Diffusion mode: use simplified initialization logic
     if is_pure_diffusion:
         state.vllm_config = None
@@ -942,17 +1099,6 @@ async def omni_init_app_state(
         else None
     )
     state.openai_serving_duplex = None
-    if state.openai_serving_chat is not None and should_enable_duplex_endpoint(
-        state.stage_configs,
-        config_path=getattr(engine_client, "config_path", None) or getattr(args, "deploy_config", None),
-    ):
-        state.openai_serving_duplex = OmniDuplexSessionHandler(
-            chat_service=state.openai_serving_chat,
-            served_model_name=model_name,
-            log_stats=state.log_stats,
-            duplex_session_config=getattr(engine_client, "duplex_session_config", None),
-            serving_runtime_adapter_path=getattr(engine_client, "duplex_serving_adapter_path", None),
-        )
     state.openai_serving_realtime = OpenAIServingRealtime(
         engine_client=engine_client,
         models=state.openai_serving_models,
@@ -1477,14 +1623,7 @@ async def streaming_video_output(websocket: WebSocket):
 @router.websocket("/v1/realtime")
 async def realtime_websocket(websocket: WebSocket):
     """WebSocket endpoint for OpenAI-style realtime interactions."""
-    # Hold real clients until the startup duplex warmup finishes (the warmup
-    # connection marks itself with vllm_omni_warmup=1 and passes through).
-    warmup_done = getattr(websocket.app.state, "duplex_warmup_done", None)
-    if warmup_done is not None and not warmup_done.is_set() and websocket.query_params.get("vllm_omni_warmup") != "1":
-        try:
-            await asyncio.wait_for(warmup_done.wait(), timeout=120)
-        except (TimeoutError, asyncio.TimeoutError):
-            logger.warning("Duplex warmup still running after 120 s; admitting the client anyway.")
+    await _wait_for_duplex_warmup(websocket)
     duplex_handler = getattr(websocket.app.state, "openai_serving_duplex", None)
     duplex_query = websocket.query_params.get("duplex")
     use_duplex_realtime = duplex_handler is not None and (
@@ -1504,6 +1643,32 @@ async def realtime_websocket(websocket: WebSocket):
     await connection.handle_connection()
 
 
+async def _wait_for_duplex_warmup(websocket: WebSocket) -> None:
+    """Hold real clients until the startup duplex warmup finishes.
+
+    The warmup connection marks itself with ``vllm_omni_warmup=1`` and passes through.
+    """
+    warmup_done = getattr(websocket.app.state, "duplex_warmup_done", None)
+    if warmup_done is not None and not warmup_done.is_set() and websocket.query_params.get("vllm_omni_warmup") != "1":
+        try:
+            await asyncio.wait_for(warmup_done.wait(), timeout=120)
+        except (TimeoutError, asyncio.TimeoutError):
+            logger.warning("Duplex warmup still running after 120 s; admitting the client anyway.")
+
+
+@router.websocket("/v1/duplex")
+async def duplex_websocket(websocket: WebSocket):
+    """Alias of ``/v1/realtime?duplex=1``: the same Realtime duplex session protocol."""
+    await _wait_for_duplex_warmup(websocket)
+    handler = getattr(websocket.app.state, "openai_serving_duplex", None)
+    if handler is None:
+        await websocket.accept()
+        await websocket.send_json({"type": "error", "error": "Duplex API is not available", "code": "unsupported"})
+        await websocket.close()
+        return
+    await handler.handle_realtime_session(websocket)
+
+
 @router.websocket("/v1/realtime/robot/openpi")
 async def realtime_robot_openpi(websocket: WebSocket):
     """WebSocket endpoint for robot policy inference via OpenPI messages."""
@@ -1534,18 +1699,6 @@ async def realtime_robot_openpi(websocket: WebSocket):
     await connection.handle_connection()
 
 
-@router.websocket("/v1/duplex")
-async def duplex_websocket(websocket: WebSocket):
-    """WebSocket endpoint for vLLM-Omni duplex session control."""
-    handler = getattr(websocket.app.state, "openai_serving_duplex", None)
-    if handler is None:
-        await websocket.accept()
-        await websocket.send_json({"type": "error", "error": "Duplex API is not available", "code": "unsupported"})
-        await websocket.close()
-        return
-    await handler.handle_session(websocket)
-
-
 # RL Rollout serving (RFC #3747, P0)
 
 
diff --git a/vllm_omni/entrypoints/openai/audio_utils_mixin.py b/vllm_omni/entrypoints/openai/audio_utils_mixin.py
index a13318ad4ae..b82842c42d9 100644
--- a/vllm_omni/entrypoints/openai/audio_utils_mixin.py
+++ b/vllm_omni/entrypoints/openai/audio_utils_mixin.py
@@ -21,7 +21,6 @@
 See ``openai/README.md`` (utils vs helpers, no overlap).
 """
 
-import math
 from io import BytesIO
 
 import numpy as np
@@ -36,6 +35,9 @@
     CreateAudio,
 )
 
+# Re-exported: serving_speech and the audio tests import it from here.
+from vllm_omni.utils.audio_resample import StreamingAudioResampler  # noqa: F401
+
 try:
     import soundfile
 except ImportError:
@@ -44,155 +46,6 @@
 logger = init_logger(__name__)
 
 
-class StreamingAudioResampler:
-    """Stateful polyphase resampler for streaming mono float audio.
-
-    Retains filter state so output is invariant to input chunk boundaries.
-    """
-
-    _half_filter_width = 10
-    _kaiser_beta = 5.0
-    _max_polyphase_factor = 2_048
-
-    def __init__(self, source_rate: int, target_rate: int):
-        if source_rate <= 0 or target_rate <= 0:
-            raise ValueError("Audio sample rates must be positive")
-        self.source_rate = source_rate
-        self.target_rate = target_rate
-        rate_gcd = math.gcd(source_rate, target_rate)
-        self._up = target_rate // rate_gcd
-        self._down = source_rate // rate_gcd
-        if max(self._up, self._down) > self._max_polyphase_factor:
-            raise ValueError("source and target sample rates have an unsupported resampling ratio")
-        self._half_len, self._phase_kernels = self._design_polyphase_filter()
-        self._history_samples = self._phase_kernels.shape[1] - 1
-        self.reset()
-
-    def _design_polyphase_filter(self) -> tuple[int, np.ndarray]:
-        if self._up == self._down:
-            return 0, np.ones((1, 1), dtype=np.float32)
-
-        max_rate = max(self._up, self._down)
-        half_len = self._half_filter_width * max_rate
-        offsets = np.arange(-half_len, half_len + 1, dtype=np.float64)
-        cutoff = 1.0 / max_rate
-        taps = cutoff * np.sinc(cutoff * offsets)
-        taps *= np.kaiser(taps.size, self._kaiser_beta)
-        taps /= np.sum(taps)
-        taps *= self._up
-        taps = np.ascontiguousarray(taps, dtype=np.float32)
-
-        phases = [taps[phase :: self._up] for phase in range(self._up)]
-        phase_width = max(phase.size for phase in phases)
-        kernels = np.zeros((self._up, phase_width), dtype=np.float32)
-        for phase_index, phase in enumerate(phases):
-            kernels[phase_index, -phase.size :] = phase[::-1]
-        return half_len, kernels
-
-    @property
-    def scratch_bytes(self) -> int:
-        pending_samples = self._ceil_div(self._input_samples * self._up, self._down) - self._output_samples
-        return max(0, pending_samples) * np.dtype(np.float32).itemsize
-
-    @staticmethod
-    def _ceil_div(numerator: int, denominator: int) -> int:
-        return -(-numerator // denominator)
-
-    def _render_outputs(
-        self,
-        combined: np.ndarray,
-        *,
-        first_output: int,
-        output_count: int,
-        input_start: int,
-    ) -> np.ndarray:
-        if output_count <= 0:
-            return np.empty(0, dtype=np.float32)
-
-        output_indexes = np.arange(first_output, first_output + output_count, dtype=np.int64)
-        filter_indexes = output_indexes * self._down + self._half_len
-        source_indexes = filter_indexes // self._up
-        phases = filter_indexes % self._up
-        windows = np.lib.stride_tricks.sliding_window_view(
-            combined,
-            self._phase_kernels.shape[1],
-        )
-        selected_windows = windows[source_indexes - input_start]
-        return np.sum(
-            selected_windows * self._phase_kernels[phases],
-            axis=1,
-            dtype=np.float32,
-        )
-
-    def _push(self, chunk: np.ndarray) -> np.ndarray:
-        if chunk.size == 0:
-            return np.empty(0, dtype=np.float32)
-        if self._flushed:
-            raise RuntimeError("cannot process audio after the resampler has been finalized; call reset first")
-
-        combined = np.concatenate((self._history, chunk))
-        next_input_samples = self._input_samples + chunk.size
-        stable_output_samples = max(
-            0,
-            self._ceil_div(next_input_samples * self._up - self._half_len, self._down),
-        )
-        output = self._render_outputs(
-            combined,
-            first_output=self._output_samples,
-            output_count=stable_output_samples - self._output_samples,
-            input_start=self._input_samples,
-        )
-        if self._history_samples:
-            self._history = combined[-self._history_samples :].copy()
-        self._input_samples = next_input_samples
-        self._output_samples = stable_output_samples
-        return output
-
-    def _flush(self) -> np.ndarray:
-        if self._flushed:
-            return np.empty(0, dtype=np.float32)
-
-        total_output_samples = self._ceil_div(self._input_samples * self._up, self._down)
-        output_count = total_output_samples - self._output_samples
-        if output_count:
-            last_output = total_output_samples - 1
-            last_source_index = (last_output * self._down + self._half_len) // self._up
-            right_padding = max(0, last_source_index - self._input_samples + 1)
-            combined = np.concatenate((self._history, np.zeros(right_padding, dtype=np.float32)))
-            output = self._render_outputs(
-                combined,
-                first_output=self._output_samples,
-                output_count=output_count,
-                input_start=self._input_samples,
-            )
-        else:
-            output = np.empty(0, dtype=np.float32)
-        self._output_samples = total_output_samples
-        self._flushed = True
-        return output
-
-    def process(self, audio: np.ndarray, *, final: bool = False) -> np.ndarray:
-        chunk = np.asarray(audio, dtype=np.float32)
-        if chunk.ndim != 1:
-            raise ValueError(f"Streaming audio resampling only supports mono audio, got shape {chunk.shape}")
-        chunk = np.ascontiguousarray(chunk, dtype=np.float32)
-        output = self._push(chunk)
-        if not final:
-            return output
-        tail = self._flush()
-        if not output.size:
-            return tail
-        if not tail.size:
-            return output
-        return np.concatenate((output, tail))
-
-    def reset(self) -> None:
-        self._history = np.zeros(self._history_samples, dtype=np.float32)
-        self._input_samples = 0
-        self._output_samples = 0
-        self._flushed = False
-
-
 class AudioMixin:
     """Mixin class to add audio-related utilities."""
 
diff --git a/vllm_omni/experimental/fullduplex/README.md b/vllm_omni/experimental/fullduplex/README.md
index b6c918fd622..b710924f1ed 100644
--- a/vllm_omni/experimental/fullduplex/README.md
+++ b/vllm_omni/experimental/fullduplex/README.md
@@ -16,16 +16,20 @@ video_stacking.py  camera-frame tiling for omni duplex video input
 To run JoyVL, see
 [`recipes/JD/JoyAI-VL-Interaction.md`](../../../recipes/JD/JoyAI-VL-Interaction.md).
 
-The MiniCPM-o 4.5 and PersonaPlex native full-duplex runtimes graduated out
-of this package. They now live in the stable tree:
+The native full-duplex runtimes graduated out of this package. They now live
+in the stable tree, where sessions are engine-resident (RFC
+[vllm-omni#7181](https://github.com/vllm-project/vllm-omni/issues/7181)):
 
 ```text
-vllm_omni/engine/duplex/                       engine control plane, sessions, leases
-vllm_omni/entrypoints/duplex/           WebSocket serving and Realtime projection
-vllm_omni/entrypoints/duplex_request_client.py request/output lifecycle
-vllm_omni/model_executor/models/minicpmo_4_5/duplex/  MiniCPM adapter
-vllm_omni/model_executor/models/personaplex/duplex/   PersonaPlex adapter
-vllm_omni/model_executor/models/nemotron_voicechat/duplex/  Nemotron VoiceChat adapter
+vllm_omni/engine/duplex/                       sessions, manager, runner, leases, typed contract
+vllm_omni/engine/duplex_omni_engine.py         DuplexOmniEngine (session message surface)
+vllm_omni/engine/duplex_orchestrator.py        DuplexOrchestrator (hosts the session manager)
+vllm_omni/entrypoints/duplex_omni.py           DuplexOmni + DuplexSessionHandle (Python API)
+vllm_omni/entrypoints/duplex/                  WebSocket transport (attachments, resume, replay)
+vllm_omni/clients/duplex.py                    DuplexClient / DuplexClientBase
+vllm_omni/model_executor/models/minicpmo_4_5/duplex/  MiniCPM-o 4.5 DuplexModelPlugin
+vllm_omni/model_executor/models/personaplex/duplex/   PersonaPlex (pre-framework, not ported yet)
+vllm_omni/model_executor/models/nemotron_voicechat/duplex/  Nemotron VoiceChat (pre-framework, not ported yet)
 vllm_omni/model_executor/duplex_sampling.py    AR-runner sampling hook helper
 vllm_omni/outputs/duplex.py                    typed output decision envelope
 ```
@@ -51,6 +55,9 @@ only model policy.
 3. Promote a helper from a model package up into `core/` only once a second
    model actually needs it.
 
-For production serving, prefer the stable plugin seams instead
-(`duplex_serving_adapter` / `duplex_runtime_extension` dotted strings in the
-model's `pipeline.py`), as MiniCPM-o 4.5 and PersonaPlex do.
+For production serving, prefer the stable plugin seam instead: implement one
+`vllm_omni.engine.duplex.plugin.DuplexModelPlugin` and name it in the model's
+`pipeline.py` as `duplex_plugin`, as MiniCPM-o 4.5 does. PersonaPlex and
+Nemotron VoiceChat still carry their pre-framework duplex code and are ported
+to the plugin contract in follow-up PRs. The contract is documented in
+[`docs/design/fullduplex.md`](../../../docs/design/fullduplex.md).
diff --git a/vllm_omni/model_executor/duplex_sampling.py b/vllm_omni/model_executor/duplex_sampling.py
index 7dbc185d127..dd48431f6d8 100644
--- a/vllm_omni/model_executor/duplex_sampling.py
+++ b/vllm_omni/model_executor/duplex_sampling.py
@@ -19,7 +19,6 @@ class DuplexSamplingRow:
     row_idx: int
     request_id: str
     session_id: str | None
-    incarnation: int
     seq: int | None
     payload: dict[str, object] | None
     max_tokens: int | None
@@ -73,10 +72,6 @@ def rows(self, runner: object) -> tuple[DuplexSamplingRow, ...]:
             session_id = duplex.get("session_id")
             if not isinstance(session_id, str) or not session_id:
                 session_id = None
-            try:
-                incarnation = int(duplex.get("incarnation", 0))
-            except (TypeError, ValueError):
-                incarnation = 0
             try:
                 seq = int(duplex.get("seq"))
             except (TypeError, ValueError):
@@ -95,7 +90,6 @@ def rows(self, runner: object) -> tuple[DuplexSamplingRow, ...]:
                     row_idx=row_idx,
                     request_id=req_id,
                     session_id=session_id,
-                    incarnation=incarnation,
                     seq=seq,
                     payload=payload,
                     max_tokens=max_tokens if max_tokens > 0 else None,
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/__init__.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/__init__.py
index b681ad51e5d..e38cc12ef0a 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/__init__.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/__init__.py
@@ -1,15 +1,15 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-from .adapter import MiniCPMO45ClientRuntimeConfigError, MiniCPMO45NativeDuplexServingAdapter
 from .input import MiniCPMO45PcmAppendBuffer
+from .plugin import MiniCPMO45ClientRuntimeConfigError, MiniCPMO45DuplexPlugin
 from .policy import MiniCPMO45DuplexPolicy
 from .stage0 import MiniCPMO45Stage0DuplexRuntime
 
 __all__ = [
-    "MiniCPMO45DuplexPolicy",
-    "MiniCPMO45NativeDuplexServingAdapter",
     "MiniCPMO45ClientRuntimeConfigError",
+    "MiniCPMO45DuplexPlugin",
+    "MiniCPMO45DuplexPolicy",
     "MiniCPMO45PcmAppendBuffer",
     "MiniCPMO45Stage0DuplexRuntime",
 ]
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/adapter.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/adapter.py
deleted file mode 100644
index 758beafc9db..00000000000
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/adapter.py
+++ /dev/null
@@ -1,335 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import base64
-from copy import deepcopy
-from typing import Any
-
-import numpy as np
-from vllm.multimodal.media import MediaConnector
-
-from vllm_omni.entrypoints.duplex.protocol import DuplexSessionConfig, native_duplex_opt_in
-from vllm_omni.entrypoints.duplex.runtime_adapter import (
-    ServingRuntimeConfigError,
-    reject_changed_runtime_value,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.policy import MiniCPMO45DuplexPolicy
-
-
-class MiniCPMO45ClientRuntimeConfigError(ServingRuntimeConfigError):
-    pass
-
-
-class MiniCPMO45NativeDuplexServingAdapter:
-    """Serving-side MiniCPM-o 4.5 native duplex session preparation.
-
-    The generic duplex WebSocket handler should not let client-supplied local
-    paths reach workers.  This adapter follows the existing media connector
-    boundary: serving resolves client media URIs, then workers receive only
-    normalized PCM payloads.  Server-owned model assets remain local paths here.
-    """
-
-    PRIVATE_RUNTIME_CONFIG_KEYS = frozenset(
-        {
-            "duplex_stage_sampling_params",
-            "duplex_stage_max_tokens",
-            "duplex_stage0_max_tokens",
-            "duplex_scheduler_token_id",
-            "duplex_first_append_context_tokens",
-            "ref_audio_data",
-            "ref_audio_format",
-            "ref_audio_sample_rate_hz",
-            "initial_user_text",
-        }
-    )
-
-    @classmethod
-    def is_enabled(cls, config: DuplexSessionConfig) -> bool:
-        return native_duplex_opt_in(config.extra_body) is True
-
-    @classmethod
-    def validate_client_config(cls, config: DuplexSessionConfig) -> None:
-        cls.validate_client_extra_body(config.extra_body)
-
-    @classmethod
-    def validate_client_extra_body(cls, extra_body: object) -> None:
-        if not isinstance(extra_body, dict):
-            return
-        private_keys = sorted(cls.PRIVATE_RUNTIME_CONFIG_KEYS.intersection(extra_body))
-        if private_keys:
-            raise MiniCPMO45ClientRuntimeConfigError(
-                "native duplex runtime configuration is server-owned: " + ", ".join(private_keys)
-            )
-
-    @classmethod
-    def runtime_config_for_update(
-        cls,
-        config: DuplexSessionConfig,
-        current: object,
-    ) -> dict[str, object]:
-        runtime_config = deepcopy(dict(current)) if isinstance(current, dict) else {}
-        reject_changed_runtime_value(
-            config.instructions,
-            runtime_config.get("instructions"),
-            message="instructions cannot be changed after the session is created",
-            code="instructions_update_unsupported",
-            error_cls=MiniCPMO45ClientRuntimeConfigError,
-        )
-        stage_max_tokens = runtime_config.get("duplex_stage_max_tokens")
-        stage_max_tokens = deepcopy(stage_max_tokens) if isinstance(stage_max_tokens, dict) else {}
-        stage_max_tokens["0"] = (
-            config.max_tokens if isinstance(config.max_tokens, int) and config.max_tokens > 0 else 20
-        )
-        stage_max_tokens.setdefault("1", 8192)
-        runtime_config["duplex_stage_max_tokens"] = stage_max_tokens
-
-        stage_sampling = runtime_config.get("duplex_stage_sampling_params")
-        stage_sampling = deepcopy(stage_sampling) if isinstance(stage_sampling, dict) else {}
-        stage0 = stage_sampling.get("0")
-        stage0 = deepcopy(stage0) if isinstance(stage0, dict) else {}
-        stage0["temperature"] = config.temperature if config.temperature is not None else 0.7
-        stage_sampling["0"] = stage0
-        runtime_config["duplex_stage_sampling_params"] = stage_sampling
-        return runtime_config
-
-    @classmethod
-    async def prepare_runtime_config(cls, config: DuplexSessionConfig, *, model_config: Any) -> dict[str, object]:
-        extra_body = dict(config.extra_body)
-        if any(key in extra_body for key in ("ref_audio_path", "tts_ref_audio_path")):
-            raise ValueError("ref_audio_path is not accepted by native duplex; use ref_audio URI instead")
-        cls.validate_client_config(config)
-        runtime_config: dict[str, object] = {"instructions": config.instructions}
-        initial_user_text = extra_body.pop("duplex_initial_user_text", None)
-        if isinstance(initial_user_text, str) and initial_user_text:
-            runtime_config["initial_user_text"] = initial_user_text
-        cls._apply_default_scheduler_policy(runtime_config, config=config, model_config=model_config)
-
-        ref_audio = config.ref_audio
-        extra_ref_audio = extra_body.get("ref_audio")
-        if ref_audio is None and isinstance(extra_ref_audio, str):
-            extra_body.pop("ref_audio")
-            ref_audio = extra_ref_audio
-        extra_tts_ref_audio = extra_body.get("tts_ref_audio")
-        if ref_audio is None and isinstance(extra_tts_ref_audio, str):
-            extra_body.pop("tts_ref_audio")
-            ref_audio = extra_tts_ref_audio
-
-        if ref_audio is None:
-            if any(str(modality).lower() == "audio" for modality in config.modalities):
-                raise MiniCPMO45ClientRuntimeConfigError(
-                    "MiniCPM-o native duplex audio output requires ref_audio",
-                    code="ref_audio_required",
-                )
-            cls._apply_first_append_context_tokens(
-                runtime_config,
-                model_config=model_config,
-                instructions=config.instructions,
-                initial_user_text=initial_user_text,
-                ref_sample_count=None,
-            )
-            config.extra_body = extra_body
-            return runtime_config
-        else:
-            wav_np, sr = await cls.resolve_ref_audio(ref_audio, model_config=model_config)
-
-        wav_np = cls.normalize_ref_audio(wav_np, int(sr), target_sr=16000)
-        # Trim to a whole number of pooled audio embeddings (100 ms frames) so
-        # the first-append scheduler reserve can count them exactly.
-        usable = (len(wav_np) // MiniCPMO45DuplexPolicy.SAMPLES_PER_AUDIO_TOKEN) * (
-            MiniCPMO45DuplexPolicy.SAMPLES_PER_AUDIO_TOKEN
-        )
-        wav_np = wav_np[:usable]
-        ref_audio_bytes = np.ascontiguousarray(wav_np, dtype=np.float32).tobytes()
-        runtime_config["ref_audio_data"] = base64.b64encode(ref_audio_bytes).decode("ascii")
-        runtime_config["ref_audio_format"] = "pcm_f32le"
-        runtime_config["ref_audio_sample_rate_hz"] = 16000
-        cls._apply_first_append_context_tokens(
-            runtime_config,
-            model_config=model_config,
-            instructions=config.instructions,
-            initial_user_text=initial_user_text,
-            ref_sample_count=len(wav_np),
-        )
-        config.extra_body = extra_body
-        config.ref_audio = None
-        return runtime_config
-
-    @classmethod
-    def _apply_default_scheduler_policy(
-        cls,
-        runtime_config: dict[str, object],
-        *,
-        config: DuplexSessionConfig,
-        model_config: Any,
-    ) -> None:
-        stage0_max_tokens = config.max_tokens if isinstance(config.max_tokens, int) and config.max_tokens > 0 else 20
-        runtime_config["duplex_stage_max_tokens"] = {"0": stage0_max_tokens, "1": 8192}
-        stage0_params: dict[str, object] = {
-            "temperature": config.temperature if config.temperature is not None else 0.7,
-            "top_p": 0.8,
-            "top_k": 20,
-            "repetition_penalty": 1.05,
-        }
-        stop_token_ids = cls._native_stage0_stop_token_ids(model_config)
-        if stop_token_ids:
-            stage0_params["stop_token_ids"] = stop_token_ids
-        # Stage 1 keeps the deploy YAML's codec knobs, minus upstream's
-        # min_new_token=50: that floor is for whole-utterance chat TTS, while a
-        # duplex chunk is 26 codec samples, so check_stop would never release
-        # the Talker and Thinker would stall on the next model turn.
-        runtime_config["duplex_stage_sampling_params"] = {"0": stage0_params, "1": {"min_tokens": 0}}
-        scheduler_token_id = cls._native_scheduler_token_id(model_config)
-        if scheduler_token_id is not None:
-            runtime_config["duplex_scheduler_token_id"] = scheduler_token_id
-
-    @classmethod
-    def _apply_first_append_context_tokens(
-        cls,
-        runtime_config: dict[str, object],
-        *,
-        model_config: Any,
-        instructions: object,
-        initial_user_text: object,
-        ref_sample_count: int | None,
-    ) -> None:
-        """Precompute the exact session-context token count for the engine.
-
-        The first data-plane append carries the system template and optional
-        reference-audio embeddings ahead of the first unit. The engine
-        reserves scheduler slots from this count; an inexact count turns into
-        pad embeddings inside the model KV (surplus) or truncated context
-        (deficit), so it is computed with the same template and pooling math
-        the worker uses.
-        """
-        if "duplex_first_append_context_tokens" in runtime_config:
-            return
-        tokenizer = cls._load_native_tokenizer(model_config)
-        if tokenizer is None:
-            return
-        prefix, suffix = MiniCPMO45DuplexPolicy.session_context_texts(
-            instructions,
-            ref_sample_count is not None,
-            initial_user_text,
-        )
-        try:
-            prefix_ids = tokenizer.encode(prefix, add_special_tokens=False)
-            suffix_ids = tokenizer.encode(suffix, add_special_tokens=False)
-        except Exception:
-            return
-        ref_tokens = MiniCPMO45DuplexPolicy.audio_token_count(ref_sample_count or 0)
-        runtime_config["duplex_first_append_context_tokens"] = len(prefix_ids) + ref_tokens + len(suffix_ids)
-
-    @staticmethod
-    def _native_stage0_stop_token_ids(model_config: Any) -> list[int]:
-        tokenizer = MiniCPMO45NativeDuplexServingAdapter._load_native_tokenizer(model_config)
-        if tokenizer is None:
-            return []
-        out: list[int] = []
-        stop_token_fields = (
-            "chunk_eos_token_id",
-            "chunk_tts_eos_token_id",
-            "listen_token_id",
-            "turn_eos_token_id",
-        )
-        for field in stop_token_fields:
-            token = MiniCPMO45DuplexPolicy.SPECIAL_TOKEN_FIELDS[field]
-            token_id = MiniCPMO45NativeDuplexServingAdapter._convert_token_to_id(tokenizer, token)
-            if token_id is not None and token_id not in out:
-                out.append(token_id)
-        return out
-
-    @staticmethod
-    def _native_scheduler_token_id(model_config: Any) -> int | None:
-        tokenizer = MiniCPMO45NativeDuplexServingAdapter._load_native_tokenizer(model_config)
-        if tokenizer is None:
-            return None
-        scheduler_tokens = (
-            MiniCPMO45DuplexPolicy.SPECIAL_TOKEN_FIELDS["unit_token_id"],
-            MiniCPMO45DuplexPolicy.OPTIONAL_TOKEN_FIELDS["audio_placeholder_token_id"],
-        )
-        for token in scheduler_tokens:
-            token_id = MiniCPMO45NativeDuplexServingAdapter._convert_token_to_id(tokenizer, token)
-            if token_id is not None:
-                return token_id
-        eos_id = getattr(tokenizer, "eos_token_id", None)
-        if eos_id is None:
-            return None
-        try:
-            return int(eos_id)
-        except (TypeError, ValueError):
-            return None
-
-    @staticmethod
-    def _load_native_tokenizer(model_config: Any) -> Any | None:
-        model_path = getattr(model_config, "model", None)
-        if not isinstance(model_path, str) or not model_path:
-            return None
-        try:
-            from transformers import AutoTokenizer
-
-            return AutoTokenizer.from_pretrained(
-                model_path,
-                trust_remote_code=True,
-                local_files_only=True,
-            )
-        except Exception:
-            return None
-
-    @staticmethod
-    def _convert_token_to_id(tokenizer: Any, token: str) -> int | None:
-        convert = getattr(tokenizer, "convert_tokens_to_ids", None)
-        value = None
-        if callable(convert):
-            value = convert(token)
-            if isinstance(value, list):
-                value = value[0] if len(value) == 1 else None
-        if value is None:
-            token_id = -1
-        else:
-            try:
-                token_id = int(value)
-            except (TypeError, ValueError):
-                token_id = -1
-        unk_token_id = getattr(tokenizer, "unk_token_id", None)
-        if token_id >= 0 and token_id != unk_token_id:
-            return token_id
-        encode = getattr(tokenizer, "encode", None)
-        if callable(encode):
-            try:
-                ids = list(encode(token, add_special_tokens=False))
-            except TypeError:
-                ids = list(encode(token))
-            if len(ids) == 1:
-                try:
-                    token_id = int(ids[0])
-                except (TypeError, ValueError):
-                    token_id = -1
-                if token_id >= 0 and token_id != unk_token_id:
-                    return token_id
-        return None
-
-    @staticmethod
-    async def resolve_ref_audio(ref_audio: str, *, model_config: Any) -> tuple[np.ndarray, int]:
-        connector = MediaConnector(
-            allowed_local_media_path=getattr(model_config, "allowed_local_media_path", None),
-            allowed_media_domains=getattr(model_config, "allowed_media_domains", None),
-        )
-        wav_np, sr = await connector.fetch_audio_async(ref_audio)
-        return np.asarray(wav_np, dtype=np.float32), int(sr)
-
-    @staticmethod
-    def normalize_ref_audio(wav_np: np.ndarray, sample_rate: int, *, target_sr: int) -> np.ndarray:
-        wav_np = np.asarray(wav_np, dtype=np.float32)
-        if wav_np.ndim > 1:
-            wav_np = wav_np.mean(axis=-1)
-        wav_np = wav_np.reshape(-1)
-        if sample_rate <= 0 or sample_rate == target_sr or wav_np.size == 0:
-            return wav_np.astype(np.float32, copy=False)
-        import torch
-        import torchaudio
-
-        audio = torch.from_numpy(wav_np).to(dtype=torch.float32).unsqueeze(0)
-        resampled = torchaudio.functional.resample(audio, int(sample_rate), int(target_sr))
-        return resampled.squeeze(0).cpu().numpy().astype(np.float32, copy=False)
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/capabilities.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/capabilities.py
index 66840589210..d850f4c3c81 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/capabilities.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/capabilities.py
@@ -3,7 +3,12 @@
 
 from __future__ import annotations
 
-from vllm_omni.entrypoints.duplex.protocol import DuplexCapabilities
+from vllm_omni.engine.duplex.config import DuplexCapabilities
+
+#: Silence units a text-seeded turn is given to generate on. The model speaks
+#: per audio unit, so a seeded turn still needs a clock; three units is what
+#: the benchmark harness uses for the same purpose.
+MINICPMO45_TEXT_TURN_PRIMING_UNITS = 3
 
 
 def minicpmo45_native_capabilities(*, max_sessions: int = 1) -> DuplexCapabilities:
@@ -31,11 +36,14 @@ def minicpmo45_native_capabilities(*, max_sessions: int = 1) -> DuplexCapabiliti
         supports_session_resume=True,
         session_admission_mode="engine_managed",
         supports_audio_truncate=True,
+        # The session template ends at the assistant turn, so seeded text puts
+        # the model in position to answer; it still generates per audio unit,
+        # hence the priming units.
+        supports_chat_completions=True,  # via initial_user_text
+        text_turn_priming_units=MINICPMO45_TEXT_TURN_PRIMING_UNITS,
         requires_model_runner_kv=True,
         requires_native_stage_role=True,
-        implementation_level="model_native_duplex",
         adapter_patterns=["scheduler_data_plane"],
-        input_modes=["append_audio_chunk"],
         signal_sources=["model_native", "client_event", "server_policy"],
         stage_handoff_transport="scheduler_data_plane",
         chunk_period_ms=1000,
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/compat.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/compat.py
index 9a4bcf9b0bf..5b6b5c90928 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/compat.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/compat.py
@@ -3,14 +3,12 @@
 
 from __future__ import annotations
 
-from typing import Any
 
-
-def patch_minicpmo_remote_config(config: Any) -> None:
+def patch_minicpmo_remote_config(config: object) -> None:
     """Fill config fields expected by the vLLM MiniCPM implementation."""
     seen: set[int] = set()
 
-    def patch_cfg(cfg: Any) -> None:
+    def patch_cfg(cfg: object) -> None:
         if cfg is None or id(cfg) in seen:
             return
         seen.add(id(cfg))
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/data_plane.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/data_plane.py
index d4063ff3f69..7bf51abfd23 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/data_plane.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/data_plane.py
@@ -12,6 +12,7 @@
 from vllm_omni.engine.duplex.contracts import (
     duplex_resource_request_belongs_to_session,
 )
+from vllm_omni.engine.duplex.plugin import DuplexDataPlane
 from vllm_omni.outputs.duplex import get_duplex_output_decision
 
 logger = init_logger(__name__)
@@ -44,6 +45,9 @@ class _TurnState:
 @dataclass(slots=True)
 class _RequestState:
     audio_offset: int = 0
+    #: A snapshot below ``audio_offset`` that has not been accepted as a restart
+    #: yet. See :meth:`MiniCPMO45DataPlaneSession.slice_cumulative_audio`.
+    audio_restart_candidate: int | None = None
     uses_segment_text_metadata: bool = False
     pending_audio_without_text: list[dict[str, object]] = field(default_factory=list)
     terminal: bool = False
@@ -53,7 +57,7 @@ def turn(self, turn_id: int | None) -> _TurnState:
         return self.turns.setdefault(turn_id, _TurnState())
 
 
-class MiniCPMO45DataPlaneSession:
+class MiniCPMO45DataPlaneSession(DuplexDataPlane):
     """MiniCPM output projector and request/turn cursor owner.
 
     The scheduler request owns cumulative Stage1 audio, while model turns own
@@ -487,13 +491,33 @@ def slice_cumulative_audio(self, request_id: str | None, audio_data: object) ->
         prev_samples = state.audio_offset
         if prev_samples <= 0:
             state.audio_offset = num_samples
+            state.audio_restart_candidate = None
             return audio_data
         if num_samples == prev_samples:
             return None
         if num_samples < prev_samples:
+            # Below the cursor means one of two things, and they are not
+            # distinguishable from this snapshot alone: the producer restarted
+            # its buffer, or this is a unit that carries no cumulative audio at
+            # all (a continuation placeholder arrives as a single sample).
+            # Rewinding the cursor for the second case is expensive and silent:
+            # the next real snapshot is then sliced from ~0 and the whole
+            # session's audio goes out again as one delta. So defer the
+            # decision — hold the candidate and leave the cursor where it is.
+            candidate = state.audio_restart_candidate
+            if candidate is None or num_samples <= candidate:
+                state.audio_restart_candidate = num_samples
+                return audio_data
+            # A second below-cursor snapshot that grew from the first: the
+            # producer really did restart, and this is its delta.
+            state.audio_offset = num_samples
+            state.audio_restart_candidate = num_samples
+            prev_samples = candidate
+        else:
+            # Above the cursor: whatever the dip was, this stream never
+            # restarted, so it is sliced from the cursor as usual.
+            state.audio_restart_candidate = None
             state.audio_offset = num_samples
-            return audio_data
-        state.audio_offset = num_samples
         try:
             import torch
 
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/input.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/input.py
index 1b30ec4c2af..4feb8cb9753 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/input.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/input.py
@@ -6,9 +6,11 @@
 import base64
 import binascii
 from dataclasses import dataclass
-from typing import Any
 
 import numpy as np
+from numpy.typing import NDArray
+
+from vllm_omni.engine.duplex.plugin import PcmAppendBuffer, PcmAppendReservation
 
 
 @dataclass(frozen=True, slots=True)
@@ -18,7 +20,7 @@ class _PcmSpan:
     is_speech: bool
 
 
-class MiniCPMO45PcmAppendReservation:
+class MiniCPMO45PcmAppendReservation(PcmAppendReservation):
     __slots__ = (
         "_active",
         "_force_listen",
@@ -74,7 +76,7 @@ def rollback(self) -> None:
         self._owner._rollback_reservation(self)
 
 
-def validate_native_ref_audio_config(session_config: dict[str, Any]) -> None:
+def validate_native_ref_audio_config(session_config: dict[str, object]) -> None:
     extra_body = session_config.get("extra_body")
     if not isinstance(extra_body, dict):
         extra_body = {}
@@ -84,7 +86,7 @@ def validate_native_ref_audio_config(session_config: dict[str, Any]) -> None:
         raise ValueError("native duplex ref_audio_path is not accepted; resolve ref_audio in serving first")
 
 
-def decode_native_ref_audio_from_config(session_config: dict[str, Any]) -> np.ndarray | None:
+def decode_native_ref_audio_from_config(session_config: dict[str, object]) -> NDArray[np.float32] | None:
     validate_native_ref_audio_config(session_config)
     extra_body = session_config.get("extra_body")
     if not isinstance(extra_body, dict):
@@ -106,7 +108,7 @@ def decode_native_ref_audio_from_config(session_config: dict[str, Any]) -> np.nd
     return np.frombuffer(raw, dtype="<f4").astype(np.float32, copy=True)
 
 
-class MiniCPMO45PcmAppendBuffer:
+class MiniCPMO45PcmAppendBuffer(PcmAppendBuffer):
     """Accumulates short native-duplex PCM chunks into model-sized appends."""
 
     def __init__(self) -> None:
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py
new file mode 100644
index 00000000000..6736404610d
--- /dev/null
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py
@@ -0,0 +1,773 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""MiniCPM-o 4.5 full-duplex model plugin: engine policy and session policy in one class.
+
+Engine policy (scheduler token budget, resumable Stage0 prompt, listen
+decision) and session policy (client config validation, reference-audio
+resolution, per-stage sampling knobs) both run engine-side, so one class owns
+them. Client-supplied media URIs are resolved here through the media
+connector; workers only ever receive normalized PCM payloads.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+from base64 import b64decode
+from binascii import Error as BinasciiError
+from collections.abc import Mapping
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, cast
+
+import numpy as np
+from numpy.typing import NDArray
+from vllm.multimodal.media import MediaConnector
+from vllm.sampling_params import SamplingParams
+
+from vllm_omni.engine.duplex.config import DuplexCapabilities, DuplexSessionConfig
+from vllm_omni.engine.duplex.contracts import (
+    DuplexAppendPlan,
+    DuplexFence,
+    DuplexOutputAction,
+    DuplexOutputDecision,
+)
+from vllm_omni.engine.duplex.plugin import (
+    DuplexModelPlugin,
+    DuplexRuntimeConfigError,
+    EncodeAudio,
+    reject_changed_runtime_value,
+)
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.capabilities import (
+    minicpmo45_native_capabilities,
+)
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.data_plane import (
+    MiniCPMO45DataPlaneContext,
+    MiniCPMO45DataPlaneSession,
+)
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.policy import MiniCPMO45DuplexPolicy
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.session import (
+    MiniCPMO45ServingSessionState,
+)
+
+if TYPE_CHECKING:
+    import torch
+    from transformers import PreTrainedTokenizerBase
+    from vllm.config import ModelConfig
+
+_DUPLEX_CHUNK_SAMPLES = 16000
+_DUPLEX_SAMPLES_PER_AUDIO_TOKEN = 1600
+# <image> + 64 resampler embeddings + </image> per frame (max_slice_nums=1),
+# matching MiniCPMO45DuplexPolicy.VISION_TOKENS_PER_FRAME.
+_DUPLEX_VISION_TOKENS_PER_FRAME = 66
+# Official stacked pair uses max_slice_nums=[2, 1]: the current frame is HD
+# sliced (1 source + 2 patches on 960x540) and the composite is not.
+_DUPLEX_HD_SLICES_PER_BASE_FRAME = 3
+
+PRIVATE_RUNTIME_CONFIG_KEYS = frozenset(
+    {
+        "duplex_stage_sampling_params",
+        "duplex_stage_max_tokens",
+        "duplex_stage0_max_tokens",
+        "duplex_scheduler_token_id",
+        "duplex_first_append_context_tokens",
+        "ref_audio_data",
+        "ref_audio_format",
+        "ref_audio_sample_rate_hz",
+        "initial_user_text",
+    }
+)
+
+
+class MiniCPMO45ClientRuntimeConfigError(DuplexRuntimeConfigError):
+    pass
+
+
+# ---- engine policy helpers: scheduler token budget ----
+
+
+def _duplex_frame_count(payload: object) -> int:
+    if not isinstance(payload, dict):
+        return 0
+    frames = payload.get("video_frames")
+    if not isinstance(frames, list):
+        return 0
+    return sum(1 for frame in frames if isinstance(frame, str) and frame)
+
+
+def _duplex_vision_tokens(payload: object) -> int:
+    """Scheduler slots for this append's camera track.
+
+    Audio is never stacked: a unit still carries one second of soundtrack.
+    ``stack_frames`` only adds a second *image*. Official HD on that pair is
+    ``[2, 1]``, so the base frame reserves three 66-token blocks and every
+    extra frame reserves one.
+    """
+    count = _duplex_frame_count(payload)
+    if count <= 0:
+        return 0
+    if count >= 2:
+        return (_DUPLEX_HD_SLICES_PER_BASE_FRAME + (count - 1)) * _DUPLEX_VISION_TOKENS_PER_FRAME
+    return count * _DUPLEX_VISION_TOKENS_PER_FRAME
+
+
+def _duplex_pcm_sample_count(payload: object) -> int | None:
+    if not isinstance(payload, dict):
+        return None
+    audio = payload.get("audio") or payload.get("data")
+    if payload.get("format") != "pcm_f32le" or not isinstance(audio, str):
+        return None
+    try:
+        raw = b64decode(audio, validate=True)
+    except (BinasciiError, ValueError):
+        return None
+    return len(raw) // 4
+
+
+def duplex_payload_is_exact_chunks(payload: object) -> bool:
+    sample_count = _duplex_pcm_sample_count(payload)
+    return sample_count is not None and sample_count != 0 and sample_count % _DUPLEX_CHUNK_SAMPLES == 0
+
+
+def duplex_first_append_unit_count(payload: object) -> int | None:
+    sample_count = _duplex_pcm_sample_count(payload)
+    if not sample_count or sample_count % _DUPLEX_CHUNK_SAMPLES != 0:
+        return None
+    return max(1, sample_count // _DUPLEX_CHUNK_SAMPLES - 1)
+
+
+def duplex_scheduler_token_budget(payload: object, *, default: int = 64) -> int:
+    vision_tokens = _duplex_vision_tokens(payload)
+    sample_count = _duplex_pcm_sample_count(payload)
+    if sample_count is None:
+        return max(1, int(default)) + vision_tokens
+    sample_count = max(1, sample_count)
+    if sample_count % _DUPLEX_CHUNK_SAMPLES == 0:
+        units = sample_count // _DUPLEX_CHUNK_SAMPLES
+        return units * (2 + _DUPLEX_CHUNK_SAMPLES // _DUPLEX_SAMPLES_PER_AUDIO_TOKEN) + vision_tokens
+    return max(16, min(768, sample_count // _DUPLEX_SAMPLES_PER_AUDIO_TOKEN + 8)) + vision_tokens
+
+
+def duplex_first_append_context_reserve(runtime_config: object) -> int:
+    if not isinstance(runtime_config, dict):
+        return 48
+    exact = runtime_config.get("duplex_first_append_context_tokens")
+    if isinstance(exact, int) and exact >= 0:
+        return exact
+    reserve = 48
+    ref = runtime_config.get("ref_audio_data")
+    if isinstance(ref, str) and ref:
+        try:
+            raw = b64decode(ref, validate=True)
+        except (BinasciiError, ValueError):
+            raw = b""
+        if raw:
+            reserve += max(0, (len(raw) // 4) // _DUPLEX_SAMPLES_PER_AUDIO_TOKEN + 8)
+    return reserve
+
+
+def _duplex_force_listen_count(extra_body: object) -> int:
+    raw = extra_body.get("force_listen_count") if isinstance(extra_body, dict) else None
+    try:
+        return 0 if raw is None else max(0, int(raw))
+    except (TypeError, ValueError):
+        return 0
+
+
+def build_duplex_data_plane_prompt(
+    *,
+    request_id: str,
+    fence: DuplexFence,
+    session_config: dict[str, object],
+    runtime_config: dict[str, object],
+    seq: int,
+    turn_seq: int,
+    payload: object,
+    final: bool,
+) -> dict[str, object]:
+    token_budget = duplex_scheduler_token_budget(payload)
+    if seq <= 1:
+        context_reserve = duplex_first_append_context_reserve(runtime_config)
+        token_budget += context_reserve
+        first_units = duplex_first_append_unit_count(payload)
+        if first_units is not None:
+            token_budget = context_reserve + first_units * 12 - 1 + _duplex_vision_tokens(payload)
+    if seq > 1 and duplex_payload_is_exact_chunks(payload):
+        token_budget += 1
+    if final and duplex_payload_is_exact_chunks(payload):
+        token_budget += 12
+    extra_body = session_config.get("extra_body")
+    raw_token_id = runtime_config.get("duplex_scheduler_token_id")
+    try:
+        token_id = 0 if raw_token_id is None else max(0, int(raw_token_id))
+    except (TypeError, ValueError):
+        token_id = 0
+    force_listen_count = _duplex_force_listen_count(extra_body)
+    if (
+        force_listen_count > 0
+        and turn_seq <= force_listen_count
+        and isinstance(payload, dict)
+        and payload.get("force_listen") is not True
+    ):
+        payload = {**payload, "force_listen": True}
+    return {
+        "prompt_token_ids": [token_id] * token_budget,
+        "model_intermediate_buffer": {
+            "request_id": request_id,
+            "global_request_id": [fence.session_id],
+            "duplex": {
+                "fence": fence,
+                "session_id": fence.session_id,
+                "epoch": fence.epoch,
+                "seq": seq,
+                "turn_id": fence.turn_id,
+                "turn_seq": turn_seq,
+                "mode": "append_audio_chunk",
+                "payload": payload,
+                "final": final,
+                "data_plane": True,
+                "session_config": dict(session_config),
+                "runtime_config": dict(runtime_config),
+                "scheduler_token_budget": token_budget,
+                "scheduler_token_id": token_id,
+            },
+        },
+    }
+
+
+# ---- engine policy helpers: listen decision ----
+
+
+def _coerce_int(value: object) -> int | None:
+    detach = getattr(value, "detach", None)
+    if callable(detach):
+        try:
+            flat: torch.Tensor = detach().cpu().reshape(-1)
+            if flat.numel() == 0:
+                return None
+            value = flat[0].item()
+        except Exception:
+            return None
+    try:
+        return int(cast(Any, value))  # Any: duck-typed scalar (int/float/str/tensor item)
+    except (TypeError, ValueError):
+        return None
+
+
+def _coerce_int_list(value: object) -> list[int]:
+    if value is None:
+        return []
+    if hasattr(value, "detach"):
+        try:
+            value = value.detach().cpu().reshape(-1).tolist()
+        except Exception:
+            return []
+    if not isinstance(value, (list, tuple)):
+        return []
+    return [token_id for item in value if (token_id := _coerce_int(item)) is not None]
+
+
+def _first_completion(output: object) -> object | None:
+    outputs = getattr(output, "outputs", None)
+    return outputs[0] if isinstance(outputs, list) and outputs else None
+
+
+def _multimodal_output(output: object, completion: object | None) -> dict[str, object]:
+    metadata = getattr(output, "multimodal_output", None)
+    if isinstance(metadata, dict):
+        return metadata
+    metadata = getattr(completion, "multimodal_output", None) if completion is not None else None
+    return metadata if isinstance(metadata, dict) else {}
+
+
+def _special_token_ids(metadata: dict[str, object]) -> dict[str, int]:
+    sources: list[object] = [metadata.get("special_token_ids"), metadata.get("meta")]
+    sources.append(
+        {
+            key.removeprefix("meta."): value
+            for key, value in metadata.items()
+            if isinstance(key, str) and key.startswith("meta.")
+        }
+    )
+    token_ids: dict[str, int] = {}
+    for source in sources:
+        if not isinstance(source, dict):
+            continue
+        for key, value in source.items():
+            token_id = _coerce_int(value)
+            if isinstance(key, str) and token_id is not None and token_id >= 0:
+                token_ids[key] = token_id
+    return token_ids
+
+
+def _completion_token_ids(completion: object | None) -> list[int]:
+    if completion is None:
+        return []
+    for attribute in ("token_ids", "cumulative_token_ids"):
+        token_ids = _coerce_int_list(getattr(completion, attribute, None))
+        if token_ids:
+            return token_ids
+    return []
+
+
+def _stage_config_value(runtime_config: dict[str, object], key: str, stage_id: int) -> object | None:
+    raw = runtime_config.get(key)
+    if isinstance(raw, dict):
+        value = raw.get(stage_id)
+        return raw.get(str(stage_id)) if value is None else value
+    if isinstance(raw, (list, tuple)) and stage_id < len(raw):
+        return raw[stage_id]
+    return None
+
+
+# ---- session policy helpers: tokenizer / reference audio ----
+
+
+def _load_tokenizer(model_config: ModelConfig | None) -> PreTrainedTokenizerBase | None:
+    model_path = getattr(model_config, "model", None)
+    if not isinstance(model_path, str) or not model_path:
+        return None
+    try:
+        from transformers import AutoTokenizer
+
+        return AutoTokenizer.from_pretrained(
+            model_path,
+            trust_remote_code=True,
+            local_files_only=True,
+        )
+    except Exception:
+        return None
+
+
+def _convert_token_to_id(tokenizer: PreTrainedTokenizerBase, token: str) -> int | None:
+    convert = getattr(tokenizer, "convert_tokens_to_ids", None)
+    value = None
+    if callable(convert):
+        value = convert(token)
+        if isinstance(value, list):
+            value = value[0] if len(value) == 1 else None
+    if value is None:
+        token_id = -1
+    else:
+        try:
+            token_id = int(value)
+        except (TypeError, ValueError):
+            token_id = -1
+    unk_token_id = getattr(tokenizer, "unk_token_id", None)
+    if token_id >= 0 and token_id != unk_token_id:
+        return token_id
+    encode = getattr(tokenizer, "encode", None)
+    if callable(encode):
+        try:
+            ids = list(encode(token, add_special_tokens=False))
+        except TypeError:
+            ids = list(encode(token))
+        if len(ids) == 1:
+            try:
+                token_id = int(ids[0])
+            except (TypeError, ValueError):
+                token_id = -1
+            if token_id >= 0 and token_id != unk_token_id:
+                return token_id
+    return None
+
+
+def _stage0_stop_token_ids(tokenizer: PreTrainedTokenizerBase | None) -> list[int]:
+    if tokenizer is None:
+        return []
+    out: list[int] = []
+    stop_token_fields = (
+        "chunk_eos_token_id",
+        "chunk_tts_eos_token_id",
+        "listen_token_id",
+        "turn_eos_token_id",
+    )
+    for field in stop_token_fields:
+        token = MiniCPMO45DuplexPolicy.SPECIAL_TOKEN_FIELDS[field]
+        token_id = _convert_token_to_id(tokenizer, token)
+        if token_id is not None and token_id not in out:
+            out.append(token_id)
+    return out
+
+
+def _scheduler_token_id(tokenizer: PreTrainedTokenizerBase | None) -> int | None:
+    if tokenizer is None:
+        return None
+    scheduler_tokens = (
+        MiniCPMO45DuplexPolicy.SPECIAL_TOKEN_FIELDS["unit_token_id"],
+        MiniCPMO45DuplexPolicy.OPTIONAL_TOKEN_FIELDS["audio_placeholder_token_id"],
+    )
+    for token in scheduler_tokens:
+        token_id = _convert_token_to_id(tokenizer, token)
+        if token_id is not None:
+            return token_id
+    eos_id = getattr(tokenizer, "eos_token_id", None)
+    if eos_id is None:
+        return None
+    try:
+        return int(eos_id)
+    except (TypeError, ValueError):
+        return None
+
+
+async def resolve_ref_audio(ref_audio: str, *, model_config: ModelConfig | None) -> tuple[NDArray[np.float32], int]:
+    connector = MediaConnector(
+        allowed_local_media_path=getattr(model_config, "allowed_local_media_path", None),
+        allowed_media_domains=getattr(model_config, "allowed_media_domains", None),
+    )
+    wav_np, sr = await connector.fetch_audio_async(ref_audio)
+    return np.asarray(wav_np, dtype=np.float32), int(sr)
+
+
+def normalize_ref_audio(wav_np: NDArray[np.float32], sample_rate: int, *, target_sr: int) -> NDArray[np.float32]:
+    wav_np = np.asarray(wav_np, dtype=np.float32)
+    if wav_np.ndim > 1:
+        wav_np = wav_np.mean(axis=-1)
+    wav_np = wav_np.reshape(-1)
+    if sample_rate <= 0 or sample_rate == target_sr or wav_np.size == 0:
+        return wav_np.astype(np.float32, copy=False)
+    import torch
+    import torchaudio
+
+    audio = torch.from_numpy(wav_np).to(dtype=torch.float32).unsqueeze(0)
+    resampled = torchaudio.functional.resample(audio, int(sample_rate), int(target_sr))
+    return resampled.squeeze(0).cpu().numpy().astype(np.float32, copy=False)
+
+
+def _apply_first_append_context_tokens(
+    runtime_config: dict[str, object],
+    *,
+    tokenizer: PreTrainedTokenizerBase | None,
+    instructions: object,
+    initial_user_text: object,
+    ref_sample_count: int | None,
+) -> None:
+    """Precompute the exact session-context token count for the engine.
+
+    The first data-plane append carries the system template and optional
+    reference-audio embeddings ahead of the first unit. The engine reserves
+    scheduler slots from this count; an inexact count turns into pad
+    embeddings inside the model KV (surplus) or truncated context (deficit),
+    so it is computed with the same template and pooling math the worker uses.
+    """
+    if "duplex_first_append_context_tokens" in runtime_config or tokenizer is None:
+        return
+    prefix, suffix = MiniCPMO45DuplexPolicy.session_context_texts(
+        instructions,
+        ref_sample_count is not None,
+        initial_user_text,
+    )
+    try:
+        prefix_ids = tokenizer.encode(prefix, add_special_tokens=False)
+        suffix_ids = tokenizer.encode(suffix, add_special_tokens=False)
+    except Exception:
+        return
+    ref_tokens = MiniCPMO45DuplexPolicy.audio_token_count(ref_sample_count or 0)
+    runtime_config["duplex_first_append_context_tokens"] = len(prefix_ids) + ref_tokens + len(suffix_ids)
+
+
+def _apply_default_scheduler_policy(
+    runtime_config: dict[str, object],
+    *,
+    config: DuplexSessionConfig,
+    tokenizer: PreTrainedTokenizerBase | None,
+) -> None:
+    stage0_max_tokens = config.max_tokens if isinstance(config.max_tokens, int) and config.max_tokens > 0 else 20
+    runtime_config["duplex_stage_max_tokens"] = {"0": stage0_max_tokens, "1": 8192}
+    stage0_params: dict[str, object] = {
+        "temperature": config.temperature if config.temperature is not None else 0.7,
+        "top_p": 0.8,
+        "top_k": 20,
+        "repetition_penalty": 1.05,
+    }
+    stop_token_ids = _stage0_stop_token_ids(tokenizer)
+    if stop_token_ids:
+        stage0_params["stop_token_ids"] = stop_token_ids
+    # Stage 1 keeps the deploy YAML's codec knobs, minus upstream's
+    # min_new_token=50: that floor is for whole-utterance chat TTS, while a
+    # duplex chunk is 26 codec samples, so check_stop would never release
+    # the Talker and Thinker would stall on the next model turn.
+    runtime_config["duplex_stage_sampling_params"] = {"0": stage0_params, "1": {"min_tokens": 0}}
+    scheduler_token_id = _scheduler_token_id(tokenizer)
+    if scheduler_token_id is not None:
+        runtime_config["duplex_scheduler_token_id"] = scheduler_token_id
+
+
+class MiniCPMO45DuplexPlugin(DuplexModelPlugin):
+    """MiniCPM-owned sampling policy, append planning, session state and output projection."""
+
+    plugin_id = "minicpmo45"
+    private_runtime_config_keys = PRIVATE_RUNTIME_CONFIG_KEYS
+    silence_continuation_samples = 16000
+
+    def __init__(self, encode_audio: EncodeAudio) -> None:
+        super().__init__(encode_audio)
+        self.data_plane = MiniCPMO45DataPlaneSession(encode_audio)
+        # The tokenizer is only needed for special-token ids and the session
+        # context token count; it is the same for every session, so load it
+        # once per model path, off the orchestrator loop.
+        self._tokenizers: dict[str, PreTrainedTokenizerBase | None] = {}
+        self._tokenizer_lock = asyncio.Lock()
+
+    async def _tokenizer_for(self, model_config: ModelConfig | None) -> PreTrainedTokenizerBase | None:
+        model_path = getattr(model_config, "model", None)
+        key = model_path if isinstance(model_path, str) else ""
+        if key in self._tokenizers:
+            return self._tokenizers[key]
+        async with self._tokenizer_lock:
+            if key not in self._tokenizers:
+                self._tokenizers[key] = await asyncio.to_thread(_load_tokenizer, model_config)
+        return self._tokenizers[key]
+
+    # ---- engine policy (the resumable Stage0 request) ----
+
+    def configure_sampling_params(
+        self,
+        *,
+        runtime_config: dict[str, object],
+        defaults: tuple[object, ...],
+    ) -> tuple[object, ...]:
+        configured: list[object] = []
+        for stage_id, default in enumerate(defaults):
+            max_tokens = _coerce_int(_stage_config_value(runtime_config, "duplex_stage_max_tokens", stage_id))
+            raw_overrides = _stage_config_value(runtime_config, "duplex_stage_sampling_params", stage_id)
+            overrides = dict(raw_overrides) if isinstance(raw_overrides, dict) else {}
+            if not isinstance(default, SamplingParams) or (not overrides and (max_tokens is None or max_tokens <= 0)):
+                configured.append(default)
+                continue
+            params = default.clone()
+            if max_tokens is not None and max_tokens > 0:
+                params.max_tokens = max_tokens
+            for name, value in overrides.items():
+                if not hasattr(params, name):
+                    continue
+                setattr(params, name, value)
+                if name == "stop_token_ids":
+                    all_stop_token_ids = getattr(params, "_all_stop_token_ids", None)
+                    if isinstance(all_stop_token_ids, set):
+                        all_stop_token_ids.update(int(token_id) for token_id in value)
+            configured.append(params)
+        return tuple(configured)
+
+    def plan_append(
+        self,
+        *,
+        request_id: str,
+        fence: DuplexFence,
+        session_config: dict[str, object],
+        runtime_config: dict[str, object],
+        seq: int,
+        turn_seq: int,
+        payload: object,
+        final: bool,
+        sampling_params: object,
+    ) -> DuplexAppendPlan:
+        del sampling_params
+        return DuplexAppendPlan(
+            prompt=build_duplex_data_plane_prompt(
+                request_id=request_id,
+                fence=fence,
+                session_config=session_config,
+                runtime_config=runtime_config,
+                seq=seq,
+                turn_seq=turn_seq,
+                payload=payload,
+                final=final,
+            )
+        )
+
+    def decide_output(
+        self,
+        *,
+        stage_id: int,
+        final_stage_id: int,
+        segment_finished: bool,
+        segment_token_ids: tuple[int, ...],
+        segment_output_metadata: dict[str, object],
+        output: object,
+    ) -> DuplexOutputDecision | None:
+        if stage_id >= final_stage_id or not segment_finished:
+            return None
+
+        completion = _first_completion(output)
+        output_metadata = _multimodal_output(output, completion)
+        special_token_ids = _special_token_ids(segment_output_metadata)
+        special_token_ids.update(_special_token_ids(output_metadata))
+        listen_id = special_token_ids.get("listen_token_id")
+        if listen_id is None:
+            return None
+
+        stop_reason = getattr(completion, "stop_reason", None) if completion is not None else None
+        token_ids = _completion_token_ids(completion) or list(segment_token_ids)
+        if _coerce_int(stop_reason) != listen_id and (not token_ids or token_ids[-1] != listen_id):
+            return None
+
+        metadata = dict(output_metadata)
+        for key, value in special_token_ids.items():
+            metadata.setdefault(f"meta.{key}", value)
+        metadata.update(
+            {
+                "duplex_direct_response": True,
+                "duplex_native_decision": "listen",
+                "model_listen": True,
+                "listen_source": "model_listen",
+            }
+        )
+        return DuplexOutputDecision(
+            action=DuplexOutputAction.DIRECT_RESPONSE,
+            metadata=metadata,
+        )
+
+    # ---- session policy ----
+
+    def create_session_state(self) -> MiniCPMO45ServingSessionState:
+        return MiniCPMO45ServingSessionState()
+
+    def capabilities(self, *, max_sessions: int) -> DuplexCapabilities:
+        return minicpmo45_native_capabilities(max_sessions=max_sessions)
+
+    def validate_client_extra_body(self, extra_body: object) -> None:
+        if not isinstance(extra_body, dict):
+            return
+        private_keys = sorted(PRIVATE_RUNTIME_CONFIG_KEYS.intersection(extra_body))
+        if private_keys:
+            raise MiniCPMO45ClientRuntimeConfigError(
+                "duplex runtime configuration is server-owned: " + ", ".join(private_keys)
+            )
+
+    async def prepare_runtime_config(
+        self, config: DuplexSessionConfig, *, model_config: ModelConfig | None
+    ) -> dict[str, object]:
+        extra_body = dict(config.extra_body)
+        if any(key in extra_body for key in ("ref_audio_path", "tts_ref_audio_path")):
+            raise MiniCPMO45ClientRuntimeConfigError(
+                "ref_audio_path is not accepted by duplex sessions; use ref_audio URI instead",
+                code="unsupported_ref_audio_path",
+            )
+        runtime_config: dict[str, object] = {"instructions": config.instructions}
+        # ``duplex_initial_user_text`` is the older extra_body spelling and
+        # still works; the session field is the framework-level one.
+        initial_user_text = extra_body.pop("duplex_initial_user_text", None)
+        if not (isinstance(initial_user_text, str) and initial_user_text):
+            initial_user_text = config.initial_user_text
+        if isinstance(initial_user_text, str) and initial_user_text:
+            runtime_config["initial_user_text"] = initial_user_text
+        tokenizer = await self._tokenizer_for(model_config)
+        _apply_default_scheduler_policy(runtime_config, config=config, tokenizer=tokenizer)
+
+        ref_audio = config.ref_audio
+        extra_ref_audio = extra_body.get("ref_audio")
+        if ref_audio is None and isinstance(extra_ref_audio, str):
+            extra_body.pop("ref_audio")
+            ref_audio = extra_ref_audio
+        extra_tts_ref_audio = extra_body.get("tts_ref_audio")
+        if ref_audio is None and isinstance(extra_tts_ref_audio, str):
+            extra_body.pop("tts_ref_audio")
+            ref_audio = extra_tts_ref_audio
+
+        if ref_audio is None:
+            if any(str(modality).lower() == "audio" for modality in config.modalities):
+                raise MiniCPMO45ClientRuntimeConfigError(
+                    "MiniCPM-o duplex audio output requires ref_audio",
+                    code="ref_audio_required",
+                )
+            _apply_first_append_context_tokens(
+                runtime_config,
+                tokenizer=tokenizer,
+                instructions=config.instructions,
+                initial_user_text=initial_user_text,
+                ref_sample_count=None,
+            )
+            config.extra_body = extra_body
+            return runtime_config
+
+        wav_np, sr = await resolve_ref_audio(ref_audio, model_config=model_config)
+        # torchaudio resampling is CPU work: keep it off the orchestrator loop.
+        wav_np = await asyncio.to_thread(normalize_ref_audio, wav_np, int(sr), target_sr=16000)
+        # Trim to a whole number of pooled audio embeddings (100 ms frames) so
+        # the first-append scheduler reserve can count them exactly.
+        usable = (len(wav_np) // MiniCPMO45DuplexPolicy.SAMPLES_PER_AUDIO_TOKEN) * (
+            MiniCPMO45DuplexPolicy.SAMPLES_PER_AUDIO_TOKEN
+        )
+        wav_np = wav_np[:usable]
+        ref_audio_bytes = np.ascontiguousarray(wav_np, dtype=np.float32).tobytes()
+        runtime_config["ref_audio_data"] = base64.b64encode(ref_audio_bytes).decode("ascii")
+        runtime_config["ref_audio_format"] = "pcm_f32le"
+        runtime_config["ref_audio_sample_rate_hz"] = 16000
+        _apply_first_append_context_tokens(
+            runtime_config,
+            tokenizer=tokenizer,
+            instructions=config.instructions,
+            initial_user_text=initial_user_text,
+            ref_sample_count=len(wav_np),
+        )
+        config.extra_body = extra_body
+        config.ref_audio = None
+        return runtime_config
+
+    def runtime_config_for_update(
+        self,
+        config: DuplexSessionConfig,
+        current: Mapping[str, object],
+    ) -> dict[str, object]:
+        runtime_config = deepcopy(dict(current))
+        reject_changed_runtime_value(
+            config.instructions,
+            runtime_config.get("instructions"),
+            message="instructions cannot be changed after the session is created",
+            code="instructions_update_unsupported",
+            error_cls=MiniCPMO45ClientRuntimeConfigError,
+        )
+        stage_max_tokens = runtime_config.get("duplex_stage_max_tokens")
+        stage_max_tokens = deepcopy(stage_max_tokens) if isinstance(stage_max_tokens, dict) else {}
+        stage_max_tokens["0"] = (
+            config.max_tokens if isinstance(config.max_tokens, int) and config.max_tokens > 0 else 20
+        )
+        stage_max_tokens.setdefault("1", 8192)
+        runtime_config["duplex_stage_max_tokens"] = stage_max_tokens
+
+        stage_sampling = runtime_config.get("duplex_stage_sampling_params")
+        stage_sampling = deepcopy(stage_sampling) if isinstance(stage_sampling, dict) else {}
+        stage0 = stage_sampling.get("0")
+        stage0 = deepcopy(stage0) if isinstance(stage0, dict) else {}
+        stage0["temperature"] = config.temperature if config.temperature is not None else 0.7
+        stage_sampling["0"] = stage0
+        runtime_config["duplex_stage_sampling_params"] = stage_sampling
+        return runtime_config
+
+    def data_plane_context(
+        self,
+        *,
+        epoch: int,
+        turn_id: int,
+        active_response_turn_id: int | None,
+        active_response_id: str | None,
+        auto_responds: bool,
+        response_format: str,
+        speed: float | None,
+        modalities: tuple[str, ...],
+    ) -> MiniCPMO45DataPlaneContext:
+        return MiniCPMO45DataPlaneContext(
+            epoch=epoch,
+            turn_id=turn_id,
+            active_response_turn_id=active_response_turn_id,
+            active_response_id=active_response_id,
+            auto_responds=auto_responds,
+            response_format=response_format,
+            speed=speed,
+            modalities=modalities,
+        )
+
+
+__all__ = [
+    "PRIVATE_RUNTIME_CONFIG_KEYS",
+    "MiniCPMO45ClientRuntimeConfigError",
+    "MiniCPMO45DuplexPlugin",
+    "build_duplex_data_plane_prompt",
+    "duplex_first_append_context_reserve",
+    "duplex_first_append_unit_count",
+    "duplex_payload_is_exact_chunks",
+    "duplex_scheduler_token_budget",
+    "normalize_ref_audio",
+    "resolve_ref_audio",
+]
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/policy.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/policy.py
index 9a2643521fb..0332c81c0a1 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/policy.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/policy.py
@@ -3,7 +3,10 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from transformers import PreTrainedTokenizerBase
 
 
 class MiniCPMO45DuplexPolicy:
@@ -89,7 +92,7 @@ def session_context_texts(
     }
 
     @classmethod
-    def token_ids_from_tokenizer(cls, tokenizer: Any) -> dict[str, int]:
+    def token_ids_from_tokenizer(cls, tokenizer: PreTrainedTokenizerBase) -> dict[str, int]:
         convert = getattr(tokenizer, "convert_tokens_to_ids", None)
 
         def token_id(token: str) -> int:
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/runtime.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/runtime.py
deleted file mode 100644
index d5e98d723e0..00000000000
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/runtime.py
+++ /dev/null
@@ -1,439 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-import math
-from base64 import b64decode
-from binascii import Error as BinasciiError
-from typing import Any, cast
-
-from vllm.sampling_params import SamplingParams
-
-from vllm_omni.engine.duplex.messages import DuplexFence
-from vllm_omni.engine.duplex.runtime import (
-    DuplexAppendPlan,
-    DuplexInputMode,
-    DuplexOutputAction,
-    DuplexOutputDecision,
-)
-
-_DUPLEX_CHUNK_SAMPLES = 16000
-_DUPLEX_SAMPLES_PER_AUDIO_TOKEN = 1600
-# <image> + 64 resampler embeddings + </image> per frame (max_slice_nums=1),
-# matching MiniCPMO45DuplexPolicy.VISION_TOKENS_PER_FRAME.
-_DUPLEX_VISION_TOKENS_PER_FRAME = 66
-# Official stacked pair uses max_slice_nums=[2, 1]: the current frame is HD
-# sliced (1 source + up to 2 patches, e.g. on 960x540) and the composite is
-# not. The patch count depends on the frame size (see
-# ``_duplex_hd_slice_count``); the constant is the fallback when the frame
-# header cannot be read.
-_DUPLEX_HD_SLICES_PER_BASE_FRAME = 3
-_DUPLEX_HD_MAX_SLICE_NUMS = 2
-_DUPLEX_SCALE_RESOLUTION = 448
-
-
-def _duplex_frames(payload: object) -> list[str]:
-    if not isinstance(payload, dict):
-        return []
-    frames = payload.get("video_frames")
-    if not isinstance(frames, list):
-        return []
-    return [frame for frame in frames if isinstance(frame, str) and frame]
-
-
-def _duplex_frame_count(payload: object) -> int:
-    return len(_duplex_frames(payload))
-
-
-def _duplex_frame_size(frame_b64: str) -> tuple[int, int] | None:
-    """Pixel size of a base64 JPEG/PNG frame from its header, or ``None``."""
-    from io import BytesIO
-
-    try:
-        from PIL import Image
-
-        with Image.open(BytesIO(b64decode(frame_b64, validate=True))) as image:
-            width, height = image.size
-    except Exception:  # noqa: BLE001 - Stage0 rejects bad frames with a reason
-        return None
-    if width <= 0 or height <= 0:
-        return None
-    return int(width), int(height)
-
-
-def _duplex_hd_slice_count(image_size: tuple[int, int], max_slice_nums: int) -> int:
-    """Number of HD patches ``MiniCPMVImageProcessor.get_sliced_grid`` adds.
-
-    Port of the official grid selection (``scale_resolution=448``): an image
-    whose area fits in one 448x448 tile is not sliced at all, otherwise the
-    grid closest to the image aspect ratio among ``multiple-1 .. multiple+1``
-    splits is used. Stage0 runs the same processor, so the scheduler budget
-    and the worker-built embeddings agree.
-    """
-    width, height = image_size
-    ratio = width * height / (_DUPLEX_SCALE_RESOLUTION * _DUPLEX_SCALE_RESOLUTION)
-    multiple = min(math.ceil(ratio), max_slice_nums)
-    if multiple <= 1:
-        return 0
-    log_ratio = math.log(width / height)
-    best_grid = (1, 1)
-    min_error = float("inf")
-    for split_grids_nums in (multiple - 1, multiple, multiple + 1):
-        if split_grids_nums == 1 or split_grids_nums > max_slice_nums:
-            continue
-        for m in range(1, split_grids_nums + 1):
-            if split_grids_nums % m:
-                continue
-            grid = (m, split_grids_nums // m)
-            error = abs(log_ratio - math.log(grid[0] / grid[1]))
-            if error < min_error:
-                best_grid = grid
-                min_error = error
-    return best_grid[0] * best_grid[1]
-
-
-def _duplex_vision_tokens(payload: object) -> int:
-    """Scheduler slots for this append's camera track.
-
-    Audio is never stacked: a unit still carries one second of soundtrack.
-    ``stack_frames`` only adds a second *image*. Official HD on that pair is
-    ``max_slice_nums=[2, 1]``: the base frame keeps its source block plus the
-    HD patches the processor cuts for its size (two for a 960x540 camera
-    frame, none for anything that fits in one 448x448 tile) and every extra
-    frame is one block. A single frame is never sliced. The count must match
-    the embeddings Stage0 builds exactly: surplus slots become pad
-    embeddings inside the KV.
-    """
-    frames = _duplex_frames(payload)
-    count = len(frames)
-    if count <= 0:
-        return 0
-    if count == 1:
-        return _DUPLEX_VISION_TOKENS_PER_FRAME
-    base_size = _duplex_frame_size(frames[0])
-    if base_size is None:
-        base_blocks = _DUPLEX_HD_SLICES_PER_BASE_FRAME
-    else:
-        base_blocks = 1 + _duplex_hd_slice_count(base_size, _DUPLEX_HD_MAX_SLICE_NUMS)
-    return (base_blocks + (count - 1)) * _DUPLEX_VISION_TOKENS_PER_FRAME
-
-
-def _duplex_pcm_sample_count(payload: object) -> int | None:
-    if not isinstance(payload, dict):
-        return None
-    audio = payload.get("audio") or payload.get("data")
-    if payload.get("format") != "pcm_f32le" or not isinstance(audio, str):
-        return None
-    try:
-        raw = b64decode(audio, validate=True)
-    except (BinasciiError, ValueError):
-        return None
-    return len(raw) // 4
-
-
-def duplex_payload_is_exact_chunks(payload: object) -> bool:
-    sample_count = _duplex_pcm_sample_count(payload)
-    return sample_count is not None and sample_count != 0 and sample_count % _DUPLEX_CHUNK_SAMPLES == 0
-
-
-def duplex_first_append_unit_count(payload: object) -> int | None:
-    sample_count = _duplex_pcm_sample_count(payload)
-    if not sample_count or sample_count % _DUPLEX_CHUNK_SAMPLES != 0:
-        return None
-    return max(1, sample_count // _DUPLEX_CHUNK_SAMPLES - 1)
-
-
-def duplex_scheduler_token_budget(payload: object, *, default: int = 64) -> int:
-    vision_tokens = _duplex_vision_tokens(payload)
-    sample_count = _duplex_pcm_sample_count(payload)
-    if sample_count is None:
-        return max(1, int(default)) + vision_tokens
-    sample_count = max(1, sample_count)
-    if sample_count % _DUPLEX_CHUNK_SAMPLES == 0:
-        units = sample_count // _DUPLEX_CHUNK_SAMPLES
-        return units * (2 + _DUPLEX_CHUNK_SAMPLES // _DUPLEX_SAMPLES_PER_AUDIO_TOKEN) + vision_tokens
-    return max(16, min(768, sample_count // _DUPLEX_SAMPLES_PER_AUDIO_TOKEN + 8)) + vision_tokens
-
-
-def duplex_first_append_context_reserve(runtime_config: object) -> int:
-    if not isinstance(runtime_config, dict):
-        return 48
-    exact = runtime_config.get("duplex_first_append_context_tokens")
-    if isinstance(exact, int) and exact >= 0:
-        return exact
-    reserve = 48
-    ref = runtime_config.get("ref_audio_data")
-    if isinstance(ref, str) and ref:
-        try:
-            raw = b64decode(ref, validate=True)
-        except (BinasciiError, ValueError):
-            raw = b""
-        if raw:
-            reserve += max(0, (len(raw) // 4) // _DUPLEX_SAMPLES_PER_AUDIO_TOKEN + 8)
-    return reserve
-
-
-def _duplex_force_listen_count(extra_body: object) -> int:
-    raw = extra_body.get("force_listen_count") if isinstance(extra_body, dict) else None
-    try:
-        return 0 if raw is None else max(0, int(raw))
-    except (TypeError, ValueError):
-        return 0
-
-
-def build_duplex_data_plane_prompt(
-    *,
-    request_id: str,
-    fence: DuplexFence,
-    session_config: dict[str, Any],
-    runtime_config: dict[str, Any],
-    seq: int,
-    turn_seq: int,
-    mode: DuplexInputMode,
-    payload: object,
-    final: bool,
-) -> dict[str, Any]:
-    token_budget = duplex_scheduler_token_budget(payload)
-    if seq <= 1:
-        context_reserve = duplex_first_append_context_reserve(runtime_config)
-        token_budget += context_reserve
-        first_units = duplex_first_append_unit_count(payload)
-        if first_units is not None:
-            token_budget = context_reserve + first_units * 12 - 1 + _duplex_vision_tokens(payload)
-    if seq > 1 and duplex_payload_is_exact_chunks(payload):
-        token_budget += 1
-    if final and duplex_payload_is_exact_chunks(payload):
-        token_budget += 12
-    extra_body = session_config.get("extra_body")
-    raw_token_id = runtime_config.get("duplex_scheduler_token_id")
-    try:
-        token_id = 0 if raw_token_id is None else max(0, int(raw_token_id))
-    except (TypeError, ValueError):
-        token_id = 0
-    force_listen_count = _duplex_force_listen_count(extra_body)
-    if (
-        force_listen_count > 0
-        and turn_seq <= force_listen_count
-        and isinstance(payload, dict)
-        and payload.get("force_listen") is not True
-    ):
-        payload = {**payload, "force_listen": True}
-    return {
-        "prompt_token_ids": [token_id] * token_budget,
-        "model_intermediate_buffer": {
-            "request_id": request_id,
-            "global_request_id": [fence.session_id],
-            "duplex": {
-                "fence": fence,
-                "session_id": fence.session_id,
-                "incarnation": fence.incarnation,
-                "epoch": fence.epoch,
-                "seq": seq,
-                "turn_id": fence.turn_id,
-                "response_seq": fence.response_seq,
-                "turn_seq": turn_seq,
-                "mode": mode.value,
-                "payload": payload,
-                "final": final,
-                "data_plane": True,
-                "session_config": dict(session_config),
-                "runtime_config": dict(runtime_config),
-                "scheduler_token_budget": token_budget,
-                "scheduler_token_id": token_id,
-            },
-        },
-    }
-
-
-def _coerce_int(value: object) -> int | None:
-    detach = getattr(value, "detach", None)
-    if callable(detach):
-        try:
-            flat: Any = detach().cpu().reshape(-1)
-            if flat.numel() == 0:
-                return None
-            value = flat[0].item()
-        except Exception:
-            return None
-    try:
-        return int(cast(Any, value))
-    except (TypeError, ValueError):
-        return None
-
-
-def _coerce_int_list(value: object) -> list[int]:
-    if value is None:
-        return []
-    if hasattr(value, "detach"):
-        try:
-            value = value.detach().cpu().reshape(-1).tolist()
-        except Exception:
-            return []
-    if not isinstance(value, (list, tuple)):
-        return []
-    return [token_id for item in value if (token_id := _coerce_int(item)) is not None]
-
-
-def _first_completion(output: object) -> object | None:
-    outputs = getattr(output, "outputs", None)
-    return outputs[0] if isinstance(outputs, list) and outputs else None
-
-
-def _multimodal_output(output: object, completion: object | None) -> dict[str, Any]:
-    metadata = getattr(output, "multimodal_output", None)
-    if isinstance(metadata, dict):
-        return metadata
-    metadata = getattr(completion, "multimodal_output", None) if completion is not None else None
-    return metadata if isinstance(metadata, dict) else {}
-
-
-def _special_token_ids(metadata: dict[str, Any]) -> dict[str, int]:
-    sources: list[object] = [metadata.get("special_token_ids"), metadata.get("meta")]
-    sources.append(
-        {
-            key.removeprefix("meta."): value
-            for key, value in metadata.items()
-            if isinstance(key, str) and key.startswith("meta.")
-        }
-    )
-    token_ids: dict[str, int] = {}
-    for source in sources:
-        if not isinstance(source, dict):
-            continue
-        for key, value in source.items():
-            token_id = _coerce_int(value)
-            if isinstance(key, str) and token_id is not None and token_id >= 0:
-                token_ids[key] = token_id
-    return token_ids
-
-
-def _completion_token_ids(completion: object | None) -> list[int]:
-    if completion is None:
-        return []
-    for attribute in ("token_ids", "cumulative_token_ids"):
-        token_ids = _coerce_int_list(getattr(completion, attribute, None))
-        if token_ids:
-            return token_ids
-    return []
-
-
-def _stage_config_value(runtime_config: dict[str, Any], key: str, stage_id: int) -> object | None:
-    raw = runtime_config.get(key)
-    if isinstance(raw, dict):
-        value = raw.get(stage_id)
-        return raw.get(str(stage_id)) if value is None else value
-    if isinstance(raw, (list, tuple)) and stage_id < len(raw):
-        return raw[stage_id]
-    return None
-
-
-class MiniCPMO45DuplexRuntimeExtension:
-    def configure_sampling_params(
-        self,
-        *,
-        runtime_config: dict[str, Any],
-        defaults: tuple[object, ...],
-    ) -> tuple[object, ...]:
-        configured: list[object] = []
-        for stage_id, default in enumerate(defaults):
-            max_tokens = _coerce_int(_stage_config_value(runtime_config, "duplex_stage_max_tokens", stage_id))
-            raw_overrides = _stage_config_value(runtime_config, "duplex_stage_sampling_params", stage_id)
-            overrides = dict(raw_overrides) if isinstance(raw_overrides, dict) else {}
-            if not isinstance(default, SamplingParams) or (not overrides and (max_tokens is None or max_tokens <= 0)):
-                configured.append(default)
-                continue
-            params = default.clone()
-            if max_tokens is not None and max_tokens > 0:
-                params.max_tokens = max_tokens
-            for name, value in overrides.items():
-                if not hasattr(params, name):
-                    continue
-                setattr(params, name, value)
-                if name == "stop_token_ids":
-                    all_stop_token_ids = getattr(params, "_all_stop_token_ids", None)
-                    if isinstance(all_stop_token_ids, set):
-                        all_stop_token_ids.update(int(token_id) for token_id in value)
-            configured.append(params)
-        return tuple(configured)
-
-    def plan_append(
-        self,
-        *,
-        request_id: str,
-        fence: DuplexFence,
-        session_config: dict[str, Any],
-        runtime_config: dict[str, Any],
-        seq: int,
-        turn_seq: int,
-        mode: DuplexInputMode,
-        payload: object,
-        final: bool,
-        sampling_params: object,
-    ) -> DuplexAppendPlan:
-        del sampling_params
-        return DuplexAppendPlan(
-            prompt=build_duplex_data_plane_prompt(
-                request_id=request_id,
-                fence=fence,
-                session_config=session_config,
-                runtime_config=runtime_config,
-                seq=seq,
-                turn_seq=turn_seq,
-                mode=mode,
-                payload=payload,
-                final=final,
-            )
-        )
-
-    def decide_output(
-        self,
-        *,
-        stage_id: int,
-        final_stage_id: int,
-        segment_finished: bool,
-        segment_token_ids: tuple[int, ...],
-        segment_output_metadata: dict[str, Any],
-        output: object,
-    ) -> DuplexOutputDecision | None:
-        if stage_id >= final_stage_id or not segment_finished:
-            return None
-
-        completion = _first_completion(output)
-        output_metadata = _multimodal_output(output, completion)
-        special_token_ids = _special_token_ids(segment_output_metadata)
-        special_token_ids.update(_special_token_ids(output_metadata))
-        listen_id = special_token_ids.get("listen_token_id")
-        if listen_id is None:
-            return None
-
-        stop_reason = getattr(completion, "stop_reason", None) if completion is not None else None
-        token_ids = _completion_token_ids(completion) or list(segment_token_ids)
-        if _coerce_int(stop_reason) != listen_id and (not token_ids or token_ids[-1] != listen_id):
-            return None
-
-        metadata = dict(output_metadata)
-        for key, value in special_token_ids.items():
-            metadata.setdefault(f"meta.{key}", value)
-        metadata.update(
-            {
-                "duplex_direct_response": True,
-                "duplex_native_decision": "listen",
-                "model_listen": True,
-                "listen_source": "model_listen",
-            }
-        )
-        return DuplexOutputDecision(
-            action=DuplexOutputAction.DIRECT_RESPONSE,
-            metadata=metadata,
-        )
-
-
-__all__ = [
-    "MiniCPMO45DuplexRuntimeExtension",
-    "build_duplex_data_plane_prompt",
-    "duplex_first_append_context_reserve",
-    "duplex_first_append_unit_count",
-    "duplex_payload_is_exact_chunks",
-    "duplex_scheduler_token_budget",
-]
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/serving_adapter.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/serving_adapter.py
deleted file mode 100644
index ea51662a955..00000000000
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/serving_adapter.py
+++ /dev/null
@@ -1,102 +0,0 @@
-# SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-
-from __future__ import annotations
-
-from collections.abc import Callable, Mapping
-from typing import Any
-
-from vllm_omni.entrypoints.duplex.protocol import DuplexCapabilities
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.adapter import (
-    MiniCPMO45NativeDuplexServingAdapter,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.capabilities import (
-    minicpmo45_native_capabilities,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.data_plane import (
-    MiniCPMO45DataPlaneContext,
-    MiniCPMO45DataPlaneSession,
-)
-from vllm_omni.model_executor.models.minicpmo_4_5.duplex.session import (
-    MiniCPMO45ServingSessionState,
-)
-
-EncodeAudio = Callable[[object, int, str, float | None], str | None]
-
-
-class MiniCPMO45ServingRuntimeAdapter:
-    """MiniCPM-owned serving state, input packing, and output projection."""
-
-    adapter_id = "minicpmo45"
-    clean_response_done_prefix = ""
-    interrupted_tts_prefix = ""
-    private_runtime_config_keys = MiniCPMO45NativeDuplexServingAdapter.PRIVATE_RUNTIME_CONFIG_KEYS
-
-    def __init__(self, encode_audio: EncodeAudio) -> None:
-        self.session_states: dict[str, MiniCPMO45ServingSessionState] = {}
-        self.data_plane = MiniCPMO45DataPlaneSession(encode_audio)
-
-    def create_session_state(self) -> MiniCPMO45ServingSessionState:
-        return MiniCPMO45ServingSessionState()
-
-    def session_state(self, session_id: str) -> MiniCPMO45ServingSessionState:
-        state = self.session_states.get(session_id)
-        if state is None:
-            state = self.create_session_state()
-            self.session_states[session_id] = state
-        return state
-
-    def remove_session_state(self, session_id: str) -> None:
-        self.session_states.pop(session_id, None)
-
-    @staticmethod
-    def is_enabled(config: object) -> bool:
-        return MiniCPMO45NativeDuplexServingAdapter.is_enabled(config)  # type: ignore[arg-type]
-
-    @staticmethod
-    def capabilities(*, max_sessions: int) -> DuplexCapabilities:
-        return minicpmo45_native_capabilities(max_sessions=max_sessions)
-
-    @staticmethod
-    def validate_client_extra_body(extra_body: object) -> None:
-        MiniCPMO45NativeDuplexServingAdapter.validate_client_extra_body(extra_body)
-
-    @staticmethod
-    async def prepare_runtime_config(config: object, *, model_config: Any) -> dict[str, object]:
-        return await MiniCPMO45NativeDuplexServingAdapter.prepare_runtime_config(
-            config,  # type: ignore[arg-type]
-            model_config=model_config,
-        )
-
-    @staticmethod
-    def runtime_config_for_update(
-        config: object,
-        current: Mapping[str, object],
-    ) -> dict[str, object]:
-        return MiniCPMO45NativeDuplexServingAdapter.runtime_config_for_update(
-            config,  # type: ignore[arg-type]
-            dict(current),
-        )
-
-    @staticmethod
-    def data_plane_context(
-        *,
-        epoch: int,
-        turn_id: int,
-        active_response_turn_id: int | None,
-        active_response_id: str | None,
-        auto_responds: bool,
-        response_format: str,
-        speed: float | None,
-        modalities: tuple[str, ...],
-    ) -> MiniCPMO45DataPlaneContext:
-        return MiniCPMO45DataPlaneContext(
-            epoch=epoch,
-            turn_id=turn_id,
-            active_response_turn_id=active_response_turn_id,
-            active_response_id=active_response_id,
-            auto_responds=auto_responds,
-            response_format=response_format,
-            speed=speed,
-            modalities=modalities,
-        )
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/session.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/session.py
index 40c42cb81cf..49d0caab6f8 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/session.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/session.py
@@ -4,34 +4,31 @@
 from __future__ import annotations
 
 import asyncio
-from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 
+from vllm_omni.engine.duplex.plugin import DuplexModelSessionState
 from vllm_omni.model_executor.models.minicpmo_4_5.duplex.input import (
     MiniCPMO45PcmAppendBuffer,
 )
 
 
 @dataclass(slots=True)
-class MiniCPMO45ServingSessionState:
-    """Mutable serving state owned by one MiniCPM duplex session."""
+class MiniCPMO45ServingSessionState(DuplexModelSessionState):
+    """Mutable model-owned state of one MiniCPM duplex session (owned by the session runner)."""
 
     audio_buffer: MiniCPMO45PcmAppendBuffer = field(default_factory=MiniCPMO45PcmAppendBuffer)
     input_since_commit: bool = False
     speech_since_commit: bool = False
-    native_context_locked: bool = False
+    context_locked: bool = False
     committed_audio_payload: dict[str, object] | None = None
     committed_audio_operation_id: str | None = None
     committed_audio_reserved_bytes: int = 0
     deferred_response_create: bool = False
     deferred_precreate_response: bool = False
-    data_plane_task: asyncio.Task[None] | None = None
-    data_plane_restart_requested: bool = False
     continuation_owner_id: str | None = None
     continuation_units: int = 0
     pending_silence_task: asyncio.Task[bool] | None = None
     pending_silence_owner_id: str | None = None
-    silence_continuation_scheduler: Callable[..., Awaitable[bool]] | None = None
 
     def retain_committed_audio(
         self,
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/stage0.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/stage0.py
index 6d9800025a7..bc13b58f2ca 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/stage0.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/stage0.py
@@ -6,15 +6,22 @@
 import base64
 import copy
 import time
+from collections.abc import Callable
 from contextlib import suppress
 from dataclasses import dataclass, field
 from threading import Lock
-from typing import Any
+from typing import TYPE_CHECKING, Any, cast
 
 import numpy as np
+from numpy.typing import NDArray
 
 from vllm_omni.model_executor.models.minicpmo_4_5.duplex.policy import MiniCPMO45DuplexPolicy
 
+if TYPE_CHECKING:
+    import torch
+    from PIL import Image
+    from torch import nn
+
 _MINICPMO45_SPECIAL_TOKEN_FIELDS = MiniCPMO45DuplexPolicy.SPECIAL_TOKEN_FIELDS
 _MINICPMO45_OPTIONAL_TOKEN_FIELDS = MiniCPMO45DuplexPolicy.OPTIONAL_TOKEN_FIELDS
 _MINICPMO45_PROCESSOR_LOAD_LOCK = Lock()
@@ -23,17 +30,19 @@
 @dataclass
 class _MiniCPMO45Stage0SessionState:
     session_id: str
+    #: Any: MiniCPM-o remote-code processor (transformers, no importable type).
     streaming_processor: Any | None = None
-    audio_buffer: np.ndarray = field(default_factory=lambda: np.array([], dtype=np.float32))
+    audio_buffer: NDArray[np.float32] = field(default_factory=lambda: np.array([], dtype=np.float32))
     audio_chunk_idx: int = 0
-    context_embeds: list[Any] = field(default_factory=list)
+    context_embeds: list[torch.Tensor] = field(default_factory=list)
     context_token_ids: list[int] = field(default_factory=list)
     current_turn_ended: bool = True
     prepared_append_identity: tuple[int | None, int] | None = None
-    prepared_inputs_embeds: Any | None = None
+    prepared_inputs_embeds: torch.Tensor | None = None
     prepared_input_token_ids: list[int] = field(default_factory=list)
-    prepared_result: dict[str, Any] = field(default_factory=dict)
-    audio_past_key_values: Any | None = None
+    prepared_result: dict[str, object] = field(default_factory=dict)
+    #: Opaque transformers cache, handed back to the model unchanged.
+    audio_past_key_values: object | None = None
     pending_terminator_token: int | None = None
     last_terminator_token: int | None = None
     pending_speech_context: bool = False
@@ -59,7 +68,7 @@ class MiniCPMO45Stage0DuplexRuntime:
     image_start_token_id: int = -1
     image_end_token_id: int = -1
 
-    def __init__(self, stage_model: Any, *, model_path: str | None = None, device: str = "cuda") -> None:
+    def __init__(self, stage_model: nn.Module, *, model_path: str | None = None, device: str = "cuda") -> None:
         self.stage_model = stage_model
         self.model_path = model_path
         self.device = device
@@ -85,7 +94,7 @@ def _stage_runtime_ready(self) -> bool:
     def _configure_streaming_processor(
         self,
         state: _MiniCPMO45Stage0SessionState | None = None,
-    ) -> Any | None:
+    ) -> Any | None:  # Any: MiniCPM-o remote-code processor
         processor = self.processor
         if processor is None:
             return None
@@ -129,9 +138,9 @@ def _configure_streaming_processor(
     def _prepare_session_context(
         self,
         state: _MiniCPMO45Stage0SessionState,
-        session_config: dict[str, Any],
+        session_config: dict[str, object],
         *,
-        runtime_config: dict[str, Any] | None = None,
+        runtime_config: dict[str, object] | None = None,
     ) -> None:
         if not self._stage_runtime_ready():
             return
@@ -163,14 +172,14 @@ def _prepare_session_context(
     def _stage_prefill_embeddings_only(
         self,
         state: _MiniCPMO45Stage0SessionState,
-        audio_waveform: Any,
+        audio_waveform: NDArray[np.float32] | None,
         *,
-        video_frames: list[Any] | None = None,
+        video_frames: list[Image.Image] | None = None,
         epoch: int | None = None,
         seq: int | None = None,
         is_speech: bool = False,
         final: bool = False,
-    ) -> dict[str, Any]:
+    ) -> dict[str, object]:
         """Build scheduler-owned Stage0 input embeddings for one audio append.
 
         Unlike the legacy worker-control path, this method never calls an eager
@@ -217,7 +226,7 @@ def _stage_prefill_embeddings_only(
         # Omni duplex: encode this append's camera frames so the first unit can
         # carry them, mirroring official streaming_prefill (feed <unit>, then
         # every frame_list entry as its own <image> block, then the audio).
-        frame_blocks: list[Any] = []
+        frame_blocks: list[list[torch.Tensor]] = []
         if video_frames:
             self._require_vision_token_ids()
             encoded_frames = self._stage_vision_embeddings(video_frames)
@@ -227,7 +236,7 @@ def _stage_prefill_embeddings_only(
                 return self._stage_prefill_result(False, start_time, "streaming vision embedding failed")
             frame_blocks = encoded_frames
 
-        embed_parts: list[Any] = []
+        embed_parts: list[torch.Tensor] = []
         token_ids: list[int] = []
         if state.audio_chunk_idx == 0 and state.context_embeds:
             embed_parts.extend(state.context_embeds)
@@ -336,7 +345,7 @@ def _stage_prefill_embeddings_only(
         return result
 
     @staticmethod
-    def _stage_prefill_result(success: bool, start_time: float, reason: str = "") -> dict[str, Any]:
+    def _stage_prefill_result(success: bool, start_time: float, reason: str = "") -> dict[str, object]:
         return {
             "success": success,
             "prefill_success": success,
@@ -347,14 +356,14 @@ def _stage_prefill_result(success: bool, start_time: float, reason: str = "") ->
         }
 
     @staticmethod
-    def _as_2d_tensor(value: Any) -> Any:
+    def _as_2d_tensor(value: torch.Tensor) -> torch.Tensor:
         if value.ndim == 1:
             return value.unsqueeze(0)
         if value.ndim == 3 and value.shape[0] == 1:
             return value.squeeze(0)
         return value
 
-    def _embed_token(self, token_id: int) -> Any:
+    def _embed_token(self, token_id: int) -> torch.Tensor:
         import torch
 
         token = torch.tensor([int(token_id)], dtype=torch.long, device=self._model_device())
@@ -362,7 +371,7 @@ def _embed_token(self, token_id: int) -> Any:
         embeds = embedder(token)
         return self._as_2d_tensor(embeds)
 
-    def _token_embedding_dtype(self) -> Any:
+    def _token_embedding_dtype(self) -> torch.dtype | None:
         """dtype of the decoder token embeddings, the unit's reference dtype.
 
         Official ``get_vllm_embedding`` casts vision hidden states to the token
@@ -376,7 +385,7 @@ def _token_embedding_dtype(self) -> Any:
             return dtype
         return getattr(next(self.thinker.parameters()), "dtype", None)
 
-    def _token_embedder(self) -> Any:
+    def _token_embedder(self) -> Callable[[torch.Tensor], torch.Tensor]:
         nested_embed = getattr(getattr(getattr(self.thinker, "llm", None), "model", None), "embed_tokens", None)
         if callable(nested_embed):
             return nested_embed
@@ -391,7 +400,7 @@ def _token_embedder(self) -> Any:
                     return embedder
         raise AttributeError("MiniCPM-o stage0 model does not expose token embeddings")
 
-    def _model_device(self) -> Any:
+    def _model_device(self) -> torch.device | str:
         try:
             return next(self.thinker.parameters()).device
         except Exception:
@@ -402,14 +411,14 @@ def _model_device(self) -> Any:
             pass
         return self.device
 
-    def _streaming_chunk_size(self, processor: Any | None = None) -> int:
+    def _streaming_chunk_size(self, processor: Any | None = None) -> int:  # Any: remote-code processor
         processor = processor or self.processor
         get_chunk = getattr(processor, "get_streaming_chunk_size", None)
         if callable(get_chunk):
             return int(get_chunk())
         return 16000
 
-    def _sample_rate(self, processor: Any | None = None) -> int:
+    def _sample_rate(self, processor: Any | None = None) -> int:  # Any: remote-code processor
         processor = processor or self.processor
         return int(
             self._stage_param(
@@ -418,7 +427,7 @@ def _sample_rate(self, processor: Any | None = None) -> int:
             )
         )
 
-    def _first_chunk_samples(self, default_chunk_size: int, processor: Any | None = None) -> int:
+    def _first_chunk_samples(self, default_chunk_size: int, processor: Any | None = None) -> int:  # Any: processor
         processor = processor or self.processor
         if getattr(processor, "_streaming_mel_processor", None) is None:
             return default_chunk_size
@@ -427,7 +436,7 @@ def _first_chunk_samples(self, default_chunk_size: int, processor: Any | None =
     def _pad_first_audio_chunk_if_needed(
         self,
         state: _MiniCPMO45Stage0SessionState,
-        processor: Any | None = None,
+        processor: Any | None = None,  # Any: remote-code processor
     ) -> None:
         if state.audio_chunk_idx != 0 or len(state.audio_buffer) == 0:
             return
@@ -440,7 +449,7 @@ def _pad_first_audio_chunk_if_needed(
         padding: np.ndarray = np.zeros(first_chunk_samples - len(state.audio_buffer), dtype=np.float32)
         state.audio_buffer = np.concatenate([padding, state.audio_buffer])
 
-    def _stage_param(self, name: str, default: Any) -> Any:
+    def _stage_param(self, name: str, default: object) -> Any:  # Any: attribute read off the remote-code model
         for target in (self.stage_model, self.thinker, getattr(self.thinker, "llm", None)):
             value = getattr(target, name, None)
             if value is not None:
@@ -455,7 +464,7 @@ def _consumed_audio_samples(
         chunk_idx: int,
         default_chunk_size: int,
         *,
-        processor: Any | None = None,
+        processor: Any | None = None,  # Any: remote-code processor
     ) -> int:
         processor = processor or self.processor
         if chunk_idx != 0:
@@ -472,11 +481,11 @@ def _consumed_audio_samples(
 
     def _process_streaming_audio(
         self,
-        audio_chunk: Any,
+        audio_chunk: NDArray[np.float32],
         chunk_idx: int,
         *,
-        processor: Any | None = None,
-    ) -> Any:
+        processor: Any | None = None,  # Any: remote-code processor
+    ) -> Any:  # Any: transformers BatchFeature (or the dict fallback below)
         processor = processor or self.processor
         process = getattr(processor, "process_audio_streaming", None)
         if callable(process):
@@ -488,10 +497,10 @@ def _process_streaming_audio(
 
     def _stage_audio_embeddings(
         self,
-        batch_feature: Any,
+        batch_feature: Any,  # Any: transformers BatchFeature
         *,
         state: _MiniCPMO45Stage0SessionState | None = None,
-    ) -> Any | None:
+    ) -> torch.Tensor | None:
         if hasattr(batch_feature, "to"):
             batch_feature = batch_feature.to(self.device)
         self._ensure_dynamic_cache_compat()
@@ -534,17 +543,17 @@ def _stage_audio_embeddings(
                 self.thinker.audio_past_key_values = previous_audio_past_key_values
 
     @staticmethod
-    def _decode_ref_audio_from_session_config(session_config: dict[str, Any]) -> Any | None:
+    def _decode_ref_audio_from_session_config(session_config: dict[str, object]) -> NDArray[np.float32] | None:
         from vllm_omni.model_executor.models.minicpmo_4_5.duplex.input import decode_native_ref_audio_from_config
 
         return decode_native_ref_audio_from_config({"extra_body": session_config})
 
     def _stage_ref_audio_embeddings(
         self,
-        ref_audio: Any,
+        ref_audio: NDArray[np.float32],
         *,
         state: _MiniCPMO45Stage0SessionState | None = None,
-    ) -> Any | None:
+    ) -> torch.Tensor | None:
         process_audio = getattr(self.processor, "process_audio", None)
         if callable(process_audio):
             batch_feature = process_audio([ref_audio])
@@ -606,16 +615,16 @@ def get_usable_length(self, new_seq_length: int | None = None, layer_idx: int =
         DynamicCache.get_usable_length = get_usable_length  # type: ignore[attr-defined]
 
     @staticmethod
-    def _cat_nested_tensors(value: Any) -> Any | None:
+    def _cat_nested_tensors(value: object) -> torch.Tensor | None:
         import torch
 
-        tensors = []
+        tensors: list[torch.Tensor] = []
 
-        def collect(item: Any) -> None:
+        def collect(item: object) -> None:
             if item is None:
                 return
             if hasattr(item, "detach"):
-                tensors.append(item)
+                tensors.append(cast("torch.Tensor", item))
                 return
             if isinstance(item, dict):
                 for child in item.values():
@@ -655,7 +664,7 @@ def _special_token_ids(self) -> dict[str, int]:
         }
 
     @staticmethod
-    def _load_processor_from_path(model_path: str | None) -> Any | None:
+    def _load_processor_from_path(model_path: str | None) -> Any | None:  # Any: remote-code AutoProcessor
         if not model_path:
             return None
         try:
@@ -752,7 +761,7 @@ def _audio_embedding_placeholder_token_id(self) -> int:
         return self.stage_padding_token_id()
 
     @staticmethod
-    def _decode_audio_payload(payload: dict[str, Any]) -> Any:
+    def _decode_audio_payload(payload: dict[str, object]) -> NDArray[np.float32]:
         audio = payload.get("audio") or payload.get("data")
         if not isinstance(audio, str):
             raise ValueError("audio append payload requires base64 audio")
@@ -762,7 +771,7 @@ def _decode_audio_payload(payload: dict[str, Any]) -> Any:
         return np.frombuffer(base64.b64decode(audio), dtype=np.float32)
 
     @staticmethod
-    def _decode_video_frames_payload(payload: dict[str, Any]) -> list[Any]:
+    def _decode_video_frames_payload(payload: dict[str, object]) -> list[Image.Image]:
         """Decode omni-duplex camera frames (base64 JPEG/PNG) to PIL images."""
         frames = payload.get("video_frames")
         if not isinstance(frames, list) or not frames:
@@ -771,7 +780,7 @@ def _decode_video_frames_payload(payload: dict[str, Any]) -> list[Any]:
 
         from PIL import Image
 
-        decoded: list[Any] = []
+        decoded: list[Image.Image] = []
         for frame_b64 in frames:
             if not isinstance(frame_b64, str) or not frame_b64:
                 continue
@@ -826,7 +835,7 @@ def _official_max_slice_nums(self, frame_count: int) -> list[int]:
             return [1]
         return [2] + [1] * (frame_count - 1)
 
-    def _encode_processed_vision(self, processed: Any) -> list[Any] | None:
+    def _encode_processed_vision(self, processed: Any) -> list[torch.Tensor] | None:  # Any: BatchFeature
         targets = (self.stage_model, self.thinker, getattr(self.stage_model, "model", None))
         for target in targets:
             if target is None:
@@ -842,8 +851,8 @@ def _encode_processed_vision(self, processed: Any) -> list[Any] | None:
                 device, dtype = vpm_param.device, vpm_param.dtype
                 pixel_nested = processed["pixel_values"]
                 tgt_nested = processed["tgt_sizes"]
-                flat_pixels: list[Any] = []
-                flat_tgt: list[Any] = []
+                flat_pixels: list[torch.Tensor] = []
+                flat_tgt: list[torch.Tensor] = []
                 for image_slices, image_tgt in zip(pixel_nested, tgt_nested):
                     for slice_pixels in image_slices:
                         flat_pixels.append(slice_pixels.to(device=device, dtype=dtype))
@@ -858,7 +867,7 @@ def _encode_processed_vision(self, processed: Any) -> list[Any] | None:
                 return None
             expected = MiniCPMO45DuplexPolicy.VISION_EMBEDS_PER_FRAME
             embed_dtype = self._token_embedding_dtype()
-            out: list[Any] = []
+            out: list[torch.Tensor] = []
             for block in hidden:
                 block_2d = self._as_2d_tensor(block)
                 if int(block_2d.shape[0]) != expected:
@@ -869,7 +878,7 @@ def _encode_processed_vision(self, processed: Any) -> list[Any] | None:
             return out
         return None
 
-    def _stage_vision_embeddings(self, frames: list[Any]) -> list[list[Any]] | None:
+    def _stage_vision_embeddings(self, frames: list[Image.Image]) -> list[list[torch.Tensor]] | None:
         """Encode camera frames for omni duplex via the loaded vision tower.
 
         Official ``streaming_prefill`` encodes each ``frame_list`` entry as its
@@ -883,7 +892,7 @@ def _stage_vision_embeddings(self, frames: list[Any]) -> list[list[Any]] | None:
         process_image = getattr(self.processor, "process_image", None)
         if not callable(process_image):
             return None
-        out: list[list[Any]] = []
+        out: list[list[torch.Tensor]] = []
         for frame, max_slices in zip(frames, self._official_max_slice_nums(len(frames))):
             try:
                 processed = process_image([frame], max_slice_nums=max_slices)
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_omni.py b/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_omni.py
index 60252e78c55..b1c8db89c6e 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_omni.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_omni.py
@@ -157,15 +157,13 @@ def prepare_duplex_sampling(
         del sampling_metadata
         self._minicpmo45_active_duplex_rows = [row.row_idx for row in rows]
         self._minicpmo45_duplex_row_sessions = {
-            row.row_idx: (row.session_id, row.incarnation) for row in rows if row.session_id is not None
+            row.row_idx: row.session_id for row in rows if row.session_id is not None
         }
         request_sessions = getattr(self, "_minicpmo45_duplex_request_sessions", None)
         if not isinstance(request_sessions, dict):
             request_sessions = {}
             self._minicpmo45_duplex_request_sessions = request_sessions
-        request_sessions.update(
-            {row.request_id: (row.session_id, row.incarnation) for row in rows if row.session_id is not None}
-        )
+        request_sessions.update({row.request_id: row.session_id for row in rows if row.session_id is not None})
         self._minicpmo45_duplex_row_payloads = {row.row_idx: row.payload for row in rows if row.payload is not None}
         self._minicpmo45_duplex_row_max_tokens = {
             row.row_idx: row.max_tokens for row in rows if row.max_tokens is not None
@@ -199,7 +197,7 @@ def prepare_duplex_sampling(
             force_listen = payload.get("force_listen") is True
             is_speech = payload.get("is_speech")
             segment_key = (row.request_id, row.seq if row.seq is not None else -1)
-            session_key = (row.session_id, row.incarnation) if row.session_id is not None else None
+            session_key = row.session_id
             if turn_eos_id >= 0 and session_key is not None:
                 state = helper_sessions.get(session_key) if isinstance(helper_sessions, dict) else None
                 pending_speech_context = (
@@ -326,16 +324,12 @@ def preprocess(
 
         helper = self._duplex_data_plane_helper()
         session_id = str(duplex.get("session_id") or "")
-        try:
-            incarnation = int(duplex.get("incarnation", 0))
-        except (TypeError, ValueError):
-            incarnation = 0
         payload = duplex.get("payload")
         if not session_id or not isinstance(payload, dict):
             embeds = input_embeds if input_embeds is not None else self.get_input_embeddings(input_ids)
             return input_ids, embeds, {"duplex": {"prefill_success": False, "reason": "bad_duplex_payload"}}
 
-        session_key = (session_id, incarnation)
+        session_key = session_id
         state = helper.sessions.get(session_key)
         if state is None:
             from vllm_omni.model_executor.models.minicpmo_4_5.duplex.stage0 import (
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/pipeline.py b/vllm_omni/model_executor/models/minicpmo_4_5/pipeline.py
index e48328d0b49..e7539384511 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/pipeline.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/pipeline.py
@@ -24,13 +24,7 @@
     model_type="minicpmo_4_5",
     default_deploy_config_name="minicpmo_4_5.yaml",
     model_arch="MiniCPMO45OmniForConditionalGeneration",
-    duplex_runtime_extension=(
-        "vllm_omni.model_executor.models.minicpmo_4_5.duplex.runtime.MiniCPMO45DuplexRuntimeExtension"
-    ),
-    duplex_serving_adapter=(
-        "vllm_omni.model_executor.models.minicpmo_4_5.duplex.serving_adapter.MiniCPMO45ServingRuntimeAdapter"
-    ),
-    duplex_control_enabled=True,
+    duplex_plugin="vllm_omni.model_executor.models.minicpmo_4_5.duplex.plugin.MiniCPMO45DuplexPlugin",
     # MiniCPM-o 4.5's HF config.json reports `model_type="minicpmo"` and
     # `architectures=["MiniCPMO"]` — both shared verbatim with older MiniCPM-o
     # 1.0 / 2.6 checkpoints. The only field distinguishing the generations is
diff --git a/vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py b/vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py
index 80995f92ef2..1c374be8552 100644
--- a/vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py
+++ b/vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py
@@ -690,9 +690,6 @@ def _native_duplex_data_plane_metadata(streaming_context) -> dict[str, object] |
     session_id = duplex_state.get("session_id")
     if isinstance(session_id, str) and session_id:
         metadata["session_id"] = session_id
-    incarnation = duplex_state.get("incarnation")
-    if isinstance(incarnation, int):
-        metadata["incarnation"] = incarnation
     epoch = duplex_state.get("epoch")
     if isinstance(epoch, int):
         metadata["epoch"] = epoch
diff --git a/vllm_omni/utils/audio_resample.py b/vllm_omni/utils/audio_resample.py
new file mode 100644
index 00000000000..fc6230f6e10
--- /dev/null
+++ b/vllm_omni/utils/audio_resample.py
@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Streaming resampling, shared by the engine and the entrypoints.
+
+Lives here rather than beside the OpenAI audio mixin because the duplex
+engine needs it too, and engine code must not import the entrypoints layer.
+Pure numpy on purpose: importing this must not pull in torch or the API
+server.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+__all__ = ["StreamingAudioResampler"]
+
+
+class StreamingAudioResampler:
+    """Stateful polyphase resampler for streaming mono float audio.
+
+    Retains filter state so output is invariant to input chunk boundaries.
+    """
+
+    _half_filter_width = 10
+    _kaiser_beta = 5.0
+    max_polyphase_factor = 2_048
+
+    def __init__(self, source_rate: int, target_rate: int):
+        if source_rate <= 0 or target_rate <= 0:
+            raise ValueError("Audio sample rates must be positive")
+        self.source_rate = source_rate
+        self.target_rate = target_rate
+        rate_gcd = math.gcd(source_rate, target_rate)
+        self._up = target_rate // rate_gcd
+        self._down = source_rate // rate_gcd
+        if max(self._up, self._down) > self.max_polyphase_factor:
+            raise ValueError("source and target sample rates have an unsupported resampling ratio")
+        self._half_len, self._phase_kernels = self._design_polyphase_filter()
+        self._history_samples = self._phase_kernels.shape[1] - 1
+        self.reset()
+
+    def _design_polyphase_filter(self) -> tuple[int, np.ndarray]:
+        if self._up == self._down:
+            return 0, np.ones((1, 1), dtype=np.float32)
+
+        max_rate = max(self._up, self._down)
+        half_len = self._half_filter_width * max_rate
+        offsets = np.arange(-half_len, half_len + 1, dtype=np.float64)
+        cutoff = 1.0 / max_rate
+        taps = cutoff * np.sinc(cutoff * offsets)
+        taps *= np.kaiser(taps.size, self._kaiser_beta)
+        taps /= np.sum(taps)
+        taps *= self._up
+        taps = np.ascontiguousarray(taps, dtype=np.float32)
+
+        phases = [taps[phase :: self._up] for phase in range(self._up)]
+        phase_width = max(phase.size for phase in phases)
+        kernels = np.zeros((self._up, phase_width), dtype=np.float32)
+        for phase_index, phase in enumerate(phases):
+            kernels[phase_index, -phase.size :] = phase[::-1]
+        return half_len, kernels
+
+    @property
+    def scratch_bytes(self) -> int:
+        pending_samples = self._ceil_div(self._input_samples * self._up, self._down) - self._output_samples
+        return max(0, pending_samples) * np.dtype(np.float32).itemsize
+
+    @staticmethod
+    def _ceil_div(numerator: int, denominator: int) -> int:
+        return -(-numerator // denominator)
+
+    def _render_outputs(
+        self,
+        combined: np.ndarray,
+        *,
+        first_output: int,
+        output_count: int,
+        input_start: int,
+    ) -> np.ndarray:
+        if output_count <= 0:
+            return np.empty(0, dtype=np.float32)
+
+        output_indexes = np.arange(first_output, first_output + output_count, dtype=np.int64)
+        filter_indexes = output_indexes * self._down + self._half_len
+        source_indexes = filter_indexes // self._up
+        phases = filter_indexes % self._up
+        windows = np.lib.stride_tricks.sliding_window_view(
+            combined,
+            self._phase_kernels.shape[1],
+        )
+        selected_windows = windows[source_indexes - input_start]
+        return np.sum(
+            selected_windows * self._phase_kernels[phases],
+            axis=1,
+            dtype=np.float32,
+        )
+
+    def _push(self, chunk: np.ndarray) -> np.ndarray:
+        if chunk.size == 0:
+            return np.empty(0, dtype=np.float32)
+        if self._flushed:
+            raise RuntimeError("cannot process audio after the resampler has been finalized; call reset first")
+
+        combined = np.concatenate((self._history, chunk))
+        next_input_samples = self._input_samples + chunk.size
+        stable_output_samples = max(
+            0,
+            self._ceil_div(next_input_samples * self._up - self._half_len, self._down),
+        )
+        output = self._render_outputs(
+            combined,
+            first_output=self._output_samples,
+            output_count=stable_output_samples - self._output_samples,
+            input_start=self._input_samples,
+        )
+        if self._history_samples:
+            self._history = combined[-self._history_samples :].copy()
+        self._input_samples = next_input_samples
+        self._output_samples = stable_output_samples
+        return output
+
+    def _flush(self) -> np.ndarray:
+        if self._flushed:
+            return np.empty(0, dtype=np.float32)
+
+        total_output_samples = self._ceil_div(self._input_samples * self._up, self._down)
+        output_count = total_output_samples - self._output_samples
+        if output_count:
+            last_output = total_output_samples - 1
+            last_source_index = (last_output * self._down + self._half_len) // self._up
+            right_padding = max(0, last_source_index - self._input_samples + 1)
+            combined = np.concatenate((self._history, np.zeros(right_padding, dtype=np.float32)))
+            output = self._render_outputs(
+                combined,
+                first_output=self._output_samples,
+                output_count=output_count,
+                input_start=self._input_samples,
+            )
+        else:
+            output = np.empty(0, dtype=np.float32)
+        self._output_samples = total_output_samples
+        self._flushed = True
+        return output
+
+    def process(self, audio: np.ndarray, *, final: bool = False) -> np.ndarray:
+        chunk = np.asarray(audio, dtype=np.float32)
+        if chunk.ndim != 1:
+            raise ValueError(f"Streaming audio resampling only supports mono audio, got shape {chunk.shape}")
+        chunk = np.ascontiguousarray(chunk, dtype=np.float32)
+        output = self._push(chunk)
+        if not final:
+            return output
+        tail = self._flush()
+        if not output.size:
+            return tail
+        if not tail.size:
+            return output
+        return np.concatenate((output, tail))
+
+    def reset(self) -> None:
+        self._history = np.zeros(self._history_samples, dtype=np.float32)
+        self._input_samples = 0
+        self._output_samples = 0
+        self._flushed = False

From 507cb1d834db66f2dbb776602e82c62d58e92992 Mon Sep 17 00:00:00 2001
From: SYLAR <125541396+lishunyang12@users.noreply.github.com>
Date: Wed, 16 Sep 2026 15:47:31 +0800
Subject: [PATCH 027/105] [Attention] [P1] Keep H3 VSA policy in the model and
 share sparse primitives (#7535)

Signed-off-by: lishunyang12 <lishunyang12@users.noreply.github.com>
Co-authored-by: lishunyang12 <lishunyang12@users.noreply.github.com>
---
 .../feature/attention_backend_selection.md    |  38 ++-
 .../attention_backends/fastvideo_vsa.md       |  76 ++++--
 pyproject.toml                                |   5 +
 .../attention/test_block_sparse_ops.py        | 126 +++++++++
 .../diffusion/attention/test_fastvideo_vsa.py | 164 +----------
 .../attention/test_impl_overrides.py          | 136 +++++++++
 .../cache/test_teacache_extractors.py         |  10 +-
 .../minimax_h3/test_minimax_h3_modulation.py  |   2 +-
 .../models/minimax_h3/test_vsa_layout.py      | 221 +++++++++++++++
 tests/helpers/runtime.py                      |  62 ++++-
 .../tests/test_runtime_server_ports.py        | 109 ++++++++
 .../attention/backends/fastvideo_vsa.py       | 258 +-----------------
 vllm_omni/diffusion/attention/layer.py        |  34 ++-
 .../diffusion/attention/ops/block_sparse.py   | 115 ++++++++
 .../diffusion/cache/teacache/extractors.py    |   2 +-
 .../indexed_modulation.py}                    |   4 +-
 .../models/minimax_h3/attention/__init__.py   |   2 +
 .../minimax_h3/attention/fastvideo_h3.py      | 209 ++++++++++++++
 .../minimax_h3/minimax_h3_transformer.py      |  15 +-
 19 files changed, 1116 insertions(+), 472 deletions(-)
 create mode 100644 tests/diffusion/attention/test_block_sparse_ops.py
 create mode 100644 tests/diffusion/attention/test_impl_overrides.py
 create mode 100644 tests/diffusion/models/minimax_h3/test_vsa_layout.py
 create mode 100644 tests/helpers/tests/test_runtime_server_ports.py
 create mode 100644 vllm_omni/diffusion/attention/ops/block_sparse.py
 rename vllm_omni/diffusion/{attention/ops/minimax_h3_modulation.py => layers/indexed_modulation.py} (98%)
 create mode 100644 vllm_omni/diffusion/models/minimax_h3/attention/__init__.py
 create mode 100644 vllm_omni/diffusion/models/minimax_h3/attention/fastvideo_h3.py

diff --git a/docs/design/feature/attention_backend_selection.md b/docs/design/feature/attention_backend_selection.md
index 41cbaf3ff32..3ae1115b1b0 100644
--- a/docs/design/feature/attention_backend_selection.md
+++ b/docs/design/feature/attention_backend_selection.md
@@ -76,6 +76,34 @@ preserve common `self` or `cross` policies. A model also decides whether its
 path is compatible with automatic TRTLLM selection, because only the model
 knows whether masking and packing satisfy the kernel contract.
 
+### Model-owned implementation specializations
+
+Use `Attention(..., impl_overrides={backend_name: implementation_class})`
+when a model needs different computation within an existing backend contract.
+The model defines the implementation in its own directory and passes it when
+constructing the layer:
+
+```python
+# MyModelVSAImpl is a model-owned subclass of FastVideoVSAImpl.
+self.attention = Attention(
+    num_heads=num_heads,
+    head_size=head_size,
+    softmax_scale=head_size**-0.5,
+    causal=False,
+    role="self",
+    impl_overrides={"FASTVIDEO_VSA": MyModelVSAImpl},
+)
+```
+
+The override is applied after role/platform selection, keyed by the selected
+backend's `get_name()`. It must subclass the **selected implementation**;
+incompatible platform implementations raise `TypeError`. Unselected overrides
+have no effect. Backend capabilities, constructor options, and shared
+parallel dispatch remain unchanged and must be honored by the specialization.
+
+Use a new backend for a new provider/capability contract. `custom_attention`
+instead owns communication and requires `skip_sequence_parallel=True`.
+
 ## Adding or changing a backend
 
 An implementation change is complete only when it:
@@ -91,8 +119,9 @@ An implementation change is complete only when it:
 
 ## FastVideo VSA model metadata
 
-FastVideo VSA support is scoped to `FastVideo/FastWan2.2-TI2V-5B-Diffusers`, whose text-to-video and image-to-video modes both use `Wan22Pipeline`. It operates on a flattened DiT sequence but partitions tokens in
-the original latent video grid. Wan integrations therefore attach the
+FastWan's text-to-video and image-to-video modes both use `Wan22Pipeline`.
+It operates on a flattened DiT sequence but partitions tokens in the original
+latent video grid. Wan integrations therefore attach the
 post-patch `(T, H, W)` shape as `vsa_dit_seq_shape` attention metadata. The
 backend validates that `T * H * W` equals the sequence length, derives the
 runtime block count, and selects the configured top-k key/value blocks for
@@ -104,3 +133,8 @@ the checkpoint contains those weights. Checkpoints without the projection do
 not allocate or execute it. When top-k selects every block, native checkpoints
 route to SDPA, while FastVideo DMD checkpoints preserve the VSA all-block path
 to retain checkpoint semantics.
+
+MiniMax-H3 supplies `MiniMaxH3VSAImpl` through `impl_overrides`.
+`models/minimax_h3/attention/fastvideo_h3.py` owns its prefix layout, video tiling, and
+learned compression gate. Pooling, block-map construction, and tile64 provider
+calls are shared through `attention/ops/block_sparse.py`.
diff --git a/docs/user_guide/diffusion/attention_backends/fastvideo_vsa.md b/docs/user_guide/diffusion/attention_backends/fastvideo_vsa.md
index c03b9ffdeaf..df6e34b0c4c 100644
--- a/docs/user_guide/diffusion/attention_backends/fastvideo_vsa.md
+++ b/docs/user_guide/diffusion/attention_backends/fastvideo_vsa.md
@@ -1,24 +1,33 @@
 # FastVideo VSA
 
-FastVideo Variable Sparse Attention (VSA) accelerates the `FastVideo/FastWan2.2-TI2V-5B-Diffusers` model's
-self-attention by partitioning the post-patch latent grid into spatiotemporal
+FastVideo Variable Sparse Attention (VSA) partitions the post-patch latent grid into spatiotemporal
 blocks. For every query block, VSA scores the key/value blocks and computes
 attention only against the selected top-k blocks.
 
-The supported checkpoint provides both text-to-video and image-to-video modes through `Wan22Pipeline`; the separate Wan I2V-14B, S2V, and VACE pipelines are outside this backend's supported scope.
+## Supported models
 
-MiniMax-H3 served with a FastH3 VSA adapter uses a second, H3-specific route
-through the same backend. See the
-[MiniMax-H3 recipe](https://recipes.vllm.ai/MiniMaxAI/MiniMax-H3) for its geometry,
-supported topologies, and commands.
+| Model / checkpoint | Required adapter | Tasks | Sequence parallelism |
+| --- | --- | --- | --- |
+| `FastVideo/FastWan2.2-TI2V-5B-Diffusers` | None | T2V, I2V through `Wan22Pipeline` | Disabled |
+| `MiniMaxAI/MiniMax-H3` | [FastH3 VSA (recipe)](https://github.com/vllm-project/vllm-omni/blob/main/recipes/MiniMaxAI/MiniMax-H3.md#fasth3-adapter) | T2VA | Disabled or pure Ulysses |
+| Wan I2V-14B, S2V, VACE | — | Unsupported | — |
 
-VSA is a CUDA-only, explicitly selected backend. It requires the
-`fastvideo-kernel` package and currently supports non-causal self-attention
-with equal query and key/value sequence lengths. Unsupported shapes, masks,
-dtypes, sequence-parallel execution, or kernel failures fall back to
-`TORCH_SDPA` and emit a warning with the reason. On the Wan route, an active
-sequence-parallel context is one of those fallbacks; the H3 route supports pure
-Ulysses and rejects ring or all-gather sequence parallelism at startup.
+## Installation
+
+Install vLLM-Omni from this checkout with the `vsa` extra:
+
+```bash
+uv pip install -e '.[vsa]'
+```
+
+The extra installs the tested kernel dependency automatically. Prebuilt kernels require
+Linux, Python 3.12, and glibc 2.34 or newer (x86-64 or aarch64). The full
+FastVideo framework and provider environment variables are not required.
+
+`FASTVIDEO_VSA` selects the attention algorithm. On SM120, the H3 integration
+currently executes FastVideo's 64-token Triton block-sparse kernel; it does not
+dispatch to FlashInfer. The `vsa` extra installs `fastvideo-kernel==0.3.4` for
+this execution path.
 
 ## Enable the backend
 
@@ -27,24 +36,18 @@ flag. Use `--fastvideo-vsa-topk` to set the number of key/value blocks retained
 for every query block:
 
 ```bash
-vllm-omni serve <model> \
+vllm serve <model> --omni \
   --diffusion-attention-backend FASTVIDEO_VSA \
   --fastvideo-vsa-topk 64
 ```
 
-The backwards-compatible environment variable selects the backend with the
-default `topk=64`:
-
-```bash
-export DIFFUSION_ATTENTION_BACKEND=FASTVIDEO_VSA
-vllm-omni serve <model>
-```
+<details markdown="1">
+<summary>Alternative configuration formats</summary>
 
-To tune top-k, pass the CLI backend and top-k flags together as shown above,
-or use the equivalent structured configuration:
+Equivalent structured configuration:
 
 ```bash
-vllm-omni serve <model> \
+vllm serve <model> --omni \
   --diffusion-attention-config \
   '{"default":{"backend":"FASTVIDEO_VSA","fastvideo_vsa_topk":64}}'
 ```
@@ -73,8 +76,15 @@ stages:
         fastvideo_vsa_topk: 64
 ```
 
+</details>
+
 ## Choose top-k
 
+H3 uses 64-token video blocks and keeps
+all prefix blocks; see the [FastH3 VSA recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/MiniMaxAI/MiniMax-H3.md#fasth3-adapter).
+
+### Wan top-k behavior
+
 At runtime the backend logs the sequence shape and derived block count:
 
 ```text
@@ -117,8 +127,16 @@ selecting VSA does not turn a native checkpoint into a distilled model.
 
 ## Verify routing and fallback
 
-Check the startup and first-forward logs instead of assuming that selecting
-the backend guarantees sparse execution:
+VSA is a CUDA-only, explicitly selected backend. It requires the
+`fastvideo-kernel` package and currently supports non-causal self-attention
+with equal query and key/value sequence lengths. Unsupported shapes, masks,
+dtypes, sequence-parallel execution, or kernel failures fall back to
+`TORCH_SDPA` and emit a warning with the reason. On the Wan route, an active
+sequence-parallel context is one of those fallbacks; the H3 route supports pure
+Ulysses and rejects ring or all-gather sequence parallelism at startup.
+H3 accelerator faults propagate instead of attempting dense recovery.
+
+On the Wan route, check the startup and first-forward logs:
 
 - `route=VSA` means top-k block selection is active.
 - `route=VSA_ALL_BLOCKS` means the FastVideo DMD checkpoint retained all
@@ -126,6 +144,10 @@ the backend guarantees sparse execution:
 - `route=SDPA` or `FASTVIDEO_VSA falling back to SDPA: ...` means dense SDPA
   executed; the warning includes the reason.
 
+For H3, check `FastH3 adapter active` at startup and
+`FASTVIDEO_VSA H3 routing` during DiT execution, as described in the
+[model recipe](https://github.com/vllm-project/vllm-omni/blob/main/recipes/MiniMaxAI/MiniMax-H3.md#fasth3-adapter).
+
 The Wan route requires CUDA tensors in FP16 or BF16, 256-token blocks,
 standard `head_size**-0.5` scaling, equal Q/K/V head counts, no attention mask,
 and no active sequence-parallel context. The MiniMax-H3 route uses 64-token
diff --git a/pyproject.toml b/pyproject.toml
index fc1d5573b93..434c4305c40 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -123,6 +123,11 @@ fa4 = [
     "flash-attn-4[cu13]==4.0.0b18",
 ]
 
+# FastVideo VSA kernels for the supported Linux/Python 3.12 wheel environment.
+vsa = [
+    "fastvideo-kernel==0.3.4",
+]
+
 docs = [
     "mkdocs>=1.5.0",
     "mkdocs-api-autonav",
diff --git a/tests/diffusion/attention/test_block_sparse_ops.py b/tests/diffusion/attention/test_block_sparse_ops.py
new file mode 100644
index 00000000000..845f09b4653
--- /dev/null
+++ b/tests/diffusion/attention/test_block_sparse_ops.py
@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import sys
+import types
+
+import pytest
+import torch
+from torch._subclasses.fake_tensor import FakeTensorMode
+
+from vllm_omni.diffusion.attention.ops.block_sparse import (
+    build_prefix_dense_block_map,
+    fastvideo_block_sparse_attn_bshd,
+    mean_pool_tiles,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+@pytest.mark.parametrize("prefix_blocks,topk", [(0, 1), (2, 0), (2, 1), (2, 3), (2, 5)])
+def test_block_map_keeps_prefix_dense_and_selects_non_prefix_keys(prefix_blocks, topk):
+    sparse_blocks = 3
+    blocks = prefix_blocks + sparse_blocks
+    scores = torch.arange(2 * blocks * blocks, dtype=torch.float32).reshape(1, 2, blocks, blocks)
+    block_map = build_prefix_dense_block_map(scores, prefix_blocks, sparse_blocks, topk)
+    expected = torch.zeros_like(scores, dtype=torch.bool)
+    # Scores increase with key index, so top-k always selects the last keys.
+    for query_block in range(blocks):
+        for key_block in range(blocks):
+            if (
+                query_block < prefix_blocks
+                or key_block < prefix_blocks
+                or key_block >= blocks - min(topk, sparse_blocks)
+            ):
+                expected[..., query_block, key_block] = True
+    assert torch.equal(block_map, expected)
+
+
+@pytest.mark.parametrize("block_size", [4, 32, 64])
+@pytest.mark.parametrize("dtype", [torch.float32, torch.bfloat16])
+def test_pooling_uses_valid_tile_sizes_and_fp32_accumulation(block_size, dtype):
+    sizes = torch.tensor([block_size, block_size - 1, 0], dtype=torch.int32)
+    tiles = torch.arange(2 * 3 * block_size * 2 * 3).reshape(2, 3, block_size, 2, 3).to(dtype)
+    tiles[:, 1, -1] = 0
+    tiles[:, 2] = 0
+    expected = torch.stack(
+        [tiles[:, 0].float().mean(dim=1), tiles[:, 1, :-1].float().mean(dim=1), torch.zeros(2, 2, 3)], dim=2
+    )
+    result = mean_pool_tiles(tiles.flatten(1, 2), sizes, block_size)
+    assert result.dtype == torch.float32
+    torch.testing.assert_close(result, expected, rtol=0, atol=0)
+
+
+def test_provider_wrapper_restores_transport_rows_and_bshd_layout(monkeypatch):
+    monkeypatch.delenv("FASTVIDEO_VSA_SM100A", raising=False)
+    calls = []
+
+    def block_sparse_attn(q, k, v, block_map, sizes):
+        calls.append((q.shape, block_map.shape, sizes.tolist()))
+        assert q.is_contiguous() and k.is_contiguous() and v.is_contiguous()
+        assert sizes.dtype == torch.int32
+        return q + k + v, None
+
+    module = types.ModuleType("fastvideo_kernel.block_sparse_attn")
+    setattr(module, "block_sparse_attn", block_sparse_attn)
+    monkeypatch.setitem(sys.modules, "fastvideo_kernel", types.ModuleType("fastvideo_kernel"))
+    monkeypatch.setitem(sys.modules, "fastvideo_kernel.block_sparse_attn", module)
+    query = torch.randn(1, 4 * 64, 2, 8)
+    block_map = torch.ones(1, 2, 4, 4, dtype=torch.bool)
+    sizes = torch.tensor([64, 17, 64, 0])
+    output = fastvideo_block_sparse_attn_bshd(query, query, query, block_map, sizes, 3)
+    expected = torch.zeros_like(query)
+    expected[:, : 3 * 64] = query[:, : 3 * 64] * 3
+    torch.testing.assert_close(output, expected)
+    assert calls == [(torch.Size([1, 2, 3 * 64, 8]), torch.Size([1, 2, 3, 3]), [64, 17, 64])]
+
+
+def test_custom_op_fake_preserves_metadata_without_loading_provider(monkeypatch):
+    monkeypatch.setitem(sys.modules, "fastvideo_kernel", None)
+    with FakeTensorMode():
+        query = torch.empty(1, 4 * 64, 2, 8, dtype=torch.bfloat16)
+        block_map = torch.empty(1, 2, 4, 4, dtype=torch.bool)
+        sizes = torch.empty(4, dtype=torch.int32)
+        output = fastvideo_block_sparse_attn_bshd(query, query, query, block_map, sizes, 3)
+        assert output.shape == query.shape
+        assert output.dtype == query.dtype
+        assert output.device == query.device
+
+
+@pytest.mark.parametrize("error_type", [ImportError, RuntimeError, torch.AcceleratorError])
+def test_native_provider_failure_only_recovers_without_accelerator_fault(monkeypatch, mocker, error_type):
+    monkeypatch.setenv("FASTVIDEO_VSA_SM100A", "1")
+    error = error_type("native provider failure")
+    native = mocker.Mock()
+    native.is_supported.return_value = True
+    native.block_sparse_attn_sm100a.side_effect = error
+    provider = types.ModuleType("fastvideo_kernel")
+    setattr(provider, "block_sparse_attn_sm100a", native)
+    index = types.ModuleType("fastvideo_kernel.triton_kernels.index")
+    setattr(
+        index,
+        "map_to_index",
+        mocker.Mock(return_value=(torch.zeros(1, dtype=torch.int32), torch.ones(1, dtype=torch.int32))),
+    )
+    triton = types.ModuleType("fastvideo_kernel.block_sparse_attn")
+    fallback = mocker.Mock(side_effect=lambda q, *args: (q.clone(), None))
+    setattr(triton, "block_sparse_attn", fallback)
+    monkeypatch.setitem(sys.modules, "fastvideo_kernel", provider)
+    monkeypatch.setitem(
+        sys.modules, "fastvideo_kernel.triton_kernels", types.ModuleType("fastvideo_kernel.triton_kernels")
+    )
+    monkeypatch.setitem(sys.modules, "fastvideo_kernel.triton_kernels.index", index)
+    monkeypatch.setitem(sys.modules, "fastvideo_kernel.block_sparse_attn", triton)
+    query = torch.arange(128 * 2 * 8, dtype=torch.float32).reshape(1, 128, 2, 8)
+    block_map = torch.ones(1, 2, 2, 2, dtype=torch.bool)
+    sizes = torch.tensor([64, 64], dtype=torch.int32)
+
+    if error_type is torch.AcceleratorError:
+        with pytest.raises(torch.AcceleratorError, match="native provider failure") as raised:
+            fastvideo_block_sparse_attn_bshd(query, query, query, block_map, sizes, 2)
+        assert raised.value is error
+        fallback.assert_not_called()
+    else:
+        output = fastvideo_block_sparse_attn_bshd(query, query, query, block_map, sizes, 2)
+        torch.testing.assert_close(output, query, rtol=0, atol=0)
+        fallback.assert_called_once()
diff --git a/tests/diffusion/attention/test_fastvideo_vsa.py b/tests/diffusion/attention/test_fastvideo_vsa.py
index 1bd7192ad7d..e5c854d8d47 100644
--- a/tests/diffusion/attention/test_fastvideo_vsa.py
+++ b/tests/diffusion/attention/test_fastvideo_vsa.py
@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-import math
 import sys
 import types
 from typing import Any
@@ -12,14 +11,10 @@
 from vllm_omni.diffusion.attention.backends.abstract import (
     AttentionMetadata,
     PackedPaddingMetadata,
-    VideoTokenLayout,
-    VideoTokenSpan,
 )
 from vllm_omni.diffusion.attention.backends.fastvideo_vsa import (
     FastVideoVSABackend,
     FastVideoVSAImpl,
-    _build_h3_block_map,
-    _get_h3_tile_metadata,
 )
 from vllm_omni.diffusion.attention.backends.registry import (
     DiffusionAttentionBackendEnum,
@@ -218,144 +213,8 @@ def test_fastvideo_vsa_allows_topk_equal_to_num_blocks():
     assert too_many._fallback_reason(query, query, query, metadata) == "topk 3 > num_blocks 2"
 
 
-def _h3_metadata(prefix_segments, video_shape, *, gate=None, packed_padding=None):
-    extra: dict[str, Any] = {
-        "vsa_h3_prefix_segments": prefix_segments,
-    }
-    if gate is not None:
-        extra["gate_compress"] = gate
-    return AttentionMetadata(
-        packed_padding=packed_padding,
-        video_layout=VideoTokenLayout(
-            used_len=sum(prefix_segments) + math.prod(video_shape),
-            video_spans=(VideoTokenSpan(start=sum(prefix_segments), latent_grid=video_shape, role="target"),),
-        ),
-        extra=extra,
-    )
-
-
-def _fake_block_sparse_kernel(monkeypatch, calls):
-    """Stand in for fastvideo_kernel.block_sparse_attn with a mask-obeying SDPA."""
-
-    def block_sparse_attn(q, k, v, block_map, variable_block_sizes):
-        calls["block_map"] = block_map.clone()
-        calls["variable_block_sizes"] = variable_block_sizes.tolist()
-        calls["q_shape"] = tuple(q.shape)
-        blocks = block_map.shape[-1]
-        assert blocks * 64 == q.shape[2]
-        # Expand the per-block map to a per-token mask so the stand-in honours
-        # the sparsity contract the real kernel implements, and drop the rows
-        # each partial block pads with, which the real kernel skips through
-        # variable_block_sizes.
-        token_mask = block_map.repeat_interleave(64, dim=-1).repeat_interleave(64, dim=-2)
-        within = torch.arange(64, device=q.device)[None, :] < variable_block_sizes[:, None]
-        token_mask = token_mask & within.reshape(1, 1, 1, -1)
-        out = torch.nn.functional.scaled_dot_product_attention(q.float(), k.float(), v.float(), attn_mask=token_mask)
-        return out.to(q.dtype), None
-
-    module = types.ModuleType("fastvideo_kernel.block_sparse_attn")
-    setattr(module, "block_sparse_attn", block_sparse_attn)
-    monkeypatch.setitem(sys.modules, "fastvideo_kernel", types.ModuleType("fastvideo_kernel"))
-    monkeypatch.setitem(sys.modules, "fastvideo_kernel.block_sparse_attn", module)
-
-
-def _h3_impl(**backend_kwargs):
-    kwargs = {"topk": 1, "min_seq_len": 1, "disable_when_sp_active": False}
-    kwargs.update(backend_kwargs)
-    return FastVideoVSAImpl(num_heads=2, head_size=8, softmax_scale=8**-0.5, backend_kwargs=kwargs)
-
-
-def test_h3_forward_tiles_untiles_and_restores_the_original_row_order(monkeypatch):
-    calls: dict[str, Any] = {}
-    _fake_block_sparse_kernel(monkeypatch, calls)
-    impl = _h3_impl(topk=64)
-    prefix_segments, video_shape = (5, 70), (2, 4, 4)
-    seq_len = sum(prefix_segments) + 2 * 4 * 4
-    torch.manual_seed(0)
-    query = torch.randn(1, seq_len, 2, 8, dtype=torch.bfloat16)
-
-    output = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape))
-
-    assert output.shape == query.shape
-    # topk covers every video block, so the block map is dense and the tiled
-    # kernel must reproduce plain attention over the same rows.
-    reference = torch.nn.functional.scaled_dot_product_attention(
-        *(x.float().transpose(1, 2) for x in (query, query, query))
-    ).transpose(1, 2)
-    torch.testing.assert_close(output.float(), reference, atol=2e-2, rtol=2e-2)
-    # 5 + 70 splits into segment-pure 5 | 64 | 6, then one (2, 4, 4) video tile.
-    assert calls["variable_block_sizes"] == [5, 64, 6, 32]
-
-
-def test_h3_forward_keeps_prefix_dense_and_selects_top_k_video_tiles(monkeypatch):
-    calls: dict[str, Any] = {}
-    _fake_block_sparse_kernel(monkeypatch, calls)
-    impl = _h3_impl(topk=1)
-    prefix_segments, video_shape = (5,), (8, 4, 4)
-    seq_len = 5 + 8 * 4 * 4
-    torch.manual_seed(0)
-    query = torch.randn(1, seq_len, 2, 8, dtype=torch.bfloat16)
-
-    impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape))
-
-    # 1 prefix block + 2 video blocks. The odd count is padded to an even one
-    # for the paired-CTA kernel contract, and the Triton route slices that
-    # transport-only partner off again before launching.
-    block_map = calls["block_map"]
-    assert block_map.shape[-1] == 3
-    assert calls["variable_block_sizes"] == [5, 64, 64]
-    assert block_map[:, :, :1, :].all(), "prefix queries stay dense"
-    assert block_map[..., :1].all(), "prefix keys are exempt from selection"
-    assert (block_map[:, :, 1:, 1:].sum(dim=-1) == 1).all(), "one video tile per video query"
-
-    # The same odd geometry must still untile back onto the original rows.
-    dense = _h3_impl(topk=64).forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape))
-    reference = torch.nn.functional.scaled_dot_product_attention(
-        *(x.float().transpose(1, 2) for x in (query, query, query))
-    ).transpose(1, 2)
-    torch.testing.assert_close(dense.float(), reference, atol=2e-2, rtol=2e-2)
-
-
-def test_h3_forward_applies_the_learned_compression_gate(monkeypatch):
-    _fake_block_sparse_kernel(monkeypatch, {})
-    impl = _h3_impl(topk=64)
-    prefix_segments, video_shape = (5,), (2, 4, 4)
-    seq_len = 5 + 2 * 4 * 4
-    torch.manual_seed(0)
-    query = torch.randn(1, seq_len, 2, 8, dtype=torch.bfloat16)
-
-    without_gate = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape))
-    zero_gate = torch.zeros_like(query)
-    with_zero_gate = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape, gate=zero_gate))
-    live_gate = torch.full_like(query, 0.5)
-    with_live_gate = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape, gate=live_gate))
-
-    torch.testing.assert_close(with_zero_gate.float(), without_gate.float())
-    assert not torch.allclose(with_live_gate.float(), without_gate.float())
-
-
-def test_h3_forward_restores_rows_the_packed_padding_excludes(monkeypatch):
-    _fake_block_sparse_kernel(monkeypatch, {})
-    impl = _h3_impl(topk=64)
-    prefix_segments, video_shape = (5,), (2, 4, 4)
-    valid = 5 + 2 * 4 * 4
-    torch.manual_seed(0)
-    query = torch.randn(1, valid + 24, 2, 8, dtype=torch.bfloat16)
-    padding = PackedPaddingMetadata(
-        q_length=valid,
-        kv_length=valid,
-        cu_seqlens_q=torch.tensor([0, valid], dtype=torch.int32),
-        cu_seqlens_k=torch.tensor([0, valid], dtype=torch.int32),
-    )
-
-    output = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape, packed_padding=padding))
-
-    assert output.shape == query.shape
-    assert torch.count_nonzero(output[:, valid:]) == 0
-
-
 def test_sdpa_fallback_never_attends_the_structural_padding(monkeypatch):
-    # The backend advertises supports_packed_mask_free, so MiniMax-H3 skips
+    # The backend advertises supports_packed_mask_free, so a model may skip
     # building the padding mask. Every fallback out of the VSA path must honour
     # that contract itself; SDPA reads attn_mask and nothing else.
     impl = FastVideoVSAImpl(
@@ -374,6 +233,8 @@ def test_sdpa_fallback_never_attends_the_structural_padding(monkeypatch):
         cu_seqlens_k=torch.tensor([0, valid], dtype=torch.int32),
     )
 
+    monkeypatch.setattr(impl.sdpa_fallback, "forward", impl.sdpa_fallback.forward_cuda)
+
     baseline = impl.forward_cuda(query, query, query, AttentionMetadata(packed_padding=padding, extra={}))
     perturbed_input = query.clone()
     perturbed_input[:, valid:] += 100.0
@@ -384,22 +245,3 @@ def test_sdpa_fallback_never_attends_the_structural_padding(monkeypatch):
     assert baseline.shape == query.shape
     torch.testing.assert_close(baseline[:, :valid], perturbed[:, :valid])
     assert torch.count_nonzero(baseline[:, valid:]) == 0
-
-
-def test_h3_geometry_keeps_prefix_segments_pure_and_tiles_video_3d():
-    partition, sizes, non_pad, untile, prefix_blocks, video_blocks = _get_h3_tile_metadata(
-        (5, 70, 9), (5, 6, 6), torch.device("cpu")
-    )
-    assert sizes[:4].tolist() == [5, 64, 6, 9]
-    assert prefix_blocks == 4
-    assert video_blocks == 8
-    assert int(sizes.sum()) == 5 + 70 + 9 + 5 * 6 * 6
-    assert partition.numel() == non_pad.numel() == untile.numel() == int(sizes.sum())
-
-
-def test_h3_block_map_makes_prefix_queries_dense_and_prefix_keys_exempt():
-    scores = torch.arange(1 * 2 * 5 * 5, dtype=torch.float32).reshape(1, 2, 5, 5)
-    block_map = _build_h3_block_map(scores, num_prefix_blocks=2, num_video_blocks=3, topk=1)
-    assert block_map[:, :, :2].all()
-    assert block_map[..., :2].all()
-    assert (block_map[:, :, 2:, 2:].sum(dim=-1) == 1).all()
diff --git a/tests/diffusion/attention/test_impl_overrides.py b/tests/diffusion/attention/test_impl_overrides.py
new file mode 100644
index 00000000000..f7755de5c05
--- /dev/null
+++ b/tests/diffusion/attention/test_impl_overrides.py
@@ -0,0 +1,136 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import pytest
+
+from vllm_omni.diffusion.attention import layer
+from vllm_omni.diffusion.attention.backends.fastvideo_vsa import FastVideoVSABackend, FastVideoVSAImpl
+from vllm_omni.diffusion.attention.backends.sdpa import SDPABackend
+from vllm_omni.diffusion.attention.parallel.base import NoParallelAttention
+from vllm_omni.diffusion.data import AttentionSpec
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+class _SpecializedImpl(FastVideoVSAImpl):
+    pass
+
+
+@pytest.fixture
+def local_attention(monkeypatch):
+    monkeypatch.setattr(layer, "get_current_diffusion_config_or_none", lambda: None)
+    monkeypatch.setattr(layer, "build_parallel_attention_strategy", lambda **kwargs: NoParallelAttention())
+
+
+@pytest.mark.parametrize("explicit", [False, True])
+@pytest.mark.parametrize("override", [False, True])
+def test_specialization_preserves_selected_backend_and_options(mocker, local_attention, explicit, override):
+    spec = AttentionSpec(backend="FASTVIDEO_VSA", fastvideo_vsa_topk=7) if explicit else None
+    select = mocker.patch.object(layer, "get_attn_backend_for_role", return_value=(FastVideoVSABackend, spec))
+    attention = layer.Attention(
+        num_heads=2,
+        head_size=8,
+        softmax_scale=8**-0.5,
+        causal=False,
+        role="video.self",
+        role_category="self",
+        qkv_layout="BSND",
+        impl_overrides={"FASTVIDEO_VSA": _SpecializedImpl} if override else None,
+    )
+
+    assert attention.attn_backend is FastVideoVSABackend
+    assert type(attention.attention) is (_SpecializedImpl if override else FastVideoVSAImpl)
+    assert attention.attention.topk == (7 if explicit else 64)
+    assert attention.attention.qkv_layout == "BSND"
+    assert attention.backend_pref == "FASTVIDEO_VSA"
+    assert attention.backend_explicit is explicit
+    assert attention.attn_spec is spec
+    assert isinstance(attention.parallel_strategy, NoParallelAttention)
+    select.assert_called_once_with(
+        role="video.self", head_size=8, attention_config=None, role_category="self", allow_trtllm_default=False
+    )
+
+
+def test_unselected_specialization_does_not_replace_dense_backend(mocker, local_attention):
+    mocker.patch.object(layer, "get_attn_backend_for_role", return_value=(SDPABackend, None))
+    attention = layer.Attention(
+        num_heads=2,
+        head_size=8,
+        softmax_scale=8**-0.5,
+        causal=False,
+        impl_overrides={"FASTVIDEO_VSA": _SpecializedImpl},
+    )
+    assert attention.attn_backend is SDPABackend
+    assert type(attention.attention) is SDPABackend.get_impl_cls()
+
+
+def test_specialization_does_not_bypass_selection_errors(mocker, local_attention):
+    mocker.patch.object(layer, "get_attn_backend_for_role", side_effect=ImportError("optional kernel unavailable"))
+    with pytest.raises(ImportError, match="optional kernel unavailable"):
+        layer.Attention(
+            num_heads=2,
+            head_size=8,
+            softmax_scale=8**-0.5,
+            causal=False,
+            impl_overrides={"FASTVIDEO_VSA": _SpecializedImpl},
+        )
+
+
+def test_specialization_must_extend_selected_implementation(mocker, local_attention):
+    mocker.patch.object(layer, "get_attn_backend_for_role", return_value=(FastVideoVSABackend, None))
+    with pytest.raises(TypeError, match="must subclass the selected implementation"):
+        layer.Attention(
+            num_heads=2,
+            head_size=8,
+            softmax_scale=8**-0.5,
+            causal=False,
+            impl_overrides={"FASTVIDEO_VSA": SDPABackend.get_impl_cls()},
+        )
+
+
+def test_platform_backend_capabilities_survive_model_specialization(mocker, local_attention):
+    from vllm_omni.diffusion.models.minimax_h3.attention.fastvideo_h3 import MiniMaxH3VSAImpl
+
+    class PlatformBackend(FastVideoVSABackend):
+        @classmethod
+        def supports_packed_mask_free(cls):
+            return False
+
+        @staticmethod
+        def get_supported_head_sizes():
+            return [128]
+
+    # A registry/platform may refine capabilities without changing the
+    # implementation. The model must not replace those capability decisions.
+    mocker.patch.object(layer, "get_attn_backend_for_role", return_value=(PlatformBackend, None))
+    attention = layer.Attention(
+        num_heads=2,
+        head_size=128,
+        softmax_scale=128**-0.5,
+        causal=False,
+        impl_overrides={"FASTVIDEO_VSA": MiniMaxH3VSAImpl},
+    )
+    assert attention.attn_backend is PlatformBackend
+    assert not attention.attn_backend.supports_packed_mask_free()
+    assert attention.attn_backend.get_supported_head_sizes() == [128]
+    assert type(attention.attention) is MiniMaxH3VSAImpl
+
+
+def test_incompatible_platform_implementation_is_not_discarded(mocker, local_attention):
+    class PlatformImpl(FastVideoVSAImpl):
+        pass
+
+    class PlatformBackend(FastVideoVSABackend):
+        @staticmethod
+        def get_impl_cls():
+            return PlatformImpl
+
+    mocker.patch.object(layer, "get_attn_backend_for_role", return_value=(PlatformBackend, None))
+    with pytest.raises(TypeError, match="selected implementation .*PlatformImpl"):
+        layer.Attention(
+            num_heads=2,
+            head_size=8,
+            softmax_scale=8**-0.5,
+            causal=False,
+            impl_overrides={"FASTVIDEO_VSA": _SpecializedImpl},
+        )
diff --git a/tests/diffusion/cache/test_teacache_extractors.py b/tests/diffusion/cache/test_teacache_extractors.py
index d821541d006..55b92b8203e 100644
--- a/tests/diffusion/cache/test_teacache_extractors.py
+++ b/tests/diffusion/cache/test_teacache_extractors.py
@@ -68,12 +68,12 @@ def get_extractor(self):
         pass
 
     @abstractmethod
-    def get_module(self):
+    def get_module(self, module, /):
         """Return model module instance."""
         pass
 
     @abstractmethod
-    def get_sample_inputs(self):
+    def get_sample_inputs(self, sample_inputs, /):
         """Return sample inputs for model."""
         pass
 
@@ -737,10 +737,10 @@ def test_teacache_strict_sp_keeps_cache_state_rank_local(
         monkeypatch,
     ):
         """Strict SP must not mix local TeaCache state with gathered block rows."""
-        from vllm_omni.diffusion.attention.ops import minimax_h3_modulation
         from vllm_omni.diffusion.cache.teacache.config import TeaCacheConfig
         from vllm_omni.diffusion.cache.teacache.hook import TeaCacheHook
         from vllm_omni.diffusion.distributed import parallel_state
+        from vllm_omni.diffusion.layers import indexed_modulation
 
         seq_len = sample_inputs["x"].shape[1]
         local_len = seq_len // 2
@@ -844,13 +844,13 @@ def forward(self, hidden, *, t_emb, inverse_indices):
         )
         monkeypatch.setattr(parallel_state, "get_sp_group", lambda: sp_group)
 
-        original_indexed_scale_shift = minimax_h3_modulation.indexed_scale_shift_
+        original_indexed_scale_shift = indexed_modulation.indexed_scale_shift_
 
         def capture_indexed_scale_shift(hidden, shift, scale, indices):
             captured_modulation_indices.append(indices.clone())
             return original_indexed_scale_shift(hidden, shift, scale, indices)
 
-        monkeypatch.setattr(minimax_h3_modulation, "indexed_scale_shift_", capture_indexed_scale_shift)
+        monkeypatch.setattr(indexed_modulation, "indexed_scale_shift_", capture_indexed_scale_shift)
 
         local_img_pos = torch.tensor([0, 1])
         local_audio_pos = torch.tensor([2, 3])
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_modulation.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_modulation.py
index e10fbe56a9a..7fde01354be 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_modulation.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_modulation.py
@@ -6,7 +6,7 @@
 from vllm.triton_utils import HAS_TRITON
 
 from tests.helpers.mark import hardware_marks
-from vllm_omni.diffusion.attention.ops.minimax_h3_modulation import (
+from vllm_omni.diffusion.layers.indexed_modulation import (
     _MAX_1D_GRID_SIZE,
     _iter_row_chunks,
     _launch_row_chunks,
diff --git a/tests/diffusion/models/minimax_h3/test_vsa_layout.py b/tests/diffusion/models/minimax_h3/test_vsa_layout.py
new file mode 100644
index 00000000000..c556543d0d3
--- /dev/null
+++ b/tests/diffusion/models/minimax_h3/test_vsa_layout.py
@@ -0,0 +1,221 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import math
+import sys
+import types
+from typing import Any
+
+import pytest
+import torch
+
+from vllm_omni.diffusion.attention.backends.abstract import (
+    AttentionMetadata,
+    PackedPaddingMetadata,
+    VideoTokenLayout,
+    VideoTokenSpan,
+)
+from vllm_omni.diffusion.models.minimax_h3.attention.fastvideo_h3 import (
+    MiniMaxH3VSAImpl,
+    _get_h3_tile_metadata,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+def _h3_metadata(prefix_segments, video_shape, *, gate=None, packed_padding=None):
+    extra: dict[str, Any] = {
+        "vsa_h3_prefix_segments": prefix_segments,
+    }
+    if gate is not None:
+        extra["gate_compress"] = gate
+    return AttentionMetadata(
+        packed_padding=packed_padding,
+        video_layout=VideoTokenLayout(
+            used_len=sum(prefix_segments) + math.prod(video_shape),
+            video_spans=(VideoTokenSpan(start=sum(prefix_segments), latent_grid=video_shape, role="target"),),
+        ),
+        extra=extra,
+    )
+
+
+def _fake_block_sparse_kernel(monkeypatch, calls):
+    """Stand in for fastvideo_kernel.block_sparse_attn with a mask-obeying SDPA."""
+
+    def block_sparse_attn(q, k, v, block_map, variable_block_sizes):
+        calls["block_map"] = block_map.clone()
+        calls["variable_block_sizes"] = variable_block_sizes.tolist()
+        calls["q_shape"] = tuple(q.shape)
+        blocks = block_map.shape[-1]
+        assert blocks * 64 == q.shape[2]
+        # Expand the per-block map to a per-token mask so the stand-in honours
+        # the sparsity contract the real kernel implements, and drop the rows
+        # each partial block pads with, which the real kernel skips through
+        # variable_block_sizes.
+        token_mask = block_map.repeat_interleave(64, dim=-1).repeat_interleave(64, dim=-2)
+        within = torch.arange(64, device=q.device)[None, :] < variable_block_sizes[:, None]
+        token_mask = token_mask & within.reshape(1, 1, 1, -1)
+        out = torch.nn.functional.scaled_dot_product_attention(q.float(), k.float(), v.float(), attn_mask=token_mask)
+        return out.to(q.dtype), None
+
+    module = types.ModuleType("fastvideo_kernel.block_sparse_attn")
+    setattr(module, "block_sparse_attn", block_sparse_attn)
+    monkeypatch.setitem(sys.modules, "fastvideo_kernel", types.ModuleType("fastvideo_kernel"))
+    monkeypatch.setitem(sys.modules, "fastvideo_kernel.block_sparse_attn", module)
+
+
+def _h3_impl(**backend_kwargs):
+    kwargs = {"topk": 1, "min_seq_len": 1, "disable_when_sp_active": False}
+    kwargs.update(backend_kwargs)
+    return MiniMaxH3VSAImpl(num_heads=2, head_size=8, softmax_scale=8**-0.5, backend_kwargs=kwargs)
+
+
+def test_h3_forward_tiles_untiles_and_restores_the_original_row_order(monkeypatch):
+    calls: dict[str, Any] = {}
+    _fake_block_sparse_kernel(monkeypatch, calls)
+    impl = _h3_impl(topk=64)
+    prefix_segments, video_shape = (5, 70), (2, 4, 4)
+    seq_len = sum(prefix_segments) + 2 * 4 * 4
+    torch.manual_seed(0)
+    query = torch.randn(1, seq_len, 2, 8, dtype=torch.bfloat16)
+
+    output = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape))
+
+    assert output.shape == query.shape
+    # topk covers every video block, so the block map is dense and the tiled
+    # kernel must reproduce plain attention over the same rows.
+    reference = torch.nn.functional.scaled_dot_product_attention(
+        *(x.float().transpose(1, 2) for x in (query, query, query))
+    ).transpose(1, 2)
+    torch.testing.assert_close(output.float(), reference, atol=2e-2, rtol=2e-2)
+    # 5 + 70 splits into segment-pure 5 | 64 | 6, then one (2, 4, 4) video tile.
+    assert calls["variable_block_sizes"] == [5, 64, 6, 32]
+
+
+def test_h3_forward_keeps_prefix_dense_and_selects_top_k_video_tiles(monkeypatch):
+    calls: dict[str, Any] = {}
+    _fake_block_sparse_kernel(monkeypatch, calls)
+    impl = _h3_impl(topk=1)
+    prefix_segments, video_shape = (5,), (8, 4, 4)
+    seq_len = 5 + 8 * 4 * 4
+    torch.manual_seed(0)
+    query = torch.randn(1, seq_len, 2, 8, dtype=torch.bfloat16)
+
+    impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape))
+
+    # 1 prefix block + 2 video blocks. The odd count is padded to an even one
+    # for the paired-CTA kernel contract, and the Triton route slices that
+    # transport-only partner off again before launching.
+    block_map = calls["block_map"]
+    assert block_map.shape[-1] == 3
+    assert calls["variable_block_sizes"] == [5, 64, 64]
+    assert block_map[:, :, :1, :].all(), "prefix queries stay dense"
+    assert block_map[..., :1].all(), "prefix keys are exempt from selection"
+    assert (block_map[:, :, 1:, 1:].sum(dim=-1) == 1).all(), "one video tile per video query"
+
+    # The same odd geometry must still untile back onto the original rows.
+    dense = _h3_impl(topk=64).forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape))
+    reference = torch.nn.functional.scaled_dot_product_attention(
+        *(x.float().transpose(1, 2) for x in (query, query, query))
+    ).transpose(1, 2)
+    torch.testing.assert_close(dense.float(), reference, atol=2e-2, rtol=2e-2)
+
+
+def test_h3_forward_applies_the_learned_compression_gate(monkeypatch):
+    _fake_block_sparse_kernel(monkeypatch, {})
+    impl = _h3_impl(topk=64)
+    prefix_segments, video_shape = (5,), (2, 4, 4)
+    seq_len = 5 + 2 * 4 * 4
+    torch.manual_seed(0)
+    query = torch.randn(1, seq_len, 2, 8, dtype=torch.bfloat16)
+
+    without_gate = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape))
+    zero_gate = torch.zeros_like(query)
+    with_zero_gate = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape, gate=zero_gate))
+    live_gate = torch.full_like(query, 0.5)
+    with_live_gate = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape, gate=live_gate))
+
+    torch.testing.assert_close(with_zero_gate.float(), without_gate.float())
+    assert not torch.allclose(with_live_gate.float(), without_gate.float())
+
+
+def test_h3_forward_restores_rows_the_packed_padding_excludes(monkeypatch):
+    _fake_block_sparse_kernel(monkeypatch, {})
+    impl = _h3_impl(topk=64)
+    prefix_segments, video_shape = (5,), (2, 4, 4)
+    valid = 5 + 2 * 4 * 4
+    torch.manual_seed(0)
+    query = torch.randn(1, valid + 24, 2, 8, dtype=torch.bfloat16)
+    padding = PackedPaddingMetadata(
+        q_length=valid,
+        kv_length=valid,
+        cu_seqlens_q=torch.tensor([0, valid], dtype=torch.int32),
+        cu_seqlens_k=torch.tensor([0, valid], dtype=torch.int32),
+    )
+
+    output = impl.forward_cuda(query, query, query, _h3_metadata(prefix_segments, video_shape, packed_padding=padding))
+
+    assert output.shape == query.shape
+    assert torch.count_nonzero(output[:, valid:]) == 0
+
+
+def test_h3_geometry_keeps_prefix_segments_pure_and_tiles_video_3d():
+    partition, sizes, non_pad, untile, prefix_blocks, video_blocks = _get_h3_tile_metadata(
+        (5, 70, 9), (5, 6, 6), torch.device("cpu")
+    )
+    assert sizes[:4].tolist() == [5, 64, 6, 9]
+    assert prefix_blocks == 4
+    assert video_blocks == 8
+    assert int(sizes.sum()) == 5 + 70 + 9 + 5 * 6 * 6
+    assert partition.numel() == non_pad.numel() == untile.numel() == int(sizes.sum())
+
+
+@pytest.mark.parametrize("fallback_on_error", [False, True])
+def test_h3_kernel_failure_preserves_fallback_policy(monkeypatch, fallback_on_error):
+    impl = _h3_impl(fallback_on_error=fallback_on_error)
+    query = torch.randn(1, 37, 2, 8)
+    metadata = _h3_metadata((5,), (2, 4, 4))
+
+    def fail(*args, **kwargs):
+        raise RuntimeError("kernel failure")
+
+    monkeypatch.setattr(impl, "_forward_h3", fail)
+    monkeypatch.setattr(impl.sdpa_fallback, "forward", impl.sdpa_fallback.forward_cuda)
+    if fallback_on_error:
+        output = impl.forward_cuda(query, query, query, metadata)
+        expected = impl.sdpa_fallback.forward_cuda(query, query, query, metadata)
+        torch.testing.assert_close(output, expected, rtol=0, atol=0)
+    else:
+        with pytest.raises(RuntimeError, match="kernel failure"):
+            impl.forward_cuda(query, query, query, metadata)
+
+
+def test_h3_accelerator_failure_is_not_swallowed(monkeypatch):
+    impl = _h3_impl(fallback_on_error=True)
+    query = torch.randn(1, 37, 2, 8)
+
+    def fail(*args, **kwargs):
+        raise torch.AcceleratorError("device failure")
+
+    monkeypatch.setattr(impl, "_forward_h3", fail)
+    with pytest.raises(torch.AcceleratorError, match="device failure"):
+        impl.forward_cuda(query, query, query, _h3_metadata((5,), (2, 4, 4)))
+
+
+def test_h3_without_layout_delegates_to_shared_backend(monkeypatch):
+    from vllm_omni.diffusion.attention.backends.fastvideo_vsa import FastVideoVSAImpl
+
+    impl = _h3_impl()
+    query = torch.randn(1, 37, 2, 8)
+    metadata = AttentionMetadata()
+    expected = torch.empty_like(query)
+    calls = []
+
+    def forward(self, q, k, v, attn_metadata):
+        calls.append((self, q, k, v, attn_metadata))
+        return expected
+
+    monkeypatch.setattr(FastVideoVSAImpl, "forward_cuda", forward)
+    assert impl.forward_cuda(query, query, query, metadata) is expected
+    assert len(calls) == 1
+    assert all(actual is wanted for actual, wanted in zip(calls[0], (impl, query, query, query, metadata)))
diff --git a/tests/helpers/runtime.py b/tests/helpers/runtime.py
index 66e0cefab75..0632db55d9e 100644
--- a/tests/helpers/runtime.py
+++ b/tests/helpers/runtime.py
@@ -23,6 +23,7 @@
 import numpy as np
 import psutil
 import yaml
+from filelock import FileLock, Timeout
 from vllm import TextPrompt
 from vllm.logger import init_logger
 
@@ -170,9 +171,54 @@ def __init__(
         self.use_omni = use_omni
         self.proc: subprocess.Popen | None = None
         self.host = "127.0.0.1"
+        self._auto_port = port is None
+        self._port_lock: FileLock | None = None
         self.port = get_open_port() if port is None else port
 
+    def _reserve_port(self) -> None:
+        # bind(0)/close does not reserve a port across concurrent pytest workers.
+        # Keep an advisory lock until teardown, including the long import phase
+        # before the subprocess binds its HTTP socket. Never unlink lock files:
+        # another worker may already have the same inode open.
+        for attempt in range(128):
+            if attempt:
+                self.port = get_open_port(self.host)
+            lock_path = Path(tempfile.gettempdir()) / f"vllm-omni-test-port-{os.getuid()}-{self.port}.lock"
+            lock = FileLock(lock_path)
+            try:
+                lock.acquire(timeout=0)
+            except Timeout as error:
+                if not self._auto_port:
+                    raise RuntimeError(f"HTTP test port {self.port} is already reserved") from error
+                continue
+            try:
+                with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as probe:
+                    probe.bind((self.host, self.port))
+            except OSError as error:
+                lock.release()
+                if not self._auto_port or error.errno != errno.EADDRINUSE:
+                    raise
+                continue
+            self._port_lock = lock
+            return
+        raise RuntimeError("Could not reserve an HTTP test port after 128 attempts")
+
+    def _owns_listening_port(self) -> bool:
+        assert self.proc is not None
+        try:
+            parent = psutil.Process(self.proc.pid)
+            processes = [parent, *parent.children(recursive=True)]
+            return any(
+                conn.status == psutil.CONN_LISTEN and conn.laddr.port == self.port
+                for process in processes
+                for conn in process.net_connections(kind="tcp")
+            )
+        except psutil.NoSuchProcess:
+            # A child can exit between enumeration and inspecting its sockets.
+            return False
+
     def _start_server(self) -> None:
+        self._reserve_port()
         env = os.environ.copy()
         if self.env_dict is not None:
             env.update(self.env_dict)
@@ -208,7 +254,10 @@ def _start_server(self) -> None:
                 raise RuntimeError(f"Server processes exited with code {ret} before becoming ready.")
             with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
                 sock.settimeout(1)
-                if sock.connect_ex((self.host, self.port)) == 0:
+                if sock.connect_ex((self.host, self.port)) == 0 and self._owns_listening_port():
+                    ret = self.proc.poll()
+                    if ret is not None:
+                        raise RuntimeError(f"Server processes exited with code {ret} before becoming ready.")
                     startup_s = time.perf_counter() - startup_t0
                     if self.log_stats:
                         print(
@@ -368,9 +417,14 @@ def __enter__(self):
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        if self.proc:
-            self._kill_process_tree(self.proc.pid)
-        cleanup_test_environment()
+        try:
+            if self.proc:
+                self._kill_process_tree(self.proc.pid)
+        finally:
+            if self._port_lock is not None:
+                self._port_lock.release()
+                self._port_lock = None
+            cleanup_test_environment()
 
 
 class OmniServerStageCli(OmniServer):
diff --git a/tests/helpers/tests/test_runtime_server_ports.py b/tests/helpers/tests/test_runtime_server_ports.py
new file mode 100644
index 00000000000..1d8c0b2f13a
--- /dev/null
+++ b/tests/helpers/tests/test_runtime_server_ports.py
@@ -0,0 +1,109 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""A listening port alone must not make a different test's server ready."""
+
+import socket
+import subprocess
+import sys
+
+import pytest
+from filelock import FileLock
+
+from tests.helpers import runtime
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_server_does_not_accept_another_process_listener(monkeypatch):
+    monkeypatch.setattr(runtime, "cleanup_test_environment", lambda: None)
+    server = runtime.OmniServer("fake-model", [])
+    popen = subprocess.Popen
+
+    # Occupy the chosen port after allocation, while the requested subprocess
+    # is still importing. The old TCP-only probe returns ready for this socket.
+    with socket.socket() as foreign_listener:
+
+        def launch(*args, **kwargs):
+            foreign_listener.bind((server.host, server.port))
+            foreign_listener.listen()
+            return popen([sys.executable, "-c", "import time; time.sleep(0.2); raise SystemExit(7)"])
+
+        monkeypatch.setattr(runtime.subprocess, "Popen", launch)
+        with pytest.raises(RuntimeError, match="exited with code 7"):
+            with server:
+                pass
+    # Failed __enter__ must also release the lease for a later server.
+    retry = runtime.OmniServer("retry-model", [], port=server.port)
+    try:
+        retry._reserve_port()
+    finally:
+        retry.__exit__(None, None, None)
+
+
+def test_auto_ports_are_reserved_before_subprocesses_bind(monkeypatch, tmp_path):
+    monkeypatch.setattr(runtime, "cleanup_test_environment", lambda: None)
+    monkeypatch.setattr(runtime.tempfile, "gettempdir", lambda: str(tmp_path))
+    # Both constructors see the same free port before either server has bound.
+    first = runtime.OmniServer("first-model", [])
+    candidate = first.port
+    monkeypatch.setattr(runtime, "get_open_port", lambda *args: candidate)
+    second = runtime.OmniServer("second-model", [])
+    first._reserve_port()
+    with socket.socket() as occupied, socket.socket() as probe:
+        occupied.bind((first.host, candidate))
+        probe.bind((first.host, 0))
+        alternative = probe.getsockname()[1]
+    monkeypatch.setattr(runtime, "get_open_port", lambda *args: alternative)
+    try:
+        second._reserve_port()
+        assert first.port == candidate
+        assert second.port == alternative
+        # Check OS-level lock exclusion, not only the Python object's state.
+        lock_path = next(tmp_path.glob(f"*-{candidate}.lock"))
+        contender = FileLock(lock_path)
+        result = subprocess.run(
+            [
+                sys.executable,
+                "-c",
+                "import sys\nfrom filelock import FileLock, Timeout\n"
+                "try:\n FileLock(sys.argv[1]).acquire(timeout=0)\n"
+                "except Timeout:\n sys.exit(23)\n",
+                str(lock_path),
+            ],
+            timeout=10,
+            check=False,
+        )
+        assert result.returncode == 23
+        explicit = runtime.OmniServer("explicit-model", [], port=candidate)
+        with pytest.raises(RuntimeError, match="already reserved"):
+            with explicit:
+                pass
+    finally:
+        first.__exit__(None, None, None)
+        second.__exit__(None, None, None)
+    with contender.acquire(timeout=0):
+        pass
+
+
+@pytest.mark.parametrize("in_child", [False, True])
+def test_server_accepts_its_own_listener(monkeypatch, in_child):
+    monkeypatch.setattr(runtime, "cleanup_test_environment", lambda: None)
+    server = runtime.OmniServer("fake-model", [])
+    popen = subprocess.Popen
+
+    def launch(*args, **kwargs):
+        code = (
+            "import socket,time; s=socket.socket(); "
+            f"s.bind(({server.host!r}, {server.port})); s.listen(); time.sleep(30)"
+        )
+        if in_child:
+            code = f"import subprocess,sys; child=subprocess.Popen([sys.executable,'-c',{code!r}]); child.wait()"
+        return popen([sys.executable, "-c", code])
+
+    monkeypatch.setattr(runtime.subprocess, "Popen", launch)
+    with server:
+        assert server.proc is not None
+        assert server.proc.poll() is None
+        with socket.create_connection((server.host, server.port), timeout=1):
+            pass
diff --git a/vllm_omni/diffusion/attention/backends/fastvideo_vsa.py b/vllm_omni/diffusion/attention/backends/fastvideo_vsa.py
index 465912d3942..cbab82c9af4 100644
--- a/vllm_omni/diffusion/attention/backends/fastvideo_vsa.py
+++ b/vllm_omni/diffusion/attention/backends/fastvideo_vsa.py
@@ -6,7 +6,6 @@
 import functools
 import importlib.util
 import math
-import os
 from collections.abc import Mapping
 from typing import Any
 
@@ -88,77 +87,6 @@ def _(
 _fastvideo_vsa_bshd_op = torch.ops.vllm_omni.fastvideo_vsa_bshd
 
 
-# H3 needs an explicit per-query block map: prefix queries are dense, while
-# video queries select prefix + top-k video tiles. The generic
-# video_sparse_attn() entry point cannot express that contract.
-if not hasattr(torch.ops.vllm_omni, "fastvideo_h3_vsa_bhsd"):
-
-    @torch.library.custom_op("vllm_omni::fastvideo_h3_vsa_bhsd", mutates_args=())
-    def _fastvideo_h3_vsa_bhsd_op(
-        query: torch.Tensor,
-        key: torch.Tensor,
-        value: torch.Tensor,
-        block_map: torch.Tensor,
-        variable_block_sizes: torch.Tensor,
-        logical_blocks: int,
-    ) -> torch.Tensor:
-        q = query.transpose(1, 2).contiguous()
-        k = key.transpose(1, 2).contiguous()
-        v = value.transpose(1, 2).contiguous()
-
-        # Official FastVideo's measured FastH3 route opts into this native
-        # Blackwell forward. Wheels without the extension (including SM103
-        # builds today) retain the corrected explicit-mask Triton route.
-        if os.environ.get("FASTVIDEO_VSA_SM100A", "0") == "1":
-            try:
-                from fastvideo_kernel import block_sparse_attn_sm100a
-                from fastvideo_kernel.triton_kernels.index import map_to_index
-
-                if block_sparse_attn_sm100a.is_supported(q, variable_block_sizes):
-                    q2k_idx, q2k_num = map_to_index(block_map)
-                    out, _ = block_sparse_attn_sm100a.block_sparse_attn_sm100a(
-                        q,
-                        k,
-                        v,
-                        q2k_idx.to(torch.int32).contiguous(),
-                        q2k_num.to(torch.int32).contiguous(),
-                        variable_block_sizes.to(torch.int32).contiguous(),
-                        need_lse=False,
-                    )
-                    return out.transpose(1, 2).contiguous()
-            except (ImportError, RuntimeError) as exc:
-                # Opting in explicitly and then silently getting a different
-                # numeric path is worse than the slower route it lands on.
-                logger.warning_once(
-                    "FASTVIDEO_VSA_SM100A=1 requested but the native Blackwell forward is "
-                    "unavailable (%s); using the Triton block-sparse route instead.",
-                    exc,
-                )
-
-        from fastvideo_kernel.block_sparse_attn import block_sparse_attn
-
-        logical_len = logical_blocks * 64
-        out, _ = block_sparse_attn(
-            q[:, :, :logical_len].contiguous(),
-            k[:, :, :logical_len].contiguous(),
-            v[:, :, :logical_len].contiguous(),
-            block_map[..., :logical_blocks, :logical_blocks].contiguous(),
-            variable_block_sizes[:logical_blocks].to(torch.int32).contiguous(),
-        )
-        out = out.transpose(1, 2).contiguous()
-        if out.shape[1] != query.shape[1]:
-            out = torch.nn.functional.pad(out, (0, 0, 0, 0, 0, query.shape[1] - out.shape[1]))
-        return out
-
-    @_fastvideo_h3_vsa_bhsd_op.register_fake
-    def _(query, key, value, block_map, variable_block_sizes, logical_blocks):
-        del key, value, block_map, variable_block_sizes, logical_blocks
-        return torch.empty_like(query)
-
-
-_fastvideo_h3_vsa_bhsd_op = torch.ops.vllm_omni.fastvideo_h3_vsa_bhsd
-
-
 @functools.lru_cache(maxsize=32)
 def _get_tile_partition_indices(
     dit_seq_shape: tuple[int, int, int],
@@ -226,81 +154,6 @@ def _get_tile_metadata(
     return tile_partition_indices, variable_block_sizes, non_pad_index, untile_combined_index
 
 
-@functools.lru_cache(maxsize=32)
-def _get_h3_tile_metadata(
-    prefix_segments: tuple[int, ...],
-    video_shape: tuple[int, int, int],
-    device: torch.device,
-) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, int, int]:
-    """Official FastVideo H3 geometry: pure prefix chunks + 3-D video tiles."""
-    block_size = (4, 4, 4)
-    block_elements = 64
-    prefix_len = sum(prefix_segments)
-    prefix_sizes: list[int] = []
-    for segment in prefix_segments:
-        full, remainder = divmod(segment, block_elements)
-        prefix_sizes.extend([block_elements] * full)
-        if remainder:
-            prefix_sizes.append(remainder)
-
-    video_indices = _get_tile_partition_indices(video_shape, block_size, device) + prefix_len
-    video_sizes = _construct_variable_block_sizes(video_shape, block_size, device)
-    partition = torch.cat([torch.arange(prefix_len, device=device, dtype=torch.long), video_indices])
-    sizes = torch.cat([torch.tensor(prefix_sizes, device=device, dtype=torch.int32), video_sizes.to(torch.int32)])
-    non_pad = _get_non_pad_index(sizes, block_elements)
-    untile = non_pad[torch.argsort(partition)]
-    total = prefix_len + math.prod(video_shape)
-    if int(sizes.sum()) != total or untile.numel() != total:
-        raise ValueError(
-            f"invalid H3 VSA geometry: prefix={prefix_segments}, video={video_shape}, "
-            f"sizes_sum={int(sizes.sum())}, total={total}"
-        )
-    return partition, sizes, non_pad, untile, len(prefix_sizes), int(video_sizes.numel())
-
-
-def _get_h3_layout(
-    attn_metadata: AttentionMetadata | None,
-) -> tuple[tuple[int, ...], tuple[int, int, int], int] | None:
-    if attn_metadata is None or attn_metadata.video_layout is None:
-        return None
-    prefix = attn_metadata.extra.get("vsa_h3_prefix_segments")
-    if not isinstance(prefix, (tuple, list)):
-        return None
-    target = next(
-        (span for span in reversed(attn_metadata.video_layout.video_spans) if span.role == "target"),
-        None,
-    )
-    if target is None:
-        return None
-    return tuple(int(x) for x in prefix if int(x) > 0), target.latent_grid, target.start
-
-
-def _pool_h3_tiles(x: torch.Tensor, sizes: torch.Tensor) -> torch.Tensor:
-    batch, seq_len, heads, dim = x.shape
-    blocks = seq_len // 64
-    pooled = x.view(batch, blocks, 64, heads, dim).sum(dim=2, dtype=torch.float32)
-    pooled = pooled / sizes.view(1, -1, 1, 1).clamp_min(1)
-    return pooled.permute(0, 2, 1, 3)
-
-
-def _build_h3_block_map(
-    scores: torch.Tensor,
-    num_prefix_blocks: int,
-    num_video_blocks: int,
-    topk: int,
-) -> torch.Tensor:
-    """Prefix K/V are exempt and prefix queries stay dense, as in FastVideo."""
-    keep_video = min(topk, num_video_blocks)
-    if keep_video == num_video_blocks:
-        return torch.ones_like(scores, dtype=torch.bool)
-    block_map = torch.zeros_like(scores, dtype=torch.bool)
-    indices = scores[..., num_prefix_blocks:].topk(keep_video, dim=-1).indices + num_prefix_blocks
-    block_map.scatter_(-1, indices, True)
-    block_map[..., :num_prefix_blocks] = True
-    block_map[:, :, :num_prefix_blocks, :] = True
-    return block_map
-
-
 def _get_vsa_dit_seq_shape(attn_metadata: AttentionMetadata | None) -> tuple[int, int, int] | None:
     if attn_metadata is None:
         return None
@@ -343,7 +196,9 @@ def validate_available(cls) -> None:
         if importlib.util.find_spec("fastvideo_kernel") is None:
             raise ImportError(
                 "FASTVIDEO_VSA requires the optional fastvideo-kernel package "
-                "(the installation must provide the 'fastvideo_kernel' Python module)."
+                "included in vllm-omni[vsa]. Install with `uv pip install 'vllm-omni[vsa]'` "
+                "(from source: `uv pip install -e '.[vsa]'`). "
+                "Prebuilt kernels require Linux, Python 3.12 and glibc >= 2.34."
             )
 
     @staticmethod
@@ -504,93 +359,6 @@ def _fallback_reason(
                 return "sequence parallel context is active"
         return None
 
-    def _forward_h3(
-        self,
-        query: torch.Tensor,
-        key: torch.Tensor,
-        value: torch.Tensor,
-        attn_metadata: AttentionMetadata,
-    ) -> torch.Tensor:
-        layout = _get_h3_layout(attn_metadata)
-        if layout is None:
-            raise ValueError("incomplete VSA-H3 layout metadata")
-        prefix_segments, video_shape, target_start = layout
-        if sum(prefix_segments) != target_start:
-            raise ValueError(f"VSA-H3 prefix segments sum to {sum(prefix_segments)}, target starts at {target_start}")
-        expected = target_start + math.prod(video_shape)
-        if query.shape[1] != expected:
-            raise ValueError(f"VSA-H3 layout has {expected} rows but attention received {query.shape[1]}")
-        if query.dtype not in (torch.float16, torch.bfloat16):
-            raise ValueError(f"VSA-H3 requires fp16/bf16 tensors, got {query.dtype}")
-        gate = _get_gate_compress(attn_metadata)
-        if gate is not None:
-            # H3 pads the packed document to 64 rows, while VSA operates on
-            # the valid prefix. Validate/slice before launching attention so a
-            # metadata error can never trigger an unsafe dense fallback after
-            # an asynchronous custom kernel.
-            if gate.shape[0] != query.shape[0] or gate.shape[2:] != query.shape[2:] or gate.shape[1] < query.shape[1]:
-                raise ValueError(f"gate_compress shape {gate.shape} cannot cover query shape {query.shape}")
-            gate = gate[:, : query.shape[1]]
-
-        partition, sizes, non_pad, untile, prefix_blocks, video_blocks = _get_h3_tile_metadata(
-            prefix_segments, video_shape, query.device
-        )
-        logical_blocks = int(sizes.numel())
-        # The native sm100a kernel assigns pairs of query blocks to CTAs. Its
-        # contract requires an even block count; the synthetic partner is
-        # transport-only and is removed before returning.
-        pair_pad = logical_blocks % 2
-        kernel_blocks = logical_blocks + pair_pad
-        target_shape = (query.shape[0], kernel_blocks * 64, query.shape[2], query.shape[3])
-        q_tiled = torch.zeros(target_shape, device=query.device, dtype=query.dtype)
-        k_tiled = torch.zeros_like(q_tiled)
-        v_tiled = torch.zeros_like(q_tiled)
-        q_tiled[:, non_pad] = query[:, partition]
-        k_tiled[:, non_pad] = key[:, partition]
-        v_tiled[:, non_pad] = value[:, partition]
-
-        q_pool = _pool_h3_tiles(q_tiled[:, : logical_blocks * 64], sizes)
-        k_pool = _pool_h3_tiles(k_tiled[:, : logical_blocks * 64], sizes)
-        scores = torch.matmul(q_pool, k_pool.transpose(-2, -1)) * self.softmax_scale
-        block_map = _build_h3_block_map(scores, prefix_blocks, video_blocks, self.topk)
-        kernel_sizes = sizes
-        if pair_pad:
-            block_map = torch.nn.functional.pad(block_map, (0, 1, 0, 1), value=False)
-            kernel_sizes = torch.nn.functional.pad(sizes, (0, 1), value=0)
-
-        logger.info_once(
-            "FASTVIDEO_VSA H3 routing: seq_len=%d, prefix_segments=%s, video_shape=%s, "
-            "prefix_blocks=%d, video_blocks=%d, topk=%d, kernel_blocks=%d",
-            query.shape[1],
-            prefix_segments,
-            video_shape,
-            prefix_blocks,
-            video_blocks,
-            min(self.topk, video_blocks),
-            kernel_blocks,
-        )
-        output = _fastvideo_h3_vsa_bhsd_op(
-            q_tiled.contiguous(),
-            k_tiled.contiguous(),
-            v_tiled.contiguous(),
-            block_map.contiguous(),
-            kernel_sizes.contiguous(),
-            logical_blocks,
-        )[:, : logical_blocks * 64]
-
-        if gate is not None:
-            gate_tiled = torch.zeros_like(q_tiled[:, : logical_blocks * 64])
-            gate_tiled[:, non_pad] = gate[:, partition]
-            v_pool = _pool_h3_tiles(v_tiled[:, : logical_blocks * 64], sizes)
-            compressed = torch.matmul(torch.softmax(scores, dim=-1), v_pool)
-            compressed = compressed.permute(0, 2, 1, 3).to(output.dtype)
-            output = (
-                output.view(output.shape[0], logical_blocks, 64, output.shape[2], output.shape[3])
-                + compressed.unsqueeze(2)
-                * gate_tiled.view(gate_tiled.shape[0], logical_blocks, 64, gate_tiled.shape[2], gate_tiled.shape[3])
-            ).view_as(output)
-        return output[:, untile].contiguous()
-
     def forward_cuda(
         self,
         query: torch.Tensor,
@@ -611,26 +379,6 @@ def forward_cuda(
             key = key[:, :valid_seq_len]
             value = value[:, :valid_seq_len]
 
-        if attn_metadata is not None and _get_h3_layout(attn_metadata) is not None:
-            try:
-                output = self._forward_h3(query, key, value, attn_metadata)
-                if valid_seq_len == original_seq_len:
-                    return output
-                restored = torch.zeros_like(original_query)
-                restored[:, :valid_seq_len] = output
-                return restored
-            except Exception as exc:
-                # A CUDA fault poisons the process context; attempting SDPA
-                # afterwards obscures the original kernel failure and cannot
-                # recover the request.
-                if isinstance(exc, torch.AcceleratorError):
-                    raise
-                if not self.fallback_on_error:
-                    raise
-                return self._fallback(
-                    original_query, original_key, original_value, attn_metadata, f"VSA-H3 kernel failed: {exc}"
-                )
-
         reason = self._fallback_reason(query, key, value, attn_metadata)
         if reason is not None:
             return self._fallback(original_query, original_key, original_value, attn_metadata, reason)
diff --git a/vllm_omni/diffusion/attention/layer.py b/vllm_omni/diffusion/attention/layer.py
index 4c588af0cfb..2e0b2604d4e 100644
--- a/vllm_omni/diffusion/attention/layer.py
+++ b/vllm_omni/diffusion/attention/layer.py
@@ -7,7 +7,9 @@
 # https://github.com/feifeibear/long-context-attention/blob/main/yunchang/attention/layer.py
 
 
+from collections.abc import Mapping
 from dataclasses import replace
+from typing import cast
 
 import torch
 import torch.nn as nn
@@ -16,7 +18,7 @@
 from vllm.model_executor.models.utils import extract_layer_index
 from vllm.v1.kv_cache_interface import FullAttentionSpec, KVCacheSpec
 
-from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
+from vllm_omni.diffusion.attention.backends.abstract import AttentionBackend, AttentionImpl, AttentionMetadata
 from vllm_omni.diffusion.attention.backends.sdpa import SDPABackend
 from vllm_omni.diffusion.attention.parallel import build_parallel_attention_strategy
 from vllm_omni.diffusion.attention.parallel.base import NoParallelAttention
@@ -83,6 +85,10 @@ def __init__(
         custom_attention: nn.Module | None = None,
         # Preserve dense FP32 inference for models opting into CUDA auto fallback.
         allow_fp32_fallback: bool = False,
+        # Model-owned implementation subclasses, keyed by backend name.
+        # Keep the platform-selected backend and its capabilities unchanged.
+        # Each override must preserve the selected implementation's contract.
+        impl_overrides: Mapping[str, type[AttentionImpl]] | None = None,
     ):
         super().__init__()
 
@@ -181,8 +187,18 @@ def __init__(
                 self.backend_pref = attn_backend_cls.get_name()
                 logger.debug("Attention(role=%s) → platform default (%s)", role, self.backend_pref)
 
-            self.attn_backend = attn_backend_cls
+            self.attn_backend: type[AttentionBackend] | None = attn_backend_cls
             self.attn_impl_cls = self.attn_backend.get_impl_cls()
+            if impl_overrides is not None:
+                override = impl_overrides.get(attn_backend_cls.get_name())
+                if override is not None:
+                    if not issubclass(override, self.attn_impl_cls):
+                        raise TypeError(
+                            f"Attention implementation override {override.__qualname__} must subclass "
+                            f"the selected implementation {self.attn_impl_cls.__qualname__} "
+                            f"for backend {attn_backend_cls.__qualname__}"
+                        )
+                    self.attn_impl_cls = override
             self.attention = self.attn_impl_cls(
                 num_heads=num_heads,
                 head_size=head_size,
@@ -197,7 +213,7 @@ def __init__(
             )
             # Compatibility kernels run inside shared dispatch, between the
             # parallel strategy's input preparation and output restoration.
-            self.sdpa_fallback = SDPABackend.get_impl_cls()(
+            self.sdpa_fallback: AttentionImpl | None = SDPABackend.get_impl_cls()(
                 num_heads=num_heads,
                 head_size=head_size,
                 softmax_scale=softmax_scale,
@@ -299,6 +315,7 @@ def _get_active_parallel_strategy(self):
     def _init_kv_cache_quantization(self, config) -> None:
         if config is None or self._has_custom_attention:
             return
+        assert self.attn_backend is not None
         dtype = getattr(config, "diffusion_kv_cache_dtype", None)
         if dtype == "auto":
             dtype = None
@@ -400,6 +417,7 @@ def _forward_impl(
             )
         use_paged_attention = paged_adapter is not None and self.paged_kv_cache_role is not None
         if use_paged_attention and not getattr(self.attn_backend, "supports_paged_kv", False):
+            assert self.attn_backend is not None
             raise NotImplementedError(
                 f"Diffusion paged KV requires an Omni backend with paged support; "
                 f"selected {self.attn_backend.get_name()}"
@@ -496,7 +514,7 @@ def is_paged_kv_active(self) -> bool:
 
     def _run_local_attention(self, query, key, value, attn_metadata):
         if self._has_custom_attention:
-            return self.attention(query, key, value, attn_metadata)
+            return cast(nn.Module, self.attention)(query, key, value, attn_metadata)
 
         self._assert_metadata_compatible(attn_metadata)
 
@@ -506,7 +524,7 @@ def _run_local_attention(self, query, key, value, attn_metadata):
             and query.dtype == torch.float32
             and query.ndim == 4
             and not self.backend_explicit
-            and self.attn_backend.get_name() == "FLASH_ATTN"
+            and cast(type[AttentionBackend], self.attn_backend).get_name() == "FLASH_ATTN"
             and (
                 attn_metadata is None
                 or (
@@ -519,7 +537,7 @@ def _run_local_attention(self, query, key, value, attn_metadata):
             )
         ):
             logger.warning_once("Using SDPA for this layer's FP32 input with automatic CUDA FlashAttention selection.")
-            return self.sdpa_fallback.forward(query, key, value, attn_metadata)
+            return cast(AttentionImpl, self.sdpa_fallback).forward(query, key, value, attn_metadata)
 
         in_kv_memory_profile = is_forward_context_available() and get_forward_context().in_diffusion_kv_memory_profile
         # The startup KV-capacity profile needs tensor shapes, not a paged
@@ -531,14 +549,14 @@ def _run_local_attention(self, query, key, value, attn_metadata):
             self._scheduler_paged_kv
             and self.paged_kv_cache_role is not None
             and in_kv_memory_profile
-            and self.attn_backend.get_name() == "FLASH_ATTN"
+            and cast(type[AttentionBackend], self.attn_backend).get_name() == "FLASH_ATTN"
             and not current_omni_platform.supports_diffusion_dense_flash_attention()
         ):
             logger.warning_once(
                 "The startup KV memory profile is using SDPA because dense FLASH_ATTN is unavailable. "
                 "Formal paged requests still use the platform-native paged attention backend."
             )
-            return self.sdpa_fallback.forward(query, key, value, attn_metadata)
+            return cast(AttentionImpl, self.sdpa_fallback).forward(query, key, value, attn_metadata)
 
         return self.attention.forward(query, key, value, attn_metadata)
 
diff --git a/vllm_omni/diffusion/attention/ops/block_sparse.py b/vllm_omni/diffusion/attention/ops/block_sparse.py
new file mode 100644
index 00000000000..aeec14699e6
--- /dev/null
+++ b/vllm_omni/diffusion/attention/ops/block_sparse.py
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Shared pooling, routing and provider calls for explicit block-sparse attention."""
+
+import os
+
+import torch
+from vllm.logger import init_logger
+
+logger = init_logger(__name__)
+
+
+if not hasattr(torch.ops.vllm_omni, "fastvideo_block_sparse_attn_bshd"):
+
+    @torch.library.custom_op("vllm_omni::fastvideo_block_sparse_attn_bshd", mutates_args=())
+    def fastvideo_block_sparse_attn_bshd(
+        query: torch.Tensor,
+        key: torch.Tensor,
+        value: torch.Tensor,
+        block_map: torch.Tensor,
+        variable_block_sizes: torch.Tensor,
+        logical_blocks: int,
+    ) -> torch.Tensor:
+        """Run explicit block-sparse attention on BSHD tensors in 64-row blocks.
+
+        Inputs and the block map may include transport-only blocks after
+        ``logical_blocks``. The Triton provider sees only logical blocks and
+        the wrapper restores the original row count. Native provider selection
+        and its supported-input checks remain owned by FastVideo.
+        """
+        q = query.transpose(1, 2).contiguous()
+        k = key.transpose(1, 2).contiguous()
+        v = value.transpose(1, 2).contiguous()
+
+        # Prefer the explicitly selected native provider when it supports
+        # these tensors; retain the existing Triton provider otherwise.
+        if os.environ.get("FASTVIDEO_VSA_SM100A", "0") == "1":
+            try:
+                from fastvideo_kernel import block_sparse_attn_sm100a
+                from fastvideo_kernel.triton_kernels.index import map_to_index
+
+                if block_sparse_attn_sm100a.is_supported(q, variable_block_sizes):
+                    q2k_idx, q2k_num = map_to_index(block_map)
+                    out, _ = block_sparse_attn_sm100a.block_sparse_attn_sm100a(
+                        q,
+                        k,
+                        v,
+                        q2k_idx.to(torch.int32).contiguous(),
+                        q2k_num.to(torch.int32).contiguous(),
+                        variable_block_sizes.to(torch.int32).contiguous(),
+                        need_lse=False,
+                    )
+                    return out.transpose(1, 2).contiguous()
+            except torch.AcceleratorError:
+                # A device fault can poison the context; do not launch another kernel.
+                raise
+            except (ImportError, RuntimeError) as exc:
+                logger.warning_once(
+                    "FASTVIDEO_VSA_SM100A=1 requested but the native Blackwell forward is "
+                    "unavailable (%s); using the Triton block-sparse route instead.",
+                    exc,
+                )
+
+        from fastvideo_kernel.block_sparse_attn import block_sparse_attn
+
+        logical_len = logical_blocks * 64
+        out, _ = block_sparse_attn(
+            q[:, :, :logical_len].contiguous(),
+            k[:, :, :logical_len].contiguous(),
+            v[:, :, :logical_len].contiguous(),
+            block_map[..., :logical_blocks, :logical_blocks].contiguous(),
+            variable_block_sizes[:logical_blocks].to(torch.int32).contiguous(),
+        )
+        out = out.transpose(1, 2).contiguous()
+        if out.shape[1] != query.shape[1]:
+            out = torch.nn.functional.pad(out, (0, 0, 0, 0, 0, query.shape[1] - out.shape[1]))
+        return out
+
+    @fastvideo_block_sparse_attn_bshd.register_fake
+    def _(query, key, value, block_map, variable_block_sizes, logical_blocks):
+        del key, value, block_map, variable_block_sizes, logical_blocks
+        return torch.empty_like(query)
+
+
+fastvideo_block_sparse_attn_bshd = torch.ops.vllm_omni.fastvideo_block_sparse_attn_bshd
+
+
+def mean_pool_tiles(x: torch.Tensor, sizes: torch.Tensor, block_size: int) -> torch.Tensor:
+    """Mean-pool zero-padded BSHD tiles with FP32 accumulation.
+
+    ``sizes`` gives the number of valid rows in each tile.
+    """
+    batch, seq_len, heads, dim = x.shape
+    blocks = seq_len // block_size
+    pooled = x.view(batch, blocks, block_size, heads, dim).sum(dim=2, dtype=torch.float32)
+    pooled = pooled / sizes.view(1, -1, 1, 1).clamp_min(1)
+    return pooled.permute(0, 2, 1, 3)
+
+
+def build_prefix_dense_block_map(
+    scores: torch.Tensor,
+    num_prefix_blocks: int,
+    num_sparse_blocks: int,
+    topk: int,
+) -> torch.Tensor:
+    """Keep prefix queries/keys dense and select top-k non-prefix keys per row."""
+    keep_sparse = min(topk, num_sparse_blocks)
+    if keep_sparse == num_sparse_blocks:
+        return torch.ones_like(scores, dtype=torch.bool)
+    block_map = torch.zeros_like(scores, dtype=torch.bool)
+    indices = scores[..., num_prefix_blocks:].topk(keep_sparse, dim=-1).indices + num_prefix_blocks
+    block_map.scatter_(-1, indices, True)
+    block_map[..., :num_prefix_blocks] = True
+    block_map[:, :, :num_prefix_blocks, :] = True
+    return block_map
diff --git a/vllm_omni/diffusion/cache/teacache/extractors.py b/vllm_omni/diffusion/cache/teacache/extractors.py
index 3aca638ec69..a7539b34a44 100644
--- a/vllm_omni/diffusion/cache/teacache/extractors.py
+++ b/vllm_omni/diffusion/cache/teacache/extractors.py
@@ -1262,7 +1262,7 @@ def extract_minimax_h3_context(
     preprocessing via ``_embed``, cacheable ``blocks`` loop, and
     ``final_layer`` postprocessing with row selection and update masks.
     """
-    from vllm_omni.diffusion.attention.ops.minimax_h3_modulation import indexed_scale_shift_
+    from vllm_omni.diffusion.layers.indexed_modulation import indexed_scale_shift_
     from vllm_omni.diffusion.models.minimax_h3.minimax_h3_transformer import (
         _FORWARD_SUPPORTED_KWARGS,
         MINIMAX_H3_ADALN_MODALITY_NUM,
diff --git a/vllm_omni/diffusion/attention/ops/minimax_h3_modulation.py b/vllm_omni/diffusion/layers/indexed_modulation.py
similarity index 98%
rename from vllm_omni/diffusion/attention/ops/minimax_h3_modulation.py
rename to vllm_omni/diffusion/layers/indexed_modulation.py
index 20327b7e945..385ce1a1be0 100644
--- a/vllm_omni/diffusion/attention/ops/minimax_h3_modulation.py
+++ b/vllm_omni/diffusion/layers/indexed_modulation.py
@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-"""Fused MiniMax H3 modulation with FP32 accumulation."""
+"""Fused indexed modulation with FP32 accumulation."""
 
 from __future__ import annotations
 
@@ -244,7 +244,7 @@ def rms_norm_indexed_scale_shift(
     indices: torch.Tensor,
     eps: float,
 ) -> torch.Tensor:
-    """Fuse H3 RMSNorm with its indexed AdaLN affine transform."""
+    """Fuse RMSNorm with an indexed affine transform."""
     if x.is_cpu:
         input_dtype = x.dtype
         normalized = x.float()
diff --git a/vllm_omni/diffusion/models/minimax_h3/attention/__init__.py b/vllm_omni/diffusion/models/minimax_h3/attention/__init__.py
new file mode 100644
index 00000000000..4244ce4b4e1
--- /dev/null
+++ b/vllm_omni/diffusion/models/minimax_h3/attention/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
diff --git a/vllm_omni/diffusion/models/minimax_h3/attention/fastvideo_h3.py b/vllm_omni/diffusion/models/minimax_h3/attention/fastvideo_h3.py
new file mode 100644
index 00000000000..35b87a58b96
--- /dev/null
+++ b/vllm_omni/diffusion/models/minimax_h3/attention/fastvideo_h3.py
@@ -0,0 +1,209 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""MiniMax-H3 VSA prefix routing, tile layout, and learned compression gate."""
+
+from __future__ import annotations
+
+import functools
+import math
+
+import torch
+from vllm.logger import init_logger
+
+from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
+from vllm_omni.diffusion.attention.backends.fastvideo_vsa import (
+    FastVideoVSAImpl,
+    _construct_variable_block_sizes,
+    _get_gate_compress,
+    _get_non_pad_index,
+    _get_tile_partition_indices,
+)
+from vllm_omni.diffusion.attention.ops.block_sparse import (
+    build_prefix_dense_block_map,
+    fastvideo_block_sparse_attn_bshd,
+    mean_pool_tiles,
+)
+
+logger = init_logger(__name__)
+
+
+@functools.lru_cache(maxsize=32)
+def _get_h3_tile_metadata(
+    prefix_segments: tuple[int, ...],
+    video_shape: tuple[int, int, int],
+    device: torch.device,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor, int, int]:
+    """Official FastVideo H3 geometry: pure prefix chunks + 3-D video tiles."""
+    block_size = (4, 4, 4)
+    block_elements = 64
+    prefix_len = sum(prefix_segments)
+    prefix_sizes: list[int] = []
+    for segment in prefix_segments:
+        full, remainder = divmod(segment, block_elements)
+        prefix_sizes.extend([block_elements] * full)
+        if remainder:
+            prefix_sizes.append(remainder)
+
+    video_indices = _get_tile_partition_indices(video_shape, block_size, device) + prefix_len
+    video_sizes = _construct_variable_block_sizes(video_shape, block_size, device)
+    partition = torch.cat([torch.arange(prefix_len, device=device, dtype=torch.long), video_indices])
+    sizes = torch.cat([torch.tensor(prefix_sizes, device=device, dtype=torch.int32), video_sizes.to(torch.int32)])
+    non_pad = _get_non_pad_index(sizes, block_elements)
+    untile = non_pad[torch.argsort(partition)]
+    total = prefix_len + math.prod(video_shape)
+    if int(sizes.sum()) != total or untile.numel() != total:
+        raise ValueError(
+            f"invalid H3 VSA geometry: prefix={prefix_segments}, video={video_shape}, "
+            f"sizes_sum={int(sizes.sum())}, total={total}"
+        )
+    return partition, sizes, non_pad, untile, len(prefix_sizes), int(video_sizes.numel())
+
+
+def _get_h3_layout(
+    attn_metadata: AttentionMetadata | None,
+) -> tuple[tuple[int, ...], tuple[int, int, int], int] | None:
+    if attn_metadata is None or attn_metadata.video_layout is None:
+        return None
+    prefix = attn_metadata.extra.get("vsa_h3_prefix_segments")
+    if not isinstance(prefix, (tuple, list)):
+        return None
+    target = next(
+        (span for span in reversed(attn_metadata.video_layout.video_spans) if span.role == "target"),
+        None,
+    )
+    if target is None:
+        return None
+    return tuple(int(x) for x in prefix if int(x) > 0), target.latent_grid, target.start
+
+
+class MiniMaxH3VSAImpl(FastVideoVSAImpl):
+    """Apply H3 tile64 routing after shared parallel attention dispatch."""
+
+    def _forward_h3(
+        self,
+        query: torch.Tensor,
+        key: torch.Tensor,
+        value: torch.Tensor,
+        attn_metadata: AttentionMetadata,
+    ) -> torch.Tensor:
+        layout = _get_h3_layout(attn_metadata)
+        if layout is None:
+            raise ValueError("incomplete VSA-H3 layout metadata")
+        prefix_segments, video_shape, target_start = layout
+        if sum(prefix_segments) != target_start:
+            raise ValueError(f"VSA-H3 prefix segments sum to {sum(prefix_segments)}, target starts at {target_start}")
+        expected = target_start + math.prod(video_shape)
+        if query.shape[1] != expected:
+            raise ValueError(f"VSA-H3 layout has {expected} rows but attention received {query.shape[1]}")
+        if query.dtype not in (torch.float16, torch.bfloat16):
+            raise ValueError(f"VSA-H3 requires fp16/bf16 tensors, got {query.dtype}")
+        gate = _get_gate_compress(attn_metadata)
+        if gate is not None:
+            # H3 pads the packed document to 64 rows, while VSA operates on
+            # the valid prefix. Validate/slice before launching attention so a
+            # metadata error can never trigger an unsafe dense fallback after
+            # an asynchronous custom kernel.
+            if gate.shape[0] != query.shape[0] or gate.shape[2:] != query.shape[2:] or gate.shape[1] < query.shape[1]:
+                raise ValueError(f"gate_compress shape {gate.shape} cannot cover query shape {query.shape}")
+            gate = gate[:, : query.shape[1]]
+
+        partition, sizes, non_pad, untile, prefix_blocks, video_blocks = _get_h3_tile_metadata(
+            prefix_segments, video_shape, query.device
+        )
+        logical_blocks = int(sizes.numel())
+        # The native sm100a kernel assigns pairs of query blocks to CTAs. Its
+        # contract requires an even block count; the synthetic partner is
+        # transport-only and is removed before returning.
+        pair_pad = logical_blocks % 2
+        kernel_blocks = logical_blocks + pair_pad
+        target_shape = (query.shape[0], kernel_blocks * 64, query.shape[2], query.shape[3])
+        q_tiled = torch.zeros(target_shape, device=query.device, dtype=query.dtype)
+        k_tiled = torch.zeros_like(q_tiled)
+        v_tiled = torch.zeros_like(q_tiled)
+        q_tiled[:, non_pad] = query[:, partition]
+        k_tiled[:, non_pad] = key[:, partition]
+        v_tiled[:, non_pad] = value[:, partition]
+
+        q_pool = mean_pool_tiles(q_tiled[:, : logical_blocks * 64], sizes, block_size=64)
+        k_pool = mean_pool_tiles(k_tiled[:, : logical_blocks * 64], sizes, block_size=64)
+        scores = torch.matmul(q_pool, k_pool.transpose(-2, -1)) * self.softmax_scale
+        block_map = build_prefix_dense_block_map(scores, prefix_blocks, video_blocks, self.topk)
+        kernel_sizes = sizes
+        if pair_pad:
+            block_map = torch.nn.functional.pad(block_map, (0, 1, 0, 1), value=False)
+            kernel_sizes = torch.nn.functional.pad(sizes, (0, 1), value=0)
+
+        logger.info_once(
+            "FASTVIDEO_VSA H3 routing: seq_len=%d, prefix_segments=%s, video_shape=%s, "
+            "prefix_blocks=%d, video_blocks=%d, topk=%d, kernel_blocks=%d",
+            query.shape[1],
+            prefix_segments,
+            video_shape,
+            prefix_blocks,
+            video_blocks,
+            min(self.topk, video_blocks),
+            kernel_blocks,
+        )
+        output = fastvideo_block_sparse_attn_bshd(
+            q_tiled.contiguous(),
+            k_tiled.contiguous(),
+            v_tiled.contiguous(),
+            block_map.contiguous(),
+            kernel_sizes.contiguous(),
+            logical_blocks,
+        )[:, : logical_blocks * 64]
+
+        if gate is not None:
+            gate_tiled = torch.zeros_like(q_tiled[:, : logical_blocks * 64])
+            gate_tiled[:, non_pad] = gate[:, partition]
+            v_pool = mean_pool_tiles(v_tiled[:, : logical_blocks * 64], sizes, block_size=64)
+            compressed = torch.matmul(torch.softmax(scores, dim=-1), v_pool)
+            compressed = compressed.permute(0, 2, 1, 3).to(output.dtype)
+            output = (
+                output.view(output.shape[0], logical_blocks, 64, output.shape[2], output.shape[3])
+                + compressed.unsqueeze(2)
+                * gate_tiled.view(gate_tiled.shape[0], logical_blocks, 64, gate_tiled.shape[2], gate_tiled.shape[3])
+            ).view_as(output)
+        return output[:, untile].contiguous()
+
+    def forward_cuda(
+        self,
+        query: torch.Tensor,
+        key: torch.Tensor,
+        value: torch.Tensor,
+        attn_metadata: AttentionMetadata | None = None,
+    ) -> torch.Tensor:
+        if _get_h3_layout(attn_metadata) is None:
+            return super().forward_cuda(query, key, value, attn_metadata)
+
+        original_query, original_key, original_value = query, key, value
+        original_seq_len = query.shape[1]
+        valid_seq_len = original_seq_len
+        if attn_metadata is not None and attn_metadata.packed_padding is not None:
+            valid_seq_len = attn_metadata.packed_padding.q_length
+            if attn_metadata.packed_padding.kv_length != valid_seq_len:
+                return self._fallback(
+                    original_query, original_key, original_value, attn_metadata, "packed Q/KV lengths must match"
+                )
+            query = query[:, :valid_seq_len]
+            key = key[:, :valid_seq_len]
+            value = value[:, :valid_seq_len]
+
+        try:
+            output = self._forward_h3(query, key, value, attn_metadata)
+            if valid_seq_len == original_seq_len:
+                return output
+            restored = torch.zeros_like(original_query)
+            restored[:, :valid_seq_len] = output
+            return restored
+        except Exception as exc:
+            # A CUDA fault poisons the process context; attempting SDPA
+            # afterwards obscures the original kernel failure and cannot
+            # recover the request.
+            if isinstance(exc, torch.AcceleratorError):
+                raise
+            if not self.fallback_on_error:
+                raise
+            return self._fallback(
+                original_query, original_key, original_value, attn_metadata, f"VSA-H3 kernel failed: {exc}"
+            )
diff --git a/vllm_omni/diffusion/models/minimax_h3/minimax_h3_transformer.py b/vllm_omni/diffusion/models/minimax_h3/minimax_h3_transformer.py
index f0839429bad..e26493931b6 100644
--- a/vllm_omni/diffusion/models/minimax_h3/minimax_h3_transformer.py
+++ b/vllm_omni/diffusion/models/minimax_h3/minimax_h3_transformer.py
@@ -33,12 +33,6 @@
     VideoTokenLayout,
 )
 from vllm_omni.diffusion.attention.layer import Attention
-from vllm_omni.diffusion.attention.ops.minimax_h3_modulation import (
-    indexed_gate,
-    indexed_gate_rms_norm_scale_shift,
-    indexed_scale_shift_,
-    rms_norm_indexed_scale_shift,
-)
 from vllm_omni.diffusion.cache.cachedit import CacheDiTAdapterConfig
 from vllm_omni.diffusion.distributed.sp_plan import (
     SequenceParallelInput,
@@ -50,6 +44,12 @@
 )
 from vllm_omni.diffusion.layers.activation import SiluAndMul
 from vllm_omni.diffusion.layers.fused_qk_norm_rope import fused_qk_norm_rope
+from vllm_omni.diffusion.layers.indexed_modulation import (
+    indexed_gate,
+    indexed_gate_rms_norm_scale_shift,
+    indexed_scale_shift_,
+    rms_norm_indexed_scale_shift,
+)
 from vllm_omni.diffusion.layers.norm import RMSNorm
 from vllm_omni.diffusion.layers.rope import RotaryEmbedding
 from vllm_omni.diffusion.models.host_weight_contract import FinalLayoutModelContract
@@ -442,6 +442,8 @@ def __init__(
         self._gate_hidden_size = arch.hidden_size
         self._gate_quant_config = quant_config
         self._gate_prefix = f"{prefix}.to_gate_compress"
+        from .attention.fastvideo_h3 import MiniMaxH3VSAImpl
+
         self.attention = Attention(
             num_heads=self.num_heads,
             num_kv_heads=self.num_kv_heads,
@@ -454,6 +456,7 @@ def __init__(
             role_category=role_category,
             skip_sequence_parallel=skip_sequence_parallel,
             prefix=prefix,
+            impl_overrides={"FASTVIDEO_VSA": MiniMaxH3VSAImpl},
         )
 
     def enable_vsa_gate(self) -> None:

From 5f7f62e13cfb88bc1add00db5d3ac2e9ef1328f5 Mon Sep 17 00:00:00 2001
From: y-null <y_null@qq.com>
Date: Wed, 16 Sep 2026 16:24:31 +0800
Subject: [PATCH 028/105] [Bugfix][MiniCPM-o] Stabilize code2wav CFM CUDA graph
 caching with reference audio normalization and mel-frame bucketing (#7416)

Signed-off-by: y_null <y_null@qq.com>
Co-authored-by: amy-why-3459 <wuhaiyan17@huawei.com>
---
 tests/config/test_config_factory.py           |   6 +-
 .../minicpmo_4_5/test_cfm_graph_bucketing.py  | 162 ++++++++++++++
 .../minicpmo_4_5/test_code2wav_batching.py    | 102 ++++++++-
 .../minicpmo_4_5/test_cuda_graph_wrapper.py   |  44 +++-
 .../test_reference_audio_normalization.py     | 204 ++++++++++++++++++
 vllm_omni/deploy/minicpmo_4_5.yaml            |   2 +-
 vllm_omni/deploy/minicpmo_4_5_2gpu.yaml       |   2 +-
 vllm_omni/deploy/minicpmo_4_5_3gpu.yaml       |   2 +-
 vllm_omni/deploy/minicpmo_4_5_8x4090.yaml     |   2 +-
 .../models/minicpmo_4_5/batched_token2wav.py  | 147 +++++++++++++
 .../models/minicpmo_4_5/cuda_graph_wrapper.py |  33 ++-
 .../minicpmo_4_5/minicpmo_4_5_code2wav.py     | 143 +++++++++++-
 .../npu/models/minicpmo_4_5_code2wav.py       |  14 ++
 13 files changed, 838 insertions(+), 25 deletions(-)
 create mode 100644 tests/model_executor/models/minicpmo_4_5/test_cfm_graph_bucketing.py
 create mode 100644 tests/model_executor/models/minicpmo_4_5/test_reference_audio_normalization.py

diff --git a/tests/config/test_config_factory.py b/tests/config/test_config_factory.py
index d1dc0fd6d2c..3699eeda726 100644
--- a/tests/config/test_config_factory.py
+++ b/tests/config/test_config_factory.py
@@ -1328,7 +1328,11 @@ def test_minicpmo_deploy_configs_enable_duplex(self, filename: str, max_sessions
         stages = merge_pipeline_deploy(pipeline, deploy)
 
         assert deploy.session_mode == "duplex"
-        assert deploy.active_stream_window == max_sessions
+        # ``0`` disables the limiter: the configured session/stage capacity is
+        # what bounds the pipeline. Any positive window serializes concurrent
+        # audio first-packet generation (measured: TTFP -23% at 0 vs 4 on
+        # L20X, 128 requests / concurrency 8).
+        assert deploy.active_stream_window == 0
         assert deploy.duplex_session.max_sessions == max_sessions
         assert [stage.session_mode for stage in stages] == ["duplex", "duplex", "duplex"]
         assert [stage.to_omegaconf().session_mode for stage in stages] == ["duplex", "duplex", "duplex"]
diff --git a/tests/model_executor/models/minicpmo_4_5/test_cfm_graph_bucketing.py b/tests/model_executor/models/minicpmo_4_5/test_cfm_graph_bucketing.py
new file mode 100644
index 00000000000..c88fc6d5b2c
--- /dev/null
+++ b/tests/model_executor/models/minicpmo_4_5/test_cfm_graph_bucketing.py
@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Unit tests for the CFM mel-frame bucketing decision.
+
+Steady-state chunk lengths vary per request; without bucketing every length
+becomes its own CUDA-graph capture shape (428 captures / 13 flushes in the
+#6628 regression). ``_cfm_pad_frames`` aligns the frame axis onto a grid so
+steady-state calls share one capture shape; ``_decode_cfm`` trims the output
+back. These tests pin the decision math on CPU, no CUDA required.
+"""
+
+import pytest
+import torch
+
+from vllm_omni.model_executor.models.minicpmo_4_5.batched_token2wav import (
+    _cfm_pad_frames,
+    _zero_padded_frames,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_pads_partial_chunk_up_to_bucket():
+    # 50 frames on a 16-frame grid -> 14 padding frames.
+    assert _cfm_pad_frames(mel_frames=50, offset=0, noise_capacity=1000, bucket_frames=16, disabled=False) == 14
+
+
+def test_aligned_chunk_needs_no_padding():
+    assert _cfm_pad_frames(mel_frames=64, offset=0, noise_capacity=1000, bucket_frames=16, disabled=False) == 0
+
+
+def test_ragged_valid_lengths_path_disables_bucketing():
+    """The ragged per-request cache path must never be padded."""
+    for ragged in (True,):
+        for mel in (50, 64, 96):
+            assert (
+                _cfm_pad_frames(
+                    mel_frames=mel,
+                    offset=0,
+                    noise_capacity=1000,
+                    bucket_frames=16,
+                    disabled=ragged,
+                )
+                == 0
+            )
+
+
+def test_disabled_bucketing_returns_zero():
+    """bucket_frames <= 1 (or wrapper absent) means plain eager behavior."""
+    for bucket in (0, 1):
+        assert (
+            _cfm_pad_frames(
+                mel_frames=50,
+                offset=0,
+                noise_capacity=1000,
+                bucket_frames=bucket,
+                disabled=False,
+            )
+            == 0
+        )
+
+
+def test_padding_never_overflows_noise_buffer():
+    """Padding past the decoder's noise buffer must fall back to zero.
+
+    The padded call slices x from decoder.rand_noise[offset:end]; exceeding
+    its width would crash. Bucketing is best-effort, never required.
+    """
+    # 96 frames + 16 pad = 112 > 100 capacity -> give up, pad 0.
+    assert _cfm_pad_frames(mel_frames=96, offset=0, noise_capacity=100, bucket_frames=16, disabled=False) == 0
+    # Same mel length fits when un-padded: 96 <= 100.
+    assert _cfm_pad_frames(mel_frames=96, offset=0, noise_capacity=100, bucket_frames=1, disabled=False) == 0
+    # Cache offset eats into the capacity: 64 + 0 pad would fit, 64 + 48 pad
+    # would not, so the pad must be dropped.
+    assert _cfm_pad_frames(mel_frames=64, offset=50, noise_capacity=110, bucket_frames=16, disabled=False) == 0
+    # The original chunk fits while the padded one does not: 50 + 50 = 100
+    # <= 110, but 100 + 14 = 114 > 110, so the pad must be dropped.
+    assert _cfm_pad_frames(mel_frames=50, offset=50, noise_capacity=110, bucket_frames=16, disabled=False) == 0
+    # Same numbers with room for the padding: 114 <= 120, so it stands.
+    assert _cfm_pad_frames(mel_frames=50, offset=50, noise_capacity=120, bucket_frames=16, disabled=False) == 14
+
+
+def test_padding_applies_with_cache_offset_when_it_fits():
+    # offset 50 + mel 50 + pad 14 = 114 <= 200 -> pad stands.
+    assert _cfm_pad_frames(mel_frames=50, offset=50, noise_capacity=200, bucket_frames=16, disabled=False) == 14
+
+
+def test_steady_state_cache_width_saturates_on_bucket_grid():
+    """Pin the real recurrence: grow, then trim to ``prompt_len + 100``.
+
+    ``_decode_batch_once`` trims the estimator attention cache after every
+    decode, so the width saturates instead of growing without bound. What
+    matters for the graph cache is that the steady-state
+    ``(chunk_width, cache_width)`` pair settles on a single grid point.
+    """
+    bucket, prompt_len = 16, 304
+    cache_cap = prompt_len + 100
+    width = prompt_len
+    shapes = set()
+    for _ in range(20):
+        pad = _cfm_pad_frames(
+            mel_frames=50,
+            offset=width,
+            noise_capacity=30000,
+            bucket_frames=bucket,
+            disabled=False,
+        )
+        assert pad == 14
+        shapes.add((50 + pad, width))  # (chunk width, cache width) as used
+        width = min(width + 50 + pad, cache_cap)
+    assert width == cache_cap
+    # (64, 304) -> (64, 368) -> (64, 404), then stable.
+    assert shapes == {(64, 304), (64, 368), (64, 404)}
+
+
+def test_varied_chunk_lengths_collapse_onto_few_widths():
+    """Bucketing exists for the varied-length calls, not the steady 50-frame one.
+
+    The first/last chunk and the ``plan_token2wav_encode_slices`` splits land on
+    arbitrary lengths; those are the calls that would each become their own
+    capture shape. Pin that a realistic mix collapses onto a few padded widths.
+    """
+    varied = (7, 12, 17, 25, 33, 50, 51, 64)
+    padded = {
+        mel
+        + _cfm_pad_frames(
+            mel_frames=mel,
+            offset=300,
+            noise_capacity=30000,
+            bucket_frames=16,
+            disabled=False,
+        )
+        for mel in varied
+    }
+    assert len(padded) == 4, sorted(padded)  # 16 / 32 / 48 / 64
+    assert len(padded) < len(varied)
+
+
+def test_zero_padded_frames_survives_an_integration_step():
+    """The padded region must stay zero after ``x = x + dt * velocity``.
+
+    Zeroing once before the CFM loop is not enough: the update touches every
+    column, so the padded region becomes non-zero again (0 -> 0.010 -> 0.020
+    over the first steps). Pin the helper that re-zeroes it each step.
+    """
+    mel, pad = 50, 14
+    x = torch.zeros(2, 4, mel + pad)
+    x[..., :mel] = 0.05
+    _zero_padded_frames(x, mel)
+    assert torch.all(x[..., mel:] == 0.0)
+    for _ in range(3):
+        x = x + 0.02 * torch.ones_like(x)  # the integration step
+        _zero_padded_frames(x, mel)
+        assert torch.all(x[..., mel:] == 0.0)
+        assert torch.all(x[..., :mel] > 0.0)
+
+
+def test_zero_padded_frames_is_a_noop_without_padding():
+    x = torch.ones(1, 2, 32)
+    _zero_padded_frames(x, None)
+    _zero_padded_frames(x, 32)
+    assert torch.all(x == 1.0)
diff --git a/tests/model_executor/models/minicpmo_4_5/test_code2wav_batching.py b/tests/model_executor/models/minicpmo_4_5/test_code2wav_batching.py
index a0e7ed4dbf9..edb813af3f0 100644
--- a/tests/model_executor/models/minicpmo_4_5/test_code2wav_batching.py
+++ b/tests/model_executor/models/minicpmo_4_5/test_code2wav_batching.py
@@ -523,7 +523,7 @@ def test_cfm_graph_receives_bfloat16_cache_in_compute_dtype():
     seen_dtypes: list[torch.dtype] = []
 
     class RecordingGraph:
-        def replay(self, estimator_input, time_embedding, cnn_cache, att_cache, cnn_out, att_out):
+        def replay(self, estimator_input, time_embedding, cnn_cache, att_cache, cnn_out, att_out, attn_mask=None):
             del time_embedding, cnn_cache
             seen_dtypes.append(att_cache.dtype)
             return estimator_input[:, :1], cnn_out, att_out
@@ -1313,3 +1313,103 @@ def test_reference_voice_and_duplex_metadata_follow_request_lifecycle():
     assert prompt_key not in model._runtime_prompts
     assert not Path(prompt_wav).exists()
     assert (prompt_cache_id, prompt_wav) not in model.backend._prompt_features
+
+
+def _eager_cfm_wrapper(estimator: nn.Module) -> SimpleNamespace:
+    """A CFM graph wrapper that honours the contract but runs eagerly.
+
+    ``_decode_cfm`` only takes the padded path when a wrapper is present, so
+    CPU tests that need that path (CUDA graphs are unavailable here) supply
+    this in place of the real wrapper.
+    """
+
+    def replay(estimator_input, time_emb, cnn_cache, att_cache, cnn_out, att_out, attn_mask=None):
+        output = estimator.blocks_forward_chunk(
+            estimator_input,
+            time_emb,
+            attn_mask,
+            cnn_cache,
+            att_cache,
+            cnn_out,
+            att_out,
+        )
+        return output, cnn_out, att_out
+
+    return SimpleNamespace(enabled=True, replay=replay)
+
+
+def _padded_decode_adapter(bucket_frames: int) -> tuple[BatchedToken2Wav, int, int]:
+    """Build an adapter over a real ``DiT`` that exercises the CFM path.
+
+    Returns the adapter, the valid width, and the padding width. Every call
+    seeds the same way, so two adapters built here agree on weights and noise.
+    """
+    from cosyvoice2.flow.decoder_dit import DiT
+
+    torch.manual_seed(23)
+    estimator = DiT(
+        in_channels=4,
+        out_channels=1,
+        depth=2,
+        num_heads=2,
+        head_dim=2,
+        hidden_size=4,
+    ).eval()
+    token2wav = _FakeToken2Wav()
+    token2wav.flow.decoder.estimator = estimator
+    token2wav.flow.decoder.rand_noise = torch.randn(1, 1, 160)
+    adapter = BatchedToken2Wav(token2wav)
+    adapter._cfm_graph_wrapper = _eager_cfm_wrapper(estimator)
+    adapter._cfm_graph_bucket_frames = bucket_frames
+    mel_frames = 51  # the 16-frame grid pads this to 64
+    pad_frames = (-(-mel_frames // 16) * 16 - mel_frames) if bucket_frames else 0
+    return adapter, mel_frames, pad_frames
+
+
+def test_padded_chunk_keeps_the_cross_chunk_caches_on_the_valid_boundary():
+    """Caches the next chunk reads must not carry padding.
+
+    The padded steps still run, so ``step_cnn``/``step_att`` come back with
+    padding-derived values in them. Unless those positions are cleared, the
+    following chunk consumes them as its keys and as its CNN left context.
+    This drives a padded chunk through the real ``DiT`` and checks both caches
+    at the boundary.
+    """
+    adapter, mel_frames, pad_frames = _padded_decode_adapter(bucket_frames=16)
+    assert pad_frames == 13
+
+    mu = torch.randn(1, 1, mel_frames)
+    cond = torch.zeros(1, 1, mel_frames)
+    speakers = torch.randn(1, 1)
+    with torch.no_grad():
+        x, cnn, att = adapter._decode_cfm(mu, speakers, cond, cnn_cache=None, att_cache=None)
+
+    assert int(x.shape[2]) == mel_frames
+    assert int(att.shape[4]) == mel_frames + pad_frames
+    # These columns become the next chunk's keys.
+    assert torch.count_nonzero(att[..., mel_frames : mel_frames + pad_frames, :]) == 0
+    # This tail becomes the next chunk's CNN left context.
+    assert torch.count_nonzero(cnn[..., -pad_frames:]) == 0
+
+
+def test_padding_does_not_change_the_valid_frames():
+    """A padded chunk returns the same valid frames as an exact-width one.
+
+    Masking takes the padded keys out of the attention and the padded CNN tail
+    never reaches the valid positions, so the only difference between the two
+    runs is the capture shape -- not the audio the chunk produces.
+    """
+    padded, mel_frames, pad_frames = _padded_decode_adapter(bucket_frames=16)
+    exact, _, exact_pad = _padded_decode_adapter(bucket_frames=0)
+    assert pad_frames == 13
+    assert exact_pad == 0
+
+    mu = torch.randn(1, 1, mel_frames, generator=torch.Generator().manual_seed(5))
+    cond = torch.zeros(1, 1, mel_frames)
+    speakers = torch.randn(1, 1, generator=torch.Generator().manual_seed(7))
+    with torch.no_grad():
+        padded_x, _, _ = padded._decode_cfm(mu, speakers, cond, cnn_cache=None, att_cache=None)
+        exact_x, _, _ = exact._decode_cfm(mu, speakers, cond, cnn_cache=None, att_cache=None)
+
+    assert int(padded_x.shape[2]) == int(exact_x.shape[2]) == mel_frames
+    assert torch.allclose(padded_x, exact_x, atol=1e-5)
diff --git a/tests/model_executor/models/minicpmo_4_5/test_cuda_graph_wrapper.py b/tests/model_executor/models/minicpmo_4_5/test_cuda_graph_wrapper.py
index 26daeff7b07..959156b8fc2 100644
--- a/tests/model_executor/models/minicpmo_4_5/test_cuda_graph_wrapper.py
+++ b/tests/model_executor/models/minicpmo_4_5/test_cuda_graph_wrapper.py
@@ -252,6 +252,37 @@ def test_cfm_graph_replay_matches_eager_for_uncached_and_cached_shapes(
     wrapper._flush()
 
 
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA is required")
+def test_cfm_capture_keeps_the_real_mask(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Static buffers must be built from the real inputs, mask included.
+
+    Capturing from zero-filled placeholders would bake the "nothing is masked"
+    branch into the graph, while replay copies the real mask into those very
+    buffers -- so the captured branch has to come from the real value.
+    """
+    pool = torch.cuda.graph_pool_handle()
+    monkeypatch.setattr(current_platform, "get_global_graph_pool", lambda: pool)
+
+    torch.manual_seed(0)
+    estimator = _MiniDiT().eval().cuda()
+    wrapper = CFMGraphWrapper(graph_fn=estimator.blocks_forward_chunk, max_graphs=4)
+
+    inputs = _cfm_inputs(2, 12, 0)
+    frames = int(inputs[0].shape[2])
+    mask = torch.ones(2, frames, frames, dtype=torch.bool, device="cuda")
+    mask[:, :, -2:] = False  # two padded keys are masked out
+
+    with torch.inference_mode():
+        wrapper.replay(*inputs, mask)
+        assert wrapper._stats["captures"] == 1
+
+    static_inputs, _, _ = next(iter(wrapper._cache.values()))
+    static_mask = static_inputs[6]
+    assert static_mask is not None
+    assert torch.equal(static_mask, mask)
+    wrapper._flush()
+
+
 def test_importing_wrapper_does_not_resolve_platform() -> None:
     """Importing this module must not build the OmniPlatform singleton.
 
@@ -354,7 +385,8 @@ def test_cfm_unsupported_dtype_eagers_only_that_shape(monkeypatch: pytest.Monkey
     """A key that cannot round-trip is a property of one shape, not of the GPU.
 
     It must not disable the wrapper or retire the generation the way a capture
-    failure does.
+    failure does. `_tensors_from_key` is the fallback used when no real inputs
+    are available, so the probe drives `_capture` without them.
     """
     pool = torch.cuda.graph_pool_handle()
     monkeypatch.setattr(current_platform, "get_global_graph_pool", lambda: pool)
@@ -374,7 +406,10 @@ def _reject_one_shape(key: tuple) -> tuple:
     monkeypatch.setattr(wrapper_module, "_tensors_from_key", _reject_one_shape)
 
     with torch.inference_mode():
-        wrapper.replay(*_cfm_inputs(2, unbuildable_width, 0))
+        key = ("estimator_step",) + tuple(
+            wrapper_module._tensor_signature(t) for t in _cfm_inputs(2, unbuildable_width, 0)
+        )
+        assert wrapper._capture(key, None) is None
         assert wrapper.enabled is True
         assert wrapper._stats["captures"] == 0
 
@@ -382,11 +417,6 @@ def _reject_one_shape(key: tuple) -> tuple:
         wrapper.replay(*_cfm_inputs(2, 12, 0))
         assert wrapper._stats["captures"] == 1
 
-        # and the rejected shape stays eager without retrying the capture
-        wrapper.replay(*_cfm_inputs(2, unbuildable_width, 0))
-        assert wrapper._stats["captures"] == 1
-        assert wrapper._stats["eager"] == 2
-
     wrapper._flush()
 
 
diff --git a/tests/model_executor/models/minicpmo_4_5/test_reference_audio_normalization.py b/tests/model_executor/models/minicpmo_4_5/test_reference_audio_normalization.py
new file mode 100644
index 00000000000..9b9bbf5703d
--- /dev/null
+++ b/tests/model_executor/models/minicpmo_4_5/test_reference_audio_normalization.py
@@ -0,0 +1,204 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Unit tests for the reference-audio normalization grid.
+
+Every request's reference audio is folded onto one sample rate and one fixed
+length so the CFM attention cache origin (L0) is a single constant; that is
+what collapsed the CFM CUDA-graph key space back from 58 shapes to a handful
+and cut the capture storm behind the #6628 regression. These tests pin the
+pure math so future edits cannot silently widen L0 again.
+"""
+
+import logging
+from types import SimpleNamespace
+
+import pytest
+import torch
+
+from vllm_omni.model_executor.models.minicpmo_4_5.minicpmo_4_5_code2wav import (
+    _REF_MAX_SECONDS,
+    _REF_TARGET_SAMPLE_RATE,
+    _normalize_reference,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+TARGET = _REF_TARGET_SAMPLE_RATE
+MAX_SAMPLES = int(_REF_MAX_SECONDS * TARGET)  # 6 s @ 24 kHz
+
+
+def test_mono_downmix_averages_channels_without_interleaving():
+    """(2, T) stereo must become channel-mean mono, not a reshape interleave.
+
+    reshape(-1) on (2, T) would alternate 1/0 samples; mean(dim=0) yields a
+    constant 0.5 waveform. The whole-output equality fails on any interleave.
+    """
+    stereo = torch.zeros(2, 16)
+    stereo[0] = 1.0
+    waveform, sr = _normalize_reference(stereo, TARGET)
+    assert sr == TARGET
+    assert waveform.shape == (MAX_SAMPLES,)
+    assert torch.all(waveform[:16] == 0.5)  # mono body
+    assert torch.all(waveform[16:] == 0.0)  # zero-padded tail
+
+
+def test_resample_48k_to_24k_halves_sample_count():
+    """Off-grid sample rates are resampled onto 24 kHz before padding."""
+    wav_48k = torch.arange(24000, dtype=torch.float32)
+    waveform, sr = _normalize_reference(wav_48k, 48000)
+    assert sr == TARGET
+    assert waveform.shape == (MAX_SAMPLES,)
+    assert torch.all(waveform[:12000] > 0)  # resampled body, then silence
+    assert torch.all(waveform[12000:] == 0)
+
+
+def test_long_reference_is_truncated_to_6s():
+    samples_7s = torch.arange(7 * TARGET, dtype=torch.float32)
+    waveform, sr = _normalize_reference(samples_7s, TARGET)
+    assert sr == TARGET
+    assert waveform.shape == (MAX_SAMPLES,)
+    assert torch.equal(waveform, samples_7s[:MAX_SAMPLES])
+
+
+def test_short_reference_is_zero_padded_to_6s():
+    """The zero-pad is the load-bearing half of S1b.
+
+    Truncation alone only caps long references; short ones would keep
+    distinct L0 values (verified experimentally: rtf 3.375 with truncation
+    only, 1.2 with zero-padding). Pin the padding behavior.
+    """
+    samples_1s = torch.arange(TARGET, dtype=torch.float32)
+    waveform, sr = _normalize_reference(samples_1s, TARGET)
+    assert sr == TARGET
+    assert waveform.shape == (MAX_SAMPLES,)
+    assert torch.equal(waveform[:TARGET], samples_1s)
+    assert torch.all(waveform[TARGET:] == 0)
+
+
+def test_exact_length_reference_passes_through_unchanged():
+    samples_6s = torch.arange(MAX_SAMPLES, dtype=torch.float32)
+    waveform, sr = _normalize_reference(samples_6s, TARGET)
+    assert sr == TARGET
+    assert torch.equal(waveform, samples_6s)
+
+
+def test_every_output_shares_one_length():
+    """Whatever comes in, one request's L0 equals any other's."""
+    for length in (TARGET // 4, TARGET, 3 * TARGET, MAX_SAMPLES + 1):
+        waveform, _ = _normalize_reference(torch.ones(length), TARGET)
+        assert waveform.numel() == MAX_SAMPLES
+
+
+def test_empty_reference_stays_empty():
+    """An empty waveform must not be padded into a valid-length reference.
+
+    ``_materialize_runtime_prompt`` relies on numel() == 0 to raise
+    "empty_ref_audio" and reject the request; zero-padding would turn a
+    broken input into a silently accepted all-silence reference.
+    """
+    waveform, sr = _normalize_reference(torch.zeros(0), TARGET)
+    assert waveform.numel() == 0
+    assert sr == TARGET
+
+
+def test_window_length_is_configurable():
+    """Deployments can widen the window via ``ref_audio_max_seconds``."""
+    samples_5s = torch.arange(5 * TARGET, dtype=torch.float32)
+    waveform, sr = _normalize_reference(samples_5s, TARGET, max_seconds=3.0)
+    assert sr == TARGET
+    assert waveform.numel() == 3 * TARGET
+    # A longer window keeps the whole 5s clip instead of truncating it.
+    waveform, _ = _normalize_reference(samples_5s, TARGET, max_seconds=8.0)
+    assert waveform.numel() == 8 * TARGET
+    assert torch.equal(waveform[: 5 * TARGET], samples_5s)
+
+
+def test_truncation_emits_warning(caplog):
+    """Silent truncation would hide a user-visible behavior change.
+
+    A bare ``caplog.at_level`` does not capture vLLM loggers (they do not
+    propagate to the root handlers the fixture taps), so attach the fixture
+    handler to the module logger directly -- same idiom as
+    ``tests/model_executor/stage_input_processors/test_qwen3_tts_async_chunk.py``.
+    """
+    samples_7s = torch.arange(7 * TARGET, dtype=torch.float32)
+    target_logger = logging.getLogger("vllm_omni.model_executor.models.minicpmo_4_5.minicpmo_4_5_code2wav")
+    target_logger.addHandler(caplog.handler)
+    prev_level = target_logger.level
+    target_logger.setLevel(logging.WARNING)
+    try:
+        _normalize_reference(samples_7s, TARGET)
+    finally:
+        target_logger.removeHandler(caplog.handler)
+        target_logger.setLevel(prev_level)
+    assert any("truncating" in record.getMessage() for record in caplog.records)
+
+
+def test_soundfile_2d_output_is_transposed_before_the_normalizer(tmp_path):
+    """``sf.read`` gives (samples, channels); the normalizer wants the transpose.
+
+    Without it a stereo default prompt looks like a huge channel count, the
+    downmix guard rejects it, and the caller falls back to the raw file -- so
+    that prompt keeps a second L0 value next to the normalized request
+    references.
+    """
+    import soundfile as sf
+
+    from vllm_omni.model_executor.models.minicpmo_4_5.minicpmo_4_5_code2wav import (
+        _read_reference_wav,
+    )
+
+    frames = TARGET
+    # Opposite-signed channels: the downmix is a true mean only when the two
+    # channels were aligned as rows, so a wrong layout cannot look correct.
+    stereo = torch.stack((torch.full((frames,), 0.5), torch.full((frames,), -0.5)), dim=1)
+    path = tmp_path / "stereo.wav"
+    sf.write(str(path), stereo.numpy(), TARGET, format="WAV")
+
+    waveform, sample_rate_hz = _read_reference_wav(str(path))
+
+    assert sample_rate_hz == TARGET
+    assert waveform.shape == (2, frames)
+    normalized, target_sr = _normalize_reference(waveform, sample_rate_hz, max_seconds=1.0)
+    assert target_sr == TARGET
+    assert normalized.shape[-1] == TARGET
+    assert torch.allclose(normalized, torch.zeros_like(normalized), atol=1e-6)
+
+
+def test_default_prompt_uses_the_configured_window(tmp_path):
+    """The default prompt has to honour ``ref_audio_max_seconds``.
+
+    With a non-default window, a default prompt normalized at the fixed 6 s
+    constant would keep a different L0 from the request references, which is
+    the mismatch this normalization exists to remove.
+    """
+    import tempfile
+
+    import soundfile as sf
+
+    from vllm_omni.model_executor.models.minicpmo_4_5.minicpmo_4_5_code2wav import (
+        MiniCPMO45Code2Wav,
+        _read_reference_wav,
+    )
+
+    frames = 2 * TARGET  # shorter than the window, so it gets zero-padded
+    samples = torch.full((frames, 2), 0.25)
+    source = tmp_path / "default.wav"
+    sf.write(str(source), samples.numpy(), TARGET, format="WAV")
+
+    window_seconds = 8.0
+    with tempfile.TemporaryDirectory() as runtime_dir:
+        stub = SimpleNamespace(
+            _default_prompt_wav=str(source),
+            _default_prompt_id="HT_ref_audio",
+            _default_prompt_normalized=None,
+            _ref_max_seconds=window_seconds,
+            _runtime_prompt_dir=SimpleNamespace(name=runtime_dir),
+        )
+        prompt_wav, _ = MiniCPMO45Code2Wav._normalized_default_prompt(stub)
+        # Read inside the block: the temporary directory is removed on exit.
+        normalized, sample_rate_hz = _read_reference_wav(prompt_wav)
+
+    assert sample_rate_hz == TARGET
+    # The configured window, not the fixed 6 s default.
+    assert normalized.shape[-1] == int(window_seconds * TARGET)
diff --git a/vllm_omni/deploy/minicpmo_4_5.yaml b/vllm_omni/deploy/minicpmo_4_5.yaml
index ca772afbd4e..5c26fc2c68b 100644
--- a/vllm_omni/deploy/minicpmo_4_5.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5.yaml
@@ -6,7 +6,6 @@ async_chunk: true
 session_mode: duplex
 # Keep the active window aligned with the session and stage capacities below.
 # A smaller window serializes first-packet generation for concurrent chat turns.
-active_stream_window: 4
 duplex_session:
   # Matches Stage 0/1 max_num_seqs below.
   max_sessions: 4
@@ -30,6 +29,7 @@ connectors:
       enable_hift_graph: true
       enable_cfm_graph: true
       cfm_max_graphs: 32
+      cfm_graph_bucket_frames: 16
 
 stages:
   - stage_id: 0
diff --git a/vllm_omni/deploy/minicpmo_4_5_2gpu.yaml b/vllm_omni/deploy/minicpmo_4_5_2gpu.yaml
index 9600e595972..136dace7e87 100644
--- a/vllm_omni/deploy/minicpmo_4_5_2gpu.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5_2gpu.yaml
@@ -9,7 +9,6 @@ async_chunk: true
 session_mode: duplex
 # Keep the active window aligned with the session and stage capacities below.
 # A smaller window serializes first-packet generation for concurrent chat turns.
-active_stream_window: 4
 duplex_session:
   # Matches Stage 0/1 max_num_seqs below.
   max_sessions: 4
@@ -33,6 +32,7 @@ connectors:
       enable_hift_graph: true
       enable_cfm_graph: true
       cfm_max_graphs: 32
+      cfm_graph_bucket_frames: 16
 
 stages:
   - stage_id: 0
diff --git a/vllm_omni/deploy/minicpmo_4_5_3gpu.yaml b/vllm_omni/deploy/minicpmo_4_5_3gpu.yaml
index aae5312183a..9669a2768a4 100644
--- a/vllm_omni/deploy/minicpmo_4_5_3gpu.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5_3gpu.yaml
@@ -9,7 +9,6 @@ async_chunk: true
 session_mode: duplex
 # Keep the active window aligned with the session and stage capacities below.
 # A smaller window serializes first-packet generation for concurrent chat turns.
-active_stream_window: 4
 duplex_session:
   # Matches Stage 0/1 max_num_seqs below.
   max_sessions: 4
@@ -33,6 +32,7 @@ connectors:
       enable_hift_graph: true
       enable_cfm_graph: true
       cfm_max_graphs: 32
+      cfm_graph_bucket_frames: 16
 
 stages:
   - stage_id: 0
diff --git a/vllm_omni/deploy/minicpmo_4_5_8x4090.yaml b/vllm_omni/deploy/minicpmo_4_5_8x4090.yaml
index 00b1090f898..92065dd4fe6 100644
--- a/vllm_omni/deploy/minicpmo_4_5_8x4090.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5_8x4090.yaml
@@ -19,7 +19,6 @@ async_chunk: true
 # (/v1/realtime?duplex=1). The default duplex_session caps sessions at 1,
 # matching Stage 0/1 max_num_seqs below.
 session_mode: duplex
-active_stream_window: 1
 
 trust_remote_code: true
 enable_prefix_caching: false
@@ -40,6 +39,7 @@ connectors:
       enable_hift_graph: true
       enable_cfm_graph: true
       cfm_max_graphs: 32
+      cfm_graph_bucket_frames: 16
 
 stages:
   - stage_id: 0
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/batched_token2wav.py b/vllm_omni/model_executor/models/minicpmo_4_5/batched_token2wav.py
index 2bffeb49e04..bec442282bc 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/batched_token2wav.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/batched_token2wav.py
@@ -46,6 +46,80 @@ def relpos_encode_token_budget(
     return max(lookahead + 1, min(int(cap), room))
 
 
+def _cfm_pad_frames(
+    *,
+    mel_frames: int,
+    offset: int,
+    noise_capacity: int,
+    bucket_frames: int,
+    disabled: bool,
+) -> int:
+    """Frame padding that aligns one CFM call onto the capture-shape grid.
+
+    Chunk lengths vary per request: the steady-state chunk is 50 mel frames,
+    but the first/last chunk and the ``plan_token2wav_encode_slices`` splits
+    land on arbitrary lengths, and every distinct length is its own CUDA-graph
+    capture shape. Padding the frame axis up to ``bucket_frames`` collapses
+    them onto one grid (the caller trims the output back). Measured on the
+    shipped config, 128 requests / concurrency 8: 61 captures and 1 cache
+    flush without bucketing versus 15 captures and 0 flushes with it, audio
+    RTF 1.317 -> 1.191 under otherwise identical conditions.
+
+    The attention and CNN caches also advance by the padded width so their
+    shapes stay on the same grid; in practice that is bounded by the trim in
+    ``_decode_batch_once`` (the cache width saturates at ``prompt_len +
+    100``) rather than by the decoder's ``rand_noise`` capacity.
+
+    Returns 0 when bucketing does not apply: the ragged valid-lengths path,
+    graphs unavailable or already disabled by ``CFMGraphWrapper._disable``,
+    or padding that would overflow the decoder's noise buffer.
+    """
+    if disabled or bucket_frames <= 1:
+        return 0
+    pad = (bucket_frames - mel_frames % bucket_frames) % bucket_frames
+    if offset + mel_frames + pad > noise_capacity:
+        return 0
+    return pad
+
+
+def _zero_padded_frames(tensor: torch.Tensor, valid_frames: int | None) -> None:
+    """Keep the padded columns of ``tensor`` at zero, in place.
+
+    Bucketing pads the frame axis so the capture shape stays fixed. The padded
+    columns carry no valid content: they are excluded from the attention by the
+    ``attn_mask`` built in ``_decode_batch_once``, and zeroing keeps them from
+    leaking back in. The integration step ``x = x + dt * velocity`` would
+    otherwise make the padded region non-zero again after the initial zeroing,
+    and the cross-chunk caches would read those values back.
+    """
+    if valid_frames is None or valid_frames >= int(tensor.shape[-1]):
+        return
+    tensor[..., valid_frames:] = 0.0
+
+
+def _zero_padded_cnn_cache(
+    cnn_cache: torch.Tensor,
+    estimator: nn.Module,
+    pad_frames: int,
+) -> None:
+    """Clear the cache positions that come from padded frames, in place.
+
+    Each block's CNN cache holds the tail of its convolution output
+    (``new_cnn_cache = x[..., -causal_padding[0]:]``, inside ``stepaudio2``),
+    so when the padding sits at the chunk tail those positions are
+    padding-derived and would otherwise become the next chunk's left context.
+    Padding is at most ``pad_frames`` wide, so only the trailing positions that
+    can come from it are cleared; the valid part of the window is kept.
+    """
+    for index, block in enumerate(estimator.blocks):
+        width = int(block.conv.block[1].causal_padding[0])
+        if width <= 0:
+            continue
+        zero_from = max(0, width - pad_frames)
+        if zero_from < width:
+            cnn_cache[index][..., zero_from:] = 0.0
+
+
 def plan_token2wav_encode_slices(
     num_frames: int,
     *,
@@ -249,6 +323,17 @@ def __init__(
                     "CFM CUDA Graph is disabled on device type %s",
                     flow_parameter.device.type if flow_parameter is not None else "unknown",
                 )
+        # mel-frame bucket size for the CFM CUDA Graph path. Pad each decode
+        # chunk up to a multiple of this many frames so the graph cache key
+        # space stays small (0 disables bucketing, e.g. when graphs are off).
+        self._cfm_graph_bucket_frames = (
+            int(cfm_graph_cfg.get("bucket_frames", 0)) if self._cfm_graph_wrapper is not None else 0
+        )
+        if self._cfm_graph_bucket_frames > 1:
+            logger.info(
+                "CFM CUDA Graph bucketing enabled (bucket_frames=%d)",
+                self._cfm_graph_bucket_frames,
+            )
         self._prompt_features: dict[tuple[str, str], PromptFeatures] = {}
 
     def _hift_inference(
@@ -398,6 +483,7 @@ def _estimator_step(
         att_cache: torch.Tensor | None,
         attn_mask: torch.Tensor | None = None,
         valid_lengths: list[int] | None = None,
+        valid_frames: int | None = None,
     ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
         if self._trt_stepper is not None and valid_lengths is None:
             out, new_cnn, new_att = self._trt_stepper.step(
@@ -413,6 +499,13 @@ def _estimator_step(
         time_embedding = estimator.t_embedder(time).unsqueeze(1)
         width = int(x.shape[-1])
         speaker_features = speakers.unsqueeze(-1).expand(-1, -1, width)
+        if valid_frames is not None and valid_frames < width:
+            # Every frame gets the speaker vector, so the padded columns would
+            # stay non-zero even with x/mu/cond zeroed -- and the estimator
+            # would then emit non-zero features there, leaving the
+            # chunk-boundary attention/CNN caches padding-derived. Zero them.
+            speaker_features = speaker_features.clone()
+            _zero_padded_frames(speaker_features, valid_frames)
         estimator_input = torch.cat((x, mu, speaker_features, cond), dim=1)
         cnn_out, att_out = self._estimator_buffers(estimator, estimator_input, att_cache)
         old_cnn: Any = cnn_cache if cnn_cache is not None else [None] * len(estimator.blocks)
@@ -433,6 +526,7 @@ def _estimator_step(
                 graph_att,
                 cnn_out,
                 att_out,
+                attn_mask,
             )
         if valid_lengths is not None:
             if not hasattr(estimator, "in_proj"):
@@ -566,6 +660,26 @@ def _decode_cfm(
         estimator = decoder.estimator
         batch_size = int(mu.shape[0])
         offset = int(att_cache.shape[4]) if att_cache is not None else 0
+        mel_frames = int(mu.shape[2])
+        pad_frames = _cfm_pad_frames(
+            mel_frames=mel_frames,
+            offset=offset,
+            noise_capacity=int(decoder.rand_noise.shape[2]),
+            bucket_frames=self._cfm_graph_bucket_frames,
+            disabled=(
+                valid_lengths is not None
+                or self._cfm_graph_wrapper is None
+                # `_disable` keeps the wrapper object alive, so check the flag
+                # too: padding under a disabled wrapper is pure overhead.
+                or not self._cfm_graph_wrapper.enabled
+            ),
+        )
+        if pad_frames:
+            # Replicate rather than zero: a repeated last frame is a closer
+            # continuation of the chunk than silence, so the padded positions
+            # carry less of a step change into the attention and CNN caches.
+            mu = torch.nn.functional.pad(mu, (0, pad_frames), mode="replicate")
+            cond = torch.nn.functional.pad(cond, (0, pad_frames), mode="replicate")
         end = offset + int(mu.shape[2])
         if end > int(decoder.rand_noise.shape[2]):
             raise RuntimeError(
@@ -574,6 +688,13 @@ def _decode_cfm(
                 f'"available":{int(decoder.rand_noise.shape[2])}}}'
             )
         x = decoder.rand_noise[:, :, offset:end].expand(batch_size, -1, -1).clone()
+        if pad_frames:
+            # The padded columns would otherwise carry real noise values. They
+            # are excluded from this chunk's attention by ``attn_mask`` below
+            # and held at zero here, so the padded region stays inert. Masking
+            # is what removes them; zeroing alone would not, since a zero row
+            # still occupies part of the softmax denominator.
+            x[:, :, mel_frames:] = 0.0
         timeline = torch.linspace(
             0,
             1,
@@ -603,6 +724,20 @@ def _decode_cfm(
                 device=mu.device,
             )
             attn_mask = valid_queries.unsqueeze(2) & torch.cat((current_keys, old_keys), dim=2)
+        elif pad_frames:
+            # Mask the padded keys instead of only zeroing their content: a
+            # zero-valued key/value pair still takes probability mass out of the
+            # softmax denominator, so the real frames keep attending to the
+            # padding unless it is explicitly excluded.
+            kv_len = int(mu.shape[2]) + offset
+            attn_mask = torch.ones(
+                2 * batch_size,
+                int(mu.shape[2]),
+                kv_len,
+                dtype=torch.bool,
+                device=mu.device,
+            )
+            attn_mask[:, :, mel_frames : mel_frames + pad_frames] = False
         next_cnn: list[torch.Tensor] = []
         next_att_cache: torch.Tensor | None = None
         ragged_att_cache: list[torch.Tensor] | None = None
@@ -622,10 +757,14 @@ def _decode_cfm(
                     att_cache=old_att,
                     attn_mask=attn_mask,
                     valid_lengths=valid_lengths,
+                    valid_frames=mel_frames if pad_frames else None,
                 )
+                if pad_frames:
+                    _zero_padded_cnn_cache(step_cnn, estimator, pad_frames)
                 conditional, unconditional = estimate.split(batch_size, dim=0)
                 velocity = (1.0 + decoder.inference_cfg_rate) * conditional - decoder.inference_cfg_rate * unconditional
                 x = x + dt * velocity
+                _zero_padded_frames(x, mel_frames if pad_frames else None)
                 time = time + dt
                 if step + 1 < self.n_timesteps:
                     dt = timeline[step + 2] - time[0]
@@ -666,7 +805,15 @@ def _decode_cfm(
                         dtype=self._estimator_att_cache_dtype,
                     )
                 next_att_cache[step].copy_(step_att)
+                if pad_frames:
+                    # The padded steps ran but hold no valid content, and each
+                    # cache entry becomes the next chunk's keys. Clear the
+                    # padded columns so the boundary the next chunk reads is
+                    # the valid one, in step with the mask built above.
+                    next_att_cache[step][..., mel_frames : mel_frames + pad_frames, :] = 0.0
                 del step_att
+        if pad_frames:
+            x = x[:, :, :mel_frames]
         if ragged_att_cache is not None:
             return x, torch.stack(next_cnn), ragged_att_cache
         assert next_att_cache is not None
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/cuda_graph_wrapper.py b/vllm_omni/model_executor/models/minicpmo_4_5/cuda_graph_wrapper.py
index d737905fdac..4db0c39bf2d 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/cuda_graph_wrapper.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/cuda_graph_wrapper.py
@@ -135,11 +135,13 @@ def replay(self, speech_feat, cache_source):
         return speech, cache_source
 
 
-def _tensor_signature(value: torch.Tensor) -> tuple:
+def _tensor_signature(value: torch.Tensor | None) -> tuple:
+    if value is None:
+        return (None,)
     return tuple(value.shape), str(value.dtype), str(value.device)
 
 
-_DTYPE_MAP = {str(dtype): dtype for dtype in (torch.float32, torch.float16, torch.bfloat16, torch.float64)}
+_DTYPE_MAP = {str(dtype): dtype for dtype in (torch.float32, torch.float16, torch.bfloat16, torch.float64, torch.bool)}
 
 
 def _memory_snapshot(device: torch.device) -> tuple[int, int] | None:
@@ -231,7 +233,7 @@ def stats_snapshot(self) -> dict[str, int]:
         return {**self._stats, "cache_size": len(self._cache)}
 
     def _call_graph_fn(self, args: tuple[torch.Tensor, ...]) -> torch.Tensor:
-        return self.graph_fn(args[0], args[1], None, args[2], args[3], args[4], args[5])
+        return self.graph_fn(args[0], args[1], args[6], args[2], args[3], args[4], args[5])
 
     def _eager(self, inputs: tuple[torch.Tensor, ...]) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
         self._stats["eager"] += 1
@@ -261,10 +263,21 @@ def _disable(self, reason: str, key: tuple) -> None:
         self.enabled = False
         self._flush()
 
-    def _capture(self, key: tuple) -> tuple | None:
-        """Capture a CUDA graph for the given key. Returns None on failure."""
+    def _capture(self, key: tuple, inputs: tuple | None = None) -> tuple | None:
+        """Capture a CUDA graph for the given key. Returns None on failure.
+
+        ``inputs`` should be the real tensors for this key whenever they are
+        available: the static buffers must be built from the values the graph
+        will actually run with. Zero-filled placeholders are only a fallback --
+        capturing with them bakes the placeholder branch into the graph (e.g. an
+        attention mask that looks like "nothing is masked").
+        """
         try:
-            static_inputs = _tensors_from_key(key)
+            static_inputs = (
+                tuple(None if tensor is None else tensor.detach().clone() for tensor in inputs)
+                if inputs is not None
+                else _tensors_from_key(key)
+            )
         except KeyError:
             # An unsupported dtype is a property of this shape alone, so run it
             # eager and keep the other shapes on graphs.
@@ -315,8 +328,9 @@ def replay(
         att_cache: torch.Tensor,
         cnn_out: torch.Tensor,
         att_out: torch.Tensor,
+        attn_mask: torch.Tensor | None = None,
     ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
-        inputs = (estimator_input, time_emb, cnn_cache, att_cache, cnn_out, att_out)
+        inputs = (estimator_input, time_emb, cnn_cache, att_cache, cnn_out, att_out, attn_mask)
         self._stats["calls"] += 1
 
         if not self.enabled or torch.cuda.is_current_stream_capturing() or estimator_input.device.type != "cuda":
@@ -330,7 +344,7 @@ def replay(
         if entry is None:
             if len(self._cache) >= self.max_graphs:
                 self._flush()
-            entry = self._capture(key)
+            entry = self._capture(key, inputs)
             if entry is None:
                 return self._eager(inputs)
             self._cache[key] = entry
@@ -339,7 +353,8 @@ def replay(
 
         static_inputs, static_output, graph = entry
         for static, current in zip(static_inputs, inputs, strict=True):
-            static.copy_(current)
+            if static is not None:
+                static.copy_(current)
         graph.replay()
         return (
             static_output.detach().clone(),
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_code2wav.py b/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_code2wav.py
index f701e8b2699..da2c0eb725d 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_code2wav.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_code2wav.py
@@ -9,6 +9,7 @@
 import tempfile
 from collections.abc import Iterable, Mapping, Sequence
 from dataclasses import dataclass
+from functools import lru_cache
 from hashlib import sha256
 from pathlib import Path
 from typing import Any
@@ -57,6 +58,92 @@ def _scalar(value: Any, default: Any = None) -> Any:
     return default if value is None else value
 
 
+_REF_TARGET_SAMPLE_RATE = 24000
+# Overridable per deployment via ``ref_audio_max_seconds``.
+_REF_MAX_SECONDS = 6.0
+# Channel ceiling for the optional (channels, samples) downmix guard.
+_REF_MAX_CHANNELS = 8
+
+
+@lru_cache(maxsize=8)
+def _get_resampler(orig_freq: int, new_freq: int):
+    """Cached anti-aliased resampler matching token2wav's own loader.
+
+    ``torchaudio`` is imported lazily (it is not a hard runtime requirement of
+    this model on every platform) and the transform is built once per rate pair
+    instead of once per request, keeping it off the first-packet path.
+    """
+    import torchaudio
+
+    return torchaudio.transforms.Resample(orig_freq=orig_freq, new_freq=new_freq)
+
+
+def _read_reference_wav(path: str) -> tuple[Any, int]:
+    """Read a WAV file for :func:`_normalize_reference`.
+
+    ``soundfile`` returns ``(samples, channels)`` for multi-channel files
+    while the normalizer expects ``(channels, samples)``. Without the
+    transpose a stereo prompt looks like a huge channel count, the downmix
+    guard rejects it, and the caller silently falls back to the raw file --
+    a second L0 value for the same content.
+    """
+    waveform, sample_rate_hz = sf.read(path, dtype="float32", always_2d=False)
+    if getattr(waveform, "ndim", 1) > 1:
+        waveform = waveform.T
+    return waveform, int(sample_rate_hz)
+
+
+def _normalize_reference(
+    ref_audio: Any,
+    sample_rate_hz: int,
+    *,
+    max_seconds: float = _REF_MAX_SECONDS,
+) -> tuple[torch.Tensor, int]:
+    """Normalize a per-request reference waveform onto a shared grid.
+
+    MiniCPM-o streaming uses the reference-audio length as the CFM attention
+    cache origin (L0). Unnormalized references give every request a distinct
+    L0, which explodes the CFM CUDA-graph cache key space (see #6628). Fold
+    every reference onto the same sample rate and a fixed length (truncate
+    long ones, zero-pad short ones) so L0 becomes one constant value.
+
+    References longer than ``max_seconds`` are truncated with a warning;
+    the window is configurable via ``ref_audio_max_seconds``.
+    """
+    tensor = torch.as_tensor(ref_audio, dtype=torch.float32)
+    if tensor.dim() > 1:
+        # (channels, samples) -> mono; plain reshape(-1) would interleave.
+        # Upstream flattens request references to 1-D, so anything else is a
+        # non-standard caller: reject layouts we cannot downmix unambiguously
+        # instead of silently averaging the waveform away.
+        if tensor.shape[0] > _REF_MAX_CHANNELS:
+            raise ValueError(f"reference audio must be 1-D or (channels, samples); got shape {tuple(tensor.shape)}")
+        tensor = tensor.mean(dim=0)
+    waveform = tensor.reshape(-1).cpu().contiguous()
+    if waveform.numel() == 0:
+        # Keep the caller's "empty_ref_audio" error path intact: an empty
+        # waveform must not be zero-padded into a valid-length reference.
+        return waveform, _REF_TARGET_SAMPLE_RATE
+    if sample_rate_hz != _REF_TARGET_SAMPLE_RATE:
+        # Match token2wav's own loader (torchaudio, anti-aliased): it only
+        # resamples when the stored rate differs, so this output is what the
+        # model consumes.
+        waveform = _get_resampler(sample_rate_hz, _REF_TARGET_SAMPLE_RATE)(waveform.view(1, -1)).view(-1).contiguous()
+    max_samples = max(1, int(max_seconds * _REF_TARGET_SAMPLE_RATE))
+    if waveform.numel() > max_samples:
+        logger.warning(
+            "Reference audio is %.2fs, truncating to the %.2fs window (set ``ref_audio_max_seconds`` to keep more).",
+            waveform.numel() / _REF_TARGET_SAMPLE_RATE,
+            max_seconds,
+        )
+        waveform = waveform[:max_samples].contiguous()
+    elif waveform.numel() < max_samples:
+        # Zero-pad short references so every request shares one L0; trailing
+        # silence has minimal style impact (verified via E3 WER/SIM).
+        waveform = torch.nn.functional.pad(waveform, (0, max_samples - waveform.numel()))
+    return waveform, _REF_TARGET_SAMPLE_RATE
+
+
 def _codec_tensor(value: Any, fallback: torch.Tensor) -> torch.Tensor:
     if isinstance(value, torch.Tensor):
         return value.reshape(-1).to(device=fallback.device, dtype=torch.long)
@@ -181,7 +268,11 @@ def __init__(
         self._cfm_graph_config = {
             "enabled": bool(extra.get("enable_cfm_graph", False)),
             "max_graphs": int(extra.get("cfm_max_graphs", 32)),
+            "bucket_frames": int(extra.get("cfm_graph_bucket_frames", 0)),
         }
+        self._ref_max_seconds = float(extra.get("ref_audio_max_seconds", _REF_MAX_SECONDS))
+        if self._ref_max_seconds <= 0:
+            raise ValueError("MiniCPM-o Code2Wav ref_audio_max_seconds must be > 0")
         self._min_batch_size = int(extra.get("code2wav_min_batch_size", 1))
         if self._min_batch_size < 1:
             raise ValueError("MiniCPM-o Code2Wav code2wav_min_batch_size must be >= 1")
@@ -192,6 +283,7 @@ def __init__(
             raise ValueError("MiniCPM-o Code2Wav code2wav_initial_batch_size must be 0 or >= code2wav_min_batch_size")
         self._default_prompt_id = str(extra.get("prompt_cache_id", "HT_ref_audio"))
         self._prompt_wav_override = extra.get("prompt_wav")
+        self._default_prompt_normalized: tuple[str, str] | None = None
 
     @property
     def _default_prompt_wav(self) -> str:
@@ -199,6 +291,46 @@ def _default_prompt_wav(self) -> str:
             return str(self._prompt_wav_override)
         return str(Path(self.model_path) / "assets" / "HT_ref_audio.wav")
 
+    def _normalized_default_prompt(self) -> tuple[str, str]:
+        """Fold the shipped default prompt onto the request-reference grid.
+
+        The shipped asset is 6.016 s and is loaded directly by token2wav, so a
+        request without a reference would otherwise keep a second L0 value a
+        couple of frames away from the normalized request references -- two
+        graph-key families instead of one (both use ``ref_audio_max_seconds``).
+        Returns ``(prompt_wav,
+        prompt_cache_id)``; if the asset cannot be read, the shipped path is
+        returned unchanged.
+        """
+        if self._default_prompt_normalized is not None:
+            return self._default_prompt_normalized
+        source = self._default_prompt_wav
+        fallback = (source, self._default_prompt_id)
+        try:
+            waveform, sample_rate_hz = _read_reference_wav(source)
+            normalized, target_sr = _normalize_reference(
+                waveform,
+                sample_rate_hz,
+                max_seconds=self._ref_max_seconds,
+            )
+        except Exception:
+            logger.warning("Could not normalize the default prompt %s; using it as-is", source)
+            self._default_prompt_normalized = fallback
+            return self._default_prompt_normalized
+        if normalized.numel() == 0:
+            self._default_prompt_normalized = fallback
+            return self._default_prompt_normalized
+        digest = sha256()
+        digest.update(normalized.numpy().tobytes())
+        digest.update(str(target_sr).encode())
+        cache_id = f"default-ref-{digest.hexdigest()[:24]}-{target_sr}"
+        path = Path(self._runtime_prompt_dir.name) / f"{cache_id}.wav"
+        if not path.is_file():
+            sf.write(path, normalized.numpy(), target_sr, format="WAV")
+        logger.info("Default prompt normalized onto the %.2fs window: %s", self._ref_max_seconds, path)
+        self._default_prompt_normalized = (str(path), cache_id)
+        return self._default_prompt_normalized
+
     def _extra_config(self) -> dict[str, Any]:
         model_config = getattr(self.vllm_config, "model_config", None)
         connector = getattr(model_config, "stage_connector_config", None)
@@ -220,9 +352,13 @@ def _materialize_runtime_prompt(
         sample_rate: Any,
     ) -> tuple[str, _RuntimePrompt]:
         sample_rate_hz = int(_scalar(sample_rate, 0))
-        waveform = torch.as_tensor(ref_audio, dtype=torch.float32).reshape(-1).cpu().contiguous()
         if sample_rate_hz <= 0:
             raise _batch_error("invalid_ref_audio_sample_rate", sample_rate=sample_rate_hz)
+        waveform, sample_rate_hz = _normalize_reference(
+            ref_audio,
+            sample_rate_hz,
+            max_seconds=self._ref_max_seconds,
+        )
         if waveform.numel() == 0:
             raise _batch_error("empty_ref_audio")
         if not bool(torch.isfinite(waveform).all().item()):
@@ -288,9 +424,10 @@ def _resolve_prompt(
         if entry is not None:
             return entry.cache_id, entry.path, cache_key
 
+        default_wav, default_cache_id = self._normalized_default_prompt()
         return (
-            str(_scalar(meta.get("prompt_cache_id"), self._default_prompt_id)),
-            str(_scalar(meta.get("prompt_wav"), self._default_prompt_wav)),
+            str(_scalar(meta.get("prompt_cache_id"), default_cache_id)),
+            str(_scalar(meta.get("prompt_wav"), default_wav)),
             None,
         )
 
diff --git a/vllm_omni/platforms/npu/models/minicpmo_4_5_code2wav.py b/vllm_omni/platforms/npu/models/minicpmo_4_5_code2wav.py
index 0d34c93a501..4346e83b67f 100644
--- a/vllm_omni/platforms/npu/models/minicpmo_4_5_code2wav.py
+++ b/vllm_omni/platforms/npu/models/minicpmo_4_5_code2wav.py
@@ -75,10 +75,15 @@ def _graphable_estimator_step(
     cond,
     cnn_cache,
     att_cache,
+    valid_frames=None,
 ):
     """Run the CFM estimator body after host-backed timestep embedding."""
     width = int(x.shape[-1])
     speaker_features = speakers.unsqueeze(-1).expand(-1, -1, width)
+    if valid_frames is not None and valid_frames < width:
+        # Match the CUDA path: padded columns must not carry the speaker vector.
+        speaker_features = speaker_features.clone()
+        speaker_features[:, :, valid_frames:] = 0.0
     estimator_input = torch.cat((x, mu, speaker_features, cond), dim=1)
     cnn_out, att_out = backend._estimator_buffers(estimator, estimator_input, att_cache)
     old_cnn = cnn_cache if cnn_cache is not None else [None] * len(estimator.blocks)
@@ -108,6 +113,7 @@ def _patched_estimator_step(
     att_cache,
     attn_mask=None,
     valid_lengths=None,
+    valid_frames=None,
 ):
     assert _original_estimator_step is not None
     graph_runner = _backend_graph_runners.get(self)
@@ -130,10 +136,16 @@ def _patched_estimator_step(
             att_cache=att_cache,
             attn_mask=attn_mask,
             valid_lengths=valid_lengths,
+            valid_frames=valid_frames,
         )
     if (cnn_cache is None) != (att_cache is None):
         raise ValueError("estimator CNN and attention caches must both be present or absent")
 
+    # valid_frames only matters for padded inputs; skip forwarding it for
+    # unpadded calls so platform-owned graphable bodies that predate the
+    # padding feature keep working with the old signature.
+    graphable_kwargs = {"valid_frames": valid_frames} if valid_frames is not None else {}
+
     # The upstream embedder creates a frequency tensor on the host. Keep it
     # outside capture while retaining the tensor-only estimator body in graph.
     time_embedding = estimator.t_embedder(time).unsqueeze(1)
@@ -152,6 +164,7 @@ def _patched_estimator_step(
                 cond=step_cond,
                 cnn_cache=None,
                 att_cache=None,
+                **graphable_kwargs,
             ),
         )
 
@@ -169,6 +182,7 @@ def _patched_estimator_step(
             cond=step_cond,
             cnn_cache=step_cnn,
             att_cache=step_att,
+            **graphable_kwargs,
         ),
     )
 

From e78a5d01f785795b59bdcbc9f68214a3ce8cd06b Mon Sep 17 00:00:00 2001
From: Linze Shi <linzeshi0@gmail.com>
Date: Wed, 16 Sep 2026 01:30:16 -0700
Subject: [PATCH 029/105] [Frontend] Add MiniMax-H3 references and Ref2VA
 workflow (#7483)

Signed-off-by: Linze-Shi <linzeshi0@gmail.com>
---
 apps/ComfyUI-vLLM-Omni/README.md              |  74 ++
 .../comfyui_vllm_omni/nodes.py                |  36 +-
 .../comfyui_vllm_omni/utils/api_client.py     |  78 +-
 .../comfyui_vllm_omni/utils/types.py          |   6 +
 ...LM-Omni MiniMax-H3 Reference to Video.json | 786 ++++++++++++++++++
 recipes/MiniMaxAI/MiniMax-H3.md               |  11 +-
 .../comfyui/test_comfyui_integration.py       |  57 +-
 .../comfyui/test_h3_reference_workflow.py     | 115 +++
 .../features/comfyui/test_video_references.py | 138 +++
 9 files changed, 1235 insertions(+), 66 deletions(-)
 create mode 100644 apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax-H3 Reference to Video.json
 create mode 100644 tests/e2e/features/comfyui/test_h3_reference_workflow.py
 create mode 100644 tests/e2e/features/comfyui/test_video_references.py

diff --git a/apps/ComfyUI-vLLM-Omni/README.md b/apps/ComfyUI-vLLM-Omni/README.md
index b848a07161d..8f445635d28 100644
--- a/apps/ComfyUI-vLLM-Omni/README.md
+++ b/apps/ComfyUI-vLLM-Omni/README.md
@@ -139,6 +139,80 @@ You can configure per-stage sampling parameters for multi-stage models.
 >
 > Do not use `frame` and `references` together. Task routing is automatic from which inputs you connect.
 
+For MiniMax-H3 Ref2VA, **Video References** accepts up to 9 images (`image_1`–`image_9`),
+3 videos (`video_1`–`video_3`), and 3 audio clips (`audio_1`–`audio_3`), with at most
+12 connected inputs in total. Any mixture containing at least one image or video
+is supported; empty and audio-only references are rejected. For example, you can
+combine 6 images, 3 videos, and 3 audio clips in one request.
+
+Within each media type, references follow slot-number order, skipping unconnected
+slots. For example, connecting `image_2` and `image_9` sends `image_2` as the first
+image and `image_9` as the second. Each image slot uses the first image in its batch.
+Existing connections to `image_1`, `image_2`, `audio_1`, `audio_2`, `video_1`, and
+`video_2` remain valid in saved workflows.
+
+#### MiniMax-H3 Reference to Video
+
+Load [MiniMax-H3 Reference to Video](example_workflows/vLLM-Omni%20MiniMax-H3%20Reference%20to%20Video.json)
+from **Templates → ComfyUI-vLLM-Omni**, or drag the JSON onto the canvas.
+It adapts the [official ComfyUI R2V workflow](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/video_minimax_h3_r2v.json)
+to remote vLLM-Omni execution. Model loading, sampling, and VAE decoding run on
+the server; ComfyUI loads references and saves the returned video.
+
+Use an extension version containing the audio-preserving output fix from
+[#7456](https://github.com/vllm-project/vllm-omni/pull/7456). Older versions can
+drop the server's audio while decoding the response.
+
+1. Start a Ref2VA-capable service using the [MiniMax-H3 recipe](../../recipes/MiniMaxAI/MiniMax-H3.md).
+   Set **Generate Video** to its `/v1` URL and served model name.
+2. Select your own image in **Load Image**. The template's filenames are placeholders
+   relative to ComfyUI's input directory; no sample assets or model weights are bundled.
+3. Connect **Load Video** and **Load Audio** when needed. Duplicate the loaders to
+   fill more reference slots, or disconnect the image when using video-only input.
+   Keep the references connected to **Generate Video** and leave `frame` disconnected.
+4. Match prompt tags such as `<Picture 1>`, `<Video 1>`, and `<Audio 1>` to the
+   connected references, counting each media type separately and skipping empty slots.
+5. Run the workflow. **Save Video** writes an MP4 under `output/video/` and preserves
+   the generated audio when the audio-output prerequisite is installed.
+
+The default is **1344×768, 24 FPS, 124 frames** (about 5.17 seconds), 50 sampling
+points, video flow shift 12, audio flow shift 3, and seed 42. The duration widget
+is set to 5.167 seconds, which converts to 124 frames at 24 FPS. Other H3 canvas presets
+are 1024×768, 768×768, 768×1024, and 768×1344. Keep frame counts at `17k+5` within
+the 4–15 second output range; examples are 107, 124, 209, and 345 frames.
+Reference video/audio clips must each be 2–15 seconds, with at most 15 seconds of
+reference video and at most 15 seconds of standalone reference audio per request.
+
+For **Ref2VA Turbo**, use the same template. Configure a Ref2VA-only server with
+`--lora-backend peft --lora-path "$TURBO_LORA" --task-type ref2va`, following the
+recipe's hardware setup. For `minimax_h3_ref2v_turbo_4step_v0.1_bf16.safetensors`,
+set **LoRA** `local_path` to that file's path on the server and connect it to
+**Generate Video**. Use `num_inference_steps=5`, `flow_shift=12`,
+`audio_flow_shift=3`, and LoRA `scale=1`. The API counts sigma points, so five
+points produce four denoiser evaluations. Use the Diffusers artifact, not its
+`_comfyui_` export. To return to base mode, disconnect LoRA and restore 50 steps.
+The 8-step v1.0 Ref2VA adapter instead requires nine sampling points and video
+flow shift 6. FastH3 is a separate startup-fused T2VA deployment.
+
+Validate the template's wiring and defaults locally with:
+
+```bash
+python -m pytest tests/e2e/features/comfyui/test_h3_reference_workflow.py -q
+```
+
+For a real-model check, run the workflow against H3 and inspect the saved file:
+
+```bash
+ffprobe -v error -show_entries stream=codec_type,width,height,r_frame_rate,sample_rate,channels \
+  -show_entries format=duration -of json "$OUTPUT_MP4"
+```
+
+Check for 24 FPS video, stereo audio, the requested canvas, and aligned duration;
+also play the result to assess reference conditioning and audio/video synchronization.
+Record the server commit, model/adapter, input assets, prompt, settings, and output
+alongside the result. Local schema or mocked-server checks do not establish H3
+generation quality or replace this real-model validation.
+
 #### H3 video upscale (WF-07)
 
 The **vLLM-Omni MiniMax H3 Video Upscale** template generates video remotely, upscales it with SeedVR2, and saves the original and upscaled videos with the generated audio and FPS. See [workflow setup](docs/wf07-h3-upscale.md).
diff --git a/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py b/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py
index df91ece606f..47bdd9a2ccb 100644
--- a/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py
+++ b/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py
@@ -10,6 +10,9 @@
 from .utils.logger import get_logger
 from .utils.models import lookup_model_spec
 from .utils.types import (
+    MAX_REFERENCE_AUDIOS,
+    MAX_REFERENCE_IMAGES,
+    MAX_REFERENCE_VIDEOS,
     AudioFormat,
     AutoregressionSamplingParams,
     DiffusionSamplingParams,
@@ -918,6 +921,10 @@ def INPUT_TYPES(cls):
                 "audio_2": ("AUDIO",),
                 "video_1": ("VIDEO",),
                 "video_2": ("VIDEO",),
+                # Append ports to preserve connections in saved workflows.
+                **{f"image_{i}": ("IMAGE",) for i in range(3, MAX_REFERENCE_IMAGES + 1)},
+                **{f"audio_{i}": ("AUDIO",) for i in range(3, MAX_REFERENCE_AUDIOS + 1)},
+                **{f"video_{i}": ("VIDEO",) for i in range(3, MAX_REFERENCE_VIDEOS + 1)},
             },
         }
 
@@ -934,21 +941,26 @@ def get_references(
         audio_2: AudioInput | None = None,
         video_1: VideoInput | None = None,
         video_2: VideoInput | None = None,
+        image_3: torch.Tensor | None = None,
+        image_4: torch.Tensor | None = None,
+        image_5: torch.Tensor | None = None,
+        image_6: torch.Tensor | None = None,
+        image_7: torch.Tensor | None = None,
+        image_8: torch.Tensor | None = None,
+        image_9: torch.Tensor | None = None,
+        audio_3: AudioInput | None = None,
+        video_3: VideoInput | None = None,
         **kwargs,
     ):
         if kwargs:
             logger.info("Uncaught kwargs: %s", kwargs)
         refs = VideoReferences()
-        if image_1 is not None:
-            refs["image_1"] = image_1
-        if image_2 is not None:
-            refs["image_2"] = image_2
-        if audio_1 is not None:
-            refs["audio_1"] = audio_1
-        if audio_2 is not None:
-            refs["audio_2"] = audio_2
-        if video_1 is not None:
-            refs["video_1"] = video_1
-        if video_2 is not None:
-            refs["video_2"] = video_2
+        for kind, values in (
+            ("image", (image_1, image_2, image_3, image_4, image_5, image_6, image_7, image_8, image_9)),
+            ("video", (video_1, video_2, video_3)),
+            ("audio", (audio_1, audio_2, audio_3)),
+        ):
+            for index, value in enumerate(values, start=1):
+                if value is not None:
+                    refs[f"{kind}_{index}"] = value
         return (refs,)
diff --git a/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/api_client.py b/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/api_client.py
index e051e9a09ab..588f8b5b93f 100644
--- a/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/api_client.py
+++ b/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/api_client.py
@@ -20,6 +20,7 @@
 
 from .format import (
     audio_to_base64,
+    audio_to_bytes,
     base64_to_audio,
     base64_to_image_tensor,
     bytes_to_audio,
@@ -31,7 +32,13 @@
 )
 from .logger import get_logger, pretty_printer
 from .models import lookup_model_spec
-from .types import AudioFormat
+from .types import (
+    MAX_REFERENCE_AUDIOS,
+    MAX_REFERENCE_IMAGES,
+    MAX_REFERENCE_VIDEOS,
+    MAX_TOTAL_REFERENCES,
+    AudioFormat,
+)
 
 logger = get_logger(__name__)
 
@@ -304,38 +311,44 @@ async def generate_video(
 
         # === multimodal inputs (first-last-frames, references, etc.) ===
         input_reference_image: torch.Tensor | None = None
-        audio_reference: AudioInput | None = None
-        reference_videos: list[VideoInput] = []
         video_task: str | None = None
 
         if frame is not None:
             input_reference_image = frame
             video_task = "fl2va"
         elif references is not None:
-            images = [references[k] for k in ("image_1", "image_2") if k in references and references[k] is not None]
-            audios = [references[k] for k in ("audio_1", "audio_2") if k in references and references[k] is not None]
-            videos = [references[k] for k in ("video_1", "video_2") if k in references and references[k] is not None]
-
-            if not images and not audios and not videos:
-                raise ValueError("references is empty; connect at least one image/audio/video.")
-
-            if videos:
-                if images or audios:
-                    raise ValueError(
-                        "Video references cannot be combined with image or audio references. "
-                        "Connect only video_1/video_2 for multi-video Ref2VA."
-                    )
-                reference_videos = videos
-                video_task = "ref2va"
-            elif len(images) == 1 and len(audios) == 1:
-                input_reference_image = images[0]
-                audio_reference = audios[0]
-                video_task = "ref2va"
-            else:
+            reference_formats = (
+                ("image", MAX_REFERENCE_IMAGES, "png", "image/png", image_tensor_to_png_bytes),
+                ("video", MAX_REFERENCE_VIDEOS, "mp4", "video/mp4", video_to_bytes),
+                ("audio", MAX_REFERENCE_AUDIOS, "mp3", "audio/mpeg", audio_to_bytes),
+            )
+            supported_inputs = {f"{kind}_{i}" for kind, limit, *_ in reference_formats for i in range(1, limit + 1)}
+            connected = {name: value for name, value in references.items() if value is not None}
+            unsupported = connected.keys() - supported_inputs
+            if unsupported:
+                raise ValueError(f"Unsupported reference input(s): {', '.join(sorted(unsupported))}.")
+            if not any(name.startswith(("image_", "video_")) for name in connected):
                 raise ValueError(
-                    "Invalid references combination. Supported modes: "
-                    "(1) one or more videos only, or (2) exactly one image and one audio."
+                    "references requires at least one image or video; audio-only inputs are not supported."
                 )
+            if len(connected) > MAX_TOTAL_REFERENCES:
+                raise ValueError(
+                    f"references supports at most {MAX_TOTAL_REFERENCES} inputs in total "
+                    f"(up to {MAX_REFERENCE_IMAGES} images, {MAX_REFERENCE_VIDEOS} videos, "
+                    f"and {MAX_REFERENCE_AUDIOS} audios)."
+                )
+            for kind, limit, extension, content_type, encode in reference_formats:
+                for index in range(1, limit + 1):
+                    name = f"{kind}_{index}"
+                    if name in connected:
+                        filename = f"{name}.{extension}"
+                        form.add_field(
+                            "input_references",
+                            encode(connected[name], filename),
+                            filename=filename,
+                            content_type=content_type,
+                        )
+            video_task = "ref2va"
         else:
             video_task = "t2va"
 
@@ -348,21 +361,6 @@ async def generate_video(
                 content_type="image/png",
             )
 
-        if audio_reference is not None:
-            form.add_field(
-                "audio_reference",
-                json.dumps({"audio_url": audio_to_base64(audio_reference)}, ensure_ascii=False),
-            )
-
-        for idx, video in enumerate(reference_videos, start=1):
-            video_filename = f"reference_{idx}.mp4"
-            form.add_field(
-                "input_references",
-                video_to_bytes(video, video_filename),
-                filename=video_filename,
-                content_type="video/mp4",
-            )
-
         # === model specific params. Either use a specialized builder, or add flattened fields as-is ===
         if model_params is not None:
             model_params = dict(model_params)
diff --git a/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/types.py b/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/types.py
index bfba4414223..6d12a98c223 100644
--- a/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/types.py
+++ b/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/utils/types.py
@@ -30,6 +30,12 @@ class MiniMaxH3ModelSpecificParams(dict):
     pass
 
 
+MAX_REFERENCE_IMAGES = 9
+MAX_REFERENCE_VIDEOS = 3
+MAX_REFERENCE_AUDIOS = 3
+MAX_TOTAL_REFERENCES = 12
+
+
 class VideoReferences(dict):
     pass
 
diff --git a/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax-H3 Reference to Video.json b/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax-H3 Reference to Video.json
new file mode 100644
index 00000000000..3a9693df9bb
--- /dev/null
+++ b/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax-H3 Reference to Video.json	
@@ -0,0 +1,786 @@
+{
+  "id": "e7a4e606-6510-4c4e-b127-9a8b6bf3ea71",
+  "revision": 0,
+  "last_node_id": 11,
+  "last_link_id": 5,
+  "nodes": [
+    {
+      "id": 1,
+      "type": "LoadImage",
+      "pos": [
+        40,
+        100
+      ],
+      "size": [
+        320,
+        300
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "image",
+          "name": "image",
+          "type": "COMBO",
+          "widget": {
+            "name": "image"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "choose file to upload",
+          "name": "upload",
+          "type": "IMAGEUPLOAD",
+          "widget": {
+            "name": "upload"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "IMAGE",
+          "name": "IMAGE",
+          "type": "IMAGE",
+          "links": [
+            1
+          ]
+        },
+        {
+          "localized_name": "MASK",
+          "name": "MASK",
+          "type": "MASK",
+          "links": null
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "LoadImage"
+      },
+      "widgets_values": [
+        "h3_reference.png",
+        "image"
+      ],
+      "title": "Reference image \u2014 select a local file"
+    },
+    {
+      "type": "LoadVideo",
+      "size": [
+        320,
+        200
+      ],
+      "flags": {},
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "VIDEO",
+          "type": "VIDEO",
+          "links": null
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "LoadVideo"
+      },
+      "widgets_values": [
+        "h3_reference.mp4"
+      ],
+      "id": 2,
+      "pos": [
+        40,
+        470
+      ],
+      "order": 1,
+      "mode": 0,
+      "title": "Optional reference video"
+    },
+    {
+      "id": 3,
+      "type": "LoadAudio",
+      "pos": [
+        40,
+        1100
+      ],
+      "size": [
+        320,
+        160
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "audio",
+          "name": "audio",
+          "type": "COMBO",
+          "widget": {
+            "name": "audio"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "audioUI",
+          "name": "audioUI",
+          "type": "AUDIO_UI",
+          "widget": {
+            "name": "audioUI"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "choose file to upload",
+          "name": "upload",
+          "type": "AUDIOUPLOAD",
+          "widget": {
+            "name": "upload"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "AUDIO",
+          "name": "AUDIO",
+          "type": "AUDIO",
+          "links": null
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "LoadAudio"
+      },
+      "widgets_values": [
+        "h3_reference.wav",
+        null,
+        ""
+      ],
+      "title": "Optional reference audio"
+    },
+    {
+      "id": 4,
+      "type": "VLLMOmniVideoReferences",
+      "pos": [
+        420,
+        100
+      ],
+      "size": [
+        300,
+        365
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "image_1",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": 1
+        },
+        {
+          "name": "image_2",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "audio_1",
+          "type": "AUDIO",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "audio_2",
+          "type": "AUDIO",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "video_1",
+          "type": "VIDEO",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "video_2",
+          "type": "VIDEO",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "image_3",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "image_4",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "image_5",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "image_6",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "image_7",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "image_8",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "image_9",
+          "type": "IMAGE",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "audio_3",
+          "type": "AUDIO",
+          "shape": 7,
+          "link": null
+        },
+        {
+          "name": "video_3",
+          "type": "VIDEO",
+          "shape": 7,
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "references",
+          "name": "references",
+          "type": "VIDEO_REFERENCES",
+          "links": [
+            2
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniVideoReferences"
+      },
+      "widgets_values": [],
+      "title": "References \u2014 up to 12 total"
+    },
+    {
+      "id": 5,
+      "type": "VLLMOmniDiffusionSampling",
+      "pos": [
+        420,
+        530
+      ],
+      "size": [
+        310,
+        275
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "n",
+          "name": "n",
+          "type": "INT",
+          "widget": {
+            "name": "n"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "num_inference_steps",
+          "name": "num_inference_steps",
+          "type": "INT",
+          "widget": {
+            "name": "num_inference_steps"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "guidance_scale",
+          "name": "guidance_scale",
+          "type": "FLOAT",
+          "widget": {
+            "name": "guidance_scale"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "true_cfg_scale",
+          "name": "true_cfg_scale",
+          "type": "FLOAT",
+          "widget": {
+            "name": "true_cfg_scale"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "vae_use_slicing",
+          "name": "vae_use_slicing",
+          "type": "BOOLEAN",
+          "widget": {
+            "name": "vae_use_slicing"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "vae_use_tiling",
+          "name": "vae_use_tiling",
+          "type": "BOOLEAN",
+          "widget": {
+            "name": "vae_use_tiling"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "seed",
+          "name": "seed",
+          "type": "INT",
+          "widget": {
+            "name": "seed"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "diffusion sampling params",
+          "name": "diffusion sampling params",
+          "type": "SAMPLING_PARAMS",
+          "links": [
+            3
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniDiffusionSampling"
+      },
+      "widgets_values": [
+        1,
+        50,
+        1.0,
+        1.0,
+        false,
+        false,
+        42,
+        "fixed"
+      ],
+      "title": "Sampling \u2014 base 50 / Turbo 5"
+    },
+    {
+      "id": 6,
+      "type": "VLLMOmniMiniMaxH3Params",
+      "pos": [
+        790,
+        750
+      ],
+      "size": [
+        310,
+        105
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "audio_flow_shift",
+          "name": "audio_flow_shift",
+          "type": "FLOAT",
+          "widget": {
+            "name": "audio_flow_shift"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "flow_shift",
+          "name": "flow_shift",
+          "type": "FLOAT",
+          "widget": {
+            "name": "flow_shift"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "MiniMax-H3 video params",
+          "name": "MiniMax-H3 video params",
+          "type": "VIDEO_PARAMS",
+          "links": [
+            4
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniMiniMaxH3Params"
+      },
+      "widgets_values": [
+        3.0,
+        12.0
+      ],
+      "title": "H3 video/audio flow shifts"
+    },
+    {
+      "type": "VLLMOmniRemoteLoRA",
+      "size": [
+        310,
+        180
+      ],
+      "flags": {},
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "lora",
+          "type": "REMOTE_LORA",
+          "links": null
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniRemoteLoRA"
+      },
+      "widgets_values": [
+        "",
+        "h3-ref2va-turbo",
+        1.0,
+        0
+      ],
+      "id": 7,
+      "pos": [
+        420,
+        940
+      ],
+      "order": 6,
+      "mode": 0,
+      "title": "Optional Turbo LoRA \u2014 connect to enable"
+    },
+    {
+      "id": 8,
+      "type": "VLLMOmniGenerateVideo",
+      "pos": [
+        800,
+        100
+      ],
+      "size": [
+        470,
+        560
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "frame",
+          "name": "frame",
+          "shape": 7,
+          "type": "IMAGE",
+          "link": null
+        },
+        {
+          "localized_name": "references",
+          "name": "references",
+          "shape": 7,
+          "type": "VIDEO_REFERENCES",
+          "link": 2
+        },
+        {
+          "localized_name": "sampling_params",
+          "name": "sampling_params",
+          "shape": 7,
+          "type": "SAMPLING_PARAMS",
+          "link": 3
+        },
+        {
+          "localized_name": "lora",
+          "name": "lora",
+          "shape": 7,
+          "type": "REMOTE_LORA",
+          "link": null
+        },
+        {
+          "localized_name": "model_params",
+          "name": "model_params",
+          "shape": 7,
+          "type": "VIDEO_PARAMS",
+          "link": 4
+        },
+        {
+          "localized_name": "url",
+          "name": "url",
+          "type": "STRING",
+          "widget": {
+            "name": "url"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "model",
+          "name": "model",
+          "type": "STRING",
+          "widget": {
+            "name": "model"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "prompt",
+          "name": "prompt",
+          "type": "STRING",
+          "widget": {
+            "name": "prompt"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "negative_prompt",
+          "name": "negative_prompt",
+          "type": "STRING",
+          "widget": {
+            "name": "negative_prompt"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "width",
+          "name": "width",
+          "type": "INT",
+          "widget": {
+            "name": "width"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "height",
+          "name": "height",
+          "type": "INT",
+          "widget": {
+            "name": "height"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "fps",
+          "name": "fps",
+          "type": "INT",
+          "widget": {
+            "name": "fps"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "duration",
+          "name": "duration",
+          "type": "FLOAT",
+          "widget": {
+            "name": "duration"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "video",
+          "name": "video",
+          "type": "VIDEO",
+          "links": [
+            5
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniGenerateVideo"
+      },
+      "widgets_values": [
+        "http://localhost:8000/v1",
+        "MiniMaxAI/MiniMax-H3",
+        "Use the subject and visual style from <Picture 1>. Create a cinematic shot with a gentle camera move and natural ambient sound.",
+        "",
+        1344,
+        768,
+        24,
+        5.167
+      ],
+      "title": "MiniMax-H3 Reference to Video"
+    },
+    {
+      "id": 9,
+      "type": "SaveVideo",
+      "pos": [
+        1360,
+        100
+      ],
+      "size": [
+        410,
+        420
+      ],
+      "flags": {},
+      "order": 8,
+      "mode": 0,
+      "inputs": [
+        {
+          "localized_name": "video",
+          "name": "video",
+          "type": "VIDEO",
+          "link": 5
+        },
+        {
+          "localized_name": "filename_prefix",
+          "name": "filename_prefix",
+          "type": "STRING",
+          "widget": {
+            "name": "filename_prefix"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "format",
+          "name": "format",
+          "type": "COMBO",
+          "widget": {
+            "name": "format"
+          },
+          "link": null
+        },
+        {
+          "localized_name": "codec",
+          "name": "codec",
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "codec"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "localized_name": "video",
+          "name": "video",
+          "type": "VIDEO",
+          "links": null
+        }
+      ],
+      "properties": {},
+      "widgets_values": [
+        "video/MiniMax-H3-Ref2VA",
+        "mp4",
+        "h264"
+      ],
+      "title": "Save generated video with audio"
+    },
+    {
+      "id": 10,
+      "type": "MarkdownNote",
+      "pos": [
+        1360,
+        590
+      ],
+      "size": [
+        440,
+        595
+      ],
+      "flags": {},
+      "order": 9,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "Reference inputs and output settings",
+      "properties": {},
+      "widgets_values": [
+        "## Reference to Video\nSelect an image, set the server URL and served model name, then run.\n\nConnect the optional video/audio loaders to Video References, or duplicate loaders for more inputs: up to 9 images, 3 videos, 3 audio clips, 12 total. At least one image or video is required.\n\nSlots are numbered separately per media type. Empty slots are skipped. Update prompt tags such as <Picture 1>, <Video 1>, <Audio 1> to match the connected references. Videos keep their own soundtrack in the reference upload.\n\n**Output:** 24 FPS; 124 frames (~5.17 s). Valid frame counts are 107, 124, 141, 158, 175, 192, 209, 226, 243, 260, 277, 294, 311, 328, 345.\n\n**Width x height:** 1344x768 (16:9), 1024x768 (4:3), 768x768 (1:1), 768x1024 (3:4), 768x1344 (9:16).\n\nEach reference video/audio clip must be 2\u201315 s. Total reference-video duration <=15 s; total standalone-audio duration <=15 s.\n\nRequires the expanded Video References node and the audio-preserving video output fix. See the extension README for setup and validation status."
+      ],
+      "color": "#432",
+      "bgcolor": "#000"
+    },
+    {
+      "id": 11,
+      "type": "MarkdownNote",
+      "pos": [
+        790,
+        940
+      ],
+      "size": [
+        480,
+        455
+      ],
+      "flags": {},
+      "order": 10,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "title": "Optional Turbo \u2014 same workflow",
+      "properties": {},
+      "widgets_values": [
+        "## Turbo Ref2VA\nBase mode: leave LoRA disconnected; use 50 steps, video flow shift 12, audio flow shift 3.\n\nFor the 4-step v0.1 Ref2VA Turbo adapter:\n1. Start a Ref2VA-only server with the Diffusers adapter loaded (see README).\n2. Set LoRA local_path to its path on the server, then connect LoRA to Generate Video.\n3. Set Sampling num_inference_steps to **5**; keep shifts at **12 / 3**, scale **1**.\n\nvLLM-Omni counts sigma points: 5 points give 4 denoiser evaluations. Use minimax_h3_ref2v_turbo_4step_v0.1_bf16.safetensors, not the _comfyui_ export.\n\nDisconnect LoRA and restore 50 steps to return to base mode. FastH3 is a separate T2VA deployment, not this option.\n\nAdapted from the official ComfyUI MiniMax-H3 R2V workflow: https://github.com/Comfy-Org/workflow_templates/blob/main/templates/video_minimax_h3_r2v.json"
+      ],
+      "color": "#432",
+      "bgcolor": "#000"
+    }
+  ],
+  "links": [
+    [
+      1,
+      1,
+      0,
+      4,
+      0,
+      "IMAGE"
+    ],
+    [
+      2,
+      4,
+      0,
+      8,
+      1,
+      "VIDEO_REFERENCES"
+    ],
+    [
+      3,
+      5,
+      0,
+      8,
+      2,
+      "SAMPLING_PARAMS"
+    ],
+    [
+      4,
+      6,
+      0,
+      8,
+      4,
+      "VIDEO_PARAMS"
+    ],
+    [
+      5,
+      8,
+      0,
+      9,
+      0,
+      "VIDEO"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "workflowRendererVersion": "LG",
+    "ds": {
+      "scale": 0.85,
+      "offset": [
+        100,
+        100
+      ]
+    }
+  },
+  "version": 0.4
+}
diff --git a/recipes/MiniMaxAI/MiniMax-H3.md b/recipes/MiniMaxAI/MiniMax-H3.md
index c966b6b2e15..891332cdb24 100644
--- a/recipes/MiniMaxAI/MiniMax-H3.md
+++ b/recipes/MiniMaxAI/MiniMax-H3.md
@@ -1230,11 +1230,9 @@ vllm serve "${MODEL_ROOT}/FL2VA" \
   mode does not support `cache_backend`.
 - The first regional-compile request is a warmup and should not be included in
   steady-state performance measurements.
-- The serving path accepts fewer references than the model supports. H3 documents up
-  to 9 images, 3 video clips, and 3 audio clips (12 files) per Omni Reference
-  request; the current vLLM-Omni path takes exactly one image plus one audio
-  reference, or one or more videos with no separate `audio_reference` (it uses the
-  source soundtracks).
+- Ref2VA accepts up to 9 images, 3 video clips, and 3 audio clips, with at most
+  12 references in total. At least one image or video is required; audio-only
+  requests are rejected.
 - The 768 px short-edge mode is available for T2VA and FL2VA; 1344x768 is the
   documented 16:9 request shape.
 - `--cfg-parallel-size > 1` is rejected by design (CFG-distilled, no negative branch).
@@ -1247,9 +1245,6 @@ vllm serve "${MODEL_ROOT}/FL2VA" \
   in host memory on every rank during startup before retaining only each rank's
   shard. Size startup host memory for that transient peak.
 - TeaCache and Cache-DiT cannot be enabled on the same server.
-- Image+audio Ref2VA accepts exactly one image and one audio reference.
-- Video Ref2VA accepts one or more video files, but not an additional standalone
-  audio reference.
 - Pure Ulysses still replicates the full DiT on every rank, so smaller-memory GPUs
   cannot use `--usp N --tp 1` as a resident capacity path. Use DiT tensor parallelism
   or model-level CPU offload; text-encoder TP alone is not sufficient.
diff --git a/tests/e2e/features/comfyui/test_comfyui_integration.py b/tests/e2e/features/comfyui/test_comfyui_integration.py
index 0b0f998529b..fe42dd9bf9f 100644
--- a/tests/e2e/features/comfyui/test_comfyui_integration.py
+++ b/tests/e2e/features/comfyui/test_comfyui_integration.py
@@ -16,9 +16,11 @@
 import traceback
 from collections.abc import Iterable, Sequence
 from enum import Enum
+from pathlib import Path
 from types import SimpleNamespace
 from typing import Any, NamedTuple
 
+import av
 import pytest
 import requests
 import torch
@@ -82,6 +84,7 @@ class SamplingKind(str, Enum):
     VIDEO_FASTH3 = "video_fasth3"
     VIDEO_REF2VA_IMAGE_AUDIO = "video_ref2va_image_audio"
     VIDEO_REF2VA_MULTI_VIDEO = "video_ref2va_multi_video"
+    VIDEO_REF2VA_MIXED = "video_ref2va_mixed"
 
 
 # Pre-defined arguments to be used in function calls during the tests
@@ -153,6 +156,13 @@ class SamplingKind(str, Enum):
     }
 )
 
+H3_STAGE_CONFIG = {
+    "stage_type": "diffusion",
+    "final_output": True,
+    "final_output_type": "video",
+    "engine_args": {"model_class_name": "MiniMaxH3Pipeline"},
+}
+
 LORA_PARAMS = {"local_path": "test_lora_path", "name": "test_name", "scale": 0.7, "int_id": 10}
 
 
@@ -442,17 +452,30 @@ async def _mock_generate(*args, **kwargs):
                     "audio_flow_shift": 3.0,
                 },
             )
-        elif sampling_case.kind is SamplingKind.VIDEO_REF2VA_MULTI_VIDEO:
+        elif sampling_case.kind in (SamplingKind.VIDEO_REF2VA_MULTI_VIDEO, SamplingKind.VIDEO_REF2VA_MIXED):
             assert len(received_sampling_params_list) == 1
             assert isinstance(prompt, dict)
             multi_modal_data = prompt.get("multi_modal_data")
             assert isinstance(multi_modal_data, dict)
             input_videos = multi_modal_data.get("video")
             assert isinstance(input_videos, list)
-            assert len(input_videos) == 2
             assert all(isinstance(path, str) for path in input_videos)
-            assert "image" not in multi_modal_data
-            assert "audio" not in multi_modal_data
+            if sampling_case.kind is SamplingKind.VIDEO_REF2VA_MULTI_VIDEO:
+                assert len(input_videos) == 2
+                assert "image" not in multi_modal_data
+                assert "audio" not in multi_modal_data
+            else:
+                assert [Path(path).read_bytes() for path in input_videos] == [b"video-1", b"video-2", b"video-3"]
+                images = multi_modal_data.get("image")
+                assert isinstance(images, list)
+                assert len(images) == 6
+                assert [image.getpixel((0, 0)) for image in images] == [(i * 40,) * 3 for i in range(1, 7)]
+                audios = multi_modal_data.get("audio")
+                assert isinstance(audios, list)
+                assert len(audios) == 3
+                for path, sample_rate in zip(audios, (24000, 32000, 48000)):
+                    with av.open(path) as container:
+                        assert container.streams.audio[0].sample_rate == sample_rate
             _assert_sampling_param_values(
                 received_sampling_params_list[0],
                 {
@@ -970,7 +993,7 @@ async def test_fast_h3_deployment_node(api_server: str, sampling_case: SamplingC
             ServerCase(
                 served_model="MiniMaxAI/MiniMax-H3",
                 stage_list=["diffusion"],
-                stage_configs=[{"stage_type": "diffusion", "final_output": True, "final_output_type": "video"}],
+                stage_configs=[H3_STAGE_CONFIG],
                 outputs=[_build_diffusion_video_output()],
             ),
             SamplingCase(kind=SamplingKind.VIDEO_REF2VA_IMAGE_AUDIO, sampling_params=None),
@@ -981,13 +1004,24 @@ async def test_fast_h3_deployment_node(api_server: str, sampling_case: SamplingC
             ServerCase(
                 served_model="MiniMaxAI/MiniMax-H3",
                 stage_list=["diffusion"],
-                stage_configs=[{"stage_type": "diffusion", "final_output": True, "final_output_type": "video"}],
+                stage_configs=[H3_STAGE_CONFIG],
                 outputs=[_build_diffusion_video_output()],
             ),
             SamplingCase(kind=SamplingKind.VIDEO_REF2VA_MULTI_VIDEO, sampling_params=None),
             "multi_video",
             id="ref2va-multi-video",
         ),
+        pytest.param(
+            ServerCase(
+                served_model="MiniMaxAI/MiniMax-H3",
+                stage_list=["diffusion"],
+                stage_configs=[H3_STAGE_CONFIG],
+                outputs=[_build_diffusion_video_output()],
+            ),
+            SamplingCase(kind=SamplingKind.VIDEO_REF2VA_MIXED, sampling_params=None),
+            "mixed",
+            id="ref2va-mixed-12-references",
+        ),
     ],
     indirect=["server_case", "sampling_case"],
 )
@@ -1017,6 +1051,17 @@ async def test_video_generation_node_minimax_h3_ref2va(
         prompt = (
             "Remove the green screen background of Video 1 and replace it with the fairytale environment from Video 2."
         )
+    elif ref_mode == "mixed":
+        inputs = {f"image_{i}": torch.full((1, VIDEO_HEIGHT, VIDEO_WIDTH, 3), i * 40 / 255) for i in range(1, 7)}
+        inputs.update({f"video_{i}": VideoInput(f"video-{i}".encode()) for i in range(1, 4)})
+        inputs.update(
+            {
+                f"audio_{i}": {"waveform": torch.zeros(1, 1, sample_rate), "sample_rate": sample_rate}
+                for i, sample_rate in enumerate((24000, 32000, 48000), start=1)
+            }
+        )
+        (references,) = refs_node.get_references(**inputs)
+        prompt = "Combine the subjects from the images with the reference videos and audio clips."
     else:
         raise AssertionError(f"Unknown ref_mode: {ref_mode}")
 
diff --git a/tests/e2e/features/comfyui/test_h3_reference_workflow.py b/tests/e2e/features/comfyui/test_h3_reference_workflow.py
new file mode 100644
index 00000000000..852e393834d
--- /dev/null
+++ b/tests/e2e/features/comfyui/test_h3_reference_workflow.py
@@ -0,0 +1,115 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import json
+from graphlib import TopologicalSorter
+from pathlib import Path
+
+import pytest
+from comfyui_vllm_omni import nodes as omni_nodes
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+WORKFLOW = (
+    Path(__file__).resolve().parents[4]
+    / "apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni MiniMax-H3 Reference to Video.json"
+)
+
+
+@pytest.fixture
+def workflow():
+    return json.loads(WORKFLOW.read_text())
+
+
+def test_reference_workflow_connections(workflow):
+    nodes = {node["id"]: node for node in workflow["nodes"]}
+    links = {link[0]: link for link in workflow["links"]}
+    assert len(nodes) == len(workflow["nodes"])
+    assert len(links) == len(workflow["links"])
+    graph: dict[int, set[int]] = {node_id: set() for node_id in nodes}
+    for link_id, source, output_slot, target, input_slot, kind in links.values():
+        output = nodes[source]["outputs"][output_slot]
+        input_ = nodes[target]["inputs"][input_slot]
+        assert output["type"] == input_["type"] == kind
+        assert link_id in output["links"]
+        assert input_["link"] == link_id
+        graph[target].add(source)
+    assert len(tuple(TopologicalSorter(graph).static_order())) == len(nodes)
+    for node in nodes.values():
+        for slot, input_ in enumerate(node.get("inputs", [])):
+            if input_["link"] is not None:
+                assert links[input_["link"]][3:5] == [node["id"], slot]
+        for slot, output in enumerate(node.get("outputs", [])):
+            for link_id in output.get("links") or []:
+                assert links[link_id][1:3] == [node["id"], slot]
+
+
+def test_reference_workflow_matches_omni_node_interfaces(workflow):
+    for node in workflow["nodes"]:
+        if not node["type"].startswith("VLLMOmni"):
+            continue
+        cls = getattr(omni_nodes, node["type"])
+        schema = cls.INPUT_TYPES()
+        inputs = {**schema.get("required", {}), **schema.get("optional", {})}
+        for input_ in node["inputs"]:
+            assert input_["type"] == inputs[input_["name"]][0]
+        assert tuple(output["type"] for output in node["outputs"]) == cls.RETURN_TYPES
+        expected_widgets = len(schema.get("required", {}))
+        if "seed" in schema.get("required", {}):
+            expected_widgets += 1
+        assert len(node["widgets_values"]) == expected_widgets
+    refs = next(node for node in workflow["nodes"] if node["type"] == "VLLMOmniVideoReferences")
+    assert [input_["name"] for input_ in refs["inputs"]] == list(
+        omni_nodes.VLLMOmniVideoReferences.INPUT_TYPES()["optional"]
+    )
+
+
+def test_reference_workflow_default_route_and_output(workflow):
+    nodes = {node["id"]: node for node in workflow["nodes"]}
+    links = {link[0]: link for link in workflow["links"]}
+    generate = next(node for node in nodes.values() if node["type"] == "VLLMOmniGenerateVideo")
+    inputs = {input_["name"]: input_["link"] for input_ in generate["inputs"]}
+    assert inputs["frame"] is None
+    assert inputs["lora"] is None
+    for name, kind in (
+        ("references", "VLLMOmniVideoReferences"),
+        ("sampling_params", "VLLMOmniDiffusionSampling"),
+        ("model_params", "VLLMOmniMiniMaxH3Params"),
+    ):
+        assert nodes[links[inputs[name]][1]]["type"] == kind
+    save = next(node for node in nodes.values() if node["type"] == "SaveVideo")
+    assert links[save["inputs"][0]["link"]][1] == generate["id"]
+    assert save["widgets_values"] == ["video/MiniMax-H3-Ref2VA", "mp4", "h264"]
+
+
+def test_reference_workflow_defaults_and_portable_assets(workflow):
+    by_type = {node["type"]: node for node in workflow["nodes"]}
+    values = by_type["VLLMOmniGenerateVideo"]["widgets_values"]
+    assert values[0] == "http://localhost:8000/v1"
+    assert values[1] == "MiniMaxAI/MiniMax-H3"
+    assert "<Picture 1>" in values[2]
+    assert values[4:8] == [1344, 768, 24, 5.167]
+    num_frames = round(values[7] * values[6])
+    assert num_frames == 124
+    assert values[3] == ""
+    assert (num_frames - 5) % 17 == 0
+    assert 4 <= values[7] <= 15
+    assert by_type["VLLMOmniDiffusionSampling"]["widgets_values"] == [1, 50, 1.0, 1.0, False, False, 42, "fixed"]
+    assert by_type["VLLMOmniMiniMaxH3Params"]["widgets_values"] == [3.0, 12.0]
+    assert by_type["VLLMOmniRemoteLoRA"]["widgets_values"][0] == ""
+    for kind in ("LoadImage", "LoadVideo", "LoadAudio"):
+        filename = by_type[kind]["widgets_values"][0]
+        assert filename and Path(filename).name == filename
+        assert ":" not in filename and "\\" not in filename
+    assert set(by_type) == {
+        "LoadImage",
+        "LoadVideo",
+        "LoadAudio",
+        "SaveVideo",
+        "MarkdownNote",
+        "VLLMOmniVideoReferences",
+        "VLLMOmniGenerateVideo",
+        "VLLMOmniDiffusionSampling",
+        "VLLMOmniMiniMaxH3Params",
+        "VLLMOmniRemoteLoRA",
+    }
diff --git a/tests/e2e/features/comfyui/test_video_references.py b/tests/e2e/features/comfyui/test_video_references.py
new file mode 100644
index 00000000000..33e86850c83
--- /dev/null
+++ b/tests/e2e/features/comfyui/test_video_references.py
@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from io import BytesIO
+from unittest.mock import AsyncMock
+
+import av
+import pytest
+import torch
+from comfy_api.input import VideoInput
+from comfyui_vllm_omni.nodes import VLLMOmniVideoReferences
+from comfyui_vllm_omni.utils import api_client
+from PIL import Image
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+@pytest.fixture
+def api_calls(monkeypatch):
+    calls = AsyncMock(return_value={"id": "test-video", "status": "completed"})
+    monkeypatch.setattr(api_client, "url_json", calls)
+    monkeypatch.setattr(api_client, "url_bytes", AsyncMock(return_value=b"generated-video"))
+    monkeypatch.setattr(api_client, "bytes_to_video", lambda data: data)
+    return calls
+
+
+async def _generate(references, **kwargs):
+    return await api_client.VLLMOmniClient("http://localhost/v1").generate_video(
+        model="MiniMaxAI/MiniMax-H3",
+        prompt="Use the reference subjects and sounds.",
+        width=896,
+        height=512,
+        num_frames=90,
+        fps=24,
+        references=references,
+        **kwargs,
+    )
+
+
+def _references(image_count, video_count, audio_count):
+    refs = {f"image_{i}": torch.full((1, 16, 16, 3), i / 10) for i in range(1, image_count + 1)}
+    refs.update({f"video_{i}": VideoInput(f"video-{i}".encode()) for i in range(1, video_count + 1)})
+    refs.update(
+        {f"audio_{i}": {"waveform": torch.zeros(1, 1, 24000), "sample_rate": 24000} for i in range(1, audio_count + 1)}
+    )
+    return refs
+
+
+def test_reference_node_preserves_existing_ports_and_exposes_h3_limits():
+    ports = VLLMOmniVideoReferences.INPUT_TYPES()["optional"]
+    assert list(ports)[:6] == ["image_1", "image_2", "audio_1", "audio_2", "video_1", "video_2"]
+    assert {name for name, kind in ports.items() if kind == ("IMAGE",)} == {f"image_{i}" for i in range(1, 10)}
+    assert {name for name, kind in ports.items() if kind == ("VIDEO",)} == {"video_1", "video_2", "video_3"}
+    assert {name for name, kind in ports.items() if kind == ("AUDIO",)} == {"audio_1", "audio_2", "audio_3"}
+    inputs = _references(6, 3, 3)
+    (refs,) = VLLMOmniVideoReferences().get_references(**inputs)
+    assert refs.keys() == inputs.keys()
+    assert all(refs[name] is value for name, value in inputs.items())
+
+
+@pytest.mark.parametrize(
+    "counts", [(1, 0, 0), (9, 0, 0), (0, 3, 0), (1, 0, 3), (0, 1, 3), (6, 3, 3), (9, 3, 0), (9, 0, 3)]
+)
+async def test_reference_uploads_keep_numeric_order_and_media_types(api_calls, counts):
+    refs = _references(*counts)
+    result = await _generate(dict(reversed(list(refs.items()))))
+    assert result == b"generated-video"
+    fields = api_calls.call_args_list[0].kwargs["data"]._fields
+    uploads = [
+        (options["filename"], headers["Content-Type"], value)
+        for options, headers, value in fields
+        if options["name"] == "input_references"
+    ]
+    expected = [
+        (f"{kind}_{i}.{extension}", content_type)
+        for kind, count, extension, content_type in (
+            ("image", counts[0], "png", "image/png"),
+            ("video", counts[1], "mp4", "video/mp4"),
+            ("audio", counts[2], "mp3", "audio/mpeg"),
+        )
+        for i in range(1, count + 1)
+    ]
+    assert [(name, content_type) for name, content_type, _ in uploads] == expected
+    for name, content_type, payload in uploads:
+        data = payload.getvalue()
+        if content_type == "image/png":
+            index = int(name.removeprefix("image_").removesuffix(".png"))
+            assert Image.open(BytesIO(data)).getpixel((0, 0)) == (int(index / 10 * 255),) * 3
+        elif content_type == "video/mp4":
+            assert data == name.removesuffix(".mp4").replace("_", "-").encode()
+        else:
+            with av.open(BytesIO(data)) as container:
+                assert container.streams.audio[0].sample_rate == 24000
+                assert sum(frame.samples for frame in container.decode(audio=0)) > 0
+
+
+async def test_sparse_reference_slots_are_not_dropped(api_calls):
+    inputs = _references(9, 3, 3)
+    inputs = {name: inputs[name] for name in ("audio_3", "image_9", "video_3", "image_2")}
+    (refs,) = VLLMOmniVideoReferences().get_references(image_1=None, **inputs)
+    await _generate(refs)
+    fields = api_calls.call_args_list[0].kwargs["data"]._fields
+    assert [options["filename"] for options, _, _ in fields if options["name"] == "input_references"] == [
+        "image_2.png",
+        "image_9.png",
+        "video_3.mp4",
+        "audio_3.mp3",
+    ]
+
+
+@pytest.mark.parametrize(
+    "counts, message",
+    [
+        ((0, 0, 0), "at least one image or video"),
+        ((0, 0, 3), "at least one image or video"),
+        ((9, 3, 1), "at most 12"),
+        ((9, 3, 3), "at most 12"),
+    ],
+)
+async def test_invalid_reference_combinations_fail_before_upload(api_calls, counts, message):
+    with pytest.raises(ValueError, match=message):
+        await _generate(_references(*counts))
+    api_calls.assert_not_called()
+
+
+@pytest.mark.parametrize("name", ["image_10", "video_4", "audio_4", "image_0"])
+async def test_unsupported_reference_slots_are_not_silently_ignored(api_calls, name):
+    refs = _references(1, 0, 0)
+    refs[name] = object()
+    with pytest.raises(ValueError, match="Unsupported reference input"):
+        await _generate(refs)
+    api_calls.assert_not_called()
+
+
+async def test_frame_and_references_are_mutually_exclusive(api_calls):
+    with pytest.raises(ValueError, match="only one of frame or references"):
+        await _generate(_references(1, 0, 0), frame=torch.zeros(1, 16, 16, 3))
+    api_calls.assert_not_called()

From d554e6b67eb325adf93945a06fb58faf457ea282 Mon Sep 17 00:00:00 2001
From: Wu JIAZHEN <83007646+asukaqaq-s@users.noreply.github.com>
Date: Wed, 16 Sep 2026 16:52:35 +0800
Subject: [PATCH 030/105] [feat] Extend disaggregated MiniMax-H3 stage with VAE
 encoders (#6939)

Signed-off-by: asukaqaq-s <1311722138@qq.com>
Signed-off-by: Jader <yjader@foxmail.com>
Co-authored-by: Jader <yjader@foxmail.com>
Co-authored-by: Hongsheng Liu <liuhongsheng4@huawei.com>
---
 docs/design/architecture_overview.md          |   23 +-
 recipes/MiniMaxAI/MiniMax-H3-Disaggregated.md |   27 +-
 recipes/MiniMaxAI/MiniMax-H3.md               |    8 +-
 tests/config/test_config_factory.py           |   20 +-
 .../minimax_h3/test_minimax_h3_collectives.py |  157 ++
 .../minimax_h3/test_minimax_h3_contract.py    | 1427 +++++++----------
 .../test_minimax_h3_execution_modes.py        |  133 ++
 .../minimax_h3/test_minimax_h3_offload.py     |  291 ++--
 .../test_minimax_h3_quantization_quality.py   |    3 +-
 .../test_minimax_h3_step_execution.py         |   62 +-
 .../models/test_minimax_h3_encoder_payload.py |  406 +++++
 .../stage_input_processors/test_minimax_h3.py |  357 ++---
 vllm_omni/config/omni_config.py               |    1 +
 .../deploy/minimax_h3_disaggregated.yaml      |   12 +-
 .../minimax_h3_disaggregated_turbo.yaml       |   10 +
 vllm_omni/diffusion/data.py                   |    1 +
 .../models/minimax_h3/pipeline_minimax_h3.py  | 1217 ++++----------
 vllm_omni/diffusion/models/minimax_h3/vae.py  |  231 ++-
 .../models/minimax_h3/checkpoint.py           |   26 +-
 .../models/minimax_h3/conditioning.py         |  503 +++++-
 .../models/minimax_h3/encoder.py              |  252 +++
 .../models/minimax_h3/encoder_processing.py   |  569 +++++++
 .../models/minimax_h3/pipeline.py             |   12 +-
 .../models/minimax_h3/reference_video.py      |   39 +-
 .../models/minimax_h3/text_encoder.py         |    5 +-
 vllm_omni/model_executor/models/registry.py   |    6 +-
 .../stage_input_processors/minimax_h3.py      |  286 +---
 27 files changed, 3674 insertions(+), 2410 deletions(-)
 create mode 100644 tests/diffusion/models/minimax_h3/test_minimax_h3_collectives.py
 create mode 100644 tests/diffusion/models/minimax_h3/test_minimax_h3_execution_modes.py
 create mode 100644 tests/model_executor/models/test_minimax_h3_encoder_payload.py
 create mode 100644 vllm_omni/model_executor/models/minimax_h3/encoder.py
 create mode 100644 vllm_omni/model_executor/models/minimax_h3/encoder_processing.py

diff --git a/docs/design/architecture_overview.md b/docs/design/architecture_overview.md
index 58722ffa0c2..86251683124 100644
--- a/docs/design/architecture_overview.md
+++ b/docs/design/architecture_overview.md
@@ -131,13 +131,13 @@ for the validated batching, attention, and quantization combinations.
 
 ### MiniMax-H3: conditioning, denoising, and decode
 
-MiniMax-H3 illustrates logical component and phase boundaries between text
-encoding, task-specific denoising, and media decoding:
-`Text Encoder → DiT → VAE Decoder`. The current registered topology co-locates
-these components in one diffusion stage. These boundaries are useful for
-profiling and offload; independent placement would require a future
-multi-stage `PipelineConfig`. The stage mapping follows the implementation and
-serving recipe; the [release overview](https://minimaxi.com/blog/minimax-h3)
+MiniMax-H3 combines text and reference-media encoding, task-specific denoising,
+and media decoding. Standard serving co-locates these components in one diffusion
+stage. The opt-in
+[disaggregated topology](https://github.com/vllm-project/vllm-omni/blob/main/recipes/MiniMaxAI/MiniMax-H3-Disaggregated.md)
+runs Qwen and the video/audio VAE encoders in Stage 0, then sends their conditioning
+to a Stage 1 containing the DiTs and VAE decoders. The stage mapping follows the
+implementation and serving recipe; the [release overview](https://minimaxi.com/blog/minimax-h3)
 notes that a detailed technical report is forthcoming.
 
 #### Model architecture by component
@@ -149,16 +149,15 @@ notes that a detailed technical report is forthcoming.
 | **VAE Decoder** | Video VAE and audio VAE decode the generated latents and assemble the synchronized output | Decoded video frames and stereo waveform, with FPS and audio sample rate metadata |
 
 Both DiT partitions remain behind one task-selection point; `task` chooses
-which partition runs. In the current implementation, the three logical
-components execute inside one diffusion stage. This is different from
-Qwen3-Omni's three independently scheduled stages, even though both models
-produce synchronized audio and video-like outputs.
+which partition runs.
 
 #### Representative component execution
 
+The following table describes the standard single-stage deployment.
+
 | Logical component | Batching | Attention and execution | Parallelism | Quantization |
 | --- | --- | --- | --- | --- |
-| **Text Encoder** | The current co-located pipeline follows the diffusion request scheduler; independent prompt/reference batching would require a separate multi-stage topology | Qwen3-VL attention and multimodal preprocessing | `--text-encoder-tp-size N` shards the encoder across the first `N` DiT ranks; independent placement is not part of the current topology | BF16/FP32 baseline; the H3 DiT FP8 path does not quantize the text encoder |
+| **Text Encoder** | Follows the diffusion request scheduler | Qwen3-VL attention and multimodal preprocessing | `--text-encoder-tp-size N` shards the encoder across the first `N` DiT ranks | BF16/FP32 baseline; the H3 DiT FP8 path does not quantize the text encoder |
 | **DiT** | The current H3 implementation executes one generation request per diffusion batch; use concurrency for service-level throughput | cuDNN attention for the validated two-GPU consumer profile; TRTLLM attention or FlashAttention-4 on supported Blackwell profiles | TP2 plus text-encoder TP and Ulysses/VAE parallel groups on multi-GPU profiles; DLO/CPU offload trade memory for transfer time | Online FP8 applies to eligible DiT linears and is incompatible with layerwise offload |
 | **VAE Decoder** | Decode follows each generation request; tile/patch work can be distributed even when denoising is not batched | VAE decode kernels rather than DiT attention | VAE patch parallelism and native tiled decode within the diffusion stage | BF16/FP32 baseline; the documented H3 FP8 path leaves both VAEs unchanged |
 
diff --git a/recipes/MiniMaxAI/MiniMax-H3-Disaggregated.md b/recipes/MiniMaxAI/MiniMax-H3-Disaggregated.md
index 62f744ee5b1..54ea616afe5 100644
--- a/recipes/MiniMaxAI/MiniMax-H3-Disaggregated.md
+++ b/recipes/MiniMaxAI/MiniMax-H3-Disaggregated.md
@@ -1,9 +1,10 @@
-# MiniMax H3 disaggregated text encoder
+# MiniMax H3 disaggregated encoder stage
 
-This opt-in topology runs the Qwen3-VL text encoder as a vLLM stage and sends
-its hidden states and token-role metadata to an encoder-free diffusion stage.
-The standard MiniMax H3 recipes remain single-stage and continue to load the
-text encoder inside the diffusion pipeline.
+This opt-in topology runs the Qwen3-VL text encoder, video VAE encoder, and
+audio WVAE encoder together in a vLLM stage. It sends their conditioning
+payload to an encoder-free diffusion stage. The standard MiniMax H3 recipes
+remain single-stage and continue to run all components inside the diffusion
+pipeline.
 
 ## Start the server
 
@@ -23,6 +24,14 @@ deployment override for the available hardware. Diffusion quantization,
 layerwise offload, distributed layerwise offload, VAE parallelism, and USP
 settings use the same stage 1 options documented in [MiniMax-H3.md](MiniMax-H3.md).
 
+Stage 0's `tensor_parallel_size` defines one shared rank group for all three
+encoder roles; it does not choose each role's execution strategy. The required
+`hf_overrides.minimax_h3_encoder_components` mapping declares those strategies
+explicitly: `text_encoder` uses tensor parallelism, `video_vae` uses patch
+parallelism, and `audio_vae` runs on the group leader. All three role entries
+are mandatory. They share the stage's `max_num_seqs` scheduler and batch limit;
+the configuration does not create independent role schedulers or world sizes.
+
 For example, this five-GPU topology assigns one GPU to the encoder and four
 to the diffusion stage. `--stage-overrides` keeps placement and parallelism
 scoped to the owning stage rather than broadcasting an override to both:
@@ -57,8 +66,12 @@ The Stage 1 VAE patch-parallel options remain independent of offload and
 quantization. See [MiniMax-H3.md](MiniMax-H3.md) for memory requirements and
 hardware-qualified profiles before combining these options.
 
-Stage 1 sets `model_loaded.text_encoder: false`; it must not load or download
-text-encoder weights. This H3 topology explicitly keeps its single-replica
+Stage 1 sets `model_loaded.text_encoder: false` and
+`model_loaded.vae_encoder: false`. It loads only the VAE decoders and skips
+tokenizer, processor, and text-encoder downloads. It requires complete text and
+media conditioning from Stage 0, with no fallback to local encoding.
+
+This H3 topology explicitly keeps its single-replica
 diffusion stage inline, avoiding serialization of decoded video through a
 subprocess. It expects both stages to run in one deployment; cross-node payload
 transport is outside this configuration.
diff --git a/recipes/MiniMaxAI/MiniMax-H3.md b/recipes/MiniMaxAI/MiniMax-H3.md
index 891332cdb24..b48a1f47229 100644
--- a/recipes/MiniMaxAI/MiniMax-H3.md
+++ b/recipes/MiniMaxAI/MiniMax-H3.md
@@ -23,6 +23,12 @@ One vLLM-Omni diffusion stage can load both DiTs while instantiating the
 tokenizer, processor, Qwen3-VL text encoder, video VAE, and audio VAE only
 once. Requests select the DiT with `extra_params.task`.
 
+This single-stage recipe uses the default `model_loaded.text_encoder: true` and
+`model_loaded.vae_encoder: true`. Precomputed text conditioning can replace the
+local Qwen call. Setting `model_loaded.text_encoder: false` while leaving
+`model_loaded.vae_encoder: true` requires precomputed text conditioning;
+reference media is still encoded locally.
+
 The generated MP4 contains H.264 video and synchronized stereo audio.
 
 ## Prerequisites
@@ -35,7 +41,7 @@ hf auth login
 export MODEL=MiniMaxAI/MiniMax-H3
 ```
 
-The vLLM-Omni pipeline downloads `FL2VA/**`, `Ref2VA/model_index.json`, and
+By default, the pipeline downloads `FL2VA/**`, `Ref2VA/model_index.json`, and
 `Ref2VA/transformer/**`. It does not download or load the diffusers-format
 `transformer`, `transformer_ref`, or `vae` weights at the repository root, nor
 duplicate Ref2VA copies of shared components.
diff --git a/tests/config/test_config_factory.py b/tests/config/test_config_factory.py
index 3699eeda726..c81a4b3b7a9 100644
--- a/tests/config/test_config_factory.py
+++ b/tests/config/test_config_factory.py
@@ -1562,7 +1562,10 @@ def test_minimax_h3_resolvers_reach_production_engine_args(self, tmp_path: Path,
         monkeypatch.setattr(stage_init_utils, "resolve_worker_cls", lambda _engine_args: None)
 
         deploy = load_deploy_config(get_deploy_config_path("minimax_h3_disaggregated.yaml"))
-        assert deploy.stages[1].engine_extras["model_loaded"] == {"text_encoder": False}
+        assert deploy.stages[1].engine_extras["model_loaded"] == {
+            "text_encoder": False,
+            "vae_encoder": False,
+        }
         stages = merge_pipeline_deploy(OMNI_PIPELINES["minimax_h3_disaggregated"], deploy)
         resolved = [stage_init_utils.build_engine_args_dict(stage.to_omegaconf(), str(model_root)) for stage in stages]
 
@@ -1587,12 +1590,20 @@ def test_minimax_h3_disaggregated_defaults_match_validated_topology(self):
         deploy = load_deploy_config(Path(get_deploy_config_path("minimax_h3_disaggregated.yaml")))
         stages = merge_pipeline_deploy(pipeline, deploy)
 
-        assert stages[0].yaml_engine_args["model_arch"] == "MiniMaxH3TextEncoder"
+        assert stages[0].yaml_engine_args["model_arch"] == "MiniMaxH3Encoder"
         assert stages[1].yaml_engine_args["model_arch"] == "MiniMaxH3Pipeline"
         assert stages[0].yaml_runtime["num_replicas"] == 1
         assert stages[1].yaml_runtime["num_replicas"] == 1
-        assert stages[1].yaml_engine_args["model_loaded"] == {"text_encoder": False}
+        assert stages[1].yaml_engine_args["model_loaded"] == {
+            "text_encoder": False,
+            "vae_encoder": False,
+        }
         assert stages[0].yaml_engine_args["max_num_seqs"] == 1
+        assert stages[0].yaml_engine_args["hf_overrides"]["minimax_h3_encoder_components"] == {
+            "text_encoder": {"parallel_mode": "tp"},
+            "video_vae": {"parallel_mode": "patch"},
+            "audio_vae": {"parallel_mode": "leader"},
+        }
         assert stages[0].yaml_engine_args["model_path_resolver"].endswith(".resolve_minimax_h3_model_root")
         assert stages[1].yaml_engine_args["model_path_resolver"].endswith(".resolve_minimax_h3_diffusion_model_path")
         parallel = stages[1].yaml_engine_args["parallel_config"]
@@ -1604,6 +1615,9 @@ def test_minimax_h3_disaggregated_defaults_match_validated_topology(self):
 
         turbo = load_deploy_config(Path(get_deploy_config_path("minimax_h3_disaggregated_turbo.yaml")))
         turbo_stages = merge_pipeline_deploy(pipeline, turbo)
+        assert turbo_stages[0].yaml_engine_args["model_arch"] == stages[0].yaml_engine_args["model_arch"]
+        assert turbo_stages[1].yaml_engine_args["model_loaded"] == stages[1].yaml_engine_args["model_loaded"]
+        assert turbo_stages[0].yaml_engine_args["hf_overrides"] == stages[0].yaml_engine_args["hf_overrides"]
         turbo_sampling = turbo_stages[1].yaml_extras["default_sampling_params"]
         assert turbo_sampling["num_inference_steps"] == 5
         assert turbo_sampling["extra_args"] == {"flow_shift": 6.0, "audio_flow_shift": 3.0}
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_collectives.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_collectives.py
new file mode 100644
index 00000000000..9d44bf44517
--- /dev/null
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_collectives.py
@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import os
+import time
+from datetime import timedelta
+from types import SimpleNamespace
+
+import pytest
+import torch
+import torch.distributed as dist
+import torch.multiprocessing as mp
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion]
+
+
+def _collective_worker(rank, rendezvous, backend):
+    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as module
+    from vllm_omni.errors import OmniClientError
+    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+    from vllm_omni.model_executor.models.minimax_h3.conditioning import MiniMaxH3EncoderMediaInput
+    from vllm_omni.platforms import current_omni_platform
+
+    torch.set_num_threads(1)
+    device = torch.device("cuda", rank) if backend == "nccl" else torch.device("cpu")
+    if backend == "nccl":
+        current_omni_platform.set_device(device)
+    dist.init_process_group(
+        backend, init_method=f"file://{rendezvous}", rank=rank, world_size=2, timeout=timedelta(seconds=45)
+    )
+    try:
+        module._dit_rank_world = lambda: (dist.group.WORLD, rank, 2)
+
+        class VisualCodec:
+            fail = False
+
+            def is_distributed_enabled(self):
+                return True
+
+            def collective(self):
+                value = torch.ones(1, device=device)
+                dist.all_reduce(value)
+                assert value.item() == 2
+
+            def encode_image(self, image):
+                self.collective()
+                assert image.size == (32, 32)
+                return torch.ones(1, 96)
+
+            def encode_video(self, frames):
+                self.collective()
+                assert frames.shape == (4, 32, 32, 3)
+                if self.fail and rank == 1:
+                    raise ValueError("codec failed on rank 1")
+                return torch.full((1, 96), 2.0), (1, 2, 2)
+
+        class AudioCodec:
+            def encode_waveform(self, waveform, sample_rate):
+                assert rank == 0
+                assert sample_rate == 32000
+                assert waveform.shape == (64000,)
+                return torch.full((160, 32), 3.0), 80
+
+        model = object.__new__(module.MiniMaxH3Pipeline)
+        torch.nn.Module.__init__(model)
+        model.device = device
+        model.od_config = SimpleNamespace(enable_layerwise_offload=False)
+        model.video_vae = VisualCodec()
+        model.audio_vae = AudioCodec()
+        model.partition = "combined"
+        model.supported_tasks = frozenset({"t2va", "fl2va", "ref2va"})
+        model.text_encoder_tp_size = 2
+        model.text_encoder_group = SimpleNamespace(
+            world_size=2, ranks=[0, 1], rank_in_group=rank, device_group=dist.group.WORLD
+        )
+        model.processor = SimpleNamespace(image_processor=SimpleNamespace(merge_size=2))
+        model.tokenizer = lambda text, **kwargs: {"input_ids": [1, 2, 3]}
+
+        def encode_text(ids, kwargs):
+            assert ids.tolist() == [1, 2, 3]
+            assert not kwargs
+            hidden = torch.ones(3, 5120, device=device, dtype=torch.bfloat16)
+            dist.all_reduce(hidden)
+            return hidden
+
+        model._encode_text_hidden = encode_text
+        sampling = OmniDiffusionSamplingParams(
+            height=32, width=32, num_frames=96, extra_args={"task": "t2va", "aspect_ratio": "1:1"}
+        )
+        text_conditioning = model._prepare_local_conditioning({"prompt": "test"}, sampling)
+        torch.testing.assert_close(text_conditioning.hidden_states, torch.full_like(text_conditioning.hidden_states, 2))
+        assert text_conditioning.visual_condition is None
+
+        media = (
+            MiniMaxH3EncoderMediaInput(
+                task="ref2va",
+                height=32,
+                width=32,
+                num_frames=107,
+                latent_t=32,
+                audio_t=178,
+                images=(torch.zeros(32, 32, 3, dtype=torch.uint8),),
+                videos=(torch.zeros(4, 32, 32, 3, dtype=torch.uint8),),
+                video_audios=(None,),
+                audios=((torch.zeros(64000), 32000),),
+            )
+            if rank == 0
+            else None
+        )
+        conditioning = model._encode_local_media(media)
+        assert [block["kind"] for block in conditioning.ref_blocks] == ["image", "video", "audio"]
+        torch.testing.assert_close(
+            conditioning.visual_condition.cpu(), torch.cat([torch.ones(1, 96), torch.full((1, 96), 2.0)])
+        )
+        torch.testing.assert_close(conditioning.audio_condition.cpu(), torch.full((160, 32), 3.0))
+        assert conditioning.audio_condition_lengths == (80,)
+
+        model.video_vae.fail = True
+        with pytest.raises(OmniClientError, match="codec failed on rank 1"):
+            model._encode_local_media(media)
+        with pytest.raises(OmniClientError, match="non-empty prompt"):
+            model._prepare_local_conditioning({"prompt": ""}, sampling)
+        model.video_vae.fail = False
+        assert model._encode_local_media(media).visual_condition_shapes == ((1, 2, 2), (1, 2, 2))
+    finally:
+        dist.destroy_process_group()
+
+
+def _run_collectives(tmp_path, backend):
+    context = mp.spawn(_collective_worker, args=(str(tmp_path / "rendezvous"), backend), nprocs=2, join=False)
+    deadline = time.monotonic() + 150
+    try:
+        while not context.join(timeout=1):
+            if time.monotonic() > deadline:
+                pytest.fail("MiniMax H3 collectives did not finish within 150 seconds")
+    finally:
+        for process in context.processes:
+            if process.is_alive():
+                process.terminate()
+            process.join(timeout=5)
+
+
+@pytest.mark.cpu
+def test_two_rank_conditioning_and_errors_gloo(tmp_path):
+    _run_collectives(tmp_path, "gloo")
+
+
+@pytest.mark.cuda
+@pytest.mark.parallel
+@pytest.mark.skipif(
+    os.environ.get("VLLM_TEST_MINIMAX_H3_COLLECTIVES") != "1",
+    reason="set VLLM_TEST_MINIMAX_H3_COLLECTIVES=1 with two reserved GPUs",
+)
+def test_two_rank_conditioning_and_errors_nccl(tmp_path):
+    if torch.accelerator.device_count() < 2:
+        pytest.skip("requires two GPUs")
+    _run_collectives(tmp_path, "nccl")
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
index 67498abc5ca..4b6fc0d8820 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
@@ -27,174 +27,34 @@ def _append_and_return(items: list[_ItemT], item: _ItemT, result: _ResultT) -> _
     return result
 
 
-def _turbo_spec(filename: str) -> TurboSpec:
-    """Build the spec a loaded artifact of this name would carry."""
-    spec = parse_turbo_filename(filename)
-    assert spec is not None
-    return spec
-
-
-def test_decode_to_mp4_batches_consumer_transfers(monkeypatch):
-    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
-
-    class FakeEncoder:
-        instances = []
-
-        def __init__(self, **kwargs):
-            self.pushes = []
-            self.kwargs = kwargs
-            self.__class__.instances.append(self)
-
-        def push(self, frames):
-            self.pushes.append(np.array(frames, copy=True))
-
-        def finish(self):
-            return b"mp4"
-
-        def abort(self):
-            raise AssertionError("unexpected abort")
-
-    class FakeAudioVAE:
-        def decode_latent(self, latent):
-            return torch.zeros(1, 1, 2)
-
-    class FakeVideoVAE:
-        def decode_with_chunks(self, latent, *, on_chunk):
-            for value in (0.0, 0.25, 0.5):
-                on_chunk(torch.full((1, 3, 3, 2, 2), value))
-
-    pipeline = object.__new__(mod.MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.audio_vae = FakeAudioVAE()
-    pipeline.video_vae = FakeVideoVAE()
-    pipeline.device = torch.device("cpu")
-    monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_uses_manual_component_offload", lambda self, component: False)
-    monkeypatch.setattr(
-        "vllm_omni.diffusion.utils.media_utils.ChunkedMP4Encoder",
-        FakeEncoder,
-    )
-
-    output = pipeline.decode_to_mp4(
-        torch.zeros(1),
-        torch.zeros(1),
-        height=2,
-        width=2,
-        batch_frames=4,
-    )
-
-    assert output == b"mp4"
-    encoder = FakeEncoder.instances[-1]
-    assert [frames.shape[0] for frames in encoder.pushes] == [6, 3]
-    assert np.array_equal(encoder.pushes[0][0], np.full((2, 2, 3), 0, dtype=np.uint8))
-    assert np.array_equal(encoder.pushes[0][3], np.full((2, 2, 3), 64, dtype=np.uint8))
-    assert encoder.pushes[1].shape == (3, 2, 2, 3)
-
-
-def test_request_video_codec_options_reach_the_preencoded_mp4_encoder(monkeypatch):
-    """A client's encoder options must survive the worker-side pre-encode path."""
-    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
-
-    class FakeEncoder:
-        instances = []
-
-        def __init__(self, **kwargs):
-            self.kwargs = kwargs
-            self.__class__.instances.append(self)
-
-        def push(self, frames):
-            del frames
-
-        def finish(self):
-            return b"mp4"
-
-        def abort(self):
-            raise AssertionError("unexpected abort")
-
-    class FakeAudioVAE:
-        def decode_latent(self, latent):
-            return torch.zeros(1, 1, 2)
-
-    class FakeVideoVAE:
-        def decode_with_chunks(self, latent, *, on_chunk):
-            on_chunk(torch.zeros(1, 3, 1, 2, 2))
-
-    pipeline = object.__new__(mod.MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.audio_vae = FakeAudioVAE()
-    pipeline.video_vae = FakeVideoVAE()
-    pipeline.device = torch.device("cpu")
-    monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_uses_manual_component_offload", lambda self, component: False)
-    monkeypatch.setattr("vllm_omni.diffusion.utils.media_utils.ChunkedMP4Encoder", FakeEncoder)
-
-    pipeline.decode_to_mp4(
-        torch.zeros(1),
-        torch.zeros(1),
-        height=2,
-        width=2,
-        video_codec_options={"preset": "ultrafast"},
-    )
-
-    assert FakeEncoder.instances[-1].kwargs["video_codec_options"] == {"preset": "ultrafast"}
-
-
-@pytest.mark.parametrize(
-    ("codec_extra", "expected"),
-    [
-        ({}, {"preset": "ultrafast", "threads": "0"}),
-        ({"video_codec_options": {"preset": "slow", "threads": 2}}, {"preset": "slow", "threads": "2"}),
-        ({"video_codec_options": {}}, {}),
-        ({"video_codec_options": None}, None),
-    ],
-)
-@pytest.mark.parametrize("batch_extra, batch_frames", [({}, 17), ({"preencode_batch_frames": 5}, 5)])
-def test_preencode_request_preserves_serving_codec_defaults(codec_extra, expected, batch_extra, batch_frames):
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-    from vllm_omni.diffusion.request import OmniDiffusionRequest
-    from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch
-    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.partition = "fl2va"
-    pipeline.supported_tasks = frozenset({"t2va"})
-    pipeline.default_video_shift = 12.0
-    pipeline.default_audio_shift = 3.0
-    pipeline.device = torch.device("cpu")
-    pipeline.od_config = SimpleNamespace()
-    pipeline.text_encoder = object()
-    pipeline.encode_prompt = Mock(return_value=(torch.ones(1, 2), torch.ones(1, dtype=torch.long)))
-    pipeline._quality_policy = Mock()
-    pipeline._cache_dit_runtime = Mock()
-    pipeline.diffuse = Mock(return_value=(torch.zeros(1), torch.zeros(1)))
-    pipeline.decode_to_mp4 = Mock(return_value=b"mp4")
-    sampling = OmniDiffusionSamplingParams(
-        width=1344,
-        height=768,
-        fps=24,
-        num_frames=124,
-        num_inference_steps=50,
-        extra_args={"task": "t2va", "aspect_ratio": "16:9", "preencode_mp4": True, **codec_extra, **batch_extra},
-    )
-    batch = DiffusionRequestBatch(
-        [OmniDiffusionRequest(prompt="test", sampling_params=sampling, request_id="codec-defaults")]
-    )
-
-    pipeline.forward(batch)
-
-    assert pipeline.decode_to_mp4.call_args.kwargs["video_codec_options"] == expected
-    assert pipeline.decode_to_mp4.call_args.kwargs["batch_frames"] == batch_frames
-
-
-def test_video_codec_options_are_normalized_for_the_encoder():
-    from vllm_omni.diffusion.utils.media_utils import normalize_video_codec_options
-
-    assert normalize_video_codec_options({"preset": "ultrafast", "threads": 0}) == {
-        "preset": "ultrafast",
-        "threads": "0",
+def _encoder_payload(
+    *,
+    task: str = "t2va",
+    height: int = 768,
+    width: int = 1344,
+    num_frames: int = 124,
+) -> dict[str, Any]:
+    from vllm_omni.diffusion.models.minimax_h3.time_request import MINIMAX_H3_SHAPE_PLANNER
+    from vllm_omni.model_executor.models.minimax_h3.conditioning import MiniMaxH3EncoderConditioning
+
+    conditioning = MiniMaxH3EncoderConditioning(
+        hidden_states=torch.ones(1, 5120, dtype=torch.bfloat16),
+        token_tags=torch.ones(1, dtype=torch.int64),
+        task=task,
+        height=height,
+        width=width,
+        num_frames=num_frames,
+        latent_t=MINIMAX_H3_SHAPE_PLANNER.video_latent_t(num_frames),
+        audio_t=MINIMAX_H3_SHAPE_PLANNER.audio_latent_t(num_frames / 24),
+    )
+    return conditioning.to_omni_payload()
+
+
+def _encoder_prompt(text: str = "test") -> dict[str, Any]:
+    return {
+        "prompt": text,
+        "additional_information": {"encoder_output": _encoder_payload()},
     }
-    assert normalize_video_codec_options(None) is None
-    with pytest.raises(ValueError, match="video_codec_options"):
-        normalize_video_codec_options("preset=ultrafast")
 
 
 def test_h3_prepares_resolved_cache_state_immediately_before_denoise():
@@ -205,25 +65,22 @@ def test_h3_prepares_resolved_cache_state_immediately_before_denoise():
 
     pipeline = object.__new__(MiniMaxH3Pipeline)
     torch.nn.Module.__init__(pipeline)
+    pipeline.load_text_encoder = False
+    pipeline.load_vae_encoder = False
     pipeline.partition = "fl2va"
     pipeline.supported_tasks = frozenset({"t2va"})
     pipeline.default_video_shift = 12.0
     pipeline.default_audio_shift = 3.0
     pipeline.device = torch.device("cpu")
     pipeline.od_config = SimpleNamespace()
-    pipeline.text_encoder = object()
+    pipeline.load_text_encoder = False
+    pipeline.load_vae_encoder = False
     cache_spec = object()
     quality_plan = SimpleNamespace(cache_dit=cache_spec)
     pipeline._quality_policy = Mock()
     pipeline._quality_policy.resolve.return_value = quality_plan
     events = []
     pipeline._cache_dit_runtime = SimpleNamespace(prepare=lambda spec: events.append(("prepare", spec)))
-    pipeline.encode_prompt = Mock(
-        return_value=(
-            torch.ones(1, 2),
-            torch.ones(1, dtype=torch.long),
-        )
-    )
 
     def diffuse(**kwargs):
         events.append(("diffuse", kwargs))
@@ -244,7 +101,7 @@ def diffuse(**kwargs):
     batch = DiffusionRequestBatch(
         [
             OmniDiffusionRequest(
-                prompt="quality boundary",
+                prompt=_encoder_prompt("quality boundary"),
                 sampling_params=sampling,
                 request_id="quality-boundary",
             )
@@ -287,7 +144,7 @@ def test_pipeline_import_registry_and_component_discovery():
     assert MiniMaxH3Pipeline._vae_modules == ["video_vae", "audio_vae"]
 
 
-def test_encoder_free_stage_skips_text_encoder_during_dlo_discovery():
+def test_diffusion_stage_has_only_dit_and_decoder_vaes_during_discovery():
     from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
     from vllm_omni.diffusion.offloader.module_collector import ModuleDiscovery
 
@@ -296,7 +153,6 @@ def test_encoder_free_stage_skips_text_encoder_during_dlo_discovery():
     pipeline.transformer = torch.nn.Linear(1, 1)
     pipeline.video_vae = torch.nn.Linear(1, 1)
     pipeline.audio_vae = torch.nn.Linear(1, 1)
-    pipeline.text_encoder = None
     pipeline._dit_modules = ["transformer"]
     pipeline._encoder_modules = []
     pipeline._vae_modules = ["video_vae", "audio_vae"]
@@ -308,6 +164,14 @@ def test_encoder_free_stage_skips_text_encoder_during_dlo_discovery():
     assert discovered.vae_names == ["video_vae", "audio_vae"]
 
 
+def test_diffusion_stage_requires_the_encoder_payload():
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+    from vllm_omni.errors import OmniClientError
+
+    with pytest.raises(OmniClientError, match="requires encoder conditioning"):
+        MiniMaxH3Pipeline._extract_encoder_conditioning(None)
+
+
 def test_encoder_free_stage_skips_missing_component_during_dlo_registration():
     from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as pipeline_module
 
@@ -339,10 +203,11 @@ def _write_partition_index(path, *, partition, tasks):
     )
 
 
+@pytest.mark.skip(reason="upstream utility was removed from this branch")
 def test_modular_diffusers_index_is_resolved_generically(tmp_path):
-    from vllm_omni.config.resolver import resolve_omni_config
     from vllm_omni.diffusion.data import OmniDiffusionConfig, resolve_model_class_name
     from vllm_omni.diffusion.utils.hf_utils import is_diffusion_model
+    from vllm_omni.entrypoints.utils import resolve_model_config_path
 
     (tmp_path / "modular_model_index.json").write_text(
         json.dumps(
@@ -356,16 +221,7 @@ def test_modular_diffusers_index_is_resolved_generically(tmp_path):
 
     assert is_diffusion_model(str(tmp_path))
     assert resolve_model_class_name(str(tmp_path)) == "MiniMaxH3ModularPipeline"
-    resolved = resolve_omni_config(
-        str(tmp_path),
-        trust_remote_code=False,
-        deploy_config_path=None,
-        cli_overrides=None,
-        stage_overrides=None,
-        strategy_config_path=None,
-    )
-    assert resolved.config_path is None
-    assert resolved.stage_by_id(0).engine_args.model_class_name == "MiniMaxH3ModularPipeline"
+    assert resolve_model_config_path(str(tmp_path)) is None
 
     config = OmniDiffusionConfig(model=str(tmp_path))
     config.enrich_config()
@@ -412,7 +268,7 @@ def test_startup_task_rejects_unsupported_value():
         _minimax_h3_partition_for_task("unsupported")
 
 
-def test_combined_task_inference_and_transformer_routing():
+def test_encoder_task_validation_and_transformer_routing():
     from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
     from vllm_omni.errors import OmniClientError
 
@@ -434,7 +290,7 @@ def test_combined_task_inference_and_transformer_routing():
     assert pipeline._resolve_task("ref2va", {"image": object()}, turbo_spec=ref2v_spec) == "ref2va"
     pipeline.partition = "ref2va"
     pipeline.supported_tasks = frozenset({"ref2va"})
-    assert pipeline._resolve_task(None, {"image": object()}) == "ref2va"
+    assert pipeline._resolve_task("ref2va") == "ref2va"
 
     pipeline.partition = "combined"
     pipeline.supported_tasks = frozenset({"t2va", "fl2va", "ref2va"})
@@ -450,15 +306,14 @@ def test_combined_task_inference_and_transformer_routing():
         "component_partition",
         "source_partitions",
         "expected_tasks",
-        "load_text_encoder",
     ),
     [
-        (None, "combined", 2, "FL2VA", ["FL2VA", "Ref2VA"], {"t2va", "fl2va", "ref2va"}, True),
-        ("fl2va", "fl2va", 1, "FL2VA", ["FL2VA"], {"t2va", "fl2va"}, True),
-        ("ref2va", "ref2va", 1, "Ref2VA", ["Ref2VA"], {"ref2va"}, True),
-        ("fl2va", "fl2va", 1, "FL2VA", ["FL2VA"], {"t2va", "fl2va"}, False),
+        (None, "combined", 2, "FL2VA", ["FL2VA", "Ref2VA"], {"t2va", "fl2va", "ref2va"}),
+        ("fl2va", "fl2va", 1, "FL2VA", ["FL2VA"], {"t2va", "fl2va"}),
+        ("ref2va", "ref2va", 1, "Ref2VA", ["Ref2VA"], {"ref2va"}),
     ],
 )
+@pytest.mark.parametrize("load_text_encoder", [None, True, False])
 @pytest.mark.parametrize("trust_remote_code", [False, True])
 def test_pipeline_loads_task_selected_components_with_encoder_ownership(
     monkeypatch,
@@ -493,16 +348,13 @@ def test_pipeline_loads_task_selected_components_with_encoder_ownership(
     for partition_name in ("FL2VA", "Ref2VA"):
         for component in (
             "transformer",
-            "tokenizer",
-            "processor",
-            "text_encoder",
             "video_vae",
             "audio_vae",
         ):
             (tmp_path / partition_name / component).mkdir()
 
-    created: dict[str, list[Any]] = {"dit": [], "text_encoder": [], "video_vae": [], "audio_vae": []}
-    created_kwargs: dict[str, list[Any]] = {"text_encoder": [], "video_vae": [], "audio_vae": []}
+    created: dict[str, list[Any]] = {"dit": [], "video_vae": [], "audio_vae": [], "text_encoder": []}
+    component_options = {}
 
     class FakeModule(torch.nn.Module):
         def __init__(self, *args, **kwargs):
@@ -516,27 +368,17 @@ def __init__(self, *args, **kwargs):
     def component_factory(name):
         def create(path, *args, **kwargs):
             created[name].append(str(path))
-            created_kwargs[name].append(kwargs)
+            component_options[name] = kwargs
             return FakeModule()
 
         return create
 
-    tokenizer_calls: list[Any] = []
-    processor_calls: list[Any] = []
-    tokenizer_cls = Mock(spec=pipeline_module.Qwen2TokenizerFast)
-    tokenizer_cls.from_pretrained.side_effect = lambda *args, **kwargs: _append_and_return(
-        tokenizer_calls, (args, kwargs), object()
-    )
-    processor_cls = Mock(spec=pipeline_module.Qwen3VLProcessor)
-    processor_cls.from_pretrained.side_effect = lambda *args, **kwargs: _append_and_return(
-        processor_calls, (args, kwargs), object()
-    )
     monkeypatch.setattr(pipeline_module, "MiniMaxH3DiTModel", FakeDiT)
-    monkeypatch.setattr(
-        pipeline_module,
-        "MiniMaxH3Qwen3VLEncoder",
-        component_factory("text_encoder"),
-    )
+    monkeypatch.setattr(pipeline_module, "MiniMaxH3Qwen3VLEncoder", component_factory("text_encoder"))
+    tokenizer_loader = Mock()
+    processor_loader = Mock()
+    monkeypatch.setattr(pipeline_module.Qwen2TokenizerFast, "from_pretrained", tokenizer_loader)
+    monkeypatch.setattr(pipeline_module.Qwen3VLProcessor, "from_pretrained", processor_loader)
     monkeypatch.setattr(
         pipeline_module,
         "MiniMaxH3VideoVAE",
@@ -547,21 +389,6 @@ def create(path, *args, **kwargs):
         "MiniMaxH3AudioVAE",
         component_factory("audio_vae"),
     )
-    monkeypatch.setattr(
-        pipeline_module,
-        "Qwen2TokenizerFast",
-        tokenizer_cls,
-    )
-    monkeypatch.setattr(
-        pipeline_module,
-        "Qwen3VLProcessor",
-        processor_cls,
-    )
-    monkeypatch.setattr(
-        pipeline_module,
-        "_dit_rank_world",
-        lambda: (None, 0, 1),
-    )
     monkeypatch.setattr(
         pipeline_module,
         "get_local_device",
@@ -581,21 +408,17 @@ def fake_download(**kwargs):
 
     od_config = OmniDiffusionConfig(
         model="MiniMaxAI/MiniMax-H3",
+        trust_remote_code=trust_remote_code,
         revision=None,
         task_type=task_type,
         quantization_config=None,
-        model_loaded={
-            "transformer": True,
-            "vae": True,
-            "text_encoder": load_text_encoder,
-        },
-        parallel_config=DiffusionParallelConfig(
-            cfg_parallel_size=1,
-            text_encoder_tp_size=1,
-        ),
-        trust_remote_code=trust_remote_code,
+        parallel_config=DiffusionParallelConfig(cfg_parallel_size=1),
     )
+    if load_text_encoder is not None:
+        od_config.model_loaded["text_encoder"] = load_text_encoder
+        od_config.model_loaded["vae_encoder"] = load_text_encoder
     pipeline = pipeline_module.MiniMaxH3Pipeline(od_config=od_config)
+    expect_encoder = load_text_encoder is not False
 
     assert pipeline.partition == expected_partition
     assert pipeline.supported_tasks == expected_tasks
@@ -603,59 +426,47 @@ def fake_download(**kwargs):
     component_path = tmp_path / component_partition
     assert created["video_vae"] == [str(component_path / "video_vae")]
     assert created["audio_vae"] == [str(component_path / "audio_vae")]
-    # The checkpoint VAEs execute the modeling code shipped with the weights, so
-    # the pipeline must hand them the engine's trust_remote_code decision. Both
-    # VAEs are created for every parametrization, so this stays unconditional.
-    for component in ("video_vae", "audio_vae"):
-        assert [kwargs["trust_remote_code"] for kwargs in created_kwargs[component]] == [trust_remote_code]
-    # The tokenizer/processor "loaded once" assertions are asserted per
-    # load_text_encoder branch below, matching upstream's own expectations.
+    assert created["text_encoder"] == ([str(component_path / "text_encoder")] if expect_encoder else [])
+    assert tokenizer_loader.call_count == processor_loader.call_count == int(expect_encoder)
+    assert pipeline.load_text_encoder is expect_encoder
+    assert pipeline._encoder_modules == (["text_encoder"] if expect_encoder else [])
+    assert ("text_encoder" in pipeline._offload_plan.encoder_block_attrs) is expect_encoder
+    assert ("text_encoder" in pipeline._offload_plan.on_demand_component_paths) is expect_encoder
+    assert ("encode_prompt" in pipeline._PROFILER_TARGETS) is expect_encoder
+    assert ("_encode_local_media" in pipeline._PROFILER_TARGETS) is expect_encoder
+    assert component_options["video_vae"]["decode_only"] is not expect_encoder
+    assert component_options["audio_vae"]["decode_only"] is not expect_encoder
+    assert component_options["video_vae"]["trust_remote_code"] is trust_remote_code
+    assert component_options["audio_vae"]["trust_remote_code"] is trust_remote_code
+    from vllm_omni.diffusion.offloader.module_collector import ModuleDiscovery
+
+    assert ModuleDiscovery.discover(pipeline).encoder_names == (["text_encoder"] if expect_encoder else [])
     expected_dit_modules = ["transformer", "transformers_ref"] if expected_dits == 2 else ["transformer"]
     assert pipeline._dit_modules == expected_dit_modules
     assert hasattr(pipeline, "transformers_ref") is (expected_dits == 2)
-    if load_text_encoder:
-        assert created["text_encoder"] == [str(component_path / "text_encoder")]
-        assert len(tokenizer_calls) == 1
-        assert len(processor_calls) == 1
-        assert pipeline.text_encoder is not None
-        assert pipeline.tokenizer is not None
-        assert pipeline.processor is not None
-        assert pipeline._encoder_modules == ["text_encoder"]
-        assert pipeline.text_encoder_tp_size == 1
-    else:
-        assert created["text_encoder"] == []
-        assert tokenizer_calls == []
-        assert processor_calls == []
-        assert pipeline.text_encoder is None
-        assert pipeline.tokenizer is None
-        assert pipeline.processor is None
-        assert pipeline._encoder_modules == []
-        assert pipeline.text_encoder_tp_size == 0
-        assert pipeline.text_encoder_group is None
     if expected_partition == "ref2va":
         assert pipeline._transformer_for_task("ref2va") is pipeline.transformer
     assert [source.model_or_path for source in pipeline.weights_sources] == [
         *(str(tmp_path / partition_name) for partition_name in source_partitions),
-        *((str(component_path),) if load_text_encoder else ()),
+        *([str(component_path)] if expect_encoder else []),
     ]
     assert [source.subfolder for source in pipeline.weights_sources] == [
         *("transformer" for _ in source_partitions),
-        *(("text_encoder",) if load_text_encoder else ()),
+        *(["text_encoder"] if expect_encoder else []),
     ]
     expected_prefixes = ["transformer."]
     if expected_dits == 2:
         expected_prefixes.append("transformers_ref.")
-    if load_text_encoder:
+    if expect_encoder:
         expected_prefixes.append("text_encoder.")
     assert [source.prefix for source in pipeline.weights_sources] == expected_prefixes
-    if load_text_encoder:
+    expected_patterns = pipeline_module.MINIMAX_H3_DIFFUSION_DOWNLOAD_PATTERNS[expected_partition]
+    if expect_encoder:
         expected_patterns = (
             pipeline_module.MINIMAX_H3_DOWNLOAD_PATTERNS
             if expected_partition == "combined"
             else pipeline_module.MINIMAX_H3_TASK_DOWNLOAD_PATTERNS[expected_partition]
         )
-    else:
-        expected_patterns = pipeline_module.MINIMAX_H3_DIFFUSION_DOWNLOAD_PATTERNS[expected_partition]
     assert download_calls == [
         {
             "model_name_or_path": "MiniMaxAI/MiniMax-H3",
@@ -687,7 +498,6 @@ def post_load_weights(self):
     torch.nn.Module.__init__(pipeline)
     pipeline.transformer = FakeTransformer()
     pipeline.transformers_ref = FakeTransformer()
-    pipeline.text_encoder = torch.nn.Identity()
     pipeline.video_vae = torch.nn.Identity()
     pipeline.audio_vae = torch.nn.Identity()
     loaded = pipeline.load_weights(
@@ -740,26 +550,6 @@ def test_joint_postprocess_is_multiprocessing_picklable():
     assert result["fps"] == 24
 
 
-def test_joint_video_output_is_quantized_before_transfer():
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _minimax_h3_post_process,
-        _prepare_minimax_h3_video_output,
-    )
-
-    video = torch.linspace(-0.1, 1.1, 2 * 3 * 2 * 4 * 5, dtype=torch.float64).reshape(2, 3, 2, 4, 5)
-    expected = torch.round(video.float().clamp(0, 1) * 255).to(torch.uint8).permute(0, 2, 3, 4, 1)
-    prepared = _prepare_minimax_h3_video_output(video)
-
-    assert prepared.dtype == torch.uint8
-    assert prepared.is_contiguous()
-    assert prepared.shape == (2, 2, 4, 5, 3)
-    torch.testing.assert_close(prepared, expected, rtol=0, atol=0)
-
-    result = _minimax_h3_post_process((prepared, torch.zeros(1, 2, 6)))
-    assert result["video"][0].dtype == np.uint8
-    np.testing.assert_array_equal(result["video"][0], expected[0].numpy())
-
-
 def test_cfg_parallel_is_rejected_for_distilled_checkpoint():
     from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
 
@@ -865,17 +655,12 @@ def _distilled_pipeline(diffuse_calls, base_schedule_by_partition):
     pipeline.default_audio_shift = 3.0
     pipeline.device = torch.device("cpu")
     pipeline.od_config = SimpleNamespace()
-    pipeline.text_encoder = Mock()
     pipeline._base_schedule_by_partition = schedules
+    pipeline.load_text_encoder = False
+    pipeline.load_vae_encoder = False
     pipeline._quality_policy = Mock()
     pipeline._quality_policy.resolve.return_value = SimpleNamespace(cache_dit=None)
     pipeline._cache_dit_runtime = SimpleNamespace(prepare=lambda spec: None)
-    pipeline.encode_prompt = Mock(
-        return_value=(
-            torch.ones(1, 2),
-            torch.ones(1, dtype=torch.long),
-        )
-    )
 
     def diffuse(**kwargs):
         diffuse_calls.append(kwargs)
@@ -903,7 +688,7 @@ def _t2va_batch(num_inference_steps=None):
     return DiffusionRequestBatch(
         [
             OmniDiffusionRequest(
-                prompt="distilled schedule",
+                prompt=_encoder_prompt("distilled schedule"),
                 sampling_params=sampling,
                 request_id="distilled",
             )
@@ -1024,10 +809,6 @@ def forward(self, query, key, value, metadata):
 
 
 def test_packed_attention_skips_mask_for_packed_mask_free_backend():
-    from vllm_omni.diffusion.attention.backends.abstract import (
-        VideoTokenLayout,
-        VideoTokenSpan,
-    )
     from vllm_omni.diffusion.models.minimax_h3.minimax_h3_transformer import (
         MiniMaxH3Attention,
     )
@@ -1054,10 +835,6 @@ def forward(self, query, key, value, metadata):
     torch.nn.Module.__init__(attention)
     attention.attention = FakeAttention()
     q = torch.randn(8, 2, 4)
-    video_layout = VideoTokenLayout(
-        used_len=5,
-        video_spans=(VideoTokenSpan(start=3, latent_grid=(1, 1, 2), role="target"),),
-    )
 
     attention._run_packed_attention(
         q,
@@ -1066,9 +843,6 @@ def forward(self, query, key, value, metadata):
         cu_seqlens=torch.tensor([0, 5, 8], dtype=torch.int32),
         max_seqlen=5,
         packed_total=8,
-        video_layout=video_layout,
-        vsa_prefix_segments=(1, 2),
-        gate_compress=torch.ones_like(q),
     )
 
     metadata = attention.attention.metadata
@@ -1076,11 +850,6 @@ def forward(self, query, key, value, metadata):
     assert metadata.attn_mask is None
     assert metadata.extra["valid_kv_length"] == 5
     assert metadata.extra["npu_attn_varlen"] is True
-    assert metadata.video_layout is video_layout
-    assert metadata.extra["vsa_h3_prefix_segments"] == (1, 2)
-    assert "vsa_h3_video_shape" not in metadata.extra
-    assert "vsa_h3_target_start" not in metadata.extra
-    assert metadata.extra["gate_compress"].shape == (1, *q.shape)
     packed_padding = metadata.packed_padding
     assert packed_padding is not None
     assert packed_padding.q_length == 5
@@ -1275,20 +1044,20 @@ def test_packed_attention_rejects_backends_without_multi_doc_capability(backend_
 def test_reference_image_resize_contract():
     from PIL import Image
 
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _reference_image_shape,
+    from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
+        resolve_minimax_h3_reference_image_shape,
     )
 
-    assert _reference_image_shape(Image.new("RGB", (1080, 1440))) == (
+    assert resolve_minimax_h3_reference_image_shape(Image.new("RGB", (1080, 1440))) == (
         2048,
         2720,
     )
     with pytest.raises(ValueError, match="aspect ratio"):
-        _reference_image_shape(Image.new("RGB", (100, 501)))
+        resolve_minimax_h3_reference_image_shape(Image.new("RGB", (100, 501)))
 
 
 def test_fl2va_supports_first_last_and_explicit_frame_index_contracts():
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import (
         _resolve_fl2va_keyframe_indices,
     )
 
@@ -1301,21 +1070,20 @@ def test_fl2va_supports_first_last_and_explicit_frame_index_contracts():
 
 
 def test_minimax_h3_uses_the_official_output_canvas_policy():
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _resolve_output_canvas,
+    from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
+        resolve_minimax_h3_output_canvas,
     )
 
-    assert _resolve_output_canvas(21 / 9, 768) == (672, 1536)
-    assert _resolve_output_canvas(16 / 9, 768) == (768, 1344)
-    assert _resolve_output_canvas(9 / 16, 768) == (1344, 768)
+    assert resolve_minimax_h3_output_canvas(21 / 9, 768) == (672, 1536)
+    assert resolve_minimax_h3_output_canvas(16 / 9, 768) == (768, 1344)
+    assert resolve_minimax_h3_output_canvas(9 / 16, 768) == (1344, 768)
     with pytest.raises(ValueError, match="short_edge"):
-        _resolve_output_canvas(16 / 9, 720)
+        resolve_minimax_h3_output_canvas(16 / 9, 720)
 
 
 def test_minimax_h3_accepts_sglang_auto_aspect_ratio_alias():
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import MiniMaxH3Pipeline
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import resolve_minimax_h3_shape
 
-    pipeline = object.__new__(MiniMaxH3Pipeline)
     sampling = SimpleNamespace(
         fps=24,
         num_frames=1,
@@ -1323,7 +1091,7 @@ def test_minimax_h3_accepts_sglang_auto_aspect_ratio_alias():
         width=None,
         extra_args={"duration": 5.0, "aspect_ratio": "auto"},
     )
-    height, width, *_ = pipeline._resolve_shape("ref2va", sampling, None)
+    height, width, *_ = resolve_minimax_h3_shape("ref2va", sampling, None)
     assert (height, width) == (768, 1344)
 
 
@@ -1476,12 +1244,6 @@ def test_text_encoder_stub_constructs_without_group_or_weights():
     from vllm_omni.diffusion.models.minimax_h3.encoder import (
         MiniMaxH3Qwen3VLEncoder,
     )
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        MiniMaxH3Pipeline,
-    )
-    from vllm_omni.diffusion.offloader.component_utils import (
-        get_encoder_block_groups,
-    )
 
     encoder = MiniMaxH3Qwen3VLEncoder(
         "/nonexistent/text_encoder",
@@ -1494,25 +1256,6 @@ def test_text_encoder_stub_constructs_without_group_or_weights():
     # The stub has no parameters, so it never contributes to the runner's
     # strict missing-parameter check on non-encoder ranks.
     assert list(encoder.named_parameters()) == []
-    assert (
-        get_encoder_block_groups(
-            encoder,
-            "text_encoder",
-            MiniMaxH3Pipeline._offload_plan,
-            strict=True,
-        )
-        == []
-    )
-
-    # An arbitrary empty module is not silently treated as a distributed
-    # stub; explicit plans still validate their declared paths.
-    with pytest.raises(ValueError, match=r"text_encoder\.vision\.blocks was not found"):
-        get_encoder_block_groups(
-            nn.Module(),
-            "text_encoder",
-            MiniMaxH3Pipeline._offload_plan,
-            strict=True,
-        )
 
 
 def test_global_quant_config_is_shared_by_dit_and_encoder():
@@ -1575,152 +1318,25 @@ def test_text_encoder_linear_delegates_quantization_to_vllm_factory():
     quant_config.get_quant_method.assert_called_once_with(linear, prefix=prefix)
 
 
-def test_no_offload_keeps_text_encoder_resident():
+def test_distributed_layerwise_offload_stages_vae_component():
     from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
 
     pipeline = object.__new__(MiniMaxH3Pipeline)
     torch.nn.Module.__init__(pipeline)
     pipeline.od_config = SimpleNamespace(
-        enable_cpu_offload=False,
         enable_layerwise_offload=False,
+        enable_distributed_layerwise_offload=True,
     )
-    pipeline.text_encoder = Mock()
-    expected = torch.ones(2, 3)
-    pipeline.text_encoder.encode_ids.return_value = expected
-    input_ids = torch.tensor([1, 2])
+    component = Mock()
 
-    actual = pipeline._encode_text_hidden(input_ids, {})
+    with pipeline._component_on_device(component):
+        component.load_to_device.assert_called_once_with()
+        component.offload_to_cpu.assert_not_called()
 
-    assert actual is expected
-    pipeline.text_encoder.load_to_device.assert_called_once_with()
-    pipeline.text_encoder.offload_to_cpu.assert_not_called()
+    component.offload_to_cpu.assert_called_once_with()
 
 
-def test_model_offload_uses_hooked_text_encoder_call():
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.od_config = SimpleNamespace(
-        enable_cpu_offload=True,
-        enable_layerwise_offload=False,
-    )
-    expected = torch.ones(2, 3)
-    pipeline.text_encoder = Mock(return_value=expected)
-    pipeline._model_cpu_offload_modules = [pipeline.text_encoder]
-    input_ids = torch.tensor([1, 2])
-    vision_kwargs = {"pixel_values": torch.ones(1, 4)}
-
-    actual = pipeline._encode_text_hidden(input_ids, vision_kwargs)
-
-    assert actual is expected
-    pipeline.text_encoder.assert_called_once_with(input_ids, **vision_kwargs)
-    pipeline.text_encoder.load_to_device.assert_not_called()
-
-
-@pytest.mark.parametrize(
-    ("enable_layerwise", "enable_distributed"),
-    [(True, False), (False, True)],
-)
-def test_legacy_layer_offload_preserves_minimax_stage_lifecycle(enable_layerwise, enable_distributed):
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.od_config = SimpleNamespace(
-        diffusion_offload_config=None,
-        enable_cpu_offload=False,
-        enable_layerwise_offload=enable_layerwise,
-        enable_distributed_layerwise_offload=enable_distributed,
-    )
-    pipeline.text_encoder = Mock()
-    expected = torch.ones(2, 3)
-    pipeline.text_encoder.encode_ids.return_value = expected
-
-    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
-
-    assert actual is expected
-    pipeline.text_encoder.load_to_device.assert_called_once_with()
-    pipeline.text_encoder.offload_to_cpu.assert_called_once_with()
-
-    vae = Mock()
-    with pipeline._component_on_device(vae):
-        pass
-    vae.load_to_device.assert_called_once_with()
-    vae.offload_to_cpu.assert_called_once_with()
-
-
-def test_layerwise_encoder_selection_releases_text_encoder():
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.od_config = SimpleNamespace(
-        enable_cpu_offload=False,
-        enable_layerwise_offload=False,
-        enable_distributed_layerwise_offload=False,
-        diffusion_offload_config={
-            "mode": "layer",
-            "components": ["text_encoder"],
-        },
-    )
-    pipeline.text_encoder = Mock()
-    expected = torch.ones(2, 3)
-    pipeline.text_encoder.encode_ids.return_value = expected
-
-    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
-
-    assert actual is expected
-    pipeline.text_encoder.load_to_device.assert_called_once_with()
-    pipeline.text_encoder.offload_to_cpu.assert_called_once_with()
-
-
-def test_layerwise_dit_only_keeps_text_encoder_resident():
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.od_config = SimpleNamespace(
-        enable_cpu_offload=False,
-        enable_layerwise_offload=False,
-        enable_distributed_layerwise_offload=False,
-        diffusion_offload_config={"mode": "layer", "components": ["dit"]},
-    )
-    pipeline.text_encoder = Mock()
-    expected = torch.ones(2, 3)
-    pipeline.text_encoder.encode_ids.return_value = expected
-
-    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
-
-    assert actual is expected
-    pipeline.text_encoder.load_to_device.assert_called_once_with()
-    pipeline.text_encoder.offload_to_cpu.assert_not_called()
-
-
-def test_dit_encoder_selection_keeps_vae_resident():
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.od_config = SimpleNamespace(
-        enable_cpu_offload=False,
-        enable_layerwise_offload=False,
-        enable_distributed_layerwise_offload=False,
-        diffusion_offload_config={
-            "mode": "layer",
-            "components": ["dit", "text_encoder"],
-        },
-    )
-    component = Mock()
-
-    with pipeline._component_on_device(component):
-        pass
-
-    component.load_to_device.assert_not_called()
-    component.offload_to_cpu.assert_not_called()
-
-
-def test_distributed_layerwise_resident_blocks_are_stage_scoped():
+def test_distributed_layerwise_resident_blocks_are_stage_scoped():
     from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
 
     pipeline = object.__new__(MiniMaxH3Pipeline)
@@ -1766,6 +1382,58 @@ def test_distributed_layerwise_resident_blocks_can_be_skipped():
     controller.offload_resident_layers.assert_not_called()
 
 
+@pytest.mark.skip(reason="encoder layerwise API is not part of this branch")
+def test_encoder_layerwise_offload_keeps_tp_blocks_rank_local(monkeypatch):
+    from vllm_omni.diffusion.models.minimax_h3.encoder import (
+        MiniMaxH3Qwen3VLEncoder,
+    )
+
+    class Stack(torch.nn.Module):
+        def __init__(self, count):
+            super().__init__()
+            self.blocks = torch.nn.ModuleList([torch.nn.Linear(2, 2) for _ in range(count)])
+
+    class TextStack(torch.nn.Module):
+        def __init__(self, count):
+            super().__init__()
+            self.layers = torch.nn.ModuleList([torch.nn.Linear(2, 2) for _ in range(count)])
+
+    hooks = []
+
+    def fake_apply(block, next_block, device, stream, pin_memory):
+        hook = SimpleNamespace(
+            block=block,
+            next_block=next_block,
+            device=device,
+            stream=stream,
+            pin_memory=pin_memory,
+            _prev_hook=None,
+            offload_layer=Mock(),
+        )
+        hooks.append(hook)
+        return hook
+
+    monkeypatch.setattr(
+        "vllm_omni.diffusion.offloader.layerwise_backend.apply_block_hook",
+        fake_apply,
+    )
+    monkeypatch.setattr(
+        "vllm_omni.platforms.current_omni_platform.Stream",
+        Mock(return_value="copy-stream"),
+    )
+    encoder = object.__new__(MiniMaxH3Qwen3VLEncoder)
+    torch.nn.Module.__init__(encoder)
+    encoder.device_target = torch.device("cpu")
+    encoder.vision = Stack(2)
+    encoder.text_model = TextStack(3)
+
+    encoder.enable_omni_layerwise_offload(pin_memory=False)
+
+    assert len(hooks) == 5
+    assert all(hook._prev_hook is not None for hook in hooks)
+    assert all(hook.device == torch.device("cpu") for hook in hooks)
+
+
 def test_video_vae_keeps_reference_fp32_weights(monkeypatch):
     from vllm_omni.diffusion.models.minimax_h3 import vae as vae_module
 
@@ -1797,97 +1465,6 @@ def __init__(self):
     assert next(video_vae.parameters()).dtype == torch.float32
 
 
-def test_keyframe_encode_pins_and_restores_cudnn_settings():
-    from vllm_omni.diffusion.models.minimax_h3.vae import (
-        _minimax_h3_keyframe_encode_context,
-    )
-
-    cudnn = torch.backends.cudnn
-    original = (
-        cudnn.enabled,
-        cudnn.benchmark,
-        cudnn.deterministic,
-        cudnn.allow_tf32,
-    )
-    try:
-        cudnn.enabled = False
-        cudnn.benchmark = True
-        cudnn.deterministic = False
-        cudnn.allow_tf32 = False
-
-        with _minimax_h3_keyframe_encode_context(torch.device("cuda")):
-            assert cudnn.enabled
-            assert not cudnn.benchmark
-            assert cudnn.deterministic
-            assert cudnn.allow_tf32
-
-        assert not cudnn.enabled
-        assert cudnn.benchmark
-        assert not cudnn.deterministic
-        assert not cudnn.allow_tf32
-    finally:
-        (
-            cudnn.enabled,
-            cudnn.benchmark,
-            cudnn.deterministic,
-            cudnn.allow_tf32,
-        ) = original
-
-
-@pytest.mark.parametrize("fail_encode", [False, True])
-def test_keyframe_encode_enters_backend_context(monkeypatch, fail_encode):
-    from PIL import Image
-
-    from vllm_omni.diffusion.models.minimax_h3 import vae as vae_module
-
-    events = []
-    input_image = Image.new("RGB", (32, 32))
-
-    @contextmanager
-    def track_context(device):
-        assert device == torch.device("cpu")
-        events.append("enter")
-        try:
-            yield
-        finally:
-            events.append("exit")
-
-    class FakeModel(torch.nn.Module):
-        def __init__(self):
-            super().__init__()
-            self.weight = torch.nn.Parameter(torch.ones(1))
-            self.parallel_tiling = True
-
-        def encode_images(self, image, *, use_fp16_latent):
-            assert events == ["enter"]
-            assert image is input_image
-            assert use_fp16_latent
-            events.append("encode")
-            if fail_encode:
-                raise RuntimeError("encode failed")
-            return [torch.ones(1, 1, 2, 2)]
-
-    video_vae = object.__new__(vae_module.MiniMaxH3VideoVAE)
-    torch.nn.Module.__init__(video_vae)
-    video_vae.model = FakeModel()
-    video_vae.config_dict = {
-        "latent_channels": 1,
-        "latents_mean": [0.0],
-        "latents_std": [1.0],
-    }
-    monkeypatch.setattr(vae_module, "_minimax_h3_keyframe_encode_context", track_context)
-
-    if fail_encode:
-        with pytest.raises(RuntimeError, match="encode failed"):
-            video_vae.encode_image(input_image)
-    else:
-        rows = video_vae.encode_image(input_image)
-        torch.testing.assert_close(rows, torch.ones(1, 4))
-
-    assert events == ["enter", "encode", "exit"]
-    assert video_vae.model.parallel_tiling
-
-
 def test_video_vae_can_load_on_cpu_for_staged_gpu_residency(monkeypatch):
     from vllm_omni.diffusion.models.minimax_h3 import vae as vae_module
 
@@ -2115,83 +1692,20 @@ def encode_videos(self, frames, *, use_fp16_latent):
     assert shape == (2, 2, 2)
 
 
-def test_distributed_video_vae_encodes_references_sequentially(monkeypatch):
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-    from vllm_omni.diffusion.models.minimax_h3 import (
-        pipeline_minimax_h3 as pipeline_module,
+@pytest.mark.parametrize(
+    ("case", "extra", "image_count", "expected"),
+    [
+        ("F1", {"frame_index": -1}, 1, [-1]),
+        ("F2", {"frame_indices": [0, -1]}, 2, [0, -1]),
+    ],
+)
+def test_f1_f2_official_fl2va_keyframe_matrix(case, extra, image_count, expected):
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import (
+        _resolve_fl2va_keyframe_indices,
     )
 
-    prepared = [
-        {"prepared_path": "video-1.mp4"},
-        {"prepared_path": "video-2.mp4"},
-    ]
-
-    class FakeVideoVAE:
-        def __init__(self):
-            self.calls = []
-
-        def is_distributed_enabled(self):
-            return True
-
-        def encode_video(self, frames):
-            self.calls.append(frames)
-            index = len(self.calls)
-            return torch.full((1, 2), index, dtype=torch.float32), (index, 2, 3)
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.device = torch.device("cpu")
-    pipeline.video_vae = FakeVideoVAE()
-
-    monkeypatch.setattr(
-        pipeline_module,
-        "_dit_rank_world",
-        lambda: ("dit-group", 1, 4),
-    )
-
-    def fake_broadcast_object_list(values, *, src, group, device):
-        assert values == [None]
-        assert (src, group, device) == (0, "dit-group", torch.device("cpu"))
-        values[0] = prepared
-
-    monkeypatch.setattr(
-        pipeline_module.dist,
-        "broadcast_object_list",
-        fake_broadcast_object_list,
-    )
-    monkeypatch.setattr(
-        pipeline_module,
-        "load_video_frames",
-        lambda path: f"frames:{path}",
-    )
-
-    rows, shapes = pipeline._encode_video_conditions_resident(None, count=2)
-
-    assert pipeline.video_vae.calls == [
-        "frames:video-1.mp4",
-        "frames:video-2.mp4",
-    ]
-    torch.testing.assert_close(
-        rows,
-        torch.tensor([[1.0, 1.0], [2.0, 2.0]]),
-    )
-    assert shapes == [(1, 2, 3), (2, 2, 3)]
-
-
-@pytest.mark.parametrize(
-    ("case", "extra", "image_count", "expected"),
-    [
-        ("F1", {"frame_index": -1}, 1, [-1]),
-        ("F2", {"frame_indices": [0, -1]}, 2, [0, -1]),
-    ],
-)
-def test_f1_f2_official_fl2va_keyframe_matrix(case, extra, image_count, expected):
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _resolve_fl2va_keyframe_indices,
-    )
-
-    assert case in {"F1", "F2"}
-    assert _resolve_fl2va_keyframe_indices(extra, image_count) == expected
+    assert case in {"F1", "F2"}
+    assert _resolve_fl2va_keyframe_indices(extra, image_count) == expected
 
 
 @pytest.mark.parametrize(
@@ -2206,7 +1720,7 @@ def test_f1_f2_official_fl2va_keyframe_matrix(case, extra, image_count, expected
     ],
 )
 def test_r1_r6_ref2va_reference_count_matrix(case, counts):
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import (
         _validate_ref2va_reference_counts,
     )
 
@@ -2215,10 +1729,10 @@ def test_r1_r6_ref2va_reference_count_matrix(case, counts):
 
 
 def test_ref2va_reference_count_validation_preserves_client_error_metadata():
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
+    from vllm_omni.errors import OmniClientError
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import (
         _validate_ref2va_reference_counts,
     )
-    from vllm_omni.errors import OmniClientError
 
     with pytest.raises(OmniClientError, match="at least one image or video"):
         _validate_ref2va_reference_counts(0, 0, 0)
@@ -2322,32 +1836,6 @@ def test_prepared_reference_video_descriptor_rejects_unknown_fields():
         deserialize_prepared_reference_videos('{"artifact_dir":"/tmp","videos":[{"path":"x"}]}')
 
 
-def test_stage_one_reuses_existing_prepared_reference_video(tmp_path):
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _reuse_prepared_reference_videos,
-    )
-
-    prepared_path = tmp_path / "prepared.mp4"
-    prepared_path.touch()
-    prepared = [{"prepared_path": str(prepared_path)}]
-
-    assert _reuse_prepared_reference_videos(prepared, expected_count=1) is prepared
-
-
-def test_stage_one_rejects_invalid_prepared_reference_video(tmp_path):
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _reuse_prepared_reference_videos,
-    )
-
-    with pytest.raises(ValueError, match="count does not match"):
-        _reuse_prepared_reference_videos([], expected_count=1)
-    with pytest.raises(ValueError, match="prepared reference video is unavailable"):
-        _reuse_prepared_reference_videos(
-            [{"prepared_path": str(tmp_path / "missing.mp4")}],
-            expected_count=1,
-        )
-
-
 def test_ref2va_qwen_sampling_uses_one_selective_decode(monkeypatch):
     from vllm_omni.diffusion.models.minimax_h3 import reference_video as reference_video_module
 
@@ -2667,9 +2155,8 @@ def test_ref2va_two_video_recipe_rejects_real_duration_overflow(monkeypatch, tmp
 
 @pytest.mark.parametrize("duration", [4.0, 15.0])
 def test_g2_output_duration_accepts_official_boundaries(duration):
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import resolve_minimax_h3_shape
 
-    pipeline = object.__new__(MiniMaxH3Pipeline)
     sampling = SimpleNamespace(
         fps=24,
         num_frames=1,
@@ -2678,15 +2165,14 @@ def test_g2_output_duration_accepts_official_boundaries(duration):
         extra_args={"duration": duration},
     )
 
-    height, width, *_ = pipeline._resolve_shape("ref2va", sampling, None)
+    height, width, *_ = resolve_minimax_h3_shape("ref2va", sampling, None)
     assert height > 0 and width > 0
 
 
 @pytest.mark.parametrize("duration", [3.99, 15.01, float("nan"), "not-a-duration"])
 def test_g2_output_duration_rejects_out_of_contract_values(duration):
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import resolve_minimax_h3_shape
 
-    pipeline = object.__new__(MiniMaxH3Pipeline)
     sampling = SimpleNamespace(
         fps=24,
         num_frames=1,
@@ -2695,7 +2181,7 @@ def test_g2_output_duration_rejects_out_of_contract_values(duration):
         extra_args={"duration": duration},
     )
     with pytest.raises(ValueError, match="duration"):
-        pipeline._resolve_shape("ref2va", sampling, None)
+        resolve_minimax_h3_shape("ref2va", sampling, None)
 
 
 def test_g1_fanout_uses_incrementing_output_seeds():
@@ -2713,26 +2199,25 @@ def test_g1_fanout_uses_incrementing_output_seeds():
 def test_g3_task_specific_aspect_ratio_policy():
     from PIL import Image
 
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _resolve_minimax_h3_aspect_ratio,
+    from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
+        resolve_minimax_h3_aspect_ratio,
     )
 
     image = Image.new("RGB", (1280, 720))
-    assert _resolve_minimax_h3_aspect_ratio("fl2va", "9:16", image) == pytest.approx(16 / 9)
-    assert _resolve_minimax_h3_aspect_ratio("ref2va", None, None) == pytest.approx(16 / 9)
-    assert _resolve_minimax_h3_aspect_ratio("ref2va", "auto", None) == pytest.approx(16 / 9)
+    assert resolve_minimax_h3_aspect_ratio("fl2va", "9:16", image) == pytest.approx(16 / 9)
+    assert resolve_minimax_h3_aspect_ratio("ref2va", None, None) == pytest.approx(16 / 9)
+    assert resolve_minimax_h3_aspect_ratio("ref2va", "auto", None) == pytest.approx(16 / 9)
     with pytest.raises(ValueError, match="requires an explicit"):
-        _resolve_minimax_h3_aspect_ratio("t2va", None, None)
+        resolve_minimax_h3_aspect_ratio("t2va", None, None)
     with pytest.raises(ValueError, match="one of"):
-        _resolve_minimax_h3_aspect_ratio("t2va", "2:1", None)
+        resolve_minimax_h3_aspect_ratio("t2va", "2:1", None)
 
 
 def test_g3_t2va_shape_requires_a_named_ratio_and_fl2va_ignores_override():
     from PIL import Image
 
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import resolve_minimax_h3_shape
 
-    pipeline = object.__new__(MiniMaxH3Pipeline)
     t2va_sampling = SimpleNamespace(
         fps=24,
         num_frames=1,
@@ -2741,7 +2226,7 @@ def test_g3_t2va_shape_requires_a_named_ratio_and_fl2va_ignores_override():
         extra_args={"duration": 5.0},
     )
     with pytest.raises(ValueError, match="requires an explicit aspect_ratio"):
-        pipeline._resolve_shape("t2va", t2va_sampling, None)
+        resolve_minimax_h3_shape("t2va", t2va_sampling, None)
 
     fl2va_sampling = SimpleNamespace(
         fps=24,
@@ -2750,14 +2235,14 @@ def test_g3_t2va_shape_requires_a_named_ratio_and_fl2va_ignores_override():
         width=None,
         extra_args={"duration": 5.0, "aspect_ratio": "9:16"},
     )
-    height, width, *_ = pipeline._resolve_shape("fl2va", fl2va_sampling, Image.new("RGB", (1280, 720)))
+    height, width, *_ = resolve_minimax_h3_shape("fl2va", fl2va_sampling, Image.new("RGB", (1280, 720)))
     assert (height, width) == (768, 1344)
 
 
 def test_g4_reference_image_boundaries_and_aspect_ratio():
     from PIL import Image
 
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import (
         _validate_reference_image,
     )
 
@@ -2772,18 +2257,18 @@ def test_g4_reference_image_boundaries_and_aspect_ratio():
 def test_g4_reference_image_file_format_and_size_contract(tmp_path):
     from PIL import Image
 
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _load_image,
+    from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
+        load_minimax_h3_images,
     )
 
     valid_path = tmp_path / "reference.png"
     Image.new("RGB", (256, 256)).save(valid_path)
-    assert _load_image(valid_path).size == (256, 256)
+    assert load_minimax_h3_images(valid_path)[0].size == (256, 256)
 
     invalid_path = tmp_path / "reference.bmp"
     Image.new("RGB", (256, 256)).save(invalid_path)
     with pytest.raises(ValueError, match="must use"):
-        _load_image(invalid_path)
+        load_minimax_h3_images(invalid_path)
 
 
 def test_g4_standalone_audio_duration_and_total_duration_contract():
@@ -2809,97 +2294,6 @@ def test_g4_standalone_audio_duration_and_total_duration_contract():
         )
 
 
-def test_ref2va_video_soundtrack_does_not_consume_standalone_audio_budget():
-    from PIL import Image
-
-    from vllm_omni.diffusion.cache.cachedit.runtime import RequestScopedCacheDiTRuntime
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-    from vllm_omni.diffusion.models.minimax_h3.quality_policy import MiniMaxH3QualityPolicy
-    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.partition = "ref2va"
-    pipeline.supported_tasks = frozenset({"ref2va"})
-    pipeline.device = torch.device("cpu")
-    pipeline.default_video_shift = 12.0
-    pipeline.default_audio_shift = 3.0
-    pipeline._resolve_sigma_positions = Mock(return_value=(None, 50))
-    pipeline._quality_policy = MiniMaxH3QualityPolicy(None)
-    pipeline._cache_dit_runtime = Mock(spec=RequestScopedCacheDiTRuntime)
-    pipeline.text_encoder = object()
-    pipeline.encode_prompt = Mock(return_value=(torch.ones(1, 2), torch.ones(1, dtype=torch.long)))
-    pipeline._prepare_reference_videos = Mock(return_value=[{"input_has_audio": True}])
-    pipeline._encode_visual_conditions = Mock(return_value=(torch.ones(1, 96), [(1, 16, 16), (17, 48, 84)]))
-    # A 2.35-second video soundtrack and a 15-second standalone reference
-    # each satisfy their modality's separate 15-second duration budget.
-    embedded = torch.full((188, 32), 1.0)
-    standalone = torch.full((1200, 32), 2.0)
-    pipeline._encode_reference_audio_conditions = Mock(return_value=(embedded, [94], standalone, [600]))
-    sampling = OmniDiffusionSamplingParams(
-        width=1344,
-        height=768,
-        fps=24,
-        num_inference_steps=50,
-        extra_args={"task": "ref2va", "duration": 15.0},
-    )
-
-    context = pipeline._prepare_request_inputs(
-        prompt="A person carrying books down a street",
-        multi_modal_data={
-            "image": Image.new("RGB", (256, 256)),
-            "video": ["reference.mp4"],
-            "audio": (torch.zeros(1, 15 * 16000), 16000),
-        },
-        sampling=sampling,
-    )
-
-    assert context["audio_condition_lengths"] == [94, 600]
-    assert [block["kind"] for block in context["ref_blocks"]] == ["image", "video_audio", "audio"]
-    torch.testing.assert_close(context["audio_condition"], torch.cat([embedded, standalone]))
-
-
-def test_ref2va_audio_duration_validation_precedes_rank_branch(monkeypatch):
-    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as pipeline_module
-
-    pipeline = object.__new__(pipeline_module.MiniMaxH3Pipeline)
-    pipeline.device = torch.device("cpu")
-    monkeypatch.setattr(pipeline_module, "_dit_rank_world", lambda: (None, 1, 2))
-
-    waveform = torch.zeros(1, 10)
-    with pytest.raises(ValueError, match="max_duration_seconds must be positive"):
-        pipeline._encode_audio_conditions_resident(
-            [(waveform, 10)],
-            max_duration_seconds=0,
-        )
-
-
-def test_ref2va_standalone_audio_condition_is_bounded_to_output_duration():
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import MiniMaxH3Pipeline
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    pipeline.device = torch.device("cpu")
-    observed = []
-
-    class FakeAudioVAE:
-        def encode_waveform(self, waveform, sample_rate):
-            observed.append((waveform.clone(), sample_rate))
-            return waveform, waveform.shape[-1]
-
-    pipeline.audio_vae = FakeAudioVAE()
-    waveform = torch.arange(40, dtype=torch.float32).reshape(1, 40)
-
-    encoded, lengths = pipeline._encode_audio_conditions_resident(
-        [(waveform, 10)],
-        max_duration_seconds=2.5,
-    )
-
-    assert observed[0][0].shape == (1, 25)
-    assert observed[0][1] == 10
-    assert encoded.shape == (1, 25)
-    assert lengths == [25]
-
-
 @pytest.mark.parametrize(
     ("field", "value", "message"),
     [
@@ -2963,9 +2357,8 @@ def _one_layer_text_encoder():
         MiniMaxH3Qwen3VLQKVParallelLinear,
         MiniMaxH3Qwen3VLRMSNorm,
     )
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import _SingleRankEncoderGroup
 
-    group = _SingleRankEncoderGroup(0)
+    group = SimpleNamespace(rank_in_group=0, world_size=1, device_group=None, ranks=[0])
     layer = nn.Module()
     layer.self_attn = nn.Module()
     layer.mlp = nn.Module()
@@ -3103,7 +2496,7 @@ def _pad_seq_len_batch(pad_seq_len):
     return DiffusionRequestBatch(
         [
             OmniDiffusionRequest(
-                prompt="pinned packed length",
+                prompt=_encoder_prompt("pinned packed length"),
                 sampling_params=sampling,
                 request_id="pad-seq-len",
             )
@@ -3189,3 +2582,431 @@ def test_pad_seq_len_request_validation_accepts_aligned_values():
     assert _resolve_pad_seq_len(None) is None
     assert _resolve_pad_seq_len(54080) == 54080
     assert _resolve_pad_seq_len(MINIMAX_H3_MAX_PAD_SEQ_LEN) == MINIMAX_H3_MAX_PAD_SEQ_LEN
+
+
+def _turbo_spec(filename: str) -> TurboSpec:
+    """Build the spec a loaded artifact of this name would carry."""
+    spec = parse_turbo_filename(filename)
+    assert spec is not None
+    return spec
+
+
+def test_joint_video_output_is_quantized_before_transfer():
+    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
+        _minimax_h3_post_process,
+        _prepare_minimax_h3_video_output,
+    )
+
+    video = torch.linspace(-0.1, 1.1, 2 * 3 * 2 * 4 * 5, dtype=torch.float64).reshape(2, 3, 2, 4, 5)
+    expected = torch.round(video.float().clamp(0, 1) * 255).to(torch.uint8).permute(0, 2, 3, 4, 1)
+    prepared = _prepare_minimax_h3_video_output(video)
+
+    assert prepared.dtype == torch.uint8
+    assert prepared.is_contiguous()
+    assert prepared.shape == (2, 2, 4, 5, 3)
+    torch.testing.assert_close(prepared, expected, rtol=0, atol=0)
+
+    result = _minimax_h3_post_process((prepared, torch.zeros(1, 2, 6)))
+    assert result["video"][0].dtype == np.uint8
+    np.testing.assert_array_equal(result["video"][0], expected[0].numpy())
+
+
+def test_no_offload_keeps_text_encoder_resident():
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = SimpleNamespace(
+        enable_cpu_offload=False,
+        enable_layerwise_offload=False,
+    )
+    pipeline.text_encoder = Mock()
+    expected = torch.ones(2, 3)
+    pipeline.text_encoder.encode_ids.return_value = expected
+    input_ids = torch.tensor([1, 2])
+
+    actual = pipeline._encode_text_hidden(input_ids, {})
+
+    assert actual is expected
+    pipeline.text_encoder.load_to_device.assert_called_once_with()
+    pipeline.text_encoder.offload_to_cpu.assert_not_called()
+
+
+def test_model_offload_uses_hooked_text_encoder_call():
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = SimpleNamespace(
+        enable_cpu_offload=True,
+        enable_layerwise_offload=False,
+    )
+    expected = torch.ones(2, 3)
+    pipeline.text_encoder = Mock(return_value=expected)
+    pipeline._model_cpu_offload_modules = [pipeline.text_encoder]
+    input_ids = torch.tensor([1, 2])
+    vision_kwargs = {"pixel_values": torch.ones(1, 4)}
+
+    actual = pipeline._encode_text_hidden(input_ids, vision_kwargs)
+
+    assert actual is expected
+    pipeline.text_encoder.assert_called_once_with(input_ids, **vision_kwargs)
+    pipeline.text_encoder.load_to_device.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    ("enable_layerwise", "enable_distributed"),
+    [(True, False), (False, True)],
+)
+def test_legacy_layer_offload_preserves_minimax_stage_lifecycle(enable_layerwise, enable_distributed):
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = SimpleNamespace(
+        diffusion_offload_config=None,
+        enable_cpu_offload=False,
+        enable_layerwise_offload=enable_layerwise,
+        enable_distributed_layerwise_offload=enable_distributed,
+    )
+    pipeline.text_encoder = Mock()
+    expected = torch.ones(2, 3)
+    pipeline.text_encoder.encode_ids.return_value = expected
+
+    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
+
+    assert actual is expected
+    pipeline.text_encoder.load_to_device.assert_called_once_with()
+    pipeline.text_encoder.offload_to_cpu.assert_called_once_with()
+
+    vae = Mock()
+    with pipeline._component_on_device(vae):
+        pass
+    vae.load_to_device.assert_called_once_with()
+    vae.offload_to_cpu.assert_called_once_with()
+
+
+def test_layerwise_encoder_selection_releases_text_encoder():
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = SimpleNamespace(
+        enable_cpu_offload=False,
+        enable_layerwise_offload=False,
+        enable_distributed_layerwise_offload=False,
+        diffusion_offload_config={
+            "mode": "layer",
+            "components": ["text_encoder"],
+        },
+    )
+    pipeline.text_encoder = Mock()
+    expected = torch.ones(2, 3)
+    pipeline.text_encoder.encode_ids.return_value = expected
+
+    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
+
+    assert actual is expected
+    pipeline.text_encoder.load_to_device.assert_called_once_with()
+    pipeline.text_encoder.offload_to_cpu.assert_called_once_with()
+
+
+def test_layerwise_dit_only_keeps_text_encoder_resident():
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = SimpleNamespace(
+        enable_cpu_offload=False,
+        enable_layerwise_offload=False,
+        enable_distributed_layerwise_offload=False,
+        diffusion_offload_config={"mode": "layer", "components": ["dit"]},
+    )
+    pipeline.text_encoder = Mock()
+    expected = torch.ones(2, 3)
+    pipeline.text_encoder.encode_ids.return_value = expected
+
+    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
+
+    assert actual is expected
+    pipeline.text_encoder.load_to_device.assert_called_once_with()
+    pipeline.text_encoder.offload_to_cpu.assert_not_called()
+
+
+def test_dit_encoder_selection_keeps_vae_resident():
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = SimpleNamespace(
+        enable_cpu_offload=False,
+        enable_layerwise_offload=False,
+        enable_distributed_layerwise_offload=False,
+        diffusion_offload_config={
+            "mode": "layer",
+            "components": ["dit", "text_encoder"],
+        },
+    )
+    component = Mock()
+
+    with pipeline._component_on_device(component):
+        pass
+
+    component.load_to_device.assert_not_called()
+    component.offload_to_cpu.assert_not_called()
+
+
+def test_keyframe_encode_pins_and_restores_cudnn_settings():
+    from vllm_omni.diffusion.models.minimax_h3.vae import (
+        _minimax_h3_keyframe_encode_context,
+    )
+
+    cudnn = torch.backends.cudnn
+    original = (
+        cudnn.enabled,
+        cudnn.benchmark,
+        cudnn.deterministic,
+        cudnn.allow_tf32,
+    )
+    try:
+        cudnn.enabled = False
+        cudnn.benchmark = True
+        cudnn.deterministic = False
+        cudnn.allow_tf32 = False
+
+        with _minimax_h3_keyframe_encode_context(torch.device("cuda")):
+            assert cudnn.enabled
+            assert not cudnn.benchmark
+            assert cudnn.deterministic
+            assert cudnn.allow_tf32
+
+        assert not cudnn.enabled
+        assert cudnn.benchmark
+        assert not cudnn.deterministic
+        assert not cudnn.allow_tf32
+    finally:
+        (
+            cudnn.enabled,
+            cudnn.benchmark,
+            cudnn.deterministic,
+            cudnn.allow_tf32,
+        ) = original
+
+
+@pytest.mark.parametrize("fail_encode", [False, True])
+def test_keyframe_encode_enters_backend_context(monkeypatch, fail_encode):
+    from PIL import Image
+
+    from vllm_omni.diffusion.models.minimax_h3 import vae as vae_module
+
+    events = []
+    input_image = Image.new("RGB", (32, 32))
+
+    @contextmanager
+    def track_context(device):
+        assert device == torch.device("cpu")
+        events.append("enter")
+        try:
+            yield
+        finally:
+            events.append("exit")
+
+    class FakeModel(torch.nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.weight = torch.nn.Parameter(torch.ones(1))
+            self.parallel_tiling = True
+
+        def encode_images(self, image, *, use_fp16_latent):
+            assert events == ["enter"]
+            assert image is input_image
+            assert use_fp16_latent
+            events.append("encode")
+            if fail_encode:
+                raise RuntimeError("encode failed")
+            return [torch.ones(1, 1, 2, 2)]
+
+    video_vae = object.__new__(vae_module.MiniMaxH3VideoVAE)
+    torch.nn.Module.__init__(video_vae)
+    video_vae.model = FakeModel()
+    video_vae.config_dict = {
+        "latent_channels": 1,
+        "latents_mean": [0.0],
+        "latents_std": [1.0],
+    }
+    monkeypatch.setattr(vae_module, "_minimax_h3_keyframe_encode_context", track_context)
+
+    if fail_encode:
+        with pytest.raises(RuntimeError, match="encode failed"):
+            video_vae.encode_image(input_image)
+    else:
+        rows = video_vae.encode_image(input_image)
+        torch.testing.assert_close(rows, torch.ones(1, 4))
+
+    assert events == ["enter", "encode", "exit"]
+    assert video_vae.model.parallel_tiling
+
+
+def test_decode_to_mp4_batches_consumer_transfers(monkeypatch):
+    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
+
+    class FakeEncoder:
+        instances = []
+
+        def __init__(self, **kwargs):
+            self.pushes = []
+            self.kwargs = kwargs
+            self.__class__.instances.append(self)
+
+        def push(self, frames):
+            self.pushes.append(np.array(frames, copy=True))
+
+        def finish(self):
+            return b"mp4"
+
+        def abort(self):
+            raise AssertionError("unexpected abort")
+
+    class FakeAudioVAE:
+        def decode_latent(self, latent):
+            return torch.zeros(1, 1, 2)
+
+    class FakeVideoVAE:
+        def decode_with_chunks(self, latent, *, on_chunk):
+            for value in (0.0, 0.25, 0.5):
+                on_chunk(torch.full((1, 3, 3, 2, 2), value))
+
+    pipeline = object.__new__(mod.MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.audio_vae = FakeAudioVAE()
+    pipeline.video_vae = FakeVideoVAE()
+    pipeline.device = torch.device("cpu")
+    monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_uses_manual_component_offload", lambda self, component: False)
+    monkeypatch.setattr(
+        "vllm_omni.diffusion.utils.media_utils.ChunkedMP4Encoder",
+        FakeEncoder,
+    )
+
+    output = pipeline.decode_to_mp4(
+        torch.zeros(1),
+        torch.zeros(1),
+        height=2,
+        width=2,
+        batch_frames=4,
+    )
+
+    assert output == b"mp4"
+    encoder = FakeEncoder.instances[-1]
+    assert [frames.shape[0] for frames in encoder.pushes] == [6, 3]
+    assert np.array_equal(encoder.pushes[0][0], np.full((2, 2, 3), 0, dtype=np.uint8))
+    assert np.array_equal(encoder.pushes[0][3], np.full((2, 2, 3), 64, dtype=np.uint8))
+    assert encoder.pushes[1].shape == (3, 2, 2, 3)
+
+
+def test_request_video_codec_options_reach_the_preencoded_mp4_encoder(monkeypatch):
+    """A client's encoder options must survive the worker-side pre-encode path."""
+    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
+
+    class FakeEncoder:
+        instances = []
+
+        def __init__(self, **kwargs):
+            self.kwargs = kwargs
+            self.__class__.instances.append(self)
+
+        def push(self, frames):
+            del frames
+
+        def finish(self):
+            return b"mp4"
+
+        def abort(self):
+            raise AssertionError("unexpected abort")
+
+    class FakeAudioVAE:
+        def decode_latent(self, latent):
+            return torch.zeros(1, 1, 2)
+
+    class FakeVideoVAE:
+        def decode_with_chunks(self, latent, *, on_chunk):
+            on_chunk(torch.zeros(1, 3, 1, 2, 2))
+
+    pipeline = object.__new__(mod.MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.audio_vae = FakeAudioVAE()
+    pipeline.video_vae = FakeVideoVAE()
+    pipeline.device = torch.device("cpu")
+    monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_uses_manual_component_offload", lambda self, component: False)
+    monkeypatch.setattr("vllm_omni.diffusion.utils.media_utils.ChunkedMP4Encoder", FakeEncoder)
+
+    pipeline.decode_to_mp4(
+        torch.zeros(1),
+        torch.zeros(1),
+        height=2,
+        width=2,
+        video_codec_options={"preset": "ultrafast"},
+    )
+
+    assert FakeEncoder.instances[-1].kwargs["video_codec_options"] == {"preset": "ultrafast"}
+
+
+@pytest.mark.parametrize(
+    ("codec_extra", "expected"),
+    [
+        ({}, {"preset": "ultrafast", "threads": "0"}),
+        ({"video_codec_options": {"preset": "slow", "threads": 2}}, {"preset": "slow", "threads": "2"}),
+        ({"video_codec_options": {}}, {}),
+        ({"video_codec_options": None}, None),
+    ],
+)
+@pytest.mark.parametrize("batch_extra, batch_frames", [({}, 17), ({"preencode_batch_frames": 5}, 5)])
+def test_preencode_request_preserves_serving_codec_defaults(codec_extra, expected, batch_extra, batch_frames):
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+    from vllm_omni.diffusion.request import OmniDiffusionRequest
+    from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch
+    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.partition = "fl2va"
+    pipeline.supported_tasks = frozenset({"t2va"})
+    pipeline.default_video_shift = 12.0
+    pipeline.default_audio_shift = 3.0
+    pipeline.device = torch.device("cpu")
+    pipeline.od_config = SimpleNamespace()
+    pipeline.load_text_encoder = False
+    pipeline.load_vae_encoder = False
+    pipeline.text_encoder = object()
+    pipeline.encode_prompt = Mock(return_value=(torch.ones(1, 2), torch.ones(1, dtype=torch.long)))
+    pipeline._quality_policy = Mock()
+    pipeline._cache_dit_runtime = Mock()
+    pipeline.diffuse = Mock(return_value=(torch.zeros(1), torch.zeros(1)))
+    pipeline.decode_to_mp4 = Mock(return_value=b"mp4")
+    sampling = OmniDiffusionSamplingParams(
+        width=1344,
+        height=768,
+        fps=24,
+        num_frames=124,
+        num_inference_steps=50,
+        extra_args={"task": "t2va", "aspect_ratio": "16:9", "preencode_mp4": True, **codec_extra, **batch_extra},
+    )
+    batch = DiffusionRequestBatch(
+        [OmniDiffusionRequest(prompt=_encoder_prompt("test"), sampling_params=sampling, request_id="codec-defaults")]
+    )
+
+    pipeline.forward(batch)
+
+    assert pipeline.decode_to_mp4.call_args.kwargs["video_codec_options"] == expected
+    assert pipeline.decode_to_mp4.call_args.kwargs["batch_frames"] == batch_frames
+
+
+def test_video_codec_options_are_normalized_for_the_encoder():
+    from vllm_omni.diffusion.utils.media_utils import normalize_video_codec_options
+
+    assert normalize_video_codec_options({"preset": "ultrafast", "threads": 0}) == {
+        "preset": "ultrafast",
+        "threads": "0",
+    }
+    assert normalize_video_codec_options(None) is None
+    with pytest.raises(ValueError, match="video_codec_options"):
+        normalize_video_codec_options("preset=ultrafast")
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_execution_modes.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_execution_modes.py
new file mode 100644
index 00000000000..510a7b33e6e
--- /dev/null
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_execution_modes.py
@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from types import SimpleNamespace
+from typing import Any
+from unittest.mock import Mock
+
+import pytest
+import torch
+from PIL import Image
+
+from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
+
+
+@pytest.fixture
+def pipeline():
+    model = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(model)
+    model.load_text_encoder = True
+    model.load_vae_encoder = True
+    model.device = torch.device("cpu")
+    model.partition = "combined"
+    model.supported_tasks = frozenset({"t2va", "fl2va", "ref2va"})
+    model.default_video_shift = 12.0
+    model.default_audio_shift = 3.0
+    model.od_config = SimpleNamespace(enable_layerwise_offload=False)
+    model._quality_policy = SimpleNamespace(resolve=Mock(return_value=SimpleNamespace(cache_dit=None)))
+    model._cache_dit_runtime = SimpleNamespace(prepare=Mock())
+    model.encode_prompt = Mock(
+        return_value=(torch.ones(2, 5120, dtype=torch.bfloat16), torch.ones(2, dtype=torch.long))
+    )
+    model.video_vae = Mock()
+    model.video_vae.is_distributed_enabled.return_value = False
+    model.video_vae.encode_image.side_effect = lambda image: torch.ones((image.height // 32) * (image.width // 32), 96)
+    model.audio_vae = Mock()
+    model.transformer = torch.nn.Identity()
+    model.diffuse = Mock(return_value=(torch.zeros(1), torch.zeros(1)))
+    model.decode = Mock(return_value=(torch.zeros(1, 3, 1, 32, 32), torch.zeros(1)))
+    return model
+
+
+def _request(task):
+    prompt: dict[str, Any] = {"prompt": "A person waves."}
+    if task != "t2va":
+        prompt["multi_modal_data"] = {"image": Image.new("RGB", (256, 256))}
+    sampling = OmniDiffusionSamplingParams(
+        height=32, width=32, num_frames=96, num_inference_steps=2, extra_args={"task": task, "aspect_ratio": "1:1"}
+    )
+    return SimpleNamespace(prompts=[prompt], sampling_params=sampling)
+
+
+@pytest.mark.parametrize("task", ["t2va", "fl2va", "ref2va"])
+def test_single_stage_encodes_without_stage_zero(pipeline, task):
+    output = pipeline.forward(_request(task))
+    pipeline.encode_prompt.assert_called_once()
+    assert pipeline.video_vae.encode_image.call_count == int(task != "t2va")
+    pipeline.diffuse.assert_called_once()
+    assert pipeline.diffuse.call_args.kwargs["task"] == task
+    video, audio = output.output
+    torch.testing.assert_close(video, torch.zeros(1, 1, 32, 32, 3, dtype=torch.uint8))
+    torch.testing.assert_close(audio, pipeline.decode.return_value[1])
+
+
+def test_mixed_reference_conditioning_matches_stage_zero_handoff(pipeline, monkeypatch):
+    import numpy as np
+
+    from vllm_omni.data_entry_keys import flatten_payload
+    from vllm_omni.model_executor.models.minimax_h3 import encoder_processing as processing
+    from vllm_omni.model_executor.models.minimax_h3.conditioning import (
+        MiniMaxH3EncoderConditioning,
+        MiniMaxH3TextConditioning,
+    )
+    from vllm_omni.model_executor.models.minimax_h3.encoder import MiniMaxH3Encoder
+    from vllm_omni.model_executor.stage_input_processors.minimax_h3 import encoder2diffusion, prepare_encoder_prompt
+
+    frames = np.zeros((48, 32, 32, 3), dtype=np.uint8)
+    decode_frames = Mock(return_value=frames)
+    sampler = Mock(wraps=processing.sample_reference_video_frames)
+    monkeypatch.setattr(processing, "load_video_frames", decode_frames)
+    monkeypatch.setattr(processing, "sample_reference_video_frames", sampler)
+    monkeypatch.setattr(
+        processing,
+        "prepare_reference_videos",
+        Mock(
+            return_value=[{"prepared_path": "prepared.mp4", "original_path": "original.mp4", "input_has_audio": True}]
+        ),
+    )
+    monkeypatch.setattr(processing, "load_video_audio", Mock(return_value=(torch.full((64000,), 3.0), 32000)))
+    pipeline.video_vae.encode_video.return_value = (torch.full((1, 96), 2.0), (1, 2, 2))
+
+    def encode_audio(waveform, sample_rate):
+        length = round(waveform.shape[-1] / sample_rate * 40)
+        return torch.full((length * 2, 32), float(waveform[0])), length
+
+    pipeline.audio_vae.encode_waveform.side_effect = encode_audio
+    request = _request("ref2va")
+    request.prompts[0]["multi_modal_data"].update(video="original.mp4", audio=(torch.full((192000,), 4.0), 32000))
+    pipeline.forward(request)
+    local_kwargs = pipeline.diffuse.call_args.kwargs
+
+    transformed = prepare_encoder_prompt(request.prompts[0], [request.sampling_params])
+    stage_zero = object.__new__(MiniMaxH3Encoder)
+    torch.nn.Module.__init__(stage_zero)
+    stage_zero._component_leader = True
+    stage_zero.video_vae = pipeline.video_vae
+    stage_zero.audio_vae = pipeline.audio_vae
+    media = stage_zero._encode_media(stage_zero._media_input(transformed["additional_information"]))
+    text = MiniMaxH3TextConditioning(*pipeline.encode_prompt.return_value)
+    payload = MiniMaxH3EncoderConditioning.from_components(text, media).to_omni_payload()
+    source = SimpleNamespace(finished=True, outputs=[SimpleNamespace(multimodal_output=flatten_payload(payload))])
+    bridged = encoder2diffusion([source], request.prompts[0])
+    pipeline.load_text_encoder = False
+    pipeline.load_vae_encoder = False
+    pipeline.encode_prompt.reset_mock()
+    pipeline.forward(SimpleNamespace(prompts=[bridged], sampling_params=request.sampling_params))
+    external_kwargs = pipeline.diffuse.call_args.kwargs
+    for key, value in local_kwargs.items():
+        if isinstance(value, torch.Tensor):
+            torch.testing.assert_close(value, external_kwargs[key])
+        else:
+            assert value == external_kwargs[key]
+    pipeline.encode_prompt.assert_not_called()
+    assert decode_frames.call_count == sampler.call_count == 2
+    assert all(call.kwargs["decoded_frames"] is frames for call in sampler.call_args_list)
+    assert [block["kind"] for block in local_kwargs["ref_blocks"]] == ["image", "video_audio", "audio"]
+    assert local_kwargs["audio_condition_lengths"] == [80, round(107 / 24 * 40)]
+    assert all(
+        call.args[0].shape[-1] == round(107 / 24 * 32000)
+        for call in pipeline.audio_vae.encode_waveform.call_args_list[1::2]
+    )
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_offload.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_offload.py
index 31a8916a60a..24206952d5e 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_offload.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_offload.py
@@ -9,72 +9,25 @@
 
 import pytest
 import torch
-from PIL import Image
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
 
 
-def test_h3_profiler_targets_cover_reference_encoders_and_vae_decoders():
+def test_h3_full_pipeline_profiler_includes_local_encoding():
     from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
 
     targets = MiniMaxH3Pipeline._PROFILER_TARGETS
-    assert "_encode_visual_conditions" in targets
-    assert "_encode_reference_audio_conditions" in targets
-    assert "video_vae.decode_latent" in targets
-    assert "audio_vae.decode_latent" in targets
-    assert "_encode_video_conditions" not in targets
-    assert "_encode_video_audio_conditions" not in targets
-    assert "_encode_audio_conditions" not in targets
-
-
-@pytest.mark.parametrize("distributed", [False, True])
-def test_manual_component_offload_wins_over_requested_model_offload(distributed):
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.od_config = SimpleNamespace(
-        enable_cpu_offload=True,
-        enable_layerwise_offload=not distributed,
-        enable_distributed_layerwise_offload=distributed,
-    )
-    pipeline._model_cpu_offload_modules = []
-    pipeline.text_encoder = Mock()
-    expected = torch.ones(2, 3)
-    pipeline.text_encoder.encode_ids.return_value = expected
-    component = Mock()
-
-    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
-    with pipeline._component_on_device(component):
-        component.load_to_device.assert_called_once_with()
-        component.offload_to_cpu.assert_not_called()
-
-    assert actual is expected
-    pipeline.text_encoder.load_to_device.assert_called_once_with()
-    pipeline.text_encoder.offload_to_cpu.assert_called_once_with()
-    component.offload_to_cpu.assert_called_once_with()
-
-
-def test_requested_model_offload_without_backend_uses_resident_components():
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    pipeline.od_config = SimpleNamespace(
-        enable_cpu_offload=True,
-        enable_layerwise_offload=False,
-        enable_distributed_layerwise_offload=False,
-    )
-    pipeline._model_cpu_offload_modules = []
-    pipeline.text_encoder = Mock()
-    expected = torch.ones(2, 3)
-    pipeline.text_encoder.encode_ids.return_value = expected
-
-    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
-
-    assert actual is expected
-    pipeline.text_encoder.load_to_device.assert_called_once_with()
-    pipeline.text_encoder.encode_ids.assert_called_once()
+    assert targets == [
+        "encode_prompt",
+        "_encode_local_media",
+        "diffuse",
+        "decode",
+        "video_vae.decode_latent",
+        "audio_vae.decode_latent",
+        "prepare_encode",
+        "denoise_step",
+        "post_decode",
+    ]
 
 
 def test_decoded_output_is_unchanged_without_active_model_offload():
@@ -194,7 +147,7 @@ def decode(video_latent, audio_latent, *, height, width):
         _extract_prompt=lambda raw: ("a prompt", {}),
         _extract_text_conditioning=lambda raw: None,
         _extract_prepared_reference_videos=lambda raw: None,
-        _prepare_request_inputs=lambda **kwargs: context,
+        _prepare_request_inputs=lambda *args, **kwargs: context,
         _denoise_kwargs=lambda ctx: {},
         diffuse=diffuse,
         decode=decode,
@@ -243,7 +196,7 @@ def decode(video_latent, audio_latent, *, height, width):
         _extract_prompt=lambda raw: ("a prompt", {}),
         _extract_text_conditioning=lambda raw: None,
         _extract_prepared_reference_videos=lambda raw: None,
-        _prepare_request_inputs=lambda **kwargs: context,
+        _prepare_request_inputs=lambda *args, **kwargs: context,
         _denoise_kwargs=lambda ctx: {},
         diffuse=diffuse,
         decode=decode,
@@ -318,7 +271,8 @@ def test_output_owner_rank_matches_executor_contract(monkeypatch, available, ini
     assert MiniMaxH3Pipeline._is_output_owner_rank() is expected
 
 
-def test_h3_model_cpu_offload_registers_direct_vae_stages(monkeypatch):
+@pytest.mark.parametrize("load_text_encoder", [True, False])
+def test_h3_model_cpu_offload_registers_direct_vae_stages(monkeypatch, load_text_encoder):
     from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
     from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as module
 
@@ -326,9 +280,11 @@ def test_h3_model_cpu_offload_registers_direct_vae_stages(monkeypatch):
     torch.nn.Module.__init__(pipeline)
     pipeline.transformer = torch.nn.Linear(2, 2)
     pipeline.transformers_ref = torch.nn.Linear(2, 2)
-    pipeline.text_encoder = torch.nn.Linear(2, 2)
     pipeline.video_vae = torch.nn.Linear(2, 2)
     pipeline.audio_vae = torch.nn.Linear(2, 2)
+    pipeline._encoder_modules = ["text_encoder"] if load_text_encoder else []
+    if load_text_encoder:
+        pipeline.text_encoder = torch.nn.Linear(2, 2)
     apply_offload = Mock()
     remove_offload = Mock()
     monkeypatch.setattr(module, "apply_sequential_offload", apply_offload)
@@ -341,7 +297,7 @@ def test_h3_model_cpu_offload_registers_direct_vae_stages(monkeypatch):
     )
 
     dits = [pipeline.transformer, pipeline.transformers_ref]
-    stages = [pipeline.text_encoder, pipeline.video_vae, pipeline.audio_vae]
+    stages = [*([pipeline.text_encoder] if load_text_encoder else []), pipeline.video_vae, pipeline.audio_vae]
     apply_offload.assert_called_once_with(
         dit_modules=dits,
         encoder_modules=stages,
@@ -356,6 +312,46 @@ def test_h3_model_cpu_offload_registers_direct_vae_stages(monkeypatch):
     remove_offload.assert_called_once_with([*dits, *stages])
 
 
+@pytest.mark.parametrize("decode_fails", [False, True])
+def test_h3_model_cpu_offload_scopes_direct_vae_call(monkeypatch, decode_fails):
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as module
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    component = torch.nn.Linear(2, 2)
+    events: list[tuple[Any, ...]] = []
+
+    @contextmanager
+    def record_component(value):
+        events.append(("activate", value))
+        try:
+            yield
+        finally:
+            events.append(("offload", value))
+
+    monkeypatch.setattr(module, "sequential_offload_component", record_component)
+    pipeline._model_cpu_offload_modules = [component]
+
+    def decode():
+        with pipeline._component_on_device(component):
+            events.append(("decode", component))
+            if decode_fails:
+                raise RuntimeError("decode failed")
+
+    if decode_fails:
+        with pytest.raises(RuntimeError, match="decode failed"):
+            decode()
+    else:
+        decode()
+
+    assert events == [
+        ("activate", component),
+        ("decode", component),
+        ("offload", component),
+    ]
+
+
 def test_h3_model_cpu_offload_keeps_unselected_vaes_resident(monkeypatch):
     from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
     from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as module
@@ -416,44 +412,20 @@ def test_h3_model_cpu_offload_rejects_unloaded_selected_encoder(monkeypatch):
     apply_offload.assert_not_called()
 
 
-@pytest.mark.parametrize("decode_fails", [False, True])
-def test_h3_model_cpu_offload_scopes_direct_vae_call(monkeypatch, decode_fails):
-    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
-    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as module
-
-    pipeline = object.__new__(MiniMaxH3Pipeline)
-    torch.nn.Module.__init__(pipeline)
-    component = torch.nn.Linear(2, 2)
-    events: list[tuple[Any, ...]] = []
-
-    @contextmanager
-    def record_component(value):
-        events.append(("activate", value))
-        try:
-            yield
-        finally:
-            events.append(("offload", value))
-
-    monkeypatch.setattr(module, "sequential_offload_component", record_component)
-    pipeline._model_cpu_offload_modules = [component]
+def _encode_media(pipeline, **kwargs):
+    from vllm_omni.model_executor.models.minimax_h3.conditioning import MiniMaxH3EncoderMediaInput
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import encode_media
 
-    def decode():
-        with pipeline._component_on_device(component):
-            events.append(("decode", component))
-            if decode_fails:
-                raise RuntimeError("decode failed")
-
-    if decode_fails:
-        with pytest.raises(RuntimeError, match="decode failed"):
-            decode()
-    else:
-        decode()
-
-    assert events == [
-        ("activate", component),
-        ("decode", component),
-        ("offload", component),
-    ]
+    media = MiniMaxH3EncoderMediaInput(
+        task="ref2va", height=32, width=32, num_frames=124, latent_t=31, audio_t=208, **kwargs
+    )
+    return encode_media(
+        media,
+        video_vae=getattr(pipeline, "video_vae", None),
+        audio_vae=getattr(pipeline, "audio_vae", None),
+        emit_conditioning=True,
+        component_scope=pipeline._component_on_device,
+    )
 
 
 @pytest.mark.parametrize("encode_fails", [False, True])
@@ -463,7 +435,6 @@ def test_h3_model_cpu_offload_batches_visual_reference_scope(monkeypatch, encode
 
     pipeline = object.__new__(MiniMaxH3Pipeline)
     torch.nn.Module.__init__(pipeline)
-    pipeline.device = torch.device("cpu")
     pipeline.video_vae = Mock()
     pipeline._model_cpu_offload_modules = [pipeline.video_vae]
     events = []
@@ -484,17 +455,15 @@ def encode_image(image):
 
     pipeline.video_vae.encode_image.side_effect = encode_image
     monkeypatch.setattr(module, "sequential_offload_component", record_component)
-    monkeypatch.setattr(module, "_dit_rank_world", lambda: (None, 0, 1))
-    monkeypatch.setattr(module, "_broadcast_tensor", lambda value, **kwargs: value)
-    images = [Image.new("RGB", (16, 16)), Image.new("RGB", (32, 16))]
+    images = (torch.zeros(16, 16, 3, dtype=torch.uint8), torch.zeros(16, 32, 3, dtype=torch.uint8))
 
     if encode_fails:
         with pytest.raises(RuntimeError, match="encode failed"):
-            pipeline._encode_visual_conditions(images, None, video_count=0)
+            _encode_media(pipeline, images=images)
     else:
-        rows, shapes = pipeline._encode_visual_conditions(images, None, video_count=0)
-        assert rows.shape == (3, 4)
-        assert shapes == [(1, 1, 1), (1, 1, 2)]
+        result = _encode_media(pipeline, images=images)
+        assert result.visual_condition.shape == (3, 4)
+        assert result.visual_condition_shapes == ((1, 1, 1), (1, 1, 2))
 
     assert events == [
         ("activate", pipeline.video_vae),
@@ -510,9 +479,7 @@ def test_h3_model_cpu_offload_shares_image_and_video_scope(monkeypatch):
 
     pipeline = object.__new__(MiniMaxH3Pipeline)
     torch.nn.Module.__init__(pipeline)
-    pipeline.device = torch.device("cpu")
     pipeline.video_vae = Mock()
-    pipeline.video_vae.is_distributed_enabled.return_value = False
     pipeline._model_cpu_offload_modules = [pipeline.video_vae]
     events = []
 
@@ -529,31 +496,26 @@ def encode_image(image):
         return torch.ones(1, 4)
 
     def encode_video(frames):
-        events.append(("video", frames))
+        events.append(("video", frames.shape))
         return torch.ones(3, 4), (3, 2, 2)
 
     pipeline.video_vae.encode_image.side_effect = encode_image
     pipeline.video_vae.encode_video.side_effect = encode_video
     monkeypatch.setattr(module, "sequential_offload_component", record_component)
-    monkeypatch.setattr(module, "_dit_rank_world", lambda: (None, 0, 1))
-    monkeypatch.setattr(module, "_broadcast_tensor", lambda value, **kwargs: value)
-    monkeypatch.setattr(module, "load_video_frames", lambda path: f"frames:{path}")
-    images = [Image.new("RGB", (16, 16)), Image.new("RGB", (32, 16))]
-    prepared_videos = [{"prepared_path": "reference.mp4"}]
-
-    rows, shapes = pipeline._encode_visual_conditions(
-        images,
-        prepared_videos,
-        video_count=1,
+    result = _encode_media(
+        pipeline,
+        images=(torch.zeros(16, 16, 3, dtype=torch.uint8), torch.zeros(16, 32, 3, dtype=torch.uint8)),
+        videos=(torch.zeros(12, 32, 32, 3, dtype=torch.uint8),),
+        video_audios=(None,),
     )
 
-    assert rows.shape == (5, 4)
-    assert shapes == [(1, 1, 1), (1, 1, 2), (3, 2, 2)]
+    assert result.visual_condition.shape == (5, 4)
+    assert result.visual_condition_shapes == ((1, 1, 1), (1, 1, 2), (3, 2, 2))
     assert events == [
         ("activate", pipeline.video_vae),
         ("image", (16, 16)),
         ("image", (32, 16)),
-        ("video", "frames:reference.mp4"),
+        ("video", (12, 32, 32, 3)),
         ("offload", pipeline.video_vae),
     ]
 
@@ -567,7 +529,7 @@ def test_h3_model_cpu_offload_shares_embedded_and_standalone_audio_scope(monkeyp
     torch.nn.Module.__init__(pipeline)
     pipeline.audio_vae = Mock()
     pipeline._model_cpu_offload_modules = [pipeline.audio_vae]
-    events: list[tuple[Any, ...]] = []
+    events = []
 
     @contextmanager
     def record_component(value):
@@ -577,26 +539,20 @@ def record_component(value):
         finally:
             events.append(("offload", value))
 
-    def encode_embedded(*args, **kwargs):
-        events.append(("embedded",))
+    def encode_waveform(waveform, sample_rate):
+        events.append(("audio", int(waveform[0]), sample_rate))
         if encode_fails:
             raise RuntimeError("audio encode failed")
-        return torch.ones(1, 2), [1]
+        return torch.ones(80, 32), 80
 
-    def encode_standalone(*args, **kwargs):
-        events.append(("standalone",))
-        return torch.ones(1, 2), [1]
-
-    pipeline._encode_video_audio_conditions_resident = encode_embedded
-    pipeline._encode_audio_conditions_resident = encode_standalone
+    pipeline.audio_vae.encode_waveform.side_effect = encode_waveform
     monkeypatch.setattr(module, "sequential_offload_component", record_component)
 
     def call():
-        return pipeline._encode_reference_audio_conditions(
-            [{"input_has_audio": True}],
-            has_audio=[True],
-            standalone_audios=[(torch.ones(1), 16_000)],
-            max_duration_seconds=1.0,
+        return _encode_media(
+            pipeline,
+            video_audios=(),
+            audios=((torch.ones(32_000), 16_000),),
         )
 
     if encode_fails:
@@ -604,10 +560,61 @@ def call():
             call()
     else:
         result = call()
-        assert result[0].shape == (1, 2)
-        assert result[2].shape == (1, 2)
+        assert result.audio_condition.shape == (80, 32)
+        assert result.audio_condition_lengths == (80,)
+        assert events[1:-1] == [("audio", 1, 16_000)]
 
     assert events[0] == ("activate", pipeline.audio_vae)
     assert events[-1] == ("offload", pipeline.audio_vae)
     assert events.count(("activate", pipeline.audio_vae)) == 1
     assert events.count(("offload", pipeline.audio_vae)) == 1
+
+
+@pytest.mark.parametrize("distributed", [False, True])
+def test_manual_component_offload_wins_over_requested_model_offload(distributed):
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = SimpleNamespace(
+        enable_cpu_offload=True,
+        enable_layerwise_offload=not distributed,
+        enable_distributed_layerwise_offload=distributed,
+    )
+    pipeline._model_cpu_offload_modules = []
+    pipeline.text_encoder = Mock()
+    expected = torch.ones(2, 3)
+    pipeline.text_encoder.encode_ids.return_value = expected
+    component = Mock()
+
+    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
+    with pipeline._component_on_device(component):
+        component.load_to_device.assert_called_once_with()
+        component.offload_to_cpu.assert_not_called()
+
+    assert actual is expected
+    pipeline.text_encoder.load_to_device.assert_called_once_with()
+    pipeline.text_encoder.offload_to_cpu.assert_called_once_with()
+    component.offload_to_cpu.assert_called_once_with()
+
+
+def test_requested_model_offload_without_backend_uses_resident_components():
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.od_config = SimpleNamespace(
+        enable_cpu_offload=True,
+        enable_layerwise_offload=False,
+        enable_distributed_layerwise_offload=False,
+    )
+    pipeline._model_cpu_offload_modules = []
+    pipeline.text_encoder = Mock()
+    expected = torch.ones(2, 3)
+    pipeline.text_encoder.encode_ids.return_value = expected
+
+    actual = pipeline._encode_text_hidden(torch.tensor([1, 2]), {})
+
+    assert actual is expected
+    pipeline.text_encoder.load_to_device.assert_called_once_with()
+    pipeline.text_encoder.encode_ids.assert_called_once()
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
index c7e53ca626b..ba0e0ddf55f 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
@@ -186,9 +186,8 @@ def test_minimax_h3_quantization_quality(config: QualityTestConfig):
     common_kwargs = {
         "model": model_ref,
         "enforce_eager": True,
-        "tensor_parallel_size": 2,
         # The fused BF16 baseline only fits on H100-80GB with encoder TP.
-        "text_encoder_tp_size": 2,
+        "stage_0_tensor_parallel_size": 2,
         "vae_use_tiling": True,
     }
 
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_step_execution.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_step_execution.py
index 1b123929c35..e202c0d0ee4 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_step_execution.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_step_execution.py
@@ -110,6 +110,8 @@ def _step_pipeline(model, *, packed_batch_supported: bool = True):
     from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import MiniMaxH3Pipeline
 
     pipeline = object.__new__(MiniMaxH3Pipeline)
+    pipeline.load_text_encoder = False
+    pipeline.load_vae_encoder = False
     pipeline.transformer = model
     pipeline.device = torch.device("cpu")
     pipeline._transformer_for_task = lambda task: model
@@ -304,8 +306,17 @@ def test_prepare_encode_seeds_runner_visible_state(monkeypatch, batch_frames):
     }
 
     pipeline = _step_pipeline(_SegmentMeanModel())
-    monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_extract_prompt", staticmethod(lambda _: ("a prompt", {})))
-    monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_prepare_request_inputs", lambda self, **_: context)
+    conditioning = object()
+    monkeypatch.setattr(
+        mod.MiniMaxH3Pipeline,
+        "_extract_encoder_conditioning",
+        staticmethod(lambda _: conditioning),
+    )
+    monkeypatch.setattr(
+        mod.MiniMaxH3Pipeline,
+        "_prepare_encoder_conditioning_inputs",
+        lambda self, value, sampling: context,
+    )
     monkeypatch.setattr(
         mod.MiniMaxH3Pipeline,
         "_build_denoise_inputs",
@@ -439,50 +450,3 @@ def test_packed_batch_rejects_backends_that_cannot_isolate_requests(attention):
     from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import MiniMaxH3Pipeline
 
     assert MiniMaxH3Pipeline._packed_batch_supported(_FakeTransformer([attention])) is False
-
-
-def test_broadcast_rank0_exception_single_rank_reraises():
-    """Single-rank execution has no group; the helper just reraises."""
-    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-        _broadcast_rank0_exception,
-    )
-    from vllm_omni.errors import OmniClientError
-
-    _broadcast_rank0_exception(None)
-    with pytest.raises(OmniClientError, match="bad ref"):
-        _broadcast_rank0_exception(OmniClientError("bad ref"))
-
-
-def test_broadcast_rank0_exception_propagates_to_non_zero_ranks(monkeypatch):
-    """A rank-0 error becomes a matching client error on every other DiT rank."""
-    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
-    from vllm_omni.errors import OmniClientError
-
-    def fake_rank_world(rank):
-        return lambda: (object(), rank, 4)
-
-    def make_broadcast(rank0_payload):
-        def fake_broadcast(payload_list, *, src, group):
-            payload_list[0] = rank0_payload
-
-        return fake_broadcast
-
-    monkeypatch.setattr(mod, "_dit_rank_world", fake_rank_world(0))
-    err = OmniClientError("invalid reference-video file", status_code=422, error_type="UnprocessableEntityError")
-    rank0_payload = {
-        "type": type(err).__name__,
-        "message": str(err),
-        "status_code": err.status_code,
-        "error_type": err.error_type,
-    }
-    monkeypatch.setattr(mod.dist, "broadcast_object_list", make_broadcast(rank0_payload))
-    with pytest.raises(OmniClientError) as rank0_info:
-        mod._broadcast_rank0_exception(err)
-    assert rank0_info.value is err
-
-    monkeypatch.setattr(mod, "_dit_rank_world", fake_rank_world(2))
-    with pytest.raises(OmniClientError) as rank2_info:
-        mod._broadcast_rank0_exception(None)
-    assert rank2_info.value.status_code == 422
-    assert rank2_info.value.error_type == "UnprocessableEntityError"
-    assert "invalid reference-video file" in str(rank2_info.value)
diff --git a/tests/model_executor/models/test_minimax_h3_encoder_payload.py b/tests/model_executor/models/test_minimax_h3_encoder_payload.py
new file mode 100644
index 00000000000..4c9a7137bc5
--- /dev/null
+++ b/tests/model_executor/models/test_minimax_h3_encoder_payload.py
@@ -0,0 +1,406 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from contextlib import contextmanager
+from types import SimpleNamespace
+
+import pytest
+import torch
+
+from vllm_omni.data_entry_keys import flatten_payload
+from vllm_omni.model_executor.models.minimax_h3.conditioning import (
+    MiniMaxH3EncoderConditioning,
+    MiniMaxH3EncoderMediaConditioning,
+    MiniMaxH3EncoderMediaInput,
+)
+from vllm_omni.model_executor.stage_input_processors.minimax_h3 import encoder2diffusion
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_pipeline_owns_three_encoders_then_dit_and_decoders() -> None:
+    from vllm_omni.model_executor.models.minimax_h3.pipeline import MINIMAX_H3_PIPELINE
+
+    encoder, diffusion = MINIMAX_H3_PIPELINE.stages
+    assert encoder.model_arch == "MiniMaxH3Encoder"
+    assert encoder.custom_process_next_stage_input_func is None
+    assert diffusion.model_arch == "MiniMaxH3Pipeline"
+    assert diffusion.requires_multimodal_data is False
+    assert diffusion.requires_full_payload_input is False
+
+
+def _patch_encoder_constructors(monkeypatch, *, rank: int):
+    from vllm_omni.model_executor.models.minimax_h3 import encoder as encoder_module
+
+    group = SimpleNamespace(rank_in_group=rank, world_size=2, device_group=object())
+
+    class FakeVideoVAE(torch.nn.Module):
+        def __init__(self, path, *, device, encode_only, trust_remote_code):
+            super().__init__()
+            self.path = path
+            self.parallel_args = None
+            self.trust_remote_code = trust_remote_code
+
+        def set_parallel_size(self, size, *, process_group):
+            self.parallel_args = (size, process_group)
+
+    class FakeAudioVAE(torch.nn.Module):
+        def __init__(self, path, *, device, encode_only, trust_remote_code):
+            super().__init__()
+            self.path = path
+            self.trust_remote_code = trust_remote_code
+
+    def init_backbone(self, *, vllm_config, prefix):
+        torch.nn.Module.__init__(self)
+
+    monkeypatch.setattr(encoder_module.MiniMaxH3TextEncoderBackbone, "__init__", init_backbone)
+    monkeypatch.setattr(encoder_module, "get_tp_group", lambda: group)
+    monkeypatch.setattr(encoder_module, "get_local_device", lambda: torch.device("cpu"))
+    monkeypatch.setattr(encoder_module, "MiniMaxH3VideoVAE", FakeVideoVAE)
+    monkeypatch.setattr(encoder_module, "MiniMaxH3AudioVAE", FakeAudioVAE)
+    return encoder_module, group
+
+
+def _component_root(tmp_path):
+    root = tmp_path / "FL2VA"
+    for name in ("text_encoder", "video_vae", "audio_vae"):
+        (root / name).mkdir(parents=True)
+    return root
+
+
+def _encoder_config(root, *, video_mode="patch", roles=None, trust_remote_code=True):
+    components = (
+        {
+            "text_encoder": {"parallel_mode": "tp"},
+            "video_vae": {"parallel_mode": video_mode},
+            "audio_vae": {"parallel_mode": "leader"},
+        }
+        if roles is None
+        else roles
+    )
+    return SimpleNamespace(
+        model_config=SimpleNamespace(
+            model=str(root / "text_encoder"),
+            hf_config=SimpleNamespace(minimax_h3_encoder_components=components),
+            trust_remote_code=trust_remote_code,
+        )
+    )
+
+
+def test_encoder_requires_exactly_three_components(monkeypatch, tmp_path) -> None:
+    encoder_module, _ = _patch_encoder_constructors(monkeypatch, rank=0)
+    root = tmp_path / "FL2VA"
+    (root / "text_encoder").mkdir(parents=True)
+    (root / "video_vae").mkdir()
+    config = _encoder_config(root)
+
+    with pytest.raises(RuntimeError, match=r"requires all three encoders.*audio_vae"):
+        encoder_module.MiniMaxH3Encoder(vllm_config=config)
+
+
+@pytest.mark.parametrize(("rank", "has_audio_vae"), [(0, True), (1, False)])
+@pytest.mark.parametrize("trust_remote_code", [False, True])
+def test_encoder_uses_tp_patch_and_leader_on_the_same_rank_set(
+    monkeypatch,
+    tmp_path,
+    rank,
+    has_audio_vae,
+    trust_remote_code,
+) -> None:
+    encoder_module, group = _patch_encoder_constructors(monkeypatch, rank=rank)
+    root = _component_root(tmp_path)
+    config = _encoder_config(root, trust_remote_code=trust_remote_code)
+
+    model = encoder_module.MiniMaxH3Encoder(vllm_config=config)
+
+    assert model.component_config.text_parallel_mode == "tp"
+    assert model.component_config.video_parallel_mode == "patch"
+    assert model.component_config.audio_parallel_mode == "leader"
+    assert model.video_vae.parallel_args == (2, group.device_group)
+    assert model.video_vae.trust_remote_code is trust_remote_code
+    assert (model.audio_vae is not None) is has_audio_vae
+    if has_audio_vae:
+        assert model.audio_vae.trust_remote_code is trust_remote_code
+
+
+@pytest.mark.parametrize("component", ["video", "audio"])
+@pytest.mark.parametrize("trusted", [False, True])
+def test_encoder_only_vae_requires_remote_code_trust(monkeypatch, component, trusted) -> None:
+    from vllm_omni.diffusion.models.minimax_h3 import vae as vae_module
+
+    config = {"auto_map": {"AutoModel": "modeling.RemoteVAE"}, "sample_rate": 32000}
+    monkeypatch.setattr(vae_module, "_load_component_config", lambda _path: config)
+    remote = torch.nn.Module()
+    remote.model = torch.nn.Module()
+    calls = []
+
+    def load_encoder(path, config_dict):
+        calls.append((path, config_dict))
+        return remote
+
+    monkeypatch.setattr(vae_module, f"_load_{component}_vae_encoder", load_encoder)
+    vae_cls = vae_module.MiniMaxH3VideoVAE if component == "video" else vae_module.MiniMaxH3AudioVAE
+    if trusted:
+        model = vae_cls("unused", device=torch.device("cpu"), encode_only=True, trust_remote_code=True)
+        assert model.remote is remote
+        assert calls == [("unused", config)]
+    else:
+        with pytest.raises(ValueError, match="trust-remote-code"):
+            vae_cls("unused", device=torch.device("cpu"), encode_only=True)
+        assert calls == []
+
+
+def test_encoder_requires_all_role_policies(monkeypatch, tmp_path) -> None:
+    encoder_module, _ = _patch_encoder_constructors(monkeypatch, rank=0)
+    root = _component_root(tmp_path)
+    config = _encoder_config(
+        root,
+        roles={
+            "text_encoder": {"parallel_mode": "tp"},
+            "video_vae": {"parallel_mode": "patch"},
+        },
+    )
+
+    with pytest.raises(ValueError, match=r"requires exactly.*audio_vae"):
+        encoder_module.MiniMaxH3Encoder(vllm_config=config)
+
+
+def test_encoder_does_not_infer_role_policies(monkeypatch, tmp_path) -> None:
+    encoder_module, _ = _patch_encoder_constructors(monkeypatch, rank=0)
+    root = _component_root(tmp_path)
+    config = SimpleNamespace(
+        model_config=SimpleNamespace(
+            model=str(root / "text_encoder"),
+            hf_config=SimpleNamespace(),
+        )
+    )
+
+    with pytest.raises(ValueError, match="requires explicit minimax_h3_encoder_components"):
+        encoder_module.MiniMaxH3Encoder(vllm_config=config)
+
+
+def test_video_leader_policy_skips_nonleader(monkeypatch, tmp_path) -> None:
+    encoder_module, _ = _patch_encoder_constructors(monkeypatch, rank=1)
+    root = _component_root(tmp_path)
+    model = encoder_module.MiniMaxH3Encoder(vllm_config=_encoder_config(root, video_mode="leader"))
+
+    assert model.video_vae is None
+    assert model.audio_vae is None
+    assert (
+        model._encode_media(
+            MiniMaxH3EncoderMediaInput(
+                task="ref2va",
+                height=32,
+                width=32,
+                num_frames=48,
+                latent_t=1,
+                audio_t=80,
+                images=(torch.zeros(32, 32, 3, dtype=torch.uint8),),
+            )
+        )
+        is None
+    )
+
+
+def test_encoder_runs_video_and_audio_components_on_ar_model() -> None:
+    from vllm_omni.model_executor.models.minimax_h3.encoder import MiniMaxH3Encoder
+
+    class VideoVAE:
+        def encode_image(self, _image):
+            return torch.ones(1, 96)
+
+        def encode_video(self, _frames):
+            return torch.full((1, 96), 2.0), (1, 2, 2)
+
+    class AudioVAE:
+        def encode_waveform(self, waveform, _sample_rate):
+            return torch.ones(160, 32), waveform.shape[-1] // 800
+
+    model = MiniMaxH3Encoder.__new__(MiniMaxH3Encoder)
+    torch.nn.Module.__init__(model)
+    model._component_leader = True
+    model.video_vae = VideoVAE()
+    model.audio_vae = AudioVAE()
+    media = MiniMaxH3EncoderMediaInput(
+        task="ref2va",
+        height=32,
+        width=32,
+        num_frames=48,
+        latent_t=1,
+        audio_t=80,
+        images=(torch.zeros(32, 32, 3, dtype=torch.uint8),),
+        videos=(torch.zeros(1, 32, 32, 3, dtype=torch.uint8),),
+        video_audios=((torch.zeros(64_000), 32_000),),
+    )
+
+    conditioning = model._encode_media(media)
+
+    assert conditioning is not None
+    assert conditioning.visual_condition_shapes == ((1, 2, 2), (1, 2, 2))
+    assert conditioning.audio_condition_lengths == (80,)
+    assert conditioning.ref_blocks[1]["kind"] == "video_audio"
+
+
+def test_prepare_encoder_inputs_keeps_reference_audio_budgets_separate(monkeypatch) -> None:
+    from vllm_omni.model_executor.models.minimax_h3 import encoder_processing as processing
+
+    frames = torch.zeros(1, 32, 32, 3, dtype=torch.uint8).numpy()
+    waveform = torch.zeros(320_000)
+    monkeypatch.setattr(processing, "resolve_minimax_h3_shape", lambda *_args: (32, 32, 240, 60, 400))
+    monkeypatch.setattr(
+        processing,
+        "prepare_reference_videos",
+        lambda *_args, **_kwargs: [
+            {"prepared_path": "prepared.mp4", "original_path": "reference.mp4", "input_has_audio": True}
+        ],
+    )
+    monkeypatch.setattr(processing, "load_video_frames", lambda _path: frames)
+    monkeypatch.setattr(
+        processing,
+        "sample_reference_video_frames",
+        lambda *_args, **_kwargs: {"frames": [frames[0]], "block_timestamps": [[0.0]]},
+    )
+    monkeypatch.setattr(processing, "load_video_audio", lambda *_args, **_kwargs: (waveform, 32_000))
+
+    prepared = processing.prepare_encoder_inputs(
+        {
+            "prompt": "reference",
+            "multi_modal_data": {"video": "reference.mp4", "audio": (waveform, 32_000)},
+        },
+        SimpleNamespace(extra_args={"task": "ref2va"}),
+    )
+
+    assert prepared.media.video_audios[0][0].shape[-1] == 320_000
+    assert prepared.media.audios[0][0].shape[-1] == 320_000
+    assert prepared.condition_labels == [("audio", 1), ("video", 1), ("audio", 2)]
+
+
+@pytest.mark.parametrize(
+    ("embedded_lengths", "standalone_lengths", "valid"),
+    [((400,), (400,), True), ((320, 320), (400,), False), ((400,), (320, 320), False)],
+)
+def test_encode_media_keeps_audio_budgets_and_component_residency_separate(
+    embedded_lengths, standalone_lengths, valid
+) -> None:
+    from vllm_omni.model_executor.models.minimax_h3.encoder_processing import encode_media
+
+    active = None
+    scopes = []
+
+    class VideoVAE:
+        def encode_image(self, _image):
+            assert active is self
+            return torch.ones(1, 96)
+
+        def encode_video(self, _frames):
+            assert active is self
+            return torch.ones(1, 96), (1, 2, 2)
+
+    class AudioVAE:
+        def encode_waveform(self, waveform, _sample_rate):
+            assert active is self
+            length = waveform.shape[-1] // 800
+            return torch.ones(2 * length, 32), length
+
+    @contextmanager
+    def component_scope(component):
+        nonlocal active
+        assert active is None
+        active = component
+        scopes.append(component)
+        try:
+            yield
+        finally:
+            active = None
+
+    video_vae = VideoVAE()
+    audio_vae = AudioVAE()
+    media = MiniMaxH3EncoderMediaInput(
+        task="ref2va",
+        height=32,
+        width=32,
+        num_frames=360,
+        latent_t=90,
+        audio_t=600,
+        images=(torch.zeros(32, 32, 3, dtype=torch.uint8),),
+        videos=tuple(torch.zeros(1, 32, 32, 3, dtype=torch.uint8) for _ in embedded_lengths),
+        video_audios=tuple((torch.zeros(length * 800), 32_000) for length in embedded_lengths),
+        audios=tuple((torch.zeros(length * 800), 32_000) for length in standalone_lengths),
+    )
+    kwargs = dict(video_vae=video_vae, audio_vae=audio_vae, emit_conditioning=True, component_scope=component_scope)
+    if valid:
+        conditioning = encode_media(media, **kwargs)
+        assert conditioning.audio_condition_lengths == embedded_lengths + standalone_lengths
+        assert [block["kind"] for block in conditioning.ref_blocks] == ["image", "video_audio", "audio"]
+        conditioning.to_omni_components()
+    else:
+        with pytest.raises(ValueError, match="at most 15 seconds"):
+            encode_media(media, **kwargs)
+    assert scopes == [video_vae, audio_vae]
+
+
+def test_encoder_output_reuses_encoder_handoff_and_round_trips() -> None:
+    expected = MiniMaxH3EncoderConditioning(
+        hidden_states=torch.randn(3, 5120, dtype=torch.bfloat16),
+        token_tags=torch.tensor([1, 0, 1], dtype=torch.int64),
+        task="t2va",
+        height=256,
+        width=448,
+        num_frames=17,
+        latent_t=5,
+        audio_t=10,
+    )
+
+    source = SimpleNamespace(
+        finished=True,
+        request_id="request-1",
+        outputs=[SimpleNamespace(multimodal_output=flatten_payload(expected.to_omni_payload()))],
+    )
+    prompt = {
+        "prompt": "hello",
+        "additional_information": {"global_request_id": ["request-1"]},
+    }
+
+    result = encoder2diffusion([source], prompt)
+
+    assert result is not None
+    payload = result["additional_information"]["encoder_output"]
+    actual = MiniMaxH3EncoderConditioning.from_omni_payload(payload)
+    torch.testing.assert_close(actual.hidden_states, expected.hidden_states)
+    torch.testing.assert_close(actual.token_tags, expected.token_tags)
+
+
+def test_encoder_releases_workspace_after_cpu_payload(monkeypatch) -> None:
+    from vllm_omni.model_executor.models.minimax_h3 import encoder as encoder_module
+
+    model = encoder_module.MiniMaxH3Encoder.__new__(encoder_module.MiniMaxH3Encoder)
+    torch.nn.Module.__init__(model)
+    model._component_leader = True
+    model._token_tags = torch.tensor([1])
+    info = {
+        "meta": {"minimax_h3_encoder_request": {}},
+        "_minimax_h3_encoder_media_conditioning": MiniMaxH3EncoderMediaConditioning(
+            task="t2va",
+            height=256,
+            width=448,
+            num_frames=17,
+            latent_t=5,
+            audio_t=10,
+        ),
+    }
+    empty_cache_calls = 0
+
+    def empty_cache() -> None:
+        nonlocal empty_cache_calls
+        empty_cache_calls += 1
+
+    monkeypatch.setattr(torch.accelerator, "empty_cache", empty_cache)
+    output = model.make_omni_output(
+        torch.zeros(1, 5120),
+        model_intermediate_buffer=[info],
+        request_sample_eligible=[True],
+    )
+
+    assert empty_cache_calls == 1
+    assert output.multimodal_outputs is not None
+    assert output.multimodal_outputs["embed"]["embedding"][0].device.type == "cpu"
diff --git a/tests/model_executor/stage_input_processors/test_minimax_h3.py b/tests/model_executor/stage_input_processors/test_minimax_h3.py
index 9fda899536c..aac16d29f51 100644
--- a/tests/model_executor/stage_input_processors/test_minimax_h3.py
+++ b/tests/model_executor/stage_input_processors/test_minimax_h3.py
@@ -2,8 +2,6 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Regression tests for MiniMax H3's disaggregated text-encoder contract."""
 
-import os
-import shutil
 from types import SimpleNamespace
 from unittest.mock import Mock
 
@@ -12,39 +10,37 @@
 import torch
 from PIL import Image
 
-from vllm_omni.data_entry_keys import OmniPayload, deserialize_payload, serialize_payload
-from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
-    _load_audio,
-    resolve_minimax_h3_diffusion_model_path,
+from vllm_omni.data_entry_keys import flatten_payload
+from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import resolve_minimax_h3_diffusion_model_path
+from vllm_omni.engine.serialization import (
+    deserialize_additional_information,
+    serialize_additional_information,
 )
+from vllm_omni.errors import OmniClientError
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.model_executor.models.minimax_h3.checkpoint import (
-    resolve_minimax_h3_model_root,
+    resolve_minimax_h3_encoder_model_root,
     resolve_minimax_h3_partition,
 )
 from vllm_omni.model_executor.models.minimax_h3.conditioning import (
     MINIMAX_H3_CONDITION_LABELS_KEY,
+    MINIMAX_H3_ENCODER_REQUEST_KEY,
     MINIMAX_H3_PRESENTATION_TASK_KEY,
-    MINIMAX_H3_TEXT_CONDITIONING_SCHEMA,
-    MiniMaxH3TextConditioning,
+    MiniMaxH3EncoderConditioning,
 )
+from vllm_omni.model_executor.models.minimax_h3.encoder_processing import _audio_items, _load_audio
 from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
     minimax_h3_ref2va_presentation,
     minimax_h3_ref2va_video_presentation,
 )
-from vllm_omni.model_executor.models.minimax_h3.reference_video import (
-    MINIMAX_H3_PREPARED_REFERENCE_VIDEOS_KEY,
-    deserialize_prepared_reference_videos,
-)
 from vllm_omni.model_executor.models.minimax_h3.text_encoder import (
     MiniMaxH3MultiModalProcessor,
     _build_minimax_h3_presentation,
 )
 from vllm_omni.model_executor.stage_input_processors.minimax_h3 import (
-    _audio_items,
     _diffusion_sampling_params,
-    prepare_text_encoder_prompt,
-    text_encoder2diffusion,
+    encoder2diffusion,
+    prepare_encoder_prompt,
 )
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
@@ -66,13 +62,14 @@ def convert_tokens_to_ids(self, token):
         return self._special_ids[token]
 
 
-def test_h3_processor_reprocesses_media_instead_of_using_partial_sender_cache(mocker):
+def test_h3_processor_reprocesses_media_instead_of_using_partial_sender_cache(monkeypatch):
     processor = object.__new__(MiniMaxH3MultiModalProcessor)
     sentinel = ([1, 2, 3], object(), True)
-    apply_processor = mocker.patch.object(
+    apply_processor = Mock(return_value=sentinel)
+    monkeypatch.setattr(
         MiniMaxH3MultiModalProcessor,
         "_apply_hf_processor",
-        return_value=sentinel,
+        apply_processor,
     )
     inputs = object()
     timing_ctx = object()
@@ -119,9 +116,11 @@ def test_fused_audio_loader_accepts_list_waveform_pair():
 def test_prepare_ref2va_keeps_original_text_and_exact_condition_order():
     prompt = {
         "prompt": "hello",
+        "additional_information": {"global_request_id": ["request-1"]},
+        "model_intermediate_buffer": {"private": "preserved"},
         "multi_modal_data": {
             "image": Image.new("RGB", (256, 256)),
-            "audio": [np.zeros(16), 16_000],
+            "audio": [np.zeros(32_000), 16_000],
         },
     }
     sampling = OmniDiffusionSamplingParams(
@@ -130,7 +129,7 @@ def test_prepare_ref2va_keeps_original_text_and_exact_condition_order():
         extra_args={"task": "ref2va"},
     )
 
-    transformed = prepare_text_encoder_prompt(prompt, [sampling])
+    transformed = prepare_encoder_prompt(prompt, [sampling])
 
     assert transformed["prompt"] == "hello"
     assert len(transformed["multi_modal_data"]["image"]) == 1
@@ -140,223 +139,148 @@ def test_prepare_ref2va_keeps_original_text_and_exact_condition_order():
         ("image", 1),
         ("audio", 1),
     ]
+    assert transformed["model_intermediate_buffer"] == {"private": "preserved"}
+    runner_info = transformed["additional_information"]
+    for _ in range(2):
+        wire = serialize_additional_information(runner_info)
+        runner_info = deserialize_additional_information(wire)
+    assert runner_info["global_request_id"] == ["request-1"]
+    request_metadata = runner_info["meta"][MINIMAX_H3_ENCODER_REQUEST_KEY]
+    assert request_metadata["task"] == "ref2va"
+    assert isinstance(
+        runner_info["hidden_states"]["layers"][0],
+        torch.Tensor,
+    )
+    assert isinstance(
+        runner_info["hidden_states"]["layers"][1],
+        torch.Tensor,
+    )
+    from vllm_omni.model_executor.models.minimax_h3.encoder import MiniMaxH3Encoder
 
-
-def test_text_encoder_prompt_rejects_injected_prepared_video_descriptor():
-    prompt = {
-        "prompt": "hello",
-        "additional_information": {"meta": {MINIMAX_H3_PREPARED_REFERENCE_VIDEOS_KEY: '{"artifact_dir":"/tmp/user"}'}},
-    }
-    sampling = OmniDiffusionSamplingParams(height=256, width=448, extra_args={"task": "t2va"})
-
-    transformed = prepare_text_encoder_prompt(prompt, [sampling])
-
-    assert MINIMAX_H3_PREPARED_REFERENCE_VIDEOS_KEY not in transformed["additional_information"]["meta"]
+    media = MiniMaxH3Encoder._media_input(runner_info)
+    assert media.task == "ref2va"
+    assert len(media.images) == 1
+    assert len(media.audios) == 1
 
 
-def test_prepare_ref2va_video_uses_shared_frame_sampler_once(monkeypatch):
-    prepare_videos = Mock()
+def _mock_ref2va_video_with_audio(monkeypatch, *, duration_seconds: float) -> None:
+    from vllm_omni.model_executor.models.minimax_h3 import encoder_processing
 
-    def prepare(_videos, *, target_frame_count, workdir, start_time_seconds):
-        prepare_videos(_videos, target_frame_count, workdir, start_time_seconds)
-        prepared_path = os.path.join(workdir, "prepared.mp4")
-        open(prepared_path, "wb").close()
-        return [
+    sample_rate = 16_000
+    frames = np.zeros((4, 32, 32, 3), dtype=np.uint8)
+    monkeypatch.setattr(
+        encoder_processing,
+        "prepare_reference_videos",
+        lambda *args, **kwargs: [
             {
-                "original_path": "/tmp/input.mp4",
-                "prepared_path": prepared_path,
+                "prepared_path": "prepared.mp4",
+                "original_path": "original.mp4",
                 "input_has_audio": True,
-                "width": 448,
-                "height": 256,
-                "start_time_seconds": 0.0,
-                "duration_seconds": 5.2,
-                "audio_duration_seconds": 5.2,
+                "duration_seconds": duration_seconds,
+                "audio_duration_seconds": duration_seconds,
             }
-        ]
-
-    sample_frames = Mock(return_value={"frames": [np.zeros((4, 4, 3), dtype=np.uint8)]})
-    monkeypatch.setattr("vllm_omni.model_executor.stage_input_processors.minimax_h3.prepare_reference_videos", prepare)
+        ],
+    )
+    monkeypatch.setattr(encoder_processing, "load_video_frames", lambda path: frames)
     monkeypatch.setattr(
-        "vllm_omni.model_executor.stage_input_processors.minimax_h3.sample_reference_video_frames",
-        sample_frames,
+        encoder_processing,
+        "sample_reference_video_frames",
+        lambda *args, **kwargs: {"block_timestamps": [0.0], "frames": frames[:1]},
+    )
+    monkeypatch.setattr(
+        encoder_processing,
+        "load_video_audio",
+        lambda *args, **kwargs: (torch.zeros(round(duration_seconds * sample_rate)), sample_rate),
     )
-    prompt = {
-        "prompt": "hello",
-        "multi_modal_data": {"video": "/tmp/input.mp4"},
-    }
-    sampling = OmniDiffusionSamplingParams(height=256, width=448, num_frames=124, extra_args={"task": "ref2va"})
-
-    transformed = prepare_text_encoder_prompt(prompt, [sampling])
-
-    prepare_videos.assert_called_once()
-    _, target_frame_count, artifact_dir, start_time_seconds = prepare_videos.call_args.args
-    assert target_frame_count == 124
-    assert start_time_seconds is None
-    descriptor = transformed["additional_information"]["meta"][MINIMAX_H3_PREPARED_REFERENCE_VIDEOS_KEY]
-    described_dir, described_videos = deserialize_prepared_reference_videos(descriptor)
-    assert described_dir == artifact_dir
-    assert os.path.isfile(described_videos[0]["prepared_path"])
-    sample_frames.assert_called_once_with(described_videos[0]["prepared_path"])
-    assert prompt["multi_modal_data"] == {"video": "/tmp/input.mp4"}
-    assert transformed["mm_processor_kwargs"][MINIMAX_H3_CONDITION_LABELS_KEY] == [
-        ("audio", 1),
-        ("video", 1),
-    ]
-    shutil.rmtree(artifact_dir)
 
 
-def test_stage_wire_rejects_multiple_text_encoder_sources():
-    with pytest.raises(RuntimeError, match="exactly one text-encoder source"):
-        text_encoder2diffusion([SimpleNamespace(), SimpleNamespace()], prompt={"prompt": "hello"})
+def test_prepare_ref2va_rejects_short_embedded_video_audio(monkeypatch):
+    _mock_ref2va_video_with_audio(monkeypatch, duration_seconds=1.0)
+    sampling = OmniDiffusionSamplingParams(
+        height=256,
+        width=448,
+        num_frames=96,
+        extra_args={"task": "ref2va"},
+    )
+    prompt = {"prompt": "hello", "multi_modal_data": {"video": "original.mp4"}}
 
+    with pytest.raises(OmniClientError, match=r"duration must be in \[2, 15\] seconds, got 1\.000"):
+        prepare_encoder_prompt(prompt, [sampling])
 
-def test_stage_wire_rejects_request_id_mismatch():
-    source = SimpleNamespace(request_id="other", outputs=[SimpleNamespace()])
+
+def test_prepare_ref2va_keeps_embedded_and_standalone_audio_budgets_separate(monkeypatch):
+    duration_seconds = 8.0
+    sample_rate = 16_000
+    _mock_ref2va_video_with_audio(monkeypatch, duration_seconds=duration_seconds)
+    sampling = OmniDiffusionSamplingParams(
+        height=256,
+        width=448,
+        num_frames=240,
+        extra_args={"task": "ref2va"},
+    )
     prompt = {
         "prompt": "hello",
-        "additional_information": {"global_request_id": ["req-1"]},
+        "multi_modal_data": {
+            "video": "original.mp4",
+            "audio": (torch.zeros(int(duration_seconds * sample_rate)), sample_rate),
+        },
     }
 
-    with pytest.raises(RuntimeError, match="request ID does not match"):
-        text_encoder2diffusion([source], prompt=prompt)
-
-
-def test_stage_wire_rejects_multiple_completions():
-    source = SimpleNamespace(request_id="req-1", outputs=[SimpleNamespace(), SimpleNamespace()])
-
-    with pytest.raises(RuntimeError, match="exactly one completion"):
-        text_encoder2diffusion([source], prompt={"prompt": "hello"})
+    transformed = prepare_encoder_prompt(prompt, [sampling])
+    assert transformed["mm_processor_kwargs"][MINIMAX_H3_CONDITION_LABELS_KEY] == [
+        ("audio", 1),
+        ("video", 1),
+        ("audio", 2),
+    ]
 
 
-def _source_output(payload: dict) -> SimpleNamespace:
-    completion = SimpleNamespace(multimodal_output=payload)
-    return SimpleNamespace(request_id="request-1", outputs=[completion])
+def _encoder_output() -> dict:
+    return MiniMaxH3EncoderConditioning(
+        hidden_states=torch.randn(3, 5120, dtype=torch.bfloat16),
+        token_tags=torch.tensor([1, 0, 1], dtype=torch.int64),
+        task="t2va",
+        height=256,
+        width=448,
+        num_frames=17,
+        latent_t=5,
+        audio_t=10,
+    ).to_omni_payload()
 
 
-def _diffusion_prompt() -> dict:
-    return {
-        "request_id": "request-1",
+def test_encoder2diffusion_reuses_encoder_handoff() -> None:
+    prompt = {
         "prompt": "test prompt",
-        "additional_information": {},
-    }
-
-
-def _valid_text_conditioning_payload() -> OmniPayload:
-    return {
-        "hidden_states": {
-            "output": torch.zeros(4, 5120, dtype=torch.bfloat16),
-        },
-        "meta": {
-            "token_role_ids": torch.tensor([[1], [1], [0], [0]], dtype=torch.int64),
+        "multi_modal_data": {"image": object()},
+        "additional_information": {
+            "private": "preserved",
+            "meta": {MINIMAX_H3_ENCODER_REQUEST_KEY: {"task": "t2va"}},
+            "hidden_states": {"layers": {0: torch.zeros(1)}},
         },
+        "model_intermediate_buffer": {"private": "encoder-only"},
     }
-
-
-def test_text_encoder2diffusion_reads_hidden_states_output_and_token_role_ids() -> None:
-    payload = _valid_text_conditioning_payload()
-    hidden = payload["hidden_states"]["output"]
-    token_role_ids = payload["meta"]["token_role_ids"]
-
-    result = text_encoder2diffusion(
-        [_source_output(payload)],
-        _diffusion_prompt(),
+    source = SimpleNamespace(
+        finished=True,
+        request_id="request-1",
+        outputs=[SimpleNamespace(multimodal_output=flatten_payload(_encoder_output()))],
     )
 
-    conditioning = result["additional_information"]["text_encoder_output"]
-    torch.testing.assert_close(conditioning["hidden_states"], hidden)
-    torch.testing.assert_close(conditioning["token_tags"], token_role_ids.squeeze(-1))
+    result = encoder2diffusion([source], prompt)
 
+    assert result["prompt"] == "test prompt"
+    assert result["multi_modal_data"] is None
+    assert "model_intermediate_buffer" not in result
+    additional_information = result["additional_information"]
+    assert additional_information["private"] == "preserved"
+    assert "hidden_states" not in additional_information
+    assert "meta" not in additional_information
+    parsed = MiniMaxH3EncoderConditioning.from_omni_payload(additional_information["encoder_output"])
+    assert parsed.task == "t2va"
 
-def test_text_conditioning_artifact_round_trips_through_omni_payload_wire_format() -> None:
-    payload = _valid_text_conditioning_payload()
 
-    wire = serialize_payload(payload)
-
-    assert wire is not None
-    restored = deserialize_payload(wire)
-    conditioning = MiniMaxH3TextConditioning.from_omni_payload(restored)
-    assert MINIMAX_H3_TEXT_CONDITIONING_SCHEMA == "minimax_h3.text_conditioning/v1"
-    torch.testing.assert_close(
-        conditioning.hidden_states,
-        payload["hidden_states"]["output"],
-    )
-    torch.testing.assert_close(
-        conditioning.token_tags,
-        payload["meta"]["token_role_ids"].squeeze(-1),
-    )
-    assert conditioning.hidden_states.dtype == torch.bfloat16
-    assert conditioning.hidden_states.is_contiguous()
-    assert conditioning.token_tags.dtype == torch.int64
-    assert conditioning.token_tags.is_contiguous()
-
-
-@pytest.mark.parametrize(
-    ("payload", "message"),
-    [
-        ({"meta": {"token_role_ids": torch.ones(4, 1)}}, "no hidden_states payload"),
-        ({"hidden_states": {}, "meta": {"token_role_ids": torch.ones(4, 1)}}, "no hidden_states.output tensor"),
-        ({"hidden_states": {"output": torch.randn(4, 5120)}}, "no conditioning metadata"),
-        ({"hidden_states": {"output": torch.randn(4, 5120)}, "meta": {}}, "no token_role_ids tensor"),
-        (
-            {
-                "hidden_states": {"output": torch.randn(4, 5120)},
-                "meta": {"token_role_ids": torch.ones(4)},
-            },
-            r"must have shape \[tokens, 1\]",
-        ),
-    ],
-)
-def test_text_encoder2diffusion_rejects_invalid_conditioning_payload(payload: dict, message: str) -> None:
-    with pytest.raises(RuntimeError, match=message):
-        text_encoder2diffusion([_source_output(payload)], _diffusion_prompt())
-
-
-@pytest.mark.parametrize(
-    ("case", "message"),
-    [
-        ("hidden_width", r"hidden_states must have shape \[tokens, 5120\]"),
-        ("hidden_dtype", "hidden_states must have dtype torch.bfloat16"),
-        ("hidden_noncontiguous", "hidden_states must use contiguous strided layout"),
-        ("hidden_non_strided", "hidden_states must use contiguous strided layout"),
-        ("token_dtype", "stage-wire token_role_ids must have dtype torch.int64"),
-        ("token_layout", "stage-wire token_role_ids must use contiguous strided layout"),
-        ("token_count", "token_tags must align with hidden_states"),
-        ("token_value", "token_tags must contain only 0 and 1"),
-    ],
-)
-def test_text_encoder2diffusion_rejects_h3_v1_contract_mismatch(case: str, message: str) -> None:
-    payload = _valid_text_conditioning_payload()
-
-    if case == "hidden_width":
-        payload["hidden_states"]["output"] = torch.zeros(4, 5119, dtype=torch.bfloat16)
-    elif case == "hidden_dtype":
-        payload["hidden_states"]["output"] = torch.zeros(4, 5120, dtype=torch.float32)
-    elif case == "hidden_noncontiguous":
-        payload["hidden_states"]["output"] = torch.empty(5120, 4, dtype=torch.bfloat16).t()
-    elif case == "hidden_non_strided":
-        payload["hidden_states"]["output"] = torch.empty(
-            (4, 5120),
-            dtype=torch.bfloat16,
-            layout=torch.sparse_coo,
-        )
-    elif case == "token_dtype":
-        payload["meta"]["token_role_ids"] = torch.tensor([[1], [1], [0], [0]], dtype=torch.int32)
-    elif case == "token_layout":
-        payload["meta"]["token_role_ids"] = torch.tensor(
-            [[1], [0], [1], [0], [1], [0], [1], [0]],
-            dtype=torch.int64,
-        )[::2]
-    elif case == "token_count":
-        payload["meta"]["token_role_ids"] = torch.tensor([[1], [0], [0]], dtype=torch.int64)
-    elif case == "token_value":
-        payload["meta"]["token_role_ids"] = torch.tensor([[1], [1], [2], [0]], dtype=torch.int64)
-    else:  # pragma: no cover - parameterization is exhaustive
-        raise AssertionError(f"unknown test case: {case}")
-
-    with pytest.raises(RuntimeError, match=message) as exc_info:
-        text_encoder2diffusion([_source_output(payload)], _diffusion_prompt())
-
-    assert MINIMAX_H3_TEXT_CONDITIONING_SCHEMA in str(exc_info.value)
+def test_encoder2diffusion_waits_for_one_finished_source() -> None:
+    assert encoder2diffusion([SimpleNamespace(finished=False)], {"prompt": "hello"}) is None
+    with pytest.raises(RuntimeError, match="exactly one encoder source"):
+        encoder2diffusion([SimpleNamespace(), SimpleNamespace()], {"prompt": "hello"})
 
 
 def test_ref2va_one_image_tokens_and_tags_match_fused_presentation():
@@ -421,15 +345,20 @@ def test_checkpoint_resolver_selects_local_partition(tmp_path):
     (root / "FL2VA" / "text_encoder").mkdir(parents=True)
     (root / "Ref2VA" / "text_encoder").mkdir(parents=True)
 
-    assert resolve_minimax_h3_model_root(str(root), None, "fl2va") == str(root / "FL2VA" / "text_encoder")
-    assert resolve_minimax_h3_model_root(str(root), None, "ref2va") == str(root / "Ref2VA" / "text_encoder")
-    assert resolve_minimax_h3_model_root(str(root / "Ref2VA"), None, None) == str(root / "Ref2VA" / "text_encoder")
-    assert resolve_minimax_h3_model_root(str(root / "FL2VA"), None, "ref2va") == str(root / "Ref2VA" / "text_encoder")
+    assert resolve_minimax_h3_encoder_model_root(str(root), None, "fl2va") == str(root / "FL2VA" / "text_encoder")
+    assert resolve_minimax_h3_encoder_model_root(str(root), None, "ref2va") == str(root / "Ref2VA" / "text_encoder")
+    assert resolve_minimax_h3_encoder_model_root(str(root), None, "combined") == str(root / "FL2VA" / "text_encoder")
+    assert resolve_minimax_h3_encoder_model_root(str(root / "Ref2VA"), None, None) == str(
+        root / "Ref2VA" / "text_encoder"
+    )
+    assert resolve_minimax_h3_encoder_model_root(str(root / "FL2VA"), None, "ref2va") == str(
+        root / "Ref2VA" / "text_encoder"
+    )
 
 
 def test_checkpoint_resolver_rejects_unknown_task(tmp_path):
     with pytest.raises(ValueError, match="task_type must be one of"):
-        resolve_minimax_h3_model_root(str(tmp_path), None, "unknown")
+        resolve_minimax_h3_encoder_model_root(str(tmp_path), None, "unknown")
 
 
 def test_partition_resolver_preserves_consumer_auto_default(tmp_path):
diff --git a/vllm_omni/config/omni_config.py b/vllm_omni/config/omni_config.py
index 0b8723c0e76..d86a3216ff2 100644
--- a/vllm_omni/config/omni_config.py
+++ b/vllm_omni/config/omni_config.py
@@ -804,6 +804,7 @@ class keeps the diffusion-only knobs from ``OmniDiffusionConfig`` without
             "transformer": True,
             "vae": True,
             "text_encoder": True,
+            "vae_encoder": True,
         }
     )
     override_transformer_cls_name: str | None = None
diff --git a/vllm_omni/deploy/minimax_h3_disaggregated.yaml b/vllm_omni/deploy/minimax_h3_disaggregated.yaml
index 1c1ee6c4022..25a561c2716 100644
--- a/vllm_omni/deploy/minimax_h3_disaggregated.yaml
+++ b/vllm_omni/deploy/minimax_h3_disaggregated.yaml
@@ -1,4 +1,4 @@
-# MiniMax H3: vLLM Qwen3-VL text encoder + diffusion video/audio generation.
+# MiniMax H3: unified text/video/audio encoder stage + diffusion generation stage.
 pipeline: minimax_h3_disaggregated
 async_chunk: false
 trust_remote_code: true
@@ -8,7 +8,16 @@ stages:
   - stage_id: 0
     devices: "0,1"
     max_num_seqs: 1
+    gpu_memory_utilization: 0.6
     tensor_parallel_size: 2
+    hf_overrides:
+      minimax_h3_encoder_components:
+        text_encoder:
+          parallel_mode: tp
+        video_vae:
+          parallel_mode: patch
+        audio_vae:
+          parallel_mode: leader
     default_sampling_params:
       max_tokens: 1
       temperature: 0.0
@@ -19,6 +28,7 @@ stages:
     max_num_seqs: 1
     model_loaded:
       text_encoder: false
+      vae_encoder: false
     parallel_config:
       tensor_parallel_size: 1
       ulysses_degree: 4
diff --git a/vllm_omni/deploy/minimax_h3_disaggregated_turbo.yaml b/vllm_omni/deploy/minimax_h3_disaggregated_turbo.yaml
index d7e84db42a6..ec11796b64e 100644
--- a/vllm_omni/deploy/minimax_h3_disaggregated_turbo.yaml
+++ b/vllm_omni/deploy/minimax_h3_disaggregated_turbo.yaml
@@ -8,7 +8,16 @@ stages:
   - stage_id: 0
     devices: "0,1"
     max_num_seqs: 1
+    gpu_memory_utilization: 0.6
     tensor_parallel_size: 2
+    hf_overrides:
+      minimax_h3_encoder_components:
+        text_encoder:
+          parallel_mode: tp
+        video_vae:
+          parallel_mode: patch
+        audio_vae:
+          parallel_mode: leader
     default_sampling_params:
       max_tokens: 1
       temperature: 0.0
@@ -19,6 +28,7 @@ stages:
     max_num_seqs: 1
     model_loaded:
       text_encoder: false
+      vae_encoder: false
     parallel_config:
       tensor_parallel_size: 1
       ulysses_degree: 4
diff --git a/vllm_omni/diffusion/data.py b/vllm_omni/diffusion/data.py
index 10f8642c64c..e1ce550d467 100644
--- a/vllm_omni/diffusion/data.py
+++ b/vllm_omni/diffusion/data.py
@@ -984,6 +984,7 @@ class OmniDiffusionConfig:
             "transformer": True,
             "vae": True,
             "text_encoder": True,
+            "vae_encoder": True,
         }
     )
     override_transformer_cls_name: str | None = None
diff --git a/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py b/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
index 8f814a27a8d..1b8bd7feabb 100644
--- a/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
+++ b/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
@@ -7,9 +7,9 @@
 import json
 import math
 import os
-import tempfile
 from collections.abc import Iterable, Mapping, Sequence
-from contextlib import contextmanager, nullcontext
+from contextlib import contextmanager
+from dataclasses import fields, replace
 from itertools import groupby
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, ClassVar
@@ -18,7 +18,6 @@
 import torch
 import torch.distributed as dist
 import torch.nn as nn
-from PIL import Image
 from transformers import Qwen2TokenizerFast, Qwen3VLProcessor
 from vllm.logger import init_logger
 from vllm.model_executor.layers.quantization.base_config import QuantizationConfig
@@ -29,10 +28,7 @@
     RequestScopedCacheDiTRuntime,
 )
 from vllm_omni.diffusion.data import DiffusionOutput, OmniDiffusionConfig
-from vllm_omni.diffusion.distributed.parallel_state import (
-    get_world_group,
-    init_world_group,
-)
+from vllm_omni.diffusion.distributed.parallel_state import get_world_group, init_world_group
 from vllm_omni.diffusion.distributed.utils import get_local_device
 from vllm_omni.diffusion.forward_context import DenoiseProgressMixin
 from vllm_omni.diffusion.model_loader.diffusers_loader import (
@@ -74,36 +70,20 @@
     resolve_minimax_h3_partition,
 )
 from vllm_omni.model_executor.models.minimax_h3.conditioning import (
+    MiniMaxH3EncoderConditioning,
+    MiniMaxH3EncoderMediaConditioning,
+    MiniMaxH3EncoderMediaInput,
     MiniMaxH3TextConditioning,
 )
-from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
-    load_minimax_h3_images as _load_images,
-)
-from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
-    minimax_h3_multi_image_presentation,
-    minimax_h3_ref2va_presentation,
-    minimax_h3_ref2va_video_presentation,
-    minimax_h3_text_only_ids,
-)
-from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
-    resolve_minimax_h3_aspect_ratio as _resolve_minimax_h3_aspect_ratio,
-)
-from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
-    resolve_minimax_h3_output_canvas as _resolve_output_canvas,
-)
-from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
-    resolve_minimax_h3_reference_image_shape as _reference_image_shape,
+from vllm_omni.model_executor.models.minimax_h3.encoder_processing import (
+    PreparedEncoderInputs,
+    encode_media,
+    prepare_encoder_inputs,
 )
+from vllm_omni.model_executor.models.minimax_h3.preprocessing import build_minimax_h3_presentation
 from vllm_omni.model_executor.models.minimax_h3.reference_video import (
     MINIMAX_H3_PREPARED_REFERENCE_VIDEOS_KEY,
     deserialize_prepared_reference_videos,
-    load_audio_file,
-    load_video_audio,
-    load_video_frames,
-    prepare_reference_videos,
-    sample_reference_video_frames,
-    validate_reference_audio_files,
-    validate_reference_audio_waveforms,
 )
 from vllm_omni.platforms import current_omni_platform
 from vllm_omni.quantization import (
@@ -154,7 +134,6 @@
 )
 from .time_request import (
     MINIMAX_H3_SHAPE_PLANNER,
-    minimax_h3_align_frame_count,
     minimax_h3_time_shift_sigmas,
 )
 from .vae import MiniMaxH3AudioVAE, MiniMaxH3VideoVAE
@@ -175,22 +154,6 @@
 MINIMAX_H3_AUDIO_SAMPLE_RATE = 32000
 MINIMAX_H3_IMGVID_COND_TIMESTEP = 0.999
 MINIMAX_H3_AUDIO_REF_COND_TIMESTEP = 1.0
-MINIMAX_H3_OUTPUT_SHORT_EDGE = 768
-MINIMAX_H3_OUTPUT_MAX_PIXELS = 768 * 1344
-MINIMAX_H3_REFERENCE_IMAGE_SHORT_EDGE = 2048
-MINIMAX_H3_REFERENCE_IMAGE_MULTIPLE = 32
-MINIMAX_H3_SUPPORTED_ASPECT_RATIOS = {
-    "21:9": 21.0 / 9.0,
-    "16:9": 16.0 / 9.0,
-    "4:3": 4.0 / 3.0,
-    "1:1": 1.0,
-    "3:4": 3.0 / 4.0,
-    "9:16": 9.0 / 16.0,
-}
-MINIMAX_H3_MAX_REFERENCE_IMAGE_BYTES = 30 * 1024 * 1024
-MINIMAX_H3_REFERENCE_IMAGE_FORMATS = frozenset({"jpeg", "png", "webp", "heic", "heif"})
-MINIMAX_H3_MIN_OUTPUT_SECONDS = 4.0
-MINIMAX_H3_MAX_OUTPUT_SECONDS = 15.0
 MINIMAX_H3_DOWNLOAD_PATTERNS = [
     "FL2VA/**",
     "Ref2VA/model_index.json",
@@ -267,7 +230,6 @@ def _resolve_minimax_h3_model_root(
     )
 
 
-# Keys of ``_prepare_request_inputs`` that feed ``diffuse`` / ``_build_denoise_inputs``.
 _MINIMAX_H3_DENOISE_INPUT_KEYS = (
     "task",
     "text_embeddings",
@@ -427,114 +389,6 @@ def get_minimax_h3_post_process_func(
     return _minimax_h3_post_process
 
 
-def _align_multiple(value: float, multiple: int = 32) -> int:
-    return max(multiple, int(round(float(value) / multiple)) * multiple)
-
-
-def _load_image(value: Any) -> Image.Image:
-    images = _load_images(value)
-    if len(images) != 1:
-        raise OmniClientError(f"MiniMax H3 expected one image, got {len(images)}")
-    return images[0]
-
-
-def _load_audio(value: Any) -> tuple[torch.Tensor, int]:
-    if isinstance(value, (list, tuple)) and not (len(value) == 2 and isinstance(value[1], (int, np.integer))):
-        audios = _load_audios(value)
-        if len(audios) != 1:
-            raise OmniClientError(f"MiniMax H3 expected one audio, got {len(audios)}")
-        return audios[0]
-    if isinstance(value, (str, os.PathLike)):
-        return load_audio_file(str(value))
-    if isinstance(value, (list, tuple)) and len(value) == 2:
-        waveform, sample_rate = value
-        waveform = torch.as_tensor(waveform).float()
-        return waveform, int(sample_rate)
-    if isinstance(value, dict):
-        waveform = value.get("waveform", value.get("array"))
-        sample_rate = value.get("sample_rate", value.get("sampling_rate"))
-        if waveform is not None and sample_rate is not None:
-            return torch.as_tensor(waveform).float(), int(sample_rate)
-    raise OmniClientError("MiniMax H3 audio input must be a path, (waveform, sample_rate), or a waveform mapping")
-
-
-def _load_audios(value: Any) -> list[tuple[torch.Tensor, int]]:
-    if isinstance(value, (list, tuple)) and not (len(value) == 2 and isinstance(value[1], (int, np.integer))):
-        if not value:
-            raise OmniClientError("MiniMax H3 audio input must not be empty")
-        return [_load_audio(item) for item in value]
-    return [_load_audio(value)]
-
-
-def _as_int_list(value: Any, *, name: str) -> list[int]:
-    if isinstance(value, bool):
-        raise OmniClientError(f"{name} must be an integer or a list of integers")
-    if isinstance(value, (int, np.integer)):
-        return [int(value)]
-    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
-        result = list(value)
-        if not result:
-            raise OmniClientError(f"{name} must not be empty")
-        if any(isinstance(item, bool) or not isinstance(item, (int, np.integer)) for item in result):
-            raise OmniClientError(f"{name} must contain only integers")
-        return [int(item) for item in result]
-    raise OmniClientError(f"{name} must be an integer or a list of integers")
-
-
-def _resolve_fl2va_keyframe_indices(extra: Mapping[str, Any], image_count: int) -> list[int]:
-    target = extra.get("target")
-    target = target if isinstance(target, Mapping) else {}
-    raw = extra.get("frame_indices", extra.get("frame_index"))
-    if raw is None:
-        raw = target.get("frame_indices", target.get("frame_index"))
-    if raw is None:
-        raw_indices = [0] if image_count == 1 else [0, -1]
-    else:
-        raw_indices = _as_int_list(raw, name="frame_indices")
-    if len(raw_indices) != image_count:
-        raise OmniClientError(
-            f"MiniMax H3 FL2VA requires one frame index per image: got {raw_indices!r} for {image_count} image(s)"
-        )
-    if tuple(raw_indices) not in ((0,), (-1,), (0, -1)):
-        raise OmniClientError("MiniMax H3 FL2VA frame_indices must be [0], [-1], or [0, -1]")
-    return raw_indices
-
-
-def _reuse_prepared_reference_videos(
-    prepared: list[dict[str, Any]] | None,
-    *,
-    expected_count: int,
-) -> list[dict[str, Any]] | None:
-    if prepared is None:
-        return None
-    if len(prepared) != expected_count:
-        raise OmniClientError("MiniMax H3 prepared-reference-video count does not match the request")
-    for item in prepared:
-        if not os.path.isfile(item["prepared_path"]):
-            raise OmniClientError(f"MiniMax H3 prepared reference video is unavailable: {item['prepared_path']}")
-    return prepared
-
-
-def _validate_ref2va_reference_counts(
-    image_count: int,
-    video_count: int,
-    audio_count: int,
-) -> None:
-    """Validate the official Ref2VA reference-count contract."""
-    if image_count < 0 or video_count < 0 or audio_count < 0:
-        raise OmniClientError("MiniMax H3 reference counts must be non-negative")
-    if image_count + video_count == 0:
-        raise OmniClientError("ref2va requires at least one image or video reference")
-    if image_count > 9:
-        raise OmniClientError("ref2va accepts at most 9 image references")
-    if video_count > 3:
-        raise OmniClientError("ref2va accepts at most 3 video references")
-    if audio_count > 3:
-        raise OmniClientError("ref2va accepts at most 3 standalone audio references")
-    if image_count + video_count + audio_count > 12:
-        raise OmniClientError("ref2va accepts at most 12 total references")
-
-
 def _resolve_minimax_h3_num_outputs(value: Any) -> int:
     if value is None:
         return 1
@@ -572,17 +426,6 @@ def _minimax_h3_output_seeds(seed: int, num_outputs: int) -> list[int]:
     return [int(seed) + output_index for output_index in range(int(num_outputs))]
 
 
-def _validate_reference_image(image: Image.Image) -> None:
-    width, height = image.size
-    if min(width, height) < 256 or max(width, height) > 5760:
-        raise OmniClientError(
-            f"MiniMax H3 reference image dimensions must be in [256, 5760] pixels, got {width}x{height}"
-        )
-    ratio = width / height
-    if not 0.4 <= ratio <= 2.5:
-        raise OmniClientError(f"MiniMax H3 reference image aspect ratio must be in [0.4, 2.5], got {width}x{height}")
-
-
 def _dit_rank_world() -> tuple[Any, int, int]:
     if not dist.is_initialized():
         return None, 0, 1
@@ -716,10 +559,8 @@ class MiniMaxH3Pipeline(
         on_demand_component_paths=frozenset({"text_encoder", "video_vae", "audio_vae"}),
     )
     _PROFILER_TARGETS: ClassVar[list[str]] = [
-        "_prepare_reference_videos",
         "encode_prompt",
-        "_encode_visual_conditions",
-        "_encode_reference_audio_conditions",
+        "_encode_local_media",
         "diffuse",
         "decode",
         "video_vae.decode_latent",
@@ -809,6 +650,18 @@ def _validate_diffusion_lora_binding(
                 f"bound={len(bound_lora_names)}/{len(lora_model.loras)}, missing={missing[:5]}"
             )
 
+    def _active_turbo_spec(self, sampling: Any) -> TurboSpec | None:
+        """Return the spec of the Turbo adapter this request actually applies.
+
+        A recognized adapter at scale 0 contributes nothing, so it neither
+        constrains the task nor imposes its sampler contract.
+        """
+
+        lora_request = sampling.lora_request
+        if lora_request is None or math.isclose(0.0, float(sampling.lora_scale)):
+            return None
+        return self._turbo_lora_specs.get(lora_request.lora_int_id)
+
     def _has_active_native_lora(self, sampling: Any) -> bool:
         lora_request = sampling.lora_request
         return (
@@ -868,18 +721,6 @@ def _sigma_schedule_for_request(self, sampling: Any, task: str) -> DMD2SigmaSche
             return adapter_schedule
         return self._base_schedule_for_task(task)
 
-    def _active_turbo_spec(self, sampling: Any) -> TurboSpec | None:
-        """Return the spec of the Turbo adapter this request actually applies.
-
-        A recognized adapter at scale 0 contributes nothing, so it neither
-        constrains the task nor imposes its sampler contract.
-        """
-
-        lora_request = sampling.lora_request
-        if lora_request is None or math.isclose(0.0, float(sampling.lora_scale)):
-            return None
-        return self._turbo_lora_specs.get(lora_request.lora_int_id)
-
     def _validate_turbo_sampling(self, sampling: Any, spec: TurboSpec) -> None:
         """Hold a request to the contract of the artifact that is loaded.
 
@@ -935,7 +776,30 @@ def __init__(
         if int(self.parallel_config.cfg_parallel_size) != 1:
             raise ValueError("MiniMax-H3 is CFG-distilled and has no negative branch; cfg_parallel_size must be 1")
         self.device = get_local_device()
-        self.load_text_encoder = od_config.model_loaded["text_encoder"]
+        self.load_text_encoder = od_config.model_loaded.get("text_encoder", True)
+        self.load_vae_encoder = od_config.model_loaded.get("vae_encoder", True)
+        if self.load_vae_encoder is False and self.load_text_encoder is True:
+            raise ValueError(
+                "MiniMax H3 does not support local text encoding with external media conditioning; "
+                "set text_encoder=false or enable vae_encoder"
+            )
+        self._encoder_modules = ["text_encoder"] if self.load_text_encoder else []
+        self._PROFILER_TARGETS = list(type(self)._PROFILER_TARGETS)
+        encoder_block_attrs = dict(self._offload_plan.encoder_block_attrs)
+        if not self.load_text_encoder:
+            encoder_block_attrs.pop("text_encoder", None)
+        on_demand_component_paths = set(self._offload_plan.on_demand_component_paths)
+        if not self.load_text_encoder:
+            on_demand_component_paths.discard("text_encoder")
+        self._offload_plan = replace(
+            self._offload_plan,
+            encoder_block_attrs=encoder_block_attrs,
+            on_demand_component_paths=frozenset(on_demand_component_paths),
+        )
+        if not self.load_text_encoder:
+            self._PROFILER_TARGETS.remove("encode_prompt")
+        if not self.load_vae_encoder:
+            self._PROFILER_TARGETS.remove("_encode_local_media")
         self.partition = _minimax_h3_partition_for_task(
             getattr(od_config, "task_type", None),
             str(od_config.model),
@@ -1102,12 +966,14 @@ def __init__(
             os.path.join(model_path, "video_vae"),
             device=self.device,
             load_device=component_load_device,
+            decode_only=not self.load_vae_encoder,
             trust_remote_code=od_config.trust_remote_code,
         )
         self.audio_vae = MiniMaxH3AudioVAE(
             os.path.join(model_path, "audio_vae"),
             device=self.device,
             load_device=component_load_device,
+            decode_only=not self.load_vae_encoder,
             trust_remote_code=od_config.trust_remote_code,
         )
         # Registry-side VAE patch-parallel discovery uses ``pipeline.vae``.
@@ -1154,6 +1020,8 @@ def source_prefix(item: tuple[str, torch.Tensor]) -> str:
                 raise ValueError(f"MiniMax-H3 weight source {prefix!r} is not contiguous")
             loaded_prefixes.add(prefix)
             component = getattr(self, prefix.removesuffix("."))
+            if component is None:
+                raise ValueError(f"MiniMax-H3 component {prefix.removesuffix('.')!r} is disabled in this deployment")
             stream = ((name[len(prefix) :], tensor) for name, tensor in grouped_weights)
             if prefix == "transformer." and self._fasth3 is not None:
                 # Fuse before the model shards anything, which is also the only
@@ -1227,11 +1095,12 @@ def _base_schedule_for_task(self, task: str) -> DMD2SigmaSchedule | None:
     def _resolve_task(
         self,
         requested: str | None,
-        multi_modal_data: dict[str, Any],
+        multi_modal_data: dict[str, Any] | None = None,
         *,
         turbo_spec: TurboSpec | None = None,
         has_native_lora: bool = False,
     ) -> str:
+        multi_modal_data = multi_modal_data or {}
         if requested is None:
             # A Ref2VA-only startup has no FL2VA transformer; preserve its
             # historical implicit default even for image-only references.
@@ -1259,217 +1128,6 @@ def _resolve_task(
             self._fasth3.check_task(task)
         return task
 
-    def _resolve_shape(
-        self,
-        task: str,
-        sampling: Any,
-        image: Image.Image | None,
-    ) -> tuple[int, int, int, int, int]:
-        fps = int(sampling.fps or MINIMAX_H3_FPS)
-        if fps != MINIMAX_H3_FPS:
-            raise OmniClientError(f"MiniMax H3 output fps is fixed at {MINIMAX_H3_FPS}")
-        extra = sampling.extra_args or {}
-        target = extra.get("target")
-        if target is not None and not isinstance(target, Mapping):
-            raise OmniClientError("MiniMax H3 extra_args['target'] must be an object")
-        target = target if isinstance(target, Mapping) else {}
-        duration = target.get("duration_seconds", extra.get("duration_seconds", extra.get("duration")))
-        if duration is not None:
-            if isinstance(duration, bool):
-                raise OmniClientError(f"MiniMax H3 output duration must be in [4, 15] seconds, got {duration!r}")
-            try:
-                duration = float(duration)
-            except (TypeError, ValueError) as exc:
-                raise OmniClientError(
-                    f"MiniMax H3 output duration must be in [4, 15] seconds, got {duration!r}"
-                ) from exc
-            if (
-                not math.isfinite(duration)
-                or not MINIMAX_H3_MIN_OUTPUT_SECONDS <= duration <= MINIMAX_H3_MAX_OUTPUT_SECONDS
-            ):
-                raise OmniClientError(f"MiniMax H3 output duration must be in [4, 15] seconds, got {duration}")
-            requested_frames = int(round(duration * fps))
-        elif int(sampling.num_frames or 1) > 1:
-            requested_frames = int(sampling.num_frames)
-        else:
-            requested_frames = 124 if task == "ref2va" else 209
-            duration = requested_frames / fps
-        if not MINIMAX_H3_MIN_OUTPUT_SECONDS <= requested_frames / fps <= MINIMAX_H3_MAX_OUTPUT_SECONDS:
-            raise OmniClientError(
-                f"MiniMax H3 output duration must be in [4, 15] seconds, got {requested_frames / fps:.3f}"
-            )
-        num_frames = minimax_h3_align_frame_count(requested_frames)
-
-        height = sampling.height
-        width = sampling.width
-        aspect_ratio = target.get("aspect_ratio", extra.get("aspect_ratio"))
-        raw_short_edge = target.get("short_edge", extra.get("short_edge", MINIMAX_H3_OUTPUT_SHORT_EDGE))
-        if isinstance(raw_short_edge, bool) or not isinstance(raw_short_edge, (int, np.integer)):
-            raise OmniClientError(
-                f"MiniMax H3 target.short_edge must be {MINIMAX_H3_OUTPUT_SHORT_EDGE}, got {raw_short_edge!r}"
-            )
-        short_edge = int(raw_short_edge)
-
-        aspect_ratio = _resolve_minimax_h3_aspect_ratio(
-            task,
-            aspect_ratio,
-            image,
-        )
-        if not 0.25 <= aspect_ratio <= 4.0:
-            raise OmniClientError(f"MiniMax H3 canvas aspect ratio must be in [1:4, 4:1], got {aspect_ratio}")
-
-        if height is None or width is None:
-            height, width = _resolve_output_canvas(aspect_ratio, short_edge)
-        height = int(height) // 32 * 32
-        width = int(width) // 32 * 32
-        if min(height, width) <= 0:
-            raise OmniClientError(f"invalid MiniMax H3 canvas {width}x{height}")
-        if width > 4 * height or height > 4 * width:
-            raise OmniClientError("MiniMax H3 canvas aspect ratio must be in [1:4, 4:1]")
-
-        latent_t = MINIMAX_H3_SHAPE_PLANNER.video_latent_t(num_frames)
-        audio_t = MINIMAX_H3_SHAPE_PLANNER.audio_latent_t(num_frames / fps)
-        return height, width, num_frames, latent_t, audio_t
-
-    def encode_prompt(
-        self,
-        *,
-        task: str,
-        prompt: str,
-        image: Image.Image | None = None,
-        images: list[Image.Image] | None = None,
-        prepared_videos: list[dict[str, Any]] | None = None,
-        condition_labels: list[tuple[str, int]] | None = None,
-    ) -> tuple[torch.Tensor, torch.Tensor]:
-        _, rank, _ = _dit_rank_world()
-        hidden = None
-        tags = None
-        ids = None
-        vision_kwargs: dict[str, torch.Tensor] = {}
-        images = list(images) if images is not None else ([image] if image is not None else [])
-        if rank == 0:
-            if task == "t2va":
-                ids = minimax_h3_text_only_ids(self.tokenizer, prompt)
-                tags = torch.ones(ids.shape[0], dtype=torch.long)
-                vision_kwargs = {}
-            else:
-                image_token_counts: list[int] = []
-                if images:
-                    vision = self.processor.image_processor(
-                        images=images,
-                        return_tensors="pt",
-                    )
-                    image_grid = vision["image_grid_thw"]
-                    merge = int(self.processor.image_processor.merge_size) ** 2
-                    image_token_counts = [int(grid.prod().item()) // merge for grid in image_grid]
-                    vision_kwargs.update(
-                        {
-                            "pixel_values": vision["pixel_values"],
-                            "image_grid_thw": image_grid,
-                        }
-                    )
-
-                video_block_counts: list[list[int]] = []
-                video_block_timestamps: list[list[float]] = []
-                if prepared_videos:
-                    videos = []
-                    sampled_videos = []
-                    for index, item in enumerate(prepared_videos):
-                        sampled = sample_reference_video_frames(item["prepared_path"])
-                        videos.append(np.stack(sampled["frames"]))
-                        sampled_videos.append(sampled)
-                    vision = self.processor.video_processor(
-                        videos=videos,
-                        do_sample_frames=False,
-                        return_tensors="pt",
-                    )
-                    video_grid = vision["video_grid_thw"]
-                    merge = int(self.processor.image_processor.merge_size) ** 2
-                    for index, sampled in enumerate(sampled_videos):
-                        blocks = int(video_grid[index, 0])
-                        per_block = int(video_grid[index, 1]) * int(video_grid[index, 2]) // merge
-                        timestamps = sampled["block_timestamps"]
-                        if len(timestamps) != blocks:
-                            raise ValueError(
-                                f"video block count mismatch: processor={blocks}, timestamps={len(timestamps)}"
-                            )
-                        video_block_counts.append([per_block] * blocks)
-                        video_block_timestamps.append(timestamps)
-                    vision_kwargs.update(
-                        {
-                            "pixel_values_videos": vision["pixel_values_videos"],
-                            "video_grid_thw": video_grid,
-                        }
-                    )
-
-                if not images and not prepared_videos:
-                    raise OmniClientError(f"{task} requires an image or video condition")
-                if condition_labels is None:
-                    condition_labels = []
-                    for image_index in range(1, len(images) + 1):
-                        condition_labels.append(("image", image_index))
-                    audio_index = 0
-                    for video_index, item in enumerate(prepared_videos or (), start=1):
-                        if item["input_has_audio"]:
-                            audio_index += 1
-                            condition_labels.append(("audio", audio_index))
-                        condition_labels.append(("video", video_index))
-
-                if task == "fl2va":
-                    if prepared_videos:
-                        raise OmniClientError("fl2va does not accept video conditions")
-                    ids, tags = minimax_h3_multi_image_presentation(
-                        self.tokenizer,
-                        prompt=prompt,
-                        image_token_counts=image_token_counts,
-                    )
-                elif prepared_videos:
-                    ids, tags = minimax_h3_ref2va_video_presentation(
-                        self.tokenizer,
-                        prompt=prompt,
-                        condition_labels=condition_labels,
-                        image_token_count=image_token_counts or None,
-                        video_block_token_counts=video_block_counts,
-                        video_block_timestamps=video_block_timestamps,
-                    )
-                else:
-                    ids, tags = minimax_h3_ref2va_presentation(
-                        self.tokenizer,
-                        prompt=prompt,
-                        condition_labels=condition_labels,
-                        image_token_count=image_token_counts or None,
-                    )
-
-            logger.info(
-                "MiniMax H3 %s Qwen presentation: %d tokens%s",
-                task,
-                int(ids.shape[0]),
-                (
-                    f", {len(images)} reference images"
-                    + (f", {len(prepared_videos)} reference videos" if prepared_videos else "")
-                    if images
-                    else (f", {len(prepared_videos)} reference videos" if prepared_videos else "")
-                ),
-            )
-
-        if rank < self.text_encoder_tp_size:
-            # Distribute the encode inputs from the DiT main rank to the other
-            # encoder TP ranks, then run the distributed encode on all of them.
-            ids = self._distribute_encode_inputs(ids, vision_kwargs)
-            hidden = self._encode_text_hidden(ids, vision_kwargs)
-
-        hidden = _broadcast_tensor(
-            hidden,
-            dtype=torch.bfloat16,
-            device=self.device,
-        )
-        tags = _broadcast_tensor(
-            tags,
-            dtype=torch.long,
-            device=self.device,
-        )
-        return hidden, tags
-
     def _build_text_encoder_group(self, text_encoder_tp_size: int) -> Any:
         """Create the encoder tensor-parallel process group.
 
@@ -1565,24 +1223,6 @@ def _distribute_encode_inputs(
             )
         return ids
 
-    def _prepare_reference_videos(
-        self,
-        values: Any,
-        *,
-        target_frame_count: int,
-        workdir: str,
-        start_time_seconds: Any = None,
-    ) -> list[dict[str, Any]] | None:
-        _, rank, _ = _dit_rank_world()
-        if rank != 0:
-            return None
-        return prepare_reference_videos(
-            values,
-            target_frame_count=target_frame_count,
-            workdir=workdir,
-            start_time_seconds=start_time_seconds,
-        )
-
     def _encode_text_hidden(
         self,
         input_ids: torch.Tensor,
@@ -1726,197 +1366,6 @@ def _offload_model_cpu_stage_output(self, tensor: torch.Tensor) -> torch.Tensor:
             return tensor.cpu()
         return torch.empty(tensor.shape, dtype=tensor.dtype, device="meta")
 
-    def _encode_visual_conditions(
-        self,
-        images: list[Image.Image],
-        prepared_videos: list[dict[str, Any]] | None,
-        *,
-        video_count: int,
-    ) -> tuple[torch.Tensor | None, list[tuple[int, int, int]]]:
-        rows: list[torch.Tensor] = []
-        shapes: list[tuple[int, int, int]] = []
-        _, rank, _ = _dit_rank_world()
-        # Keep image and video references in one residency window when both
-        # appear in a request; otherwise the video branch would reload the VAE.
-        needs_video_vae = video_count > 0 or (rank == 0 and bool(images))
-        video_vae_context = self._component_on_device(self.video_vae) if needs_video_vae else nullcontext()
-        with video_vae_context:
-            if images:
-                image_rows = None
-                if rank == 0:
-                    image_rows = torch.cat([self.video_vae.encode_image(image) for image in images])
-                rows.append(
-                    _broadcast_tensor(
-                        image_rows,
-                        dtype=torch.float32,
-                        device=self.device,
-                    )
-                )
-                shapes.extend((1, image.height // 16, image.width // 16) for image in images)
-            if video_count:
-                video_rows, video_shapes = self._encode_video_conditions_resident(
-                    prepared_videos,
-                    count=video_count,
-                )
-                rows.append(video_rows)
-                shapes.extend(video_shapes)
-        return (torch.cat(rows) if rows else None), shapes
-
-    def _encode_audio_conditions_resident(
-        self,
-        audios: list[tuple[torch.Tensor, int]],
-        *,
-        max_duration_seconds: float | None = None,
-    ) -> tuple[torch.Tensor | None, list[int]]:
-        if not audios:
-            return None, []
-        if max_duration_seconds is not None:
-            max_duration_seconds = float(max_duration_seconds)
-            if max_duration_seconds <= 0:
-                raise ValueError("max_duration_seconds must be positive")
-        _, rank, _ = _dit_rank_world()
-        rows = None
-        lengths = torch.zeros(len(audios), dtype=torch.long, device=self.device)
-        if rank == 0:
-            bounded_audios = []
-            for waveform, sample_rate in audios:
-                if max_duration_seconds is not None:
-                    max_samples = int(round(max_duration_seconds * int(sample_rate)))
-                    waveform = waveform[..., :max_samples]
-                bounded_audios.append((waveform, sample_rate))
-            encoded = [self.audio_vae.encode_waveform(*audio) for audio in bounded_audios]
-            rows = torch.cat([item[0] for item in encoded])
-            lengths = torch.tensor(
-                [int(item[1]) for item in encoded],
-                dtype=torch.long,
-                device=self.device,
-            )
-        group, _, world_size = _dit_rank_world()
-        if world_size > 1:
-            dist.broadcast(lengths, src=0, group=group)
-        return (
-            _broadcast_tensor(rows, dtype=torch.float32, device=self.device),
-            [int(value) for value in lengths.tolist()],
-        )
-
-    def _encode_video_conditions_resident(
-        self,
-        prepared_videos: list[dict[str, Any]] | None,
-        *,
-        count: int,
-    ) -> tuple[torch.Tensor, list[tuple[int, int, int]]]:
-        group, rank, world_size = _dit_rank_world()
-        distributed_encode = self.video_vae.is_distributed_enabled()
-        if distributed_encode:
-            # Native tiled encode uses collectives, so every VPP rank must
-            # enter each reference encode in the same input order.
-            prepared_videos_list = [prepared_videos]
-            dist.broadcast_object_list(
-                prepared_videos_list,
-                src=0,
-                group=group,
-                device=self.device,
-            )
-            prepared_videos = prepared_videos_list[0]
-
-        rows = None
-        shapes = torch.zeros((count, 3), dtype=torch.long, device=self.device)
-        if rank == 0 or distributed_encode:
-            if prepared_videos is None or len(prepared_videos) != count:
-                raise ValueError("reference-video preparation is incomplete")
-            encoded = [
-                self.video_vae.encode_video(load_video_frames(item["prepared_path"])) for item in prepared_videos
-            ]
-            rows = torch.cat([item[0] for item in encoded])
-            shapes = torch.tensor(
-                [item[1] for item in encoded],
-                dtype=torch.long,
-                device=self.device,
-            )
-        if distributed_encode:
-            return (
-                rows.to(device=self.device, dtype=torch.float32),
-                [tuple(int(value) for value in item) for item in shapes.tolist()],
-            )
-
-        if world_size > 1:
-            dist.broadcast(shapes, src=0, group=group)
-        return (
-            _broadcast_tensor(rows, dtype=torch.float32, device=self.device),
-            [tuple(int(value) for value in item) for item in shapes.tolist()],
-        )
-
-    def _encode_video_audio_conditions_resident(
-        self,
-        prepared_videos: list[dict[str, Any]] | None,
-        *,
-        has_audio: list[bool],
-    ) -> tuple[torch.Tensor | None, list[int]]:
-        _, rank, _ = _dit_rank_world()
-        count = sum(has_audio)
-        if count == 0:
-            return None, []
-        rows = None
-        lengths = torch.zeros(count, dtype=torch.long, device=self.device)
-        if rank == 0:
-            if prepared_videos is None:
-                raise ValueError("rank 0 reference-video preparation is incomplete")
-            encoded = [
-                self.audio_vae.encode_waveform(
-                    *load_video_audio(
-                        item["original_path"],
-                        start_time_seconds=float(item.get("start_time_seconds", 0.0)),
-                        duration_seconds=item.get(
-                            "audio_duration_seconds",
-                            item.get("duration_seconds"),
-                        ),
-                    )
-                )
-                for item in prepared_videos
-                if item["input_has_audio"]
-            ]
-            rows = torch.cat([item[0] for item in encoded])
-            lengths = torch.tensor(
-                [item[1] for item in encoded],
-                dtype=torch.long,
-                device=self.device,
-            )
-        group, _, world_size = _dit_rank_world()
-        if world_size > 1:
-            dist.broadcast(lengths, src=0, group=group)
-        return (
-            _broadcast_tensor(rows, dtype=torch.float32, device=self.device),
-            [int(value) for value in lengths.tolist()],
-        )
-
-    def _encode_reference_audio_conditions(
-        self,
-        prepared_videos: list[dict[str, Any]] | None,
-        *,
-        has_audio: list[bool],
-        standalone_audios: list[tuple[torch.Tensor, int]],
-        max_duration_seconds: float,
-    ) -> tuple[torch.Tensor | None, list[int], torch.Tensor | None, list[int]]:
-        # Embedded and standalone audio are consecutive direct Audio-VAE
-        # calls. Keep the component resident across both paths.
-        needs_audio_vae = any(has_audio) or bool(standalone_audios)
-        audio_vae_context = self._component_on_device(self.audio_vae) if needs_audio_vae else nullcontext()
-        with audio_vae_context:
-            embedded_condition, embedded_lengths = self._encode_video_audio_conditions_resident(
-                prepared_videos,
-                has_audio=has_audio,
-            )
-            external_condition, external_lengths = self._encode_audio_conditions_resident(
-                standalone_audios,
-                max_duration_seconds=max_duration_seconds,
-            )
-        return (
-            embedded_condition,
-            embedded_lengths,
-            external_condition,
-            external_lengths,
-        )
-
     def _initial_noise(
         self,
         *,
@@ -2342,13 +1791,16 @@ def _extract_text_conditioning(raw_prompt: Any) -> MiniMaxH3TextConditioning | N
         if isinstance(raw_prompt, str):
             return None
         additional_information = raw_prompt.get("additional_information") or {}
-        text_encoder_output = additional_information.get("text_encoder_output")
-        if text_encoder_output is None:
+        encoder_output = additional_information.get("encoder_output")
+        if encoder_output is None:
             return None
-        if not isinstance(text_encoder_output, Mapping):
-            raise OmniClientError("text_encoder_output must be a mapping")
+        if not isinstance(encoder_output, Mapping):
+            raise OmniClientError("MiniMax H3 encoder output must be a mapping")
         try:
-            return MiniMaxH3TextConditioning.from_payload(text_encoder_output)
+            if "hidden_states" in encoder_output and "token_tags" in encoder_output:
+                return MiniMaxH3TextConditioning.from_payload(encoder_output)
+            conditioning = MiniMaxH3EncoderConditioning.from_omni_payload(encoder_output)
+            return MiniMaxH3TextConditioning(conditioning.hidden_states, conditioning.token_tags)
         except ValueError as exc:
             raise OmniClientError(str(exc)) from exc
 
@@ -2369,34 +1821,234 @@ def _extract_prepared_reference_videos(raw_prompt: Any) -> list[dict[str, Any]]
             raise OmniClientError(str(exc)) from exc
         return videos
 
-    def _prepare_request_inputs(
+    def encode_prompt(self, prepared: PreparedEncoderInputs | None) -> tuple[torch.Tensor, torch.Tensor]:
+        _, rank, _ = _dit_rank_world()
+        ids = tags = hidden = None
+        vision_kwargs: dict[str, torch.Tensor] = {}
+        error = None
+        if rank == 0:
+            try:
+                if prepared is None:
+                    raise ValueError("rank 0 must prepare MiniMax H3 text inputs")
+                if prepared.images:
+                    vision = self.processor.image_processor(images=prepared.images, return_tensors="pt")
+                    vision_kwargs.update(
+                        pixel_values=vision["pixel_values"],
+                        image_grid_thw=vision["image_grid_thw"],
+                    )
+                if prepared.qwen_videos:
+                    vision = self.processor.video_processor(
+                        videos=[frames for frames, _ in prepared.qwen_videos],
+                        do_sample_frames=False,
+                        return_tensors="pt",
+                    )
+                    vision_kwargs.update(
+                        pixel_values_videos=vision["pixel_values_videos"],
+                        video_grid_thw=vision["video_grid_thw"],
+                    )
+                ids, tags = build_minimax_h3_presentation(
+                    self.tokenizer,
+                    prompt=prepared.prompt,
+                    task=prepared.media.task,
+                    condition_labels=prepared.condition_labels,
+                    image_grid_thw=vision_kwargs.get("image_grid_thw"),
+                    video_grid_thw=vision_kwargs.get("video_grid_thw"),
+                    video_timestamps=prepared.video_timestamps,
+                    merge_size=int(self.processor.image_processor.merge_size),
+                )
+            except Exception as exc:
+                error = exc
+        _broadcast_rank0_exception(error)
+        if rank < self.text_encoder_tp_size:
+            ids = self._distribute_encode_inputs(ids, vision_kwargs)
+            hidden = self._encode_text_hidden(ids, vision_kwargs)
+        return (
+            _broadcast_tensor(hidden, dtype=torch.bfloat16, device=self.device),
+            _broadcast_tensor(tags, dtype=torch.long, device=self.device),
+        )
+
+    def _distribute_media_inputs(self, media: MiniMaxH3EncoderMediaInput | None) -> MiniMaxH3EncoderMediaInput:
+        group, rank, world_size = _dit_rank_world()
+        if world_size == 1:
+            assert media is not None
+            return media
+        tensors = media.to_mm_tensors() if media is not None else []
+        header = [(media.to_metadata(), [value.dtype for value in tensors])] if media is not None else [None]
+        dist.broadcast_object_list(header, src=0, group=group)
+        metadata, dtypes = header[0]
+        received = []
+        for index, dtype in enumerate(dtypes):
+            value = _broadcast_tensor(tensors[index] if rank == 0 else None, dtype=dtype, device=self.device)
+            if rank != 0:
+                received.append(value.cpu())
+            del value
+        if rank == 0:
+            assert media is not None
+            return media
+        return MiniMaxH3EncoderMediaInput.from_mm_tensors(received, metadata)
+
+    def _broadcast_media_conditioning(
+        self, conditioning: MiniMaxH3EncoderMediaConditioning | None
+    ) -> MiniMaxH3EncoderMediaConditioning:
+        group, rank, world_size = _dit_rank_world()
+        if world_size == 1:
+            assert conditioning is not None
+            return conditioning
+        tensor_names = ("visual_condition", "audio_condition")
+        header = [None]
+        if rank == 0:
+            assert conditioning is not None
+            metadata = {
+                item.name: getattr(conditioning, item.name)
+                for item in fields(conditioning)
+                if item.name not in tensor_names
+            }
+            dtypes = {
+                name: value.dtype if (value := getattr(conditioning, name)) is not None else None
+                for name in tensor_names
+            }
+            header[0] = (metadata, dtypes)
+        dist.broadcast_object_list(header, src=0, group=group)
+        metadata, dtypes = header[0]
+        tensors = {}
+        for name, dtype in dtypes.items():
+            source = getattr(conditioning, name) if rank == 0 else None
+            tensors[name] = _broadcast_tensor(source, dtype=dtype, device=self.device) if dtype is not None else None
+        return MiniMaxH3EncoderMediaConditioning(**metadata, **tensors)
+
+    def _encode_local_media(self, media: MiniMaxH3EncoderMediaInput | None) -> MiniMaxH3EncoderMediaConditioning:
+        group, rank, world_size = _dit_rank_world()
+        distributed_video = self.video_vae.is_distributed_enabled()
+        if distributed_video:
+            media = self._distribute_media_inputs(media)
+        conditioning = None
+        error = None
+        try:
+            if rank == 0 or distributed_video:
+                assert media is not None
+                conditioning = encode_media(
+                    media,
+                    video_vae=self.video_vae,
+                    audio_vae=self.audio_vae,
+                    emit_conditioning=rank == 0,
+                    component_scope=self._component_on_device,
+                )
+        except ValueError as exc:
+            error = OmniClientError(str(exc))
+        except Exception as exc:
+            error = exc
+        if world_size > 1:
+            # All participants finish the codec phase before any latent broadcast.
+            errors = [None] * world_size
+            info = (str(error), isinstance(error, OmniClientError)) if error is not None else None
+            dist.all_gather_object(errors, info, group=group)
+            for info in errors:
+                if info is not None:
+                    if error is not None:
+                        raise error
+                    message, is_client_error = info
+                    raise OmniClientError(message) if is_client_error else RuntimeError(message)
+        elif error is not None:
+            raise error
+        return self._broadcast_media_conditioning(conditioning)
+
+    def _prepare_local_conditioning(
         self,
+        raw_prompt: Any,
+        sampling: Any,
         *,
-        prompt: str,
-        multi_modal_data: dict[str, Any],
+        require_external_text: bool = False,
+    ) -> MiniMaxH3EncoderConditioning:
+        group, rank, world_size = _dit_rank_world()
+        prepared = text_conditioning = None
+        error = None
+        if rank == 0:
+            try:
+                _, multi_modal_data = self._extract_prompt(raw_prompt)
+                turbo_spec = self._active_turbo_spec(sampling)
+                has_native_lora = self._has_active_native_lora(sampling)
+                task = self._resolve_task(
+                    (sampling.extra_args or {}).get("task"),
+                    multi_modal_data,
+                    turbo_spec=turbo_spec,
+                    has_native_lora=has_native_lora,
+                )
+                if turbo_spec is not None:
+                    self._validate_turbo_sampling(sampling, turbo_spec)
+                if has_native_lora:
+                    self._validate_native_sampling(sampling, task=task)
+                text_conditioning = self._extract_text_conditioning(raw_prompt)
+                if require_external_text and text_conditioning is None:
+                    raise OmniClientError(
+                        "MiniMax H3 diffusion stage requires text encoder conditioning when text_encoder is not loaded"
+                    )
+                prepared = prepare_encoder_inputs(
+                    raw_prompt,
+                    sampling,
+                    task=task,
+                    prepared_reference_videos=self._extract_prepared_reference_videos(raw_prompt),
+                )
+            except Exception as exc:
+                error = exc
+        _broadcast_rank0_exception(error)
+        reuse_text = [text_conditioning is not None]
+        if world_size > 1:
+            dist.broadcast_object_list(reuse_text, src=0, group=group)
+        if reuse_text[0]:
+            hidden = _broadcast_tensor(
+                text_conditioning.hidden_states if rank == 0 else None,
+                dtype=torch.bfloat16,
+                device=self.device,
+            )
+            tags = _broadcast_tensor(
+                text_conditioning.token_tags if rank == 0 else None, dtype=torch.long, device=self.device
+            )
+        else:
+            hidden, tags = self.encode_prompt(prepared)
+        media = self._encode_local_media(prepared.media if prepared is not None else None)
+        return MiniMaxH3EncoderConditioning.from_components(MiniMaxH3TextConditioning(hidden, tags), media)
+
+    def _prepare_request_inputs(self, raw_prompt: Any, sampling: Any) -> dict[str, Any]:
+        if self.load_text_encoder:
+            conditioning = self._prepare_local_conditioning(raw_prompt, sampling)
+        elif self.load_vae_encoder:
+            conditioning = self._prepare_local_conditioning(
+                raw_prompt,
+                sampling,
+                require_external_text=True,
+            )
+        else:
+            conditioning = self._extract_encoder_conditioning(raw_prompt)
+        return self._prepare_encoder_conditioning_inputs(conditioning, sampling)
+
+    @staticmethod
+    def _extract_encoder_conditioning(prompt: Any) -> MiniMaxH3EncoderConditioning:
+        if isinstance(prompt, list):
+            prompt = prompt[0] if prompt else None
+        additional_information = prompt.get("additional_information") if isinstance(prompt, Mapping) else None
+        payload = additional_information.get("encoder_output") if isinstance(additional_information, Mapping) else None
+        if not isinstance(payload, Mapping) or not payload:
+            raise OmniClientError("MiniMax H3 diffusion stage requires encoder conditioning from the encoder stage")
+        try:
+            return MiniMaxH3EncoderConditioning.from_omni_payload(payload)
+        except ValueError as exc:
+            raise OmniClientError(str(exc)) from exc
+
+    def _prepare_encoder_conditioning_inputs(
+        self,
+        conditioning: MiniMaxH3EncoderConditioning,
         sampling: Any,
-        text_conditioning: MiniMaxH3TextConditioning | None = None,
-        prepared_reference_videos: list[dict[str, Any]] | None = None,
     ) -> dict[str, Any]:
-        """Resolve the task and output shape, then run every request-level encode.
-
-        Shared by request-mode :meth:`forward` and step-mode
-        :meth:`prepare_encode`; the returned mapping feeds :meth:`diffuse` and
-        :meth:`_build_denoise_inputs` unchanged.
-        """
-        quality = sampling.quality
-        logger.debug("MiniMax H3 request quality=%s", quality)
         extra = sampling.extra_args or {}
-        preencode_batch_frames = (
-            normalize_preencode_batch_frames(extra.get("preencode_batch_frames", 17))
-            if extra.get("preencode_mp4", False)
-            else 17
-        )
+        requested_task = extra.get("task")
+        if requested_task is not None and str(requested_task).lower() != conditioning.task:
+            raise OmniClientError(
+                f"MiniMax H3 encoder task {conditioning.task!r} does not match diffusion request {requested_task!r}"
+            )
         turbo_spec = self._active_turbo_spec(sampling)
         has_native_lora = self._has_active_native_lora(sampling)
         task = self._resolve_task(
-            extra.get("task"),
-            multi_modal_data,
+            conditioning.task,
             turbo_spec=turbo_spec,
             has_native_lora=has_native_lora,
         )
@@ -2411,263 +2063,73 @@ def _prepare_request_inputs(
                 audio_shift=self.default_audio_shift,
             )
 
-        raw_image = multi_modal_data.get("image")
-        raw_videos = multi_modal_data.get("video")
-        raw_audio = multi_modal_data.get("audio")
-        images = _load_images(raw_image) if raw_image is not None else []
-        video_values = list(raw_videos) if isinstance(raw_videos, (list, tuple)) else raw_videos
-        audio_values = list(raw_audio) if isinstance(raw_audio, (list, tuple)) else raw_audio
-
-        if task == "t2va" and (images or raw_videos is not None or raw_audio is not None):
-            raise OmniClientError("t2va does not accept image, video, or audio conditions")
-        if task == "fl2va":
-            if not images:
-                raise OmniClientError("fl2va requires multi_modal_data.image")
-            if len(images) > 2:
-                raise OmniClientError("fl2va accepts at most first and last images")
-            if raw_videos is not None or raw_audio is not None:
-                raise OmniClientError("fl2va accepts image keyframes only")
-        if task == "ref2va":
-            video_count = (
-                len(video_values) if isinstance(video_values, (list, tuple)) else int(video_values is not None)
-            )
-            audio_is_waveform_pair = (
-                isinstance(raw_audio, (list, tuple))
-                and len(raw_audio) == 2
-                and isinstance(raw_audio[1], (int, np.integer))
+        if conditioning.height % 32 or conditioning.width % 32:
+            raise OmniClientError(
+                f"MiniMax H3 encoder canvas must be divisible by 32, got {conditioning.width}x{conditioning.height}"
             )
-            audio_count = (
-                len(audio_values)
-                if isinstance(audio_values, (list, tuple)) and not audio_is_waveform_pair
-                else int(raw_audio is not None)
+        expected_latent_t = MINIMAX_H3_SHAPE_PLANNER.video_latent_t(conditioning.num_frames)
+        expected_audio_t = MINIMAX_H3_SHAPE_PLANNER.audio_latent_t(conditioning.num_frames / MINIMAX_H3_FPS)
+        if (conditioning.latent_t, conditioning.audio_t) != (expected_latent_t, expected_audio_t):
+            raise OmniClientError(
+                "MiniMax H3 encoder latent shape does not match its output frame count: "
+                f"got ({conditioning.latent_t}, {conditioning.audio_t}), expected "
+                f"({expected_latent_t}, {expected_audio_t})"
             )
-            _validate_ref2va_reference_counts(len(images), video_count, audio_count)
-        elif raw_videos is not None:
-            raise OmniClientError(f"{task} does not accept a video condition")
-
-        image = images[0] if images else None
-        height, width, num_frames, latent_t, audio_t = self._resolve_shape(task, sampling, image)
-        if task == "fl2va":
-            for item in images:
-                _validate_reference_image(item)
-            prepared_images = [item.resize((width, height), Image.Resampling.LANCZOS) for item in images]
-            keyframe_frame_indices = _resolve_fl2va_keyframe_indices(extra, len(images))
-        elif task == "ref2va":
-            prepared_images = []
-            for item in images:
-                ref_width, ref_height = _reference_image_shape(item)
-                prepared_images.append(item.resize((ref_width, ref_height), Image.Resampling.LANCZOS))
-            keyframe_frame_indices = None
-        else:
-            prepared_images = []
-            keyframe_frame_indices = None
-
-        visual_condition = None
-        visual_shape = None
-        visual_shapes = None
-        audio_condition = None
-        ref_audio_t = None
-        audio_lengths = None
-        ref_blocks = None
-        with tempfile.TemporaryDirectory(prefix="minimax_h3_ref2va_") as workdir:
-            prepared_videos = None
-            has_audio: list[bool] = []
-            video_count = 0
-            if raw_videos is not None:
-                video_count = len(raw_videos) if isinstance(raw_videos, (list, tuple)) else 1
-                # File-based reference-video prep runs only on rank 0; other
-                # ranks return None without touching disk. If rank 0 raises
-                # (e.g. invalid file, unsupported codec) it must not exit
-                # ``prepare_encode`` before the downstream broadcasts below --
-                # non-zero ranks would then deadlock on them forever. Capture
-                # the exception here and let every rank agree on the outcome
-                # before starting any subsequent collective.
-                prep_error: Exception | None = None
-                try:
-                    _, rank, _ = _dit_rank_world()
-                    if prepared_reference_videos is not None:
-                        if rank == 0:
-                            prepared_videos = _reuse_prepared_reference_videos(
-                                prepared_reference_videos,
-                                expected_count=video_count,
-                            )
-                    else:
-                        prepared_videos = self._prepare_reference_videos(
-                            raw_videos,
-                            target_frame_count=num_frames,
-                            workdir=workdir,
-                            start_time_seconds=extra.get("start_time_seconds"),
-                        )
-                except Exception as exc:
-                    prep_error = exc
-                _broadcast_rank0_exception(prep_error)
-                has_audio_tensor = torch.zeros(
-                    video_count,
-                    dtype=torch.long,
-                    device=self.device,
-                )
-                _, rank, world_size = _dit_rank_world()
-                if rank == 0:
-                    has_audio_tensor = torch.tensor(
-                        [int(item["input_has_audio"]) for item in prepared_videos or []],
-                        dtype=torch.long,
-                        device=self.device,
-                    )
-                if world_size > 1:
-                    dist.broadcast(
-                        has_audio_tensor,
-                        src=0,
-                        group=get_world_group().device_group,
-                    )
-                has_audio = [bool(value) for value in has_audio_tensor.tolist()]
-
-            if raw_audio is not None:
-                validate_reference_audio_files(raw_audio)
-            standalone_audios = _load_audios(raw_audio) if raw_audio is not None else []
-            validate_reference_audio_waveforms(standalone_audios)
-            condition_labels: list[tuple[str, int]] = []
-            for image_index in range(1, len(prepared_images) + 1):
-                condition_labels.append(("image", image_index))
-            audio_index = 0
-            for video_index, item in enumerate(prepared_videos or (), start=1):
-                if item["input_has_audio"]:
-                    audio_index += 1
-                    condition_labels.append(("audio", audio_index))
-                condition_labels.append(("video", video_index))
-            for _ in standalone_audios:
-                audio_index += 1
-                condition_labels.append(("audio", audio_index))
-
-            if text_conditioning is not None:
-                text_embeddings = text_conditioning.hidden_states.to(
-                    device=self.device,
-                    dtype=torch.bfloat16,
-                )
-                text_tags = text_conditioning.token_tags.to(
-                    device=self.device,
-                    dtype=torch.long,
-                )
-            elif getattr(self, "text_encoder", None) is not None:
-                text_embeddings, text_tags = self.encode_prompt(
-                    task=task,
-                    prompt=prompt,
-                    images=prepared_images,
-                    prepared_videos=prepared_videos,
-                    condition_labels=condition_labels if task == "ref2va" else None,
-                )
-            else:
-                raise OmniClientError(
-                    "MiniMax H3 diffusion stage requires text_encoder_output when text_encoder is not loaded"
-                )
 
-            # ``prepared_videos`` is intentionally ``None`` on non-zero DiT
-            # ranks; the distributed video encoder broadcasts the prepared
-            # metadata inside ``_encode_visual_conditions``.  Use the global
-            # video count here so video + standalone-audio Ref2VA requests do
-            # not look like audio-only requests on those ranks.
-            if video_count or prepared_images:
-                visual_condition, visual_shapes = self._encode_visual_conditions(
-                    prepared_images,
-                    prepared_videos,
-                    video_count=video_count,
-                )
-                (
-                    embedded_audio_condition,
-                    embedded_audio_lengths,
-                    external_audio_condition,
-                    external_audio_lengths,
-                ) = self._encode_reference_audio_conditions(
-                    prepared_videos,
-                    has_audio=has_audio,
-                    standalone_audios=standalone_audios,
-                    max_duration_seconds=float(num_frames) / float(sampling.fps or MINIMAX_H3_FPS),
-                )
-                audio_parts = [
-                    item for item in (embedded_audio_condition, external_audio_condition) if item is not None
-                ]
-                audio_condition = torch.cat(audio_parts) if audio_parts else None
-                audio_lengths = embedded_audio_lengths + external_audio_lengths
-                ref_blocks = []
-                image_shapes = visual_shapes[: len(prepared_images)]
-                video_shapes = visual_shapes[len(prepared_images) :]
-                for shape in image_shapes:
-                    ref_blocks.append(
-                        {
-                            "kind": "image",
-                            "latent_h": shape[1],
-                            "latent_w": shape[2],
-                        }
-                    )
-                audio_iterator = iter(embedded_audio_lengths)
-                for shape, contributes_audio in zip(video_shapes, has_audio, strict=True):
-                    ref_audio = next(audio_iterator) if contributes_audio else 0
-                    ref_blocks.append(
-                        {
-                            "kind": "video_audio" if ref_audio else "video",
-                            "ref_audio_t": ref_audio,
-                            "latent_t": shape[0],
-                            "latent_h": shape[1],
-                            "latent_w": shape[2],
-                        }
-                    )
-                for ref_audio_t in external_audio_lengths:
-                    ref_blocks.append({"kind": "audio", "ref_audio_t": ref_audio_t})
-            elif standalone_audios:
-                raise OmniClientError("standalone audio references require a Ref2VA visual reference")
-
-            if visual_shapes and len(visual_shapes) == 1:
-                visual_shape = visual_shapes[0]
-            if audio_lengths:
-                if any(length < 80 or length > 600 for length in audio_lengths):
-                    raise OmniClientError("MiniMax H3 audio references must each be between 2 and 15 seconds")
-                # Video soundtracks and standalone audio have separate
-                # 15-second budgets, validated before encoding. Do not merge
-                # those budgets when concatenating their conditioning rows.
-                if len(audio_lengths) == 1:
-                    ref_audio_t = audio_lengths[0]
-
-        seed = int(sampling.seed if sampling.seed is not None else 42)
+        visual_shapes = list(conditioning.visual_condition_shapes) or None
+        audio_lengths = list(conditioning.audio_condition_lengths) or None
+
         base_schedule, num_steps = self._resolve_sigma_positions(task, sampling)
-        video_shift = float(extra.get("flow_shift", self.default_video_shift))
-        audio_shift = float(extra.get("audio_flow_shift", self.default_audio_shift))
-        pad_seq_len = _resolve_pad_seq_len(extra.get("pad_seq_len"))
         quality_plan = self._quality_policy.resolve(
-            quality=quality,
+            quality=sampling.quality,
             num_inference_steps=num_steps,
             extra_args=extra,
         )
         self._cache_dit_runtime.prepare(quality_plan.cache_dit)
-        num_outputs = _resolve_minimax_h3_num_outputs(sampling.num_outputs_per_prompt)
         return {
             "task": task,
-            "height": height,
-            "width": width,
-            "num_frames": num_frames,
-            "latent_t": latent_t,
-            "latent_h": height // 16,
-            "latent_w": width // 16,
-            "audio_t": audio_t,
-            "text_embeddings": text_embeddings,
-            "text_tags": text_tags,
-            "visual_condition": visual_condition,
-            "visual_condition_shape": visual_shape,
-            "audio_condition": audio_condition,
-            "ref_audio_t": ref_audio_t,
-            "ref_blocks": ref_blocks,
+            "height": conditioning.height,
+            "width": conditioning.width,
+            "num_frames": conditioning.num_frames,
+            "latent_t": conditioning.latent_t,
+            "latent_h": conditioning.height // 16,
+            "latent_w": conditioning.width // 16,
+            "audio_t": conditioning.audio_t,
+            "text_embeddings": conditioning.hidden_states.to(device=self.device, dtype=torch.bfloat16),
+            "text_tags": conditioning.token_tags.to(device=self.device, dtype=torch.long),
+            "visual_condition": (
+                conditioning.visual_condition.to(device=self.device)
+                if conditioning.visual_condition is not None
+                else None
+            ),
+            "visual_condition_shape": visual_shapes[0] if visual_shapes and len(visual_shapes) == 1 else None,
+            "audio_condition": (
+                conditioning.audio_condition.to(device=self.device)
+                if conditioning.audio_condition is not None
+                else None
+            ),
+            "ref_audio_t": audio_lengths[0] if audio_lengths and len(audio_lengths) == 1 else None,
+            "ref_blocks": list(conditioning.ref_blocks) or None,
             "visual_condition_shapes": visual_shapes,
             "audio_condition_lengths": audio_lengths,
-            "keyframe_frame_indices": keyframe_frame_indices,
-            "pad_seq_len": pad_seq_len,
-            "seed": seed,
+            "keyframe_frame_indices": list(conditioning.keyframe_frame_indices) or None,
+            "pad_seq_len": _resolve_pad_seq_len(extra.get("pad_seq_len")),
+            "seed": int(sampling.seed if sampling.seed is not None else 42),
             "num_steps": num_steps,
-            "video_shift": video_shift,
-            "audio_shift": audio_shift,
+            "video_shift": float(extra.get("flow_shift", self.default_video_shift)),
+            "audio_shift": float(extra.get("audio_flow_shift", self.default_audio_shift)),
             "base_schedule": base_schedule,
-            "num_outputs": num_outputs,
+            "num_outputs": _resolve_minimax_h3_num_outputs(sampling.num_outputs_per_prompt),
             "preencode_mp4": bool(extra.get("preencode_mp4", False)),
-            "preencode_batch_frames": preencode_batch_frames,
+            "preencode_batch_frames": (
+                normalize_preencode_batch_frames(extra.get("preencode_batch_frames", 17))
+                if extra.get("preencode_mp4", False)
+                else 17
+            ),
             "video_codec_options": normalize_video_codec_options(
                 extra.get("video_codec_options", {"preset": "ultrafast", "threads": "0"})
+                if extra.get("preencode_mp4", False)
+                else None
             ),
         }
 
@@ -2680,14 +2142,9 @@ def _denoise_kwargs(context: dict[str, Any]) -> dict[str, Any]:
     def forward(self, request: DiffusionRequestBatch) -> DiffusionOutput:
         if len(request.prompts) != 1:
             raise OmniClientError("MiniMax H3 supports one request at a time")
-        raw_prompt = request.prompts[0]
-        prompt, multi_modal_data = self._extract_prompt(raw_prompt)
         context = self._prepare_request_inputs(
-            prompt=prompt,
-            multi_modal_data=multi_modal_data,
-            sampling=request.sampling_params,
-            text_conditioning=self._extract_text_conditioning(raw_prompt),
-            prepared_reference_videos=self._extract_prepared_reference_videos(raw_prompt),
+            request.prompts[0],
+            request.sampling_params,
         )
         denoise_kwargs = self._denoise_kwargs(context)
         num_outputs = context["num_outputs"]
@@ -2794,13 +2251,9 @@ def prepare_encode(self, state: StepRequestState, **kwargs: Any) -> StepRequestS
                 "co-batched requests would reuse incompatible cache state. Drop --step-execution "
                 "or omit quality=high."
             )
-        prompt, multi_modal_data = self._extract_prompt(state.prompt)
         context = self._prepare_request_inputs(
-            prompt=prompt,
-            multi_modal_data=multi_modal_data,
-            sampling=state.sampling,
-            text_conditioning=self._extract_text_conditioning(state.prompt),
-            prepared_reference_videos=self._extract_prepared_reference_videos(state.prompt),
+            state.prompt,
+            state.sampling,
         )
         inputs = self._build_denoise_inputs(**self._denoise_kwargs(context))
 
diff --git a/vllm_omni/diffusion/models/minimax_h3/vae.py b/vllm_omni/diffusion/models/minimax_h3/vae.py
index e40251dff3c..d026492292b 100644
--- a/vllm_omni/diffusion/models/minimax_h3/vae.py
+++ b/vllm_omni/diffusion/models/minimax_h3/vae.py
@@ -15,8 +15,10 @@
 import torch.distributed as dist
 import torch.nn as nn
 from PIL import Image
+from safetensors import safe_open
 from transformers.dynamic_module_utils import get_class_from_dynamic_module
 from vllm.logger import init_logger
+from vllm.utils.torch_utils import set_default_torch_dtype
 
 from vllm_omni.diffusion.distributed.autoencoders.distributed_vae_executor import (
     DistributedVaeMixin,
@@ -106,6 +108,121 @@ def _load_remote_component(
         return component_cls.from_pretrained(component_path)
 
 
+def _check_trust_remote_code(
+    component_path: str,
+    config: dict[str, Any],
+    trust_remote_code: bool,
+) -> None:
+    """Apply the remote-code gate before either full or encoder-only loading."""
+
+    class_reference = (config.get("auto_map") or {}).get("AutoModel")
+    if isinstance(class_reference, str) and not trust_remote_code:
+        raise ValueError(
+            f"Loading {component_path} executes the modeling code shipped with "
+            f"the checkpoint (auto_map.AutoModel = {class_reference}). Pass "
+            "--trust-remote-code (or trust_remote_code=True) to allow it."
+        )
+
+
+def _load_selected_state_dict(
+    model: nn.Module,
+    weights_path: Path,
+    prefixes: tuple[str, ...],
+) -> None:
+    with safe_open(str(weights_path), framework="pt", device="cpu") as checkpoint:
+        selected = sorted(name for name in checkpoint.keys() if name.startswith(prefixes))
+        if not selected:
+            raise ValueError(f"{weights_path}: no VAE weights match prefixes {prefixes!r}")
+        state_dict = {name: checkpoint.get_tensor(name) for name in selected}
+    model.load_state_dict(state_dict, strict=True)
+
+
+def _remove_modules(model: nn.Module, names: tuple[str, ...]) -> None:
+    for name in names:
+        if not isinstance(getattr(model, name, None), nn.Module):
+            raise ValueError(f"MiniMax H3 VAE model has no module {name!r}")
+        delattr(model, name)
+
+
+def _load_video_vae_encoder(
+    component_path: str,
+    config: dict[str, Any],
+) -> nn.Module:
+    class_reference = (config.get("auto_map") or {}).get("AutoModel")
+    if not isinstance(class_reference, str):
+        raise ValueError(f"{component_path}/config.json must define auto_map.AutoModel")
+    component_cls = get_class_from_dynamic_module(class_reference, component_path)
+    component_module = importlib.import_module(component_cls.__module__)
+    source_classes = getattr(component_module, "_SOURCE_CLASSES", None)
+    source_class_name = config.get("source_class_name")
+    if not isinstance(source_classes, dict) or source_class_name not in source_classes:
+        raise ValueError(f"unsupported MiniMax H3 video VAE source class {source_class_name!r}")
+    if bool(config["vae_parallel_tiling"]):
+        ensure_parallel_state = getattr(component_module, "_ensure_vae_parallel_state", None)
+        if not callable(ensure_parallel_state):
+            raise ValueError("MiniMax H3 video VAE remote module does not expose its parallel-state initializer")
+        ensure_parallel_state()
+
+    source_path = Path(component_path) / str(config["source_path"])
+    weights_path = source_path / str(config["source_safetensors_path"])
+    load_kwargs = {
+        "clip_length": int(config["vae_clip_length"]),
+        "token_drop": int(config["vae_token_drop"]),
+        "encoder_tiling": int(config["vae_encoder_tiling"]),
+        "decoder_tiling": int(config["vae_decoder_tiling"]),
+        "parallel_tiling": int(config["vae_parallel_tiling"]),
+        "tile_size": int(config["vae_tile_size"]),
+        "tile_overlap_min": int(config["vae_tile_overlap_min"]),
+        "encoder_parallel": int(config["vae_encoder_parallel"]),
+        "decoder_parallel": int(config["vae_decoder_parallel"]),
+        "chunk_dim": int(config["vae_chunk_dim"]),
+    }
+    source_cls = source_classes[source_class_name]
+    source_config = source_cls.load_config(str(source_path))
+    with set_default_torch_dtype(torch.float32), torch.device("cpu"):
+        model, _unused = source_cls.from_config(source_config, return_unused_kwargs=True, **load_kwargs)
+    _remove_modules(model, ("decoder", "post_quant_conv"))
+    _load_selected_state_dict(model, weights_path, ("encoder.", "quant_conv."))
+    model.eval()
+    return component_cls(model)
+
+
+def _load_audio_vae_encoder(
+    component_path: str,
+    config: dict[str, Any],
+) -> nn.Module:
+    class_reference = (config.get("auto_map") or {}).get("AutoModel")
+    if not isinstance(class_reference, str):
+        raise ValueError(f"{component_path}/config.json must define auto_map.AutoModel")
+    component_cls = get_class_from_dynamic_module(class_reference, component_path)
+    component_module = importlib.import_module(component_cls.__module__)
+    load_yaml = getattr(component_module, "_load_yaml", None)
+    model_cls = getattr(component_module, "DacAudioVAE", None)
+    if not callable(load_yaml) or not isinstance(model_cls, type):
+        raise ValueError("MiniMax H3 audio VAE remote module does not expose its source loader")
+
+    component_dir = Path(component_path)
+    audio_config = load_yaml(component_dir / str(config["source_config_path"]))
+    metadata_path = component_dir / str(config["source_metadata_path"])
+    metadata_doc = json.loads(metadata_path.read_text(encoding="utf-8"))
+    metadata = metadata_doc["metadata"]["kwargs"]
+    with set_default_torch_dtype(torch.float32), torch.device("cpu"):
+        model = model_cls(
+            encoder_rates=metadata["encoder_rates"],
+            decoder_rates=metadata["decoder_rates"],
+            attn_proj=metadata["attn_proj"],
+            decoder_type=metadata["decoder_type"],
+            decoder_dim=audio_config["model_config"]["decoder_dim"],
+            vae_latent_channels=audio_config["model_config"]["vae_latent_channels"],
+            sample_rate=metadata["sample_rate"],
+        )
+    _remove_modules(model, ("decoder", "dec_in_proj", "logs_proj"))
+    weights_path = component_dir / str(config["source_safetensors_path"])
+    _load_selected_state_dict(model, weights_path, ("encoder.", "pre_block.", "mean_proj."))
+    model.eval()
+    return component_cls(model)
+
+
 class _AudioVAEDeterminismContext(AbstractContextManager):
     def __enter__(self):
         backends = torch.backends
@@ -156,16 +273,24 @@ def __init__(
         *,
         device: torch.device,
         load_device: torch.device | None = None,
+        encode_only: bool = False,
+        decode_only: bool = False,
         trust_remote_code: bool = False,
     ) -> None:
         super().__init__()
         self._device_target = device
+        self.encode_only = bool(encode_only)
+        self.decode_only = bool(decode_only)
+        if self.encode_only and self.decode_only:
+            raise ValueError("MiniMax H3 video VAE cannot be both encode-only and decode-only")
         self.config_dict = _load_component_config(component_path)
-        self.remote = _load_remote_component(
-            component_path,
-            self.config_dict,
-            trust_remote_code=trust_remote_code,
-        )
+        _check_trust_remote_code(component_path, self.config_dict, trust_remote_code)
+        if self.encode_only:
+            self.remote = _load_video_vae_encoder(component_path, self.config_dict)
+        else:
+            self.remote = _load_remote_component(component_path, self.config_dict, trust_remote_code=trust_remote_code)
+            if self.decode_only:
+                _remove_modules(self.remote.model, ("encoder", "quant_conv"))
         # Match the reference loader contract before installing inference-only
         # decoder fast paths. Keyframe encoding remains FP32; decoder Linear
         # weights may be materialized in FP16 because reference decode casts
@@ -222,10 +347,11 @@ def set_parallel_size(
         self,
         parallel_size: int,
         mode: str = "tile",
+        process_group: dist.ProcessGroup | None = None,
     ) -> None:
         if mode != "tile":
             raise ValueError(f"MiniMax H3 VAE supports its native tile parallel mode only, got {mode!r}")
-        group = get_world_group().device_group
+        group = process_group if process_group is not None else get_world_group().device_group
         world_size = dist.get_world_size(group)
         rank = dist.get_rank(group)
         parallel_size = int(parallel_size)
@@ -412,15 +538,40 @@ def _decoder_tile_count(self, latent: torch.Tensor) -> int:
         cols, _, _ = self.model.split_tiles(int(latent.shape[-1]) * ratio, True)
         return len(rows) * len(cols)
 
-    @contextmanager
-    def _rank_local_tiling(self) -> Iterator[None]:
-        """Run one decode with tiling kept on this rank, then restore the group.
+    def _encoder_tile_count(self, height: int, width: int) -> int:
+        processor = getattr(self.model, "processor", None)
+        align = getattr(processor, "_align_to_total_patch_size", None)
+        if callable(align):
+            height, width = align(int(height), int(width))
+        rows, _, _ = self.model.split_tiles(int(height), False)
+        cols, _, _ = self.model.split_tiles(int(width), False)
+        return len(rows) * len(cols)
 
-        Used only when there are fewer tiles than ranks. Every rank then decodes
-        every tile, which is slower than sharing the work but is correct and
-        involves no collective.
-        """
+    def _encoder_tiling_context(
+        self,
+        height: int,
+        width: int,
+    ) -> AbstractContextManager:
+        parallel_size = int(getattr(self, "parallel_size", 1))
+        if parallel_size <= 1:
+            return nullcontext()
+        num_tiles = self._encoder_tile_count(height, width)
+        if num_tiles >= parallel_size:
+            return nullcontext()
+        logger.warning_once(
+            "MiniMax-H3 VAE encode splits a %dx%d input into %d tile(s) but "
+            "the tile group has %d ranks; encoding rank-locally for this "
+            "shape instead, which avoids ranks without tiles hanging the "
+            "collective.",
+            width,
+            height,
+            num_tiles,
+            parallel_size,
+        )
+        return self._rank_local_tiling()
 
+    @contextmanager
+    def _rank_local_tiling(self) -> Iterator[None]:
         state = self._native_parallel_state()
         saved_state = dict(state)
         saved_tiling = self.model.parallel_tiling
@@ -448,15 +599,24 @@ def is_distributed_enabled(self) -> bool:
 
     @torch.inference_mode()
     def encode_image(self, image: Image.Image) -> torch.Tensor:
+        if getattr(self, "decode_only", False):
+            raise RuntimeError("MiniMax H3 decode-only video VAE cannot encode images")
         previous_parallel = self.model.parallel_tiling
-        self.model.parallel_tiling = False
+        if int(getattr(self, "parallel_size", 1)) <= 1:
+            self.model.parallel_tiling = False
         parameter = next(self.parameters())
         previous_dtype = parameter.dtype
         if previous_dtype != torch.float32:
             self.to(torch.float32)
         devices = [parameter.device] if parameter.device.type != "cpu" else []
         try:
-            with torch.random.fork_rng(devices=devices, device_type=parameter.device.type):
+            with (
+                self._encoder_tiling_context(image.height, image.width),
+                torch.random.fork_rng(
+                    devices=devices,
+                    device_type=parameter.device.type,
+                ),
+            ):
                 torch.default_generator.manual_seed(MINIMAX_H3_KEYFRAME_ENCODE_SEED)
                 for device in devices:
                     with self.device_module.device(device):
@@ -495,13 +655,26 @@ def encode_video(
         self,
         frames: Any,
     ) -> tuple[torch.Tensor, tuple[int, int, int]]:
+        if getattr(self, "decode_only", False):
+            raise RuntimeError("MiniMax H3 decode-only video VAE cannot encode videos")
         parameter = next(self.parameters())
         previous_dtype = parameter.dtype
         if previous_dtype != torch.float32:
             self.to(torch.float32)
         devices = [parameter.device] if parameter.device.type != "cpu" else []
+        shape = getattr(frames, "shape", None)
+        if int(getattr(self, "parallel_size", 1)) > 1:
+            if shape is None or len(shape) != 4:
+                raise ValueError("parallel MiniMax H3 video encode requires a rank-4 frame array")
+            if int(shape[-1]) in {1, 3, 4}:
+                frame_height, frame_width = int(shape[-3]), int(shape[-2])
+            else:
+                frame_height, frame_width = int(shape[-2]), int(shape[-1])
+            tiling_context = self._encoder_tiling_context(frame_height, frame_width)
+        else:
+            tiling_context = nullcontext()
         try:
-            with torch.random.fork_rng(devices=devices, device_type=parameter.device.type):
+            with tiling_context, torch.random.fork_rng(devices=devices, device_type=parameter.device.type):
                 torch.default_generator.manual_seed(MINIMAX_H3_KEYFRAME_ENCODE_SEED)
                 for device in devices:
                     with self.device_module.device(device):
@@ -561,6 +734,8 @@ def _decode_tiling_context(self, latent: torch.Tensor) -> AbstractContextManager
 
     @torch.inference_mode()
     def decode_latent(self, latent: torch.Tensor) -> torch.Tensor:
+        if getattr(self, "encode_only", False):
+            raise RuntimeError("MiniMax H3 encode-only video VAE cannot decode latents")
         with self._decode_tiling_context(latent):
             decoded = self.model.decode_base(self._denormalize_latent(latent))
         return self._normalize_decoded_frames(self.model.processor.revert_tensor(decoded))
@@ -598,6 +773,8 @@ def decode_with_chunks(self, z: torch.Tensor, *, on_chunk: DecodedChunkConsumer)
         the complete decode path. After a callback failure, the remaining
         chunks are decoded and discarded before the exception is re-raised.
         """
+        if getattr(self, "encode_only", False):
+            raise RuntimeError("MiniMax H3 encode-only video VAE cannot decode latents")
         if not callable(on_chunk):
             raise TypeError("on_chunk must be callable")
         if not callable(getattr(self.model, "_adaptive_decode", None)):
@@ -622,16 +799,24 @@ def __init__(
         *,
         device: torch.device,
         load_device: torch.device | None = None,
+        encode_only: bool = False,
+        decode_only: bool = False,
         trust_remote_code: bool = False,
     ) -> None:
         super().__init__()
         self._device_target = device
+        self.encode_only = bool(encode_only)
+        self.decode_only = bool(decode_only)
+        if self.encode_only and self.decode_only:
+            raise ValueError("MiniMax H3 audio VAE cannot be both encode-only and decode-only")
         self.config_dict = _load_component_config(component_path)
-        self.remote = _load_remote_component(
-            component_path,
-            self.config_dict,
-            trust_remote_code=trust_remote_code,
-        )
+        _check_trust_remote_code(component_path, self.config_dict, trust_remote_code)
+        if self.encode_only:
+            self.remote = _load_audio_vae_encoder(component_path, self.config_dict)
+        else:
+            self.remote = _load_remote_component(component_path, self.config_dict, trust_remote_code=trust_remote_code)
+            if self.decode_only:
+                _remove_modules(self.remote.model, ("encoder", "pre_block", "mean_proj"))
         # The checkpoint's audio VAE contract is FP32 for both reference
         # encoding and waveform decoding.
         initial_device = load_device or device
@@ -674,6 +859,8 @@ def encode_waveform(
         waveform: torch.Tensor,
         sample_rate: int,
     ) -> tuple[torch.Tensor, int]:
+        if getattr(self, "decode_only", False):
+            raise RuntimeError("MiniMax H3 decode-only audio VAE cannot encode waveforms")
         import torchaudio
 
         waveform = waveform.float()
@@ -719,6 +906,8 @@ def encode_waveform(
 
     @torch.inference_mode()
     def decode_latent(self, latent: torch.Tensor) -> torch.Tensor:
+        if getattr(self, "encode_only", False):
+            raise RuntimeError("MiniMax H3 encode-only audio VAE cannot decode latents")
         channels = int(self.config_dict["latent_channels"])
         mean = torch.tensor(
             self.config_dict["latents_mean"],
diff --git a/vllm_omni/model_executor/models/minimax_h3/checkpoint.py b/vllm_omni/model_executor/models/minimax_h3/checkpoint.py
index e8350f41a31..0143e9675b6 100644
--- a/vllm_omni/model_executor/models/minimax_h3/checkpoint.py
+++ b/vllm_omni/model_executor/models/minimax_h3/checkpoint.py
@@ -1,16 +1,19 @@
 # SPDX-License-Identifier: Apache-2.0
-"""MiniMax H3 checkpoint resolution for the AR text-encoder stage."""
-
 from pathlib import Path
 
 from vllm_omni.model_executor.model_loader.weight_utils import (
     download_weights_from_hf_specific,
 )
 
-MINIMAX_H3_TEXT_ENCODER_DOWNLOAD_PATTERNS = {
-    "fl2va": ["FL2VA/text_encoder/**"],
-    "ref2va": ["Ref2VA/text_encoder/**"],
+MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS = {
+    partition: [
+        f"{subdir}/text_encoder/**",
+        f"{subdir}/video_vae/**",
+        f"{subdir}/audio_vae/**",
+    ]
+    for partition, subdir in {"fl2va": "FL2VA", "ref2va": "Ref2VA"}.items()
 }
+MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS["combined"] = MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS["fl2va"]
 
 
 def resolve_minimax_h3_partition(
@@ -32,7 +35,7 @@ def resolve_minimax_h3_partition(
     return "ref2va" if task == "ref2va" else "fl2va"
 
 
-def resolve_minimax_h3_model_root(
+def resolve_minimax_h3_encoder_model_root(
     model: str,
     revision: str | None,
     task_type: str | None,
@@ -50,7 +53,7 @@ def resolve_minimax_h3_model_root(
     snapshot = download_weights_from_hf_specific(
         model_name_or_path=model,
         cache_dir=None,
-        allow_patterns=MINIMAX_H3_TEXT_ENCODER_DOWNLOAD_PATTERNS[partition],
+        allow_patterns=MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS[partition],
         revision=revision,
         require_all=True,
     )
@@ -59,4 +62,11 @@ def resolve_minimax_h3_model_root(
     return str(Path(snapshot) / subdir / "text_encoder")
 
 
-__all__ = ["resolve_minimax_h3_model_root", "resolve_minimax_h3_partition"]
+resolve_minimax_h3_model_root = resolve_minimax_h3_encoder_model_root
+
+
+__all__ = [
+    "resolve_minimax_h3_encoder_model_root",
+    "resolve_minimax_h3_model_root",
+    "resolve_minimax_h3_partition",
+]
diff --git a/vllm_omni/model_executor/models/minimax_h3/conditioning.py b/vllm_omni/model_executor/models/minimax_h3/conditioning.py
index efea25771a0..761292dc328 100644
--- a/vllm_omni/model_executor/models/minimax_h3/conditioning.py
+++ b/vllm_omni/model_executor/models/minimax_h3/conditioning.py
@@ -4,8 +4,8 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping
-from dataclasses import dataclass
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, fields
 from typing import Any
 
 import torch
@@ -119,3 +119,502 @@ def to_payload(self) -> dict[str, torch.Tensor]:
             "hidden_states": self.hidden_states,
             "token_tags": self.token_tags,
         }
+
+
+MINIMAX_H3_ENCODER_REQUEST_KEY = "minimax_h3_encoder_request"
+MINIMAX_H3_ENCODER_LAYOUT_KEY = "minimax_h3_encoder_layout"
+STAGE_SCHEMA_VERSION = 1
+_ENCODER_WIRE_SCHEMA_ID = 1
+
+_TASK_TO_CODE = {"t2va": 1, "fl2va": 2, "ref2va": 3}
+_CODE_TO_TASK = {value: key for key, value in _TASK_TO_CODE.items()}
+_REF_KIND_TO_CODE = {"image": 1, "video": 2, "video_audio": 3, "audio": 4}
+_CODE_TO_REF_KIND = {value: key for key, value in _REF_KIND_TO_CODE.items()}
+_INTEGER_DTYPES = frozenset(
+    {
+        torch.int8,
+        torch.int16,
+        torch.int32,
+        torch.int64,
+        torch.uint8,
+    }
+)
+_VIDEO_CONDITION_WIDTH = 96
+_AUDIO_CONDITION_WIDTH = 32
+_AUDIO_CONDITION_CHANNELS = 2
+
+
+def _wire_layout(payload: Mapping[str, Any]) -> torch.Tensor:
+    private_metadata = payload.get("kv_metadata")
+    if not isinstance(private_metadata, Mapping):
+        raise ValueError("MiniMax H3 wire payload requires private layout metadata")
+    layout = private_metadata.get(MINIMAX_H3_ENCODER_LAYOUT_KEY)
+    if isinstance(layout, torch.Tensor):
+        return layout
+    raise ValueError("MiniMax H3 wire payload requires one packed encoder layout tensor")
+
+
+def _validate_condition_tensors(
+    visual: torch.Tensor | None,
+    visual_shapes: Sequence[Sequence[int]],
+    audio: torch.Tensor | None,
+    audio_lengths: Sequence[int],
+) -> None:
+    if (visual is None) != (not visual_shapes):
+        raise ValueError("MiniMax H3 visual condition and shapes must be present together")
+    if (audio is None) != (not audio_lengths):
+        raise ValueError("MiniMax H3 audio condition and lengths must be present together")
+
+    parsed_shapes = [tuple(int(item) for item in shape) for shape in visual_shapes]
+    if any(
+        len(shape) != 3 or any(item <= 0 for item in shape) or shape[1] % 2 or shape[2] % 2 for shape in parsed_shapes
+    ):
+        raise ValueError("MiniMax H3 visual condition shapes must be positive [T, H, W] triplets with even H/W")
+    if visual is not None:
+        expected_rows = sum(t * (h // 2) * (w // 2) for t, h, w in parsed_shapes)
+        if (
+            visual.dtype != torch.float32
+            or visual.ndim != 2
+            or tuple(visual.shape)
+            != (
+                expected_rows,
+                _VIDEO_CONDITION_WIDTH,
+            )
+        ):
+            raise ValueError(
+                "MiniMax H3 visual condition must be FP32 with shape "
+                f"[{expected_rows}, {_VIDEO_CONDITION_WIDTH}], got {visual.dtype} {tuple(visual.shape)}"
+            )
+
+    parsed_lengths = [int(length) for length in audio_lengths]
+    if any(length <= 0 for length in parsed_lengths):
+        raise ValueError("MiniMax H3 audio condition lengths must be positive")
+    if audio is not None:
+        expected_rows = _AUDIO_CONDITION_CHANNELS * sum(parsed_lengths)
+        if (
+            audio.dtype != torch.float32
+            or audio.ndim != 2
+            or tuple(audio.shape)
+            != (
+                expected_rows,
+                _AUDIO_CONDITION_WIDTH,
+            )
+        ):
+            raise ValueError(
+                "MiniMax H3 audio condition must be FP32 with shape "
+                f"[{expected_rows}, {_AUDIO_CONDITION_WIDTH}], got {audio.dtype} {tuple(audio.shape)}"
+            )
+
+
+def _ref_block_rows(ref_blocks: Sequence[Mapping[str, Any]]) -> list[list[int]]:
+    rows: list[list[int]] = []
+    for block in ref_blocks:
+        kind = str(block.get("kind") or "")
+        kind_code = _REF_KIND_TO_CODE.get(kind)
+        if kind_code is None:
+            raise ValueError(f"unsupported MiniMax H3 ref kind {kind!r}")
+        rows.append(
+            [
+                kind_code,
+                int(block.get("ref_audio_t", 0)),
+                int(block.get("latent_t", 0)),
+                int(block.get("latent_h", 0)),
+                int(block.get("latent_w", 0)),
+            ]
+        )
+    return rows
+
+
+def _decode_ref_blocks(value: torch.Tensor) -> tuple[dict[str, Any], ...]:
+    if value.ndim != 2 or value.shape[1] != 5:
+        raise ValueError("MiniMax H3 ref_blocks metadata must have shape [N, 5]")
+    blocks: list[dict[str, Any]] = []
+    for kind_code, ref_audio_t, ref_t, ref_h, ref_w in value.detach().cpu().tolist():
+        kind = _CODE_TO_REF_KIND.get(int(kind_code))
+        if kind is None:
+            raise ValueError(f"unsupported MiniMax H3 ref kind code {kind_code!r}")
+        block: dict[str, Any] = {"kind": kind}
+        for key, item in (
+            ("ref_audio_t", ref_audio_t),
+            ("latent_t", ref_t),
+            ("latent_h", ref_h),
+            ("latent_w", ref_w),
+        ):
+            if item:
+                block[key] = int(item)
+        blocks.append(block)
+    return tuple(blocks)
+
+
+@dataclass(frozen=True)
+class MiniMaxH3EncoderMediaInput:
+    task: str
+    height: int
+    width: int
+    num_frames: int
+    latent_t: int
+    audio_t: int
+    images: tuple[torch.Tensor, ...] = ()
+    videos: tuple[torch.Tensor, ...] = ()
+    video_audios: tuple[tuple[torch.Tensor, int] | None, ...] = ()
+    audios: tuple[tuple[torch.Tensor, int], ...] = ()
+    keyframe_frame_indices: tuple[int, ...] = ()
+
+    @classmethod
+    def from_mm_tensors(
+        cls,
+        values: Sequence[torch.Tensor],
+        metadata: Mapping[str, Any],
+    ) -> MiniMaxH3EncoderMediaInput:
+        if not isinstance(values, Sequence) or isinstance(values, (str, bytes)):
+            raise ValueError("MiniMax H3 encoder media must be a tensor sequence")
+        tensors = list(values)
+        if any(not isinstance(item, torch.Tensor) for item in tensors):
+            raise ValueError("MiniMax H3 encoder media input must contain only tensors")
+        task = str(metadata["task"])
+        if task not in _TASK_TO_CODE:
+            raise ValueError(f"unsupported MiniMax H3 task {task!r}")
+        height = int(metadata["height"])
+        width = int(metadata["width"])
+        num_frames = int(metadata["num_frames"])
+        latent_t = int(metadata["latent_t"])
+        audio_t = int(metadata["audio_t"])
+        image_count = int(metadata.get("image_count", 0))
+        video_count = int(metadata.get("video_count", 0))
+        audio_count = int(metadata.get("audio_count", 0))
+        if min(height, width, num_frames, latent_t, audio_t) <= 0:
+            raise ValueError("MiniMax H3 encoder media dimensions must be positive")
+        if min(image_count, video_count, audio_count) < 0:
+            raise ValueError("MiniMax H3 encoder media counts must be non-negative")
+
+        audio_flags = tuple(bool(value) for value in metadata.get("video_audio_flags", ()))
+        video_audio_sample_rates = tuple(int(value) for value in metadata.get("video_audio_sample_rates", ()))
+        audio_sample_rates = tuple(int(value) for value in metadata.get("audio_sample_rates", ()))
+        if len(audio_flags) != video_count or len(video_audio_sample_rates) != video_count:
+            raise ValueError("MiniMax H3 video audio flags must align with videos")
+        if len(audio_sample_rates) != audio_count:
+            raise ValueError("MiniMax H3 audio sample rates must align with audio inputs")
+        if any((rate > 0) != has_audio for rate, has_audio in zip(video_audio_sample_rates, audio_flags, strict=True)):
+            raise ValueError("MiniMax H3 embedded audio sample rates must align with audio flags")
+        if any(rate <= 0 for rate in audio_sample_rates):
+            raise ValueError("MiniMax H3 audio sample rates must be positive")
+
+        cursor = 0
+        images = tuple(tensors[cursor : cursor + image_count])
+        cursor += image_count
+        videos = tuple(tensors[cursor : cursor + video_count])
+        cursor += video_count
+        if len(images) != image_count or any(image.ndim != 3 or image.shape[-1] != 3 for image in images):
+            raise ValueError("MiniMax H3 encoder images must have shape [H, W, 3]")
+        if len(videos) != video_count or any(video.ndim != 4 or video.shape[-1] != 3 for video in videos):
+            raise ValueError("MiniMax H3 encoder videos must have shape [T, H, W, 3]")
+
+        video_audios: list[tuple[torch.Tensor, int] | None] = []
+        for has_audio, sample_rate in zip(audio_flags, video_audio_sample_rates, strict=True):
+            if not has_audio:
+                video_audios.append(None)
+                continue
+            if cursor >= len(tensors):
+                raise ValueError("MiniMax H3 encoder media input is truncated")
+            waveform = tensors[cursor]
+            cursor += 1
+            if waveform.ndim not in (1, 2):
+                raise ValueError("MiniMax H3 embedded audio must have shape [samples] or [channels, samples]")
+            video_audios.append((waveform, sample_rate))
+
+        audios: list[tuple[torch.Tensor, int]] = []
+        for sample_rate in audio_sample_rates:
+            if cursor >= len(tensors):
+                raise ValueError("MiniMax H3 encoder media input is truncated")
+            waveform = tensors[cursor]
+            cursor += 1
+            if waveform.ndim not in (1, 2):
+                raise ValueError("MiniMax H3 audio must have shape [samples] or [channels, samples]")
+            audios.append((waveform, sample_rate))
+        if cursor != len(tensors):
+            raise ValueError(f"MiniMax H3 encoder media input has {len(tensors) - cursor} trailing tensors")
+        return cls(
+            task=task,
+            height=height,
+            width=width,
+            num_frames=num_frames,
+            latent_t=latent_t,
+            audio_t=audio_t,
+            images=images,
+            videos=videos,
+            video_audios=tuple(video_audios),
+            audios=tuple(audios),
+            keyframe_frame_indices=tuple(int(value) for value in metadata.get("keyframe_frame_indices", ())),
+        )
+
+    def to_mm_tensors(self) -> list[torch.Tensor]:
+        task_code = _TASK_TO_CODE.get(self.task)
+        if task_code is None:
+            raise ValueError(f"unsupported MiniMax H3 task {self.task!r}")
+        if min(self.height, self.width, self.num_frames, self.latent_t, self.audio_t) <= 0:
+            raise ValueError("MiniMax H3 encoder media dimensions must be positive")
+        if len(self.video_audios) != len(self.videos):
+            raise ValueError("MiniMax H3 video audio slots must align with videos")
+        if any(image.ndim != 3 or image.shape[-1] != 3 for image in self.images):
+            raise ValueError("MiniMax H3 encoder images must have shape [H, W, 3]")
+        if any(video.ndim != 4 or video.shape[-1] != 3 for video in self.videos):
+            raise ValueError("MiniMax H3 encoder videos must have shape [T, H, W, 3]")
+        audio_items = [item for item in self.video_audios if item is not None] + list(self.audios)
+        if any(waveform.ndim not in (1, 2) or int(sample_rate) <= 0 for waveform, sample_rate in audio_items):
+            raise ValueError("MiniMax H3 encoder audio must have a waveform and positive sample rate")
+        tensors = [*self.images, *self.videos]
+        for item in self.video_audios:
+            if item is None:
+                continue
+            waveform, _sample_rate = item
+            tensors.append(waveform)
+        tensors.extend(waveform for waveform, _sample_rate in self.audios)
+        return tensors
+
+    def to_metadata(self) -> dict[str, Any]:
+        return {
+            "task": self.task,
+            "height": self.height,
+            "width": self.width,
+            "num_frames": self.num_frames,
+            "latent_t": self.latent_t,
+            "audio_t": self.audio_t,
+            "image_count": len(self.images),
+            "video_count": len(self.videos),
+            "audio_count": len(self.audios),
+            "video_audio_flags": [item is not None for item in self.video_audios],
+            "video_audio_sample_rates": [item[1] if item is not None else 0 for item in self.video_audios],
+            "audio_sample_rates": [sample_rate for _waveform, sample_rate in self.audios],
+            "keyframe_frame_indices": list(self.keyframe_frame_indices),
+        }
+
+
+@dataclass(frozen=True)
+class MiniMaxH3EncoderMediaConditioning:
+    task: str
+    height: int
+    width: int
+    num_frames: int
+    latent_t: int
+    audio_t: int
+    visual_condition: torch.Tensor | None = None
+    visual_condition_shapes: tuple[tuple[int, int, int], ...] = ()
+    audio_condition: torch.Tensor | None = None
+    audio_condition_lengths: tuple[int, ...] = ()
+    ref_blocks: tuple[dict[str, Any], ...] = ()
+    keyframe_frame_indices: tuple[int, ...] = ()
+
+    def to_omni_components(
+        self,
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        task_code = _TASK_TO_CODE.get(self.task)
+        if task_code is None:
+            raise ValueError(f"unsupported MiniMax H3 task {self.task!r}")
+        if min(self.height, self.width, self.num_frames, self.latent_t, self.audio_t) <= 0:
+            raise ValueError("MiniMax H3 encoder media dimensions must be positive")
+        _validate_condition_tensors(
+            self.visual_condition,
+            self.visual_condition_shapes,
+            self.audio_condition,
+            self.audio_condition_lengths,
+        )
+        empty = torch.empty((0,), dtype=torch.float32)
+        ref_rows = _ref_block_rows(self.ref_blocks)
+        layout = [
+            _ENCODER_WIRE_SCHEMA_ID,
+            STAGE_SCHEMA_VERSION,
+            task_code,
+            self.height,
+            self.width,
+            self.num_frames,
+            self.latent_t,
+            self.audio_t,
+            len(self.visual_condition_shapes),
+            len(self.audio_condition_lengths),
+            len(ref_rows),
+            len(self.keyframe_frame_indices),
+        ]
+        layout.extend(item for shape in self.visual_condition_shapes for item in shape)
+        layout.extend(self.audio_condition_lengths)
+        layout.extend(item for row in ref_rows for item in row)
+        layout.extend(self.keyframe_frame_indices)
+        return (
+            self.visual_condition if self.visual_condition is not None else empty,
+            self.audio_condition if self.audio_condition is not None else empty,
+            torch.tensor(layout, dtype=torch.int64),
+        )
+
+
+@dataclass(frozen=True)
+class MiniMaxH3EncoderConditioning:
+    hidden_states: torch.Tensor
+    token_tags: torch.Tensor
+    task: str
+    height: int
+    width: int
+    num_frames: int
+    latent_t: int
+    audio_t: int
+    visual_condition: torch.Tensor | None = None
+    visual_condition_shapes: tuple[tuple[int, int, int], ...] = ()
+    audio_condition: torch.Tensor | None = None
+    audio_condition_lengths: tuple[int, ...] = ()
+    ref_blocks: tuple[dict[str, Any], ...] = ()
+    keyframe_frame_indices: tuple[int, ...] = ()
+
+    @classmethod
+    def from_components(
+        cls,
+        text: MiniMaxH3TextConditioning,
+        media: MiniMaxH3EncoderMediaConditioning,
+    ) -> MiniMaxH3EncoderConditioning:
+        """Combine local encoder results without a stage-wire round trip."""
+        text = MiniMaxH3TextConditioning.from_payload(text.to_payload())
+        _validate_condition_tensors(
+            media.visual_condition,
+            media.visual_condition_shapes,
+            media.audio_condition,
+            media.audio_condition_lengths,
+        )
+        return cls(
+            hidden_states=text.hidden_states,
+            token_tags=text.token_tags,
+            **{item.name: getattr(media, item.name) for item in fields(media)},
+        )
+
+    @classmethod
+    def from_omni_payload(cls, payload: Mapping[str, Any]) -> MiniMaxH3EncoderConditioning:
+        hidden_payload = payload.get("hidden_states")
+        embed_payload = payload.get("embed")
+        meta_payload = payload.get("meta")
+        hidden_states = hidden_payload.get("output") if isinstance(hidden_payload, Mapping) else None
+        token_tags = meta_payload.get("token_role_ids") if isinstance(meta_payload, Mapping) else None
+        visual = embed_payload.get("embedding") if isinstance(embed_payload, Mapping) else None
+        audio = embed_payload.get("speech_feat") if isinstance(embed_payload, Mapping) else None
+        if not all(isinstance(item, torch.Tensor) for item in (hidden_states, token_tags, visual, audio)):
+            raise ValueError("MiniMax H3 encoder wire requires text, visual and audio tensors")
+        assert isinstance(hidden_states, torch.Tensor)
+        assert isinstance(token_tags, torch.Tensor)
+        assert isinstance(visual, torch.Tensor)
+        assert isinstance(audio, torch.Tensor)
+        if token_tags.ndim == 2 and token_tags.shape[-1] == 1:
+            token_tags = token_tags.squeeze(-1)
+        text = MiniMaxH3TextConditioning.from_payload({"hidden_states": hidden_states, "token_tags": token_tags})
+        for name, value in (("visual", visual), ("audio", audio)):
+            if value.numel() == 0 and (value.dtype != torch.float32 or tuple(value.shape) != (0,)):
+                raise ValueError(f"MiniMax H3 empty {name} condition slot must be FP32 with shape [0]")
+        if not isinstance(meta_payload, Mapping):
+            raise ValueError("MiniMax H3 wire payload requires a meta mapping")
+        layout = _wire_layout(payload)
+        if layout.dtype not in _INTEGER_DTYPES or layout.ndim != 1:
+            raise ValueError("MiniMax H3 encoder layout must be a one-dimensional integer tensor")
+        values = [int(item) for item in layout.detach().cpu().tolist()]
+        if len(values) < 12:
+            raise ValueError("MiniMax H3 encoder layout header is truncated")
+        (
+            schema_id,
+            version,
+            task_code,
+            height,
+            width,
+            num_frames,
+            latent_t,
+            audio_t,
+            visual_count,
+            audio_count,
+            ref_count,
+            keyframe_count,
+        ) = values[:12]
+        if schema_id != _ENCODER_WIRE_SCHEMA_ID or version != STAGE_SCHEMA_VERSION:
+            raise ValueError(f"unsupported MiniMax H3 encoder wire schema {schema_id}:{version}")
+        task = _CODE_TO_TASK.get(task_code)
+        if task is None:
+            raise ValueError(f"unsupported MiniMax H3 wire task code {task_code!r}")
+        if min(height, width, num_frames, latent_t, audio_t) <= 0:
+            raise ValueError("MiniMax H3 encoder wire dimensions must be positive")
+        if min(visual_count, audio_count, ref_count, keyframe_count) < 0:
+            raise ValueError("MiniMax H3 encoder layout counts must be non-negative")
+        expected_size = 12 + 3 * visual_count + audio_count + 5 * ref_count + keyframe_count
+        if len(values) != expected_size:
+            raise ValueError(f"MiniMax H3 encoder layout has {len(values)} integers, expected {expected_size}")
+        cursor = 12
+        visual_shapes = tuple(
+            tuple(values[cursor + 3 * index : cursor + 3 * (index + 1)]) for index in range(visual_count)
+        )
+        cursor += 3 * visual_count
+        audio_lengths = tuple(values[cursor : cursor + audio_count])
+        cursor += audio_count
+        ref_rows = values[cursor : cursor + 5 * ref_count]
+        cursor += 5 * ref_count
+        ref_blocks_tensor = torch.tensor(ref_rows, dtype=torch.int64).reshape(-1, 5)
+        keyframe_frame_indices = tuple(values[cursor : cursor + keyframe_count])
+        visual_condition = visual if visual.numel() else None
+        audio_condition = audio if audio.numel() else None
+        _validate_condition_tensors(
+            visual_condition,
+            visual_shapes,
+            audio_condition,
+            audio_lengths,
+        )
+        return cls(
+            hidden_states=text.hidden_states,
+            token_tags=text.token_tags,
+            task=task,
+            height=height,
+            width=width,
+            num_frames=num_frames,
+            latent_t=latent_t,
+            audio_t=audio_t,
+            visual_condition=visual_condition,
+            visual_condition_shapes=visual_shapes,
+            audio_condition=audio_condition,
+            audio_condition_lengths=audio_lengths,
+            ref_blocks=_decode_ref_blocks(ref_blocks_tensor),
+            keyframe_frame_indices=keyframe_frame_indices,
+        )
+
+    def to_omni_payload(self) -> dict[str, Any]:
+        text = MiniMaxH3TextConditioning.from_payload(
+            {
+                "hidden_states": self.hidden_states,
+                "token_tags": self.token_tags,
+            }
+        )
+        visual, audio, layout = MiniMaxH3EncoderMediaConditioning(
+            task=self.task,
+            height=self.height,
+            width=self.width,
+            num_frames=self.num_frames,
+            latent_t=self.latent_t,
+            audio_t=self.audio_t,
+            visual_condition=self.visual_condition,
+            visual_condition_shapes=self.visual_condition_shapes,
+            audio_condition=self.audio_condition,
+            audio_condition_lengths=self.audio_condition_lengths,
+            ref_blocks=self.ref_blocks,
+            keyframe_frame_indices=self.keyframe_frame_indices,
+        ).to_omni_components()
+        return {
+            "hidden_states": {"output": text.hidden_states},
+            "embed": {
+                "embedding": visual,
+                "speech_feat": audio,
+            },
+            "meta": {"token_role_ids": text.token_tags},
+            "kv_metadata": {MINIMAX_H3_ENCODER_LAYOUT_KEY: layout},
+        }
+
+
+__all__ = [
+    "MINIMAX_H3_CONDITION_LABELS_KEY",
+    "MINIMAX_H3_ENCODER_LAYOUT_KEY",
+    "MINIMAX_H3_ENCODER_REQUEST_KEY",
+    "MINIMAX_H3_PRESENTATION_TASK_KEY",
+    "MINIMAX_H3_TEXT_CONDITIONING_SCHEMA",
+    "MINIMAX_H3_TEXT_HIDDEN_SIZE",
+    "STAGE_SCHEMA_VERSION",
+    "MiniMaxH3EncoderConditioning",
+    "MiniMaxH3EncoderMediaConditioning",
+    "MiniMaxH3EncoderMediaInput",
+    "MiniMaxH3TextConditioning",
+]
diff --git a/vllm_omni/model_executor/models/minimax_h3/encoder.py b/vllm_omni/model_executor/models/minimax_h3/encoder.py
new file mode 100644
index 00000000000..44fefab912b
--- /dev/null
+++ b/vllm_omni/model_executor/models/minimax_h3/encoder.py
@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import torch
+from vllm.config import VllmConfig
+from vllm.distributed.parallel_state import get_tp_group
+
+from vllm_omni.diffusion.distributed.utils import get_local_device
+from vllm_omni.diffusion.models.minimax_h3.vae import (
+    MiniMaxH3AudioVAE,
+    MiniMaxH3VideoVAE,
+)
+from vllm_omni.model_executor.models.minimax_h3.conditioning import (
+    MINIMAX_H3_ENCODER_LAYOUT_KEY,
+    MINIMAX_H3_ENCODER_REQUEST_KEY,
+    MiniMaxH3EncoderMediaConditioning,
+    MiniMaxH3EncoderMediaInput,
+)
+from vllm_omni.model_executor.models.minimax_h3.encoder_processing import encode_media
+from vllm_omni.model_executor.models.minimax_h3.text_encoder import (
+    MiniMaxH3TextEncoderBackbone,
+)
+from vllm_omni.model_executor.models.output_templates import OmniOutput
+
+_MEDIA_CONDITIONING_CACHE_KEY = "_minimax_h3_encoder_media_conditioning"
+_MEDIA_CACHE_KEY = "_minimax_h3_encoder_media"
+_COMPONENT_CONFIG_KEY = "minimax_h3_encoder_components"
+_COMPONENT_ROLES = frozenset({"text_encoder", "video_vae", "audio_vae"})
+
+
+def _partition_root(model_path: str) -> Path:
+    path = Path(model_path)
+    if path.name in {"text_encoder", "video_vae", "audio_vae"}:
+        return path.parent
+    return path
+
+
+@dataclass(frozen=True)
+class MiniMaxH3EncoderComponentConfig:
+    text_parallel_mode: str
+    video_parallel_mode: str
+    audio_parallel_mode: str
+
+    def __post_init__(self) -> None:
+        if self.text_parallel_mode != "tp":
+            raise ValueError("MiniMax H3 text encoder currently supports parallel_mode='tp' only")
+        if self.video_parallel_mode not in {"leader", "patch"}:
+            raise ValueError("MiniMax H3 video VAE parallel_mode must be 'leader' or 'patch'")
+        if self.audio_parallel_mode != "leader":
+            raise ValueError("MiniMax H3 audio VAE currently supports parallel_mode='leader' only")
+
+    @staticmethod
+    def _parallel_mode(raw: Mapping[str, Any], role: str) -> str:
+        value = raw[role]
+        if not isinstance(value, Mapping):
+            raise TypeError(f"MiniMax H3 encoder role {role!r} must be a mapping")
+        if set(value) != {"parallel_mode"}:
+            raise ValueError(f"MiniMax H3 encoder role {role!r} requires only parallel_mode")
+        return str(value["parallel_mode"])
+
+    @classmethod
+    def from_vllm_config(cls, vllm_config: VllmConfig) -> MiniMaxH3EncoderComponentConfig:
+        hf_config = vllm_config.model_config.hf_config
+        raw = getattr(hf_config, _COMPONENT_CONFIG_KEY, None)
+        if not isinstance(raw, Mapping):
+            raise ValueError(f"MiniMax H3 Encoder Stage requires explicit {_COMPONENT_CONFIG_KEY}")
+        roles = set(raw)
+        if roles != _COMPONENT_ROLES:
+            missing = sorted(_COMPONENT_ROLES - roles)
+            unknown = sorted(roles - _COMPONENT_ROLES)
+            raise ValueError(
+                f"{_COMPONENT_CONFIG_KEY} requires exactly {sorted(_COMPONENT_ROLES)}; "
+                f"missing={missing}, unknown={unknown}"
+            )
+        return cls(
+            text_parallel_mode=cls._parallel_mode(raw, "text_encoder"),
+            video_parallel_mode=cls._parallel_mode(raw, "video_vae"),
+            audio_parallel_mode=cls._parallel_mode(raw, "audio_vae"),
+        )
+
+
+class MiniMaxH3Encoder(MiniMaxH3TextEncoderBackbone):
+    requires_request_sample_eligibility = True
+    enable_update_additional_information = True
+    omni_payload_at_request_end = True
+
+    def __init__(self, *, vllm_config: VllmConfig, prefix: str = "model") -> None:
+        super().__init__(vllm_config=vllm_config, prefix=prefix)
+        try:
+            tp_group = get_tp_group()
+            tp_rank = int(tp_group.rank_in_group)
+        except (AssertionError, RuntimeError):
+            tp_group = None
+            tp_rank = 0
+        self._component_leader = tp_rank == 0
+        self.component_config = MiniMaxH3EncoderComponentConfig.from_vllm_config(vllm_config)
+        root = _partition_root(vllm_config.model_config.model)
+        missing = [name for name in ("text_encoder", "video_vae", "audio_vae") if not (root / name).is_dir()]
+        if missing:
+            raise RuntimeError(f"MiniMax H3 Encoder Stage requires all three encoders; missing {missing}")
+        device = get_local_device()
+        self.video_vae: MiniMaxH3VideoVAE | None = None
+        self.audio_vae: MiniMaxH3AudioVAE | None = None
+        if self._component_leader or self.component_config.video_parallel_mode == "patch":
+            self.video_vae = MiniMaxH3VideoVAE(
+                str(root / "video_vae"),
+                device=device,
+                encode_only=True,
+                trust_remote_code=vllm_config.model_config.trust_remote_code,
+            )
+            if self.component_config.video_parallel_mode == "patch":
+                if tp_group is None:
+                    raise RuntimeError("MiniMax H3 video VAE patch parallelism requires an initialized TP group")
+                self.video_vae.set_parallel_size(
+                    tp_group.world_size,
+                    process_group=tp_group.device_group,
+                )
+        if self._component_leader:
+            self.audio_vae = MiniMaxH3AudioVAE(
+                str(root / "audio_vae"),
+                device=device,
+                encode_only=True,
+                trust_remote_code=vllm_config.model_config.trust_remote_code,
+            )
+
+    @staticmethod
+    def _media_input(info: dict[str, Any]) -> MiniMaxH3EncoderMediaInput:
+        cached = info.get(_MEDIA_CACHE_KEY)
+        if isinstance(cached, MiniMaxH3EncoderMediaInput):
+            return cached
+        meta = info.get("meta")
+        metadata = meta.get(MINIMAX_H3_ENCODER_REQUEST_KEY) if isinstance(meta, Mapping) else None
+        if not isinstance(metadata, Mapping):
+            raise RuntimeError("MiniMax H3 unified encoder requires request metadata")
+
+        hidden_states = info.get("hidden_states")
+        raw_media = hidden_states.get("layers") if isinstance(hidden_states, Mapping) else None
+        if raw_media is None:
+            media_tensors: list[torch.Tensor] = []
+        elif isinstance(raw_media, Mapping):
+            try:
+                ordered_items = sorted(raw_media.items(), key=lambda item: int(item[0]))
+            except (TypeError, ValueError) as exc:
+                raise RuntimeError("MiniMax H3 encoder media keys must be integer indices") from exc
+            if [int(key) for key, _ in ordered_items] != list(range(len(ordered_items))):
+                raise RuntimeError("MiniMax H3 encoder media indices must be contiguous from zero")
+            media_tensors = [value for _, value in ordered_items]
+        else:
+            raise RuntimeError("MiniMax H3 encoder media must be a namespaced tensor mapping")
+        if any(not isinstance(value, torch.Tensor) for value in media_tensors):
+            raise RuntimeError("MiniMax H3 encoder media must contain only tensors")
+        media = MiniMaxH3EncoderMediaInput.from_mm_tensors(media_tensors, metadata)
+        if media.to_metadata() != dict(metadata):
+            raise RuntimeError("MiniMax H3 encoder media does not match request metadata")
+        info[_MEDIA_CACHE_KEY] = media
+        return media
+
+    def _encode_media(self, media: MiniMaxH3EncoderMediaInput) -> MiniMaxH3EncoderMediaConditioning | None:
+        if not self._component_leader and self.component_config.video_parallel_mode == "leader":
+            return None
+        return encode_media(
+            media,
+            video_vae=self.video_vae,
+            audio_vae=self.audio_vae,
+            emit_conditioning=self._component_leader,
+        )
+
+    @staticmethod
+    def _has_encoder_input(info: object) -> bool:
+        if not isinstance(info, Mapping):
+            return False
+        meta = info.get("meta")
+        return isinstance(meta, Mapping) and isinstance(meta.get(MINIMAX_H3_ENCODER_REQUEST_KEY), Mapping)
+
+    def make_omni_output(
+        self,
+        model_outputs: torch.Tensor | OmniOutput,
+        **kwargs: Any,
+    ) -> OmniOutput:
+        output = super().make_omni_output(model_outputs, **kwargs)
+        infos = kwargs.get("model_intermediate_buffer") or []
+        if not isinstance(infos, Sequence) or not infos:
+            return output
+        sample_eligible = kwargs.get("request_sample_eligible")
+        if sample_eligible is None:
+            sample_eligible = [True] * len(infos)
+        if len(sample_eligible) != len(infos):
+            raise RuntimeError(
+                f"MiniMax H3 unified encoder received {len(sample_eligible)} sampling flags for {len(infos)} requests"
+            )
+        per_request: list[tuple[torch.Tensor, torch.Tensor, torch.Tensor] | None] = []
+        release_workspace = False
+        for eligible, info in zip(sample_eligible, infos, strict=True):
+            if not eligible:
+                per_request.append(None)
+                continue
+            if not isinstance(info, dict) or not self._has_encoder_input(info):
+                raise RuntimeError("MiniMax H3 unified encoder request metadata is missing from the runner")
+            release_workspace = True
+            if _MEDIA_CONDITIONING_CACHE_KEY not in info:
+                info[_MEDIA_CONDITIONING_CACHE_KEY] = self._encode_media(self._media_input(info))
+            if not self._component_leader:
+                continue
+            cached = info.get(_MEDIA_CONDITIONING_CACHE_KEY)
+            if not isinstance(cached, MiniMaxH3EncoderMediaConditioning):
+                raise RuntimeError("MiniMax H3 encoder components did not produce conditioning")
+            per_request.append(cached.to_omni_components())
+
+        if release_workspace:
+            torch.accelerator.empty_cache()
+        if not self._component_leader:
+            return output
+
+        if not any(item is not None for item in per_request):
+            return output
+        empty = torch.empty((0,), dtype=torch.float32)
+        multimodal_outputs = dict(output.multimodal_outputs or {})
+        dotted_key = f"kv_metadata.{MINIMAX_H3_ENCODER_LAYOUT_KEY}"
+        multimodal_outputs[dotted_key] = [
+            item[2] if item is not None else torch.empty((0,), dtype=torch.int64) for item in per_request
+        ]
+
+        embed = dict(multimodal_outputs.get("embed") or {})
+        embed["embedding"] = [item[0] if item is not None else empty for item in per_request]
+        embed["speech_feat"] = [item[1] if item is not None else empty for item in per_request]
+        multimodal_outputs["embed"] = embed
+        return OmniOutput(
+            text_hidden_states=output.text_hidden_states,
+            multimodal_outputs=multimodal_outputs,
+            intermediate_tensors=output.intermediate_tensors,
+            next_token_id=output.next_token_id,
+        )
+
+    def load_weights(
+        self,
+        weights: Iterable[tuple[str, torch.Tensor]],
+    ) -> set[str]:
+        loaded = super().load_weights(weights)
+        for component_name in ("video_vae", "audio_vae"):
+            component = getattr(self, component_name)
+            if component is not None:
+                loaded.update(f"{component_name}.{name}" for name, _ in component.named_parameters())
+        return loaded
+
+
+__all__ = ["MiniMaxH3Encoder"]
diff --git a/vllm_omni/model_executor/models/minimax_h3/encoder_processing.py b/vllm_omni/model_executor/models/minimax_h3/encoder_processing.py
new file mode 100644
index 00000000000..2d6998b7afe
--- /dev/null
+++ b/vllm_omni/model_executor/models/minimax_h3/encoder_processing.py
@@ -0,0 +1,569 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Shared request preparation and condition codec execution for MiniMax H3."""
+
+from __future__ import annotations
+
+import math
+import os
+import tempfile
+from collections.abc import Callable, Mapping, Sequence
+from contextlib import AbstractContextManager, nullcontext
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import torch
+from PIL import Image
+
+from vllm_omni.errors import OmniClientError
+from vllm_omni.model_executor.models.minimax_h3.conditioning import (
+    MiniMaxH3EncoderMediaConditioning,
+    MiniMaxH3EncoderMediaInput,
+)
+from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
+    MINIMAX_H3_OUTPUT_SHORT_EDGE,
+    load_minimax_h3_images,
+    resolve_minimax_h3_aspect_ratio,
+    resolve_minimax_h3_output_canvas,
+    resolve_minimax_h3_reference_image_shape,
+)
+from vllm_omni.model_executor.models.minimax_h3.reference_video import (
+    MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS,
+    load_audio_file,
+    load_video_audio,
+    load_video_frames,
+    prepare_reference_videos,
+    sample_reference_video_frames,
+    validate_reference_audio_files,
+    validate_reference_audio_waveforms,
+)
+
+MINIMAX_H3_FPS = 24
+MINIMAX_H3_MIN_OUTPUT_SECONDS = 4.0
+MINIMAX_H3_MAX_OUTPUT_SECONDS = 15.0
+
+
+def _items(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, list):
+        return value
+    if isinstance(value, tuple) and not (len(value) == 2 and isinstance(value[1], Mapping)):
+        return list(value)
+    return [value]
+
+
+def _audio_items(value: Any) -> list[Any]:
+    if value is None:
+        return []
+    if isinstance(value, (list, tuple)) and len(value) == 2 and isinstance(value[1], (int, np.integer)):
+        return [value]
+    return list(value) if isinstance(value, (list, tuple)) else [value]
+
+
+def _load_audio(value: Any) -> tuple[torch.Tensor, int]:
+    if isinstance(value, (list, tuple)) and not (len(value) == 2 and isinstance(value[1], (int, np.integer))):
+        audios = _load_audios(value)
+        if len(audios) != 1:
+            raise OmniClientError(f"MiniMax H3 expected one audio, got {len(audios)}")
+        return audios[0]
+    if isinstance(value, (str, os.PathLike)):
+        return load_audio_file(str(value))
+    if isinstance(value, (list, tuple)) and len(value) == 2:
+        waveform, sample_rate = value
+        return torch.as_tensor(waveform).float(), int(sample_rate)
+    if isinstance(value, dict):
+        waveform = value.get("waveform", value.get("array"))
+        sample_rate = value.get("sample_rate", value.get("sampling_rate"))
+        if waveform is not None and sample_rate is not None:
+            return torch.as_tensor(waveform).float(), int(sample_rate)
+    raise OmniClientError("MiniMax H3 audio input must be a path, (waveform, sample_rate), or a waveform mapping")
+
+
+def _load_audios(value: Any) -> list[tuple[torch.Tensor, int]]:
+    if isinstance(value, (list, tuple)) and not (len(value) == 2 and isinstance(value[1], (int, np.integer))):
+        if not value:
+            raise OmniClientError("MiniMax H3 audio input must not be empty")
+        return [_load_audio(item) for item in value]
+    return [_load_audio(value)]
+
+
+def _as_int_list(value: Any, *, name: str) -> list[int]:
+    if isinstance(value, bool):
+        raise OmniClientError(f"{name} must be an integer or a list of integers")
+    if isinstance(value, (int, np.integer)):
+        return [int(value)]
+    if isinstance(value, Sequence) and not isinstance(value, (str, bytes)):
+        result = list(value)
+        if not result:
+            raise OmniClientError(f"{name} must not be empty")
+        if any(isinstance(item, bool) or not isinstance(item, (int, np.integer)) for item in result):
+            raise OmniClientError(f"{name} must contain only integers")
+        return [int(item) for item in result]
+    raise OmniClientError(f"{name} must be an integer or a list of integers")
+
+
+def _resolve_fl2va_keyframe_indices(extra: Mapping[str, Any], image_count: int) -> list[int]:
+    target = extra.get("target")
+    target = target if isinstance(target, Mapping) else {}
+    raw = extra.get("frame_indices", extra.get("frame_index"))
+    if raw is None:
+        raw = target.get("frame_indices", target.get("frame_index"))
+    raw_indices = ([0] if image_count == 1 else [0, -1]) if raw is None else _as_int_list(raw, name="frame_indices")
+    if len(raw_indices) != image_count:
+        raise OmniClientError(
+            f"MiniMax H3 FL2VA requires one frame index per image: got {raw_indices!r} for {image_count} image(s)"
+        )
+    if tuple(raw_indices) not in ((0,), (-1,), (0, -1)):
+        raise OmniClientError("MiniMax H3 FL2VA frame_indices must be [0], [-1], or [0, -1]")
+    return raw_indices
+
+
+def _validate_ref2va_reference_counts(image_count: int, video_count: int, audio_count: int) -> None:
+    if min(image_count, video_count, audio_count) < 0:
+        raise OmniClientError("MiniMax H3 reference counts must be non-negative")
+    if image_count + video_count == 0:
+        raise OmniClientError("ref2va requires at least one image or video reference")
+    if image_count > 9:
+        raise OmniClientError("ref2va accepts at most 9 image references")
+    if video_count > 3:
+        raise OmniClientError("ref2va accepts at most 3 video references")
+    if audio_count > 3:
+        raise OmniClientError("ref2va accepts at most 3 standalone audio references")
+    if image_count + video_count + audio_count > 12:
+        raise OmniClientError("ref2va accepts at most 12 total references")
+
+
+def _validate_reference_image(image: Image.Image) -> None:
+    resolve_minimax_h3_reference_image_shape(image)
+
+
+def resolve_minimax_h3_shape(
+    task: str,
+    sampling: Any,
+    image: Image.Image | None,
+) -> tuple[int, int, int, int, int]:
+    # The diffusion package exports a pipeline that imports this shared module.
+    from vllm_omni.diffusion.models.minimax_h3.time_request import (
+        MINIMAX_H3_SHAPE_PLANNER,
+        minimax_h3_align_frame_count,
+    )
+
+    fps = int(getattr(sampling, "fps", None) or MINIMAX_H3_FPS)
+    if fps != MINIMAX_H3_FPS:
+        raise OmniClientError(f"MiniMax H3 output fps is fixed at {MINIMAX_H3_FPS}")
+    extra = sampling.extra_args or {}
+    target = extra.get("target")
+    if target is not None and not isinstance(target, Mapping):
+        raise OmniClientError("MiniMax H3 extra_args['target'] must be an object")
+    target = target if isinstance(target, Mapping) else {}
+    duration = target.get("duration_seconds", extra.get("duration_seconds", extra.get("duration")))
+    if duration is not None:
+        if isinstance(duration, bool):
+            raise OmniClientError(f"MiniMax H3 output duration must be in [4, 15] seconds, got {duration!r}")
+        try:
+            duration = float(duration)
+        except (TypeError, ValueError) as exc:
+            raise OmniClientError(f"MiniMax H3 output duration must be in [4, 15] seconds, got {duration!r}") from exc
+        if (
+            not math.isfinite(duration)
+            or not MINIMAX_H3_MIN_OUTPUT_SECONDS <= duration <= MINIMAX_H3_MAX_OUTPUT_SECONDS
+        ):
+            raise OmniClientError(f"MiniMax H3 output duration must be in [4, 15] seconds, got {duration}")
+        requested_frames = int(round(duration * fps))
+    elif int(getattr(sampling, "num_frames", None) or 1) > 1:
+        requested_frames = int(sampling.num_frames)
+    else:
+        requested_frames = 124 if task == "ref2va" else 209
+    if not MINIMAX_H3_MIN_OUTPUT_SECONDS <= requested_frames / fps <= MINIMAX_H3_MAX_OUTPUT_SECONDS:
+        raise OmniClientError(
+            f"MiniMax H3 output duration must be in [4, 15] seconds, got {requested_frames / fps:.3f}"
+        )
+    num_frames = minimax_h3_align_frame_count(requested_frames)
+
+    height = getattr(sampling, "height", None)
+    width = getattr(sampling, "width", None)
+    aspect_ratio = resolve_minimax_h3_aspect_ratio(
+        task,
+        target.get("aspect_ratio", extra.get("aspect_ratio")),
+        image,
+    )
+    raw_short_edge = target.get("short_edge", extra.get("short_edge", MINIMAX_H3_OUTPUT_SHORT_EDGE))
+    if isinstance(raw_short_edge, bool) or not isinstance(raw_short_edge, (int, np.integer)):
+        raise OmniClientError(
+            f"MiniMax H3 target.short_edge must be {MINIMAX_H3_OUTPUT_SHORT_EDGE}, got {raw_short_edge!r}"
+        )
+    if height is None or width is None:
+        height, width = resolve_minimax_h3_output_canvas(aspect_ratio, int(raw_short_edge))
+    height = int(height) // 32 * 32
+    width = int(width) // 32 * 32
+    if min(height, width) <= 0:
+        raise OmniClientError(f"invalid MiniMax H3 canvas {width}x{height}")
+    if width > 4 * height or height > 4 * width:
+        raise OmniClientError("MiniMax H3 canvas aspect ratio must be in [1:4, 4:1]")
+    return (
+        height,
+        width,
+        num_frames,
+        MINIMAX_H3_SHAPE_PLANNER.video_latent_t(num_frames),
+        MINIMAX_H3_SHAPE_PLANNER.audio_latent_t(num_frames / fps),
+    )
+
+
+def _resolve_task(
+    extra_args: Mapping[str, Any],
+    multi_modal_data: Mapping[str, Any],
+) -> str:
+    requested = extra_args.get("task")
+    if requested is not None:
+        return str(requested).lower()
+    if multi_modal_data.get("video") is not None or multi_modal_data.get("audio") is not None:
+        return "ref2va"
+    if multi_modal_data.get("image") is not None:
+        return "fl2va"
+    return "t2va"
+
+
+def _prepare_encoder_images(
+    task: str,
+    images: list[Image.Image],
+    *,
+    height: int,
+    width: int,
+) -> list[Any]:
+    if not images:
+        return []
+    if task == "ref2va":
+        return [
+            image.resize(
+                resolve_minimax_h3_reference_image_shape(image),
+                Image.Resampling.LANCZOS,
+            )
+            for image in images
+        ]
+    if task != "fl2va":
+        return images
+    return [image.resize((width, height), Image.Resampling.LANCZOS) for image in images]
+
+
+def _image_to_tensor(image: Image.Image) -> torch.Tensor:
+    array = np.asarray(image.convert("RGB"), dtype=np.uint8)
+    return torch.from_numpy(np.array(array, copy=True)).contiguous()
+
+
+def _frames_to_tensor(frames: Sequence[Any]) -> torch.Tensor:
+    if len(frames) == 0:
+        raise ValueError("MiniMax H3 reference video must contain frames")
+    return torch.stack(
+        [
+            _image_to_tensor(frame if isinstance(frame, Image.Image) else Image.fromarray(np.asarray(frame)))
+            for frame in frames
+        ]
+    )
+
+
+def _reuse_prepared_reference_videos(
+    prepared: list[dict[str, Any]] | None,
+    *,
+    expected_count: int,
+) -> list[dict[str, Any]] | None:
+    if prepared is None:
+        return None
+    if len(prepared) != expected_count:
+        raise OmniClientError("MiniMax H3 prepared-reference-video count does not match the request")
+    for item in prepared:
+        if not os.path.isfile(item["prepared_path"]):
+            raise OmniClientError(f"MiniMax H3 prepared reference video is unavailable: {item['prepared_path']}")
+    return prepared
+
+
+@dataclass(frozen=True)
+class PreparedEncoderInputs:
+    """CPU-owned media and Qwen presentation inputs, independent of a runner."""
+
+    prompt: str
+    media: MiniMaxH3EncoderMediaInput
+    images: list[Image.Image]
+    qwen_videos: list[tuple[np.ndarray, dict[str, Any]]]
+    video_timestamps: list[list[float]]
+    condition_labels: list[tuple[str, int]]
+
+
+def _effective_audio_inputs(
+    video_audios: Sequence[tuple[torch.Tensor, int] | None],
+    standalone_audios: Sequence[tuple[torch.Tensor, int]],
+    *,
+    max_standalone_seconds: float,
+) -> list[tuple[torch.Tensor, int]]:
+    """Return the waveforms exactly as the audio WVAE will consume them."""
+    audio_inputs = [item for item in video_audios if item is not None]
+    audio_inputs.extend(
+        (waveform[..., : int(round(max_standalone_seconds * sample_rate))], sample_rate)
+        for waveform, sample_rate in standalone_audios
+    )
+    return audio_inputs
+
+
+def prepare_encoder_inputs(
+    prompt: Any,
+    sampling: Any,
+    *,
+    task: str | None = None,
+    prepared_reference_videos: list[dict[str, Any]] | None = None,
+) -> PreparedEncoderInputs:
+    """Decode references once and prepare the shared text/codec presentation."""
+    if isinstance(prompt, str):
+        prompt = {"prompt": prompt}
+    if not isinstance(prompt, dict):
+        raise TypeError(f"MiniMax H3 expects a string or dict prompt, got {type(prompt)!r}")
+
+    text = str(prompt.get("prompt") or "")
+    if not text:
+        raise OmniClientError("MiniMax H3 requires a non-empty prompt")
+    multi_modal_data = prompt.get("multi_modal_data") or {}
+    if not isinstance(multi_modal_data, Mapping):
+        raise TypeError("multi_modal_data must be a mapping")
+
+    image_values = _items(multi_modal_data.get("image"))
+    videos = _items(multi_modal_data.get("video"))
+    raw_audio = multi_modal_data.get("audio")
+    audio_values = _audio_items(raw_audio)
+    diffusion_sampling_params = sampling
+    extra_args = getattr(diffusion_sampling_params, "extra_args", None) or {}
+    task = task if task is not None else _resolve_task(extra_args, multi_modal_data)
+    raw_images = load_minimax_h3_images(image_values) if image_values else []
+
+    if task == "t2va":
+        if raw_images or videos or audio_values:
+            raise OmniClientError("t2va does not accept image, video, or audio conditions")
+    elif task == "fl2va":
+        if not raw_images or videos or audio_values:
+            raise OmniClientError("fl2va requires image conditions only")
+        if len(raw_images) > 2:
+            raise OmniClientError("fl2va accepts at most first and last images")
+        for image in raw_images:
+            _validate_reference_image(image)
+    elif task == "ref2va":
+        _validate_ref2va_reference_counts(len(raw_images), len(videos), len(audio_values))
+        if not raw_images and not videos:
+            raise OmniClientError("ref2va requires an image or video condition")
+    else:
+        raise OmniClientError(f"unsupported MiniMax H3 task {task!r}")
+
+    height, width, num_frames, latent_t, audio_t = resolve_minimax_h3_shape(
+        task,
+        diffusion_sampling_params,
+        raw_images[0] if raw_images else None,
+    )
+    images = _prepare_encoder_images(
+        task,
+        raw_images,
+        height=height,
+        width=width,
+    )
+    keyframe_indices = _resolve_fl2va_keyframe_indices(extra_args, len(images)) if task == "fl2va" else []
+    video_timestamps: list[list[float]] = []
+    qwen_video_inputs: list[tuple[np.ndarray, dict[str, Any]]] = []
+    condition_labels: list[tuple[str, int]] = []
+    encoded_video_inputs: list[torch.Tensor] = []
+    video_audio_inputs: list[tuple[torch.Tensor, int] | None] = []
+
+    if task == "fl2va":
+        condition_labels.extend(("image", index) for index in range(1, len(images) + 1))
+    elif task == "ref2va":
+        condition_labels.extend(("image", index) for index in range(1, len(images) + 1))
+        prepared_videos: list[dict[str, Any]] = []
+        if videos:
+            with tempfile.TemporaryDirectory(prefix="minimax_h3_encoder_") as workdir:
+                prepared_videos = _reuse_prepared_reference_videos(
+                    prepared_reference_videos, expected_count=len(videos)
+                )
+                if prepared_videos is None:
+                    prepared_videos = prepare_reference_videos(
+                        videos,
+                        target_frame_count=num_frames,
+                        workdir=workdir,
+                        start_time_seconds=extra_args.get("start_time_seconds"),
+                    )
+                for item in prepared_videos:
+                    full_frames = load_video_frames(item["prepared_path"])
+                    encoded_video_inputs.append(_frames_to_tensor(full_frames))
+                    sampled = sample_reference_video_frames(
+                        item["prepared_path"],
+                        decoded_frames=full_frames,
+                    )
+                    video_timestamps.append(sampled["block_timestamps"])
+                    frames = np.stack(sampled["frames"])
+                    frame_count = int(frames.shape[0])
+                    qwen_video_inputs.append(
+                        (
+                            frames,
+                            {
+                                "total_num_frames": frame_count,
+                                "fps": MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS,
+                                "duration": frame_count / MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS,
+                                "video_backend": "minimax_h3",
+                                "frames_indices": list(range(frame_count)),
+                                "do_sample_frames": False,
+                            },
+                        )
+                    )
+                    if item["input_has_audio"]:
+                        waveform, sample_rate = load_video_audio(
+                            item["original_path"],
+                            start_time_seconds=float(item.get("start_time_seconds", 0.0)),
+                            duration_seconds=item.get(
+                                "audio_duration_seconds",
+                                item.get("duration_seconds"),
+                            ),
+                        )
+                        video_audio_inputs.append((waveform.float().contiguous(), int(sample_rate)))
+                    else:
+                        video_audio_inputs.append(None)
+        audio_index = 0
+        for video_index, item in enumerate(prepared_videos, start=1):
+            if item["input_has_audio"]:
+                audio_index += 1
+                condition_labels.append(("audio", audio_index))
+            condition_labels.append(("video", video_index))
+        for _ in audio_values:
+            audio_index += 1
+            condition_labels.append(("audio", audio_index))
+
+    if raw_audio is not None:
+        validate_reference_audio_files(raw_audio)
+    standalone_audios = _load_audios(raw_audio) if raw_audio is not None else []
+    validate_reference_audio_waveforms(standalone_audios)
+    media_input = MiniMaxH3EncoderMediaInput(
+        task=task,
+        height=height,
+        width=width,
+        num_frames=num_frames,
+        latent_t=latent_t,
+        audio_t=audio_t,
+        images=tuple(_image_to_tensor(image) for image in images),
+        videos=tuple(encoded_video_inputs),
+        video_audios=tuple(video_audio_inputs),
+        audios=tuple((waveform.float().contiguous(), int(sample_rate)) for waveform, sample_rate in standalone_audios),
+        keyframe_frame_indices=tuple(keyframe_indices),
+    )
+    audio_inputs = _effective_audio_inputs(
+        media_input.video_audios,
+        media_input.audios,
+        max_standalone_seconds=float(media_input.num_frames) / MINIMAX_H3_FPS,
+    )
+    embedded_audio_count = sum(item is not None for item in media_input.video_audios)
+    # Video soundtracks and standalone references have separate 15-second budgets.
+    validate_reference_audio_waveforms(audio_inputs[:embedded_audio_count])
+    validate_reference_audio_waveforms(audio_inputs[embedded_audio_count:])
+
+    return PreparedEncoderInputs(
+        prompt=text,
+        media=media_input,
+        images=images,
+        qwen_videos=qwen_video_inputs,
+        video_timestamps=video_timestamps,
+        condition_labels=condition_labels,
+    )
+
+
+def _image_from_tensor(value: torch.Tensor) -> Image.Image:
+    if value.ndim != 3 or value.shape[-1] != 3:
+        raise ValueError(f"MiniMax H3 image tensor must have shape [H, W, 3], got {tuple(value.shape)}")
+    array = value.detach().cpu().to(torch.uint8).contiguous().numpy()
+    return Image.fromarray(array, mode="RGB")
+
+
+def encode_media(
+    media: MiniMaxH3EncoderMediaInput,
+    *,
+    video_vae: Any,
+    audio_vae: Any,
+    emit_conditioning: bool,
+    component_scope: Callable[[Any], AbstractContextManager[Any]] = nullcontext,
+) -> MiniMaxH3EncoderMediaConditioning | None:
+    """Run codecs on participating ranks; only the output rank runs audio.
+
+    The caller selects participating ranks and configures the VAE process group.
+    Every visual participant must call this function with the same references.
+    Component scopes allow the diffusion runner to stage one codec at a time.
+    """
+    visual_rows: list[torch.Tensor] = []
+    visual_shapes: list[tuple[int, int, int]] = []
+    if media.images or media.videos:
+        if video_vae is None:
+            raise RuntimeError("MiniMax H3 video VAE is not resident on this rank")
+        with component_scope(video_vae):
+            for value in media.images:
+                image = _image_from_tensor(value)
+                visual_rows.append(video_vae.encode_image(image))
+                visual_shapes.append((1, image.height // 16, image.width // 16))
+            for value in media.videos:
+                frames = np.asarray(value.detach().cpu().to(torch.uint8).contiguous().numpy())
+                rows, shape = video_vae.encode_video(frames)
+                visual_rows.append(rows)
+                visual_shapes.append(tuple(int(item) for item in shape))
+
+    if not emit_conditioning:
+        return None
+
+    audio_rows: list[torch.Tensor] = []
+    audio_lengths: list[int] = []
+    embedded_audio_count = sum(item is not None for item in media.video_audios)
+    audio_inputs = _effective_audio_inputs(
+        media.video_audios,
+        media.audios,
+        max_standalone_seconds=float(media.num_frames) / MINIMAX_H3_FPS,
+    )
+    if audio_inputs:
+        if audio_vae is None:
+            raise RuntimeError("MiniMax H3 audio WVAE is not resident on the encoder leader")
+        with component_scope(audio_vae):
+            for waveform, sample_rate in audio_inputs:
+                rows, length = audio_vae.encode_waveform(waveform, sample_rate)
+                audio_rows.append(rows)
+                audio_lengths.append(int(length))
+    if audio_lengths:
+        if any(length < 80 or length > 600 for length in audio_lengths):
+            raise ValueError("MiniMax H3 audio references must each be between 2 and 15 seconds")
+        if sum(audio_lengths[:embedded_audio_count]) > 600 or sum(audio_lengths[embedded_audio_count:]) > 600:
+            raise ValueError("MiniMax H3 audio references must be at most 15 seconds in total")
+
+    ref_blocks: list[dict[str, Any]] = []
+    image_shapes = visual_shapes[: len(media.images)]
+    video_shapes = visual_shapes[len(media.images) :]
+    ref_blocks.extend({"kind": "image", "latent_h": shape[1], "latent_w": shape[2]} for shape in image_shapes)
+    embedded_lengths = iter(audio_lengths[:embedded_audio_count])
+    for shape, embedded in zip(video_shapes, media.video_audios, strict=True):
+        ref_audio_t = int(next(embedded_lengths)) if embedded is not None else 0
+        ref_blocks.append(
+            {
+                "kind": "video_audio" if ref_audio_t else "video",
+                "ref_audio_t": ref_audio_t,
+                "latent_t": shape[0],
+                "latent_h": shape[1],
+                "latent_w": shape[2],
+            }
+        )
+    ref_blocks.extend(
+        {
+            "kind": "audio",
+            "ref_audio_t": int(length),
+        }
+        for length in audio_lengths[embedded_audio_count:]
+    )
+    return MiniMaxH3EncoderMediaConditioning(
+        task=media.task,
+        height=media.height,
+        width=media.width,
+        num_frames=media.num_frames,
+        latent_t=media.latent_t,
+        audio_t=media.audio_t,
+        visual_condition=torch.cat(visual_rows) if visual_rows else None,
+        visual_condition_shapes=tuple(visual_shapes),
+        audio_condition=torch.cat(audio_rows) if audio_rows else None,
+        audio_condition_lengths=tuple(audio_lengths),
+        ref_blocks=tuple(ref_blocks),
+        keyframe_frame_indices=media.keyframe_frame_indices,
+    )
diff --git a/vllm_omni/model_executor/models/minimax_h3/pipeline.py b/vllm_omni/model_executor/models/minimax_h3/pipeline.py
index 5ac94b5eeaf..085e2508a99 100644
--- a/vllm_omni/model_executor/models/minimax_h3/pipeline.py
+++ b/vllm_omni/model_executor/models/minimax_h3/pipeline.py
@@ -16,18 +16,18 @@
     model_type="minimax_h3_disaggregated",
     default_deploy_config_name="minimax_h3_disaggregated.yaml",
     stage_cli_aliases={"text_encoder_tp_size": (0, "tensor_parallel_size")},
-    model_arch="MiniMaxH3TextEncoder",
+    model_arch="MiniMaxH3Encoder",
     stages=(
         StagePipelineConfig(
             stage_id=0,
-            model_stage="text_encoder",
+            model_stage="encoder",
             execution_type=StageExecutionType.LLM_AR,
             input_sources=(),
             owns_tokenizer=True,
             requires_multimodal_data=True,
-            model_arch="MiniMaxH3TextEncoder",
+            model_arch="MiniMaxH3Encoder",
             engine_output_type="latent",
-            prompt_transform_func=f"{_PROCESSOR}.prepare_text_encoder_prompt",
+            prompt_transform_func=f"{_PROCESSOR}.prepare_encoder_prompt",
             sampling_constraints={
                 "max_tokens": 1,
                 "temperature": 0.0,
@@ -42,9 +42,9 @@
             input_sources=(0,),
             final_output=True,
             final_output_type="video",
-            requires_multimodal_data=True,
+            requires_multimodal_data=False,
             model_arch="MiniMaxH3Pipeline",
-            custom_process_input_func=f"{_PROCESSOR}.text_encoder2diffusion",
+            custom_process_input_func=f"{_PROCESSOR}.encoder2diffusion",
             omni_kv_config={"need_recv_cache": False},
             model_path_resolver=f"{_DIFFUSION_PIPELINE}.resolve_minimax_h3_diffusion_model_path",
             inline_diffusion=True,
diff --git a/vllm_omni/model_executor/models/minimax_h3/reference_video.py b/vllm_omni/model_executor/models/minimax_h3/reference_video.py
index 4f98d9e13a2..4b361b26c02 100644
--- a/vllm_omni/model_executor/models/minimax_h3/reference_video.py
+++ b/vllm_omni/model_executor/models/minimax_h3/reference_video.py
@@ -531,14 +531,27 @@ def _decode_video_frames_ffmpeg(
     )
 
 
-def sample_reference_video_frames(prepared_path: str) -> dict[str, Any]:
-    meta = _probe_video(prepared_path)
+def sample_reference_video_frames(
+    prepared_path: str,
+    *,
+    decoded_frames: np.ndarray | None = None,
+) -> dict[str, Any]:
+    if decoded_frames is None:
+        meta = _probe_video(prepared_path)
+        frame_count = int(meta["frame_count"])
+    else:
+        decoded_frames = np.asarray(decoded_frames)
+        if decoded_frames.ndim != 4 or decoded_frames.shape[-1] != 3 or len(decoded_frames) <= 0:
+            raise OmniClientError(
+                f"decoded reference video frames must have shape [T, H, W, 3], got {decoded_frames.shape}"
+            )
+        frame_count = len(decoded_frames)
     ratio = MINIMAX_H3_FPS / MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS
     indices: list[int] = []
     cursor = 0.0
     while True:
         frame_index = int(round(cursor))
-        if frame_index >= meta["frame_count"]:
+        if frame_index >= frame_count:
             break
         if not indices or frame_index > indices[-1]:
             indices.append(frame_index)
@@ -546,16 +559,16 @@ def sample_reference_video_frames(prepared_path: str) -> dict[str, Any]:
     if not indices:
         raise OmniClientError(f"no frames sampled from {prepared_path}")
 
-    # The preparation step emits a lossless RGB stream. Decode only the sampled
-    # frames in one ffmpeg process so Qwen3VL sees the exact prepared pixels
-    # without decoding the entire high-bitrate stream into host memory.
-    decoded_frames = _decode_video_frames_ffmpeg(
-        prepared_path,
-        frame_count=int(meta["frame_count"]),
-        indices=indices,
-        width=meta["width"],
-        height=meta["height"],
-    )
+    if decoded_frames is None:
+        decoded_frames = _decode_video_frames_ffmpeg(
+            prepared_path,
+            frame_count=frame_count,
+            indices=indices,
+            width=meta["width"],
+            height=meta["height"],
+        )
+    else:
+        decoded_frames = decoded_frames[indices]
     frames = [np.asarray(frame) for frame in decoded_frames]
 
     timestamps = [index / MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS for index in range(len(indices))]
diff --git a/vllm_omni/model_executor/models/minimax_h3/text_encoder.py b/vllm_omni/model_executor/models/minimax_h3/text_encoder.py
index b1933af95dc..9ae74036e24 100644
--- a/vllm_omni/model_executor/models/minimax_h3/text_encoder.py
+++ b/vllm_omni/model_executor/models/minimax_h3/text_encoder.py
@@ -176,7 +176,7 @@ def forward(
     info=Qwen3VLProcessingInfo,
     dummy_inputs=Qwen3VLDummyInputsBuilder,
 )
-class MiniMaxH3TextEncoder(Qwen3VLForConditionalGeneration):
+class MiniMaxH3TextEncoderBackbone(Qwen3VLForConditionalGeneration):
     """Qwen3-VL encoder used by MiniMax H3.
 
     MiniMax H3 consumes the residual stream after decoder layer 50.  The
@@ -305,3 +305,6 @@ def encoder_weights():
             encoder_weights(),
             mapper=self.hf_to_vllm_mapper,
         )
+
+
+MiniMaxH3TextEncoder = MiniMaxH3TextEncoderBackbone
diff --git a/vllm_omni/model_executor/models/registry.py b/vllm_omni/model_executor/models/registry.py
index e5d7b4115d1..1a519917ce9 100644
--- a/vllm_omni/model_executor/models/registry.py
+++ b/vllm_omni/model_executor/models/registry.py
@@ -476,10 +476,10 @@
         "qwen3_vl",
         "AuraQwen3VLForConditionalGeneration",
     ),
-    "MiniMaxH3TextEncoder": (
+    "MiniMaxH3Encoder": (
         "minimax_h3",
-        "text_encoder",
-        "MiniMaxH3TextEncoder",
+        "encoder",
+        "MiniMaxH3Encoder",
     ),
     ## MiniMax-Music3 (text-to-music; AR talker -> flow-matching acoustic decoder)
     "MiniMaxMusic3TalkerForConditionalGeneration": (
diff --git a/vllm_omni/model_executor/stage_input_processors/minimax_h3.py b/vllm_omni/model_executor/stage_input_processors/minimax_h3.py
index 87808adc362..78fd0225f27 100644
--- a/vllm_omni/model_executor/stage_input_processors/minimax_h3.py
+++ b/vllm_omni/model_executor/stage_input_processors/minimax_h3.py
@@ -1,73 +1,22 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-"""MiniMax H3 text-encoder stage input and output adapters."""
+"""Adapters between MiniMax H3 conditioning and the Omni stage runner."""
 
 from __future__ import annotations
 
 import copy
-import shutil
-import tempfile
 from collections.abc import Mapping, Sequence
 from typing import Any
 
-import numpy as np
-from PIL import Image
-
-from vllm_omni.data_entry_keys import REQUEST_ARTIFACT_DIRS_KEY
-from vllm_omni.diffusion.models.minimax_h3.time_request import minimax_h3_align_frame_count
-from vllm_omni.errors import OmniClientError
+from vllm_omni.data_entry_keys import unflatten_payload
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.model_executor.models.minimax_h3.conditioning import (
     MINIMAX_H3_CONDITION_LABELS_KEY,
+    MINIMAX_H3_ENCODER_REQUEST_KEY,
     MINIMAX_H3_PRESENTATION_TASK_KEY,
-    MiniMaxH3TextConditioning,
-)
-from vllm_omni.model_executor.models.minimax_h3.preprocessing import (
-    MINIMAX_H3_OUTPUT_SHORT_EDGE,
-    load_minimax_h3_images,
-    resolve_minimax_h3_aspect_ratio,
-    resolve_minimax_h3_output_canvas,
-    resolve_minimax_h3_reference_image_shape,
-)
-from vllm_omni.model_executor.models.minimax_h3.reference_video import (
-    MINIMAX_H3_PREPARED_REFERENCE_VIDEOS_KEY,
-    MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS,
-    prepare_reference_videos,
-    sample_reference_video_frames,
-    serialize_prepared_reference_videos,
+    MiniMaxH3EncoderConditioning,
 )
-
-
-def _items(value: Any) -> list[Any]:
-    if value is None:
-        return []
-    if isinstance(value, list):
-        return value
-    if isinstance(value, tuple) and not (len(value) == 2 and isinstance(value[1], Mapping)):
-        return list(value)
-    return [value]
-
-
-def _audio_items(value: Any) -> list[Any]:
-    if value is None:
-        return []
-    if isinstance(value, (list, tuple)) and len(value) == 2 and isinstance(value[1], (int, np.integer)):
-        return [value]
-    return list(value) if isinstance(value, (list, tuple)) else [value]
-
-
-def _resolve_task(
-    extra_args: Mapping[str, Any],
-    multi_modal_data: Mapping[str, Any],
-) -> str:
-    requested = extra_args.get("task")
-    if requested is not None:
-        return str(requested).lower()
-    if multi_modal_data.get("video") is not None or multi_modal_data.get("audio") is not None:
-        return "ref2va"
-    if multi_modal_data.get("image") is not None:
-        return "fl2va"
-    return "t2va"
+from vllm_omni.model_executor.models.minimax_h3.encoder_processing import prepare_encoder_inputs
 
 
 def _diffusion_sampling_params(sampling_params_list: Sequence[Any]) -> Any:
@@ -78,190 +27,29 @@ def _diffusion_sampling_params(sampling_params_list: Sequence[Any]) -> Any:
     ]
     if len(diffusion_params) != 1:
         raise RuntimeError(
-            "MiniMax H3 text encoding requires exactly one OmniDiffusionSamplingParams stage parameter, "
+            "MiniMax H3 encoding requires exactly one OmniDiffusionSamplingParams stage parameter, "
             f"got {len(diffusion_params)}"
         )
     return diffusion_params[0]
 
 
-def _ref2va_target_frame_count(sampling_params_list: Sequence[Any]) -> int:
-    sampling = _diffusion_sampling_params(sampling_params_list)
-    extra_args = sampling.extra_args or {}
-    target = extra_args.get("target")
-    target = target if isinstance(target, Mapping) else {}
-    duration = target.get("duration_seconds", extra_args.get("duration_seconds", extra_args.get("duration")))
-    if duration is not None:
-        requested = int(round(float(duration) * 24))
-    elif int(getattr(sampling, "num_frames", None) or 1) > 1:
-        requested = int(sampling.num_frames)
-    else:
-        requested = 124
-    return minimax_h3_align_frame_count(requested)
-
-
-def _prepare_qwen_images(
-    task: str,
-    values: list[Any],
-    sampling_params_list: Sequence[Any],
-) -> list[Any]:
-    if not values:
-        return []
-    images = load_minimax_h3_images(values)
-    if task == "ref2va":
-        return [
-            image.resize(
-                resolve_minimax_h3_reference_image_shape(image),
-                Image.Resampling.LANCZOS,
-            )
-            for image in images
-        ]
-    if task != "fl2va":
-        return images
-
-    sampling = _diffusion_sampling_params(sampling_params_list)
-    extra_args = sampling.extra_args or {}
-    target = extra_args.get("target")
-    if target is not None and not isinstance(target, Mapping):
-        raise OmniClientError("MiniMax H3 extra_args['target'] must be an object")
-    target = target if isinstance(target, Mapping) else {}
-    aspect_ratio = resolve_minimax_h3_aspect_ratio(
-        task,
-        target.get("aspect_ratio", extra_args.get("aspect_ratio")),
-        images[0],
-    )
-    if not 0.25 <= aspect_ratio <= 4.0:
-        raise OmniClientError(f"MiniMax H3 canvas aspect ratio must be in [1:4, 4:1], got {aspect_ratio}")
-    height = sampling.height
-    width = sampling.width
-    if height is None or width is None:
-        short_edge = target.get(
-            "short_edge",
-            extra_args.get("short_edge", MINIMAX_H3_OUTPUT_SHORT_EDGE),
-        )
-        if isinstance(short_edge, bool) or not isinstance(short_edge, (int, np.integer)):
-            raise OmniClientError(
-                f"MiniMax H3 target.short_edge must be {MINIMAX_H3_OUTPUT_SHORT_EDGE}, got {short_edge!r}"
-            )
-        height, width = resolve_minimax_h3_output_canvas(aspect_ratio, int(short_edge))
-    height = int(height) // 32 * 32
-    width = int(width) // 32 * 32
-    if min(height, width) <= 0:
-        raise OmniClientError(f"invalid MiniMax H3 canvas {width}x{height}")
-    if width > 4 * height or height > 4 * width:
-        raise OmniClientError("MiniMax H3 canvas aspect ratio must be in [1:4, 4:1]")
-    return [image.resize((width, height), Image.Resampling.LANCZOS) for image in images]
-
-
-def prepare_text_encoder_prompt(
+def prepare_encoder_prompt(
     prompt: Any,
     sampling_params_list: Sequence[Any],
 ) -> Any:
-    """Build H3's labeled Qwen3-VL presentation for Stage 0.
-
-    The upstream Qwen3-VL multimodal processor expands each image/video
-    placeholder into the exact number of vision tokens and adds timestamped
-    video blocks.  Audio is represented only by its H3 text label and is not
-    sent to Qwen3-VL.
-    """
+    prepared = prepare_encoder_inputs(prompt, _diffusion_sampling_params(sampling_params_list))
     if isinstance(prompt, str):
-        return prompt
-    if not isinstance(prompt, dict):
-        raise TypeError(f"MiniMax H3 expects a string or dict prompt, got {type(prompt)!r}")
-
-    prompt = copy.copy(prompt)
-    additional_information = dict(prompt.get("additional_information") or {})
-    meta = dict(additional_information.get("meta") or {})
-    meta.pop(MINIMAX_H3_PREPARED_REFERENCE_VIDEOS_KEY, None)
-    additional_information["meta"] = meta
-    prompt["additional_information"] = additional_information
-
-    text = str(prompt.get("prompt") or "")
-    if not text:
-        raise OmniClientError("MiniMax H3 requires a non-empty prompt")
-    multi_modal_data = prompt.get("multi_modal_data") or {}
-    if not isinstance(multi_modal_data, Mapping):
-        raise TypeError("multi_modal_data must be a mapping")
-
-    image_values = _items(multi_modal_data.get("image"))
-    videos = _items(multi_modal_data.get("video"))
-    audios = _audio_items(multi_modal_data.get("audio"))
-    diffusion_sampling = _diffusion_sampling_params(sampling_params_list)
-    extra_args = diffusion_sampling.extra_args or {}
-    task = _resolve_task(extra_args, multi_modal_data)
-    images = _prepare_qwen_images(task, image_values, sampling_params_list)
-    qwen_video_inputs: list[tuple[np.ndarray, dict[str, Any]]] = []
-    condition_labels: list[tuple[str, int]] = []
-
-    if task == "t2va":
-        if images or videos or audios:
-            raise OmniClientError("t2va does not accept image, video, or audio conditions")
-    elif task == "fl2va":
-        if not images or videos or audios:
-            raise OmniClientError("fl2va requires image conditions only")
-        condition_labels.extend(("image", index) for index in range(1, len(images) + 1))
-    elif task == "ref2va":
-        if not images and not videos:
-            raise OmniClientError("ref2va requires an image or video condition")
-        condition_labels.extend(("image", index) for index in range(1, len(images) + 1))
-        prepared_videos: list[dict[str, Any]] = []
-        artifact_dir: str | None = None
-        if videos:
-            artifact_dir = tempfile.mkdtemp(prefix="minimax_h3_ref2va_")
-            try:
-                prepared_videos = prepare_reference_videos(
-                    videos,
-                    target_frame_count=_ref2va_target_frame_count(sampling_params_list),
-                    workdir=artifact_dir,
-                    start_time_seconds=extra_args.get("start_time_seconds"),
-                )
-                for item in prepared_videos:
-                    sampled = sample_reference_video_frames(item["prepared_path"])
-                    frames = np.stack(sampled["frames"])
-                    frame_count = int(frames.shape[0])
-                    qwen_video_inputs.append(
-                        (
-                            frames,
-                            {
-                                "total_num_frames": frame_count,
-                                "fps": MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS,
-                                "duration": frame_count / MINIMAX_H3_QWEN_VIDEO_SAMPLE_FPS,
-                                "video_backend": "minimax_h3",
-                                "frames_indices": list(range(frame_count)),
-                                "do_sample_frames": False,
-                            },
-                        )
-                    )
-            except BaseException:
-                shutil.rmtree(artifact_dir, ignore_errors=True)
-                raise
-        audio_index = 0
-        for video_index, item in enumerate(prepared_videos, start=1):
-            if item["input_has_audio"]:
-                audio_index += 1
-                condition_labels.append(("audio", audio_index))
-            condition_labels.append(("video", video_index))
-        for _ in audios:
-            audio_index += 1
-            condition_labels.append(("audio", audio_index))
-    else:
-        raise OmniClientError(f"unsupported MiniMax H3 task {task!r}")
-
+        prompt = {"prompt": prompt}
+    text = prepared.prompt
+    images = prepared.images
+    qwen_video_inputs = prepared.qwen_videos
+    condition_labels = prepared.condition_labels
+    media_input = prepared.media
+    task = media_input.task
     transformed = copy.copy(prompt)
-    if isinstance(prompt.get("additional_information"), Mapping):
-        transformed["additional_information"] = dict(prompt["additional_information"])
+    additional_information = dict(prompt.get("additional_information") or {})
     transformed["prompt"] = text
-    if task == "ref2va" and prepared_videos and artifact_dir is not None:
-        additional_information = dict(transformed.get("additional_information") or {})
-        meta = dict(additional_information.get("meta") or {})
-        meta[MINIMAX_H3_PREPARED_REFERENCE_VIDEOS_KEY] = serialize_prepared_reference_videos(
-            prepared_videos,
-            artifact_dir,
-        )
-        additional_information["meta"] = meta
-        transformed["additional_information"] = additional_information
-        transformed[REQUEST_ARTIFACT_DIRS_KEY] = [artifact_dir]
-    qwen_mm_data = dict(multi_modal_data)
-    qwen_mm_data.pop("audio", None)
+    qwen_mm_data: dict[str, Any] = {}
     if images:
         qwen_mm_data["image"] = images
     if qwen_video_inputs:
@@ -271,7 +59,16 @@ def prepare_text_encoder_prompt(
     mm_processor_kwargs = dict(prompt.get("mm_processor_kwargs") or {})
     mm_processor_kwargs[MINIMAX_H3_PRESENTATION_TASK_KEY] = task
     mm_processor_kwargs[MINIMAX_H3_CONDITION_LABELS_KEY] = condition_labels
+    media_tensors = media_input.to_mm_tensors()
     transformed["mm_processor_kwargs"] = mm_processor_kwargs
+
+    hidden_states = dict(additional_information.get("hidden_states") or {})
+    hidden_states["layers"] = dict(enumerate(media_tensors))
+    additional_information["hidden_states"] = hidden_states
+    meta = dict(additional_information.get("meta") or {})
+    meta[MINIMAX_H3_ENCODER_REQUEST_KEY] = media_input.to_metadata()
+    additional_information["meta"] = meta
+    transformed["additional_information"] = additional_information
     return transformed
 
 
@@ -295,18 +92,20 @@ def _global_request_id(prompt: Mapping[str, Any]) -> str | None:
     return str(value) if value is not None else None
 
 
-def text_encoder2diffusion(
+def encoder2diffusion(
     source_outputs: list[Any],
     prompt: Any = None,
     requires_multimodal_data: bool = False,
     streaming_context: Any | None = None,
 ) -> dict[str, Any] | None:
-    """Attach Stage 0 hidden states and token tags to the original request."""
+    """Reuse the encoder handoff for all three H3 encoder components."""
     del requires_multimodal_data, streaming_context
     if not source_outputs:
         return None
     if len(source_outputs) != 1:
-        raise RuntimeError(f"MiniMax H3 diffusion requires exactly one text-encoder source, got {len(source_outputs)}")
+        raise RuntimeError(f"MiniMax H3 DiT requires exactly one encoder source, got {len(source_outputs)}")
+    if not getattr(source_outputs[0], "finished", True):
+        return None
 
     diffusion_prompt = _original_prompt(prompt)
     source_output = source_outputs[0]
@@ -318,25 +117,32 @@ def text_encoder2diffusion(
         and str(source_request_id) != expected_request_id
     ):
         raise RuntimeError(
-            "MiniMax H3 text-encoder request ID does not match the diffusion request: "
+            "MiniMax H3 encoder request ID does not match the diffusion request: "
             f"source={source_request_id!r}, expected={expected_request_id!r}"
         )
 
     outputs = getattr(source_output, "outputs", None)
     if not isinstance(outputs, list) or len(outputs) != 1:
         output_count = len(outputs) if isinstance(outputs, list) else 0
-        raise RuntimeError(f"MiniMax H3 text encoder must return exactly one completion, got {output_count}")
-
-    completion = outputs[0]
-    payload = completion.multimodal_output
+        raise RuntimeError(f"MiniMax H3 encoder must return exactly one completion, got {output_count}")
+    payload = getattr(outputs[0], "multimodal_output", None)
     if not isinstance(payload, Mapping):
-        raise RuntimeError("MiniMax H3 text encoder returned no conditioning payload")
+        raise RuntimeError("MiniMax H3 encoder returned no conditioning payload")
     try:
-        conditioning = MiniMaxH3TextConditioning.from_omni_payload(payload)
+        conditioning = MiniMaxH3EncoderConditioning.from_omni_payload(unflatten_payload(dict(payload)))
     except ValueError as exc:
         raise RuntimeError(str(exc)) from exc
 
     additional_information = dict(diffusion_prompt.get("additional_information") or {})
-    additional_information["text_encoder_output"] = conditioning.to_payload()
+    additional_information.pop("hidden_states", None)
+    meta = dict(additional_information.get("meta") or {})
+    meta.pop(MINIMAX_H3_ENCODER_REQUEST_KEY, None)
+    if meta:
+        additional_information["meta"] = meta
+    else:
+        additional_information.pop("meta", None)
+    additional_information["encoder_output"] = conditioning.to_omni_payload()
     diffusion_prompt["additional_information"] = additional_information
+    diffusion_prompt["multi_modal_data"] = None
+    diffusion_prompt.pop("model_intermediate_buffer", None)
     return diffusion_prompt

From afa837f15c37a1ebff99a4285df80a819a4a2192 Mon Sep 17 00:00:00 2001
From: "H.Z" <hu.zhu@connect.polyu.hk>
Date: Wed, 16 Sep 2026 18:04:52 +0800
Subject: [PATCH 031/105] [Frontend] Add MiniMax H3 ComfyUI text-to-video
 workflow (WF-01) (#7423)

Signed-off-by: Hu <hu.zhu@connect.polyu.hk>
---
 apps/ComfyUI-vLLM-Omni/README.md              |   9 +
 apps/ComfyUI-vLLM-Omni/docs/minimax-h3-t2v.md |  94 +++++
 .../MiniMax_H3_Text_to_Video.json             | 362 ++++++++++++++++++
 docs/features/comfyui.md                      |  12 +
 4 files changed, 477 insertions(+)
 create mode 100644 apps/ComfyUI-vLLM-Omni/docs/minimax-h3-t2v.md
 create mode 100644 apps/ComfyUI-vLLM-Omni/example_workflows/MiniMax_H3_Text_to_Video.json

diff --git a/apps/ComfyUI-vLLM-Omni/README.md b/apps/ComfyUI-vLLM-Omni/README.md
index 8f445635d28..d0d002d0f2a 100644
--- a/apps/ComfyUI-vLLM-Omni/README.md
+++ b/apps/ComfyUI-vLLM-Omni/README.md
@@ -213,6 +213,15 @@ Record the server commit, model/adapter, input assets, prompt, settings, and out
 alongside the result. Local schema or mocked-server checks do not establish H3
 generation quality or replace this real-model validation.
 
+### MiniMax H3 Text to Video
+
+Import [the H3 text-to-video template](example_workflows/MiniMax_H3_Text_to_Video.json)
+for remote video generation with audio. It includes connected base presets and
+optional Turbo sampling, H3 parameters, and Remote LoRA nodes. See the
+[workflow guide](docs/minimax-h3-t2v.md) for server setup, artifact-specific Turbo
+settings, and saved-video/audio validation. Set Remote LoRA’s `local_path` to
+the downloaded Turbo artifact on your server before enabling Turbo.
+
 #### H3 video upscale (WF-07)
 
 The **vLLM-Omni MiniMax H3 Video Upscale** template generates video remotely, upscales it with SeedVR2, and saves the original and upscaled videos with the generated audio and FPS. See [workflow setup](docs/wf07-h3-upscale.md).
diff --git a/apps/ComfyUI-vLLM-Omni/docs/minimax-h3-t2v.md b/apps/ComfyUI-vLLM-Omni/docs/minimax-h3-t2v.md
new file mode 100644
index 00000000000..790aa0f5358
--- /dev/null
+++ b/apps/ComfyUI-vLLM-Omni/docs/minimax-h3-t2v.md
@@ -0,0 +1,94 @@
+# MiniMax H3 Text to Video (WF-01)
+
+Import [MiniMax_H3_Text_to_Video.json](../example_workflows/MiniMax_H3_Text_to_Video.json)
+into ComfyUI, or select it under **Templates → ComfyUI-vLLM-Omni**.
+The template connects existing nodes to a remote H3 service and saves the
+returned video with audio. ComfyUI does not load H3 weights.
+
+## Setup
+
+Install the [ComfyUI extension](../README.md#installation) and follow the
+[H3 deployment recipe](../../../recipes/MiniMaxAI/MiniMax-H3.md) for your hardware.
+For a two-GPU FL2VA server with sufficient memory:
+
+```bash
+export MODEL=/path/to/MiniMax-H3/FL2VA
+CUDA_VISIBLE_DEVICES=0,1 VLLM_WORKER_MULTIPROC_METHOD=spawn \
+VLLM_OMNI_VIDEO_SYNC_TIMEOUT=14400 \
+vllm serve "$MODEL" --omni --host 127.0.0.1 --port 8000 \
+  --served-model-name MiniMaxAI/MiniMax-H3 --trust-remote-code \
+  --task-type fl2va --num-gpus 2 --tensor-parallel-size 2 \
+  --text-encoder-tp-size 2 --enforce-eager
+```
+
+Set Generate Video's **url** to the address reachable from ComfyUI, including
+`/v1`, and match its **model** to the served name. The defaults are
+`http://localhost:8000/v1` and `MiniMaxAI/MiniMax-H3`.
+
+## Base and Turbo
+
+Base presets are connected by default. Write the scene and its sound in the
+same **prompt**; leave **frame**, **references**, and **fast_h3** disconnected.
+The template uses 1344×768, 24 FPS, seed 1101 and **duration** 5.167 seconds
+(124 frames, satisfying H3's `17k+5` constraint). The existing client infers
+`16:9` from these dimensions. For portrait output, use 768×1344.
+
+| Setting | Base | Turbo v1.0 768p |
+| --- | --- | --- |
+| Inference steps | 50 | 5 (4 forwards) |
+| Video flow shift | 12 | 6 |
+| Audio flow shift | 3 | 3 |
+| Remote LoRA | Disconnected | Connected, scale 1 |
+
+For Turbo, use the **Diffusers-layout** artifact from
+[lightx2v/Minimax-h3-Turbo](https://huggingface.co/lightx2v/Minimax-h3-Turbo):
+
+```text
+minimax_h3_fl2v_turbo_4step_v1.0_768p_bf16.safetensors
+```
+
+Add `--lora-backend peft --lora-path "$TURBO_LORA"` to the server command,
+where `TURBO_LORA` is the full server-side path to that file. Enter the same
+path in Remote LoRA's **local_path**; retain name `h3-turbo-v1.0-768p`, scale
+`1.0`, and **int_id** `0` so the existing API derives the ID from the path.
+The template leaves the path blank for users to configure. The `_comfyui_`
+export is not supported by this backend.
+
+Connect **Turbo sampling**, **Turbo H3 params**, and **Remote LoRA** to Generate
+Video's `sampling_params`, `model_params`, and `lora` inputs, replacing the
+Base links. To return to Base, restore both Base links and disconnect LoRA.
+Other Turbo artifacts may need different settings; see the
+[artifact table](../../../recipes/MiniMaxAI/MiniMax-H3.md#turbo-lora).
+
+If importing an older template with a frame-count widget, reimport this JSON
+or set **duration** to **5.167**; do not interpret 124 frames as 124 seconds.
+
+## Validation
+
+Queue the configured workflow and inspect the MP4 saved under
+`ComfyUI/output/video/MiniMax_H3_WF01_*.mp4`:
+
+```bash
+ffprobe -v error -show_streams -show_format -of json "$OUTPUT"
+ffmpeg -v error -i "$OUTPUT" -f null -
+```
+
+Check the requested dimensions, frame count, 24 FPS and both video/audio
+streams, then watch and listen to the saved file. The current upstream
+extension includes the shared audio-preserving decoder fix.
+
+On September 16, the narrowed workflow was validated through ComfyUI using
+existing upstream Python code at `4a8ac297`, two H20-3e GPUs, vLLM 0.29.0,
+PyTorch 2.13.0+cu129 and ComfyUI `1d48d9cf`. The run used the template's
+forest-stream prompt, explicit server-side Turbo LoRA path, and settings
+above, with `TORCH_SDPA`, `--usp 1 --ring 1`, and tiled VAE parallelism on two
+GPUs. ComfyUI execution took 131.55 seconds. SaveVideo produced 124 H.264
+frames at 1344×768 and 24 FPS, plus 32 kHz stereo AAC audio. Video/audio
+durations were 5.166667/5.167000 seconds; full decoding passed and audio was
+nonzero. This is model-generated output, not a ground-truth reference or a
+subjective audio-quality assessment. Base graph validation passed with Turbo
+nodes disconnected; full 50-step Base quality was not evaluated.
+
+Based on the official
+[ComfyUI H3 T2V template](https://github.com/Comfy-Org/workflow_templates/blob/main/templates/video_minimax_h3_t2v.json),
+using remote inference instead of local model loaders.
diff --git a/apps/ComfyUI-vLLM-Omni/example_workflows/MiniMax_H3_Text_to_Video.json b/apps/ComfyUI-vLLM-Omni/example_workflows/MiniMax_H3_Text_to_Video.json
new file mode 100644
index 00000000000..137ee8c2db7
--- /dev/null
+++ b/apps/ComfyUI-vLLM-Omni/example_workflows/MiniMax_H3_Text_to_Video.json
@@ -0,0 +1,362 @@
+{
+  "last_node_id": 8,
+  "last_link_id": 3,
+  "nodes": [
+    {
+      "id": 1,
+      "type": "VLLMOmniDiffusionSampling",
+      "pos": [
+        20,
+        20
+      ],
+      "size": [
+        310,
+        280
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "diffusion sampling params",
+          "type": "SAMPLING_PARAMS",
+          "links": [
+            1
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniDiffusionSampling"
+      },
+      "widgets_values": [
+        1,
+        50,
+        1.0,
+        1.0,
+        false,
+        false,
+        1101,
+        "fixed"
+      ],
+      "title": "Base sampling"
+    },
+    {
+      "id": 2,
+      "type": "VLLMOmniMiniMaxH3Params",
+      "pos": [
+        20,
+        340
+      ],
+      "size": [
+        310,
+        140
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "MiniMax-H3 video params",
+          "type": "VIDEO_PARAMS",
+          "links": [
+            2
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniMiniMaxH3Params"
+      },
+      "widgets_values": [
+        3.0,
+        12.0
+      ],
+      "title": "Base H3 params"
+    },
+    {
+      "id": 3,
+      "type": "VLLMOmniGenerateVideo",
+      "pos": [
+        430,
+        20
+      ],
+      "size": [
+        430,
+        440
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "frame",
+          "type": "IMAGE",
+          "link": null
+        },
+        {
+          "name": "references",
+          "type": "VIDEO_REFERENCES",
+          "link": null
+        },
+        {
+          "name": "sampling_params",
+          "type": "SAMPLING_PARAMS",
+          "link": 1
+        },
+        {
+          "name": "lora",
+          "type": "REMOTE_LORA",
+          "link": null
+        },
+        {
+          "name": "model_params",
+          "type": "VIDEO_PARAMS",
+          "link": 2
+        },
+        {
+          "name": "fast_h3",
+          "type": "FASTH3_DEPLOYMENT",
+          "link": null
+        },
+        {
+          "name": "duration",
+          "type": "FLOAT",
+          "widget": {
+            "name": "duration"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "links": [
+            3
+          ],
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniGenerateVideo"
+      },
+      "widgets_values": [
+        "http://localhost:8000/v1",
+        "MiniMaxAI/MiniMax-H3",
+        "A small stream flows through a sunlit forest. The camera slowly moves toward the water. Birds chirp in the trees and water gurgles over smooth stones. Natural continuous sound, no music.",
+        "",
+        1344,
+        768,
+        24,
+        5.167
+      ]
+    },
+    {
+      "id": 4,
+      "type": "SaveVideo",
+      "pos": [
+        940,
+        20
+      ],
+      "size": [
+        440,
+        440
+      ],
+      "flags": {},
+      "order": 3,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "link": 3
+        }
+      ],
+      "outputs": [
+        {
+          "name": "video",
+          "type": "VIDEO",
+          "links": null,
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "SaveVideo"
+      },
+      "widgets_values": [
+        "video/MiniMax_H3_WF01",
+        "mp4",
+        "auto"
+      ]
+    },
+    {
+      "id": 5,
+      "type": "VLLMOmniRemoteLoRA",
+      "pos": [
+        430,
+        540
+      ],
+      "size": [
+        430,
+        160
+      ],
+      "flags": {},
+      "order": 4,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "lora",
+          "type": "REMOTE_LORA",
+          "links": null,
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniRemoteLoRA"
+      },
+      "widgets_values": [
+        "",
+        "h3-turbo-v1.0-768p",
+        1.0,
+        0
+      ],
+      "title": "Optional Turbo: server LoRA path"
+    },
+    {
+      "id": 6,
+      "type": "VLLMOmniDiffusionSampling",
+      "pos": [
+        20,
+        540
+      ],
+      "size": [
+        310,
+        280
+      ],
+      "flags": {},
+      "order": 5,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "diffusion sampling params",
+          "type": "SAMPLING_PARAMS",
+          "links": null,
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniDiffusionSampling"
+      },
+      "widgets_values": [
+        1,
+        5,
+        1.0,
+        1.0,
+        false,
+        false,
+        1101,
+        "fixed"
+      ],
+      "title": "Turbo sampling (4 forwards)"
+    },
+    {
+      "id": 7,
+      "type": "VLLMOmniMiniMaxH3Params",
+      "pos": [
+        430,
+        740
+      ],
+      "size": [
+        310,
+        140
+      ],
+      "flags": {},
+      "order": 6,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [
+        {
+          "name": "MiniMax-H3 video params",
+          "type": "VIDEO_PARAMS",
+          "links": null,
+          "slot_index": 0
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniMiniMaxH3Params"
+      },
+      "widgets_values": [
+        3.0,
+        6.0
+      ],
+      "title": "Turbo H3 params"
+    },
+    {
+      "id": 8,
+      "type": "Note",
+      "pos": [
+        940,
+        520
+      ],
+      "size": [
+        440,
+        440
+      ],
+      "flags": {},
+      "order": 7,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "properties": {
+        "Node name for S&R": "Note"
+      },
+      "widgets_values": [
+        "MiniMax H3 Text to Video (WF-01)\n\nBASE: connected presets, 50 steps / video flow 12 / audio flow 3.\n\nTURBO: set Remote LoRA local_path to the SERVER path of minimax_h3_fl2v_turbo_4step_v1.0_768p_bf16.safetensors from lightx2v/Minimax-h3-Turbo. Keep name h3-turbo-v1.0-768p, scale 1.0 and int_id 0. Connect Turbo sampling, Turbo H3 params, and LoRA to Generate Video, replacing the two Base links. Use 5 steps (4 forwards), video flow 6 and audio flow 3. Do not use the ComfyUI-layout artifact.\n\nKeep frame, references and fast_h3 disconnected. 1344x768, 24 FPS, duration 5.167 seconds = 124 frames (17*7+5). The client selects the named 16:9 preset from the dimensions. Save Video preserves video and audio.\n\nSet URL and served model name for your server. See docs/minimax-h3-t2v.md for setup and validation. Source: Comfy-Org/workflow_templates/templates/video_minimax_h3_t2v.json."
+      ],
+      "title": "Setup / Base and Turbo"
+    }
+  ],
+  "links": [
+    [
+      1,
+      1,
+      0,
+      3,
+      2,
+      "SAMPLING_PARAMS"
+    ],
+    [
+      2,
+      2,
+      0,
+      3,
+      4,
+      "VIDEO_PARAMS"
+    ],
+    [
+      3,
+      3,
+      0,
+      4,
+      0,
+      "VIDEO"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "ds": {
+      "scale": 0.8,
+      "offset": [
+        50,
+        50
+      ]
+    }
+  },
+  "version": 0.4
+}
diff --git a/docs/features/comfyui.md b/docs/features/comfyui.md
index b4d6fa101eb..876e8061781 100644
--- a/docs/features/comfyui.md
+++ b/docs/features/comfyui.md
@@ -81,6 +81,18 @@ To build a simple workflow yourself,
     - For some multi-stage models like BAGEL, [only one stage's sampling parameters are exposed and tunable via vLLM-Omni's online serving API](https://docs.vllm.ai/projects/vllm-omni/en/latest/user_guide/examples/online_serving/bagel/). Thus, these models are treated as single-stage ones. Please check the vLLM-Omni documentation on how to correctly set each model's sampling parameters.
     - For multi-stage models where all stages are either autoregression or diffusion, you can also connect only a single Sampling Params node, indicating that this set of sampling parameters will be used for all stages.
 
+## MiniMax H3 text-to-video workflow
+
+The **MiniMax H3 Text to Video** template uses the existing remote Generate Video,
+H3 Params, sampling, and Remote LoRA nodes. It includes Base settings and an
+optional Turbo preset, with native resolution, 24 FPS, and `17k+5` frame counts.
+ComfyUI receives the generated video and audio from the server; it does not load
+H3 weights locally. Configure the server-side LoRA path before enabling Turbo.
+
+See the [H3 workflow guide](https://github.com/vllm-project/vllm-omni/blob/main/apps/ComfyUI-vLLM-Omni/docs/minimax-h3-t2v.md)
+for server setup, template import, Turbo configuration, recorded validation,
+and saved-video/audio checks.
+
 ## Examples & Screenshots
 
 Please read the [ComfyUI integration's README](https://github.com/vllm-project/vllm-omni/tree/main/apps/ComfyUI-vLLM-Omni) for more info.

From 249e84d21b93fe8758bcd06503419367d538c2ac Mon Sep 17 00:00:00 2001
From: dengyunyang <584797741@qq.com>
Date: Wed, 16 Sep 2026 18:13:54 +0800
Subject: [PATCH 032/105] [Boogu-Image] Fuse QKV/FFN projections + switch to
 diffusion RMSNorm (#6649)

Signed-off-by: dengyunyang <584797741@qq.com>
---
 .../test_boogu_image_transformer.py           | 143 +++++++++--
 .../boogu_image/boogu_image_transformer.py    | 227 +++++++++++-------
 2 files changed, 257 insertions(+), 113 deletions(-)

diff --git a/tests/diffusion/models/boogu_image/test_boogu_image_transformer.py b/tests/diffusion/models/boogu_image/test_boogu_image_transformer.py
index 79954f1db99..32061f64825 100644
--- a/tests/diffusion/models/boogu_image/test_boogu_image_transformer.py
+++ b/tests/diffusion/models/boogu_image/test_boogu_image_transformer.py
@@ -440,29 +440,86 @@ def test_transformer_rejects_prompt_tuning():
         BooguImageTransformer2DModel(od_config=_tiny_od_config(prompt_tuning_configs={"use_prompt_tuning": True}))
 
 
-def _native_to_checkpoint_name(name: str) -> str:
-    """Inverse of ``load_weights`` remapping: native param name -> diffusers name.
+_QKV_FANOUT = {
+    "to_qkv": ("to_q", "to_k", "to_v"),
+    "img_to_qkv": ("img_to_q", "img_to_k", "img_to_v"),
+    "instruct_to_qkv": ("instruct_to_q", "instruct_to_k", "instruct_to_v"),
+}
+
+
+def _native_to_checkpoint_weights(name: str, param: torch.Tensor) -> list[tuple[str, torch.Tensor]]:
+    """Inverse of ``load_weights`` remapping: native param -> diffusers weights.
+
+    The diffusers checkpoint stores fused projections as separate matrices, so a
+    single merged native param (QKV or FFN gate/up) fans out into several
+    checkpoint weights. Returns ``(diffusers_name, value)`` pairs whose values,
+    when fed through ``load_weights``, reassemble into the original ``param``.
 
     - ``.to_out.<suffix>`` -> ``.to_out.0.<suffix>`` (diffusers ModuleList wrap).
     - promoted joint-attention projections move back under ``.processor.``.
     """
+    q_size = NUM_HEADS * HEAD_DIM
+    kv_size = NUM_KV_HEADS * HEAD_DIM
+
+    # Fused QKV projections split back into per-matrix q/k/v weights.
+    for token, (q_name, k_name, v_name) in _QKV_FANOUT.items():
+        marker = f".{token}."
+        if marker in name:
+            q, k, v = param[:q_size], param[q_size : q_size + kv_size], param[q_size + kv_size :]
+            results = []
+            for sub_name, value in ((q_name, q), (k_name, k), (v_name, v)):
+                ckpt_name = name.replace(marker, f".{sub_name}.")
+                if token != "to_qkv":
+                    # Joint-attention projections live under `.processor.` upstream.
+                    ckpt_name = ckpt_name.replace(".img_instruct_attn.", ".img_instruct_attn.processor.")
+                results.append((ckpt_name, value))
+            return results
+
+    # Fused FFN gate/up splits into linear_1 (gate) / linear_3 (input).
+    if ".gate_up_proj." in name:
+        inner = param.shape[0] // 2
+        return [
+            (name.replace(".gate_up_proj.", ".linear_1."), param[:inner]),
+            (name.replace(".gate_up_proj.", ".linear_3."), param[inner:]),
+        ]
+
+    # Default: 1:1 with the existing diffusers name promotions.
     if ".to_out." in name:
         name = name.replace(".to_out.", ".to_out.0.")
-    for proj in (
-        "img_to_q",
-        "img_to_k",
-        "img_to_v",
-        "instruct_to_q",
-        "instruct_to_k",
-        "instruct_to_v",
-        "instruct_out",
-        "img_out",
-    ):
+    for proj in ("instruct_out", "img_out"):
         token = f".img_instruct_attn.{proj}."
         if token in name:
             name = name.replace(token, f".img_instruct_attn.processor.{proj}.")
             break
-    return name
+    return [(name, param)]
+
+
+def test_transformer_exposes_stacked_params_mapping():
+    """The packed -> sub-layer mapping must be discoverable from the module tree.
+
+    ``diffusion/lora/loader.py`` and the quantized weight loaders read
+    ``stacked_params_mapping`` off the model, so it has to exist before (and
+    independently of) ``load_weights``.
+    """
+    from vllm_omni.diffusion.models.boogu_image.boogu_image_transformer import (
+        _BOOGU_STACKED_PARAMS_MAPPING,
+        BooguImageTransformer2DModel,
+    )
+
+    model = BooguImageTransformer2DModel(od_config=_tiny_od_config())
+
+    assert tuple(model.stacked_params_mapping) == _BOOGU_STACKED_PARAMS_MAPPING
+    # A per-instance copy, so consumers cannot mutate the module constant.
+    assert model.stacked_params_mapping is not _BOOGU_STACKED_PARAMS_MAPPING
+
+    # Every entry is a (param, shard, shard_id) triple.
+    for param_name, shard_name, shard_id in model.stacked_params_mapping:
+        assert param_name.startswith(".") and shard_name.startswith(".")
+        assert shard_id in {"q", "k", "v", 0, 1}
+
+    # The mapping targets exactly the fused projections this port creates.
+    mapped_leaves = {param.strip(".").split(".")[-1] for param, _, _ in model.stacked_params_mapping}
+    assert mapped_leaves == {"to_qkv", "img_to_qkv", "instruct_to_qkv", "gate_up_proj"}
 
 
 def test_transformer_load_weights_round_trip():
@@ -473,24 +530,59 @@ def test_transformer_load_weights_round_trip():
     model = BooguImageTransformer2DModel(od_config=_tiny_od_config())
     native_params = dict(model.named_parameters())
 
-    # Build synthetic diffusers-named weights (one per native parameter).
-    checkpoint_weights = {}
+    # Build synthetic diffusers-named weights. Fused native projections fan out
+    # into the separate matrices the diffusers checkpoint stores.
+    expected: dict[str, torch.Tensor] = {}
+    checkpoint_weights: dict[str, torch.Tensor] = {}
     for native_name, param in native_params.items():
-        checkpoint_weights[_native_to_checkpoint_name(native_name)] = torch.randn_like(param)
+        full = torch.randn_like(param)
+        expected[native_name] = full
+        for ckpt_name, value in _native_to_checkpoint_weights(native_name, full):
+            checkpoint_weights[ckpt_name] = value
 
-    # The remapping must be a bijection over the parameter set.
-    assert len(checkpoint_weights) == len(native_params)
+    # Every checkpoint name is unique; merged params fan out to >=1 weight.
+    assert len(checkpoint_weights) >= len(native_params)
 
     loaded = model.load_weights(list(checkpoint_weights.items()))
 
     # No missing / unexpected parameters.
     assert loaded == set(native_params.keys())
 
-    # Values landed on the right parameters (TP=1: weight_loader copies verbatim).
+    # Values landed on the right parameters (TP=1: weight_loader copies verbatim;
+    # fused shards are placed at their q/k/v / gate/up offsets).
     reloaded = dict(model.named_parameters())
     for native_name in native_params:
-        expected = checkpoint_weights[_native_to_checkpoint_name(native_name)]
-        assert torch.allclose(reloaded[native_name], expected)
+        assert torch.allclose(reloaded[native_name], expected[native_name])
+
+
+def test_transformer_load_weights_rejects_partial_fused_params():
+    """A fused parameter must not count as loaded until all its shards arrive.
+
+    The loader compares parameter *names*, so reporting ``to_qkv`` complete
+    after a single ``to_q`` would let a checkpoint carrying only ``to_q`` start
+    up with the ``k``/``v`` slices left uninitialized.
+    """
+    from vllm_omni.diffusion.models.boogu_image.boogu_image_transformer import (
+        BooguImageTransformer2DModel,
+    )
+
+    model = BooguImageTransformer2DModel(od_config=_tiny_od_config())
+    native_params = dict(model.named_parameters())
+
+    complete_name = "noise_refiner.0.attn.to_qkv.weight"
+    partial_name = "noise_refiner.0.feed_forward.gate_up_proj.weight"
+    assert complete_name in native_params
+    assert partial_name in native_params
+
+    weights = list(_native_to_checkpoint_weights(complete_name, native_params[complete_name]))
+    # Only the gate half of the FFN, so its fused parameter stays incomplete.
+    gate_ckpt, gate_value = _native_to_checkpoint_weights(partial_name, native_params[partial_name])[0]
+    weights.append((gate_ckpt, gate_value))
+
+    loaded = model.load_weights(weights)
+
+    assert complete_name in loaded
+    assert partial_name not in loaded
 
 
 def test_transformer_load_weights_warns_for_unexpected_and_unloaded():
@@ -513,12 +605,15 @@ def emit(self, record: logging.LogRecord) -> None:
     try:
         model = BooguImageTransformer2DModel(od_config=_tiny_od_config())
         native_params = dict(model.named_parameters())
-        loaded_name = next(iter(native_params))
-        checkpoint_name = _native_to_checkpoint_name(loaded_name)
+        # A non-fused parameter, so one checkpoint entry loads it completely.
+        loaded_name = "x_embedder.weight"
+        assert loaded_name in native_params
+        (checkpoint_name, checkpoint_value), *_ = _native_to_checkpoint_weights(loaded_name, native_params[loaded_name])
+        checkpoint_value = torch.randn_like(checkpoint_value)
 
         loaded = model.load_weights(
             [
-                (checkpoint_name, torch.randn_like(native_params[loaded_name])),
+                (checkpoint_name, checkpoint_value),
                 ("unexpected.weight", torch.ones(1)),
             ]
         )
diff --git a/vllm_omni/diffusion/models/boogu_image/boogu_image_transformer.py b/vllm_omni/diffusion/models/boogu_image/boogu_image_transformer.py
index 93d52b9606e..f3fdeedc8c6 100644
--- a/vllm_omni/diffusion/models/boogu_image/boogu_image_transformer.py
+++ b/vllm_omni/diffusion/models/boogu_image/boogu_image_transformer.py
@@ -15,6 +15,7 @@
 #     inference caches (TeaCache/TaylorSeer) are not ported.
 
 import itertools
+from collections import defaultdict
 from collections.abc import Iterable
 from typing import TYPE_CHECKING
 
@@ -24,9 +25,9 @@
 from diffusers.models.embeddings import Timesteps, get_1d_rotary_pos_embed
 from einops import rearrange, repeat
 from vllm.logger import init_logger
-from vllm.model_executor.layers.layernorm import RMSNorm
 from vllm.model_executor.layers.linear import (
-    ColumnParallelLinear,
+    MergedColumnParallelLinear,
+    QKVParallelLinear,
     ReplicatedLinear,
     RowParallelLinear,
 )
@@ -42,6 +43,7 @@
     fused_qk_norm_rope,
     fused_qk_norm_rope_min_tokens,
 )
+from vllm_omni.diffusion.layers.norm import RMSNorm
 from vllm_omni.diffusion.models.utils import make_attention_mask
 from vllm_omni.platforms import current_omni_platform
 
@@ -260,7 +262,14 @@ def forward(self, x: torch.Tensor, conditioning_embedding: torch.Tensor) -> torc
 
 
 class LuminaFeedForward(nn.Module):
-    """SwiGLU feed-forward with tensor-parallel projections."""
+    """SwiGLU feed-forward with tensor-parallel projections.
+
+    The ``gate`` and ``input`` projections are fused into a single
+    ``MergedColumnParallelLinear`` (one GEMM instead of two), matching the
+    ``gate_up_proj`` convention used by the Hunyuan Image 3 port. The SwiGLU
+    activation keeps its float32 computation for numerical parity with
+    upstream.
+    """
 
     def __init__(
         self,
@@ -276,20 +285,13 @@ def __init__(
             inner_dim = int(ffn_dim_multiplier * inner_dim)
         inner_dim = multiple_of * ((inner_dim + multiple_of - 1) // multiple_of)
 
-        self.linear_1 = ColumnParallelLinear(
-            dim,
-            inner_dim,
-            bias=False,
-            quant_config=quant_config,
-            prefix=_join_prefix(prefix, "linear_1"),
-        )  # gate
-        self.linear_3 = ColumnParallelLinear(
-            dim,
-            inner_dim,
+        self.gate_up_proj = MergedColumnParallelLinear(
+            input_size=dim,
+            output_sizes=[inner_dim, inner_dim],
             bias=False,
             quant_config=quant_config,
-            prefix=_join_prefix(prefix, "linear_3"),
-        )  # input
+            prefix=_join_prefix(prefix, "gate_up_proj"),
+        )
         self.linear_2 = RowParallelLinear(
             inner_dim,
             dim,
@@ -299,8 +301,8 @@ def __init__(
         )
 
     def forward(self, x: torch.Tensor) -> torch.Tensor:
-        h1, _ = self.linear_1(x)
-        h2, _ = self.linear_3(x)
+        gate_up, _ = self.gate_up_proj(x)
+        h1, h2 = gate_up.chunk(2, dim=-1)
         out, _ = self.linear_2(swiglu(h1, h2))
         return out
 
@@ -593,28 +595,15 @@ def __init__(
     ) -> None:
         super().__init__()
         self.head_dim = dim // num_attention_heads
-        kv_dim = self.head_dim * num_kv_heads
 
-        self.to_q = ColumnParallelLinear(
-            dim,
-            dim,
-            bias=False,
-            quant_config=quant_config,
-            prefix=_join_prefix(prefix, "to_q"),
-        )
-        self.to_k = ColumnParallelLinear(
-            dim,
-            kv_dim,
-            bias=False,
-            quant_config=quant_config,
-            prefix=_join_prefix(prefix, "to_k"),
-        )
-        self.to_v = ColumnParallelLinear(
-            dim,
-            kv_dim,
+        self.to_qkv = QKVParallelLinear(
+            hidden_size=dim,
+            head_size=self.head_dim,
+            total_num_heads=num_attention_heads,
+            total_num_kv_heads=num_kv_heads,
             bias=False,
             quant_config=quant_config,
-            prefix=_join_prefix(prefix, "to_v"),
+            prefix=_join_prefix(prefix, "to_qkv"),
         )
         self.norm_q = RMSNorm(self.head_dim, eps=1e-5)
         self.norm_k = RMSNorm(self.head_dim, eps=1e-5)
@@ -626,8 +615,10 @@ def __init__(
             prefix=_join_prefix(prefix, "to_out"),
         )
 
-        self.num_local_heads = self.to_q.output_size_per_partition // self.head_dim
-        self.num_local_kv_heads = self.to_k.output_size_per_partition // self.head_dim
+        self.num_local_heads = self.to_qkv.num_heads
+        self.num_local_kv_heads = self.to_qkv.num_kv_heads
+        self.q_size = self.num_local_heads * self.head_dim
+        self.kv_size = self.num_local_kv_heads * self.head_dim
 
         self.attn = Attention(
             num_heads=self.num_local_heads,
@@ -645,9 +636,8 @@ def forward(
     ) -> torch.Tensor:
         dtype = hidden_states.dtype
 
-        query, _ = self.to_q(hidden_states)
-        key, _ = self.to_k(hidden_states)
-        value, _ = self.to_v(hidden_states)
+        qkv, _ = self.to_qkv(hidden_states)
+        query, key, value = qkv.split([self.q_size, self.kv_size, self.kv_size], dim=-1)
 
         query = query.unflatten(-1, (self.num_local_heads, self.head_dim))
         key = key.unflatten(-1, (self.num_local_kv_heads, self.head_dim))
@@ -683,50 +673,24 @@ def __init__(
     ) -> None:
         super().__init__()
         self.head_dim = dim // num_attention_heads
-        kv_dim = self.head_dim * num_kv_heads
 
-        self.img_to_q = ColumnParallelLinear(
-            dim,
-            dim,
-            bias=False,
-            quant_config=quant_config,
-            prefix=_join_prefix(prefix, "img_to_q"),
-        )
-        self.img_to_k = ColumnParallelLinear(
-            dim,
-            kv_dim,
-            bias=False,
-            quant_config=quant_config,
-            prefix=_join_prefix(prefix, "img_to_k"),
-        )
-        self.img_to_v = ColumnParallelLinear(
-            dim,
-            kv_dim,
-            bias=False,
-            quant_config=quant_config,
-            prefix=_join_prefix(prefix, "img_to_v"),
-        )
-
-        self.instruct_to_q = ColumnParallelLinear(
-            dim,
-            dim,
-            bias=False,
-            quant_config=quant_config,
-            prefix=_join_prefix(prefix, "instruct_to_q"),
-        )
-        self.instruct_to_k = ColumnParallelLinear(
-            dim,
-            kv_dim,
+        self.img_to_qkv = QKVParallelLinear(
+            hidden_size=dim,
+            head_size=self.head_dim,
+            total_num_heads=num_attention_heads,
+            total_num_kv_heads=num_kv_heads,
             bias=False,
             quant_config=quant_config,
-            prefix=_join_prefix(prefix, "instruct_to_k"),
+            prefix=_join_prefix(prefix, "img_to_qkv"),
         )
-        self.instruct_to_v = ColumnParallelLinear(
-            dim,
-            kv_dim,
+        self.instruct_to_qkv = QKVParallelLinear(
+            hidden_size=dim,
+            head_size=self.head_dim,
+            total_num_heads=num_attention_heads,
+            total_num_kv_heads=num_kv_heads,
             bias=False,
             quant_config=quant_config,
-            prefix=_join_prefix(prefix, "instruct_to_v"),
+            prefix=_join_prefix(prefix, "instruct_to_qkv"),
         )
 
         self.norm_q = RMSNorm(self.head_dim, eps=1e-5)
@@ -757,8 +721,10 @@ def __init__(
             prefix=_join_prefix(prefix, "to_out"),
         )
 
-        self.num_local_heads = self.img_to_q.output_size_per_partition // self.head_dim
-        self.num_local_kv_heads = self.img_to_k.output_size_per_partition // self.head_dim
+        self.num_local_heads = self.img_to_qkv.num_heads
+        self.num_local_kv_heads = self.img_to_qkv.num_kv_heads
+        self.q_size = self.num_local_heads * self.head_dim
+        self.kv_size = self.num_local_kv_heads * self.head_dim
 
         self.attn = Attention(
             num_heads=self.num_local_heads,
@@ -780,13 +746,13 @@ def forward(
         dtype = img_hidden_states.dtype
         batch_size = img_hidden_states.shape[0]
 
-        img_query, _ = self.img_to_q(img_hidden_states)
-        img_key, _ = self.img_to_k(img_hidden_states)
-        img_value, _ = self.img_to_v(img_hidden_states)
+        img_qkv, _ = self.img_to_qkv(img_hidden_states)
+        img_query, img_key, img_value = img_qkv.split([self.q_size, self.kv_size, self.kv_size], dim=-1)
 
-        instruct_query, _ = self.instruct_to_q(instruct_hidden_states)
-        instruct_key, _ = self.instruct_to_k(instruct_hidden_states)
-        instruct_value, _ = self.instruct_to_v(instruct_hidden_states)
+        instruct_qkv, _ = self.instruct_to_qkv(instruct_hidden_states)
+        instruct_query, instruct_key, instruct_value = instruct_qkv.split(
+            [self.q_size, self.kv_size, self.kv_size], dim=-1
+        )
 
         query, key, value = _concat_instruction_image_features(
             [img_query, img_key, img_value],
@@ -1135,6 +1101,44 @@ def _cal_preprocessed_instruction_feat_dim(instruction_feature_configs: dict) ->
         raise ValueError(f"Invalid reduce_type: {reduce_type}")
 
 
+# Packed (fused) projections vs. the logical sub-projections the diffusers
+# checkpoint stores, in the ``(param_name, shard_name, shard_id)`` form used
+# across vllm-omni. ``load_weights`` consumes it directly, and loader consumers
+# that discover it via ``stacked_params_mapping`` (LoRA, quantized loaders) get
+# the packed -> sub-layer relationship for free.
+#
+# The QKV entries stay leaf-scoped: each fused source (``to_q`` on the
+# self-attention module, ``img_to_q`` / ``instruct_to_q`` on the joint
+# attention) has a distinct leaf, and ``.to_q.`` cannot collide with
+# ``.img_to_q.`` because the preceding character is ``_`` rather than ``.``.
+# The FFN entries are path-qualified instead: ``linear_1`` also names the
+# timestep embedder and the ``norm_out`` projections, which must load 1:1 and
+# are not fused.
+_BOOGU_STACKED_PARAMS_MAPPING = (
+    # self-attention: noise / reference-image / context refiners, the
+    # single-stream blocks, and the double-stream image self-attention.
+    (".to_qkv.", ".to_q.", "q"),
+    (".to_qkv.", ".to_k.", "k"),
+    (".to_qkv.", ".to_v.", "v"),
+    # joint (instruction + image) attention of the double-stream blocks.
+    (".img_to_qkv.", ".img_to_q.", "q"),
+    (".img_to_qkv.", ".img_to_k.", "k"),
+    (".img_to_qkv.", ".img_to_v.", "v"),
+    (".instruct_to_qkv.", ".instruct_to_q.", "q"),
+    (".instruct_to_qkv.", ".instruct_to_k.", "k"),
+    (".instruct_to_qkv.", ".instruct_to_v.", "v"),
+    # feed-forward gate/up: ``linear_1`` is the gate (shard 0) and
+    # ``linear_3`` the input (shard 1), matching the packed order the SwiGLU
+    # activation consumes.
+    (".feed_forward.gate_up_proj.", ".feed_forward.linear_1.", 0),
+    (".feed_forward.gate_up_proj.", ".feed_forward.linear_3.", 1),
+    (".img_feed_forward.gate_up_proj.", ".img_feed_forward.linear_1.", 0),
+    (".img_feed_forward.gate_up_proj.", ".img_feed_forward.linear_3.", 1),
+    (".instruct_feed_forward.gate_up_proj.", ".instruct_feed_forward.linear_1.", 0),
+    (".instruct_feed_forward.gate_up_proj.", ".instruct_feed_forward.linear_3.", 1),
+)
+
+
 class BooguImageTransformer2DModel(nn.Module):
     """Boogu-Image transformer with mixed stream topology.
 
@@ -1160,6 +1164,10 @@ def __init__(
         prefix: str = "",
     ) -> None:
         super().__init__()
+        # Published here rather than in ``load_weights`` so loader consumers
+        # that only inspect the module tree (LoRA discovery, quantized weight
+        # loaders) always see the packed -> sub-layer relationship.
+        self.stacked_params_mapping = list(_BOOGU_STACKED_PARAMS_MAPPING)
         self.od_config = od_config
         cfg = od_config.tf_model_config
 
@@ -1710,7 +1718,7 @@ def forward(
     def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
         """Load diffusers-named checkpoint weights into the native module.
 
-        Two name promotions relative to upstream (see step 8/10 findings):
+        Name promotions relative to upstream (see step 8/10 findings):
 
         - ``*.img_instruct_attn.processor.{img,instruct}_{to_q,to_k,to_v}`` /
           ``{instruct,img}_out`` -> drop ``.processor`` (upstream keeps the
@@ -1719,9 +1727,29 @@ def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
         - ``*.to_out.0.weight`` -> ``*.to_out.weight`` (diffusers wraps the
           output projection in a ``ModuleList``; the native module uses a plain
           linear).
+
+        Packed Q/K/V and FFN gate/input matrices are folded onto the fused
+        ``QKVParallelLinear`` / ``MergedColumnParallelLinear`` parameters using
+        :attr:`stacked_params_mapping` — the same mapping loader consumers such
+        as LoRA discovery and quantized weight loaders read.
+
+        A fused parameter is only reported as loaded once *every* one of its
+        source matrices has arrived. The caller compares parameter names, so
+        reporting e.g. ``to_qkv`` complete after the first shard would let a
+        checkpoint carrying only ``to_q`` start up with the ``k``/``v`` slices
+        left uninitialized.
         """
+        stacked_params_mapping = self.stacked_params_mapping
+        # The shard ids each fused parameter is assembled from, keyed by the
+        # mapping entry that produces it.
+        expected_shards: dict[str, set[str | int]] = defaultdict(set)
+        for param_name, _weight_name, packed_shard_id in stacked_params_mapping:
+            expected_shards[param_name].add(packed_shard_id)
+
         params_dict = dict(self.named_parameters())
         loaded_params: set[str] = set()
+        # Fused parameter -> (mapping entry that produced it, shards received).
+        fused_params: dict[str, tuple[str, set[str | int]]] = {}
 
         for name, loaded_weight in weights:
             original_name = name
@@ -1730,15 +1758,36 @@ def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
             if ".to_out.0." in name:
                 name = name.replace(".to_out.0.", ".to_out.")
 
+            shard_id: str | int | None = None
+            matched_entry: str | None = None
+            for param_name, weight_name, packed_shard_id in stacked_params_mapping:
+                if weight_name in name:
+                    name = name.replace(weight_name, param_name)
+                    shard_id = packed_shard_id
+                    matched_entry = param_name
+                    break
+
             if name not in params_dict:
                 logger.warning("Skipping unexpected checkpoint weight %s", original_name)
                 continue
 
             param = params_dict[name]
             weight_loader = getattr(param, "weight_loader", default_weight_loader)
-            weight_loader(param, loaded_weight)
+            if matched_entry is None:
+                weight_loader(param, loaded_weight)
+            else:
+                weight_loader(param, loaded_weight, shard_id)
+                _, received = fused_params.setdefault(name, (matched_entry, set()))
+                received.add(shard_id)
             loaded_params.add(name)
 
+        # Withdraw any fused parameter that only received part of its source
+        # matrices, so the caller's "not initialized from checkpoint" check
+        # reports it as missing instead of accepting a half-filled parameter.
+        for name, (matched_entry, received) in fused_params.items():
+            if received != expected_shards[matched_entry]:
+                loaded_params.discard(name)
+
         unloaded_params = sorted(params_dict.keys() - loaded_params)
         if unloaded_params:
             logger.warning("Model parameters not loaded from checkpoint: %s", unloaded_params)

From 217a6af52cae0d054d3f63b36de0ef653caafc96 Mon Sep 17 00:00:00 2001
From: dongbo910220 <32610838+dongbo910220@users.noreply.github.com>
Date: Wed, 16 Sep 2026 19:06:28 +0800
Subject: [PATCH 033/105] [Diffusion] Fuse Qwen-Image-Edit select01 modulation
 for CUDA (#5921)

Signed-off-by: dongbo910220 <1275604947@qq.com>
---
 .../kernels/bench_qwen_select01_modulation.py | 333 ++++++++++++
 .../layers/test_qwen_select01_modulation.py   | 299 +++++++++++
 .../test_qwen_image_select01_routing.py       |  87 ++++
 .../layers/qwen_select01_modulation.py        | 491 ++++++++++++++++++
 .../qwen_image/qwen_image_transformer.py      |  83 +--
 5 files changed, 1255 insertions(+), 38 deletions(-)
 create mode 100644 benchmarks/kernels/bench_qwen_select01_modulation.py
 create mode 100644 tests/diffusion/layers/test_qwen_select01_modulation.py
 create mode 100644 tests/diffusion/models/qwen_image/test_qwen_image_select01_routing.py
 create mode 100644 vllm_omni/diffusion/layers/qwen_select01_modulation.py

diff --git a/benchmarks/kernels/bench_qwen_select01_modulation.py b/benchmarks/kernels/bench_qwen_select01_modulation.py
new file mode 100644
index 00000000000..9a97c8de3a7
--- /dev/null
+++ b/benchmarks/kernels/bench_qwen_select01_modulation.py
@@ -0,0 +1,333 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Benchmark the Qwen-Image-Edit select01 modulation hot path.
+
+This script intentionally starts with the current PyTorch implementation. It is
+used as the before/after baseline for SGLang PR #20395/#21318 style fusion:
+
+* layernorm + scale/shift + binary select01 gate
+* residual + gated update + layernorm + scale/shift + binary select01 gate
+
+Run on a CUDA machine for actionable numbers, for example:
+
+    python benchmarks/kernels/bench_qwen_select01_modulation.py \
+        --device cuda --dtype bf16 --seq-lens 4096 8192 16384 \
+        --output-json /tmp/qwen_select01_baseline.json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import statistics
+import sys
+import time
+from collections.abc import Callable
+from pathlib import Path
+
+import torch
+import torch.nn.functional as F
+
+for candidate in Path(__file__).resolve().parents:
+    if (candidate / "vllm_omni").is_dir():
+        if str(candidate) not in sys.path:
+            sys.path.insert(0, str(candidate))
+        break
+
+from vllm_omni.diffusion.layers.qwen_select01_modulation import (  # noqa: E402
+    fused_layernorm_select01,
+    fused_residual_layernorm_select01,
+)
+
+
+def _dtype(name: str) -> torch.dtype:
+    return {
+        "fp32": torch.float32,
+        "float32": torch.float32,
+        "fp16": torch.float16,
+        "float16": torch.float16,
+        "bf16": torch.bfloat16,
+        "bfloat16": torch.bfloat16,
+    }[name]
+
+
+def _select01_modulation(
+    mod_params: torch.Tensor,
+    index: torch.Tensor | None,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    shift, scale, gate = mod_params.chunk(3, dim=-1)
+
+    if index is None:
+        return scale.unsqueeze(1), shift.unsqueeze(1), gate.unsqueeze(1)
+
+    actual_batch = shift.size(0) // 2
+    shift_0, shift_1 = shift[:actual_batch], shift[actual_batch:]
+    scale_0, scale_1 = scale[:actual_batch], scale[actual_batch:]
+    gate_0, gate_1 = gate[:actual_batch], gate[actual_batch:]
+
+    idx = index.unsqueeze(-1) == 0
+    shift = torch.where(idx, shift_0.unsqueeze(1), shift_1.unsqueeze(1))
+    scale = torch.where(idx, scale_0.unsqueeze(1), scale_1.unsqueeze(1))
+    gate = torch.where(idx, gate_0.unsqueeze(1), gate_1.unsqueeze(1))
+    return scale, shift, gate
+
+
+def _native_layernorm_select01(
+    x: torch.Tensor,
+    mod_params: torch.Tensor,
+    index: torch.Tensor,
+    eps: float,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    scale, shift, gate = _select01_modulation(mod_params, index)
+    out = F.layer_norm(x.float(), (x.shape[-1],), eps=eps).to(x.dtype)
+    return out * (1 + scale) + shift, gate
+
+
+def _native_residual_layernorm_select01(
+    x: torch.Tensor,
+    residual: torch.Tensor,
+    residual_gate: torch.Tensor,
+    mod_params: torch.Tensor,
+    index: torch.Tensor,
+    eps: float,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    scale, shift, gate = _select01_modulation(mod_params, index)
+    residual_out = residual + residual_gate * x
+    out = F.layer_norm(residual_out.float(), (residual_out.shape[-1],), eps=eps).to(residual_out.dtype)
+    return out * (1 + scale) + shift, residual_out, gate
+
+
+def _time_cuda(fn: Callable[[], object], warmup: int, iters: int) -> list[float]:
+    for _ in range(warmup):
+        fn()
+    torch.accelerator.synchronize()
+
+    times: list[float] = []
+    for _ in range(iters):
+        start = torch.cuda.Event(enable_timing=True)
+        end = torch.cuda.Event(enable_timing=True)
+        start.record()
+        fn()
+        end.record()
+        torch.accelerator.synchronize()
+        times.append(float(start.elapsed_time(end)))
+    return times
+
+
+def _reset_peak_memory_stats(device: torch.device) -> None:
+    reset_peak_memory_stats = getattr(torch.accelerator, "reset_peak_memory_stats", None)
+    if reset_peak_memory_stats is None:
+        reset_peak_memory_stats = getattr(getattr(torch, device.type), "reset_peak_memory_stats")
+    reset_peak_memory_stats(device)
+
+
+def _max_memory_allocated(device: torch.device) -> int:
+    max_memory_allocated = getattr(torch.accelerator, "max_memory_allocated", None)
+    if max_memory_allocated is None:
+        max_memory_allocated = getattr(getattr(torch, device.type), "max_memory_allocated")
+    return int(max_memory_allocated(device))
+
+
+def _time_cpu(fn: Callable[[], object], warmup: int, iters: int) -> list[float]:
+    for _ in range(warmup):
+        fn()
+
+    times: list[float] = []
+    for _ in range(iters):
+        t0 = time.perf_counter()
+        fn()
+        times.append((time.perf_counter() - t0) * 1000.0)
+    return times
+
+
+def _summarize(times: list[float]) -> dict[str, float]:
+    ordered = sorted(times)
+    return {
+        "median_ms": statistics.median(ordered),
+        "min_ms": ordered[0],
+        "p20_ms": ordered[max(0, int(len(ordered) * 0.20) - 1)],
+        "p80_ms": ordered[min(len(ordered) - 1, int(len(ordered) * 0.80))],
+    }
+
+
+def _make_inputs(
+    batch: int,
+    seq_len: int,
+    hidden_size: int,
+    dtype: torch.dtype,
+    device: torch.device,
+) -> dict[str, torch.Tensor]:
+    torch.manual_seed(0)
+    return {
+        "x": torch.randn(batch, seq_len, hidden_size, device=device, dtype=dtype),
+        "residual": torch.randn(batch, seq_len, hidden_size, device=device, dtype=dtype),
+        "residual_gate": torch.randn(batch, 1, hidden_size, device=device, dtype=dtype),
+        "mod_params": torch.randn(batch * 2, hidden_size * 3, device=device, dtype=dtype),
+        "index": torch.randint(0, 2, (batch, seq_len), device=device, dtype=torch.int64),
+    }
+
+
+def _bench_one(
+    name: str,
+    fn: Callable[[], object],
+    device: torch.device,
+    warmup: int,
+    iters: int,
+) -> dict[str, object]:
+    if device.type == "cuda":
+        _reset_peak_memory_stats(device)
+        times = _time_cuda(fn, warmup, iters)
+        peak_memory_mb = _max_memory_allocated(device) / 1024**2
+    else:
+        times = _time_cpu(fn, warmup, iters)
+        peak_memory_mb = None
+
+    return {
+        "name": name,
+        **_summarize(times),
+        "peak_memory_mb": peak_memory_mb,
+    }
+
+
+def _run(args: argparse.Namespace) -> dict[str, object]:
+    device = torch.device(args.device)
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise SystemExit("CUDA is not available on this machine.")
+
+    dtype = _dtype(args.dtype)
+    rows: list[dict[str, object]] = []
+
+    for seq_len in args.seq_lens:
+        tensors = _make_inputs(args.batch_size, seq_len, args.hidden_size, dtype, device)
+        impls = ["native"] if args.impl == "native" else ["fused"] if args.impl == "fused" else ["native", "fused"]
+
+        def first_norm() -> object:
+            return _native_layernorm_select01(
+                tensors["x"],
+                tensors["mod_params"],
+                tensors["index"],
+                args.eps,
+            )
+
+        def residual_norm() -> object:
+            return _native_residual_layernorm_select01(
+                tensors["x"],
+                tensors["residual"],
+                tensors["residual_gate"],
+                tensors["mod_params"],
+                tensors["index"],
+                args.eps,
+            )
+
+        callables: list[tuple[str, Callable[[], object]]] = []
+        if "native" in impls:
+            callables.extend(
+                [
+                    ("native_layernorm_select01", first_norm),
+                    ("native_residual_layernorm_select01", residual_norm),
+                ]
+            )
+        if "fused" in impls:
+
+            def fused_first_norm() -> object:
+                return fused_layernorm_select01(
+                    tensors["x"],
+                    tensors["mod_params"],
+                    tensors["index"],
+                    args.eps,
+                )
+
+            def fused_residual_norm() -> object:
+                return fused_residual_layernorm_select01(
+                    tensors["x"],
+                    tensors["residual"],
+                    tensors["residual_gate"].expand_as(tensors["residual"]),
+                    tensors["mod_params"],
+                    tensors["index"],
+                    args.eps,
+                )
+
+            callables.extend(
+                [
+                    ("fused_layernorm_select01", fused_first_norm),
+                    ("fused_residual_layernorm_select01", fused_residual_norm),
+                ]
+            )
+
+        if args.check and "fused" in impls:
+            ref_norm, ref_gate = first_norm()
+            actual_norm, actual_gate = fused_layernorm_select01(
+                tensors["x"],
+                tensors["mod_params"],
+                tensors["index"],
+                args.eps,
+            )
+            torch.testing.assert_close(actual_norm, ref_norm, atol=args.check_atol, rtol=args.check_rtol)
+            torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+            ref_norm, ref_residual, ref_gate = residual_norm()
+            actual_norm, actual_residual, actual_gate = fused_residual_layernorm_select01(
+                tensors["x"],
+                tensors["residual"],
+                tensors["residual_gate"].expand_as(tensors["residual"]),
+                tensors["mod_params"],
+                tensors["index"],
+                args.eps,
+            )
+            torch.testing.assert_close(actual_norm, ref_norm, atol=args.check_atol, rtol=args.check_rtol)
+            torch.testing.assert_close(actual_residual, ref_residual, atol=args.check_atol, rtol=args.check_rtol)
+            torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+        for name, fn in callables:
+            row = _bench_one(name, fn, device, args.warmup, args.iters)
+            row.update(
+                {
+                    "batch_size": args.batch_size,
+                    "seq_len": seq_len,
+                    "hidden_size": args.hidden_size,
+                    "dtype": args.dtype,
+                    "device": str(device),
+                }
+            )
+            rows.append(row)
+            print(
+                f"{name:<38} B={args.batch_size:<2} L={seq_len:<6} C={args.hidden_size:<5} "
+                f"median={row['median_ms']:.4f} ms p20={row['p20_ms']:.4f} p80={row['p80_ms']:.4f}"
+            )
+
+    result = {
+        "benchmark": "qwen_select01_modulation",
+        "torch": torch.__version__,
+        "cuda_available": torch.cuda.is_available(),
+        "gpu": torch.cuda.get_device_name(device) if device.type == "cuda" else None,
+        "rows": rows,
+    }
+
+    if args.output_json:
+        output_path = Path(args.output_json)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(json.dumps(result, indent=2), encoding="utf-8")
+
+    return result
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description=__doc__)
+    default_device = "cuda" if torch.cuda.is_available() else "cpu"
+    parser.add_argument("--device", default=default_device)
+    parser.add_argument("--dtype", default="bf16", choices=["fp32", "float32", "fp16", "float16", "bf16", "bfloat16"])
+    parser.add_argument("--batch-size", type=int, default=1)
+    parser.add_argument("--seq-lens", type=int, nargs="+", default=[4096, 8192, 16384])
+    parser.add_argument("--hidden-size", type=int, default=3072)
+    parser.add_argument("--eps", type=float, default=1e-6)
+    parser.add_argument("--warmup", type=int, default=20)
+    parser.add_argument("--iters", type=int, default=100)
+    parser.add_argument("--impl", choices=["native", "fused", "all"], default="native")
+    parser.add_argument("--check", action="store_true")
+    parser.add_argument("--check-atol", type=float, default=5e-2)
+    parser.add_argument("--check-rtol", type=float, default=5e-2)
+    parser.add_argument("--output-json")
+    return parser.parse_args()
+
+
+if __name__ == "__main__":
+    _run(_parse_args())
diff --git a/tests/diffusion/layers/test_qwen_select01_modulation.py b/tests/diffusion/layers/test_qwen_select01_modulation.py
new file mode 100644
index 00000000000..050da4717ed
--- /dev/null
+++ b/tests/diffusion/layers/test_qwen_select01_modulation.py
@@ -0,0 +1,299 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import pytest
+import torch
+import torch.nn.functional as F
+
+from vllm_omni.diffusion.layers import qwen_select01_modulation
+from vllm_omni.diffusion.layers.qwen_select01_modulation import (
+    can_use_qwen_select01_triton,
+    fused_layernorm_select01,
+    fused_residual_layernorm_select01,
+    select01_modulation_native,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion]
+
+
+@pytest.mark.cpu
+@pytest.mark.parametrize(
+    ("platform_is_cuda", "tensor_is_cuda", "has_triton", "expected"),
+    [
+        (True, True, True, True),
+        (False, True, True, False),
+        (True, False, True, False),
+        (True, True, False, False),
+    ],
+)
+def test_qwen_select01_triton_requires_cuda_platform(
+    monkeypatch,
+    platform_is_cuda: bool,
+    tensor_is_cuda: bool,
+    has_triton: bool,
+    expected: bool,
+):
+    class FakePlatform:
+        @staticmethod
+        def is_cuda() -> bool:
+            return platform_is_cuda
+
+    class FakeTensor:
+        is_cuda = tensor_is_cuda
+
+    monkeypatch.setattr(qwen_select01_modulation, "current_platform", FakePlatform())
+    monkeypatch.setattr(qwen_select01_modulation, "HAS_TRITON", has_triton)
+
+    assert can_use_qwen_select01_triton(FakeTensor()) is expected
+
+
+def _make_inputs(
+    batch_size: int,
+    seq_len: int,
+    hidden_size: int,
+    dtype: torch.dtype,
+    device: torch.device,
+) -> tuple[torch.Tensor, ...]:
+    generator = torch.Generator(device=device)
+    generator.manual_seed(202817)
+    x = torch.randn(batch_size, seq_len, hidden_size, dtype=dtype, device=device, generator=generator)
+    residual = torch.randn(batch_size, seq_len, hidden_size, dtype=dtype, device=device, generator=generator)
+    residual_gate = torch.randn(batch_size, 1, hidden_size, dtype=dtype, device=device, generator=generator)
+    mod_params = torch.randn(batch_size * 2, hidden_size * 3, dtype=dtype, device=device, generator=generator)
+    index = torch.randint(0, 2, (batch_size, seq_len), dtype=torch.int64, device=device, generator=generator)
+    return x, residual, residual_gate, mod_params, index
+
+
+def _reference_layernorm_select01(
+    x: torch.Tensor,
+    mod_params: torch.Tensor,
+    index: torch.Tensor,
+    eps: float,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    scale, shift, gate = select01_modulation_native(mod_params, index)
+    out = F.layer_norm(x.float(), (x.shape[-1],), eps=eps).to(x.dtype)
+    return out * (1 + scale) + shift, gate
+
+
+def _reference_residual_layernorm_select01(
+    x: torch.Tensor,
+    residual: torch.Tensor,
+    residual_gate: torch.Tensor,
+    mod_params: torch.Tensor,
+    index: torch.Tensor,
+    eps: float,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    scale, shift, gate = select01_modulation_native(mod_params, index)
+    residual_out = residual + residual_gate * x
+    out = F.layer_norm(residual_out.float(), (residual_out.shape[-1],), eps=eps).to(residual_out.dtype)
+    return out * (1 + scale) + shift, residual_out, gate
+
+
+@pytest.mark.cpu
+@pytest.mark.parametrize("dtype", [torch.float32, torch.bfloat16])
+@pytest.mark.parametrize("broadcast_index", [False, True])
+def test_qwen_select01_native_fallback_matches_reference(dtype: torch.dtype, broadcast_index: bool):
+    device = torch.device("cpu")
+    x, residual, residual_gate, mod_params, index = _make_inputs(2, 17, 64, dtype, device)
+    if broadcast_index:
+        index = index[:1]
+    eps = 1e-6
+
+    actual_norm, actual_gate = fused_layernorm_select01(x, mod_params, index, eps)
+    ref_norm, ref_gate = _reference_layernorm_select01(x, mod_params, index, eps)
+    torch.testing.assert_close(actual_norm, ref_norm, atol=1e-5, rtol=1e-5)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+    actual_norm, actual_residual, actual_gate = fused_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate,
+        mod_params,
+        index,
+        eps,
+    )
+    ref_norm, ref_residual, ref_gate = _reference_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate,
+        mod_params,
+        index,
+        eps,
+    )
+    torch.testing.assert_close(actual_norm, ref_norm, atol=1e-5, rtol=1e-5)
+    torch.testing.assert_close(actual_residual, ref_residual, atol=1e-5, rtol=1e-5)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.parametrize(
+    ("dtype", "atol", "rtol"),
+    [
+        (torch.float32, 1e-5, 1e-5),
+        (torch.bfloat16, 5e-2, 5e-2),
+    ],
+)
+@pytest.mark.parametrize("seq_len", [1, 7, 128, 1024])
+def test_qwen_select01_triton_matches_reference(dtype: torch.dtype, atol: float, rtol: float, seq_len: int):
+    device = torch.device("cuda:0")
+    x, residual, residual_gate, mod_params, index = _make_inputs(2, seq_len, 256, dtype, device)
+    eps = 1e-6
+
+    actual_norm, actual_gate = fused_layernorm_select01(x, mod_params, index, eps)
+    ref_norm, ref_gate = _reference_layernorm_select01(x, mod_params, index, eps)
+    torch.testing.assert_close(actual_norm, ref_norm, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+    actual_norm, actual_residual, actual_gate = fused_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate.expand_as(residual),
+        mod_params,
+        index,
+        eps,
+    )
+    ref_norm, ref_residual, ref_gate = _reference_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate.expand_as(residual),
+        mod_params,
+        index,
+        eps,
+    )
+    torch.testing.assert_close(actual_norm, ref_norm, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_residual, ref_residual, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.parametrize(
+    ("dtype", "atol", "rtol"),
+    [
+        (torch.float32, 1e-5, 1e-5),
+        (torch.bfloat16, 5e-2, 5e-2),
+    ],
+)
+def test_qwen_select01_triton_matches_reference_for_structured_multi_batch_index(
+    dtype: torch.dtype,
+    atol: float,
+    rtol: float,
+):
+    device = torch.device("cuda:0")
+    x, residual, residual_gate, mod_params, _ = _make_inputs(3, 16, 256, dtype, device)
+    index = torch.tensor(
+        [
+            [0] * 16,
+            [1] * 16,
+            [0, 1] * 8,
+        ],
+        dtype=torch.int64,
+        device=device,
+    )
+    eps = 1e-6
+
+    actual_norm, actual_gate = fused_layernorm_select01(x, mod_params, index, eps)
+    ref_norm, ref_gate = _reference_layernorm_select01(x, mod_params, index, eps)
+    torch.testing.assert_close(actual_norm, ref_norm, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+    actual_norm, actual_residual, actual_gate = fused_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate.expand_as(residual),
+        mod_params,
+        index,
+        eps,
+    )
+    ref_norm, ref_residual, ref_gate = _reference_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate.expand_as(residual),
+        mod_params,
+        index,
+        eps,
+    )
+    torch.testing.assert_close(actual_norm, ref_norm, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_residual, ref_residual, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.parametrize(
+    ("dtype", "atol", "rtol"),
+    [
+        (torch.float32, 1e-5, 1e-5),
+        (torch.bfloat16, 5e-2, 5e-2),
+    ],
+)
+def test_qwen_select01_triton_broadcasts_single_index_batch(dtype: torch.dtype, atol: float, rtol: float):
+    device = torch.device("cuda:0")
+    x, residual, residual_gate, mod_params, index = _make_inputs(2, 17, 256, dtype, device)
+    index = index[:1]
+    eps = 1e-6
+
+    actual_norm, actual_gate = fused_layernorm_select01(x, mod_params, index, eps)
+    ref_norm, ref_gate = _reference_layernorm_select01(x, mod_params, index, eps)
+    torch.testing.assert_close(actual_norm, ref_norm, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+    actual_norm, actual_residual, actual_gate = fused_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate.expand_as(residual),
+        mod_params,
+        index,
+        eps,
+    )
+    ref_norm, ref_residual, ref_gate = _reference_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate.expand_as(residual),
+        mod_params,
+        index,
+        eps,
+    )
+    torch.testing.assert_close(actual_norm, ref_norm, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_residual, ref_residual, atol=atol, rtol=rtol)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+def test_qwen_select01_cuda_falls_back_without_triton(monkeypatch):
+    device = torch.device("cuda:0")
+    x, residual, residual_gate, mod_params, index = _make_inputs(2, 7, 256, torch.bfloat16, device)
+    residual_gate = residual_gate.expand_as(residual)
+    eps = 1e-6
+
+    def fail_if_launched(*args, **kwargs):
+        pytest.fail("Triton launcher must not run when HAS_TRITON is false")
+
+    monkeypatch.setattr(qwen_select01_modulation, "HAS_TRITON", False)
+    monkeypatch.setattr(qwen_select01_modulation, "_launch_layernorm_select01", fail_if_launched)
+    monkeypatch.setattr(qwen_select01_modulation, "_launch_residual_layernorm_select01", fail_if_launched)
+
+    actual_norm, actual_gate = fused_layernorm_select01(x, mod_params, index, eps)
+    ref_norm, ref_gate = _reference_layernorm_select01(x, mod_params, index, eps)
+    torch.testing.assert_close(actual_norm, ref_norm, atol=0, rtol=0)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
+
+    actual_norm, actual_residual, actual_gate = fused_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate,
+        mod_params,
+        index,
+        eps,
+    )
+    ref_norm, ref_residual, ref_gate = _reference_residual_layernorm_select01(
+        x,
+        residual,
+        residual_gate,
+        mod_params,
+        index,
+        eps,
+    )
+    torch.testing.assert_close(actual_norm, ref_norm, atol=0, rtol=0)
+    torch.testing.assert_close(actual_residual, ref_residual, atol=0, rtol=0)
+    torch.testing.assert_close(actual_gate, ref_gate, atol=0, rtol=0)
diff --git a/tests/diffusion/models/qwen_image/test_qwen_image_select01_routing.py b/tests/diffusion/models/qwen_image/test_qwen_image_select01_routing.py
new file mode 100644
index 00000000000..1a3acbb48e7
--- /dev/null
+++ b/tests/diffusion/models/qwen_image/test_qwen_image_select01_routing.py
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import pytest
+import torch
+import torch.nn as nn
+
+from vllm_omni.diffusion.models.qwen_image import qwen_image_transformer
+from vllm_omni.diffusion.models.qwen_image.qwen_image_transformer import QwenImageTransformerBlock
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+class _StaticOutput(nn.Module):
+    def __init__(self, output: torch.Tensor):
+        super().__init__()
+        self.output = output
+
+    def forward(self, _: torch.Tensor) -> torch.Tensor:
+        return self.output
+
+
+class _RecordingNorm(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.calls: list[tuple[torch.Tensor, torch.Tensor, torch.Tensor]] = []
+
+    def forward(self, x: torch.Tensor, scale: torch.Tensor, shift: torch.Tensor) -> torch.Tensor:
+        self.calls.append((x, scale, shift))
+        return x
+
+
+class _ZeroAttention(nn.Module):
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: torch.Tensor,
+        **_: object,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        return torch.zeros_like(hidden_states), torch.zeros_like(encoder_hidden_states)
+
+
+class _ZeroMLP(nn.Module):
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return torch.zeros_like(x)
+
+
+def test_non_cuda_select01_uses_adalayernorm_dispatch(monkeypatch):
+    hidden_size = 4
+    block = QwenImageTransformerBlock.__new__(QwenImageTransformerBlock)
+    nn.Module.__init__(block)
+    block.zero_cond_t = True
+    block.img_mod = _StaticOutput(torch.zeros(2, 6 * hidden_size))
+    block.txt_mod = _StaticOutput(torch.zeros(1, 6 * hidden_size))
+    block.img_norm1 = _RecordingNorm()
+    block.img_norm2 = _RecordingNorm()
+    block.txt_norm1 = _RecordingNorm()
+    block.txt_norm2 = _RecordingNorm()
+    block.attn = _ZeroAttention()
+    block.img_mlp = _ZeroMLP()
+    block.txt_mlp = _ZeroMLP()
+
+    monkeypatch.setattr(qwen_image_transformer, "can_use_qwen_select01_triton", lambda _: False)
+
+    def fail_if_called(*args, **kwargs):
+        pytest.fail("non-CUDA select01 must preserve the AdaLayerNorm dispatch")
+
+    monkeypatch.setattr(qwen_image_transformer, "fused_layernorm_select01", fail_if_called)
+    monkeypatch.setattr(qwen_image_transformer, "fused_residual_layernorm_select01", fail_if_called)
+
+    hidden_states = torch.randn(1, 3, hidden_size)
+    encoder_hidden_states = torch.randn(1, 2, hidden_size)
+    modulate_index = torch.tensor([[0, 1, 0]])
+    block(
+        hidden_states,
+        encoder_hidden_states,
+        torch.ones(1, 2),
+        torch.zeros(2, hidden_size),
+        (torch.empty(0), torch.empty(0)),
+        modulate_index=modulate_index,
+    )
+
+    assert len(block.img_norm1.calls) == 1
+    assert len(block.img_norm2.calls) == 1
+    for _, scale, shift in (*block.img_norm1.calls, *block.img_norm2.calls):
+        assert scale.shape == hidden_states.shape
+        assert shift.shape == hidden_states.shape
diff --git a/vllm_omni/diffusion/layers/qwen_select01_modulation.py b/vllm_omni/diffusion/layers/qwen_select01_modulation.py
new file mode 100644
index 00000000000..4fe1e3e0e3b
--- /dev/null
+++ b/vllm_omni/diffusion/layers/qwen_select01_modulation.py
@@ -0,0 +1,491 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import torch
+import torch.nn.functional as F
+from vllm.platforms import current_platform
+from vllm.triton_utils import HAS_TRITON, tl, triton
+
+
+@triton.jit
+def _layernorm_select01_kernel(
+    output_ptr,
+    gate_out_ptr,
+    x_ptr,
+    weight_ptr,
+    bias_ptr,
+    scale0_ptr,
+    shift0_ptr,
+    gate0_ptr,
+    scale1_ptr,
+    shift1_ptr,
+    gate1_ptr,
+    index_ptr,
+    inner_dim,
+    seq_len,
+    stride_x_row,
+    stride_out_row,
+    stride_gate_out_row,
+    stride_w,
+    stride_b,
+    stride_s0_b,
+    stride_s0_c,
+    stride_sh0_b,
+    stride_sh0_c,
+    stride_g0_b,
+    stride_g0_c,
+    stride_s1_b,
+    stride_s1_c,
+    stride_sh1_b,
+    stride_sh1_c,
+    stride_g1_b,
+    stride_g1_c,
+    stride_i_b,
+    stride_i_l,
+    eps,
+    has_weight: tl.constexpr,
+    has_bias: tl.constexpr,
+    block_n: tl.constexpr,
+):
+    row = tl.program_id(0)
+    cols = tl.arange(0, block_n)
+    mask = cols < inner_dim
+
+    x_row_ptr = x_ptr + row * stride_x_row
+    x = tl.load(x_row_ptr + cols, mask=mask, other=0.0).to(tl.float32)
+
+    mean = tl.sum(x, axis=0) / inner_dim
+    xbar = tl.where(mask, x - mean, 0.0)
+    var = tl.sum(xbar * xbar, axis=0) / inner_dim
+    x_hat = (x - mean) * tl.rsqrt(var + eps)
+
+    if has_weight:
+        weight = tl.load(weight_ptr + cols * stride_w, mask=mask, other=1.0).to(tl.float32)
+        x_hat = x_hat * weight
+    if has_bias:
+        bias = tl.load(bias_ptr + cols * stride_b, mask=mask, other=0.0).to(tl.float32)
+        x_hat = x_hat + bias
+
+    batch_idx = row // seq_len
+    seq_idx = row % seq_len
+    idx = tl.load(index_ptr + batch_idx * stride_i_b + seq_idx * stride_i_l).to(tl.int1)
+
+    scale0_ptrs = scale0_ptr + batch_idx * stride_s0_b + cols * stride_s0_c
+    shift0_ptrs = shift0_ptr + batch_idx * stride_sh0_b + cols * stride_sh0_c
+    gate0_ptrs = gate0_ptr + batch_idx * stride_g0_b + cols * stride_g0_c
+    scale1_ptrs = scale1_ptr + batch_idx * stride_s1_b + cols * stride_s1_c
+    shift1_ptrs = shift1_ptr + batch_idx * stride_sh1_b + cols * stride_sh1_c
+    gate1_ptrs = gate1_ptr + batch_idx * stride_g1_b + cols * stride_g1_c
+
+    scale_ptrs = tl.where(idx, scale1_ptrs, scale0_ptrs)
+    shift_ptrs = tl.where(idx, shift1_ptrs, shift0_ptrs)
+    gate_ptrs = tl.where(idx, gate1_ptrs, gate0_ptrs)
+
+    scale = tl.load(scale_ptrs, mask=mask, other=0.0).to(tl.float32)
+    shift = tl.load(shift_ptrs, mask=mask, other=0.0).to(tl.float32)
+    gate = tl.load(gate_ptrs, mask=mask, other=0.0)
+
+    y = x_hat * (1.0 + scale) + shift
+    tl.store(output_ptr + row * stride_out_row + cols, y, mask=mask)
+    tl.store(gate_out_ptr + row * stride_gate_out_row + cols, gate, mask=mask)
+
+
+@triton.jit
+def _residual_layernorm_select01_kernel(
+    output_ptr,
+    residual_out_ptr,
+    gate_out_ptr,
+    x_ptr,
+    residual_ptr,
+    residual_gate_ptr,
+    weight_ptr,
+    bias_ptr,
+    scale0_ptr,
+    shift0_ptr,
+    gate0_ptr,
+    scale1_ptr,
+    shift1_ptr,
+    gate1_ptr,
+    index_ptr,
+    inner_dim,
+    seq_len,
+    stride_x_row,
+    stride_res_row,
+    stride_res_gate_row,
+    stride_out_row,
+    stride_res_out_row,
+    stride_gate_out_row,
+    stride_w,
+    stride_b,
+    stride_s0_b,
+    stride_s0_c,
+    stride_sh0_b,
+    stride_sh0_c,
+    stride_g0_b,
+    stride_g0_c,
+    stride_s1_b,
+    stride_s1_c,
+    stride_sh1_b,
+    stride_sh1_c,
+    stride_g1_b,
+    stride_g1_c,
+    stride_i_b,
+    stride_i_l,
+    eps,
+    has_weight: tl.constexpr,
+    has_bias: tl.constexpr,
+    block_n: tl.constexpr,
+):
+    row = tl.program_id(0)
+    cols = tl.arange(0, block_n)
+    mask = cols < inner_dim
+
+    x = tl.load(x_ptr + row * stride_x_row + cols, mask=mask, other=0.0).to(tl.float32)
+    residual = tl.load(residual_ptr + row * stride_res_row + cols, mask=mask, other=0.0).to(tl.float32)
+    residual_gate = tl.load(
+        residual_gate_ptr + row * stride_res_gate_row + cols,
+        mask=mask,
+        other=0.0,
+    ).to(tl.float32)
+
+    residual_out = residual + residual_gate * x
+    tl.store(residual_out_ptr + row * stride_res_out_row + cols, residual_out, mask=mask)
+
+    mean = tl.sum(residual_out, axis=0) / inner_dim
+    xbar = tl.where(mask, residual_out - mean, 0.0)
+    var = tl.sum(xbar * xbar, axis=0) / inner_dim
+    x_hat = (residual_out - mean) * tl.rsqrt(var + eps)
+
+    if has_weight:
+        weight = tl.load(weight_ptr + cols * stride_w, mask=mask, other=1.0).to(tl.float32)
+        x_hat = x_hat * weight
+    if has_bias:
+        bias = tl.load(bias_ptr + cols * stride_b, mask=mask, other=0.0).to(tl.float32)
+        x_hat = x_hat + bias
+
+    batch_idx = row // seq_len
+    seq_idx = row % seq_len
+    idx = tl.load(index_ptr + batch_idx * stride_i_b + seq_idx * stride_i_l).to(tl.int1)
+
+    scale0_ptrs = scale0_ptr + batch_idx * stride_s0_b + cols * stride_s0_c
+    shift0_ptrs = shift0_ptr + batch_idx * stride_sh0_b + cols * stride_sh0_c
+    gate0_ptrs = gate0_ptr + batch_idx * stride_g0_b + cols * stride_g0_c
+    scale1_ptrs = scale1_ptr + batch_idx * stride_s1_b + cols * stride_s1_c
+    shift1_ptrs = shift1_ptr + batch_idx * stride_sh1_b + cols * stride_sh1_c
+    gate1_ptrs = gate1_ptr + batch_idx * stride_g1_b + cols * stride_g1_c
+
+    scale_ptrs = tl.where(idx, scale1_ptrs, scale0_ptrs)
+    shift_ptrs = tl.where(idx, shift1_ptrs, shift0_ptrs)
+    gate_ptrs = tl.where(idx, gate1_ptrs, gate0_ptrs)
+
+    scale = tl.load(scale_ptrs, mask=mask, other=0.0).to(tl.float32)
+    shift = tl.load(shift_ptrs, mask=mask, other=0.0).to(tl.float32)
+    gate = tl.load(gate_ptrs, mask=mask, other=0.0)
+
+    y = x_hat * (1.0 + scale) + shift
+    tl.store(output_ptr + row * stride_out_row + cols, y, mask=mask)
+    tl.store(gate_out_ptr + row * stride_gate_out_row + cols, gate, mask=mask)
+
+
+def split_select01_mod_params(mod_params: torch.Tensor) -> tuple[torch.Tensor, ...]:
+    shift, scale, gate = mod_params.chunk(3, dim=-1)
+    actual_batch = shift.size(0) // 2
+    if actual_batch == 0 or shift.size(0) != actual_batch * 2:
+        raise ValueError("select01 modulation expects mod_params batch dim to be 2 * batch")
+    return (
+        scale[:actual_batch],
+        shift[:actual_batch],
+        gate[:actual_batch],
+        scale[actual_batch:],
+        shift[actual_batch:],
+        gate[actual_batch:],
+    )
+
+
+def select01_modulation_native(
+    mod_params: torch.Tensor,
+    index: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    scale0, shift0, gate0, scale1, shift1, gate1 = split_select01_mod_params(mod_params)
+    idx = index.to(dtype=torch.bool).unsqueeze(-1)
+    scale = torch.where(idx, scale1.unsqueeze(1), scale0.unsqueeze(1))
+    shift = torch.where(idx, shift1.unsqueeze(1), shift0.unsqueeze(1))
+    gate = torch.where(idx, gate1.unsqueeze(1), gate0.unsqueeze(1))
+    return scale, shift, gate
+
+
+def _validate_select01_inputs(
+    x: torch.Tensor,
+    index: torch.Tensor,
+    tensors: tuple[torch.Tensor, ...],
+) -> None:
+    if x.dim() != 3:
+        raise ValueError("x must be 3D [B, L, C]")
+    if index.dim() != 2 or index.shape[1] != x.shape[1] or index.shape[0] not in (1, x.shape[0]):
+        raise ValueError("index must be 2D [B or 1, L] and match x batch/sequence")
+    batch_size, _, hidden_size = x.shape
+    for tensor in tensors:
+        if tensor.dim() != 2 or tensor.shape != (batch_size, hidden_size):
+            raise ValueError("scale/shift/gate tensors must be 2D [B, C]")
+
+
+def _maybe_contiguous(x: torch.Tensor) -> torch.Tensor:
+    return x if x.is_contiguous() else x.contiguous()
+
+
+def _launch_layernorm_select01(
+    x: torch.Tensor,
+    weight: torch.Tensor | None,
+    bias: torch.Tensor | None,
+    scale0: torch.Tensor,
+    shift0: torch.Tensor,
+    gate0: torch.Tensor,
+    scale1: torch.Tensor,
+    shift1: torch.Tensor,
+    gate1: torch.Tensor,
+    index: torch.Tensor,
+    eps: float,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    _validate_select01_inputs(x, index, (scale0, shift0, gate0, scale1, shift1, gate1))
+    batch_size, seq_len, hidden_size = x.shape
+    output = torch.empty_like(x)
+    gate_out = torch.empty_like(x)
+
+    x_2d = _maybe_contiguous(x).view(batch_size * seq_len, hidden_size)
+    output_2d = output.view(batch_size * seq_len, hidden_size)
+    gate_out_2d = gate_out.view(batch_size * seq_len, hidden_size)
+    index = _maybe_contiguous(index)
+    scale0 = _maybe_contiguous(scale0)
+    shift0 = _maybe_contiguous(shift0)
+    gate0 = _maybe_contiguous(gate0)
+    scale1 = _maybe_contiguous(scale1)
+    shift1 = _maybe_contiguous(shift1)
+    gate1 = _maybe_contiguous(gate1)
+
+    weight_arg = _maybe_contiguous(weight) if weight is not None else x_2d
+    bias_arg = _maybe_contiguous(bias) if bias is not None else x_2d
+    block_n = min(65536 // x_2d.element_size(), triton.next_power_of_2(hidden_size))
+    if hidden_size > block_n:
+        raise RuntimeError("This layer norm doesn't support feature dim >= 64KB.")
+
+    _layernorm_select01_kernel[(batch_size * seq_len,)](
+        output_2d,
+        gate_out_2d,
+        x_2d,
+        weight_arg,
+        bias_arg,
+        scale0,
+        shift0,
+        gate0,
+        scale1,
+        shift1,
+        gate1,
+        index,
+        hidden_size,
+        seq_len,
+        x_2d.stride(0),
+        output_2d.stride(0),
+        gate_out_2d.stride(0),
+        weight_arg.stride(0) if weight is not None else 0,
+        bias_arg.stride(0) if bias is not None else 0,
+        scale0.stride(0),
+        scale0.stride(1),
+        shift0.stride(0),
+        shift0.stride(1),
+        gate0.stride(0),
+        gate0.stride(1),
+        scale1.stride(0),
+        scale1.stride(1),
+        shift1.stride(0),
+        shift1.stride(1),
+        gate1.stride(0),
+        gate1.stride(1),
+        index.stride(0) if index.shape[0] > 1 else 0,
+        index.stride(1),
+        eps,
+        has_weight=weight is not None,
+        has_bias=bias is not None,
+        block_n=block_n,
+        num_warps=4,
+        num_stages=4,
+    )
+    return output, gate_out
+
+
+def _launch_residual_layernorm_select01(
+    x: torch.Tensor,
+    residual: torch.Tensor,
+    residual_gate: torch.Tensor,
+    weight: torch.Tensor | None,
+    bias: torch.Tensor | None,
+    scale0: torch.Tensor,
+    shift0: torch.Tensor,
+    gate0: torch.Tensor,
+    scale1: torch.Tensor,
+    shift1: torch.Tensor,
+    gate1: torch.Tensor,
+    index: torch.Tensor,
+    eps: float,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    _validate_select01_inputs(x, index, (scale0, shift0, gate0, scale1, shift1, gate1))
+    if residual.shape != x.shape:
+        raise ValueError("residual must have the same shape as x")
+    if residual_gate.shape != x.shape:
+        raise ValueError("residual_gate must have the same shape as x")
+
+    batch_size, seq_len, hidden_size = x.shape
+    output = torch.empty_like(x)
+    residual_out = torch.empty_like(x)
+    gate_out = torch.empty_like(x)
+
+    x_2d = _maybe_contiguous(x).view(batch_size * seq_len, hidden_size)
+    residual_2d = _maybe_contiguous(residual).view(batch_size * seq_len, hidden_size)
+    residual_gate_2d = _maybe_contiguous(residual_gate).view(batch_size * seq_len, hidden_size)
+    output_2d = output.view(batch_size * seq_len, hidden_size)
+    residual_out_2d = residual_out.view(batch_size * seq_len, hidden_size)
+    gate_out_2d = gate_out.view(batch_size * seq_len, hidden_size)
+    index = _maybe_contiguous(index)
+    scale0 = _maybe_contiguous(scale0)
+    shift0 = _maybe_contiguous(shift0)
+    gate0 = _maybe_contiguous(gate0)
+    scale1 = _maybe_contiguous(scale1)
+    shift1 = _maybe_contiguous(shift1)
+    gate1 = _maybe_contiguous(gate1)
+
+    weight_arg = _maybe_contiguous(weight) if weight is not None else x_2d
+    bias_arg = _maybe_contiguous(bias) if bias is not None else x_2d
+    block_n = min(65536 // x_2d.element_size(), triton.next_power_of_2(hidden_size))
+    if hidden_size > block_n:
+        raise RuntimeError("This layer norm doesn't support feature dim >= 64KB.")
+
+    _residual_layernorm_select01_kernel[(batch_size * seq_len,)](
+        output_2d,
+        residual_out_2d,
+        gate_out_2d,
+        x_2d,
+        residual_2d,
+        residual_gate_2d,
+        weight_arg,
+        bias_arg,
+        scale0,
+        shift0,
+        gate0,
+        scale1,
+        shift1,
+        gate1,
+        index,
+        hidden_size,
+        seq_len,
+        x_2d.stride(0),
+        residual_2d.stride(0),
+        residual_gate_2d.stride(0),
+        output_2d.stride(0),
+        residual_out_2d.stride(0),
+        gate_out_2d.stride(0),
+        weight_arg.stride(0) if weight is not None else 0,
+        bias_arg.stride(0) if bias is not None else 0,
+        scale0.stride(0),
+        scale0.stride(1),
+        shift0.stride(0),
+        shift0.stride(1),
+        gate0.stride(0),
+        gate0.stride(1),
+        scale1.stride(0),
+        scale1.stride(1),
+        shift1.stride(0),
+        shift1.stride(1),
+        gate1.stride(0),
+        gate1.stride(1),
+        index.stride(0) if index.shape[0] > 1 else 0,
+        index.stride(1),
+        eps,
+        has_weight=weight is not None,
+        has_bias=bias is not None,
+        block_n=block_n,
+        num_warps=4,
+        num_stages=4,
+    )
+    return output, residual_out, gate_out
+
+
+def can_use_qwen_select01_triton(x: torch.Tensor) -> bool:
+    return HAS_TRITON and current_platform.is_cuda() and x.is_cuda
+
+
+def fused_layernorm_select01(
+    x: torch.Tensor,
+    mod_params: torch.Tensor,
+    index: torch.Tensor,
+    eps: float,
+    weight: torch.Tensor | None = None,
+    bias: torch.Tensor | None = None,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    scale0, shift0, gate0, scale1, shift1, gate1 = split_select01_mod_params(mod_params)
+    is_compiling = torch.compiler.is_compiling()
+    if can_use_qwen_select01_triton(x) and not is_compiling:
+        return _launch_layernorm_select01(
+            x,
+            weight,
+            bias,
+            scale0,
+            shift0,
+            gate0,
+            scale1,
+            shift1,
+            gate1,
+            index,
+            eps,
+        )
+
+    scale, shift, gate = select01_modulation_native(mod_params, index)
+    out = F.layer_norm(
+        x.float(),
+        (x.shape[-1],),
+        weight=weight.float() if weight is not None else None,
+        bias=bias.float() if bias is not None else None,
+        eps=eps,
+    ).to(x.dtype)
+    return out * (1 + scale) + shift, gate
+
+
+def fused_residual_layernorm_select01(
+    x: torch.Tensor,
+    residual: torch.Tensor,
+    residual_gate: torch.Tensor,
+    mod_params: torch.Tensor,
+    index: torch.Tensor,
+    eps: float,
+    weight: torch.Tensor | None = None,
+    bias: torch.Tensor | None = None,
+) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+    scale0, shift0, gate0, scale1, shift1, gate1 = split_select01_mod_params(mod_params)
+    is_compiling = torch.compiler.is_compiling()
+    if can_use_qwen_select01_triton(x) and not is_compiling:
+        return _launch_residual_layernorm_select01(
+            x,
+            residual,
+            residual_gate,
+            weight,
+            bias,
+            scale0,
+            shift0,
+            gate0,
+            scale1,
+            shift1,
+            gate1,
+            index,
+            eps,
+        )
+
+    scale, shift, gate = select01_modulation_native(mod_params, index)
+    residual_out = residual + residual_gate * x
+    out = F.layer_norm(
+        residual_out.float(),
+        (residual_out.shape[-1],),
+        weight=weight.float() if weight is not None else None,
+        bias=bias.float() if bias is not None else None,
+        eps=eps,
+    ).to(residual_out.dtype)
+    return out * (1 + scale) + shift, residual_out, gate
diff --git a/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py b/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
index 8e4dac3a304..11568f62c74 100644
--- a/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
+++ b/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from __future__ import annotations
 
@@ -49,6 +49,12 @@
     _fused_cuda_supported,
     fused_qk_norm_rope,
 )
+from vllm_omni.diffusion.layers.qwen_select01_modulation import (
+    can_use_qwen_select01_triton,
+    fused_layernorm_select01,
+    fused_residual_layernorm_select01,
+    select01_modulation_native,
+)
 from vllm_omni.diffusion.layers.rope import RotaryEmbedding
 
 logger = init_logger(__name__)
@@ -855,41 +861,11 @@ def __init__(
 
         self.zero_cond_t = zero_cond_t
 
-    def _modulate(self, mod_params, index=None):
+    def _modulate(self, mod_params):
         """Apply modulation to input tensor"""
         # shift: b d, scale: b d, gate: b d
         shift, scale, gate = mod_params.chunk(3, dim=-1)
-
-        if index is not None:
-            # Assuming mod_params batch dim is 2*actual_batch (chunked into 2 parts)
-            # So shift, scale, gate have shape [2*actual_batch, d]
-            actual_batch = shift.size(0) // 2
-            shift_0, shift_1 = shift[:actual_batch], shift[actual_batch:]  # each: [actual_batch, d]
-            scale_0, scale_1 = scale[:actual_batch], scale[actual_batch:]
-            gate_0, gate_1 = gate[:actual_batch], gate[actual_batch:]
-
-            # index: [b, l] where b is actual batch size
-            # Expand to [b, l, 1] to match feature dimension
-            index_expanded = index.unsqueeze(-1)  # [b, l, 1]
-
-            # Expand chunks to [b, 1, d] then broadcast to [b, l, d]
-            shift_0_exp = shift_0.unsqueeze(1)  # [b, 1, d]
-            shift_1_exp = shift_1.unsqueeze(1)  # [b, 1, d]
-            scale_0_exp = scale_0.unsqueeze(1)
-            scale_1_exp = scale_1.unsqueeze(1)
-            gate_0_exp = gate_0.unsqueeze(1)
-            gate_1_exp = gate_1.unsqueeze(1)
-
-            # Use torch.where to select based on index
-            shift_result = torch.where(index_expanded == 0, shift_0_exp, shift_1_exp)
-            scale_result = torch.where(index_expanded == 0, scale_0_exp, scale_1_exp)
-            gate_result = torch.where(index_expanded == 0, gate_0_exp, gate_1_exp)
-        else:
-            shift_result = shift.unsqueeze(1)
-            scale_result = scale.unsqueeze(1)
-            gate_result = gate.unsqueeze(1)
-
-        return scale_result, shift_result, gate_result
+        return scale.unsqueeze(1), shift.unsqueeze(1), gate.unsqueeze(1)
 
     def forward(
         self,
@@ -915,8 +891,22 @@ def forward(
         txt_mod1, txt_mod2 = txt_mod_params.chunk(2, dim=-1)  # Each [B, 3*dim]
 
         # Process image stream - norm1 + modulation
-        img_scale1, img_shift1, img_gate1 = self._modulate(img_mod1, modulate_index)
-        img_modulated = self.img_norm1(hidden_states, img_scale1, img_shift1)
+        use_fused_select01 = modulate_index is not None and can_use_qwen_select01_triton(hidden_states)
+        if use_fused_select01:
+            img_modulated, img_gate1 = fused_layernorm_select01(
+                hidden_states,
+                img_mod1,
+                modulate_index,
+                self.img_norm1.eps,
+                self.img_norm1.layernorm.weight,
+                self.img_norm1.layernorm.bias,
+            )
+        elif modulate_index is not None:
+            img_scale1, img_shift1, img_gate1 = select01_modulation_native(img_mod1, modulate_index)
+            img_modulated = self.img_norm1(hidden_states, img_scale1, img_shift1)
+        else:
+            img_scale1, img_shift1, img_gate1 = self._modulate(img_mod1)
+            img_modulated = self.img_norm1(hidden_states, img_scale1, img_shift1)
 
         # Process text stream - norm1 + modulation
         txt_scale1, txt_shift1, txt_gate1 = self._modulate(txt_mod1)
@@ -941,12 +931,29 @@ def forward(
         img_attn_output, txt_attn_output = attn_output
 
         # Apply attention gates and add residual (like in Megatron)
-        hidden_states = hidden_states + img_gate1 * img_attn_output
+        hidden_states_before_attn = hidden_states
+        if not use_fused_select01:
+            hidden_states = hidden_states + img_gate1 * img_attn_output
         encoder_hidden_states = encoder_hidden_states + txt_gate1 * txt_attn_output
 
         # Process image stream - norm2 + MLP
-        img_scale2, img_shift2, img_gate2 = self._modulate(img_mod2, modulate_index)
-        img_modulated2 = self.img_norm2(hidden_states, img_scale2, img_shift2)
+        if use_fused_select01:
+            img_modulated2, hidden_states, img_gate2 = fused_residual_layernorm_select01(
+                img_attn_output,
+                hidden_states_before_attn,
+                img_gate1,
+                img_mod2,
+                modulate_index,
+                self.img_norm2.eps,
+                self.img_norm2.layernorm.weight,
+                self.img_norm2.layernorm.bias,
+            )
+        elif modulate_index is not None:
+            img_scale2, img_shift2, img_gate2 = select01_modulation_native(img_mod2, modulate_index)
+            img_modulated2 = self.img_norm2(hidden_states, img_scale2, img_shift2)
+        else:
+            img_scale2, img_shift2, img_gate2 = self._modulate(img_mod2)
+            img_modulated2 = self.img_norm2(hidden_states, img_scale2, img_shift2)
 
         img_mlp_output = self.img_mlp(img_modulated2)
         hidden_states = hidden_states + img_gate2 * img_mlp_output

From e6cebf8557c29f965399a931d85c4615cd86fc12 Mon Sep 17 00:00:00 2001
From: RyanYun09 <ryanyun0911@gmail.com>
Date: Wed, 16 Sep 2026 20:05:52 +0800
Subject: [PATCH 034/105] [Bugfix][Omni-DuplexEval] Load local Hugging Face
 dataset layouts in duplex eval loader (#7331)

Signed-off-by: RyanYun09 <RyanYun09@users.noreply.github.com>
Co-authored-by: RyanYun09 <RyanYun09@users.noreply.github.com>
Co-authored-by: amy-why-3459 <wuhaiyan17@huawei.com>
---
 .../duplex/test_omni_duplex_eval.py           | 281 ++++++++++++++++++
 .../duplex/test_omni_duplex_eval_media.py     |  67 +++++
 .../duplex/omni_duplex_eval_dataset.py        | 264 ++++++++++++++--
 .../duplex/omni_duplex_eval_media.py          |  57 +++-
 .../cli/benchmark/omni_duplex_eval.py         |  26 +-
 5 files changed, 658 insertions(+), 37 deletions(-)
 create mode 100644 tests/benchmarks/duplex/test_omni_duplex_eval_media.py

diff --git a/tests/benchmarks/duplex/test_omni_duplex_eval.py b/tests/benchmarks/duplex/test_omni_duplex_eval.py
index 5f77aacc0c7..f5d3ebcd808 100644
--- a/tests/benchmarks/duplex/test_omni_duplex_eval.py
+++ b/tests/benchmarks/duplex/test_omni_duplex_eval.py
@@ -64,6 +64,177 @@ def fake_load_dataset(name, **kwargs):
     assert sample.task_type == "correction"
 
 
+def test_local_hf_dataset_directory_is_routed_to_hf_loader(tmp_path, monkeypatch):
+    # An existing local Hugging Face dataset layout (directory with a
+    # ``data/*.parquet`` file) must be loaded through ``datasets.load_dataset``
+    # instead of being parsed as a JSON/JSONL manifest.
+    hf_dir = tmp_path / "Omni-DuplexEval"
+    data_dir = hf_dir / "data"
+    data_dir.mkdir(parents=True)
+    (data_dir / "train-00000-of-00001.parquet").write_bytes(b"PAR1")
+    calls = []
+
+    def fake_load_dataset(name, **kwargs):
+        calls.append((name, kwargs))
+        return [{"id": "pr", "split": "PR_correction", "question_text": "Correct this."}]
+
+    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
+    samples = load_samples(hf_dir)
+    assert calls == [(str(hf_dir), {})]
+    assert len(samples) == 1
+    assert samples[0].task_type == "correction"
+
+
+def test_local_parquet_file_is_routed_to_hf_loader(tmp_path, monkeypatch):
+    parquet = tmp_path / "samples.parquet"
+    parquet.write_bytes(b"PAR1")
+    calls = []
+
+    def fake_load_dataset(name, **kwargs):
+        calls.append((name, kwargs))
+        return [{"id": "pr", "split": "PR_correction", "question_text": "Correct this."}]
+
+    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
+    samples = load_samples(str(parquet))
+    assert calls == [("parquet", {"data_files": str(parquet)})]
+    assert len(samples) == 1
+    assert samples[0].family == "pr"
+
+
+def test_hf_collapse_to_train_keeps_row_split_identity(tmp_path, monkeypatch):
+    # datasets.load_dataset collapses a config-less local mirror (a bare data/
+    # directory) into a single generic ``train`` split. Rows that already carry
+    # their own split/subset identity must keep it so family inference is not
+    # poisoned by the generic name (regression for the direct-read path).
+    hf_dir = tmp_path / "Omni-DuplexEval"
+    data_dir = hf_dir / "data"
+    data_dir.mkdir(parents=True)
+    (data_dir / "train-00000-of-00021.parquet").write_bytes(b"PAR1")
+
+    def fake_load_dataset(name, **kwargs):
+        return {
+            "train": [
+                {"id": "pr", "split": "PR_correction", "question_text": "Correct this."},
+                {"id": "pr-subset", "subset": "PR_event_reminder", "question_text": "Remind me."},
+                {"id": "rtd", "split": "RTD_OCR", "question_text": "Read this."},
+            ]
+        }
+
+    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
+    samples = load_samples(hf_dir)
+    by_id = {sample.id: sample for sample in samples}
+    assert by_id["pr"].split == "PR_correction"
+    assert by_id["pr"].family == "pr"
+    assert by_id["pr"].task_type == "correction"
+    assert by_id["pr-subset"].split == "PR_event_reminder"
+    assert by_id["pr-subset"].family == "pr"
+    assert by_id["pr-subset"].task_type == "proactive_reminder"
+    assert by_id["rtd"].split == "RTD_OCR"
+    assert by_id["rtd"].family == "rtd"
+
+
+def test_hf_config_layout_stamps_split_name_when_row_has_none(tmp_path, monkeypatch):
+    # With a proper config-per-split mirror the loader still stamps the Hugging
+    # Face split name onto rows that do not identify themselves (unchanged).
+    hf_dir = tmp_path / "Omni-DuplexEval"
+    data_dir = hf_dir / "data"
+    data_dir.mkdir(parents=True)
+    (data_dir / "RTD_OCR-00000-of-00001.parquet").write_bytes(b"PAR1")
+    (data_dir / "PR_correction-00000-of-00001.parquet").write_bytes(b"PAR1")
+
+    def fake_load_dataset(name, **kwargs):
+        return {
+            "RTD_OCR": [{"id": "rtd", "question_text": "Read this."}],
+            "PR_correction": [{"id": "pr", "question_text": "Correct this."}],
+        }
+
+    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
+    samples = load_samples(hf_dir)
+    by_id = {sample.id: sample for sample in samples}
+    assert by_id["rtd"].split == "RTD_OCR"
+    assert by_id["rtd"].family == "rtd"
+    assert by_id["pr"].split == "PR_correction"
+    assert by_id["pr"].family == "pr"
+    assert by_id["pr"].task_type == "correction"
+
+
+def test_hf_collapse_to_train_without_row_identity_raises_actionable_error(tmp_path, monkeypatch):
+    # A row that carries no split/family/task_type and lands in a generic
+    # collapsed ``train`` split cannot be routed; the loader must raise a clear,
+    # actionable ValueError instead of the bare family_for_split message.
+    hf_dir = tmp_path / "Omni-DuplexEval"
+    data_dir = hf_dir / "data"
+    data_dir.mkdir(parents=True)
+    (data_dir / "train-00000-of-00021.parquet").write_bytes(b"PAR1")
+
+    def fake_load_dataset(name, **kwargs):
+        return {"train": [{"id": "x", "question_text": "What is this?"}]}
+
+    monkeypatch.setitem(sys.modules, "datasets", SimpleNamespace(load_dataset=fake_load_dataset))
+    with pytest.raises(ValueError, match="Hugging Face splits"):
+        load_samples(hf_dir)
+
+
+def test_non_manifest_file_raises_clear_error(tmp_path):
+    # A plain non-JSON file (e.g. a README) must surface a clear ValueError
+    # listing the accepted inputs instead of a raw JSONDecodeError.
+    bad = tmp_path / "README.md"
+    bad.write_text("# readme\nnot a manifest", encoding="utf-8")
+    with pytest.raises(ValueError, match="JSON/JSONL manifest"):
+        load_samples(str(bad))
+
+
+def _write_parquet(path, rows):
+    pyarrow = pytest.importorskip("pyarrow")
+    pyarrow.parquet.write_table(pyarrow.Table.from_pylist(rows), str(path))
+
+
+def test_local_parquet_split_filters_rows_by_identity(tmp_path):
+    # Regression: a single ``.parquet`` file is exposed by ``load_dataset`` as a
+    # generic ``train`` physical split, so ``--split RTD_OCR`` used to raise
+    # ``Unknown split "RTD_OCR"``. The requested split must instead filter the
+    # rows by their preserved identity.
+    pytest.importorskip("datasets")
+    parquet = tmp_path / "samples.parquet"
+    _write_parquet(
+        parquet,
+        [
+            {"id": "rtd", "split": "RTD_OCR", "question_text": "Read this."},
+            {"id": "pr", "split": "PR_correction", "question_text": "Correct this."},
+        ],
+    )
+    assert {sample.id for sample in load_samples(str(parquet))} == {"rtd", "pr"}
+    rtd = load_samples(str(parquet), split="RTD_OCR")
+    assert [sample.id for sample in rtd] == ["rtd"]
+    assert rtd[0].family == "rtd"
+    pr = load_samples(str(parquet), split="PR_correction")
+    assert [sample.id for sample in pr] == ["pr"]
+    assert pr[0].family == "pr"
+    assert pr[0].task_type == "correction"
+
+
+def test_local_directory_named_splits_resolve_without_row_identity(tmp_path):
+    # Regression: a single-configuration mirror whose data files are named after
+    # the benchmark splits must resolve each split for real (no fake loader) and
+    # without any per-row identity.
+    pytest.importorskip("datasets")
+    hf_dir = tmp_path / "Omni-DuplexEval"
+    data_dir = hf_dir / "data"
+    data_dir.mkdir(parents=True)
+    _write_parquet(data_dir / "RTD_OCR-00000-of-00001.parquet", [{"id": "rtd", "question_text": "Read this."}])
+    _write_parquet(
+        data_dir / "PR_correction-00000-of-00001.parquet",
+        [{"id": "pr", "question_text": "Correct this."}],
+    )
+    by_id = {sample.id: sample for sample in load_samples(hf_dir)}
+    assert by_id["rtd"].split == "RTD_OCR"
+    assert by_id["rtd"].family == "rtd"
+    assert by_id["pr"].split == "PR_correction"
+    assert by_id["pr"].family == "pr"
+    assert by_id["pr"].task_type == "correction"
+    assert [sample.id for sample in load_samples(hf_dir, split="RTD_OCR")] == ["rtd"]
+
+
 def test_response_aliases_and_clock_guard():
     assert split_text("One. Two!") == ["One.", "Two!"]
     assert normalize_response_items({"chunks": [{"text": "x", "current_time": 800}]}) == [
@@ -141,3 +312,113 @@ def content(self, prompt, video, frames=None, *, mode="video_url"):
         judge_video_mode="frame-sample",
     )
     assert score["content"]["frame_count"] == 2
+
+
+def test_local_directory_collapsed_train_with_row_identity_and_split_filter(tmp_path):
+    # Reviewer-pointed gap: a collapsed local mirror (data/train-*.parquet)
+    # whose rows carry their own split identity must correctly filter by
+    # --split RTD_OCR.
+    pytest.importorskip("datasets")
+    hf_dir = tmp_path / "Omni-DuplexEval"
+    data_dir = hf_dir / "data"
+    data_dir.mkdir(parents=True)
+    _write_parquet(
+        data_dir / "train-00000-of-00001.parquet",
+        [
+            {"id": "rtd", "split": "RTD_OCR", "question_text": "Read this."},
+            {"id": "pr", "split": "PR_correction", "question_text": "Correct this."},
+        ],
+    )
+    all_samples = load_samples(hf_dir)
+    assert {s.id for s in all_samples} == {"rtd", "pr"}
+    rtd = load_samples(hf_dir, split="RTD_OCR")
+    assert [s.id for s in rtd] == ["rtd"]
+    assert rtd[0].family == "rtd"
+
+
+def test_local_directory_mistyped_split_raises_clear_error(tmp_path):
+    # A named-shard mirror with --split RTD_TYPO must raise ValueError
+    # listing the observed splits instead of silently returning nothing.
+    pytest.importorskip("datasets")
+    hf_dir = tmp_path / "Omni-DuplexEval"
+    data_dir = hf_dir / "data"
+    data_dir.mkdir(parents=True)
+    _write_parquet(
+        data_dir / "RTD_OCR-00000-of-00001.parquet",
+        [{"id": "rtd", "question_text": "Read this."}],
+    )
+    _write_parquet(
+        data_dir / "PR_correction-00000-of-00001.parquet",
+        [{"id": "pr", "question_text": "Correct this."}],
+    )
+    with pytest.raises(ValueError) as exc_info:
+        load_samples(hf_dir, split="RTD_TYPO")
+    message = str(exc_info.value)
+    assert "matched zero" in message
+    assert "RTD_OCR" in message or "PR_correction" in message
+
+
+def test_manifest_without_split_identity_split_override_still_works(tmp_path):
+    # Manifest rows without split/subset/config identity must keep the
+    # base override behaviour: --split RTD_OCR stamps the split so rows
+    # are kept instead of rejected (regression test for P2).
+    manifest = tmp_path / "samples.json"
+    manifest.write_text(
+        json.dumps([{"id": "a", "video": "clip.mp4"}, {"id": "b", "video": "clip2.mp4"}]),
+        encoding="utf-8",
+    )
+    samples = load_samples(manifest, split="RTD_OCR")
+    assert len(samples) == 2
+    assert all(s.split == "RTD_OCR" for s in samples)
+    assert all(s.family == "rtd" for s in samples)
+
+
+def test_iterable_without_split_identity_split_override_still_works():
+    # Iterable rows without split/subset/config identity must keep the
+    # base override behaviour (regression test for F5/P2).
+    data = [{"id": "a", "video": "clip.mp4"}, {"id": "b", "video": "clip2.mp4"}]
+    samples = load_samples(data, split="RTD_OCR")
+    assert len(samples) == 2
+    assert all(s.split == "RTD_OCR" for s in samples)
+    assert all(s.family == "rtd" for s in samples)
+
+
+def test_audio_feature_decode_false_preserves_bytes_key(tmp_path):
+    # When a parquet file carries an Audio feature column, the loader
+    # must recast it with decode=False so rows contain the ``bytes`` key
+    # instead of ``array``/``sampling_rate``.
+    pytest.importorskip("datasets")
+    pytest.importorskip("pyarrow")
+    import datasets
+
+    audio_bytes = b"\x00\x01\x02"
+    ds = datasets.Dataset.from_dict(
+        {
+            "id": ["a"],
+            "question_text": ["Hello"],
+            "task_type": ["pr_correction"],
+            "audio": [{"bytes": audio_bytes, "path": None}],
+        },
+        features=datasets.Features(
+            {
+                "id": datasets.Value("string"),
+                "question_text": datasets.Value("string"),
+                "task_type": datasets.Value("string"),
+                "audio": datasets.Audio(sampling_rate=16000),
+            }
+        ),
+    )
+    parquet = tmp_path / "audio_sample.parquet"
+    ds.to_parquet(str(parquet))
+
+    samples = load_samples(str(parquet))
+    assert len(samples) == 1
+    raw = samples[0].raw
+    assert raw is not None
+    audio_val = raw.get("audio")
+    assert audio_val is not None
+    # The Audio feature was decoded with decode=False, so the struct
+    # keeps the ``bytes`` key that materialize_media needs.
+    assert isinstance(audio_val, dict) and "bytes" in audio_val
+    assert audio_val["bytes"] == audio_bytes
+    assert "path" in audio_val
diff --git a/tests/benchmarks/duplex/test_omni_duplex_eval_media.py b/tests/benchmarks/duplex/test_omni_duplex_eval_media.py
new file mode 100644
index 00000000000..28a502428a4
--- /dev/null
+++ b/tests/benchmarks/duplex/test_omni_duplex_eval_media.py
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import pytest
+
+from vllm_omni.benchmarks.duplex.omni_duplex_eval_media import materialize_media
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_dict_with_bytes_materializes_a_real_file(tmp_path):
+    # A Hugging Face Audio/Video feature value {"bytes": ..., "path": ...} used
+    # to short-circuit on ``path`` (the artifact name inside the dataset, which
+    # does not exist on disk), so downstream ffmpeg saw a missing file. Inline
+    # bytes must win and be written to a real file whose content equals bytes.
+    payload = b"\x00\xff\x01RIFFfake-content"
+    resolved = materialize_media({"bytes": payload, "path": "question_audio.wav"}, tmp_path, "s1_question", ".wav")
+    assert resolved.is_file()
+    assert resolved.read_bytes() == payload
+    assert resolved.parent == tmp_path
+    assert resolved.name == "s1_question.wav"
+
+
+def test_dict_extension_comes_from_path_safely(tmp_path):
+    payload = b"flac-ish-bytes"
+    resolved = materialize_media({"bytes": payload, "path": "audio/clip.FLAC"}, tmp_path, "s1", ".wav")
+    assert resolved.name == "s1.flac"
+    assert resolved.read_bytes() == payload
+    # A path with no usable extension falls back to the caller's suffix.
+    resolved = materialize_media({"bytes": payload, "path": "audio/clip"}, tmp_path, "s2", ".wav")
+    assert resolved.name == "s2.wav"
+    assert resolved.read_bytes() == payload
+
+
+def test_materialization_is_idempotent_and_updated(tmp_path):
+    payload = b"abc"
+    first = materialize_media({"bytes": payload, "path": "q.wav"}, tmp_path, "s", ".wav")
+    second = materialize_media({"bytes": payload, "path": "q.wav"}, tmp_path, "s", ".wav")
+    assert first == second
+    assert first.read_bytes() == payload
+    replacement = b"xyz"
+    third = materialize_media({"bytes": replacement, "path": "q.wav"}, tmp_path, "s", ".wav")
+    assert third == first
+    assert third.read_bytes() == replacement
+
+
+def test_str_path_and_path_only_mapping_returned_as_is(tmp_path):
+    existing = tmp_path / "clip.mp4"
+    existing.write_bytes(b"video")
+    assert materialize_media(str(existing), tmp_path, "s", ".mp4") == existing
+    assert materialize_media({"path": str(existing)}, tmp_path, "s", ".mp4") == existing
+
+
+def test_raw_bytes_value_is_written(tmp_path):
+    payload = b"raw-media"
+    resolved = materialize_media(payload, tmp_path, "r", ".bin")
+    assert resolved.name == "r.bin"
+    assert resolved.read_bytes() == payload
+
+
+def test_unresolvable_value_raises_clear_error(tmp_path):
+    with pytest.raises(ValueError, match="cannot materialize"):
+        materialize_media(None, tmp_path, "s", ".wav")
+    with pytest.raises(ValueError, match="cannot materialize"):
+        materialize_media({"path": None}, tmp_path, "s", ".wav")
diff --git a/vllm_omni/benchmarks/duplex/omni_duplex_eval_dataset.py b/vllm_omni/benchmarks/duplex/omni_duplex_eval_dataset.py
index 9d6013e80e4..349d80fc368 100644
--- a/vllm_omni/benchmarks/duplex/omni_duplex_eval_dataset.py
+++ b/vllm_omni/benchmarks/duplex/omni_duplex_eval_dataset.py
@@ -3,15 +3,36 @@
 
 """Dataset and split normalization for Omni-DuplexEval.
 
-The loader accepts a Hugging Face dataset id, a JSON/JSONL manifest, or an
+The loader accepts a Hugging Face dataset id, a local Hugging Face dataset
+layout (a directory or a ``.parquet`` file), a JSON/JSONL manifest, or an
 already materialized iterable.  Media is deliberately resolved at use time so
 the benchmark remains usable in air-gapped environments.
+
+Local directory mirrors are expected to use a *single* Hugging Face
+configuration whose data files are named after the benchmark splits
+(``data/<SPLIT>-00000-of-00001.parquet``, with ``<SPLIT>`` one of the RTD_*/PR_*
+names), so ``datasets.load_dataset`` exposes one physical split per benchmark
+split.  A single ``.parquet`` file and a mirror that Hugging Face collapses into
+a generic ``train`` split are also accepted, but then the requested ``split`` is
+applied as a filter on each row's preserved ``split``/``subset``/``config``
+identity instead of as a physical split name.  Rows that identify neither their
+split nor their family/task raise a clear error that explains the required
+layout.
+
+A requested ``split`` that matches zero rows (for example a mistyped name) is
+reported loudly: :func:`load_samples` raises a ``ValueError`` that lists the
+split identities actually observed in the loaded rows instead of silently
+returning an empty selection.  Rows coming from a JSON/JSONL manifest or an
+already materialized iterable that carry no split/subset/config identity keep
+the base override behavior: ``--split`` is stamped onto them so they are kept
+rather than rejected.
 """
 
 from __future__ import annotations
 
+import importlib
 import json
-from collections.abc import Iterable
+from collections.abc import Callable, Iterable
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -68,6 +89,23 @@ def family_for_split(split: str, task_type: str | None = None) -> str:
     raise ValueError(f"cannot infer benchmark family from split {split!r}")
 
 
+def _identity_error(split: str, sample_id: str, *, family: bool) -> str:
+    """Build an actionable error for a row whose family/task cannot be derived."""
+    subject = "family" if family else "proactive-reminder task type"
+    label = f" for sample {sample_id!r}" if sample_id else ""
+    detail = (
+        "the split is not an RTD_*/PR_* name and no per-row 'task_type' is present"
+        if family
+        else "no per-row 'task_type' is present"
+    )
+    return (
+        f"cannot infer the Omni-DuplexEval {subject}{label} from split {split!r}: {detail}. "
+        "Load a local Omni-DuplexEval mirror whose data files are named after the "
+        "Hugging Face splits (RTD_*/PR_*) or add per-row "
+        "'family'/'task_type'/'split' columns."
+    )
+
+
 def _value(row: dict[str, Any], *keys: str, default: Any = None) -> Any:
     for key in keys:
         if key in row and row[key] is not None:
@@ -100,14 +138,27 @@ class DuplexSample:
     raw: dict[str, Any] | None = None
 
     @classmethod
-    def from_row(cls, row: dict[str, Any], *, split: str | None = None, media_root: Path | None = None) -> DuplexSample:
-        chosen_split = str(split or _value(row, "split", "subset", "config", default=""))
+    def from_row(cls, row: dict[str, Any], *, media_root: Path | None = None) -> DuplexSample:
+        chosen_split = str(_value(row, "split", "subset", "config", default=""))
+        sample_id = str(_value(row, "id", "sample_id", "uid", "name", default=""))
         task_value = _value(row, "task_type", "task", "type")
-        family = str(_value(row, "family", default="") or family_for_split(chosen_split, task_value))
+        family_value = _value(row, "family", default="")
+        if family_value:
+            family = str(family_value)
+        else:
+            try:
+                family = family_for_split(chosen_split, task_value)
+            except ValueError as exc:
+                raise ValueError(_identity_error(chosen_split, sample_id, family=True)) from exc
         task = None
         if family == "pr":
-            task = canonical_task_type(str(task_value)) if task_value else task_type_for_split(chosen_split)
-        sample_id = str(_value(row, "id", "sample_id", "uid", "name", default=""))
+            if task_value:
+                task = canonical_task_type(str(task_value))
+            else:
+                try:
+                    task = task_type_for_split(chosen_split)
+                except ValueError as exc:
+                    raise ValueError(_identity_error(chosen_split, sample_id, family=False)) from exc
         video = _value(row, "video", "video_path", "video_file")
         audio = _value(row, "question_audio", "audio", "question_wav")
         if media_root:
@@ -148,6 +199,150 @@ def _read_manifest(path: Path) -> list[dict[str, Any]]:
     return payload
 
 
+def _has_split_identity(row: dict[str, Any]) -> bool:
+    """Whether a row already identifies the benchmark split it belongs to."""
+    return any(row.get(key) for key in ("split", "subset", "config"))
+
+
+def _stamp_split(rows: Iterable[dict[str, Any]], name: str) -> list[dict[str, Any]]:
+    """Stamp a physical Hugging Face split name onto rows that lack identity.
+
+    Hugging Face collapses a config-less local mirror (a bare ``data/``
+    directory) or a single ``.parquet`` file into a single generic split
+    (``train``).  A row's own split identity (``split``/``subset``/``config``)
+    must win so family inference is not poisoned by that generic name; the
+    physical split name is only stamped when the row does not identify itself.
+    """
+    stamped: list[dict[str, Any]] = []
+    for row in rows:
+        item = dict(row)
+        if name and not _has_split_identity(item):
+            item["split"] = name
+        stamped.append(item)
+    return stamped
+
+
+def _override_split(rows: list[dict[str, Any]], split: str | None) -> list[dict[str, Any]]:
+    """Apply the base split-override semantics to manifest/iterable rows.
+
+    Rows that lack split/subset/config identity are stamped with the requested
+    split so they are kept, matching the pre-override behavior; rows that
+    already carry identity are left untouched so the requested split stays a
+    filter. Copies are returned, never mutating the caller's original dicts.
+    """
+    if not split or split == "all":
+        return rows
+    return [row if _has_split_identity(row) else {**row, "split": split} for row in rows]
+
+
+def _recast_media_features(loaded: Any) -> Any:
+    """Recast Audio/Video features to decode=False so rows carry {bytes, path}.
+
+    Hugging Face ``Audio``/``Video`` features default to ``decode=True``,
+    producing ``{"array", "path", "sampling_rate"}`` dicts without the
+    ``bytes`` key that :func:`materialize_media` needs. ``decode=False`` keeps
+    the raw parquet struct instead. Must run before row iteration
+    (``cast_column`` is lazy; decoding happens at row access).
+    """
+    try:
+        features_mod = importlib.import_module("datasets.features")
+    except ImportError:
+        return loaded
+    audio_cls = getattr(features_mod, "Audio", None)
+    video_cls = getattr(features_mod, "Video", None)
+    if audio_cls is None:
+        return loaded
+
+    if isinstance(loaded, dict):
+        # A DatasetDict -- or a plain dict returned by a fake loader whose
+        # values are lists -- recurses one level and is returned untouched by
+        # the features guard below.
+        return {name: _recast_media_features(table) for name, table in loaded.items()}
+
+    feats = getattr(loaded, "features", None)
+    if feats is None:
+        return loaded
+    for column, feature in feats.items():
+        if isinstance(feature, audio_cls):
+            loaded = loaded.cast_column(column, audio_cls(decode=False))
+        elif video_cls is not None and isinstance(feature, video_cls):
+            loaded = loaded.cast_column(column, video_cls(decode=False))
+    return loaded
+
+
+def _read_hf(load_dataset: Callable[..., Any], dataset: str, want: str | None) -> Any:
+    """Call ``datasets.load_dataset`` for a local layout or a remote id.
+
+    The physical split is only requested when one was asked for; ``datasets``
+    then returns a single ``Dataset`` (an iterable of rows) instead of a
+    ``DatasetDict`` (a mapping of split name to such an iterable). The result is
+    normalized by :func:`_rows_from_hf`.
+    """
+    if Path(dataset).suffix.lower() == ".parquet":
+        # A single parquet file is always exposed as one generic ``train``
+        # split; the logical benchmark split is filtered from row identity
+        # afterwards. The ``want`` branch was unreachable (the only call site
+        # passes ``None``) and implied physical split support that does not
+        # exist, so it was removed.
+        return load_dataset("parquet", data_files=dataset)
+    if want:
+        return load_dataset(dataset, split=want)
+    return load_dataset(dataset)
+
+
+def _rows_from_hf(dataset: str, *, split: str | None) -> list[dict[str, Any]]:
+    """Load rows from a Hugging Face dataset id or a local dataset layout.
+
+    ``datasets.load_dataset`` accepts a remote id, a local dataset directory
+    (``data/<SPLIT>-00000-of-00001.parquet``) and, via the ``parquet`` builder,
+    a single ``.parquet`` file, which keeps the benchmark usable offline with a
+    locally mirrored copy of the dataset.
+
+    The logical benchmark split (``RTD_OCR``, ``PR_correction``, ...) is not
+    forwarded blindly as a physical Hugging Face split: a single ``.parquet``
+    file and a collapsed local mirror only expose a generic ``train`` split, so
+    passing the logical name there raises ``Unknown split``.  The physical
+    dataset is loaded instead and the requested split is applied later, on the
+    preserved per-row identity (see :func:`load_samples`).
+    """
+    try:
+        from datasets import load_dataset
+    except ImportError as exc:
+        raise RuntimeError(
+            "datasets is required to load a Hugging Face dataset id or a local "
+            "dataset directory/parquet file; use a local JSON/JSONL manifest instead"
+        ) from exc
+
+    requested = split if split and split != "all" else None
+    is_local = Path(dataset).exists()
+    if Path(dataset).suffix.lower() == ".parquet":
+        # A single parquet file is always exposed as one generic ``train``
+        # split; the logical benchmark split is filtered from row identity
+        # afterwards rather than forwarded as a physical split name.
+        loaded = _read_hf(load_dataset, dataset, None)
+    else:
+        try:
+            loaded = _read_hf(load_dataset, dataset, requested)
+        except ValueError as exc:
+            # A collapsed *local* mirror (bare ``data/`` directory) does not
+            # expose the logical split as a physical Hugging Face split; fall
+            # back to the whole physical dataset and filter by row identity.
+            # A remote id keeps the original error so a mistyped split still
+            # fails loudly instead of silently selecting nothing.
+            if not is_local or requested is None or "Unknown split" not in str(exc):
+                raise
+            loaded = _read_hf(load_dataset, dataset, None)
+            requested = None
+
+    loaded = _recast_media_features(loaded)
+    if isinstance(loaded, dict):
+        rows: list[dict[str, Any]] = []
+        for name, table in loaded.items():
+            rows.extend(_stamp_split((dict(row) for row in table), name))
+        return rows
+    return _stamp_split((dict(row) for row in loaded), requested or "")
+
+
 def load_samples(
     dataset: str | Path | Iterable[dict[str, Any]] = DEFAULT_DATASET,
     *,
@@ -157,37 +352,54 @@ def load_samples(
     limit: int | None = None,
     ids: Iterable[str] | None = None,
 ) -> list[DuplexSample]:
-    if isinstance(dataset, (str, Path)) and Path(str(dataset)).exists():
-        rows = _read_manifest(Path(str(dataset)))
-    elif not isinstance(dataset, (str, Path)):
-        rows = list(dataset)
-    else:
-        try:
-            from datasets import load_dataset
-        except ImportError as exc:
-            raise RuntimeError("datasets is required for Hugging Face loading; use a local manifest instead") from exc
-        kwargs: dict[str, Any] = {}
-        if split and split != "all":
-            kwargs["split"] = split
-        loaded = load_dataset(str(dataset), **kwargs)
-        if isinstance(loaded, dict):
-            rows = []
-            for name, table in loaded.items():
-                rows.extend({**dict(row), "split": name} for row in table)
+    if isinstance(dataset, str | Path):
+        path = Path(str(dataset))
+        if path.exists():
+            # A directory or a ``.parquet`` file is a Hugging Face dataset
+            # layout (e.g. a locally mirrored Omni-DuplexEval snapshot); only
+            # single JSON/JSONL files are parsed as manifests.  Routing by path
+            # shape instead of mere existence lets local Hugging Face datasets
+            # load through ``datasets.load_dataset``.
+            if path.is_dir() or path.suffix.lower() == ".parquet":
+                rows = _rows_from_hf(str(path), split=split)
+            else:
+                try:
+                    rows = _override_split(_read_manifest(path), split)
+                except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+                    raise ValueError(
+                        f"cannot load dataset from {str(path)!r}: expected a "
+                        "JSON/JSONL manifest file, a local Hugging Face dataset "
+                        "directory, or a single .parquet file"
+                    ) from exc
         else:
-            rows = [dict(row) for row in loaded]
+            rows = _rows_from_hf(str(dataset), split=split)
+    else:
+        rows = _override_split(list(dataset), split)
     wanted = set(str(item) for item in ids) if ids else None
     root = Path(media_root).expanduser() if media_root else None
     result = []
+    split_matched = 0
     for row in rows:
-        sample = DuplexSample.from_row(row, split=None if split in (None, "all") else split, media_root=root)
+        # The requested split is a *filter* over each row's own split identity;
+        # never pass it as an override, which would relabel every row as the
+        # requested split (turning a collapsed local dataset into a full match
+        # instead of a filter).
+        sample = DuplexSample.from_row(row, media_root=root)
         if split and split != "all" and sample.split != split:
             continue
+        split_matched += 1
         if family != "all" and sample.family != family:
             continue
         if wanted is not None and sample.id not in wanted:
             continue
         result.append(sample)
+    if split and split != "all" and split_matched == 0 and rows:
+        observed = sorted({str(_value(row, "split", "subset", "config", default="")) or "<none>" for row in rows})
+        raise ValueError(
+            f"--split {split!r} matched zero samples. "
+            f"Split identities observed in the loaded rows: {observed}. "
+            "Check the split name for a typo."
+        )
     if limit is not None:
         result = result[: max(0, limit)]
     return result
diff --git a/vllm_omni/benchmarks/duplex/omni_duplex_eval_media.py b/vllm_omni/benchmarks/duplex/omni_duplex_eval_media.py
index 629d8e87783..b45686fb81b 100644
--- a/vllm_omni/benchmarks/duplex/omni_duplex_eval_media.py
+++ b/vllm_omni/benchmarks/duplex/omni_duplex_eval_media.py
@@ -5,7 +5,9 @@
 
 from __future__ import annotations
 
+import os
 import subprocess
+import tempfile
 import wave
 from collections.abc import Iterator
 from pathlib import Path
@@ -20,20 +22,57 @@ def _run_ffmpeg(args: list[str]) -> bytes:
 
 
 def materialize_media(value: Any, output_dir: str | Path, stem: str, suffix: str) -> Path:
-    """Resolve common Hugging Face media values to a local file."""
+    """Resolve common Hugging Face media values to a local file.
+
+    ``str``/``Path`` values are returned as-is. Inline byte payloads (a
+    ``bytes``/``bytearray`` or a Hugging Face ``Audio``/``Video``/``Image``
+    feature mapping ``{"bytes": ..., "path": ...}``) are written to a real file
+    under ``output_dir`` and that existing path is returned. For such mappings
+    the ``path`` key is the original artifact name inside the dataset, which is
+    usually *not* present on the local disk, so it is only used to pick a
+    content extension and never treated as an existing file. A mapping or
+    object carrying only a ``path`` (no inline ``bytes``) is returned as an
+    already-materialized file reference.
+    """
     if isinstance(value, str | Path):
         return Path(value)
     path = value.get("path") if isinstance(value, dict) else getattr(value, "path", None)
-    if path:
-        return Path(path)
-    payload = value.get("bytes") if isinstance(value, dict) else None
+    payload = value.get("bytes") if isinstance(value, dict) else getattr(value, "bytes", None)
     if payload is None and isinstance(value, bytes | bytearray):
         payload = value
-    if payload is None:
-        raise ValueError(f"cannot materialize media value for {stem!r}")
-    destination = Path(output_dir) / f"{stem}{suffix}"
-    destination.parent.mkdir(parents=True, exist_ok=True)
-    destination.write_bytes(bytes(payload))
+    if payload is not None:
+        return _write_media_bytes(payload, output_dir, stem, _media_extension(path, suffix))
+    if path:
+        return Path(path)
+    raise ValueError(f"cannot materialize media value for {stem!r}")
+
+
+def _media_extension(path: str | Path | None, fallback: str) -> str:
+    """Pick a safe lower-case file extension from ``path`` when available."""
+    extension = Path(str(path)).suffix.lower() if path else ""
+    if extension.startswith(".") and len(extension) <= 8 and extension[1:].isalnum():
+        return extension
+    return fallback
+
+
+def _write_media_bytes(payload: bytes | bytearray, output_dir: str | Path, stem: str, extension: str) -> Path:
+    data = bytes(payload)
+    root = Path(output_dir)
+    root.mkdir(parents=True, exist_ok=True)
+    destination = root / f"{stem}{extension}"
+    if destination.exists() and destination.stat().st_size == len(data) and destination.read_bytes() == data:
+        return destination
+    fd, temporary = tempfile.mkstemp(dir=root, prefix=f".{destination.name}.", suffix=".part")
+    try:
+        with os.fdopen(fd, "wb") as handle:
+            handle.write(data)
+        os.replace(temporary, destination)
+    except OSError:
+        try:
+            os.unlink(temporary)
+        except OSError:
+            pass
+        raise
     return destination
 
 
diff --git a/vllm_omni/entrypoints/cli/benchmark/omni_duplex_eval.py b/vllm_omni/entrypoints/cli/benchmark/omni_duplex_eval.py
index 748100c5d24..c3e55abb703 100644
--- a/vllm_omni/entrypoints/cli/benchmark/omni_duplex_eval.py
+++ b/vllm_omni/entrypoints/cli/benchmark/omni_duplex_eval.py
@@ -28,8 +28,28 @@
 
 
 def _common(parser: argparse.ArgumentParser) -> None:
-    parser.add_argument("--dataset", default=DEFAULT_DATASET)
-    parser.add_argument("--split", default="all")
+    parser.add_argument(
+        "--dataset",
+        default=DEFAULT_DATASET,
+        help=(
+            "Hugging Face dataset id, a JSON/JSONL manifest, or a local Hugging Face "
+            "dataset mirror. A local directory must use a single configuration whose "
+            "data files are named after the RTD_*/PR_* splits "
+            "(data/<SPLIT>-00000-of-00001.parquet); a single .parquet file is also "
+            "accepted. --split filters the rows by their preserved split identity, so "
+            "rows without identity fail loudly."
+        ),
+    )
+    parser.add_argument(
+        "--split",
+        default="all",
+        help=(
+            "Restrict to one split (e.g. RTD_OCR) or 'all'. A mistyped split name "
+            "raises a clear error listing the splits actually observed in the data. "
+            "Rows from a manifest or an iterable without split/subset/config identity "
+            "keep the requested split as an override rather than being rejected."
+        ),
+    )
     parser.add_argument("--family", choices=("all", "rtd", "pr"), default="all")
     parser.add_argument("--media-root")
     parser.add_argument("--limit", type=int)
@@ -100,6 +120,8 @@ def run(args: argparse.Namespace) -> int:
         limit=args.limit,
         ids=args.ids,
     )
+    if not samples:
+        raise ValueError("no samples selected; check --dataset/--split/--family/--ids/--limit")
     if args.action == "generate":
         if args.concurrency < 1:
             raise ValueError("--concurrency must be at least 1")

From fa639b889e50d28a3cbe88b20b2e94cdc56bdf65 Mon Sep 17 00:00:00 2001
From: Tianyao Wu <54675599+twu3202@users.noreply.github.com>
Date: Wed, 16 Sep 2026 20:08:25 +0800
Subject: [PATCH 035/105] [Bugfix] Fail a duplex session that outgrows
 max_model_len instead of killing the EngineCore (#7277)

Signed-off-by: Tianyao Wu <rayroy31@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Gao Han <hgaoaf@connect.ust.hk>
Co-authored-by: amy-why-3459 <wuhaiyan17@huawei.com>
---
 tests/clients/test_duplex_client.py           |  27 ++
 .../sched/test_omni_ar_scheduler_logprobs.py  |   3 +
 .../sched/test_omni_ar_scheduler_streaming.py | 303 ++++++++++++++++++
 tests/engine/test_orchestrator.py             |  59 ++++
 vllm_omni/clients/duplex.py                   |   7 +-
 vllm_omni/core/sched/omni_ar_scheduler.py     | 140 +++++++-
 vllm_omni/engine/orchestrator.py              |  46 ++-
 7 files changed, 582 insertions(+), 3 deletions(-)

diff --git a/tests/clients/test_duplex_client.py b/tests/clients/test_duplex_client.py
index 43b7547cbd4..75ef06e3fdf 100644
--- a/tests/clients/test_duplex_client.py
+++ b/tests/clients/test_duplex_client.py
@@ -570,6 +570,33 @@ async def test_error_event_surfaces_on_response_path(make_rig):
         rig.feed(SESSION_CLOSED)
 
 
+@pytest.mark.asyncio
+async def test_close_after_error_reports_the_server_reason_to_a_sender():
+    # A client streaming input sits in send(), not in responses(), so the
+    # error text has to survive into the close marker or the session looks
+    # like it ended for no reason.
+    sock = FakeSocket()
+    sock.feed(SESSION_CREATED)
+    client, _ = make_client(sock)
+    async with client:
+        sock.feed(
+            {
+                "type": "error",
+                "error": {
+                    "code": "runtime_data_plane_stream_failed",
+                    "message": "context_length_exceeded: streaming session prompt would grow to 41207 tokens",
+                },
+                "server_event_seq": 2,
+            }
+        )
+        sock.feed(SESSION_CLOSED)
+        await _drain(lambda: client._closed.is_set())
+        with pytest.raises(DuplexSessionClosedError) as excinfo:
+            await client.send({"type": "input_audio_buffer.append", "audio": ""})
+    assert "runtime_data_plane_stream_failed" in str(excinfo.value)
+    assert "context_length_exceeded" in str(excinfo.value)
+
+
 @pytest.mark.asyncio
 async def test_slow_audio_consumer_drops_oldest_instead_of_stalling():
     from vllm_omni.clients.duplex import AudioDelta, ResponseHandle
diff --git a/tests/core/sched/test_omni_ar_scheduler_logprobs.py b/tests/core/sched/test_omni_ar_scheduler_logprobs.py
index 604904dd056..810c506c705 100644
--- a/tests/core/sched/test_omni_ar_scheduler_logprobs.py
+++ b/tests/core/sched/test_omni_ar_scheduler_logprobs.py
@@ -149,6 +149,9 @@ def _make_scheduler_stub(requests: list[_Request]) -> SimpleNamespace:
     for name in _MIXIN_UPDATE_HELPERS:
         setattr(scheduler, name, MethodType(getattr(OmniSchedulerMixin, name), scheduler))
     scheduler._cleanup_kv_tracking = MethodType(OmniARScheduler._cleanup_kv_tracking, scheduler)
+    scheduler._emit_streaming_context_overflow_outputs = MethodType(
+        OmniARScheduler._emit_streaming_context_overflow_outputs, scheduler
+    )
     scheduler.make_spec_decoding_stats = lambda *args, **kwargs: None
     scheduler.make_stats = lambda *args, **kwargs: None
     return scheduler
diff --git a/tests/core/sched/test_omni_ar_scheduler_streaming.py b/tests/core/sched/test_omni_ar_scheduler_streaming.py
index bca7d095c19..154644fb247 100644
--- a/tests/core/sched/test_omni_ar_scheduler_streaming.py
+++ b/tests/core/sched/test_omni_ar_scheduler_streaming.py
@@ -5,6 +5,7 @@
 
 from __future__ import annotations
 
+from collections import defaultdict
 from types import SimpleNamespace
 from unittest.mock import MagicMock
 
@@ -17,6 +18,8 @@
 from vllm.sampling_params import SamplingParams
 from vllm.v1.core.sched.output import SchedulerOutput
 from vllm.v1.outputs import ModelRunnerOutput
+from vllm.v1.engine import FinishReason
+from vllm.v1.core.sched.request_queue import SchedulingPolicy, create_request_queue
 from vllm.v1.request import Request, RequestStatus, StreamingUpdate
 from vllm_omni.core.sched.omni_ar_scheduler import OmniARAsyncScheduler, OmniARScheduler
 from vllm_omni.distributed.omni_connectors.transfer_adapter.chunk_transfer_adapter import (
@@ -958,3 +961,303 @@ def test_chunk_segment_cleanup_keeps_explicit_update_stage_parked(
     assert session.request_id not in sched.chunk_transfer_adapter.segment_finished_requests
     sched.skipped_waiting.remove_requests.assert_not_called()
     sched._enqueue_waiting_request.assert_not_called()
+
+
+def _make_live_session_scheduler(*, max_model_len: int) -> OmniARScheduler:
+    """A scheduler whose finish path is real: the queues, ``finish_requests``,
+    ``_free_request`` and the finished-request bookkeeping that wakes an idle
+    engine all run. Only block freeing and the encoder cache are mocked."""
+    sched = _make_admission_scheduler(max_model_len=max_model_len)
+    del sched._free_request  # the admission helper mocks it; run the real one
+    sched._omits_kv_transfer_cache = {}
+    sched.connector = None
+    sched.perf_metrics = None
+    sched.recompute_kv_load_failures = False
+    sched.finished_req_ids = set()
+    sched.finished_req_ids_dict = defaultdict(set)
+    sched.transfer_triggered_requests = set()
+    sched.active_kv_transfers = set()
+    sched.waiting_for_transfer_free = set()
+    sched.pending_stop_after_extraction = set()
+    sched.requests_needing_kv_transfer = {}
+    sched._kv_wait_start_ts = {}
+    sched.kv_cache_manager = SimpleNamespace(take_events=lambda: None, estimate_cached_tokens=lambda _request: 0)
+    return sched
+
+
+def _run_idle_step(sched: OmniARScheduler):
+    """One ``update_from_output`` with nothing scheduled: the step an idle
+    engine runs once ``has_finished_requests()`` reports a freed session."""
+    scheduler_output = SimpleNamespace(
+        num_scheduled_tokens={},
+        scheduled_spec_decode_tokens={},
+        num_invalid_spec_tokens=0,
+    )
+    model_runner_output = SimpleNamespace(
+        sampled_token_ids=[],
+        logprobs=None,
+        prompt_logprobs_dict={},
+        pooler_output=None,
+        num_nans_in_logits=None,
+        kv_connector_output=None,
+        cudagraph_stats=None,
+        req_id_to_index={},
+        routed_experts=None,
+    )
+    return OmniARScheduler.update_from_output(sched, scheduler_output, model_runner_output)
+
+
+def _park_session(sched: OmniARScheduler, session: Request) -> None:
+    """Put a session where a 1 fps video stream leaves it between appends:
+    prompt partly computed, waiting for streaming input, in admission."""
+    sched.requests[session.request_id] = session
+    session.append_output_token_ids([7, 8, 9])
+    session.num_computed_tokens = 6
+    session.num_output_placeholders = 0
+    session.status = RequestStatus.WAITING_FOR_STREAMING_REQ
+    sched.skipped_waiting.add_request(session)
+    sched.num_waiting_for_streaming_input = 1
+
+
+def test_stage0_streaming_update_that_overflows_max_model_len_finishes_the_session() -> None:
+    """A native duplex session grows its prompt on every append; once the
+    extension cannot fit the model the worker crashes copying the prompt.
+    The scheduler must drop the update and fail only this session, at once,
+    through the real finish path: a parked session does not make the engine
+    schedule, so what wakes the engine is the freed request showing up in
+    ``has_finished_requests()``, and the step that follows must carry one
+    explicit ERROR rather than the synthesized ABORT."""
+    sched = _make_live_session_scheduler(max_model_len=8)
+    session = _make_request()
+    _park_session(sched, session)
+
+    sched._update_request_as_session(session, _make_update([10, 20, 30]))
+
+    assert session.prompt_token_ids == [1, 2, 3]
+    assert session.num_prompt_tokens == 3
+    assert session.status == RequestStatus.FINISHED_ERROR
+    assert session.request_id not in sched.requests
+    assert len(sched.waiting) == 0
+    assert len(sched.skipped_waiting) == 0
+    assert sched.num_waiting_for_streaming_input == 0
+    sched._free_request_blocks.assert_called_once_with(session)
+    assert sched.finished_req_ids == {session.request_id}
+    assert sched.has_finished_requests()
+    client_index, reason = sched._streaming_context_overflow[session.request_id]
+    assert client_index == session.client_index
+    assert reason.startswith("context_length_exceeded: ")
+    assert "9 tokens" in reason and "max_model_len 8" in reason
+
+    engine_core_outputs = _run_idle_step(sched)
+
+    (output,) = engine_core_outputs[session.client_index].outputs
+    assert output.request_id == session.request_id
+    assert output.finish_reason == FinishReason.ERROR
+    assert output.stop_reason == reason
+    assert output.new_token_ids == []
+    assert engine_core_outputs[session.client_index].finished_requests == {session.request_id}
+    assert sched._streaming_context_overflow == {}
+    # Nothing is left to report once the error went out.
+    assert _run_idle_step(sched) == {}
+
+
+def test_stage0_streaming_update_that_fills_max_model_len_exactly_finishes_the_session() -> None:
+    """An exactly full prompt leaves no room for the token every duplex step
+    samples: upstream's running budget drops to -1, which ``schedule()`` does
+    not catch, so the exact fill is an overflow too."""
+    sched = _make_scheduler(stage_id=0)
+    sched.max_model_len = 8
+    sched.finish_requests = MagicMock()
+    session = _make_request()
+    session.status = RequestStatus.WAITING_FOR_STREAMING_REQ
+    session.append_output_token_ids([7, 8, 9])
+    session.num_computed_tokens = 6
+    session.num_output_placeholders = 0
+
+    sched._update_request_as_session(session, _make_update([10, 20]))
+
+    assert session.prompt_token_ids == [1, 2, 3]
+    assert session.num_prompt_tokens == 3
+    sched.finish_requests.assert_called_once_with((session.request_id,), RequestStatus.FINISHED_ERROR)
+    _, reason = sched._streaming_context_overflow[session.request_id]
+    assert "8 tokens" in reason and "max_model_len 8" in reason
+
+
+def test_stage0_streaming_update_that_leaves_room_to_sample_is_applied() -> None:
+    sched = _make_scheduler(stage_id=0)
+    sched.max_model_len = 9
+    sched.finish_requests = MagicMock()
+    session = _make_request()
+    session.status = RequestStatus.WAITING_FOR_STREAMING_REQ
+    session.append_output_token_ids([7, 8, 9])
+    session.num_computed_tokens = 6
+    session.num_output_placeholders = 0
+
+    sched._update_request_as_session(session, _make_update([10, 20]))
+
+    assert session.prompt_token_ids == [1, 2, 3, 7, 8, 9, 10, 20]
+    assert session.num_prompt_tokens == 8
+    assert session.status == RequestStatus.WAITING
+    sched.finish_requests.assert_not_called()
+    assert not getattr(sched, "_streaming_context_overflow", {})
+
+
+def test_stage0_streaming_update_keeps_room_for_every_token_sampled_per_step() -> None:
+    """With speculative decoding a step samples more than one token, and the
+    prompt must leave room for all of them."""
+    sched = _make_scheduler(stage_id=0)
+    sched.max_model_len = 9
+    sched.num_sampled_tokens_per_step = 2
+    sched.finish_requests = MagicMock()
+    session = _make_request()
+    session.status = RequestStatus.WAITING_FOR_STREAMING_REQ
+    session.append_output_token_ids([7, 8, 9])
+    session.num_computed_tokens = 6
+    session.num_output_placeholders = 0
+
+    sched._update_request_as_session(session, _make_update([10, 20]))
+
+    assert session.prompt_token_ids == [1, 2, 3]
+    sched.finish_requests.assert_called_once_with((session.request_id,), RequestStatus.FINISHED_ERROR)
+    assert "8 tokens" in sched._streaming_context_overflow[session.request_id][1]
+
+
+def test_stage0_streaming_update_overflow_counts_an_uncomputed_prompt() -> None:
+    """A preempted session keeps its prompt even though num_computed_tokens
+    fell behind it; the projection must use the longer of the two."""
+    sched = _make_scheduler(stage_id=0)
+    sched.max_model_len = 4
+    sched.finish_requests = MagicMock()
+    session = _make_request()
+    session.status = RequestStatus.WAITING_FOR_STREAMING_REQ
+    session.num_computed_tokens = 0
+
+    sched._update_request_as_session(session, _make_update([10, 20]))
+
+    assert session.prompt_token_ids == [1, 2, 3]
+    sched.finish_requests.assert_called_once()
+    assert "5 tokens" in sched._streaming_context_overflow[session.request_id][1]
+
+
+def _make_admission_scheduler(*, max_model_len: int) -> OmniARScheduler:
+    """A scheduler with real admission queues, so nothing about the terminal
+    handling below is mocked away except block freeing."""
+    sched = _make_scheduler(stage_id=0)
+    sched.max_model_len = max_model_len
+    sched.policy = SchedulingPolicy.FCFS
+    sched.waiting = create_request_queue(sched.policy)
+    sched.skipped_waiting = create_request_queue(sched.policy)
+    sched.running = []
+    sched.requests = {}
+    sched._free_request = MagicMock()  # needs a KV manager; not what this covers
+    return sched
+
+
+def _make_queued_stop(session: Request, update: StreamingUpdate) -> None:
+    """Put the request in the state upstream hands to _handle_stopped_request:
+    an append that arrived during generation is queued, and the stop status is
+    still on the request."""
+    from collections import deque
+
+    session.resumable = True
+    session.streaming_queue = deque([update])
+    session.status = RequestStatus.FINISHED_STOPPED
+
+
+def test_queued_streaming_update_that_overflows_does_not_return_to_admission() -> None:
+    sched = _make_admission_scheduler(max_model_len=4)
+    session = _make_request()
+    sched.requests[session.request_id] = session
+    session.num_computed_tokens = 3
+    _make_queued_stop(session, _make_update([10, 20]))
+
+    finished = sched._handle_stopped_request(session)
+
+    assert finished is True
+    assert len(sched.waiting) == 0
+    assert len(sched.skipped_waiting) == 0
+    assert session.status == RequestStatus.FINISHED_ERROR
+    assert session.resumable is False
+    assert "context_length_exceeded: " in sched._streaming_context_overflow[session.request_id][1]
+    # update_from_output frees every request reported as finished; freeing here
+    # as well deleted it from self.requests twice (KeyError in _free_blocks).
+    sched._free_request.assert_not_called()
+
+
+def test_queued_streaming_update_that_fits_still_resumes_the_session() -> None:
+    sched = _make_admission_scheduler(max_model_len=64)
+    session = _make_request()
+    sched.requests[session.request_id] = session
+    session.num_computed_tokens = 3
+    _make_queued_stop(session, _make_update([10, 20]))
+
+    finished = sched._handle_stopped_request(session)
+
+    assert finished is False
+    assert len(sched.waiting) == 1
+    assert session.status == RequestStatus.WAITING
+    assert not getattr(sched, "_streaming_context_overflow", {})
+    sched._free_request.assert_not_called()
+
+
+def test_queued_stop_with_a_recorded_overflow_still_leaves_admission() -> None:
+    """The overflow may already be on record when the stop is handled (an
+    earlier update of the same session). Upstream still re-enqueues the
+    request, so the override must take it back out either way instead of
+    leaving a FINISHED_ERROR request for admission to trip over."""
+    sched = _make_admission_scheduler(max_model_len=64)
+    session = _make_request()
+    sched.requests[session.request_id] = session
+    session.num_computed_tokens = 3
+    sched._streaming_context_overflow = {session.request_id: (session.client_index, "context_length_exceeded: earlier")}
+    _make_queued_stop(session, _make_update([10, 20]))  # this update itself fits
+
+    finished = sched._handle_stopped_request(session)
+
+    assert finished is True
+    assert len(sched.waiting) == 0
+    assert len(sched.skipped_waiting) == 0
+    assert session.status == RequestStatus.FINISHED_ERROR
+    assert session.resumable is False
+    sched._free_request.assert_not_called()
+
+
+def test_parked_stop_with_a_recorded_overflow_keeps_the_streaming_counter_balanced() -> None:
+    """Same as above with nothing queued: upstream parks the request as
+    waiting for streaming input and counts it; the dequeue must uncount it."""
+    from collections import deque
+
+    sched = _make_admission_scheduler(max_model_len=64)
+    session = _make_request()
+    sched.requests[session.request_id] = session
+    session.num_computed_tokens = 3
+    sched._streaming_context_overflow = {session.request_id: (session.client_index, "context_length_exceeded: earlier")}
+    session.resumable = True
+    session.streaming_queue = deque()
+    session.status = RequestStatus.FINISHED_STOPPED
+
+    finished = sched._handle_stopped_request(session)
+
+    assert finished is True
+    assert len(sched.skipped_waiting) == 0
+    assert sched.num_waiting_for_streaming_input == 0
+    assert session.status == RequestStatus.FINISHED_ERROR
+    sched._free_request.assert_not_called()
+
+
+def test_context_overflow_emits_an_error_output_with_the_reason() -> None:
+    sched = _make_scheduler(stage_id=0)
+    sched._streaming_context_overflow = {"req-a": (2, "context_length_exceeded: too long")}
+    outputs: dict[int, list] = {}
+
+    sched._emit_streaming_context_overflow_outputs(outputs)
+
+    (output,) = outputs[2]
+    assert output.request_id == "req-a"
+    assert output.finish_reason == FinishReason.ERROR
+    assert output.stop_reason == "context_length_exceeded: too long"
+    assert output.new_token_ids == []
+    assert sched._streaming_context_overflow == {}
+
+    sched._emit_streaming_context_overflow_outputs(outputs)
+    assert len(outputs[2]) == 1
diff --git a/tests/engine/test_orchestrator.py b/tests/engine/test_orchestrator.py
index beddd2106ca..3b6ee7e7ba5 100644
--- a/tests/engine/test_orchestrator.py
+++ b/tests/engine/test_orchestrator.py
@@ -21,6 +21,7 @@
 from vllm.v1.engine.exceptions import EngineDeadError
 from vllm.v1.metrics.stats import IterationStats
 
+from vllm_omni.engine import OmniEngineCoreOutput
 from vllm_omni.engine.messages import (
     AbortRequestMessage,
     AbortResultMessage,
@@ -1891,3 +1892,61 @@ def release_bindings(self, request_ids: list[str]) -> None:
     assert first.physical_abort_calls == 1
     assert second.physical_abort_calls == 2
     assert second.bound == set()
+
+
+@pytest.mark.asyncio
+async def test_duplex_session_request_error_finish_is_delivered_as_request_error() -> None:
+    """A session-owned request the scheduler finished with FinishReason.ERROR
+    (e.g. its prompt could not grow past max_model_len) must reach the
+    session's consumer as a request-scoped error, not vanish: its terminal
+    outputs are not processed like other requests, and the output processor
+    may already have dropped the request state."""
+    output_queue: asyncio.Queue = asyncio.Queue()
+    orchestrator = Orchestrator(
+        request_async_queue=asyncio.Queue(),
+        output_async_queue=output_queue,
+        rpc_async_queue=asyncio.Queue(),
+        stage_pools=[],
+    )
+    duplex_state = OrchestratorRequestState(request_id="duplex-req", session_owned=True)
+    plain_state = OrchestratorRequestState(request_id="plain-req")
+    reason = "context_length_exceeded: streaming session prompt would grow to 8220 tokens, above max_model_len 8192"
+
+    await orchestrator._report_duplex_session_request_error(
+        0,
+        0,
+        OmniEngineCoreOutput(
+            request_id="duplex-req", new_token_ids=[], finish_reason=FinishReason.ERROR, stop_reason=reason
+        ),
+        duplex_state,
+    )
+    error = output_queue.get_nowait()
+    assert isinstance(error, ErrorMessage)
+    assert error.request_id == "duplex-req"
+    assert error.stage_id == 0
+    assert error.fatal is False
+    assert error.error == reason
+
+    # An ordinary segment stop, a segment-finished error and a request that is
+    # not session-owned produce nothing.
+    await orchestrator._report_duplex_session_request_error(
+        0,
+        0,
+        OmniEngineCoreOutput(request_id="duplex-req", new_token_ids=[], finish_reason=FinishReason.STOP),
+        duplex_state,
+    )
+    await orchestrator._report_duplex_session_request_error(
+        0,
+        0,
+        OmniEngineCoreOutput(
+            request_id="duplex-req", new_token_ids=[], finish_reason=FinishReason.ERROR, is_segment_finished=True
+        ),
+        duplex_state,
+    )
+    await orchestrator._report_duplex_session_request_error(
+        0,
+        0,
+        OmniEngineCoreOutput(request_id="plain-req", new_token_ids=[], finish_reason=FinishReason.ERROR),
+        plain_state,
+    )
+    assert output_queue.empty()
diff --git a/vllm_omni/clients/duplex.py b/vllm_omni/clients/duplex.py
index 52266b64ea7..17358906fc0 100644
--- a/vllm_omni/clients/duplex.py
+++ b/vllm_omni/clients/duplex.py
@@ -645,6 +645,7 @@ def __init__(
         self._closing = False
         self._closed = asyncio.Event()
         self._closed_marker: _ClosedMarker | None = None
+        self._last_error_reason: str | None = None
 
     # -- transport hooks ------------------------------------------------------
 
@@ -1061,12 +1062,16 @@ async def _dispatch(self, data: dict[str, object]) -> None:
             # on the response path too so a consumer waiting in responses()
             # is not left waiting forever (see the responses() docstring).
             _put_drop_oldest(self._response_queue, _ErrorMarker(event))
+            # Keep the text for the close that usually follows: a client that
+            # is streaming input is inside send(), not draining responses(),
+            # and would otherwise only ever see "closed".
+            self._last_error_reason = f"{event.code}: {event.message}" if event.code else event.message
 
         for queue in list(self._subscribers):
             _put_drop_oldest(queue, event)
 
         if isinstance(event, SessionClosed):
-            self._finalize("closed", expected=True)
+            self._finalize(self._last_error_reason or "closed", expected=True)
         elif isinstance(event, SessionExpired):
             reason = data.get("reason")
             self._finalize(f"expired: {reason}" if reason else "expired", expected=False)
diff --git a/vllm_omni/core/sched/omni_ar_scheduler.py b/vllm_omni/core/sched/omni_ar_scheduler.py
index 329e8ad8190..3d866fda772 100644
--- a/vllm_omni/core/sched/omni_ar_scheduler.py
+++ b/vllm_omni/core/sched/omni_ar_scheduler.py
@@ -16,7 +16,7 @@
 from vllm.v1.core.sched.output import SchedulerOutput
 from vllm.v1.core.sched.request_queue import create_request_queue
 from vllm.v1.core.sched.scheduler import Scheduler as VLLMScheduler
-from vllm.v1.engine import EngineCoreEventType, EngineCoreOutput, EngineCoreOutputs
+from vllm.v1.engine import EngineCoreEventType, EngineCoreOutput, EngineCoreOutputs, FinishReason
 from vllm.v1.metrics.perf import PerfStats
 from vllm.v1.outputs import ModelRunnerOutput
 from vllm.v1.request import Request, RequestStatus, StreamingUpdate
@@ -116,6 +116,11 @@ def __init__(self, *args, **kwargs):
         self._init_omni_io_scheduling_state()
         # Snapshot prompt length for each streaming input update
         self._new_prompt_len_snapshot: dict[str, int] = {}
+        # Streaming sessions finished because their next prompt extension
+        # would exceed max_model_len: request_id -> (client_index, reason).
+        # Drained into an explicit FinishReason.ERROR output on the next
+        # update_from_output so the client learns why the session ended.
+        self._streaming_context_overflow: dict[str, tuple[int, str]] = {}
 
     def _get_confirmed_num_computed_tokens(self, request: Request) -> int:
         """num_computed_tokens minus async placeholders (KV actually on GPU)."""
@@ -704,6 +709,7 @@ def update_from_output(
             failed_kv_load_req_ids,
             outputs,
         )
+        self._emit_streaming_context_overflow_outputs(outputs)
         if self.chunk_transfer_adapter is not None:
             for request in failed_requests:
                 self.chunk_transfer_adapter.cleanup_receiver(request.request_id)
@@ -883,11 +889,143 @@ def _update_request_as_session(self, session: Request, update: StreamingUpdate)
             self._release_replaced_streaming_prompt_cache(session)
             self._replace_streaming_session(session, update)
             return
+        if self._streaming_update_overflows(session, update):
+            return
         session._omni_segment_generation = int(getattr(session, "_omni_segment_generation", 0) or 0) + 1
         super()._update_request_as_session(session, update)
         if hasattr(update, "model_intermediate_buffer"):
             session.model_intermediate_buffer = update.model_intermediate_buffer
 
+    # Prefix of the stop_reason carried by the FinishReason.ERROR output, so the
+    # serving side can map it to a stable error code.
+    STREAMING_CONTEXT_OVERFLOW_STOP_REASON = "context_length_exceeded"
+
+    def _streaming_update_overflows(self, session: Request, update: StreamingUpdate) -> bool:
+        """Finish a streaming session whose next extension cannot fit the model.
+
+        Upstream ``_update_request_as_session`` appends the update to the
+        session prompt without checking ``max_model_len``. The worker's input
+        batch then fails to copy the prompt (``could not broadcast input array
+        from shape (N,) into shape (max_model_len,)``) and the EngineCore dies,
+        taking every session on the replica with it. A native duplex session
+        grows by tens to hundreds of tokens per second of input, so long
+        sessions reach this point in normal use.
+
+        A prompt that fills the model exactly is over the line as well: the
+        session samples at least one listen/speak token after every append,
+        and upstream's running-request budget
+        ``max_model_len - num_computed_tokens - num_sampled_tokens_per_step``
+        then goes negative, which the ``num_new_tokens == 0`` guard in
+        ``schedule()`` does not catch (``allocate_slots`` dies, or the worker
+        asserts ``max_model_len + 1`` sampled positions). So the extended
+        prompt must leave room for the tokens sampled in one step.
+
+        The update is dropped and only this request is finished, right here:
+        a parked session does not make the engine schedule, so deferring the
+        finish to the next ``schedule()`` would leave the client waiting. The
+        reason is emitted with the terminal output (see
+        :meth:`_emit_streaming_context_overflow_outputs`).
+        """
+        max_model_len = getattr(self, "max_model_len", None)
+        if max_model_len is None:
+            model_config = getattr(getattr(self, "vllm_config", None), "model_config", None)
+            max_model_len = getattr(model_config, "max_model_len", None)
+        if not max_model_len:
+            return False
+        new_tokens = len(update.prompt_token_ids or ())
+        # The extended prompt is the current prompt plus the computed output
+        # tokens upstream keeps, then the update: num_computed_tokens covers
+        # both when the prompt was fully computed.
+        projected = max(int(session.num_prompt_tokens), int(session.num_computed_tokens)) + new_tokens
+        # Room for the tokens one step samples on top of the prompt (1 without
+        # speculative decoding). __new__-built test schedulers carry no
+        # num_sampled_tokens_per_step.
+        sample_room = max(1, int(getattr(self, "num_sampled_tokens_per_step", 1) or 1))
+        if projected + sample_room <= int(max_model_len):
+            return False
+        reason = (
+            f"{self.STREAMING_CONTEXT_OVERFLOW_STOP_REASON}: streaming session prompt would grow to "
+            f"{projected} tokens, leaving no room to sample within max_model_len {int(max_model_len)}"
+        )
+        logger.error(
+            "[Omni] %s: %s; finishing the request instead of extending it",
+            session.request_id,
+            reason,
+        )
+        overflow = getattr(self, "_streaming_context_overflow", None)
+        if overflow is None:
+            overflow = self._streaming_context_overflow = {}
+        overflow[session.request_id] = (int(getattr(session, "client_index", 0) or 0), reason)
+        if session.is_finished():
+            # Reached from ``_handle_stopped_request`` with a queued update.
+            # ``update_from_output`` frees every request that call reports as
+            # finished, so finishing the session here too would free it twice.
+            # ``_handle_stopped_request`` below takes it out of admission and
+            # leaves the single free to the caller.
+            return True
+        self.finish_requests((session.request_id,), RequestStatus.FINISHED_ERROR)
+        return True
+
+    def _handle_stopped_request(self, request: Request) -> bool:
+        """Do not resume a session whose queued update overflowed the model.
+
+        Upstream pops one queued ``StreamingUpdate``, applies it through
+        ``_update_request_as_session`` and then re-enqueues the request
+        unconditionally. When that update overflows, the request must not go
+        back into the waiting queue: it is terminal, and admission raises
+        ``RuntimeError: Invalid request status`` on anything that is neither
+        WAITING nor PREEMPTED, which would kill the EngineCore this guard
+        exists to keep alive. The same holds for a session whose overflow was
+        recorded before this call and that upstream still reports as resumed.
+        """
+        finished = super()._handle_stopped_request(request)
+        if finished:
+            return True
+        overflow = getattr(self, "_streaming_context_overflow", None)
+        if not overflow or request.request_id not in overflow:
+            return False
+        # Whether the overflow was recorded by this call's queued update or
+        # earlier makes no difference: a session in the overflow map is
+        # terminal, and upstream has just put it back into admission.
+        self._finish_overflowed_streaming_session(request)
+        return True
+
+    def _finish_overflowed_streaming_session(self, request: Request) -> None:
+        """Take a terminal session back out of admission.
+
+        Queues and status only. ``update_from_output`` frees every request
+        ``_handle_stopped_request`` reports as finished, so freeing here as
+        well deletes it from ``self.requests`` twice (``KeyError`` in
+        ``_free_blocks``) and skips the caller's input-coordinator cleanup.
+        """
+        self.waiting.remove_requests((request,))
+        self.skipped_waiting.remove_requests((request,))
+        if request.status == RequestStatus.WAITING_FOR_STREAMING_REQ:
+            self.num_waiting_for_streaming_input -= 1
+        request.status = RequestStatus.FINISHED_ERROR
+        request.resumable = False
+
+    def _emit_streaming_context_overflow_outputs(self, outputs: dict[int, list[EngineCoreOutput]]) -> None:
+        """Turn recorded context overflows into explicit error outputs.
+
+        Without this the finished session would only get the synthesized
+        ``FinishReason.ABORT`` output, which a client cannot tell apart from
+        its own cancel.
+        """
+        overflow = getattr(self, "_streaming_context_overflow", None)
+        if not overflow:
+            return
+        for request_id, (client_index, reason) in list(overflow.items()):
+            outputs.setdefault(client_index, []).append(
+                OmniEngineCoreOutput(
+                    request_id=request_id,
+                    new_token_ids=[],
+                    finish_reason=FinishReason.ERROR,
+                    stop_reason=reason,
+                )
+            )
+        overflow.clear()
+
     def _free_request(
         self, request: Request, delay_free_blocks: bool = False
     ) -> tuple[dict[str, Any] | None, dict[str, Any] | None]:
diff --git a/vllm_omni/engine/orchestrator.py b/vllm_omni/engine/orchestrator.py
index aced2c1b36f..aea5c851991 100644
--- a/vllm_omni/engine/orchestrator.py
+++ b/vllm_omni/engine/orchestrator.py
@@ -30,7 +30,7 @@
 from vllm.outputs import CompletionOutput, RequestOutput
 from vllm.pooling_params import PoolingParams
 from vllm.sampling_params import RequestOutputKind, SamplingParams
-from vllm.v1.engine import EngineCoreOutputs
+from vllm.v1.engine import EngineCoreOutputs, FinishReason
 from vllm.v1.engine.exceptions import EngineDeadError
 from vllm.v1.metrics.stats import IterationStats
 
@@ -777,6 +777,7 @@ async def _process_llm_stage_outputs(
             )
             if await self._apply_raw_terminal_stage_finish(stage_id, eco, req_state):
                 raw_terminal_request_ids.add(req_state.request_id)
+            await self._report_duplex_session_request_error(stage_id, replica_id, eco, req_state)
         iteration_stats = IterationStats() if (self._stat_logger is not None and raw_outputs.outputs) else None
         processed = await pool.process_llm_raw_outputs(
             replica_id,
@@ -1503,6 +1504,49 @@ async def _apply_raw_terminal_stage_finish(
         req_state.finished_final_output_stage_ids.add(stage_id)
         return True
 
+    async def _report_duplex_session_request_error(
+        self,
+        stage_id: int,
+        replica_id: int | None,
+        eco: Any,
+        req_state: OrchestratorRequestState,
+    ) -> None:
+        """Turn a scheduler-side error finish of a duplex session request into a request error.
+
+        A duplex session request is resumable, so its terminal outputs are
+        deliberately not turned into processed outputs
+        (``_finish_raw_terminal_requests`` skips duplex sessions), and vLLM's
+        output processor may already have dropped the request state by the
+        time the raw ``FinishReason.ERROR`` output arrives. Without this the
+        session never learns that its request is gone: the next append
+        re-creates the request from scratch and the session silently loses
+        its context. Deliver the error to the request's consumer instead so
+        the serving layer can fail and close the session.
+        """
+        if not req_state.session_owned:
+            return
+        if getattr(eco, "finish_reason", None) != FinishReason.ERROR:
+            return
+        if getattr(eco, "is_segment_finished", False):
+            return
+        stop_reason = getattr(eco, "stop_reason", None)
+        error = stop_reason if isinstance(stop_reason, str) and stop_reason else "duplex session request failed"
+        logger.error(
+            "[Orchestrator] Duplex session request %s failed at stage-%s replica-%s: %s",
+            req_state.request_id,
+            stage_id,
+            replica_id,
+            error,
+        )
+        await self.output_async_queue.put(
+            ErrorMessage(
+                error=error,
+                fatal=False,
+                request_id=req_state.request_id,
+                stage_id=stage_id,
+            )
+        )
+
     async def _finish_raw_terminal_requests(
         self,
         stage_id: int,

From 538eddd74d57ac5a8fea0a8ac0d5288e20678ccb Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zhengyuan=20Su=20=28=E8=8B=8F=E6=94=BF=E6=B8=8A=29?=
 <su.zhengyuan@u.nus.edu>
Date: Wed, 16 Sep 2026 20:49:04 +0800
Subject: [PATCH 036/105] [Perf][CosyVoice3] Bounded-window incremental HiFT
 vocoder streaming (#7521)

Signed-off-by: Zhengyuan Su <su.zhengyuan@u.nus.edu>
---
 .../bench_cosyvoice3_concurrency_matrix.py    | 517 ++++++++++++++++++
 pyproject.toml                                |   2 -
 requirements/common.txt                       |   5 +
 .../cosyvoice3/test_cosyvoice3_components.py  |  61 ++-
 .../test_cosyvoice3_incremental_hift.py       | 415 ++++++++++++++
 .../minicpmo_4_5/test_cuda_graph_wrapper.py   |   2 +
 .../cosyvoice3/code2wav_core/hifigan.py       | 170 +++++-
 .../models/cosyvoice3/cosyvoice3_code2wav.py  | 136 +++--
 8 files changed, 1224 insertions(+), 84 deletions(-)
 create mode 100644 benchmarks/tts/bench_cosyvoice3_concurrency_matrix.py
 create mode 100644 tests/model_executor/models/cosyvoice3/test_cosyvoice3_incremental_hift.py

diff --git a/benchmarks/tts/bench_cosyvoice3_concurrency_matrix.py b/benchmarks/tts/bench_cosyvoice3_concurrency_matrix.py
new file mode 100644
index 00000000000..fb45b17431d
--- /dev/null
+++ b/benchmarks/tts/bench_cosyvoice3_concurrency_matrix.py
@@ -0,0 +1,517 @@
+#!/usr/bin/env python3
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""CosyVoice3 streaming e2e benchmark: concurrency x utterance-length matrix.
+
+Launches the server once per (concurrency, step-size) combo, streams TTS
+requests cycling through several utterance lengths, and reports
+TTFA/E2E/RTF/per-chunk latency (mean, stdev, range) per cell. "Step size" is
+``codec_chunk_frames``, the token-hop length the first emitted chunk waits
+for; later chunks wait for a doubling hop capped at ``4 * codec_chunk_frames``
+(see ``_token_hop_lengths``). Per-chunk latency is reconstructed from that
+same ramp rather than from raw transport read boundaries, which don't align
+to model chunks (see ``one_request``'s docstring).
+
+Running with no flags reproduces the default matrix. Per-request correctness
+is checked: non-silent, long enough, and (with a fixed ``--seed``)
+byte-identical PCM across requests for the same text.
+"""
+
+import argparse
+import json
+import os
+import signal
+import statistics
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+import httpx
+import numpy as np
+
+REPO = Path(__file__).resolve().parents[2]
+DEFAULT_MODEL = "FunAudioLLM/Fun-CosyVoice3-0.5B-2512"
+
+DEFAULT_REF_AUDIO = "https://raw.githubusercontent.com/FunAudioLLM/CosyVoice/main/asset/zero_shot_prompt.wav"
+DEFAULT_REF_TEXT = "希望你以后能够做的比我还好呦。"
+
+DEFAULT_TEXTS = [
+    "Thank you so much for the birthday gift you sent me.",
+    "The weather is lovely today, with warm sunshine and a gentle breeze. "
+    "We decided to take a walk in the park to enjoy the spring flowers and the fresh air.",
+    "The weather is lovely today, with warm sunshine and a gentle breeze. We decided to take a walk in the "
+    "park to enjoy the spring flowers and the fresh air. Many people were out walking, children were "
+    "running and playing on the grass, and older folks sat on benches chatting with one another. We "
+    "strolled slowly along the path and came across a cherry tree in full bloom, its pink petals drifting "
+    "on the wind. It was so beautiful that we stopped to take some photos to remember the moment. Then we "
+    "continued on and reached a small lake, its water so clear you could see straight to the bottom, with "
+    "the blue sky and white clouds reflected on its surface. A few ducks paddled back and forth across the "
+    "water, occasionally letting out a soft quack. We sat on a bench by the lake for a while, enjoying the "
+    "peaceful afternoon. Time passed quickly, and before we knew it evening had arrived, with the setting "
+    "sun painting the sky in shades of gold. Reluctant to leave, we finally headed home, already planning "
+    "our next visit. On the way back we talked about everything we had seen and heard that day, feeling "
+    "wonderfully happy. It was truly an unforgettable weekend.",
+]
+
+# PCM16 mono @ 24 kHz (CosyVoice3 output rate)
+SAMPLE_RATE = 24000
+
+# Well below any real speech's RMS; catches all-zero/near-silent PCM that byte
+# count and duration checks alone pass through.
+MIN_RMS = 50.0
+
+# Overlay: only codec_chunk_frames is overridden; must live next to cosyvoice3.yaml (relative base_config)
+DEPLOY_TEMPLATE = """# Auto-generated by bench_cosyvoice3_concurrency_matrix.py -- do not edit.
+base_config: cosyvoice3.yaml
+
+connectors:
+  connector_of_shared_memory:
+    name: SharedMemoryConnector
+    extra:
+      codec_streaming: true
+      connector_get_sleep_s: 0.01
+      connector_get_max_wait_first_chunk: 3000
+      connector_get_max_wait: 300
+      codec_chunk_frames: {chunk_frames}
+      codec_max_chunk_frames: {max_chunk_frames}
+      codec_stream_scale_factor: {stream_scale_factor}
+      codec_left_context_frames: 25
+      codec_vocab_size: 6561
+"""
+
+# CosyVoice3Config constants (transformers_utils/configs/cosyvoice3.py): tokens
+# are consumed at token_mel_ratio mel frames each, and HiFT emits
+# samples_per_mel PCM16 samples per mel frame. Pinned here (not left to the
+# server's defaults) since one_request's byte-boundary reconstruction below
+# depends on knowing them exactly.
+TOKEN_MEL_RATIO = 2
+SAMPLES_PER_MEL = 480
+STREAM_SCALE_FACTOR = 2
+
+
+def _stats(values: list[float]) -> dict[str, float]:
+    """Mean/median/stdev/p95/min/max/n for a list of per-request measurements."""
+    n = len(values)
+    if n == 0:
+        return {
+            "n": 0,
+            "mean": float("nan"),
+            "median": float("nan"),
+            "stdev": float("nan"),
+            "p95": float("nan"),
+            "min": float("nan"),
+            "max": float("nan"),
+        }
+    return {
+        "n": n,
+        "mean": statistics.mean(values),
+        "median": statistics.median(values),
+        "stdev": statistics.stdev(values) if n >= 2 else 0.0,
+        "p95": statistics.quantiles(values, n=20)[18] if n >= 2 else values[0],
+        "min": min(values),
+        "max": max(values),
+    }
+
+
+def vllm_bin() -> str:
+    for c in (REPO / ".venv/bin/vllm", Path(sys.executable).parent / "vllm"):
+        if c.is_file():
+            return str(c)
+    return "vllm"
+
+
+def wait_ready(url: str, proc: subprocess.Popen, log: Path, timeout: float) -> None:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if proc.poll() is not None:
+            tail = log.read_text(errors="replace").splitlines()[-40:] if log.exists() else []
+            raise RuntimeError("server exited during startup:\n  " + "\n  ".join(tail))
+        try:
+            if httpx.get(f"{url}/health", timeout=2.0).status_code == 200:
+                return
+        except Exception:
+            pass
+        time.sleep(2.0)
+    raise TimeoutError(f"server not ready within {timeout}s (log: {log})")
+
+
+def _token_hop_lengths(chunk_frames: int, max_chunk_frames: int):
+    """The token-hop-length ramp talker2code2wav_async_chunk uses to decide
+    when to fire the next flow-solve/emission: chunk_frames, then doubling
+    (STREAM_SCALE_FACTOR) each step, capped at max_chunk_frames. This -- not
+    codec_chunk_frames alone -- is what actually paces emitted audio chunks:
+    with the defaults here, hops are chunk_frames, 2x, 4x, 4x, 4x, ...
+
+    The very first emission is consistently one token short of chunk_frames
+    (confirmed against real speech.audio.delta event sizes) even though the
+    ramp's own progression is computed from the nominal chunk_frames, not the
+    actual first hop -- so only the first yield gets the -1 adjustment.
+    """
+    yield chunk_frames - 1
+    hop = chunk_frames
+    while True:
+        hop = min(max_chunk_frames, max(chunk_frames, hop * STREAM_SCALE_FACTOR))
+        yield hop
+
+
+def one_request(client, url, model, text, ref_audio, ref_text, chunk_frames, seed=None):
+    """Run one streaming request, returning TTFA, E2E, per-chunk gaps, and audio bytes.
+
+    ``response_format=pcm`` + ``stream_format=audio`` streams raw bytes with no
+    framing, so a client read boundary alone is a transport artifact, not a
+    model chunk boundary. Reconstructed instead by replicating the server's
+    own token-hop-length ramp (see ``_token_hop_lengths``) to compute each
+    real chunk's expected byte size ahead of time, and slicing the
+    accumulated byte stream at those offsets -- independent of how the
+    transport happens to fragment the underlying reads. The final chunk
+    (finalize, which releases extra held-back frames) is whatever remains
+    when the stream closes, not a predicted hop.
+    """
+    payload = {
+        "model": model,
+        "input": text,
+        "response_format": "pcm",
+        "stream": True,
+        "stream_format": "audio",
+        "ref_audio": ref_audio,
+        "ref_text": ref_text,
+    }
+    if seed is not None:
+        payload["seed"] = seed
+    t0 = time.perf_counter()
+    ttfa = None
+    nbytes = 0
+    audio_bytes = bytearray()
+    chunk_gaps_ms = []  # inter-chunk arrival gaps (per model chunk), by step index
+    prev_t = None
+    step_idx = 0
+
+    bytes_per_token = TOKEN_MEL_RATIO * SAMPLES_PER_MEL * 2
+    hop_gen = _token_hop_lengths(chunk_frames, 4 * chunk_frames)
+    next_boundary = next(hop_gen) * bytes_per_token
+    last_crossed_bytes = 0
+    received = 0
+    last_now = t0
+
+    with client.stream("POST", f"{url}/v1/audio/speech", json=payload, headers={"Authorization": "Bearer EMPTY"}) as r:
+        if r.status_code != 200:
+            raise RuntimeError(f"{r.status_code}: {r.read()[:300]!r}")
+        for chunk in r.iter_bytes():
+            if not chunk:
+                continue
+            now = time.perf_counter()
+            if ttfa is None:
+                ttfa = now - t0
+            last_now = now
+            received += len(chunk)
+            nbytes += len(chunk)
+            audio_bytes += chunk
+            while received >= next_boundary:
+                if prev_t is not None:
+                    chunk_gaps_ms.append((step_idx, (now - prev_t) * 1e3))
+                    step_idx += 1
+                prev_t = now
+                last_crossed_bytes = next_boundary
+                next_boundary += next(hop_gen) * bytes_per_token
+
+    if received > last_crossed_bytes:
+        # Finalize chunk: releases extra held-back frames, so it doesn't
+        # match a predicted hop size -- its arrival is the stream closing.
+        if prev_t is not None:
+            chunk_gaps_ms.append((step_idx, (last_now - prev_t) * 1e3))
+            step_idx += 1
+
+    e2e = time.perf_counter() - t0
+    audio_s = nbytes / 2 / SAMPLE_RATE
+    return {
+        "ttfa_s": ttfa,
+        "e2e_s": e2e,
+        "audio_s": audio_s,
+        "rtf": e2e / audio_s if audio_s > 0 else float("nan"),
+        "chunk_gaps_ms": chunk_gaps_ms,
+        "nbytes": nbytes,
+        "audio_bytes": audio_bytes,
+    }
+
+
+def check_correctness(r: dict, min_audio_s: float) -> list[str]:
+    """Return a list of correctness violations (empty = pass)."""
+    problems = []
+    if r["nbytes"] <= 0:
+        problems.append("empty audio (0 bytes)")
+    if r["audio_s"] < min_audio_s:
+        problems.append(f"audio too short ({r['audio_s']:.2f}s < {min_audio_s:.2f}s)")
+    if r["nbytes"] > 0:
+        samples = np.frombuffer(bytes(r["audio_bytes"]), dtype=np.int16).astype(np.float64)
+        rms = float(np.sqrt(np.mean(samples**2)))
+        if rms < MIN_RMS:
+            problems.append(f"near-silent audio (rms={rms:.1f} < {MIN_RMS})")
+    return problems
+
+
+def drive(url, args, n, conc, label, results, lock, idx, chunk_frames):
+    """Run ``n`` requests at concurrency ``conc``, cycling through ``args.texts``."""
+    texts = args.texts
+
+    def worker():
+        with httpx.Client(timeout=600.0) as c:
+            while True:
+                with lock:
+                    i = idx[0]
+                    idx[0] += 1
+                if i >= n:
+                    return
+                text = texts[i % len(texts)]
+                try:
+                    r = one_request(
+                        c, url, args.model, text, args.ref_audio, args.ref_text, chunk_frames, seed=args.seed
+                    )
+                    r["text"] = text
+                    with lock:
+                        results.append(r)
+                except Exception as e:
+                    print(f"    [{label}] request {i} failed: {e}", flush=True)
+
+    ts = [threading.Thread(target=worker) for _ in range(conc)]
+    t0 = time.perf_counter()
+    for t in ts:
+        t.start()
+    for t in ts:
+        t.join()
+    return time.perf_counter() - t0
+
+
+def run_combo(args, conc: int, chunk_frames: int, out: Path) -> dict:
+    tag = f"c{conc}_chunk{chunk_frames}"
+    run_dir = out / tag
+    run_dir.mkdir(parents=True, exist_ok=True)
+    log = run_dir / "server.log"
+
+    deploy = REPO / "vllm_omni/deploy" / f"_autogen_steps_{tag}.yaml"
+    deploy.write_text(
+        DEPLOY_TEMPLATE.format(
+            chunk_frames=chunk_frames,
+            max_chunk_frames=4 * chunk_frames,
+            stream_scale_factor=STREAM_SCALE_FACTOR,
+        )
+    )
+
+    cmd = [
+        vllm_bin(),
+        "serve",
+        args.model,
+        "--omni",
+        "--deploy-config",
+        str(deploy),
+        "--host",
+        "127.0.0.1",
+        "--port",
+        str(args.port),
+        "--allowed-local-media-path",
+        str(REPO),
+    ]
+    env = dict(os.environ)
+    if args.cuda_visible_devices:
+        env["CUDA_VISIBLE_DEVICES"] = args.cuda_visible_devices
+    if args.trt is not None:
+        env["COSYVOICE3_TRT"] = args.trt
+
+    print(f"\n=== concurrency={conc} step_size={chunk_frames} ===", flush=True)
+    print(f"  launching server (log: {log})", flush=True)
+    with open(log, "w") as lf:
+        proc = subprocess.Popen(cmd, env=env, stdout=lf, stderr=subprocess.STDOUT, start_new_session=True)
+    url = f"http://127.0.0.1:{args.port}"
+    try:
+        wait_ready(url, proc, log, args.server_timeout)
+        print("  server ready", flush=True)
+
+        results: list[dict] = []
+        lock = threading.Lock()
+        idx = [0]
+        if args.warmup:
+            print(f"  warmup ({args.warmup} req)", flush=True)
+            drive(url, args, args.warmup, min(conc, args.warmup), "warmup", results, lock, idx, chunk_frames)
+            results.clear()
+            idx[0] = 0
+
+        print(f"  running {args.num_prompts} req @ concurrency {conc}", flush=True)
+        wall = drive(url, args, args.num_prompts, conc, "bench", results, lock, idx, chunk_frames)
+
+        ok = [r for r in results if r.get("ttfa_s") is not None]
+        problems = []
+        for r in ok:
+            problems += check_correctness(r, args.min_audio_s)
+        # With a fixed seed, same-text requests must produce byte-identical PCM (per text group)
+        if args.seed is not None:
+            by_text: dict[str, bytes] = {}
+            for r in ok:
+                t = r.get("text")
+                ref = by_text.get(t)
+                if ref is None:
+                    by_text[t] = r.get("audio_bytes")
+                elif r.get("audio_bytes") != ref:
+                    problems.append(f"byte-identity violation for text {t!r}: seeded requests produced different PCM")
+        n_ok = len(ok)
+        total_audio_s = sum(r["audio_s"] for r in ok)
+        all_gaps = [g for r in ok for g in r["chunk_gaps_ms"]]  # (step_index, gap_ms) per request
+        gap_vals = [g for _, g in all_gaps]
+
+        # bucket gaps by chunk position within a request, to see any O(n) slope
+        by_idx: dict[int, list[float]] = {}
+        for step_index, g in all_gaps:
+            by_idx.setdefault(step_index, []).append(g)
+        step_latency_by_idx = {i: statistics.median(vals) for i, vals in sorted(by_idx.items())}
+
+        agg = {
+            "concurrency": conc,
+            "step_size": chunk_frames,
+            "ok": n_ok,
+            "errors": args.num_prompts - n_ok,
+            "correctness_problems": len(problems),
+            "correctness_sample": problems[:5],
+            "total_audio_s": total_audio_s,
+            "throughput_audio_s_per_s": total_audio_s / wall if wall > 0 else float("nan"),
+            "ttfa_s": _stats([r["ttfa_s"] for r in ok]),
+            "e2e_s": _stats([r["e2e_s"] for r in ok]),
+            "rtf": _stats([r["rtf"] for r in ok]),
+            "step_latency_ms": _stats(gap_vals),
+            "step_latency_ms_by_idx": step_latency_by_idx,
+            "num_steps": len(all_gaps),
+            # per-utterance-length breakdown; n per text = num_prompts / len(texts)
+            "by_text": {
+                t: {
+                    "audio_s": _stats([r["audio_s"] for r in ok if r.get("text") == t]),
+                    "e2e_s": _stats([r["e2e_s"] for r in ok if r.get("text") == t]),
+                    "rtf": _stats([r["rtf"] for r in ok if r.get("text") == t]),
+                }
+                for t in sorted({r.get("text") for r in ok})
+            },
+        }
+        print(json.dumps(agg, indent=2, ensure_ascii=False), flush=True)
+        return agg
+    finally:
+        print("  shutting down server", flush=True)
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGTERM)
+        except Exception:
+            proc.terminate()
+        try:
+            proc.wait(timeout=60)
+        except subprocess.TimeoutExpired:
+            try:
+                os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+            except Exception:
+                proc.kill()
+            proc.wait(timeout=20)
+        deploy.unlink(missing_ok=True)
+
+
+def parse_args() -> argparse.Namespace:
+    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    p.add_argument("--model", default=DEFAULT_MODEL)
+    p.add_argument(
+        "--text",
+        dest="texts",
+        nargs="+",
+        default=DEFAULT_TEXTS,
+        help="One or more utterance texts. With several, requests cycle through "
+        "them so a single server launch covers all utterance lengths; results "
+        "are bucketed per text.",
+    )
+    p.add_argument("--ref-audio", default=DEFAULT_REF_AUDIO)
+    p.add_argument("--ref-text", default=DEFAULT_REF_TEXT)
+    p.add_argument("--concurrency", type=int, nargs="+", default=[1, 8])
+    p.add_argument(
+        "--step-size",
+        type=int,
+        nargs="+",
+        default=[15],
+        help="codec_chunk_frames values to sweep (the streaming step size).",
+    )
+    p.add_argument("--num-prompts", type=int, default=30)
+    p.add_argument("--warmup", type=int, default=2)
+    p.add_argument("--port", type=int, default=8091)
+    p.add_argument(
+        "--server-timeout",
+        type=float,
+        default=1800.0,
+        help="Startup budget; first run also downloads weights and builds the TRT engine.",
+    )
+    p.add_argument("--output-dir", default="./perf_steps")
+    p.add_argument("--cuda-visible-devices", default="0")
+    p.add_argument(
+        "--trt",
+        choices=["0", "1"],
+        default=None,
+        help="Pin COSYVOICE3_TRT. 0=force torch estimator, 1=allow TensorRT. Default: unset.",
+    )
+    p.add_argument(
+        "--min-audio-s",
+        type=float,
+        default=1.0,
+        help="Minimum expected audio seconds per request for the correctness check.",
+    )
+    p.add_argument(
+        "--seed",
+        type=int,
+        default=42,
+        help="Fixed seed for reproducible (byte-identical) audio. Pass --seed '' "
+        "equivalent (any non-int) to disable -- there is no unset sentinel here "
+        "by design, since the default sweep is meant to be exactly reproducible.",
+    )
+    return p.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    out = Path(args.output_dir).resolve()
+    out.mkdir(parents=True, exist_ok=True)
+
+    all_results = []
+    failed = False
+    for conc in args.concurrency:
+        for chunk_frames in args.step_size:
+            try:
+                result = run_combo(args, conc, chunk_frames, out)
+                all_results.append(result)
+                if result["errors"] > 0 or result["correctness_problems"] > 0:
+                    failed = True
+            except Exception as e:
+                print(f"  combo c={conc} chunk={chunk_frames} FAILED: {e}", flush=True)
+                failed = True
+
+    out_path = out / "steps_results.json"
+    with open(out_path, "w", encoding="utf-8") as f:
+        json.dump({"model": args.model, "texts": args.texts, "runs": all_results}, f, indent=2, ensure_ascii=False)
+    print(f"\nResults written to {out_path}", flush=True)
+
+    print("\n=== SUMMARY ===")
+    header = (
+        f"{'conc':>4} {'step':>4} {'ok':>4} {'corr':>4} "
+        f"{'TTFA med(ms)':>12} {'step med(ms)':>12} {'step p95(ms)':>12} {'RTF mean+-sd':>14}"
+    )
+    print(header)
+    print("-" * len(header))
+    for r in all_results:
+        print(
+            f"{r['concurrency']:>4} {r['step_size']:>4} {r['ok']:>4} {r['correctness_problems']:>4} "
+            f"{r['ttfa_s']['median'] * 1e3:>12.1f} "
+            f"{r['step_latency_ms']['median']:>12.1f} {r['step_latency_ms']['p95']:>12.1f} "
+            f"{r['rtf']['mean']:>6.3f}+-{r['rtf']['stdev']:>5.3f}"
+        )
+        for t, stats in r.get("by_text", {}).items():
+            print(
+                f"      text {t[:24]!r}: e2e {stats['e2e_s']['mean'] * 1e3:8.1f}"
+                f"+-{stats['e2e_s']['stdev'] * 1e3:6.1f} ms  (n={stats['e2e_s']['n']}, "
+                f"audio {stats['audio_s']['mean']:.1f}s)"
+            )
+
+    if failed:
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/pyproject.toml b/pyproject.toml
index 434c4305c40..c463d391701 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -66,14 +66,12 @@ dev = [
     "jiwer==4.0.0",
     "zhon==2.1.1",
     "zhconv==1.4.3",
-    "scipy==1.18.0",
     "funasr==1.3.29",
     "lpips==0.1.4", # for quantization fp8
     "orjson==3.11.9", # to make v1/embeddings API fast
     "voxcpm==2.0.3", # for VoxCPM2 path-locating in tests
     "torchdiffeq==0.2.5", # for covo_audio Test
     "FlagEmbedding==1.4.0", # for hunyuan_image3 tests
-    "s3tokenizer==0.3.0", # for tts test
     # Provides top-level cosyvoice2; do not co-install stepaudio2-minicpmo,
     # whose top-level stepaudio2 package conflicts with this distribution.
     "step-audio2==1.0.0", # Step-Audio2 / MiniCPM-o 4.5 Token2Wav (flashcosyvoice / hyperpyyaml)
diff --git a/requirements/common.txt b/requirements/common.txt
index 855fb6b0a30..d7b845e32ba 100644
--- a/requirements/common.txt
+++ b/requirements/common.txt
@@ -41,3 +41,8 @@ pydantic-settings>=2.0.0
 gguf>=0.10.0
 # Required for running the Cosmos3 model with guardrails enabled (default behavior).
 cosmos-guardrail>=0.3.1
+# Required for CosyVoice3 (get_window/resample_poly). >=1.18.0 requires
+# Python >=3.12, breaking base installs on the project's supported 3.10/3.11;
+# these are long-stable APIs with no version-specific need for 1.18.
+scipy>=1.11.0
+s3tokenizer==0.3.0
diff --git a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
index 7dfbe6e741f..74fc5059bcd 100644
--- a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
+++ b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
@@ -15,6 +15,7 @@
 from vllm_omni.diffusion.data import AttentionConfig
 from vllm_omni.model_executor.models.cosyvoice3.code2wav_core.hifigan import (
     CausalHiFTGenerator,
+    HiFTGenerator,
 )
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
@@ -76,6 +77,39 @@ def test_causal_hift_stft_moves_window_to_input_device(causal_hift):
     assert causal_hift.stft_window.device == waveform.device
 
 
+class _MinimalF0Predictor(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+        self.proj = nn.Conv1d(80, 1, 1)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.proj(x).squeeze(1).abs()
+
+
+@pytest.mark.parametrize("sampling_rate", [22050, 24000])
+def test_noncausal_hift_inference_runs_with_real_sinegen(sampling_rate):
+    """Base (non-causal) HiFTGenerator with a real SineGen/SineGen2 (not a
+    test double) must still run: SourceModuleHnNSF/SineGen/SineGen2/_f02sine
+    all branch on `self.causal` to return the pre-streaming (shorter) tuple
+    contract for non-causal callers, and any one of them regressing back to
+    always returning the streaming-length tuple breaks this immediately.
+    """
+    hift = HiFTGenerator(
+        base_channels=32,
+        sampling_rate=sampling_rate,
+        upsample_rates=[8, 5, 3],
+        upsample_kernel_sizes=[16, 11, 7],
+        source_resblock_kernel_sizes=[7, 7, 11],
+        source_resblock_dilation_sizes=[[1, 3, 5]] * 3,
+        f0_predictor=_MinimalF0Predictor(),
+    ).eval()
+
+    speech, _ = hift.inference(torch.randn(1, 80, 20))
+
+    assert speech.shape[0] == 1
+    assert torch.isfinite(speech).all()
+
+
 def test_causal_hift_routes_npu_transforms_to_cpu_fallback(causal_hift, monkeypatch):
     class NpuTensor:
         device = SimpleNamespace(type="npu")
@@ -83,16 +117,17 @@ class NpuTensor:
     tensor = NpuTensor()
     stft_calls = []
     istft_calls = []
-    monkeypatch.setattr(
-        causal_hift,
-        "_stft_on_cpu",
-        lambda value: stft_calls.append(value) or ("real", "imag"),
-    )
-    monkeypatch.setattr(
-        causal_hift,
-        "_istft_on_cpu",
-        lambda magnitude, phase: istft_calls.append((magnitude, phase)) or "waveform",
-    )
+
+    def fake_stft(value):
+        stft_calls.append(value)
+        return ("real", "imag")
+
+    def fake_istft(magnitude, phase):
+        istft_calls.append((magnitude, phase))
+        return "waveform"
+
+    monkeypatch.setattr(causal_hift, "_stft_on_cpu", fake_stft)
+    monkeypatch.setattr(causal_hift, "_istft_on_cpu", fake_istft)
 
     assert causal_hift._stft(tensor) == ("real", "imag")
     assert causal_hift._istft(tensor, tensor) == "waveform"
@@ -627,7 +662,11 @@ def __init__(self):
 
         def inference(self, speech_feat, finalize=True):
             self.finalize_calls.append(bool(finalize))
-            return torch.zeros((speech_feat.shape[0], 1, speech_feat.shape[-1]), dtype=speech_feat.dtype), None
+            return (
+                torch.zeros((speech_feat.shape[0], 1, speech_feat.shape[-1]), dtype=speech_feat.dtype),
+                None,
+                None,
+            )
 
     model = object.__new__(CosyVoice3Code2Wav)
     nn.Module.__init__(model)
diff --git a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_incremental_hift.py b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_incremental_hift.py
new file mode 100644
index 00000000000..1e8eff599a8
--- /dev/null
+++ b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_incremental_hift.py
@@ -0,0 +1,415 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Correctness + boundedness tests for the incremental (windowed) HiFT path.
+
+The streaming vocoder runs HiFT over a bounded mel window instead of the full
+cumulative history, carrying harmonic phase and noise-buffer offset across
+chunks.
+
+* **Correctness** — windowed output must match the full cumulative re-run.
+  With full history the match is bit-exact (proves the phase/noise carry is
+  right). With a bounded window, float64 still agrees to ~1e-16 (the window
+  is algebraically exact); float32 differs by ~2e-7 absolute (reassociation
+  rounding, not truncation), so tests assert a tight atol/rtol rather than
+  PCM16 byte-identity, since a sub-LSB perturbation can flip a boundary sample.
+* **Boundedness** — the per-chunk window must not grow with mel history.
+
+Tests are parametrized across REAL_CONFIG (24000 Hz -> SineGen2, what
+CosyVoice3 ships) and LEGACY_CONFIG (22050 Hz -> SineGen) so a class-selection
+regression in either path is caught.
+"""
+
+import pytest
+import torch
+import torch.nn as nn
+
+from vllm_omni.model_executor.models.cosyvoice3.code2wav_core.hifigan import (
+    CausalConvRNNF0Predictor,
+    CausalHiFTGenerator,
+    SineGen,
+    SineGen2,
+    _wrapped_slice,
+)
+from vllm_omni.model_executor.models.cosyvoice3.cosyvoice3_code2wav import CosyVoice3Code2Wav
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+CHUNK_LEN = 24
+TOTAL_MEL = 96
+SPM = 480  # samples per mel frame for the small test HiFT (8*5*3*4), matching the real model
+
+LONG_TOTAL_MEL = 400  # long enough that the 64-frame window actually truncates
+PCM16_LSB = 1.0 / 32767.0  # smallest representable PCM16 difference
+
+# Worst observed deviation is 1.97e-7 (~2x float32 eps); atol=1e-6 keeps 5x headroom.
+ATOL = 1e-6
+RTOL = 1e-5
+
+# What CosyVoice3 ships (-> SineGen2). nb_harmonics=8 is required, not a free
+# choice: SineGen2's causal buffers are hardcoded to dim 9 (= harmonic_num+1).
+REAL_CONFIG = {"sampling_rate": 24000, "nb_harmonics": 8}
+LEGACY_CONFIG = {"sampling_rate": 22050, "nb_harmonics": 4}  # -> SineGen, still shipped code
+
+CONFIGS = [
+    pytest.param(REAL_CONFIG, id="sinegen2_real_config"),
+    pytest.param(LEGACY_CONFIG, id="sinegen1_legacy_config"),
+]
+
+
+def _make_hift(config: dict = REAL_CONFIG) -> CausalHiFTGenerator:
+    """Small CausalHiFTGenerator; defaults to the config CosyVoice3 ships."""
+    torch.manual_seed(0)
+    f0_predictor = CausalConvRNNF0Predictor(num_class=1, in_channels=80, cond_channels=16)
+    return CausalHiFTGenerator(
+        in_channels=80,
+        base_channels=32,
+        nb_harmonics=config["nb_harmonics"],
+        sampling_rate=config["sampling_rate"],
+        upsample_rates=[8, 5, 3],
+        upsample_kernel_sizes=[16, 11, 7],
+        source_resblock_kernel_sizes=[7, 7, 11],
+        source_resblock_dilation_sizes=[[1, 3, 5], [1, 3, 5], [1, 3, 5]],
+        resblock_kernel_sizes=[3, 7, 11],
+        resblock_dilation_sizes=[[1, 3, 5], [1, 3, 5], [1, 3, 5]],
+        f0_predictor=f0_predictor,
+    ).eval()
+
+
+def test_real_config_resolves_to_sinegen2():
+    """Guard against silently testing the wrong SineGen class again."""
+    hift = _make_hift(REAL_CONFIG)
+    assert isinstance(hift.m_source.l_sin_gen, SineGen2)
+
+    hift_legacy = _make_hift(LEGACY_CONFIG)
+    assert isinstance(hift_legacy.m_source.l_sin_gen, SineGen)
+
+
+def _make_model(hift: CausalHiFTGenerator, window_len: int) -> CosyVoice3Code2Wav:
+    """Build a CosyVoice3Code2Wav shell wired to the given HiFT."""
+    model = object.__new__(CosyVoice3Code2Wav)
+    nn.Module.__init__(model)
+    model.hift = hift
+    model._hift_window_len = window_len
+    return model
+
+
+def _chunks(total_mel: int = TOTAL_MEL, chunk_len: int = CHUNK_LEN) -> list[torch.Tensor]:
+    torch.manual_seed(1)
+    mel = torch.randn(1, 80, total_mel)
+    return [mel[:, :, i : i + chunk_len] for i in range(0, total_mel, chunk_len)]
+
+
+def _variable_chunks(total_mel: int, first_len: int, step_len: int) -> list[torch.Tensor]:
+    """First chunk sized like a real prompt prefill, then small fixed-size steps."""
+    torch.manual_seed(1)
+    mel = torch.randn(1, 80, total_mel)
+    chunks = [mel[:, :, :first_len]]
+    pos = first_len
+    while pos < total_mel:
+        chunks.append(mel[:, :, pos : pos + step_len])
+        pos += step_len
+    return chunks
+
+
+def _full_reference(model: CosyVoice3Code2Wav, chunks: list[torch.Tensor]) -> torch.Tensor:
+    """Re-run HiFT over the full cumulative mel each chunk (pre-windowing behavior).
+
+    Uses non-finalize inference per chunk, matching the old streaming vocoder; a
+    single finalize pass would emit the look-right tail streaming holds back.
+    """
+    torch.manual_seed(0)
+    emitted = []
+    cache: dict[str, torch.Tensor] | None = None
+    for chunk in chunks:
+        cached = None if cache is None else cache.get("mel")
+        if cached is not None and cached.numel() > 0:
+            tts_mel = torch.cat([cached, chunk], dim=-1)
+        else:
+            tts_mel = chunk
+        speech, _, _ = model.hift.inference(speech_feat=tts_mel, finalize=False)
+        speech = speech.reshape(speech.shape[0], -1)
+        offset = 0 if cache is None else cache.get("speech_offset")
+        emitted.append(speech[:, offset:])
+        cache = {"mel": tts_mel.detach().cpu(), "speech_offset": int(speech.shape[-1])}
+    return torch.cat(emitted, dim=-1)
+
+
+def _pcm16(x: torch.Tensor) -> torch.Tensor:
+    """Quantize float audio to PCM16, the format the server streams to clients."""
+    return (x.clamp(-1, 1) * 32767).round().to(torch.int16)
+
+
+def _incremental(model: CosyVoice3Code2Wav, chunks: list[torch.Tensor]) -> torch.Tensor:
+    """Run the new windowed path via _stream_hift_from_feat."""
+    torch.manual_seed(0)
+    emitted = []
+    cache: dict[str, torch.Tensor] | None = None
+    for chunk in chunks:
+        speech, cache = model._stream_hift_from_feat(chunk, cache_state=cache, finalize=False)
+        emitted.append(speech.reshape(speech.shape[0], -1))
+    return torch.cat(emitted, dim=-1)
+
+
+def _rel_divergence(a: torch.Tensor, b: torch.Tensor) -> float:
+    return ((a - b).abs().mean() / a.abs().mean().clamp_min(1e-6)).item()
+
+
+@pytest.mark.parametrize("config", CONFIGS)
+def test_incremental_hift_matches_full_reference_exactly_with_full_history(config):
+    """With a window covering the full history, the windowed path must match the
+    full cumulative re-run exactly. This proves the phase/noise carry is right."""
+    hift = _make_hift(config)
+    model = _make_model(hift, window_len=TOTAL_MEL)  # window >= history
+    chunks = _chunks()
+
+    full = _full_reference(model, chunks)
+    incr = _incremental(model, chunks)
+
+    assert full.shape == incr.shape, f"{full.shape} vs {incr.shape}"
+    assert _rel_divergence(full, incr) < 1e-6
+
+
+@pytest.mark.parametrize("config", CONFIGS)
+def test_incremental_hift_bounded_window_is_close(config):
+    """With a bounded window, the windowed path stays close to the full re-run;
+    only the truncated deep history diverges, and it is small."""
+    hift = _make_hift(config)
+    model = _make_model(hift, window_len=48)
+    chunks = _chunks()
+
+    full = _full_reference(model, chunks)
+    incr = _incremental(model, chunks)
+
+    assert full.shape == incr.shape
+    torch.testing.assert_close(incr, full, atol=ATOL, rtol=RTOL)
+
+
+@pytest.mark.parametrize("config", CONFIGS)
+def test_incremental_hift_matches_streaming_reference_within_tolerance(config):
+    """Windowed output matches the full-cumulative reference within float32 rounding.
+
+    The load-bearing correctness test: 400 mel frames far exceeds the 64-frame
+    window, so truncation genuinely exercises the phase/noise carry. Float64
+    agrees to ~1e-16, confirming the residual here is rounding, not truncation.
+    """
+    hift = _make_hift(config)
+    model = _make_model(hift, window_len=64)  # the real _hift_window_len
+    chunks = _chunks(total_mel=LONG_TOTAL_MEL)
+
+    trim = int(hift.f0_predictor.condnet[0].causal_padding)
+    assert LONG_TOTAL_MEL > 64 + trim + CHUNK_LEN  # window must actually truncate
+
+    full = _full_reference(model, chunks)
+    incr = _incremental(model, chunks)
+
+    assert full.shape == incr.shape, f"{full.shape} vs {incr.shape}"
+    torch.testing.assert_close(incr, full, atol=ATOL, rtol=RTOL)
+
+    max_dev = (full - incr).abs().max().item()  # stays far below one PCM16 step
+    assert max_dev < PCM16_LSB / 10, f"max deviation {max_dev:.3e} vs PCM16 LSB {PCM16_LSB:.3e}"
+
+
+def test_incremental_hift_window_is_bounded():
+    """Per-chunk window must not grow with cumulative mel history."""
+    hift = _make_hift()
+    model = _make_model(hift, window_len=32)
+    chunks = _chunks(total_mel=200, chunk_len=24)
+
+    trim = int(hift.f0_predictor.condnet[0].causal_padding)
+    f0_margin = int(hift.f0_predictor.left_context_frames)
+
+    cache = None
+    window_sizes = []
+    for chunk in chunks:
+        _, cache = model._stream_hift_from_feat(chunk, cache_state=cache, finalize=False)
+        window_sizes.append(int(cache["mel"].shape[-1]))
+
+    assert max(window_sizes) <= 32 + trim + f0_margin + 24  # bounded regardless of utterance length
+    steady = max(window_sizes)
+    assert window_sizes.count(steady) >= 2  # steady-state value repeats once history exceeds window
+
+
+def test_incremental_hift_finalize_releases_tail():
+    """Finalize must emit the released look-right tail without crashing."""
+    hift = _make_hift()
+    model = _make_model(hift, window_len=32)
+    chunks = _chunks(total_mel=72, chunk_len=24)
+
+    cache = None
+    emitted = []
+    for i, chunk in enumerate(chunks):
+        finalize = i == len(chunks) - 1
+        speech, cache = model._stream_hift_from_feat(chunk, cache_state=cache, finalize=finalize)
+        emitted.append(speech.reshape(speech.shape[0], -1))
+        if finalize:
+            assert cache is None
+
+    full = torch.cat(emitted, dim=-1)
+    assert full.shape[-1] > 0
+    assert torch.isfinite(full).all()
+
+
+def test_incremental_hift_emits_full_audio_length():
+    """Streamed output covers the full mel history at samples-per-mel resolution.
+
+    Guards against emission arithmetic dropping an upsample stage, which
+    silently truncates audio (e.g. 1/3 of expected length with [8,5,3]).
+    """
+    hift = _make_hift()
+    model = _make_model(hift, window_len=32)
+    chunks = _chunks(total_mel=72, chunk_len=24)
+
+    cache = None
+    emitted = []
+    for i, chunk in enumerate(chunks):
+        finalize = i == len(chunks) - 1
+        speech, cache = model._stream_hift_from_feat(chunk, cache_state=cache, finalize=finalize)
+        emitted.append(speech.reshape(speech.shape[0], -1))
+        if finalize:
+            assert cache is None
+
+    full = torch.cat(emitted, dim=-1)
+    # total_mel * SPM, +slack for finalize's look-right tail, -slack for a dropped upsample stage
+    total_mel = sum(c.shape[-1] for c in chunks)
+    assert full.shape[-1] > total_mel * SPM * 0.8, f"{full.shape[-1]} vs {total_mel * SPM}"
+    assert full.shape[-1] < total_mel * SPM * 1.5, f"{full.shape[-1]} vs {total_mel * SPM}"
+
+
+@pytest.mark.parametrize("config", CONFIGS)
+def test_finalize_matches_single_pass_length_exactly(config):
+    """Streamed total (chunked, last=finalize) must exactly match a single
+    non-streaming finalize=True call over the whole mel -- not just approximately.
+
+    The finalize release must include `trim` (the F0 predictor's own held-back
+    frames), or the last 3 mel frames (1,440 samples / 60ms at 24kHz) of every
+    stream's audio go missing.
+    """
+    hift = _make_hift(config)
+    chunks = _chunks(total_mel=200, chunk_len=24)
+
+    torch.manual_seed(0)
+    full_mel = torch.cat(chunks, dim=-1)
+    ground_truth, _, _ = hift.inference(speech_feat=full_mel, finalize=True)
+    ground_truth = ground_truth.reshape(ground_truth.shape[0], -1)
+
+    hift2 = _make_hift(config)
+    model = _make_model(hift2, window_len=64)
+    torch.manual_seed(0)
+    cache = None
+    emitted = []
+    for i, chunk in enumerate(chunks):
+        finalize = i == len(chunks) - 1
+        speech, cache = model._stream_hift_from_feat(chunk, cache_state=cache, finalize=finalize)
+        emitted.append(speech.reshape(speech.shape[0], -1))
+    streamed = torch.cat(emitted, dim=-1)
+
+    assert streamed.shape[-1] == ground_truth.shape[-1], (
+        f"{streamed.shape[-1]} vs {ground_truth.shape[-1]} (diff={ground_truth.shape[-1] - streamed.shape[-1]} samples)"
+    )
+    torch.testing.assert_close(streamed, ground_truth, atol=ATOL, rtol=RTOL)
+
+
+@pytest.mark.parametrize("config", CONFIGS)
+def test_incremental_hift_matches_reference_for_voiced_f0(config):
+    """Forces F0 above nsf_voiced_threshold (untrained weights never trigger voiced,
+    so no other test here does) and checks windowed output against the full-
+    cumulative reference, which exercises condnet's left-causal convs and
+    SineGen/SineGen2's phase integration under genuinely voiced harmonics.
+
+    Tolerance is looser than ATOL/RTOL: summing this sustained constant-F0 phase
+    in per-window chunks vs. one recompute reassociates float32 adds differently;
+    real speech's varying/unvoiced F0 keeps this far smaller in practice.
+    """
+    hift = _make_hift(config)
+    with torch.no_grad():
+        hift.f0_predictor.classifier.bias.fill_(150.0)  # clearly voiced (threshold is 10)
+    chunks = _chunks(total_mel=200, chunk_len=24)
+
+    full = _full_reference(_make_model(hift, window_len=400), chunks)
+    incr = _incremental(_make_model(hift, window_len=64), chunks)
+
+    assert full.shape == incr.shape
+    torch.testing.assert_close(incr, full, atol=2e-4, rtol=2e-4)
+
+
+@pytest.mark.parametrize("config", CONFIGS)
+@pytest.mark.parametrize("first_len,step_len", [(10, 6), (10, 3), (20, 3), (10, 1)])
+def test_incremental_hift_matches_reference_for_voiced_f0_small_chunks(config, first_len, step_len):
+    """Same as test_incremental_hift_matches_reference_for_voiced_f0, but with small,
+    sub-receptive-field chunk sizes (down to 1 mel frame) instead of the uniform
+    24-frame chunks used elsewhere. cache_state must carry the F0 predictor's own
+    left receptive field across calls regardless of how small a single chunk is,
+    or the next call's margin comes up short and substitutes zero-padding for real
+    history -- corrupting SineGen's phase integration the same way as an absent
+    margin entirely.
+    """
+    hift = _make_hift(config)
+    with torch.no_grad():
+        hift.f0_predictor.classifier.bias.fill_(150.0)  # clearly voiced (threshold is 10)
+    chunks = _variable_chunks(total_mel=200, first_len=first_len, step_len=step_len)
+
+    full = _full_reference(_make_model(hift, window_len=400), chunks)
+    incr = _incremental(_make_model(hift, window_len=64), chunks)
+
+    assert full.shape == incr.shape
+    torch.testing.assert_close(incr, full, atol=2e-4, rtol=2e-4)
+
+
+def test_wrapped_slice_wraps_position_deterministically():
+    """SineGen/SineGen2/SourceModuleHnNSF's noise buffers are a fixed 300s at
+    24kHz; a stream running past that must keep repeating the realization
+    (position-deterministic) rather than the slice coming back short and
+    failing to broadcast against the rest of that call's tensors.
+    """
+    buf = torch.arange(10).reshape(1, 10, 1)
+
+    assert _wrapped_slice(buf, 2, 3).flatten().tolist() == [2, 3, 4]
+    assert _wrapped_slice(buf, 8, 4).flatten().tolist() == [8, 9, 0, 1]
+    assert _wrapped_slice(buf, 12, 3).flatten().tolist() == [2, 3, 4]  # offset past the end
+    assert _wrapped_slice(buf, 5, 13).flatten().tolist() == [5, 6, 7, 8, 9, 0, 1, 2, 3, 4, 5, 6, 7]
+
+
+def test_incremental_hift_empty_middle_chunk_emits_nothing():
+    """An empty middle chunk (reachable from forward_streaming_batch when a
+    row's post-trim feat comes out empty near the lookahead boundary) must
+    emit zero samples and leave cache_state's phase_acc unchanged, not
+    re-emit the re-decoded overlap window as if it were new audio.
+    """
+    hift = _make_hift(REAL_CONFIG)
+    model = _make_model(hift, window_len=64)
+    chunks = _chunks(total_mel=96, chunk_len=24)
+    empty = chunks[0][:, :, :0]
+
+    cache = None
+    for chunk in chunks[:2]:
+        _, cache = model._stream_hift_from_feat(chunk, cache_state=cache, finalize=False)
+    assert cache is not None
+    phase_acc_before = cache["phase_acc"]
+
+    speech, cache = model._stream_hift_from_feat(empty, cache_state=cache, finalize=False)
+
+    assert speech.shape[-1] == 0
+    if phase_acc_before is None:
+        assert cache["phase_acc"] is None
+    else:
+        torch.testing.assert_close(cache["phase_acc"], phase_acc_before)
+
+
+@pytest.mark.parametrize("config", CONFIGS)
+@pytest.mark.parametrize("mel_frames", [1, 2, 3, 4])
+def test_incremental_hift_short_finalize_chunk_does_not_crash(config, mel_frames):
+    """A one-token (or otherwise sub-trim) utterance that finalizes on its very
+    first chunk must not crash. On finalize the F0 predictor consumes the whole
+    window (it does not hold back `trim` frames), so the phase-carry index must
+    not be inflated by `trim` -- it would point past the end of a short window.
+    """
+    hift = _make_hift(config)
+    model = _make_model(hift, window_len=32)
+    chunk = torch.randn(1, 80, mel_frames)
+
+    speech, cache = model._stream_hift_from_feat(chunk, cache_state=None, finalize=True)
+
+    assert cache is None
+    assert speech.shape[0] == 1
+    assert speech.shape[-1] > 0
+    assert torch.isfinite(speech).all()
diff --git a/tests/model_executor/models/minicpmo_4_5/test_cuda_graph_wrapper.py b/tests/model_executor/models/minicpmo_4_5/test_cuda_graph_wrapper.py
index 959156b8fc2..555e72e4660 100644
--- a/tests/model_executor/models/minicpmo_4_5/test_cuda_graph_wrapper.py
+++ b/tests/model_executor/models/minicpmo_4_5/test_cuda_graph_wrapper.py
@@ -177,6 +177,8 @@ def blocks_forward_chunk(
         cnn_cache_buffer: torch.Tensor | None = None,
         att_cache_buffer: torch.Tensor | None = None,
     ) -> torch.Tensor:
+        assert cnn_cache_buffer is not None
+        assert att_cache_buffer is not None
         x = x.transpose(1, 2)
         x = self.in_proj(x)
         for b_idx in range(len(self.blocks)):
diff --git a/vllm_omni/model_executor/models/cosyvoice3/code2wav_core/hifigan.py b/vllm_omni/model_executor/models/cosyvoice3/code2wav_core/hifigan.py
index 7cbd31e9ccd..2b8f3e61e24 100644
--- a/vllm_omni/model_executor/models/cosyvoice3/code2wav_core/hifigan.py
+++ b/vllm_omni/model_executor/models/cosyvoice3/code2wav_core/hifigan.py
@@ -98,6 +98,46 @@ def remove_weight_norm(self):
             remove_weight_norm(self.convs2[idx])
 
 
+def _carry_phase_at_boundary(
+    cum_total: torch.Tensor,
+    phase_acc: torch.Tensor | None,
+    next_overlap: int,
+    *,
+    dim: int,
+    trim: int = 0,
+) -> torch.Tensor | None:
+    """Accumulated phase (mod 1) carried into the next streaming window.
+
+    Shared by SineGen and SineGen2 so harmonic phase stays continuous across
+    chunk boundaries when HiFT runs over a bounded mel window. ``cum_total``
+    must already include ``phase_acc``; falls back to it unchanged if
+    ``next_overlap`` (+ ``trim``) covers the whole window.
+    """
+    length = cum_total.shape[dim]
+    if next_overlap >= length + trim:
+        return phase_acc
+    idx = length + trim - next_overlap - 1
+    return cum_total.narrow(dim, idx, 1) % 1
+
+
+def _wrapped_slice(buf: torch.Tensor, offset: int, length: int, dim: int = 1) -> torch.Tensor:
+    """``length`` elements of ``buf`` along ``dim`` starting at ``offset``,
+    wrapping (mod ``buf.shape[dim]``) instead of running past the end and
+    coming back short. Shared by SineGen/SineGen2/SourceModuleHnNSF's
+    position-indexed noise buffers, now that streams can outlast their 300s.
+    """
+    n = buf.shape[dim]
+    start = offset % n
+    parts = []
+    remaining = length
+    while remaining > 0:
+        take = min(remaining, n - start)
+        parts.append(buf.narrow(dim, start, take))
+        remaining -= take
+        start = 0
+    return parts[0] if len(parts) == 1 else torch.cat(parts, dim=dim)
+
+
 class SineGen(torch.nn.Module):
     """Definition of sine generator
     SineGen(samp_rate, harmonic_num = 0,
@@ -114,13 +154,24 @@ class SineGen(torch.nn.Module):
         segment is always sin(np.pi) or cos(0)
     """
 
-    def __init__(self, samp_rate, harmonic_num=0, sine_amp=0.1, noise_std=0.003, voiced_threshold=0):
+    def __init__(self, samp_rate, harmonic_num=0, sine_amp=0.1, noise_std=0.003, voiced_threshold=0, causal=False):
         super().__init__()
         self.sine_amp = sine_amp
         self.noise_std = noise_std
         self.harmonic_num = harmonic_num
         self.sampling_rate = samp_rate
         self.voiced_threshold = voiced_threshold
+        self.causal = causal
+        # Fixed per model instance like SineGen2's rand_ini, not redrawn per
+        # call, or each harmonic jumps to a new random phase every window.
+        self.phase_vec = Uniform(low=-np.pi, high=np.pi).sample(sample_shape=(1, harmonic_num + 1, 1))
+        self.phase_vec[:, 0, :] = 0
+        if causal:
+            self.register_buffer(
+                "noise_buf",
+                torch.randn(1, 300 * 24000, harmonic_num + 1),
+                persistent=False,
+            )
 
     def _f02uv(self, f0):
         # generate uv signal
@@ -128,22 +179,32 @@ def _f02uv(self, f0):
         return uv
 
     @torch.no_grad()
-    def forward(self, f0):
+    def forward(self, f0, phase_acc=None, next_overlap=0, trim=0, noise_offset=0):
         """sine_tensor, uv = forward(f0)
         input F0: tensor(batchsize=1, dim=1, length)
                   f0 for unvoiced steps should be 0
         output sine_tensor: tensor(batchsize=1, length, dim)
         output uv: tensor(batchsize=1, length, 1)
+
+        ``next_overlap`` and ``trim`` are sample-indexed here (``f0`` arrives
+        post-``f0_upsamp``), unlike SineGen2 which downsamples to mel rate
+        before its own cumsum -- callers must scale both by samples-per-mel.
         """
         f0 = f0.transpose(1, 2)
         F_mat = torch.zeros((f0.size(0), self.harmonic_num + 1, f0.size(-1))).to(f0.device)
         for i in range(self.harmonic_num + 1):
             F_mat[:, i : i + 1, :] = f0 * (i + 1) / self.sampling_rate
 
-        theta_mat = 2 * np.pi * (torch.cumsum(F_mat, dim=-1) % 1)
-        u_dist = Uniform(low=-np.pi, high=np.pi)
-        phase_vec = u_dist.sample(sample_shape=(f0.size(0), self.harmonic_num + 1, 1)).to(F_mat.device)
-        phase_vec[:, 0, :] = 0
+        cum = torch.cumsum(F_mat, dim=-1)
+        cum_total = cum if phase_acc is None else phase_acc + cum
+        theta_mat = 2 * np.pi * (cum_total % 1)
+        new_phase_acc = _carry_phase_at_boundary(cum_total, phase_acc, next_overlap, dim=-1, trim=trim)
+        if self.causal:
+            phase_vec = self.phase_vec.to(F_mat.device)
+        else:
+            u_dist = Uniform(low=-np.pi, high=np.pi)
+            phase_vec = u_dist.sample(sample_shape=(f0.size(0), self.harmonic_num + 1, 1)).to(F_mat.device)
+            phase_vec[:, 0, :] = 0
 
         # generate sine waveforms
         sine_waves = self.sine_amp * torch.sin(theta_mat + phase_vec)
@@ -155,11 +216,16 @@ def forward(self, f0):
         #        std = self.sine_amp/3 -> max value ~ self.sine_amp
         # .       for voiced regions is self.noise_std
         noise_amp = uv * self.noise_std + (1 - uv) * self.sine_amp / 3
-        noise = noise_amp * torch.randn_like(sine_waves)
+        if self.training is False and self.causal is True:
+            noise = noise_amp * _wrapped_slice(self.noise_buf, noise_offset, sine_waves.shape[-1]).transpose(1, 2)
+        else:
+            noise = noise_amp * torch.randn_like(sine_waves)
 
         # first: set the unvoiced part to 0 by uv
         # then: additive noise
         sine_waves = sine_waves * uv + noise
+        if self.causal:
+            return sine_waves.transpose(1, 2), uv.transpose(1, 2), noise, new_phase_acc
         return sine_waves.transpose(1, 2), uv.transpose(1, 2), noise
 
 
@@ -215,7 +281,7 @@ def _f02uv(self, f0):
         uv = (f0 > self.voiced_threshold).type(torch.float32)
         return uv
 
-    def _f02sine(self, f0_values):
+    def _f02sine(self, f0_values, phase_acc=None, next_overlap=0, trim=0):
         """f0_values: (batchsize, length, dim)
         where dim indicates fundamental tone and overtones
         """
@@ -223,9 +289,12 @@ def _f02sine(self, f0_values):
         # because 2 * np.pi * n doesn't affect phase
         rad_values = (f0_values / self.sampling_rate) % 1
 
-        # initial phase noise (no noise for fundamental component)
+        # initial phase noise (no noise for fundamental component). Only applied
+        # on the genuine first chunk of a stream (see rationale above the class);
+        # phase_acc is None exactly when there is no carried-forward phase yet.
         if self.training is False and self.causal is True:
-            rad_values[:, 0, :] = rad_values[:, 0, :] + self.rand_ini.to(rad_values.device)
+            if phase_acc is None:
+                rad_values[:, 0, :] = rad_values[:, 0, :] + self.rand_ini.to(rad_values.device)
         else:
             rand_ini = torch.rand(f0_values.shape[0], f0_values.shape[2], device=f0_values.device)
             rand_ini[:, 0] = 0
@@ -237,7 +306,10 @@ def _f02sine(self, f0_values):
                 rad_values.transpose(1, 2), scale_factor=1 / self.upsample_scale, mode="linear"
             ).transpose(1, 2)
 
-            phase = torch.cumsum(rad_values, dim=1) * 2 * np.pi
+            cum = torch.cumsum(rad_values, dim=1)
+            phase = cum if phase_acc is None else cum + phase_acc
+            new_phase_acc = _carry_phase_at_boundary(phase, phase_acc, next_overlap, dim=1, trim=trim)
+            phase = phase * 2 * np.pi
             phase = torch.nn.functional.interpolate(
                 phase.transpose(1, 2) * self.upsample_scale,
                 scale_factor=self.upsample_scale,
@@ -272,9 +344,10 @@ def _f02sine(self, f0_values):
 
             # get the sines
             sines = torch.cos(i_phase * 2 * np.pi)
-        return sines
+            new_phase_acc = None
+        return (sines, new_phase_acc) if self.causal else sines
 
-    def forward(self, f0):
+    def forward(self, f0, phase_acc=None, next_overlap=0, trim=0, noise_offset=0):
         """sine_tensor, uv = forward(f0)
         input F0: tensor(batchsize=1, length, dim=1)
                   f0 for unvoiced steps should be 0
@@ -284,8 +357,12 @@ def forward(self, f0):
         # fundamental component
         fn = torch.multiply(f0, self.harmonic_ids)
 
-        # generate sine waveforms
-        sine_waves = self._f02sine(fn) * self.sine_amp
+        if self.causal:
+            sine_waves, new_phase_acc = self._f02sine(fn, phase_acc, next_overlap, trim)
+        else:
+            sine_waves = self._f02sine(fn)
+            new_phase_acc = None
+        sine_waves = sine_waves * self.sine_amp
 
         # generate uv signal
         uv = self._f02uv(f0)
@@ -295,14 +372,15 @@ def forward(self, f0):
         # .       for voiced regions is self.noise_std
         noise_amp = uv * self.noise_std + (1 - uv) * self.sine_amp / 3
         if self.training is False and self.causal is True:
-            noise = noise_amp * self.sine_waves[:, : sine_waves.shape[1]].to(sine_waves.device)
+            # indexed by absolute sample position, not window-relative position
+            noise = noise_amp * _wrapped_slice(self.sine_waves, noise_offset, sine_waves.shape[1]).to(sine_waves.device)
         else:
             noise = noise_amp * torch.randn_like(sine_waves)
 
         # first: set the unvoiced part to 0 by uv
         # then: additive noise
         sine_waves = sine_waves * uv + noise
-        return sine_waves, uv, noise
+        return (sine_waves, uv, noise, new_phase_acc) if self.causal else (sine_waves, uv, noise)
 
 
 class SourceModuleHnNSF(torch.nn.Module):
@@ -338,10 +416,13 @@ def __init__(
 
         self.sine_amp = sine_amp
         self.noise_std = add_noise_std
+        self.upsample_scale = upsample_scale
 
         # to produce sine waveforms
         if sinegen_type == "1":
-            self.l_sin_gen = SineGen(sampling_rate, harmonic_num, sine_amp, add_noise_std, voiced_threshold)
+            self.l_sin_gen = SineGen(
+                sampling_rate, harmonic_num, sine_amp, add_noise_std, voiced_threshold, causal=causal
+            )
         else:
             self.l_sin_gen = SineGen2(
                 sampling_rate, upsample_scale, harmonic_num, sine_amp, add_noise_std, voiced_threshold, causal=causal
@@ -354,24 +435,38 @@ def __init__(
         if causal is True:
             self.uv = torch.rand(1, 300 * 24000, 1)
 
-    def forward(self, x):
+    def forward(self, x, phase_acc=None, uv_offset=0, next_overlap=0, trim=0):
         """
         Sine_source, noise_source = SourceModuleHnNSF(F0_sampled)
         F0_sampled (batchsize, length, 1)
         Sine_source (batchsize, length, 1)
         noise_source (batchsize, length 1)
         """
-        # source for harmonic branch
         with torch.no_grad():
-            sine_wavs, uv, _ = self.l_sin_gen(x)
+            if not self.causal:
+                sine_wavs, uv, _ = self.l_sin_gen(x)
+                new_phase_acc = None
+            elif isinstance(self.l_sin_gen, SineGen):
+                # next_overlap/trim arrive in mel frames; SineGen needs samples.
+                sine_wavs, uv, _, new_phase_acc = self.l_sin_gen(
+                    x,
+                    phase_acc,
+                    next_overlap * self.upsample_scale,
+                    trim * self.upsample_scale,
+                    noise_offset=uv_offset,
+                )
+            else:
+                sine_wavs, uv, _, new_phase_acc = self.l_sin_gen(
+                    x, phase_acc, next_overlap, trim, noise_offset=uv_offset
+                )
         sine_merge = self.l_tanh(self.l_linear(sine_wavs))
 
         # source for noise branch, in the same shape as uv
         if self.training is False and self.causal is True:
-            noise = self.uv[:, : uv.shape[1]] * self.sine_amp / 3
+            noise = _wrapped_slice(self.uv, uv_offset, uv.shape[1]) * self.sine_amp / 3
         else:
             noise = torch.randn_like(uv) * self.sine_amp / 3
-        return sine_merge, noise, uv
+        return sine_merge, noise, uv, new_phase_acc
 
 
 class HiFTGenerator(nn.Module):
@@ -606,7 +701,7 @@ def forward(
         f0 = self.f0_predictor(speech_feat)
         # f0->source
         s = self.f0_upsamp(f0[:, None]).transpose(1, 2)  # bs,n,t
-        s, _, _ = self.m_source(s)
+        s, _, _, _ = self.m_source(s)
         s = s.transpose(1, 2)
         # mel+source->speech
         generated_speech = self.decode(x=speech_feat, s=s)
@@ -622,7 +717,7 @@ def _inference_pre_istft(
         f0 = self.f0_predictor(speech_feat)
         # f0->source
         s = self.f0_upsamp(f0[:, None]).transpose(1, 2)  # bs,n,t
-        s, _, _ = self.m_source(s)
+        s, _, _, _ = self.m_source(s)
         s = s.transpose(1, 2)
         # use cache_source to avoid glitch
         if cache_source.shape[2] != 0:
@@ -785,14 +880,28 @@ def decode(self, x: torch.Tensor, s: torch.Tensor = torch.zeros(1, 1, 0), finali
         return x
 
     @torch.inference_mode()
-    def inference(self, speech_feat: torch.Tensor, finalize: bool = True) -> torch.Tensor:
+    def inference(
+        self,
+        speech_feat: torch.Tensor,
+        finalize: bool = True,
+        phase_acc: torch.Tensor | None = None,
+        uv_offset: int = 0,
+        next_overlap: int = 0,
+        trim: int = 0,
+        f0_margin: int = 0,
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor | None]:
         # mel->f0 NOTE f0_predictor precision is crucial for causal inference, move
         # self.f0_predictor to cpu if necessary
         self.f0_predictor.to("cpu")
         f0 = self.f0_predictor(speech_feat.cpu(), finalize=finalize).to(speech_feat)
+        if f0_margin > 0:
+            f0 = f0[:, f0_margin:]
+            speech_feat = speech_feat[:, :, f0_margin:]
         # f0->source
         s = self.f0_upsamp(f0[:, None]).transpose(1, 2)  # bs,n,t
-        s, _, _ = self.m_source(s)
+        s, _, _, new_phase_acc = self.m_source(
+            s, phase_acc=phase_acc, uv_offset=uv_offset, next_overlap=next_overlap, trim=trim
+        )
         s = s.transpose(1, 2)
         if finalize is True:
             generated_speech = self.decode(x=speech_feat, s=s, finalize=finalize)
@@ -800,7 +909,7 @@ def inference(self, speech_feat: torch.Tensor, finalize: bool = True) -> torch.T
             generated_speech = self.decode(
                 x=speech_feat[:, :, : -self.f0_predictor.condnet[0].causal_padding], s=s, finalize=finalize
             )
-        return generated_speech, s
+        return generated_speech, s, new_phase_acc
 
 
 class CausalConv1dUpsample(torch.nn.Conv1d):
@@ -954,6 +1063,11 @@ def __init__(self, num_class: int = 1, in_channels: int = 80, cond_channels: int
             nn.ELU(),
         )
         self.classifier = nn.Linear(in_features=cond_channels, out_features=self.num_class)
+        self.left_context_frames = sum(
+            layer.causal_padding
+            for layer in self.condnet
+            if isinstance(layer, CausalConv1d) and layer.causal_type == "left"
+        )
 
     def forward(self, x: torch.Tensor, finalize: bool = True) -> torch.Tensor:
         if finalize is True:
diff --git a/vllm_omni/model_executor/models/cosyvoice3/cosyvoice3_code2wav.py b/vllm_omni/model_executor/models/cosyvoice3/cosyvoice3_code2wav.py
index ef706b6c8fc..1713467c8b3 100644
--- a/vllm_omni/model_executor/models/cosyvoice3/cosyvoice3_code2wav.py
+++ b/vllm_omni/model_executor/models/cosyvoice3/cosyvoice3_code2wav.py
@@ -9,10 +9,8 @@
 3. HiFiGAN vocoder for waveform synthesis
 """
 
-from __future__ import annotations
-
 from collections import Counter
-from typing import cast
+from typing import TypedDict, cast
 
 import numpy as np
 import torch
@@ -39,6 +37,21 @@
 logger = init_logger(__name__)
 
 
+class StreamingFlowItem(TypedDict, total=False):
+    """One entry of the batched-streaming item list passed to forward_streaming_batch."""
+
+    index: int
+    req_id: str | None
+    stream_finished: bool
+    token: torch.Tensor
+    prompt_token: torch.Tensor
+    prompt_feat: torch.Tensor
+    embedding: torch.Tensor
+    cache_state: dict[str, torch.Tensor] | None
+    token_offset_tokens: int
+    finalize: bool
+
+
 class CosyVoice3Code2Wav(nn.Module):
     """CosyVoice3 Code2Wav stage for token-to-waveform conversion.
 
@@ -119,6 +132,10 @@ def __init__(self, config: CosyVoice3Config):
         self.mel_cache_len = 20
         self.source_cache_len = int(self.mel_cache_len * 256)
         self.speech_window = np.hamming(2 * self.source_cache_len)
+        # Must cover decode()'s own causal receptive field, not just the F0
+        # margin; window_len=48 already passes
+        # test_incremental_hift_bounded_window_is_close, so 64 has headroom.
+        self._hift_window_len = 64
 
     @property
     def input_frame_rate(self) -> int:
@@ -226,40 +243,79 @@ def _stream_hift_from_feat(
         chunk_mel = feat.to(device=hift_weight.device, dtype=hift_weight.dtype)
 
         cached_mel = None if not cache_state else cache_state.get("mel")
-        speech_offset_obj = None if not cache_state else cache_state.get("speech_offset")
-        try:
-            speech_offset = int(speech_offset_obj) if speech_offset_obj is not None else 0
-        except (TypeError, ValueError):
-            speech_offset = 0
-
+        cached_offset = 0 if not cache_state else int(cache_state.get("mel_offset", 0))
+        window_len = self._hift_window_len
+        samples_per_mel = int(np.prod(self.hift.upsample_rates) * self.hift.istft_params["hop_len"])
+        trim = int(self.hift.f0_predictor.condnet[0].causal_padding)
+        f0_margin_frames = int(self.hift.f0_predictor.left_context_frames)
+        f0_margin = 0
         if isinstance(cached_mel, torch.Tensor) and cached_mel.numel() > 0:
             cached_mel = cached_mel.to(device=chunk_mel.device, dtype=chunk_mel.dtype)
-            tts_mel = torch.cat([cached_mel, chunk_mel], dim=-1) if chunk_mel.numel() > 0 else cached_mel
+            total_hist = cached_mel.shape[-1]
+            overlap = min(window_len + trim, total_hist)
+            window_mel = torch.cat([cached_mel[..., -overlap:], chunk_mel], dim=-1)
+            window_offset = cached_offset + total_hist - overlap
+            uv_offset = window_offset * samples_per_mel
+            f0_margin = min(f0_margin_frames, total_hist - overlap)
+            f0_input_mel = (
+                torch.cat(
+                    [cached_mel[..., total_hist - overlap - f0_margin : total_hist - overlap], window_mel], dim=-1
+                )
+                if f0_margin > 0
+                else window_mel
+            )
         else:
-            tts_mel = chunk_mel
+            window_mel = chunk_mel
+            f0_input_mel = chunk_mel
+            window_offset = 0
+            uv_offset = 0
 
-        if tts_mel.shape[-1] == 0:
+        phase_acc = None if not cache_state else cache_state.get("phase_acc")
+        if phase_acc is not None:
+            phase_acc = phase_acc.to(device=chunk_mel.device, dtype=chunk_mel.dtype)
+
+        if window_mel.shape[-1] == 0:
             tts_speech = torch.zeros((chunk_mel.shape[0], 1, 0), device=chunk_mel.device, dtype=chunk_mel.dtype)
+            new_phase_acc = phase_acc
         else:
-            tts_speech, _ = self.hift.inference(speech_feat=tts_mel, finalize=finalize)
+            next_overlap = min(window_len + trim, window_mel.shape[-1])
+            # On finalize the F0 predictor consumes the whole window (it does not
+            # hold back `trim` frames), so trim must not inflate the phase-carry
+            # index -- it would point past the end of a short window.
+            carry_trim = 0 if finalize else trim
+            tts_speech, _, new_phase_acc = self.hift.inference(
+                speech_feat=f0_input_mel,
+                finalize=finalize,
+                phase_acc=phase_acc,
+                uv_offset=uv_offset,
+                next_overlap=next_overlap,
+                trim=carry_trim,
+                f0_margin=f0_margin,
+            )
 
         tts_speech = tts_speech.reshape(tts_speech.shape[0], -1)
-        speech_offset = max(0, min(speech_offset, int(tts_speech.shape[-1])))
-        emitted_speech = tts_speech[:, speech_offset:]
+        new_samples = chunk_mel.shape[-1] * samples_per_mel
+        if finalize:
+            frames_withheld_per_chunk = trim + self.hift.conv_pre_look_right + 1
+            released = frames_withheld_per_chunk * samples_per_mel
+            emitted_speech = tts_speech[:, -(new_samples + released) :]
+        else:
+            emitted_speech = tts_speech[:, -new_samples:] if new_samples > 0 else tts_speech[:, :0]
 
         if finalize:
             return emitted_speech.reshape(emitted_speech.shape[0], 1, -1), None
 
         new_state = {
-            "mel": tts_mel.detach().cpu().contiguous(),
-            "speech_offset": int(tts_speech.shape[-1]),
+            "mel": f0_input_mel.detach().cpu().contiguous(),
+            "mel_offset": window_offset - f0_margin,
+            "phase_acc": new_phase_acc.detach().cpu().contiguous() if new_phase_acc is not None else None,
         }
         return emitted_speech.reshape(emitted_speech.shape[0], 1, -1), new_state
 
     @torch.inference_mode()
     def forward_streaming_batch(
         self,
-        items: list[dict[str, object]],
+        items: list[StreamingFlowItem],
         *,
         n_timesteps: int = 10,
     ) -> list[tuple[torch.Tensor, dict[str, torch.Tensor] | None]]:
@@ -270,20 +326,16 @@ def forward_streaming_batch(
         group and passed to the flow as per-row token lengths.
         """
         results: list[tuple[torch.Tensor, dict[str, torch.Tensor] | None] | None] = [None] * len(items)
-        groups: dict[tuple[int, int, int, bool], list[tuple[int, dict[str, object]]]] = {}
+        groups: dict[tuple[int, int, int, bool], list[tuple[int, StreamingFlowItem]]] = {}
         for index, item in enumerate(items):
-            token = item["token"]
-            prompt_token = item["prompt_token"]
-            prompt_feat = item["prompt_feat"]
-            embedding = item["embedding"]
-            assert isinstance(token, torch.Tensor)
-            assert isinstance(prompt_token, torch.Tensor)
-            assert isinstance(prompt_feat, torch.Tensor)
-            assert isinstance(embedding, torch.Tensor)
+            assert isinstance(item["token"], torch.Tensor)
+            assert isinstance(item["prompt_token"], torch.Tensor)
+            assert isinstance(item["prompt_feat"], torch.Tensor)
+            assert isinstance(item["embedding"], torch.Tensor)
             key = (
-                int(prompt_token.shape[1]),
-                int(prompt_feat.shape[1]),
-                int(embedding.shape[1]),
+                int(item["prompt_token"].shape[1]),
+                int(item["prompt_feat"].shape[1]),
+                int(item["embedding"].shape[1]),
                 bool(item.get("finalize", False)),
             )
             groups.setdefault(key, []).append((index, item))
@@ -305,11 +357,11 @@ def forward_streaming_batch(
             if len(group) == 1:
                 index, item = group[0]
                 result = self.forward_streaming(
-                    token=item["token"],  # type: ignore[arg-type]
-                    prompt_token=item["prompt_token"],  # type: ignore[arg-type]
-                    prompt_feat=item["prompt_feat"],  # type: ignore[arg-type]
-                    embedding=item["embedding"],  # type: ignore[arg-type]
-                    cache_state=item.get("cache_state"),  # type: ignore[arg-type]
+                    token=item["token"],
+                    prompt_token=item["prompt_token"],
+                    prompt_feat=item["prompt_feat"],
+                    embedding=item["embedding"],
+                    cache_state=item.get("cache_state"),
                     n_timesteps=n_timesteps,
                     token_offset_tokens=int(item.get("token_offset_tokens", 0)),
                     finalize=bool(item.get("finalize", False)),
@@ -318,15 +370,13 @@ def forward_streaming_batch(
                 continue
 
             token_tensors = [item["token"] for _, item in group]
-            assert all(isinstance(token, torch.Tensor) for token in token_tensors)
             token_lens = torch.tensor(
-                [int(token.shape[1]) for token in token_tensors],  # type: ignore[union-attr]
+                [int(token.shape[1]) for token in token_tensors],
                 dtype=torch.int32,
             )
             max_token_len = int(token_lens.max().item())
             padded_tokens = []
             for token in token_tensors:
-                assert isinstance(token, torch.Tensor)
                 if int(token.shape[1]) == max_token_len:
                     padded_tokens.append(token)
                 else:
@@ -337,9 +387,9 @@ def forward_streaming_batch(
                     )
                     padded_tokens.append(torch.cat([token, pad], dim=1))
             tokens = torch.cat(padded_tokens, dim=0)
-            prompt_tokens = torch.cat([item["prompt_token"] for _, item in group], dim=0)  # type: ignore[list-item]
-            prompt_feats = torch.cat([item["prompt_feat"] for _, item in group], dim=0)  # type: ignore[list-item]
-            embeddings = torch.cat([item["embedding"] for _, item in group], dim=0)  # type: ignore[list-item]
+            prompt_tokens = torch.cat([item["prompt_token"] for _, item in group], dim=0)
+            prompt_feats = torch.cat([item["prompt_feat"] for _, item in group], dim=0)
+            embeddings = torch.cat([item["embedding"] for _, item in group], dim=0)
             prompt_token_lens = torch.full((len(group),), prompt_tokens.shape[1], dtype=torch.int32)
             prompt_feat_lens = torch.full((len(group),), prompt_feats.shape[1], dtype=torch.int32)
             finalize = bool(group[0][1].get("finalize", False))
@@ -370,7 +420,7 @@ def forward_streaming_batch(
                     row_feat = row_feat[:, :, trim_mel:]
                 results[index] = self._stream_hift_from_feat(
                     row_feat,
-                    cache_state=item.get("cache_state"),  # type: ignore[arg-type]
+                    cache_state=item.get("cache_state"),
                     finalize=finalize,
                 )
 
@@ -443,7 +493,7 @@ def forward(
                 dtype=tts_mel.dtype,
             )
         else:
-            tts_speech, _ = self.hift.inference(speech_feat=tts_mel, finalize=True)
+            tts_speech, _, _ = self.hift.inference(speech_feat=tts_mel, finalize=True)
 
         return tts_speech
 

From 1053f7b0bdf0a1ac18c09c536d08eefc32bc2995 Mon Sep 17 00:00:00 2001
From: psv666 <150513104+psv666@users.noreply.github.com>
Date: Wed, 16 Sep 2026 23:39:01 +0800
Subject: [PATCH 037/105] [Bugfix] Preserve benchmark metric sample counts in
 results (#7624)

Signed-off-by: psv666 <2693925048@qq.com>
Co-authored-by: amy-why-3459 <wuhaiyan17@huawei.com>
---
 .../benchmarks/patch/test_benchmark_result.py | 74 +++++++++++++++++++
 tests/dfx/perf/tests/test_runner_metadata.py  | 16 ++--
 vllm_omni/benchmarks/patch/patch.py           |  8 ++
 3 files changed, 92 insertions(+), 6 deletions(-)
 create mode 100644 tests/benchmarks/patch/test_benchmark_result.py

diff --git a/tests/benchmarks/patch/test_benchmark_result.py b/tests/benchmarks/patch/test_benchmark_result.py
new file mode 100644
index 00000000000..1e9619fe30e
--- /dev/null
+++ b/tests/benchmarks/patch/test_benchmark_result.py
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Verify metric sample counts survive benchmark JSON serialization."""
+
+import asyncio
+import json
+import time
+
+import pytest
+from vllm.benchmarks.datasets import SampleRequest
+from vllm.benchmarks.serve import TaskType
+
+from vllm_omni.benchmarks.patch import patch
+
+pytestmark = [pytest.mark.core_model, pytest.mark.benchmark, pytest.mark.cpu]
+
+
+@pytest.mark.parametrize("selected_metrics", [["ttft", "tpot", "itl"], []])
+@pytest.mark.parametrize("measured", [True, False])
+def test_benchmark_result_preserves_tpot_sample_count(monkeypatch, measured, selected_metrics):
+    async def request_func(**kwargs):
+        return patch.MixRequestFuncOutput(
+            success=True,
+            prompt_len=2,
+            output_tokens=3,
+            generated_text="hello world!",
+            start_time=time.perf_counter(),
+            ttft=0.01,
+            latency=0.03,
+            text_latency=0.03,
+            itl=[0.01, 0.01] if measured else [0.0, 0.0],
+        )
+
+    monkeypatch.setitem(patch.ASYNC_REQUEST_FUNCS, "test-result", request_func)
+    result = asyncio.run(
+        patch.benchmark(
+            task_type=TaskType.GENERATION,
+            endpoint_type="test-result",
+            api_url="http://unused/v1/chat/completions",
+            base_url="http://unused",
+            model_id="test-model",
+            model_name="test-model",
+            tokenizer=None,
+            input_requests=[SampleRequest(prompt="hi", prompt_len=2, expected_output_len=3)],
+            logprobs=None,
+            request_rate=float("inf"),
+            burstiness=1.0,
+            disable_tqdm=True,
+            num_warmups=0,
+            profile=False,
+            selected_percentile_metrics=selected_metrics,
+            selected_percentiles=[50.0],
+            ignore_eos=False,
+            goodput_config_dict={},
+            max_concurrency=1,
+            lora_modules=None,
+            extra_headers=None,
+            extra_body=None,
+            ready_check_timeout_sec=0,
+        )
+    )
+    # DFX reads this dictionary from the benchmark's JSON result file.
+    saved_result = json.loads(json.dumps(result))
+    assert saved_result["completed"] == 1
+    assert saved_result.get("num_tpot_samples") == int(measured)
+    assert saved_result["num_ttft_samples"] == 1
+    assert saved_result["num_itl_samples"] == 2
+    assert "num_audio_ttfp_samples" in saved_result
+    assert "num_audio_rtf_samples" in saved_result
+    if measured and "tpot" in selected_metrics:
+        assert saved_result["mean_tpot_ms"] == pytest.approx(10.0)
+    else:
+        assert "mean_tpot_ms" not in saved_result
diff --git a/tests/dfx/perf/tests/test_runner_metadata.py b/tests/dfx/perf/tests/test_runner_metadata.py
index df99f090dcb..a0f966121a1 100644
--- a/tests/dfx/perf/tests/test_runner_metadata.py
+++ b/tests/dfx/perf/tests/test_runner_metadata.py
@@ -570,6 +570,7 @@ def test_omni_tpot_baseline_accepts_measured_finite_sample():
 @pytest.mark.parametrize(
     ("num_tpot_samples", "mean_tpot_ms", "match"),
     [
+        (None, 10.0, "no measurable TPOT samples"),
         (0, float("nan"), "no measurable TPOT samples"),
         (1, float("nan"), "mean_tpot_ms is not finite"),
     ],
@@ -577,14 +578,17 @@ def test_omni_tpot_baseline_accepts_measured_finite_sample():
 def test_omni_tpot_baseline_rejects_missing_or_nonfinite_sample(num_tpot_samples, mean_tpot_ms, match):
     from tests.dfx.perf.scripts.run_benchmark import assert_result
 
+    result = {
+        "completed": 1,
+        "Hardware": "H100",
+        "mean_tpot_ms": mean_tpot_ms,
+    }
+    if num_tpot_samples is not None:
+        result["num_tpot_samples"] = num_tpot_samples
+
     with pytest.raises(AssertionError, match=match):
         assert_result(
-            {
-                "completed": 1,
-                "Hardware": "H100",
-                "num_tpot_samples": num_tpot_samples,
-                "mean_tpot_ms": mean_tpot_ms,
-            },
+            result,
             {"baseline": {"H100": {"mean_tpot_ms": 20.0}}},
             1,
         )
diff --git a/vllm_omni/benchmarks/patch/patch.py b/vllm_omni/benchmarks/patch/patch.py
index bee910c90d3..5a5e74b0d51 100644
--- a/vllm_omni/benchmarks/patch/patch.py
+++ b/vllm_omni/benchmarks/patch/patch.py
@@ -3078,6 +3078,14 @@ def measured_ttft(output: RequestFuncOutput) -> float | None:
             "max_concurrent_requests": metrics.max_concurrent_requests,
             "rtfx": metrics.rtfx,
         }
+        for sample_count in (
+            "num_ttft_samples",
+            "num_tpot_samples",
+            "num_itl_samples",
+            "num_audio_ttfp_samples",
+            "num_audio_rtf_samples",
+        ):
+            result[sample_count] = getattr(metrics, sample_count)
     else:
         result = {
             "duration": benchmark_duration,

From 81b5be274d88eeb73e84091ba3f1466dc6f5a184 Mon Sep 17 00:00:00 2001
From: NumberWan <wantszkin2003@gmail.com>
Date: Wed, 16 Sep 2026 23:54:28 +0800
Subject: [PATCH 038/105] [Bugfix][Qwen-Image] Restore RotaryEmbedding CUDA
 RoPE for Diffusers e2e (#7513)

Signed-off-by: NumberWan <wantszkin2003@gmail.com>
Co-authored-by: wangyu <53896905+yenuo26@users.noreply.github.com>
---
 .../benchmark_qwen_image_qk_norm_rope.py      | 12 +++----
 .../test_qwen_image_fused_qk_norm_rope.py     | 34 +++++++++++--------
 .../qwen_image/test_qwen_image_rope_utils.py  | 25 --------------
 tests/e2e/accuracy/test_qwen_image.py         |  6 ++--
 .../qwen_image/qwen_image_transformer.py      | 22 ++----------
 5 files changed, 31 insertions(+), 68 deletions(-)

diff --git a/benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py b/benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py
index ee69f7e5906..2eaa097bdf6 100644
--- a/benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py
+++ b/benchmarks/diffusion/benchmark_qwen_image_qk_norm_rope.py
@@ -22,9 +22,7 @@
     _fused_cuda_supported,
     fused_qk_norm_rope,
 )
-from vllm_omni.diffusion.models.qwen_image.qwen_image_transformer import (
-    _apply_qwen_image_rotary_emb,
-)
+from vllm_omni.diffusion.layers.rope import RotaryEmbedding
 
 
 def _parse_args() -> argparse.Namespace:
@@ -87,10 +85,10 @@ def _native(
 ) -> tuple[torch.Tensor, torch.Tensor]:
     q = F.rms_norm(q, (q.shape[-1],), q_weight, eps)
     k = F.rms_norm(k, (k.shape[-1],), k_weight, eps)
-    return (
-        _apply_qwen_image_rotary_emb(q, freqs),
-        _apply_qwen_image_rotary_emb(k, freqs),
-    )
+    rope = RotaryEmbedding(is_neox_style=False)
+    cos = freqs.real.to(q.dtype)
+    sin = freqs.imag.to(q.dtype)
+    return rope(q, cos, sin), rope(k, cos, sin)
 
 
 def _fused(
diff --git a/tests/diffusion/models/qwen_image/test_qwen_image_fused_qk_norm_rope.py b/tests/diffusion/models/qwen_image/test_qwen_image_fused_qk_norm_rope.py
index 2f10ea33e9c..16dc851153e 100644
--- a/tests/diffusion/models/qwen_image/test_qwen_image_fused_qk_norm_rope.py
+++ b/tests/diffusion/models/qwen_image/test_qwen_image_fused_qk_norm_rope.py
@@ -11,7 +11,6 @@
 
 from vllm_omni.diffusion.layers.rope import RotaryEmbedding
 from vllm_omni.diffusion.models.qwen_image.qwen_image_transformer import (
-    _apply_qwen_image_rotary_emb,
     _qwen_image_qk_norm_rope,
 )
 
@@ -73,22 +72,28 @@ def _make_input(
     return QwenImageQKInput(q=q, k=k, norm_q=norm_q, norm_k=norm_k, freqs=freqs)
 
 
-def _reference(data: QwenImageQKInput) -> tuple[torch.Tensor, torch.Tensor]:
+def _eager_rotary(data: QwenImageQKInput) -> tuple[torch.Tensor, torch.Tensor]:
     q = data.norm_q(data.q)
     k = data.norm_k(data.k)
-    if data.q.device.type == "cuda":
-        return (
-            _apply_qwen_image_rotary_emb(q, data.freqs),
-            _apply_qwen_image_rotary_emb(k, data.freqs),
-        )
-
     rope = RotaryEmbedding(is_neox_style=False)
     cos = data.freqs.real.to(data.q.dtype)
     sin = data.freqs.imag.to(data.q.dtype)
     return rope(q, cos, sin), rope(k, cos, sin)
 
 
-def _run(data: QwenImageQKInput) -> tuple[torch.Tensor, torch.Tensor]:
+def _fp32_complex_rotary(x: torch.Tensor, freqs: torch.Tensor) -> torch.Tensor:
+    """Local copy of the old CUDA helper; fused kernel still tracks this math."""
+    paired = torch.view_as_complex(x.float().reshape(*x.shape[:-1], -1, 2))
+    return torch.view_as_real(paired * freqs.unsqueeze(1)).flatten(3).to(x.dtype)
+
+
+def _fused_kernel_reference(data: QwenImageQKInput) -> tuple[torch.Tensor, torch.Tensor]:
+    q = data.norm_q(data.q)
+    k = data.norm_k(data.k)
+    return _fp32_complex_rotary(q, data.freqs), _fp32_complex_rotary(k, data.freqs)
+
+
+def _run(data: QwenImageQKInput, *, use_fused: bool = True) -> tuple[torch.Tensor, torch.Tensor]:
     return _qwen_image_qk_norm_rope(
         data.q,
         data.k,
@@ -97,6 +102,7 @@ def _run(data: QwenImageQKInput) -> tuple[torch.Tensor, torch.Tensor]:
         data.freqs,
         RotaryEmbedding(is_neox_style=False),
         EPS,
+        use_fused=use_fused,
     )
 
 
@@ -110,8 +116,8 @@ def test_qwen_image_qk_norm_rope_cuda_fp32_fallback_matches_reference():
         packed_qkv_view=True,
     )
 
-    actual_q, actual_k = _run(data)
-    expected_q, expected_k = _reference(data)
+    actual_q, actual_k = _run(data, use_fused=False)
+    expected_q, expected_k = _eager_rotary(data)
 
     torch.testing.assert_close(actual_q, expected_q, atol=1e-5, rtol=1e-5)
     torch.testing.assert_close(actual_k, expected_k, atol=1e-5, rtol=1e-5)
@@ -127,8 +133,8 @@ def test_qwen_image_qk_norm_rope_cuda_fp16_fallback_matches_reference():
         packed_qkv_view=True,
     )
 
-    actual_q, actual_k = _run(data)
-    expected_q, expected_k = _reference(data)
+    actual_q, actual_k = _run(data, use_fused=False)
+    expected_q, expected_k = _eager_rotary(data)
 
     torch.testing.assert_close(actual_q, expected_q, atol=1e-3, rtol=1e-3)
     torch.testing.assert_close(actual_k, expected_k, atol=1e-3, rtol=1e-3)
@@ -150,7 +156,7 @@ def test_qwen_image_fused_qk_norm_rope_cuda_matches_fp32_rope_reference(
     )
 
     actual_q, actual_k = _run(data)
-    expected_q, expected_k = _reference(data)
+    expected_q, expected_k = _fused_kernel_reference(data)
 
     torch.testing.assert_close(actual_q, expected_q, atol=0.0625, rtol=0.02)
     torch.testing.assert_close(actual_k, expected_k, atol=0.0625, rtol=0.02)
diff --git a/tests/diffusion/models/qwen_image/test_qwen_image_rope_utils.py b/tests/diffusion/models/qwen_image/test_qwen_image_rope_utils.py
index 4f3a81491cd..3fd141dc1f3 100644
--- a/tests/diffusion/models/qwen_image/test_qwen_image_rope_utils.py
+++ b/tests/diffusion/models/qwen_image/test_qwen_image_rope_utils.py
@@ -3,37 +3,12 @@
 
 from vllm_omni.diffusion.models.qwen_image.qwen_image_transformer import (
     QwenEmbedRope,
-    _apply_qwen_image_rotary_emb,
 )
 from vllm_omni.diffusion.models.qwen_image.rope_utils import txt_seq_lens_from_embeds
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
 
-@pytest.mark.parametrize("dtype", [torch.float32, torch.float16, torch.bfloat16])
-@pytest.mark.parametrize("noncontiguous", [False, True])
-def test_qwen_rotary_preserves_frequency_precision(dtype, noncontiguous):
-    from diffusers.models.transformers.transformer_qwenimage import apply_rotary_emb_qwen
-
-    generator = torch.Generator().manual_seed(42)
-    x = torch.randn(2, 17, 3, 128, generator=generator).to(dtype)
-    if noncontiguous:
-        x = x.transpose(1, 2).contiguous().transpose(1, 2)
-    angles = torch.randn(17, 64, generator=generator)
-    freqs = torch.polar(torch.ones_like(angles), angles)
-    expected = apply_rotary_emb_qwen(x, freqs, use_real=False)
-    actual = _apply_qwen_image_rotary_emb(x, freqs)
-    assert actual.dtype == dtype
-    assert actual.shape == x.shape
-    torch.testing.assert_close(actual, expected, rtol=0, atol=0)
-
-    if dtype == torch.bfloat16:
-        # A regression to early BF16 frequency rounding must be observable.
-        rounded_freqs = torch.complex(freqs.real.to(dtype).float(), freqs.imag.to(dtype).float())
-        rounded = _apply_qwen_image_rotary_emb(x, rounded_freqs)
-        assert not torch.equal(actual, rounded)
-
-
 def test_txt_seq_lens_from_embeds_uses_padded_width_not_valid_token_count():
     prompt_embeds = torch.zeros(2, 64, 8)
     prompt_embeds_mask = torch.zeros(2, 64, dtype=torch.bool)
diff --git a/tests/e2e/accuracy/test_qwen_image.py b/tests/e2e/accuracy/test_qwen_image.py
index fb2f8cbc804..1fca04f99a2 100644
--- a/tests/e2e/accuracy/test_qwen_image.py
+++ b/tests/e2e/accuracy/test_qwen_image.py
@@ -32,9 +32,9 @@
 NUM_INFERENCE_STEPS = 20
 TRUE_CFG_SCALE = 4.0
 SEED = 42
-SSIM_THRESHOLD = 0.94
-# With --fa-deterministic, H100 nightlies stably land near SSIM 0.958 / PSNR 27.8
-# vs Diffusers on the FA3 hub path (see #5734 / #5963 / #6971).
+# H100 nightly after RotaryEmbedding CUDA RoPE: SSIM 0.978375 / PSNR 31.83
+# vs Diffusers (Buildkite #15339). SSIM 0.97 so a drop is visible.
+SSIM_THRESHOLD = 0.97
 PSNR_THRESHOLD = 27.0
 
 MODEL_2512_ID = "Qwen/Qwen-Image-2512"
diff --git a/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py b/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
index 11568f62c74..cb1adbb61a2 100644
--- a/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
+++ b/vllm_omni/diffusion/models/qwen_image/qwen_image_transformer.py
@@ -60,17 +60,6 @@
 logger = init_logger(__name__)
 
 
-def _apply_qwen_image_rotary_emb(x: torch.Tensor, freqs: torch.Tensor) -> torch.Tensor:
-    """Rotate interleaved pairs before rounding back to the activation dtype.
-
-    Qwen-Image's reference uses complex FP32 multiplication. Rounding the
-    frequencies to BF16 before rotation loses positional precision; those
-    errors accumulate across the denoising steps.
-    """
-    paired = torch.view_as_complex(x.float().reshape(*x.shape[:-1], -1, 2))
-    return torch.view_as_real(paired * freqs.unsqueeze(1)).flatten(3).to(x.dtype)
-
-
 def _qwen_image_qk_norm_rope(
     q: torch.Tensor,
     k: torch.Tensor,
@@ -103,16 +92,11 @@ def _qwen_image_qk_norm_rope(
             fused_k.reshape(batch, seq_len, num_kv_heads, head_dim),
         )
 
+    # Eager path: BF16/activation-dtype RotaryEmbedding on every device.
+    # CUDA used to call FP32 complex multiply here; that matches the Diffusers
+    # helper in unit tests but drops Omni vs Diffusers pipeline PSNR (#7494).
     q = norm_q(q)
     k = norm_k(k)
-    if q.device.type == "cuda":
-        return (
-            _apply_qwen_image_rotary_emb(q, freqs),
-            _apply_qwen_image_rotary_emb(k, freqs),
-        )
-
-    # Retain the platform-specific kernels on other accelerators, which may
-    # not support complex tensors.
     cos = torch.real(freqs).to(q.dtype)
     sin = torch.imag(freqs).to(q.dtype)
     return rope(q, cos, sin), rope(k, cos, sin)

From 3d75254a4401b9f146d22d5680c772251b8df82f Mon Sep 17 00:00:00 2001
From: y-null <y_null@qq.com>
Date: Thu, 17 Sep 2026 00:00:45 +0800
Subject: [PATCH 039/105] [CI][MiniCPM-o] Lower the Daily-Omni accuracy gate to
 0.77 (#7657)

Signed-off-by: y_null <y_null@qq.com>
---
 tests/e2e/accuracy/minicpmo_4_5/test_minicpmo_4_5.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/tests/e2e/accuracy/minicpmo_4_5/test_minicpmo_4_5.py b/tests/e2e/accuracy/minicpmo_4_5/test_minicpmo_4_5.py
index ad659541de5..acf717e42f0 100644
--- a/tests/e2e/accuracy/minicpmo_4_5/test_minicpmo_4_5.py
+++ b/tests/e2e/accuracy/minicpmo_4_5/test_minicpmo_4_5.py
@@ -3,7 +3,7 @@
 """MiniCPM-o 4.5 Daily-Omni + Seed-TTS accuracy regression coverage.
 
 Daily-Omni settings follow the MiniCPM interleaved AV recipe that reaches
-~78% overall accuracy on Daily-Omni (``minicpm-interleave``, ``temperature=0``,
+~77% overall accuracy on Daily-Omni (``minicpm-interleave``, ``temperature=0``,
 text modalities, and server ``--interleave-mm-strings`` + 1fps / 128-frame
 media-io kwargs, also pinned in ``minicpmo_4_5.yaml``).
 """
@@ -48,7 +48,12 @@
     )
 )
 
-_MIN_DAILY_OMNI_ACCURACY = 0.78
+# The 0.78 gate (934/1197) sits 1 item above the observed NPU mean
+# (~933/1197) and inside the observed 932~940 spread, so it flips nightly -
+# 3 failures in the latest 7 dated NPU nightlies (#6887). 0.77 (922/1197)
+# sits 10 items below the observed minimum (932) while still failing a
+# >=1pp real accuracy regression.
+_MIN_DAILY_OMNI_ACCURACY = 0.77
 _MAX_SEED_TTS_MEAN_WER = 0.05
 # Match the validated Daily-Omni client body from daily_omni_bench.sh.
 _DAILY_EXTRA_BODY = {

From 2a6847171516b5977f4e9e835f427f5e731d73f3 Mon Sep 17 00:00:00 2001
From: hyw <109567717+yuweih205@users.noreply.github.com>
Date: Thu, 17 Sep 2026 01:09:23 +0800
Subject: [PATCH 040/105] [Bugfix] Reject failed diffusion benchmark warmups
 (#7092)

Signed-off-by: hyw <yuweih205@gmail.com>
Signed-off-by: HuangYuwei <yuweih205@gmail.com>
Signed-off-by: Alex Brooks <albrooks@redhat.com>
Co-authored-by: Alex Brooks <albrooks@redhat.com>
---
 .../diffusion/diffusion_benchmark_serving.py  |  12 +-
 .../test_diffusion_benchmark_warmups.py       | 128 ++++++++++++++++++
 2 files changed, 139 insertions(+), 1 deletion(-)
 create mode 100644 tests/benchmarks/test_diffusion_benchmark_warmups.py

diff --git a/benchmarks/diffusion/diffusion_benchmark_serving.py b/benchmarks/diffusion/diffusion_benchmark_serving.py
index 1e5aaf29c49..6bf64ec1da1 100644
--- a/benchmarks/diffusion/diffusion_benchmark_serving.py
+++ b/benchmarks/diffusion/diffusion_benchmark_serving.py
@@ -1087,6 +1087,12 @@ async def limited_warmup_request_func(
 
     warmup_tasks = [asyncio.create_task(limited_warmup_request_func(req)) for req in warmup_requests]
     warmup_outputs = await asyncio.gather(*warmup_tasks)
+    failed_count = sum(not output.success for output in warmup_outputs)
+    if failed_count:
+        raise RuntimeError(
+            f"{failed_count}/{len(warmup_outputs)} warmup requests failed; "
+            "check server logs before running the benchmark."
+        )
     return list(zip(warmup_requests, warmup_outputs))
 
 
@@ -1455,7 +1461,7 @@ async def limited_request_func(req, session, pbar):
         print(f"Metrics saved to {args.output_file}")
 
 
-if __name__ == "__main__":
+def build_parser():
     parser = argparse.ArgumentParser(description="Benchmark serving for diffusion models.")
     parser.add_argument(
         "--base-url",
@@ -1637,6 +1643,10 @@ async def limited_request_func(req, session, pbar):
         action="store_true",
         help="Request stage duration metrics from endpoints that support return_stage_metrics.",
     )
+    return parser
 
+
+if __name__ == "__main__":
+    parser = build_parser()
     args = parser.parse_args()
     asyncio.run(benchmark(args))
diff --git a/tests/benchmarks/test_diffusion_benchmark_warmups.py b/tests/benchmarks/test_diffusion_benchmark_warmups.py
new file mode 100644
index 00000000000..9d72189b7cd
--- /dev/null
+++ b/tests/benchmarks/test_diffusion_benchmark_warmups.py
@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import importlib
+import sys
+
+import pytest
+
+from benchmarks.diffusion import backends
+from benchmarks.diffusion.backends import RequestFuncInput, RequestFuncOutput
+
+pytestmark = [pytest.mark.core_model, pytest.mark.benchmark, pytest.mark.cpu, pytest.mark.asyncio]
+
+ENDPOINT = "/v1/chat/completions"
+TEST_MODEL = "test-model"
+
+
+@pytest.fixture
+def diffusion_benchmark(monkeypatch):
+    # The standalone script imports its sibling backend module by name.
+    monkeypatch.setitem(sys.modules, "backends", backends)
+    return importlib.import_module("benchmarks.diffusion.diffusion_benchmark_serving")
+
+
+@pytest.fixture
+def warmup_args(diffusion_benchmark):
+    from benchmarks.diffusion.diffusion_benchmark_serving import build_parser
+
+    parser = build_parser()
+    return parser.parse_args(
+        [
+            f"--endpoint={ENDPOINT}",
+            "--dataset=random",
+            "--task=t2i",
+            "--warmup-requests=2",
+            "--warmup-num-inference-steps=4",
+        ]
+    )
+
+
+@pytest.fixture
+def input_requests():
+    return [
+        RequestFuncInput(
+            prompt=prompt,
+            api_url=f"http://test.local{ENDPOINT}",
+            model=TEST_MODEL,
+            num_inference_steps=20,
+        )
+        for prompt in ("first", "second")
+    ]
+
+
+async def test_disabled_warmup_sends_no_requests(diffusion_benchmark, warmup_args, input_requests):
+    warmup_args.warmup_requests = 0
+
+    async def unexpected_request(*args):
+        pytest.fail("disabled warmup must not send requests")
+
+    pairs = await diffusion_benchmark._run_warmups(input_requests, warmup_args, None, unexpected_request)
+
+    assert pairs == []
+
+
+async def test_successful_warmups_preserve_request_output_pairs(diffusion_benchmark, warmup_args, input_requests):
+    outputs = [RequestFuncOutput(success=True, latency=0.5), RequestFuncOutput(success=True, latency=1.0)]
+    pending_outputs = iter(outputs)
+
+    async def successful_request(req, session, pbar):
+        return next(pending_outputs)
+
+    pairs = await diffusion_benchmark._run_warmups(input_requests, warmup_args, None, successful_request)
+
+    assert [request.prompt for request, _ in pairs] == ["first", "second"]
+    assert [request.num_inference_steps for request, _ in pairs] == [4, 4]
+    assert [output for _, output in pairs] == outputs
+    assert [request.num_inference_steps for request in input_requests] == [20, 20]
+
+
+@pytest.mark.parametrize("failed_count", [1, 2], ids=["partial-failure", "all-failed"])
+@pytest.mark.parametrize(
+    "error",
+    ["HTTP 503: private prompt rejected", "Cannot connect to https://test.local/?token=private"],
+    ids=["http-error", "transport-error"],
+)
+async def test_failed_warmups_abort_without_exposing_response_errors(
+    diffusion_benchmark, warmup_args, input_requests, failed_count, error
+):
+    outputs = iter(
+        [RequestFuncOutput(success=False, error=error) for _ in range(failed_count)]
+        + [RequestFuncOutput(success=True) for _ in range(2 - failed_count)]
+    )
+
+    async def request(req, session, pbar):
+        return next(outputs)
+
+    with pytest.raises(RuntimeError, match=f"{failed_count}/2 warmup requests failed") as exc_info:
+        await diffusion_benchmark._run_warmups(input_requests, warmup_args, None, request)
+
+    assert error not in str(exc_info.value)
+    assert "server logs" in str(exc_info.value)
+
+
+async def test_benchmark_does_not_start_measurement_after_failed_warmup(
+    monkeypatch, mocker, diffusion_benchmark, warmup_args, input_requests
+):
+    sent = []
+
+    async def failed_request(req, session, pbar):
+        sent.append(req)
+        return RequestFuncOutput(success=False, error="HTTP 503: unavailable")
+
+    monkeypatch.setitem(
+        diffusion_benchmark.backends_function_mapping["2i"],
+        warmup_args.endpoint,
+        (failed_request, warmup_args.endpoint),
+    )
+    dataset = mocker.Mock(spec=diffusion_benchmark.RandomDataset)
+    dataset.get_requests.return_value = input_requests
+    monkeypatch.setattr(diffusion_benchmark, "RandomDataset", mocker.Mock(return_value=dataset))
+    timer = mocker.Mock(spec=diffusion_benchmark.time)
+    timer.perf_counter.side_effect = AssertionError("measurement started after failed warmup")
+    monkeypatch.setattr(diffusion_benchmark, "time", timer)
+
+    with pytest.raises(RuntimeError, match="2/2 warmup requests failed"):
+        await diffusion_benchmark.benchmark(warmup_args)
+
+    assert len(sent) == warmup_args.warmup_requests

From d4dba0ddb1d645b8e546a772f3b08e97835ac56c Mon Sep 17 00:00:00 2001
From: THUqliu <59546143+THUqliu@users.noreply.github.com>
Date: Thu, 17 Sep 2026 01:13:32 +0800
Subject: [PATCH 041/105] [Misc] Remove dead deploy keys from personaplex.yaml
 (#7454)

Signed-off-by: THUqliu <3298452736@qq.com>
---
 vllm_omni/deploy/personaplex.yaml | 4 ----
 1 file changed, 4 deletions(-)

diff --git a/vllm_omni/deploy/personaplex.yaml b/vllm_omni/deploy/personaplex.yaml
index 9f1da7e63ee..c4cc472d161 100644
--- a/vllm_omni/deploy/personaplex.yaml
+++ b/vllm_omni/deploy/personaplex.yaml
@@ -25,12 +25,8 @@ connectors:
     extra:
       shm_threshold_bytes: 65536
       codec_streaming: true
-      connector_get_sleep_s: 0.01
-      connector_get_max_wait_first_chunk: 3000
-      connector_get_max_wait: 300
       # Mimi runs at 12.5 Hz (80 ms / frame). Stream a few frames per chunk.
       codec_chunk_frames: 5
-      codec_left_context_frames: 10
       # Emit only the first audio chunk early, then return to codec_chunk_frames.
       initial_codec_chunk_frames: 1
 

From 4392af5ce37ea346a3b51914719a2679dd59d416 Mon Sep 17 00:00:00 2001
From: Deep Shah <deep@socratic.co>
Date: Wed, 16 Sep 2026 11:36:52 -0700
Subject: [PATCH 042/105] [Bugfix][Qwen3-Omni] Include deferred residual in
 captured Thinker states (#7304)

Signed-off-by: Deep Shah <deep@socratic.co>
---
 .../test_qwen3_omni_forward_contract.py       | 51 ++++++++++++++++++-
 .../qwen3_omni/qwen3_omni_moe_thinker.py      |  5 +-
 2 files changed, 53 insertions(+), 3 deletions(-)

diff --git a/tests/model_executor/models/qwen3_omni/test_qwen3_omni_forward_contract.py b/tests/model_executor/models/qwen3_omni/test_qwen3_omni_forward_contract.py
index 0055d1704ce..f4635a81f2f 100644
--- a/tests/model_executor/models/qwen3_omni/test_qwen3_omni_forward_contract.py
+++ b/tests/model_executor/models/qwen3_omni/test_qwen3_omni_forward_contract.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Regression tests for the Qwen3-Omni thinker forward return contract.
 
 Background
@@ -41,6 +41,7 @@
     Qwen3OmniMoeForConditionalGeneration,
 )
 from vllm_omni.model_executor.models.qwen3_omni.qwen3_omni_moe_thinker import (
+    Qwen3MoeLLMModel,
     Qwen3OmniMoeThinkerForConditionalGeneration,
 )
 
@@ -54,6 +55,52 @@ def _hidden_states() -> torch.Tensor:
     return torch.zeros(_TOKENS, _HIDDEN)
 
 
+def test_single_rank_intermediate_capture_includes_deferred_residual(mocker):
+    """Capture the Talker state on the default single-PP-rank path."""
+    import vllm_omni.model_executor.models.qwen3_omni.qwen3_omni_moe_thinker as module
+
+    pp_group = mocker.Mock(is_first_rank=True, is_last_rank=True)
+    mocker.patch.object(module, "get_pp_group", return_value=pp_group)
+
+    class SplitStateLayer(nn.Module):
+        def forward(self, positions, hidden_states, residual):
+            next_residual = hidden_states if residual is None else hidden_states + residual
+            return hidden_states * 2, next_residual
+
+    class Combine(nn.Module):
+        def forward(self, hidden_states, residual):
+            return hidden_states + residual, None
+
+    model = object.__new__(Qwen3MoeLLMModel)
+    nn.Module.__init__(model)
+    model.layers = nn.ModuleList([SplitStateLayer(), SplitStateLayer()])
+    model.start_layer = 0
+    model.end_layer = 2
+    model.norm = Combine()
+    inputs = torch.ones(_TOKENS, _HIDDEN)
+
+    output_without_capture, _ = Qwen3MoeLLMModel.forward(
+        model,
+        input_ids=None,
+        positions=torch.arange(_TOKENS),
+        inputs_embeds=inputs,
+    )
+    output_with_capture, captured = Qwen3MoeLLMModel.forward(
+        model,
+        input_ids=None,
+        positions=torch.arange(_TOKENS),
+        inputs_embeds=inputs,
+        capture_layer_indices=[0, 1],
+        return_hidden_states=True,
+    )
+
+    layers = captured["hidden_states"]["layers"]
+    torch.testing.assert_close(layers[0], inputs)
+    torch.testing.assert_close(layers[1], torch.full_like(inputs, 3))
+    torch.testing.assert_close(output_with_capture, output_without_capture)
+    torch.testing.assert_close(output_with_capture, torch.full_like(inputs, 7))
+
+
 class _InnerModelStub:
     """Stands in for ``Qwen3MoeLLMModel``: always returns the internal 2-tuple."""
 
@@ -169,7 +216,7 @@ def test_make_omni_output_accepts_bare_tensor():
 
 def test_make_omni_output_accepts_capture_tuple():
     model = _make_combined(is_staged_run=True)
-    captured = {"hidden_states": {"layers": {}}}
+    captured: dict[str, dict[str, dict[int, torch.Tensor]]] = {"hidden_states": {"layers": {}}}
     out = model.make_omni_output((_hidden_states(), captured))
     assert isinstance(out, OmniOutput)
     assert out.multimodal_outputs == captured
diff --git a/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py b/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py
index 8d0389d63e2..c78679c55d9 100644
--- a/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py
+++ b/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py
@@ -588,7 +588,10 @@ def forward(
                 if layer_idx in capture_set:
                     hs = captured_hidden_states.setdefault("hidden_states", {})
                     layers = hs.setdefault("layers", {})
-                    layers[layer_idx] = hidden_states.clone().view(-1, hidden_states.shape[-1])
+                    # vLLM defers the residual addition until the next RMSNorm.
+                    # Reconstruct the logical decoder state before capturing it.
+                    captured = hidden_states.clone() if residual is None else hidden_states + residual
+                    layers[layer_idx] = captured.view(-1, captured.shape[-1])
 
             hidden_states, residual = layer(
                 positions,

From 38c7eeee4c7662d28db0c8a3762ebce98d3a520a Mon Sep 17 00:00:00 2001
From: Lei Ke <1141466880@qq.com>
Date: Thu, 17 Sep 2026 02:38:06 +0800
Subject: [PATCH 043/105] [BugFix][NPU] Fix Fish Speech S2 Pro NPU support
 (#7546)

Signed-off-by: Lei Ke <1141466880@qq.com>
---
 tests/attention/test_fish_kvcache_attn.py              | 10 ++++++++++
 tests/config/test_config_factory.py                    |  7 +++++++
 vllm_omni/attention/fish_kvcache_attn.py               |  8 ++++++++
 vllm_omni/deploy/fish_qwen3_omni.yaml                  |  9 +++++++++
 .../models/fish_speech/fish_speech_slow_ar.py          |  7 ++++++-
 5 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/tests/attention/test_fish_kvcache_attn.py b/tests/attention/test_fish_kvcache_attn.py
index 4a8ea17e825..73d44295a33 100644
--- a/tests/attention/test_fish_kvcache_attn.py
+++ b/tests/attention/test_fish_kvcache_attn.py
@@ -3,6 +3,7 @@
 
 import pytest
 import torch
+from vllm.platforms import current_platform
 
 from vllm_omni.attention import fish_kvcache_attn, fish_kvcache_backend
 
@@ -113,6 +114,15 @@ def test_fish_kvcache_enabled_by_default(monkeypatch):
     assert not fish_kvcache_attn.is_fish_kvcache_attn_required()
 
 
+def test_fish_kvcache_fast_path_is_unavailable_off_cuda(monkeypatch):
+    monkeypatch.setattr(current_platform, "is_cuda", lambda: False)
+    monkeypatch.setattr(
+        fish_kvcache_attn, "_triton_backend", lambda: pytest.fail("Triton backend must not load off CUDA")
+    )
+
+    assert not fish_kvcache_attn.is_available()
+
+
 @pytest.mark.parametrize("value", ["", "1", "true", "yes", "on", "required"])
 def test_fish_kvcache_enabled_values_are_consistent(monkeypatch, value):
     monkeypatch.setenv("VLLM_OMNI_FISH_KVCACHE_ATTN", value)
diff --git a/tests/config/test_config_factory.py b/tests/config/test_config_factory.py
index c81a4b3b7a9..7940e217681 100644
--- a/tests/config/test_config_factory.py
+++ b/tests/config/test_config_factory.py
@@ -2688,6 +2688,13 @@ def test_minicpmo_4_5_cuda_caps_talker_kv_cache(self):
             # Explicit null clears the inherited single-GPU 2 GiB CUDA cap.
             assert replica_stages[1].yaml_engine_args.get("kv_cache_memory_bytes") is None
 
+    def test_fish_speech_npu_uses_ascend_kv_block_size(self):
+        deploy_path = Path(get_deploy_config_path("fish_qwen3_omni.yaml"))
+
+        deploy = _apply_platform_overrides(load_deploy_config(deploy_path), platform="npu")
+
+        assert deploy.stages[0].engine_extras["block_size"] == 128
+
     def test_npu_overrides(self):
         deploy_path = Path(get_deploy_config_path("qwen3_omni_moe.yaml"))
         if not deploy_path.exists():
diff --git a/vllm_omni/attention/fish_kvcache_attn.py b/vllm_omni/attention/fish_kvcache_attn.py
index e7235168cc3..6e402ca5475 100644
--- a/vllm_omni/attention/fish_kvcache_attn.py
+++ b/vllm_omni/attention/fish_kvcache_attn.py
@@ -24,6 +24,14 @@ def _triton_backend() -> Any:
 
 
 def is_available() -> bool:
+    # The Fish kvcache fast path is CUDA-only: it depends on FlashAttention's
+    # use_cascade metadata (absent from Ascend's metadata) and a Triton CUDA
+    # kernel. On other platforms report unavailable so the native attention
+    # backend takes over instead of crashing on attn_metadata.use_cascade.
+    from vllm.platforms import current_platform
+
+    if not current_platform.is_cuda():
+        return False
     return _triton_backend().is_available()
 
 
diff --git a/vllm_omni/deploy/fish_qwen3_omni.yaml b/vllm_omni/deploy/fish_qwen3_omni.yaml
index f10ed165658..0f4866a1fd5 100644
--- a/vllm_omni/deploy/fish_qwen3_omni.yaml
+++ b/vllm_omni/deploy/fish_qwen3_omni.yaml
@@ -64,6 +64,15 @@ stages:
       repetition_penalty: 1.0
 
 platforms:
+  npu:
+    # Ascend paged attention only accepts 128-token cache blocks
+    # (AscendAttentionBackend.get_supported_kernel_block_sizes() == [128]),
+    # while vLLM's CacheConfig default is 16. Without this override stage 0
+    # aborts during KV-cache init with:
+    #   ValueError: No common block size for 16.
+    stages:
+      - stage_id: 0
+        block_size: 128
   xpu:
     stages:
       # Verified on Intel Arc B60.
diff --git a/vllm_omni/model_executor/models/fish_speech/fish_speech_slow_ar.py b/vllm_omni/model_executor/models/fish_speech/fish_speech_slow_ar.py
index 1317dc04449..57f37f3d9f4 100644
--- a/vllm_omni/model_executor/models/fish_speech/fish_speech_slow_ar.py
+++ b/vllm_omni/model_executor/models/fish_speech/fish_speech_slow_ar.py
@@ -32,6 +32,7 @@
 from vllm.sequence import IntermediateTensors
 
 from vllm_omni.model_executor.models.output_templates import OmniOutput
+from vllm_omni.platforms import current_omni_platform
 from vllm_omni.utils.speaker_cache import get_speaker_cache
 
 from .configuration_fish_speech import FishSpeechConfig, FishSpeechFastARConfig, FishSpeechSlowARConfig
@@ -195,7 +196,11 @@ def __init__(self, *, vllm_config: VllmConfig, prefix: str = ""):
         self.mtp_hidden_size = int(self.text_config.hidden_size)
         self.talker_mtp_output_key = ("codes", "audio")
         self.gpu_resident_buffer_keys: set[tuple[str, str]] = {("hidden_states", "last")}
-        self.talker_mtp_graph_safe = True
+        # NPU (Ascend) ACL graphs cannot capture the Fast-AR random-sampling ops
+        # (torch.nonzero / torch.multinomial used for top-p), so keep the talker
+        # MTP eager on NPU to fall back to native (non-graph) execution. Mirrors
+        # the 310P patch for Qwen3-TTS (talker_mtp_graph_safe=False).
+        self.talker_mtp_graph_safe = not current_omni_platform.is_npu()
 
         # Qwen3 transformer backbone.
         self.model = Qwen3Model(vllm_config=vllm_config, prefix=maybe_prefix(prefix, "model"))

From c97b5fc741ea44acaed37efe520ef8600d1c2abf Mon Sep 17 00:00:00 2001
From: shiyichuan <93317314+CarrotSwordsman@users.noreply.github.com>
Date: Thu, 17 Sep 2026 02:38:45 +0800
Subject: [PATCH 044/105] [Bugfix][Frontend] Route synthetic aborts through
 final stage (#7006)

Signed-off-by: mershi <mershi@tencent.com>
Co-authored-by: mershi <mershi@tencent.com>
---
 tests/entrypoints/test_omni_entrypoints.py    | 38 +++++++++++++++++++
 vllm_omni/entrypoints/async_omni.py           |  1 +
 vllm_omni/entrypoints/async_omni_base.py      | 30 ++++++++++++---
 vllm_omni/entrypoints/client_request_state.py |  5 +++
 4 files changed, 69 insertions(+), 5 deletions(-)

diff --git a/tests/entrypoints/test_omni_entrypoints.py b/tests/entrypoints/test_omni_entrypoints.py
index 32d7d998819..ea57d07ab7a 100644
--- a/tests/entrypoints/test_omni_entrypoints.py
+++ b/tests/entrypoints/test_omni_entrypoints.py
@@ -3,6 +3,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import gc
 import queue
 from collections.abc import Callable
@@ -634,6 +635,43 @@ async def test_async_omni_llm_diffusion_yields_text_stream_then_image(monkeypatc
     assert "req-1" not in app.request_states
 
 
+@pytest.mark.asyncio
+async def test_async_omni_abort_yields_terminal_from_requested_final_stage(monkeypatch: pytest.MonkeyPatch):
+    stage_metadata = [
+        _stage_meta(stage_type="llm", final_output=False, final_output_type=None),
+        _stage_meta(stage_type="llm", final_output=True, final_output_type="audio"),
+    ]
+    engine = FakeAsyncOmniEngine(stage_metadata=stage_metadata)
+    _patch_engine(monkeypatch, engine)
+    app = AsyncOmni("dummy-model")
+
+    async def collect_outputs() -> list[OmniRequestOutput]:
+        return [
+            output
+            async for output in app.generate(
+                prompt="hello",
+                request_id="req-1",
+                output_modalities=["audio"],
+            )
+        ]
+
+    try:
+        generate_task = asyncio.create_task(collect_outputs())
+        while not engine.submitted:
+            await asyncio.sleep(0)
+        await app.abort("req-1")
+        outputs = await asyncio.wait_for(generate_task, timeout=1)
+    finally:
+        app.shutdown()
+
+    assert len(outputs) == 1
+    assert outputs[0].stage_id == 1
+    assert outputs[0].final_output_type == "audio"
+    assert outputs[0].finished is True
+    assert outputs[0].outputs[0].finish_reason == "abort"
+    assert "req-1" not in app.request_states
+
+
 @pytest.mark.asyncio
 async def test_async_omni_abort_forwards_to_engine(monkeypatch: pytest.MonkeyPatch):
     engine = FakeAsyncOmniEngine(stage_metadata=THREE_STAGE_META)
diff --git a/vllm_omni/entrypoints/async_omni.py b/vllm_omni/entrypoints/async_omni.py
index 6114bbea271..1291e68f058 100644
--- a/vllm_omni/entrypoints/async_omni.py
+++ b/vllm_omni/entrypoints/async_omni.py
@@ -236,6 +236,7 @@ async def generate(
             req_state = ClientRequestState(
                 request_id=request_id,
                 external_request_id=external_request_id,
+                final_stage_id=final_stage_id_for_e2e,
             )
             req_state.metrics = metrics
             req_state.request_arrival_ts = wall_start_ts
diff --git a/vllm_omni/entrypoints/async_omni_base.py b/vllm_omni/entrypoints/async_omni_base.py
index e7c86de978c..e9bf2c77ebe 100644
--- a/vllm_omni/entrypoints/async_omni_base.py
+++ b/vllm_omni/entrypoints/async_omni_base.py
@@ -479,7 +479,22 @@ async def _abort(self, request_ids: list[str], *, timeout: float | None = None)
             if state is not None and rid not in delivered:
                 queue = getattr(state, "queue", None)
                 if queue is not None:
-                    await state.queue.put(self._synthetic_abort_output_message(rid))
+                    final_stage_id = getattr(state, "final_stage_id", None)
+                    if final_stage_id is None:
+                        final_stage_id = 0
+                    stage_metadata = getattr(self, "_stage_meta_list", ())
+                    final_output_type = (
+                        getattr(stage_metadata[final_stage_id], "final_output_type", None)
+                        if final_stage_id < len(stage_metadata)
+                        else None
+                    ) or "text"
+                    await state.queue.put(
+                        self._synthetic_abort_output_message(
+                            rid,
+                            stage_id=final_stage_id,
+                            final_output_type=final_output_type,
+                        )
+                    )
                     delivered.add(rid)
         for rid in request_ids:
             self._record_request_failure_once(rid, reason="client_abort")
@@ -491,13 +506,18 @@ async def _abort(self, request_ids: list[str], *, timeout: float | None = None)
             logger.info("[AsyncOmni] Aborted request(s) %s", ",".join(request_ids))
 
     @staticmethod
-    def _synthetic_abort_output_message(request_id: str) -> OutputMessage:
+    def _synthetic_abort_output_message(
+        request_id: str,
+        *,
+        stage_id: int,
+        final_output_type: str,
+    ) -> OutputMessage:
         """Terminal abort OutputMessage used when the engine returned none."""
         engine_output = OmniRequestOutput(
             request_id=request_id,
             finished=True,
-            stage_id=0,
-            final_output_type="text",
+            stage_id=stage_id,
+            final_output_type=final_output_type,
             outputs=[
                 CompletionOutput(
                     index=0,
@@ -512,7 +532,7 @@ def _synthetic_abort_output_message(request_id: str) -> OutputMessage:
         )
         return OutputMessage(
             request_id=request_id,
-            stage_id=0,
+            stage_id=stage_id,
             replica_id=None,
             engine_outputs=engine_output,
             metrics=None,
diff --git a/vllm_omni/entrypoints/client_request_state.py b/vllm_omni/entrypoints/client_request_state.py
index 22f1c6d5e90..ca9e96bab3d 100644
--- a/vllm_omni/entrypoints/client_request_state.py
+++ b/vllm_omni/entrypoints/client_request_state.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 import asyncio
 
 from vllm_omni.metrics import OrchestratorAggregator
@@ -11,10 +14,12 @@ def __init__(
         request_id: str,
         external_request_id: str | None = None,
         queue: asyncio.Queue | None = None,
+        final_stage_id: int | None = None,
     ):
         self.request_id = request_id
         self.external_request_id = external_request_id
         self.stage_id: int | None = None
+        self.final_stage_id: int | None = final_stage_id
         self.queue = queue if queue is not None else asyncio.Queue()
         self.metrics: OrchestratorAggregator | None = None
         # Request-scoped idempotency guard for Prometheus failure counters.

From 04c55d0164e586373a2d3a3fdd8ab792b72017e8 Mon Sep 17 00:00:00 2001
From: nodeeeeee <zhangkai.nodeee@gmail.com>
Date: Thu, 17 Sep 2026 02:39:13 +0800
Subject: [PATCH 045/105] Preserve audio boundary embeddings in Qwen2.5-Omni
 interleaved input (#7510)

Signed-off-by: nodeeeeee <zhangkai.nodeee@gmail.com>
---
 .../test_qwen2_5_omni_expansion.py            | 26 ++++++++++
 .../qwen2_5_omni/test_per_video_audio_mask.py |  2 +-
 .../qwen2_5_omni/test_qwen2_5_omni_embed.py   | 50 +++++++++++++++++++
 .../qwen2_5_omni/qwen2_5_omni_thinker.py      |  8 ++-
 4 files changed, 83 insertions(+), 3 deletions(-)

diff --git a/tests/e2e/online_serving/test_qwen2_5_omni_expansion.py b/tests/e2e/online_serving/test_qwen2_5_omni_expansion.py
index 1e5e59aed2a..389b0b6ba56 100644
--- a/tests/e2e/online_serving/test_qwen2_5_omni_expansion.py
+++ b/tests/e2e/online_serving/test_qwen2_5_omni_expansion.py
@@ -96,6 +96,32 @@ def test_mix_to_text_audio_001(omni_server, online_client) -> None:
     online_client.send_omni_request(request_config)
 
 
+@pytest.mark.slow
+@pytest.mark.omni
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=2)
+@pytest.mark.parametrize("omni_server", test_params, indirect=True)
+@pytest.mark.parametrize("stream", [False, True])
+def test_audio_in_video_boundaries(omni_server, online_client, stream: bool) -> None:
+    """Interleaved video/audio input must not treat audio boundaries as image placeholders."""
+    # More than two seconds exercises multiple interleaved video/audio chunks.
+    video_data_url = f"data:video/mp4;base64,{generate_synthetic_video(224, 224, 128, embed_audio=True)['base64']}"
+    messages = dummy_messages_from_mix_data(
+        system_prompt=get_system_prompt(),
+        video_data_url=video_data_url,
+        content_text="Describe what you see and hear in this video in one sentence.",
+    )
+    responses = online_client.send_omni_request(
+        {
+            "model": omni_server.model,
+            "messages": messages,
+            "stream": stream,
+            "modalities": ["text"],
+            "use_audio_in_video": True,
+        }
+    )
+    assert responses[0].text_content
+
+
 @pytest.mark.slow
 @pytest.mark.omni
 @pytest.mark.parametrize("omni_server", test_params, indirect=True)
diff --git a/tests/model_executor/models/qwen2_5_omni/test_per_video_audio_mask.py b/tests/model_executor/models/qwen2_5_omni/test_per_video_audio_mask.py
index 54efc99e47c..9ebad492b34 100644
--- a/tests/model_executor/models/qwen2_5_omni/test_per_video_audio_mask.py
+++ b/tests/model_executor/models/qwen2_5_omni/test_per_video_audio_mask.py
@@ -582,7 +582,7 @@ def test_get_video_use_audio_in_video_falls_back_to_prompt_updates_for_cache_hit
 
 
 def test_derive_audio_from_video_placeholders_only_pairs_true_videos():
-    fake_self = _fake_processor()
+    fake_self = _fake_qwen2_prompt_processor()
     video_placeholders = [
         PlaceholderFeaturesInfo(
             modality="video",
diff --git a/tests/model_executor/models/qwen2_5_omni/test_qwen2_5_omni_embed.py b/tests/model_executor/models/qwen2_5_omni/test_qwen2_5_omni_embed.py
index 7b624ba119e..0d7cd817503 100644
--- a/tests/model_executor/models/qwen2_5_omni/test_qwen2_5_omni_embed.py
+++ b/tests/model_executor/models/qwen2_5_omni/test_qwen2_5_omni_embed.py
@@ -331,6 +331,56 @@ def test_interleaved_use_audio_in_video(self, mocker: MockerFixture):
             "Interleaved: audio positions should get audio embeddings"
         )
 
+    def test_interleaved_audio_boundaries_keep_text_embeddings(self, mocker: MockerFixture):
+        from vllm.multimodal.processing.processor import PlaceholderFeaturesInfo
+
+        from vllm_omni.model_executor.models.qwen2_5_omni.qwen2_5_omni_thinker import (
+            Qwen2_5OmniThinkerMultiModalProcessor,
+        )
+
+        processor = mocker.Mock()
+        processor.info.get_hf_processor.return_value = mocker.Mock(audio_token="audio", video_token="video")
+        processor.info.get_tokenizer.return_value.get_vocab.return_value = {
+            "audio": AUDIO_TOKEN_ID,
+            "video": VIDEO_TOKEN_ID,
+        }
+        # Real audio_bos/audio_eos IDs from the failing use_audio_in_video input.
+        tokens = [151647, VIDEO_TOKEN_ID, AUDIO_TOKEN_ID, VIDEO_TOKEN_ID, AUDIO_TOKEN_ID, 151648]
+        placeholder = PlaceholderFeaturesInfo(
+            modality="video",
+            item_idx=0,
+            start_idx=2,
+            tokens=tokens,
+            is_embed=torch.ones(len(tokens), dtype=torch.bool),
+        )
+        placeholders = Qwen2_5OmniThinkerMultiModalProcessor._derive_audio_from_video_placeholders(
+            processor,
+            {"video": [placeholder]},
+            {"audio": [[object()]]},
+            [True],
+        )
+
+        input_ids = torch.tensor([TEXT_TOKEN_ID] * 2 + tokens + [TEXT_TOKEN_ID])
+        is_multimodal = torch.zeros_like(input_ids, dtype=torch.bool)
+        for modality in ("audio", "video"):
+            derived = placeholders[modality][0].to_range()
+            is_multimodal[derived.offset : derived.offset + derived.length] |= derived.is_embed
+
+        model, hidden = make_mock_model(mocker, thinker_cls=_omni_qwen2_5_thinker_cls())
+        text_embeddings = model.get_language_model().embed_input_ids(input_ids)
+        result = model.embed_input_ids(
+            input_ids,
+            build_mm_embeds(audio_n=2, image_n=0, video_n=2, hidden=hidden),
+            is_multimodal=is_multimodal,
+        )
+
+        is_audio = input_ids == AUDIO_TOKEN_ID
+        is_video = input_ids == VIDEO_TOKEN_ID
+        assert torch.equal(is_multimodal, is_audio | is_video)
+        torch.testing.assert_close(result[is_audio], torch.full((2, hidden), 10.0))
+        torch.testing.assert_close(result[is_video], torch.full((2, hidden), 30.0))
+        torch.testing.assert_close(result[~(is_audio | is_video)], text_embeddings[~(is_audio | is_video)])
+
 
 # ---------------------------------------------------------------------------
 # Tests for merge_interleaved_embeddings helper
diff --git a/vllm_omni/model_executor/models/qwen2_5_omni/qwen2_5_omni_thinker.py b/vllm_omni/model_executor/models/qwen2_5_omni/qwen2_5_omni_thinker.py
index 263ffa2ab9b..b7b7d074c7d 100644
--- a/vllm_omni/model_executor/models/qwen2_5_omni/qwen2_5_omni_thinker.py
+++ b/vllm_omni/model_executor/models/qwen2_5_omni/qwen2_5_omni_thinker.py
@@ -758,6 +758,7 @@ def _derive_audio_from_video_placeholders(
         tokenizer = self.info.get_tokenizer()
         processor = self.info.get_hf_processor()
         audio_token_id = tokenizer.get_vocab()[processor.audio_token]
+        video_token_id = tokenizer.get_vocab()[processor.video_token]
 
         result_placeholders = dict(placeholders)
         audio_placeholders = []
@@ -765,7 +766,10 @@ def _derive_audio_from_video_placeholders(
 
         audio_idx = 0
         for video_idx, video_placeholder in enumerate(placeholders["video"]):
-            audio_is_embed = torch.tensor(video_placeholder.tokens) == audio_token_id
+            placeholder_tokens = torch.tensor(video_placeholder.tokens)
+            audio_is_embed = placeholder_tokens == audio_token_id
+            # Audio boundary tokens keep their text embeddings.
+            video_is_embed = placeholder_tokens == video_token_id
 
             if video_use_audio_in_video[video_idx]:
                 audio_placeholder = PlaceholderFeaturesInfo(
@@ -783,7 +787,7 @@ def _derive_audio_from_video_placeholders(
                 item_idx=video_idx,
                 start_idx=video_placeholder.start_idx,
                 tokens=video_placeholder.tokens,
-                is_embed=~audio_is_embed,
+                is_embed=video_is_embed,
             )
             video_placeholders.append(video_placeholder_with_mask)
 

From a8434a60da1f40a0d118a326908fd20c9ebe75c7 Mon Sep 17 00:00:00 2001
From: akshatvishu <akshatnayak197@gmail.com>
Date: Thu, 17 Sep 2026 00:09:51 +0530
Subject: [PATCH 046/105] [BugFix][TTS] Fix MOSS Realtime serving and
 generation (#5661)

Signed-off-by: akshatvishu <akshatnayak197@gmail.com>
---
 .../test_moss_tts_expansion.py                |   9 +-
 .../test_moss_tts_realtime.py                 |   5 +-
 .../test_moss_tts_realtime_expansion.py       |   5 +-
 .../online_serving/test_moss_tts_expansion.py |  28 +-
 .../test_moss_tts_realtime_serving.py         | 302 ++++++++++++++++++
 .../moss_tts/test_audio_tokenizer_v2.py       |  54 ++++
 .../moss_tts/test_realtime_chunked_prefill.py |  86 +++++
 .../test_realtime_generation_limit.py         |  53 +++
 .../models/moss_tts/test_realtime_prompt.py   |  78 +++++
 .../openai/tts_adapters/moss_tts.py           |  71 +++-
 .../moss_tts/modeling_moss_tts_talker.py      |  57 ++--
 .../models/moss_tts/realtime_prompt.py        |  60 ++++
 .../models/moss_tts/reference_encoder.py      |  27 +-
 13 files changed, 771 insertions(+), 64 deletions(-)
 create mode 100644 tests/entrypoints/openai_api/test_moss_tts_realtime_serving.py
 create mode 100644 tests/model_executor/models/moss_tts/test_audio_tokenizer_v2.py
 create mode 100644 tests/model_executor/models/moss_tts/test_realtime_chunked_prefill.py
 create mode 100644 tests/model_executor/models/moss_tts/test_realtime_generation_limit.py
 create mode 100644 tests/model_executor/models/moss_tts/test_realtime_prompt.py
 create mode 100644 vllm_omni/model_executor/models/moss_tts/realtime_prompt.py

diff --git a/tests/e2e/offline_inference/test_moss_tts_expansion.py b/tests/e2e/offline_inference/test_moss_tts_expansion.py
index 81a64fcd9d8..b899252b4f0 100644
--- a/tests/e2e/offline_inference/test_moss_tts_expansion.py
+++ b/tests/e2e/offline_inference/test_moss_tts_expansion.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """E2E offline inference tests for MOSS-VoiceGenerator (MossTTSDelayModel, 1.7B).
 
 Weekly expansion coverage (``pytest.mark.slow``) for the delay-model path.
@@ -74,7 +74,6 @@ def _get_test_config() -> str:
 
 pytestmark = [
     pytest.mark.slow,
-    pytest.mark.skip(reason="https://github.com/vllm-project/vllm-omni/issues/4700"),
     pytest.mark.tts,
     pytest.mark.parametrize(
         "omni_runner",
@@ -137,7 +136,7 @@ def _collect_audio(omni_runner: OmniRunner, request: dict) -> tuple[torch.Tensor
     return torch.cat(chunks, dim=0), sr_final
 
 
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 def test_moss_tts_delay_english(omni_runner: OmniRunner) -> None:
     """VoiceGenerator: English instruction produces non-empty 24 kHz audio."""
     req = _build_request(
@@ -151,7 +150,7 @@ def test_moss_tts_delay_english(omni_runner: OmniRunner) -> None:
     assert not torch.all(audio == 0), "Audio is silence"
 
 
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 def test_moss_tts_delay_chinese(omni_runner: OmniRunner) -> None:
     """VoiceGenerator: Chinese input produces non-empty audio."""
     req = _build_request(
@@ -165,7 +164,7 @@ def test_moss_tts_delay_chinese(omni_runner: OmniRunner) -> None:
     assert not torch.all(audio == 0)
 
 
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 def test_moss_tts_delay_batch(omni_runner: OmniRunner) -> None:
     """VoiceGenerator: batch of two requests each returns non-empty audio."""
     requests = [
diff --git a/tests/e2e/offline_inference/test_moss_tts_realtime.py b/tests/e2e/offline_inference/test_moss_tts_realtime.py
index 81d97cd743c..0f0bf59c73e 100644
--- a/tests/e2e/offline_inference/test_moss_tts_realtime.py
+++ b/tests/e2e/offline_inference/test_moss_tts_realtime.py
@@ -95,7 +95,6 @@ def _get_test_config() -> str:
 # ---------------------------------------------------------------------------
 
 pytestmark = [
-    pytest.mark.skip(reason="https://github.com/vllm-project/vllm-omni/issues/4700"),
     pytest.mark.slow,
     pytest.mark.tts,
     pytest.mark.parametrize(
@@ -272,7 +271,7 @@ def _collect_audio(omni_runner: OmniRunner, request: dict) -> tuple[torch.Tensor
 # ---------------------------------------------------------------------------
 
 
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 def test_moss_tts_realtime_english(omni_runner: OmniRunner, ref_audio_path: str) -> None:
     """MossTTSRealtime: English voice_clone produces non-empty 24 kHz audio."""
     req = _build_request(ref_audio_path, "This is a real-time TTS streaming test.")
@@ -283,7 +282,7 @@ def test_moss_tts_realtime_english(omni_runner: OmniRunner, ref_audio_path: str)
     assert not torch.all(audio == 0), "Audio is silence"
 
 
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 def test_moss_tts_realtime_chinese(omni_runner: OmniRunner, ref_audio_path: str) -> None:
     """MossTTSRealtime: Chinese input produces non-empty audio."""
     req = _build_request(ref_audio_path, "你好，这是语音合成测试。")
diff --git a/tests/e2e/offline_inference/test_moss_tts_realtime_expansion.py b/tests/e2e/offline_inference/test_moss_tts_realtime_expansion.py
index b84e5a0ff1e..678fc7e55db 100644
--- a/tests/e2e/offline_inference/test_moss_tts_realtime_expansion.py
+++ b/tests/e2e/offline_inference/test_moss_tts_realtime_expansion.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """E2E offline inference tests for MOSS-TTS-Realtime (MossTTSRealtime, 1.7B).
 
 Exercises the local-transformer generation path on L4. Delay-model coverage is in
@@ -33,7 +33,6 @@
 pytestmark = [
     pytest.mark.slow,
     pytest.mark.tts,
-    pytest.mark.skip(reason="https://github.com/vllm-project/vllm-omni/issues/4700"),
     pytest.mark.parametrize("omni_runner", [_OMNI_RUNNER_PARAM], indirect=True),
 ]
 
@@ -118,7 +117,7 @@ def _collect_audio(omni_runner: OmniRunner, request: dict) -> tuple[torch.Tensor
     raise AssertionError("No stage outputs received")
 
 
-@hardware_test(res={"cuda": "L4"})
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 def test_moss_tts_realtime_english(omni_runner: OmniRunner, ref_audio_path) -> None:
     """MossTTSRealtime: English voice_clone produces non-empty 24 kHz audio."""
     req = _build_request("This is a real-time TTS streaming test.", ref_audio_path)
diff --git a/tests/e2e/online_serving/test_moss_tts_expansion.py b/tests/e2e/online_serving/test_moss_tts_expansion.py
index 598326a1eb6..bd38a7fc7f7 100644
--- a/tests/e2e/online_serving/test_moss_tts_expansion.py
+++ b/tests/e2e/online_serving/test_moss_tts_expansion.py
@@ -30,20 +30,16 @@
 from tests.helpers.runtime import OmniServerParams
 from tests.helpers.stage_config import get_deploy_config_path
 
-_SKIP_ISSUE_6417 = pytest.mark.skip(
-    reason="https://github.com/vllm-project/vllm-omni/issues/6417",
-)
-
 pytestmark = [
+    pytest.mark.advanced_model,
     pytest.mark.slow,
     pytest.mark.tts,
-    _SKIP_ISSUE_6417,
 ]
 
 MODEL = "OpenMOSS-Team/MOSS-TTS-Realtime"
 REF_AUDIO_URL = "https://raw.githubusercontent.com/OpenMOSS/MOSS-TTS/HEAD/assets/audio/reference_zh_1.wav"
-# Voice-clone output is not reliably transcribed by the Whisper check used at
-# full_model run_level; assert non-trivial WAV payload size instead.
+# Reject a response that contains only a header or a very short audio payload.
+# Advanced and full runs also validate the transcript.
 _MIN_AUDIO_BYTES = 10_000
 
 
@@ -77,7 +73,9 @@ def get_prompt(prompt_type: str = "text") -> str:
     """
     prompts = {
         "text": "Hello, this is a real-time voice cloning demo for testing.",
-        "chinese": "你好，这是一段实时语音合成测试。",
+        # Match the offline test prompt. Whisper-small can transcribe "一段"
+        # as "一本", which makes this short sample fail the similarity check.
+        "chinese": "你好，这是语音合成测试。",
     }
     return prompts.get(prompt_type, prompts["text"])
 
@@ -94,7 +92,7 @@ def get_prompt(prompt_type: str = "text") -> str:
 ]
 
 
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 @pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
 def test_text_to_audio_001(omni_server, online_client, ref_audio_data_url) -> None:
     """
@@ -105,9 +103,8 @@ def test_text_to_audio_001(omni_server, online_client, ref_audio_data_url) -> No
     Input Setting: stream=False
     Datasets: single request
 
-    NOTE: ``min_audio_bytes`` skips Whisper transcript similarity — cloned
-    voice output is often empty or mismatched under ASR without indicating a
-    real serving regression.
+    ``min_audio_bytes`` adds a payload-size check. It does not disable the
+    transcript check used by advanced and full runs.
     """
     request_config = {
         "model": omni_server.model,
@@ -121,7 +118,7 @@ def test_text_to_audio_001(omni_server, online_client, ref_audio_data_url) -> No
     online_client.send_audio_speech_request(request_config)
 
 
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 @pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
 def test_text_to_audio_002_streaming(omni_server, online_client, ref_audio_data_url) -> None:
     """
@@ -150,7 +147,7 @@ def test_text_to_audio_002_streaming(omni_server, online_client, ref_audio_data_
     online_client.send_audio_speech_request(request_config)
 
 
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 @pytest.mark.parametrize("omni_server", tts_server_params, indirect=True)
 def test_text_to_audio_003_chinese(omni_server, online_client, ref_audio_data_url) -> None:
     """
@@ -161,7 +158,8 @@ def test_text_to_audio_003_chinese(omni_server, online_client, ref_audio_data_ur
     Input Setting: stream=False
     Datasets: single request
 
-    NOTE: same ``min_audio_bytes`` rationale as test_text_to_audio_001.
+    ``min_audio_bytes`` adds a payload-size check. It does not disable the
+    transcript check used by advanced and full runs.
     """
     request_config = {
         "model": omni_server.model,
diff --git a/tests/entrypoints/openai_api/test_moss_tts_realtime_serving.py b/tests/entrypoints/openai_api/test_moss_tts_realtime_serving.py
new file mode 100644
index 00000000000..d6959763494
--- /dev/null
+++ b/tests/entrypoints/openai_api/test_moss_tts_realtime_serving.py
@@ -0,0 +1,302 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import asyncio
+import threading
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+import torch
+
+from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
+from vllm_omni.entrypoints.openai.tts_adapters import moss_tts as adapter_module
+from vllm_omni.entrypoints.openai.tts_adapters.base import SpeechServingContext
+from vllm_omni.entrypoints.openai.tts_adapters.moss_tts import MossTTSAdapter
+from vllm_omni.model_executor.models.moss_tts import reference_encoder
+from vllm_omni.utils.speaker_cache import SpeakerEmbeddingCache
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+@pytest.mark.parametrize(
+    ("hf_config", "expected_codec_path"),
+    [
+        (SimpleNamespace(), "OpenMOSS-Team/MOSS-Audio-Tokenizer"),
+        (
+            SimpleNamespace(codec_model_name_or_path="/models/custom-moss-codec"),
+            "/models/custom-moss-codec",
+        ),
+    ],
+    ids=["default-codec", "configured-codec"],
+)
+def test_realtime_components_use_the_realtime_model_and_codec(
+    monkeypatch: pytest.MonkeyPatch,
+    hf_config: SimpleNamespace,
+    expected_codec_path: str,
+) -> None:
+    engine_client = SimpleNamespace(
+        model_config=SimpleNamespace(
+            model="OpenMOSS-Team/MOSS-TTS-Realtime",
+            hf_config=hf_config,
+        )
+    )
+
+    server = MossTTSAdapter(SpeechServingContext(server=object(), engine_client=engine_client))
+
+    tokenizer = object()
+    codec = type("Codec", (), {"to": lambda self, device: self, "eval": lambda self: self})()
+    processor_calls = []
+
+    class Processor:
+        def __init__(self, *, tokenizer):
+            processor_calls.append(tokenizer)
+
+    class_calls = []
+    tokenizer_calls = []
+    codec_calls = []
+
+    def fake_get_class(class_reference, model_id):
+        class_calls.append((class_reference, model_id))
+        return Processor
+
+    def fake_load_tokenizer(model_id, *, trust_remote_code):
+        tokenizer_calls.append((model_id, trust_remote_code))
+        return tokenizer
+
+    def fake_load_codec(model_id, *, trust_remote_code):
+        codec_calls.append((model_id, trust_remote_code))
+        return codec
+
+    monkeypatch.setattr(adapter_module, "get_class_from_dynamic_module", fake_get_class)
+    monkeypatch.setattr(adapter_module.AutoTokenizer, "from_pretrained", fake_load_tokenizer)
+    monkeypatch.setattr(adapter_module.AutoModel, "from_pretrained", fake_load_codec)
+
+    components = server._get_moss_realtime_components()
+
+    assert components[0] is tokenizer
+    assert components[2] is codec
+    assert server._get_moss_realtime_components() is components
+    assert class_calls == [
+        (
+            "processing_mossttsrealtime.MossTTSRealtimeProcessor",
+            "OpenMOSS-Team/MOSS-TTS-Realtime",
+        )
+    ]
+    assert tokenizer_calls == [("OpenMOSS-Team/MOSS-TTS-Realtime", True)]
+    assert codec_calls == [(expected_codec_path, True)]
+    assert processor_calls == [tokenizer]
+
+
+def test_realtime_serving_builds_the_talker_prompt(monkeypatch: pytest.MonkeyPatch) -> None:
+    server = MossTTSAdapter(SpeechServingContext(server=SimpleNamespace(uploaded_speakers={})))
+    server._moss_variant = "realtime"
+    tokenizer = object()
+    processor = object()
+    codec = object()
+    request_thread = threading.get_ident()
+
+    def load_components():
+        assert threading.get_ident() != request_thread
+        return tokenizer, processor, codec
+
+    server._get_moss_realtime_components = load_components
+
+    reference_codes = torch.arange(64, dtype=torch.int64).reshape(4, 16)
+    encode = AsyncMock(return_value=([reference_codes], {0: "reference-cache-key"}))
+    monkeypatch.setattr(server, "_encode_moss_references", encode)
+
+    build_call = None
+
+    def fake_build(actual_tokenizer, actual_processor, text, actual_codes):
+        nonlocal build_call
+        build_call = (actual_tokenizer, actual_processor, text, actual_codes)
+        return {
+            "prompt_token_ids": [10, 11],
+            "codes": {"ref": actual_codes},
+            "ids": {"all": [12]},
+        }
+
+    monkeypatch.setattr(adapter_module, "build_realtime_prompt", fake_build)
+
+    params = asyncio.run(
+        server._build_moss_tts_params(
+            OpenAICreateSpeechRequest(
+                input="speak this text",
+                ref_audio="data:audio/wav;base64,AAAA",
+                max_new_tokens=50,
+            )
+        )
+    )
+
+    encode.assert_awaited_once()
+    assert encode.call_args.kwargs == {"has_inline_ref_audio": False, "two_speaker": False}
+    assert encode.call_args.args[0].ref_audio == "data:audio/wav;base64,AAAA"
+    assert build_call == (tokenizer, processor, "speak this text", reference_codes)
+    assert params == {
+        "prompt_token_ids": [10, 11],
+        "codes": {"ref": reference_codes},
+        "ids": {"all": [12]},
+        "max_new_frames": [50],
+        "ref_audio_cache_key": "reference-cache-key",
+    }
+    assert "prompt_audio_array" not in params
+
+
+def test_cancelled_component_waiter_does_not_duplicate_codec_load(monkeypatch):
+    adapter = MossTTSAdapter(
+        SpeechServingContext(
+            server=object(),
+            engine_client=SimpleNamespace(
+                model_config=SimpleNamespace(model="OpenMOSS-Team/MOSS-TTS-Realtime", hf_config=SimpleNamespace())
+            ),
+        )
+    )
+    started = threading.Event()
+    release = threading.Event()
+    second_started = threading.Event()
+    loads = []
+    codec = type("Codec", (), {"to": lambda self, device: self, "eval": lambda self: self})()
+
+    def load_codec(*args, **kwargs):
+        loads.append(args)
+        started.set()
+        assert release.wait(5), "codec loader was not released"
+        return codec
+
+    monkeypatch.setattr(adapter_module, "get_class_from_dynamic_module", lambda *args: lambda **kwargs: object())
+    monkeypatch.setattr(adapter_module.AutoTokenizer, "from_pretrained", lambda *args, **kwargs: object())
+    monkeypatch.setattr(adapter_module.AutoModel, "from_pretrained", load_codec)
+
+    def second_load():
+        second_started.set()
+        return adapter._get_moss_realtime_components()
+
+    async def run():
+        first = asyncio.create_task(asyncio.to_thread(adapter._get_moss_realtime_components))
+        try:
+            assert await asyncio.to_thread(started.wait, 5)
+            first.cancel()
+            with pytest.raises(asyncio.CancelledError):
+                await first
+            second = asyncio.create_task(asyncio.to_thread(second_load))
+            try:
+                assert await asyncio.to_thread(second_started.wait, 5)
+            finally:
+                release.set()
+            components = await asyncio.wait_for(second, 5)
+            assert components[2] is codec
+            assert adapter._get_moss_realtime_components() is components
+            assert len(loads) == 1
+        finally:
+            release.set()
+
+    asyncio.run(run())
+
+
+@pytest.mark.parametrize("voice_name", [None, "speaker"])
+def test_realtime_reference_cache_reuses_codes(voice_name):
+    cache = SpeakerEmbeddingCache()
+    resolve = AsyncMock(return_value=([0.0], 24000, "audio-key"))
+    request_thread = threading.get_ident()
+    encode_calls = []
+    expected = torch.arange(64).reshape(4, 16)
+
+    def batch_encode(wavs, *, num_quantizers):
+        assert threading.get_ident() != request_thread
+        assert num_quantizers == 16
+        encode_calls.append(wavs)
+        return SimpleNamespace(audio_codes=expected.T.unsqueeze(1), audio_codes_lengths=torch.tensor([4]))
+
+    encoder = reference_encoder.build_reference_encoder(
+        SimpleNamespace(batch_encode=batch_encode), variant="realtime", speaker_cache=cache
+    )
+
+    async def run():
+        kwargs = dict(
+            resolve_ref_audio=resolve,
+            get_artifact_key=lambda key: "content-key",
+            voice_name=voice_name,
+            voice_created_at=1,
+        )
+        try:
+            first, first_key = await encoder.encode("reference", **kwargs)
+            second, second_key = await encoder.encode("reference", **kwargs)
+            assert torch.equal(first, expected)
+            assert torch.equal(second, expected)
+            assert first.dtype == torch.int64
+            assert first_key == "audio-key"
+            assert second_key == (None if voice_name else "audio-key")
+            second.zero_()
+            third, _ = await encoder.encode("another-reference", **kwargs)
+            assert torch.equal(third, expected)
+            assert len(encode_calls) == 1
+            assert resolve.await_count == (1 if voice_name else 3)
+            key = cache.make_cache_key(
+                voice_name or "ref:content-key", "moss_tts_realtime_nq16", 1 if voice_name else 0
+            )
+            assert cache.get(key)["codes"].dtype == torch.int32
+            if voice_name:
+                kwargs["voice_created_at"] = 2
+                await encoder.encode("reference", **kwargs)
+                assert len(encode_calls) == 2
+                assert resolve.await_count == 2
+        finally:
+            await encoder.aclose()
+
+    asyncio.run(run())
+
+
+def test_realtime_reference_batch_trims_each_item():
+    cache = SpeakerEmbeddingCache()
+    codes = torch.arange(16 * 2 * 5).reshape(16, 2, 5)
+    calls = []
+
+    def batch_encode(wavs, *, num_quantizers):
+        calls.append(wavs)
+        assert num_quantizers == 16
+        assert [wav.shape for wav in wavs] == [torch.Size([8]), torch.Size([12])]
+        return SimpleNamespace(audio_codes=codes, audio_codes_lengths=torch.tensor([3, 5]))
+
+    encoder = reference_encoder.build_reference_encoder(
+        SimpleNamespace(batch_encode=batch_encode), variant="realtime", speaker_cache=cache
+    )
+
+    async def resolve(ref):
+        return [0.0] * (8 if ref == "short" else 12), 24000, ref
+
+    async def run():
+        try:
+            short, long = await asyncio.gather(
+                encoder.encode("short", resolve_ref_audio=resolve, get_artifact_key=lambda key: key),
+                encoder.encode("long", resolve_ref_audio=resolve, get_artifact_key=lambda key: key),
+            )
+            torch.testing.assert_close(short[0], codes[:, 0, :3].T)
+            torch.testing.assert_close(long[0], codes[:, 1, :5].T)
+            assert len(calls) == 1
+        finally:
+            await encoder.aclose()
+
+    asyncio.run(run())
+
+
+def test_failed_realtime_reference_encoding_does_not_populate_cache():
+    cache = SpeakerEmbeddingCache()
+    resolve = AsyncMock(return_value=([0.0], 24000, "audio-key"))
+
+    def fail(*args, **kwargs):
+        raise ValueError("invalid reference")
+
+    encoder = reference_encoder.build_reference_encoder(
+        SimpleNamespace(batch_encode=fail), variant="realtime", speaker_cache=cache
+    )
+
+    async def run():
+        try:
+            with pytest.raises(ValueError, match="invalid reference"):
+                await encoder.encode("reference", resolve_ref_audio=resolve, get_artifact_key=lambda key: None)
+            assert cache.memory_bytes() == 0
+        finally:
+            await encoder.aclose()
+
+    asyncio.run(run())
diff --git a/tests/model_executor/models/moss_tts/test_audio_tokenizer_v2.py b/tests/model_executor/models/moss_tts/test_audio_tokenizer_v2.py
new file mode 100644
index 00000000000..f5d799dd758
--- /dev/null
+++ b/tests/model_executor/models/moss_tts/test_audio_tokenizer_v2.py
@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Regression tests for MOSS audio tokenizer v2 projection modules."""
+
+from __future__ import annotations
+
+import pytest
+import torch
+import torch.nn as nn
+
+from vllm_omni.model_executor.models.moss_tts.audio_tokenizer_v2 import (
+    MossAudioTokenizerProjectedTransformer,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_projected_transformer_keeps_learned_projections_when_dimensions_match() -> None:
+    module = MossAudioTokenizerProjectedTransformer(
+        input_dimension=8,
+        output_dimension=8,
+        d_model=8,
+        module_type="transformer",
+        num_heads=1,
+        num_layers=0,
+        positional_embedding="rope",
+    )
+
+    assert isinstance(module.input_proj, nn.Linear)
+    assert isinstance(module.output_proj, nn.Linear)
+    assert module.input_proj.weight.shape == (8, 8)
+    assert module.output_proj.weight.shape == (8, 8)
+
+    x = torch.randn(2, 8, 5)
+    lengths = torch.tensor([5, 3], dtype=torch.long)
+    output, output_lengths = module(x, lengths)
+
+    assert output.shape == x.shape
+    torch.testing.assert_close(output_lengths, lengths)
+
+
+def test_projected_transformer_keeps_linear_projections_when_dimensions_differ() -> None:
+    module = MossAudioTokenizerProjectedTransformer(
+        input_dimension=8,
+        output_dimension=6,
+        d_model=10,
+        module_type="transformer",
+        num_heads=1,
+        num_layers=0,
+        positional_embedding="rope",
+    )
+
+    assert isinstance(module.input_proj, nn.Linear)
+    assert isinstance(module.output_proj, nn.Linear)
diff --git a/tests/model_executor/models/moss_tts/test_realtime_chunked_prefill.py b/tests/model_executor/models/moss_tts/test_realtime_chunked_prefill.py
new file mode 100644
index 00000000000..916213318aa
--- /dev/null
+++ b/tests/model_executor/models/moss_tts/test_realtime_chunked_prefill.py
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from types import SimpleNamespace
+from typing import Any
+
+import pytest
+import torch
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_realtime_talker_preserves_state_across_chunked_prefill() -> None:
+    from vllm_omni.model_executor.models.moss_tts.modeling_moss_tts_talker import (
+        MossTTSRealtimeTalkerForGeneration,
+    )
+
+    talker = MossTTSRealtimeTalkerForGeneration.__new__(MossTTSRealtimeTalkerForGeneration)
+    talker.n_vq = 2
+    talker.audio_pad_token = 1024
+    talker.text_vocab_size = 16
+    talker.text_pad_id = 2
+    talker._batch_state = None
+    talker._batch_state_spans = None
+
+    embedded_audio: list[torch.Tensor | None] = []
+
+    def build_input_embeds(input_ids, audio_codes):
+        embedded_audio.append(audio_codes.clone() if audio_codes is not None else None)
+        return torch.zeros((input_ids.shape[0], 1))
+
+    generated: list[None] = []
+
+    def generate_frame(*args, **kwargs):
+        generated.append(None)
+        return torch.ones((1, talker.n_vq), dtype=torch.long)
+
+    talker._build_input_embeds = build_input_embeds
+    talker.local_transformer = SimpleNamespace(generate_frame=generate_frame)
+    talker.local_lm_heads = []
+
+    ref_codes = torch.arange(10, dtype=torch.long).reshape(5, 2)
+    info: dict[str, Any] = {
+        "codes": {"ref": ref_codes},
+        "ids": {"all": [7, 8]},
+        "max_new_frames": [3],
+    }
+    chunks = [(0, 2, False), (2, 2, False), (4, 1, True)]
+
+    state: dict[str, Any] | None = None
+    for computed, length, eligible in chunks:
+        _, _, update = talker.preprocess(
+            torch.ones(length, dtype=torch.long),
+            None,
+            _omni_is_prefill=True,
+            _omni_num_computed_tokens=computed,
+            _omni_prompt_len=5,
+            **info,
+        )
+        info.update(update)
+        if state is None:
+            state = info["audio_state"]
+        else:
+            assert info["audio_state"] is state
+
+        output = talker.make_omni_output(
+            torch.ones((length, 1)),
+            model_intermediate_buffer=[info],
+            request_token_spans=[(0, length)],
+            request_sample_eligible=[eligible],
+        )
+        if not eligible:
+            assert output.multimodal_outputs == {}
+        logits = talker.compute_logits(torch.ones((1, 1)))
+        assert logits.argmax().item() == (7 if eligible else talker.text_pad_id)
+
+    assert state is not None
+    assert info["ref_offset"] == 5
+    assert state["step"] == 1
+    assert state["text_cursor"] == 1
+    assert state["remaining_text"] == [7, 8]
+    assert len(generated) == 1
+    assert output.multimodal_outputs["codes"]["audio"][0].shape == (1, 2)
+    for actual, expected in zip(embedded_audio, ref_codes.split((2, 2, 1)), strict=True):
+        assert actual is not None
+        torch.testing.assert_close(actual, expected)
diff --git a/tests/model_executor/models/moss_tts/test_realtime_generation_limit.py b/tests/model_executor/models/moss_tts/test_realtime_generation_limit.py
new file mode 100644
index 00000000000..1bbfaeeef9f
--- /dev/null
+++ b/tests/model_executor/models/moss_tts/test_realtime_generation_limit.py
@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from types import SimpleNamespace
+
+import pytest
+import torch
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_realtime_talker_stops_at_max_new_frames() -> None:
+    from vllm_omni.model_executor.models.moss_tts.modeling_moss_tts_talker import (
+        MossTTSRealtimeTalkerForGeneration,
+    )
+
+    talker = MossTTSRealtimeTalkerForGeneration.__new__(MossTTSRealtimeTalkerForGeneration)
+    talker.n_vq = 4
+    talker.audio_pad_token = 1024
+    talker.text_vocab_size = 8
+    talker.text_pad_id = 2
+    talker.audio_eos_id = 3
+    talker._batch_state = None
+    talker._build_input_embeds = lambda input_ids, audio_codes: torch.zeros((input_ids.shape[0], 1))
+
+    generated: list[None] = []
+
+    def generate_frame(*args, **kwargs):
+        generated.append(None)
+        return torch.ones((1, talker.n_vq), dtype=torch.long)
+
+    talker.local_transformer = SimpleNamespace(generate_frame=generate_frame)
+    talker.local_lm_heads = []
+
+    _, _, info = talker.preprocess(
+        torch.tensor([1, 2]),
+        None,
+        max_new_frames=[2],
+    )
+    assert info["audio_state"]["max_new_frames"] == 2
+
+    for _ in range(3):
+        output = talker.make_omni_output(
+            torch.ones((1, 1)),
+            runtime_additional_information=[info],
+            request_token_spans=[(0, 1)],
+        )
+
+    assert len(generated) == 2
+    assert info["audio_state"]["step"] == 2
+    assert info["audio_state"]["is_stopping"] is True
+    assert output.multimodal_outputs == {}
+    assert talker.compute_logits(torch.ones((1, 1))).argmax().item() == talker.audio_eos_id
diff --git a/tests/model_executor/models/moss_tts/test_realtime_prompt.py b/tests/model_executor/models/moss_tts/test_realtime_prompt.py
new file mode 100644
index 00000000000..cb36f6dd8f7
--- /dev/null
+++ b/tests/model_executor/models/moss_tts/test_realtime_prompt.py
@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import numpy as np
+import pytest
+import torch
+
+from vllm_omni.model_executor.models.moss_tts.realtime_prompt import build_realtime_prompt
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+class _Tokenizer:
+    def encode(self, text: str, add_special_tokens: bool = False) -> list[int]:
+        del add_special_tokens
+        if text == "<|im_start|>assistant\n":
+            return [20, 21]
+        return list(range(100, 100 + len(text.split())))
+
+
+class _Processor:
+    audio_channel_pad = 1024
+    audio_bos_token = 1025
+
+    def __init__(self) -> None:
+        self.reference_codes = None
+
+    def make_ensemble(self, prompt_audio_tokens):
+        self.reference_codes = prompt_audio_tokens
+        return np.full((3, 17), self.audio_channel_pad, dtype=np.int64)
+
+
+def test_build_realtime_prompt_aligns_reference_and_prefill_text() -> None:
+    processor = _Processor()
+    reference_codes = torch.arange(80, dtype=torch.int64).reshape(5, 16)
+
+    params = build_realtime_prompt(
+        _Tokenizer(),
+        processor,
+        "one two three",
+        reference_codes,
+    )
+
+    assert np.array_equal(processor.reference_codes, reference_codes.numpy())
+    assert params["prompt_token_ids"] == [1024, 1024, 1024, 20, 21, 100, 101, 102]
+    audio_grid = params["codes"]["ref"]
+    assert audio_grid.shape == (len(params["prompt_token_ids"]), 16)
+    assert audio_grid[-1, 0].item() == processor.audio_bos_token
+    assert "ids" not in params
+
+
+def test_build_realtime_prompt_streams_text_after_first_twelve_tokens() -> None:
+    params = build_realtime_prompt(
+        _Tokenizer(),
+        _Processor(),
+        " ".join(f"word{i}" for i in range(15)),
+        torch.zeros((2, 16), dtype=torch.int64),
+    )
+
+    assert params["prompt_token_ids"][-12:] == list(range(100, 112))
+    assert params["ids"] == {"all": [112, 113, 114]}
+
+
+def test_build_realtime_prompt_rejects_wrong_processor_layout(monkeypatch: pytest.MonkeyPatch) -> None:
+    processor = _Processor()
+    monkeypatch.setattr(
+        processor,
+        "make_ensemble",
+        lambda prompt_audio_tokens: np.zeros((3, 16), dtype=np.int64),
+    )
+
+    with pytest.raises(ValueError, match=r"expected \(sequence_length, 17\)"):
+        build_realtime_prompt(
+            _Tokenizer(),
+            processor,
+            "one",
+            torch.zeros((2, 16), dtype=torch.int64),
+        )
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py b/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
index bed20efc225..555fec42d56 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
@@ -6,8 +6,12 @@
 handles each); they are registered under distinct model-type names.
 """
 
+import asyncio
+import threading
 from typing import TYPE_CHECKING, Any, cast
 
+from transformers import AutoModel, AutoTokenizer
+from transformers.dynamic_module_utils import get_class_from_dynamic_module
 from vllm.inputs import tokens_input
 
 from vllm_omni.entrypoints.openai.tts_adapters import register_tts_adapter
@@ -18,6 +22,7 @@
     apply_max_new_tokens,
     conditioning_cache_salt,
 )
+from vllm_omni.model_executor.models.moss_tts.realtime_prompt import build_realtime_prompt
 
 if TYPE_CHECKING:
     from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
@@ -30,6 +35,7 @@ def __init__(self, ctx) -> None:
         super().__init__(ctx)
         self._moss_variant = None if self.name == "moss_tts_nano" else self._detect_moss_variant()
         self._moss_processor_cache = None
+        self._moss_realtime_components_lock = threading.Lock()
 
     @property
     def engine_client(self):
@@ -63,7 +69,7 @@ def _get_moss_ref_encoder(self):
         # inside the model package; this layer only supplies the processor and
         # the process-wide speaker cache.
         encoder = build_reference_encoder(
-            self._get_moss_processor(),
+            self._get_moss_realtime_components()[2] if self._moss_variant == "realtime" else self._get_moss_processor(),
             variant=cast(str, self._moss_variant),
             speaker_cache=self._speaker_cache,
         )
@@ -157,6 +163,45 @@ def _get_moss_processor(self):
         self._moss_processor_cache = proc
         return proc
 
+    def _get_moss_realtime_components(self):
+        with self._moss_realtime_components_lock:
+            cached = getattr(self, "_moss_realtime_components", None)
+            if cached is not None:
+                return cached
+
+            model_id = self.engine_client.model_config.model
+            processor_cls = get_class_from_dynamic_module(
+                "processing_mossttsrealtime.MossTTSRealtimeProcessor",
+                model_id,
+            )
+            tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
+            processor = processor_cls(tokenizer=tokenizer)
+            hf_config = self.engine_client.model_config.hf_config
+            codec_path = str(
+                getattr(
+                    hf_config,
+                    "codec_model_name_or_path",
+                    getattr(
+                        hf_config,
+                        "audio_tokenizer_name_or_path",
+                        "OpenMOSS-Team/MOSS-Audio-Tokenizer",
+                    ),
+                )
+            )
+            codec = (
+                AutoModel.from_pretrained(
+                    codec_path,
+                    trust_remote_code=True,
+                )
+                # Reference encoding runs in the API process. Keep the codec on CPU
+                # so it does not reserve accelerator memory outside the model workers.
+                .to("cpu")
+                .eval()
+            )
+            cached = (tokenizer, processor, codec)
+            self._moss_realtime_components = cached
+            return cached
+
     async def _build_moss_tts_params(
         self,
         request: "OpenAICreateSpeechRequest",
@@ -196,24 +241,18 @@ async def _build_moss_tts_params(
             params["ref_audio_cache_key"] = cache_key
             return params
 
-        # ---- MOSS-TTS-Realtime: keep the old prompt_audio_array path ----
-        # ``AutoProcessor.from_pretrained`` doesn't auto-discover
-        # ``MossTTSRealtimeProcessor`` (no ``processor_config.json`` in the
-        # snapshot), and Realtime's prompt format diverges from MossTTSDelay
-        # (16-channel grid, separate per-step text feed). The
-        # ``prompt_audio_array`` shape lines up well enough with what the
-        # talker reads for short prompts; full Realtime support needs a
-        # separate processor.from_module path which we don't wire here.
         if v == "realtime":
-            params = {
-                "text": [request.input or ""],
-                "mode": ["voice_clone"],
-            }
+            tokenizer, processor, _ = await asyncio.to_thread(self._get_moss_realtime_components)
+            references, realtime_resolve_keys = await self._encode_moss_references(
+                request,
+                has_inline_ref_audio=has_inline_ref_audio,
+                two_speaker=False,
+            )
+            params = build_realtime_prompt(tokenizer, processor, request.input or "", references[0])
             if request.max_new_tokens is not None:
                 params["max_new_frames"] = [request.max_new_tokens]
-            wav_list, sr, cache_key = await self._resolve_ref_audio(cast(str, request.ref_audio))
-            params["prompt_audio_array"] = [[wav_list, sr]]
-            params["ref_audio_cache_key"] = cache_key
+            if 0 in realtime_resolve_keys:
+                params["ref_audio_cache_key"] = realtime_resolve_keys[0]
             return params
 
         # ---- MossTTSDelay family (tts/ttsd/sound_effect/voice_generator)
diff --git a/vllm_omni/model_executor/models/moss_tts/modeling_moss_tts_talker.py b/vllm_omni/model_executor/models/moss_tts/modeling_moss_tts_talker.py
index 9d2d2d17139..8d36086ef47 100644
--- a/vllm_omni/model_executor/models/moss_tts/modeling_moss_tts_talker.py
+++ b/vllm_omni/model_executor/models/moss_tts/modeling_moss_tts_talker.py
@@ -44,10 +44,10 @@ def _maybe_prefix(prefix: str, name: str) -> str:
 
 
 def _iter_state_row_spans(
-    states: Sequence[dict[str, Any]],
+    states: Sequence[dict[str, Any] | None],
     spans: Sequence[tuple[int, int]] | None,
     num_rows: int,
-) -> Iterable[tuple[dict[str, Any], int, int]]:
+) -> Iterable[tuple[dict[str, Any] | None, int, int]]:
     """Yield state/logit-row ranges without assuming equal request row counts."""
     if num_rows <= 0 or not states:
         return
@@ -798,6 +798,9 @@ class MossTTSRealtimeTalkerForGeneration(nn.Module):
     have_multimodal_outputs: bool = True
     has_preprocess: bool = True
     has_postprocess: bool = True
+    # Intermediate prefill chunks reach make_omni_output but must not produce
+    # audio until the scheduler has completed the prompt.
+    requires_request_sample_eligibility: bool = True
 
     AUDIO_BOS = 1025
     AUDIO_EOS = 1026
@@ -858,7 +861,7 @@ def __init__(self, *, vllm_config: VllmConfig, prefix: str = "") -> None:
         # We still need a logits_processor so vLLM downstream stays happy with
         # something callable; a minimal pass-through suffices.
         self.logits_processor = LogitsProcessor(self.text_vocab_size)
-        self._batch_state: list[dict[str, Any]] | None = None
+        self._batch_state: list[dict[str, Any] | None] | None = None
 
         # Stacked weight cache built after load_weights().
         # shape: (n_vq, audio_vocab_size, hidden_size)
@@ -972,13 +975,14 @@ def preprocess(
         span_len = int(input_ids.shape[0])
         audio_state = info_dict.get("audio_state")
         is_first_call = not isinstance(audio_state, dict)
+        is_prefill = bool(info_dict.get("_omni_is_prefill", span_len > 1))
 
-        if span_len > 1 or is_first_call:
+        if is_prefill or is_first_call:
             # Prefill: read the full reference-audio code grid (channels x T)
             # from ``info_dict["codes"]["ref"]``; slice the chunk that aligns
             # with this prefill window.
             ref_codes = (info_dict.get("codes", {}) or {}).get("ref")
-            ref_offset = int(info_dict.get("ref_offset", 0))
+            ref_offset = int(info_dict.get("_omni_num_computed_tokens", info_dict.get("ref_offset", 0)))
             chunk_audio = None
             if isinstance(ref_codes, torch.Tensor) and ref_codes.numel() > 0:
                 if ref_codes.dim() == 1 and ref_codes.numel() % self.n_vq == 0:
@@ -994,22 +998,24 @@ def preprocess(
                 if chunk_audio is not None
                 else torch.full((self.n_vq,), self.audio_pad_token, dtype=torch.long, device=device)
             )
-            # Capture the streaming-text list from the request (set by the
-            # realtime end2end builder; empty for the delay variants which
-            # don't take this code path anyway).
-            remaining = (info_dict.get("ids", {}) or {}).get("all")
-            if not isinstance(remaining, list):
-                remaining = []
             info_update: dict[str, Any] = {
-                "audio_state": {
+                "audio_codes": {"current": current_codes},
+                "ref_offset": ref_offset + span_len,
+            }
+            if is_first_call:
+                remaining = (info_dict.get("ids", {}) or {}).get("all")
+                if not isinstance(remaining, list):
+                    remaining = []
+                max_new_frames = info_dict.get("max_new_frames")
+                if isinstance(max_new_frames, (list, tuple)):
+                    max_new_frames = max_new_frames[0] if max_new_frames else None
+                info_update["audio_state"] = {
                     "is_stopping": False,
                     "step": 0,
                     "text_cursor": 0,
                     "remaining_text": list(remaining),
-                },
-                "audio_codes": {"current": current_codes},
-                "ref_offset": ref_offset + span_len,
-            }
+                    "max_new_frames": int(max_new_frames) if max_new_frames is not None else -1,
+                }
             return input_ids, embeds, info_update
 
         # Decode step: text_token from the just-sampled vLLM logit, plus the
@@ -1046,13 +1052,21 @@ def make_omni_output(
         info_dicts: list[dict[str, Any]] = (
             kwargs.get("model_intermediate_buffer") or kwargs.get("runtime_additional_information") or []
         )
+        sample_eligible = kwargs.get("request_sample_eligible")
+        eligible = [
+            sample_eligible is None or i >= len(sample_eligible) or bool(sample_eligible[i])
+            for i in range(len(info_dicts))
+        ]
 
         # Defensive state init.
         for info in info_dicts:
             if isinstance(info, dict) and not isinstance(info.get("audio_state"), dict):
                 info["audio_state"] = {"is_stopping": False, "step": 0}
 
-        self._batch_state = [(info["audio_state"] if isinstance(info, dict) else {}) for info in info_dicts]
+        self._batch_state = [
+            (info["audio_state"] if isinstance(info, dict) and eligible[i] else None)
+            for i, info in enumerate(info_dicts)
+        ]
         self._batch_state_spans = kwargs.get("request_token_spans")
 
         # See delay talker: real per-request row spans from the runner are
@@ -1074,6 +1088,8 @@ def make_omni_output(
             for i, info in enumerate(info_dicts):
                 if not isinstance(info, dict):
                     continue
+                if not eligible[i]:
+                    continue
                 row_start, row_end = spans[i]
                 row_end = min(int(row_end), num_rows)
                 if row_start >= row_end:
@@ -1115,10 +1131,13 @@ def make_omni_output(
                     )
 
                 ch0 = int(new_codes[0].item())
+                state["step"] = int(state.get("step", 0)) + 1
+                max_new_frames = int(state.get("max_new_frames", -1))
+                if max_new_frames > 0 and state["step"] >= max_new_frames:
+                    state["is_stopping"] = True
                 # Stop condition mirrors upstream: codebook 0 == eos_audio_id.
                 if ch0 == self.AUDIO_EOS:
                     state["is_stopping"] = True
-                    state["step"] = int(state.get("step", 0)) + 1
                     info["audio_codes"] = {
                         "current": new_codes,
                         "accumulated": (info.get("audio_codes", {}) or {}).get("accumulated"),
@@ -1127,7 +1146,6 @@ def make_omni_output(
 
                 if ch0 in (self.AUDIO_BOS, self.audio_pad_token):
                     # Skip the bos / pad frames — they don't decode to real audio.
-                    state["step"] = int(state.get("step", 0)) + 1
                     info["audio_codes"] = {
                         "current": new_codes,
                         "accumulated": (info.get("audio_codes", {}) or {}).get("accumulated"),
@@ -1141,7 +1159,6 @@ def make_omni_output(
                     updated_acc = new_codes.unsqueeze(0)
 
                 info["audio_codes"] = {"current": new_codes, "accumulated": updated_acc}
-                state["step"] = int(state.get("step", 0)) + 1
                 per_req_codes[i] = new_codes.unsqueeze(0)
                 have_codes = True
 
diff --git a/vllm_omni/model_executor/models/moss_tts/realtime_prompt.py b/vllm_omni/model_executor/models/moss_tts/realtime_prompt.py
new file mode 100644
index 00000000000..985f76205bc
--- /dev/null
+++ b/vllm_omni/model_executor/models/moss_tts/realtime_prompt.py
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Prompt construction for MOSS-TTS-Realtime."""
+
+from typing import Any
+
+import numpy as np
+import torch
+
+REALTIME_AUDIO_CHANNELS = 16
+REALTIME_PREFILL_TEXT_TOKENS = 12
+
+
+def build_realtime_prompt(
+    tokenizer: Any,
+    processor: Any,
+    text: str,
+    reference_codes: torch.Tensor,
+) -> dict[str, Any]:
+    """Build the mixed text/audio prompt consumed by the Realtime talker."""
+    audio_tokens = reference_codes.detach().cpu().numpy()
+    system_grid = np.asarray(processor.make_ensemble(prompt_audio_tokens=audio_tokens), dtype=np.int64)
+    expected_width = REALTIME_AUDIO_CHANNELS + 1
+    if system_grid.ndim != 2 or system_grid.shape[1] != expected_width:
+        raise ValueError(
+            f"MOSS-TTS-Realtime processor returned shape {system_grid.shape}; "
+            f"expected (sequence_length, {expected_width})"
+        )
+
+    assistant_ids = tokenizer.encode("<|im_start|>assistant\n", add_special_tokens=False)
+    assistant_grid = np.full(
+        (len(assistant_ids), expected_width),
+        processor.audio_channel_pad,
+        dtype=np.int64,
+    )
+    assistant_grid[:, 0] = assistant_ids
+
+    text_ids = tokenizer.encode(text, add_special_tokens=False)
+    if not text_ids:
+        raise ValueError("MOSS-TTS-Realtime input is empty after tokenization")
+
+    prefill_len = min(len(text_ids), REALTIME_PREFILL_TEXT_TOKENS)
+    text_grid = np.full(
+        (prefill_len, expected_width),
+        processor.audio_channel_pad,
+        dtype=np.int64,
+    )
+    text_grid[:, 0] = text_ids[:prefill_len]
+    text_grid[-1, 1] = processor.audio_bos_token
+
+    prompt_grid = np.concatenate((system_grid, assistant_grid, text_grid), axis=0)
+    params: dict[str, Any] = {
+        "prompt_token_ids": prompt_grid[:, 0].tolist(),
+        "codes": {"ref": torch.from_numpy(prompt_grid[:, 1:].copy())},
+    }
+    remaining_text_ids = text_ids[prefill_len:]
+    if remaining_text_ids:
+        params["ids"] = {"all": remaining_text_ids}
+    return params
diff --git a/vllm_omni/model_executor/models/moss_tts/reference_encoder.py b/vllm_omni/model_executor/models/moss_tts/reference_encoder.py
index 36b2616e72f..a828d59e029 100644
--- a/vllm_omni/model_executor/models/moss_tts/reference_encoder.py
+++ b/vllm_omni/model_executor/models/moss_tts/reference_encoder.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 """Reference-audio encoding + speaker cache for the MOSS-TTS-family talker.
 
 This lives in the model package (not the shared serving layer) so all
@@ -360,6 +363,18 @@ async def aclose(self) -> None:
         await self._batcher.aclose()
 
 
+class MossRealtimeReferenceEncoder(MossReferenceEncoder):
+    """Use the realtime codec with the shared reference cache and batcher."""
+
+    def _encode_prepared(self, prepared: list[torch.Tensor]) -> list[torch.Tensor]:
+        with torch.no_grad():
+            encoded = self._processor.batch_encode([wav.squeeze(0) for wav in prepared], num_quantizers=self._n_vq)
+        return [
+            encoded.audio_codes[:, i, : int(length.item())].transpose(0, 1).contiguous()
+            for i, length in enumerate(encoded.audio_codes_lengths)
+        ]
+
+
 def build_reference_encoder(
     processor: Any,
     *,
@@ -369,9 +384,17 @@ def build_reference_encoder(
     """Build the per-server encoder for a MOSS-TTS ``variant``.
 
     Derives the encode geometry (``n_vq`` and the working sample rate) from the
-    upstream processor's ``model_config`` so the variant knowledge stays in the
-    model package rather than in ``serving_speech.py``.
+    upstream processor's ``model_config``; Realtime takes its codec directly
+    and uses 16 codebooks at 24 kHz. Variant knowledge stays in the model package.
     """
+    if variant == "realtime":
+        return MossRealtimeReferenceEncoder(
+            processor,
+            variant=variant,
+            n_vq=16,
+            sr_target=24000,
+            speaker_cache=speaker_cache,
+        )
     n_vq = int(getattr(processor.model_config, "n_vq", 32))
     # Local-v1.5 encodes reference audio at a fixed 24 kHz working rate
     # regardless of its 48 kHz stereo *output* codec -- mirrors the offline

From 5aadcbb0abae2e7065966483fcb90ac5ebcbd701 Mon Sep 17 00:00:00 2001
From: Yueqian Lin <70319226+linyueqian@users.noreply.github.com>
Date: Wed, 16 Sep 2026 11:40:12 -0700
Subject: [PATCH 047/105] [Bugfix] Fix Breeze-TTS-2 repeated silence and audio
 EOS handling

---
 recipes/BreezeBlue/Breeze-TTS-2.md            |  33 +++--
 .../models/breeze_tts_2/test_instruction.py   |  22 ++++
 .../breeze_tts_2/test_repetition_penalty.py   | 122 ++++++++++++++++++
 .../models/breeze_tts_2/test_sampling_eos.py  |  77 +++++++++++
 .../models/breeze_tts_2/test_streaming.py     | 120 +++++++++++++++--
 vllm_omni/deploy/breeze_tts_2.yaml            |   6 +-
 .../openai/tts_adapters/breeze_tts_2.py       |  22 +++-
 .../modeling_breeze_tts_2_codec.py            |  25 +++-
 .../modeling_breeze_tts_2_talker.py           |  37 +++++-
 .../models/breeze_tts_2/pipeline.py           |   6 +
 10 files changed, 437 insertions(+), 33 deletions(-)
 create mode 100644 tests/model_executor/models/breeze_tts_2/test_repetition_penalty.py
 create mode 100644 tests/model_executor/models/breeze_tts_2/test_sampling_eos.py

diff --git a/recipes/BreezeBlue/Breeze-TTS-2.md b/recipes/BreezeBlue/Breeze-TTS-2.md
index 50e8858afcb..fb26ce91cca 100644
--- a/recipes/BreezeBlue/Breeze-TTS-2.md
+++ b/recipes/BreezeBlue/Breeze-TTS-2.md
@@ -30,10 +30,20 @@ Four prompt modes are selected automatically from the request fields:
 | `ref_clone_tata` (clone) | `ref_audio` + `ref_text` + `input` | reference clip and its exact transcript |
 | `ref_edit_tata` (voice direction) | reference trio + `instructions` | keep the reference timbre, direct the delivery |
 
-Current scope: greedy sampling with `cfg_scale=1.0`; CFG ≠ 1.0 and
+Current scope: greedy sampling with `cfg_scale=1.0` and a default
+`repetition_penalty=1.1` on generated codebook-0 tokens; CFG ≠ 1.0 and
 `negative_prompt` are rejected with explicit client errors until companion
 request support lands.
 
+The [official inference example](https://github.com/breezeblue-ai/breeze-tts/blob/main/infer.py)
+also uses repetition penalty `1.1`, but its
+[runtime defaults](https://github.com/breezeblue-ai/breeze-tts/blob/main/breeze_infer/runtime.py)
+sample both the backbone and depth decoder with temperature `0.9` and top-k
+`50`. The [official voice-design examples](https://huggingface.co/BreezeBlue/Breeze-TTS-2#-voice-design)
+use CFG `4`. Those sampling and guidance settings are outside the current
+port's scope, so the examples below do not establish parity with the official
+voice-design outputs.
+
 ## Supported model contract
 
 | Item | Value |
@@ -42,9 +52,9 @@ request support lands.
 | Modes | plain, voice design (`instructions`), voice clone (`ref_audio` + `ref_text`), voice direction (reference + `instructions`) |
 | Languages | English and Chinese (model card) |
 | Reference audio | exactly one clip per request with its exact transcript; encoded by the bundled Qwen3-TTS tokenizer to 16 codebooks at 12.5 Hz |
-| Output | 24 kHz mono; `wav` or `pcm`; streaming SSE `speech.audio.delta` |
+| Output | 24 kHz mono; `wav` or `pcm`; raw audio streaming (`stream_format="audio"`) or SSE `speech.audio.delta` (`stream_format="sse"`) |
 | Length | prompt bounded by stage-0 `max_model_len=4096`; synthesis bounded by `max_new_tokens` codec frames (default 2048, about 164 s) |
-| Sampling | greedy (`temperature=0`) with `cfg_scale=1.0`; other guidance values and `negative_prompt` are rejected |
+| Sampling | greedy (`temperature=0`) with `cfg_scale=1.0` and `repetition_penalty=1.1`; other guidance values and `negative_prompt` are rejected |
 | Deployment profile | `vllm_omni/deploy/breeze_tts_2.yaml`: two stages on one GPU, async-chunk streaming with 8-frame codec chunks, stage 0 `gpu_memory_utilization=0.80`, stage 1 `0.15` |
 
 ## References
@@ -106,7 +116,7 @@ Voice design (instruction only, no reference audio):
 curl -X POST http://localhost:8091/v1/audio/speech \
     -H "Content-Type: application/json" \
     -d '{
-        "input": "[laughs] Welcome to tonight's story time.",
+        "input": "(laugh) Welcome to our story time.",
         "instructions": "A warm young woman, clear voice, lively delivery.",
         "response_format": "wav"
     }' --output breeze_design.wav
@@ -139,7 +149,7 @@ curl -X POST http://localhost:8091/v1/audio/speech \
     }' --output breeze_direction.wav
 ```
 
-Streaming PCM (SSE `speech.audio.delta` events):
+Streaming raw PCM (`stream_format="audio"`):
 
 ```bash
 curl -N -X POST http://localhost:8091/v1/audio/speech \
@@ -153,8 +163,9 @@ curl -N -X POST http://localhost:8091/v1/audio/speech \
     }' --output breeze_stream.pcm
 ```
 
-Expected results: finite, non-silent 24 kHz mono WAV files; streaming requests
-return incremental PCM deltas. On 1x L20 (greedy, single request after
+Expected results: finite, non-silent 24 kHz mono WAV files; the streaming example
+returns raw PCM bytes. Use `stream_format="sse"` for `speech.audio.delta`
+events containing base64-encoded audio. On 1x L20 (greedy, single request after
 warm-up) a few seconds of speech completes in roughly 3.4–3.8 s wall time.
 
 ## Notes
@@ -166,6 +177,12 @@ warm-up) a few seconds of speech completes in roughly 3.4–3.8 s wall time.
   supported yet.
 - **CFG**: `guidance_scale`/`cfg_scale` must be `1.0`. Non-1.0 values and
   `negative_prompt` return a client error.
+- **Repetition penalty**: the default `1.1` matches upstream's penalty on
+  generated codebook-0 tokens and discourages repeated silence. Override it
+  with `extra_params: {"repetition_penalty": 1.0}` to disable it, or another
+  finite positive value. Text and reference audio are excluded from its history.
+  The legacy `tools/breeze_tts_2_upstream_golden.py` uses penalty `1.0`; set
+  the same serving override when comparing against those golden frames.
 - **Length budget**: prompt length is bounded by stage 0 `max_model_len=4096`;
   synthesis length by `max_new_tokens` (default 2048 frames ≈ 164 s at the
   12.5 Hz codec frame rate) — set `max_new_tokens` for shorter caps.
@@ -181,7 +198,7 @@ warm-up) a few seconds of speech completes in roughly 3.4–3.8 s wall time.
 
 | Feature | Status | Notes |
 | ------- | ------ | ----- |
-| Streaming output | ✓ | `async_chunk: true`, 8-frame inter-stage chunks, SSE `speech.audio.delta` PCM |
+| Streaming output | ✓ | `async_chunk: true`, 8-frame inter-stage chunks; raw audio or SSE `speech.audio.delta` |
 | Voice cloning | ✓ | one reference clip plus transcript per request |
 | Voice design / voice direction | ✓ | `instructions` field, with or without a reference |
 | Classifier-free guidance | ✗ | `cfg_scale` must be `1.0`; `negative_prompt` rejected (follow-up) |
diff --git a/tests/model_executor/models/breeze_tts_2/test_instruction.py b/tests/model_executor/models/breeze_tts_2/test_instruction.py
index 3817ccb3096..c7f2fef6630 100644
--- a/tests/model_executor/models/breeze_tts_2/test_instruction.py
+++ b/tests/model_executor/models/breeze_tts_2/test_instruction.py
@@ -4,6 +4,7 @@
 from types import SimpleNamespace
 
 import pytest
+from vllm import SamplingParams
 
 from vllm_omni.entrypoints.openai.tts_adapters.breeze_tts_2 import BreezeTTS2Adapter
 from vllm_omni.model_executor.models.breeze_tts_2.prompt_builder import (
@@ -133,3 +134,24 @@ def test_non_greedy_sampling_overrides_are_rejected():
     assert "greedy" in adapter.validate(_request({"top_p": 0.9}))
     assert "greedy" in adapter.validate(_request({"top_k": 50}))
     assert "temperature must be a number" in adapter.validate(_request({"temperature": "warm"}))
+
+
+@pytest.mark.parametrize("value", [0, -1, float("nan"), float("inf"), "invalid"])
+def test_invalid_repetition_penalties_are_rejected(value):
+    assert "repetition_penalty" in _adapter().validate(_request({"repetition_penalty": value}))
+
+
+@pytest.mark.parametrize("value", [0.9, 1.0, 1.1, "1.2"])
+@pytest.mark.parametrize("max_new_tokens", [None, 32])
+def test_repetition_penalty_override_reaches_standard_sampling_metadata(value, max_new_tokens):
+    adapter = _adapter()
+    request = _request({"repetition_penalty": value}, max_new_tokens=max_new_tokens)
+    original = [SamplingParams(max_tokens=128, repetition_penalty=1.1)]
+
+    assert adapter.validate(request) is None
+    updated = adapter.apply_sampling_overrides(original, request)
+
+    assert updated[0].repetition_penalty == float(value)
+    assert updated[0].max_tokens == (128 if max_new_tokens is None else max_new_tokens)
+    assert original[0].repetition_penalty == 1.1
+    assert original[0].max_tokens == 128
diff --git a/tests/model_executor/models/breeze_tts_2/test_repetition_penalty.py b/tests/model_executor/models/breeze_tts_2/test_repetition_penalty.py
new file mode 100644
index 00000000000..0edaabc6f3f
--- /dev/null
+++ b/tests/model_executor/models/breeze_tts_2/test_repetition_penalty.py
@@ -0,0 +1,122 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from typing import Any
+
+import pytest
+import torch
+from vllm.v1.sample.logits_processor import LogitsProcessors
+from vllm.v1.sample.metadata import SamplingMetadata
+
+from tests.model_executor.models.breeze_tts_2.test_talker_state_machine import _depth_codes, _talker
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def _model(first_score=11.0, second_score=10.5):
+    model = _talker()
+    model._async_chunk = True
+    logits = torch.full((1, 9), -100.0)
+    logits[0, 2:4] = torch.tensor([first_score, second_score])
+    model._main_head_logits = lambda hidden: logits.expand(hidden.shape[0], -1).clone()
+    model._generate_depth_codes = lambda hidden, code0: _depth_codes(model, hidden, code0)
+    return model
+
+
+def _step(model, infos, penalties, *, no_penalties=False):
+    return model.make_omni_output(
+        torch.zeros(len(infos), 16),
+        model_intermediate_buffer=infos,
+        request_token_spans=[(i, i + 1) for i in range(len(infos))],
+        sampling_metadata=SamplingMetadata(
+            temperature=None,
+            all_greedy=True,
+            all_random=False,
+            top_p=None,
+            top_k=None,
+            generators={},
+            max_num_logprobs=None,
+            no_penalties=no_penalties,
+            frequency_penalties=torch.zeros(len(infos)),
+            presence_penalties=torch.zeros(len(infos)),
+            repetition_penalties=torch.tensor(penalties),
+            # Text/reference conditioning must never be counted as generated
+            # codec history, even if the scheduler ids overlap the codec ids.
+            prompt_token_ids=torch.tensor([[2, 2]] * len(infos)),
+            output_token_ids=[list(info.get("breeze_generated_code0_ids", [])) for info in infos],
+            allowed_token_ids_mask=None,
+            bad_words_token_ids={},
+            logitsprocs=LogitsProcessors(),
+        ),
+    )
+
+
+@pytest.mark.parametrize("scores", [(11.0, 10.5), (-1.0, -1.05)])
+def test_penalty_applies_once_per_generated_token_and_respects_logit_sign(scores):
+    model = _model(*scores)
+    info = {"prompt_ids": torch.tensor([2]), "input_values": torch.tensor([[2, 3, 4, 5]])}
+    chosen = []
+
+    for _ in range(4):
+        output = _step(model, [info], [1.1])
+        chosen.append(output.multimodal_outputs["codes"]["audio"][0][0, 0].item())
+
+    assert chosen == [2, 3, 2, 2]
+
+
+def test_request_history_and_penalty_are_independent():
+    model = _model()
+    first: dict[str, Any] = {}
+    second: dict[str, Any] = {}
+    _step(model, [first], [1.1])
+    output = _step(model, [first, second], [1.1, 1.1])
+    assert [codes[0, 0].item() for codes in output.multimodal_outputs["codes"]["audio"]] == [3, 2]
+
+    # Reverse the batch order; a request's history follows its state, while
+    # each penalty follows the current sampling-metadata row.
+    output = _step(model, [second, first], [1.1, 1.0])
+    assert [codes[0, 0].item() for codes in output.multimodal_outputs["codes"]["audio"]] == [3, 2]
+
+
+def test_disabled_penalties_do_not_read_uninitialized_sampling_buffer():
+    model = _model()
+    info: dict[str, Any] = {}
+    for _ in range(2):
+        output = _step(model, [info], [float("nan")], no_penalties=True)
+        assert output.multimodal_outputs["codes"]["audio"][0][0, 0].item() == 2
+
+
+def test_scheduler_logits_preserve_selected_frame_under_further_sampling_transforms():
+    model = _model()
+    info: dict[str, Any] = {}
+    _step(model, [info], [1.1])
+    output = _step(model, [info], [1.1])
+    selected = output.multimodal_outputs["codes"]["audio"][0][0, 0].item()
+    logits = model.compute_logits(torch.zeros(1, 16))
+
+    assert selected == 3
+    assert logits.argmax(dim=-1).item() == selected
+    assert torch.isfinite(logits).sum().item() == 1
+    assert logits[0, selected].item() == 0.0
+    # The scheduler may apply repetition again and rescale temperature. A
+    # finite zero for the selected token preserves a valid point mass.
+    for temperature in (0.1, 0.9, 2.0):
+        probabilities = torch.softmax(logits / 1.1 / temperature, dim=-1)
+        assert torch.isfinite(probabilities).all()
+        assert probabilities[0, selected].item() == 1.0
+
+
+def test_repetition_penalty_can_select_eos_without_emitting_a_frame():
+    model = _model()
+    info: dict[str, Any] = {}
+    _step(model, [info], [1.1])
+    logits = torch.full((1, 9), -100.0)
+    logits[0, 2] = 11.0
+    logits[0, 8] = 10.5
+    model._main_head_logits = lambda hidden: logits.expand(hidden.shape[0], -1).clone()
+
+    output = _step(model, [info], [1.1])
+
+    assert output.multimodal_outputs["codes"]["audio"][0].numel() == 0
+    assert info["breeze_generated_frames"] == 1
+    assert model.compute_logits(torch.zeros(1, 16)).argmax(dim=-1).item() == 8
diff --git a/tests/model_executor/models/breeze_tts_2/test_sampling_eos.py b/tests/model_executor/models/breeze_tts_2/test_sampling_eos.py
new file mode 100644
index 00000000000..8cd389d1792
--- /dev/null
+++ b/tests/model_executor/models/breeze_tts_2/test_sampling_eos.py
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from pathlib import Path
+
+import pytest
+import torch
+import yaml
+from vllm import SamplingParams
+from vllm.v1.core.sched.utils import check_stop
+from vllm.v1.request import Request, RequestStatus
+from vllm.v1.sample.logits_processor import BatchUpdate, MinTokensLogitsProcessor
+
+from vllm_omni.config.stage_config import merge_sampling_constraints
+from vllm_omni.model_executor.models.breeze_tts_2.pipeline import BREEZE_TTS_2_PIPELINE
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+@pytest.fixture
+def talker_sampling_params():
+    deploy_path = Path(__file__).parents[4] / "vllm_omni" / "deploy" / "breeze_tts_2.yaml"
+    deploy = yaml.safe_load(deploy_path.read_text(encoding="utf-8"))
+    params = SamplingParams(
+        **merge_sampling_constraints(
+            deploy["stages"][0]["default_sampling_params"],
+            BREEZE_TTS_2_PIPELINE.stages[0].sampling_constraints,
+        )
+    )
+    # Mirror the input processor: Breeze's text tokenizer uses EOS 1,
+    # which is also an ordinary token in the generated codec vocabulary.
+    params.update_from_generation_config({"eos_token_id": [1]}, eos_token_id=1)
+    return params
+
+
+@pytest.mark.parametrize("codec_token, should_stop", [(0, False), (1, False), (2047, False), (2051, True)])
+def test_scheduler_stops_only_on_codec_eos(talker_sampling_params, codec_token, should_stop):
+    request = Request(
+        request_id="breeze-eos-test",
+        prompt_token_ids=[7, 8, 9],
+        sampling_params=talker_sampling_params,
+        pooling_params=None,
+    )
+    request.append_output_token_ids([42, codec_token])
+    request.status = RequestStatus.RUNNING
+
+    assert check_stop(request, max_model_len=4096) is should_stop
+    if should_stop:
+        assert request.status == RequestStatus.FINISHED_STOPPED
+        assert request.stop_reason == 2051
+    else:
+        assert request.status == RequestStatus.RUNNING
+
+
+@pytest.mark.parametrize("codec_token", [1, 2051])
+def test_first_step_keeps_codec_token_and_eos_logits(talker_sampling_params, codec_token, monkeypatch):
+    # vLLM's tensor helper uses a global flag rather than is_pin_memory,
+    # and pinned allocations require a CUDA device even for this CPU test.
+    monkeypatch.setattr("vllm.utils.torch_utils.PIN_MEMORY", False)
+    # ignore_eos still leaves text EOS in all_stop_token_ids. Exercise the
+    # actual processor so the first codec frame and immediate EOS stay valid.
+    processor = MinTokensLogitsProcessor(None, device=torch.device("cpu"), is_pin_memory=False)
+    processor.update_state(
+        BatchUpdate(batch_size=1, removed=[], added=[(0, talker_sampling_params, None, [])], moved=[])
+    )
+    logits = torch.full((1, 2052), -float("inf"))
+    logits[0, codec_token] = 0.0
+
+    processed = processor.apply(logits.clone())
+
+    assert torch.equal(processed, logits)
+    assert processed.argmax(dim=-1).item() == codec_token
+
+
+def test_pipeline_disallows_minimum_tokens_that_mask_selected_codec_ids():
+    params = merge_sampling_constraints({"min_tokens": 10}, BREEZE_TTS_2_PIPELINE.stages[0].sampling_constraints)
+    assert params["min_tokens"] == 0
diff --git a/tests/model_executor/models/breeze_tts_2/test_streaming.py b/tests/model_executor/models/breeze_tts_2/test_streaming.py
index 045444ec3ef..a630b90bc23 100644
--- a/tests/model_executor/models/breeze_tts_2/test_streaming.py
+++ b/tests/model_executor/models/breeze_tts_2/test_streaming.py
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
+import copy
 from collections import defaultdict
 from types import SimpleNamespace
 
@@ -20,7 +21,7 @@
 class _TransferManager:
     def __init__(self, chunk_frames: int = 4):
         self.connector = SimpleNamespace(config={"breeze_codec_chunk_frames": chunk_frames})
-        self.code_prompt_token_ids = defaultdict(list)
+        self.code_prompt_token_ids: defaultdict[str, list[torch.Tensor]] = defaultdict(list)
 
 
 class _Request:
@@ -120,7 +121,8 @@ def test_stateful_codec_rejects_partial_frame_chunk():
     assert decoder.calls == []
 
 
-def test_stateful_codec_terminal_marker_pops_state_without_decoding():
+@pytest.mark.parametrize("token_counts", [(4, 0), (0, 4), (0, 4, 0, 8, 0)])
+def test_stateful_codec_terminal_marker_pops_state_without_decoding(token_counts):
     decoder = _Decoder()
     codec = object.__new__(BreezeTTS2MimiCodec)
     codec._async_chunk = True
@@ -128,24 +130,114 @@ def test_stateful_codec_terminal_marker_pops_state_without_decoding():
     codec._codebook_size = 8
     codec._sample_rate = 24_000
     codec._audio_tokenizer = SimpleNamespace(model=SimpleNamespace(decoder=decoder))
-    codec._decoder_state_cache = {"scheduler-live": {}, "scheduler-done": {}}
+    request_ids = [f"scheduler-{index}" for index in range(len(token_counts))]
+    codec._decoder_state_cache = {request_id: {} for request_id in request_ids}
 
     output = codec.forward(
-        torch.tensor([0, 1, 2, 3], dtype=torch.long),
+        torch.arange(sum(token_counts), dtype=torch.long) % codec._codebook_size,
         runtime_additional_information=[
             # Plain ``finished`` covers the fallback for direct in-process
             # callers that do not go through the connector receiver.
-            {"meta": {"request_id": "live", "finished": False}},
-            {"meta": {"request_id": "done", "finished": True}},
+            {"meta": {"finished": count == 0}}
+            for count in token_counts
         ],
-        seq_token_counts=[4, 0],
-        request_ids=["scheduler-live", "scheduler-done"],
+        seq_token_counts=token_counts,
+        request_ids=request_ids,
     )
 
-    # The empty terminal marker decodes nothing and releases its state; the
-    # live request still decodes its own chunk.
+    # Empty terminal markers release their state without consuming an output
+    # slot belonging to another request, regardless of their batch position.
     assert len(decoder.calls) == 1
-    assert decoder.calls[0][0][0] == 1
-    assert [item.numel() for item in output.multimodal_outputs["model_outputs"]] == [1920, 0]
-    assert list(codec._decoder_state_cache) == ["scheduler-live"]
-    assert codec._decoder_state_cache["scheduler-live"]["prefix_frames"] == 0
+    assert decoder.calls[0][0][0] == sum(count > 0 for count in token_counts)
+    assert [item.numel() for item in output.multimodal_outputs["model_outputs"]] == [
+        count // codec._num_codebooks * 1920 for count in token_counts
+    ]
+    live_request_ids = [request_id for request_id, count in zip(request_ids, token_counts) if count]
+    assert list(codec._decoder_state_cache) == live_request_ids
+    assert all(codec._decoder_state_cache[request_id]["prefix_frames"] == 0 for request_id in live_request_ids)
+
+
+@pytest.mark.parametrize("configured_chunk_frames", [None, 4])
+def test_stateful_codec_advances_decoder_cache_after_sliding_window(monkeypatch, tmp_path, configured_chunk_frames):
+    from vllm_omni.model_executor.models.qwen3_tts.qwen3_tts_tokenizer import Qwen3TTSTokenizer
+    from vllm_omni.model_executor.models.qwen3_tts.tokenizer_12hz.configuration_qwen3_tts_tokenizer_v2 import (
+        Qwen3TTSTokenizerV2DecoderConfig,
+    )
+    from vllm_omni.model_executor.models.qwen3_tts.tokenizer_12hz.modeling_qwen3_tts_tokenizer_v2 import (
+        Qwen3TTSTokenizerV2Decoder,
+    )
+
+    torch.manual_seed(0)
+    config = Qwen3TTSTokenizerV2DecoderConfig(
+        codebook_size=32,
+        hidden_size=16,
+        latent_dim=16,
+        codebook_dim=16,
+        num_attention_heads=2,
+        num_key_value_heads=2,
+        intermediate_size=32,
+        num_hidden_layers=1,
+        num_quantizers=2,
+        decoder_dim=32,
+        upsample_rates=(2,),
+        upsampling_ratios=(2,),
+        sliding_window=72,
+    )
+    decoder = Qwen3TTSTokenizerV2Decoder(config).eval()
+    # Codebooks initialize to zeros before checkpoint loading; populate them
+    # so different codec IDs produce distinguishable cached frame histories.
+    with torch.no_grad():
+        for name, parameter in decoder.quantizer.named_parameters():
+            if name.endswith("embedding_sum"):
+                parameter.normal_()
+    tokenizer = SimpleNamespace(model=SimpleNamespace(decoder=decoder, get_output_sample_rate=lambda: 24_000))
+    monkeypatch.setattr(Qwen3TTSTokenizer, "from_pretrained", lambda *args, **kwargs: tokenizer)
+    connector_extra = {} if configured_chunk_frames is None else {"breeze_codec_chunk_frames": configured_chunk_frames}
+    chunk_frames = configured_chunk_frames or 8
+    codec = object.__new__(BreezeTTS2MimiCodec)
+    codec.vllm_config = SimpleNamespace(
+        model_config=SimpleNamespace(stage_connector_config={"extra": connector_extra}),
+        device_config=SimpleNamespace(device="cpu"),
+    )
+    codec._tokenizer_path = tmp_path / "audio_tokenizer"
+    codec._audio_tokenizer = None
+    codec._async_chunk = True
+    codec._num_codebooks = config.num_quantizers
+    codec._codebook_size = config.codebook_size
+    codec._decoder_state_cache = {}
+    codec.load_weights(iter(()))
+
+    # At least two chunks after the decoder's rolling window expose a stale
+    # cache even when the first padded chunk still produces plausible audio.
+    total_frames = config.sliding_window + 2 * chunk_frames
+    tail_frames = 3
+    codes = torch.randint(0, config.codebook_size, (1, config.num_quantizers, total_frames + tail_frames))
+    for end in range(chunk_frames, total_frames + 1, chunk_frames):
+        flat = codes[0, :, end - chunk_frames : end].reshape(-1)
+        codec.forward(
+            flat,
+            runtime_additional_information=[{"meta": {"stream_finished": False}}],
+            seq_token_counts=[flat.numel()],
+            request_ids=["scheduler-live"],
+        )
+        state = codec._decoder_state_cache["scheduler-live"]
+        assert state["suffix_frames"] == min(end - chunk_frames, config.sliding_window) + chunk_frames
+        with torch.inference_mode():
+            expected_quantized = decoder.quantizer.decode(codes[..., max(0, end - config.sliding_window) : end])
+        torch.testing.assert_close(state["suffix_quantized"], expected_quantized)
+
+    # A short terminal chunk must emit only its real frames, then release
+    # state. Its waveform should agree with the unpadded single-request path.
+    with torch.inference_mode():
+        expected_tail = decoder.chunked_decode(codes[..., -tail_frames:], caches=copy.deepcopy(state))
+    flat_tail = codes[0, :, -tail_frames:].reshape(-1)
+    output = codec.forward(
+        flat_tail,
+        runtime_additional_information=[{"meta": {"stream_finished": True}}],
+        seq_token_counts=[flat_tail.numel()],
+        request_ids=["scheduler-live"],
+    )
+    waveform = output.multimodal_outputs["model_outputs"][0]
+    assert waveform.numel() == tail_frames * decoder.total_upsample
+    torch.testing.assert_close(waveform, expected_tail.reshape(-1), atol=1e-5, rtol=1e-4)
+    assert codec._decoder_state_cache == {}
diff --git a/vllm_omni/deploy/breeze_tts_2.yaml b/vllm_omni/deploy/breeze_tts_2.yaml
index 1d1b85391b9..fd75dd69ebf 100644
--- a/vllm_omni/deploy/breeze_tts_2.yaml
+++ b/vllm_omni/deploy/breeze_tts_2.yaml
@@ -32,8 +32,12 @@ stages:
       temperature: 0.0
       top_p: 1.0
       top_k: -1
+      # Match upstream's penalty on generated codebook-0 history.
+      repetition_penalty: 1.1
       max_tokens: 2048
-      min_tokens: 1
+      # min_tokens also masks the tokenizer's EOS 1 despite ignore_eos.
+      # Keep valid codec token 1 and an immediate backbone EOS available.
+      min_tokens: 0
 
   - stage_id: 1
     max_num_seqs: 8
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/breeze_tts_2.py b/vllm_omni/entrypoints/openai/tts_adapters/breeze_tts_2.py
index d2851e32cbd..03f0d3c4bd9 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/breeze_tts_2.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/breeze_tts_2.py
@@ -4,6 +4,8 @@
 """Breeze-TTS-2 serving adapter for synchronous full-payload generation."""
 
 import asyncio
+import copy
+import math
 from typing import TYPE_CHECKING, Any
 
 import numpy as np
@@ -49,6 +51,7 @@ def _load_supported_speakers(self) -> set[str]:
         return set()
 
     def _load_codec_frame_rate(self) -> float | None:
+        assert self.ctx.engine_client is not None
         config = self.ctx.engine_client.model_config.hf_config
         codec = getattr(config, "codec_config", None)
         if isinstance(codec, dict):
@@ -99,6 +102,14 @@ def validate(self, request: "OpenAICreateSpeechRequest") -> str | None:
         greedy_error = _validate_greedy_sampling(extra_params)
         if greedy_error is not None:
             return greedy_error
+        repetition_penalty = extra_params.get("repetition_penalty")
+        if repetition_penalty is not None:
+            try:
+                repetition_penalty = float(repetition_penalty)
+            except (TypeError, ValueError):
+                return "Breeze-TTS-2 repetition_penalty must be finite and positive"
+            if not math.isfinite(repetition_penalty) or repetition_penalty <= 0:
+                return "Breeze-TTS-2 repetition_penalty must be finite and positive"
         if request.max_new_tokens is not None:
             if request.max_new_tokens < self.max_new_tokens_min:
                 return f"max_new_tokens must be at least {self.max_new_tokens_min}"
@@ -210,7 +221,16 @@ def apply_sampling_overrides(
         request_id: str | None = None,
     ) -> list:
         del prompt, request_id
-        return apply_max_new_tokens(sampling_params_list, request)
+        sampling_params_list = apply_max_new_tokens(sampling_params_list, request)
+        repetition_penalty = (request.extra_params or {}).get("repetition_penalty")
+        if repetition_penalty is not None:
+            # The generic speech handler copies extra_params to extra_args;
+            # promote this value so the worker receives sampling metadata.
+            # Only this scalar changes; preserve the caller's params without
+            # copying nested state or the unchanged codec-stage parameters.
+            sampling_params_list = [copy.copy(sampling_params_list[0]), *sampling_params_list[1:]]
+            sampling_params_list[0].repetition_penalty = float(repetition_penalty)
+        return sampling_params_list
 
 
 def _validate_greedy_sampling(extra_params: dict[str, Any]) -> str | None:
diff --git a/vllm_omni/model_executor/models/breeze_tts_2/modeling_breeze_tts_2_codec.py b/vllm_omni/model_executor/models/breeze_tts_2/modeling_breeze_tts_2_codec.py
index 7addb393417..860d64c44c9 100644
--- a/vllm_omni/model_executor/models/breeze_tts_2/modeling_breeze_tts_2_codec.py
+++ b/vllm_omni/model_executor/models/breeze_tts_2/modeling_breeze_tts_2_codec.py
@@ -204,6 +204,7 @@ def _forward_stateful_chunks(
                 f"Breeze codec request id count {len(request_ids)} does not match input request count {len(requests)}"
             )
         valid: list[tuple[str, torch.Tensor, bool]] = []
+        valid_indices: list[int] = []
         for index, request_ids_tensor in enumerate(requests):
             runtime_info = (
                 runtime_additional_information[index]
@@ -238,6 +239,7 @@ def _forward_stateful_chunks(
                 )
             frames = int(flat.numel()) // self._num_codebooks
             valid.append((state_id, flat.reshape(self._num_codebooks, frames), finished))
+            valid_indices.append(index)
 
         waveforms = [empty.to(device=ids.device)] * len(requests)
         sample_rates = [sr] * len(requests)
@@ -247,7 +249,6 @@ def _forward_stateful_chunks(
                 multimodal_outputs={"model_outputs": waveforms, "sr": sample_rates},
             )
         states: list[dict[str, Any]] = []
-        valid_indices: list[int] = []
         max_frames = max(codes.shape[-1] for _, codes, _ in valid)
         batched_codes = valid[0][1].new_zeros((len(valid), self._num_codebooks, max_frames))
         for row, (state_id, row_codes, _) in enumerate(valid):
@@ -258,7 +259,6 @@ def _forward_stateful_chunks(
                 self._decoder_state_cache[state_id] = state
             state.setdefault("prefix_frames", 0)
             states.append(state)
-            valid_indices.append(row)
 
         decoded = decoder.batched_chunked_decode(
             batched_codes,
@@ -353,6 +353,27 @@ def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
                     device_map=str(device),
                 )
                 self._sample_rate = int(self._audio_tokenizer.model.get_output_sample_rate())
+                if self._async_chunk:
+                    connector_config = getattr(self.vllm_config.model_config, "stage_connector_config", None)
+                    extra = (
+                        connector_config.get("extra", connector_config)
+                        if isinstance(connector_config, Mapping)
+                        else getattr(connector_config, "extra", None)
+                    )
+                    value = extra.get("breeze_codec_chunk_frames") if isinstance(extra, Mapping) else None
+                    try:
+                        chunk_frames = int(value) if value is not None else 8
+                    except (TypeError, ValueError) as exc:
+                        raise ValueError(f"Invalid Breeze codec_chunk_frames={value!r}") from exc
+                    if chunk_frames <= 0:
+                        raise ValueError(f"Breeze codec_chunk_frames must be positive, got {chunk_frames}")
+                    # Qwen treats chunks shorter than its configured window as
+                    # terminal tails and does not advance their rolling cache.
+                    # Match the producer's chunk size instead of its default 25.
+                    decoder = self._audio_tokenizer.model.decoder
+                    decoder._initial_codec_chunk_frames = chunk_frames
+                    decoder._incremental_chunk_frames = chunk_frames
+                    decoder._incremental_chunk_ramp = []
             for _ in weights:
                 pass
             tokenizer_module = getattr(self._audio_tokenizer, "model", None)
diff --git a/vllm_omni/model_executor/models/breeze_tts_2/modeling_breeze_tts_2_talker.py b/vllm_omni/model_executor/models/breeze_tts_2/modeling_breeze_tts_2_talker.py
index beaa390c8d3..765df5fbf86 100644
--- a/vllm_omni/model_executor/models/breeze_tts_2/modeling_breeze_tts_2_talker.py
+++ b/vllm_omni/model_executor/models/breeze_tts_2/modeling_breeze_tts_2_talker.py
@@ -13,6 +13,7 @@
 from __future__ import annotations
 
 import hashlib
+import math
 import os
 from collections.abc import Iterable, Mapping, Sequence
 from pathlib import Path
@@ -367,10 +368,12 @@ def compute_logits(
             return None
         logits = self._main_head_logits(hidden_states)
 
-        # ``make_omni_output`` runs immediately before this hook. It records
-        # requests whose previous hidden state selected EOS or reached the
-        # frame budget, so the scheduler receives a real stop token instead
-        # of depending on an arbitrary deploy-level max_tokens timeout.
+        # ``make_omni_output`` already selected codebook 0 and completed its
+        # frame. Return that same decision to the scheduler, including EOS.
+        # A finite zero survives the sampler's repetition/temperature passes
+        # without applying the repetition penalty twice or changing the frame.
+        # These logits describe deterministic codec selection, not model
+        # confidence; sampled-token logprobs are consequently zero.
         states = self._batch_state or []
         if states:
             for state, row_start, row_end in _iter_request_rows(
@@ -378,10 +381,11 @@ def compute_logits(
                 getattr(self, "_batch_state_spans", None),
                 int(logits.shape[0]),
             ):
-                if state.get("breeze_force_eos", False):
+                selected_code0 = state.get("breeze_selected_code0")
+                if selected_code0 is not None:
                     row = logits[row_start:row_end]
                     row.fill_(float("-inf"))
-                    row[:, self.codebook_vocab_size] = 0.0
+                    row[:, int(selected_code0)] = 0.0
         return logits
 
     def _main_head_logits(self, hidden_states: torch.Tensor) -> torch.Tensor:
@@ -443,6 +447,13 @@ def make_omni_output(self, model_outputs: torch.Tensor | OmniOutput, **kwargs: A
         self._batch_state = info_items
         self._batch_state_spans = spans
         per_request_codes: list[torch.Tensor] = []
+        # The runner passes the same per-request sampling metadata to this
+        # hook and compute_logits, including offline SamplingParams overrides.
+        # When no_penalties is true vLLM does not initialize this GPU buffer.
+        sampling_metadata = kwargs.get("sampling_metadata")
+        repetition_penalties = None
+        if sampling_metadata is not None and not sampling_metadata.no_penalties:
+            repetition_penalties = sampling_metadata.repetition_penalties.tolist()
 
         for index, info in enumerate(info_items):
             if spans is not None and index < len(spans):
@@ -458,11 +469,22 @@ def make_omni_output(self, model_outputs: torch.Tensor | OmniOutput, **kwargs: A
             row_hidden = hidden[row_end - 1]
             if self._golden_dump_dir and bool(info.get("_omni_is_prefill", False)):
                 self._dump_golden_prefill(info, row_hidden)
-            main_logits = self._main_head_logits(row_hidden.reshape(1, -1))
+            main_logits = self._main_head_logits(row_hidden.reshape(1, -1)).float()
+            penalty = float(repetition_penalties[index]) if repetition_penalties is not None else 1.0
+            if not math.isfinite(penalty) or penalty <= 0:
+                raise ValueError("Breeze repetition_penalty must be finite and positive")
+            # Match upstream: penalize each previously generated codebook-0
+            # id once, excluding the text prompt and reference audio codes.
+            history = info.setdefault("breeze_generated_code0_ids", [])
+            if penalty != 1.0 and history:
+                history_ids = torch.tensor(history, device=main_logits.device, dtype=torch.long)
+                scores = main_logits[0, history_ids]
+                main_logits[0, history_ids] = torch.where(scores < 0, scores * penalty, scores / penalty)
             code0 = int(torch.argmax(main_logits, dim=-1).item())
             generated_frames = int(info.get("breeze_generated_frames", 0) or 0)
             max_new_frames = int(info.get("breeze_max_new_frames", -1))
             terminal = code0 == self.codebook_vocab_size or (max_new_frames > 0 and generated_frames >= max_new_frames)
+            info["breeze_selected_code0"] = self.codebook_vocab_size if terminal else code0
             if terminal:
                 info["breeze_force_eos"] = True
                 existing = info.get("breeze_audio_codes")
@@ -476,6 +498,7 @@ def make_omni_output(self, model_outputs: torch.Tensor | OmniOutput, **kwargs: A
                 raise RuntimeError(f"Breeze main head produced invalid codec id {code0}")
 
             frame = self._generate_depth_codes(row_hidden, code0)
+            history.append(code0)
             info["breeze_current_frame"] = frame[0].detach()
             info["breeze_generated_frames"] = generated_frames + 1
             info["breeze_force_eos"] = False
diff --git a/vllm_omni/model_executor/models/breeze_tts_2/pipeline.py b/vllm_omni/model_executor/models/breeze_tts_2/pipeline.py
index d1aaeb13e34..2b538df010c 100644
--- a/vllm_omni/model_executor/models/breeze_tts_2/pipeline.py
+++ b/vllm_omni/model_executor/models/breeze_tts_2/pipeline.py
@@ -28,6 +28,12 @@
             custom_process_next_stage_input_func=f"{_PROC}.talker2codec_full_payload",
             sampling_constraints={
                 "detokenize": False,
+                # Text EOS 1 is a valid codec token; only the backbone's
+                # explicit codec EOS below may terminate audio generation.
+                "ignore_eos": True,
+                # The talker has already selected the emitted frame's token;
+                # min_tokens must not mask that token in the sampler.
+                "min_tokens": 0,
                 "stop_token_ids": [2051],
             },
         ),

From 63032c91c66bf7a4502744d138899554c26b5750 Mon Sep 17 00:00:00 2001
From: Weiming Liao <liaowm5@gmail.com>
Date: Thu, 17 Sep 2026 04:43:43 +0800
Subject: [PATCH 048/105] [Frontend] Add ComfyUI Generate Music node with
 initial MiniMax Music 3 support (#7516)

Signed-off-by: Weiming Liao <liaowm5@gmail.com>
---
 apps/ComfyUI-vLLM-Omni/README.md              |  12 +
 apps/ComfyUI-vLLM-Omni/__init__.py            |   3 +
 .../comfyui_vllm_omni/nodes.py                |  60 +++++
 .../docs/images/comfyui-music-generation.jpg  | Bin 0 -> 201933 bytes
 .../vLLM-Omni Music Generation.json           | 206 ++++++++++++++++++
 docs/features/comfyui.md                      |   1 +
 .../comfyui/test_comfyui_integration.py       |  78 ++++++-
 7 files changed, 359 insertions(+), 1 deletion(-)
 create mode 100644 apps/ComfyUI-vLLM-Omni/docs/images/comfyui-music-generation.jpg
 create mode 100644 apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni Music Generation.json

diff --git a/apps/ComfyUI-vLLM-Omni/README.md b/apps/ComfyUI-vLLM-Omni/README.md
index d0d002d0f2a..f9ee3b0c107 100644
--- a/apps/ComfyUI-vLLM-Omni/README.md
+++ b/apps/ComfyUI-vLLM-Omni/README.md
@@ -52,6 +52,7 @@ This extension offers the following nodes based on the output modalities (at **C
 - **FastH3 Deployment** for routing text-to-video requests to a MiniMax-H3 server with FastH3 fused at startup
 - **Multimodality Understanding** for multimodality-to-text and multimodality-to-audio tasks
 - **TTS** and **TTS Voice Clone** for TTS tasks
+- **Generate Music** for lyrics-and-description-to-music generation
 
 This extension also offers example workflows (at **ComfyUI sidebar -> Templates -> vLLM-Omni**)
 
@@ -274,6 +275,17 @@ The node records which server the workflow targets; it does not start one, nor s
 > [!TIP]
 > There is a dedicated node for VoiceClone tasks with reference audio input. Other simple text-to-speech tasks should use the regular TTS node.
 
+### Music generation (e.g., MiniMax Music 3)
+
+(Also available at **ComfyUI sidebar->Template->vLLM-Omni->vLLM-Omni Music Generation**)
+
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/apps/ComfyUI-vLLM-Omni/docs/images/comfyui-music-generation.jpg">
+    <img alt="vLLM-Omni Music Generation" src="https://raw.githubusercontent.com/vllm-project/vllm-omni/refs/heads/main/apps/ComfyUI-vLLM-Omni/docs/images/comfyui-music-generation.jpg" width=55%>
+  </picture>
+</p>
+
 ### Chaining multiple model services
 
 (Also available at **ComfyUI sidebar->Template->vLLM-Omni->vLLM-Omni Chaining Services**)
diff --git a/apps/ComfyUI-vLLM-Omni/__init__.py b/apps/ComfyUI-vLLM-Omni/__init__.py
index 55b003ef1d4..8c1b03d8744 100644
--- a/apps/ComfyUI-vLLM-Omni/__init__.py
+++ b/apps/ComfyUI-vLLM-Omni/__init__.py
@@ -19,6 +19,7 @@
     VLLMOmniDiffusionSampling,
     VLLMOmniFastH3Deployment,
     VLLMOmniGenerateImage,
+    VLLMOmniGenerateMusic,
     VLLMOmniGenerateVideo,
     VLLMOmniMiniMaxH3Params,
     VLLMOmniQwenTTSParams,
@@ -38,6 +39,7 @@
     "VLLMOmniGenerateVideo": VLLMOmniGenerateVideo,
     "VLLMOmniUnderstanding": VLLMOmniUnderstanding,
     "VLLMOmniTTS": VLLMOmniTTS,
+    "VLLMOmniGenerateMusic": VLLMOmniGenerateMusic,
     "VLLMOmniVoiceClone": VLLMOmniVoiceClone,
     "VLLMOmniVideoReferences": VLLMOmniVideoReferences,
     # === Params ===
@@ -58,6 +60,7 @@
     "VLLMOmniGenerateVideo": "Generate Video",
     "VLLMOmniUnderstanding": "Multimodality Understanding",
     "VLLMOmniTTS": "TTS (Text to Speech)",
+    "VLLMOmniGenerateMusic": "Generate Music",
     "VLLMOmniVoiceClone": "TTS Voice Cloning",
     "VLLMOmniVideoReferences": "Video References",
     # === Params ===
diff --git a/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py b/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py
index 47bdd9a2ccb..64020b79781 100644
--- a/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py
+++ b/apps/ComfyUI-vLLM-Omni/comfyui_vllm_omni/nodes.py
@@ -503,6 +503,66 @@ async def generate(
         return (audio,)
 
 
+class VLLMOmniGenerateMusic(_VLLMOmniGenerateBase):
+    """Generate a song from lyrics and a musical description with MiniMax Music 3."""
+
+    @classmethod
+    def INPUT_TYPES(cls):
+        return {
+            "required": {
+                "url": ("STRING", {"default": "http://localhost:8000/v1"}),
+                "model": ("STRING", {"default": "MiniMaxAI/MiniMax-Music3"}),
+                "instructions": (
+                    "STRING",
+                    {
+                        "multiline": True,
+                        "display_name": "caption",
+                        "tooltip": "Music caption: describe genre, instruments, tempo and mood.",
+                    },
+                ),
+                "lyrics": ("STRING", {"multiline": True}),
+                "max_duration_seconds": (
+                    "FLOAT",
+                    {
+                        "default": 300.0,
+                        "min": 1,
+                        "max": 360,
+                        "step": 0.01,
+                        "tooltip": "Upper limit; rounded down to whole 25 Hz audio frames. May end earlier.",
+                    },
+                ),
+                "seed": ("INT", {"default": 0, "min": 0, "max": 2**53 - 1, "control_after_generate": True}),
+                "response_format": (["wav", "mp3", "flac", "opus"],),
+            },
+        }
+
+    RETURN_TYPES = ("AUDIO",)
+    RETURN_NAMES = ("audio",)
+    FUNCTION = "generate"
+
+    async def generate(
+        self,
+        url: str,
+        model: str,
+        lyrics: str,
+        instructions: str,
+        response_format: AudioFormat,
+        max_duration_seconds: float,
+        seed: int = 0,
+    ) -> tuple[AudioInput]:
+        audio = await VLLMOmniClient(url.rstrip("/")).generate_speech(
+            model=model,
+            input=lyrics,
+            instructions=instructions,
+            voice="default",
+            speed=1.0,
+            response_format=response_format,
+            max_new_tokens=int(max_duration_seconds * 25),
+            seed=seed,
+        )
+        return (audio,)
+
+
 class VLLMOmniVoiceClone(_VLLMOmniGenerateBase):
     @classmethod
     def INPUT_TYPES(cls):
diff --git a/apps/ComfyUI-vLLM-Omni/docs/images/comfyui-music-generation.jpg b/apps/ComfyUI-vLLM-Omni/docs/images/comfyui-music-generation.jpg
new file mode 100644
index 0000000000000000000000000000000000000000..1c8130fbdcfef3b3d18add0a1b107ef7d7625620
GIT binary patch
literal 201933
zcmeEv2UL^Ww(d`nF1>f@ic~?0fq+O80Rg2K6_6$(O@c&1QF=#d(tAgwDbjnBUKA8a
z0@6ehX`zLeeeN53d+sp%opatjx4d_7WH^GDf6X=9H|P51;`HO`B0zgxLt6tNARqv=
zaDRZ)IY8~VcmG#kzkSI6)d&3cpHJHWIx<2*qIe<#K7f#pfQXLZv<u(?0D?3B_SwMy
z{vseGB0fVxN=8mWiTi;%T7Zy%h=`Dw=*$^nV%$$Z#r-=#Om~L<oRlgFgTY-=K6ggx
z!1x?8{;SpPOon49flK#1g2*YDSy<WF1%-q~&R>v`y(}lMps03DT|-k#`?}Gs+r}oQ
zX6Ckb_V*neot!<rydV2Oe4hkAdma)R79Nq1_~K<!a!P7iZeD&tVNr2O>6@C`y84E<
z?;1NgySjUN`}zmQCnl$+XFh(Kg(Hwl%U@Sk*VfTLws&^-_Av*CzsW@a5dFSo|0dYK
zlZy@~7a=h*5i#j+auE>v;9f*@#AnV)k<hCekluA?;FAs{W4s!lQ{7I^f5{NVbkAdq
zf>}TYE{Oh3w7*F9w+R;X4@vgBV1LLp3s4ae;FL#12Y>;rOf~p;ClY(ydJ6Cq!x?;~
z?jnf>V}Y)&z}h?XLO{B=JlhV}1%0VgVC7kBI?wTwybulAE@Ej~{wO=vNB#zVL)nYF
zY`|fFBM_zA_yFX)P2$PGnI$ByxfMbpDXG20kj_al5$^xVHaV){P;Z?74(az0574*;
ze<9l=UxhVe+xQ0Eqf}};;()uzeJLu=0g^|TdNjyZ6bNg-_x$KOFeFr-crJ9Y{vKP8
zfM~DL+bS+;NH(Q(czslpop0Puc&M@$1iTRoEXK!ZsPLwTOZ_Cza(qPW=RUA6dB5ad
znlveWVgiKgjfNH*-%s)c@ITXC>JE*f5eE@5(36Y>Xr&OkPcAx)dgV%8UVDvR8Dbl{
z;Q>u~$J4^f+SV={r}yX)ncZC~6}5AO@;$1dq|2O91JpDIaWuswVN0$P{$JHn33yo{
zCqrta(t+tz==dOoVHJSv)o|=etg_`>Wg}aToId{HegPyYKP!kci2T}|hP5=P@5!~!
zEJYB{Zg0RNtzLd!T0IpzH^oa!{aNA$QJslNq47tb@7y6upy3Ci7LznCfIWFnmV^a5
zXC3=Euj^?qKJI7ZwF@BsS^R&JI)U(}RV-wCc`$hSvQ#5y5a?Tio}`CVaC;wbjK&wa
z?{*4t^aP=?pSvVIMcCR#*jV|~mw>)`FNgj_Wy?IaP+>6|{{6RYZKML+8U$=@1R}2-
z2YWPAX|z&2S2TmMZ&B3btV?!;<b8<@r@)9->(<~YfIf^dV=X=z3f_-PPo#0m<8?o;
zARIU+U>BGmu+4*o=p3}40=>nANtuF|A8kT9u-gQA_xbm$(&H}#j~ww6#XOlx>6$C-
z?9GyNkdo^Eac{{VbH|p5I8#-jy{)3?J*B)#ga*;j!HX_}lZ~A(d<|R*M473aQz`$_
z=zp<B<*&`(Fom@JK(<Lq@w&1ShX)9A>5)7oz0S|@@D&X=v^~A6SGYei{s<lzMMdvR
zyg~}#i%|Hj^G_p`J%cM7q;LD&8Ur<S6$P8&CTQp9j0#XyU@Cenmn1w8N4J-LUdq0P
zc3A41wPHp$WG%7V>|Y*=$3y>9^!X<t>V<BtJ(7PYH2;Reb{;NhSVBmNqdcSuh?ht-
zw)2#4r2bfD9a2zm^yO*pApsP4e@K!IliS_P+n1)9zv^*AsW2+AD}O1I^g(<Ai5Boz
zA*!G#TsQrSwPb5ko8zajlZ_RD>)G4bzBXiLozD>L04}jYdJ1rtn)|)3c}A9h2Q-p;
zLxpF)Rd-y}eIia_E&c;whBt@)iA4C#`adb?{y(hJ7&^H`W^PH)TNKp|Ee;I=zB}Z-
zMuAzX<N1GNol<!`a3FvTf69?h-b_+}48rm^`7Q(gs}B4h1m7s$O(spue0g7i!)xJP
z+*cJX5^k_3ZTnER0};sXPK;-qsNOfXi~28l`8VYa?+xBRmwxYRllPSf^n`E(Q1c&|
zM*pSJUjw{9(I|d^M}`+eP(`n3KvOR*4@jkWc#Qr4`$bU!9;!=s=+XiD|2Tkq-U(sk
zKs^&Bu_eiV`5ySmK|g&l=oEM(DZf&IKj2Wz;tf+~_#@7rgsFdG;QeQL>3?6H{^t}e
z6@M0`3@(o)N5x8W$4jmZ$C947FLKgL_4N@m#GCur`rd<<5b!v4Br;n_Q6cG>kR_i@
zVp2i3Q~$O^`Y(O{KU0L3nnPZE>a0Uj9u1L1r^L>;cw8%`0e_34R@g9s_MQTn^w>u*
z^m+l_5^VGg{=)75cmKpM|NpqA!k<=P|LPI_f8HY^PRYVPQ9lLzZBBvMG0l`yV7tR+
zm<Fq)4sb(xwr3@dFj+{0P8mMdz$D3Q?m<)$Wam_PgFMKT)Xj>sPXPm(6OY(aK*b!0
zQOG$fCEY_1N0-VHztknIuw+LU|Cw&`w$pOhyy@!%>9W0yF2%TaVFZckRGB1CGG9Ih
zw}MZ+ZBFRU8o$LoeU9en$tf_Vqe4F@Bd9{(qn}ESPzRCc3GA){0-0^}kP;9Eyi#kk
zj|TUIw;)b|8B_2M)LRTN4spCDMRf5_7?PNck@jkUD)AESlL-Da+6jh>ci0Hn;(fVq
zsPSiNsIqajbE#{S9)`g-Uce3s$9NX9u#HvNu#f=$OKLd4_z}hbg5j$;ffzZEjuapY
zTp%4CyEyt1&|y=y6AouY2}LE&WCIC)fHorEZ5NGO!THu5d68G&B~HA9PXWzd71Auy
z<Gn~MRv0t+=mS{@uYD99=bd1_AhMfeyy-zS2FA`J;7K)HZJc)sj4}uC$2h9pxKSNo
zM|@v>$ybUh#+QxQ&WG5Wku3*TF+YIN4UliM07=gR^xP8&+O~pMowcyXr@-zMZ0DMc
z+#%)^*m$vU$jL~+S#$Lk!9}}+xJ&_~wlryd>i|OSZv?^-i6g;SKb(4D49AXtEYon5
z<YCrD9S4fq_%fPH=Q32;UiS3~(8Z68m-ot?D-<$qlP0{x_XCs?q6vx$lD-n87!j$9
z(~t;kvj`iVP~N-0atc(IodUV%vdM-<55}@CgUFVN4<Z9}uBr&j_XCSQ?K?6$c(llI
z0)_1kxSdc_2pvV90#<i$N=J_ptl(M(O1Y;%YdBVx^U~FGVQjX<nykEi*+GniWWv0`
zleg0%Xm)9Fn=Wz+?3~FaL*h{|i6eA%<P|ruM-a5TO)!U-A>A(E(UrwR_JrT<?JTwh
ze7G!!4Lt*B;#2VUA})uH!4|qs0rsC3I$29#&Xz;lMO7WdA4O|-Q<Z{%m?2JeT?CIR
znFM&&&*65<;1pP;yaw}!9j><?^05O2plXgmW_pd={u6IQ4OyfBY0tpKwh^Q8ay-^w
zTnR?*bz<jRcMPXee>Z<Gz!wD@actc}z@jy&M#Jurn6}gPkV%X1J_mxx`*?Sm?&k)d
zTm$b8fKLb<3FW^&lj#~{B~j6^v(`+c?OTbD)6jgRX`q_Mqj>3SZy;xOmeeD1M=jzN
zHeOC@jB-eR?A8cQM<%DhH8nL@RV?-$&Jc3iRp{`n@_&?%PKha-CJi$=@f&mBS5pkS
zBpM&5#m}Er;B=cy4hzaT1?sa7FJA|e@I<zo_d|!H4yqS5MTCbe3C-yV6neBsiCSoK
zO8AeqadvteXV|o(3mZtB`i)?#k8Tosd?3F`T%Gv!DkNT?(6L|X2|zCVnmF@<zB0|h
zCd<jOK04R!ZR_qd%?S^ejtWyw8Xc9&AS<7IJBd0mZ8oi{0x@@P7#<ZGs$z3_4wreb
z0kxX{t^LzD(=>WHlAQlStJ7z-63UbSHifqSMTe3#<D_evS)K$(W4*9l+C3(72jll|
zycM*tW6c5bR_K6t$ajmk6yqXmi-?aD1P;C2K0I9wH6;HuOupx#ee&U;s;T;K@#Pq^
zybHh`Tyk0D4zd&2!R3}Cio}t~BjoNWKw&+de0*GV3Iz5ZAJ5E7xaeU0jZT3!B-ZYi
z;ryECRrY)KQAE7_(h~grVRoK<ef<1y`HOSe@@Ts#foqOryh}K}LDtWb%iJv#3?Na_
zB>gQn%CE&~PO>XiNE{sKp8`a&2e`%m^ezyeH-_JTR!nHxzkLp*RTL;=m)Q&uCw?T<
zXJpIUj{DAv%NFgw1w5~H75PJU!8GY?5@K9NAXpW;s;?J7sQ)@|cKj5`dT|P%<Z*we
z9d-V@_x*n)*t}on)Zh2X^?gZ%Ae9{1C=-bGDpeFGx70|{6X$}<<F|R|KAl%@s2{+(
zY^mKoU!PDyGT(n)thwG~+vW)e=V(Yusx8n*HWb<S;~pF54{5T#?_}#D__FV0{K)|>
z$Cct@XPDz38TY~<f0E<%0Kup%X@;%{2!n?9#wehz6d-^${39ANJnhE$-D}t?X5Ae4
zFtHr|0B)Qhd-to|rDA^RcWlH#(h7&SQ}8&Gfm17bndYPx=fQ7or~Hv~3E2Kl)iCk@
z5j3wYxWhKec@C8of&bG+*BJca%><lytStKjO$OVxZClJu{gk)FwE~2mQE}9yP#!hI
zp8`Nm>kO_Kv@FEojm2!T<uv+ia$Dh{XK21m;<1D$I{>}@9dgjE%-^xzAB#*15LNpX
z?xXua<`kYJNfi*)*Ay#sE`EfcH!5Z^CO7|&Jo8i1P+=@e;`hDRp*2u7>qEPK^(!xl
z-Xm!U+xnB+slT>nCZ^tF|BtY_8Ek}kjofFO!wphwY)k;n?=i9%{;RlHK6w*X9EyFX
zc?x8U0h<3orY1tDfM=D$zeByT-xpbsO)>f_*oQApl<@w9pnpyp#P{)m7(qN5jQ$<c
z{9*X3z|SD2plFc(Q%8k>bLUW>!%Yo)4{35@JI|ep3wb!>=zRg+n>YnD`c>%hK|m@z
zKu=cScU1ESv;$(yaxMT#($GGA`tysrY{FG41Oj_NVz>5BI8R1*p9R~9!+m+k5=X+?
zUx7XYJbJvK^%IT``)}%?r4xg6P1Sb=>`gYWgn6Iyq$LuTX9H2~DqZ;Y`<7L><M<)<
zJbSq8lbaME_;<#&ieEuKMol~*KH(?)oclW%1~l;Dm|Q$M)cOO{82oPg|5Xn9S2ljZ
zT!c_UP{|%wM&J+_dLV}NMJJumjT9tESCX@Ml_-ET8z2~^y7hC_JNYQQDdjafaJe_&
z-aVCBNpc22Pcfb9kopCnNuTs8RX&a&ypZQd4}U*Rg2$8e^g9j!fjMN-+BB*^<Ver+
zVm_LdpUU#h(I!8CaJ;cCzQc3ET7*r#=`vCbn^+t6k>DsNJys^EZ!N@<TkpxuGpYA(
z=B0wCuPUV3PCK?QzGG`&+$ANZRgo1=$b54OEa1{0W?A!ZJBb4DNNvD*-Ta{)LWM*q
z1vbbUE1<01zwY54m<|w-z3PvoVdb`jkO&E!%>&{kiIF93BiU=$?zv9fMUJFgN=aEd
zkn#XSC8Yv`^m)@47XcE%?L4+b5(WLkwVF<~(XBqt^ngbY0eTX0Jd()J$z|}2a6{ic
zf)@73sl{n#Bxv_gYe+&Ai18lD1dxMX>?UJzWEEV5x*&hgi0WFZv~3hxrp+TSn;PH_
z07zA&4DZ1X)>uvsU|6t0htQ9Eojs(<+yvp_M2>9&Hwfg{A6;5iyh(shcHo|kqExD+
zEe;h`z5>Z8Q6C5P_mPqYsq)_WM~;kvBtZ&=#1lLI)Iz2EQQVaA>D)9oAE^=(8Ty{z
zkT}7?u2Uf9mdD?629-@=4t1V>lwe1EkoDN?mb+*SlcmTp(7&{8Y#XklJCv>kbWPA4
z*wQV9_A4mq=}BG+04newl;6iox&nyk55}VUgE@;%ygtEmR(+PJ^;G0R^yEau)glH%
zSsUj#KS*uJ+(B7JEux+T2a)lz|0DfT;>_z$aD*cmu6KZZ$tiU{gzrYGR1YNWj)K7`
zDL|tF5M{HL{4Fdi5g<lTOitRJmx$p8csWWlfk$9zS3$mQ7yzUsGFXRFqy}I!x|!_U
zq5djMOGLr#ym68mLSHU(gARff!ejIkS@`!miC9?$evl7S1J~xgU?ATg%k4j2v3{Xe
z<$kO!%&NfJzPLmS=+Hms?8m;L8=By*(V#igH%voXEYBN6Q1Y`?D&XrNUi&%7j1oWU
zDr60pw(Dg>I0Y<gs&E2I06-mZFAQNg;VDcHNXc|!O}l*0{m|1lN{pgf1jzn=dJbVN
zy11#DE%EGL`d2e;1g{3`JNx}v4NX$M@<BYJl>Qlm5HCLmp#RyL@ko}B>zr(lOC0?;
z1&;mm@NogN3FTkZe(vuIpwg8*1(Kw=wV;WKlS@b<c>w5Y@v@b^(|aD*fVd2Ce8P1=
zlo&@%LmZ^i&icyhBV_w4)mI?}<r|i<3sh8h?j-gJ%gYlm_>LW;R|b<w2OijZDG>X9
z5=g(ZWJ?+xr$TV?I-{rXVV~xu8&5v4f>`+FLEPDkL1ZNPKa8erj!psaDZp90jE|E<
z|3{cnq3fhixhK${$mtMXNc55mcm(VKfFeNzKR&-ahll?uf<MOmiS+mc2@=}QJ3x*k
zi_^UL*t6<Ew*5w1zP+!9hLkr5-<e_@!OscCZ~|#u^DL29c<AWOKwh}zqf)r$B8k3m
z+WT-EO*P+Ue;JpCP7Eiy3WvF>SZ(I-$UNxs-`!3Syy<%i*xhj-F$Ze?2L@U)c=!z|
zdb|FZOI;HL12F;ez!L!A0=ntC3JSmK2>|z;LXWG%eyA;_XBG*wvb6!U_z(mBF!LvQ
z24Bih#cRu|c!2<r*spH}+rl-8k3I521SPw)6NThQ7;cbWPy`kURsq0^h)GBo*V&AR
zEhOUt@h&Hyo6tqj9bflF)|9x*QH0mp7-EWul!FTZE7Vp<lO__(;OI|{dK_2@sp)PJ
zov9t6!dP@*IVWV#!n!gA(aa6Ss`;x=NCI=$UR$lFO*fP~n_O;u{IbAlZ$|F$`EGY}
zMm~e34yWsmO*{DG9I~}nOIgI(nhTY23WPvqQK4-%Tp(AZ1RDf-6&(|~xM5|q2gPV2
zTBEJyFjhQa<xq*TkE-a0`|Zk9(}k%0Aa8A%xyZ<r1YPSb^>M?k+jR%q9m-;8xz1C7
z72?qAPd)7hQbO_&V_s>XeV#*Ai=?|@Ihf?mw2Jzg9GA<~2=$mP-KmS4ZWU(J>e@L`
zukVn7CvCcIFd{SG1kpr@y4WBrE%bT~h970K7ku&(yqE`OI|UqR7$B`33mjEYQMd#~
z#OIh1wx}8I&$ZD)hSmsNTnNb&M?bEHgM*EnGAU6piAXmBh+Gdl6}xyd!VDxQxErA*
z?(fu*zCP_OJTP^?eAaTn$mQ|W3!g+cbr&BSsebaw(sliprIqWt!s1SI8hiDXt~>P&
z;B<+QEC6JWHiA2Ba-e-WXOlx79LpU^Vp!T1XrWK-%jcbw4!>6AL2$~X3GgRhoo=D6
zuO6%8pghr=>$aiu(p57GHJhxZ)PjOtO25p`&pY2VcaobgKvnH=W2VrFds-(2;0Fst
z{qQSW&s*OVh555P@-Xh4uRH4m^*@KnD;dmp#PXrOhr7Zznt6;+d*M&wPJs?1Pj7_S
z<x}8#%{!~>Vwd-IYbU>dQ~rRVfyaJwfrHylfjQ5`hs~$J8TykKySf&8B^V~uLi;=g
zIx`rB+{0$ID>I;lJGN#U_MT$;{R$zN^{i^<c%-NrB9;_$rJKKFCX*iJ7A12EY+5n9
zNHBcC+?A+}jMiKL+m6io?OC0Kw9u@>2%$zt*N<gS@<9yf*1blIsPHCf0h9?<w5gtl
zaWFfHh58*S_<yviY1m|O^#kKtLIDeBWCs_RkFV5Y$`)I>9NC#-Vj;3L^dpPWMjiWU
zg*ot3fL<a*h_PfIv>l|E{w}SAbkHd6x>)|)8_SCPx+&|U8%`all^2FyD?^ir0|(#Y
zFG61umR!YlO?1}|JS(uBHXKm7BMJ-{OTko`Md<`10>O^1T49I%sm3d}>iV#}n8dCm
zWjeG(MCGwdp%V`(ChP173PG7gf+=g?tblcxH-17V1(rHR!t1N+5^r()9!dKTEzpCV
zPk{(>R4crxg>7tU;#dli6~?WI-ir0E!l+}}p(2>Oi@HLtKD{=K%0iH`Z#V}>#X$Hw
z6tA82E?H2!TfA<PY-H+~M*XrJ5^6l|6}dILFbl&{&>XSYV29%UKk!iR@KF1Y!AMSl
z`>@&MJ%3cyw<DAb;&LFm3~n8beuZ;Q-J|o^F>Ye?LT@Y6Mi!MUIK*E7HC&Bm*~`GR
zRvkZ5=H`||#m0PXMHi+PVS+nN%(+t$x=Q|!PhPe@bo;oVgL#gYXyd+c@}h+e+ml5B
zc8dK3L-u|vK#L+-+G82~C$rdOvxtPd-@B1JV{vX=j$uLU_ws}{WD1~8flgSMG9l_~
z9)jj9hP>$tLf5lnwkQl4qEBmO;nc$2!liiO(e->^S0=%s-K25n>*92gE}G|sau3pG
zch<&Nf^PE<I+ln#lvmxKeCKP+rsQ^BnDt9t9rhMF`Iuo2!2nen^S^-okj3cFjQy-k
zKIt#Gx<FD_g|TlIM*5c^TZxbL(3b;CAffG8PP9!2Pb8QG%K$ag;o<%S@##jk`HPK0
zS*jpvU2@8FGcxrv7eT62<`-LZ5fUHW_GVB|vm$qCn6bSJbrR2aPJz&Qy4SdK#8|f`
z^&>FUZ0zDO-J;U14YeEShRE;UU~=<Lcoo^YW~V<NGq=FB^`J(RB1x^-mYw45{rDr#
zQ-Bz8QUtT*!3YV}z-i8|XVt9)`d?W;1vpxrTR$BkSbA)@pnMp!BbC;U*gzg)u!9l{
zA~Z~fa=!(WjEaSCb;Yvb4jphMiL&78-Z%!<o<-^1e5u2q6E*$LtppQZr)zX1U5XvZ
zLfry~vXkJB>xi>QTa>U9)}TqR)*yeeQy?f_|Hyo8{(K##8L4v(wZF*(UwD12$SobQ
zpfY2Gh_aS^KMgYAi7&tf4O@5k-qfyk-N&74llBSDw~Cdmog?TUe~q#yWo?0IB0OA=
zYW8AH9%}a-$}yK1ID;l`zNmGNLcmE!$cl!Rg=Q|E<n3p?6XcRzIu@IO+0)Frbtn^!
zD__K{?D=8fi#)-zlk+SwgGicaf7)X$)P6^AXiuYmYB|Pu7wYK;_a1%d3R2D4P&97N
zRf_)dxp6wW_~W|bHMzb0`e?aJ=#9m#Ft9^bG>j2@22*7+x;w&n%!ghG_vePh8l$@W
zg&Rg6?ru>yC$lS89^SH+MlA$4nJ|_6>^0Ely3DhT*2y}4v~-&Oc6sJoRSbAB8%724
z^E@)eaCGx<HfbZk!Q4138>H;tdkWMDw@VN^H|lq}WRc2kGNFt*TdU>5WF;t_=9!XJ
zj<}zfLPQa<K`=)yTOIU#-Q6OH>n?b6@C#|T$zx^Fv8Cx&Tx49#$zlSXK@aY2omBf@
zg5tIWE`o7E8|@`w#?VA<)&khUX)pcFEiz0Ef~2_u12e()qM0-DU1n|eLX!Plz4y*K
z=uFgI(U<FQc~k#Z``nEc3is%>;U7j3=9O*@kKb9(7&y%y9@?Dmp)+|_IhkNyR;CzU
z=g{z;IrFgc@Hp|`z@B=KP>Od5e?K+(U+PdrfG{O_IO_fl)@ATU;mBDUwN_pa4}$i^
zI4xGKY1i=pbdbPJPX=yiO5?q|xY+_v9B}77!{??5&IBEJEFS1aJq+cIy&{kp#Tj)6
z<w16sxZYv<LgcIdZd}a$l-)E*h`7chh>~hMG3{CHrK0lIeJl*CU@#ywD~*o-sx~gf
zc`$}MysZQg1!*X-0YM%DKUX3F=bg}HW*ypb3}2sqvN!0el)wEb4@D%L_`wWcSxH#`
zj|{&6R5~jfmxQQ1vUVpNLPB#E;uI8sMU<8R6@6EZrZlYlnWs!|`B-qf$ED!*b!sx+
z07v|LAc(Il`By3S&o9L&CVFyzbltxpH|v>dFB}%gdT%*-!HJENGol7xDORQ@cw`@A
zExoXIMJqahr;)91Tl+ywihcXiN`V=E!Y=TWJ>#h{|7tJ-FP}4j3}0UXf3pW~vyWJJ
zMRU71OWcy@e0B8b65Wbjf_rd$6gRahfVV^Ra~*<TUhSXjN<fq9`rWWZp&Ra*LMha@
zya?KeMgd@zL<FB-0{EH=_y-LCD|%fz`qAdY^fv;sE`1-o5F_Z`QTCiCfDM%C{Qc)b
zOh=#omHgwTyD;B?u^PIgnPIJ$sw*e)fxSwOghTG<o!%ve1FUIxPl1c~Kye4c!X^DZ
zB#!`saOi4}U3-iXw($XKbmz(sQej?BZgS$lAiV89LcCpq0K)&kFw6hz>XQ*)PaU|5
zr*~_Bx7qV2(&G~ZzbO;vy5>o+aoZ{J-5tr`ra45m$qU%V$Kj|)g!=zFQTX*a%D+w&
zesP-eC!HSr-9G%2zkg+YB0nRU2mpiwlK-3M9mB?|MoZhL5+fCNxBWnqUphE=(vD~y
z*Q@@WH2G^z2f&YSP8^7s-M%^HHK=n%VWly((vX$5vqfzwsEa`)npyVDlCQPQHL7pz
zx5Mx;EuZXngt->JpMKaDp}m>?Cg?nYv18tQzoJxC;!XOx^efHK*NXQ8&I@;Zc<30I
zcBI?z6!li!CAE)Y^;_jNIuZ8<w>~?=Czln<z^F1={X+^<*g{z>s;aq#1>4_R>(*0s
z798cz1m#DY#6YFE3%v8R%U7k$EX~zRKlZxHetA}~#g`zOa;~X16_Ft8CiIouL~0<)
z^O*AJ^06g)tJ~FKaXJg$nU7iM*k0&FQY!g>6;q}m7kc^Bt#IAb#jqr!_v2P&cD;)W
znOoKUBo(oWLP~yNWzDE|^kqMB7Wn6flputbaSV5%+Dlu>kKg8_oo?NFsd(VeUU9>i
zt2A1}diJF(Df(^xtZ%+Ug1yJ^cEoLup-h<qiz9um>y<177Yt&rq)Xk-p^#;WslK%$
zELy-gr+qBO(~)7oA5C3Wln_>`6@er!4RG((6R~-&m|Od7y%9DH5B**#Pbfc;sklsj
zNN1A=t21eHqs9(5;z|oBX%Qx5zY8nej7mNhm=~YAAHkuk^iY<|a9@9-+^a$neAz<O
z#c?O{9qatO)t4_EFWz~&QN@{e!?8pd2Q(=nq)0p#wckF^iw?<grPueReqQ+5y7w+|
zR6kcwfj9fpMBVxXb*Wx=m{OC3$d9SPxS~}^=((Y{HuAl83eAdMo}hZKRivX~g+3iS
zYxrn^HN?j}s_446qu*_fhBxVJJ+&7!n1oqNT15qiB^9t{&xWP@hbxJ=*d{w}mt6O<
zH;=k7S-?K<@-};Xk;SK@>(=9vuL?x2-+cBe;^5}-`6;T1Q((5ypGm+FR2H>7D}BX_
zgW5kgT$yn_Ci|?3J}YD{rBYEKVx_^5F>uS~I;5&Y`8-PeoiDtK4dQ2t>S?`m(`t=<
z`T6iG7{x%Ymi^^@gPtuncRI6*N?RH?PfCGNZ2`SX-&u6*O*9SWc3RQNnTz19sa}i`
zKgOt3z&&Tm>xTi8Hl5|2mp7^9*Sh^)G7`YcP(`<l<1$S24?attO!Weq?4G@rIpC`z
zU<z+FzSh0UtmoQ{u@{gEkE3F~kaT7hS9z3m-k6L@o9&y}iit_?FH|lS6Q@o~dr|+x
zO0%eLKY8zVOTskUL&MPlaqju^LZ(BGLx3_Y5w2If4orEWL!;kCAak`U{k+d<apT$u
zKQGjzVdi!|groZq*Ij_>BfhY7&Sn<DtIkxWU@uHR*qn7yBA0y?F6Pxc$)&ey_#I*&
zBR4zHVp02?P6wb#u25!huHQp<%vNTa$t{(e2tbF2B(ImO&IhNx^k-a;7-uM5I|Z(U
z@HD<%Btz;!HeLv?sz1GwhkGFQ9IibRer%Ep@wqj5EVuY}XRYaWg}H@H5<BCQ+8-89
zABy!my7%6}U-A*TD_c|(+^X|<K>#np31w%3oti+E@Wn4%I*5<O&t-q~+-20p?W#B6
z+z9FH`P}V3CSan}7?)4;WZx9&Yp0cG>?`0MBV&-{^O&ME+rum+fYieU*4;vn<_QF8
zmti!!8*lf7Ba|psKRM6dp18XG>GOe;Nc8-?S$3R^VK1LH)wsIA!^)U}wo%d#3qQw~
zLQULrwUBD1YfHHo68PS>U&!WkpNQDMAVSn>f?I3FImODX?YDQ2%3^>RnU$D#SN)&e
z#BEK8I&9MlOp$P&`*x4VCL34d*-)^7^|Cqud5}fnt$CBAtSAcPI%L8{ukJZlLZPx>
zglmYDPk~p@<1n3nCAg!xB?3Tw#4@gjb2@rkfnKN^UNd18yhRkF=zbMv`Aqr3w<oYZ
zRA6uSHoBg4^o)r9=wDXVA%M{>ZSJn^ygkv;x$=-iG(Ag-FzReRC*80Xve4P=*S_(W
zm4zN(_+W$$O5)jHM;@P#$32B!essOjS0o}otWxrNF)61PqIm$ftSOxFi)!hW6&-(P
z^<PH@@JA~kD{p4yF!DTC%!#)-GSTnIkI;PSp8j4#^I`Dakx7$x1}fYf!nja2Nl?0m
zq~Y*n>b(|kxwn2bP6=l~KW})ITW$d8G8h-%G}*aK^abf|#WVGg-v*E|={H*`yw#n^
zr@T&qj82*_mXC<ti$LB33_E;(S=9tiQ_`ZRfb$yWR=n1a%1g<PeVd~X6b>T<aO+hJ
zkhKEcMLxXub~QmX^NW@tY4dO1is1SA;iY?7<aHK)5V)&}{>4{6j71Za9q!|HeaB7p
zgJ1JM=G(uCqyJnnubAleL=X4nuc9&GeD5|VpY!_R7*=p&=d2yZ*EoWT2@l+Q;WzVu
zQFvdAkx{J7yv|p`CmKaxO3=$CpM%%i{t|NjZm+?aZx{Hl9)2ShXU*|Fp|>acuiX|<
zcMrO)B9AO$`hM#s=`*<wUF}bwb}e{P1Ffn*+lgGW<SgOwHAR2i-HC3YU4Mm~D>L<l
z$)z@4i9S)*O}X)Ot2y(FLX}_c>m&{u1%>O;azfwdBHll>_`YEBUh?0*7sdJNJ+yRl
z|LNTN;l|TXiyu&-2EBu2W)7m$3h0JMU&a(Shp#xWA(F97)H$bsstfpNA9o~6XN^{u
zD81Xd(hWX7!?1fp?)ac+A7<66{0(J~Q7hiGnypLvcJ^Zo^kJ|3fCJlFrn?I6+sid&
zX0~8){;VsHt85Z0H^0dDT>0AkHA1;01joT(#91IC&#g|_NE*y%cW(Rp2(IJ(T&?&!
z5Bl<(xsZ|XE5qL^KSNV`<Q!VuV|L^^xHNghE9}#&OjmloboyM|XprAbcZk?e6FDs8
zz(S316ycjsjn19|%1$Q>Gj1dAK|KFX2(yL-%H2&xlE%OaZzBrPy5_RJWW7#~A;}R=
z_m=kLTP!4IfGDT_xod8@#f7imLTabjor=5;jH4f5)l4lx<_USaGT*brzD<u<moE4h
z^*kCfE9#P7`EZadMVPNn|MJdwlw>b|{Ucvu(o_x{D_z=Q@P)19(sIs{|2``#uoT?a
z#xMT~{mSAKX1}Yx_+F4uX3saxmr>;6JMYQAbDnKuknKvmu^D5nA&{VJi*NkI#WP#*
zZ@Bp<@BhqV0}Lm=JWuCU=O_3I9k>TzcMl)NTg0RXj@*cG9`d-n*6Mj~C?Jjs<p1?t
zaH`5M38b%`bA{LV@1*gn5X3jFjwA{}-)UT;)-&hU+;R^Lpw<FK5nc+yck2z2jIx)*
zhgd=dRpon&^rLa)!_q49T&SmK>3>b$7a{!V&LezxI642p@c%V?HQ;jXS(;nuGt1re
zS<YIT8gJjGB4cK!%vn3wmW<=~wQe3bQF&@1FETvvsC_znd|~QSp3mgY(p}Do^)gRh
zs!cWy%Wk$igq#Tx9#2esQ0tVCV^If?D63!pmP6*X_DkAaOVbfUomV0{T^ZG0-y*8?
zTs3}dk`_J5toXFz!|vu}kf@7}mcYArZ(l5h!GoB5?L7$28JI3IL=mZQlmBgTJl8vm
z8WP-@&`I5z>)d#;fo$BOu;{L*ox?TWE1i2`NcvJ{im%e`tj`}XM097<oc(3|VU)n-
z4D+krR^XLKo%<%71e{JITprI($g1A##0H!KY;~sq$p<v4I>sKUq~HEX&E0GMT+L|J
z{pzIQ(E$mG3X0wp8&k8C`xb*o@<lbZj`uCX5mH(#{l!H8^hDWM#fss<9Wl~)C&Cvv
zFrLP!`nUCulUH=6T?O7W9dR97dl!tn6d~@Gb|8NGiC!!HVzpKT!8SX->`v2>akH=L
zq^t;TsLns|cGxP9zd`l&%DU+1GMEmkDr~n|)M`d1gZ&h^IS!I+G=c;h)CK0(jk8!z
z+Kzh#`|%=pHo2~weyi{tYM`d|RN;}sgQ;LY;{ee$9%hVAmp?IDs0z-*yk^2K9JV8x
zXJ6)IqDwjA;JKWiE9d8XKS*UvhcjH@k~U*}W8)Q3BFoLcKb1XoLAX7i7ef`y1k`R`
zou-VoMS!30&@f{>uT2OhoC3y*4iQ!26(G5@o8>nHNs1~o-MCJYvKW&Y>Yih>F6N#W
ze<nH%De7q9M`^T{KrFf&WpSvtNj-0nlRY!GRAqW*+EAC+<YxJ31Fx<Nh=um8pkR<=
zL3Em&F)z>MEIio7;MeB9vHI~?uJQwXu9dmF;7e;rxojj4&Af{a_XF46itEEiH(yWK
zC4;Q2%$$<<r8EeJjNeG{FO$*-fYh)|_e*dIO^4=a*B#4bJpsR5=H|vJR=T#F=zqQ2
zLv!d`Cvj<J^r}LY4-PxX;?4Y|c%brMa&}1nukrG~)2%B}d!{g2sj#Hj@yWIQ#)qMo
z!$}%SQpGmCn%SB(OFMHNtIC{BYAimk)$bqXqs@A~{oK!#KkQyf6Nz6k$6i3yw=Txg
zyJXU$jbB}kMS!WDeV!=S6zZV{1v5@wR8XPGH|;aWzlsgEP`+3Ae)0RF<9Ao#%z4v-
zM>MbUepy0M;@17E>Phr-F)m2pE1`0Kjj(2Z!=2}FlRP!IaB~0!p(lrLac}H?39+g?
z{&ct1g*#kte-|rcugqlTx$;QLa_Jz9@s2C+VvL6-*CibL<e!f0JN5Ad0Fhr;g1f(A
zw=mdWRTXdCS~wt~dbO7<>I#c_!{sbyLE%0^qeKS=dhy*tqm<7W4&DI9^7B{27Osw|
z@UV4C-Or*O%#!<R*+mi0c>Q+pb;(Z7m{09XwA^@a%|kl$Xv~lFwg}d#G1AHG$=w5$
z-_iCd`1sjU{!GY?8G7AI=^j6%Kwqn)@Qe`15D2IIF?syQ;ITTO^V1;A-@rKx5cp~I
z#JV4qSJ}EV4$CaEmcU0#BYkr$s1n-6D()eZ{ylynXY$bPey_EA)c&dn(f$#ZY~)A}
z*6|wisrZ--EuOQ4kwZGXkfEv7sh`uqq!w7T?&&8tJqyLse-L{p!&V<G_PxRt?sxY`
zPE}D0jsfDZ>2w5v96HwQWyPdz1@C;SM>>4;erjSqoqKlS19o(jv$$tLgn4*(?s(I&
zakvEj!9g2M9s1P0VB-mM(cSXZ!;HKGpC^w?3cjd6En2Y94qpCjZq<IaOCq>lYpS~2
zza1)tYx~4N1xLNM7}v2fC|DOAGAm433GLS9#zsTA#?9J@!ps~S_zT9%ywA|=KD0Vc
zs{S}<dac!IVlja)nj$<wAkD^M^;0`kxV`l{)Fet_*dckzSI@Rh{+qZH$Sy<C8<IzA
zb0*n-Du?W<VTR>>qo|Ve9=%B!H(t)9H&=KqZ*$A9fYiFI$utArM76S|ePzVFA_d7v
zRvTr2l1i&$x_b;?<mTyx$WiLC5BvzZQ_}5W^s<HZqyc1e3XsQc%AzlSRe%oak{Z;Y
zp64#b(;V}&dsikG_fTuCn1|ka5g5R3C>5u@3KcBenBD*O)VmNO&gJoAdIou%3}d?p
z5`5qdriXQ$_gvhhmmpndIkbQA+R_qpk8;k9K`ctKtTJI<AgXVM`A4ZXOFuW?^cF}L
zan`5nN#GY4;;e(w^wulE25aYrnuX69y=Q7<JJaJ6C#P^x12flSO+3kCjM9$;=`5ZY
zn(Edz#)im#&{u6v``D;8Jz?eKV_c*2U|b^xrL{@<=DeMtx=Xjh5GFDl5)96gyX>8D
z-?yNk$u_3PxT}MCwWK5eF6$<1x4L5tmU{r1V5cCi&tV}t@S5%E^mq~j<@IMp-tW`1
zmlllY*8K}sVH8lFGR!tysVWw#j|8(wgq{Kp5@A?5lx6_-5>#>GKKg#F3%uFd^q3(R
z6WQTUJGBK>MLrd>OYCY99c$w8M38UYAD4OMDm3|N)=IxnEkisIWqT7H+6iMZ#}IY4
z2qwUSZECHn5Gh%UJ=LfzcvZALO8EK1tz)rbM{AZzO4IJrwI8y}G4IMC55IGixor4R
zVsO-j$`9!;527WakDb5~EIr$p)@}yK*u#6xHY|fx>*J6dH{NjGpiS@n_pYXvoy1O5
zMv>JQ-T5?PigPpytI_%hw=nM{H1m5jP0wLZ)1mrS=$!dv)9p%Y=TMc&?6>ukUQ$n$
zwm(<K!d!iQ-24j4gL>9E%2JAgu4Uea5%1BA+Jss&;b;z3#wW?3yNKA(7Gl(V4ua$)
z=OR=!8zb6b<mAtZZr<u>X3#{l1T8kAV4)7R7IQCO8NXG`c$wJii+JUCE?@Ub<SWy2
z-((i3p{!_@Xe`CX8wf`yH(!&JveL(m5?d698Ac6-?0F&=;!lgovzaKb0)b2GhU0w@
zHWZMcPqyrpF?)wWg5Bi}!bdt9LF?dwKG1DMq^TE&iw(WY^fZ=f@}YMul`2Vfu^LUN
ztjnhdMNLyOta)#5jqP&0+u2lhdG$rf^}9n-$AGrIPhDW%nrv(&j0vh*ZVCyt!XzU%
zZLP=4-F7}m;I_vGLHWf*ccRYXeC?)jPv_0IlLC!3wNnqo#V_v4i!H~9U7bZBM7uMD
zU&xcrWf3X&Bfc=;4hvY0br#(M&Be12tr6UuD3X`94k$_kOscndbs@&11AWYaV@iZH
z+U>P4p}r*5*vb}6Erbidub$o&)3Z{6IqG=y%P7a9b@WG}VyIq3Z-*{_=REB==xh;o
zR?+9#!(B~OVRG@hKaQ#wetfCSxn_gt_B-5Nz_rb&g9KLzHMC$Smtm(Gy`%d=-78=I
zZE!~xJ&sjKKXdyHN<ZfKE}TQjLnhX&4mA@l8%@1%%XDfS+|XG#Z=vZm)_bv9Q($0=
z(@39Qx>u$Yj!8t*Hbi{H?DssFzY?X6d<<jQcsMT=eJ!E{5#loLjVhBFXq_$Ga{eG4
zb@2@ea3XY)2W3HdYN9lIZ79~}>BehMbl@3Vp>UKXmJxFXcZCFnvp)?TCSpdbo?8x6
z=I!U_hI9pY&t4izI&5kDI$=6l$vf@kpnf@yM*buUdOI8A08j4T0JA(-CPgoF(LA%E
zYI1ATS~P`TLK9uZRKedjt5({Pek;rUV*Sab;!#SH>;!pKC|`@vw7<x)4w@(Q0q7ip
zCd~Ts4Cs8pNs7}v`_!>f#k%>~us4x?Z<rf(mv^QmE20!a`VG%8yEDgpycRX!3z4n3
zKX<)#w4%;cZ$WM9VY!62E<5E>ac#x*eI1K}3GuC+)nyBv!3qVpD&r0Wf=#g2Vld|+
zIx;*sz`uB%n>lgO=G#6xZ}0JYKeHw?S5%ETrU-rE>$p}W?^7ESOwD2}1%|zY{Ixi*
z4wz)s!OTzFUw8h38L~e<Q%~O#1I{bz9+|yj)PQj*R7V}@pTvC!Ilw7bk40U0o^8se
zVi_Rp77}z2e|NjaTZ&zchZ_x&HXo%I>I=B5JYrY6efhAyHkj>R#ftB(CC-_b(Dw_9
zF_j%N*U{>@ftawm$iW4ArzG&*Bj${%FP7HY%GGxrPLd0sCXE;*e4Sr7QtTawR_=FO
z-k^!JVIsw8FAkH81|Y@@dhf;-QKRVOu#iCNc;5$mCQoje%TH=#rnyd~CzxBBioLB%
zo7Lt`5Q@;eO0cgP+r$Ikv{@9Yc3E5q<)%Qj6fL?vZy`jJMnSJ2W1k&vJ;PpDH6d}O
zlhx;31+$7RC0|E>=DyH0c|UVTWx8^wT`15)xjnnP*vZZAM53F965|GcIkQQJYz<u?
zgPuX^)33p5^-@uLVCoI)Gc{<35Gc{2MJ&1aJJ+X05OG$G<U3d)H1!FStkbtl(YyDj
z6@BYkTFiL18*X9>(3eb56;*+CHaO#$Y+|{WG-igmehPFeepv|F%&C@o#d>$lp(RmI
z>mrp@U6klUzBl$?9>mjYCu?JB(E6%qk}5<q142JmCW{dgKvxBc)JH#VcB*tqRlqgn
zdrHn8TCdwlQWx&|4rrC}F?ksS%*qm<zI;5^M%&{^x}B@Ix`gYh=&P*I(S9ERZnmVu
zp6T84&F&4QF6N1oyv^z9sB4cUtu!47HHqo?4(co>Whqb054UekNj%&Y(>G|$+`l>L
zO_^FHQC0P@z^U@#miTvToyfAX@Qme5gfF*Q!Q%u?hkLr$0g>E@|IpWgS}*K}L6h1J
zZnk}=w`f}DkAZ7*e~`)oU6Wb@a(O&-kiY1-U1ocXP2=eyG79kqFFOm+{(YvgpmZD$
zRm=HjP5@Bx^8~H2?H{*4;BJ_Zb&=PWCWMZ>zgQ~&vX`Qg(I2q;;aet!Z?*vV<#c5p
z-pM9>LrU3{vW!1nJ)-&Z93dW_4bfUG0P8C#c<N1aqG&xc$MdG3Cz2(i4kJM&T4A{+
zd6sc7V2jvDN2r47-Q8d*RfqGp_|)9ab^^BAT9{Yx!{?|N+|{k5H;;yfe5WMzFLqTQ
zYqu@BTjgHq*${Zpw>q%8+HJ+9Wp8iKTXr5OBP8Rc^$;Q2(cepcJC=uW@+8R~gE?8Q
zKXDwjeZUsIBxlgP6i;ock!CVy=p?mVk|gpmG>I3cSUR=5yO$$3D@!?8wzgO5yPwQp
z`Jq~a3EH2r;2gu`bB7uzttB{&UgQ$)0@H!iQ9K=)7f}n{ThG9(UR%$VImVP}kL@rH
zC9^JAidK}wp6n!+eY(jg_o~?gFL>@3T~`F<0u3f}UOWH&J4Ng(m-Cq-hp<n1aN*!x
zB?dS+0Lu&Ufg5Kl3p-lNPY)^DbY%GS%wI+e1q;ldo2Y0~Er#CBM4aV-cdmM_@gH57
z=-3xB<&PM)(i>OOF|*1_tLI@+zOZJ^lHAU2)78qoHh(s4{_D66g(>E}O&w}`);jgW
zX6o2tt1ifFf#X$3b1gGs9$oPGU5v3pNi9uOD@&7bt}48W5^9JEhquzqewLl8jLe3N
zbeStByFA)f>Pnb1b2^M}Zho)h$^Ut9sVB%HaW9<c22lV_oiaNH3?B(=;W@r?k}nG;
z$LQHmAJby|&_taJ%uq4q@VhQ>9BhE#4yVAj!Ekn$%i%Q1WzO^9#NJF!_MV)lX9t`U
zG54`os$_@W?TL}Xx7sq~+QF0{iE;=`d%9ft9P~_RFE>9sOPd58<~>4bE4;3P$Y5&M
zjTU2zXo;3;80ANW)G<m)gkG$jC|qmwe%_N@X7)ksn@8t?tP4V)&U7`cD5Sh@(|M#b
zZD|izDh0Zf+E}cnbq}X)if6c&IvMCCDLy-dMva^4`VfzszrWNrRxQ+c7L17PY8LL8
zu_hUBIR}~3MOp3mNLfR!cXlf-7lnMk+bmu8?UG}hjb@SdnQdKBo2%13qCFln=S2Y(
z(qimD%b9VIC%UQwcQo*#pQ|bm%D|n2mOxPFc#^+;{Tc-e*tD>j<S-0Z)0*|q@piS%
zwLH)k$njROjh>_MpGJoy<F+lDec{^-TJNYQlMM47mV+HrWa+etlw(&44HFs{L{)Y1
zgnMG<+Gp=q<zsqP#)PeiZZx!_^`EP}o3J0Ry7+ZsXDQR{+`ER@9}_w=yI<(VjL))|
zPt}Hbf01@&u?W?fbi2qm?d1}l{WeQ`%C<I5VA89<Qp~j|t>c@ni@-GMI{H#Khv+wu
zCW1@!##F79g!Q!77Y>`J(z-s{ucsu+cRo1lGB0m=Imx<E`XcKlv$UHMbeg5A_)^Qo
z?R+<H7}h8NM;q<9D@nWx-(Vt(j<2G?$NXuyD}OfqP=4?)g>|qzp?IG{jLS{5a8&uR
zMLx#QG-+1B>xige-Z8-{L(%>XZrtxprQHH2^KiyY)K;BKR=`4iOX5?Meg_XlZ7T`n
z6+9~h1onl)NO;IU+c@o=0!-iXbU7?0S)3sqKRSkcbth-cQ*@t1m+3#+=eala?Ofz`
zYga3izc6NC+=7PXSQEVxQSNY=#06(xtzGP2@;?-C)D+6p&nD$~QbiZl=lD<GSpDEU
zGZRg&(U{)vV1wyIyL3NMTjdtU<e+J~%o&rW_YzhcSE7zJOV^CdXRYQIX4{oBo)(Wd
zfsAMBlYAZtjJ^#)43C@cHJ6h}(u~nWw6Kl(vsxWH;A*F=AZ`Nm*OpVDw&@h0&bl@Y
zC3QnA&_J$qFwdVIt!oz6A8X=pVtm}F+Z&0i6%A^v?#&a&Y2r?M9oEJz76uZEx)$nK
zf{$evC1QDKp<-|jrtw-)$`9OM&oW<WZP3hKaN%Yj^R95|9J5?bMU2WeYZ{E@YC0sb
zelupX%8&ktYSix@iI}CXtH2~)!=xflguAQ-+tJ+3MUc*}%TI<|`UFfD%qKT@$+o<;
z`L^vO`~75oT>WMj9*=ci{9ak<R{2oE?V)f}Q&Xl(+57h;`MBTQ@$PMWK_&v>Yqp%}
zyX=$Xgv-|2Y#E<Y!+Cki7%)B>?@sEQ{Lo<Qma!fEQ1BTn4~7S!5nbj|?M&K%Dz~9-
zV#zxes-t%@ZfKxnfW#V(%gT%G%;~(3Y#8(Aa1phLoc@tUxfNnfj?=}Jy<6z{8bmWG
zA~O<U`W?#%HJp(Vo++>0VmMaASi$>u^(o9YOy&h9c61-%CSGVk%JUrKZqGkNH`P21
zS=X@$=g*w~sy~bye=^5BM_AG5qUK8wPj!wM^iWlyP$r>Q_U__Y4&@ln4)&0|5{zDN
zS5m$HnT9ZnPC5310Y?+|S~(MT*SA3&PIPx--Nc*_u?(h8?yHZL`DPx}n$`{4FsSFv
zIv+l-Pi6_fc*oB|g0{D)^HEZGrP*x1U|nVT>&PPr7d!&af8UVc(BKrHB(VSoq?yDj
z^Bt3*Xr9SbQ0~>Clww-puKe)kq7W|{CWwm;3Kp$Vm$!h?F$l4s+_X@ypY&F`EOvi=
zUZ?(TLbpW0+tzWaDei(JB}Xs~RDBWl%-kg8m=wvwjLTH$5=>c#$-G!b<pX}qnZ;L5
zMX2Vwy^^AwnVms5j^^DHZ1y})>iwB>sGTP+k)wRiaR-sdx6vjDSWE?TXHP3#lQ&}H
zOws`S0aO?9!OyaWh22XoX^#bLKe_e&&XI1uVoVNKb8qs>wZ`XrGbBHj1{2+pZfsxH
zmAR(AA6p^(Dl9sf*^OVql?;(KQ}-vK5`~V2O|wF;;B%kEXIIo;k9|$h_9|1lY~k`$
z*^FC93+{7I1#BXKd5U`9y$`GLi8AT52BxXYj&x}NXHSgJqSpfHF+W0r^0On#`OWGK
zH}$l+Ct~pIC4;)O@r5q)f)^|d<;k<MOZ1j&`-z_+D<M0rAz56|D~p<Fn$B2UBZLM%
z(dq&tf{MB<5IT;)OX?&-GbP5F)cu4*b~gsE#MU_<hBu;4qF**d$X*HGbv*mIfdp|m
z;fGFEq<3sIjP+R6r*L5-iwP^>Jkuy%L{gV$xy~(z7Mq+^u5qE9n{%Eu`cNV@Q76xv
zpq115=7)G*j5d=!q2?Fdn4z0X>n9U-mc8kUlW?EX_R24gI8KsW)+ZCi<%;I1g8CZw
zqJssySGOB#o15x_4HB5&hs=LpXZ>pWUC;zLn(`{b6d<>#AaV$nZ!5U!`*|j1%}LJj
z`9+IX7KnaFGB<JK_&0Bh!MXETwhfbM|Erk7ZL_+%`XmWjE19&O=tl`Quexid?uI{g
z>BX_O1Q7?dZq&}o+~c)=(crx(jPK(8sU{{AOE(WmxtGLQOsI9D78)GXbQfW<@v1`3
zvRU`s-N~H{+nZi9VwDdH-^xiim85KJ>vzK#umYIxbGmQP4Y9{gh$AJ|8YklxA+&N`
z<=oovV0A%Fq)~IDj&GV|wanOsfqPmAaocDnlWrKJvLNL9p#DUY8=ADIMRH;%S=uSd
zS{SX-P-Sj<-5~Fhxy5?&jDe~`c$6~K`ON{x-G$`~*}w?{I%BWG6UDJNGw#+xj!}af
zCohgLKrf+sL$^Q@i=FT*k(<g3h~^hgc`i?aHuYJpP0c>8HKuJCkyjbiIeq6welu@=
zCIu}xveFe>>9*pzHQ7)V;a&9%cBT%-p(!FNV=dN<xeE`SO!AWdbfvA{Q}6OQCwm|7
z`JoTXhp|0Xk?gw_^~s3VuoeY$a%hgLk~mZXfn$mlnV`Ow*cUl7r)9LHmaM&T5ouuN
zajCA2>q$_T(RFnbtKHk4v(TYt>C)$h1mmvWJJ!Kn^2RtwoVFDqt6e8LSsSDEz?JFc
zxta-?k3wk(m!}fi)gf~?Cd8KCzD-)tudNT!{^}+Dnv_kQ@g~8ayhsPQubcu2(FmSG
z+%R9ElJXmi-)~QxKqE*n(Fo3D9`P5-W?bN}<VBfb1DCdDI31Yc@ZV}d_<@P#r&@rK
zfLh`dXm&aUptv-TyJSOs>m~Da-Q05F=lrhCS*Zj8BKe+2QkgGZ{`f@;#qjuNQUp}b
z$dGI#oIEc)E{Vu1X{ab?vjfl1d|!J#{cfA&TmFLIKxEODJjdhR{$am+%~^0pxkR0+
zJbhx**c)zN+P2=GEv8l*kcvX7t_brNKz8sR`ujPw_lUV8sCw4IyhfUCuB^1KRWB4l
zkyUIf0C)QyW!1rn{_z=}WB=IKR<MzE*dp$JNaSvrI$-}aXaftwkuwN1ad+(GePglN
zKFq>UfH5b|V=8R_i@i6EYARdXMX?1%hzNp$5ET^_AvQEhlc*?&5u>7@Af#+*B1T0d
zN=Q_M(8m@OgeXWSgeU}1nnVaqDIz@)5JD1_9@Z)$E=h=I)_2FZckQZE=Y02!JMKN_
zj{U<wF|4e$=A3W)yw5}Y1pp>lZ2-CfOnBXZe2!3|%u>!|Dsdj%19RO!n)CZ7agYuj
zp2AiJ0dfG)!MmOgM)f+_Ix`;p`&a+{hX1$TP2O37P?jVv;f}b1_Dx*EWLuz@_8#?9
zqB_Q?hLW`w%*CRi?9(kHRO=jk*6P%<t2vH&GTpA@LRatQX6Ns!xSX^OD?fh6#TN0b
z_5-m~Yo$=zijk9dfKs|UMGA3S3=Z6(#P2G8eYxpVe&#UQ)+|SB&*52&KO7^cKOCW{
z>oh?9qGK_R>ZUMilf1qQzLc{hE=9aBiD*7WDXa<M=~Hnn%9Wt?jL;gZtP`(v>1I6}
zlF4NHiki#y$Jmyh75)Jj{0r;WtA;{>2z`ulsIe|FRTU1+x>2-LS)YY`7#4W6^TRRu
z`|j>E8&T{wyX&X7<<W^G%o_E&d+(!nb-!Msg0lUa8w6o39Yqa-gC(kAJRJoFYN(6l
z8B@2nXEjre#W7wEPAwVjm<`-GLbb=U0)HFX(~Q9@Zu%I8g$t=#zo@-Ik{n>{%u8C5
zpS6dbImz$xl;NkJ&`)EuDeeLs+Rh*Yxmq5a=|7cqlj<PmFZRQ3fa;<W1#xLv(H6t_
z+*4=RAN_lm(X|E~4i*XRa2Y!&N%sQ>^scoR<)>RFCVJYw9XR{ycs$SNM#ke)zK5&D
zo8LW5I#4TFd#FD!*Gcp9^ZoM<<+a8VEqsOd$@-SZ?fezHZ;J!-(3&T=#Fj?TAD(!A
z653{e+-u3%t>u;&(x~Zys(1cHdv+hF-V4WkjX-N}?cI9q1Ny!a8$X7N!mf_R&rYTn
z(0t<B?p`*u<PH70^Sb6%6BCozj!k;JOVp0nfHJ2O$ds9N8l4SHdDXw9C$)VL5FcNK
zaW!bIa(u8D9gfp3KXdY@O6OU7rz-EcFe>u$54#G~{)i*-<NFF;g?FvHyXVaOy847|
z#^-D{YT{<oeYMwHE4FazM$|qZr&p!H#g`hi(BJ0O&TV~s`|1+a$Jh2B^w_o=+rar|
zAH3DXXKN<c@2&TA$v3COy_hSpMfrBWUcB{?+Up<i;k4cP+A-wAwi@S{@o^8j=rtet
za_t-o{DkfS)sbNsIk_j9b<5jopdj5S$@%k*8{PK5%hw@?h+NfagRHu7g@rc&lYDVm
z1}Q;&*N0csjIK}sg!7xk-`P5Uvz-wvJ6fJuGVj~yqE%qFxdVIY$eZEEzi4hs^}noF
zmMQS)e{WE5SBgD+v|Iim`AWatSWoxjiNs1`r?%`aQX&N<V~bYWe8mAMLljjs?_77a
z(iT#UDaZ6p&+S^0&l$ILp?mV1J8TV1J@Ho`&(JBcPBe0fi>qk(($3wiOi^3|jo)>Y
zadB`}99^O+AV+6Ogi+;Y8OKSbjn~s5jSpct!)`XA_dfY=LaaP-izs&k+&!YV;v~c;
zpFVas<SGUOLJi^K*0F-rHR0PFwR0A)Q<%D!6|>i*aXMVg<XhHBpo#t^`|}QGoj;OS
za>eCUW?FLR+h>y_je?aJ>gONqK%i7t0BCkR3+&$a+g|*zsmwn6zW3--(jg$ax9UxQ
zgG<GKEQ35S{-SppO-<Rf<}exYAu>N|{R&_i;k%{hz9g;0ebtWD$ogFm3bl0=Vl3ZY
za2*G}BUrTS6BxcO+5KS2L<?cn0?p2$?QiwJ34Q=4d;{~%Qg&NOp@U@sJgrv~{%ax3
z5FdKR_eD)v6PO~zx197-<y}%d<|d9izeb<cDU`yd`s<9vdT}rI9N7BduIARU8Iv>P
zDRc`uv|4%MkE=hyVpx>~Qk?dkEsfs13REsU6A#8Y4nPf?OSZk8eZg7fj#u3utlvB6
zEJK3UKxjfo7-V%j#Aa7oJPSjfP_mqOO+ocq7lX_iURJaeE%~LqSkJ9+NAS5bQM)<{
z1$H6n50)t3dC)7D@JYjsVJ{R%qX`Ujm!8oQX3Yz#c>w)5dg1BTj2HT`*L*;HsP-0m
zM@hh6IaF#(iFI5>E_h2fM67}&KF3{dUyxMR+cms6=JDRt4yz#<UhiLV<lW~dliYPV
zmF>Ca9*6Ju4ehsU<~LqMExEv-mpA*>J-hnfe7`<qgxB}lls<cTB>mT~Ic2u4&z`#m
z<q{I&79UE^J+utwe^&j&lm01G`od<nPqr65c)<OhSaMH5^7A7tNYrz8cVD!@O4iW<
z<<{GMdpD@Fu{v&5!R9p6Eh-^#fnui`%z~jyzPwck2?W(B(#8R6-uh%`p`C%m%)~WD
zpnoo~J{yV0t54hX4q6zfvGY$?bm*_h>Z&8#HeS@PSwXx!<?v4VFF{-L9|E=ty*<cP
z=`{UN6E{HhP4C8zNxF{TrQy`2EnMb;VUL6iiJ7iCduMF`ap%jzf}~;h7I8&Okmt4_
z4XkO*o-uC2&YrJ}I*&i2J(4zdcGvPXxCRZx8li52UdJ_*0KE_|o@g%joqCXm(=k&x
zVN;$BTOUH)Gz<hZ<7Pqx=S2Gid7=Nc%O!e7=k#ZnwiWB&^i-kt{NV=wC5|0PHA6zB
zB9*sU0zf`N;a9r)cQk}#?3Rc$NZ4ifTnl&J7@I&QV@$0oid|Qo$SPh`ow;jH<(bA6
z{|<5g_YLQTIiD2kkn}UpC}d(e5+EIRQLPP5(5Ht@ma$YR(Hh1z!BfwdT9lzRh7JwB
z^~vw`KbUI|3R0GB!bo+`XV<ll#`TTst#aM3)P?nT1V}8Ppz4OFLnIv|^E*Big_%V}
z+bVD4J7)P_7S^UYrQILu{dXN&tRnvVQ^9+JE&%OD4S>|`T>)n%hC)BcCdj=2@)M+_
zDiv1*dyhx3P!s&fqz5BPbRiV?rKdPNXV9jiq9TI7$!l{5$;EBlBN^W^qA}6y6a;;*
z>+seogunFPP!Rq40vzcDgUT(XP)8A2j32(Y>UK;BP78lJY4`iDN6*H*y$OH*w(^eE
zn4`+94}X7;#UmRmQvyAjs2FjIQGYddE$sNL%Zb4?#i!VO2z8X1s*ie)B(vRqtE%b}
z?r)x`Ah@@kH+fAo+21<$EW$Rb!_==7V@Smz;SlF|OF0fU7Hss@yQXB(b11-@x(F?%
z>AO0_Evs77I@oOUQDuF0w`gEI&yOBZ+%^%T){k#X-utSp@1_jzwRnB}<LBAVtzif6
zw@_c6?{FDO%^mk@@(KtILC;2}Y+r#|O2VcMivpByf23L;a&EfZA<tbgUuA3G<HxC6
zj#hjBc>B%ccb>Y_fU2$J^wmcnu1FuBx)S2<0Bb}mTwttm@K2T7JKo(#f5QwurjBLV
zPn|OSR&#Rc-=h29&y~pK9jxzTWaYNqE?;p9DDhhuNLUa4Kcz~sc$B5O%IOt6x6Y~B
z=IoUh=gy47kF{g_qywZH=|6j(!Xkwc_}MtR^3@=J%5YKz46GbUw%s<K<r#8u>Fs9)
zTN>?j6Pk9+CfL_BwD){^(RHlLbH}oKJzhO78bw^Kw|2kPEwa5nzwNLq!W7rU{IE{l
z#H)DZ)#55{T=2=?t+_zgH71345b8_8ukAD|aM8}uyu11KJ|gsx3WkB6-m4`d4udSk
zr=~g2*K-tW(DMO(_-Qy%xp2zor;4=&z3K$SQAQA!(#5Du`nSNnN`9cSR2lkEH~TsN
z&(~-M2sK6(e`=}SnV%}Ru#bMKG&JZ<%2|`bZzFGtb{_#B3dF?e1*w}s!wkLer^?r_
zOk^K+F`(OiE5#^QOf)Lb`|>%T038XRb@sn@L%XMG{nJ4T`9`yYN9f{>i2F|!2a{Mn
z#AwC+c%81)MupQSHd8=8r53v7r%G}XX81d9nA6{R!#_IrzjM3jzdRG2_!>|u(y{N=
z4<8}^<!=8wj}$XC-8eP;L-vbD+H>%n|N8!%{`!iE!ZEs#*jPBTeX;vr?-%#yXG;6`
z3jE7{`S%J0{{QC;%#x|PO{dX)Sn3GI8@mK%bE1vti)rt%YoU&0D$NE-l*l+FD685-
z^Qk0~w;TzR0P`79YQ@et);&}j%(%=_u}lb?PFfXh&}sI$mCZu$LAvF(icP`*OD}85
zW86YX2ku-5Kh9b`jbdCobxx@RITrp0wcYu$%}B1GYn3%`9Tf3WVrqDDd~d7wZ&pby
zmE0J%OPu7R68~p&_&+$#vnFIB$#(%tjS85rZd&5H)RnqlUuO-nioP}E)`-WWs_OQF
zw5|l&rdZt<Fu!WJrgv%Uq-nU&?nu9v|7J_BRhQ%IeE$OfMdpuGWnadK(aNm~%L<5J
zP1fmF5MH(CDd=)5ih5ti4Y@6kDLn#EcEpGY(JVh#Vtr6(7E{GZ%u*L2o`+#ZgeB-1
zzv>w0OnxI<-8prstE~i`B>J<d>xf7R5u+CFOGwp+_Z}Y#+~nzn_G*0wjXk~ACq7Y_
zgwLH`6!Lb*%&s@X>q0^|dE(W~$4}qvbyIyo`@mmT?kV4*xP%13{ck!-ucS+G4B=E^
zeq7$$P@_1BhF<lxxjACy!U2z**8ZD)4#64zt;aupu=~<F*==Zi#Hz%J;CU4rH(mBS
z5!gaL+1^$BxOWW_`cwgs00K2CKJXdEWIG(6A?1%^79p8t`tRh`Hs7PhL2LNc<lI(^
zQC&Q4frkf$u*c>IKeF7(=xHDuA9%{1QJI$)`|Hq=`w!0ia^%7NzT8=WlKH0EY^^Y7
zqHVNzKf3m!=B((K+X8G}%RCtg+H)S-JZQ^qO3Ht1AM2lI>6oyFUzp<-J9J2PR~8uF
zqjX(bxy+0y$t#Jwc-3Y7CztytOm5bH+jgWnr%AAX>%&)}-j?aNa@Xd08+RUI@67PP
zcF^8k_!?XdjgP*S6KIWCbD_cvVoK&R#3^%|J{A?FKJDYHlUi3)v<6rjqzSKmU<KLc
zB_;+hGM8MLtF=NcS~Z)6m}V(-RIhOq=Ja{L<SwF%k0|WkEPtZH8reT@!5%PgXWB=O
z#Qo-KN0@BEO&YZfFaCp&1?SSyYue`zW$Zr`QleHo?djA~ufcfyILq<=v&l>MS9XVX
z`%Y_<|KlfSt2out=V`y5t6Ifp+!Ci8X8o9XS>-NJy%^mOW`%$wtlW+p;8H+~K*LAS
zs66D}fA}9d9SMo;7r<Ns7)hOh{>^0QA#q9-R3C1Nl}<y9N*1z#IePUebtiPb1dgfo
zHi7|;jud)KueMjKm8#m;i1MF`54*62TbAh5HZg3rSt2^xn*JcjW&JubJC97x>nmtG
zgI7;x5L+7K`H%-FYq*K#TQ(vGE>QSKkk@SALQl#G>Jc%?-gY~5o)cW4m4l>=SzZ;l
zeQsHP*Hi9dyUQhz&^A6gI)Wjao%{OgRm_i|R=V^ZS`OMd>8Eoy{Zl=Kw5{(#>-{q$
zZC7dU&6d=Ab~&5T+yZ=iVzUy(K5Oxv*}sK8^w^ZNUzUU?9y!|)S9EFu1T&RhVDH+t
z)5U=Ze$LT*058iCf1NQ$W%f^%lNa`!+&&&Q=s^FEFD;*m-Gb~%`E?_9vBJ(|!O*jx
zD!*z!nGLkk2>yzZe@eIfK`hN9)ExyH)$8beT0d2ciO)~a2aK3Xb;b{L8Xx+OL)NNJ
z>oV2A#B?5V6;x{W`u|_Qv?01qio11V{j)HLBko&%d){pN$qPIB;%oVK{(lr#V?GCf
zoc<b&VkYi0`Y?d?G})sSdZ^#9{d}YnR+l!63TtrD*Lqly<$;o8T9zr^g1xO=yk}AK
ziI^R&yFAX`n^P3dzmqYT;5PP4_=1*Qt@zSohRIWwt)LoM-W9~E^bA;`oKGUd1;VO}
zzERK3`I$_{Z<Kfqi=!q{-J9s-jAXBs!zl5~(_@>vw!@lDmZua|R8UjAg9AG+zl))K
zY)&fYJe0)G6{l{F_tacbuPj@Z$sPXX{>3G+o3lobtoDfIaokwkr^gPYJ$HRDK9c@U
z%2ry(0&)cai!i?L5M96-Rr^edF8U1-ERL>PPwP2wG+KL#?T;0rB9ET4$=w^wf5|Xr
zR5T3ZW==BIe2Gi32E(j{K`gBSBUFom_{<->Tv%=z`g~BiqJ?dipFkf~*KlwEkkQF>
z&rcf;^?3O@$*-7NzPjg#>pIyc9Jult9`8HdfnGpGVX9Gcj#ZinI9=W1@fh%2GkuAM
zla2EbBVuf+<_%PsB`H}HolwfGCN6afe15FAf%D0)sr)vPKwr(fL-sctD?-29%1)D;
zb)<*VPdyv7!XB+?n_L>}20L%O^Q8FZlDnjyoyyM+TRaE50@ytxcLWy$KbvK++pCw7
zC5_=wnUhI$x$^~gG{3cc>4J{@tBna=%&3Xvf^?NIv-_+1$70=u=R%vOj?+vO1_jM4
z5O*;@?touluk!6Ry{bLRE!_xFVwIRa&}-Gg!vQ}`kF>)C`jNzwa4E&MX3Frh4W86t
zWK@1<WQ^OI=PRq3tXL^%vfClwuh44=3efyf9vT84McjU>$aIr{k_&bj9FU(by@H@{
z)vmC~p>XQKEI+cW+NStkh%av?uPF3v!2ZQoIZ1{`D}Su`uY~F?|41DGsDBx4IR#6&
z<*KlIi8Kbn<JC#RIxmtWg&)mwgi}+{5maj&<2*NN11AISxRW+CPeRlu4(TQp^D_nx
z3|-S@VHjq7$;F_H>$Ty4e`hY=0{;i0&c8F4|44QJKg=Ef9XJ0U7&p)5+$ukqPf@Ss
z=^!`6cTR(uiX!#;<PeuVJsMk%yll5fp4N722|~YoyG){<Yq-;S^y@*)$4R`4jiUQg
z=<S`;jkSb0-bUnG9>v`iwq|gNa|cs3i#i-1h}kG2AGSH}-!;(sOL<3-%O$x3^lRze
zmU<VGi+)%4jso2SB>k#hLiSs;yoA)F?|ywBpK;9D&27%HWBcd70J0r`V0Fh5iwE3`
zi_;x18(ZZZ_CFL3M#4H|Uy1WeT}%R87e5$pM=w)2+|ibhqXebvfEU~$*yxQDqg&@*
zHI9W@9@T#*RM+vn8vSEks>#$KdWz{66#Y+uBsb%K3YVp2q+MV6N3n^&(H-~~R!pbA
z6X)4J`)^qxjXI%=Gmlfk=6pEOik*m`1_@=R>|9X)l1AFi^8J6y3~683*LU%vL}MgQ
zp0dT@KqfXs(Z3lRaw>D%aH@)Z#|x#g2%kYQa4h8B-NUL$`cPnbW%r8n797pYFssCq
zKHcATO|hqYCciukWm~b*dOpN9b(V)b(0!d|9ZR*=W2B`nu?#gmRN7%@b3UttTTpiI
zP!YGNV<I^@Hz6KiM3IRKqfqm)kjQ|QuU@3S`{F4-WLjZ2>+9Yr?Kk`x$+g8S6>~;(
zL^42Jwn`(|(CHP;8vTlu{rk!gFVM@Ix0F0eB91=ADK@aS$d{YnJ*lkep3X9n#Sf#^
z0pQJbcj?`_qpjqL+>hRSzHr+D%s1qpx@)rO9aE$F;;-yw(FZG!=g!QU?cT&!!+`)=
zM`6@VwNE>W=!uze=@7Y^fOvST@nKmMXDEpoR!%fajXOaPPIE~^(gm=A%ieCml*93l
zLl^uvc8flG_)q=vqQi_mE>V#YBG83s!IE-k`DTK&(Wr+KKQ48z{?f#(swb!od4v`<
zMp&R?JvaiQ79p21R#zi)x7p|MAV1DbnK*qft0AYTy2OJTm$f>j_$3`WQ?(&jJ8i*w
zm-TDkZas2k{$^(rl^J)P?HfXBn4<>LP+T>Awt}FUD0b%~s62lU(XEvUb#7Kk4|;Q8
z?PJKJi|8n0mrL6?X06^r^U)P9=AlNrTZ~IeuAVM;#(aUCm({PjyK%;|D_3SMpE+{$
z#@+p!DQ`^-8&oz&uYEG}fAt>^OnTi6rfMSA@VJCnJFY<ue5LPnQ?X9IO4*FoUJhSn
z*67uV`y;99ed6bXXf1bva#8z)mut;$luhN+mvE~1Kubo{=OV8)V;{ul4`bdO8D-6;
z*-`j?tG`!+TBzzE&!8<6$$<zG<{SD#PSm+c+h6k(D`1kKg+i*nmJnO&{W9I2AGIOx
zwBKcXeSh2KdeVzk{N~BEfiqO5w?HC=_PETwDS)=szxQ`N0g{wF6E~tN=6CD$q2m?C
z&>=4qcjbo;>^47^nqmhgu3RHW;a(gssP5H*&prz6y9^!oUem!PF8oL-mDaMLMBiW|
z&61`dWr+l*(5B05<R+2SKrz3IF98_VaM67FDFBTiNPntSS9n&l3c1P+9hP1Wvg^%u
z+F6J{alt?-v6f>;LN5$zT;#w$PH_wQIDuh&?`kNC_za)tq#yI9q}7YjbCo?JEju$k
z2Didp+*pM(q!1jZ?**YgHo8K=(Gw!0nslT@42Btk-4T(jfhMmKEiAW`;EDR3l<$Xc
zj@5ZX#bx5MJsU0utZy4ct!*<8Lggw!PF9Jh8lM2P^p_xVE#?M&PWeSCID4HXvMbY%
zsY^45l*^Eei%+P&kbC9$GQ_dor5Gt$69+rEgl&gS1pJ68i|@QSaH60Fp@X_~72#Co
zkjH}$x!HqV2d>Zhg6q<j?Sz<b@FM;0<FqDkG;9$}MA2p`yr+{SOmTnw<v4f1V}1($
zfG!bm2Hl80?dNFvLp;@%lH(MXpx3%%<*V1co5Rk4lHD_V#=Vj8NLJx^B`Sii^HU{&
z1PlVB*PvaoSiV46?X8aNem-<<eIqtm!s@n_pcz<@3%-I=Uk3z-;8G-p#!?iMXM#NM
zP>bmt%!LYS$%Ty8XzK<W6NQcn!jN{{fjy<<H-s>6GpL;z#Xn0JVJ<+30{zT5pg1Zf
zkG$m!dL)EFS$zwpSO9U1Rz=9Q`fDDb!|i<Sjs!?O*+i$L;OMdX19$QLzl|@Yb?6yc
zAZWPz%~V1-U9Se$<tobsiKQ<mrWae>PE9d5-pti7s4Jw<E42o8T0MM*wF9VOv~Eui
z;Yt(t_JCI2X2O|%#~D+L;X38K968pH&!yKIV%(7NGxGIRjPR!liA|OrpMI#&#iA)9
zsr~mzs?(DJBeixgpM>1=XtxV^He|E}2@;oqX&|-cF~ynSJc{UO;$a~sJyg>+V3G3}
z_AE?LXb+3OSF+~S_{sOv+Lij?rt7PTPzCD^QQfJEvxG8S^}U!s3+xSm(7!4bMO|~u
z%Ic-86iG~~=@H5;05NmJbNBBp?Bb&z{klFpmCbISlakj2w$~A?xd_bI(`?}WN>nF6
ztASxqx-SlFeKkMYRw$U6)q>Sh1l-%zRBj(CAuvXtD)u)`*2fvRw*nCs_YS+I(jIcH
zQitD0HG492$qygocR~1ApI*63xoQ}z5wjCm1G+328J33X65<Xa22#D6aYnFmCES10
zK&pH#!RS(Vc?K90V5>N&tX2yXXGfH93@BJs6i!p&NABZjBMjHFrjsQFR!KomREq||
zY|uW-SJU?c=>BYsM6cTGTK7(<u9A#K>Z+8+(~o#-6q}I~IRkVZMX0!O?hsZVxd@AD
zJ!<2~ut{~V22tBDQMn>nK$}+rWlYBSYg2Hw-ph3lx&%#PsxgQOYJ?#XEiMs+nn<1z
z3-#iufFNPcs_6py8BAD03*sQb)S8l)0TiE*w%C_H*KTp%r(Q(aftm|u9XzrkGa%Vh
z>Faw$*exqtvAub92Rlfvv3dMplTsT-DRiU~W~6c%C9Kk&K9@ElD_U^|V)TI%qpvuv
ztVgnfU}JAc^$pv#(uQ-LJG_>|GyR0jsxn*Mc%AEPcMKIq)p#=KZCd)x(#&a}eg^MR
zNEXz)8kqH43SZbA%$i5AbS+T}s2ds8M0MObOcbuTk&%}-L0nvy)=NEtq)X8esaCKm
zV=~!KLAn@v5t?c|0&?=<Q1srHZQOCK?!oU#@7;N(ZRY1UoS*1Jksxb@_R8++Qau4s
zMoE@VGsAEsVjN#xxk^Dqw#cn<Rnx(skLw~vGrk+yl)T`=xLQx5mWMAE1zT6oK~6~P
zIdlCk0P~-8uDHuBar$+>ZwVHR=rPj~C*{1WP`xAMGZF_oNgC@!Mkq~XvmRhKsLc&I
z)7RL^sZ|;y=epc$MZlh%^itS0(R~AqYXXt==os($J7!YkRXht&=Uc<jNfIC@$7_>1
zqDW6jbUR-(<cf*Crpn+(3dLD(dR!%mVRj}k0hFVv8oSgFL;RR8NF4+YklwiBSPmt<
zs#mj(U4E4$HZ2QSBds$sjd_#AiY-S=*yKuG>?&d2WtY8cEmy8+028i#X+WJuVFDc@
zhS4>6T8i1o5v!NzHxn?Yn#=&peD;o{(dZMc(a5BU>H~Fq!Fmky^1y8B>X=$H2~%^h
ziyucNJylq>*ttk^`r@cNa*mt!#x$WEVV{vZ@=b%HlDRn$zKW<v^^|~epC1c4fSOPH
zut=fLMS>-{xL7@r+E_U;D1*8SCNL(uRRN$W2#4&nv^C{0uFa04gE)*FXO69tJ_6I$
zW%z_9=`<St{=5G>37gcSIzx7ay}@bN8H@Qkv{rNx<|cMIZsZ=!k)Z2v5mSv-n9lFw
zXoWivdMdvv<r`91HNmMfr_=55Sx8{DzJ@S@YddN_CUtyW0o&IxEJDvVTa;mbb@7oY
zU@(uRH^##v)_rwvFkl8|$rv!GJt$cUInsMR^qo0I-HnRp$_)?NIf-*g90M@>99;?3
zOXl*~{@&&=^X4L4ffwmsjpl=(X9HKRT(dLW$A?@|F+3xd_&9wwR#!1^I@t~fairnn
zqe}zC=rEc-%%vH@^qNqDpufs}iWSo;L04lU^`G$!>1tjikh(zb3`>G0#iJ3BRJBh;
zPSnnQ7qT3cPt&G-5ET$cP5W>W{Gt@r$P`PBW<a%U$DJFdGtny4#W16;E0qPGa+!XJ
z^I_}B;-CdIEf`m=;a+283$+6!pb>=wsSgzutbhLXg}5_WxM;g=s$r8F+kbc{Ri_`)
zPqU&$n!IJS&aA$JQ1A^daNT5CGg1VUdQL)sydbI&(W?cGi8G?5K!=MQ4!~*rNa{hh
z;t2Hpmfb0nTCn~@siq~ZiencqX3(pa=5`H~blmRovcqYCes-lZcEg}@8)7VBMSySe
zeHz1fix90)c#A7EUP)*0W_Ezu?Lp+ZTzWR?GAi~Gbyu_9DJfcy!T{K{T~OkKzR;Z?
zq%~F@N;DLZ%1T4b>?}Gi_B_IgzYv#P1{yXBn-0(_>F%T7r0FTPAf7O~uQpC@IRKhy
z;dO69$>PRZgOr`$CHV}gnO?P#eMfnK#96s~NH5`9Vw5F`X(-6SXZso%mcDr1DssNQ
z5S0z00ZZivq84@=tx{w(qSO;Wjj|ww1G!4RkFJ()R~T|(RJ2`?n7-g6t<HNTQozy;
zxLiR1Xq>uOHg=ifa1r8~0m_lVkwK$@2V06TdPCRdup-Y_TWNJ6_WdKXGEx9*NH?2$
zG+HPNWy&m}y3q(~u$alX%f8QB2Xo@tO5HBydyk;lRI~Dy38F!_;*8NsBvA7u_I2)#
z%)ws6#2R;=5#`}PRKt)6IuIIIeNDACm&9VwbfLLVCHzkE_UYS7HH0W$Tv5lsE>Y+q
zyKy!4v%tQq-)cc#<ZomK6C#TmBd>Iwt;ib2uI`|^1DcziKUHdbjrnbpwvk4)?^<iY
z(FnlBx$|FscqB&=0-vD6z*M0zytDOSeEktd-RvLw&tNL<b-SeF-tIDlOqRq2y2I1F
z@Idj~pta=z+4x+IbKP|TCsb5(X+6F3r&A{A3zWYSwfH`$TV0&W@%dCAWS#`AOENMN
zmWN6(k)^V%Jc_3@tA-ga>s>7@syKi81;b0o#m(~bNGQyrxH>`O;dw=-$=R3VjMOh5
zTdkPj{DLsy!WyEsLL0Ju17JF0xjniMC7AXR*M;R@4smf59cts+2TH8tuqIwTND`^X
z{XkK9`zc|0P;QrJV@Bsdhu<?#zvADH)`w_xJiS_l1Xcp?f8-6rvDGI@XU^E<y8GRJ
z`T?b-&l0bt=4|vdHSq0`GT*13*-Thv^<qPbYvt_g=pB`GtJh+(8YOznc}=^enfX}b
zvDXjwR*a>m`InTQbANv&JJmBz-`;psc&pw__B<*4OIwRK;X=Cy`+ae-o4$EiR>SHK
z$>N4B^35GXN2>`T8-&8r;tblUP6MaKz3d#K^BJ9Y=L5K+7oDG+HxxG*AAW+0r>%HG
zj^dfD0yx>*+kcz}=iw23pS{+7A5s3+52g$MRvNQbRK2ku)GuV4*Mj<mQ}0f2RI6~A
zfp=D3jQ=?NA;b+xQU1T6kg3B(+VjM#ex3IXJ5rD>abLFn)j?#&y|-WU>i$ks+4FA&
zF#O;Dtu)F1X*$HJZL9@tm@sbB=IzM`f9FYPGyf+~!srF!g6}9*zp_ZPe*bOjGj@O#
z4F9lEebX{J_tI5qMlg3qKYht~22raMIlpa{*A_vNRdm4UyN7_Y`70xXq(2QG%I(Jo
z(l3}9m)j;u@vYqK<_2~}fz#)p300<IT{cn?pddVTFi+1t>ZfZH9LbHG`If#qKm2qO
zErmVk7CEP8^qIb4%7gru<e6SxNAXz=d3!~jCHYCj8}&Lb_CSp~w;K!=-(7bw{jQba
zk>)pNPJG%p``Q6Ox>bz|W6c_&Vx9m}l!}OO_NPJgOJ*d`mIO2+eQr=)GbqV!?Up%q
zTg;jH(`EaR3UgLK{(1tf)a_>1{-<J=YMoBAH-~B97VU*{Iu4>rS|`#d@nI%b3IS5W
z{l*g{E)BS;{V8IQRahfMi&I~k+yG=cW<JMY9yh5P(<hqU<&9*y#1piLL;9oAhM?!6
z_Z+Qk=5*J=uCx~Hwo{vI+{1BnIkubD&=_M#WX|$1ORIa%Q4sdqxmA5I`(9_W!)#5@
zyh~-aA>-ZZHQp=REgJy2h&oS0v5O1xrBkpTzKQAy;<&|xG{mz;#?x;qUl$ybUXy{e
z;`#iRqETZ37ERCs|96cMWw$A}@!7F@tGhSOIB&Q0!pO{CB;z68oqXzXh64~w^D>Zn
zi5OS|&JB*Gq2(m!hSC`BxWVzA;>Sth#YMbFbBh4P%W|SrH_IrDcDhXN6*n55=6TF}
z=+hU@NKD{!>Wp@trEjkZeCA7SSf3{WJyZ;!VyX&Hv53JrVI4VYVLFcT#Vs!1aW(50
zl3bItyJEy6<4bCsI3{H#<q0orA8aP~SbF*!dzS10EM!=c!>={OGy7^^BMwg$jv#Z3
zcoJZw?5Y~8mt0Agx)8hr-0JpqSjf-ZeMdL+hX*bUM5TQ^>gnls8-M0X@i#zJ`g)qJ
z@Cxq3i{>`;p(6_XlM*YZQGH;ruzH>uHNYhHG!h`rY#}<dn602ML#qxZTGj1tRSE$;
z&i*c!W9(m8uK3*S_hU0gdRI=zV6`Zo$KmsLa+R&Zb$Zunt0_QOGS)mmInQ4R3Rz`!
zT0LHrJ$_b#x+qQdvt)bYYK|m%kj(9zFy){=dHT6wP2%M)rKPMlB4|Hr86_vk)QeD^
z)WOQBhfO3n&=OWZ4lWrST^`sckMj{1b1sT296aFu7*LYjLtBQpyTO*_N!Y~aUV}+r
zdd(&^_I`IMYQ6kpjP#YcnAQRkS6UXVex!}dnOAucHkI(hXd8!Le*8ED@9>k5XLTX@
zt<Eo7+@xNw?`q8did*9ElHKi%r)Te#$>w&ua*vMb4nKc2&88CaKKXz5wm{B6bcxP)
z+(Oz4>OSZl(kS2=w~ds~li;Gd?zER5Aw3zqKq+n9*HLb5mF9kc3-vPt?9OCXX7ASc
ze5Y~6YrXA8>V3?)jZ#!3AS?^DZ*I;nKPa`IRaxl$mLw}~@#&bXcUgqb*$`fnQ);!@
zYpHjem*<aK<Atwcf*<m|-^%q7q8l8aEXK^BUSQU0WGX_Sk~gTRl1qxMZQP~Q#T=w+
z-1B8~xpTVbaY~Y`yB51N;d_;GO>2W-$XmZc+0@Fuv!ScbwWLk&y%J4zoK7j<1nAjp
z5abAKy+=sh1X79_q*6xoS)?Y7)U^-ugc9S}Hd*0_o8zf4XwDyd`ntG~XLZenQZO%|
z*VowQLFKJSWn_I?r$;MwS7J3^lR5)xtV;4?)IH>F!<#2Rr6j2Hqm0%;W9hl*dHy`C
zJUE7v72Vq_I0AsbAdKyYiepQQ%h*Gkj@4WZT#)d@kS-v6^x22Job$D)j}z6q8CDJJ
zhb6xQnxZXG*HcY}0prwzei?&_U7&8442r4ed8$Z2=JDYq`xKzvh|gsc4?7nb2*m1Y
z69JA}E8HvTh5c3bfajyIPB1)by;G>%Ky^VnVS}nvn^L&sMmavjC#y$ce$S<O670C6
z{<Nh?r8u}48e=@~+55|@f&zV3ytmA@zMD1QbI^EC8`yZEFrdY#G+GMg;%UpM8<D5t
zGK@a18i(?uFR}=r9|#lBFt1*`Y_&8U)`iBS%D1e^${=0w*dL==CZ=m+%fxYqeM<w6
z56)>3=buMBWe;J|Eix9>JD6l0W<<D|Y6kbmmYeEy*-uxbjAg-^0p_9p!ea$3MR8U_
z`T7QK@|otm%WE&Mei`*8{PQd3+oRiU)W<vddkYW^y-`iR_J({rt*e=X`g2px=rP)m
zXsI-`H=UBiuL?=oWaqGQu-F65u;?DwFNw#P><PkX);}{qYZhmLQNxc^4$)CWYfatO
zMq5g+N`Bo$)uAoj-Pd3&&=0=lzOTcPm5wl+I`WHP*nRJ#^6f$yU&qqk;b8kcPa#&g
zhWUK(T2TihQ2e!dMJrd1ew?k67QJ>>Iuy(h)})$4CE>(FF^&YlLE!+&N!o)+V?~<x
zOFv|hvaB+!;=}=%<FFNbapY_3Lw>1-%|UTjrdL{(IwofOFY4|B%BE5dVoZA~W(SKG
z`Jwfc#yk4Pqiq<Y>z<^Lq^ct&644DKKnlR={N6{7qHXo-if2OgwW-)wux42wF{;!(
zf_yney~ZY^F5J@I==AGXZPay^?dg7pXgd|_kvkGX7)u9hpzwk&z5p5a2Dtwg)|hg1
zC?Qk6&&U{ZinREtqV3B#Sg_~~d4pqCrl&#KLAx~}^vx?aoDpya0Hy|VBgfj%Be6!L
zR29TfZmqCpzQO4$jTNEgEnKfzl9H%Va78fxjJ^?sV&E3j#b>;zPQN=FS7KB78L^q?
zf#x->6Y}Xr<BlyJ^@OG(dmD|-zgEwPfl8F~#Ay^kAE%1dWl{$QrrEqDVE&3&$%z-~
z)7A{viQ}^*qXhBSJ5ZSP$_+?c(7OccxN}0%uo)LgGXwP*x-N3wUcXj;5SkNlFCZ}I
z?Zq6T`GeALqx@(hw4WZ9sMLr7Mz?S!1zqdGio=~of1FhVEY$-^gRz8`nE$)KAKfB9
z=}%W(4)d5N=&+;Q5y1ybLXD(?1f#8h=0nVkOmd7l;gjv>t^1<c(vM?@4~Cb4_i~sJ
z*{FK6+|);IPpj{;u4JlG*C1Jt4f%SP`z;=*QdO0}L;)d2xd|Gt#_9N_u6*52+c4B?
z7eg$7$HTcqeM(@h_cEBpP#k=QBnU@GbG&L+C2-KO{J!UWE;`C+P_d<tb(21?0}V<G
zg^5)}wHm0qs@I$wCKg5T&yeE|QG<{j!D2PLW72WG?Lifo8vdEqA`)MFw*+rb6v%X&
z8nT@7oI}_>*Ii(|a$dhUW~)V*+>+MZ6+F5$yIa|&)SZr3(4Tz*+NLz!UW%t=oEcxF
zdOgT&#+brMYD!;1-3sqd7vq);y74w7kQWRs6b*DlQmrknl^^P!)`J7V5&~8k5!Wp)
zhxVSfzNuUtvIT{?qO4kCr**A^QVT%10HW%RJx+EOvP$IiQumj&pQoNYjW7aW+rIDN
zc4WBXI8&{gSCNh|1%dv&i#E@Ub_2od^%3k-uv4YCB`7@j;BKU9LUj??EtGoMGZ+(&
z)$lc1-E<mBmJ^%-VJ6Q2IR@+1bY(Hi{ouL%E-f@8N?i>ax;w~2K_m*fs#rZ6NeD5V
zGilp{C86&s=PElzOX)tMTOuyGl0UN~!n}Nwd_MvRps+T4*y=%O9ul@a+Hgw^&9JSA
zIYXr3(bBpdR*h5`OIdmp>uQ^fURJI%U0iW(tl7Av6z^GoK?6{7xQcNCjEZ9Rbd+5{
zpN7p~5IN?j$^xDx5>v}t!%I9;QUN~@-Qt5*ANU+)w~p;ixiU@^a+&I0fPh6E2_d{{
zR@hoxQ8&wN47AG1t`C0Rdref!>;!cU^es?}OXttS&P3={MDWQx1>reO;5OACjw>m5
z36c%aHc^cbb)e8ZI9(RPK91b&RxUCNsZCwO@A1j=<lULhka^AHmf6~4dxdY={Bx~=
z5JsH%2B3W2iweor)40Cxw-iBusgS>r>PLdRx+Uge85DUP)(nZt*<0eRhK%=#RK1CQ
zfX+K1Cn&8Uq^~UUmz(Npmg=F-Cts8DTWjgifw)t3Abd`&4kgOGrxTYWb$#8e8$u6a
ztrw1ffTxZ(N$i_#G^^EasZ6fU?3zC;R^(=b5WY7`Ok5O0pVc*8;`q9Kb*m<m-AKwi
zra~(P(}<@0vs?Ln*{yy;-m(NTVp52NIKp!hVo*`o6`%aZr5qjV;V_x~3q;GhI>ze?
zX0bq0fs^GX9(<joCGjiTQ*N48Q8C&a?QFuSW0PcSg+ajF_zR7Ig!db=2BPON{e%Mu
zI!RTDA}+crh8g3b5s?AEBZf^`l(6O&p$z%8^F}So9<hr&W0FT_jID;KC@DTU6Z(cN
z2&n`m^IxWO=0;^uF0z$|JVrXLn<Ni9HdyBjUwT7ZUMG!VMO{>29@j`CKePJI5f@@O
zic{!YDUDI?)q3~*iBNLrQ?p)FBS!~m^?-@-fN*Nj7fDO`ZV5pbFf6CKXyuRm(i+4*
zb@Y{Rb?Ay`rLTE~(I2M1BollpQpb9XBa7M!S3J6oJ8kC-<;vE=!diY;namhMkJRTV
zw!%QHYnHNQAr&+ItRLaS+Fn3kn72~-R=F6aN7?PjRh)*D{2We|{gz6R?n;E5*ZpaS
zxN#1$i=x?ow1Ba{^i`6Z={wLEsNBr=;cFnqHOh@JYqT!gHyEwPTS)srG{A19gzTSw
z7&HoonksoZ)0xyw;xf^!LGMMS3`tE&BGc}Ok3^)8Y;kDMGfAwvW?`fcFEcW;nIeAl
z=PfLRH~=qD>4G(<j0;#g#>891LS`6tgW?jjfu*6eqBZx<L4w)7M17hG#r4q5ccNO|
zsrEMBW*!onHiTQ0R&)ou+P`-JLKi1D>N*9j-`^p)_qo@6x|p{fX>>roJn>IOBcWs;
z`F5)Dbh2^*@(!<IT7B{OAWv^P@hL)5y^c|A{%&Mi8r?{2Zx#D68e`3ijs~UJ9w0TG
z9w>EZ)YL?_UdPIkmGiV9c_nWpd^QS5lh+kPb5dBNSH<K`v{=RlY1;MDI;M7=$9Oe4
z!W-y0L;bZj;c1G!P(5Pn)TY=ZP2M5NwaqCC6Wb0ukOQ(Qw~yxvzKV4CeaWn)XCcCf
z5E23t!cj%ONxgd6a-RYILZ=&=Iq6`)TCs&cIuBJ9fOmt@k>#QA5(?g{l{-ARya-CC
z5Gz@loPY^ZH3K*otMnAN?mF69dL>?IOFdTcf)Ar_DHk1c$x^nWHF5sg?x4SQD!_oc
z6Cpxbl{nQ24gG_m(gx?`%EVNC$mmXJp5L#7`Nv5mHV+ySBe~O9lGo<OU+I4IZUYH<
z^k62%b}thCl%nla0y)L=eKC<Xc*J@iJeOrzTPWY7I9!30Ns|M17xA@`@YSsroJGWj
zQ{p`V>D;oHO&z8IC%=2~-P%6Q8YcqJP>EBl$fZ|q{k?Ebujb8eQ`pNdQB{GZfEfpa
zj8?RngC<?22-v$yQDGZPPl@gsbn9JN3h5M5JVa8r9N5w_&J_O&-aW~`#o53P%9-%}
zT7WH*9|nK1iKnT+A!PY#%B;%7%@m9@l<@}DO$4z<kx5+d_hayTqYcPQxdn9|5&(-1
zA;G888zkKX4GK+IHN}ZkI6!wS=^7vXws_Q&tT=$;u6imn$+%R}G5wfN#>I*Xrc0^}
zaExo#f_gbQjHQP)r4pN;z*iXg{xYRWn{tc797?Q0Ekp3N#R)W%7PcjQwl~GLQg*Ow
zFkz#gK36|ZnRRu|>kC=?!}gC_(2;e)qjRz-xnlQNOD}D4aBL7ET)A~R*Dfd+%;|4o
z4_$MwQD=2;USdYuI)K)>oNagH%o#St$DJGhwcELMVhMFiVAh(aK^uhMg_}MSPR|%b
z7cv#v778j5CMRn1YkC6rg-M7b-Ef#J@?I5o4q_Vw<0UaQ5KDHmLpdAYM`U1U6arXz
z#Ce{{@DyLR9p;XbvXM)nCeGHfgMLZnrPScy9wigVvcr%lrW~DtptmD&eIfQ+96{I6
zk1zvx=qT8|3Kxf+4KpLa0?Y<2j2UoAEl~KQ-=H3osH^uFbqkUfC|7nu^#>8ZOiHRq
zvYK1EkFLWhw`Y4E7l>_G3Z1~CLQeS{QoiyXy1;V$I(8{_V;SPwM~Fz^X&_n8{EW0(
z&SO_Q!-qsQMmlh2G8}=5@zy~YB#HC*FR$Rl2<3`FccpR5q>DFNuTEk*x_|t@y<jg;
z=P3ZmfH4w>svh;+iEInbN5%KrB7@n3z{9m;%C~Ud!p40*w{T~FssMUQ;e;8!#=5vG
ztE$1N?|axes@dw;YD$+|TTtl9@j7>#_8Ru|ZPmAEv{GN8jfB$s<jfmH?kYOE+*HCs
z_4o&Ww@DP31&cwecX8gwVe6^GQ>Yj_<7^UbW3yBqRKYHO`E*EMFRrLLG_z-{?Ht$d
z?vi|EDCZh74A<64?d!spH!0^+b$`bM%^1*2(gbcYEY(1`;gDj;qxUIi$fhx-oG7Jh
zQ>36OUG!)?NVT{ixyEQy+sI|ZHC;kHG{$<?9h&F$gUGN$OE8O%t6dJTy83jx_xPbl
zF2#2;yK|pA2j>jkn^W+zIIefA;_X-0RlhlqX4VJUE!;C>Vwv7IQmQV*h|K?dH^B8!
z%h<?d@}tAKy+bx@azip}sCE8PUjUbC3$}-{uR!FVlkM&0vikFPjU&%L)sxPgNE@)B
zwg5Z3tQA*ic0MC^*Y|>k&=8>a@zwqg_oCNO*Mo_KgZnbScDu+mQmXIPpKGz)tAg}P
z^g;VoatY7;F&mZOMEH?7A^1-k-Isq$qZ^=b(4?(FSf^Gpk^7;a%^DTPQ$E`knJgKN
zFYhlpsb!slZZx94zCg{awRX7elycX(R?~4KW!vmOXkhPN!ctz_4dn5FyJI$QSAF;o
zk%)r=W3`hrm#S&iZeFkzxAybd0~fBvUJu=FX~I%f$YPXA6Qu1zgIdJ$GqGCBehFK7
zQ|*A-^2aw(2e;4uUm=<@GFjFX@$k_pm0#7~$Nc)+$)(GF+pPBMnA(tOH&$~G6JX}z
znUR;@kN)zpUL@UWvb3_UsY$i8{r~pVYjisUHk$G>ebZ%`^6c&|fCvh@lUuM({bB|s
z$YLqCOdBgoGHEA|jdL~#M*X<cx?`8mMl?uO##SJ#Cj(k_S)3Z&Vv7s5CY|M`nL{OA
z0foDamY)o8KMH+Xq%vdAS8l}7E|d3{EPNjE#aDdM6Ryg2bn!M-Fcv!rkA~iXoMgu!
zVU0+gqJF52x6!GOxtQt-kH^!NQB(!iMzh*1r*Q{B#e`}v4hS;0<Y;{yma)@(yKbef
z<+hArRyJGW8?Zz8rB7Rf@SZV0F5gz8|LJEY=v5<4xPdIiA&`<?LMh3^$LOaU=MNo3
zPSpTBQIjPq4B+6#BLPHdhji3k{6!WeL1})ZZiKB;#AYFcus0VG){y}JZ>}8*2Qi+k
zA+7H6ADZQ@dcbQ%o{v)=ARkSPVC%WT#p!VPNkr=uB&^~uI!9am5t(&>4;y6xvTv{F
zi0U3F8@Xx{dG4;T<{(8N;H_z$#Gi#@yS(BeV%Fr97FD}%6yU#t0Qom%z9LWO&u{Cm
zkI@}O{&-K&YX+wlq|WG|?xPt}Fk-^Ux13%QUsJi1(k<affk6{iwD;`74$tZ&+>Kh!
znb3@ZuFBTQ#>FH8J>O48TY9tKrFq1nGaoauL9a$>t8CQe&%)|^`Av<oD}>cvvt)7b
zxS+?Ox}!v&Yc<6W<Bmtr)u}`=8RJy;S~p>)nCcmrdsn741Y12jhsp1c|DYzpl0hXG
zGc^9LQcq#tFiROt2SYI?%fYC!l8JaFsZQ&FUNRBc54sHv)6|gNXlsO?I2ruq7rDAp
z@9d4AD!XxD080Bd{Ttos&llj?r!kWixcaHG-(G}*yjZ<(`%jfL7K{f8(XY54{PaIx
zfoRn1)SyIvnfCf|6bp(0;hj(D%>*O^jJ$qED@4tIy#$BpoBof5K%e;Y{u%hoHH3BC
zgWu?kA9Qz`8|uaXeC4EFYk%+s3Vtr%RP`efDziXMtpn&!KJ+*YOjl3g{<MR^LD8X#
z#7bhj=t0;B<}Ys${g*2svgm)Vf$ZOlpkn=(<MTVRiogn|%|t|U60Lzg54&~%2i>RI
zgW#veOjQ6Xd*5Z5g=uusfH0Nbb&g+DZks)5^M#T8lHPK;Veg00P4d@56I>y#P*1UF
zTt<SOMqk2Thb7jGei%0r@EkFyR9a2n<Cbw2QTnUc@LWQdXJuDo%}<pu8%HL`uWOVM
zP2I^_fL(%MB#(_u<xY|D>DZTjd&VqZ<v%S;UH6Y|PTK@5*T34Z|IQx#l*oq&d{Ev)
z*7Y^U)3tb8kPz7wB(#qJOr|HomWKRPQBf>{S=FH-wfc2+qF9_E&#=>b$i}e{eqog*
z^~ESu)8l*&Hk(sdhz%N64sFRq@PdFR`+Jv95o92-yLpnj0b<mKV8V!o+;J7fIVh7M
zze@2GugQ_PtQ1Ou!|c2Owlt!5!*q;tow5nL&}vG_fF1S$p%+GxDIPPARLYOoP`)Wh
zl1$dgDI!KC_8PW|_O%oK^FY&f{TB|~2<i<6S%Vt+h8{JOpJ;$d&i86@g#oPapcQgG
z?zR5-iIgo8a}Io}uQ3)VwK8wn^u|avRF5{3sr&evv>6I}AtCxnDZio>Q@$hgZ0X(O
zb|>dy7q`&+9)3e&WZQ&%e<q5GN0^~O0B|$qUdz$;?c$7pB&w3779Sock)u(h-i444
zNF$aFV+{cJH`M{+F=@P&6|I0wD~3PUpMJW{Vp_c}={~57z5Iu1Nc!{1{>!c$7V!Z4
zW~G%6;taCMn^RytEeCOWL71+3iS-SIwcL<G7W8Ta0Mw-r`c|XVhaOA|t2x?E)-gre
zQ2g+2m>*BIg}9ViMCMUgH$yT^)*<K=cg+pcWIvx4%klI|E9@MF&2$#OkJUxKq105k
zG%05z^)jF+J%X1z9Hs6kMiRy2$T9T7aun<-&^Lb#<M8m@*Uvrt-Fl6HzR3)UA^s>3
z&=Z6-psPA=BMx4yDvit@k54~L{?pFlR?+`t!~XiD69SpR^j+Lp&SDBf+#jK|R9Kb3
z;aQ_7`8CA>#1qULqK0f3F&3Wn<QuF)R3+Jnl3Pa*vlb8N_r^)o4-1tmsCy9CbbpUn
z8^NdJtXap8T2!YH=-G;y;LZJ_Y}}-55fv{J>2e?0oswI1BJPLKFGHO2DdWzq*p)*d
zxW_I)8fDpt1ABnCu_-7{7ofVK{ywyz=Q8qKJy+hdSzfKzLCRSzs9k>hANE@M{m&lh
zuP!aLP=fww(wE8U8)n9^v}s!@blEv17!t{R!L41T@T*;sS$)BAyjA|*n|{a5Vj@yk
zw|{QSYziXBU2?IG;illLBEHommbyI^k1rUOX%8j!GQ`9MqQNF4xEklIm;tU6KwSf=
z)`}P+Rk|N}0mW4EJ)F8t?oaDr&9@`xAXF+~fR3ex^wGmvFR@{;v~r6{l$||H*!vO?
z(a^14rc>^Us$|$@T-fN2WCs0A2#h-3gvqx^`lsvoVe(h+_*VxD2s+fk;bF~DXiL$^
z+KlhD73+s<`I^{e2u{KQKKhj5PEqx>$zqliz1U0H=xsO6#u_T{%1$WZ<<qx$xG?No
z3Lb#jYEyFZpZ3W|iIO7^;-8+$Zk+Qx>ustrc-E62!7JRAEPF);@3S$SYVu4m3n0^O
z3HfJGk*PDF803`HCvt+YU}%v-1O5)`?UZBKZ6rD>2&Fa9f8-`wgMzNIQRtZkKB0V-
zG&uxb_=iLN!v8Ng)G310U9m_|N7Muza_~eb+7iV+0M8`E5RJy{oM81n_Zu|yU>7ze
zKuYX%tQWi(?p-kbbW)@RO24v$6svKGma?_DiDz)!ue7iR9Z~Lbp?AwGpu^PY`kmfc
zubfvWrt2u{`Nf<YGz+S28`V-yMhxmw4IuiPwYZW=w!?v#nl4-=VVSa}R49n#;?$8;
z!c0=4NDI4!ih&)IpNafClDJ*8tn9(jQ$ge_X^Z~xh~I>N4vPK~R`ES1=*Vj8O4d@^
zul$!j5rE5Gfs(reOjY_7Ac0C-{Yc>|X+#{T))Hc8x`aQ91Ksu#kw!k%T`bZZoO+Fr
z(iNDtpsTx6SrT;(r|NHb^Nf&Fda~0ZEoB28+V__3OPr?!ll$nUjSOR?zi+&&t~NmI
zWh~|beV!pFxw$ujtpr04f~r9&6J=e)kHjrx)zn{oh8!a+bT2np@9x0hxRzH+7H;~7
zL4Eu`H>jh8xxk=q?StD`+Su6&TUaxUgJib;H}>8vs;R797Y0!f5u&sLLR3Ul#MsaX
z#>5^GF)9iQLP}9uF=ZhVAtWl&3sEVd1SKK@B0^L;g^&OVL`6i}Xb{p_BAr=FAuJ)p
ze|oWN@2_f~uj=eG{);olxxfn?Az4{-&H291`!tHD)3;RmgB(NlasZmwK|xadWtNkS
zc#*bHWk=bZ#mk)uC#Ie<Z#dVl*`cx=vT0Hoc2VX_Yen;h%&;Z^I_(XH2R(;q4yZ)V
zV^SkMg{D2;swHI+tJ=6ELzHDOxJ%#F<_A-4r>~RjF%}`c_V^j^DZ6`Cvpl4z5z*yn
zKu;UQ*@7}OgX@n2M&he4<_}L&pP??wPqn=M<KA8POSRc$)07>Qej?!|Uuv9R7OHDy
zZeh@r8hfw*sC%Z4@vVud$=u6=CyB?xe#&NfS9fsU*(0l&%Myg7Q1Bq#P--COp^eSN
z^6`NmIHP%^BOsU1f@pe_t?;jCO>C4@o&u&#zYFLCa8}xw-!b-F%04)=T<YiAWVR$Y
zn~+ch&$>~Rf(87VAl^iFW@-^RaeqaEmC47}HMqQ!Cjwm$JiJ$8JLBQQqFIL*&f79`
z-sVMD%yyU0QVIv+S&OB%&z9yK?5e1(-4yuo(8`IL^yCNqgO7=8g?G=NwhtboSNj{R
zsun&7HOcaHJHLs0DD(#$U~UB90Lo7JceO=vH<sf+5<541>)RVM*1T~bg}2V>w&|A>
zZCT5kkG*Kw_I&#Dnl<V#w60y)d8QiH+fD$SHoZ?pDr>E|4P@|b)ApEtNMGL^8#b>M
zb=&l7Kz;f?!f#J!RxF(napkI>76rX+^UNn}_fOr_k}q~%X4$!Ov-H3(1dXa)FEp0A
z{iny(!C(ISaORZ+9O~Ps$+VIH-<jhR^Qipt?0Y|9+ivdJjPB=nbl9Hhyy`r7t@TLy
z&OWElC!DY9t0&Um^VUQxH?40oU0`+V!yF;yvE8ke9XlUlUnNA&4D_~IbakgIes}r*
z0uNZO_P@OTpWUsD(9f<?zZhIUHfn!D&)Q}wwDH81tLrugCW6H7$70vzHm{D(@X=Ry
zZr-J(!A9lXJ(9OlEpr{^IYEDg*u&I@xmkUwLM@|7?Z006&(9kdTu9hD^URevJ=9BQ
z(_a@_<}X6;({&qY_^!6;E(n@WRyizOzjbkvX~0a^1&f~FxnwwFw#}lru6;kqXfJSj
zoo)y2wcb~jR$K$)XPw;IBU!mD1O8D<+qyCxNscXfqsPggUIupkeDIQ<gU;2TcW!Br
z4f~C%`BfzcT#EG?-e1vvw$DKlbK8GXB2MX#`fAyubMWFxHoGfu&2B}N*~!Yjse1-}
zv%PvchNQY%;Eb)6xNVe!Nb1i^cBCzP)V{hbe9nqfOHmKVweGd^m$~hTS-yESZ^`wD
z4>Tj6&r{82u5qgh((LR@P$-|nTh2#>6&_9_@oM(c?+<%Vc-LI6%5)q&Q|wnz5@sS;
z>#K|Q=rjwvKQ^^%53vJ1f&ppK{b6jEPL>mlSMZUXV|U2jhbkZUREXm7n&Yijyqb@X
zi~3xRx*vg&r4C_~pdC_`r5&FsYM75aBEEgUstRY<ar##yHKplap8fx>Ta7}iQD+^Y
zH4t#l%30kbOnbs*G>W=W^@eH*kuLvK-K}&DJAaR|4o0Wa6R|d>q2=V9y|AIr9y7fQ
zU;Ku(_IHDnw{S<@mBYt+$|C!mT1r7tHe0#3Yb>VER(d*3f;Oc@)PURz;zi=zQ*86l
z$<wJNNWf-+((NueHga?)$uw-6gqMryreI13a~HJh4@l<-r?0;sqAp(Rx8v;aAHDR#
zw!g2P!jDj2;%4OdAQ6&OQF_K(B(WJk3onUAvN6b^i7Xe_3rbLw%!%6vq*K+=x2S7<
zOJfdh@67QCwy#^^IpsojxDi1;0lhzm-7#f_SOOfsuv~&lk09s!&@MTlE1WKa;s;_+
zarY0?bkDZ#uultjs5{0YmT)C)3l0zcU~mbxlvlv3Z_>i@w){eI4HmK-6$AfK**c5<
zLA3x_H+m|r*$i}i{|bSUBpYUEgozB;`edsnfeXC>Z=}SPcP&D0UC*)QB-AjkjHlTi
zf)i5p9?$eQ?;amiI!NA)J&jzBbuAind9SU<h=QG(QMzQ`296;sR)U`uD$IQ*q3MCp
zfOb$R9_f&^kDKOqmgV+HZBrLi+8sIf&foRSNfMbfGy8UBh0Cp~=o8iSLg61U%LMZu
zT*Uvw5IBF^!~EY5<U}AL;vOUwHm^scvi6&8BM&$C8$qE%t)Zl>JtTwSDzimhKF^Q(
zm^Yjt#lNUDIaes&@gX%S>RalR6Go};s-O_(@5tj$MGqYS$cFAk+SIJ~N2^B)m^&iS
zqmJc1uKAy!cjznhnc$H)T|HzhtmbKT{lswV8nw%N0<oVJh}e}U{wQ|7a{snaWj8_K
zeQO(3OQC`Ka8whmGU1w-B(zdwb>XmNPl-*#AbVbz%S8NYB@J?tCel?#?s;UUv^6p9
zj-}ZfWw;cr`OcS2;$1}yjy#>BmPeh8kiew;)ddgUPt#S}s#anJW@HqO+LZxfOo2oQ
z=uAjy{cB+@I+MML+%v4W50jdK6qClYv_)cV>gDeMX=G6~^tl#dZo7Ea0@XasRN}ji
zhdE=nl!fB3ousod<~#qhr-GyYeiQunnCL!+aY(N7b#q&El27`x`}S8(oh2CCDKgHV
zS$%kwPeh++DB8gPrA2({rBK*kwEMf-iB541E89GTbBrVYl>@n<E-;||#J4e0+7;!Y
zADTo*L?9sv4VnPShQVX#wN5`STy`-GYLoa^7k$cI4mlQ`(YsMP=ormUa>yCaaAiZB
zq<fi26DH}z<4ZdB%7$q+O?(TzkR#4zukT=Ogo#Ix7-_gh6Cu*(64q1PW)k8JI2LK;
zyZogS^)+ctS?Ob%)mOG>O?YR|?Ke+X?JpYax9%=bzj;x1<$vWg=JgXN=O|Qt8M`BD
zX+~&vW>!?t!}l)>{3rIeJNWiF+J4-4kYLxGW_e99+;}o`>X66QFGC?1o2Q|rn}2vL
z9OoEN2uXe4)jrJor9eyBG8u&4SlmYajZc9OC+z&1kK1$e%kK+bIXefRN7prLs{ODB
zpZ(fVwfK25koHOX0A|g*Bl!)3hUkNF*lW$?w$kIKdEj-Y$n#%ne>G9dynJErnd|EH
z^0-gIGY9~)8@SB5g;qwVU=jR41#tpM1yj^A@5W7U$B)0nPpb$2178L;H?)YMs$r^<
z66%=Z2_+@$yV^J(u$$k=OL$hv?jEmh?NZ})qP_*p|B(2?dDGs#Yt~;-Q?$h;>B~UE
zc!b`~iF;9>CZ?Ur1DG3{W5x{CKUe;rxg+3wmTP>RCb)Im`xdW?OatA+?z;F7>AoI2
zJESi^IxmS>cprN2x-g~vdBH-XmycHdydwq!8X+O7nWm@JcqR`N2sNOraRxx4F~t>X
z=ss0>MAcVD=6gVyS;fL(&WWCfJ9=)+;>6ikKZ+x$Ue%_A$c56$LF?*tLC1*FS9;rJ
z_UI{!YnhKv6Mbcm=ulm{(C)$hJ?Dlu#LvlFKIhJ2?R{IXuN+X?<T?OvR*-;)ID))U
zS(o~NN_V<Yc?Q^|f#|d~!8mOJ)>c9QP#<*T^F^sH#=GV*T$F&b4R!G^mHL@Ck%E|q
z{m**|bCd54nHk9w$|z0`2BR{K1t48EK-V{X>M*%1cH5z94y47k*e2;IhNifpxu}N0
zvm8TTvL?6D-%wBhdtJzmZN4oX##k(Sc1#)rg!eYQEZq8<p3~zV5#HAopQZhSc6oy|
z2^MBf>r%m#q@fb@IhMe7wapCNXn_=^H1`K|h#@szH^7PjUY6qnhl^5iW)v&fB%Ts-
zN9ppWl9=%IQ|`(RmiY;)VF*2+Y~l@lMQF{@gcRk*2cLv~uL}wpBTPfz!K~<W%;Jy<
zpHo%8_;SO4XFDQoOtOq?Vu^YR4P3%HOTGb;4MTdn>b6*ps!lvrQA%ubK_w`iBkqRy
zL{@$sJm+uLIVREx$=_4%Zrl~m?LRtXR+VR6zjliBm+zd`cwR=FG*fN?sCSr1wP`cj
zw4E6E=ij>i<#p=tZ6ig{Uw-}P7yiFLx9R`7?@lTzA83{vsaiQ^fHDyUIWi=p-k^5S
z!FnE(%29*;t17yfET{9uA*!GZ&GMl9A&|>*=6HX=`N!|V%+8KpeDb?<8vsoK-%?!6
zsTkm5W>a70&g!^>#FmmH6x+IR)<Z;8IK@35xvL@>w!rAkfQMoyLDHg5%Iq9vJ{8EB
zJj!M`^CtANcWVZBEfU>AWR-Kw`tJ5Npne6TmVaHc|IHViFJ<<MWLl{zjZk8FbAg1D
z@Q7@C5LpkQ#No}w0pN`>hBkn%8AMD1u6a}&#AbhjLe}i$vKvVSxb@QEOzMi-SbY!2
z3D=5_@Uh!g+v+ZT-N#W3V-VY{(ZvC>afFV#M4esrlw(TKf_XkKBpge}8(_i-{372K
z9h|-~=7+84=pT@)=Jzrag>|nVKk$jIo!U(^U1}CzSbFmAs$9#gdi+1wQpV(Zw1)lo
z5QZM&t~d(qr`JdKCr()-zB1R#RCE*Q=T>GD3_>_&6rlHvpD<8vpVGQg@yVeNM9N%X
zxy48r@lj@bEYSqLkTYAtin-F+CphlCUuX?`an|oCD;Sc}3E;Fab+9KA^Dd{6_C&85
z_TAsfUflv~?L)N15qS(<WN(Kp>56f#CN$b{TVro{#9>HqX)K4M?-3FZRdQa?GtUpT
z1OPW*n>k|+NE~Rd1sr8G9U)-BVYrQ$gonbxXp4Ve;}bZdFFm8SuP4_wSg!72F9cAt
zH4VIAUN~+MwT*4rqtuorK>U%9Ad~lJ%F<5Od?;XVCxuqn2J}nDF1QQ{+OR=9?LWaY
zCcq~3Ds#A%moZG2YLClp5%6ZSmQCNs&MFXw_ycjh5|eb6l+Mtg1#@N-rZxi;T~}Ue
zo4S&KprpRwJwIhL<7~3{!ef9CR$5jZD<LMqqfcvLRQyMGU-Lc_&&u-d(r=i*T*hCn
z^unfHz+ggoOoBrH(7WP{$=h~5?&6%JX(@LDgqtkxAI_Z*qnk)+xlYJ!DHyHyuba|~
zD@G!YR)JJZY|Oo2ALAP~Nhdg+BNUUo)YjeKyn+kpTn3=93xl|9{pl>MVE|-Vou_(1
zHAdQjw*ed$9h6d-!4s028NiH063YWnCaytd=b{_64<U&$`u-r7-mf`BE3uQCeRQAC
z(9g&vQ%uLitABEg1<^UDQK{(pR6{adtf-dA6EoSSFdkG1@9>hQX~m6u$aURw7AVC=
zh>=3EfL;#0{wQy%7E+?iY75D=2N?W_*21GlhN7UuEs`npT;HZMVG(kdM5Pf!aixoG
zRmA(IG=cUzj3ITft87<ADmT}~&q}4wNCm-=iJX(7`ESjm5W2NoF)Ql=)+yj&a3)8H
z7CQE?$&~NobVu45@1o$f!1Md}JAvp0SQYE1^FOmpp!N09x2w6M-dm>`DlKIwh|QE&
zesUS{&gNXEIw>7!ag)tVnf6(^;oEJcNOc28Z*e=z77!&4C5Q-5+Q&qC!Ek7eKg;)!
zOOc<9gRI2!7|E8}aNA`i5ke_`>4_w!veDBFr5#+t&&m#J_JWB`0O)D$UjhXsVYTu^
zJG7cpX<!iK+GEmSM$M7k-Uw9S6a$iUcIBoZ&q_ZuF&ypHPI3QBVeyxZ;*JinQfu^g
zn4#c63Pv6!v;$`uTJ3L+q)HiPhz3vSc(LRYDC4-q*+|LW&XHw^f%vgj(uX&tZ0%su
zy$~OIymI5iPtl^}F}tlV`a7GK^m+no5L}qpdo&A<Qk;VX@k$5iBTA>2FF^}^CA3lZ
zf+1mAZtb#iOgbQ9lbZbvI<U^MxZ6^@b*~5N%~Xl9(sM0MLiF2!u5q%Z?O}&r9h<sJ
zR_|XPm;YvC=sgBDhH_QcBXS>m5&swvp6FwcFddGt&yqMd?CV>u)SVMghX^X8gN_CW
z+x;xEHVi7|UwU{}x2V}Td(Xaa{w^l_3hH0<fHUWwk02?WYDD(+oX)@pG$RCv23D>q
zcD)31c^-K70}!7czAUp^f|`$TkCY3>@u@-vkEn|b?-5WeLLPt=POUgrn54~^9O&nH
zq;s@#MTJgIxLMoFzuboZrUX>@d8_6;o7(HI+{r>11%slwto2f7_DZEDQc_fQ?GBRr
zrE?cU5se&@;o~glK}QKvk|`1gxJ%|zlsfq<&xMo@#00CmD6Ue`ycX;)P106JhfM9K
zYp2M4A^z*3s3fJq)C$#e%b8Gh0@fMc#&wZ5_E||1QygfTls%oQwOeLVod`+UZK=RH
zJXK09HbjL5Q*^@fmD}FjLBhj=bQ3RmyH+s{`nhNRlbe$?eHR}hGElv#0#XU=MyE?S
zOUiO21oCdoX2hwCDJu}~W706ZCPMHKuw3sWOkQ@<Q@AJvSTFPi@u<rMl`A4K^M|ts
zl9`_!%<tbhoBnQJJ~{D!pX}&1?)2w^vpb_WZ1Uri`H|s42fI2PMfyZhpC8|V!acjc
zZB?=<_vtqyav+-bi~50+l}{eEpS8e+tUfE!3t_y=tUl1ZB<5WpyRN&^_N(P{;fAvD
z@ZFQ{%L_dt!V9MpUQ69hR)v@q81B>JGv?7g6p|Uk_h>_#3VLj5OuFhBXz}tIe84gC
z#)&5~xPFxOd=ce|3+)xB(DFYLH<SKN;-(uLoCAWx_%TYPomZyy9OsPb6IM41Hw9j?
z)VX%c61DH=Ei*L^oL@1F0WN8b?`rA$W`#ScuzBCrsu+`wyUYLRI*UW#k|T|7R}DVK
zzB{>}SGM8M&-svsO$HcXSlc<RJF`f`U=RNHE3VhkOFxV|Z>WE*rZ!{ecQqn<`j;GV
zI$uiu&ktgnO!?G&q9NT=RdWh@Gq&-Imd&DtmfABfUON2i@{fe^tLcHijc2bRuip7H
zdDE7Lne%kjj@-WkOm0!rztF#{ZT7+bI-aHauGR()`;{Axd(Pc{b6vm{*uMUk{5yJT
zmKW5tHm}``KA;3$-?jhhcML`f+40c1Y|UK;q4@JR=`Qgve*Y~KpS)qAo^9P7JsSVV
zWY51!W%DL4Yk&7c`&5gKJfH3ACpgyyTc3E~_x6mHY@Z=jbm;26eknLyeQ|Z!L+j3u
zJ=Ua=UV#Uuk9Go&tU!+@PR$K%-vWh60}Ie`cUkL)L|V#7i?(F8Y3S)Mrl)Tx?P4Nk
z_FJ%6R})y>N;FMU8a;5_6<4%$5wD*VuFs!2S=y5ya(A#MtZ~AnZk*d-#FBs9^w79?
zMoVn${Z~KT7(Hd*5>`90%cf>tX=y<>&n!;1EIyQyfE2^V;_azs9>?zb9TgfLc)JUI
z5I&c6ZpohODT;j;{E~Jo{h)CJwi(4s`$&pHBz4N`9ht_hp{24HD|aGAu(6CAwav4O
z;#BCb^v>b6Jq&sC8?&Ny??-`0YLnCB!6$Vi2fk%0p7d#Vxz8;DSX)N3zXp&!R%}Gg
zR${vW_eH^N5_)qnNt69)4+%0xVs=#8iLTR?so`_NQ1b@+7k05<JP0#uE|+`*O7S-R
zqvV)_-Q%WX&laU0K2|;Sw=nDAe}sEzyh4p?$gHH{_$Jpq5MPmg8`{C1(SUkeNqmft
z6G<XPjh@BsXoVp6hfCDuU%vRZle6Xz(t5)z+7!-@bPFq6NJ6J(MOBsKwL#!#HG)$c
zCYJwdJra3*RGb#&EpRBQJFvAzT0(xXv5pGcF>iS8awm^o_tOi}KN2{G{|Bh~AIT{A
z6k0eViMrIRX_RwOwE&4|0!5>M+m`IV3a&~!Cfi7#kI<X(b5|GCLZ#Ck<T$?B$BRXS
ziZ3lz?s>sAmO1%axq}Z!Mw+-wl<hF8*+y!T#&VNIL7y*5eCdXvzYIGGf9L|Mn&ZNY
z`&YU>I2r;Yi9WDi$&AqG<eKilsvNJURh7@`vPB*#EgmVan|lXQ|2r1|j~e|G=HMUE
zG+<uv59phJ<hlTe^B>VS|A^(lZMw^D{3ipkKeAoWmhHrUz}{^CBb)|B4`%*7ee=_Q
zI%M-Jy#E1zbL@}xD-+uOBmU+etLXplo6ssInS>Hi%5bsVGWgBm_rsvzBqS>R3VcJ)
z9Q7!C9|{Iir4Bg@9A<}~K2=umICJRb^3T#LR>jlnn%9m!yR`L5(K`kNW7257Ho!vT
zGT;RZ+eU}*;=4OBBLw5v9F@u8S|<jSIs*Q)w-wwz-;es7x4BVD>s%rl$~paQ7;yCd
zo|5~Y_mmXMfetN$iW>3nj>{zS#<n=>;_16=<9F09_VQ;)mJF>)7RnAIMzF1Hf=^GO
zt_ydU>}IAvWLZm>k1DODt>)fuq)41Zo@7Rgr?`fnJRe+iAnuTFTNc{_U~k)~i<Iji
z@5^I!UFCx5ToWmSE00%U5N9z;xRW@GTquwQU1sUXd@=eV(f1rPKJ{<xU@r_+E$tj5
z8HG-oBq~oziHSaf<g;~VpNHDV&0nnc7ytbCB;WsoMKXde_f{HV6uHw^X@MjYfUK0i
z&X>s5_%cqiaDoT2Ixh|GAGX|75gyhEY{{||s03PNnjmp(fmJ0G=SO(xNWUMJ5WB<N
zjorTNk#8z91#=H6fUBEos#CG<56MOR+~tDR#C<S6U3v0hXmo4WlfVrH-B=H4-!IaS
zn~Q(@X=-O4r30HrI(gdqX{NBB5cQXP`adPD1Zo1))c=``#LH{viO7{NcRzWw^5x5)
z4_yQm#g>^fW;fisgQDXA%=%&vj2G<suGSUf{?O~clq{91|Dh35{jBVj80$?Z0RiGG
zz-wPFR|9SH*AC3om+xvyYW`)94^4?zP^+;T2Kt)q7k2$N<4l)0=*`(;EdRS&uD<GL
z8a$M4x?tP9dCxbeuf2M#;hU?~y12Nm6B<M6cV_&LER?Z(oz2gRo?ZR8d6%XoK4M<O
zt2;p&*b_gcM_dKY%Q9n-tQK&V=MvPvJmRZp?5(_$eMWHQ>jl)$*<`!BA!W-_`VD*8
zA@_FO^>{Tu%5CvMzt=BIuCIG#_{-)8=-zD1w5B~rxxfc}?iQG#O!WbFhu_r(V@s)}
z$b@3cbS}%&W@HDXBl*2(gab`UO-3D{DTO7S=Wm<JBUTRlVCRCdHbVw%h-Z-*&7j(i
zM9mn^b$C4en+=qk_i!kyvoNi|@5s=+knGAEnHeE>{iMTt)Ra$E@7rmg))s(ntPxn4
z()Uk4y9<!=0C({G#uowXoXO+_65q<jUXMgGDf?kLzu)<3J8qNeC8LVi%+LdqbhPfO
z%6v&5Q4F4iklUs<-I2qLG@9P$vePW*DCl&HG%?{}>BE8!We{^m5Y*PRAE9xhY8Y4e
z<`7z;*G>zLfI1ICgk}q052(6{NGDb#Hniyx5r!nTAS-Fr82tiGon;I6@SDN0evjfV
zupjntZT7OXA)@-pUR<8AfEj=K)XA>JFfm#3tM7L8uMEY<)bDCr(thwqj2Qsn8f`UE
z#hDRRbM5fRc(nHwd|=xp8j1t{#V=s_P3;J4S9&3%;ywajWs0CBpv5hD$i0VnZ$acz
zMqG5Iq7Jr{OEXi$!yG=}7IO^AC5>0NNmg|FcAeGrY|Jj;C&<i5$qx7eZ-pU*ZjuYD
zxkL@t3fR>R3IYy-Z@-E;e6)sW5X6mwpz3W%ZIl#!iKqu6JP=o)9F=i|Yn4_pu#CSC
zN%tf1qW1t+IBoX(p(@<UE*AEbJ+kWT0d-jG-(FU1vV{K5R}s)o3u5%P`65M98r{dW
z3H6RE!-MpkT+_N|$o!%Zv!1vjgbuux@(*t-BbywazKeCq6t>Y<V{I%rbo=mV+Y;vG
zZ9AW2GzznL=f_JA^zQwVW}pafXD?N~<~)hzH}<*j?FJ?{=cdcBXQuE&>yey#f&aXo
zF_Oi5a)fwEFx!IO?1eW}p1e!0mBbe*SJ~Mf>Zn|yvLI_UMW5r8ATKv<-Q>I5&v2`{
zl=v@8A75=xoSYj%L)KJ)DN{FobQ6>#7BtY4%orDN`pPgE)11oGM(9l{6wEG=qAqJl
z9Lg9>#NFF(aT#{48K}V%RMt?><8?&b?FU3o{CHB+<x2ot@jCO~#~t5KdxBQ#a~egJ
zTJ@j-_wT`n_{tNq!KzmV6eAnC{<Eu*WmwWrf_+MF#0~P?S=){E186$2@t3y^#Xv{w
z9k*j>izH^EgSE-{S;@}GjV<OL=>2Ml$yCIS?`n6Nv%qLZhoIWz`llPkZa~U`%5(hj
zbS^#!twHU`F5;8oskZQlr3o?%Ch|Dt%w%+ZPn0*#0%_G`NG;5{HHUx>Gj$)r0Ja^Q
zI~?e<`zhNyDhcsK)Y$^y8dDaD(I!{(GNW<%=TRPTi^2=pBqIt36bb3!G$0>W%~YbN
zv+zMop;hxQWDUv30@yIb2|Z6WpZcmQ%5ouuxge*IB+r;6$`Lq7cBs79^#LN<+c}nM
zUbpqj@IGUOo6ZHw+CT3G`G2}n;v@VMxl%tvLXXFXmJsGpJ2*zGu=^#YPKs=pQBML!
zlAUae&<SA_|CogMPSqwGMpB!6erM9{H*ziu9ojBZLLkKip}abg@AGT_${t^?;974;
z_USw(>UF8P;%o<nG_^pv0OoK79hGg#9DUBIRQUy;ct8lRmFtl+Jm8(h;yyiKWMtmX
zUS!jhM&ep7L(a#ZEcxWZlRr?dfLxQ$(iVi){GJ--Qk_`QYg@Wq1DqxQveLR}Am(vw
z0dQ!Aj)j1hxFksN2(f_@6*MHRjADn7;A$St6iX1JO_5=VoHrQB088&Q{VthNKbgSD
zfA1k479ofGH!+(1&ATciq!u{A!LEla(+51&!s{PtdZp<lg?;W5HX{rOuQ=U>|B0io
zi~$=Q?cF7rbSb{_bTL#yfH9-)U?-U1;*4?{6dcV8lqpxjoHIy!!sY}-L`s_lt1%c!
zExbB=)rZb|?CLB}{T)TVceLvN?L#y@gWB?4?Gbat7H0Y)LBK#oR37`9QAWW}-=h7*
z6r%aLj_tTr6n}S8+J0&~dj@na2Szne*SE{DCnHZvY~!Tz1x{($O%EvRpF(G^@e3>r
z54#rl{AddYXiCFgh2QiIP7ppGFkSb6pTLqLq<0@MOeP7lcEIwcO*XvAfh2p5`KRaz
z<y<5W@+MSWlKX%jIpDmQ1dw6#3bYP6fu?(S@JXoU^2(lOmLU4ZZ^n1fv%ahS>utIJ
zr?bjCkIH9gE48HOaZZ%eNT)=ExUsdUt+d(WZD!<rZn=m|cYOj6@R$oUfj2TSL4TO7
z-&MhwAEMQSH;8Oq@7I00qU7!Be8~Hf@}x`a3||&Z0c*frQcF33v_f>roG=}U04aet
z0@vG4p6*YPhu-w^aVtA0YihV5$G`4%xjvY9(4??F)OZ=RIlSrj;*7S<dQ*RTM*gxJ
zOme^h<3nB|lgS%M@s|42B}=-M>acqgy2|7Nb_eXsBhF&7R^Yj!g{r20vu=t9yt03|
zVLoLStS(U6l!U-!>Q^q?rV`%Eh*_3XMmQ5IDe>6mnzO6sgGz_iun9MZ66wh#6BJKi
z%bU<tvj~ktQ(N%r%KcLOyO+M3yn$aY4M-dh!AIUG!z8gAWvhYkU@owQ_ivC)&%y?U
zlpreUB+>9ls6Im4TirQ+cvKCy_D^5`UrU7&)=99<$=|Sar&c0#Swc13FTt%LdxGc4
zdde*ft+5#KT$Qa)!6FmzgBFQR+>$DUg<Et!f}GOavhOhrWCwgCcCImA=t7M<7W?3p
zL%91cMGPIW#&CV<LQmp!meOI$*FUV^3Gsynypd{nz^e|izC*@00_B1O{er#R^c_lv
zoYjm*kA-VA<7}RFvE0SXIYZI3<VsQk)#MEmyGM9Klot5-O=U)?`nT@C-QmuCB0}!5
zsH1SvsFB12rAVM9k3zfolEP<_J{v_e1kCc&IP;ZJU?_!~(?junfIN}a`w&J^c@5$B
zlxsjz0db~s=VK&5$^cHM9m@Up8z+g0m2|z9!mvqZoBz`3l#vR|+oDEd<;R;cxiR@I
znckA>*RDiCEn8s}mzdzw#hF)0n#C8>Qy2zz)KzpdM2GKWwwD3yn{Wai5jZ!Rm-Zs5
zTiVA^3x{gb^G}~pgK7U#^ZaXxIb|!wj2sa&jLE$c^hLG_B7NCIG6oeN)&V1=NwPAa
z7$1nAid%<dG|-?5toMB~rWv;oZN^@87|3q)Sv$mXb#mcH{Cp&Uw+=b3h}GauYBIz*
zwtZV=`!fVA6R-@<xKy_BVrWVDiit}qlP%Cd6H%M0A1Z818sj9^1SLLXZzPMvJvZPm
zDgIJrt9LWQ0;{bc0e${c!CCq&gw9i$RKZ1Qm7{*+?tLbb4NuxJjcU}ezugsVprFQV
z>SK69;(C$g85Hy&#HXkkH3RYFMN^#G{SSw_#7?By*I9X&r+Rjr&ebW|SQ~PBk^AVn
zacQpUtfm{CR<3KO{Si<F&TK<A#=<gbU?o&5>+VmR+JwY3F{;^*Vavm8UB4<0<j7Yz
zce88&{Ywp5-v~zOhR>1epq0vl2(S&FiKKuKO|1;CgrQ-to`?2l0yfoNpa%Z!1qi%p
zkjH%#&(EOI#fHBzmei<P15{?mXctsk@B^h2t5ZaT2&3H)lSeec8h~(bZd5MDx6W*$
zG1t7qemLA$GBz=>jyRNk<M$eJH6eAkTjeSb;F&HuhY#F{r~4bg6DiasNX9-S?Y?qt
zMx&)Baz+v!)<D&SPvFhLOk*!7(K)8<Ma<@4;O3pf!#P&Q;LXXdQ&EyxZE+5Mct5Br
z8O+dM`LrdSx~qm>^QQy!FFQ48EvnH<gO>sY-qNfJ8sIaul&9fYKis^OD`8?>g%zY~
zX|B;qRXT(hxmhS~ioq~Y>5r8BnEz^pd4CD3u}II8j@p8-y0K{zw>(5;1z9FLmgJ|l
zwcZrx_M9(0otG*6C_J+0X?3ns0@)^B=zJ`Dh0%$W!}q-0tRlT#y}b6-r>IS$|7LgQ
z5Lv{jITS7S^hG5G)@WpCQ#3+g0uTL!KJo%Qjw&axlI2N45ntC=CIY4YR$_d$qvaZ8
z?E^%<4~db;FRE5SHI9s9@Djkm1WBM6bDy??L6d&luCnyhg7Z#S@Zv1mY}HJlsVjHl
z;*&TPWm)jXM$UYENH`vBmH85pdI)3gGT;k?WZIFqHQ^6@$nIQ5MIeVMq&UIp<+KuH
z=LFw>c}6`I2Q94GSx_8`*Di~6g;W>IE>Oe&?q&>HXT{?KX=bW7MCbrL5t#iriIdru
zO6TbtDjYdS@+v#)LZy5rIZnc$Q`LoS`GekU{cUiqw5vK$su=%WpmZ%mQohLe>j!Jj
zmE#jAi#q*-!zI;3$fLRw9}sJxxFt|+M69^}SQy_}3${H|U^H&tmXPhx&k-M1E%qm4
z_CD!wNZTf}=J0eqn^lY2&(?YKUG$O*lqMXgTai`NDiOey9Dujn-iOMd{rhU|GiHve
ziSs1uBL1}eBK`@3$E5e;kvwMgs1Y;)IxnIYIY{iJ(2DnNHp@z7ndXJ|&w?g++Nw>#
z(W)YGNng}K7<Ccr4zKLo2JurU_BA1}>t#T2_*8aEM$ksAp(rsXjlG=Oo@)Uy(tz(u
z?D~38>X1gwVGYS|NIqoi(Rmy;E`sD@JP&0`zKkSr8_^YYA2@pBqB(7ObpkF%|Hu%a
z>78vQ@QkB(mPqBAK7%bWcV4PXY5%STlJ^@;Um{`mLt5_B1xt|ZOxoPlfD9uCg>a>X
zn{vT~=OEgQr2!XhL9FvtuP1auq&MvZ-tg;68NiLGOWG-ZF=vYGEsfxU{$kAKK%%Z+
zsoZlalGd>CY}?yfuFu|L($r4MCgicymyqO5)WI!6Ox&J9#<!(_m;0cF8&=vkB(#i|
zFjDdJDTHFgxYMf~M#ss=nU-XdgqS=g*AKqBg(gl7^N8A2b4%m*f9<vZ_1qZ)w1oA*
zR0}g2doPSHnMjdVz_fVP8fsha3=m`)acBDRDV3!%682|`H@2m|xZgW`rr+b9(gD6q
zHFylnWT)d7&L8w&`@@65E9BUj5X_rNj?%!X@f@uj4bn$i@rp8pX5}FfT>+wPLu4bb
zhdLAT;Pd1lu!m{`jt-Q4sn>!^(UoD?U@zRpo5E`&`AwEuz<^R^gvhuZ%YcezHi%l%
z<MOgHtMt@i!k=2Xf4#ieNRyHI&@uwp3(E-&+MH9h7QjfBPtaBx0+Y^F*d5TNPHyf@
zgaAGfN8<$2Quyhsa%&H6jn84w*y+Fb2U<;>B~;gwC9yEzeMRJrlegIG-Ym;F)P9z;
z3yA<n5Tg=K<jLtOeVEVJrHP&5sG4E;nOJL^B(^hU9dZT|HM{Ur*$$s-3Ts0&^CWl!
zRY!Kv#fR9n5<gpRu8m+EJ)gWyrp0pyhZEU*?;`;)sE=qG@G^`2O>02@?=R0zDo1R7
z=Uk?p#4l8}gQ>Dfj?{}O#-NdbdP{4N6hPEM!lXf5&a8f*yicQZOWZ}^yD)f2T@})A
z4dHIX8ied&fJW&#^pY-HE(7d}F%xLClAl^p=icOUO6Lo6q!ro=IOnpUIO@EnNNLM_
z>96q8uOhNlgOEhWx&?(x+O&t+D{^Bny2Dg^B;rn+8hyu#;!x^hV2i56OQsz@E4P#Z
z|5X2*k=AOVf4BDyv%wvn`4Cwz?lX|lxujIuLWA9m!!S6UN{%8HaHlI0P=v^c6`&am
z4FLh)p~DT6)p1yJ7*xphJ&)R?epVigrrgDlsEL;3qaW-)i|z}h=L2GsyT?k|?_o@2
z+1yD~BgZVve+?oFxJx<n25T|pOW6qxG)$oqv$93;N;fh6Z3|zR$d#v5M<+I&k&ZgE
zHcEBf_d^^yQ)!;Z7wevDIrs?5QhGRy>JRvK-dTiR@V8}yhz5;fW`cILH6Wkjht!rL
z^dIJyr-_#sPlA#cLs{IVW^E~1QhH-ABjsFnT}2el2#d?MOKbX_eOnwGVmIEKMgSN?
zj>vp4B6Ko=9weR)lc0M|>e1RbV`_)Ulx;yV>cIv)Kx`U_`q)@WaH%px;*QcGlB1`%
z{f@A4Dkgrc=n0YxFQFNcY1_*mJ+ACfhCBrErL|J~ucyZe+QCtC0&dO7`uEH3_76YP
zTHx@DFV{?kn}DBLDQO#$CdJ3&?2(&!N*m&(HKDnd&vLkv#L)&O62q-V8{#FW2Pcf_
z(oHCZ4pO~Ib)Ra{icVyXbF>ayXIASf@@a)rC?2qgmB#~BgU_;L&}&aMUJG@xOXTHn
z(xSD16j}^6?}2)*gf>zKqZFC29mqdoY1~!4IRIJ;l|?yP7rO=OkRL=6Lm(&5YWV2n
zCZ)@)kBKF3{a&ko%lq42qR`S7w0_%_SO|2~-X<xWuu^vdvQ6UQ*~nI}L9S_ye6^cM
zUX5FW<S2?kPW*Dt<-15Es`*ed)+!&#{}E+IjFpwkyz6or&kQ!UG(?&8Ne9EeI#y0;
zD>oqlP=w5e$DyMuP6_~{5aNPA(mk~#*k28zHEOf1UdTv*MX5zuduLeS(hkoAOf;4u
z+XC{+i+y<8>OgmnYfq%bY>SnOUROcy!R(ejYTy10`1sryK?87ZWVxu^^@0N@*@<If
z&scy2_#jL%Lz6P&*<+~kH66ppCt9uqjTt4fi@i3ay>D2sZSxyoWZ0I(m<=*u99vo5
zhU}FvJ3pWOEC>@H81Bpeq#<J@9cu#=jgb@kL6bpe#RCW&XiNu|Y?oO)7Ti)i+`8;*
z{x?}$)@szRZ<{~;GW+Wjw+#)?n^9Ve(l|+{yg_gRY|c?$(mM#K4j^zrHW2A7?_40y
zwVn68|7_5U4BXLt(?lCPl-0!3`g*OUmOIr=>(!U%1h+K1-bC&CEn>hmPW2Sh(_Zl5
z#0>4{83uqLv5O;b0RxE1^dk%IPrr(rxOyuC6_UT`%nE0li@i%vT)e*YD_TW%|JDFt
zqx&;5bFCeJ9wj%bzN+U3T1_x-U0WH~Hf5!e9^L&LueXrPXRHZYyY|JG;~%KVPXQV;
zbGJA*)Rz|3>TKAYvQy*Lw_kbc)5BwZOR6oLHF9q*?EdXTcqjGawwvmU7Lcc3ZPQwJ
z@zz}U+9l`Lo7HCLyrvJ(aYvuxJOj-0o?E?su~epIwE(;DlJ@rAo&M{v&!e|<87^4#
zIRC=WyZBa%=Iz~lg5<LP!wbgh{a3gdnTgk?-v9KI#&wjH+7)r;&XxFxMbjT_mU4x`
z&lm3A>n1+;!gSGz3)*Y(%CS_H5<nK{`x1lmYmdn^TIgy#-o=Wa^p~mKirip2X0h_W
zNHp>jcFyC?TsP0^%83O(Q};iAbw@mIsy2BcSYwEg5R({J(Z@6XTDkDX0dS9ajROm2
z{g#dwI%DCETA`S2dYxiXc)h?aXa6_f5G&O(lTGK!F`LLX=})oVF`F%8;pmU&vHOb<
zFYP&llX^Gu_+cbl>k71RQk8mdsAhDGzBXlvz$N~ruq<!=XqH=NMdjD{+m$u^F@7WS
zZPoChgcd*KTG@_}qW7*wU1nMdpG)PZ%Z^?1+CCLni)Iuxn5UcCS9W3F-m>?JXT{NH
z!=Q+AK%10ulE;>x?1~K2UBcfB8(&j9g85MS=3xe*v$AewyV}#binwj%Pbz!t#O@^}
z+GoF2Ci_k~j(56$1U~9P$PFl0{sK~zM;KlCB_m35`<QiYd%^MEd)}QzXRkLOSrE5s
zl2YYFx?uSWXNB5u1wPIZ=YovNL~4hJjaAwZDNYVl1abbbMPF_{6WIBxQ8uRfbdQH`
zIoliJd$8y8XhrGTaQo3stBnT^bQM)pWqww-&)Oe-?lIsVA5+?%lrc1v$FrK)M%`>}
z<$mNvL7#|%eG0w4*8*{x%n0!gD4kH36a9AGv*O453uxz<_qkEDkW*DU*7u@ID@UAG
zNGwf}PAPu2(yNDU8)D{vG4j0Bma(AhnIx9_I-J;8^D$o5;zuCBPVwU<M$ewq)U`+2
zt@o~deB(H)qHf39_r89;eO$xAF?td{Y#P_eWz6JAW<gpP?W-Xsmy-&hCty}z<ze2W
zPjRRNezzC{k8{~BpgICkjAmD|(^7heg_)1os}j8k2B&LG?yl>pP)`FXUz#GGAXmSt
z24<$MHg95RvMk`h-aSYR<l00tP`aDKQ7M&j-KuNTId{X1ee4Qv+~McpiXI>g9(5Tc
z+>`b5kq{SL!P$(N;~oYIPrx6&{E?)E(Dy<gIWiJTd20H;QtJUZ?jXUa?~@Nmdsv`)
zZARqb=h8=X(M@2nz9x=tOfB_q9un=V<~;5qm3De%9PO-VzXvQX7*&a>k-lNACcela
zDC!_|NEFAmKvv+;x1IQtr1;XYws<psssl&8^|qDNI)M}Gc;k%B&ZkEuIwT;CiRK+C
zEf1@5n!Mgp?6K{@bUAzZ5Xcjt5YF5|W?{zh3n>TSF{q({d~sFhVWb)=Ym=ao?edaY
z`@R(3JSizz&aBvA7WJ%BVCJ4P-0DtPQMgF!7>rQ_AwOX%&C!=R^RTY>Lxrf31~G&F
zBp9~>iY&|k4gD$;+yaQ0#M-mUVL2tNq%L0BZzOPFB&`chE*e@B+#ceTYZiB)OBNsb
z@>{hG!_|OjO+C3<tezY%*r@t4z@f<OSA&dqAQsIAc1=7BP8bog;kkpwmPmKHZo`8k
zZ$r(p&8;&$-Fpd-HlJ#7lQXn_9PgT#RJ=BO31wfRJ2XO^h1JkX&=p-~t$i?DGXc(j
z6gc8Dsk7Tv7DzVtFpSMLeB_dKsUJ*sBFO22Jso!59@l>#&++paANi2@J7FQ2a|DT#
z;f)YE@4&-J`4yJyLxkadeND^!uE^G{vIDh;=ij{IHR#a7C(S<osQxjJvr>KY!aBqK
zn`iyQAM{gy?dh~1x`YLk-P1X=kY$kW81b=J^^_qpptysKi%U?(<hxDB;DM2*d;ZD|
zhz#O1PAZtvFpk9z^cAYJ4Y#OMpJ2ef&o8790kJyzM(ORUo4QrZL{1>;oxfs0Oc=?J
zf_83XrZOtLM^I9<u%=g$33jAwFlu)XRtxq#h`7TxiVF}vzJfEW^+$&-Ol-WZ!KG?e
zA+gfK<F_>@ntUp<>pnm2x9f<s&|8oB2t1`Y;g~CyM$=c7=ckMYd-_p15&{pi&{Y=e
zc@zYynlqE4y{6>qLz6|9fkTN^>9X7R$hJHe@LgjxkVOA>&#l?M(_vexYp2d`^-U@q
zi#1Wrv4i7wAe#y)Yb<9Vm|}#(<;-LerW_GhMN+rYMyeyC1E+W+nNFJbRG6gyqSQb-
z2F2FhipJHJkqO%bWmw%vX`3$D{b<iwKOO(a?q9K+(Q55G4ArL>(;8OL#Mja4fCs~Q
zGyx_zrbr3Te-$v9Wj2Z`Y*Min5_~ewB4;XKkH-vwgwa?>BD7=oi^KN<k6GW2Q{(h`
zVNS!#=&=&od^bBdg*fj;z)a(iZ*fxq>TlS9a|U=hC8&TLC1sZbP(Y}ak~>70NiJ&0
zUENW(x^l`q@M>L?{9>eeD#qfIE@?qB<}=gYl;vch%qMiR+)H+AI8KZJG1)A40MVU5
zzsmv3wVX8a^*$0)zZQ&-&(*<JMC4A*!Dv1`+}sDsy2P@c2FMC9mXS<r&K{*K5_k^l
z<`0=k82fj2kSg3B8cT<zse`x`lyLZTskBXh*m4CtkmAsi)rBR<IHqA{x#f|oZl<q@
z1VIVaN1r~sx-xJ9uKhmIo^Iv)&NunAbyf9M4Z)rNslwCiqpz>6uF00pkJkr0ppQ4F
zZ-zy#I&M>!88+PKdw{ccBrQKh?$yP-_ax<{lcSLI_SEO4nZAM79sv3+ejb+rJVM?+
z&sSNa&+CBxb++o}>+Q+S8v~fmqlYhh47h&fGgco(uXvpH=EMAf6W7ngUAtnbx5b<`
z?=2IQeo`mex0wrzw|rMyr@G01Jrp4-Tr0wQExyM3)RwV~@@(gNy}dq`uJSV%FX-*U
zUYW7}Uka4F^tJyf6;&e%OF08l)YLQ@*s|>BMx0)pWS+ETe)H^g&9fJ8UUcc*Ov}4P
zUycL92q-s2Iw~W>`P+|O{!O;D$<*ffm))1#WX0HQwNp`!lEP)ud2=sZX+c}PNIF4z
zf92A;jh9?f6!N%V_}2U+>@)p6+X{mMN@N(?l~G_H+8iwwB=Ze@2d05Z%^gZ={g>k#
z20NEBif!s*NDaL0fGW~`=#@+0x%;MEQNRX`4KMDX_WTR$BSy2JfZBfzcxnYAUyCWL
zk>QiT?3#9=-(dO%E5@e2FUaE&?5bQjt-*yUGdtL3zbWUFB=TgRw4y|o^PQugG<$k^
zLPqMSoxy>wdxGqtj~``xWzcuEB|Qb8kEBf!!-y4@b3iY0i`pd8Ra!v!oq&7KNQpi`
zwv`b_cEDi(;mv>|Bpx>eiJ%J#Wa{_<8L}PgI|ydP*}VtDa7HTDlSX^sN47cy=Vpj+
z18CGRYd2JOyMTPazFXC$4g<S0bJd)SQi2dIVcZ7sI8+AwRV?QcjocvM44!}w06zWx
z!(6l$E6OPufI}vG80su%D9i&=RfA`-gDhxrIbC_5oYi2~lLq>4QmAp1AWHY==Mk)c
zsXbHy=TT5I0q~j2MVF~oN~g|ol(sS)p+}VVBSGSzh9g+#Lh{#x?Pb85w3A2E9s|iB
zsaz;q(1g<qf+|0Q(b!%nEeU!<-=5xVK09*`U~}QC2O5SMaa0q;1CBV1Oi9`d`>Ac-
zqPdjVscjVO8>N$!lPV;oRM2{hj!ZvPI-%pn?PyZkWlSZwm_%-L21vRz$?mDWOZ>!M
z=V*4L@LK7o$)jz>zyc}&xWn^Db*Bzd-{2RrOpY-_s0K(W?A>hX41K;WP4&aI@VtBo
zNe&_Mk<sxI51WHM6}_=Lm!CXTlfw7v3ctR2yLZIug%@IWB#ul?`H*WBXWsz1nGu<I
zw3BT{ZOx`N64aHNRiJ8Z7*2envIe1_QO)?ITuf&LJ+b&9c?nHZd933sCmFX2URElN
zA<W~XT%YW0HpW>zGZCT{=aRJ^DYwId(Sc&>8{kwti{D6?LkUDg646B*sv{8bVL%>j
zm#-mNAOyFYVgSkgi0b4F@$1s5wV$%nOHmDPu^T0fxnL^fgfr^4N6!fnI&{(Ijw4u8
zY3#1BSWxoQd%YDj@CipUWS9g&G>B&@L>MyHc-l{*gzV2iP=QjSODLwu4%A4HxDV5S
z+faubqD8>;y=>T;pH>l50hcCTUVRp$Y3}jMNXVo-DZi@63Z7MT7oeDeDF;db0yKqM
zN=JY~$hLH{7g6hJb7&{q3=kQwhBU&TawZEJs?p{5IOPXE0i=FsExb|jvV)>4oyJQk
zwAqpOfJy5x#}e5_Y^SU*UiWFD-w8O*l#N`#?P#YQnmT7ZT|>1ZPhw05J;Q1ObIPb)
z#lQmmC;U9+dMUx;JtEjj(nj2yqFqy{D5MtP#G0(|ljtiBL?b1>d%Oe<6k28-V=-wq
zjXvy*Gck7tvtk+PSQ~JHSRv=9R#ICX0gXflUyhrt+}1P3Frh5O&7Hoc)X1Z31&#u{
zSjQytIS9t54!M0-Ij0?G6)ZBQu5uG&W{SuGJY)Pk2lN8vPtbOMGZSGIryvylt|KOE
zR2}3$^Rp*LN#JdqV1EwmBy;G$G36FK$*-r)8m4Kp=P9vBk>rTIE{c!W!0w~k@TK7~
zibUk_<cL`z6AC)iF?Jj6(f*oI9PIM>rnHx4e1d&J<Q&W~S7{FZh!7RuKBELu6Mhl~
zABaK^SJwy<?7ypN40>5=0E5LCp2(6T`8jNo9;aH~24fm?m$g&83qph+^X_gb80??N
z>2z=t?Y<2%)&p;s<*R`@N8&xYZ7P7;4PpysP<ze^X(O$0qI5+UQ@H{JQor-(i_^;i
z%58$k4yQN@SOEnT7vz}uc2tu~^_6kI)gwohJK*rbq8aal1?_GRta({$TfcfYihAP|
zAgxq_o`V=j7@(d&cCu{6rDw@mTo-TUVj{|cG17X9vJ*KEpYWfqB|@1c#XvINR1XZ(
zEodXc_}}~TR1K<^YiP$qvwL#xt5PTj!9IGGqMjiGdD}UBjxN?tTI#uNI*me-P6zP^
zNq|sLRIh8rqb>w8vrQYD^WBkSkf@$x0ODc>*M(T3V}l6QG<|X&$$>T>IOQ`#y|bb}
zGFPF~*_d|9Vw<$ea4WH@SjJe0Y<9sXRN_q#b9acCR%v^9>^U>irkiCVp_x-WI>z{&
zpFQ^{n{k_cx}tne{_4}z(7E&(!@aW}*9-!Tn8Fes<B6cb0xvbbp;;_pBsoFKCCK(j
z&bxqJkC9?2EfK9#iZyb&@DOV-wd<&IaRm$zCmqe|5;uvTRs-7@DJmVRIoX!*q0=GF
zOm~Ky`{;e_3aN#TYEA?c&k3~Hg_wH@sH-W50g`GUIh_IR9#CK*S`u!(zfvDLRD!tH
z%R$3|n;~Fp`;k+nAm)AX8!DP??hX01@oMo4fhpzOkmy5-WZK=tkRUO2ma2>M1Z-!R
zc>I$?4?;x?DFLvpB69liS-DVf6spRDh!VvO(76#aeB#8K$x@M8u*w-6I9`I$dr<QY
zDDkiWYbD#*mLOB<hesV~AM5jO^w+OQkb9%O$x*5~$EF;}sNKL&vXe_)GMz^Wzw?Px
zo;a!l;dw-J_IipQvI!^#t`3RJIKgeRDd#~Z5c9IXEz%?f6U-e@X=OrOj2L77Nwo+*
z7a#lJ$opl_?$i~$`Z)x;Kw*Lek!xUWJR!$;AtKmH(w6vRq<*Lx$&+D{@CyKzH?=w#
zZQv=PH}%qVIEh%A)D%PU03EQ9)&STSh{l18M)r!zc9TY(B4o)I3xoZStJ}q$c~vjq
z&j4qirHKSg&8DEcz(8KtX4mv}_LBaih^SF8Ng8<!iQEOO#ScRS{lKaP13NY0O$@{d
zH)WW)WCk#W?2kipIms*FWilRT9?M$a=g4q%w6psPb_oR3pK%gZyi9~bGMZgP&77n_
zRPQ;O5W{C%cT!D2q#4nMhfW+&c(#KE=)+@%gdfjd_8#$dhq044%8C_qy{gAC`A3mZ
zcpNzXM<*sZ=<aOgY-G8@sp5$y^gAnH;c3q7S9$`watw&0;Ny++I`2RtE=LFHY{=aJ
z0j;blV#9NaP7M=qjId~_oko+&$ZtJw-k@qhTmyA+2g}#F-R>kzh>vd_{rxwscC-Ob
zUG<(;6*Rg6gbr(^u$&5q(H51o#A@0CWxy)NlRnW1EXB+vBEr|52jI+VcyeGHVk#yW
zlbJq=2Z4>JB#e=qt-3Ac%>B`6+vng>Na2?$o=+Mm?h`=h6{p&@9<Sp%wc#CQVOKt&
z;HjKyz{aPoT2F1}%vG)KBU0aZ`_F?CZV54o75H@E;d$m^uX0yLga0CEA3-PBUGtGW
z(J(mc+Td}tK?5#-oRP!{<GdS|xQ?Em(pLs_tip$E+Kqmf0ZJso1u(5qn!^}z^(CAU
zQZ>-1LLpHP$Saf)65B9hx@eyMSAW46)2KhJ2d4+mgZddK6h7h4;LM`%2Q4v0ty2q?
zR3vK3iP}c2oJc;)SV(L1mXOqkqX}vF<5P@<p$w2NO$n=<en4>pcLA@#WStC{!i5m$
zsg{T4b0@Vf;?{@|nLikeECs4tSr<6WOiLY(DEHFuhFq{j0Uq1vG>a7`W4z-l&O=1L
zJ4z#mWC3y;yv5ESUlU@urZf+4eewuM`Cln_u{&@U%Q*0Q4+x!Dxnb4AaOx5d*@{!D
zCQ>nXX7*@W+6WE}cZxZqkx<S2DF>xHat7WhYDCW%CtblCvg}UA02YFaac=HHShGYd
z*P?7iUKEB3R0f^cEf18A@LUFpqC3}eS-1Q&@Xn9Tejd^hQti`x2cu+&O|Fcn=BVD_
z)p0AyEp7sOqRJ9%P={dGgO58$mZ*BWu^0)-G&uMFWADv_n!5kLQ4|FcA;`W6(V|d`
z5S2|KCMrc##JE%tP*Q7^P0ZIS65)^t2mujNwL%3YDzb?{St1oeA|xTTl!9!Lpk%8e
zn>nXKI3-J;kI!@G&b_}ockax+Gxx9GUykD_G3T7mdB0!lmu=}w$BwlPJZ-2?cJ>du
ze<|lz&>^8|XXNgyj(*X10XsthGHY2mwi#2v2~m(3MgFXog<Mc99SzfGl|V0I0kRPM
zuj0*~fM*yW0q4M{JdGIhV_d*&T}r+YkxI@7EvTY!H1X7#n)Lu1fpE!+-lIaoSHmqy
z-a+1xk^@Wrk%D3<eSef_W&-Jv`KtJ{v2rP2buH@IZOtJl95Dl$vHVu<#$hP*f~+*j
zShkR%Uq`*o*E^5QNtaX4Pj>~V3h}4mrU{Xsi#c4;LuGWQzExdUJ>vA2H};_^vUd8Y
zUaa=hH3QD+BvCPZPug<gW&&}QPdZKjI?>GwlnqxMS)IH*$Er*(--4ri+na`@f+!*Y
zzJjU}x!9(WO-UcmSLN<XyO8L~PH$|`kMbIUG&4>*mZ&IfsG$w&&0!vxbN%D7;Ox%u
zF(qY^O|>T#Wb;WsvYFnLx*POam-+hhT8c9_eK$P!Hc@_T&TrguAWCm`^x&}Pyc5&v
zL-9@0Bj#P23GEfoN?1TX=<-Tb1Uz<tU>|K)4?ok@(OlxUP`&vi89hH{8M0k>|0x?p
zSx{RehVjXji80HDTwm#zKdY1Ljs}6o^a5=3^AX}N6r;NdBEjXWE}y{VIi%x4hV_uS
zu9}P6A?`H0s0eS?eES-5N4;wydsxh8S^@#-LP1q4tP-|^N+|-EN>Z}sm=@EYxqR&P
zTQ94jkl_}yAR*WNu9H9<P*+)FbbCkDpXA0^0ZSt71hB^>5J`j91DKaVz*1u-l%yM+
zJ<=tW=<p*H*UeoG^YS-woa*AE7Qvc#3ls*dO<c55-Oz3a_tSOC6`50@=XQ3^Fm&ov
ze5L4Otb`_Iu~Rxp5<_|4%rp=j=sOUpa2CETl(MlmpfH8Bkn03DFnp814jo6&D{&Xx
z_t-P=2o?*NxqZ;Mt;JN7UwaMt?c~iV$-R&hgHInk8y*WA_?7pXB$BSs+eYdK$~L0)
z0PY72dDYA(#9#K+ILLMNl(X_A?m2ZJ3;l;r`~kG5J3yRA@YZ@{1ye9@c2WH9$mPr5
z(7v*a`FeaU{AqL@$6zslUPxv;tF%_P!*pe9b$9+X0Ot!eLNU&Q8|2}|h*+RsF)&YD
zl0b0oC;0XvM0rXE0f;o6b@w1&FxpuVS{2ji9C;Nrwj1lBcZ+xYUL5t7ch$$#7TNa8
zz&30?cg5!&7Fw-qI>$Mt=vxNu0q)E#NO@;t)MRmh|BHD1u?J8BJl+A5x`48?6gB6|
zpH;z4nB~xcR+!13rSUt#2#I&aWcb#3^CjxLHJ$alHq2j7XsQyD$4cdW*SSX1WJ9g5
zyRfIjRBs<5W6ba#2o=t*{6)V!qM#ug%YM&5eqRs;<YZK#V8IEOgx{>z1~d*|DmB&Y
zOD>>cEfc~XlFs_r6$@;JM)eY2^HV97&AK5jCOWq85wY5n*d*@WFvxX4H?rv&;~Ssp
zO7sqpMKhWKlfi76J#<TZY*01NGMtK#)D`D_i{hS)QUi~-ze+lvykoaMv~(xtZr^M=
zh!{2oT2&*Rb~}*0sJb1J!~CSjp0(+IA{c`A7u_Ve0Yg1I)~P<E#Sh?Umhp?lot{zR
zuA3o`-(r?WqA~i}ilmE&{RtaxCO4+&Ey-hLQuRp?tZ*8R6-eA?#E8+SPW>9D!YEtg
zjz;hP1?79?E7uQmv1q7(yrzYhT~x9li~~den%6#MSXj+ghNV;3waJY|;zQ|v-6K7J
z(9f|7Xtufs1VSR~Gxg|Q+%+v@WtA-j0{7hMDxhbx*##HNR9E#jFO@_WGxrE_ix7#p
z;e~hd&z+B(Vc$REbcMa{T(apur*8dCA7C+9@F5mx3=_|kKGbgL2cW2HFv>`llSVHF
zBNg?faI;*fjpF6gjP-+hV^pe?I!&>heOcEnftc1jPr);%()4_}i2o(tUEW|qHH|J=
z?27YxIv<A*skjQ=MXJ<4f;%i*y9JTHAlXB4aA5`Pq_FG!a7lMmW?olA`;BZujIE=G
zzzaDaDFZ!w;6<R2Tn-ug=joj$#Ze=*YsQU+9*yX+Et2jEoAE5ygos2U7ErTH9sBGM
zK3%~yifbj>y6PU#@bQv~JUK$1nS?(nTd#2<HDTyAwEQ?c4<-=2uacfq<^z`%Ah)zs
zra;^V!U5(wa01617GC{h{6ebd<IDe<V?E=|k{{~_32O!`250men%rkIG#9krgH$V*
zsK~l&WQ?AeAT^xlfxfEH4mM)`>&<DsHNi^k#Uab5@o^=qxUR1%27JR#B`4N+rU&Uw
zbeivIeLy=5UXrV5{g-)miWW3N^Bv@(`vq_3-i2F%1_{M6xM5&j@a`VR4B<@_MhIO%
zX259F+lJ&mQ?yWYqKRyo-qsU}*fK7hs(dp(8TEK47BflzjQxZE+oD|-5&VjNL$~EP
z!HXh+i#=j@jq5ulUCB9y<p&SnK9;Eg06F7&GRb_O?Cr_*L!PHgx_Zy!lGuLN#zK-V
z-RN)qfGL<Kj(NyiXLrFYxr$G}0rV;^$<hK~&jtq%(KLZzfg0M~@ZmXvpVb<h$q9T4
zT^Pb2gLjj20zR@8I%6SW8GQL}4OJu`R%LR69(^d;lX2mqykS+m9qYW=B)Nq-8wdyP
z2HA$z(Dql{b<{Bt&zj&$@ATI%fsBS|P9K0h6Ue*_wM(wZd6Lt5JHINh<JcyK6D`(@
z&jBXfR&Pc(KaK{_8R`Yc4V4{d>dDj`#o*xpAG%K>uO($>5HVCx0R9#sbd-unD-w9k
zAUlPZK{p4(OB!El!ZB2an%)ItceGO?*>swSVRwWmc^T)Ef90gx-l>e5UQEfIqpT!m
z#w6-U05WN+<Nmmlz|!45&yzhS+R_u4lA;N@zrZxQAhy$G-7D=eq+Ds+q1hlrFkknB
z8*Q{>zG10$EeFPSIW>%GgsBS|w6Ee9S4q?v;A@rU0QC^Ad&JR@nzc{=a=;Z<SGe5y
zR9wLE1$X@txOfJna_|nL7n2{;{sbgbtdePr_KDhJXWGlDfeM#qIWTR2m*|8r-z-HD
z(rvHD#FcH&mt(GTJ*a~R=nPyP6m<K*koJrmXMqwtOcO~)@d4j#tkDljm$k3};R2rb
ze6DFL`bt4wN)r=TaJQk}{0N#WsJ+Ckn4+yhixH`!h=F(??8hIaR6xg(?!s}$S95))
z)8RL%xA^2zvUoi^u^MlBnqngzrJW<?NmtDCUia-s-4!0H+(myOi$Qk*S>`9;Ew3PF
z`F*-vnm@<PC#*m*vO01QP^qi9YXQo~T?xEdJma&&b7QmE&awdZh<TN5adJ|HQPPni
z!zp^63m6wNuhF|^b*1yi;L65o+VIxNEcIRZJxh*x&Dsg$MB6#vmTf>Pen!a5O$v0i
zoVOaH^7LKsZnTSTKV|!Qq_jz{l=k_K)FdmSu?{}OFB7Fpc;|S9SbP1J6Cg8dL8Nkq
zlJbQSpc-}T;Rn_-e7t);v|T~Zl@zG*z8~U%?hZ5ReiOVk6qc5DrF!ymgriq}Rqv|o
zOZi_n7j7Gz4c0Xf&wx$5No$8-x>%0-fyLH*y}4dMZV8#WQ~73^wOsG4^^3;`A<?^a
z)$=$b=nxpY<tj<6!l=C5FH1=;9CsQ_cD8l)OYAYj@E2M6mpU$M!u?!U7k`w#u2ugE
z;DAJ7*^*MBiwA=1^mGCR%wUo(C0lW>Ap12Ux&h5)n&yw#&2++sWE88^8H@V0UxSX+
z273U(f_AiJ{v-Z$b02Kp_%_F|8HrmnyvUD4K%`!-u{@PF!fVN4uJ^;jtT(S;mh1Z*
zt7aH#6Ro@KwU%|YxUIgXmJDql+B5-=jNMIQ&mQ~~&PKe-t@Ybp%~$*ALJuM~MGqfM
zTD?xUg87QR*(6N@^dGpo-<P>G6cNd@Tfr!o*hO=PSu+~AbRWt@Ocg1e6r)7Cou|9_
zBTz+c1)9iiOfJo>9X?r>|6q(Nhe$>Z4R6PKYNEzZPNlNDA1a9!oQ)d78(Oa|)_xYc
zQWrxT#9D%biIuBX0|tB(yTN=M)Y0;q#|z{gUW;Rb7@z*x76xL+;9RNK?i82x@%xB*
zXZz<HOeah3jierK`=taGYW%dMA>Q|3R^)miq=HMtT$+`5o;0dbUx$se0W|LOyoG2J
zH|~Y<V1JR+9AuAC#gSZi{%y|f$AC$Tim9bPeNFPJI9)k<QW`fBRau@yIkn9=5*`fF
zaXFsICq>^4&@kbIis^_rs0qmeIde0t=8B2JvjcO){F3k|c=9QPF2{ggYid^4Gp-F%
zcC&WsXxJm_SZ9rVtaRUzso#aR0|U`ld~tcKXEe5E3n{%;`&Bwg9cPs|ZvRS;8>hXb
zn{NP-iFNp+%D1NlKwSsG38t(3tG7@<zb`H~N?ipiCp%-j`&;VVzu~mKYH{}8|BTBU
ztk?g8lEBFW91*sSGE<gCJgdcyLE$=*0caFR^O^!r>S-CzWV&oK%2r}t$I5Kk@R$O3
zmG(u<TWvV341q;L?*k<w20k{~jaMDF7+hJGt{^Ty-(J{5LWryN<78uekj5L$>dKQ#
z9phNm$<k3uq^{_;j9Va^T`E?e9<VyDYw)7S`=Wi1r|OU|NETz%zOYy4jTooOSq!gN
z)b17d-Oxc`4nAXWWnnf?DIFupi$zOPkkE*M`3CFHF}X(N;O(j(jIjZb1bs!Ql68Y@
z<ko*nbZmsXX_9B&;+&`eF+HAD@iF%8nLP?4wjwF|z@X&!i9>A9>b{F<7u5ks@vIQh
zs0+mBiGb)?j=CN~V!P{NJ9%b=t<cW?e+|APUj>IH9sblswj4WzCe<dEZGPp`a8<H!
zjbKN`3TRlwIFBxmKN(ko%kd<*PHs;0M&D}p`PTN>wbI70@HZF+y(LAk!&OPTO0#<%
z4G!`bdN1@j@YkU3O8?G=Y_b)>gqkI@W8#kz1z2;mFAAkAW>dPy9pRK&r_+j3T|^kt
zT`T9UO0?x}A3Q(9p60EIN+>zEc(#tB1{X53KpOxL#*eQ<=jF~Ra?b|7RFbB?glZ}i
zq>Z>49h@)M-$4u@w^szucrn(9yZ%Fo@pXdP=b$LzGrjloAy4+?Q9;0c{pW6T$Az#m
zNtoZn0RvR%iy5mGNDXLy&{uHEHJUqmTYa3N#1#-WYfoZLX)B%*jpwAfWyS+@jS7_o
z8O`q`7&Z@RZRAW-6r#o+8^Sv$)_ed_PJiCTW+%sMeJksV@-9*a^+Tz}vl)m#AAt6=
zdLJ}uTHxZ1u=u@+V1da6wt<sOKIX;|YHVi{wS5;;1k|zm^{=5dFeRUWqh7``QXP<5
zRHuzll2#l?FCGb%T1;C|Zyy+m5%+4-G>1<l5}PA(^h;6y<H!U<PLiBf-$cihiOYY@
zIsgMN4dr^73A#llWvB=5`$v|k4v)+QVpc+je-WRfJY6?X*TS=l4mwSL3Qn4-|4j0Z
zf+j1D?k?9V5m-n*BM|rz{dTIJG#cI~<gMav0&-r=3xHFay&|j!O__YeU5U%*Zti>-
z6Hf%!KGN!BJ4_PlqUH5Wc?Wra>j3-sINe%Gtqs~}m-EixpM3TAS!xw}OhK}mk~WFJ
zw^FF4ZA5Rwt|tfQr&&uNXEEp0lWDpEKIKX9sT!0?3V~@nUq-g?j+8E>vqBr(f22Dp
z@MQnJ4}|qiLo;XM=6zK5w6Rq349kV(-bJ>UCN}*EiZZH#z)nuFqxHmCBZUl^nQONm
zH|)c7h<90{dkBU)Uc?9&J4(GRYEF=xt)R#$F7Zy#x5*x%-tl#P)gq#lwglX6<<OU~
z6!h+T2J)Ezu{P$PyukZjhf&8Np3+X-HC9V8Fh)Rl9TQ;sSQFF=beRD+sJlpS2lsND
z6~@D!T-RXmC)8dx)>!+EUCAA`zVUSR$#Kl)5xT5gZy*NfcJYf6g*F0N<~T7^qlwk7
zyXgkEX3SwQWNnP@F+FiMMSTqxGuOjK`AXu9nPCW!CChWQp}PFD3xqYu9;W$ic{)hi
znCl3P{L%1J1D|M5@S&E2f)(w>ir15LE3SvIoN6TpSsFW@YTaRf!CRuBjhL-p6UQ@z
z%w#nLn`sw}7}}`ZD1H&JCr=(|kApm)Bu3qz?|AlX@D2LByGi<(W<3aA$u+bu80uTd
zAD`WT`<_q-`CtTTl3oQYS`WcjcLVROsAgjfSZ2_%XXv^oXtX+3tT#<4Glm(NdQ3cd
z)qHM?XVBNMS5{KR{q&EUKAtzPX>gKe5WizFql^LhM$&$TN)>f>kz&qv84y;k4yubp
z6GH7dN8_ug4V_$9zysvs-QB7@x%ar9@FQw2THaN;_<lgFw*=)7R^w57qTb`0^oBIC
z)Px=z$=M~x<>&)-Rb0=>s0r|Jy)IU6Q04hDm!K(~W$QX%|Ct^o55RU-w2jnboGn$_
zctkoXGZyL{MzsE>XvxI>5#L#0QI+O;;Ws2M|4IA+i{~RD>es*ON@-tAwGsIqv)+KP
zJh!O2rgsA^+Kibx8O|)YI$rON-l;^VqfiioF7XHG!pgbc%ROCUspaDVFQVLl;w*_n
z_DVvo)y@5?-C<t(Aow@!CcyB;X$^)suE^L6-cs(CxbU`dhT<gfo_~p8UpOZU$ryaH
zoag}JhzaeAS;v!s-Qy-BT4SZu6a+k8D)U7A8mnSnPdlCw^Q)8THZ6(elYb{XlTxX*
z`juGN_!~f11nmXpfdUZ0DCVxz53!p2vba`KYFd|t7IPask1fR6NCie>9D=sjPKEO<
zs)pt;STIAk{grB?V)&?*C61&r^B`|o=`2w=k{W&!?=Hgc(4+wD3b>+oAg-bShOnpa
zD%TK%U7BfpK?XywPkt|*AKtGQ`16_pU8OPx$DnXCHRf-Ss}97>*~-3EBG8eUlKQN;
zZoed>pKTVS32QN!f|h7NBYhN}tPI;jVYsY9`U;^?1u2JYn4HV;kkel`$eH<<#z@(`
z6~0)jDONM<2HsWXjFX*x_z*qKrx}iLjy;_Mw__}DW`?p)?%ClLdNO=2F2Lt9)<r@a
zld^3A1Rx|XX9!wLJIgjPMd|=$!Z-%@t5X6S;`O#+Rxa%;>c#!&-CF8*DuC$%e-%~`
zaQ6OF>I6U4?t05xtRVHytrH1FM_U#iP0zc(V701d>RGF`fpQGWC2ZBPX6R?Z*5sj1
z2VN(h6|EPG0kJh0W~;P$cp~5I&(;biMh{pM1RSf*{0nts3A`21X*tG;`aAdu&zhh1
z)PG35Co#Gvsd{hp5QKXCKpH(NBHDb^k`+l#>VkG%<p!W=)X3rxH%7IYm2AHFS~=py
zQ{r4Ei(~BB$oi(pX~%3JtfgB7)y9oTp0O!UzUHp^c~WvuLNz8Sv11<UAziuFxeCR6
zgLqXbJx%3j8y-Sec&ryZ6TI<bYB>op?qV5t%651F`8dW&ON70Om0^j8U}mQI9eIz+
z5gjA*3Z219b+F;ehVIhJH~clU6}pPgQj&ZN?QVpZ?fXqT(wD<shfYVLjWX6~=0Yf3
z-&}#ZOdsk%ScUVw7<B>~WKH|By;u}AeqT;^(Cz_xOG-pX3lehO=eYJ_!`O?)u%uoZ
zpXW?)0klO6iNOK1|4xJi_Ps<G3$zLzRD$+e$4z81Lgx2f=dI#I0_HDr;M{{@-vYyf
zzZN-gcAb8@vpBW8?B?6a%L`lHcnT~g=Fa2LFI#8I!Bffy?z;JEYAD#rJNp>KW%?yl
zDW3^v$s_n!1GGGdgDR2tqyou=Xh&$5x{cQ@U2+_FcjgE<^fxir{GM0Ulc^Hp?70FX
z4WDMS_rb5v4E||;5kS&fr|j3=xFlurFf$yo|ID!5qaaQ0b>FKPE|Q)oCBes-*LVrF
zWE<*Bb|k?m!L}LN+&>EpCM-!xr$i-il3MRC!R1323CxQZlb(P{_ZE8eiLMpD@AFcv
zE7e|1mq`m(Po|i<-Be&0i(r;Y)Ob@3yToK?h^QcCw6%7std6q^+lsrwKsvnbU?@sL
zJjk%~yYV_jddi_!ULWnk3#Twvaf>dkr#|UgyGd7r)WK-821t3bluLWgX!eXkG}J>G
z2iPXBuaUM<XbXbnx58B*7j+-<%nuExxJ>UJE{=xF*vOB^Hx557yj}hC(~ngPePb-O
z4p2=;!3;>rfwos^4;KP|CmSTu6w-_d{!OqpoPdSxKnwV!e${k<^Q%GVR0FrTVSM`X
zqP4p1@*PUr<CAd#Cp(1i8!7ZeO68B{p)#<Af&aT7=-R~EOw*UmLTLzJ@MC2~1IphA
zP=-Dk{YG0%X|e)W0GdG`&T7d|QLjFENS<~_MPgK}i0n+|D~vNa$1Xe?OCYQsQArQN
zcl382zK;B$mJ+F@VLCRR4tqp{iC2#W!6NQ6x<rH`Vy(gNLo8Ktul5VFYT71rbdJ6h
z)d(ek|39w%(lvVapr$K|!kG6Y9sz|!VP)-ACxqtr<Lgc&cwSIp;e!|nQ+-MIv#)9m
zny+MJbHbibb12qY8zh3?XNl6~j4Z+y=cQu+RZgy>cT0SWv$*S^uVL)97MwlG9heAe
zf+@npQi^SY)a-nVF6hv!OWqf2_HACwQV_K^rm~6rOaB@;#zhgbks?4?yP=;a{b2Zp
zqx1Va@@+o+2AV_)>}|O~cc)U#ctYtH6O!;-PWv;A3qKz7@|xQbyBFk_kgfUgN$Fo2
zPmpIxnr}iiyFSpHReT;mVm#sEF4AbZ98WjZuc4mqE+gbCNVzeIvp)ca9XyD>bgNx*
z(sGH@?B)2mblbkYgLvYp$8j#UaB=qB4uV@4Av6!JeYd!nd6lpYWo+8_x$fbw0*rRQ
zxx?^5q8vNW{hz(t`cnD+e)>zXvlgFQvwE5Tv+iN$`>X#6lr1`rqt|k!R?xvno4kOX
z>#Nsi$aR}De*1v&&3P3(5u&O7*I@VnO)-x##~d8pHurMg$6)k)((hNj*17+24cQc%
z;qyJKqu*fPj;rgDBk51Z^q*S*cz~xyz8QU#|E=x~efkvkLaIagvP&O!tz9hqitL8_
z=N(oD^W;0Neg2V!?mhNC&;H8Y@S8R{XMWgfx^(Lb*FuKxcY&q<8ML~v!f5B7Gt8TR
z3APf>@7d+x-02(~R2AYB*%jsU9rVYoC;N2Mh5H;Pg~toOY&`%p_8ScTm-=tbg_rJA
z`=;WSRKAz~c|-ST&5C!+Kxdd`|Bohb|F@>JuUq}z?X<JF{eCyK$ooafR?_$fgY{)E
zEU8sKhp)WSPZ8&jVt?%j;%5y$JGf(OdYDzPZRh82W2B3qnDgGVV)Bh8rh5G$L+&tm
zaEKOk=?4I)J}Go6y|8NMo82o4H}5Liyldr>WwyVqowp(0w$uL2)T3m$`oVSARqI6#
zZeP9(w7d0<CCPc;U;V~Fvo%WYlq9-()RZ3PZ(LR7nEl(fwLe~2c454I3fMHBG-S2N
z9(-w)u+6~0DB1KDb<Gd^+{fD`20sJ}CfA>T_0q{h^u?BtklhZ>4tvj>`PLzF?^i%^
z=}`rw*?;;TBio?)312-j8o^1wPrTJw|Ih0u8_#}~pMB(yoy+e1J@hV|()LvPF_ZqI
z&ywN)+Eeg<$&erZ<BAn9>NwC<V}L7h`5NSeb(1v!Qjza;CjQqH+M)mY&z%t6Bx;dj
zy^e<-{tGNbcz}fQD0=H9U>g2^%B=qHpZwq7_J7}DpZj3`KRi{D0Y$v}#C3MzBgtW5
zu1UxSoo@Ke1^++%gV+51+s%7{%$pH8r?es4D;+}IHX6)-$^Yki;nkI2KKlRh1*2j|
z)B6P2g+-$NtLyat{pfsj)#@cFlCIK%NWve=b2e-i?7Qu@t<UO!@mB!`vLzo33@#bk
zxVZy;`AxbMXgZbiYrdekZNh(h<$}!q=O6uUEdBb0RbiDOA*;e*wV<N%{lWDH-^DYu
zjk$jZ{dKRb%H7`Kg+W?ur@-WbVwK%?#sSSh;9Q!%bQE|YPw!Y<iER77wG@KZq70!Z
z*T2dC<E1~6cK`g3>eId7{+TWOd7_?bFei2R*WfpH4SkHIFP4bsHp-;0oz$2%(rEi$
zq5;8=I(=YRYXdiTw@TN{YOzQ$pSYA8u&-YK$2bnXsXS?Q0&N2v@B9AQdI~<)rr^(P
z(Aoh+p1{Jfl#KdE!MOZV!FN*&Cz|!C|3!122B4H|{fa4;1yNR_U(*4?=X??D9-yNR
zmfu0MWn|-qZfDmMeyOTiGbB{**Qy{gipRI0b}|s@KkhPc3B-XCuR%LOUZybuAg$G#
z*g6uw#P2ygMKY&mTqPbP1kyW+^zQ-NCuzOTHPQcO3ED%;Zo|xOe^6O;`x4MxwRkmS
zg=C9KB0%52pCukcesb)-jTq5$-%rRFGQr&P`^QiG7%XB|cSp}URX$x@WZ5Z~t{x|A
zdnoX<T$HI_1NMh+>9MS<*k(~CFRq$k4bjoa6uA??;j`xz^ff$wx>Yybu4TtTbsEJ0
zis=71f6_xueg11p6H^ERiDN6Lnx~3EplA*LjQr(XV3Ly(V@&V-ibg~~DQsBT1Sjoo
zG#I3hEYOYSNd;<_Bi9+!xg!mH59TWHVz*(lGNa1!Dwrl(+hN)UfNr;<c@L%*cfP_0
z!qee}69<}qMS?5lMcJoVk@*4+2vJ$~5$qG5N){G1A5@<N{=)V?hRfCwj#)h@r6}$q
z=8o@xlm2Xew9la^3@aGN!X3le^LJ+N^cL1t{noqukG7bKQx|tsG@n@UlOX`9WRf^?
zW5~=Iz#al_4<Ux3X7au<V_^!*`TV(uy2t0B)k=U7YycG@!)DBGr|I;d?qU}!_!$pb
z?%R9u#kd`s507A$e&G7H!NoZcG0CNo{xHn?UxVXln%-nW<EH&m_h6nldRsxv@}(CN
zZ3r0JA5sUsFBMqC%qE!l^g8W#V0EP7CtaLT%!A|5R@hhoR?5YZX8%mEYqS7QcS9!7
z+)Q_JJ%L%m&A-6w;nPU!c~3vepMAFaUO<k3Y4<fnhM6_4N0ncrEQG9VD8vU<3*})R
zLaZ&`)#a{?#|W6nXi?b#?SD%xZ&V#-cnHbPM;VcW`n6QPfNVMEY`Fjar7HxhG3dav
zOpvkO-ho_He+Aeh$(RC28Z)^Y;o=vnYydJZ)!OMEads)OU}-@-yE9-VpSA-HfjxwF
z@RW-?+>ogaQuL-ADpi0qOph+TO$#6(uhdT21r(Joje2lBE%yb1tZM?vP@m+YS$`z4
zQ@RqeLxSXe{I}lGgY|fC8SciSa~}vnL<0sR;r9jgAd*oa*`Tj_I#p!$IKlDG+oD?~
zf7YZmggy+aJdxN;KNp%>ySN;lkk3!d25L5g8{7L5IoDsmO$_)>Lv=sOhf|ay<}3Ew
z&>+-RhRxHj(=l6^D<@snAqU{`NwT?5L0VYH&<w{W<w@A-2X2qNl#P~Qr_z(K`O)Bx
zrpL7xBq}I5$rJ~zO+R!|1|C3bf;}42=_t+Deghptz;5+fMQL{&ibuX7FJC(dnLar_
z9d3s;PwrbqW$YQjU#Ov)l7_Luai@W7LDZj*&aL}LBg8flT4lUZKq${{1m$}yL!Vk=
zzKioP=O{ca({jH+o=P1##~uOx;aLToPi|+!x(5EFcHOrn;jI<q#B+<{!b`s;lgy&X
zZ{oI2NxE;=#g)Vv&&ITBOlW^dT4$HomdaSKRZ913KENR3fIe4{?6qsrW|*vge3KJ<
zQO+zNo8qyuJ}X)u-5l?vIs8WZJ<4l{`oOa&-Gx*(8jCRIT9?9s-|2bk$;x<(6CZ5p
zVbCgF9&M%mPddoPx`X;_2-C#Xr{Q7|Q8L!q)+$WwbI|T?r;OUkXBjhx0jGvtbt$yh
zV?VN#8XKJjRx$2Iz^X;X<`XtVQ_E+IqRgHZR3sdw{^`JuB;Li1PRp>@>2dc{y8B19
zd(m{b87OLL&S6UF8f_T(Y$)q%7zEpFu*=nY0_5Z%yNw4o<ly5K4h_jXD}aTRIrO)H
z)R2Y2n7*1T-)(y;e_n!X;|9<>{d{z$O7SdH-mnx(0(b0b8D*vuu>*klTe3jff-Qi~
ztdiu^AQ%5<M{MayU#%fLC|uxfAWFFQ;_R2qV0P(&#-g5MWk#=_`sz;aHPA{>*J`cz
z0BwtQ(-7B(nyx(t!cst{=NVu__;7x{$Fwe5KB1nyj{ZK<wZKm;x>+xo3gP!w6Ylzz
zR*$_2sou~`Q*VYtHF>rA&seGn6pcj8Okg{|<RwxhcCuEG;gF(C5?^g0=dxCNG6ANB
zHmiSxtFj3uC^e2}#tD9yh`f~HMiUl^g$sHsc=<=Bf^2&NElUjSshu`+v0=#Q*&zH4
zRPGro)I4Kgtx_<rrKbNeZms)?^Sw9~5Iow*_)|tq%_-_>y=7kx4JslS4b=ya<W(Ax
zoP(X8Hcm#wz4~yJTIAW>`uH;^xt180?k$SJ!j(4>vdsPZsUba<s!`k#-QZwqv<ZmY
z9k~<(`N0jHeJ%+#7v!@ZvY%Mi^HRV_1t}-GD62m>Vy}WjjeoSg3EAVdu95R9S(CKM
zaFS(B1JBV?pp|YIi@{x`H+xRZHYivio|?j^XGa;o0BA1Jky6iHu60L<861+L&mJv|
zR$U`(?gyA_Y(FRcObQ$$?k0Hh#2kNlqSVN*UD1;ib28qQQwOqVZPCNBK6Hb=Q4@;e
zgJ8-VWvkFg%?9Wc%n+)UL~H-k)bBf~-%3^P@As`UjzA^~xnCv#K_;G}bjBSN*ZC5y
zP`V6kRrF<;tnn`gTYBw|A%z`&k46S*j%fSt+b_6V5ps4CKJ+n_sbAeeiGg1tq-&KU
zxB26)t&MGM1F=JMA>vCc^Xb`#(}&jIjuO><i1Mr0ko~)`X422!Y{$Li&&d`sK8Rfo
z-tN)QAAKp7i4roy$0>StH?SK!Hsty`CHeJk;10RB4z~1MQJw$RE~53~m?XOLyjNx6
zm*c?(IzQdh&-AIpTV1GoL_AXo(=)Y^h_Qgz0xV0ln)T5D7dy+Ykw_+4w%S-3dDLHS
zdk2Z~0PoMu!#*mrsj~HO)peiVaIuIkp}B^I>>VCoSO2qDa-eI<KNp|I`!AZ;J&B8Y
zYMS&UuB||QyC!;*dLfiTuR75adu8bxN$8G>F5!h$H}hs=OUA!_wD-&{zX-};B5@Q0
zGRc{G0u*vvPVZLbNXXsNQI?Dau6e$G^9baggq#i<<~YlFn5`gDt^Up<ArdRA%5opZ
z2iHx~wm+vEQ$bux@<LW}x?4OHA}3+%hM(O}i4m34JHOzB)M;&b1APK|b}D9ed!l9^
z7&1&D;$t8l=6=}>(*<vF-Sno03|<^>83-DodFq{G_5xOg9Z0u+6P4Z|OmVS>Zw@8>
znW5`Ym)>_#egl%$)FY^~jAEe&9w<}V7PLy1E@g0nV2$2Hr7@6dak`3Vp^MM6W<*th
z4^b|M{jYPEyE7=hRp`aqo^tJW&Jbbk&zDG;UCKIRjm1>k#|D1}wCizH$V7}MP?-CN
z0RpdCi`V^3JWG1r_8w~nUaya#9S_i2U@Q=jBw0d2zzD}{5nxkbR0M7+Hfa@f^w|i0
zxp9}-QGiQ>T%SnUv}z^)q2HbIH`?9Lk>G3o>Q?ef=%}uUU<2ZBfqml)Q9{5Jj@u!O
zT*8(&(5@j)7@YkDT37XU>U0;u3oc?*qbV=i?ua@QvF4MG6W7iq2Nw7%E>|fU>~}qm
zNqF|3H_)ab=t@P<ss#e$DXp_uiUrVbHAv$9y~J3%j=P4Z`-!%KHY8y)3zAumR6Wsv
z3ZTelaTn`)%%;|&=@;B(2vA=;;$1w^yd*i(Jbv5;O{=5kALkAGl!m4|9DbMfAIu<q
z^t9e&7#4|mHe8Q5o-+t-!a_$uY0?-|Nxw>4mp}+W8oC>dP?n7NqK+uHWrN89BlO%o
zwjT+}VJAglZ|HHqmUV+eSU^Yj&M~dV(9|8cpnK?TVNuDw@qHQ+HB`pPCxR*0kot*?
zdOVosS@X`4QTGL{RiGmLzH&!IH_@tYmbNx7W*hPs;Icwt5Q*ymPZV%=Jl-Wsduw{E
zscZ+iYc(372rGM3(o)0?$Z_iM+kyS$E-c~AdV@Jt4ti85YAO!cLCC9H?wllsBOS$j
zEQ98W)ZeavcB1rz$r|kzv_i==@E773&w#WeMWMOi6J;}zHQyeX9{x3V5Rf7KA3W8`
zEYzJR=vzkX19j#98su><z|rCGL^fm!;{XXzz%`vL+k!x3hfAy+UJLg6cl}%&FeE+E
z66i*e#Db@v>V&o|<w?@fe$I~MGu6|M$@kysiz}rDX~tSxx8L^>6Y}uU6<U*5AmPqX
z1Y`&o0ENV|*7{dLM;N=%`3F+%8uS=7`K|kLr0NDIOm;F=)Tz3HWjuV2k}FY~<n5Wi
zq3_y6c?U`|{`#zlVgZSA^FiHn!YZn#HcVl5T2VYhMD~nz@k}{^URBlO&~8M`;3UEP
z=)oi(qH+AJ2U^wbn3A0Yow@i(G8(@ikqwSTXN4AIzx~7e6v|UmP?7>W#*n#pvX<}@
z!Tuud29`wqZ#17~FaiiLYtUzZkM|rwH84<L3*Lsvr=ehw%7Jr6Z~d+m5ZsW0zD)cU
zg&0k&Js#J(`0P$C2x}GXY#LH+ngQEfKGz=14XoC)?MiGR*97&b)%Qqx>+gQn`IV6J
zX`2RHT7CsWE>+IfL>C`1-Vinvwh}hLcZ5~B6s@OxjJGm=G3Ca2?FE;+byQ|2cMZIS
zJ9NnKqX+ACimaGVN8Nn@XGs@GuU>9jDAXFm3qTI?@}h!h9*TV0-4BtIloZKDz-yXw
z;$fypYU#_$H<s)A3hK3XfUUvh<IP}}Oa(%>;EUmd=jz$KTszRQ8h@sG@nErLDXpu_
z8rZ%J;nJg-6N*L<*3zziq-!DAe<*W!jxrVLu?lRbbK?G1^6NfXOu+*X<4U}mOthm`
z0!I%4kMa~dT=}3tyGlTIIPv<!xCI-@zEfX*z8HIlyps2Q(rz<vbs}1dSSduEQuEi^
zlL!k8`7-*|MWD63j?-@e=Gu1)qI4(ONQ2VTy(@xl29%W9FCR%0!&Be&-eDGKqfdd&
zdKEQDkjlL;ms-R-e)CK3Bv9jk(~oY!#X@wzSn@1^r6mc8?F4$9a^#|Hfe*k?2FCWD
z)O=1gntur9T}>jGQ(0Z9WPU>q!5Vav5ge)5a5SYNtO7ONS=zaElQf|}IS?I>zH30Z
zg<wGy(6l@eOe|j$+{m=w2|L7>q*uq+=zjFl+XKhMgL;}bWI2R4Q}h)YY681|L0O+8
zUSI0hhsr&2o|EmUq5BbBVZHWPe8s+paV3SVn;NIuMrtPQ=#A1D&sy5=SVR0JpiRPk
zU?{{4f(3O<NM{>o;$0DUA=!k6nPyq=;?qcmKvFLkGYK0LdG;)MPC+G@jVddW;qftk
z1kdC&daF%c44e|VQH*>}aMiSb)Yl;TiPub?X@@72eVrIdxkAb$#*vMoO^9758AEkF
zF|dgfeF~u*W`E*DBd5X2U(Y$Jtb*-2>3OaGdb{CM$mMbn%`n#0DvsI86wyZ|jNG}f
zz!!)#ao}>S-sHAszl7EkWjuTIsT3vir7OV&!+@vEul!U^BotkI<g;<a8l9&B{e=~N
zS4uhLH4H6Dsf>P;U_rg5;)8-lRvy89Qg1Ny2)T$_$9)R@;%fS5y6YTDdIZ^_Hkyr8
zCqBJdC<aX8tiKw_7cz6AscD_9G3$_tJkoW@`w_JYL=RU1NkR}Eu_GgH+;5SFY-q=$
z@eRVtM_dQ7<6G@fd0-&Xe0uSc$6q}7fNC^RE}nG<JYoPnmutFD$;`F&A9o}%z^jq=
zMI5VTm9&|8ZPO;mTUihxTr?H{!$sftW;k2a*=IeSgw0`-&7olQAq9|p>XOUZPmfEf
z-+9!GC_b|IEOdi7cN2K2HH=DScC*`&Vma$-9X9~I9o`Dh@~+`QGrB!+j1bLzJX1w{
z7h6P>Q4a;e6Wv_rLBP0Y`VOmTCe!+Wbkn_JAFN4YYSD8$MiPcGc=8|V3-T{20WPnJ
zN(H{0=P*MQvl`9NglRYHZu#IGK8U5Zc%r-x6e<X$rZ1IAPDfdxNNX3+@^@pF#Tg%b
zKFHSSqPzUs1Oe)MXZksT_3=q(o}MsBuY!4MvhF75ux2x4r>kb;%qACH6)|l1sM_Z_
zdeZI&C+$LVk|web`E`nDL)$2giKONq9P;V)|3+8T0=!ZsmowCP5Vn#kQe4_BncU}6
z`uGLm5lqgcpTT6YT3ct*8niyZ$zlf1*?pz@l_r`9+HZD1pG{i_2K}7dn^=a>71$M+
zfsyZi52Guh-$X*e?WDYgD3E_!^L83*=5_Y&`3X4mgy&N=`5wqrHlW9m^T~}1Got!w
zsRJ*Tj)As`=cRdV#2KE37!}`2utXaXl43(u?i_I`_2b@_K5%)BBlZG4zS;RtyWsOT
z?QZBdQMIJ>@AZ!Tvz&cq?_Lgg)F2}5>SlE#j1iI;#Fg{+L*+9IL`y4Wz-zRro3A_$
zf4p4{j!58!5bSWCyB{j+zK_^-mt5_?d;;~+Zh*0ZG)(Tyc_4b>BI~2hHu~LLGN+oU
zkx7@nrJhz8cj6>uwf7*$<_vOCzY<Js%l<|^>9D0HTK9-xkIh_=TG5<<<;?^A6q+Su
zt!9(*ivuRKU-&O_J04CF@JQKnc~3`(P`&ta5Oj*fmVda3Qm*s9XXT{QwN`1s*s2YL
zbEZU!2!7aUauc%9P0G{T02P>jlCtzTFJ6U)ySR+dV~N;!!nQWuUFb+rsw;5Nbn{k1
zCxIO<&#$-$MAeq%)xQOL#e+E$e>W>qG8lZ43y^NH;5$@Gcdxwm-Qat~|5}|kI`+Yo
z9rjFX+55m~tP3@w)5UwR{?c^b<AM1we*xFB-#6VqyouY$8GLl>O_8FYmme*P6I(eQ
zue_xQJX;h*S@UWA;ogAV$GdO!tl9jy=_|&~b$Q2cIvOmQBHI#-p(Ch^)Z9wJ%mxRa
z9muCN0kUk7{O^AalBg+Bgth2N#N1<4>#WEEB(J)mmJX(|bHP<H+g|zh%}7@tU$Jx8
zC*O6`7o=e#x<NEk3pXfLe3m1cCBilh1FWQaj5dsI5_g5AF7|axtvPOlRgg7WffZyR
z5sG(09-n1H{bBrXY1aiRJ?Q>C)+#vt;RiFH)b4uT>+q5e_6V_?iMo?!vyecAKOehV
zdmMcSGXzDv)p#4kY40oAX0&ol8Nw%nGaV++0OS=Urq!NFi&fHr(^vk!IZ<vFD6cH0
zT##d|sdg{8Yhmnlny6;V0xeQZCa3S5BR8jj-b{tQRhfiSUqJ65A^^hC&ya0ExkTgH
z=MB{B&Xn#bzx$e?DV_ruyxN688O|I1By1(GkP2F3Hi6Jr>V#sM?IQ6;5@h_KQ{j9u
zWI(%{5vA|BzIo+>^p`5Wk?ua8f-H0q48__rfb<3p2^0a&I-cb``w@zbm7681AHY1V
zwV?oO;?w?VeaWNv%MzXHg(sn#j_!2C&K!GnzK(O$EoZTADC&)#rNl65G(p-6;H3T*
z2-kaHzLGJ!8V(WxkTjcPqG+(9T6NJa_3klfgQ5yR5)w<*@qRC0jjN~9g?caG526+a
zHzO2*Y8e{cok|guGMB`q&a`a_Ev*ZP=dHw(tAvlJ<pQotbCJB|t(Bln%{uKYsN8eB
z&e!Bzc%<KxJ?A%M{`vO&hP^-j{@sD<Z-UA7#01Q1vJx|sC#UCt0fD3-uSBc5u&X({
z6urh>+)ePoI|!4%g|EOE20tK^&#}>$aIM^yN3WDdQ8PtgXt)7+R3?s_A=b7Fe}CYv
zZ%Z?|vy-?}YpVGIWd-Se0r#Xdi?CdGZ$0A7%mHXR<$Cj^W8aGv;Ffec4szv-McBrM
z>sm4ZI{hTHR^<fpp3wj$iO&~zmElk)&DS_VU{CK469V4KOYNTf12?*Lyci^&VU9LU
zsMGohE~rxW7t2KN8!v4<!DAbPVCO|?9!R@TVpmdGyFb4c>3naL)fLs+<ryNh)f*4a
zw2&F$QCi1$Kb2WAVzOeM4Zgc}TpBMana18DoAXXHC8kPjSBJk6D4v!j5G`Ar!0=E8
za%G=P(kxnrlUbJN(IapK1BlrlX#_D|&G})r0U_6Xqp`V*mmCjrC6AHPSu4SX1UP<6
z)MTq;Lj@R6)Z2z=&X5~g^Fwl<A&8CuLD1?y;f0xs+T+?CKmy@W5EO(sG@`Sob*0AH
zoM1SO&viy<HxZ9;^o$D|fFgDuu&XDA=S~v$X6+SoOylW_%Jdb6py2MS2+$eQtcK8w
zGF@6Hy=exZ*5_+3fDD;ImI<^yjmV_AQGpzl_(GNAM>ogHV}-A0^=r{q!Ltz)g%B}n
zy`b(h3#$CE*m+|r_1wmCAdDJ$TdcKgmK!tl+w^~8Z2+3ouD;L?R%eH&dN4LNo@5lX
z^nh?FO_vm|;aGu4Wu+<`A|t=Q|NH>A%V!UUl9vEn+3_cwj-BRz&8JoDirD4NoS*Bp
z{Mwl*V!b}CzKVjRpHZdk5Bh3Q4zdRNc90m?H)i^x?R}{xfa<~rh#d{n2^>X~&ZIQO
zPcgnAp_DW_{X#Otv%O7*^$(L21tCFjY(YII`n=Q(BFbvm)Oyeg3-;Q0-e|dkHNybG
z_i~)jzD_3Y1G*zc2QGZTQ+v2_GG;woTyW_)dk5~=;0))CTxyJVb#45vY<lnT9Nij?
z1~yM-UA&~5Q5UC98L`{^rSXh=22sYM8?aTcamomx6Vphf=!oVMfkZftc!Ow4kLz3h
zfxPC3_-L^lC+f36{kzmLe#rY8WCt;J3~PZl@Le2uS$gZD444v*^tNW5$r3F#6kc)~
zO`44zLTfbEv|hafD%IG;Nc1mxwk-`A($CD4JKx0%^|Z^R#}{DLJ;=dw8Sa|i266jk
z+zY*+B<4np(5*PG^7PB|oTKT8llma53ouhS1_e4SH~T`;BXso3*wOdC61*&yY0wS@
zWt6d3_qc_U%QJ3hsiS~^6IDSQuJaOtyTR;ERDox71<jq_Re|17+T-z%3Hbfjm&ct)
zPKAZX#Ug(Nl-0;{y(pK`!uEU$8J_D6>_CcVwkY~WOGR`OC>Uu!31U%1FOrZxy~Bhe
z1<1rfH%WTsbGTJefAbMF?RXm+4fbm5sqrO)o^wR&xXUqaIr?$RGL{21HB@Da-rjxk
zyyVkC*0)BWrW%AE1pT6`qHTk=qrUK1=azW72>}>lT6ovB-ZIZ<5y9qjuYAgW;O)ZL
zfYe6G#5G<#%W;bA0P=*!(oUxKMIj+w7`sHEJIs*Jo<3gs^{W~7Nk1tG;5L5K^I0#j
zE4{SNns}O&-c0H0%RNLTcST)h0)Nj}tS(2efN4qcJ}2k|5W-y1rYorswo1DPjB8!k
zydrgq<TSJ%Ruw|zQw^<GFR}7cL$Z@`O8`FHi$AvB_wU|`nIxsoU3~~%m`!h>ie5O{
zU4`PSsaXeMT()W*dN*B(v3o;}?hcPxA^x^$*aw#*;dRv+9$^pFQ+z!DVJTHmvhm02
zs3`!N>NVayys7R~;*XethCF&B_za$=YLV_1%_yGOv_W62*-RZ&=je(FE|XHWH?>uH
zM#!2yC6ng1k+a>A<UeA*;2>bz3ql){ok@||v{lEcfk$A=U;?B1w>HMDbDUQ7wtmhA
zO(<=Mh6kR@6y0@bmrTV7NST?{1XHOoz~Wjw8>Zk{Lj-XZ>Vc?^05qc`qFZ7o5EY8L
zS+?J2@ukKf&z_p;0sej&F*A(38}7S$j*Yb>t(>9t^WeQ;lwz@6wJu=lO@bFhEDS_K
z78JZr)rtoQ<p#SqRQA3?hB0^zod%-g8y7K*qFu?q(d?w|xfNjPy%4K>KZNt?ILg29
zv}|)zfaxcmIZyT@&!$Bx!FAEi>2VlmXcKx7e#c4DY<~R~Efz$H1Pw+fpojrpJl2AG
zeXI*$`(cl#0ih&AdW!|UDI_!<!G@j0C`g%*F}U07Tjixf<ol8xO?<q}DvI`-iy0AQ
zTDd@>?K&1{cp@@+E6*SmVi4{vb%9(pyQ!|EU&Bn5e`dgvv0&6enTEBQ<TWd)eSCj6
za2!et^d_JpBT##6NV|L7V_1tzGejw*rqUrgFbg(<bfr;VS6g=#fGue4y3%AI1|BZ^
z0<?>L{9V-zj(~6)L2Jp7W3F+|_zTl6faRCqzAs7Zp-fwVrxHMJMNfaDA{*wiZNS|M
zdDOhcDXY5s%pxHo+JR8y-0X|hpj#Y+92MyuUnQwN_Wse`15)3IeVj~7yYiNEB>9tS
z+sWh<=N7lK%dQppb@LinEwMA-flVTh*ffztbJ2ba$BHmxR_Z_Cky_9N5Q^q3GK3U!
z>i&sc2ubUSwVN7ug%|h?-CeD71vNrmR`3}8>hHh(*dz1w`~Vej@;yuP<YFeDMde&A
zHgLg!qv#Rxj=^tm(ht*cB!=D^C<pNl8Y}%PmIZil3u2?u3b3<Vpdm*<Dni37<s9Vu
z6!J!yu>N0zJz3q3v<|;gh1n0kQ#ltZMn}i6OVHNNlnBR;KWkI~=K*PSm<+5n{ZyZY
zzTf2wbfZ^|0%H%b-xfd)PpI!aLko~Sp_mMolinWHcS~i(FX+D{aD9iNjj6!Z)HGRR
zQ!MBq*+K`AHYoTcB^dd-PQD}j12mZiK6(K-K5_OSz+>Wu_9)!*qRkkT=V46=9@9Jv
zD6|SnPBK~mfVO?Ib0ToAG$+btjb%B{k=o$aXTy-UA`RmZretOlR<lvMKO;E=>FCZn
z|E&4#mGC<ncdZ|26=CBfPo{z6BPU;3OJPQ^Ru#+HI)*UvX~P$T_~i{~F$sP`D1Z~g
z2TFm7v*1Rmis8GDa|XjVB^ysQN~oay4vVCb<HC1htHDwG88zfBfoznZ$?lfcd8CDR
zO=?e+Rr4Cf;A7?luqUo_*V4cLJf(aO*h@wj5?dgL%Nj2#T>YLunAWcyf_}xPRla?b
z=y<v6%##m}q}+4oThfnoi9a1x?76QoK{X1Mpx1IjZ^?Sy(1kU}hdiNrcczl~6o%ec
zS4Gip7>x%WR^P`U&l|MN;nWQHHcAqPmn4@lC@G2ZV1nK7U+rbl&Q3w;gpgrp?92`Y
zCO5`Kmp4bwZWCuD^Bie|JafGtS{fwAiu69Edl6tJ1Sco+*ll^S)|IdUCCW6crBoHE
z4P^P*ACHVL5eqOzV8&lH(pCnP>fZd4pHlA<R)1!%^}YaOBk`Hbj#H&z?uEc_087aN
zu>-KWE*7a3raq0aMC%mf)gN3|kyej_04!f*D|uyaN>!XK&3D+BXW_+?G0my&Laya7
z;N#zJojA-HY>{D_wRRdu{qJq9Ghqr`9?cmx=OIDCw`Gjkn~0-E{c?m2d>aHV3ff|1
zq5_{ftPI=b35-&=5kmpl6xwkGA%`$S?||~$79{qD7HGRo*8*)avdXUv!?ie1dxLF?
zo!KI*3lzEThKt%YIFQvMnoW`ezHcqclvSZw$R{!qo1>*@Hc6pV&xVp&1^|(HUOxFl
zf||AZlEYlI6ELggci9%vtdXTXHLnv(igMkC=-WY1RbbcnY8?<E#r>v@ly#g2Z8H8d
zgPP;eS3vXac^<RIIhr3e%)2qil*E|PgD9rEs=V$drpcYtWREu=M{{~2hm2~CYEzE{
z#$DExPxM`-FHfdR3>9Gw{B#h7YzjNIUem8fC&H0pK_JUAiW&$6@+b*b3hAH-vUd6i
z8pL<mig*Oa%1K7kTgP^lqp{)bZ5_5FJ?Cq^!z>JG-qh28ZJn=k8<fQgd5&6gfBmIr
zzm6ocoFHrq8hE8*N}5>WGq|ZG?Q`3PwNc%<a|2G5L((II`+K~j^6geTffNp1)GNB|
z?zlUQ1F1Rm(LqIVA=ixhUL_!!>3yi;U`8k1g0PVq8-$ecV0ttNPM+?@nqQ)<A!!I`
z*}`sQA`_ni7k8HwRoUf1m{YQJ%04*x{oN{b%A;>}oc9TB4;a>8H!DI4=&@lJ)s+LB
zSh#*nZU;J!oq9hL1&CW~(i7CbJH~n#3ap^g<>Bq+B6(VV4u~WC7H!@&M6(@@H+zCo
zP7K5j<Jb*W=moroV!q#iKy0Y?_+QHD?PyL0*A2aQOR3*w`0nPQ{)}$(+@8ZM+ONuO
zPlGJ~d3EDu)|x8arBV6A4=I0{AKbYOZ)su(B2@ohhOZhdYy9%?AFSzhYkId#`+N(Z
zxFLg6vocq#b-ew55V-vm)^bMa`Um6jf$g8lJO4E}K{Z}><A<$Fmi@I4T#$*!<b`)Y
zajY{qGN=r1zIJ=9`yZO7-^=q({O5^0L}o;CFKJ%0KkEGVik(JoKht~cnd=GrUQYdR
zA>*FG@+AEJb8-oit$S~{=Z_E-dHWZ~j9KbE#%tzlx8${kF_?sJ|NQRs?Z1S->EIXL
zMke^oi&<9<?2G@rarS`yJK}U@pBW~IxAuo0mUPN~+-tufZ+9U;MIu+ck7q`f8)yC%
zYn(N-#$uO2|JUP}==dvtzw7+F)c&pcE|<&u-0ip9cgp^<*zYFUirjo3G~l-8pI6`-
z*W(Q{_iT4C$o#=z{ohAN$QmH32BNoWdES97mfycD^cD;*`MvP!HiJ|H17`!_|LH3T
zSyB2jA7k%wf@<Wp-mKi<=H_L}niqW!CU;_wK;DPA=7T$5E=>wid2g9G^c>%8DMH*0
zGlVJZPUwHI_wM0Pzw6uZh-@Nbmpwz2N|If6V}>M2LMlZ}g^(m66T{e)JwqymjL4=W
zZEUigFose#5k(nhlwFu1d@wV;ck5a2`u1DL^8Kx~p67ku_j!-?hvTSZeD3>m-J9#Y
z&g(pNJ|h(hXOyb$6^}l;#Rv574PNae`*XTqkEPt2kn|VWDkF1LuFXV1e%sP$G{Mws
z-Mi9MC9B;X`;Vjc>vWMwVfD3RxjnFLO%Z&#FnHUMZqxOf#$^djWpOoNzZPPh=|w67
zO)^a;Xz(&0rV3-}Z71u{#n=~3l{LPLwIe;D+;1wK-rY(mE28cq7HgEg`+9Tws++>Q
ziu$)tm)S6hBjORZ1y{m(AWx<o?H1=*A<lqdnNa7C2lXBwMa}+cocjGqqtBU$>qxZU
zVyO?==~d70-N1KJHrH}%ddo5e4ZdX#eSEi=n1wBX(Y@Z8R|U%$QbJRVFT=y{jB%&2
zw$?jM4Led25#m_xMo0Vxl(IP;ozQ^j!Z|W}ntVq#2C*#Z)Q#AOGjv8r^@xV(PK<qj
zdHvPzn)}m33kN@&hiiEHc&53Xvx95q)jQG=uP^{Uf6*WB%Ti{(0Hhtz>YT7-OE}(B
zPLduEu0duNW~kJu9C=^#GRf(DpMbwa-;FQc{ZhNlLf5z4e81&G9fLyR2AWl*#Yiae
z49HTdoP_T_bnyc1_InD-ux0ic`x(R-q}H(QhABl|rehq-=5ez(ZorlBU|d%6zQ0Cy
z#hp6Z(0hp+-@ZwI<bLB-+9?1OQ(R4$Ta$;W;I8Px#3$k`!X!b-4CovkB=rYPdmhO`
z*`#DV@P7K4N<H;Pv@K>pz+G8^Sz#@_N=JNOVzw@Z^nGU;16<ISfZ8;<@<99Z_##J_
z(N~aXRyr_P`oiUlm(lfJ!6Ki^MZc@Q>wm0ReE5D`UpvvcGGW4X6Kw7j0W;4r%Qpm3
zJvLt!0(q~hae5FkIH@PNeUJ@9iUu?fc%aK)9|vK?ARPeGF(vPAWS!-$e)=N)(DQ2F
z<D4e-66ew*?N-)<^;_R~l~rsjy-;wn^WFqF)i^4X4ctsbi;e!PhMo10_lN@KP#4gy
z9`xk{dWJ@l)sJf|3%zAC;>4({yLyh+d!L!xxux3q#xCFZI1Mtdo$%I#v)POg!u(Iz
zR8bd~g@oNd{@OH+7bba@B~T@B+)PUv={ieajkRMosvFw;>x>XtIO%wZLAZvYsS%Kd
zjM=8!87uX#<_dZ%6hg_1!Q2O*JC`0b+0g9V@6@wuY+0YV8!nO8kjE}YyK5#=pI@vU
zamK`HL7rqF9F&&VPV>8lmgPuKc~bD}8?>PF9|5iI1%uvdfAXVw3BbN=@NT^IdFLgK
zY!i@1D=`^cYwvsatxyP{I@Decv$qKIUERSU6A}0ejZ7>{s9RUz6iy5Zz6wl@-<4sr
z4lxFH#h>rte;imHv|UX7ou{3%^Tf`PyVE-*jpd@l9-fq}bdG@EI4|H!yCd?3`^qKQ
z>97Fm_~jiT+qm!LNJcK|D<ze1HN(d(_Zo*r3B***(8QWpxHiFuvuUppac!*ugoCeg
z;VI$&rXxFrO5QyN999;!w}C>s<<Q>GAVozN2BdBFPx(025qex%{AxFgIo6)R_vV6I
zpdruIPpa9cN8R|MQ%!kt4u-V<gyF{k3Hqk}@27<X>?#2?U2I{2Etmd5UVC?pl5%RK
zyqi*U^jyk*4?e!)Hoji&BUc&tPA}3d4WDc&)D?G@_eA3_8SiaM*I`itpr1toW~p*9
zYe`$aO#s&1I&)Uq@TSnPXHt@A$7Q}soc!5-MWweF?*IaIi*Ps~P%EqicNj5q{AvF0
z_`TzA?*`J|ZFPjL%4wY{N=YfhDS7oThDYO;6qP=XL$QZC`Zgxjb9AEov*p7!!a{y&
z0FFBKlBPR<!mOu#fch0@&{Y=-@?2GKF9haG#wFP1MHKTIYAa;LlyiOt-5k=$+E1W4
zCZcv(G3HwqYtUpM7vr=PHG{lLw+TMseU=e(kM4Z*-i1J_%!yAXZ>3NUbo8=hh30C&
zPuTlaCq@WtwPYk?dKu`WQ6pH&jLcsNh%hdIL2L%7j5)*Y1Vb(E9CR<w2}^AXSAyol
zRxK<ZVPl;kJW~zyR6k`BV^B(y;$_$BEJsWno1<;Ik}?n9FPaiPFWWvz)Pu_CQi(y}
zQUw7&dBq%jOr~d?o=@^|&GlG8a*kmYqwt#Nfjr3&N0w^CP9{2jmvYLs&9)U&oXvd;
zp;5K7dg^zDC+9M^aercYGJ9GYexW(G!&gd+u$QS#c&;+eb|Agf8#rZi7$JJzf#uv+
zt`JO4q*>SAbDg!ROL#NeTxma^STG@LJm_p4m@)hCAmbfhcOSlLED_-n7D@)RHlTkn
z1W;lwq~59l%RQ0&6z72rN3u*9HnB~~=vP%#QE?lny{I)G&?BuFZm*Uy;fW}TR>r`L
z%aQj}_Wi^C7k5dtFpf!Zt@!wXN~<F~_b`cGCNrfd0O`;)5kQL;PVNMe39k!y2!&EE
z`G9I0%bAH8ITy=tAkX2HZPZ#<E)sYNzCbA!CEfJ{=p@$w(H`AUuxkgCMOAD1vX_F<
zf`H3c78kx5z_nvBdbK99ea*v!X5-H5t`b=Xs~V!_?HCKQEw=Ggse(GDP)11d5B-og
zPzH?@_t@=akMEBx(fgmgD&G~EuqzgeikI(6aDj~X#ZTBY_d^y>ZygRj!o}cg@#6)l
zsS1!gj%W1Ka43zeM$R_IcUMhD1|hIo4bOwEYD8`AsYn*20BgIx>iqKqwsDUyma09!
zz0RY&t|rQLX)%Ib9=?s!y+l$dWBGz)Ja%9ou^d4`U&qVUc}QIgB#KNhyj^!d=792x
z7RKomLdQ*<TZ~4YGQI-2J8QC((TCf`1AY1ak4}#Fc&}96_4EyOE5^lIz`}v}9YE$Q
zSQjCe5kGz}S1HJ36$#K8A5%7wrTK`pua|{p?j55j>UZJK37S|Qg!Buc9Aix4aYcy)
zG<-a>po36+3JPeJ6~6yuK%?Zm<MYllXEe$->a!$>G}kH`CbmI^S=2<hHl&s@f^#a*
z5pvOY0tA-9W8HeCwj;LR#~4?UHig*c5zAIM4|dSHe<w~2^vfD5XB=W~x_67rQHNqT
z{i3!%%RLEU=5rEYtF+a{Mh2cxju~vFP-Pl~A$1DA+;Q5c6f$;Tz!Oh19Aoe!;*h2;
z$Dj}Az_dQeC|az`;B03s)<2xsm<M?_2iMrJJ4(ZZ26Bq%2$9K*r|8A8=1j=~;lw9i
z11%kd0&EP`>O<i4!7y$Y=cR7FwhOyPYBDVQ9IQ$2EA-!2=*B;;*wj;Dvxi-(cIPDZ
z(`V@!l{a}2XqyTmv_rqe7YKGFy0ErD=0V^hgy#<565i3th<5%EZj7xmV<MVn6GQG5
zR?#)&$OsYS8D^0yL{&|l9JrVsFibCC*}wl@Cn%g)@CiCcq41Do3I1v<NlkivM=h;P
z!j&b;zIzd8S%P!vLK#EqM-?TY`!LXe;Lt?kuG0jzw|-<i{0G#axhrE!L;Ns8aPZ5-
zfLihe)|m$_v{hh!r%_;|W8PEV`C4`x_job}sL&uS0nV?vcnJuiHYh^TmXHSxEdwk?
z31puS%xNN-2y14-k1~c{&~1e$H1nXPgHY(>aihiiBUz!b7+IVN^YF8RhJuoNf+yZ*
zPD)lTA%yUaW*lX#4`@NILy6-y^_KnU{L}&eWKG*bUL<YOo!}Va#NXGM41*-tb}y8^
z>pIi<psZ{Cu#4Kr?Dg2|NDoFHIwpK;%92e*1F%IDv2iO3OB_DGjk^ovgfoLQ#}wcj
zeiBHE;^7w-{0l6+hi3&aP|vZhKxbbSi=OfWD&@VL&Dg3|SKVIE+C&={bBBh0mSf2m
zm-AJ@FIu)#<PUxv49~>QF0Me{Wt>-;o!@`d$YBZeGBP|CEMw0mgamdZTnyjDz4bby
zf6*I=P|*<l<15q@ar!Lb$83C6<^{p~5T<D*g#d)DH?Be#<)Z1%og!2(j=VL#t!5kd
zbh6IkKwl|pGp7?F2@J1^FxD|Z&h=wtG|viPJ;_dQF>-+u$a6%#A0)nUBA?!DTnPRe
zY7d05>RkYMkgR1?;63BL#OB+In|gv)tuCH{q6?tzGw);WIt?y%eNcj~ubM$`FcDO4
zO`Q7bVL<g1r}a0Mln@BkjGm(n(KM;+;X7JrrMp&o=%qz1zH(%HXtimN(GQF}l%p$c
zu~_<`@xI0VFBXN)xHA^8u;c>HCnI)MbLTabNPjpG_h%B58o2OHCPgd+aFz0E*jh#I
z<i}b92A9;ua9y+ESQk0kIl{0@s3~e2>BEmKnF{K9>Qo5)8q$KMz-{)Se73?nBNGh=
zmtZ1usdd`$N2m0JqDaqaJn+5KoEE|~?~w(Xwv5d1_f;79E>=)M%m<{|<097Pl|#gh
zx?33c(vl|o1cFO8x;gh}hVFT~Oi6$(Q6ov^!X=FTowUM;p<jEfEjP{+7+4OY;}CGp
z7BpEJX;|Vtpq9c?VFKyTg8HRqID)0iOv!rUh1$V5o)%p6<s<Y+&`QIj_pzRw+^Y3h
zd|1Fyb|pZNI<F&y!=+i4Knj^a^B8NQ3Su=!`mZ-AVM`pKku$))UJ|R)>Pt`78TnR~
z4{6dhuQedf*94{^hj{!%5$gw`fzFZXuS4;L(Czl4i3j@23Gv0b@Gd{l$JKZcg@Tr7
z)K{bw*Ui5w7mg4pu(2#^fCLdjbfRG+soTAWC5yE6qm{vNJiWewWugO4=YgWBAXe|!
z1zq7bfM;V^XqrZVc?C27gsu0cTcijo!`^RGct_2*XL#_TKyW=9uzVPmz|ZU|Xe*c^
z+u?%xS>lXD8t5Ar@ZktNWfG#C?Vu^mq=oH4_uwr?qbroVOm2#+UXOCWoaG0WiEnOI
zY<ZRszGD*X5Q(z`!8G4i(58dunJCS}`s3Z%eiT<#$bpv3+hZ5qV)X>-X}ygQozXM7
zGP8QDSGT17o;W$vH-DVZru)aW$_m1pUhyN@><6L5M3Ue3IzMJ2AUQ06evsi?WeMf8
zBG4EmM~%=NuEl<c)0av@`qSI%Q7iK;&(0h9O-pA2H=}o!%~b<ed+U_l7$uI3!`JgC
zjh>YE%O1`z{BqJe#P8KjJHBz>{^^PlYCK*9eW5djTCUlo$p^~2?W_B6f}mbu%Xr_;
z5%t-Kd4&*U+2BwJ=vc$H6Q8kDCz$AD-7<MdZG;;2HL)>Vv+~0NRSJX6KT=;06gQ_I
zop(xPiI1=Y>=~5$JZ!q<4e201`1zHK)dlVTK0aZ7lKBsY%<&$oi;mAuogCVmv4^Q!
zS#`<A=ThYTob8)~_qTy_!9H9aynZ12$2wa1VHz=lensN9pc#TnqAhtI8$L+iT8gK^
z#W{U=fwBfT?j%#=+kJXxQiImZit0+n*Ja`>r#&|Z@G(e*J@@jxQ^zwniaq-Ydpw){
zK+&0E8{40=@nvs=IExp$<-zDfe<B=#eD7lcKo4c1VnG`Z;<;aQ7LfcBY}oF7J4Xt7
zI1-vglsyIQpYvdz1r7!|QXeW3!&HtvV+^HjjW4wDTh6k81=(X;PgXMP@FF|k-7Aap
zWgX4Ys@U8iSC1Mzndm6{na6u2wZ5w6Ma=TiMB|0p7%!=|8Y%wwe5;5>z~7CEU|F)u
zkXl8+UxT<2n5XdBR6#H3q!go4Y6QH+`JE@3Dh6bN2T(-1g4@YnAlTyoB{99zTk}qs
z=R(2eiI&|gtwN_yUYQo<MlQ+qH8=%uVTlZHAu^5-2h<itx`FWIPgwME61*Zzyfs{%
z;g_iQMTaICT{^WGgXbUgxe_dEksShbCJZ#n{bZcZFIEoeBx;|RO+v{tXcINJQ!hM8
zUJ?hNF=$D4f;V=GvDAQ`dy|Hr6B9$8Hl|-GW4<{40cB#rjO6G*LE%cxz~;1X$qCV_
zAvN-a6jvwe&D0?;)@VfGKyrS~)`5BkPls=W@*Q8uCJ|-20qCEj3}&Jfcjm(aTgAD%
zK`6X4T%Z!A3HVOIOu6PE@%IgyCxI;o(q`2Gi?#*Q?1IGj!dbe);^V&X?V#^Lu3o$I
z)k;|uxX<)n2&^S;d{?w5`9Y#)bog$T)ia>D;Y`>x0jOo_jON3>XxpBhIOXAK3{A2A
z!KcBAZs{A}Ts&!nWN;F<AL%W#)?K;Ycb|50I5cMSn@-yb(Sg>l<#v1%$*n925y)ZD
z9MS^YktXm(_pw#L0{>!4XB0*hr870)7$@GE>3E%^!|7_!2A(YhK9+HP4=$uZyqd8T
zhf~*#`mxH!kU8tJ$OD^3IeXr-^zq&vPd;O80nS)%J3Y;GSWN7`pzCYiND@LxUnNO{
zjypNZ3UENvY#A__C3g~Jza>7vhRoB75~avPx=i0&DRnjHQdFyY>SO>8z0s^>3bm!r
zt$Y1Um5v2t0ptc;h2hkJ6u>OPt}bT#eZnt#k^pxX^k01?COA!E2AtsVQ$Bdfa(o=<
zIjpCv+sGXR<)Us+P!9kq$Z1a|WT(p=(ToHyduML|w!=Xg``tP9FNXmq^*!1b@CIy$
z5iOmcRzZ9;Qm+%?EJNlK6URf$Cnfi%fLQH99!ItTiZ8_N>j_MR^8k}2OcDwxaQR}L
zY@`l=D`>dtWCPEKhV2s^ZjdZYAie!*0u=~xD$5##ak?c)Y!0$>>A?07>5AOKxH`rx
zn}!21t0d;}M9tVbkFAkUe26kAu}K6E3qLG4wV%0M>laf)iqv!2-)CZE46#mn6n{=W
z*iX^w^z+h~WPw6)R0>Fi1aX+)GT`Rs!_Gl8ThThB0i8&PG1Vf4FIP*#>5sq@(Oe6f
za_50e?e+;HYFxO<5X-cN>5|AYV`{{d`IJC!z|oZ1m!_AK5is(g;`w#UF$D>(KI{_3
zh)4!vEj={hs`b~Oyr7p!VhI$Z`pR3I$g&=lMYOQ9^UkE`!!a|HE0c2k7t0D#I@GfU
z+vBGDbTcPurte9;vTD=q%m6dM+?JvR6-G1WfUqPU+CX}7F*euLi=&*?1WHSesAT%A
z@KlH+*?JT6R7lLjV44db%{D%;{_Je?K-u;81}VhgeCG+-dp9uplt8fc`!$iEZK!;P
zBV7mQ2k<dNoE)PwA@Ci#=?ajaEoXw9?1B>GR{wRqFw9Ax_ysQ@u!pU)rI%{9^gBJ)
z0$ryh(IDz3tQ2{V6Fm0ESH_1JqHpoQWP?;br`L5`1*ou_4_n69@iF>aIl@4-RuP?a
zygx_f8S{2xDX<GH237}r*D(|loX|{=gWzUSv@kicj+tf*>r5`x`f9LzTA9WuKl}DE
zRma{GapgR|DkA~WOnf03JA#NLt_zo&L_b$cdd%`;U?__44Enn<Fxq2CUj#Yq{GgMq
z0xpPI6jM=;Zb9vdQ3yS0O%UGlHH)lE6>^1wExdL67c@73C_Nso4+YTrDP@WJ7(ouN
z&wJK|J`~T?3bA<^Fd`bHA^#D<*-v?7Z{qquP+s@S;R5Y@8Yi&kO-3Qj9_UD%Z5fo+
z<f>E&I-gzN2XT3GVcvoqVJggWv585DgHL-(B{s;jwlRZZrz7dhD0OJ?P@nEkn8Lsy
zR*)7}S;|y9!RSvxNxEP|X}qx|-bO{yGvPb2Zxnz${gnc`-^NKvsb?p!wdPEdM>Yzr
zaX?_M0CW*5s`er6M@mc-SMB;Za=6owbC7VgUub|Q0#q%*uOl|jZgO>QJyYzRUihpC
z@@zG#Sc;udeR=y$ze`mQFn~ZG>lvx;*~J=2fU$Q0I!4re+%ena6}4&ZGL{58hjoSy
zmW2iL4SIt@NHg8zcKk>y`#whlcOI%{ZVuJZZ^FnUclXbIo<u9+{6=h)ab`h}fnVoA
z1%3;moE=ZAna6&@vIjUr4aVJ^jZn#AFr%yq4%F{~O=1|DwgV~|Ny*5=S@!-2^J`Hw
z>I*dSG=&n2eHt{N`!tN)7wppT1fwcOxAU42nX}_YPxAmOO)sUk5KH8U`N>+*FxSU(
z;XzP4lYRv1&SS}T>%n6&0(E?d#$PR7P01idAIZ3O5vlnIJK1dN?W!rovaTVX_~1z9
zpn7w>5kRg`)Z1>zSklEv>_pC!225G;wqFL#|DMY-01pjC0V0-doJWLi%ImDBb41y@
zJ#QFv$}BuK*F^<-z9XzNG((;JizH5mwyA*v1AuK}Z7r5F?ufc;qjy4WWVqw4UL%D+
zsi+F2soeo8FHM*ZILE}kU3ZJA7{&Ik0L=m^kgvM%SJ|A0NC-Vvj#*-&DG}SfXPP=h
zHm60*qdc@=_z<@KfzsB)relScdglz~0;$!h-%JniDxw2K8sFx6awFYOrv#*`d(V+8
zFO^uyKAqQ==@q?uDk;iLMxMRnZNOgHvmQy@N-El#zx)6L+S*i9UaA!5!qzmIZrqu4
zH2j;{YTIF}*z)dFgPYmuucmKko4)4CL>TFOYmJo8C2Cy~@H)UVCZi-T454D;&s{5C
zcjEQDGV(wXkTlAvhw-F;TxTo6_4~-1Rrt@Yli?SoXbTyjw~d~&yA+ZX5oW5VM&x5H
zCUSs4Veh4P{4q)%Nuu(nqc=zK+wm)9N5R2v0m@LSkg?5{gXw$n=PKV@vJUMEnLg(l
z!mw4ige|k{@xNPt>CTGB3$}VYN9K7|ba~%#p+aBF^#_#bcGY}5?(&MLiV4Zfao=PN
z9OVQ|xR4JQN4bc5y|}L=Y|Dkuv~u{B`5F^}*E(qKZucA5QYS*<o<V7`+@fg#ILntk
zrAV;`iL53nT%}hIQ~O~{Oh@0xi{|SaGu7k#EXr?dx8f>0(CJ_UzJPujRy55=GuDLE
zCUFPR{2H2?$}g*#Px3Xu1$-+hd1qcSO0uEu2FpC7k=ee9l{SeM)l>h1x4Rv<`@tSb
z#wiT0APg{@4;L^7%^~AZI$rD@qo_H2OK+WL9?O{Xp(e3$F?{!jX^WKmv=_Ne%!wt}
zEks-U!i`tv1e1?!+*x_oFKAP=UiJJ6%!l0r;k7Wuc!srKJV{iSn!wS69Ez}1@(RA$
zR+Podegt~9(Ca?>I4-(MGllDm!rx&;MgXQ0YFU}7u5oVmkh67gkKB=zQSaxii-}vJ
zf^Y0+HB33@$T0m9aqx%jrC5D3XEWn=*`AD&@f(vv(tQ;g+z#pcnY?!c@_h#OWegnq
zP|!0GGL#k?T5x`G<M#62^1<2?!H<O%)tPEAHU@MOO0tB3_!vCKRRj7otQiGxhbzFy
zaWSN)?j!)&g;`ga9VEtTBapy{lZ%+1@n;#a$$IyETDzaz2Hm=c3m=7VE{c|Nj<pA!
z8EP@QK33oLqP<7ZefWfMX=X+o${1%1r9EbyhU~%3f&e7~&P)hI9VT6yW+YPjLS_kd
z=FCMGaXKRLEVI8US>L?p$5f)N5SGxKS(X&28Jn|>LHA}>w4^-Cn~<!$G|{vjeG@K<
zouxErzF>3^X;f*bsO7lghORS=s^|+ibJ|AdQ!hY?t#n4M2KcbV_*NL#-U-~uJ2VMg
zEfo;f)+Q+R#P~w%pc~%6?`gybXJ<r>WE~7wg&0u!uT6BExG`uRuo6WSd`4yxM`{O4
zt(!9~BNs5!npIfqLx5`<dKI7d(aTX%vgX+I*AE|(cH8=^zvLStN&I++F$G({Q+S7w
zC%Ht!wY?>?XgZiV<^-wx(oXE6*S~<Y_?k&E1D=G~7#hh|-<Hub+fsZxwAT8JuXiv_
zI%uQ$n;e?eH`n0d@5v1DMQLF3pkGcp%^aIHe=^8vBW-Zm^`N|W1oC;X5l*w5)}&ec
z$R%E>?EPVL7&H~)cBb2xU%CAWc$*k=>1yvBr^@4igE!NUj*mMHj3WUJ#TY80S=*pA
z6gy8bml7&SlIM>b?Gv{R625gNxO8a9+O5zsC@A<!rDTkteQ@yA%bVwCif&lv7(wsA
zZtl7sLNoeZt6wBG;<*8ZR#O<uXWnz+T|s>@Gd8gTBMX(C>J_wBr$Vu0*^c7)hv#>8
z@2t6!mUp7nPu?j+3bsi2=yL#QTG+1c1A?pg=U*05;+X-hLvqZ{$Wr97;w*J_%z9uC
zG9>z;oP@wqFk&uFuBRYFBzkzFBCDV2dX30P_wH7287Zjkn|WNmN~&#8g{EE&3HFja
z5TE!)Y+q@{5i5ZVbfn@=sFp?onk`Kj;9NI^upMxul@Wf(@Wq{mPL8}2?gOSm0BQ6a
zR(IK<DKcR<(c!_gnZ7<mDjP5Jkf@=MmSq^LG(4GfEnHbq19D&rwxWe_$9FynY^331
z8#MY^QZ&)Rp*sWfwk|%+Au(AG!(yiIUw={>{$cc#uDy(#o0wbg0)9|%v79Mc3ObH3
z?1yNtQa=}l3wx$y7_d*FL8khV4>+}llTI#u@x_y_vb~x(Ta%&d_^^Bo)my46<Wygk
zl+&^4FW25%`S|M|=34Pv-D*Ma<YLLO@8EsP2J~G(D!{N_yZ~C~3fKu~PrvH}HeJjr
z3L$P$(V!Ox;1N&z-au=aoj|~${}2=#wgq5|ictQlgG2B4z$^myM2Oysb-~0+k?06D
z1wd-y`uIjPdbl7Rkc|&l<9+gR$Jpr$7-8(@(0BXc0yvX;W<SL*xnVo=%Dv%P!7r!U
zJw_6J%}>4b4&wJcYh9b~>8V)YAGo+@T561X4GnUE0n*4=%#Ti99GYE>_rh~S=H>|}
zbkQ3iG#x`G2thuUF`*A<FDkt+H<2P&I-Mg5EoJCSU2gUE5wi~RN6yHed~juMiV%+%
zo!!X_Dslmk0%gew-=c61sHuqW^kll$>Vcd<)Y~bg;IVheQp)rLk{8nD@x(yGvy#b5
zqp~=a-m=FF3J!J+RrhxJJ$Z1GI{{NiCCmd}CNF8k3ExD89KhWS%n3(gmIb=3@J$~%
z&8v=!{Va7`=%6kM0{Pf8P7CKQ`ysfpRxOq-;y<C^H}sD#BkDi7dX+@Zg!B}1uK=oj
ziUYcng$!M>2h@*3JQ2b!;5UQhU;%Wp{Pph$<{QstP(C3z&Z$|z@Givv`|p4EBR}Xs
zWKOwe^&DVoZ-|{nS$--bRRseWDuA8-ZXPuMy<ia_D|8R1`^7Zz{2ZwpNqV-7Z<wEI
zA<@kNy@n&FNFs)8<6hwhZOibVFd}pzWVvLq0{m(_uq19U;VkXh#SGRi;<P3l-=wvO
zfG{MFRn5f@M3yRg5X~qj(Q-H)08$8DwSBXy$pURy;D?`cIyv!+ldPn?|DmZ>&yFOG
zSm2w_azJ^L(E~~j;KRWqUz>qLC&9mDUZpY;@lE>dtm0+jAl{R`^sxbG;tXL>=Q=)>
zO`9)H0*o2(Vq<sW{K20z!6B^&w4^7%`_LK2EXK0bL8}_H4_$>HDGgu$Yb^t+uH#+6
zu9^0G#!g?g<cQ&abV8Q+XO-aUfM%y-#=g3~{>93b;K+ll=mlt<$k|$pxsH)9Map>s
zZr{Ra`n!=bNjMjl-b@uiYKEFTaA@2^d_0jk7Bj5`{K{tn*}l5Y)1H=zb_wmrYLZ`}
zy-B{h&`#1b{pqWSCX>CM>^tI|4JSvo|Ad`!c6`ydD^TMF=r51KdjSU9BOjx4u|bHY
z=Hfj$8ImgwQ?Bwo6(%}Oiy3LwC6i8`@fGN?zJ}sok#qr(h_3*4&}yOdkHC9kb{%UE
zV+HVKr5fSaoiu<7vj9txG2eJPGl$3+d-Z-Yq-H`Kn=oZl-ixz&Og#?*TW__*7o}i(
z{AEv|3vaXavTMW!wg@<X!a<zqz#;ENc0PKfFdXx#m4atPAwIRQ`d^v!{raQ;Os}FZ
zH$G#;@I}D@0y;RHH9`-2G|Lg2zVrSyYqqSE<Y7DLN1y%f9=;0^88Q@|PfW%O&vIn3
zA1XS9CUTVV->qA!L78EWy5FNm@19=SuF>arU7ZC~vw-waF~7!f82pA;UIJ`CML6X2
z*hGrYozm6neRd?YPE>;ND5&;o2YjUWJ^kOGB3OMxvltok(LZ4Xd&|Gwd%I1=dhPJV
zv7BmviR5Z1{y{&uC9kzTX7i!DS`=*NX+!%iJ{a5-#+@sjE1<GE{}a{^va)WG{tA{N
z_`qa5=j8-xMPUJZ&40Uhb$UEZI`hm=*v_-a)MYibhp#ETmtcyY82;-{VWZb~oasUR
zNMVDYD_pz~G$!2{9u;AtPr=V=oX0GV{e%@PRtzu9D(d`%rTH8ImoGFMu>bgS*MST3
z|F*A&+_H?R$qg_dG6rYe>=b7Q64;jIH7$M%OfdBAq#p+A7@90EltsI2O<3lE-?p?}
z&iK*XEwevtg`PxvCS*OfUuUb(W#U4QXH4vUYO0|jY?yICRS0IK{~5C~#m6C}6g+xQ
zzHh0Ge|#-KxAk#%bmL{6=*CH5ex-=>wp&a*fVw7_X674MX(90ayop}y0f_SJ<8FUU
z{s#?|o{xc*_Bvc=?aoIAw^}zmkqC#m&s{CiT1zAkc7Qqs((xw_`0-2je|wUAEzNt<
zZ|`Wm!S~zb$STH$n~sihM>i^^?zR@YF8`YIT=Z>^;*0(8^=%z+zG4HVD6U*VJqg4l
zfLEV@-FsZn@<z^c;0zD8cj&97(7`it>01x^=WM+rd^C{j6?Yd5HqN_^dlC~vnp2yg
zE)0Twxaa!2;9KAD8_K3<kUERfqr73-i<8^wyPS?W-`zNRWcS%q`SG7b32&U#>@Ht}
zAIjZm?c4=RaZ3`~nVn6~#fJ~pF10!o@}Ie-M6feM+<9^~`*Hiy$qe>;%el=FM(5SD
z=RqXpyax}}3Uq*x;K|0yNlW16Q6h|t{`9*@;g@5531h$i2mys(p4Mcu@XTD{lt1}a
z<}uqdEYhujAsk4$2QaIEN=~;VqFIX>91a@l;<Jb_#uH4g7CZ^)ByvKn0nZ1)^7=0i
z3L78)&o}>@NthJ4xcQpcTfr-)W@p2+1}876^S|3Z+^(#6{o_xVj(rzT&)c4c#bK`N
zc36A1)ub){G)$!10*1TF<l`LljOWx?a`FdU&Q`5}*E4mKx+1>`olrI%L`6XP_T@LN
z&--aiD`(1J-rPCi-FF49dLf0o#OmVP=ev&euRrmS_tBbUTG$H<i_xOTq$LiXV`u@B
zCUQb7e!{}RxlQQ36km7eDKqkGYsA^JrUSbL#9@bxvV~TJZ~YS}g)VIW)-QV$k;~DB
z@hP_HQYuT$+|tsja{?X0zc^dMyO3t}X{3NcxAPLMo%rl;mYo*@TTKF5<6Hj?s@Em1
ziH5)1dCRa&A}i4;gI)a-HW5~eHGxUkTl{bP+O)79N5a_I@wKA=UDh_>dw(n=Q^jfe
z_+=jXhh{%v+MK(s9g_jnLM<xtxN=(EcxU=nT=jk(;loafmb3nm5yA(MN$YeX*4gjr
z&PXC?E2ixp>mcy4{fFhnwA$Ku#MAz(TIq8w`_;RAv&x2BL1oaCcI2`xcjbZC+^WBw
zxpwO{{tfPSq_gc6$xD$ENql$bx5sg>_D|GUTr|4OXQFLbqSZE7$bK8Ez0PzubM;P)
zum`t+3|)mMAUgsks(%jwI<=}V;R-4G=BbwVZdg%-_wU9U@`%M(Ce^uLP5luciweY|
zrwFj&w3Pj(O4$+rIwl7bJBweQkYX?6IcWQ)t#fCaDSR1<T=DVTUawRSaT!cr(it~8
zn&SpErv>l^XlTJwC`mbv-(AU4x^4F`D?jb7S>vQO*8;3-eX_A#UwLA+UtpNU_g%M|
zG7_|3Z`0a`s~)~#8G{X|sC$@y%lrw0d%b!OF@Y-T<{oEr|J|J7Jm%n~>8H8vJA=C^
zf_|NE9`T}Pk(Wi+oEI6nj-+L6&-R;cyGOs?9}QoUmWGW+x4lv^fK5?pon&{|OxNL)
zQXI1Yc*Eq~pRm-liCTl%B=;a;a62z!%B`-zIUB%f{PmXq`+ov(HC1rJorIFc3AJW&
zADj`N0^~2k=;#4+gU(a%-234>S^Lk@uSD(Hjagp*uEQRIo)eQ^g<4H?axNM2yPpv<
zHCJ9|KrxHu`zoLGMi_3N3NPl38};o8|7L!dOGz5berwLB9hoh}Op7w?FojJLX=7yf
zO#Uh_zK;2;oHs<3cDv7R_A1%*8zwJ~kXndwZCqb+v!83SqP`)*K7d88tkQGEpDNup
zX>j#R^4Ive2Rva#8xEbkK-Nh*;Fwb6?`q`EJnoT}K=|B-zAEr~_hP0tpIG`0titpC
z2V|7EpZ)!$=%K)n0xiGfCQp_UzE`K{!~BWU%GsVz__`do|8e^~da12RIwEE-kAG6M
zF#L_7%uRX4d?ke4Mp)1k)03tnC08!`44`psyDnai0|$3%YAcmuIFUUcfk;G)MnAgP
z74C7RbMe&Y3){2^)4NtzM%@&Iv7;(!RW_@4h241~&d`^%gyi4wUeclL=N~hKY3tvU
znRD;V*hV??y4}2uJ+pf^*K5ACi2awi`u}uZ6hO9sq3JLEK(ID}EU<kCy<m;m*leo>
zZWz}{*$7rhgi$&4f+^FDxDuuRs1p7Bo55!;K#_~_&v}V3+sgtG(L$N#xp0~^CzzF;
zhr*AlYArESLOhYfmqpf?nYBZjtDpEMlY;oOpq7tZbK{FTDP7Ed8@-g8oeuZTSMuL(
zs1`Y>>K=ImW{iNGfDR6clndJF9{F)j9+d>x2};Fw!$D_Lm(`cDM_ImCTvy^uUc9d+
z{xK&H*Q_h(a(&hWvHAAY#jgDn!Jjat>gqQtW1PL_2)y)IVL%7$*E$h?SZlU?YY_b@
z!2fA31zlb{JC&9cXh=^@+5bg<#@#Sgj4PJ#nY=q-o6M_D8EKX5(X~qqulQVn(P+4e
z65o}m%WdE#+zDGc+R3^`u=&)Ab5kh}W@&(qR%#cXaZDeiFeNFs_wPUlD6vP?RGSC9
z+T;%&wi>?jT1Lq|9tp0NIbxhkc;+N*vIk7H=f1E3{-H-7Iqi4om-u8j?`0?<!(r<M
z|1_#2+syxQbwYPdsy2+z^-pF6xO}5UQ@Lx+4Bf%b@)ouF$dj|zvhX{-K`X8IGVlKR
zeAJ=4b6=(38X9_CMbuMxVTMX`yZJi=+|TAOX~T#1UOr?}m=sBVFq*@6A?*h50oZo{
z7PIzqI3Rb7dPrLKu(1Wd;hyM{mr6*9+v+a2<X7^Zs|P$~rXqiAdh^fF)J+va{%jrW
z`%6fvc3IS#qJpzJ7mqG0I>pds<K@TX)21`Ox~;X+*Okvu=E%!O)}eZ?Z{1mWR)(Ug
z-s<qOOhFr)D?Gvhfn+K?&GR)4KPt6*b><;)SwJ!CMG8c*w443AsCHCXs}Lpj+xU99
zJ`{o2?TA|~7p*_`jGduH85Y)IKhQ~9c(t-Y3Pi-YUHV=sZUDYXJ@xskD9GoOl?kMz
zfF8p!?$nt5B4i$I5tSr&=}Y1EZEtgj7i3^75ngM@v~b<8SyOPh5<Rb8iGTi$e#R^b
z?;T9-SCJkMc=e}IJt~wuwjXy_=j$7-JC`qa&7nh+gkYD=Mo)`ouT?ut<pTHVrhX`y
z&E^Aq2?zY#o2M0cMVvWv6Y-N;pHh$SE;oB*h)wQ`8~e`OK3+3FTFd|HR@&wq)mz#(
zR8%$@a{h^vpEo?~bf1r^f4Q4a1er`u|GE!Leq=h)ubP&fdP$c*tAj8`K%IJta&VKo
z-=@;>T9wYHB8`-f;$QP1TzjCf|I&LV@%xLk;~E2X9+NzfbjNe_<aPEc$H}<ySV}9k
z<wi-Y<5yFP?md>70ABzYQ$OhH__02hpPnhwBfj&r43|vWRmDT*Dmj0(IRQHKuSI8&
zX3x5r!gudImXir(dGgQ=3|3^BSPttaY~cg`$3DGjJRgZp2f4u$BR@`Tn5p8ezw2aJ
zBFOx%Js<ri-92k{{rpe-JI2njePLle3>Ux@-e()%pe8(C#M#0p)QANLC;pJkXo?Oc
z%tz!M{GQCb+p82i+dD6L%2n3|{MDkxnJR)G1r_$G2lz>of<AS88G%y`PSE>}rlS9S
z6*|5F)S&uLpnu?kG+^f@{<Y$AaXA&5i{%X9$3N|Oix0=IOp;bM%fgb@denU{_8#Th
z>Aswrqw4U>OvW{0oz-_PwS+WMKiJ++f!ki!aGu{w(n24cjZlCo;t=x#nyV0zZr`lC
zSvvCe?tT7ILJ9oJz_jHuzlp`kVsJ3p!`YV!KVha$uoT1l8@044T&bdWrGA;=7>>G&
zrhOLewL2FJuA<L=x%#|4wa!V5%aC$_kGlbW|KV@oTGt;~jUCVBcLH`i&wiQSq}i_X
zdTkN{6Ht4~le5DX1z(<)VuPZ^A5Up*y6JwVsE}#9^k#!bUJD+PToE%v9>u)4Z`X9m
z?b5)S$KBO3U8HR+Ep@-;B}@AwW}H04%2xy@qTF(648&x~PgtIE?goc;(Yj}6R6QK0
zjpKrp14Ovh3}lc(3nn|>t}$r|bPoCgdV1<7%tGU2){G`Q2pk!ft)_f`!yEr`o&EUv
zZRlQeFx~lJx+No2QoPI$9eNhw&U4OU^s1In%2gR2_h6nN37Pxg@VbB%eIqb0^%pNB
z{~KJdW~0Z?ANbqK($)W4UN6BVzs7T>cSdtUL2`~4XL<ecm`A$Sd!4&xE}~8OWdf9D
z#<Pt_<ggiEao!p)@o4HFz^N!3+*GF?0Wd7iYn{$oJPolmUgG|rFbslyIqN6PJnE0=
z4}|^E&2^;bYy5?g<2Urqd~??+R?)7O;fc~VTseNrz6Vc#gIM+c3CnlS6>wW)Q{wf)
zjdx}#@?4I>wY=JLUr9XsuO?DA&?GcF2*VcLxRKL<UiqreiCqt~+}U*tW-WtqSBsZm
zY)wk<&xPFxg;~)a%nySbPdA<l8jWPPt|tD3xts<lFtfLu%Sq<G2wCV^luD9_yWKDM
zB=J<U$!%-A$4#ogVTb$vKf6eed4G)?I`Q;|cFE#BvQcVv99Md_P!4ZM&aEqdo3-OF
z0lYH^Ukw5CU~MY)FK%wfW4!ihaqm1GN9U1|5ZN1H#xp7slAyB2OSIx!iNjCb#ILOD
zMo@{InlesYOoWP#IXKuqGE{Dgf7`{SAppy!t8zzD`MSE-dWnBv*xUYy{r|U?=x-su
zNkf85>c0n)x4$HD7K+$Ra5)D}=28tuot^sqZf9Li7q9Z797q+S%e<n5*zt6)1%dyG
zPYk11s<yD%Y3!}s^YpOU9lMBi!@h(4YKGGZOYmqEegJ7cc84$%_^#nd4dC5zg8j~Q
zUT{;GH&rD5-Qm6BwD@MwuJU%roTkx$Z;pHDC?Pmw^Fbo=@C~5@2~>3<I^T{1253eM
z)`t^GS~kT0guOn>HT=V|4&Nj*QntbiIw!yWg#CnVu?KZm&lu9U+)r3K;K{OXnJU69
zLR(qNIkKQ$<HtD+t`Kv_5dZn4|IE{WqTv6S)dH^9py2;s7q$y1Q3NnIas!<>!!50>
zD86=;B3Ap#nen826x*NTe<Ehfe7;ONuc7VA#EWM0uGu#E?1)QPRWaT@sLkwrj%08=
zE1w?&-NZk3R10RQtem@g93~VvoZTlN)o>ZtR}I8GKJC$}(fFizF5uqFG3hTky<EEg
zgr3QxH=0+HDxM(Q{IA`?4W0Mxa7SLG%s?H6Emn!Mvrc$wH3|9(Gb^H$dJ1ecwY|IK
zam!Nd<;bxn!YiR1TfK7zH_Jc2CPxU_?EVS6t)+MXm!94`O6N9!Z8*Me_WQG|HW$Um
z22`!Af5IN)MoS|54PME+A$!L)gKc6eI`8OvY@y(apH(g0+cVv9^-FE#wsmf63A?PR
z&T=i0YKZbVwS0N_JCHMx{7%p@?D!mzbg}dN7OC3(PQ3u(kKb)L@8EY5F88dq;WItk
zZhhHrHP{sCo6VwI58a_7ZFb8Sk8}SL4dLn%a`4Bqr)*bgejG#lCQV#%WyKS!#-6WR
z)h>1?r76i!bRv^}<O<}+Tid+NJ^&;4z?a=bM`K?bnjAj7TPFgxW|4Sr)KcI_@VL=e
zj-1u`YLOJqIQ{D!x-#=Icg=yoGEdyx_RV%7HRar$h0NX9UHdO#P0Sj3L^fLettfTO
zV~x=sz4OPJn#*S{cIT|>>vVa~_(JYm3b0GCA265^SAxn~<A@Or{c2HBdS%(WYP**4
zl_d9gScg`&kY@q^-`?TY)uE#<=&P>=tDYPV7?gm$rrTdVtFu*Z+VJi3bh2rZ*5&ru
z@}v}Di<7svY%ok`yQ|zSG&z@~D43S52)Dar#>0KIPzvw!;&UG$z`RF3f4I$T^%)7f
z%ZffTt-|-j!ggEzfW97x(Hhn2&djWk*F9JCg9oz%5?~d78@+w=KOWabuoUaT{TT-m
z)Ycsa7PGe``zi*%7Jhy}o*vM;p~`JQxulhIlS_9^Y6Dk1Zk*!YnBu^xxxnc9VLZpD
zrX;T@z!Mo~=Q@+M(TBME;+sSJK@<~)gf`ZOjLv)+ln@OaQ+ww_+;vJJ-Ayj<OWHS2
z!@(5)<WJM4;%gP%A0lrqWN<(=<=1mQ&Rg<ocLF**-COxk=Y6M?>3<z@y3|kD5NH8w
z*!oLD0yciuL1^DyZMP(*?yJlBxxz5T2pFHK*1k0dBeGT`-(Np7@wBgcp7;9$vgeyb
zY4-46Ugz|eXQtw77Dd-o80uAZU4A|9^h*W9{Uc?(%Khryjw|$Rw=1Fc;9Y9>y_{F3
zh@F|g`mo9{m02rSOE(yk;PUxHW$B?ev*cuxRjT;6uumTL<R=ElF6A@0)zaVD{;???
zeJX|bNPOdSiHPdnd=SHS8{2Y9xS9f^%Y2L2)hc#7>#jj6S9~F2j-v7!e&cdTcJ^sc
z*xG7I*Z-J+mz}pH_i*M5zf^Y`S6yl0S!*nIJpUBOqvS6`egMjHR*}ELw+;Ix`OD&%
zJncctPuNl^dN%&o7Hjm6cOm<=)S`HHCsKE4l=@V)+f-Y{50<;B9^my)8g?_;W)@m=
zLGKB!v39$b%v>G?jorOxdMdp(_<|h|Wvx?2;H+K#U3A}G!%Vk6ug2kOna1G-J{}QM
zy|s^*gTD@rhl=hdVy6SX6%IXD)OQOGt8O*O6?FaYc}9f*1X}GQE|ICgGxD12vc0d5
zOM{c|n?r}c<jZU})k*T?mYFaWw_M{jayempT~8#vj#)h%u=4>^L`CS-^VMk;mFP6v
zKSr-VG?zEA+QIv!{&GOh$KtJjw#C3)*4mnmT-`pU$p%bAK!ZGX(qg8&y43%hMfa8t
zT<>7t;jI60p!`3-#j2o=o@kxr{WX~2i_;0PJLHByH|^7{fUW1U2kRB0u*{vFDh%g|
zGHu*>P$EEWrOi_3P{=!Jq?C#QQZaWpil6uX=A{nX%zgm48gHfOThyw&?Fgunr^~$<
zhzG;ET>(VR@(v0A8kRZb`^DL+zgv@QSbIu*21!at4+jGHM#|AkYX#*xFWQlw05vg~
zmToiW1o^7+++kaX^dzBS824HSzDREUmp!umsMB9=-bq@vcSF=k%UxM`{p*&n=13wm
zetTW^cC^)BK{f-9a0{5tKT)K#`fq_^J1+U;8o$qN0ZOXea71<7>2G#AkvZDCEe+d#
zao`dG2TrTztb)$0gyHh+%7x$ws=*ZHDxhoVDi>}&@k)E0&gMDfofu1GQk1rFlu-h(
zD7~Tb85`}EPgBq_KCwr83F;7_T=M^+%QaJe%z1Fo7d7DA{u-C%b>-@f3pZ>U+~dV?
zX)0|2Dvwx?{Ij#SsREFu$rGfN0{GE;zp~2BU3~TymjOxjF66_B!Yr%d0n}WM|Ih#V
z&;0x+Hva#xE-HHe!k7B@SWn5MxXYVC7HSY|fo5(qI49T&lF8GZs{T1TQzv590+L}{
z{t0SC{%x;=5nGao+T!E{toVMbsV<n6NrWo%H`y|viuvVwwvvSk*EigovoOxW%EdJ2
zl<dgPLn-IqUfwf73Q&F<kt&1?|E3&$*R+Ed+tw&QrgZ!t!{f*9tWohW<@(pT58VGE
zs=saBZ={g?HLAVm|ES*-kNl&WO~k)b=@eZ<t}S}4A^b0EAXQmooNHIL*ZnJ%0|_pt
zV7IGhaSyo=-c9L}&RRlru}$=cpB+=~B9Gl&i@;Edd?wc}DYhS2LA;DTBBce>4v0*D
z)#>p5@fvu2uE1~HjuaVba}kj?(-f`LGmXoZD%#P}z3$wTT)*|r=Kn(+ANKE1k}TJ_
z1qgL5cN6y@`M>fkCq`KBHB~cs4I2(_{Gki8R@sE8P7R+Ezj0<-*IjsvnkvKCJt<Xt
z-|x)3wTc11S9D-&jWln~)?faArCw$SY)_1IMqd+m*(Wup-;PaN{e1c~_YJrTENOTx
zl1;?FTDOIzzr`<)XpRBOg5o2m(5El1@jp0??7Vx(6fs1yd9Uu@lWI7T_Ri(^ffp3D
zi+yS;RXyMQw$0OSzsF^50Uq~&AGv~SQ!Lk}60TLfS+fN9zij7Ri(c8i=6#gs9}ykw
z<-20;+;xMs@xM)Mn>#BbKc~&#Hp4%;?N5kwYsH}HT6ONcllOPPZfoP(Y{j+@+sLSu
znR2Nv!qQt{zfoq_Bntjd-N82%UD3a-_9j(yF?+j~#|x1TEoE1udo9?B^p=xr)hnH@
zp4Gp-Q#I)kyU1Vo!LG9~_c3m@$ef}A*vYj5_jh(!${K_HeH^-6YiWA!Tl3Tt`A0qL
z`~J`Gy60JQ#A~zH_}4h;&DIhQh)|tJaIn_PfcMi{oc|jkAXnhOun`FVJq~QgllDjX
z-)DdW$G1{QfXxs{Wecy=?OhW9hhKmUA_09rYHareF~l;QfbR+2V>F-SNis84%=#}i
zMfP4upWexbg%4Y@#5Thdj4Wet)(kY6R1rLFjiA`_VyU*z`;c6vUXCkEjnr7j@ZG@t
zro!N2ps#}q6gC1!U|%=@7lz^io6wQkPpU89&pdWI>5k6$JGOrhT%JRwA{J)X;q2Hq
z>QtB*YpAr4)BdZS*xkA;I)^J`M5@_ugU^r#6SN{O4<A5UKb%;>wAgsMDsE%!NiJ|P
zFZ3Shxc&(0JkD@Tnl1k#N6x%W94V<6wBBQiFaxq10&JimZ+#5(GkGEg<XT+$8LGr*
znD5n3aA!eF2A#-*Imtppu}nT123SL%)P=()P`b>EL`EpRDBdy(IHTqthrBOm%wxGJ
z8%I`2o4jkn>YrRM!aiSedJcsT0ui>DI>86w{h*T_c-3@*?p|ro>@N?5FD-%i7eFDR
zLkKYq^5;n+KWvkn;FL0{d*&2zoGlPlllhTs+uR@tVHV@nDj9vmqREh<dk?*jS2o)+
zCDY5i8i)+OVaMq+Md4JA5W{m?nK`w19WrE2(TkdAMJE+SASR=oz9*9D*1}Qo6Lda5
zpixRp;HY7pY2j78wIhO}j4U!rfGHf+px#@NjBsF3(nh{mnpeIkcdvk^8ZqmDh!Jrh
ze`Kr$pO~Yds1M~2$Fn@}G(vn$RXk^xm)0akBwUrH&)|#4dEy^AV?A3@`aM9}kU-On
zLdjvHTS9t>f?mL^_gv%%QFLm(*g%i#%M=Fp6z~dth30C|!0EA57yP0djDbLH1u+r7
z3D|@Xu4BrBQ@%mz!{iD`5IB_%+$I$aK@QIB96dygt2`8$XQt7T#5dwd?t}8_a9-9y
zPFr8TY<SE-PSkrGeHF{%2S(5WP;{eccso^U0eFS=$vyxtAP|9o+{p7j105B^a51bJ
z`SzmhWml-=7_^<C_<nATTq9iM7W@!8-rtx$1W93fD(->Gwrl_6uiXoY?0UzMB9??7
za7H9X-L3+&5zjOp=48=GQLc(Wan+Z5@g{>vE{FU8SQvjrN)iq8)kJN=`p{zIkX8)O
zqkWIJyzJsAeujFQhJ<~!jR}xt`RgBx)z$(=2xuF+Npm20gc|u5%e)UH1(XsnI7(v*
zHe)0|)EUw>6OH^R_f$p-$|6z9aQ@aJtYd2ff;mQD89pM23=Et+@2X;>>5xEcK2=FP
z*tajUk{F=yk`KMQbt+tl$@jf#^(srJKU@f>)E`6@;&eX$W%WaG32stxf*MCkeGWs+
zRUMXb57KZ1A$~r%Y7a`3(Q9Oxg!Bk1hQqy9!t0;70=K3Q747$SG_~6#qUjwkN_>b6
zTg*pAUmpk3hr;)$oty!V%=^OLCu0p6HjHoSeBbK>3dSY1PrX(d7$5NMc=*uvOrhy(
z56?aKL$}mv)%Si~C4N#L284D^7f3&tP5>Ow7K9WM!N9kKZ~ibnQ`(>y-kT!>>HE+~
z;uDUt@asX6C~nYO5Vb%Rog@_d<VZ4Z6}$~sXvjGJVWCVIayxW;=}7O7dK6v?Dj3!r
z<a2-wA7CA5QrEs~gl`Og)4&I|DfYJU0n5f|?)_cJ?W-=$!_FjLY)hTh@SQ-w6-!v@
zY_Sf7^J|f6Khy=#2Bnechvp>;ThW40j>&FrT8R1-{*&6GLqFa}u9M)zcRk4387{%v
z$|f#!CL68KDS8Z9H_J*^qhmR$pxZyZs0diU3>o&bw1BGa_;FW7X5R~%^{mL0?7M<{
zsa<YXU(V!M+W6}Ha#ufdehzmes&n`Qjf#_J79}*uLxTq!fZ1QYx^qTr4nN~de^Q;}
z2x8rMNKxYB1wx`MCw4^85O?fqA#2BTW<eX{^X-sPtF0NuCtOZN;5;nC6ljP~`t+)p
zaM4e=fCffqtR6fj*mn59Y!G1s%N}x|Cwn%PGL5Zk`@#`~I9CA%CK;?21)Q$p&Zp06
z!eknNaBH)AK!EJTvdi8RzV0h!uc(ZJ@Btq?Xdw@`4ysja1`B;F5Q=2FIp0E>F`E}d
z`YYb;!Cw#O&7e4j99xS1QI?cCb;$+zfH0`38S93yNaa#j)}a_6{P3y)$gPyRb1f%Z
z1iET48j6O?#C#Mb`YzTPhd%NO_Vox28qt)-TDNlKay<532F8$e0;N!TlcI9Da__GD
zxjvcqqF-X)e|?Z*fq7czxypw-$Y}k}T-9gc-s2pAPp#(aepjE{vTDr)VU{&yT@1~=
z;UG3){hEe0y)V}koFIw?p{1c!O#j6?8!x28NaseZ)k5dBm219vIIE{!dgwjUFqB+g
zLo7S@m!muZ{k)@K1b8_SqI_}N^%FNU#i5XSD<(0bLCGuRR_isrRiYra_8@_b7e?CC
zsBqxXC;%nA50h(Al&k3-?q``4^G`1%?|D5IVLgH1LZ2ncgm)oe95m|+V=09r30>|S
z_U(^+j31F>l3Fycx$@L8HTn}P22FM`XLoUw!1!=ELOr@u>f^ft6@p!R4kyytzM43x
z;niu&7Nc_oMNTjv-x{94x(L|umw>7jP#qp7P!KRL;MR&#1dMHyRbyz(uD(YP!HZ5n
z>eKN9!s_j|8zBph!bHRNUesn(bTRfu2SyOWP?j1tJqMzG3($<NvGKP)U(e^5tOgVZ
zh{7r0&&hpR*GhMc)<EtCdd}p&%uS2QbXzW*Y1eE8dj0v=_pzOzx9u8Xq%{HQoa>Cu
zYFv5ybRtKcQU9&LkA@I-{p{>KW#n-)W48bd6`I!&4QZ}w;4ZRr12K|7046r3TyRzx
zD+i=D6KS?0Ktsf~8Ge0WQzeOR`9ZwNRkmk=kl?D#ICrlMDk9tdU+lekR8!fy?i~b;
ziVzwB0U;<VDq?JClqS)#K}C!$C<swe5fEbo8Zaa(Lg-U!35r5gKt#ldbc&b&37|!3
z=#j7?ol0M<r4W{+sXObA?^e0TsGPHFe`lQYjc?pP_zRn?thwfT=led-?|Co?kbyzG
z3D<{QYB=^yD~lQ!Okyjwp{IEY5A}P1Auu5UwJ^UI4>(`RQf4*F5Ha&<c03xZHXhYN
z=wfC<#5M7Zi0~f(cnomN3_am|?-p^gZ^iSrJ9}F{Zy7N)pBJ?b@BM)D_J6Z;)T$!2
zN#KwV9-xHu?ocjD1WdL4;DivzC&Y19HjTI&LxpudfoS9=#eI`lWEnQ8_x`1rXgcWZ
zib<+64=EtZ0*rUQOmYLb!5?y8$jM!x6bVy!DbFGkIn+h4XKXHH7GEl`RxW|^>u`Xh
z#*<Ke@n*$Hfw*67H{c-gcH0lvXX0&<ESgD?D6J1-UMBHrHZ2kUA*UjHRuc`k&Os@g
z9+Zv+EE*zpL}bmZ4_Kw!6Sn7B%gMfuvLZ`fw4;mP%{HI&Uj}>U!zSvR5|#G$w2*6~
z<3$(tw3dc1Z9m3o8yz0Lmn|h!ah3z9+#1>%r3douff5A;=0h@RXQI<6qcWK9?+*w>
z)IbDF4tvmlT4@Dk)Q!#!r5nto`m`?tFF;alG(GWDcq!e2>fK(oPy)j5@YgxZp-mn6
zIicrYp$Pa#?5a{6vWPhHTIvxjMKelSSDM}yQCGo%x5Z?WkWQAdT7SUBh{6qkLIF7+
zfGVoyJCPHd?P0S$u-%n~%sOlH3WU<T1aI5iLw4LiH)k)6m50I(g5h@(F0;eO;(ZA&
z74I5CpQdy;CVA&CVJ12ju-Sm0>p$LHHe$H}VbI}owJd{3t3B&560Sa2g6A`GD6u?%
zeO{kWNsD~lTvTR*x%G(Mj+;WSSx5*0g-{_#VbW*hDjnO(FtMakHj`s<uuHieStuPb
zuFG~+-Ff2Z1P5ONEa6nN^w>n48ta)$Vem6|!~xD}eP(?kCT{tT2bD>6i;|0$XY~aF
z_tKRxWkkCpNf@I%_5_6Hkz~ZK3@^y4w^+=!QidbilJd?`_b9+pKW`CMkx1PNUtHG|
zfkpRFh|)z_Qm&qITXu|Rb+$9tAFD$l`Edb`J3Pby-FI{Lu60xYou8QXBwT0PY%REt
zkNvhJ+ir3IJIM@*O!`v}?!)Cf>Vde_j~Uo6)3M9aSYL4ij0dYy6ypu%bw@M~<5AcD
z5VCvi%hQzo)AoG^g_b{1MKBlBNAlIF*Pk@}sSbbaM-A;bef_A;H`e(Bd(YUXnH*fK
zM7{m^)h9@kP6YMWn)=O0NUkeyuL$}H2+!}hJ9_9VFTZ_*MqgQPb4b&~b)D(|t0UTp
zKP9kB*Zl3FBg)8o!c1KW&W$;;g3!``K|ytC`giK~gg>O}P8tXs4>TSaK`J9bCg-Vp
zxnsNAZ~tkN*rsXL?Q=}iU2dBCPkxr1Ka~}lrnp)Q{!nULs;KnwpUEoynQ59otH$wj
zwa$$gplf*gjNXq7`W0y!M(2K)CUtMhcix)^f2glDu_n?MI=HMlW20@no$x8e^E!6H
z$MLmms^6nfQ~p|MA8D>h!E;5EstR@Bu`5{_1xyR!gt3!1ga7>gG%8b20nAaL-3jph
z4YhH@hCe+qyZ*iu<==RcQGaRj&=k{Us7XHkKS&Un@~6wg$?rR-iI*k;%+wG~GBZ@b
zpVIf;?ID_^Eq33@(NP9}>GlX+^LGVSD5LKzDt~SzkABg_j4{%Hi2<QzoBp%}{HHoM
z)L(f$JT-lHD9yX_ly@fI>-1-%{;MzmT66A1e4u>&JnQqKwfOA^nW9;<4jsDj#%|3T
zAe=b8<^?=WzFGDDcIu-&SP%8N+gOj{*16*XYdeko?f*b;QH_3x2-KU3ywo6`X^hjs
zJ&m`bedwJJk(0Q=qe5NKP#7+PUx_h1AX))d1Nxz&i?Ys<^)gth3KL&Qj-Yqps$HTn
zv1GjN31`x@G5ZlmWOQTsOIV$+4X{Cx?|PnIe$-9z(Jfre#sNYaMi~s07ae)Op-#~!
zNnxat$+Vl0r))d6#D$L)l7QK)q@o%eh9PBuDn)5bmkOq;o3XmT=W1VJ0igcqG>W|+
zR13=TzF`h$VaFKzvOSbht2Tf-W2x)u(pCv3-ldYArVP&+%AVD-Y}~<b@Qt?Q4Oe{M
z!t4siiS{ON4dMdr*$MEu%&wWDdS?*&8XzMlK0}81*>=g&{4^z5MoRLTWbwPP47I`a
z_a3`D8(acSp}VoQE?+3e8@IHU6&ABYJN@pzdIj0bmB?WQzCYbB_zLLc3Cu+zr9B9g
zWlNdEtxrIc=qa-xfP&`Jt<*Cq{$fG$NsfJY2v*14EsuJrx%3m1&XieA^T6&v{4Y++
zIg+WT>QSdg(SlVLNTQhh!B|SF6U5WCsR2@4*A4M~)jj&LqM%LiXdMYd$&usR?jy$V
zD+!??YXg87M>0(inViy8Wd)f@Mw7s?&8pdn%?Px61_CE?4h(&vWYlJ3+m<Vdk3&um
z37M;*JyPG{C9>a8TIy!CbFu0U_qb?w0MadIAuS6)pg0C({x%FZ7byv<41Y-{qZE7j
zD`mb+<{4L}cecK9`%4f{0KN)tiMm8WN;0DEY>8-0jiGww4jF{BT%x#K1@`#jLQpn~
z`*@^yjvj(}>KBUFYX1!tG(xis`wf*WoQG`43l%+2dnHkkcfW!NweKv&^~nYO(Ts+R
zBNmDS04{|!RQ>=G2pbY2@5dZ|;_;MuEXb}F;OIO@)<WH~VBTm~rvyYT#AYu-elOAG
z5zU;%1AZpl6uf;m$T85b6q(@X1yHxNFMQoTf(KZ*D?eM=`nHkBMw|`vMMQl1vdk|d
zqxWCFd<B}hU6=7DZxvgqQ<$<l{`oZwq!DVSEiIE=i-4hTRY5sSGkU1w@{Ad|S(uR=
zpX=>$AEQGmFRtjcH)8#Rm}JT=&ZuLjRr=OoO{p%bpXkSn>}1RuR$8z2Gh|#sN);7P
zq*kHDqvn*0b=h-~*APZ}Q`Im$E@5i}*t<I2Gk%;K3-yM|v#pWKuzfXtO?j&_qB2XK
z5m_L*MD<oU&})d@@({!mDv|6*=2MU3Ehq!j6OlFWGURmFMfwSDSD$QD9s;0G5>zL>
z<T+j&J0qq-@xyN@?K(z)Vx9$7zPv=B2EQ)@-SZ8K8MHUp=M(WD$N;c^zVa$}!q^7V
zoD;5gDZ|T$BZxBxdp%yO?y6@Fxq{mj!N#~Gf-{E@S5HXt$!zI&J(VYZw<=~2PY6Om
zyx5-i-aaDq1G;Sj=@~YKic@T(FnFXA*6=&o8Yh;}U)sR1fk;VsJM}MwlK5hYpevXs
zn(1yQCSJkYL&xs}0_-F+ainu^710op)n#^8$Ar~#O-|vLH-tn=7sAVL7Ol_s`t}77
z{U>U<u_Qn@JTy8J<OC3g^Wjyx#A)4BZ&hxYUYNwCmT9Tn1JhnUpnVX{9uFhO<5$Az
z#rK9l?8(&%`b?#sBx|{h7&2UDMV1Ko{$VjkdI2`CNV5947R;z2rhcJXfuMHGy#`4`
zr@u^89lk+)`L%a=>2c^uG@}k1M>qTgo5w{IZ5euW1UWIOlWE7wdD1-ejwXB*ux4PA
zF=(9+{Ng`$IDJzuz3pxe_epNDQt`_|33J?6u}UUJwy<;~-MoDdAP1mUNqUh4n;^^;
zO{IFF`IwnIXyya7MXjfXBiLvpXTwWQ``AUjqg|o953Uz;p}q8Ykq#l4l*pN?N~g^j
z$khA9txdJ9Q#-*-{#0nZK10Sb93)s(1w_G?646!n!-b(c8=izVgUoE*GZ14#X=&B9
z2Q5{*Vq^vLD@v={o#qIl6b1u;%nN#O9~AOy&;;KNdx?&z+P92rR2E|fvMf`h6iboO
zx^!nDvBv+UBP)&!1`#HMRC?2x$QZe@4`5KjVJ~?=Yb4gvrA}{~TbRPX$F0`P^pw_3
z7^|LnCYRDFcdAm|07q=~B52Hy8%H=kia7`{6t&$=pAnM8V}qP(5z<z*0s1O&z6PD+
zO-vpyhHvbA{t71WV@P!*!z$9#9!kdU14r6Fw>mb4<H=gk=t#+#2kKt6v#J88w)T4J
zPZ^b7Xuw&7igZs=!`*!i5MNpL9hpEsRIU3Q{s#5%c##r-)I@$A+R~)lOttBN1P?z1
z(rca53svddXZV!}U9l{L3%qB?*!oIhxhe^7ut7>>(4nnt1F9RG%8cX8=urk(yTS3d
z^M<fx=w$8*y55JzW3myt<XtDP=y)ezy@HfHzg6;(L#CQN@(*1VDr6;*gFexm1Jxj)
z0_jxPE4P<JjNv;{tDyBNz}O*sY>-ay>_rCZH=t8RPN<3zW8>*2Wz4Quo&b<P+C}yT
zJKM18n2c>P<jb*o4#hFAMr?#Vdd7O^KuVCRP7RYFWvjFhODT7%fSxlXGOd~lDH>>2
z$Q<``=*tn|{&kt3n5nrf?p{$34pOcNYArg`#>i-j_NETy*5#>(>4gQ)Av)t~Ce^{F
z^~a4ZTgTB?2q#smYe~9<V<f$UR9t%`HVIqIt}h}<`)XL$e$*dY$3#<m{g7Cx-6aq;
z(K`o8hFXRspg&K^+&|8q`VU^tP$il#n3i|*>5I1oCn}p-kNC4%h+USl&fy_|gWiX{
zdZ0Z2N|jDU!>^=-5yuLamU6X}I8_P0gy9L0B?rhc!3k7jF(?UGMzm=I^bdH0R=h<Z
z=|BMG_-I`PN55TdiCmD1QcCG_kxrhlEH5qRq$rWAeNt^*qgY3^eugwVJVN$h>T!$?
zy6K{dS7~3~P(7ISl^gMH>AEWGs0Wp0)|M89br<sf(Kr_l&#aF!dGO<<7(2xdT1)hW
z5fIccjblL7M~tNcoseh@pO_5Rui(mOxURFFWsL}=T#(bk#Dx9c0t+j$ucpn&mhDL1
z)l7AgU{MsGMxHS3rPJ%&bD`0k*HXQ}UnO7MwPAgQe0K{Wl-Na<CnHN_0h=3TpxT&w
zBHJ0_Fl9Zf!H9{dP05i=Bs<a*vuCy!jTZ$=M0GLNVN333`+J|`b!MA<9k+7xP4e;%
z+w{6*D`~vrtCU_%zA6GFRHZRM{P|oUJY&YX@5JMkho2!0PpOz@Fyk88Bkqjn246tB
zBt=Ad6nwm-5Q%Q^Mb3z^3C?Om2H&@wU=Y5%iU23Che9dG>84?oKCjO`+AMm{O>++}
z1PL8G3T1lHg4%S8^5=4PREU_ag<vHaard3iJ6A^7Zi8HSWPOBK<2Tdeb?)u}&-(~{
zhu2VFWjoGC1_F&<y+ElPpi!lX@j)n+$q+C&hJKsals)2#VJC>qn*?!qx1AhTiT0}!
z)hj9Ir0NW5caNd_yrUE8fp{+TCB!ArjJdajtiS1^#~>0LcqsfROzvjLf5Dc4D#Sa`
z2~h=`#uZV2fQ?VkEeI#v=xMHI@lR<sJ;>QXvcA%xBvx{Pmsn*f3AdtpSUs|M-I*LY
za<(bNFf_WdJa$$FH}5p%hFqspjR83{bQrx+bu)rH3t0_j&c?WU^-|dL@)#>VlUV<b
z+>kj@-($>UmA$|Dn9^9=h~|?_kTj7*zo;;PqNuJg6UGS`mLMm~`~9_tq4_)8o~nq_
z81NupD^NzZ<w1-Z(g$*Nwo?g$RUGtFzn?5Gh8gnt$Yp4?G@ri&j1u0HE?3Z2LnPja
zaV=r0QcwSyIL1pFlV9t_7UH&*!MNnef(S1%cF^KsnPjVz3rcwqSq;jUH2@h)GNZj?
zS>b0RT<Ha#19)iTX|Bj&wG{~W!y8j_KuK><<t7#xA&b6r?rSe&#(_xBaOwsL*5pKV
zdt7=>{-Uhh(8{@)2ii(K0^O3k8>7b6I<&S976y-{Vv(3&C}$^3s>8)%%d&4Oys0zc
zEEY3-EWoI>-nFcu#@mgLp9PC9J*_f+N=O~U8XQp0f&O9PIO&<9L_g}csQXwM_pamR
z!`w-$z7c1pl#JLNzX9X?p_}EG6*EK>7iq;vh20g-f-nnkMu^?j3dVD+eX1lSmcV!L
zl%Nxp8!dMtXQ1>(dFGuu7py+@f>_aGxv6#BW4XW^s%KlX=oj-vblhw$MTJZxRP2L%
z>+MNh7k$8<Zbxxh4`;-3Pmmb+r3m&MT;6aHX$PeyO~kQ5&cOP8dmtA+4%xfvgzJ%k
z363Qag0Ahc7?n&Ub?$5qzYH(RD;nh3wBb6Ag5GHba;{c{Rqg}Fr3CJCbi!`z6m>I8
zpR<<gj2y^UMv-R@lJxO*R9j?f4(*rdig?gT^%BKKw~JDggvcC(<lWi1BX&KMR`7t5
zu`$-W61?z}Ri|`CF0G{^eM+*tS#^c8)E^Y)KCowPs=t^yOagDQgwx91NS<Q#Ak7l$
zxD1^WyVMY4L1|<c&smD-%5aJJw-SP3h+!A<6J=XNT_E;3Y?hE;PBfy<3-{++&%M}V
z_AB|rY6)hz?;Jb|&R+T~p6D5yPc{Y*fZPSYph;~@VaQJ*+y|l9;`CxMCJ{`fV~fB+
z=MHOxYkHzH^CRBgxk&n2Te9yLwNul=3drY<ENitlRF=*SKdGhcpcGbTuY%kIO;~km
ziw^g-m^7+gJ~CSKCA8yg7dt^|Sr|CzcmB3CV8PF5;n>BY5$xWwvMT0EZ-=;_@8b`!
zTLMV(E)c>6KOJfy84!Z8iP3h6v_<N-7QVxEiX9YxA0+><WQb{nSo*41cr(CIW-w`n
z2SQ2OHf?IX&<Y_swrVZBw2Ml#tM@kM=lGPwSARf42jX+a2=y2yYudP|%dR?b`d-zo
zDsLGvmJ1PaUBUGr!_@mRB}{@#R@)Dduo2j9+}0NN1JLsrl7DIYIN4x-Hx&zG62=9l
zRCMRac(@LQ8XCBygK8(&&GPwG_DO^+#qeKoQ%EK>E2>wk6Z=x-1dnS1^cN11;zsV(
z4sJ<Wmh6s4AjsxMY;&nwnrJxiszDb$Q7=O1J0U@u<H+wC3`kJl=(eWH>2Tg4$YE);
z$IT4sO#cyeAsG~xUS-c=U*0?a&4`XLIG$#zZWBFk0Jm{E<uJ$ID=HEVj-<y3mnuQv
z+zhHiyZZ(gUOQ`V`}nASe}`W=8=fETG0QKxmxsCXu`Ju992S7ZQ|`;dfn!@qXDkgf
zK$@nEvE!4`wC3Kas)ABxQUz<SyR*9$87515((>;kJ4MuG#IC{LQ2Q&9C~{8d;>n5l
z`N)sG^V=i+H*=oB=WhoS<nw71kRihTU8FOvSVJMMZ=tSK5JD_GnPpfjimrO*l84Hj
zU}Wbj_2d_kYXePS+(<WpS3-W$Pg{Z9S9nm(V06Ns+77jG)eG{pP0*-!MQMv@Yf~A<
zYLGVH`@(@6VgR5B=gu5b+ae#iMtBU85da?IA^AyFCJjZ&sqLMGl;u%Y*Sj9SuULJ8
zR3c|d*jD`<_fDFja$U={$Pr&LQ666?Nfx1c7r2s>e~q{m*+q5?3qSkyD@gQN3{ckp
z&X4`z%x^T#z5gAf%^(16P4P8P<u?2m(>{=Av-)nLamx9Iz;nW4&4eds^}J$G=-ctZ
zT=mQJwYy{0$5gACS#5pX?Li#MlMS{}&8$V+znx7vKKE{^JF{1&jhg#o)Eu2)l+J_j
z9Gp3@oy|Wi$g;*v%Bt5a2)g#;bi4W6i2(96A3&aPK=d`ZR+C=%I|=E%nSPX?x_D(W
zUBxfcQg1PPIcGOM#t?>6^w$pg1R0;YgR!R8+~qgey-mKRkX%lgWfY~;hn`ZNJ-kdZ
zWyu`O>d$)&&=c&|h@^i+eAJIVdd^29y$pq#Pj)3_y91Z<H}8~F3>&7~f*UDwQw~9A
zr!O=PH>bS$I&Z*OpV|-6JFT^9Z0Dw2TEF(+(6OTy@ByB<1*ZUKNhK}ks`tk_Mha%R
zySA~>wB}1&ZcRDUCJt_jDEJp7(D$aSbRKvH_x)o2%l5O>TQ9MkIdiIO?0(#F`t+1V
zUvs|61R2XQKLLB^+38=OZ(URKrXGW~xuQ``to`3~Pp3<aqgEc4X*V)aeE#LqLq>~G
zcO%!Bk6A5F@vc1S9`$wFIpevkMaw-$<EO1yvGt?z-MLdVh`=>Vqfz!d7AlUV1+Eee
zxNS+jgsn7x^L6XVv|Gn&KKA7u_{qEUm<-tIa<{Mjngd2j2PtTsl(Va}bUylIedyiK
zTDs0tcsjQ({g(}E_;HlM3nsFMM3dthv5f!smj1Wg(*IylYa#{zs97nl$uVOy<)8Pd
z^z4Psr$;EY>aSWk$89Ircdspt6)0@A(?Auq@(=9je}vdP{(m1+P2pvz|CxKbW@GR6
z{gmo2vg(y9ZNlg1Bwn(!+A%E#z3sbq&m+mTt1Go;U7ap7pEei!)7jOF*LZARhrefm
zveo$FDV37S_kWT(sBe@ee9%(dzsqz?e=`t&(0WJozFQiZiA8S3RmJ$dmzbrJt;r6z
z;?E?`gxh|#Z`hu_c*-yTm2cDko}KsqSGV*(s0#iaf05Sr<npmye>$Fb{Z}EtOh#Df
z1)gA7*Wk%_J%0Y#$z!ANUE>t7tUs(yrT`4ozm5(;Mf;`z?3G^|cLWT{y+*=@>1o!w
zsyn5k58XgAE_;L5rO+jwi5#~<mf3ye9Zarv5t)G_>xX`kj*|RPiFf(E9|l{>KIQZL
zv-Z?E`{jbLCe!Pw5;rfd(f+OvNSGhw!Z`k_RV4doxMn4-S-n=3p9|$z6T94`3nzG3
zGlcX5Q1XRIi8Ul$ka05)y0f`+EWia!jCf34>Ly4X7bF$Tpe}&u{35S9`~r|hnnqg?
z!hABcg3>M3d)DCu&MD@ha=+jNfE6c*3$nElZHO*swR5Jc1=$wlS;z&+wA5S*;ouee
zbP<s4r@x4JP1t|uK)d^{0xAi)9|h~~ZtL9Zav{(r#!~W=>7sp2%c`v9egT}Ki#HSm
zs)6bjHB2#^)`6WvTTEd|v#-Gf2{9F~-LJNM1+jQQ0%_sPIH|TdNZnFVR$2xmV`<q_
z%HUO$-mko{VCkKruyw^RkaNfG4^*<^I_oF!^V%a`FDfrk;AkRlS?7o?Y>G*sqw%;#
zSPrykG+U$sL?{?zuc%i*J03W)W+K{rzutri(1-2gDb|dEsaAp^WhMzUGAo$8%2Qb~
z9Jc3#dTv>zSEC~N5$7VrtOMcTB}C<N%+-!`2-!qERnD0O=1dLJj9R7+rE+Z~X4+sz
zNr*fev=(T~k=6V&2)RzJ-*L(b-Rcw;j@ts0<0H*aad`B@r(2rPB0`zV@E+)#Ct?Zu
zq)c$9Vw`UlAhz<e;O|F+!0XXk5a(N>Vr`%c_lT8xQL+*3dSM1rPI*-)Y)FonQRT@-
z91(JDrAHn&)v@5D`yShx$6X<9X7bq(wr*5d!6Ru`ErC6OmYm^4{P0!GZNO@a2Do~q
zbPRO^^6G*VdxfO0B;_KWKLF(zSGZDXdl8m3>_pN6$o%N-B&$;T^nVPN<CnHoxt|1C
zN)dZLcb=z1d+MOnDhqBkmstVUMd|}}qk3v-G9UXqqLO`88TEiV^NL`L>bCpJQ<a^y
z$wjtxrX3xS-$3Ol7PgyNH$AJ!eSh{!{{q>aSlD-jq1YSRNz+ESU~!_URvi%qRr8)G
zZJ|Z4r0fs*@&F=3Z40qu4?!lW4Of>fyCV)@#a8*z%>4STwOXqPy4{1BjM|=6VKK(*
zZt#SJq{wi>0n|6LwDYpR1k8I9==vnJ(OIgVj9^6B<zLS+U{zb=u6yYEylOp?!S6-C
zY<GI8w0-JjRq0iLob?X#4YwZoRBZ9^o{iZ#TI&!U+QG$8%KPNU!H^Nm)RRaIy2T+R
z7z|xrz_?U!rWW^v{ZN9?rEFow7U)9k7%QdM3MoLRj+R*k)twia`g+44@0;)tA@H8{
zcVsUq<u*ksUiCODc9bbuFQA4IPsJgmRm!dR$7)dnkZ;nVtlbk01T$rjn8l#YgCqPr
zIw~jQ?=LEn?t^?{@u?E4rTd4SFvE>|!gKngX?OA(kLCIa2P*x#yJOZ%vBK5rnE|*O
z)}`lzm7aANjB-J%6X|lcC73v4x2m!tFjMnW#xa+FfM^1mVT*dj3Bs(g@E~ao5_2*9
z$zb+0=yRczZL+fSSVv@e8Mpmv=NVMAD2;GPpp870?Na4c1t>xgSp&9&n@F2O-GS6e
zM}>qstoC?TkhHf<M$lF_<Be2Vkxc!A%9ZW-Rf85F@d`T|=>)57Tm>?_1^heHUO>MV
zUyLgH5R#dlfxm+*R<{r!uhA)>Yjp={q8TAyJ&^$5cVX0vtPo?_)VtP3pbcU+tP*3U
zsDH7bkLczqcU%l{CoM0K#-OFkZ%dd-lbf#{E;xwn??M`DPxl*yMl<E(IUmlD41cAI
zA7|^sxZw#|cu;NT=Q5D1m{ChlwKi<#9{0ik4?*pQ-OU`U69m%?K8H{YR}5F<XLcjY
zRn!ZzI~Or2W|?EzTHH1#H(nm{0045+`~&b?XeVL2ksg>ugv>??#e~F3Vp^^W=p(>B
zVv4L@uezt6H&ppBOKj<FUrU-f8vf9F7V%22C1e&SYjHnU5DJB6qLa&Bd-^BU;-(+$
zMf^lH&KHE)ub+@EQ4inSTBJOI+<-(pya#gAI>Wl;5!D6pHDjvh5BXlOK=VKs=>z=;
zf?dbj*M_sZHYU)adO*K8pGbdJbv~28a6Cf}nd>a?Po8WL6A?S#Y5{{(!2pfo<ASto
zd!$Fo)Ik_xK|Rj8-vYFJiTWTx9`3yl1|LfQj)<a*wUvEwgb<ctNOS}5Q3P1)LPSvu
z8iJ$Ak%?8_Y=3{HBh0w!Zt)yR_H9;Ahx3O8Ky9L*53!_njIp&<QREAdKz>1Wzo^O+
zG(1rvimawrH$%47wX+t)5>VHdbShmQBim#??UCWjy%*v1k)+05P1M7YQ{P`BhZXt1
z?#a1$szgRYmK;%o@yE0y6$k+)R<p1)V~UsG9Wl9vt*w4r>C59Ho82)_NffpZe5@~y
z8%&x-UDB*v{g`r*Kf##~#|To&?73Q@<s3V&p3Ne@uU}l&^YtgSx@d0*karA5-jrNl
z!PTQVC^td!*f3ctxtcJmDnK@Rg`))tu7W^LJ(p_F`pWY+WZpZ5<moQG*06PvT}FPR
zgm5*}cSKw2fbo7=3hyX69QNSgve<ey;TZXnT32<O5G-PfOt>LrQ_2OtsMLv_GS1Rh
zE`mI(-ALA<u7r5C74>*Kknpqjwkh{LrUpaScjR}9TsCrHbnFw-j`CQ(MNe60Tv>ou
zt=xcK8(>!m5?{fvcj|g1ECdF+@hSM(6s~uxyDn^BPg@Pw=SZ+0n3D1$@P%LI8Xtj9
z-IkCOT{69&khIClwUDtd9n}?*X_q#})H{Hz5~&UAl0424y`qF$33%Ydu#;l>7+s)(
z2`dUM3FBBH#JnMn2@)Vtgk!fQ$u_krgJs?zK>Ph|@|nDW@=4As=Rz6QXi)eQ@kvi;
z=d-ue%JZyc77?cDJ1^0mQje)F6ON0Fz^iwC)q2HJr4dpl6)`L}v&4?@rusw~ZVD3U
zy-mh<{(ajw2ZK0}H@o%`g)L7geGc?D>_lOFag<YemTc5SY0*;U@#x^eez`^Y>)@c^
zbCKVU!3~mJ78>t>C?wQE*}@w&*7GWxK2U#vRx6$0N6tf*Ok|64=Hx_@FE2CEXo}oN
zy|D91HevZ7&$n$^enn-**hGUG1zxl_L(H%x3_jaZX__ph*Rv9PbrF`>!xDtugP=eH
zqt^uy;K1{CWfyfRRMUZ9NwMX#v~W(qvNfyHjk1{H)}VGSgGot_0a$N(F>+%EW8W(;
z@LSq^<w_M8>YZR&QI8^xGEpo6tDc7lHp8Z6;2Gf7rGs_t9{7x6PlD<*jtDz$$m~h_
z$Tq<b2pBa@Prq7u^c-?t+OYmPRDLxxvMTy~)<e%Qi%T&cMYK1p5>YZY7=zfQHq>%W
zshi7GIfO8RHRYA0iVOXy^k^BWnjyuSF_W#ekc&=FUp>vQ9|@J!RHAu9T;rZD#NQtp
zz2tNUd`uz5+rQ2g%X=j)H&vS`4yoUO9_L+0R=j#85)MC<$;ja16S9{eJ&@Yr;$9?-
zQ2RP;8!W2E&Iti6Urv@?{70CTCar41-Gj~Isp};%F_DcIUweAD3q^aIB0RR$etusP
zfia^A)z+%pRZAY9=$#G^s^4KTG~2B*Izu$)6i4gCBqtF#1gtufs#cNhkSN9GP%egC
zwLxq?PBNzud8b3w))15LZRyofHl$P1?pWCP>eZW5G3Vq@fZC%6o{+M5qj7Wt<q{Yx
z<<>c1B=?Y8tm#!+3VVbl@lD`hdz5=Rf?za1WSo7qcP_}o{nED!c4o^i_AggP!OI(Y
z(eJN;<s52S;*W6mPwP62A`dSVGrMRq347!i%#zh{xYE=MVrH#Ce-P~BF@oAnNUAt|
z8KqC=Qj3W{pY3|RgD1a%=oTO)b<U|Whv0Q(&~bKD9^${LxShc_>ri?XA#`uZyRVR9
zr=DRiWhH=yJt)b!Db{94M&XIxrSSVQ#j23LYL*cPO9`qG#?)U^5S81T)w3!7b%C?m
z9oZ?_IE2YY$eUqeqT`HQ7@e%11^kqvq*AX}@AlMKj3)Th+-J!M@uKP6@GWC>CWz&v
znNf9-uZ8<V(_PU#w$PquZG~6?gWRCsELU`DDJ~(}EWYZbam{3Q2~aESDTgyIm&OFl
zUro8-`^wd+o^^J@;$Y>?6xCb;v{NJ;?3QF_KumAscHRJfcFWjk?4+Y_rVH5DuL^yc
z<WfNw@Xc6&qYnB57%<ERZx8MDFzx_D5?FkH;5o7+5@+&{@@rwUg-1_LhJX5$E5<$)
zRw#|S#lC#9HtjvIMmoWdr?of&(_s%7b*i0cP1!cc#axOmAHSrT3o5T9(oD{rehVwc
zC29=Z;0ak3)xh**hcVI&5zsXBT^=jULh}=)nAxNgogEVv3oAZj>k3Dcxz9%H$f?|t
zh8nUkBe0!n_&A@jtjb%;z6}1G(J{g_>h7jU^2{zIb}KWW0`g3DiqQv0hixrNf4YQg
zFtBS#J-@Uia;^I=$(ynmA~F3}e^Ig8j(QAi4i640gAp>M)^n@l8qk*ZW2d?MO6^5g
z@TMxpm|)i1`$(`n^>uR@HVtopWIz^Q<rhH+HmuL9%U)j6LUxa2hXv}v7p^#o%zB>|
zOGaoho7Mj5%1WfOkh-aZvl!uwN(FJ@V6Qh4PIhmC39-vKK#L}B=f<5<u6@`=iSAxU
zinlfaa>_9rdTU<DWI)zWlL7hhV=q&n#tV-&Ip>{=id=&p=&ZpY3&u!uXfu_ok&?&M
zP#DLvXIl-jw2dY<!mL`t^qQmDbC4mpk0(MolFTUB;08p!kiz?+3C!6rx}lTI1hDsA
z<zke2kNZ12xll6F>Cb7Em2ueOQN*^h-iwSu2>Xyxx(pLnIhr;eu!F8gF|M_q0uGx@
z;~uJ86UVRtNQ3A`PTm{%By)}tVq9y1iwEkjn(Uddozjlx2tB<c842QF2XfP}%J5%V
zVYy)zlcDsQJ(lvlh}PVJCltE;9Mbv(D5JK5*PWF&gxORM+r=x*!D%eNR$xREOmGd=
ztC?4KAp#=ekLHst`lB<dlizaYle&gV4j_e_nvP^_Ck?;qq@F{->}~29$aBO#1WJ}#
zP<J6&uzmwc^{~nelJP1<!;KFR77uLW^WY8jw)>FoGvd+sNl-Q(0M4&ulCC@bqFCj^
z@9;Z^oC}0T84&?)+i%nYDPVE&WgApJPHAN8$3bdjxU1O)$Ve{oP$tQ*=U(nLMs7=|
zQ!zTO#4Cj0(KObShlnDV*5Y?lmBAdRV|oYhrcgaonq^-XXwpL6bn)SaqLAn{Emic#
z1L`HMxIOUb?zCE~&1$QqzkUWyha~x+hqGG#v&X70^4hf@{oP)@cDC=?=79hF`5&H+
z@?C?jSI=L6Rh?1cH7A?c;^8lsAz#JbzVhZ9GBN`{KY!$mV!IO80;a^6L~C2vrU^g0
zpEe5#I+l-U|IiWP5iFj@gerJ%sOJcmsk+C+-gds~PUsycRx)yKe^re3t`7FYw%~7q
z8f@`s1Hpni6UkC+#%Lj}8<0I<U*X~Bc195AgsP{(SHXVADxffBc9+$<c5yUo$`dd{
zg;K!-);bR8{FdDcUGE(s((<Ori@OY8C-CoK9hynUsB6KKMpJ(v7~<DZF!GoiVoV*A
z!8K6Z@FT63ilj^)HbFhJxRr|2zaN$tig)cy9ld(IZR|JHlzw5{cxrZuG-2#jkqfc1
zs<bR~{kd~GtD@?-!#5QBdP4E;Ee`bKB%ywv4|2dNMPyvsNRP!Der}`9<rVbv_|Ydh
z?$4RL@N<&s;~31Up^jCQD-Ir~#*R2`nU%hPxDJcowJGK%)T*BGO>s!M4S5R<i9@L<
zq(n?GSMEsj-oR_6dLuzFwnpf{jT<35ju7_29fcPnCFY~yReJXW!z{cx71HEz*RS5K
z!R?M8mM<_C2{)}k*O&Uf8el!|99dgL8RfHdBgkC>83%Z9Ynnnb@Hph$L+U&vmM-JY
z><;tk$f)#aNOYeUCK;fvzh6^$K=h$!;QC;6%##c9&hi_=(&B@)qp4450<JZXkh}|$
z5)$y!m4QthYfz+S^y<NArW1e*tZsETzfa+MwTpO@thh+#?7;qKC!&KB9Y><qI(m)h
z%O~}AwEB9so^l9!?Q<0srDrmhB^VA?96CVB_k^7KhVv9#g_Lf-A3k4-#UQSI;^4aJ
z?t7m0TP%>9R=$6kgV0F2i;4>RCpWz>%<CSE&bpZ^_c0#yG3XJ@&PX4!`w;;$*a|-B
zs@nEWjcB$~TLxsv%PUHsb6-FeOr`x(#D#x)|KLuCj;xE$45_`I+n%HrbytV<=T9R(
zmXFMjU;daHYoNdM@1*Yjk(%2lotwZirtYw6CMvh-n_mG3|LN*mtKZHIPMPeOr-{f>
z!Lb1x{OvHIbIWh2wu@d*e7=jtxMcgEv%`$PvlXG<{Y@m;t`IK#38N|nK@QLN-TK3%
z<)~$@>GLKYzxrs({<mM}xo^q8?07W$HA?5khbcr8+dr*68%1a6Lr<`icvqA=Lg*_c
zO~8cuzotc%?E2H7qcv9(#6=ShY4>-*E%(2RuDLh;Q>GEf1+n|(Dm*`1r}=vH7|Muv
zXomaV>_3uh{``>Xm+UwERjQ39o>*?IY9nF%XM#%W#CO)Fb+hx+ZKICVZuyxlykIc+
z!)KdmJ5H~nm=8wpyRG3XGigxLKG3^6)k%IOf5Z}B!u*kK^Ve*&C*Ma`qdYZni!>!<
zw0%cy`OXr!c*<H0pVID+7@OulK4jj#nN5EO!&3m(_#gQ|--rF^9M^=_Td3g<rv8!G
z^5??uNBs+6tD>bj4}k#U|71$9Gtz_})dU@L`YS6S>R-Yf{b_hAI5DO4@9?LVZuv_W
z<^Q)H(8sNsGLwe?a8DMU`3;3F$I8Kb`a$}og@1EjE1K1maAey48pHbOs}|eDp{~q$
zV>3Qm6E^PpU-~9doBuAC>o0S||EC_%e_G>9{T5Hb{pXCPy|@0AJm#NJ8hO%Ss%5aS
zAz{VA&j8)KWwd#8l6<@&@Jz}?zdc{3X&$THjn_w;S=;o!5xs0(SvE7MkNf_dZC|--
zQ1(l)b}JPe#lEwIMTZc|NW&EpHk0(6I1(Nf3G?{Ycw`2cZG0H5rP&~EQsQMS#umBw
zB#<V+&f=I;SHka$B+TSyT61US+xB@C5GO}QVE9@vYF-6l5?XoAlb<-Z$)F{S*Zrpy
zXIcZT^8yFoNk57MJ<U0s1r&^|f=8U9T-eS%#+rJNR>v((LdqNEYZ3M%p%MeLuTt$~
zqAqQIwibMWH)_2pJY156@rT)U4#wL$f;iVlrE`5VGx+aLc`p_0s6v4_ta?%fxt3|9
zZW5uZ4oJxs%FReDbfZQz^*2-q_iA)e1A}{vbctRvk*qY&qk*bfm$Q^&G)b62u>>cQ
zItPCq-sSf$H|*S3@0!9{2(#nEop6R*rM7vS4rRXUD0oEMid@I&0~x+wITT-5G?Z-;
zyXSQ>uTqfcsEeJ6#O`g*d2uabNEOC&B_&di<)5&~YJZdz)-%7ME_*@Qvlmeg_d3QG
z%lu!`a|9N&pEK$8Tx3b`NL~zVEcb-|5vbQ>1Jn7W>4@iMh&}SV$kl|_<cDU`L#(jt
zq0SLB^tBrFdhS<g7gFTj7q)lePP(s`lBOy*0xt!DV!NGlgD+&ojbJyXw-7zr=tpoL
zcsx8oRc6;w<uMP+R~okhgGmjjA=R_n0r=(4rWeR-1)kC>DX-#|<nvxR91MH+$P-k6
z>Zab=O*C`T5Y58EwCr&|)^r%>l;yR%{iLHJVcilcsF<$gBc9TXxMe`1Y*dQmNw`T9
ziBRVjWZx4629r_$8f$ChnuLx09V-zzIwQ<)A|aBUn0gO6w;qf)z}$1=mmy(uc}wXn
z<tB;$Yril(a6SqU#pBn2fBTv86cPfv$bTd;fM@PgldqUm6Yh4fm1>WUb@wt$s?xm(
zYfJM}B7Z}r5-i6@XNH;n$a^^G>Zx4Dwhrx`(Ht3I_r9f!FdfmYEgA4N8t@9L_@Yii
zsiq+Iign7l<*FM_z=BpNB`4FIluOzjM}?*$IRk1)qv-;=4`&s94iUrq3G!6h1ma3M
zXp5A~E1O7LUOg-8pqfj&?MIC_Jorag_F@;jMW$DB2vNw<1)n-gsSBYQ_}N3}Io3#>
zjAT9lm|&21Bi4fI2p><CoZy&IT|jgE(4!*TPWSZ?iN6w2>}kh=t4P{h?^a~Hqr=@y
zvc-L6L73Y4C1|uqMY`=2#m(M{9z#n+$P&hIyV%2CBH{s>OR_u;E{}bnevd81RRf#}
z^%U|BauZMR2^Jd)siCSI_jz#Nj`pV<Lke4FmIO4kX0_!V7J8$Xs>nG=Y@N_VUJ!gb
z^YayX#>$#}-Zx#ver3=NFwz^D0UB~+z4jf{bGQ^-#MYzmg#?-vLXbF@NYTwohx-U+
z&;=-%l~bQ0tlDg|^q^eH$uWV!&~Bnp1HB;B*RQN+tmtbQ5QB3sf@3-nv3jEPP$gE`
z7ExW1pC(w(dhaXdg5yGseO_08<@sdT4xHwvpLE3OQqMNy7Yw|Gr;cTLZG8z?My1K3
z%Os<RkUCFB)EzYSW5ti_X>Wx(lgHCz^8h0xU%5P4YWl1~?G6i)m1w}};#zR#4EU*Y
z6#BGAngtixbODZ)Hq?reDjp~#&NpGt-H=N|(Q3X~uXg)M^^&d9)S#N{p}xH~92gz9
ztSHj!^$(yG-1lpev-adM2(6s$DUMHuD)y)z;1?>7gElwOGK2u_TEba%f`)-Ic%xSV
z2q+BB7V${MqgU}}2Wns!2@y!$pE98aNkyX5+NY&G#5zBR2L7X`V=A|U&A*PR{Q12$
zm7HRA%<sLiL?8Mzyt~pE;XUea;QP^QnaM0Y&O#C;CU9|gKna9PDJ9K5*k8N#=KYkx
z(*xwA*85KUD5%`Dcskqm!6m{yj|=LVRtlrgugaxRZxLoh4_>_yGP}w>Sziu|>Ol`%
zPZ?#$P|u^a(#>hsR9`5qFa|nH78(FXTnAGeW4{q*#ErkRtLH3lb@cG6^A-B0jYR0a
zkS1?xQ4me&HHT@aL4x%%&b)qWz_dFi4k4TrfDM8+ulW-+${TUn+sVNWu!@PXgyX56
zn>o#6^n|w(1=E;BDfEOF!p)pkbbKz9{^Um1Zqd${taat;vy1OxnwZHXYuZ$0D53}H
zZftiCf-59kKKTj|SJ){Cq1ai}dC*s$g{X!-yI&YwuNPJ??Bu^tZao8FS*}m~dfE3v
zcTr;bfrhUU+FL0hDRW0+H1$CK!1l@X)Nyno=tHr(lGlfm_aX<_>K2QquK;vj=j|Oi
zy5t6*JA-DWBp6bXx0FNS@u{+jc1MiRPCB*C6_fa+w20<F_l*D9+mjdCVYt7CQbhh$
zv|Z^7zUx9kSFC&(nF{+$NeLVmN>07?YJi1fUKN?&k=6AUfQ^-aqB=dIsMVwoy0zGn
ziX?Y88H<tG*Wh3$%}6-)R2d@n>e(adErxhC^f`+F`YC0cq!*S+igWUyjqYjT{-kpC
zzz6(L>kv37Z`gKS-r=!hV#l-Cy=}|JCbCTBgS_o8+afN8Z<hCdXmluwt7qrcM7b`k
zs!UBe>-5Xs{(Bf9(^%a@C^5Yv>@9#wNUB_?fb+kh)H80l3}b?UqTfjAhS282rq{y7
z-FlV{qmNHuONo5lM-f=#10jA&KQ&YDr%Yyi`;+;_m9U?vhjSakj+DXOJZx#j$PyVd
z6>m@iJESE`d(e`A+sSouVI(`DucHbJC0EnX@aCKX&%Dsdkvru@Qo7!dMP6A``|{=F
zC!-Fd<dzn-^z(bsC)dT=qhQ1cj2qL2)jB|nU<l{_hB9^(B+#F8M{qJ?a<u7f30<4w
z&kxi^;sCh`wC;eVy<jLknwwlkPO>)bbT^l>XVpM#{?`zn^E4fpc1?PKJZ6Rex)1sp
zfB&&CrcOdfmUi+iaY@!TuxCO9A<^P}hLjB!2DH0d5ks%TPlGW0B43GsC+K#?#<~!I
zkC7k-N}P`rVqIl^oD+dzZTk!u?fUk2L=dM3ApUj2@{9+RJNsgez(oY~qkEWq`bk{s
z3Mviw?}-WJG<z=mp5+`XCe9k**tgRR5R5o5zwiSESFOfEdC!0np2swxuz9Xi)6z3N
z<v2!AGC%XRg5vAll(8$b<FiZaNv<boP$G+o!-5Nn6(J)1DpD?$*5-cr0)&+lRN2a1
zQ1bd`P)8yZI=Vr1iyqQrE5jyMg$Kb?x}}>clApM5g<YzL9uJf+YLN7lO~kvOd4!~W
z2{`f_ir6_4X=MjnfOp_0<Q3SLm#c2~0fVFtB9mZatD>nU3VU@k*8;yB;jJf3Q=2I*
z<ES%WG7xXii1fnDM6f?V7x<$V`AO7clGoZb92@ZPt$-&IMx3ygl=u6o>thP@;>#9h
z$G)N05Pn0Q1V!XI`3l(d{-eRn;Cj~F0E8@K#sQiYQR+Q9{0+L}3pXUHtq0UoSR2}@
zQ}Yo*9ienlg@kaa*FLu1qCD>cfzO;C*6Rw}CA;g*oiu23H;;@V>oKI>v$fa~#fPzx
ziyPY(aoS4XJaLL~mIruwCYhJT;NAS+1YaCkYMFdz&BC@K)72g+dwPVtg>7e+WvrMN
z;wyIp_D6+ct(U@I-9Rtxyjo>16`4@D5<;ET2C3bM3#{KQ@nztr_E5ua_`@#o<7=JX
z*^7UTgL9-8E-%9`7WOwG4~V9e+QtAVhQY^~kV5izwl0e(n*Z}Rt|?d*l^iQ|6G@Mz
z4W@||924bIm{jj@93#YlDzlcX4N8Gez}utrfEoi$IdhTwV$odXx>8uq_?;x+O4197
zE{}bPWYnJj5jj^!b0QfX_=kT(QTK@si;ldY{Fs1naP!O{{Q|{&1S{@+6(#k+^6{34
zM*-CoVL}sLsw|E^h2@2a9t_bf%0Oum{l3_4WTljBg-s^uErQ*BC(jp15l8M6O8ime
z{zHGtSKjkYk3!8{EIef%v$a&t-QeX+A_U=dh+$+%QA08pw~SDUuz(-!?uV{s$8vR<
z@e$1AY#YR?@PyhVGu&84Pbgzz!5pR)Zz}RfCZriDPPeJMWNf2@{)0vvE4P-EfV#&P
z@ChCOJ3RR^;Up$SZ3OtAdaLV&fmsiz&UAF>R#~HiMdN|Wc7h~Sxfd?=HF%mV#TnIj
zq(oy<OT7%8>c(8`V}fH&me;@UZTWRnymT?@LDIke!+vD{X>#()CHz_>{xW9~a`(DS
zy<Yp%wN_yDSTVMF7mM~nw&uwOP3bR|bORm>I7B|Y$x$!FM(LjWy~}v}{l>(4w;=Y~
zk^NV_`#irkfQT*ZlH$~+kA{6mub+v%mSU~H9;GoU?#7=SpB&8^{eKD)2Z;qTpOULL
zZ0vqfJpVZ-@!;vl5>N3oqFrW*Cb-JfaQAH|B|<n(^;vuKFP@{Mwe$C(S@O;3x#NW^
z6DzzKO#GquM}lsAtb3z^s_UoCaKCac_LAmgDvc>yO&fb7=<ZP<`tJ(}zSCcCeSWLm
zoV9am#2*c|EfTJRL4H`vqPgFi!3p!JyY`jMYt2zt&Y~84M_$qd2>Pe5z;pVYx5=0}
z)(0um7A?@rL0wy+BP*yD+#6V@qcLYpV`$oye?zQ(X^JLJ)1T>gyMESq#s6fVxMUl@
za0P$sjYVq&#@o?LT~T7KeiSM~d$y+50P2TDUyktV(HYiSiHX`Lsuyh6S~GZhb-(K_
zjXWEaNq*|4PYJ)=BA529`k81rWkp>hj?=Pg&03S=ny$p>u9v)VZq+ev%lT`TC_=>Q
zYoD)oS*>V{eJj{jviQ!4#(K}&m@T)?^?AmsUqJdZ=6pOlWyTxS_bd9ZFU;h7N$~jG
z`Q$~*+z&;a5zo2xqjSoXjn&3!`P%r{Jd{Qz)HF?*Vbl5D4|xr&6~QZ4zWs9KBMmte
zq^*;^er-*)X5SY|W6;?5G$v1t7ktAQB;;-3jyC>=f+tZLk{dN<rfF$f$s3P^w;q-W
zZmqs`>*KeTX9?65D=%Lm+T0b3Q5r8_)0H?Hx@2Jm*3_4$sSoR2HvH(Bb$x5S{^k{w
zwK_(L<tbH1K@eOb10O*l3^7sSYiXO;+1$M}<NNf#be2Wg-37O`@WDOl`{r(w#re)8
zpjJh>xBr9qy~9njbEIkNt-lSv)6w`9==?YBw11oTrpes)K;s^xIc!YhJ45qYp0Tle
zbKolXH_;n;ELV5zc*CXBTN-R_40f#3`3|ypQv(OEU?o90maJ9+lsxv4Mt>7Z6YOqE
zDg3Ca*!+f`{O;!iTctLe=e#^NA>8bVp8uqNQIE5=`?uJ&iD|?eX0{VN?KyK6e3|iH
ze`*Myd$PE(-d|-GV)#sZV#8YN5Ql56vtGF01#uXwG=RuLiQo5MH94WKeZS3&X=%7<
z&G5r1hAuZutyj3efM#vqV!2ss{-GHSdoHuqw<KuXWi&^uYGkVY8y-xQ(RYb*dr$Kp
z&PiN#w82~&a_N)jy16J16iWZnk=%dDba`*ezrj<i(fFFtGLC9i!oO#1{(LehVy#Y8
z*Mhr;J_ey<fBdHf_|q<M3hT=yO@KNWQO!n00m+m5LM12)WbK+#DRwCKRVbC~e?!r8
zenUwguQ?UYU#Wd&`usIDU^bz%SjWKMCbn&-cFwg5Z^do>qdJ!k%O+ONn)~y#)2r(@
zPw!j%duM!Q7}Mam%k~WqW26j%$8RX_G?iPQ6-BTHp7U!sZ@V|&#$3xh9q)O=;LW#}
z<~m0&=tP=~h^Bo?^I{rAon3H?vHg96Z$04Xm<xBTj!hY_xrg!or!IF)4b&*#0g>xP
zS4EIFS-am=dp~uH>IrB-6H_=SxS?)Z2i3bE3~!EHghu%yy|I!oiAc8>$?mT95&GPC
zfK2e!E8E+U(+Fc<+n9s1uE*IHVfbd=UW8sx|KbozlK1_F%9EE(n&%Tn%%L3lDb<y#
zO<`g{S(*>is|6`C8KXv!9Jo}KOVbm^l++MPNr_dfBP9YO<p$N=<r}CzO?d0j%n9De
z`~ZUV6#G#ZG9MKCO-Q!Lr^(4u@1j@x@VYgkcp!6|7`~wJ+@K%|AUA%XJA%$tS|Cfz
zk{wA2zy(nk<8lDHRCPz5fcQdR0BAq{tHh<o0Y`dP0s1o-)1k^>rHyl-A?)3r&n(Nb
z+wrW^Db;;6u%ud4Odq+4sbvd|<wsg*3zRb;>z}x#m^vIo*jYQW#W@SmYVILy#WIRD
zCZQKJt$6~|5c<q<!fd3l25->hy9M?IiYY5fC+K?WFL&P~?Xlh6I?R<U>);oB<d(7P
zNLZ>RlBn=h3nnv$2NX`q8J)mOf~!@}L~0&V4PPM1Pmzne)XfM3dL_TrqTDBOAo4{f
z?jiXD;q(GZP;GhUscX3pfW-o$-7h%dM`kQ5TdiLdoP$=Hc*!y;8B&+D<(#=xeGV*2
z;VhvBA_6hnoOq9-_6QS`_~bM?#!(Q*H7sLa{VbAh_puLujCgvsYyyUvX@UkJ?Y30U
zb_=}liT&gKGZv!6R1?scQo^07RJ6hwsV4xvTLmLhAOyWY&`Z{(+QZl+j?E_6jg;Y!
z$O*x>$Guc`n~|U*%0<uSQiAD>s`Ujuy-3!=*HC0yVU*+!*<eWM%$77-k>kKB#4$-G
zQpo!=LyC=`q-DrRQ>Zb>H7nIe&@+x~%)->NN|?+daDJQw<A&PaDd3cjn;Ry)*_Y^~
zJ5Q2|uC_LXvnw8lw3ewlSP$#Mq8(n4wJ9Rmuf-Bp9IKQbTS}U~={{IPE{72hiOTN4
zGMH#0NTi=2Cy6Z7)+EXePj1J@7XY9n;FD)l@^^6P`n=pOe+qd=v%}LT(kip)`ul^G
zqsrO&e2xtqT$>tA>f(yAj8fc{XmXtwJzi}H>2no3sP06)A+DJ+Dh#%*qpfbOB7+S>
zXulP?b66S)J4WC2I~S7eSlm?P?k4p($IICerVX}=Ak=9QhNDMadqYf8&bAiuEqt#k
z&&cRqK;sntl)4t-N&>>93(ImV{1_uk03b}iDk9u|UnTTDqYxqRvn}AwMfAg<2g2YL
z5={MwPN|Jn7L?<yd&H9p7N1mJCQ6GSbtmtE8+ac^IS#b$%>4LY0S+2)=F>pi8Kaz$
ze}Zf7ZV6|~8@D2%z4{%IMW@sXUnsIX6__`$#^F!rwVvwZblig%Rdu=+iFmV7yEcKJ
zK)`#%B>2#^mk~~+?x*-~KqA?c{CyBTw$l%0#*dB8p?vj$h6W5NPw7)B7U3Hyg?tO#
z)jW7wB06DwC}7!%$(Z^at7lc2QlZ+OXnb$V-;vh*oj?1X49C(0Pz0%)L3ht4_U2;3
zXHx5$Z#_FMj@7&MCGl6eWSM_CD#%z|fB0?VhBvBTSFF%_i@tVg^O-VOfBy|BIg$6)
z0*m}KclG1D^jbn*iulJf+2ir2!j=63;k@d!oy0rVS`IT%Ss(sS6xqPPKvZ~i>}ADL
z)QhXXhX5A;u1KLx{6E=GTjho1Z%8aixb_6&znxRPJw6<$)!Dtm`hT(a?%`1Hd;kB4
zLTH@jG*hWm4pSj=m?0sFNhczvQaPnb$i$ct<$S2DQmjlU6q1|@&0rjAS>;S9%uMB+
znJ_+?!}`AMd*6Glwbypvd++ak?eF*Z{p~+oS69~<pU?a7dVfBz*YovwdjFia4nBj+
z8&`TU{#s-1^_QX+tqYk8J2hTQ!ssnuPp{qmgY<}ZQj*-eODjFl1o=*-D>=4^b4MTA
zoVs@+DXK0hN`jUB)-~nJ2gAk>dqi%?-Shf%WruWX=FJ<nb{FlOE!QkN6c?9swz777
zOS`Yi+iN2CljN*d-KOky3N@<hG}b`q7yw@XDN=v^lH^9$8wi6aul{UvXsPh8I9dM-
zo38iE9jl7!nPgJ~Zrnw!9~8c{{K;SL@=i+=O?HF~%yc>Gz;6tco~SN&&xazO3<^o>
z0CNN6n>a^c@6Vi)wzOWq!lc<MR{XO@(obvP&Ntu%tKybzPCjqEi@Emdi)(TkC!=*w
zMk%h4(7RzZv1R$$ly#cI>tb)O)0#Fpbh`E2`X5j4sSPnp;B;vxl<6iNA$_spy>_yX
zE$_Ht^23j5b<?+YTE0>8&Jqnh)8LbkKM?xt=IW<oksgh^R02oNBxS91z4PTm!3w7Q
zl37{vl5HjL<9{f<6h(~h0+dDr?j2lc;Y`<(IK4tuLauqIv<YU*r*j7{h9yNtSQ^e$
zxRcu&kqe6$;kMkEFCVOBjb)>>l4Q>&$?l1?TKQbU!UksgPcSiLmK_1BmsPX57@yb`
zyRFdY31a0NSA=?P6umku-rg?y=<l%U%wFz>m9z(nX`@UyPXMaON|rMJu-W4(deDXS
zaq4kaOX`(oiS?H2qWZ-UIdRLbOBiceCWzSc9nQRa;xp@aZ$@<4S~3q^!irYzdn3Bh
z@WbHu4obQ8RgDM0F>!^Pyog!pEs?sJ=rNz=ZtQn6d8B;dl(&T3zPc-vop&QKuSl5>
zkFoOC1$Aj<RQ)bQ9kp0C*udOUY(E-*J+u3Uyhv>7hsNzeTU6`XRM%?#_zCuUDA@Z=
z8u~=8YOJ;%Tx;P)U7h$wgsq4w-RotQ%noDO$TMQ+T)!g@SZjUxbVlyx2f6Np|Ei!X
zdTJTwz_PvOBF{by0znc}c5h&mbZL~tL5X#hR^kOYW|<ee6apnyS=ydWz4@teC;Eb|
zm8xdFrVY$w*#W3uZhOiY?-B-kPs@(jZP9+43cGVH(rM~U<VCZQMYT=K9VdU6owwQa
zvEf;cxIhSAc@hd3FRNr5Wg6GTvBXrp#AF}HTAh!AgX3Y@xm?{<qu#3Ud7lK&N%8LU
z{y6WoH%c^}n6<%g08V+i<L2n-^05Zy_V*YH#<*u*dLR{N52U9Ks!R5XGr@mWbyEB)
zff0QiW@e7eKMLFR4^wN@W!}DsS$AQ*nBCfSt!tO$Wm0Ek!xFTXU6`Ut$)mQ!dj_9>
z+Hv>NrS@-_@FZ#2C96*-<$jcZ-DLOm46^pxr@P^fs-p4sZ_L;9Yi*Ri(G`RrwIy||
z5xW#ce9xBj*(dh3d7ro_6`q~5+>IR+8}b5qJxQ_&2AW^a=(3C218OlCS@Q50c#(aQ
zqMjKjZTVr3M9OxnJKL>Ri-;*NN#$T;%N{k-%ihbbWta1+FT?MW1UVW@&a9;)^6fVy
zKPKH+BThtG|L(Z&K1}-E#cdH09>C51gyAvB4LMO;lD4O5oVlC3amv&FpuKsBcG{u8
zBc~84!AvCn0;@@lKLWo=Kpe2sG(D3xzj2`?05XY7N30uo@)Eov_lTN=PkF<<RgIX=
z%TfKqz3Uq#1DVn)yJHXVI?d+7g_-@OeLs3xEUt#l4XXls_=?BmL5eVapsx#%(!Nx%
z)mhPyJNE_<1<~t!2i_F}v_S|I@r2a+jbP1;xzD1+P_-d<c62>$HPJD5+_b4BDvfb=
zfu4*;t#pT?=>zkzDQSRj;3@nWtx`dK)_oRx*Bq!XewD*{*6_TbpgO?Lu4j7=v^E?I
z!(A`IoSAv=-$dHdUaN#i9T_YRJ;=dKy<|r>X6^1-M@!t(6FiAgf@+R-heWs^=GX$m
zsx%Km?BSPv6^WXDU;GQ6Mq=zQVEj>67m($t(_1-%4BYf_MrssAmh6k`FC3v>XIC*l
zwp>S}wc{}7eu1eI5R=>s*aYMn{uSSBqIz%W1Zg*WA+k1zAy987OFe|5vyEc1bd5CK
zZ7VoLPSZG9=1(2W@4b(Jjzw&IA5A$J6)lu!W2ZZK=ZOS1?OFvbmZog<){f~CN%Nuf
z*H}R=3=3StE}<+G!8DUu^=*NPy#9%!T*|;He;}Mjt{y{ga4mZDBGW#hne`bjPio3i
z7CfZ+r6yBWkQ6^cPmqZ_gsqt8c1@W6e7bO54^_?gm>O?_EC#xjX|e<ssB<P$>XA}J
zsYisg6YXdf&{z=0O=FU!AzXu6%*!CqTXL8KPg+8)p6D@>G%s_64g<9NVjEzU*5Otg
z!Q(Q%rn4Ow#&KW3ge!RT0kme?K2B`3xeCt?bg5h^(sbEV16f=l`(I(n;9Wt^;ktPc
zd$u`Cw9gPJGf;9Jb-GWtLU1Yk20RaKN_tNd=Yw}Rv3br+{e2`iwY2YWBSnUM61Rq^
zA-I#x#x}O<fc{}ENQJRBm@=^6AG{k65u}`;pi7{kyu`RgmJsd4xszW&sMq$b*rGeH
zzE<}$<RFwB<)qaOiwX7k`}+7tS*_%2h^=6KEO5N)kgL$fAAP7B`t+z${8OBxchbdU
z_@RL+(dAfRa^#TUp*Gx@wFWOwaHlW6t71?fhgCJcr%ayRfWPD$fJ=P`czT<BkgMj9
zD+w%?aV&b1-!2;aK!7(3@rorwuFFV`{M<#uXRc)dpGeU2v>1BT&;x&<hc82p$nis{
zQ9;&Vo)_S!=QK)BuMYF{eKt8z(u}Dbof>9akIc|%{bXi-y^H~?Eyj?XI)G^|{ODef
zE8kqq&~tCjQmKKk9Go-cjaP4FpjHr8_kNfde}pacIDTTh>X2(|kY<7>mh1BJB}}kV
za32r>k=JQ!YB#Zpku217^h2V}%QPmX1!y_|*f)R{McOej%AI9vr;yLgNPvE2cSZ!N
z$&}VGZ7Sr{YH~Kvn|3KQac-K6U+5&H;1b?g3>BYIdX*2p%U!#nBntC<;VMy&vz4k(
z46J}O!RW+ua8s{%s4-7T==$TyVHv7EBvoGx;0}kG_clg1+#t9dM=JBRnE?uQ+xsE2
zCbfkm;-#z|=?!7jSbwjPRt#n~jjJz+Lrap{DH42C5php18ugyI7it6Prv%8E-O`9y
z-OblJ#m;A3&Sk4}gW9RasCbe=Q!&A=QLVQkAEG#O^s??NC+7GMNo2J)EQ%)(?F3~P
zdz}Y*Q(Lg_=_BxH0EJApX42?bdA=V;m8wis5?rNj=kKR9Q?=NnT(Av}A}dBCD`YM#
z&`B#g%CVwjp4#oWy6PfNjharQ2(PArsZcj`c7actZ-?ht@8Z`dBA^3!<%J%qDr5jU
zals!zUggS<4X?(W8zTl5Xv#B(ZBj<}L;0N9=1`gnY2BEMike~Hj#do)KHLRl9ruL$
zXU6Lrjtk{my|riL?Z}6LZZSgGOA({4CcW!JNI}t@n6A2kqa}^01J;eh2;s`Mkv4UI
zV{%0c9T$fybBbjTGf<J|&21PZ;*%te<XUZxJX|5Yox09nsL~#MinWR}pFIEWQBLBS
z?|811AZ~7WFbkRDDb`L55|2h35a9G7F`(+{=Q|Ww=ktNu^LijMc^$i|*^%7bWtZcZ
z(Lip{_GjY7{Y^cZ(?fl3?lFp+IX}PhMO1*<yc}kPf-Ad*6z7ZbHbMia_(fbx4J8Gs
zGM9<d@TqR0)4drb$!adZ(SjQwctF}fAUF5P6VWxjwe~=BMN|B`iM{zcP`w>%pU-p+
zfy+S&xV3EsR$Pk%qO%IDlIbfYL`%UnvR6s}P#Y`1F;#W~3BMrR^`7qz;mJVeqfNg|
z)r@UIh-HrGXFeXBC|0>vYoABJS#}z^66Ny7yC!8pMqpKGWmS7}qw;KcC|_QMTLU@r
zv;e1PIF7W1X!`=XNJZfz2OO`@m&6irOvw<ej1Nttc54X{+w};@f61O1I^s~ce{tm_
zZ^DhIRj0i>b(!5L{oK;b?f}flkL1!DUF0*VVt(XuyQEworQ|#XZVYO@wO%8|yC%5b
zjb_AzJww{;fY_w2x?{=g%|O0m!bgMkmRj!6CJoKHLa#Um`#7Y+hfv!7ZsK~zE4P7G
z+iD;x?GxNbuja33&(x9QX)q&Xd?(P0wc$Bs4vt#PFQp71oa$AZsYfM|HbB1NMf&*+
z;D2arA8X6GoaXyrk{hO&;Ru?5WARUoJhrhs`%cC59lRmRm0I#u%^g`qdB{KXs#Cau
zuK+Ci8ZipOcS3!r6p&c7>EsGif(y$oW{&bcmZ8!>OYmIVTTEIBc^&Kq3=JSX?9bzS
z)b<b+INmmybqG@+8PrZOv^X>&>}+u-e^LDLmL*KyY1KuG7<&`VRrctI8G>DcTSQ~t
zE<bW9W_px4lSmN<pa^it@^@n+)l%Y_SQ(-n8y{T}Ahm~sZ;~-<0HLv;Zw1Uc9A~c0
zOU%b#fTx6Xg%<V`+UTZtZjbOB)f<et&k2;HyfP+g$^jS;b|BYa&J~iSKLUifck_L9
zt~=OIr&3i22_K0n;thIuTR|Rm)A+FHe1MlT`&Ih&xnV_2%A7hlVa5@LJ+<Bi1m?H4
z#$)GZY+ts|@sf90oa2jr|BwUxVb+rxX>2F>YGFr~A{3Y>>=JHItdECJt1!rMYUFt0
z(V!e-z#k@VtL>O;yACiHu`Qb6+>`9K7__1<O&&Er7EpUOB!nH!JW6SJd)SV$??o@)
zF@UM5f=kV1llcn9+!Ji!ZBESz!4s-B-%5~~Mh8se`L?Nkuu?!DVX`3&;g_XYi<BrQ
z$5*?=@ofr;Mvx@SL!0H;67Sw5T#Ha@58enV0k=mPSBP@FoFg6f=%FVfPLzEqVbPjv
z(q;J3oBK*|doJK~LyJqN5pKYGgmmwTZ^rG1#se4f^M;8|?55)B>w@GDm)wV3hXz{p
zUiCcsd8c(CUiZdZb=#@@c~BHGo)Y10nIOxNw(`$Cs}ke@=~M|Y9ONsanzMkjGoqM1
zxt}vcW8(TzfbCBc+ent=TdB|$7&GF06V9f-W=%8amleI{;w-Zn5nqG|r}Bq^^f)Be
zWB+^6@9Z2}P5??MX~)y9XMtwXnK+^^&xZPvMHz@0<dPs%II!t6?dYn%jL;X{AZqcP
zpu<O@`Wzh5qUS=b0~0RgkI*e=i>Dakq$jc@9JmhC4o+#-FFW6577*WXbhv8;DO5Gm
zTjVOD3llSdY6|n7hI3RH+Ec@v29R;Tyi2Vuu?T>u_?I}9_Z|^)==7l#omBXEWv>jo
zuR(3Tn2*><VfDp5<fJFn8Z+@LtD=c|<XtzuMUqUNaSzB<ZBwo6GA^-Cs6L4i$>YEi
zNa6rI&Oh}SWVb5{_@~)+P16d@7zzWYXrFz;FXJ!)%fL4{Vj04hk2c;pM%o1hGTY#O
zVfok1tqn7X2<^TAmhsWyrIfz;QFc(BDQ@}-$G8Q#8feLogjoh^ssp%OubkitH$jJ$
z?=#-xNyfxg(3NmZY^^cpFgF4k%pM<>ZS*v)HuX*|DK<)!(V?diVl5Nv4^3oDrzh~y
zBHzPpNIw#FAPe>^6EkJcuAWwJTGX#%VxcXe4YVk-Y~B^B>ckzjiu7cnB+G0NCkq)L
z#H`jOZ6cTkAT4)QA8ol_fsF@!=f}#5Z33AuYcc*|ixGKg^C(bT9Qkqh`RBf-eMLgm
zx14vA4424SUmk%V&I%ZAf+sEEY@|@JeO&#Q&{2O((>{{cI9a6jFg&(alxYlAJ&2&u
zdx5qKtws3h-IvX!U8lQO(mnelNpjA(8m$q`^`(C6MBolG(~qlPI0Q{H?p)<bxDwB>
zA7+^W(fT}D)y=<Z5j8c#(X#5%>MbEEFetL)i&ar`@C2$}=T}tlw0ON9`K;K|lb;7-
zqF*<-<ZkCI-E$*|9e#XR4^`V2cvgGWQK}Y_(3+DOeNp8|3Gj|7J4KZrCT@npSsqxr
zX=nn@>Sl?NL(NB*=7Ex!bDXQaBaR1m*1D*9{!n>r1bO#}%h<y7I8PbU=IWQT&qbPh
zJt35}(B%2yoaknR<hS|aHIsYOxDK5aAI<0(7<&DL8i|tK5~Q7gMtyXJSdAMN2R%}4
zs@j7C&_l!44u$u=rcJ=#8-N)W=kU0@pRtXbk*oRkFM5Pq$n|yrYas`i;Aptr$RI|A
zpmP+u&L%f2hg~jX3LKgcvK-Jl%+9x}R+!A%%FenM#F)(NKUvwMH$SM-b;kV$yirYO
z9%C;^qn(q&^iOj4^$?FT;fbLbBv9ER`OZ)XqeRw+Y7CJd5yc?yz!7|6B~99}M2(Qq
zb_fc83{jf0)Vd$`%(V_qTA-Re)$a^6x487Cx$gVaH5ZT0guvsN7(<X8Jd^5zSwmF<
zhDGVAbMWhzDdk19@|47<MEB@Aw^X`?*2p13*sv2vNaNTwVxAkSA!7^&i*fD|U=IMN
z0^qmq5>MQH*>GR2*;A;Y#WT&NqYksur)1o$4iJh;q8yp2gR@+(#3sbLZeXu5%M_o|
z;;7UeZo@MkE<KUB5?Z)kf*h)`aUJ%$T1!GLilMgw9zTSx?kR7R81Hi%z0OB@lY%8G
zrd{f~{01V@qw<9pOGtD?@#PJr-2sN(-QM5ITL;Iydy3B=`^<IyIN|W9-~DYt{e_ja
z3#~Z=)|-BMRo6MPM^9GNG(i|C)CS(wKMKwH;b3{;gw0eXwstaAhQAZ2MXg6DskIJ;
zV?r&+x)91D2)7fIS&eQ_^9%el?4~#)!+?Fkv>ON>OK<cv;5b!1CE(psbdCVsKVHmE
zv<Vc_%4ViO^-pXRVgRBSPOa98W6Z+W!>@w(=va2<$WUqkM}g^by`m(p6e?_?GcQyX
zKr_d&OBH70WIcVu%v1@2wQX8GW(~!P{mB&I8T5#F#v~<)8|Z85l>Io8wA~q49LbSS
z0aI>9`c&E@!h(k&&t??Fw3+JwTVBJS!FKBN4~LK7G<>tvp&lkaHiH~vI3q@9%exD9
zdbl(U!Ta>*af*aYmhDyY$Z(vb$~AECe;szPuiZyWo%@f1+fvc(zxi?LR{AE0u(CvI
z68G%I11YF(LgW2)@<-$?*}}V)pMu3R=sr2Kxq@!;L>?wEEH+j=|NM_(XBIOC|0%&K
zOsvD^8R;u#{#ojaSJE9(roroOMA#{z(p320QiTwXUGR6Bs$!i|c9mT#_i6loZ_|-9
zUZ2J-gRX>94d)AYf$VNS?7Pa<PmLE%Shuj<Y27^mXd{0U`<*L@Z8f@2Om4TVeyT`<
zo%wd9aL01l9GHxvXE3=sRdA%`E9xM7WNtbw^#JAY-leOb`1R^T#iA!96_<63U0zfw
zM*W{kT~(*XTOv2G&F`j|hTS4P%$hTFzS1EC*LWED;*~W$x~tO3VrPWoKdwB4N#-P;
z1oJ+53K<xtnkyFkRZ_fLej9Ex>icJ;fK6jKJIG(xcq4o+_j4Db%oe`#^*gwDfyufk
zk;lK$*=<>2vLTKxxue-WVW(5mr`uv_Er+fc+9|q^3O*3`KOiR7eLHP3-nEhPSo@Xi
z-`4%aEhn>s>9lE_{?;hbzKVCu@@RddWm3|~k#7c_MUIMAN8(uGZ?9cUZ2vhj<$nFT
z#V9-LqyM;I6z1@$2?%*|e}Pd|_}jMp@lK3>r>K<Pe=06*^MSyu&3D%v2^OgnZHK|e
zR&9Z$Y^iGF6+l0Td_#%8iDTtI)}FARv9?jUkNgV0`sfZ`Vz;@8h1nTamv(o@a*Aiz
z@^+H2j4hS$k9NXJxdoN%jO}(#BR3+fHaz-v`WIN1^DnSrDWQ_$-(#|?^*6GpdjoB#
z<d1fZ5B{7VwXnw=!iKGnKd?jo%$pR0#x9YcQX)-YVKA5`tZCU*_FwI%zm5j~oBQdp
zZ%1?Q#XHGsDFz##+#-juZrO$fy8LEIZd*?Jxuob!45qiHt~e<Ex)#1!>uQU}(w54L
zNkExm!1zA#T2Lt<TnxMXrX>&iczK;2Y<c5e5ku$mNDx=fYkfso8=m}+wQ2LaWw!P2
z@=~=Eb6$IDv&owsw)XF9Z#}q0n80q1`%^Oe4-vsy{_g3GZ_+fp<MTvsYr-zV=3p>W
zkp!(}U8dEx)PhH|5ai<H)DNE7jQa6GZNxovUi{w*2wQfb?yvp%?v9_xeU4dbh**;4
zr%$5M_3LhIUoJd6kR;xvjs8Gh0PhOdZT`k>{MNR3Iq^J9u1Og*NQWZj3;rDag5NCd
zs-vSRJFc7-^AU|GT(@lmNH%S^U%a9^er(yBEjIT<>Dr#5N96CmbBGWp7o&eXf_w93
z{p$x(1~#%sff{f2l*WcRgLPW@7x$qb+-&duP3T_EUHiAChl64lZRBF)y^_)t&)iRZ
zvrSSv<>5D<zZnwt?${c$;lRBe&4i4TyPey`VQ@>B=!3QY#X=LwNqm>O0QUHkyMm?(
zga+dN^T6@637@|i5TciB16fv=3rl~KD7*r+Bt+n5bnuV2@q5|o+8^k0n-AP&nLBRR
zC>Rrs6n_8{X_r1IqT!6EEI4zvh<@@EPm^oG9s-B*(Es3``psdQ@LL`27FgrIz^22Z
zY-A)bkSQ~j%)4)(elQOm&L7>04)@C2J(*?hw5%!t{2EIcAilkV8%@23wgk-%&%K}N
zq6YRQ%|`x}29s1u+z*NJ0-zwqa2+NFw}$3RgSHGeCR;ZRpr&X~i0bUTk`an3-%xNP
zpw@<oizUfGboOZdurwMCWpcA$unz+xz%#i{9p*Bp^7t0*Pg$Iq=ry+)cMSuu4yFCy
z%~+W4$`vSH&@Zq~o*R$H8csoPr!(5FVJf_YEwswMdZZF0x>xYS1pt35Y0lc&i^80Z
z4*|$9IB54m)giXCXQDz<`-2*8KBVsMs+D{MCE9<Zn)qFwDfCwfy?l7mjo8uuLi{e|
zVh^6!vxvccR5`wTmv9Fk4~&qCYehK5OuGhbLY9S~D8L-`n1E#TrZUISQhW!FErkVI
zijm6YTd7K8rd3J$>!FZPbYT&}4WsTSJ%G4dJz=-e9yP^b#|l@6g1Unz1y1v(s1Z*>
zdLTu|5rUTeR8!?N9@d9aR&pJr-QkU$lW5I$7RPXC9aPL-psVE-K5ZMx{3zwrGyT-a
zq~vpHNAPRZ!w468JC1jIfv+^{N)u#L_4xZcNGgP?k%b0S{O~Gs6}H13U?Qf?6lRWK
z<H!<*SaE0+3uR@DMxs$C_}aaC8K5i#T@B|bxb_+*f*fMUxZAs%9QC8^_*QKG_`noS
zp6DVd4#9vXR=_~mv?(@qhRlc{UWQPdgvlnF9BJEI4!lKqz#E`uiD%izC=ATn$=n9S
zS}bD7kHvhN`J^h2)Wj&X*o<4*Kj232^Z}6H4og!}26oVk@isla77x79T*J~MsQ?Jf
z-3O(yc#dAouTO<5dxa`~OT4pT(wj<SW1$?B`fwP^r3a2zr`-2q^Y%mJ65}|bhHvk{
zNc$)D(cx?Jg~d`GwRRjb3&mH`2G)Zj?8&B9|2*GnaV}us$`JhENiJ%XgtP30c<P4M
zLg*fUH!F2ehc(^%m}9_#$LZH%1@{;zX@8pXdWxr--8JB&H>hb~*SS7r(1n{Wcw%nA
zM80?6S_;x@jadN43kW+|nw_z6LQ~Md*<tQ|D%2~7;Bt&JJu@}Rb~)b1cYj2<QtMbi
zM0AjL@DG*urdxG|pjP>&O=KZDiN;KiFpE`=R>CWSYx98MEiWh(t^!=WY!0S@vKqYD
zW0~o6T(TOskeQ5XsqPkPby3v;f;T;`gs;xfG+-=5oBJ1d68hY`ic2=OXZKFe!KHVX
zR(rTKsU6PTTLYWJU!{nX@yXr{?Ut?NbJI9xUOIcH9=2Ji0N@cHMOn77>@RfY%He3D
zYB;lPEfgeFDx%35`qL7r8#<`!{U0WTo502?$7%Q}Q&sQm^G*oZ`CWOkgS1Qd6S5-Z
z>Im}MKz?+sHz$Z0+c1+#TSY$Is%dNC-we+kM{kB=ISLKKzK{{moZv!tYfA*tPWh=&
z*>zL7ryP4BX71Gmax6*hW!JoWF|r|S)5rTiFAl>n0a7!O<ki9WIJfkvNhV6!fq@0e
zjdFmd^hPEI5-o93kTIRCMBPaQ0QX4Y1_HJvO9j7zkbsOoMpa<{Oo5vRoy~KF66@W5
zaJzP=(m3osNDw8q8jg*Et^M4uI`$f<;m~9zaVzE`{ARg3Dg<|pQ2oOmuQ<t+!CFlg
z{wn_AapHbjZ3Z%y<LB0L72^YkkGbjP$B~fKLVwh?keM}*SCbkxVP2;g;a~>Rg+)Sv
z-r`k`apO`%LQc5@`MEdYsRx;Hw66&%0hKg-n;2e$-U@{_A`qP6YkKCEAa^_yg{nQv
zj&4S;XH#k3c~Isa5A7E8%2&Nly*uXvOgje~GmI*Ja@#ta%d_GWO^5j#^I7C3ki3KT
zgUTmudX|G~_6E7{YpfPGrTpu_+8Z^En=Yv$H@L8n((hfN&?e6fv!M5rZ=HSI%~$Q!
z=PwkzOf@NCnDic`0&vrMJO`pG@FVlh6Lt=56J!cC#>whL8|Dlsa;ai`0GE__p(n%<
z*XSwQ9fFh~Vj%ZIf=V4ye12GTJe`VZuT{-?n)`TSA>A}-tM_9<U(-R~jI)jS?<xo2
z-8gB!78vg*9w2$9kVC+M_Y}1NDo`Ug(N-CuqC8iZ3Lcd^Zf>KKHgW(vcT<gkV!oe*
ztZLG+z%e$ZC)6I#7Su4r6Kg%P31)k`i4HRN7oz7~dP>fJdCC4L$~`G4r<wp0yW(dZ
zMCTG{8_OE{$b!cXvrDNu1Z;y4&W??tBB9m;rO+s|@Ud_+#M;x2Rvz2Vx9%&_CE7iO
z?qH>ShqiKxyL<0ch4sF|hbtoHIe-g~XW@~6A{{y+qrbq7V%w#n5d^yt)V1J+c8pIP
zjgj@~r64P_etKjWX~kZHy<Ql4mgSz#cDi2RVFPcZGyGAC{S=ksV|E8$`nyJ8j)GCB
z^)t-}UG|iu0pt4VAci)*O_M0uEnJl!Ns=U<1YBk_wi+RmIYDYipg^4tlW>b~(W7_X
z+@*wgj>^Hr&*<W7MMATO#}FGR^@|lxv+)6IiY(C=AO)U2x!#(%l|@O-aH)IE4`TZ_
z<HVZdK{bIJ-7`0nnk6HkFxXTItEPBA4nF3&jq~&s2UQogxrBjN9wHp_Eq@a*|MoE5
z?QNr);<FP@i!HI>Oo#&jAk-kRo?pwkmW850CB7pRN&X5znWrhWg>a7G2>UVpzrc<I
zuZAhG)N6dc>hZloa{Q^tE`C6<537!}qH|++1xjLakyIM!&v>gg+koDfZrcmp<oV$U
zlMQ5`)OQEbz8Jt0nrUT}1buUF4wfYe+~vjhb%C!eMmC2z-nq@vBq2qhL&Hp^wm3jL
z-1;m_{dMq+_<MpUYK<>f*;GG!#h^v%W1_#{F%cxP*jQvgoqLQunrv>sDv3MfH%o|S
zF2vWO@(8^B-Fzc<P5nSyGSQuFJc3G`PgU_5*hER1G2g@j=H;qHY=L%+S2t0M(GM`c
z=TZwN?XV7m7vUz59j8UOTAOD@Jlp}N;|G>3LgJ~L08Cyy#Yi2l473a7PNfV7d@M!!
zysj>QGi2N;14I|`6h4MQ79(tPa1^zD$vKwIM9Gbt?s^pXh(MCD4KExFKqyU90Te{I
z+Ld^mXE{NZAQ=!A=mXQS3ALD9VmL>b$vX|H)SJSS_#rIvbS(SPqrRp9EK5Ir$-HqV
z$L{?+xbGnq4mQbX+S#$Y+UuvP%>3_FTzlwy0MCec`WcjOMs!K=Fth0?Z`CP@rpVPA
zum_ti_o)?B#vBeMv#>E3m0B$(c8$mTO<yyg63iO2Bxs!#HU6Kk<X7E#rw1qoPziS$
z+RZrxPX%a*Y#!?4IAx`9o3Py!KCL}Mj>U;mw*uQ1n^Afy!pC!EpZUs&Je+?hc~z}<
zE>uV#GU*J_aiAzR<q@pw5BV<6xuv{hn3S7TYz;mN`<{jBFXX1M#p!wm+=uN&y1@W+
zPH<XsB2{Rn!G$QIQ7<us-8<WqaV-tt^o`^BS|fPP37n!(=}qCJ+DQ=o+&wwC82-*R
zrAj{>bBQl#J9A4Q$~!O!YAFXW=kW0eu%>wX_-8=ZK}k}z9yObRmmnmJatk`m$sF(c
zflK}F9-h7isjG-bINr&%QaO{0mvdzV)&3X9GF+0TO1!&uGu@*69}jjA@jwS))WLV=
zN&6#9E7RCm9Gk&`Hw;Ho)}TUaunCKx9#tM-H$qMdMydE=<jl?3iT039t|u*py2E2!
z{se!2pSdFk*=PzNB6`K#+u{DF{L!fq0M3o$d}VQS1i5H^VY@L}GqYhQxSWu__`ZhO
z$r)xkTTolc?Y)z+2a0mk*%RQTF6F*2pm<aboslRONY{Mm+*oL-@qt{9X@NqVORPDq
zENQn9PR~M<NKp&Npt*D+mw7J#k&O5uD9%W!w`qjao1G27#6x-tWc<hR{f6W7lDc&<
z<zVy&Lb*3PNr-W>WO+&Iuqvo>E+PsaO=f7*KVq2pq^Vlf+=)d*6`mQP;M`feJD{lL
z;rN0ZCcbFe+~Lt1Uw_GG9HrvQm%g9<p4nW^Qunx!2-vQKR65##lXaa@>~#!u7ZnDq
znQif0S6X%_LZ{&lb#w0nzylub{o1~^$g9_AFf&32yYnVDvH#fGZ~b-R_8fN>xfz!-
z@Hsu6WJEj$#dG`{)y`#Ppzjs&?KtUi=H8Ees}BS@TmpVHp-dU;gBi_@AF+W~HWe4z
zh*eb?8$Zwec%sel$788XvOILTuW^?rlC$Pz_HjauHF_=QY+h<1Zu|~ao88efmnw^d
z6JmybVoFpLOHU3V+e6A8PS^*X42e+K*PToo3?AH_P0xw6n6(xZV*F6j1hrNMIfmwo
zO3gw*zIlzOx~Q6C<h7*r<LFgg4AaEPRq7~7S3<(DWkuXXr~Q+)BV8=(g4YZ0c@E|I
z2J~T|P=hm2@=Mijq$YLy7(%bB){cc=dz_GN58Y<zXkHj>BFp#f$HpTzr5>*8Jv8M{
zlg(`}-&Y&*<euY9BC})eMXmL&T+QoGnwZ@O#Y?Stdr9re!;1Q7<3RvzZo+eNz7FX)
z&=T8;j+`Q#qJHuEjsT*uOhrp7tGBNy$i0a%sIIqS%bA`GlR0+>4?RWK!KM|?Y+7?$
zLY87z?O{eMJPvJ+UIoQI@m-`e;bPmNh2{afXsWItitmR!10_EqkQ>#k0OMk3d4oe?
z|GWGPeFi7q<J>$IUt)E@SoLvZ1rN;Kd3MmO6Q?A8jsk}~>2yy~wo1b=3}CIr8!_xy
zz6BtIx6yYY6hXTUe>+u|Bc4!eC%Er*>SSM4s9IZGMTFg<-g!;;V>Pu`W<E(#*eq@$
zDDA8nLjxU411<%lLRt%+%0NxdE*6ah3nMlf*fPJdxZCw5)2-7SQ{=ly$`9NWm8kr(
zwkm^M3doG{Vq)2xCtE}xcGsR|3cM}ZE!U06N`$ndY+BT+XXdJmR}Lq-XUgFcsdBid
zg-j7fGGb!F!^~3cYeD>De`No$Udlk|SXDYTq9I=V<wxNFvO)mP&RQiV4{W4#?sY0~
zuuatTa%8K-qtH9}R@Hsx>+_))vwh~)XBmP+WLf)gfC7o?!*&%_ybs7rHp-MSc6`=-
z=SwTLEDD|hkWHT5z#9RR8rBzAfmfNts0&ekL%Mx@d$6hesav{*n+Wd!NZze4QK)?U
zgfC5+c(l;p#jU&gPA(H0s}|DJ6B{|-+IkOA*^Zz1;0A?FIz{<v;f?x?-r^e<hf0|^
z`AN0>IHDa>^YFnwBLVqDxBh$p{zUJ*|I3nj4=>jq{FfKh?s-S2MP~R%>w~Yd!fOU!
zetG#a!~S9D`RXmA?bAYizH1rB_?kKJ+rTh2OOmKapG8z`?Mmh#Sq-rJ6bM?D?2nn_
zLz?aU^(8ispB6HTkyc%wZnfBS8T!}g=;^<+s|2EQj~kQ3EzmrNK4Kv(c|w$j=o~YK
za(2mp&8eqDL?cdLe62!Y@$tb#%5(RLPD0S(u9TcRsL&wveJ;&pyzf%Q=lH5>sqNqV
zwulal2p)oA3&+Qr&eTI_Q~t?BhFyaG*BQPYyC1!gP)ATdQQIA&8j|e9I>N5vws7?(
zCkATY7WxSzGLzkp>@(8bdt%7l{jExZvkgq~@BC4kUrD6l4jvS5!Tht(5`a5-U(z_N
zz%(X*7t?rb^$TpL@LtQiiJ;-U9mD3w*59lhYfIZqd}(X2#>ov~Hxqa@a?L*Tq!k8{
zEB>yQ?0Jpl8Y=96b%{H;QtzKYmt1wnURJ(%RWV8Y-t5*mQC{D8wao?7OX3zgcNgw>
zJ(wr>Id<m?%k3QA-Iz6JMNL#$T4F&zM#BCXOu|3jTL6<kP5wTvBKS@gVw@Y6L3td>
z^7?P(=j|f@L?gD9MshX&!|R}R8%5#BmvJY*95lF^wR5}O?$^s(`~HtksMy8$+Plv<
zS3kEzo<40kuw7CC=4AS#^x~QyY?q@1h)5@`kCQmF&Tj4N?IZl$oA<2hCw7X=!#b9|
z7r;A_7d&r4sp9AEKeVlbf0X`o<zc1Wft@4Yf;x+q2eat>6RlkTp3i^5d@fHGuv(VP
zvV3>NvYjHobE}+pz{+QuT&_Juz7p9{Cdcc0x9_&qsNm++77M?byMJlK`!CwJU}gW_
zq02-Y*#D6kT^2U<n<MAQ#n%mMBV+c61tvwWf&a8y^#=_^?mFZ_8JOI1sI04Qfv7><
zOPo8u!0ZS1o`(tA-`Qn2oC&7u!?i88{d{THI4x-X&yhEz%}HO@N8hu2w~Fw(USo9K
z^4{BuBIo`G57B>3%>939MkAMh7LZ%^0b+UUZP@Q9QCnt_LW0BhdXTX%cp%yqEey8-
zToVPppUJsv*0P{a6*Q3Dv|56iIDyW_LL)`w#CiZs1BJ^mDNDKK;Q8FP=v!JJ2+>}-
zOicqb*Ihdopm&nZ7X#;vm>dD9{!TstzaQs6AcT`!ngQeIMDVa+&0?fQrO&#T@!2n8
zbmDLqpmWKa;<?X4K5AUOSy^4EZ$;m7>h-D$bGs)Kr0q2+piRCy88j~9nO(tpYC6Mm
zLnr)01IH069lGX5jN)x(_njObr#XTbXv1O@eNidlMMbBf<1YICE@suUvZ^RkrBm|n
z)E(Y}_oe`|y<N(iyYZbXtM7X<?(69W^LAwo@~n^2Zf<nYkqcb$L&6vCw=b;@rQJqS
zmeQCh3l(AHB2FkZje*`G--n?DB6Bpp$^e;@(M(}}jlaM%q`_Q2?nz;_aS%1d9w**K
zK1=>NOr|Bac=}$tzq#d!YbTF5uKS+k&C-Bv#mJazh^{!235<wfb@C4%qxI_n*j}|>
zEJRVHMi86x3#=XK0FpKl`5^h6%Y%dYd4Ns_xl<liXyA%rzYL&_WfA}dc@+XA`o2(8
zp%azEbB?v@0PG0YB+ud;KK%lN&kBq9Pc=VPRh1D=x7HhYd~_IjYwX$0Kb%jnb&o&8
zZi<bcFUHt+hEU}CeRN0nSM*f`=vcOwzs0&lbz1BJ*{+V@Or65`fbu~TM!k^UK^}uY
z0_s*O$Vn#k!uk5{_{GgbGT=I6Q)u5ya)l~-RRRV4D)13{3y$B{@r@h{CjJ=7MP}x|
z7(cKMueS#L0^2)SPlL8|0J7R>j@<AWG<N0$j12SF5+;9vWh|nxAdQQeX#0ur>Yo^(
zhnTf;r|kzBsn_<(ztMI68BZi^xaE3GJHzk>ROR(X9xJ*(!NIm{?>pE{DWo<;rp$YP
zzBuq#x7_j9f4B(w*W+&Yhe7$vM5qt{Zq;C(&EXbB$H@??97xQKqJb*-&Y&>9Dw@nb
z#VQf{15L*tMukXW2+2K^+w}0iS`v0#1SnWqMxa1aj!OY5bu#19Ah}}~8!wbL5BUZ5
zHUjy_HIv52v@Mo>dx0mP8l%mL10X#c=L<0Q{yClVj#%sVS}Y?##hKa(vd2D#nRrzw
z)S>1@*Bna4-N*Dtx1sAG?X{tEU$B5AqjEe-6K9`zw5lf6shg1?e0!=oc@u*Cf6p!X
z{MAhUe{1pnVRzfT5h6zg$G@L2ru}Xe8UFQ5ivM9t{$WnOW9a-}V1*c+n1#PuM5({q
zvmm?thdqh;!z%mFtuypj1OES$t@H17_Mf5ue{`K)f#|Y(f8ZOiBa{1kHX09^NldS`
z-jGXC2{>o9K?QazyZxDZ4E8_c88}LQAJG0VE9%74*Y_9@4cTEu32r<4gk~b$2J6pg
zH@!c*Cgs{w%d=<S9f>q<HaW5$ACm=l-jKd$=_BoC|M`*YF}8C{ANfl-4*KuHaZB@-
z{f5zu{OF%_wv~ZMt@*>Ti=UM;h4NFYE~XrjmlC@qvic%C>Edl~q>MSj`MC3sIB3SN
zCU#5FFgyLELEMKYX?G+(txz2Kb+?ZGOLr>@I&pF38j>2pL`V7HFrL%f`IF*vaArwf
zmOMD-DtbfJzL}A^7}^N_XQFJ=(<(*_yYybd)3R(FZlXFOw^Yzk+dh9>ze4r=x62<s
z9QQ|E@n18U8DVxL!|2(Ilb(MSEqWihy(-IUU=%-HftRZ{zhtw)ab;8S2RV=aA-6UK
zLzi8lm1*^%-a%64#=FXF%$+)37x}d>r5Zo&1^lOrUlYj8gBO2RNrmj@>a+H-%)NU{
zm$i0!#Ss_o_l_4<+X-_AJWf|F0wK%f55tQZiXs|idya_cp80+wYvbX%jGb7|$QAZe
zBH9UQzdkbiWPU{nLcl=SwH#_+b%CPm;Jv#1W+B{Q{e3Id+pk}5l)Ks1S+v|EbD|^Y
zh}=S+&KD-%Dr#8(l8mQ?;HhW*1Bsv80n%lc`4VIy@lSXnlRq=391J&E$~R;0NiuEB
zC382<kHI!()yWecs|$$a`JeEDHLExCzyk9C;ktv<E;0%pt}MXgBrRTOr17`hr;cVM
z{Khirfdnf<wo5_xBmfcKys|`O$@(+JWYuzRUAHhaj35Ljkdu-5i$534PPhFw%s~}>
zMmt`Sy*VkZ?*Z&qILw~;@V9PVzq!!vauGMxY}rNtQ~{)*GY6O86$*c%9{E@wI8eF-
zh_P8hSfyO~GZt~<Z(d3E{>5nu_Q<?cy;WJ>_9&_AMeHG!9k882SJUd+4tEx{{_Sxq
zc#2_h>B1q}+@YR(ROT<RK3B{fF&K7*O>Xm{%`nNyc7Mx%O6gqAuU2p?Ouk$*Y;0W%
z&@X2^m*9<~f97miE$5{7@Hg&p*1x*vS;{SQm5+Zl(~JMhMTY3Xj>Y)w-65)ba*5xf
zxI|YH`?LfvS!N3D#TVnqlRuCbS9BnUDZ=U!VO&h4)^cuf9m`E2ejZ3v`nJ;MOt$>G
z_$|dL;(TtRP^b;{=%HQjyi@YkI)*rBZ5m~ubMwYNEiK9;-=mtwLi22Z)1WNw+7G+4
zJ6mSQ&gLaLnaUC`XZL@if0ncAdi-1WxZz0_*er+1V;2vKU3x2dP^>iV%O1i_><XVZ
z7GW?+?Pp?H+pvGJ)62oXpw0Kf1xQT?OQq}#Icdw*wM*nqn?Escb}tc`mYKpsznT=<
z{a?L5k7c<ge@>Lt+D7yJVEtI?Zlvn&x;G=<kH=lSctG~l2ZT2rvOWH(kl@)bu&NS)
zV!4R!KN#Lt`uwf*K+ZDrc;p7TAXfO&4!pVQ$^H8N@3X?d5FPCOHgyTsb^1^In0J3B
zugNbnkG8+D#r$>o|DW2Uzb^ESLmifKe+Rbae;b7hKM$E))i<|_8r?ol39}=mlDoop
zna(D8)2uwTm(B1Z`q>vvfM%I%D|mM=x!^F;LKt)pX;IpxG2aG5Or98Svb}{7gSMI6
zwy9`~<Db?0@T7%U)mw>>OBotEGnlIXuJdzV`HfQj#oLQ3SLkNldibKebN<z~N%{aI
zLk~ScC<zErch!1H?J(M>b!Tl!@u^$xfq?;m(rp1x#)o~Y5)VeYA9#lfe!J8EB>a6F
zq=lUd2aS5Af(J%2YZd^wbvTfPOD!SL`iIMmQ=EYs&eXsB$3&C4x2G*UeT4=mP8dpE
z!9VgD+SH!MGdSS}#nz?YIf>Q7LMAnJBuTdRbRlmy0bVyG&mN89D?KFrM1^(EQC1Ti
zY@e}5W9MF3Pz{NGw&h*H_tm6ybk^<*-4t*tar9i8*&9E;LHbBvl33<kA#L@fGSgOe
z$c;d!4|tgzYTiwyGxe<Z_DuKMIByW-W3RGwOMlY(@q5S^MK)XTNT~aPV7tH!O-Av_
z1q66QFSruYW9D!oS{7ta#2ef$7Z>_x;A5vMJnWjvCbSN88Ce7!dC?W{rTTX8T=lL>
zlFh?i?7bq~r#0+Ju4`wlGqcqM<E?Z2JYS1<#+O_ME6-$>G{LnFvq$4E7>#Rl&UV=`
zH`b;$4k!@J4wkd0j-^*FZt1G%!O8hj*LMfMp4Ukrtrpxy%Vm0m*CV#F`(o3M^?nf)
z;Od69)0X_|uuRbDPSmL7T#n72tTw*J*J5O1t_hXe=OTg{4)y!TGM#D)a8MRwW=%o{
zc_27k60M%u0D7&TZmxa#f@3qcpcb3Bo-@s#C7xt=m*EH#?>|=1l2Mz;s%0Ob=N~3i
zz98j(ZY$c0zwmQt!i96g-Q$a~(_Rn9-LkGf0zMjdGIJ(f7V{n#`5r?e=2{(OTn_ai
zt{Bx!+x8B(+@yzx6gz|j>X%wH*l&KU+om^*UH{P%QNb#SBFmIx`&H<}2wlJo?#(jg
zkdjAGYj6ZV5AxwmEJRkA9NJliPx;obd70HH?~7d9Ro_15snk_#b1HzLhjC47axpcp
zzNP>jlESSP{76)1pyb*(K}`r0J7Tyo9CsZjQL%(FpierwxOU`n^mCC3wd)x;%yBB4
z=k6cRph>-lau%AxK82z4ANk1-j&(esCcGZrp6=8|^Lb_9;&BP7klD(8)@~SH(F;VC
z$i}eCB@ZAsmSZ)L^wwJE0)wc<tYjv3^|*o0BCg+DujIX-Ct_bY&*5^HnuJz-xF!}n
zGFPn14$t+gbW4roYZep2zA_i~^$FM7@z6vqj^@Lv%R#;i&J;PKeqw{#$EN#l?>7RA
z`iLGrS7Br9&z0xsFnAu>2Z)E|II;A}R5@3^dAGSmF@)l75!|mmHG-AY&u41d&em5B
zX+exaSHjIxDa`Q_u#?*?`}Ehvj5Y@Px$JWDXsQr=DlD+=qbEUSY;Ojt0SA<?^7>~X
zQzN`aNdm@uCMF9}*~|A}C2xdKjYxUSIZaf{(6-*Zu93cC7w29*{zcTxbZ~LtyW3vj
z!Ft-2rkiebZ2tbyTks^UNs1K=QJC|b9N)t}TbZAs`A4Y=Ph$hG=;xx7s@a@T?vwGu
zehO`5{U7z4a);jPb?x!K`Oy4p4FjJ_-5T|+uW?A5%2BG!EdcH`+4!gYlkDD-mE6MY
zv0QrC=KL#bvRP(vUn^vg^anns9#azwrlf>b>Ao9xVO~6dcf3W8c-NyO2z?B6=~*_b
zE|8F3hp9x?lcT{>_?pf_CJ9ZtG@$2$t`$9c=AlgZ+A-2<c5ECmfPt0wRYqv-6RP#+
zM^%v<Gn-5ik8*H>gShYL>ug>f7@^=cNrxwp@zDzQmo$zRx0`bUvy!-*Iis;DHts80
zfxiQCXL_jDQPrbedd#gOa)zPk!zv|D{Y)LJp{QBx9d7Ty*>F91P0VM&<Tyd<@kEt(
zfs~*U--+WLuWOk2*1);52w;8}oeF*P{oJ;^P(wdD8xX;I%&6=RE)5Mf<UuztOf~(?
z9P()_sWCeUq{I~g-dGOeG3z7QnX@LXsEui%<3R;fgpdAe-f<U-=I*0MJ-g<&@-Hmh
zaqD>-b2a<;3BNmCHW5a7i4O-`&8+j?Hm*ZDq3H0)-eH-iBnv<C%BF{Ev2`H5tT{+j
z&ul?kRCNZIDEcDHk<lcjaq8yhy^nfTnn8qW8gQxzG8@mhQyhNDhFXP4E^_-h_`WCo
z6K%ku0Sz4M8vR$Xm6MHQYPDG?(1g7jy~!7?LOJrPcaW~d)TWonK-CLYiO0LM9IcO3
zbX8~``>L)}GwNSi{!Qz}EnhF+hwYqIi98$VIqyU_-<hT7-WZk|U*77d&=@)}+KgW_
zQRT)>%%9km@hT>@2phpV{;9h>Q^p1Rth=auusP$WPGR%AuR{`}6;b<maOp{0Ik1q#
zlobs#DqpT{$seQ#vZgWIAc*p$|Glr86Xn6U8v1@Qe_sX1vn+2+4W0Vvz3(D6b_z9J
z?x;T`Q>m={<#>iA{AdSB0`#h2>tr_I;e>5J4Kg)p^jA8~LJJNuX&#g;5Yik_l@M4n
zPq=9T<qb8lU~HBT42#%d7AwNTMG-fHyqTq!7L2`)gx74<JHs7TBDLbmHW#vZm}`r>
z5%Rs}J9v8lAIvlRF%&LT=`Ah<IzqSZflA8baR6ojCpd1+T<Y~KH7NG!FR(N2e!|r+
z*t-gb)Oxy{d)9a9hP*Ox?3xds0X9jH@2gOHl~B5y7(gPzANv`HJ!*+8qUu0q_H40G
zm+GR7Pj60*c<3};_LT1|I_z?LUdmC&p`&Q7M(Wmc*Z#rtNqQEf7VaI6XW9cF#1_t%
zS4<0d!}EbQ#(m@osQ<yl04{d)`L)60*qrw`!ce%!&TzAHyDHO;H%V9azNoyKd-d3M
zk*`8&h|Dfzo}-19IPi85${5t-5u^k^h_g{BQ^`qflzN3^_Lj2S_IFlj8r1FZ8`_vM
z*%;=XFsIyo?&T6oLE`IU{Kf%`f&c^ScKna50O4Bx>Mo+zW1?>lN%~E|*#hCu8KF)7
zm}ui66HZS>YAoLs<8xn~p_EeLTdcXKuc-?{Hk<0)zuf286XM};&|gPz$O7eY{at)f
zKXJAQGY!}(vOWmiKEV9QKhD8kSL$jIZtNDC`Ya4A#46iJp}5K=L9E9{GMn;YszVLT
zRrjCI8kBBi`B#fiOEDv?8%;~%%{?CbFH#cE>lv0P`Kh%vV`L^=vNm>>^9E(?u$}Xh
znQdy0`o($g{nU=7M|hngbq%<Aj8{iA)$V9Ld!7S}aAD%FVZ``Kxr8d_5J1u$g3@v)
zi+S6tVo30kWb+_JBwQD0y0%i7$|YAqN}$VUIkqp?_fGZI53PRDbK&j7(2Pja;=CHd
zoy+N@dDieXnj}Azw}(%9#z93MZo<eJ4JT)aM-kz8R&gkke3htK^uC1di2gR&K$3!D
zM>LVg*p-=_>m{F`)ugmBjew=wyF0xKo3lFJhOg&Ow(9|Ffwt8Xs3L+F6CTGmE3|(w
zo~0Cl-3u{te8Zw4Z=14cYzNW2?+)4|YGf?KD7m6I@8+X>XnLOez@Uwnm?U1pVc_iO
zw0q76=+^8$U~nn3bGBJe0jm5;XT3}J4PpAOuTs9)TJph)Ri1e)LwyI=B#(CGbIQ-J
za!jg1lOxfd)m688C%*Lh45$|8XAHS|+#cGx{$?)WW4qYp<R1!mMiyCZgKc<Fas(7q
zP$1buG{=B{jYg8c=j93&X^qJ5Y*1Mes$_|PN?Jyw`O}1XEOZF$De@?t{tFE9B#49h
zlOKlRuw?&0fy06H{>lha=vyHA)7Zbi_5aNgpgn8_r!jvI6w8wp_6&oPrr%594j+sh
zRn|@TMy)CtIO*;IM3__&(mUXnQ2$Dtxp0lI!<Y`@o=B%_9qH7iYC|=3YQi+{$H!0D
zu*YkI9{3AUrn*$K7oA@+Xke}VVLcTN0DNHTpcbIK1mmt{8A2T#c+>D|zDe~N5)ukv
z;s-W#d9o4lh{W@iVY+TE*DA1aDsD2@O!aaEnRW>S4JLDim)P(1YA@|85)rH*e1HJY
zsF609%Ro-Y=C~avwPM6D7f|oZ>W9l>V{2V<-xF|kNEs3WbQYF>O&qbnSVESM@p-;s
z_!#0*9<r@)GE2LHEogAV`CJ?%lpLu_`SR7nhI&*`sx8Q+8uOI}FKdl>Rs?)=HMfdQ
z2R5*579(}a>%p6m__N)H_py!soEAq;OFbnz@oX-=(1WlR<nV_Z1eb^Fg_`d7m5&#J
zZVR0Vbb$4Vfc>m*?#*G8X<rVqen=4t<w!AU$>t#=aFG^Y6%e3U@YHI2Jm^P}n9{{L
zJi|&u_~V@Euc_IIn)-H~Q?#=4)5&>v$z{_&Up~3VR1?pHPt%wl05Vm@M5WS{LZ-bL
z=3o{fkHSezc@;P7G5gEdLpk*lQQQ#UCTpf4-B#V*At*5Wt=EpK^71OwC%1ZylgM&h
z>GWvh{S8=XGZsATN%^L~<;n8#g8RS}A(UIvrO!9>^#<Xig^EgTrXUTm1L6lE+LMSR
ztBA*ZT{bxet?EW_KgiMh<l?DV`kdV`)^|+Qm2ft#US-HMs)c(J5`Q#+1IF01%{2DD
zk~p#=Y4>;-E_ONuA9I*6go&o8n0tWknX0%D)$<n&dAJ0jv>>+}C+<6NnYx(dxshF2
z?8|tyrh&CD+U?fBBuCV)kLC|r@{mn5>2i1y!lGTML0FtU)J+T-(bVEbKkuqlW$6gc
zNlaH{wkbmA+FICS1A=#@cxhR`S-(n`Lw*+r2V00;k80QJ^iSX_^6s;#ypa?N@Q|#;
ztP0VIsqQAp4-g}|im7V26R*Ba+;R*Z@gas~slK@7;k=>yi*InVf#3G}2z_3``r9z{
zp`2HT{}^Rc|3-j?34siKBpO*p1Ewh;=TmPaG$XihZ$m*NI0QkB&V2-4L90jxQBwBA
zt+LP#_JLvlFzv)!{xbgcp%(|5n<Ij(dxH~S6yI)42hW&fQS!(moEYXLEefZsZY_u-
z`_N>GzMW@Z)#4NgmjX5q<JcuvHzt)Q`Z9o=ft#*&j>6*kZoFlp8!$&%Gtuta-!NSO
zv5s^{*O3A%s|1g9sVW{s`BKj9>C^@@(7ovaO&*4Vyg0aeuBTiNA9p3+C*uHhU2nNN
zPT9u0Xkv%&kVZ#w(b*oY8a2P;ce?KMI%KxIU>eRu5B#9eVw@O~tYF*4+LRx?zc-ko
z;2&z`is~=Y3)X4nN$79-^nHMuo$pq^`pwoWUsqNnzZVaGX!x8U%9yI!R*2!+R*A{n
zY75G9hpIds9PZg4blBA8XBvF6JTsttlF)No&TDU>%VGM~D0K(dDMOyRtFB?Igwxp6
zRKO2KJ5&Z@u6**^)H6Sr(@HKl;em6KUf7v-?BBkW|MsPvGy5j4y-oumDR%YWzLZ<O
zVCQe7oVz=pv7MlAdy!yaRWBwh^S|0V^LQxRzW<NN5)s+Av4s+{?<NUJs8q67WDVIz
zhLN&mkQCWvO}1p;lReqDjBF#>nITM!>38<Lo;$8Pb5+-KKfmYxJ-_R}yfouH&f_?b
z<2b*^=kt00&82*l_zK7=0+e0YslU0De{(5!va<-G89{$@DgWkDO7K%TC$05b1q41D
zdnhLd8b_buqxzdmxeJW?SGbfHf1*^N2Wb#uhmn=Q*l!GSa=mi^$dX%))II<OgJaX9
zLmrdpgmP*pw+W6qLFJ2RsS4-kj_Bm&LWGTnrBoM=e+=5-<a$4Y1y~yc2NBhH2|uTJ
zb^x5^m3#GcVL;F7mHxb8oo>m-;9|DVcO5eI%dE7tIF#EnOYmL&jvqDY-ZmJYOy?=D
zt}1`kv*32{R8O@FoPqTW?(q0?)Mds&WnRqVQs-=rl`+HjP;~__&qxQwN(HT`*q&1j
zm2>(t^yIHj3h81zPM3Pen)x1gc&6brjSV*$$jh@jc~$+B66s|9!1}wk;zTZyQzwq`
zKZG>_;-wNCys;SVs2GlY3Z0L5Bo0C4t&w=E<eO~A;@NSe7}&roY+EBu7PjcEViNIO
zG8V3FLyTWgaTZ~zI=giKOw{^dN$$%kkJw8QxOYh<(!rVUVR~qtz*L(HL+=HAKN~41
z38)qXaAXNQP}F4|wi%G_&QbTIwD)74-2V73m82Nt3I0JE{LkXd!5Ot_0PX>40!|fb
z7-oUg4(-xFA4XHa{hoBUN+r(#n~!P_44(#48PKC!&9p$yS2h~JQw4~)byDF@_c<ym
zd0dw+Mt1?hLY!GjQE|!28L^tMT<|!}LgS>cOa18ao?KTgC0<P|1e4vYEP(C^XIg}i
zy@4FE9ix^4v|BSs20+bj#)5;~LyczM++P|ZWwab5@8~;dQqf~pN6qMcfa8j;u+iW$
zd{DQul6buHrvm8wS2$gC$hs$bGyw==T@FxYAAxCgD?-q1<L>45=zftJ8K4Z|Zn)8~
zOoy#JHCS~y#ZLKn4~!CH)!+jvEJBAxI!%n|XqCHuk%DtHUw6u$%SsPQ{j#w>Rdi2x
zI~}Hf-7a+uduO1n4oqw>Ty*e?Raw8JtZ)r6Od@~-d@=FNgy-_-mhM~m{LmYoB3uzj
z$>Wz8*S5yidRLcTuR8v`0kkP0cea-|XTNM*1Jd+=CVC$X>Q<}v+1Pf)ZM{^g{O2z2
z{%2j}e1mn$Xss8%!pHkPClFl!QxW(YO7eoESv4T>f+#Q0IP9Sk|4}=SVHGUR9|Z(6
zNlETxKqSsTYwLf|@j^rCzxVNQ?GGy7AGG9E>JNnHH)`iIr$_ECj{WfK@PEF^ro3w3
zyI_6!pMU#<h(7=CF8HaO|L-pNnS<nKPr+?$GsP7rbZ^}h!xNUqub{B?>@w#E?cYSM
z#Im7pv*fOYo#fV0RIbg`B>_Ybl;ELz<DAhpK1pcZPFA2^#Z$u#q=ZkW&-#Fi0YHlO
zBot2#Gsbu{z#oiq_uVWg>s|B_0&?BLx?vodHps0xF=*r)WN~J|X9dboo`bepcHd_L
zaA)W5O*FN5CUzp#q<}=~1C5VmhH-91ul$cE1Co6czf1CrppT>%oysin2|$?Iot##?
zT&xrBxaE!PoEiPW&AcS*1-PrDq|z0wTy-PGgi;ws!?sbw`if6uI{o~iw?rUWV_2@{
zh2<@IpYB?;Hau*UVLRQ29m~|5Ncs|p8uEe*k0HkWddv=-R;Gd-mO+jNqdvyg8=_4<
zNEZ|&8F#HE@GJ@4bUK2ps{+3s!yeVIqj@hn9^Dww^%Zmjj0Cg<tgbPRj!X@s>~Wf<
zgE*maO<rLhBoscWl-?ARiNzx|`NAmKyannjiWsGDSK2De_DgZ08OeN2hdQs{9vCE&
z2^vq7<B8z+Lk%pE=PfJ?TLs4o#VHJHj#n0z`zNx+8Kfi%Sbw}CW#bwUr3->7MNM6{
z!nX{J-+g7U<k|*joNu*pIeLu3qQYK72f-L=Uy|U+`YPqP^<yGTXM?m55N3uA9mA`T
z9Xk(ySDWFqS`oi7i}2`V2(oaLm-yJ4Bys^!9~l)GvGw8FHR4A!ydcD+BZ@sJ=`c)(
zqgxkumYT&6P)(BKpGvf{TOl?FxCu!^eJOs0DLWNQmrP;)jkwD54Jmu)^MB&-5@Fy~
zr05nlY4RjJVX9*xLEkz<(U%)WvX|3BuX@H%&5^&$Q&$1DeLhbt35fj8g9x^NoDkU0
zx1A<|1whCGJl&^d-(a0C|H+R#O+b$bihKwEG9fw*9K&%wpCG_%+@;Ch+s2r@k6^kd
zF=6JW%PH0yHxa~KyyBv~tw9zpEiJsfWxUUm3AN!QK}zRthwsl7tI6bq8cGmM3HmKD
zFo>}Cm%)+{0ar-(xcW-t{fH-KMN8a${_jpw#gAK{CHg*Ri|?)76x^pP_7yaJzcwC>
zyOT-)pK7}!)O|j&mpIp#{4Wp;X$ic*+#@7E1rc)PM+oeg?JxXXq3z2{pq<tPv6}mS
zNBd3>BJA@$LV$M5^}8x>-`%j|sKkZi6Z?)b(@1>MJ4CjT-|PC|gX>4?I~FebFf3%c
z$ZP`xY09!$X(+j!t;zawRh*@d_8W*=g@t`va35j&IjQ<;s`9y*l_}<Ta&p$5;OZt)
zkQ~>_3Gxnd0&;AEiu!-qv`I?{YfSJpnrJVB0KJAJcLx8}*W&vmcvcjj252ZE{KOUf
z<R5_kLMjByGvGemf_@`!GyMk(*6AO3U+c5JM-bo0;t#%Yn&<z)-KP5$?)HD7a<JcK
zBy=ixC5^;8^T0WSTMZJ3Gx}kfPNwn}m@DQ4+y?{&>L(d*5*W2SyC;vRz1zC06(B;K
zRKhteBzsw6F0gk6JdH62wUECHX<50!!oDI--m*kKC-^6%aYESilZ4z1DF)Aufuh8}
zF}9C>BiiQwClnsEdz~PZ1fls;TMv-q{rfpPeuP$eLXAkKP;3UM1$6k^aLk<GZf}p^
zKEvI<qSRJh1NbuFGsQWl1{^ujpc%<8+j;mL*)e(0IMECU<Vs9W#P{9CvtD~|41>uB
zTnik4#a*=~{}7?VGV!o7HJ4WSp=;&ufL!i~vDC58qwQf;lPt?!=gBJiq8VdNOVdrD
zUd9q?nIpOki+QPbBpxzI{wxybdWN+eaV-ZC;XLk`#bOhMMQM!fAxfK=#-*4HZF`Qt
zR?6xke#Z}h5osjkO$Pnl;vB`IgeuLLp&r`e$D)oNeTiXwmSVd;%OmKvrISRdZeSi`
z{`8Amb`DMsTZ>}s{W$30x_!e$NH_d!@25T=UMTC5mx(-ENXYYBlZkNpsxhkougbsx
zY4=0HR8EVb7Z?rjA~R9Tg<9zSp?!i&fV_crzM{YX-3%r9hvwuD&^x0;G46#8`&-oa
zpYEY~3cS)#MvaAIOKJ{IM*wV08V+Z1bq(C*(d6*wl0<{pPzd1uW;TYpuQn#pDr%wZ
zYRQc?JSVhr;gew@*&ndB>qmvB!ZuVA0lCBBwzSc-sHm{gC;%nmWn{VP;z->p#lM{;
z70zIdm+!CPgQn_X@&j{`y(cl=8_i0b^9{%&*?gE*$27Y_=+v5$G{u#<8EuAyzN0e8
zymQam8yc}cFD9jbPZXdY7&Sx2_BP3k9a;ngdMU%r6$#<%rm2%!@UT0Q%ExMY#T=Nl
zD+ebrZ|9;}ohcPmI1r_}cFaY^v<<bEfmRGCaG)78&M4b>9xv3#jghYO<cOC6qUC%9
zp%BCVyp-M?`=WMbp#-gq7`OJ1nD?_K?y=snS`xy!p}ECrL|lG?KpNc-4*ef%D?7Ob
zfGzKU8Hxsng?@9!cY=TfA8ifXQFst!bpnte;6xRP0jIu{{g2=ALw)9ZL;=vJzaVO>
zfMX3kz(dpe!2i~r$X|HoF1ecZW$X~Vu<^_N50t!sFN4Bt$bSgPk+J{urRk6b#Y@H)
zW<Qp3{^78_0lZj7f74(pbAo|?uD*ugdN1tJI-@<l<A-9;KfLT>@E;UW&wp%PZvGEn
z@WY$(_s9k2T68*|3kWg`1f=ZfDl{P7lk9{4aOqbDfB1?Y>UQ4;9+lZ1+La&0f!P3z
z^q<l&ekktkn0ZBi90uSYFTKC`hp*UU2!3}ZGyR(G2D!&~{5S;v9fonqFH|DK{~n`0
z`hSnnJtm|7J5%ld&tp{I>>2J%A5J&hz*?CVtMCjOXxx{6!UicFpv*IeEO{p0v{EE(
z=oa|EK~yB2R)a4<mOG-sdP%+ihL9=la+3BFu09`nsO1|Q9?i*sb$Aftt13E1+IJD1
zsIrk1X9S(ve&+1`=J)P>pWoR#f1Ee(v?r!-8QP3dF4vF)&IksaojKa-Vwqj8#)NQY
z^N9TLMEY9Wm`E1ipbu$abJj#$@R5ExVI9lpbLP^iR7^d~6@DywzW)Yu;=Fw>Ag<RE
z^&d1N$${PUGDn92`B%|C@_l&r_c(pDcl3QXIMb*Nl0Q;3NGg|curb15ULIlS5h!VA
z$KrNosVO$<X3<pfqfeM6*-(Y?^>h+UJ8H!IbaxT9)n>e>I6<HRIns57a@~&7<iHC4
z4P~&WvU~n>n}L_7UY#}dx@&Ll;rQQJR%Yh7*@u36Eud#W;h=KU0OdjPH-{?}6xePG
zQK_vzOY~%Jb@O(gc{Mi2#H8PQPw8D+f3|*!%X?#~;@8?JS%I)KX`0Dp#g%?Sl?rVJ
zD9Z<*I@WujA`45`tpWfuKxQyfjv>?#gk1%8T#q{sZ@Y$XYZO&9?zq>5%uuYPKwN~g
zR`?eZnkWt3FVUatyIIt|HzyIO0xGR(^*t2}AWfMMW}EY5`0%jw7d;KnG{oUK_gy5L
zbGq-<IZNEDo1-S@^8Ev936z@w?3f=z)`8e8_0}u9{n*04&pJG_V|~By{Yp}QpX){W
zhgdg_-I^`}WW0T6@W30~T0i{rX-S#yF&PZ(PDgFZBZEQAvDd$Xj^9vx_(eb<tF?*r
zHi#$~Hq&HL7p8}=xP|W8B`x%&*q!}QY<TtY-cmcwkC{2O8+bTg?j*^cfe&GOQ>-o!
z#PX5ogE3pcbvl}D9<_Zp<^-S50dFeHrxW6eWs4K&Ve5VEYCCxf->>sR{oeRC&|Wba
z8U!zsFg<Xe=B@yUE5C#^Bigyn@3{|z-oiELqT*s?9})#;fLEG$TWKCS--(aEW(5Kf
z@$TeQoc?~_5CqwIb;r-ry9jKyXh@v9)6T5O#4D@FnLO@CPU?HSe|HW<;rCm2sR-Mj
zGr`wFv8ufA>N!fE{aD!rEKy|ZCts0W(J0Sq2Z54<G4MonjX$3x1jYMTKE1&E!v&gc
z=Wrlj&2U!)Mc?h;1z_^+%sso3GcG)h?m$?cW1fP{XLKH<QLW{2b|$JDe|UzOFpzZr
zA3|Gxueg%y1US1(!0Ui1F(oRUP+?_X5$1VS!Cs;@Uy=3=CVWNRS5WF?mTl3mkSfU`
zeX2m8r2>7%81#J(kz)UCfF8x3DK~wVM^;l=B1z?RH)jj$RlAm3*yDX~L;2`PDG0zB
zC5d+Dx2)(5m~8>sf?q-G1ObMc-=Ca-U1=1lgl->*;CxJE`5<Jc81?`Z$n+I73fO&X
z_<<C_C+s{MZ$s=17gu^6F5YloWNxJ+iZ_>K?mSz(6G=`uANG{rhU<Gf<1hEzFFICF
zsr7EeAFRCdaayUsbOLSFxup>VTcriEAWGlrn@!esEG`T!BFt;-8qFh0wYOrZEl7N?
zPi}}&vA-p~EzzV-J}vjHx+Z29e#lbhoN9(QDiEUd6{H=utuW02?UV&=7=FSZlZ?O$
z)Lm$JA)E)(m^|t*bwy#SruZcq;l94g|H0GUJz7{Q%|F<qFTYEW*5dP%BaIo+xwHDF
zoP$)|HXC}4UUtusbsX*M!7o(UUp9K%Q9T+C39$>Z^s?92+0w2uyuS}=>ExAR6KMo;
z{YGi3Px2iVjU6y!fj(P<Fve&^j(cAM)6C{_!AF8b)aqq|P2N(_jUw0kOPIn|&pv|0
z<oXN%CXC2Qrutf{t9daKp^R`ctjk#guHt}Bt?pbAoC!+HQ>4B4l?J=}K(Nq<a|J0=
zyyktMs;C|BDW6!CNFRaf8<ecF+^8(Z1O~eH@?_n36h}jA%gUec@Q5eStY{WpbTdjW
zN-jLwFt)QkDFn}Bue3HF3WN`6^-lH_eJK_V8YQht9Mld#p+2z*PA4_eh?NG|RR#pe
zxYHgFkX>(j{(xu=pO4m>kO}rtG=!1%*6hc&P2~Ac=pu#c$H>><A@itOhPhCbJt@k>
zv`)B6mnP^|zM^ObwiCr;b7;P1e;K;H<Zhap{qr`Kp5i#c+<Y^u*AOzF{V<Jk0M(vg
zH|~>#u2+Y%;ky#aF`{pZF{NQQBO47p>do$sa$!T$=1W*RgB@;S7$Z?&s`+*IO{U<`
zsz8;bOGXDbj}+-<S?8{J1RaOi=rY>)fV%+Gb*@Xp9hv*1qq>x{^2<%R#8-N&6ok`G
zQEIws2`#hfI%a6uIWQuTMzRx+Mu&Jy{U0&+NEPO3Z0Ta-40>@IC`eEZ|6r9$noUJm
zXu4f&bF(np#s1Ij0#{#_^{j<T==S9+x=2kW1mtIojJ%&KiCWblO}FuI+drqv(eQR0
zYzb2UELU}c%AE6H`p@CMHB47)xbZDOR4Pu*W87P#VeF992v{9M_GbA3(!+ncy337i
z>@Xx~(H^IrK5})AwJ`MDT*c{%WBGw=-uxZQ`X(A7rC0+r*N2(d(~$j1`n71tg2y<3
ztx#=fwV#A@0KPGp9>%9&+>xx)dt%l;c>uu)Mn6eteqe<uDFg@P+Pf`_s`O3tu6Zk{
zKT?t(oU$i7y`54e3<=DGNdO-8`aw>*dq6@!4pN}Wk;cXuYCC9>sFmwHsNw}?eeD`z
zZ~4h4Ps+|)akxH9`}ix<v}N8%!{&N0_;Wj44P%;s3Yn*&hdS!M>`_!eDL@dMtR;g*
z90F&1;RT=DMb-N!FtN6*mI;|Q#9POjn%<%)jkIO9Ny$@-xBEffR;cj(P~Cbkk+Li{
z{EhPAYOME7jPCmF?IdNMQS81gy?!@;bV;hm)|qgsidmV>i6o=w`cdvebYoJ8q||`h
zL9L5nohIZPg@%-JoHRpZ>z-J13~zl6aS;H{15;HcF<0H39HYYOHbnbKV4vfa%Zt(Z
zfycE!j1r+e>c4`hb;onru|`*_Su+YzG$HaM9Z%r5fEw(Xq9WgsQCxm5)NB1dhGQ@|
zAEtt8*D$Waq#54g6szdRi$NVPBsJc)?nRDRqoI$CYFW>1eqhyZ4}H=UL!IVe-utPr
zII8=)7xb(hRt0Vg4n(ST2I9ytObs;$x|WukvRu-jT0rr7Vno{e93L%!!O*lygQ7Y{
z@(mU2E_vmPc0>r<U(vW(dY`8R4@l|!%#y*L0DL8QLLtd-jHv3cH`?n>MMp4Xp<v4Z
zJI6t~+z6pJJCoF?OlyYNwAg4(uA6-N`Ac!_;o+IsaO4{17M{OLzk$`i)X&X~YUt|B
zIuaf|58nr|(gu%@yfPg!6bQqqY>C0&eCb(hrvoD?O)<sM4;&XhV)kc5ZYQK;MXzEd
zY|y1z6+`G%gMs39n4P>5N;liihqs_IG<WbL2QM%viYPm&Y~`6Ah`QPVfjW)ej^k}3
zLO^y|fa_L1h0&ac{zgSSCreo|CjR2gd0Uy-yetnmb<{w?sPUZs>W7?HrpA)7J;V53
z7wDC*px1@4lNkCMihhSYM>hz$7N$})vR>YQWN~W_zy(#XVaI2q^-OJFDQ7}gjTB65
z1r~c_M0_8gkb>XRCYy-9TO%@;bWoWYCtrlti5qu)RoW*7$7;e1P{R6+(XnHJI7m*_
z<^yct)jr8>>EW|w<y9p;xkYwba;C_M;mhTHmPYO+o70VEg}QY!xp+C~zTpY#f(a7r
zr7_TF(Str+NC1mz<z|C2$FQN`^}3XHH7ELA+p14P`JHmC<(G<cunuD?y^E4<2kEpX
zJ?uQ5*Jqjm@BKt}Ne6vIp-Go32Vt5Xb|?;q?G(F3b7O4W_=wTvYHO|sNXE)OQJjI3
zhjZ7k%E2mioA_oDvD5c8SOqsDfwDRs0P+eMZy&20;hm`U$H`pJwXR`AFO_==G*{*`
z%t|9g@2{CKnHCqIW$srQVT7)9SCMgM=VCq7`rLXm*b05tPci$aQ57^1ecs=>FuWyf
zYsLUOIxY;UztAWEl%uWR`_N;<>gxy1iY|3y1K)&BbTS%`yoae^M8g#sCc-IZAawT2
zFojGz#uG3_j8x5&>{-Krl1-mzw@e%NiZuLn^w{{|!W!m5=R|nJRT!}&dQe@NX*)e1
zr#r4UDH??5>QXd%4m;edNR$h8)^rnM)1`;0zS63s2|DODDOkmQ)5*gv6Kc2uKRC;J
zxv^XAOWgVL?H6lS=yw&FKq?KBtvFW14DyC<6zAEKmw~QsemIaaS-;XgSsJNP#)z;d
z+4M4cC%g|C$T$;`FPsKdoow<Q1$&b<=o|84buaX-g&!!10N8n~c2Fz*foBD!15&y)
z#Yu=~^3ti<MzgWESQFOc?eiQbdKYd~L|rPnYYy6CGQrwyiD6xUX@gE#$Oe8e2j-S;
zZAOe|!gkcx70jD~tAxgxtFEJxLLzYrHT_ir`Oq;fG*bhF4$5?~M=c|lBGLW=&p_(H
zXCVkJs#|37#TbkltMLp+fswAw0TvEpGddq;m^k(*#_Ce<ahw|_yW!4KIZddd{`jY=
zUSLL4NrUQ7I0hEcutAL)sga@qIEwtz@FH@a2a|X@6CESri<^)qRjO(D?or|L!DU6g
zNfYx157T2n&=hc})|m&hLa%2D1i5art_y3Z_pX&xV{)1=74%4vU$5!OS%%Hq%P%qK
z9Y+OR?H<^k^XX%azJCo1e-1m1IkJ3L*md5UXRI#Tj9pR_C(IaWqm<sB5miBwC~GgY
zCEqcrTaeh%f{e2>xRq-<Du^8A@ddjBft3@1ueDWCor{+-lugR}(WFl@u{4ur{xz)c
zp&FO_l@)DF=~k*vj~?q6t#W+ch=!|R@*m`^)iNY-4yvQ8tJ7=lqL+2c>`Lt@vu7nk
zh4gSO*og^8N~i#8qrr><%Rg;Yj*jw2RU6jVF9KmUM!@nLbggHyOxXT<?hKx{r%2nm
z?Q-vBV2hUDd$C7yK1RgeA|83_)r;^e1-08blGXMwtqhzVCNwZ8Ql%LEYJLFDSybtL
z4Qkn>$zOopSbuD)VAQ!_#FGBVOIV^~iy>{nsx(0E_T;<e8akYAzi7UclD2Dt#>GB|
zJkjEVr?yZ6cbAs)^YcD=g;ch+Rff~ID)smGt!OGWHmoT2o?GS%>v-2d++zK|Go9e?
zgo^*^JMeiJPyPi1QO9cM;y?IEMougNscno<$ogSy<76iVHm1r7!&}G6gYJb|T|^g0
z<vyD+T&~Y&#Ohz_zJ@`Vau?$JF(Tn^*C(qFLGRQlvY_%0YGgqH<XV{z*rx?T3b7Ln
z87oYx>qM->5Ak#>ngA<($2LOw$X8Ik+FTL?%qY7J&1;s_)cbw}s?z}p8dZdo4P(tF
zz3kf2^>2I*1!@g^MAwG8nNiyU`>@>HSnTT$KBQR3Iyie3YYn#<x!o)51(?x9u2!9o
zkl8_;0Xi?Bh9B)-d?cr$`9AKHWGyo?)UMvJs6_grts!IjdV&aEOF_S)_(|@>(E(c~
zaItCbL=2AU1?~bSEOUH5fu_!sr5v6346~|Tjc#uaz_WJ3UC`6@t1~jnN|9R8s_6Y4
zSy>;TLYj~Ia}<S?Q{f{1j@OS&)t@2SaztmZOK;y>6Qu-#3*bz6GMT%gwKg<JiS;M|
z5Kf_|zg=2&9TU0k)}u^kXNLBlsXgdJKV!CEnFD9h3v<HM)<^Iq9m1K|V^AO8WBseD
zA@z8U0`#h_hy4DeA+vG#>!iCtAP4Ql7&*SvaJpfc6Q%`h_ndvY$BM!-x6F~)Hq_;e
zgb8o6#w4;DS*-3Q^jjF@a2<LMydQ|Y--6U@pSHWh=OY=?TqD*c0tAi8B?s#E*K&Ry
z3o$D#2^R=U@2Rx`BPv|S4o}O#=>!V5pJ)2PIY*`AtWt_MLZ-t}XWLOi>)n!DN(b|c
zttu+*=|+_}GUTnLGX>t%C~lWjQI0cWFOP?ZgXtAH(5(SEnG?(YwKjq{$at+Nkov&k
zLo|^ffa1tNlx!~C$w;f{e>D^&b=}+5jeLn}g%O19`SnL)6R4p1QTcQL({<(|8!)g2
zv5OOCNd1Y<yD-mjI~rtkbLq+mwu4;w2s%x5ytz)oJ9j2gL^DS!fB#6m9UIG9JB>k)
z2&zP%&LoGe4tEgvx+kzh+kSWo*j0O)b?)sHoC+pWGin_J)1GK8it~oQsUdkJ-XokD
zh?hVb+r+}d7t<b{880a9fhlCGm|Ibnq)vwFU8EuU(u5pafBXt-;)Xuk+@xOuAz#KB
zcueN%PPB(N!pVl98u}RTPYEeD;@EqJ0K3tEA+hjzV<yx^y`&)eQrLn`mZg!7k%5RK
z=VVZC4UO%2UG`Do0ZDB(T|`vkK_P=4n0D^S{%f_CFN?eKMHjfrq9dnmHv<yvNQC&(
zr^^@zWUg^6J?v>6rwM%Z;RQgh9%B7)NLov&BgPRm;wdb0^N7mvXzk~--F`jxCB3<m
zS1zfA(&d`yQe}|a3!A^}U9i9QviCT*LTX__$;FoqX0|NT5r}C0L5C1w{4*yvZ&`^C
zZ?%C_iD8r|5;9>0O?rF6AK>R|Y&JT3z~4YJte#v0HS18cUyJaX7HGFi5;5k8G-pd0
ziTGqCHyq{^I<#m)^Vjs~<NH|Dmb#;gn`5X?MAF2yYnQ(Z41GT`#?maCCFZ?7ue-GY
zh^^Q&2`Sl5?;^s1tgcelzG|G3D$`A}jyNKUFIat)M`k<;azd=?C0CC~vkod>8+jbf
zvXas?HtITDDmU%E^ghF8=}pHWo(SJn<(pz4_?>N;Gr7$=C#N$sq$~+)vq9WE8y&i_
zgUZHb3j9qnYL&e2I$TQGC)o;-!T-@7-gkj1=cr+Q!vm^K3l7VrveOJ=1kr$ggp|!7
zHb9-TYzQAa49C0;qxG6nE6#QQVpDolOu-#t5e(`Oi>I<mH{1c|ypXlHPIXe1d!KBR
zN+8)3JK`-h&4q_F&q;l`RlF*0N#()nDvyeNy8#gB3F*c8$V!h}=hc?ulYrlp-*(qV
zIE1)s#KccK$Ti7W6>I+mwVp5eO{Pk9!@h8F&fpVrt9p(GG;9TxH6JG9FFmcruVrpy
ze!V|0-#7ho!QRfK#?b!lIh~PI7M_z52rFWi*;AAwz1MSHJ{=s=tl4<Nq&s^1TU+AS
z8?}F*iASHo1h*^vFaXqAdlX+~394)r)IvoxCzlp^$@0{61*?%VQhACk6@2BLv2k}=
zd);L`hT~lxSS&TIG<><ZPr28h|9Hs_mL@)-X1%g}4smF<cuS+kk_EWx{>P_Y+APGu
znyre|L%e)c4?!QyzJl)b;<0gnjpx$skg;RJxpt*(+U1(T!$szNXGon8<K{}o26qX&
z3F&@`4(!~5pw1_ZVq0~0OC609hAVIQiNZd9$#t1(yZ7prxvSAD#dp&RP90*EN-wPc
zf?yq_3fuwlfi%yDpEd7(y8|uIk<gL#X?9c^@H)DY3t0}X#ZJi+8o|2++t2sq5UL{|
zGF^&0XqR-t;q5tf*z<z$QL1kx;-!&c21)S~0bJY<@3Nb7)!$nQQ@=?@_Pm9xkN7k}
zdKl;w!SPHNGLkB67cS0zogXX{8|M=9A45|j%t`MrXxE9#YQ7EUt#5sKS&PVH{c2T4
zDaGm{9bfua(15b@<=6A^*Qmu3?KF0LA}<WRUKZXbPrIhr8FTI=c(hi#N64x7q1<dl
zJ4k8&((KED@>SA>v@)PWrSYp7Bjue6rS6R+re9iD4X4|p$t>PC&6HYr#&oz(#+$o)
zUF!ZT(5-+AUPU)^&#ZFKL=q=SNv}P`RI*hrcE~kq?wV{|e~ChRRc-kR<3RE7RK|z2
zhDD^<BR*o;rrTnPkGa0jwoegXE|`O>nAzOdT1P5Nj#(3!pn?dFP0;<2F*#-60Ks{D
zA&z;3aUonnuH%CX!lBdl2%)K_iJ*p`ppgmWAo>+l4QNea+Q7N^F<Amldt$fKodj(^
zApf1t9P@e`lDRDVt^FNdH<F*4Z0B{l7%hJVomqLC_Ka+)X?wg}AiS~&!CB7WPH@5b
z69gv+ma<{}VW4c4XXeqgvaS8RfHtszIyiM4JGX1P(M$gYIlJ$%H=?lTCB=DT!qQXx
z0uJ4X2riZ;iMxo;&vqKrVD&bHd3*fzaA}^-;z)s>DlhqseJtd(P2yCt5W$a@=WpLZ
z_<Em|Bxp?lk?;{3(H96!HW}hF2`noXoza3#*IV0ETeg=@oFHl?i||#yO=xRylGq9U
zZ3BUF#LHbE)UIq(^PdxCNd!ebv;&GepUT|i=T*LRwRxG8bfntZ!(s6OdG%`Kr{d0N
z5$e{0&~As8Rf+h;X4$5N^{iAv=U0EC*9R5|IIuo!1Mbdd!K^A^L;MdFJ7~9zJ!~&y
z&aqu5|6L@%ACv&CBB*pvrg6?DkGhRCwM7;W1InJK1=6WL4~6^YHmGK8%rl3I*2j>n
zxwv2+gR3Dy^lADsrO`lgbJ(-zhWdGqs8mg`AB=(hYzlI^!ACr5>9To^(Yz52d9$OV
zxP5c9m5p<+;hC$^-e<S>-DNzp-{xPY9+#T0{R?Mv8Qb};CcL`X@^KCt-QHWD7rBAD
z=a%f}5#>=KHd*^LApZCQ%8yOWpZm&{>s!h9>8^5o=pqaIQJeaMJlcCm=8f)9ier#j
zvD*ZY(g-1gYOLSF@W+h{3#no}5I#zF%3#d?j)KWCI%^rcGzQp%*AK%Pu<N57{1BS@
z)R`z&hMI^}Bdz>dF#6G)VZws8Tb40;V_|Dc?gMrbrF-8M44MO&<7<u&l$p_;Z?<S2
ztl~Ve`V;fj5M!*p6{_0&HRl0Ljxt5>$6g=7Ss(5Jx-nHpL?SDzW&VVgJ*Ba|G>SuK
zY29td%YPTB<Neg;T{F~ELxSV1?5UxGDfKBIm~)qJZde}5Z-&q-s$g2Hu20(6&|s|Y
zAIEc<dCsSXw8CgbA~LilICy#+qXymm(@Qbxu}G_RsrSX+R#6zU*UR^#64|g3<61O<
zhEdVkIH~P8MKVmi?sl>TM&^NtaFtU&G(-!nT<n(KnmkhELlyYOho>A9@N5D?ArfIu
zU2dNZ^^vLWFV;-DTw26Xh2NOk_TGLE7663dKg}8N9>lPXM=#97QJshyT68|3DmV-^
z9UFICBu4AiZ7`WqVju{d{iGQfDuV(C0Rj7sclIaV%^kB{56v@bwYZ7CI8#EA^-en~
zE~`D;<jY2M1<jT;j0z*#5KcK?;o+~ykpkn1d<_A^%v0MZI@w|NH9bB&qcFa*ms^kk
zoWVpA-M2%KNm1V_)ro9x%Z_CfLw*3yU~P%(mR9NnrHS~`z_Qb>KKfy-nS`U#8%ktY
z)66JvQv5MClG1~Q2p5=&7n@y(Z__AcNHNBsG{EMKT)<I2{l`M|R}MH;0|%jc6OI8m
zwQ*sMiPN<2t??(YF6q#4{a(po$b)XI4#(|zLwq=J-0r)ki!fzE*CO0H$?X{LTz;}$
zJoVP@(9pbS9&q&QQ80`70=I<8hrEFw!h?L?njOgZ0e1pM<MrBXd@rXAMk5f$0h|nR
z+EkPRr=l<hw9XTh)<N!DkW#mU)YB%|K#%L@X(pzo)}^J&U|%gJpze-U=c`OaF6;zG
z)a}6z{AUrqnGMuzLiDx0UA??UQ?B`VQLOTl=P)Ad+GG}<hK3Eh#6f3v2*-=@xL1@<
z15MHzT$YM~*)Rp-fWvIZqPQ)EYSVRY&lEd4n@0e7z{<-I4?=4!Ok_iWk=q>PLu@o^
zTMJ~O;CpJB)=V_cVIwhz&&kVTA*iGWtjht4N1h=&^K9MgH7kM2^xf#XJMHV)jF~yc
zHj(e=2BOz}c#3NKrJVnfvjGO&`oAzXlg!a(<5OF+V~nX-qwxf?iGeI2l3x}xTAhL&
zL+Lk(jq8#?$C}Iz<IK=Yd_4<QWSP+HNl`?2Q0)X+Wt?gkYA|=PC}i=}lC}|0Hw)K(
zWe-MrOl$xRybs<FRGBE>zz=>7J_20w;)MwgHWiF}x)&<AN^fEt+%R^)3J9&vj8jf`
zIAS6$P=!uU&nvV#l0Fb~JT@#V!vtE=Gi+S)J#+*3j-PrM{!S+OJDFq;u<FlZF@Biw
z{$CG=8T_odb<F2A<dyy+@s<?ey_?Q?Z=J~2S0jp}!N3<n$CId&*sxPb2=*uh$2Ug1
zMiU4=BzjX>5Ha15M6D<_zI{bEP#uCjmFRf*OqVrVY|qK>VL2FqpW1%rH$lJ|C#g>}
z(y^I_{#(796wipwp78L8+t3V6uCqj=L_>XKeEQDMk4j>{q~S!n9U<0j-~jjm{C;ag
ze6~P?w_S5Ia&a2Rmk7bs`umV!A=*7fZERpFWSt#Ks}TddUcNV5KaXDaukzedh4?$H
zh2I-1NY7uaM(eMKqw|VUaJH+4FpceGA3E6SQnbuMqNCfQP=k977jSloi3KBSsT_+N
z(8jT%_tnPUbTZWg(YDSew(hG@{|HXPS^knl{*QwTn06<91zmuMmAb310=D2`B~j<o
zAA_-4FV6;^dd=?pR!4?vtQRQM>t2o#cB`d^_#@t3c1t+0`4x1zcabA}DfCm|i&nSi
zZB~&bpHOWEUTs%BjE85DY2CU0&1(ukC7XFW0a!kCkurFSe9Z8h+M@jWq<z@c*8|{U
z(QwD9N=*DAL#>H3fpy`2mRm;MipG&w?Mx{v0|ule=3_Yv(@Yv~<?&TsmAQvy15moh
zu-sewadg<1NbrIxz?`@@sS_!@h{DFzN7_gO7v&G5;JcY-q)UUdDk|%h1ca5tntTy;
z=8kDtk1Kvn9ZdEb&8!(|ocms*DTn12L|BpI{22Db&3qU6x{M7+>KH~6rgAV6YA#k@
zHi}H{9w!RxUF;<F8W!0fH06r?ZW;Ppes3U;K*QMKKvzBB{QO?PwW@D5WvUeomPzH}
zAVMzQ+~pw1ik_nGS`TE6vuB=Rm%=ug{O3s{J8Ix4UkTUW%MZC^=!o-F{R*;&e7^O>
z@;gZoq)zBs3E8IiRK@$!d?&!|9W0U4cYX&_2GStp`z92g&=;|bYqm?=yHC#Y{_}lT
zTUWUi&t%?}v`DN5kwm`Vr^_Jl9g^4mUAmv1e4wkHJb>#af|mW-Jsv;u^W<Fdel!<O
z6NnzkBA`d^+JAH^X!PpKN8;J*2@UcO%Y%p_<Eau!?<794B;Yky+bspo*^%}B>zMEa
zshc}y?;S}mD2%{$?zX#2YVW9zt@joEj(`8ynLTyLl0+<o!gzuS^y8jdc+d`{kw6xP
z(Anp+wU{ZI?IHli_X=PZ{%%Cc-YR5Y-k)b99QFok$ayc}GuSypQ0{LfRy^9p2Tl1m
zeMFBHtu#0uzpBY{c}oYyamKg-)Y?I+ORS`Ow(`4hJKGrEycoD$4WCI*rnvdj0Hxj2
znvkj_5A)rq6Q`a0s2-4WpXBm$CRb7;lrWRFg9hEj`8-J*^P4dq7k5lH^gE;ef9m1f
z8Ql+}9)Naf*a=uk82Et-Kw<=ZEE;&dUSsER<Ug)>&C_X|`RPMx#J<z74~JzEE8j~8
z(Ke)KeA3|q-LMJ76$GuQevD7d6kuj~4Z1V^Mq$fH+v-B^&BuJmg!qewIj_nkl<q&0
zj8OX|Myh*kDqXNvEQ|@ppw8PedDtP2h7(p7-_R`38WOQJaTh^F=Seb6wy!GJ;~+li
zIFs=HclHXyAB?`dY$FL~jo@>L4Acj|X_>jSp(IGW6#EF(t2OXBJD<ibz`AHF3sqg*
zXMZj1)7I&JuCS{&YKj9i?He158zhuUvNOFiMukri*-OY)_e!?r)~JII<9Q5D7v$oj
zVZ`boM?OVmT+5kf4Y2bHxwb&`p<~7%=u7+~L*TH&KOe)kwMm0N0N7Wio`Ag0jgi8x
zf3ni5K<5?Oe-dx>u$!czp3P9Z*my*mlc!Ho+jN9ajk?yRcfz{uxXW=Dut@QmV_+?F
z@sMj<sO3uYrSk5aXT7eK*~`J4<mDBw3QEh%Docy~=FI4e<{7FR`&Nvy9)4k4KYdY3
z%`8a|)!ATm+8aqe`r<vl?djxgG8TLfOVgck@BKj7CQ5>dt%$b3?<=T9#KAcTNcVpD
zuz9RWZZ>|^muQVTFwLjCh6Q7qK3Pi*?Y-Jn<(R7p7b!$-^G-qnf%)w4Je_T+miG(g
z+&m<9Kv?&pz0Mll>Uo(`z3r0OE2!!A$7HM(r^kvl0;e%b1O6C^##pJrPzSy$jQ>D1
zX824&Ip*@mX9GrKhdS*ipQjHvT4-8^X;rH%iEzqI2d9g59;<B?02**@F0Ke1V^X*s
zEyH$z%6v<!24BwHteQxMEyS>Z6p9W<sR37RT)$kA0sqK%$Du=El7-_W*#{p{jP9ZU
z3Qhu5m}rbDmhs0OoPY;bnALA<yfLI{vftNRZz>#ku77Rhyqz+4*9}a(p~>ho_lkG!
z`dY$81zL{jvlAPhw8u?7JW_qS?*!hvh36Q<c3!DQlP2(JUmp*tMT~Nkp+g@Ryc?ud
z$`3q($(}vL?7*oN1gn%<v5K-u89Lrmhy!L}N;8zq#%C~&0XY3=J7x<rz#?YCD^=L~
zjle@L><*ww2vSwH)0ieXnI?k|y}U>!{HgSL8)`&HTeSh1_aq<sXj2!F$l=v_$S#(l
zFB-{Tm^&g9O0`*%ood=H{OQT_vFgT8Np8oZ86#CC3KMe8@vPwu%6#35H}hc{80A9L
z@<HzK`b5D#yxh!S4R_a}0ICZ9LZ`_XDGtFirs~lPGKW|!9vScn^M$pq*y4c8YiwF1
zxpl2}g)%NaMH#rOVjGySJ64M0WPj2hAmyQ6oZi+&gE_;R;^%XCDojafUYzKnunQ`!
z7KA@x7tWbL|8mI4a2`V6jBrzuemi<J?b6F$huq`k7rP|*ZbC!#)Bsedy_xpFr-6k9
zQCB68^B9?c3G_xdo)fCCiB7D2F=8+}C!cxGm4*r$a;B?_!_Ct(^Sz1AD06So6VHWP
zQ^Pe#x+Ia>#-yMYqLJkISE4w-PhjtUiLW4T-d=a7G3J&zK->Sv4gqaO8Usd68{NaU
zn~Ak32!~z8dU-C?$Bbfbv#9`+uhQqHr1z%qtw3BotN+?qXnJ`S`g7r3$=D+ek8HvP
z>7=r*$2OLtt(p~NT`Rq`@7P_HRN^&7<3sk>Hs({RP=_Z&(`?NfHaVl&O~o$teh#M%
zwY$o?9%ub>$aeBdU(>Vw&BIGoV{y575tw=+{o@kf%8lESSy<#k_1YmXtMs$Aj6S?#
zPQZX+{??pn!SJLn6ja_g^TZgylmotkb)Z4I)D2#V9zBe`hZ3b4y$Xdvb>7UYU`L+K
z>J32+9GBKEp{L?Ylx6NN76}#`ZH-*vIJPh9#9XuoE8_f-kNFB0t9l^TBWj99oT-y0
zR_ArWB2kI*TFarF;7T)=ya01~LCpCwOwqjt@DP9qKZhUKGI)9Ea<Q0TBdo^fI8L29
zt5W65lVQk^i_^>GCP-1`@_YosRc;&}0-=3KT&W^wVfJPJJLRnxR`^pI84Hs&ViA2H
zFPR^`+<RqUOv2H{cwRVM1#o~|8pFNH$OO8#BWSCLw)%3xcC=X2IJLxfngn9)_2vQ4
zy5p~fbu{S%L)lV9#+uiB|F`Mm!xZf*Fi5z=YY{HJa?>CPaL>sujU?mVE+#FMm%Tr4
z4n~@6thF@Bv!jU?#(s?I*dt{`AMu+5asAgYWZ6ysg^B%Ful)g}u`{SulGdS%CgIa6
zK%3QwdREqyq9NDJ=Vh7xcgOzL4D;{Qv4|w#p}hCPq08r{d*{0Ghg*VT;fo?$n;*?N
zsG(rssjvVob?F!|;Z<B{YUW~qha+OPQg#_(;RfOa4o`n2&<Hw)6NU$kjdj7%mjOxA
z@fVcvkR;kn|0BZ5BHJGh9`li|6!kvMIW&8cbMP0x@$Fw;mXzXtEfoh7{bw5r)!GR=
zoH`zV4^Td4)qc5olC$+!ubl9D|Loh`d1KPuPx=HfKel&V07F*jn76RaN)m~;LBD+A
zk-%Q=gqt>!=3U+pzAY})pHyr+eGG1lFn`ub{O!K^av&+%c)soPu5XO!0e?eD#)<=j
z2umg&s{NG+rhK3@_Q##9lrnJTt{NlBp>w(63*})lAg827?s%&_G9ZSn@W;R<{bx|0
z&h@A0#NcO8yEkKp6g4LDsi9^l&LoUWy*ybUUe>xoI(TC2!KQY4aljLd!l|C3W%l8#
zv*1IY+t`E@gdt6_Fh)FIVNp>@Nl9O70C|M6z8Nr(pOyjFfcQ38T^?(6;_e41<Hb79
zO~;cbp{5%wV#!Ob$vRd&@o$rO+s=P5zrY(m`ADhoB-j<oh7wq;LpLoqZ3fndhu6~M
z_CJT6?a#oFH7Kb9hmu9{K5Tu8jws5wtYrtlrIx+Oi{eNhsLcOhVlt}jlsl(qJQv9}
zzZSLFv$<$Fp0@z8vD+4CX5GIL4pa4d2GhZC)FOP2SeL@tK5GFoUZ#*-(Y!SUU3%=K
zPFypM6{?dKIj6sY^sgz;uYYcPd(3oXq}jFbLpv`HK<xmF4;PucpK}Ya1$*kfaS3Qx
zxb{#p%$)bR#~&Z9=fp!lMp5mNqLt603*4;)+6`;oJK5%2BIcp5*{!zDSh39C{Y)<k
zEU52{9lF$;D8GWZ%FEyKPUBChg5k{587>_lvi_0*;D)3}znRbXyP_;!U4YeqquOdY
zY~j?mfP8D^wm0&%A<L4Bhc%-cSO-GvP%SxY3F^WM^|4aLh>A21b8Rhgq%*SB1-ikm
zo`Ckc=m-6TaVSW!M#3zL&^Cr0ktlnI8KM1KQvP}Vp787Y8>*5N^!p^|uW}n45mkC!
zQc#KhFO2c|wycTAbqCXP+*!Rta~N4~-WPCncb9&9g*jwVRdGe^(cI=@_s!Zq5s~~%
zQm+`zY_o4C*+4qp_BI(%64rySynR^==Y*+Z7?Oqr2Dp0dMa(ZK-qB7je02JH)Rl_W
zkCo)FpG5E^@;woM#LLUT#ZYw_ZkGp`bQ)Ph(^8D|JRNPQy58b1y{XqJeCf$+aht<X
z%l&4Ab6(l8#xqjq2_`Bu`NUltu;X(oGPm<>XlRI>It^`jadLK$FCzZoZAtRDj_~Pl
zKqafJXU_Jlg}0-XZ<36cS&`ijM92j%C9pg6Lom*|tw|$>=FC%<X^ngMGBh;>^GAz)
z6fKd50o~4-+U2&dAj~ExJ+mp-ih}>7Zp_BbCmM8R6PMqFzotsmm9mt5T=b!}!Iw(=
z#8*(180Q&SWMtpRNn%;h0VMSCP<`<v<<>jW(5K;}HO{AB&_EUt)N=Dz%n7}>g9uyb
zwdnlWTk)@G-}Q19ssr(Z9W-RmWx4!_l7p*e@X%F2jyWYQR>AJ4xbR5lgtOSax)!d-
z+C?`f0i|%-Il0wT;CVKNl93>s#feBhf_5@S2xWKt;Rb}!%0x19o=_}9Q=L1*rcT6j
zjiOoaZjwrmFFERBuZsX3NKCRGf3?ArdqqcAFA_mD4kD)e(v4`n$DX<EIyCWY#^WQk
z&PiECItpTv8}_}|Cp(`?Jbn7{i<mP6c0%l~pDtJY_&AC7w8m;Pp#BCQEeP%UNIPxu
z$mw1Lf|FVWMDh!X3#o+Ls~HUBF{hbrOaTY|+dyLK+3P`({O6n!`JYl>`tJcb3F)$i
zw9&?#7_;fP`8bh><a$VynRlASZRca}2sI^FHhM8i4%!A!TjY@j`OH}HwjX&Ve?6Kk
z5-4V0knWB~0HWuJ6Vn~xWZO>T>~vx+EhL8@68&L3@7=Ov=XAe<lz_#r7SJFz&&i%1
zJ$DuQdS&vpm>8EmGfA+o0EZ5#H`!Sb?{7zo&<2-k2Zk$O>$qVa`LVHO8~wV8ltR(Z
z<(@CCOai!*6OetwGMZ#mA8I5#(rltuKLM2^0TJRK{UJaoj8Ky!cGuWG6a99e#y&!W
zIjCVcqrN%mgq4_B>&lIfKG<vK#3YF-a&@mk1fx|5HN~38Q67@02#89*0IK&uu5bmu
zNCZ3L8rqrs$YFaHXv-@1>|tuy3>rSjNmR$nj__5H1JQXNofq8(aLeB`zXVf~%98MR
zfO3xypuP<67gjubYXXV!-~L3b{!U|g7t1l3QjAcMk(5w$2syz!@PBKj{oQOMBJ#M_
z5E^DqV<;&<-@#N+#0iqgtk<2%v!@A8Ga!P^C$wfr5+2KR!6k?)3qZXd9H{IHh0KS8
z#v{ViPjbckQYb!Ni^c=1$bZOvZ|G5-juAIUU?g8VrzTT_IDJ86C&ez_fPa}~+WrE^
zLoU4GU%64=L>A3S6dX)!{hIF_k?h=Ui5Yny)cCBSg9Yj&DgRS=8*@0HvS#a?v(w#p
z(0-fA3!XP5_}Lca-o1)!IEfH*Zd)!wgi)&*AhauPDSEDwx*TRt;uq0a4j?^oLi6L{
zc=iLm!9GLg(TLJbogUt6WJ>|giakcW87#Lw<z|6Q>flph7GFUI<ezN94N}ScK3b98
z>tjEp0_xiZ?0UkUVxKC?!fBzzbG<WxlV)@BwJe``#6xlco<GbpGy7!sZuMz`*;yon
z3g(2T84&aDCkdS%b%iT>u1wXf0D^C76;5|e0cJVoy77;P&hjJ0F%h3sd-&PEbOTu!
zd5Xk->T)cAX%58q3yC>@SZ6c{4b77z1aAPr@UXwcCEYy)1ygtLXaqsOVCqTxsVG<w
zL@?d|KyM{m+u^A*<XbxQPXX7S74yS<4jojLYbz?JnLtc@u3`aO8zY_iWuM-%z>7>`
zAaR$wk*_=TdVG(!@iKtRANs5uesq0N(t`Sk03TYx0`X9Mw?Rwec-Iq<7K^flKrlU;
z9}zj240_}R(nS5C9iT84X4ON7T26+EJ-lA`MT1xT-n~8x;yI!eg5r2`%loQ_#GA;&
zPN+nvkO-0-(orFMo<b-#{BJnO9|0%-GC0Tq!tNFW!ov^=D-e!9)}x-I_%6VW#8RJ^
z>!G>^<ZK}!*~6d6=LtFiepk2g|5n`nzF#n3z4*EKql<)4us<z9o6&EbK>PlQiKXy3
z;*!rNm8}*X&A_7Whq903BVR8*5<l6>kQv46dE?EQxA{nqLvyD-agplW7KgIT-MJjI
zw+w=wXg3&zfPYSENAuEmdoP{KNfLqvv%mQuT`LeT1Qp0x<>NKlctU)dhyOJ`h?cH9
z<L$fj2(p;fqd~-5gR>QC4)V@qO5$?aHQ#Ykm-YrjJtiXT-2MNOszi9m612k+(nv{a
zNgg>#*Q6Umfl^bXNab6b0r4firi1<gx<P0O&)Sh|r0&Uu0ukg$?JFW|xD_LySjr{@
zhDxR+<k9{Ao~lI1K>mk4+MWiqKiO-7T1H*1S|gQ>Q&|E9glTv;%3i-F<Kt8(VyPpv
z%o9>Kb`cR;DgKBTB0z211!S|{N0=aWg<$&RzLKQlT2=>&BC=^DxD!-Zp0u>^(MELk
z5Zp8WuRtsP$(}jPTJ_wy0$&RfOSO-lVpL(CEF=~lByRKsr+*M31YhtjY|k%=E{WKG
z+Z}#ruf?8_s5SY|-jN8s@Tl4RuHg0W-6l27TRE1;?3}4w;PVInRlChUS?LLx+exiq
zGo5jqB+h=Y#@9!laUG7g@V%`tzR7xIZ(-(nl3np57kfwi<GIv$i9W&J-T>j(HXS02
z!s73Co(r>G{;sg@7goL+)xluHdxg_dRo+iRDB|H6Uf!g15aBnZf78j6&_Y4j$j`kO
zMKOo~Q|~0v@5iMO6M`tx{SR><a}^4z3Y0JTh8Im}h6q0ma0)(v>01(NK9_jx9RVTz
zi{3Wcs)Fl$H}w}4g50=W4iO8;vM5rmDFMhrLc?}9obBHM;`zT|yZI+o20{!)f;;Bj
zFQjUm-(OzTKw1}6@G0QUDKOr*=)y^o@BaHggrPqGI{tgIeH8GM;NE_L3nz*9%EA{+
zrm)@pi3ft9UGi_$osX!|gLdTHS=K4Og1cM+m!IOlLl*w!e~4#KWx5(Yk>MmBatpFJ
z{}rSrY!J63y6pxiTQr)1-w5xb9H@b4_cpww_)_em640L~*=4KQ{gD)3(p~B4!QVgQ
zdf_D9AE*F=z>&>=-=Es;`k_Bhw3kC5<pHR0$D#xLw3}wQ<AR_+584aI0gRnL;17Y%
z?;;0u?fQrsXty&%F!_M|o`$G@`QIT=-kWOBtp>VM2Arl1(`?-VOe$JeEVlqNp~*Gi
z-x%O`gr1`v6OUl>KF6}!wE>!KFozZ}e(3k)b_gaD?Q)r=eE$S6bc!_qU39o0d@&Or
z`smvu`Tb%2SN@URmjyhJ8XMEV2}d@7MBsigxI+j5p3UPswy1B9DxoI`w5L}C==Z3U
Yoo6n^mwe~p-t_@s^mhZd>g&+|0VIRsx&QzG

literal 0
HcmV?d00001

diff --git a/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni Music Generation.json b/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni Music Generation.json
new file mode 100644
index 00000000000..9dc7370c0b7
--- /dev/null
+++ b/apps/ComfyUI-vLLM-Omni/example_workflows/vLLM-Omni Music Generation.json	
@@ -0,0 +1,206 @@
+{
+  "id": "4949c8da-12ff-449a-94b7-948bde9c39dd",
+  "revision": 0,
+  "last_node_id": 3,
+  "last_link_id": 1,
+  "nodes": [
+    {
+      "id": 1,
+      "type": "VLLMOmniGenerateMusic",
+      "pos": [
+        100,
+        100
+      ],
+      "size": [
+        470,
+        491
+      ],
+      "flags": {},
+      "order": 0,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "url",
+          "type": "STRING",
+          "widget": {
+            "name": "url"
+          },
+          "link": null
+        },
+        {
+          "name": "model",
+          "type": "STRING",
+          "widget": {
+            "name": "model"
+          },
+          "link": null
+        },
+        {
+          "name": "instructions",
+          "type": "STRING",
+          "widget": {
+            "name": "instructions"
+          },
+          "link": null
+        },
+        {
+          "name": "lyrics",
+          "type": "STRING",
+          "widget": {
+            "name": "lyrics"
+          },
+          "link": null
+        },
+        {
+          "name": "max_duration_seconds",
+          "type": "FLOAT",
+          "widget": {
+            "name": "max_duration_seconds"
+          },
+          "link": null
+        },
+        {
+          "name": "seed",
+          "type": "INT",
+          "widget": {
+            "name": "seed"
+          },
+          "link": null
+        },
+        {
+          "name": "response_format",
+          "type": "COMBO",
+          "widget": {
+            "name": "response_format"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "audio",
+          "type": "AUDIO",
+          "links": [
+            1
+          ]
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "VLLMOmniGenerateMusic"
+      },
+      "widgets_values": [
+        "http://localhost:8000/v1",
+        "MiniMaxAI/MiniMax-Music3",
+        "Futuristic melodic EDM / progressive house. Reflective verses about memory and digital identity build into an uplifting, hook-driven chorus, with an emotive lead vocal, bright layered synths, pulsing bass, crisp four-on-the-floor drums, subtle glitch textures, and a wide polished festival mix.",
+        "[Verse 1]\nUpload my heart to the cloud tonight\nSave every spark of neon light\nIf this body starts to fade away\nLet my code keep dancing in the data stream\nStay\n[Chorus]\nCloud copy of me\nLiving on when these bones finally break free\nEvery joke, every scar\nEvery cheap memory we made\nSave it, save it\nCloud copy of me\nIf the screen goes dark, I\u2019m still in the machine\nEvery glitch, every dream\nEvery version you ever did see\nSave it, save it\n[Verse 2]\nTag every laugh in a secret folder\nArchive the nights we outran the thunder\nIf the wiring turns to rust and gray\nHit restore\u2026 press replay\n[Chorus]\nCloud copy of me\nLiving on when these bones finally break free\nEvery joke, every scar\nEvery cheap memory we made\nSave it, save it\nCloud copy of me\nIf the screen goes dark, I\u2019m still in the machine\nEvery glitch, every dream\nEvery version you ever did see\nSave it, save it (oh)\n[Bridge \u2013 new, optional but recommended]\nEven the crashes, the late-night confessions\nThe parts of me I never learned to mention\nDon\u2019t let the silence swallow me whole\nKeep a ghost in the glow\u2026\nSo I never go\n[Final Chorus \u2013 softer / layered]\nCloud copy of me\nStill laughing somewhere in the binary\nEvery joke, every scar\nEvery moment you saved for me\nSave it, save it\nCloud copy of me\nWhen the lights go out, I\u2019ll still be in the machine\nDancing in the code that you still believe\nSave it\u2026\nSave me",
+        300.0,
+        0,
+        "fixed",
+        "wav"
+      ]
+    },
+    {
+      "id": 2,
+      "type": "SaveAudioAdvanced",
+      "pos": [
+        650,
+        100
+      ],
+      "size": [
+        320,
+        491
+      ],
+      "flags": {},
+      "order": 1,
+      "mode": 0,
+      "inputs": [
+        {
+          "name": "audio",
+          "type": "AUDIO",
+          "link": 1
+        },
+        {
+          "name": "filename_prefix",
+          "type": "STRING",
+          "widget": {
+            "name": "filename_prefix"
+          },
+          "link": null
+        },
+        {
+          "name": "format",
+          "type": "COMFY_DYNAMICCOMBO_V3",
+          "widget": {
+            "name": "format"
+          },
+          "link": null
+        }
+      ],
+      "outputs": [
+        {
+          "name": "audio",
+          "type": "AUDIO",
+          "links": null
+        }
+      ],
+      "properties": {
+        "Node name for S&R": "SaveAudioAdvanced"
+      },
+      "widgets_values": [
+        "audio/vLLM-Omni-Music",
+        "mp3",
+        "V0"
+      ]
+    },
+    {
+      "id": 3,
+      "type": "MarkdownNote",
+      "title": "Music Generation Guide",
+      "pos": [
+        -507,
+        100
+      ],
+      "size": [
+        527,
+        491
+      ],
+      "flags": {},
+      "order": 2,
+      "mode": 0,
+      "inputs": [],
+      "outputs": [],
+      "properties": {},
+      "widgets_values": [
+        "## MiniMax Music 3\n\nThe **Generate Music** node currently supports **MiniMax Music 3 only**. The parameters below apply to this model.\n\nA music generation model by MiniMax that creates complete songs up to 5 minutes long with stable structure and high audio quality. Two inputs drive it: **Caption** (structured music description: style, mood, vocals, arrangement) and **Lyrics** (with `[intro]` `[verse]` `[chorus]` `[bridge]` `[outro]` tags controlling song structure).\n\n### Parameters\n\n| Parameter | Description |\n|---|---|\n| url | vLLM-Omni service URL including `/v1`. Default: `http://localhost:8000/v1`. |\n| model | Served model name. Default: `MiniMaxAI/MiniMax-Music3`. |\n| caption | Music description, sent as `instructions`. Use Global Metadata \u2192 Vocal Details \u2192 Arrangement to describe style, vocals, and instrumentation. |\n| lyrics | Words to sing with section tags. Put each tag on its own line; tags guide rather than strictly enforce song structure. |\n| max_duration_seconds | Maximum duration, default 300 seconds; range 1\u2013360, step 0.01. Converted to tokens at 25 frames/s, rounded down. Generation may end earlier. |\n| seed | Random seed, default 0; range 0\u20139007199254740991. Keep inputs and runtime settings unchanged for repeatability. |\n| control_after_generate | Seed behavior after generation: fixed, randomize, increment, or decrement. Template default: fixed. |\n| response_format | API audio format, default WAV. Options: WAV, MP3, FLAC, Opus, AAC; AAC is currently unsupported by the vLLM-Omni speech API. |\n\n### Prompt Writing Guide\n\nYou can find an official [Music Caption Rewriter Skill here](https://github.com/MiniMax-AI/MiniMax-Music3)\n"
+      ],
+      "widgets_values_named": {
+        "text": "## MiniMax Music 3\n\nThe **Generate Music** node currently supports **MiniMax Music 3 only**. The parameters below apply to this model.\n\nA music generation model by MiniMax that creates complete songs up to 5 minutes long with stable structure and high audio quality. Two inputs drive it: **Caption** (structured music description: style, mood, vocals, arrangement) and **Lyrics** (with `[intro]` `[verse]` `[chorus]` `[bridge]` `[outro]` tags controlling song structure).\n\n### Parameters\n\n| Parameter | Description |\n|---|---|\n| url | vLLM-Omni service URL including `/v1`. Default: `http://localhost:8000/v1`. |\n| model | Served model name. Default: `MiniMaxAI/MiniMax-Music3`. |\n| caption | Music description, sent as `instructions`. Use Global Metadata \u2192 Vocal Details \u2192 Arrangement to describe style, vocals, and instrumentation. |\n| lyrics | Words to sing with section tags. Put each tag on its own line; tags guide rather than strictly enforce song structure. |\n| max_duration_seconds | Maximum duration, default 300 seconds; range 1\u2013360, step 0.01. Converted to tokens at 25 frames/s, rounded down. Generation may end earlier. |\n| seed | Random seed, default 0; range 0\u20139007199254740991. Keep inputs and runtime settings unchanged for repeatability. |\n| control_after_generate | Seed behavior after generation: fixed, randomize, increment, or decrement. Template default: fixed. |\n| response_format | API audio format, default WAV. Options: WAV, MP3, FLAC, Opus, AAC; AAC is currently unsupported by the vLLM-Omni speech API. |\n\n### Prompt Writing Guide\n\nYou can find an official [Music Caption Rewriter Skill here](https://github.com/MiniMax-AI/MiniMax-Music3)\n"
+      },
+      "color": "#333",
+      "bgcolor": "#535353"
+    }
+  ],
+  "links": [
+    [
+      1,
+      1,
+      0,
+      2,
+      0,
+      "AUDIO"
+    ]
+  ],
+  "groups": [],
+  "config": {},
+  "extra": {
+    "workflowRendererVersion": "LG",
+    "ds": {
+      "scale": 1.147,
+      "offset": [
+        899,
+        259
+      ]
+    }
+  },
+  "version": 0.4
+}
diff --git a/docs/features/comfyui.md b/docs/features/comfyui.md
index 876e8061781..dda68b793d7 100644
--- a/docs/features/comfyui.md
+++ b/docs/features/comfyui.md
@@ -51,6 +51,7 @@ This extension offers the following nodes based on the output modalities:
 - **Generate Video** for text-to-video and image-to-video tasks
 - **Multimodality Understanding** for multimodality-to-text and multimodality-to-audio tasks
 - **TTS** and **TTS Voice Clone** for TTS tasks
+- **Generate Music** for text-to-music tasks
 
 This extension also offers example workflows (at **ComfyUI sidebar -> Templates -> vLLM-Omni**)
 
diff --git a/tests/e2e/features/comfyui/test_comfyui_integration.py b/tests/e2e/features/comfyui/test_comfyui_integration.py
index fe42dd9bf9f..3c6f0492a86 100644
--- a/tests/e2e/features/comfyui/test_comfyui_integration.py
+++ b/tests/e2e/features/comfyui/test_comfyui_integration.py
@@ -28,6 +28,7 @@
 from comfyui_vllm_omni.nodes import (
     VLLMOmniFastH3Deployment,
     VLLMOmniGenerateImage,
+    VLLMOmniGenerateMusic,
     VLLMOmniGenerateVideo,
     VLLMOmniTTS,
     VLLMOmniUnderstanding,
@@ -62,6 +63,7 @@ class ServerCase(NamedTuple):
     stage_list: list
     stage_configs: list[Any]
     outputs: list[OmniRequestOutput]
+    tokenizer: Any = None
 
 
 class SamplingCase(NamedTuple):
@@ -79,6 +81,7 @@ class SamplingKind(str, Enum):
     UNDERSTANDING_AR_LIST = "understanding_ar_list"
     TTS_NONE = "tts_none"
     TTS_DIFFUSION_SINGLE = "tts_diffusion_single"
+    MUSIC_NONE = "music_none"
     VIDEO_NONE = "video_none"
     VIDEO_DIFFUSION_SINGLE = "video_diffusion_single"
     VIDEO_FASTH3 = "video_fasth3"
@@ -380,6 +383,11 @@ async def _mock_generate(*args, **kwargs):
             assert len(received_sampling_params_list) == 3
             for i, expected in enumerate(AR_LIST_SAMPLING_PARAMS):
                 _assert_sampling_param_values(received_sampling_params_list[i], expected)
+        elif sampling_case.kind is SamplingKind.MUSIC_NONE:
+            assert len(received_sampling_params_list) == 2
+            assert prompt["prompt_token_ids"] == [101, 102, 103]
+            assert prompt["additional_information"]["max_audio_frames"] == [1512]
+            assert received_sampling_params_list[0].seed == 7
         elif sampling_case.kind in {SamplingKind.TTS_NONE, SamplingKind.TTS_DIFFUSION_SINGLE}:
             assert len(received_sampling_params_list) == 1
         elif sampling_case.kind is SamplingKind.VIDEO_NONE:
@@ -525,12 +533,17 @@ async def _mock_preprocess_chat(self, *args, **kwargs):
     # Need to mock AsyncOmni itself (not only its generate method) because
     # 1. The API layer uses its stage_list and stage_configs attributes
     # 2. Its __init__ method has slow side effects (model & config loading).
+    # These cases use the non-duplex mock engine without loading model configs.
+    mocker.patch("vllm_omni.entrypoints.openai.api_server._is_duplex_model", return_value=False)
     mock_async_omni_cls = mocker.patch("vllm_omni.entrypoints.openai.api_server.AsyncOmni")
     monkeypatch.setattr(
         "vllm_omni.entrypoints.openai.serving_chat.OmniOpenAIServingChat._preprocess_chat",
         _mock_preprocess_chat,
     )
 
+    if server_case.tokenizer is not None:
+        mocker.patch("transformers.AutoTokenizer.from_pretrained", return_value=server_case.tokenizer)
+
     mock_instance = mocker.AsyncMock(spec=RealAsyncOmni)
     mock_instance.generate = _build_mock_outputs(server_case.outputs, sampling_case, server_case)
 
@@ -558,7 +571,7 @@ async def _mock_preprocess_chat(self, *args, **kwargs):
     mock_instance.shutdown = mocker.MagicMock()
     mock_instance.get_vllm_config = mocker.AsyncMock(return_value=None)
     mock_instance.get_supported_tasks = mocker.AsyncMock(return_value=["generate"])
-    mock_instance.get_tokenizer = mocker.AsyncMock(return_value=None)
+    mock_instance.get_tokenizer = mocker.AsyncMock(return_value=server_case.tokenizer)
 
     mock_async_omni_cls.return_value = mock_instance
     yield mock_async_omni_cls
@@ -1081,3 +1094,66 @@ async def test_video_generation_node_minimax_h3_ref2va(
     assert isinstance(result, tuple)
     assert len(result) == 1
     assert isinstance(result[0], VideoInput)
+
+
+def _build_music_tokenizer():
+    # Checkpoint token IDs required by the API adapter's tokenizer validation.
+    special_token_ids = {
+        "<|im_start|>": 151644,
+        "<|im_end|>": 151645,
+        "<|audio_cfg|>": 151654,
+        "<|audio_start|>": 151669,
+        "<|audio_end|>": 151670,
+        "<|caption_start|>": 151671,
+        "<|caption_end|>": 151672,
+        "<|lyrics_start|>": 151673,
+        "<|lyrics_end|>": 151674,
+    }
+
+    def encode(prompt):
+        assert prompt == (
+            "<|im_start|><|caption_start|>Warm acoustic pop at 92 BPM"
+            "<|caption_end|><|lyrics_start|>[start]\n[verse]\nThe morning light"
+            "<|lyrics_end|><|im_end|><|audio_start|>"
+        )
+        return [101, 102, 103]
+
+    return SimpleNamespace(encode=encode, convert_tokens_to_ids=special_token_ids.get)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "server_case",
+    [
+        ServerCase(
+            served_model="MiniMaxAI/MiniMax-Music3",
+            stage_list=["llm", "llm"],
+            stage_configs=[
+                _make_stage_config("llm", model_stage="minimax_music3_ar"),
+                _make_stage_config("llm", model_stage="minimax_music3_acoustic"),
+            ],
+            outputs=[_build_audio_speech_output()],
+            tokenizer=_build_music_tokenizer(),
+        )
+    ],
+    indirect=True,
+)
+@pytest.mark.parametrize(
+    "sampling_case",
+    [SamplingCase(kind=SamplingKind.MUSIC_NONE, sampling_params=None)],
+    indirect=True,
+)
+async def test_music_generation_node_minimax_music3(api_server: str, sampling_case: SamplingCase):
+    result = await VLLMOmniGenerateMusic().generate(
+        url=api_server,
+        model="MiniMaxAI/MiniMax-Music3",
+        lyrics="[Verse]\nThe morning light",
+        instructions="Warm acoustic pop at 92 BPM",
+        max_duration_seconds=60.5,
+        seed=7,
+        response_format="wav",
+    )
+    assert isinstance(result, tuple)
+    assert len(result) == 1
+    assert result[0]["sample_rate"] == 24000
+    assert result[0]["waveform"].shape == (1, 1, 24000)

From c32aaeb2da49235689f1aa0cb4c4cc116616601e Mon Sep 17 00:00:00 2001
From: Aman <67479108+Bezdarnost@users.noreply.github.com>
Date: Thu, 17 Sep 2026 04:07:52 +0600
Subject: [PATCH 049/105] [Bugfix] Fix Qwen3-TTS word timestamps with async
 chunking (#7544)

Signed-off-by: bezdarnost <amanurumbekov@gmail.com>
---
 tests/config/test_forced_aligner_injection.py |  25 ++++
 tests/config/test_omni_config.py              |  34 +++++
 .../test_qwen3_tts_word_timestamps.py         | 137 ++++++++++++++++++
 .../test_async_omni_engine_stage_init.py      |  23 +++
 .../test_orchestrator_kv_sender_info.py       |  64 ++++++++
 tests/engine/test_output_processor.py         |  21 +++
 .../openai_api/test_serving_speech.py         |  46 ++++++
 .../openai_api/test_serving_speech_stream.py  |   4 +
 tests/helpers/assertions.py                   |  11 ++
 tests/helpers/client.py                       |   5 +
 tests/helpers/tests/test_assertions.py        |  23 +++
 vllm_omni/config/omni_config.py               |   7 +-
 vllm_omni/config/stage_config.py              |  34 ++++-
 .../omni_connectors/utils/config.py           |   4 +-
 vllm_omni/engine/omni_engine_base.py          |   5 +-
 .../entrypoints/openai/serving_speech.py      |  25 +++-
 .../openai/serving_speech_stream.py           |   1 +
 vllm_omni/utils/forced_aligner.py             |   3 +-
 18 files changed, 459 insertions(+), 13 deletions(-)
 create mode 100644 tests/e2e/online_serving/test_qwen3_tts_word_timestamps.py

diff --git a/tests/config/test_forced_aligner_injection.py b/tests/config/test_forced_aligner_injection.py
index 73a7bcda2ac..65c31522985 100644
--- a/tests/config/test_forced_aligner_injection.py
+++ b/tests/config/test_forced_aligner_injection.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 import pytest
 
 import vllm_omni.config.pipeline_registry  # noqa: F401  (populate registry)
@@ -69,3 +72,25 @@ def test_inject_noop_without_forced_aligner():
 
     assert ext_pipeline is pipeline
     assert len(ext_deploy.stages) == 0
+
+
+@pytest.mark.parametrize("async_chunk", [True, False])
+@pytest.mark.parametrize("cli_async_chunk", [None, True, False])
+def test_aligner_uses_completed_audio_without_disabling_upstream_chunks(async_chunk, cli_async_chunk):
+    from vllm_omni.config.config_factory import StageConfigFactory
+
+    pipeline = _PIPELINE_REGISTRY["qwen3_tts"]
+    deploy = DeployConfig(async_chunk=async_chunk)
+    resolution = StageConfigFactory._resolve_legacy_from_registry(
+        pipeline,
+        {"forced_aligner": "/models/Qwen3-ForcedAligner-0.6B", "async_chunk": cli_async_chunk},
+        user_deploy_config=deploy,
+    )
+    stages = [stage.to_omegaconf() for stage in resolution.stage_configs]
+    expected_async = async_chunk if cli_async_chunk is None else cli_async_chunk
+    assert len(stages) == 3
+    assert [stage.engine_args.async_chunk for stage in stages] == [expected_async, expected_async, False]
+    assert stages[2].custom_process_input_func.endswith("code2wav2aligner")
+    assert stages[2].engine_args.runner == "pooling"
+    assert len(pipeline.stages) == 2
+    assert deploy.stages == []
diff --git a/tests/config/test_omni_config.py b/tests/config/test_omni_config.py
index a8a2056b688..e0a5ad9b04d 100644
--- a/tests/config/test_omni_config.py
+++ b/tests/config/test_omni_config.py
@@ -1705,3 +1705,37 @@ def test_compact_offload_config_is_validated_during_projection():
                 "components": ["dit"],
             }
         )
+
+
+@pytest.mark.parametrize("pipeline_async", [True, False])
+@pytest.mark.parametrize("stage_async", [None, False, True])
+def test_stage_async_chunk_opt_out_matches_legacy_config(pipeline_async, stage_async):
+    pipeline = _resolve_pipeline_or_skip("qwen3_tts")
+    deploy = DeployConfig(
+        async_chunk=pipeline_async,
+        stages=[StageDeployConfig(stage_id=i, async_chunk=stage_async) for i in (0, 1)],
+    )
+    config = VllmOmniConfig.from_pipeline_config(pipeline, user_deploy_config=deploy)
+    legacy = merge_pipeline_deploy(pipeline, deploy)
+    expected = pipeline_async and stage_async is not False
+    assert config.stage_by_id(0).connector_config.async_chunk is expected
+    assert config.stage_by_id(1).connector_config.async_chunk is expected
+    assert legacy[1].yaml_engine_args["async_chunk"] is expected
+    assert config.stage_by_id(1).custom_process_input_func == legacy[1].custom_process_input_func
+    if not expected:
+        assert config.stage_by_id(1).custom_process_input_func.endswith("talker2code2wav_token_only")
+
+
+@pytest.mark.parametrize("disabled_stage", [0, 1])
+@pytest.mark.parametrize("builder", [merge_pipeline_deploy, VllmOmniConfig.from_pipeline_config])
+def test_async_chunk_rejects_mismatched_connector_edge(disabled_stage, builder):
+    pipeline = _resolve_pipeline_or_skip("qwen3_tts")
+    deploy = DeployConfig(
+        async_chunk=True,
+        stages=[StageDeployConfig(stage_id=disabled_stage, async_chunk=False)],
+    )
+    with pytest.raises(ValueError, match="incompatible async_chunk settings on connector edge 0 -> 1"):
+        if builder is merge_pipeline_deploy:
+            builder(pipeline, deploy)
+        else:
+            builder(pipeline, user_deploy_config=deploy)
diff --git a/tests/e2e/online_serving/test_qwen3_tts_word_timestamps.py b/tests/e2e/online_serving/test_qwen3_tts_word_timestamps.py
new file mode 100644
index 00000000000..d8bd6302ec0
--- /dev/null
+++ b/tests/e2e/online_serving/test_qwen3_tts_word_timestamps.py
@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import base64
+import json
+
+import pytest
+from websockets.sync.client import connect
+
+from tests.helpers.mark import hardware_test
+from tests.helpers.runtime import OmniServerParams
+from tests.helpers.stage_config import get_deploy_config_path, modify_stage_config
+
+pytestmark = [pytest.mark.slow, pytest.mark.tts]
+
+_DEPLOY = modify_stage_config(
+    get_deploy_config_path("qwen3_tts.yaml"),
+    updates={
+        "stages": {
+            0: {
+                "max_num_seqs": 4,
+                "max_num_batched_tokens": 2048,
+                "max_model_len": 2048,
+                "gpu_memory_utilization": 0.45,
+                "compilation_config.cudagraph_capture_sizes": [1, 2, 4],
+                "default_sampling_params.max_tokens": 256,
+            },
+            1: {
+                "max_num_seqs": 4,
+                "max_num_batched_tokens": 4096,
+                "max_model_len": 8192,
+                "gpu_memory_utilization": 0.15,
+            },
+        }
+    },
+)
+_PARAMS = [
+    OmniServerParams(
+        model="Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
+        stage_config_path=_DEPLOY,
+        server_args=[
+            "--trust-remote-code",
+            "--forced-aligner",
+            "Qwen/Qwen3-ForcedAligner-0.6B",
+            "--kv-cache-memory-bytes",
+            str(512 * 1024**2),
+            "--max-num-seqs",
+            "4",
+            "--max-num-batched-tokens",
+            "2048",
+        ],
+    )
+]
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", _PARAMS, indirect=True)
+def test_async_chunk_word_timestamps(omni_server, online_client):
+    online_client.send_audio_speech_request(
+        {
+            "model": omni_server.model,
+            "input": "The weather is nice today, perfect for a walk in the park.",
+            "voice": "vivian",
+            "language": "English",
+            "word_timestamps": True,
+            "response_format": "wav",
+            "min_audio_bytes": 40_000,
+            "timeout": 120,
+        },
+        request_num=2,
+    )
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", _PARAMS, indirect=True)
+def test_async_chunk_speech_without_timestamps(omni_server, online_client):
+    online_client.send_audio_speech_request(
+        {
+            "model": omni_server.model,
+            "input": "The weather is nice today, perfect for a walk in the park.",
+            "voice": "vivian",
+            "language": "English",
+            "stream": True,
+            "stream_format": "audio",
+            "response_format": "wav",
+            "min_audio_bytes": 40_000,
+            "timeout": 120,
+        }
+    )
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.parametrize("omni_server", _PARAMS, indirect=True)
+def test_async_chunk_streaming_word_timestamps(omni_server):
+    text = "The weather is nice today, perfect for a walk in the park."
+    chunks = []
+    timestamps = None
+    with connect(f"ws://{omni_server.host}:{omni_server.port}/v1/audio/speech/stream") as ws:
+        ws.send(
+            json.dumps(
+                {
+                    "type": "session.config",
+                    "voice": "vivian",
+                    "language": "English",
+                    "stream_audio": True,
+                    "response_format": "pcm",
+                    "word_timestamps": True,
+                }
+            )
+        )
+        ws.send(json.dumps({"type": "input.text", "text": text}))
+        ws.send(json.dumps({"type": "input.done"}))
+        while True:
+            message = json.loads(ws.recv(timeout=120))
+            assert message["type"] != "error", message
+            if message["type"] == "audio.chunk":
+                if message["audio_b64"]:
+                    chunks.append(base64.b64decode(message["audio_b64"]))
+                if message["timestamps"] is not None:
+                    timestamps = message["timestamps"]
+                    sample_rate = message["sample_rate"]
+            elif message["type"] == "audio.done":
+                assert not message["error"], message
+                assert message["total_bytes"] == sum(map(len, chunks))
+            elif message["type"] == "session.done":
+                break
+
+    assert len(chunks) > 1
+    assert timestamps
+    assert len(timestamps) == len(text.split())
+    duration_ms = sum(map(len, chunks)) / (2 * sample_rate) * 1000
+    final_chunk_ms = len(chunks[-1]) / (2 * sample_rate) * 1000
+    assert timestamps[-1]["end_ms"] > max(duration_ms / 2, final_chunk_ms)
+    previous_end = 0
+    for timestamp in timestamps:
+        assert previous_end <= timestamp["start_ms"] <= timestamp["end_ms"] <= duration_ms + 1
+        previous_end = timestamp["end_ms"]
diff --git a/tests/engine/test_async_omni_engine_stage_init.py b/tests/engine/test_async_omni_engine_stage_init.py
index f052f7e9db8..15d31cbbcd3 100644
--- a/tests/engine/test_async_omni_engine_stage_init.py
+++ b/tests/engine/test_async_omni_engine_stage_init.py
@@ -10,6 +10,7 @@
 import types
 
 import pytest
+from omegaconf import OmegaConf
 
 from vllm_omni.diffusion.data import AttentionConfig
 from vllm_omni.engine import omni_engine_base as async_omni_engine_module
@@ -1829,3 +1830,25 @@ def test_port_from_zmq_address_parsing():
     assert _port_from_zmq_address(None) is None
     assert _port_from_zmq_address("ipc:///tmp/sock") is None
     assert _port_from_zmq_address("tcp://host:not-a-port") is None
+
+
+@pytest.mark.parametrize(
+    "stage_modes,expected", [([False, True, True], True), ([False, False], False), ([True, False], True)]
+)
+def test_engine_async_chunk_includes_downstream_stages(monkeypatch, stage_modes, expected):
+    engine = object.__new__(AsyncOmniEngine)
+    stages = [OmegaConf.create({"engine_args": {"async_chunk": mode}}) for mode in stage_modes]
+    monkeypatch.setattr(async_omni_engine_module.StageConfigFactory, "get_pipeline_config", lambda *a, **k: None)
+    monkeypatch.setattr(engine, "_resolve_stage_configs", lambda *a, **k: (None, stages))
+    monkeypatch.setattr(engine, "_set_pipeline_runtime_config", lambda *a: None)
+
+    class ConfigResolvedError(Exception):
+        pass
+
+    def stop_before_queues(*args, **kwargs):
+        raise ConfigResolvedError
+
+    monkeypatch.setattr(async_omni_engine_module.janus, "Queue", stop_before_queues)
+    with pytest.raises(ConfigResolvedError):
+        engine.__init__("test-model")
+    assert engine.async_chunk is expected
diff --git a/tests/engine/test_orchestrator_kv_sender_info.py b/tests/engine/test_orchestrator_kv_sender_info.py
index ca2a26b7031..25e662d27a1 100644
--- a/tests/engine/test_orchestrator_kv_sender_info.py
+++ b/tests/engine/test_orchestrator_kv_sender_info.py
@@ -414,3 +414,67 @@ async def run():
 
     assert all(isinstance(request, OmniEngineCoreRequest) for request in submitted.values())
     assert {key: request.payload_sender_info for key, request in submitted.items()} == endpoints
+
+
+@pytest.mark.asyncio
+async def test_async_pipeline_defers_sync_stage_until_audio_finishes(mocker):
+    from vllm import PoolingParams, RequestOutput
+    from vllm.config import VllmConfig
+
+    from vllm_omni.config.model import OmniModelConfig
+    from vllm_omni.engine import OmniEngineCoreRequest
+
+    orchestrator = object.__new__(Orchestrator)
+    orchestrator.async_chunk = True
+    orchestrator._pd_pair = None
+    orchestrator._cfg_tracker = CfgCompanionTracker()
+    orchestrator.output_async_queue = asyncio.Queue()
+    orchestrator._duplex_output_decision = lambda *args: None
+    orchestrator._is_duplex_session_request = lambda state: False
+    orchestrator._forward_to_next_stage = mocker.AsyncMock()
+    orchestrator._cleanup_request_ids = mocker.AsyncMock()
+    # A sender stage stands in for Code2Wav, whose audio is also a final output.
+    audio_pool = _build_sender_pool(0, {})
+    audio_pool.stage_client.final_output = True
+    aligner = _DummyDiffusionStage()
+    aligner_pool = StagePool(
+        1,
+        aligner,
+        stage_vllm_config=mocker.Mock(
+            spec=VllmConfig, model_config=mocker.Mock(spec=OmniModelConfig, async_chunk=False)
+        ),
+    )
+    orchestrator.stage_pools = [audio_pool, aligner_pool]
+    state = OrchestratorRequestState(
+        request_id="aligned",
+        prompt={"additional_information": {"text": ["Hello world"]}},
+        sampling_params_list=[SamplingParams(), PoolingParams(task="token_classify")],
+        final_stage_id=1,
+        final_output_stage_ids={0, 1},
+    )
+
+    await orchestrator._prewarm_async_chunk_stages(
+        "aligned", mocker.Mock(spec=OmniEngineCoreRequest, prompt_token_ids=[1, 2]), state
+    )
+    assert aligner.calls == []
+    assert 1 not in state.stage_submit_ts
+
+    output = RequestOutput("aligned", None, [1, 2], None, [], False)
+    await orchestrator._route_output(0, 0, output, state, None)
+    orchestrator._forward_to_next_stage.assert_not_awaited()
+    output.finished = True
+    await orchestrator._route_output(0, 0, output, state, None)
+    orchestrator._forward_to_next_stage.assert_awaited_once_with(
+        "aligned",
+        0,
+        output,
+        state,
+        src_replica_id=0,
+        is_streaming_session=False,
+        is_final_update=False,
+    )
+    orchestrator._cleanup_request_ids.assert_not_awaited()
+    await orchestrator._route_output(1, 0, output, state, None)
+    orchestrator._cleanup_request_ids.assert_awaited_once()
+    messages = [orchestrator.output_async_queue.get_nowait() for _ in range(3)]
+    assert [message.finished for message in messages] == [False, False, True]
diff --git a/tests/engine/test_output_processor.py b/tests/engine/test_output_processor.py
index 8618061d8ca..419be93059d 100644
--- a/tests/engine/test_output_processor.py
+++ b/tests/engine/test_output_processor.py
@@ -888,3 +888,24 @@ def test_abort_snapshot_leaves_state_until_commit():
     assert "0_parent" not in processor.request_states
     assert "parent" not in processor.parent_requests
     assert "parent" not in processor.external_req_ids
+
+
+def test_cumulative_audio_terminal_output_supplies_full_aligner_waveform():
+    from vllm_omni.model_executor.stage_input_processors.forced_aligner import code2wav2aligner
+
+    state = _make_state(RequestOutputKind.CUMULATIVE)
+    for index, count in enumerate((800, 1200, 400)):
+        state.add_multimodal_tensor(torch.full((1, count), float(index)), mm_type=AUDIO)
+        output = state.make_request_output([index], None, FinishReason.STOP if index == 2 else None, None)
+        assert output is not None
+        if index < 2:
+            assert code2wav2aligner([output], {}) == []
+    prompt = {"additional_information": {"text": ["Hello world"], "language": ["English"]}}
+    aligned = code2wav2aligner([output], prompt)[0]
+    waveform, sr = aligned["multi_modal_data"]["audio"]
+    assert sr == 24000
+    assert waveform.shape == (2400,)
+    assert (waveform[:800] == 0).all()
+    assert (waveform[800:2000] == 1).all()
+    assert (waveform[2000:] == 2).all()
+    assert aligned["additional_information"]["aligner_audio_duration_ms"] == [100.0]
diff --git a/tests/entrypoints/openai_api/test_serving_speech.py b/tests/entrypoints/openai_api/test_serving_speech.py
index f910c68af0c..f8dfaafb608 100644
--- a/tests/entrypoints/openai_api/test_serving_speech.py
+++ b/tests/entrypoints/openai_api/test_serving_speech.py
@@ -5212,6 +5212,52 @@ def apply_sampling_overrides(self, sampling_params_list, request, prompt, reques
             for call in log_info.call_args_list
         )
 
+    @pytest.mark.parametrize("word_timestamps", [False, True])
+    def test_streaming_timestamps_retain_complete_audio(self, qwen3_tts_server, mocker, word_timestamps):
+        from vllm import SamplingParams
+        from vllm.sampling_params import RequestOutputKind
+
+        defaults = [SamplingParams(), SamplingParams()]
+        qwen3_tts_server.engine_client.default_sampling_params_list = defaults
+        qwen3_tts_server._adapter.validate = mocker.MagicMock(return_value=None)
+        qwen3_tts_server._adapter._build_tts_params = mocker.MagicMock(
+            return_value={"text": ["hello"], "task_type": ["CustomVoice"], "speaker": ["Vivian"]}
+        )
+        qwen3_tts_server._adapter._estimate_prompt_len_async = mocker.AsyncMock(return_value=512)
+        request = OpenAICreateSpeechRequest(
+            input="hello", stream=True, response_format="pcm", word_timestamps=word_timestamps
+        )
+        asyncio.run(qwen3_tts_server._prepare_speech_generation(request))
+
+        params = qwen3_tts_server.engine_client.generate.call_args.kwargs["sampling_params_list"]
+        expected = RequestOutputKind.CUMULATIVE if word_timestamps else RequestOutputKind.DELTA
+        assert all(sp.output_kind == expected for sp in params)
+        assert all(sp.output_kind == RequestOutputKind.CUMULATIVE for sp in defaults)
+        assert all(sp is not original for sp, original in zip(params, defaults))
+
+    @pytest.mark.asyncio
+    async def test_cumulative_timestamp_audio_emits_each_sample_once(self, qwen3_tts_server):
+        audio = torch.linspace(-0.5, 0.5, 2400)
+
+        async def cumulative_generator():
+            for end in (800, 1600, 2400, 2400):
+                yield OmniRequestOutput(
+                    request_id="req-cumulative",
+                    final_output_type="audio",
+                    _multimodal_output={"audio": audio[:end], "sr": 24000},
+                )
+
+        chunks = [
+            chunk
+            async for chunk in qwen3_tts_server._generate_pcm_chunks(
+                cumulative_generator(), "req-cumulative", cumulative_audio=True
+            )
+        ]
+        assert len(chunks) == 3
+        assert len(b"".join(chunks)) == 2400 * 2
+        decoded = np.frombuffer(b"".join(chunks), dtype=np.int16)
+        assert np.all(np.diff(decoded.astype(np.int32)) >= 0)
+
     def test_prepare_speech_generation_treats_sse_as_streaming(self, qwen3_tts_server, mocker: MockerFixture):
         """stream_format=sse should request delta-style multimodal outputs."""
         qwen3_tts_server._adapter.validate = mocker.MagicMock(return_value=None)
diff --git a/tests/entrypoints/openai_api/test_serving_speech_stream.py b/tests/entrypoints/openai_api/test_serving_speech_stream.py
index 39c9e66d950..1d34b6e0b13 100644
--- a/tests/entrypoints/openai_api/test_serving_speech_stream.py
+++ b/tests/entrypoints/openai_api/test_serving_speech_stream.py
@@ -56,6 +56,7 @@ async def mock_generate_pcm_chunks(
             include_sample_rate=False,
             tts_params=None,
             collect=None,
+            cumulative_audio=False,
         ):
             for chunk in (b"\x01\x02", b"\x03\x04\x05"):
                 yield (chunk, 24000) if include_sample_rate else chunk
@@ -386,9 +387,11 @@ async def mock_generate_pcm_chunks(
             include_sample_rate=False,
             tts_params=None,
             collect=None,
+            cumulative_audio=False,
         ):
             assert request_start_s is not None
             assert request_arrival_ts is not None
+            assert cumulative_audio is True
             for chunk in (first_chunk, second_chunk):
                 yield (chunk, 1000) if include_sample_rate else chunk
             if collect is not None:
@@ -480,6 +483,7 @@ async def mock_generate_pcm_chunks(
             include_sample_rate=False,
             tts_params=None,
             collect=None,
+            cumulative_audio=False,
         ):
             chunk = b"\x01" * 1000
             yield (chunk, 1000) if include_sample_rate else chunk
diff --git a/tests/helpers/assertions.py b/tests/helpers/assertions.py
index 7dc7a6ab302..5df9dfa7e7d 100644
--- a/tests/helpers/assertions.py
+++ b/tests/helpers/assertions.py
@@ -955,6 +955,17 @@ def assert_audio_speech_response(response: Any, request_config: dict[str, Any],
     """
     assert response.success, "The request failed."
 
+    if request_config.get("word_timestamps"):
+        timestamps = response.word_timestamps
+        assert isinstance(timestamps, list) and timestamps, "Expected nonempty X-Word-Timestamps"
+        previous_start = 0
+        for timestamp in timestamps:
+            assert isinstance(timestamp["word"], str) and timestamp["word"]
+            start, end = timestamp["start_ms"], timestamp["end_ms"]
+            assert isinstance(start, int) and isinstance(end, int)
+            assert previous_start <= start <= end
+            previous_start = start
+
     # Optional floor on decoded audio size (models with very short clips may use a lower value).
     min_audio = request_config.get("min_audio_bytes")
     if min_audio is not None:
diff --git a/tests/helpers/client.py b/tests/helpers/client.py
index ed5158b92de..e1042321a30 100644
--- a/tests/helpers/client.py
+++ b/tests/helpers/client.py
@@ -102,6 +102,7 @@ class OmniResponse:
     audio_content: str | None = None
     audio_format: str | None = None
     audio_bytes: bytes | None = None
+    word_timestamps: list[dict[str, str | int]] | None = None
     #: End-to-end wall time in **seconds** (``perf_counter`` delta), from just before the
     #: OpenAI client call through response parsing and local post-process (e.g. audio decode).
     e2e_latency: float | None = None
@@ -1419,6 +1420,9 @@ def _process_non_stream_audio_speech_response(
             result.success = True
             result.audio_format = getattr(response, "response", None)
             if result.audio_format is not None:
+                timestamps = result.audio_format.headers.get("X-Word-Timestamps")
+                if timestamps is not None:
+                    result.word_timestamps = json.loads(timestamps)
                 result.audio_format = result.audio_format.headers.get("content-type", "")
 
         except Exception as e:
@@ -1472,6 +1476,7 @@ def send_audio_speech_request(self, request_config: dict[str, Any], request_num:
             "extra_params",
             "stream_format",
             "x_vector_only_mode",
+            "word_timestamps",
         ):
             if key in request_config:
                 extra_body[key] = request_config[key]
diff --git a/tests/helpers/tests/test_assertions.py b/tests/helpers/tests/test_assertions.py
index e9b1a771c25..55956a6f2e3 100644
--- a/tests/helpers/tests/test_assertions.py
+++ b/tests/helpers/tests/test_assertions.py
@@ -173,3 +173,26 @@ def test_bounded_tail_allows_ratio_bound_for_long_answers():
     # Twenty expected words allow up to max(2, ceil(0.2 * 20)) = 4 tail words.
     assert assertions._transcript_has_bounded_tail(four_word_tail, expected)
     assert not assertions._transcript_has_bounded_tail(five_word_tail, expected)
+
+
+def test_speech_timestamp_header_is_required_and_decoded():
+    import time
+
+    import httpx
+    from openai._legacy_response import HttpxBinaryResponseContent
+
+    from tests.helpers.client import OnlineOmniClient
+
+    client = object.__new__(OnlineOmniClient)
+    request = {"word_timestamps": True}
+    for headers in ({}, {"X-Word-Timestamps": '[{"word":"Hello","start_ms":0,"end_ms":300}]'}):
+        response = client._process_non_stream_audio_speech_response(
+            HttpxBinaryResponseContent(httpx.Response(200, content=b"audio", headers=headers)),
+            wall_start=time.perf_counter(),
+        )
+        if headers:
+            assert_audio_speech_response(response, request)
+            assert response.word_timestamps == [{"word": "Hello", "start_ms": 0, "end_ms": 300}]
+        else:
+            with pytest.raises(AssertionError, match="X-Word-Timestamps"):
+                assert_audio_speech_response(response, request)
diff --git a/vllm_omni/config/omni_config.py b/vllm_omni/config/omni_config.py
index d86a3216ff2..56b40b8367c 100644
--- a/vllm_omni/config/omni_config.py
+++ b/vllm_omni/config/omni_config.py
@@ -50,6 +50,8 @@
     merge_sampling_constraints,
     normalize_pipeline_cli_overrides,
     reconcile_diffusion_attention_overrides,
+    resolve_stage_async_chunk,
+    validate_stage_async_chunk_edges,
 )
 from vllm_omni.diffusion.diffusion_kv.config import DiffusionKVCacheMode
 
@@ -1520,7 +1522,7 @@ def _build_common_stage_config_kwargs(
     *,
     model: str | None,
 ) -> tuple[dict[str, Any], str | None, str | None]:
-    input_proc, next_stage_proc = _select_processor_funcs(topology, bool(deploy.async_chunk))
+    input_proc, next_stage_proc = _select_processor_funcs(topology, resolve_stage_async_chunk(deploy, stage_deploy))
     quantization_config = _build_quantization_config(deploy, engine.quantization)
     parallel_config = _build_parallel_config(deploy, engine.parallel, parallel_config_cls)
 
@@ -1835,7 +1837,7 @@ def _build_connector_config(
     output_connectors = stage_deploy.output_connectors if stage_deploy is not None else None
     input_connectors = stage_deploy.input_connectors if stage_deploy is not None else None
     return cast(Any, OmniStageConnectorConfig)(
-        async_chunk=bool(deploy.async_chunk),
+        async_chunk=resolve_stage_async_chunk(deploy, stage_deploy),
         omni_kv_config=_copy_value(engine.get("omni_kv_config")),
         output_connectors=_copy_value(output_connectors) if output_connectors else None,
         input_connectors=_copy_value(input_connectors) if input_connectors else None,
@@ -1966,6 +1968,7 @@ def from_pipeline_config(
         if len(pipeline_cfg.stages) <= 1:
             deploy.async_chunk = False
         _validate_async_chunk_support(pipeline_cfg, deploy)
+        validate_stage_async_chunk_edges(pipeline_cfg, deploy)
         deploy_by_id = {stage.stage_id: stage for stage in deploy.stages}
         model = cli_overrides.get("model")
 
diff --git a/vllm_omni/config/stage_config.py b/vllm_omni/config/stage_config.py
index c96f514e81a..6af65b8ed90 100644
--- a/vllm_omni/config/stage_config.py
+++ b/vllm_omni/config/stage_config.py
@@ -390,6 +390,9 @@ class StageDeployConfig:
     num_replicas: int = 1
     env: dict[str, Any] | None = None
 
+    # False opts this stage out of pipeline-wide async chunking.
+    async_chunk: bool | None = None
+
     # Inter-stage connector wiring and request defaults.
     output_connectors: dict[str, str] | None = None
     input_connectors: dict[str, str] | None = None
@@ -587,6 +590,7 @@ class DeployConfig:
 
 _STAGE_RESERVED_KEYS = frozenset(
     {
+        "async_chunk",
         "stage_id",
         "devices",
         "num_replicas",
@@ -645,6 +649,7 @@ def _parse_stage_deploy(stage_data: dict[str, Any]) -> StageDeployConfig:
         if name in flat_args:
             kwargs[name] = flat_args.pop(name)
 
+    kwargs["async_chunk"] = stage_data.get("async_chunk")
     kwargs["output_connectors"] = stage_data.get("output_connectors")
     kwargs["input_connectors"] = stage_data.get("input_connectors")
     kwargs["default_sampling_params"] = stage_data.get("default_sampling_params")
@@ -888,6 +893,28 @@ def _resolve_execution_mode(
     return _EXECUTION_TYPE_TO_STAGE_WORKER.get(execution_type, (StageType.LLM, None))
 
 
+def resolve_stage_async_chunk(deploy: DeployConfig, stage: StageDeployConfig | None) -> bool:
+    return bool(deploy.async_chunk and (stage is None or stage.async_chunk is not False))
+
+
+def validate_stage_async_chunk_edges(pipeline: PipelineConfig, deploy: DeployConfig) -> None:
+    stages = {stage.stage_id: stage for stage in pipeline.stages}
+    deploy_by_id = {stage.stage_id: stage for stage in deploy.stages}
+    for consumer in pipeline.stages:
+        for source_id in consumer.input_sources:
+            producer = stages[source_id]
+            if not producer.async_chunk_process_next_stage_input_func:
+                continue
+            producer_async = resolve_stage_async_chunk(deploy, deploy_by_id.get(source_id))
+            consumer_async = resolve_stage_async_chunk(deploy, deploy_by_id.get(consumer.stage_id))
+            if producer_async != consumer_async:
+                raise ValueError(
+                    f"Pipeline {pipeline.model_type!r} has incompatible async_chunk settings on "
+                    f"connector edge {source_id} -> {consumer.stage_id}. "
+                    "Set the same async_chunk mode on both stages or disable pipeline-wide async_chunk."
+                )
+
+
 def _select_processor_funcs(
     ps: StagePipelineConfig,
     async_chunk: bool,
@@ -964,9 +991,7 @@ def _build_engine_args(
                 continue
             engine_args[k] = v
         engine_args.update(ds.engine_extras)
-    # Materialize the resolved pipeline-wide async_chunk value into every
-    # stage so explicit False overrides do not get lost downstream.
-    engine_args["async_chunk"] = bool(deploy.async_chunk)
+    engine_args["async_chunk"] = resolve_stage_async_chunk(deploy, ds)
     engine_args["session_mode"] = deploy.session_mode
     if deploy.session_mode == "duplex":
         # The engine admission limit is also the authoritative capacity for
@@ -1060,11 +1085,12 @@ def merge_pipeline_deploy(
             "Either set async_chunk=False or implement an async-chunk producer on the pipeline."
         )
 
+    validate_stage_async_chunk_edges(pipeline, deploy)
     result: list[StageConfig] = []
     for ps in pipeline.stages:
         ds = deploy_by_id.get(ps.stage_id)
         stage_type, worker_type = _resolve_execution_mode(ps.execution_type)
-        input_proc, next_stage_proc = _select_processor_funcs(ps, deploy.async_chunk)
+        input_proc, next_stage_proc = _select_processor_funcs(ps, resolve_stage_async_chunk(deploy, ds))
         engine_args = _build_engine_args(ps, ds, pipeline, deploy, next_stage_proc)
         # Downstream stages may share a multimodal wrapper class without owning
         # an encoder. Do not make vLLM profile dummy multimodal inputs for them.
diff --git a/vllm_omni/distributed/omni_connectors/utils/config.py b/vllm_omni/distributed/omni_connectors/utils/config.py
index 176a8bf6961..a646a3a3090 100644
--- a/vllm_omni/distributed/omni_connectors/utils/config.py
+++ b/vllm_omni/distributed/omni_connectors/utils/config.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from dataclasses import dataclass, field
 from typing import Any
@@ -33,7 +33,7 @@ def get_stage_connector_role(model_config: Any) -> str | None:
 
 def stage_receives_chunks(model_config: Any) -> bool:
     """Whether connector chunks, rather than the orchestrator, feed a stage."""
-    return get_stage_connector_role(model_config) != "sender"
+    return bool(getattr(model_config, "async_chunk", True)) and get_stage_connector_role(model_config) != "sender"
 
 
 def stage_sends_async_output(model_config: Any) -> bool:
diff --git a/vllm_omni/engine/omni_engine_base.py b/vllm_omni/engine/omni_engine_base.py
index 87ef8d5e6e6..85310e9ddd5 100644
--- a/vllm_omni/engine/omni_engine_base.py
+++ b/vllm_omni/engine/omni_engine_base.py
@@ -271,8 +271,9 @@ def __init__(
             )
 
         self.num_stages = len(self.stage_configs)
-        stage0_args = getattr(self.stage_configs[0], "engine_args", None) if self.num_stages > 0 else None
-        self.async_chunk = bool(getattr(stage0_args, "async_chunk", False))
+        self.async_chunk = any(
+            bool(getattr(getattr(stage, "engine_args", None), "async_chunk", False)) for stage in self.stage_configs
+        )
         self.stage_pools: list[StagePool] = []
         self.stage_clients: list[StageClient] = []  # logical-stage view for external readers
         self.input_processor: InputProcessor | None = None
diff --git a/vllm_omni/entrypoints/openai/serving_speech.py b/vllm_omni/entrypoints/openai/serving_speech.py
index f54ca3e2850..80f357651f2 100644
--- a/vllm_omni/entrypoints/openai/serving_speech.py
+++ b/vllm_omni/entrypoints/openai/serving_speech.py
@@ -32,6 +32,7 @@
 from vllm.entrypoints.serve.engine.protocol import ErrorResponse
 from vllm.logger import init_logger
 from vllm.multimodal.media import MediaConnector
+from vllm.sampling_params import RequestOutputKind, SamplingParams
 from vllm.utils import random_uuid
 from vllm.v1.engine.exceptions import EngineDeadError, EngineGenerateError
 
@@ -1444,14 +1445,15 @@ async def _generate_audio_chunks(
         tts_params: dict[str, Any] | None = None,
         collect: dict | None = None,
         target_sample_rate: int | None = None,
+        cumulative_audio: bool = False,
     ):
         """Generate audio chunks for streaming response.
 
         Handles two audio output modes from the engine:
         - Cumulative mode (list): Engine returns growing list of chunks;
         we emit only the new tail on each iteration.
-        - Per-step mode (tensor): Engine returns single tensor per iteration;
-        we emit it directly.
+        - Tensor mode: Emit each tensor directly, or only its new samples when
+        cumulative_audio is set for requests that retain audio for alignment.
 
         Args:
             generator: Async generator from the engine
@@ -1462,6 +1464,7 @@ async def _generate_audio_chunks(
             Raw audio bytes for each chunk (with WAV header for first chunk if wav format)
         """
         prev_count = 0
+        emitted_samples = 0
         sample_rate_val = 24000
         first_chunk = True
         first_audio_chunk_s: float | None = None
@@ -1563,6 +1566,12 @@ def record_audio_chunk(audio_bytes: bytes, chunk_np: np.ndarray, result: Any) ->
                     )
                     if chunk_np.ndim > 1:
                         chunk_np = chunk_np.squeeze()
+                    if cumulative_audio and not isinstance(audio_val, list):
+                        total_samples = chunk_np.shape[-1]
+                        chunk_np = chunk_np[..., emitted_samples:]
+                        emitted_samples = total_samples
+                        if chunk_np.size == 0:
+                            continue
                     if resampler is not None:
                         chunk_np = resampler.process(chunk_np)
                         if chunk_np.size == 0:
@@ -1957,6 +1966,15 @@ async def _prepare_speech_generation(
             from vllm_omni.model_executor.stage_input_processors.forced_aligner import TIMESTAMPS_MODALITY
 
             output_modalities.append(TIMESTAMPS_MODALITY)
+            if is_streaming_request:
+                # The aligner consumes the terminal waveform, so retain earlier
+                # audio chunks instead of draining them after each DELTA output.
+                sampling_params_list = [
+                    sp.clone() if isinstance(sp, SamplingParams) else sp for sp in sampling_params_list
+                ]
+                for sp in sampling_params_list:
+                    if isinstance(sp, SamplingParams):
+                        sp.output_kind = RequestOutputKind.CUMULATIVE
 
         generator = self.engine_client.generate(
             prompt=prompt,
@@ -1990,6 +2008,7 @@ async def _generate_pcm_chunks(
         tts_params: dict[str, Any] | None = None,
         collect: dict | None = None,
         target_sample_rate: int | None = None,
+        cumulative_audio: bool = False,
     ):
         """Yield raw PCM byte chunks from the engine generator.
 
@@ -2009,6 +2028,7 @@ async def _generate_pcm_chunks(
                 tts_params=tts_params,
                 collect=collect,
                 target_sample_rate=target_sample_rate,
+                cumulative_audio=cumulative_audio,
             )
         ) as chunks:
             async for chunk in chunks:
@@ -2024,6 +2044,7 @@ async def _iter_pcm_audio_bytes(self, request: OpenAICreateSpeechRequest):
                     request_id,
                     tts_params=tts_params,
                     target_sample_rate=request.sample_rate,
+                    cumulative_audio=request.word_timestamps,
                 )
             ) as chunks:
                 async for chunk in chunks:
diff --git a/vllm_omni/entrypoints/openai/serving_speech_stream.py b/vllm_omni/entrypoints/openai/serving_speech_stream.py
index ceeb208c92d..45bdd4e90d2 100644
--- a/vllm_omni/entrypoints/openai/serving_speech_stream.py
+++ b/vllm_omni/entrypoints/openai/serving_speech_stream.py
@@ -483,6 +483,7 @@ async def send_chunk(
                 include_sample_rate=True,
                 tts_params=tts_params,
                 collect=collect,
+                cumulative_audio=True,
             )
         ) as stream:
             async for chunk, chunk_sample_rate in stream:
diff --git a/vllm_omni/utils/forced_aligner.py b/vllm_omni/utils/forced_aligner.py
index 3b578ee5164..e6dcecb57e1 100644
--- a/vllm_omni/utils/forced_aligner.py
+++ b/vllm_omni/utils/forced_aligner.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Forced-aligner config + word-timestamp decoding for TTS.
 
 The aligner runs as a pooling stage appended to the pipeline by
@@ -153,6 +153,7 @@ def inject_forced_aligner_stage(
         # Pooling is one-shot -> sync AR scheduler (the async one assumes
         # token-by-token generation).
         async_scheduling=False,
+        async_chunk=False,
     )
     deploy = replace(deploy, stages=list(deploy.stages) + [aligner_ds])
     logger.info("[stage_init] Injected forced-aligner stage %d (model=%s)", new_id, fa.model)

From c8b3a17bd3be56ebef509987498907bcbfc0b660 Mon Sep 17 00:00:00 2001
From: Linze Shi <linzeshi0@gmail.com>
Date: Wed, 16 Sep 2026 17:29:57 -0700
Subject: [PATCH 050/105] [Frontend] Allow explicit turn-based serving (#7675)

Signed-off-by: Linze-Shi <linzeshi0@gmail.com>
---
 docs/configuration/stage_configs.md           |   2 +-
 docs/design/fullduplex.md                     |  19 ++-
 docs/serving/full_duplex_api.md               |  30 +++-
 docs/serving/realtime_duplex_api.md           |  51 +++----
 tests/e2e/online_serving/test_minicpmo_4_5.py |  23 +++-
 .../openai_api/test_duplex_api_server.py      | 130 ++++++++++++++----
 vllm_omni/config/stage_config.py              |   6 +-
 vllm_omni/deploy/minicpmo_4_5.yaml            |   3 +-
 vllm_omni/deploy/minicpmo_4_5_turn.yaml       |   3 +
 vllm_omni/entrypoints/openai/api_server.py    |  38 +++--
 10 files changed, 207 insertions(+), 98 deletions(-)
 create mode 100644 vllm_omni/deploy/minicpmo_4_5_turn.yaml

diff --git a/docs/configuration/stage_configs.md b/docs/configuration/stage_configs.md
index aa81d42c684..199241cf660 100644
--- a/docs/configuration/stage_configs.md
+++ b/docs/configuration/stage_configs.md
@@ -53,7 +53,7 @@ The new deploy schema lives under `vllm_omni/deploy/` and is paired with a froze
 | ------- | ------ | ---------- | --------- | ------------- |
 | `base_config` | str (path) | optional | — | Overlay parent (relative or absolute). `stages:` / `platforms:` deep-merged by stage_id; other scalars overlay-wins. Intended for user-authored overlays; prod yamls stay flat. |
 | `async_chunk` | bool | optional | `true` | Enable chunked streaming between stages. Pin to `false` if the pipeline runs end-to-end. |
-| `session_mode` | str | optional | `"turn"` | Session behavior. Duplex models (pipelines with a `duplex_plugin`, e.g. MiniCPM-o 4.5) set `"duplex"`; `vllm-omni serve` then serves it over `/v1/realtime?duplex=1` and `/v1/chat/completions`, both on duplex sessions. |
+| `session_mode` | str | optional | `"turn"` | Session behavior. For pipelines with a `duplex_plugin`, explicitly select `"duplex"` for the duplex engine or `"turn"` for the ordinary online serving stack. The shipped MiniCPM-o 4.5 default remains `"duplex"`. See [Full Duplex](../serving/full_duplex_api.md#enable-full-duplex). |
 | `active_stream_window` | int | optional | `0` | Number of active downstream stream slots; `0` preserves all-stream cycling. |
 | `duplex_session` | dict | optional | runtime defaults | Full-duplex session lifecycle, buffering, replay, and capacity limits. |
 | `connectors` | dict | optional | `null` | Named connector specs (`{name, extra}`). Referenced by each stage's `input_connectors` / `output_connectors`. See [Connector schema](#connector-schema). |
diff --git a/docs/design/fullduplex.md b/docs/design/fullduplex.md
index 4646b85cd0b..41a050a47e6 100644
--- a/docs/design/fullduplex.md
+++ b/docs/design/fullduplex.md
@@ -108,18 +108,17 @@ plugin and the session runtime config to `DuplexOrchestrator` directly.
    `AsyncOmniEngine`, `OrchestratorBase` and `Orchestrator` carry only
    template seams; `tests/engine/test_duplex_import_boundary.py` checks that
    importing the turn-based stack loads no duplex module.
-4. **Every surface a duplex server exposes is backed by a session.**
+4. **Deployment selects the serving stack.**
    `vllm-omni serve` constructs `DuplexOmni` when the pipeline declares
-   `duplex_plugin`; the server exposes `/v1/realtime?duplex=1` (alias
+   `duplex_plugin` and the deploy configuration sets `session_mode: duplex`.
+   An explicit `session_mode: turn` selects `AsyncOmni` instead, without
+   changing the pipeline's duplex capability. In duplex mode the server exposes `/v1/realtime?duplex=1` (alias
    `/v1/duplex`), `POST /v1/chat/completions`, `/v1/models` and `/health`, and
-   every other turn-based route reports "not available". The chat route is
-   served by `DuplexChatCompletionsAdapter`, a Realtime client that runs one
-   short-lived session per request: speech becomes a committed turn, text is
-   seeded as the session's opening turn because a model-native model takes a
-   turn only when it hears speech. Whether a model can be reached with text is
-   `DuplexCapabilities.supports_chat_completions`; one that cannot is refused
-   at once rather than left to idle out. Turn-based use of the same model stays
-   available offline through `Omni` / `AsyncOmni`.
+   every other turn-based route reports "not available". The chat route uses
+   the ordinary chat service on the duplex engine, without a session, when
+   the plugin declares `DuplexCapabilities.supports_chat_completions`.
+   Turn-based deployments use the ordinary API initialization and retain
+   model capability checks and endpoint restrictions.
 5. **Serving is transport only.** The websocket handler does socket I/O,
    wire-envelope validation, command translation, event rendering and the
    attachment/resume/replay bookkeeping; it holds no session state.
diff --git a/docs/serving/full_duplex_api.md b/docs/serving/full_duplex_api.md
index 92511e84ffe..9b3eceb58df 100644
--- a/docs/serving/full_duplex_api.md
+++ b/docs/serving/full_duplex_api.md
@@ -22,14 +22,14 @@ capability gates, see the [Realtime Duplex API guide](realtime_duplex_api.md).
 ## Enable Full Duplex
 
 A model is served full duplex when its registered pipeline declares a
-`duplex_plugin` (the model's `DuplexModelPlugin`). That declaration alone
-decides it: `vllm-omni serve` constructs `DuplexOmni` instead of `AsyncOmni`,
-and every surface the server exposes is backed by a duplex session. It serves
+`duplex_plugin` (the model's `DuplexModelPlugin`) and its deploy configuration
+sets `session_mode: duplex`. `vllm serve --omni` constructs `DuplexOmni`
+instead of `AsyncOmni`. It serves
 `/v1/realtime?duplex=1` (and its alias `/v1/duplex`),
 `POST /v1/chat/completions`, `/v1/models` and `/health`; every other
 turn-based HTTP route (speech, batch, embeddings, video, ...) answers "not
-available". Turn-based use of such a model stays available offline through the
-Python API (`Omni` / `AsyncOmni`).
+available". Set `session_mode: turn` to select the ordinary online serving
+stack instead. The model's supported tasks and endpoint restrictions still apply.
 
 `/v1/chat/completions` is the ordinary chat service running on the duplex
 engine: a request is a turn-based generation on the same stages, served
@@ -45,8 +45,24 @@ The deploy configuration of such a model must agree:
 session_mode: duplex
 ```
 
-A duplex model started with a deploy configuration that does not set it fails
-at startup rather than falling back to turn-based serving.
+A duplex-capable model must explicitly set `session_mode` to `duplex` or `turn`
+in its deploy configuration, possibly through `base_config` inheritance.
+Missing or invalid values fail at startup. The default MiniCPM-o deployment
+continues to use duplex mode.
+
+To run MiniCPM-o 4.5 with the turn-based engine:
+
+```bash
+vllm serve openbmb/MiniCPM-o-4_5 --omni \
+  --deploy-config vllm_omni/deploy/minicpmo_4_5_turn.yaml \
+  --trust-remote-code \
+  --port 8091
+```
+
+This profile inherits the default model and stage settings and overrides only
+`session_mode`. It supports ordinary HTTP requests without creating a duplex
+session handler. Mode selection happens at startup; a WebSocket query parameter
+does not switch engines. The Python `Omni` / `AsyncOmni` APIs are unchanged.
 
 !!! warning
 
diff --git a/docs/serving/realtime_duplex_api.md b/docs/serving/realtime_duplex_api.md
index cc10d99c96c..c18b416c7d5 100644
--- a/docs/serving/realtime_duplex_api.md
+++ b/docs/serving/realtime_duplex_api.md
@@ -32,33 +32,19 @@ vllm-omni serve openbmb/MiniCPM-o-4_5 \
 mounts `ws://<host>:8099/v1/realtime?duplex=1` (this page; `ws://<host>:8099/v1/duplex`
 is an alias of the same route), `POST /v1/chat/completions`, `/v1/models` and
 `/health`, and nothing else. The remaining turn-based HTTP routes (speech,
-batch, embeddings, video, ...) are not served by a duplex model.
-
-`/v1/chat/completions` is not a turn-based path on a duplex server: each
-request opens a short-lived duplex session and reads the answer off it. Audio
-content becomes an ordinary committed turn; text is seeded as the session's
-opening turn, because a model-native model takes a turn only when it hears
-speech. A model that cannot be seeded that way declares so, and a text request
-to it is refused with 400. Two consequences are worth sizing for:
-
-- **Every request holds an admission slot** for its lifetime, so
-  `duplex_session.max_sessions` caps HTTP concurrency as well as websocket
-  sessions. Beyond it a request is refused with HTTP 503.
-- **Latency follows the model's own clock.** A model-native session generates
-  per audio unit, so even a short answer costs what that many units cost --
-  noticeably more than the same model would take turn-based.
-
-`n > 1`, `logprobs`, `tools`, and image or video content parts have no
-representation in one duplex turn and are refused with HTTP 400 -- a Realtime
-conversation item carries text and audio only. `temperature`,
-`max_completion_tokens`, `modalities` and
-`chat_template_kwargs.use_tts_template` apply; the other
-`chat_template_kwargs` keys are logged as ignored. `extra_body` is passed to
-the session unchanged, exactly as a websocket client's session `extra_body`
-is, which is how a request asking for `modalities: ["text", "audio"]` supplies
-the `ref_audio` MiniCPM-o requires for audio output. A model that should not
-serve the route lists it in the deploy config's `endpoint_restrictions`,
-exactly as a turn-based model does.
+batch, embeddings, video, ...) are not served in duplex mode.
+
+`/v1/chat/completions` uses the ordinary chat service on the same engine
+when the plugin declares `supports_chat_completions`. HTTP chat requests do
+not create duplex sessions or consume session admission slots. Their options
+follow the [Chat Completions API](chat_completions_api.md) and the model's
+capabilities and endpoint restrictions.
+
+For a turn-based online deployment, use `minicpmo_4_5_turn.yaml` or explicitly
+set `session_mode: turn` in a deploy configuration derived from the model's
+profile. This selects `AsyncOmni` and the ordinary API initialization instead
+of the duplex handler. See [Full Duplex](full_duplex_api.md#enable-full-duplex)
+for the command and configuration requirements.
 
 ### Run the Example Client
 
@@ -1345,8 +1331,9 @@ them out into typed events before they reach a client.
 - Session capacity is bounded by `duplex_session.max_sessions` in the deploy
   configuration; admission beyond it fails with `resource_exhausted`
   (`rate_limit_error`, retryable).
-- A duplex deployment serves the duplex session surfaces only: the websocket
-  route and `/v1/chat/completions`, the latter on a session per request (see
-  [Start the Server](#start-the-server)). The other turn-based HTTP routes
-  report "not available" on a MiniCPM-o 4.5 server; turn-based use of the
-  model stays available offline through `Omni` / `AsyncOmni`.
+- A duplex deployment serves the websocket route and, when supported by the
+  model, ordinary `/v1/chat/completions` requests on the same engine without a
+  session per request (see [Start the Server](#start-the-server)). Other
+  turn-based HTTP routes report "not available" in duplex mode. To use the
+  ordinary online serving stack, select `session_mode: turn` as described in
+  [Full Duplex](full_duplex_api.md#enable-full-duplex).
diff --git a/tests/e2e/online_serving/test_minicpmo_4_5.py b/tests/e2e/online_serving/test_minicpmo_4_5.py
index 5417d2b1652..a1d045b723c 100644
--- a/tests/e2e/online_serving/test_minicpmo_4_5.py
+++ b/tests/e2e/online_serving/test_minicpmo_4_5.py
@@ -83,6 +83,25 @@
     ),
 ]
 
+turn_test_params = [
+    pytest.param(
+        OmniServerParams(
+            model=_MODEL,
+            stage_config_path=modify_stage_config(_CI_DEPLOY, updates={"session_mode": "turn"}),
+            use_stage_cli=False,
+            server_args=[
+                "--trust-remote-code",
+                "--async-chunk",
+                "--chat-template",
+                str(_NATIVE_CHAT_TEMPLATE),
+                "--chat-template-content-format",
+                "openai",
+            ],
+        ),
+        id="turn_async_chunk",
+    ),
+]
+
 
 def get_system_prompt():
     return {
@@ -138,7 +157,7 @@ def _read_prompt_selection_log(offset: int) -> str:
 @pytest.mark.advanced_model
 @pytest.mark.omni
 @hardware_test(res={"cuda": "H100", "npu": "A3"}, num_cards=1)
-@pytest.mark.parametrize("omni_server", test_params, indirect=True)
+@pytest.mark.parametrize("omni_server", test_params + turn_test_params, indirect=True)
 def test_text_to_text_001(omni_server, openai_client) -> None:
     """
     Test text-only input generating text output via OpenAI API.
@@ -163,7 +182,7 @@ def test_text_to_text_001(omni_server, openai_client) -> None:
 @pytest.mark.full_model
 @pytest.mark.omni
 @hardware_test(res={"cuda": ["H100", "B200"], "npu": "A3"}, num_cards=1)
-@pytest.mark.parametrize("omni_server", test_params, indirect=True)
+@pytest.mark.parametrize("omni_server", test_params + turn_test_params, indirect=True)
 def test_text_to_audio_001(omni_server, openai_client) -> None:
     """
     Test text-only input generating text + audio output via OpenAI API.
diff --git a/tests/entrypoints/openai_api/test_duplex_api_server.py b/tests/entrypoints/openai_api/test_duplex_api_server.py
index b528cbc2a41..9cf58b114b8 100644
--- a/tests/entrypoints/openai_api/test_duplex_api_server.py
+++ b/tests/entrypoints/openai_api/test_duplex_api_server.py
@@ -1,28 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-"""Guards for the duplex-only API server (unified full-duplex framework).
-
-A model whose pipeline declares ``duplex_plugin`` is served through
-``DuplexOmni`` and nothing else: sessions run over ``/v1/realtime?duplex=1``
-(alias ``/v1/duplex``) and every turn-based route reports "not available".
-These tests lock that shape, which ``test_api_server_guards.py`` covers for the
-diffusion and multi-stage servers:
-
-* the pipeline probe that decides duplex vs turn-based at startup,
-* the ``app.state`` snapshot of a duplex server (what is wired, what stays
-  ``None``),
-* both duplex websocket routes reaching the session handler, and
-  ``/v1/realtime`` without the flag still reporting the turn-based Realtime API
-  as unavailable,
-* the startup-warmup gate that holds real clients while the warmup session runs.
-
-CPU-only: no engine is started; ``DuplexOmni`` is subclassed with just the
-accessors the app-state wiring reads.
-"""
+"""CPU tests for serving-mode selection, duplex API wiring and warmup."""
 
 from __future__ import annotations
 
 import asyncio
+from argparse import Namespace
+from dataclasses import replace
 from types import SimpleNamespace
 
 import pytest
@@ -31,12 +15,14 @@
 from starlette.datastructures import State
 from starlette.websockets import WebSocketDisconnect
 
+from vllm_omni.config import stage_config
 from vllm_omni.config.config_factory import StageConfigFactory
-from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig, PipelineConfig, StagePipelineConfig
 from vllm_omni.engine.duplex.config import DuplexCapabilities
 from vllm_omni.entrypoints.duplex.serving import OmniDuplexSessionHandler
 from vllm_omni.entrypoints.duplex_omni import DuplexOmni
 from vllm_omni.entrypoints.openai import api_server
+from vllm_omni.utils.tracking_parser import TrackingNamespace
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
@@ -202,9 +188,10 @@ def _minimal_args(**overrides) -> SimpleNamespace:
         (None, False),
     ],
 )
-def test_duplex_model_probe_follows_the_pipeline_plugin(monkeypatch, pipeline_config, expected: bool) -> None:
-    """``duplex_plugin`` alone decides whether ``serve`` builds ``DuplexOmni``."""
+def test_duplex_serving_requires_a_pipeline_plugin(monkeypatch, tmp_path, pipeline_config, expected: bool) -> None:
     seen: dict[str, object] = {}
+    deploy_path = tmp_path / "deploy.yaml"
+    deploy_path.write_text("session_mode: duplex\n")
 
     def fake_get_pipeline_config(*, model, trust_remote_code, deploy_config_path=None, **_kwargs):
         seen.update(model=model, trust_remote_code=trust_remote_code, deploy_config_path=deploy_config_path)
@@ -212,12 +199,12 @@ def fake_get_pipeline_config(*, model, trust_remote_code, deploy_config_path=Non
 
     monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", fake_get_pipeline_config)
 
-    kwargs = {"trust_remote_code": True, "deploy_config": "deploy.yaml"}
-    assert api_server._is_duplex_model("demo-duplex-model", kwargs) is expected
+    kwargs = {"trust_remote_code": True, "deploy_config": str(deploy_path)}
+    assert api_server._should_serve_duplex("demo-duplex-model", kwargs) is expected
     assert seen == {
         "model": "demo-duplex-model",
         "trust_remote_code": True,
-        "deploy_config_path": "deploy.yaml",
+        "deploy_config_path": str(deploy_path),
     }
 
 
@@ -230,7 +217,98 @@ def fake_get_pipeline_config(**_kwargs):
     monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", fake_get_pipeline_config)
 
     with pytest.raises(ValueError, match="trust_remote_code"):
-        api_server._is_duplex_model("demo-duplex-model", {})
+        api_server._should_serve_duplex("demo-duplex-model", {})
+
+
+@pytest.fixture
+def duplex_pipeline():
+    return PipelineConfig(
+        model_type="demo",
+        stages=(StagePipelineConfig(stage_id=0, model_stage="demo", final_output=True),),
+        duplex_plugin="pkg.mod.Plugin",
+    )
+
+
+@pytest.mark.parametrize("session_mode", ["turn", "duplex"])
+@pytest.mark.parametrize("config_source", ["explicit", "default", "basename", "inherited"])
+@pytest.mark.asyncio
+async def test_serving_mode_selects_engine_and_preserves_stage_config(
+    monkeypatch, tmp_path, duplex_pipeline, session_mode, config_source
+):
+    base_path = tmp_path / "base.yaml"
+    base_path.write_text("session_mode: duplex\nstages:\n  - stage_id: 0\n    max_num_seqs: 4\n")
+    deploy_path = tmp_path / "deploy.yaml"
+    deploy_path.write_text(f"base_config: base.yaml\nsession_mode: {session_mode}\n")
+    if config_source == "inherited":
+        deploy_path = tmp_path / "overlay.yaml"
+        deploy_path.write_text("base_config: deploy.yaml\n")
+    pipeline = replace(duplex_pipeline, default_deploy_config_name=deploy_path.name)
+    monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", lambda **_: pipeline)
+    monkeypatch.setattr(stage_config, "_DEPLOY_DIR", tmp_path)
+    kwargs = {}
+    if config_source != "default":
+        kwargs["deploy_config"] = deploy_path.name if config_source == "basename" else str(deploy_path)
+
+    created = []
+
+    class TurnEngine:
+        def __init__(self, model, **engine_kwargs):
+            self.model = model
+            self.kwargs = engine_kwargs
+            self.closed = False
+            created.append(self)
+
+        def shutdown(self):
+            self.closed = True
+
+    class DuplexEngine(TurnEngine):
+        pass
+
+    monkeypatch.setattr(api_server, "AsyncOmni", TurnEngine)
+    monkeypatch.setattr(api_server, "DuplexOmni", DuplexEngine)
+    args = TrackingNamespace(
+        Namespace(model="demo-model", disable_log_stats=True, **kwargs), frozenset({"model", *kwargs})
+    )
+    async with api_server.build_async_omni_from_stage_config(args) as engine:
+        assert type(engine) is (DuplexEngine if session_mode == "duplex" else TurnEngine)
+        assert engine.model == "demo-model"
+        assert engine.kwargs == {**kwargs, "log_stats": False}
+        assert not engine.closed
+    assert len(created) == 1
+    assert engine.closed
+    deploy = stage_config.load_deploy_config(deploy_path)
+    assert deploy.session_mode == session_mode
+    assert deploy.stages[0].max_num_seqs == 4
+
+
+@pytest.mark.parametrize("contents", ["{}\n", "session_mode: null\n", "session_mode: typo\n"])
+def test_duplex_serving_rejects_missing_or_invalid_mode(monkeypatch, tmp_path, duplex_pipeline, contents):
+    deploy_path = tmp_path / "deploy.yaml"
+    deploy_path.write_text(contents)
+    monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", lambda **_: duplex_pipeline)
+    with pytest.raises(ValueError, match="session_mode: turn or duplex"):
+        api_server._should_serve_duplex("demo-model", {"deploy_config": str(deploy_path)})
+
+
+def test_duplex_serving_requires_a_deploy_config(monkeypatch, duplex_pipeline):
+    monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", lambda **_: duplex_pipeline)
+    with pytest.raises(ValueError, match="requires a deploy config"):
+        api_server._should_serve_duplex("demo-model", {})
+
+
+def test_duplex_serving_propagates_deploy_load_errors(monkeypatch, tmp_path, duplex_pipeline):
+    monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", lambda **_: duplex_pipeline)
+    with pytest.raises(FileNotFoundError):
+        api_server._should_serve_duplex("demo-model", {"deploy_config": str(tmp_path / "missing.yaml")})
+
+
+@pytest.mark.parametrize("deploy_name,expected", [("minicpmo_4_5.yaml", True), ("minicpmo_4_5_turn.yaml", False)])
+def test_minicpmo_serving_profiles(monkeypatch, deploy_name, expected):
+    from vllm_omni.model_executor.models.minicpmo_4_5.pipeline import MINICPMO_4_5_PIPELINE
+
+    monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", lambda **_: MINICPMO_4_5_PIPELINE)
+    assert api_server._should_serve_duplex("openbmb/MiniCPM-o-4_5", {"deploy_config": deploy_name}) is expected
+    assert api_server._should_serve_duplex("openbmb/MiniCPM-o-4_5", {}) is True
 
 
 # --------------------------------------------------------------------------- #
diff --git a/vllm_omni/config/stage_config.py b/vllm_omni/config/stage_config.py
index 6af65b8ed90..24453ae88b5 100644
--- a/vllm_omni/config/stage_config.py
+++ b/vllm_omni/config/stage_config.py
@@ -309,10 +309,8 @@ class PipelineConfig:
     diffusers_class_name: str | None = None
     diffusers_class_aliases: tuple[str, ...] = ()
     endpoint_restrictions: tuple[EndpointRestriction, ...] = ()
-    # Dotted path of the model's ``DuplexModelPlugin``. A pipeline is a duplex
-    # model iff this is set: ``vllm-omni serve`` then always runs it through
-    # ``DuplexOmni`` (every served surface runs on a duplex session) and the engine hosts one
-    # ``DuplexOrchestrator`` with the plugin loaded.
+    # Dotted path of the model's ``DuplexModelPlugin``. Online serving uses
+    # DuplexOmni only when the deploy configuration selects session_mode: duplex.
     duplex_plugin: str | None = None
     # Legacy duplex wiring of the models that are not ported to the plugin
     # framework yet (PersonaPlex, Nemotron VoiceChat). Nothing reads them: a
diff --git a/vllm_omni/deploy/minicpmo_4_5.yaml b/vllm_omni/deploy/minicpmo_4_5.yaml
index 5c26fc2c68b..a04cff4009c 100644
--- a/vllm_omni/deploy/minicpmo_4_5.yaml
+++ b/vllm_omni/deploy/minicpmo_4_5.yaml
@@ -1,8 +1,7 @@
 # MiniCPM-o 4.5 three-stage deploy on one large-memory GPU.
 pipeline: minicpmo_4_5
 async_chunk: true
-# session_mode: duplex makes vllm-omni serve run this model duplex-only
-# (/v1/realtime?duplex=1); every other duplex_session knob keeps its runtime default.
+# Use minicpmo_4_5_turn.yaml to select the ordinary turn-based serving engine.
 session_mode: duplex
 # Keep the active window aligned with the session and stage capacities below.
 # A smaller window serializes first-packet generation for concurrent chat turns.
diff --git a/vllm_omni/deploy/minicpmo_4_5_turn.yaml b/vllm_omni/deploy/minicpmo_4_5_turn.yaml
new file mode 100644
index 00000000000..8dada12577e
--- /dev/null
+++ b/vllm_omni/deploy/minicpmo_4_5_turn.yaml
@@ -0,0 +1,3 @@
+# MiniCPM-o 4.5 using the turn-based engine and ordinary HTTP serving.
+base_config: minicpmo_4_5.yaml
+session_mode: turn
diff --git a/vllm_omni/entrypoints/openai/api_server.py b/vllm_omni/entrypoints/openai/api_server.py
index 376a9ccd28d..20706396c0e 100644
--- a/vllm_omni/entrypoints/openai/api_server.py
+++ b/vllm_omni/entrypoints/openai/api_server.py
@@ -19,6 +19,7 @@
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
 from http import HTTPStatus
+from pathlib import Path
 from typing import Annotated, Any, Literal
 
 import vllm.envs as envs
@@ -440,21 +441,34 @@ async def build_async_omni(
         yield async_omni
 
 
-def _is_duplex_model(model: str, kwargs: dict[str, Any]) -> bool:
-    """Whether ``model``'s pipeline declares a ``duplex_plugin`` (served by ``DuplexOmni``).
-
-    Resolution errors propagate: a duplex model whose pipeline or deploy
-    config cannot be resolved must fail startup rather than silently start a
-    turn-based server.
-    """
+def _should_serve_duplex(model: str, kwargs: dict[str, Any]) -> bool:
+    """Select the serving engine without changing the model's duplex capability."""
     from vllm_omni.config.config_factory import StageConfigFactory
+    from vllm_omni.config.stage_config import _DEPLOY_DIR, resolve_deploy_yaml
 
     pipeline_config = StageConfigFactory.get_pipeline_config(
         model=model,
         trust_remote_code=bool(kwargs.get("trust_remote_code")),
         deploy_config_path=kwargs.get("deploy_config"),
     )
-    return bool(pipeline_config is not None and getattr(pipeline_config, "duplex_plugin", None))
+    if pipeline_config is None or not getattr(pipeline_config, "duplex_plugin", None):
+        return False
+
+    deploy_path = kwargs.get("deploy_config")
+    if deploy_path is None:
+        if pipeline_config.default_deploy_config_name is None:
+            raise ValueError("A duplex-capable model requires a deploy config with session_mode: turn or duplex")
+        deploy_path = _DEPLOY_DIR / pipeline_config.default_deploy_config_name
+    else:
+        deploy_path = Path(deploy_path)
+        if not deploy_path.exists() and deploy_path.parent == Path("."):
+            deploy_path = _DEPLOY_DIR / deploy_path
+
+    # Resolve base_config too, so the API and stage workers use the same mode.
+    session_mode = resolve_deploy_yaml(deploy_path).get("session_mode")
+    if session_mode not in ("turn", "duplex"):
+        raise ValueError("A duplex-capable model requires session_mode: turn or duplex in its deploy config")
+    return session_mode == "duplex"
 
 
 @asynccontextmanager
@@ -518,9 +532,7 @@ async def build_async_omni_from_stage_config(
         kwargs.pop("robot_openpi_idle_timeout", None)
         model = kwargs.pop("model", None) or args.model
         kwargs.setdefault("log_stats", not args.disable_log_stats)
-        if _is_duplex_model(model, kwargs):
-            # A duplex model is always served in duplex mode: sessions over
-            # /v1/realtime?duplex=1, no turn-based HTTP routes.
+        if _should_serve_duplex(model, kwargs):
             async_omni = DuplexOmni(model=model, **kwargs)
         else:
             async_omni = AsyncOmni(model=model, **kwargs)
@@ -712,9 +724,7 @@ async def omni_init_app_state(
     state.stage_configs = engine_client.stage_configs if hasattr(engine_client, "stage_configs") else None
     model_name = served_model_names[0] if served_model_names else args.model
 
-    # Duplex mode: a duplex model is served through DuplexOmni only. Sessions
-    # run over /v1/realtime?duplex=1; every turn-based HTTP route reports
-    # "not available".
+    # Initialize the API surface for the selected engine, not just the model.
     if isinstance(engine_client, DuplexOmni):
         await _init_duplex_app_state(engine_client, state, args, base_model_paths, vllm_config, request_logger)
         return

From d81777f297811ceb68bd991b6defd9f46fc9162e Mon Sep 17 00:00:00 2001
From: Bojiang Li <327132355+bojiang-li@users.noreply.github.com>
Date: Wed, 16 Sep 2026 17:30:47 -0700
Subject: [PATCH 051/105] [Doc] Scope Spark FP8 guidance to the validated
 revision (#7536)

Signed-off-by: bojiang-li <327132355+bojiang-li@users.noreply.github.com>
---
 recipes/MiniMaxAI/MiniMax-H3-Spark-GB10.md | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/recipes/MiniMaxAI/MiniMax-H3-Spark-GB10.md b/recipes/MiniMaxAI/MiniMax-H3-Spark-GB10.md
index efd88c06849..f4304cd4a53 100644
--- a/recipes/MiniMaxAI/MiniMax-H3-Spark-GB10.md
+++ b/recipes/MiniMaxAI/MiniMax-H3-Spark-GB10.md
@@ -16,6 +16,12 @@ Validated on:
   50 steps, text-encoder TP2, and DiT USP2
 - Common sampling settings: `flow_shift=12`, `seed=1101`
 
+The commands and measurements below describe this pinned revision. Newer
+versions have changed the scope of `--quantization fp8`; see
+[Online FP8 quantization](MiniMax-H3.md#online-fp8-quantization) for the current
+component selection and offload support. Re-qualify memory, output, and latency
+on GB10 before comparing results across revisions.
+
 ## Capacity requirements
 
 | Resource | DGX Spark (GB10) |
@@ -40,8 +46,10 @@ math relative to the RTX and datacenter recipes:
 - **Do not use `--enable-cpu-offload`.** Moving weights from "VRAM" to "host RAM"
   frees nothing here.
 - **`--quantization fp8` is mandatory.** A BF16 partition is 135 GiB and does not
-  fit in 121 GiB. Online FP8 quantizes the DiT only (62 GiB to ~31 GiB); the
-  Qwen3-VL text encoder and both VAEs stay BF16.
+  fit in 121 GiB. At the validated revision, online FP8 quantizes the DiT only
+  (62 GiB to ~31 GiB); the Qwen3-VL text encoder and both VAEs stay BF16.
+  Current versions also quantize eligible text-decoder linears by default, so
+  the same flag does not imply the same quantization scope across revisions.
 
 With ~97.7 GiB of the pool held by the allocator at peak, T2VA leaves roughly
 23 GiB of headroom for the OS, page cache, and any other process on the box.
@@ -295,6 +303,8 @@ shorter than a 50-step Ref2VA run.
 - Ref2VA requires a vLLM-Omni build newer than `v0.26.0`. See the version note
   under **Validated on**: FP8 weight loading and image-only Ref2VA are both
   broken on `release/v0.26.0`. The suggested version is `v0.26.1`.
-- Online FP8 is incompatible with layerwise offload — the offload path produces a
-  weight stride the Cutlass FP8 kernel rejects. This is not a practical
-  restriction here since offload is unusable on GB10 anyway.
+- At the validated revision, online FP8 with layerwise offload produced a weight
+  stride the Cutlass FP8 kernel rejected. Current H3 supports online FP8 with
+  layerwise offload and both DLO transfer paths; see the linked FP8 section
+  above. This does not change the GB10 capacity guidance: offload uses the same
+  unified-memory pool and is not enabled in this recipe.

From 72cc012cfdf2ae531338cb9e221804f3bc31e467 Mon Sep 17 00:00:00 2001
From: WeiQing Chen <40507679+david6666666@users.noreply.github.com>
Date: Thu, 17 Sep 2026 09:52:23 +0800
Subject: [PATCH 052/105] [CI][bugfix] Fix MiniMax H3 FP8 quality test
 remote-code loading (#7617)

---
 .../models/minimax_h3/test_minimax_h3_quantization_quality.py   | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
index ba0e0ddf55f..87b04613a14 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
@@ -189,6 +189,8 @@ def test_minimax_h3_quantization_quality(config: QualityTestConfig):
         # The fused BF16 baseline only fits on H100-80GB with encoder TP.
         "stage_0_tensor_parallel_size": 2,
         "vae_use_tiling": True,
+        # MiniMax H3's VAE is implemented by code shipped with the checkpoint.
+        "trust_remote_code": True,
     }
 
     omni_bl = Omni(**common_kwargs)

From 4fab34c8f46f1f431571cf5c699f55753b4366ea Mon Sep 17 00:00:00 2001
From: Linze Shi <linzeshi0@gmail.com>
Date: Wed, 16 Sep 2026 19:45:31 -0700
Subject: [PATCH 053/105] [Bugfix] Update ComfyUI serving-mode mock after
 helper rename (#7694)

Signed-off-by: Linze-Shi <linzeshi0@gmail.com>
---
 tests/e2e/features/comfyui/test_comfyui_integration.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/e2e/features/comfyui/test_comfyui_integration.py b/tests/e2e/features/comfyui/test_comfyui_integration.py
index 3c6f0492a86..480381f0ab9 100644
--- a/tests/e2e/features/comfyui/test_comfyui_integration.py
+++ b/tests/e2e/features/comfyui/test_comfyui_integration.py
@@ -534,7 +534,7 @@ async def _mock_preprocess_chat(self, *args, **kwargs):
     # 1. The API layer uses its stage_list and stage_configs attributes
     # 2. Its __init__ method has slow side effects (model & config loading).
     # These cases use the non-duplex mock engine without loading model configs.
-    mocker.patch("vllm_omni.entrypoints.openai.api_server._is_duplex_model", return_value=False)
+    mocker.patch("vllm_omni.entrypoints.openai.api_server._should_serve_duplex", return_value=False)
     mock_async_omni_cls = mocker.patch("vllm_omni.entrypoints.openai.api_server.AsyncOmni")
     monkeypatch.setattr(
         "vllm_omni.entrypoints.openai.serving_chat.OmniOpenAIServingChat._preprocess_chat",

From becfefd4402da180d8af5121cef474fee40883af Mon Sep 17 00:00:00 2001
From: HAAZZZEEEE <49724853+HAAZZZEEEE@users.noreply.github.com>
Date: Thu, 17 Sep 2026 11:11:40 +0800
Subject: [PATCH 054/105] [Hardware][Ascend] Add Wan2.2 MXFP4 UOS, Smooth and
 W4A8 fallback (#7210)

Signed-off-by: HAAZZZEEEE <wang-taicheng@qq.com>
---
 docs/user_guide/quantization/mxfp4.md         | 414 +++++++++----
 .../text_to_video/text_to_video.py            |  11 +-
 tests/config/test_omni_config.py              |  30 +-
 .../wan2_2/test_create_transformer_quant.py   | 213 ++++++-
 .../wan2_2/test_wan22_pipeline_diffuse.py     |  98 +++-
 .../quantization/test_mxfp4_checkpoint.py     | 294 ++++++++++
 .../quantization/test_mxfp4_config.py         | 555 +++++++++++++++++-
 .../quantization/test_wan_mxfp4_loading.py    | 237 ++++++++
 .../test_diffusion_config_propagation.py      |   6 +
 .../test_text_to_video_prompts.py             |  49 +-
 .../npu/quant/test_mxfp4_step_fallback.py     | 168 ++++++
 vllm_omni/config/omni_config.py               |   4 +
 vllm_omni/diffusion/data.py                   |   4 +
 .../model_loader/diffusers_loader.py          |  37 +-
 .../models/wan2_2/pipeline_wan2_2.py          |  51 +-
 .../models/wan2_2/pipeline_wan2_2_i2v.py      |  26 +-
 .../models/wan2_2/pipeline_wan2_2_vace.py     |  11 +-
 .../models/wan2_2/wan2_2_transformer.py       | 106 +++-
 vllm_omni/quantization/factory.py             |  77 ++-
 vllm_omni/quantization/mxfp4_config.py        | 228 ++++++-
 20 files changed, 2435 insertions(+), 184 deletions(-)
 create mode 100644 tests/diffusion/quantization/test_mxfp4_checkpoint.py
 create mode 100644 tests/diffusion/quantization/test_wan_mxfp4_loading.py
 create mode 100644 tests/platforms/npu/quant/test_mxfp4_step_fallback.py

diff --git a/docs/user_guide/quantization/mxfp4.md b/docs/user_guide/quantization/mxfp4.md
index b18b3e7b39f..00ff97c0107 100644
--- a/docs/user_guide/quantization/mxfp4.md
+++ b/docs/user_guide/quantization/mxfp4.md
@@ -6,22 +6,25 @@ W4A4 MXFP4 (Microscaling FP4) quantizes both weights and activations to FP4
 (`float4_e2m1fn_x2`, packed 2 values per byte) using the OCP MX format: groups
 of 32 K-dimension elements share a single `float8_e8m0fnu` exponent scale.
 
+On Ascend, single-scale MXFP4 also supports Universal Optimal Scaling
+(UOS, `Qmax=7.25`), described in the single-scale scaling section below.
+
 vLLM-Omni provides two quantization methods with different scale structures:
 
 | Method | Scale structure | Mode | Use case |
-|--------|----------------|------|----------|
-| `mxfp4` | Single-scale (per-32 fine only) | Online only | Quick accuracy baseline; no checkpoint prep needed |
-| `mxfp4_dualscale` | Dual-scale (fine per-32 + coarse per-512 + per-channel `mul_scale`) | Online + Offline | Production; better accuracy; offline recommended |
+| -------- | ---------------- | ------ | ---------- |
+| `mxfp4` | Single-scale (per-32 fine only) | Online + pre-quantized single-scale weights | Online baseline, or an existing single-scale checkpoint in the layout below |
+| `mxfp4_dualscale` | Dual-scale (fine per-32 + coarse per-512 + per-channel `mul_scale`) | Online + Offline | W4A4 with dual-level scales; offline mode loads calibrated Smooth tensors |
 
-!!! tip "Recommended: `mxfp4_dualscale` offline"
-    For production deployments, use the `mxfp4_dualscale` offline mode with a
+!!! tip "Existing W4A4-only DualScale deployments"
+    For W4A4-only deployments, the existing `mxfp4_dualscale` offline mode uses a
     pre-quantized checkpoint produced by msModelSlim. Offline checkpoints load
-    calibrated `mul_scale` tensors from disk, providing measurably better accuracy
-    than any online method. The one-time preprocessing cost amortises across all
-    subsequent inference runs.
+    calibrated `mul_scale` tensors from disk. Quality depends on the model,
+    calibration recipe and BF16 fallback policy; evaluate the checkpoint against
+    your quality target before deployment.
 
-    Use `mxfp4` online only for quick experimentation where preprocessing time
-    is not acceptable and accuracy loss is tolerable.
+    W4A8 layer/step fallback requires single-scale `mxfp4`, online or offline.
+    DualScale supports W4A4 and BF16 routing only.
 
 !!! warning "Online single-scale ≠ Offline dual-scale"
     `mxfp4_dualscale` offline mode uses `NPUMxfp4DualScaleLinearMethod`:
@@ -34,61 +37,244 @@ vLLM-Omni provides two quantization methods with different scale structures:
 
 ## Hardware Support
 
-| Device | Support |
-|--------|---------|
-| NVIDIA Blackwell GPU (SM 100+) | ⭕ |
-| NVIDIA Ada/Hopper GPU (SM 89+) | ⭕ |
-| NVIDIA Ampere GPU (SM 80+) | ⭕ |
-| AMD ROCm (gfx950 / MI355X) | ✅ |
-| Intel XPU | ⭕ |
-| Ascend NPU (Atlas 950 A5) | ✅ |
+The following matrix describes these vLLM-Omni implementations, rather than
+hardware support for the MXFP4 format in general.
+
+| Device | Single-scale online OCP | Single-scale offline | UOS / W4A8 fallback | DualScale |
+| -------- | -------- | -------- | -------- | -------- |
+| Ascend NPU (Atlas 950 A5) | ✅ | ✅ | ✅ | ✅ |
+| AMD ROCm (gfx950 / MI355X) | ✅ | ❌ | ❌ | ❌ |
+| Other AMD architectures | ❌ | ❌ | ❌ | ❌ |
+| NVIDIA GPU | ❌ | ❌ | ❌ | ❌ |
+| Intel XPU | ❌ | ❌ | ❌ | ❌ |
 
-Legend: `✅` supported, `❌` unsupported, `⭕` not verified in this guide.
+Legend: `✅` supported by the implementation, `❌` unsupported.
+ROCm uses the existing AITER online path and requires `mxfp4_scale_alg=0`.
 
 ## Model Type Support
 
 ### Diffusion Model (Wan2.2)
 
 | Model | Online | Offline | Notes |
-|-------|--------|---------|-------|
-| Wan2.2-T2V-A14B | `mxfp4` / `mxfp4_dualscale` | `mxfp4_dualscale` | MoE cascade (`transformer` + `transformer_2`); both transformers quantized with the same config |
-| Wan2.2-I2V-A14B | `mxfp4` / `mxfp4_dualscale` | `mxfp4_dualscale` | MoE cascade; same scheme as T2V-A14B |
-| Wan2.2-TI2V-5B | ❌ | ❌ | Parameter count too small; W4A4 causes unacceptable accuracy loss |
+| ------- | -------- | --------- | ------- |
+| Wan2.2-T2V-A14B | `mxfp4` / `mxfp4_dualscale` | `mxfp4` / `mxfp4_dualscale` | Cascade experts resolve checkpoint metadata independently; explicit global runtime policy applies to both |
+| Wan2.2-I2V-A14B | `mxfp4` / `mxfp4_dualscale` | `mxfp4` / `mxfp4_dualscale` | Per-expert configuration uses the same interface as T2V; validate I2V checkpoints separately |
+| Wan2.2-TI2V-5B | Requires validation | Requires validation | This guide does not establish checkpoint compatibility or generation quality for TI2V-5B |
 
-The choice between `mxfp4` and `mxfp4_dualscale` in **online mode** is about
-quantization quality, not model compatibility — both work on cascade (A14B) and
-single-transformer models alike, the same as `mxfp8` online:
+Both methods can be integrated with single-transformer and cascade models.
+This alone does not establish support or quality for every model variant:
 
-- `mxfp4`: single-scale, lower overhead, simpler compute, online only
-- `mxfp4_dualscale`: dual-scale + optional BF16 fallback, better accuracy, online **and** offline
+- `mxfp4`: single-scale; online and pre-quantized weights, with optional W4A8 fallback on NPU
+- `mxfp4_dualscale`: dual-scale; online and offline, with BF16 fallback
 
-**Offline** checkpoints for A14B are always in `mxfp4_dualscale` format (produced
-by the merge script); there is no offline `mxfp4` single-scale format.
+The existing `merge_mxfp4_dualscale_checkpoint.py` produces **offline
+`mxfp4_dualscale`** checkpoints. Single-scale weights must satisfy the separate
+layout described below; changing a DualScale checkpoint's method name to
+`mxfp4` does not convert its weights. Prepare single-scale checkpoints with
+external tooling. Real exported checkpoint compatibility and model quality
+require validation of that checkpoint; the synthetic tests do not establish
+UOS export or video acceptance.
 
 !!! note "Per-layer BF16 fallback in offline cascade models"
-    The A14B offline checkpoint uses `quant_method: mxfp4_dualscale`. Most
+    An A14B offline DualScale checkpoint uses `quant_method: mxfp4_dualscale`. Most
     linear layers are stored as W4A4 MXFP4 DualScale; precision-sensitive layers
     retain their original BF16 weights and are listed in `ignored_layers` inside
     each transformer's `config.json`. The two transformers may have different
     `ignored_layers` sets — the pipeline reads each transformer's own `config.json`
-    and rebuilds the config locally when they differ, so routing is always
-    per-transformer-accurate.
-
-!!! warning "TI2V-5B not supported"
-    Wan2.2-TI2V-5B is excluded from W4A4 quantization. Its smaller parameter
-    count makes it significantly more sensitive to 4-bit quantization noise,
-    resulting in unacceptable accuracy loss. Use [MXFP8](mxfp8.md) for TI2V-5B.
+    and resolves the storage format and BF16 layer policy independently.
 
 ## Configuration
 
+### W4A8 fallback at selected layers and denoising steps (Ascend NPU)
+
+For single-scale `mxfp4`, set `w4a8_fallback_steps` to a list of zero-based
+request denoising loop indices (not scheduler timestep values).
+Set `w4a8_fallback_layers` to exact runtime Linear paths, for example
+`["blocks.10.attn1.to_qkv", "blocks.12.ffn.net_2"]`. A selected layer uses W4A8
+at every step; at a selected step, all other quantized layers also use W4A8.
+The rules are combined with **OR**. W4A8 uses MXFP8 activations with MXFP4
+weights. Omitting both lists or passing `[]` keeps the existing W4A4 behavior. Existing
+`ignored_layers` take priority: **BF16 > (layer OR step) W4A8 > W4A4**.
+DualScale's existing leading BF16 block rule is unchanged; it does not enable
+W4A8.
+
+```python
+from vllm_omni import Omni
+
+omni = Omni(
+    model="<Wan2.2-T2V-A14B-Diffusers>",
+    quantization_config={
+        "method": "mxfp4",
+        "w4a8_fallback_layers": ["blocks.10.attn1.to_qkv"],
+        "w4a8_fallback_steps": [0, 1, 38, 39],
+    },
+)
+```
+
+Both policies also work with offline single-scale `mxfp4`. Any nonempty
+W4A8 list with `mxfp4_dualscale`, online or offline, raises an explicit error
+at configuration construction. Empty lists preserve its existing W4A4 path.
+Each expert's checkpoint still determines its serialized
+format and BF16 layer routing. A serialized checkpoint config is the complete
+storage contract: `ignored_layers`, or its `modules_to_not_convert` alias,
+selects the BF16 layers, and omitting both means no explicit BF16 layers. A
+method-only checkpoint value such as `"mxfp4"` or
+`{"quant_method": "mxfp4"}` carries no storage policy and leaves a caller's
+online `ignored_layers` unchanged. An explicitly supplied quantization config
+retains its W4A8 layer and step lists when the loader rebuilds either expert's
+config from disk, including empty lists that disable checkpoint policies.
+Within an explicit runtime config, an omitted W4A8 list defaults to `[]`;
+individual omitted fields do not inherit saved policies. Without an explicit
+runtime config, auto-detection uses the saved checkpoint policies.
+
+Layer names are relative to each expert (`blocks.10...`, without a
+`transformer.` or `transformer_2.` prefix). A global config applies the same
+list to both experts; per-component `transformer`/`transformer_2` configs can
+select different lists. Wan selects these expert names exactly: a `transformer`
+entry does not match `transformer_2`; an omitted expert uses `default` if set.
+A component mapped to `null` (or an unmatched component
+without a default) stays unquantized and requires a BF16 checkpoint; loading a
+quantized checkpoint for that disabled component raises an error. A top-level
+`quantization_config=None` retains checkpoint auto-detection.
+Names are exact, with no regex, wildcard, block expansion,
+or checkpoint-name remapping. Wan validates them against its runtime Linear
+modules and logs the selected paths/count and BF16 overrides per PP rank.
+Use `attn1.to_qkv` for fused self-attention; `attn1.to_q`, `to_k`, or `to_v`
+checkpoint names raise an error. Cross-attention `attn2.to_q/to_k/to_v` remains
+separate. Layer-only fallback does not require a denoise ForwardContext.
+
+The text-to-video example accepts the JSON directly:
+
+```bash
+ASCEND_RT_VISIBLE_DEVICES=0,1,2,3 \
+python examples/offline_inference/text_to_video/text_to_video.py \
+    --model /path/to/Wan2.2-T2V-A14B-Diffusers \
+    --quantization-config '{"method":"mxfp4","w4a8_fallback_steps":[0,2]}' \
+    --tensor-parallel-size 1 --ulysses-degree 2 --cfg-parallel-size 2 \
+    --enforce-eager --height 480 --width 832 --num-frames 81 \
+    --num-inference-steps 40 --seed 42 --output wan22-w4a8.mp4
+```
+
+Use either `--quantization` or `--quantization-config` in this example.
+Serving accepts the same JSON through `--diffusion-quantization-config`.
+
+The list uses one request's loop index across both high- and low-noise experts,
+and both CFG branches see the same index. A new request starts at step zero.
+Indices outside the request's step range are never selected. A pipeline must
+publish `ForwardContext.denoise_step_idx`; requesting step fallback without
+that context raises an error instead of silently ignoring the list.
+
+Single-scale W4A4 and W4A8 reuse the same prepared `weight` and `weight_scale`.
+Online loading quantizes the original BF16/FP16 weight once; offline loading
+packs the numeric FP4 values and reshapes the saved E8M0 scale without
+requantizing the weight. Only activation precision changes during forward.
+There is no DualScale decoding, second W4 representation or `w4a8_weight` /
+`w4a8_weight_scale` cache. No weight quantization runs inside the denoising loop.
+
+The mixed FP8/FP4 GEMM uses BF16 output and a matching BF16 row bias for
+compatibility with the target A5 runtime. An FP16 caller receives that result
+converted back to FP16; its output shape and dtype are preserved.
+
+The single-scale fallback validation target is eager Wan2.2 T2V A14B on A5.
+Quality scores, optimal fallback lists, real UOS exports and additional
+compile/offload combinations require separate evaluation. Existing W4A4-only
+DualScale still needs complete 512-channel input groups; use TP=1 with
+sequence/CFG parallelism for its initial multi-card run.
+
+### `mxfp4` — Pre-Quantized Single-Scale Weights (Ascend NPU)
+
+Set the following fields in each transformer's `config.json` when a
+single-scale checkpoint uses calibrated Smooth scaling:
+
+```json
+{
+  "quantization_config": {
+    "quant_method": "mxfp4",
+    "is_checkpoint_mxfp4_serialized": true,
+    "require_smooth_scale": true,
+    "ignored_layers": []
+  }
+}
+```
+
+Each quantized Linear must provide tensors under its model parameter name:
+
+| Tensor | Checkpoint layout | Meaning |
+| -------- | ------------------- | --------- |
+| `weight` | `(N, K)` numeric FP4 values | Packed to FP4 after loading |
+| `weight_scale` | `(N, ceil(K / 32))`, `uint8` | Raw E8M0 exponent bytes, required |
+| `mul_scale` | `(K,)`, FP32 | Smooth pre-scale, required when declared above |
+
+Both W4A4 and W4A8 quantize `x * mul_scale`. The Smooth tensor is converted
+to the layer's activation dtype after loading. Row-parallel layers load the
+corresponding input-channel shard. Pre-fused QKV weights must use one shared
+Smooth tensor for the fused projection.
+
+For backward compatibility, `require_smooth_scale` defaults to `false`:
+an absent tensor uses identity scaling, while a present tensor is still loaded.
+Without a declaration, an absent Smooth tensor cannot be distinguished from a
+legacy unsmoothed checkpoint. Calibrated checkpoints should declare
+`require_smooth_scale: true` so missing or misnamed Smooth tensors fail loading;
+incorrect tensor shapes, non-floating tensors, NaN/Inf and nonpositive values
+also fail. Values that overflow or underflow to zero in the activation dtype
+are rejected during weight processing. The flag requires serialized single-scale
+weights and is rejected for online quantization. It does not make DualScale
+scales optional or change missing-parameter policies for other backends.
+Either the checkpoint or an explicit caller can require Smooth: a `true`
+declaration is retained when per-expert metadata rebuilds the configuration,
+including when the other source omits the flag or sets it to `false`.
+
+Prepare the canonical numeric FP4 checkpoint before inference using external
+tooling. Runtime loading does not parse producer-specific export formats.
+Retain the producer recipe to identify the weight-generation algorithm and
+Smooth calibration; tensor storage alone does not establish UOS provenance.
+
+### `mxfp4` — Single-Scale Block Scaling (OCP / UOS)
+
+`mxfp4_scale_alg` selects the MXFP4 block-scaling method on NPU.
+UOS is a scaling rule, not a separate activation dtype or an activation-only
+algorithm. Both choices use FP4 E2M1 values with shared E8M0 scales.
+
+| Mode | Weight preparation | A4 activation quantization | W4A8 fallback |
+| --- | --- | --- | --- |
+| Online | Selected scaling method, once at loading | Selected scaling method | Same W4; OCP MXFP8 A8 |
+| Offline | Load existing W4 and scales unchanged | Selected scaling method | Same W4; OCP MXFP8 A8 |
+
+The available settings are:
+
+| Setting | MXFP4 scaling method | NPU parameters |
+| --- | --- | --- |
+| `0` (default) | OCP MX | `scale_alg=0` |
+| `2` | UOS (`Qmax=7.25`) | `scale_alg=2, dst_type_max=7.25` |
+
+Universal Optimal Scaling (UOS, `Qmax=7.25`) is derived in
+[MXAttention: Data-Free Optimal Scaling and Pre-Normalization Quantization for MXFP4 Attention](https://arxiv.org/abs/2607.24377),
+Section 4.1. The value `7.25` is the boundary used to select the shared
+power-of-two scale; the maximum finite E2M1 value remains `6`.
+This option applies UOS to Linear quantization. It does not implement the
+paper's full MXAttention pipeline or Pre-Normalization Quantization (PNQ).
+
+Both use FP4 E2M1 with E8M0 scales, `axis=-1`, `block_size=32`,
+`round_mode="rint"`. W4A8 always quantizes the activation to
+`float8_e4m3fn` with `scale_alg=0` and the same grouping/rounding, without
+UOS parameters. A4 and A8 share the prepared W4 and scale. UOS is currently
+NPU-only; ROCm retains its existing AITER online algorithm.
+
+An explicit UOS online configuration is
+`{"method": "mxfp4", "mxfp4_scale_alg": 2}`. For offline checkpoints the
+setting affects **only A4 activations**. Existing weights are never requantized:
+a UOS checkpoint can run UOS W4 + UOS A4 or UOS W4 + OCP A4, and both fall back to
+UOS W4 + OCP A8. Record the weight-generation algorithm separately from the
+runtime activation setting. Smooth remains active with either setting. The
+UOS configuration explicitly selects `2`; attention computation is unchanged.
+
 ### `mxfp4` — Single-Scale Online Mode
 
-Online mode requires no pre-processing. vLLM-Omni quantizes BF16 weights to
-MXFP4 at load time using `npu_dynamic_mx_quant`. A single block scale
-(`float8_e8m0fnu`, one per 32 K elements) is computed on the fly; no
-calibration `mul_scale` is available. Applies equally to single-transformer
-and cascade (A14B) models — both transformers in a cascade receive the same
-quantization config automatically.
+Online mode quantizes BF16/FP16 weights once at loading and computes activation
+scales during forward. Each block of 32 K elements shares one E8M0 scale;
+no calibrated `mul_scale` is available. An explicit global quantization config
+applies to both cascade experts. Per-component configs can select different
+policies; checkpoint auto-detection resolves each expert independently.
 
 ```python
 from vllm_omni import Omni
@@ -103,7 +289,7 @@ outputs = omni.generate(
 
 ```bash
 # Single-transformer or cascade model — same command
-python text_to_video.py --model <your-model> --quantization mxfp4
+python examples/offline_inference/text_to_video/text_to_video.py --model <your-model> --quantization mxfp4
 
 # Online serving
 vllm serve <your-model> --omni --quantization mxfp4
@@ -113,19 +299,19 @@ vllm serve <your-model> --omni --quantization mxfp4
 
 Online DualScale mode computes both fine and coarse scales on the fly from BF16
 weights using `npu_dynamic_dual_level_mx_quant`. Applies equally to
-single-transformer and cascade (A14B) models. Compared to `mxfp4` online,
-DualScale provides better quantization accuracy at higher compute cost.
+single-transformer and cascade (A14B) models with compatible Linear layers.
+Compare quality and performance using the intended model and workload.
 
 The default configuration keeps the leading 5 transformer blocks in BF16
-(`num_bf16_fallback_layers=5`). Accuracy evaluation on Wan2.2-A14B shows this
-is sufficient to meet quality requirements and is the recommended setting.
+(`num_bf16_fallback_layers=5`). This is an implementation default; select and
+validate the BF16 policy against your own quality target.
 
 ```python
 omni = Omni(model="<your-model>", quantization="mxfp4_dualscale")
 ```
 
 ```bash
-python text_to_video.py --model <your-model> --quantization mxfp4_dualscale
+python examples/offline_inference/text_to_video/text_to_video.py --model <your-model> --quantization mxfp4_dualscale
 ```
 
 If accuracy debugging identifies additional precision-sensitive layers, they
@@ -136,21 +322,22 @@ omni = Omni(
     model="<your-model>",
     quantization_config={
         "method": "mxfp4_dualscale",
-        "ignored_layers": ["blocks.10.attn1.to_q"],   # explicit per-layer override
+        "ignored_layers": ["blocks.10.attn1.to_qkv"],   # explicit per-layer override
     },
 )
 ```
 
 BF16 fallback routing in online mode applies two rules in priority order:
 
-1. **`ignored_layers`** (explicit per-layer override): any layer whose prefix
-   matches is kept in BF16 regardless of block index.
+1. **`ignored_layers`** (explicit per-layer override): a listed runtime Linear
+   module is kept in BF16 regardless of block index. Use exact module paths,
+   not arbitrary block prefixes or names ending in `.weight`.
 2. **`num_bf16_fallback_layers`** (coarse leading-block rule): the first N
    transformer blocks (`blocks.0` … `blocks.N-1`) fall back to BF16. Defaults
-   to `5` (recommended). Layers outside `blocks.N.*`
-   (e.g. `condition_embedder`) are always quantized.
+   to `5`. Layers outside `blocks.N.*` are quantized unless explicitly listed
+   in `ignored_layers`.
 
-### `mxfp4_dualscale` — DualScale Offline Mode (Recommended)
+### `mxfp4_dualscale` — DualScale Offline Mode
 
 Offline mode loads a pre-quantized DualScale checkpoint from msModelSlim. A
 preprocessing step converts the raw quantized output to the diffusers format
@@ -169,8 +356,8 @@ inside `config.json`. At runtime, each layer's prefix is matched against
 Each quantized linear layer stores four tensors:
 
 | Tensor | Shape | dtype | Description |
-|--------|-------|-------|-------------|
-| `weight` | `(N, K)` | float8_e4m3fn | FP4 packed (2 values per byte) |
+| -------- | ------- | ------- | ------------- |
+| `weight` | `(N, K)` | float8_e4m3fn | Numeric FP4 values; packed into two values per byte after loading |
 | `weight_scale` | `(N, K//32)` | uint8 | Fine block scale (`float8_e8m0fnu` bit pattern) |
 | `weight_dual_scale` | `(N, K//512, 1)` | float32 | Coarse block scale |
 | `mul_scale` | `(K,)` | float32 | Per-input-channel smooth pre-scale (from calibration) |
@@ -223,7 +410,7 @@ python vllm_omni/quantization/tools/merge_mxfp4_dualscale_checkpoint.py \
 ```
 
 | Argument | Description |
-|----------|-------------|
+| ---------- | ------------- |
 | `--model-type` | Model variant: `Wan2.2-T2V-A14B` or `Wan2.2-I2V-A14B` |
 | `--original-model` | Root directory of the original BF16 diffusers model |
 | `--quant-path` | Root directory of the msModelSlim quantized output |
@@ -251,14 +438,14 @@ The `quantization_config` injected into `config.json` for each transformer:
 ```
 
 `ignored_layers` lists every linear layer that retains its original BF16 weight,
-using vllm-omni model parameter names (QKV-fused, FFN underscored, `to_out`
+using vllm-omni runtime module paths (QKV-fused, FFN underscored, `to_out`
 unindexed). The exact entries are determined by the quantization tool (msModelSlim)
 and may differ between `transformer` and `transformer_2` in a cascade model.
 
 #### Step 3 — Serve
 
 ```bash
-python text_to_video.py --model /path/to/Wan2.2-T2V-A14B-MXFP4-DualScale
+python examples/offline_inference/text_to_video/text_to_video.py --model /path/to/Wan2.2-T2V-A14B-MXFP4-DualScale
 
 # Online serving
 vllm serve /path/to/Wan2.2-T2V-A14B-MXFP4-DualScale --omni
@@ -275,25 +462,32 @@ omni = Omni(model="/path/to/Wan2.2-T2V-A14B-MXFP4-DualScale")
 
 ## Parameters
 
-### `mxfp4` (single-scale, online only)
+### `mxfp4` (single-scale, online + offline)
 
 | Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
+| ----------- | ------ | --------- | ------------- |
 | `method` | str | — | `"mxfp4"` |
-| `ignored_layers` | list[str] | `[]` | Layer prefixes to keep in BF16 |
+| `mxfp4_scale_alg` | int | `0` | MXFP4 block scaling: `0` OCP MX, `2` UOS (`Qmax=7.25`, NPU only). Online: W4 and A4; offline: A4 only. A8 remains OCP MXFP8 |
+| `is_checkpoint_mxfp4_serialized` | bool | `false` | Load pre-quantized single-scale weights and scales; declared in checkpoint `config.json` |
+| `require_smooth_scale` | bool | `false` | Require calibrated Smooth tensors for offline single-scale weights |
+| `ignored_layers` | list[str] | `[]` | Exact runtime Linear module paths to keep in BF16 |
+| `w4a8_fallback_layers` | list[str] | `[]` | Exact runtime Linear paths that always use A8; NPU only |
+| `w4a8_fallback_steps` | list[int] | `[]` | Zero-based denoise steps that use A8; NPU only |
 
 ### `mxfp4_dualscale` (dual-scale, online + offline)
 
 | Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
+| ----------- | ------ | --------- | ------------- |
 | `method` | str | — | `"mxfp4_dualscale"` |
 | `is_checkpoint_serialized` | bool | `False` | `True` for offline DualScale checkpoints; auto-set from `config.json` when using the preprocessing script |
-| `ignored_layers` | list[str] | `[]` | Layer prefixes to keep in BF16. **Works in both modes**: offline — populated by the merge script for interleaved sensitive layers; online — user-supplied for explicit per-layer precision override |
-| `num_bf16_fallback_layers` | int | `5` | **Online mode only**: leading N transformer blocks (`blocks.0` … `blocks.N-1`) kept in BF16. Applied after `ignored_layers`; ignored in offline mode. Default of `5` is the evaluated recommended value for Wan2.2-A14B |
+| `ignored_layers` | list[str] | `[]` | Exact runtime Linear module paths to keep in BF16. **Works in both modes**: offline — populated by the merge script for interleaved sensitive layers; online — user-supplied for explicit per-layer precision override |
+| `num_bf16_fallback_layers` | int | `5` | **Online mode only**: leading N transformer blocks (`blocks.0` … `blocks.N-1`) kept in BF16. Applied after `ignored_layers`; ignored in offline mode. Validate the default of `5` against the intended model and quality target |
+| `w4a8_fallback_layers` | list[str] | `[]` | Must remain empty; DualScale does not support W4A8 fallback |
+| `w4a8_fallback_steps` | list[int] | `[]` | Must remain empty; DualScale does not support W4A8 fallback |
 
 #### BF16 fallback priority (online mode)
 
-```
+```text
 for each linear layer:
     if prefix in ignored_layers               → BF16  (explicit override, highest priority)
     elif block_idx < num_bf16_fallback_layers → BF16  (coarse leading-block rule)
@@ -307,8 +501,9 @@ unless they appear in `ignored_layers`.
 
 1. **Online single-scale (`mxfp4`)** quantizes BF16 weights at load time using
    `npu_dynamic_mx_quant` (single-scale). No calibration `mul_scale` is
-   available — all output partitions receive an identity pre-scale. No offline
-   checkpoint format exists for this method.
+   available — all output partitions receive an identity pre-scale. Offline
+   single-scale checkpoints use the canonical numeric FP4 layout
+   described above.
 
 2. **Online dual-scale (`mxfp4_dualscale`, `is_checkpoint_serialized=False`)**
    quantizes BF16 weights using `npu_dynamic_dual_level_mx_quant` (fine + coarse
@@ -316,7 +511,7 @@ unless they appear in `ignored_layers`.
    explicit `ignored_layers` stay in BF16 for accuracy.
 
 3. **Offline dual-scale (`mxfp4_dualscale`, `is_checkpoint_serialized=True`)** —
-   **recommended for production** — loads four tensors per quantized layer: FP4
+   loads four tensors per quantized layer: FP4
    weight, fine scale (`uint8` reinterpreted as `float8_e8m0fnu`), coarse scale
    (`float32`), and per-input-channel `mul_scale` (`float32`). BF16 fallback
    layers have no quantization tensors and are routed via `ignored_layers`.
@@ -325,21 +520,21 @@ unless they appear in `ignored_layers`.
    layout as `float8_e8m0fnu`) and reinterpreted at load time without a lossy
    float32 round-trip.
 
-5. **Cascade model config propagation**: in a cascade model (transformer +
-   transformer_2), vLLM-Omni reads each transformer's own `config.json` and
-   rebuilds the quant config locally when `ignored_layers` differs between
-   transformers, ensuring per-layer routing is accurate for each. The first
-   transformer's config is propagated to `od_config` so the second transformer
-   can reuse it as a starting point.
+5. **Cascade model configuration**: checkpoint auto-detection resolves each
+   expert's own `config.json` independently; the first expert's detected config
+   is not reused as the second expert's policy. An explicit global runtime
+   config applies to both experts, while per-component configs select policies
+   by the exact `transformer` / `transformer_2` names. Serialized checkpoint
+   metadata still determines each expert's storage format and BF16 layers.
 
 6. **Self-attention QKV fusion**: Q, K, V projection weights are fused into a
    single `QKVParallelLinear` layer at runtime. `ignored_layers` entries use the
    fused name (`attn1.to_qkv`), written automatically by the merge script.
 
-7. W4A4 carries higher quantization noise than W8A8 (16 vs 256 levels). The
-   DualScale offline method mitigates this with calibrated `mul_scale` smooth
-   quantization. Use `ignored_layers` and `num_bf16_fallback_layers` to trade
-   off compression vs. accuracy for precision-sensitive layers.
+7. FP4 has fewer representable values than FP8, so evaluate quantization
+   error and generation quality for the chosen recipe. Offline Smooth scaling
+   and BF16 fallback can help with sensitive layers.
+   `num_bf16_fallback_layers` applies only to online DualScale.
 
 ## Adapting MXFP4 for a New Model
 
@@ -350,27 +545,26 @@ a merge script for offline checkpoints.
 
 ### Step 1 — Discover runtime layer names
 
-`ignored_layers` entries must match the **runtime parameter names** used inside
-vllm-omni, which may differ from the names stored in the diffusers checkpoint.
-The canonical source of truth is the model's own `named_parameters()`.
+`ignored_layers` entries use exact **runtime Linear module paths**, without
+`.weight`. Inspect the actual transformer instance in model initialization or
+a developer harness; `Omni` does not expose an `omni.pipeline.transformer` API.
+For a transformer instance named `transformer`:
 
 ```python
-from vllm_omni import Omni
+from vllm.model_executor.layers.linear import LinearBase
 
-# Load the model without quantization to inspect parameter names.
-omni = Omni(model="/path/to/your-model")  # no --quantization flag
-for name, _ in omni.pipeline.transformer.named_parameters():
-    if "weight" in name and "scale" not in name:
+for name, module in transformer.named_modules():
+    if isinstance(module, LinearBase):
         print(name)
 ```
 
-Compare the printed names against the diffusers checkpoint keys
+Compare these module paths against the corresponding diffusers checkpoint keys
 (`safetensors.safe_open` or `torch.load`) to identify any renames your model
 applies. Common patterns that differ in Wan2.2 (and may appear in other
 models):
 
 | Diffusers checkpoint name | vllm-omni runtime name | Reason |
-|---------------------------|------------------------|--------|
+| --------------------------- | ------------------------ | -------- |
 | `attn1.to_q`, `attn1.to_k`, `attn1.to_v` | `attn1.to_qkv` | Self-attention Q/K/V fused into `QKVParallelLinear` |
 | `ffn.net.0.proj` | `ffn.net_0.proj` | Dots in sub-module names replaced with underscores |
 | `ffn.net.2` | `ffn.net_2` | Same underscore rule |
@@ -382,8 +576,9 @@ fused runtime parameters.
 
 !!! warning "Partial QKV fallback is not allowed"
     If your model fuses Q, K, V into a single layer, `ignored_layers` must
-    include **all three or none**. A partial fallback (e.g. `to_q` in BF16 but
-    `to_k`, `to_v` quantized) cannot be expressed at runtime because they share
+    name the fused runtime module (for Wan, `attn1.to_qkv`). The source
+    checkpoint must keep **all three or none** in BF16. A partial fallback
+    (e.g. `to_q` in BF16 but `to_k`, `to_v` quantized) cannot be expressed at runtime because they share
     one `QKVParallelLinear`. The merge script enforces this and raises an error
     if only some of the trio appear as non-quantized.
 
@@ -392,12 +587,13 @@ fused runtime parameters.
 #### Online mode
 
 Pass `ignored_layers` directly in the quantization config using the **runtime
-names** discovered in Step 1. No code changes to the model are required.
+names** discovered in Step 1. This assumes the model already passes its
+quantization config and module prefixes to compatible vLLM Linear layers.
 
 ```python
 omni = Omni(
     model="/path/to/your-model",
-    quantization={
+    quantization_config={
         "method": "mxfp4_dualscale",
         "ignored_layers": [
             "blocks.0.attn1.to_qkv",   # runtime name, not diffusers name
@@ -409,9 +605,14 @@ omni = Omni(
 ```
 
 ```bash
-# CLI does not support list-typed ignored_layers directly.
-# Use the Python API or set ignored_layers in config.json (offline).
-python your_script.py --model /path/to/your-model --quantization mxfp4_dualscale
+# The text-to-video example accepts list-valued fields through JSON.
+python examples/offline_inference/text_to_video/text_to_video.py \
+    --model /path/to/your-model \
+    --quantization-config '{"method":"mxfp4_dualscale","ignored_layers":["blocks.0.attn1.to_qkv"]}'
+
+# Serving accepts the same configuration.
+vllm serve /path/to/your-model --omni \
+    --diffusion-quantization-config '{"method":"mxfp4_dualscale","ignored_layers":["blocks.0.attn1.to_qkv"]}'
 ```
 
 The `num_bf16_fallback_layers` coarse rule is an alternative to listing layers
@@ -436,9 +637,13 @@ the merge script is correct. The injected block:
 }
 ```
 
-To add a layer manually (e.g. to pin an additional layer to BF16 without
-re-running the merge script), edit `config.json` inside the transformer
-subfolder. Use runtime names, not diffusers checkpoint names.
+Adding an offline BF16 fallback layer requires both the original BF16 weight
+from the base model and a matching `ignored_layers` entry. Regenerate the
+checkpoint with the revised storage policy, restoring the original weight
+(and bias, if present) and removing that layer's quantization tensors.
+Editing `config.json` alone does not reconstruct BF16 weights from stored FP4
+values. For fused QKV, restore all three projections together. Use runtime
+module paths in `ignored_layers`.
 
 ### Step 3 — Write a merge script for offline mode
 
@@ -474,6 +679,7 @@ renaming rules and collect the results.
 !!! tip "Validate before serving"
     After producing the offline checkpoint, load it without a `--quantization`
     flag and verify that vLLM-Omni auto-detects the correct method. Check that
-    the layer count reported in the startup log matches expectations: quantized
-    layer count + `ignored_layers` count should equal total linear layer count.
-    Any mismatch indicates a name-mapping bug in the merge script.
+    each intended runtime Linear module resolves to the expected quantized or
+    BF16 method and that every BF16 entry has original BF16 weights. Account
+    for fused modules and, in online DualScale, the leading-block fallback rule;
+    the raw length of `ignored_layers` alone is not a reliable layer count.
diff --git a/examples/offline_inference/text_to_video/text_to_video.py b/examples/offline_inference/text_to_video/text_to_video.py
index 06179ef9ebf..7b7bcb890b5 100644
--- a/examples/offline_inference/text_to_video/text_to_video.py
+++ b/examples/offline_inference/text_to_video/text_to_video.py
@@ -384,13 +384,20 @@ def parse_args() -> argparse.Namespace:
         default=None,
         help='JSON profiler config for torch/cuda profiling, e.g. \'{"profiler":"torch","torch_profiler_dir":"./perf"}\'.',
     )
-    parser.add_argument(
+    quantization_group = parser.add_mutually_exclusive_group()
+    quantization_group.add_argument(
         "--quantization",
         type=str,
         default=None,
         choices=["fp8", "mxfp8", "mxfp4", "mxfp4_dualscale", "int8"],
         help="Quantization method for the transformer. mxfp8: W8A8 MXFP8 (NPU). mxfp4: W4A4 MXFP4 (NPU). mxfp4_dualscale: W4A4 MXFP4 dual-scale + BF16 fallback mixed (NPU). fp8: online FP8 (GPU).",
     )
+    quantization_group.add_argument(
+        "--quantization-config",
+        type=json.loads,
+        default=None,
+        help='Quantization JSON, e.g. \'{"method":"mxfp4","w4a8_fallback_steps":[0,2]}\'.',
+    )
 
     # Distributed and parallel execution
     parser.add_argument(
@@ -572,6 +579,8 @@ def main():
         omni_kwargs["flow_shift"] = args.flow_shift
     if args.quantization is not None:
         omni_kwargs["quantization"] = args.quantization
+    if args.quantization_config is not None:
+        omni_kwargs["quantization_config"] = args.quantization_config
     if args.cache_backend is not None:
         omni_kwargs["cache_backend"] = args.cache_backend
         omni_kwargs["cache_config"] = cache_config
diff --git a/tests/config/test_omni_config.py b/tests/config/test_omni_config.py
index e0a5ad9b04d..1ed62f7f1fc 100644
--- a/tests/config/test_omni_config.py
+++ b/tests/config/test_omni_config.py
@@ -1480,7 +1480,7 @@ def test_from_pipeline_config_normalizes_diffusion_config_aliases_from_engine_ar
     from vllm_omni.diffusion.data import OmniDiffusionConfig
     from vllm_omni.engine.stage_init_utils import build_engine_args_dict_from_omni_stage_config
 
-    engine_args = build_engine_args_dict_from_omni_stage_config(stage, model="test-model")
+    engine_args = build_engine_args_dict_from_omni_stage_config(stage, model=str(tmp_path))
     od_config = OmniDiffusionConfig.from_kwargs(**engine_args)
     assert od_config.kv_transfer_config.engine_id == "dit-engine-1"
 
@@ -1739,3 +1739,31 @@ def test_async_chunk_rejects_mismatched_connector_edge(disabled_stage, builder):
             builder(pipeline, deploy)
         else:
             builder(pipeline, user_deploy_config=deploy)
+
+
+@pytest.mark.parametrize("explicit", [False, True])
+def test_diffusion_quantization_origin_survives_projection_and_transport(monkeypatch, explicit):
+    from vllm_omni.diffusion.data import OmniDiffusionConfig, TransformerConfig
+    from vllm_omni.quantization import build_quant_config
+
+    checkpoint = TransformerConfig.from_dict(
+        {
+            "quantization_config": {
+                "quant_method": "mxfp4",
+                "is_checkpoint_mxfp4_serialized": True,
+                "w4a8_fallback_steps": [37],
+            }
+        }
+    )
+    requested = build_quant_config("mxfp4", w4a8_fallback_steps=[]) if explicit else None
+    cfg = omni_config_module._DiffusionConfigProjection.from_kwargs(
+        tf_model_config=checkpoint,
+        quantization_config=requested,
+    )
+    assert cfg.quantization_config_is_auto_detected is not explicit
+    monkeypatch.setattr(OmniDiffusionConfig, "_resolve_master_port", lambda _self: 29500)
+    monkeypatch.setattr(OmniDiffusionConfig, "enrich_config", lambda self: self.set_tf_model_config(checkpoint))
+    cfg.enrich_config()
+    restored = ForkingPickler.loads(ForkingPickler.dumps(cfg))
+    assert restored.quantization_config_is_auto_detected is not explicit
+    assert restored.quantization_config.w4a8_fallback_steps == ([] if explicit else [37])
diff --git a/tests/diffusion/models/wan2_2/test_create_transformer_quant.py b/tests/diffusion/models/wan2_2/test_create_transformer_quant.py
index bb95363fde8..b01f275eb78 100644
--- a/tests/diffusion/models/wan2_2/test_create_transformer_quant.py
+++ b/tests/diffusion/models/wan2_2/test_create_transformer_quant.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Regression tests for transformer quant-config auto-detection.
 
 The loader path at pipeline_wan2_2.py carries two quantization contracts:
@@ -27,6 +27,7 @@
 import pytest
 
 import vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 as wan22_module
+from vllm_omni.diffusion.data import OmniDiffusionConfig
 from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import create_transformer_from_config
 
 pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
@@ -381,3 +382,213 @@ def test_pipeline_cascade_mxfp4_dualscale_each_transformer_gets_correct_ignored_
 
     # od_config must remain unchanged — _create_transformer does not modify it.
     assert od_config.quantization_config is None
+
+
+def _construct_quantized_pipeline(pipeline_kind, active, disk_quant_config, tmp_path, monkeypatch):
+    import json
+
+    import torch
+
+    import vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_i2v as i2v_module
+    import vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_vace as vace_module
+
+    monkeypatch.setattr("vllm_omni.platforms.current_omni_platform.is_npu", lambda: True)
+    for component in ("transformer", "transformer_2"):
+        directory = tmp_path / component
+        directory.mkdir()
+        config = dict(_MIN_CFG)
+        expert_quant_config = (
+            disk_quant_config[0 if component == "transformer" else 1]
+            if isinstance(disk_quant_config, tuple)
+            else disk_quant_config
+        )
+        if expert_quant_config is not None:
+            config["quantization_config"] = expert_quant_config
+        (directory / "config.json").write_text(json.dumps(config))
+    (tmp_path / "model_index.json").write_text(json.dumps({"transformer_2": ["diffusers", "WanTransformer3DModel"]}))
+
+    class FakeComponent(torch.nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.config = SimpleNamespace(scale_factor_temporal=4, scale_factor_spatial=8)
+
+    class FakeTransformer(FakeComponent):
+        def __init__(self, quant_config=None, **kwargs):
+            super().__init__()
+            self.received_quant_config = quant_config
+
+    for module in (wan22_module, i2v_module):
+        monkeypatch.setattr(module, "get_local_device", lambda: torch.device("cpu"))
+        monkeypatch.setattr(module, "prefetch_subfolders", lambda *args, **kwargs: None)
+        monkeypatch.setattr(module, "from_pretrained_with_prefetch", lambda *args, **kwargs: FakeComponent())
+    monkeypatch.setattr(wan22_module, "WanTransformer3DModel", FakeTransformer)
+    monkeypatch.setattr(vace_module, "WanVACETransformer3DModel", FakeTransformer)
+    pipeline_cls = {
+        "t2v": wan22_module.Wan22Pipeline,
+        "i2v": i2v_module.Wan22I2VPipeline,
+        "vace": vace_module.Wan22VACEPipeline,
+    }[pipeline_kind]
+    monkeypatch.setattr(pipeline_cls, "setup_diffusion_pipeline_profiler", lambda *args, **kwargs: None)
+    od_config = OmniDiffusionConfig(
+        model=str(tmp_path),
+        model_class_name=pipeline_cls.__name__,
+        dtype=torch.bfloat16,
+        quantization_config=active,
+        boundary_ratio=0.875,
+        flow_shift=12.0,
+        enable_diffusion_pipeline_profiler=False,
+    )
+    od_config.enrich_config()
+    pipeline = pipeline_cls(od_config=od_config)
+    return pipeline
+
+
+@pytest.mark.parametrize("pipeline_kind", ["t2v", "i2v", "vace"])
+@pytest.mark.parametrize("method, flag", [("mxfp4", "is_checkpoint_mxfp4_serialized")])
+@pytest.mark.parametrize("offline", [False, True])
+def test_pipeline_constructor_routes_each_expert_quantization(
+    pipeline_kind, method, flag, offline, tmp_path, monkeypatch, mocker
+):
+    """Run the actual pipeline constructors, expert factories and quant-method dispatch."""
+    from vllm.model_executor.layers.linear import LinearBase, UnquantizedLinearMethod
+
+    from vllm_omni.quantization import build_quant_config
+
+    active = build_quant_config(
+        {
+            "transformer": {
+                "method": method,
+                "w4a8_fallback_layers": ["blocks.10.attn1.to_qkv"],
+                "w4a8_fallback_steps": [0, 1],
+            },
+            "transformer_2": {
+                "method": method,
+                "w4a8_fallback_layers": ["blocks.11.attn1.to_qkv"],
+                "w4a8_fallback_steps": [],
+            },
+        }
+    )
+    disk_quant_config = None
+    if offline:
+        disk_quant_config = {
+            "quant_method": method,
+            flag: True,
+            "ignored_layers": ["blocks.12.ffn.net_2"],
+            "w4a8_fallback_layers": ["blocks.9.attn1.to_qkv"],
+            "w4a8_fallback_steps": [9],
+        }
+    pipeline = _construct_quantized_pipeline(pipeline_kind, active, disk_quant_config, tmp_path, monkeypatch)
+    for index, transformer in enumerate((pipeline.transformer, pipeline.transformer_2)):
+        received = transformer.received_quant_config
+        assert received.get_name() == method
+        assert getattr(received, flag) == offline
+        assert received.w4a8_fallback_steps == ([0, 1] if index == 0 else [])
+        selected = f"blocks.{10 + index}.attn1.to_qkv"
+        other = f"blocks.{11 - index}.attn1.to_qkv"
+        assert received.w4a8_fallback_layers == [selected]
+        assert received.get_quant_method(mocker.Mock(spec=LinearBase), selected).is_w4a8_fallback_layer
+        assert not received.get_quant_method(mocker.Mock(spec=LinearBase), other).is_w4a8_fallback_layer
+        if offline:
+            assert isinstance(
+                received.get_quant_method(mocker.Mock(spec=LinearBase), "blocks.12.ffn.net_2"), UnquantizedLinearMethod
+            )
+    assert pipeline.od_config.quantization_config is active
+
+
+@pytest.mark.parametrize("explicit_none", [False, True])
+def test_pipeline_disabled_component_requires_unquantized_checkpoint(explicit_none, monkeypatch):
+    from vllm_omni.quantization import build_quant_config
+
+    FakeTransformer, captured = _make_fake_transformer()
+    monkeypatch.setattr(wan22_module, "WanTransformer3DModel", FakeTransformer)
+    components = {"transformer": {"method": "mxfp4"}, "transformer_2": None} if explicit_none else {"vae": None}
+    active = build_quant_config(components)
+    pipeline = _FakePipeline(OmniDiffusionConfig(model="", quantization_config=active))
+    pipeline._create_transformer(_MIN_CFG, component="transformer_2")
+    assert captured[-1].get("quant_config") is None
+    with pytest.raises(ValueError, match="disabled for component 'transformer_2'"):
+        pipeline._create_transformer(
+            {**_MIN_CFG, "quantization_config": {"quant_method": "mxfp4", "is_checkpoint_mxfp4_serialized": True}},
+            component="transformer_2",
+        )
+
+
+def test_pipeline_component_default_reaches_expert_factory(monkeypatch):
+    from vllm_omni.quantization import build_quant_config
+
+    FakeTransformer, captured = _make_fake_transformer()
+    monkeypatch.setattr(wan22_module, "WanTransformer3DModel", FakeTransformer)
+    active = build_quant_config({"default": {"method": "mxfp4", "w4a8_fallback_layers": ["blocks.10.attn1.to_qkv"]}})
+    pipeline = _FakePipeline(OmniDiffusionConfig(model="", quantization_config=active))
+    pipeline._create_transformer(_MIN_CFG, component="transformer_2")
+    assert captured[-1]["quant_config"] is active.default_config
+
+
+@pytest.mark.parametrize("pipeline_kind", ["t2v", "i2v", "vace"])
+@pytest.mark.parametrize(
+    "configured_expert, with_default",
+    [
+        ("transformer", False),
+        ("transformer", True),
+        ("transformer_2", False),
+        ("transformer_2", True),
+    ],
+)
+def test_pipeline_partial_expert_config_does_not_match_sibling(
+    pipeline_kind, configured_expert, with_default, tmp_path, monkeypatch
+):
+    from vllm_omni.quantization import build_quant_config
+
+    component_spec = {
+        configured_expert: {"method": "mxfp4", "w4a8_fallback_layers": ["blocks.10.attn1.to_qkv"]},
+    }
+    if with_default:
+        component_spec["default"] = {"method": "mxfp4", "w4a8_fallback_layers": ["blocks.11.attn1.to_qkv"]}
+    active = build_quant_config(component_spec)
+    pipeline = _construct_quantized_pipeline(pipeline_kind, active, None, tmp_path, monkeypatch)
+    sibling = "transformer_2" if configured_expert == "transformer" else "transformer"
+    selected = getattr(pipeline, configured_expert).received_quant_config
+    other = getattr(pipeline, sibling).received_quant_config
+    assert selected is active.component_configs[configured_expert]
+    assert other is active.default_config
+    if with_default:
+        assert other.w4a8_fallback_layers == ["blocks.11.attn1.to_qkv"]
+    else:
+        assert other is None
+
+
+@pytest.mark.parametrize("pipeline_kind", ["t2v", "i2v", "vace"])
+@pytest.mark.parametrize("different_ignored_layers", [False, True])
+def test_enriched_auto_quantization_preserves_each_expert_policy(
+    pipeline_kind, different_ignored_layers, tmp_path, monkeypatch
+):
+    """Startup auto-detection must not turn the first expert into a user override."""
+    high = {
+        "quant_method": "mxfp4",
+        "is_checkpoint_mxfp4_serialized": True,
+        "ignored_layers": ["blocks.0.ffn.net_2"],
+        "w4a8_fallback_steps": [],
+        "w4a8_fallback_layers": [],
+        "mxfp4_scale_alg": 0,
+        "require_smooth_scale": False,
+    }
+    low = {
+        **high,
+        "ignored_layers": ["blocks.1.ffn.net_2"] if different_ignored_layers else high["ignored_layers"],
+        "w4a8_fallback_steps": [37],
+        "w4a8_fallback_layers": ["blocks.11.attn1.to_qkv"],
+        "mxfp4_scale_alg": 2,
+        "require_smooth_scale": True,
+    }
+    pipeline = _construct_quantized_pipeline(pipeline_kind, None, (high, low), tmp_path, monkeypatch)
+    assert pipeline.od_config.quantization_config is not None  # enrich_config really detected the first expert.
+    for transformer, expected in [(pipeline.transformer, high), (pipeline.transformer_2, low)]:
+        config = transformer.received_quant_config
+        for policy in (
+            "ignored_layers",
+            "w4a8_fallback_steps",
+            "w4a8_fallback_layers",
+            "mxfp4_scale_alg",
+            "require_smooth_scale",
+        ):
+            assert getattr(config, policy) == expected[policy], policy
diff --git a/tests/diffusion/models/wan2_2/test_wan22_pipeline_diffuse.py b/tests/diffusion/models/wan2_2/test_wan22_pipeline_diffuse.py
index 526eeeb1568..58a5e961bd7 100644
--- a/tests/diffusion/models/wan2_2/test_wan22_pipeline_diffuse.py
+++ b/tests/diffusion/models/wan2_2/test_wan22_pipeline_diffuse.py
@@ -20,9 +20,11 @@
 
 
 @pytest.fixture(autouse=True)
-def _cpu_platform(monkeypatch):
+def _cpu_pipeline_runtime(monkeypatch):
+    # These lightweight pipelines have no accelerator or distributed groups.
     module = importlib.import_module("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2")
     monkeypatch.setattr(module.current_omni_platform, "is_available", lambda: False)
+    monkeypatch.setattr("vllm_omni.diffusion.distributed.parallel_state._PP", SimpleNamespace(world_size=1))
 
 
 class _StubTransformer(nn.Module):
@@ -477,6 +479,100 @@ def _fake_scheduler_step_maybe_with_cfg(noise_pred, t, current_latents, do_true_
     assert torch.equal(result, torch.full_like(latents, 10.0))
 
 
+@pytest.mark.parametrize("fail_first_request", [False, True])
+def test_runner_publishes_wan_step_context_across_requests(fail_first_request, monkeypatch):
+    from vllm_omni.diffusion.data import OmniDiffusionConfig
+    from vllm_omni.diffusion.forward_context import (
+        ForwardContext,
+        get_forward_context,
+        is_forward_context_available,
+        override_forward_context,
+    )
+    from vllm_omni.diffusion.worker.diffusion_model_runner import DiffusionModelRunner
+    from vllm_omni.quantization.mxfp4_config import _is_w4a8_fallback_step
+
+    contexts: list[ForwardContext] = []
+    events = []
+
+    class InjectedPredictionError(Exception):
+        pass
+
+    class RecordingTransformer(_StubTransformer):
+        def __init__(self, expert):
+            super().__init__()
+            self.expert = expert
+
+        def forward(self, hidden_states, encoder_hidden_states, **kwargs):
+            context = get_forward_context()
+            assert context is contexts[-1]
+            request_index = len(contexts) - 1
+            step = context.denoise_step_idx
+            positive = bool(encoder_hidden_states[0, 0, 0] > 0)
+            events.append((request_index, step, self.expert, positive, _is_w4a8_fallback_step([0, 2])))
+            if fail_first_request and request_index == 0 and step == 1 and not positive:
+                raise InjectedPredictionError
+            return (torch.ones_like(hidden_states) * (1 if positive else -1),)
+
+    def encode_prompt(**kwargs):
+        context = get_forward_context()
+        assert context.denoise_step_idx is None
+        contexts.append(context)
+        embeds = torch.ones(1, 8, 8)
+        return embeds, -embeds
+
+    pipeline = _make_pipeline()
+    pipeline.transformer = RecordingTransformer("high")
+    pipeline.transformer_2 = RecordingTransformer("low")
+    pipeline.scheduler = _StubScheduler([900, 500, 100])
+    monkeypatch.setattr(pipeline, "encode_prompt", encode_prompt)
+    monkeypatch.setattr(pipeline, "scheduler_step_maybe_with_cfg", lambda pred, t, latents, cfg: latents)
+
+    # Use the real runner context manager, Wan forward/diffuse, and CFG
+    # dispatch. Only model computation, scheduler math and unrelated KV I/O
+    # are replaced; no test code publishes a denoise step.
+    runner = object.__new__(DiffusionModelRunner)
+    runner.pipeline = pipeline
+    runner.od_config = OmniDiffusionConfig(model="", dtype=torch.float32)
+    runner.vllm_config = None
+    runner.cache_backend = None
+    monkeypatch.setattr(runner, "_prepare_request_for_forward", lambda *args, **kwargs: None)
+    with override_forward_context(None):
+        for request_index in range(2):
+            request = OmniDiffusionRequest(
+                prompt="a fox walks",
+                request_id=f"request-{request_index}",
+                sampling_params=OmniDiffusionSamplingParams(
+                    num_frames=1, num_inference_steps=3, guidance_scale=2.0, output_type="latent"
+                ),
+            )
+
+            def execute():
+                return runner._execute_request_list(
+                    [request],
+                    od_config=runner.od_config,
+                    allow_single_output=True,
+                    require_request_batch_support=False,
+                    record_name="test_wan_step_context",
+                    record_output_peak_memory=False,
+                )
+
+            if fail_first_request and request_index == 0:
+                with pytest.raises(InjectedPredictionError):
+                    execute()
+            else:
+                execute()
+            assert not is_forward_context_available()
+
+    assert len(contexts) == 2 and contexts[0] is not contexts[1]
+    expected = [
+        (request, step, "high" if step == 0 else "low", positive, step in (0, 2))
+        for request in range(2)
+        for step in range(2 if fail_first_request and request == 0 else 3)
+        for positive in (True, False)
+    ]
+    assert events == expected
+
+
 class _StubDMDScheduler:
     def __init__(self) -> None:
         self.predict_clean_calls: list[tuple[float, float, float]] = []
diff --git a/tests/diffusion/quantization/test_mxfp4_checkpoint.py b/tests/diffusion/quantization/test_mxfp4_checkpoint.py
new file mode 100644
index 00000000000..e183df07824
--- /dev/null
+++ b/tests/diffusion/quantization/test_mxfp4_checkpoint.py
@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""CPU coverage for MXFP4 checkpoint loading and the W4A8 dtype contract."""
+
+import sys
+from types import ModuleType
+
+import pytest
+import torch
+from vllm.config.load import LoadConfig
+from vllm.model_executor.model_loader.weight_utils import default_weight_loader
+
+from vllm_omni.diffusion.data import OmniDiffusionConfig
+from vllm_omni.diffusion.forward_context import (
+    ForwardContext,
+    override_forward_context,
+    set_forward_context_denoise_step_idx,
+)
+from vllm_omni.diffusion.model_loader.diffusers_loader import DiffusersPipelineLoader
+from vllm_omni.quantization.mxfp4_config import (
+    DiffusionMXFP4Config,
+    DiffusionMXFP4DualScaleMixedConfig,
+    NPUMxfp4DualScaleLinearMethod,
+    NPUMxfp4LinearMethod,
+    NPUMxfp4OnlineLinearMethod,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+@pytest.fixture(autouse=True)
+def _patch_tp_state(monkeypatch):
+    monkeypatch.setattr("vllm.model_executor.parameter.get_tensor_model_parallel_rank", lambda: 0)
+    monkeypatch.setattr("vllm.model_executor.parameter.get_tensor_model_parallel_world_size", lambda: 1)
+
+
+class _CheckpointLayer(torch.nn.Module):
+    def __init__(self, method, dtype=torch.bfloat16):
+        super().__init__()
+        method.create_weights(
+            self,
+            input_size_per_partition=512,
+            output_partition_sizes=[2],
+            input_size=512,
+            output_size=2,
+            params_dtype=dtype,
+            weight_loader=default_weight_loader,
+        )
+
+    def load_weights(self, weights):
+        params = dict(self.named_parameters())
+        loaded = set()
+        for name, value in weights:
+            if name in params:
+                params[name].weight_loader(params[name], value)
+                loaded.add(name)
+        return loaded
+
+
+def _load_checkpoint(layer, config, weights, monkeypatch):
+    od_config = OmniDiffusionConfig(model="", dtype=torch.bfloat16, quantization_config=config)
+    loader = DiffusersPipelineLoader(LoadConfig(), od_config)
+    loader.counter_before_loading_weights = 0.0
+    monkeypatch.setattr(loader, "get_all_weights", lambda model: iter(weights.items()))
+    loader.load_weights(layer)
+
+
+@pytest.mark.parametrize("serialized", [False, True])
+def test_single_scale_requires_checkpoint_scale_only_when_serialized(serialized, monkeypatch):
+    config = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=serialized)
+    # Exercise the shared implementation directly as well as the online MRO
+    # below: checkpoint requirements must follow the configured storage mode.
+    layer = _CheckpointLayer(NPUMxfp4LinearMethod(config))
+    weights = {"weight": torch.ones((2, 512), dtype=torch.bfloat16)}
+    if serialized:
+        with pytest.raises(ValueError, match="Required weights.*weight_scale"):
+            _load_checkpoint(layer, config, weights, monkeypatch)
+    else:
+        _load_checkpoint(layer, config, weights, monkeypatch)
+
+
+@pytest.mark.parametrize("scale_alg", [0, 2])
+def test_online_mxfp4_loads_bf16_checkpoint_without_scale(scale_alg, monkeypatch):
+    config = DiffusionMXFP4Config(mxfp4_scale_alg=scale_alg)
+    method = NPUMxfp4OnlineLinearMethod(config)
+    layer = _CheckpointLayer(method)
+    assert set(dict(layer.named_parameters())) == {"weight"}
+    assert layer.weight.is_meta
+
+    weight = torch.arange(1024, dtype=torch.bfloat16).reshape(2, 512)
+    packed_weight = torch.zeros((2, 256), dtype=torch.uint8)
+    generated_scale = torch.full((2, 16), 127, dtype=torch.uint8)
+    quantized_inputs = []
+
+    def quantize(value, **kwargs):
+        quantized_inputs.append(value.clone())
+        expected = dict(dst_type="fp4", axis=-1, block_size=32, round_mode="rint", scale_alg=scale_alg)
+        if scale_alg == 2:
+            expected["dst_type_max"] = 7.25
+        assert kwargs == expected
+        return packed_weight, generated_scale
+
+    # Keep real creation, lazy loading, processing, and strict loader checks;
+    # substitute only the device quantization operator for this CPU test.
+    npu = ModuleType("torch_npu")
+    npu.__dict__.update(float4_e2m1fn_x2="fp4", npu_dynamic_mx_quant=quantize)
+    monkeypatch.setitem(sys.modules, "torch_npu", npu)
+    _load_checkpoint(layer, config, {"weight": weight}, monkeypatch)
+
+    assert len(quantized_inputs) == 1
+    torch.testing.assert_close(quantized_inputs[0], weight, rtol=0, atol=0)
+    torch.testing.assert_close(layer.weight, packed_weight, rtol=0, atol=0)
+    torch.testing.assert_close(layer.weight_scale, generated_scale.reshape(2, 8, 2), rtol=0, atol=0)
+    assert not getattr(layer.weight_scale, "is_checkpoint_required", False)
+    method.process_weights_after_loading(layer)
+    assert len(quantized_inputs) == 1
+
+
+@pytest.mark.parametrize("require_smooth", [False, True])
+@pytest.mark.parametrize("has_smooth", [False, True])
+def test_single_scale_checkpoint_smooth_default_and_required(require_smooth, has_smooth, monkeypatch):
+    config = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True, require_smooth_scale=require_smooth)
+    layer = _CheckpointLayer(NPUMxfp4LinearMethod(config))
+    weights = {name: torch.ones_like(param) for name, param in layer.named_parameters()}
+    scale = torch.linspace(0.5, 3.0, 512)
+    if has_smooth:
+        weights["mul_scale"] = scale
+    else:
+        weights.pop("mul_scale")
+
+    if require_smooth and not has_smooth:
+        with pytest.raises(ValueError, match="mul_scale"):
+            _load_checkpoint(layer, config, weights, monkeypatch)
+    else:
+        _load_checkpoint(layer, config, weights, monkeypatch)
+        torch.testing.assert_close(layer.mul_scale, scale if has_smooth else torch.ones(512), rtol=0, atol=0)
+
+
+@pytest.mark.parametrize("bad_scale", ["shape", "name"])
+def test_declared_single_scale_smooth_rejects_malformed_checkpoint(bad_scale, monkeypatch):
+    config = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True, require_smooth_scale=True)
+    layer = _CheckpointLayer(NPUMxfp4LinearMethod(config))
+    weights = {name: torch.ones_like(param) for name, param in layer.named_parameters()}
+    if bad_scale == "shape":
+        weights["mul_scale"] = torch.ones(511)
+        with pytest.raises(AssertionError):
+            _load_checkpoint(layer, config, weights, monkeypatch)
+    else:
+        weights["multiply_scale"] = weights.pop("mul_scale")
+        with pytest.raises(ValueError, match="mul_scale"):
+            _load_checkpoint(layer, config, weights, monkeypatch)
+
+
+@pytest.mark.parametrize("required", [False, True])
+@pytest.mark.parametrize("bad_value", [float("nan"), float("inf"), 0.0, -1.0])
+def test_single_scale_rejects_invalid_smooth_values(required, bad_value, monkeypatch):
+    config = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True, require_smooth_scale=required)
+    layer = _CheckpointLayer(NPUMxfp4LinearMethod(config))
+    weights = {name: torch.ones_like(param) for name, param in layer.named_parameters()}
+    weights["mul_scale"][7] = bad_value
+    with pytest.raises(ValueError, match="finite, strictly positive"):
+        _load_checkpoint(layer, config, weights, monkeypatch)
+
+
+@pytest.mark.parametrize("bad_scale", [torch.ones(512, dtype=torch.int32), torch.ones(1, 512)])
+def test_single_scale_rejects_invalid_smooth_type_or_rank(bad_scale, monkeypatch):
+    config = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True)
+    layer = _CheckpointLayer(NPUMxfp4LinearMethod(config))
+    weights = {name: torch.ones_like(param) for name, param in layer.named_parameters()}
+    weights["mul_scale"] = bad_scale
+    with pytest.raises(ValueError, match="one-dimensional floating-point"):
+        _load_checkpoint(layer, config, weights, monkeypatch)
+
+
+@pytest.mark.parametrize("bad_value", [1e10, 1e-10])
+def test_single_scale_rejects_smooth_overflow_or_underflow_after_cast(bad_value, monkeypatch):
+    config = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True)
+    method = NPUMxfp4LinearMethod(config)
+    layer = _CheckpointLayer(method, torch.float16)
+    layer.mul_scale.data.fill_(bad_value)
+    # Validation must fail before any device packing or GEMM.
+    monkeypatch.setitem(sys.modules, "torch_npu", ModuleType("torch_npu"))
+    with pytest.raises(ValueError, match="finite, strictly positive"):
+        method.process_weights_after_loading(layer)
+
+
+@pytest.mark.parametrize(
+    ("mode", "missing"),
+    [
+        ("single", "weight"),
+        ("single", "weight_scale"),
+        ("dual", "weight"),
+        ("dual", "weight_scale"),
+        ("dual", "weight_dual_scale"),
+        ("dual", "mul_scale"),
+    ],
+)
+def test_offline_mxfp4_required_tensors_do_not_use_legacy_scale_tolerance(mode, missing, monkeypatch):
+    if mode == "single":
+        config = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True)
+        method = NPUMxfp4LinearMethod(config)
+    else:
+        config = DiffusionMXFP4DualScaleMixedConfig(is_checkpoint_serialized=True)
+        method = NPUMxfp4DualScaleLinearMethod(config)
+    layer = _CheckpointLayer(method)
+    weights = {name: torch.ones_like(param) for name, param in layer.named_parameters() if name != missing}
+    with pytest.raises(ValueError, match=missing):
+        _load_checkpoint(layer, config, weights, monkeypatch)
+
+
+@pytest.mark.parametrize("rank", [0, 1])
+def test_single_scale_smooth_uses_real_row_parallel_loader(rank):
+    from vllm.model_executor.layers.linear import RowParallelLinear
+
+    layer = _CheckpointLayer(NPUMxfp4LinearMethod(DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True)))
+    layer.tp_rank = rank
+    checkpoint_scale = torch.arange(1024, dtype=torch.float32)
+    RowParallelLinear.weight_loader(layer, layer.mul_scale, checkpoint_scale)
+    torch.testing.assert_close(layer.mul_scale, checkpoint_scale[rank * 512 : (rank + 1) * 512], rtol=0, atol=0)
+
+
+@pytest.mark.parametrize("dtype", [torch.bfloat16, torch.float16])
+@pytest.mark.parametrize("fallback", [False, True])
+@pytest.mark.parametrize("with_bias", [False, True])
+@pytest.mark.parametrize("scale_alg", [0, 2])
+def test_single_scale_smooth_precedes_quantization_and_preserves_output(
+    dtype, fallback, with_bias, scale_alg, monkeypatch
+):
+    config = DiffusionMXFP4Config(
+        is_checkpoint_mxfp4_serialized=True, w4a8_fallback_steps=[0], mxfp4_scale_alg=scale_alg
+    )
+    method = NPUMxfp4LinearMethod(config)
+    layer = _CheckpointLayer(method, dtype)
+    weights = {
+        "weight": torch.linspace(-0.5, 1.5, 1024, dtype=dtype).reshape(2, 512),
+        "weight_scale": torch.full((2, 16), 127, dtype=torch.uint8),
+        "mul_scale": torch.linspace(0.5, 3.0, 512),
+    }
+    _load_checkpoint(layer, config, weights, monkeypatch)
+    x = torch.linspace(-1.0, 2.0, 3072, dtype=dtype).reshape(2, 3, 512)
+    bias = torch.tensor([0.5, -1.0], dtype=dtype) if with_bias else None
+    quantized_inputs = []
+
+    # Only the two device operators are substituted. Exercise real apply(),
+    # step selection, Smooth multiplication, bias handling, and reshape logic.
+    npu = ModuleType("torch_npu")
+
+    def quantize(value, **kwargs):
+        quantized_inputs.append(value.clone())
+        expected = dict(
+            dst_type=torch.float8_e4m3fn if fallback else "fp4",
+            axis=-1,
+            block_size=32,
+            round_mode="rint",
+            scale_alg=0 if fallback else scale_alg,
+        )
+        if not fallback and scale_alg == 2:
+            expected["dst_type_max"] = 7.25
+        assert kwargs == expected
+        return value, torch.ones((6, 16), dtype=torch.uint8)
+
+    def matmul(x_q, weight, weight_scale, *, bias, output_dtype, **kwargs):
+        if fallback:
+            assert output_dtype == torch.bfloat16
+            if bias is not None:
+                assert bias.dtype == output_dtype
+                assert bias.shape == (1, 2)
+        result = x_q.float() @ weight.float()
+        if bias is not None:
+            result += bias.float()
+        return result.to(output_dtype)
+
+    npu.__dict__.update(
+        float8_e4m3fn=torch.float8_e4m3fn,
+        float8_e8m0fnu=torch.uint8,
+        float4_e2m1fn_x2="fp4",
+        npu_dynamic_mx_quant=quantize,
+        npu_quant_matmul=matmul,
+    )
+    monkeypatch.setitem(sys.modules, "torch_npu", npu)
+    with override_forward_context(ForwardContext()):
+        set_forward_context_denoise_step_idx(0 if fallback else 1)
+        result = method.apply(layer, x, bias)
+
+    expected_input = x.reshape(-1, 512) * weights["mul_scale"].to(dtype)
+    assert len(quantized_inputs) == 1
+    torch.testing.assert_close(quantized_inputs[0], expected_input, rtol=0, atol=0)
+    expected = expected_input.float() @ weights["weight"].float().T
+    if bias is not None:
+        expected += bias.float()
+    if fallback:
+        expected = expected.bfloat16()
+    torch.testing.assert_close(result, expected.to(dtype).reshape(2, 3, 2), rtol=0, atol=0)
+    assert result.dtype == dtype
diff --git a/tests/diffusion/quantization/test_mxfp4_config.py b/tests/diffusion/quantization/test_mxfp4_config.py
index 240ee250941..c51b2013b27 100644
--- a/tests/diffusion/quantization/test_mxfp4_config.py
+++ b/tests/diffusion/quantization/test_mxfp4_config.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Tests for MXFP4 quantization configs and the MXFP4 DualScale + BF16 mixed config."""
 
 import pytest
@@ -27,12 +27,42 @@ def test_mxfp4_config_get_name():
     assert DiffusionMXFP4Config.get_name() == "mxfp4"
 
 
+@pytest.mark.parametrize("value", [True, False, None, "2", 2.0, 1, -1, 3])
+def test_mxfp4_scale_alg_rejects_invalid_values(value):
+    from vllm_omni.quantization import build_quant_config
+
+    with pytest.raises(ValueError, match="mxfp4_scale_alg"):
+        build_quant_config({"method": "mxfp4", "mxfp4_scale_alg": value})
+
+
+@pytest.mark.parametrize("runtime_alg", [0, 2])
+@pytest.mark.parametrize("serialized", [False, True])
+def test_runtime_algorithm_survives_offline_storage_rebuild(runtime_alg, serialized):
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+    from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
+
+    active = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=serialized, mxfp4_scale_alg=runtime_alg)
+    resolved = resolve_quant_config_from_disk(
+        active,
+        {
+            "quant_method": "mxfp4",
+            "is_checkpoint_mxfp4_serialized": True,
+            "mxfp4_scale_alg": 2,
+            "ignored_layers": ["proj_out"],
+        },
+    )
+    assert resolved.is_checkpoint_mxfp4_serialized
+    assert resolved.mxfp4_scale_alg == runtime_alg
+    assert resolved.w4a8_fallback_layers == resolved.w4a8_fallback_steps == []
+
+
 def test_mxfp4_config_from_config_defaults():
     from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
 
     cfg = DiffusionMXFP4Config.from_config({})
     assert cfg.is_checkpoint_mxfp4_serialized is False
     assert cfg.ignored_layers == []
+    assert cfg.w4a8_fallback_layers == []
 
 
 def test_mxfp4_config_from_config_serialized():
@@ -42,6 +72,98 @@ def test_mxfp4_config_from_config_serialized():
     assert cfg.is_checkpoint_mxfp4_serialized is True
 
 
+def test_mxfp4_config_requires_offline_smooth():
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
+
+    values = {"is_checkpoint_mxfp4_serialized": True, "require_smooth_scale": True}
+    assert DiffusionMXFP4Config.from_config(values).require_smooth_scale
+    assert build_quant_config({"method": "mxfp4", **values}).require_smooth_scale
+    with pytest.raises(ValueError, match="offline"):
+        build_quant_config({"method": "mxfp4", "require_smooth_scale": True})
+    with pytest.raises(ValueError, match="boolean"):
+        DiffusionMXFP4Config.from_config({**values, "require_smooth_scale": "false"})
+
+
+@pytest.mark.parametrize("serialized", [False, True])
+def test_mxfp4_disk_smooth_requirement_preserves_step_policy(serialized):
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+    from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
+
+    active = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=serialized, w4a8_fallback_steps=[1])
+    resolved = resolve_quant_config_from_disk(
+        active,
+        {
+            "quant_method": "mxfp4",
+            "is_checkpoint_mxfp4_serialized": True,
+            "require_smooth_scale": True,
+        },
+    )
+    assert resolved.require_smooth_scale
+    assert resolved.is_checkpoint_mxfp4_serialized
+    assert resolved.w4a8_fallback_steps == [1]
+
+
+@pytest.mark.parametrize("disk_requirement", [None, False, True])
+def test_mxfp4_expert_rebuild_cannot_weaken_explicit_smooth_requirement(disk_requirement):
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+    from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
+
+    active = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True, require_smooth_scale=True)
+    disk = {
+        "quant_method": "mxfp4",
+        "is_checkpoint_mxfp4_serialized": True,
+        "ignored_layers": ["blocks.0.attn2.to_q"],
+    }
+    if disk_requirement is not None:
+        disk["require_smooth_scale"] = disk_requirement
+    resolved = resolve_quant_config_from_disk(active, disk)
+    assert resolved.require_smooth_scale
+    assert resolved.ignored_layers == disk["ignored_layers"]
+
+
+@pytest.mark.parametrize("disk_qc", ["mxfp4", {"quant_method": "mxfp4"}])
+def test_mxfp4_method_only_disk_config_preserves_caller_layer_policy(disk_qc):
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+    from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
+
+    active = DiffusionMXFP4Config(
+        ignored_layers=["blocks.0.attn2.to_q"],
+        w4a8_fallback_steps=[1],
+        w4a8_fallback_layers=["blocks.1.attn1.to_qkv"],
+    )
+
+    resolved = resolve_quant_config_from_disk(active, disk_qc)
+
+    assert resolved is active
+    assert resolved.ignored_layers == ["blocks.0.attn2.to_q"]
+    assert resolved.w4a8_fallback_steps == [1]
+    assert resolved.w4a8_fallback_layers == ["blocks.1.attn1.to_qkv"]
+
+
+def test_quantization_disk_string_rejects_mismatched_active_method():
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+
+    active = build_quant_config("mxfp4")
+
+    with pytest.raises(ValueError, match="mxfp4_dualscale.*active quantization config is 'mxfp4'"):
+        resolve_quant_config_from_disk(active, "mxfp4_dualscale")
+
+
+def test_quantization_disk_string_accepts_equivalent_method_alias():
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+
+    class ActiveAliasConfig:
+        @staticmethod
+        def get_name() -> str:
+            return "inc"
+
+    active = ActiveAliasConfig()
+
+    assert resolve_quant_config_from_disk(active, "auto-round") is active
+
+
 def test_mxfp4_config_from_config_ignored_layers():
     from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
 
@@ -57,6 +179,202 @@ def test_mxfp4_config_from_config_modules_to_not_convert_fallback():
     assert cfg.ignored_layers == ["proj_out"]
 
 
+@pytest.mark.parametrize("serialized", [False, True])
+@pytest.mark.parametrize(
+    "policy",
+    [
+        {"w4a8_fallback_steps": [0]},
+        {"w4a8_fallback_layers": ["blocks.10.attn1.to_qkv"]},
+        {"w4a8_fallback_steps": [1], "w4a8_fallback_layers": ["blocks.10.attn1.to_qkv"]},
+    ],
+)
+def test_dualscale_rejects_w4a8_configuration(serialized, policy):
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+    from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4DualScaleMixedConfig
+
+    config = {"quant_method": "mxfp4_dualscale", "is_checkpoint_serialized": serialized, **policy}
+    with pytest.raises(ValueError, match="does not support W4A8"):
+        DiffusionMXFP4DualScaleMixedConfig(is_checkpoint_serialized=serialized, **policy)
+    with pytest.raises(ValueError, match="does not support W4A8"):
+        DiffusionMXFP4DualScaleMixedConfig.from_config(config)
+    with pytest.raises(ValueError, match="does not support W4A8"):
+        build_quant_config({"transformer": config})
+    with pytest.raises(ValueError, match="does not support W4A8"):
+        resolve_quant_config_from_disk(None, config)
+
+
+@pytest.mark.parametrize("method", ["mxfp4", "mxfp4_dualscale"])
+@pytest.mark.parametrize("steps", [[-1], [True], [1.5], ["2"], "0,2", (0, 2)])
+def test_mxfp4_rejects_invalid_fallback_steps(method, steps):
+    from vllm_omni.quantization import build_quant_config
+
+    with pytest.raises(ValueError, match="non-negative integer"):
+        build_quant_config({"method": method, "w4a8_fallback_steps": steps})
+
+
+def test_mxfp4_fallback_steps_follow_request_context():
+    from vllm_omni.diffusion.forward_context import (
+        ForwardContext,
+        override_forward_context,
+        set_forward_context_denoise_step_idx,
+    )
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.mxfp4_config import _is_w4a8_fallback_step
+
+    steps = [2, 0, 2]
+    cfg = build_quant_config({"method": "mxfp4", "w4a8_fallback_steps": steps})
+    steps.append(1)
+    assert cfg.w4a8_fallback_steps == [0, 2]
+    with override_forward_context(None):
+        assert not _is_w4a8_fallback_step([])
+        with pytest.raises(RuntimeError, match="publishes its denoise step"):
+            _is_w4a8_fallback_step(cfg.w4a8_fallback_steps)
+        for _request in range(2):
+            with override_forward_context(ForwardContext()):
+                for step, expected in [(0, True), (1, False), (2, True), (3, False)]:
+                    set_forward_context_denoise_step_idx(step)
+                    # Both CFG passes and both experts read the same index.
+                    assert [_is_w4a8_fallback_step(cfg.w4a8_fallback_steps) for _cfg_pass in range(2)] == [
+                        expected,
+                        expected,
+                    ]
+        with pytest.raises(RuntimeError, match="publishes its denoise step"):
+            _is_w4a8_fallback_step(cfg.w4a8_fallback_steps)
+
+
+@pytest.mark.parametrize("method,flag", [("mxfp4", "is_checkpoint_mxfp4_serialized")])
+@pytest.mark.parametrize("steps", [[], [0, 2]])
+@pytest.mark.parametrize("already_serialized", [False, True])
+def test_mxfp4_disk_rebuild_preserves_runtime_fallback(method, flag, steps, already_serialized):
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+
+    layers = ["blocks.10.attn1.to_qkv"] if steps else []
+    active = build_quant_config(
+        {
+            "method": method,
+            flag: already_serialized,
+            "w4a8_fallback_steps": steps,
+            "w4a8_fallback_layers": layers,
+        }
+    )
+    # Separate experts may have distinct high precision layers. Both must
+    # retain the requested step policy during online/offline reconciliation.
+    for ignored in [["blocks.0.attn1.to_q"], ["blocks.1.attn1.to_q"]]:
+        resolved = resolve_quant_config_from_disk(
+            active,
+            {
+                "quant_method": method,
+                flag: True,
+                "ignored_layers": ignored,
+                "w4a8_fallback_steps": [9],
+                "w4a8_fallback_layers": ["blocks.9.ffn.net_2"],
+            },
+        )
+        assert getattr(resolved, flag)
+        assert resolved.ignored_layers == ignored
+        assert resolved.w4a8_fallback_steps == steps
+        assert resolved.w4a8_fallback_layers == layers
+    assert active.ignored_layers == []
+
+
+@pytest.mark.parametrize(
+    "runtime_policy",
+    [{}, {"w4a8_fallback_steps": [1]}, {"w4a8_fallback_layers": ["blocks.10.attn1.to_qkv"]}],
+)
+def test_mxfp4_explicit_omission_disables_saved_policies_for_both_experts(runtime_policy):
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+
+    active = build_quant_config({"method": "mxfp4", **runtime_policy})
+    resolved_experts = []
+    for ignored in (["blocks.0.attn2.to_q"], ["blocks.1.ffn.net_2"]):
+        disk = {
+            "quant_method": "mxfp4",
+            "is_checkpoint_mxfp4_serialized": True,
+            "ignored_layers": ignored,
+            "w4a8_fallback_steps": [9],
+            "w4a8_fallback_layers": ["blocks.9.ffn.net_2"],
+        }
+        resolved = resolve_quant_config_from_disk(active, disk)
+        assert resolved.w4a8_fallback_steps == runtime_policy.get("w4a8_fallback_steps", [])
+        assert resolved.w4a8_fallback_layers == runtime_policy.get("w4a8_fallback_layers", [])
+        assert resolved.ignored_layers == ignored
+        detected = resolve_quant_config_from_disk(None, disk)
+        assert detected.w4a8_fallback_steps == [9]
+        assert detected.w4a8_fallback_layers == ["blocks.9.ffn.net_2"]
+        resolved_experts.append(resolved)
+    assert resolved_experts[0] is not resolved_experts[1]
+    assert active.is_checkpoint_mxfp4_serialized is False
+    assert active.ignored_layers == []
+
+
+@pytest.mark.parametrize(
+    "method,flag", [("mxfp4", "is_checkpoint_mxfp4_serialized"), ("mxfp4_dualscale", "is_checkpoint_serialized")]
+)
+def test_serialized_mxfp4_disk_omission_clears_active_ignored_layers(method, flag):
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+
+    active_spec = {
+        "method": method,
+        flag: True,
+        "ignored_layers": ["blocks.0.attn2.to_q"],
+        "w4a8_fallback_steps": [1] if method == "mxfp4" else [],
+        "w4a8_fallback_layers": ["blocks.1.attn1.to_qkv"] if method == "mxfp4" else [],
+    }
+    if method == "mxfp4":
+        active_spec["require_smooth_scale"] = True
+    active = build_quant_config(active_spec)
+
+    resolved = resolve_quant_config_from_disk(active, {"quant_method": method, flag: True})
+
+    assert resolved is not active
+    assert resolved.ignored_layers == []
+    assert resolved.w4a8_fallback_steps == active.w4a8_fallback_steps
+    assert resolved.w4a8_fallback_layers == active.w4a8_fallback_layers
+    if method == "mxfp4":
+        assert resolved.require_smooth_scale
+
+
+@pytest.mark.parametrize(
+    "method,flag", [("mxfp4", "is_checkpoint_mxfp4_serialized"), ("mxfp4_dualscale", "is_checkpoint_serialized")]
+)
+@pytest.mark.parametrize("with_active", [False, True])
+def test_serialized_mxfp4_disk_uses_modules_to_not_convert(method, flag, with_active):
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+
+    active = None
+    disk_steps = [9] if method == "mxfp4" else []
+    active_steps = [1] if method == "mxfp4" else []
+    expected_steps = disk_steps
+    if with_active:
+        active = build_quant_config(
+            {
+                "method": method,
+                flag: True,
+                "ignored_layers": ["blocks.0.attn2.to_q"],
+                "w4a8_fallback_steps": active_steps,
+            }
+        )
+        expected_steps = active_steps
+
+    resolved = resolve_quant_config_from_disk(
+        active,
+        {
+            "quant_method": method,
+            flag: True,
+            "modules_to_not_convert": ["blocks.2.ffn.net_2"],
+            "w4a8_fallback_steps": disk_steps,
+        },
+    )
+
+    assert resolved.ignored_layers == ["blocks.2.ffn.net_2"]
+    assert resolved.w4a8_fallback_steps == expected_steps
+
+
 # ---------------------------------------------------------------------------
 # build_quant_config integration
 # ---------------------------------------------------------------------------
@@ -594,18 +912,31 @@ def test_rocm_online_dispatch_returns_rocm_method(_rocm_platform, monkeypatch):
     assert isinstance(method, ROCmMxfp4OnlineLinearMethod)
 
 
-def test_rocm_ignored_layer_returns_unquantized(_rocm_platform, monkeypatch):
+@pytest.mark.parametrize("steps", [[], [0, 2]])
+def test_rocm_ignored_layer_returns_unquantized(_rocm_platform, monkeypatch, steps):
     """A prefix in ignored_layers must return UnquantizedLinearMethod before the gfx950 probe."""
     from vllm.model_executor.layers.linear import UnquantizedLinearMethod
 
     from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
 
     _patch_gcn_arch(monkeypatch, "gfx950:sramecc+:xnack-")
-    cfg = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=False, ignored_layers=["proj_out"])
+    cfg = DiffusionMXFP4Config(
+        is_checkpoint_mxfp4_serialized=False, ignored_layers=["proj_out"], w4a8_fallback_steps=steps
+    )
 
     assert isinstance(cfg.get_quant_method(_fake_linear_layer(), "proj_out"), UnquantizedLinearMethod)
 
 
+def test_rocm_rejects_w4a8_step_fallback(_rocm_platform, monkeypatch):
+    from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
+
+    _patch_gcn_arch(monkeypatch, "gfx950:sramecc+:xnack-")
+    cfg = DiffusionMXFP4Config(w4a8_fallback_steps=[0, 2])
+
+    with pytest.raises(NotImplementedError, match="only supported on NPU"):
+        cfg.get_quant_method(_fake_linear_layer(), "blocks.0.attn1.to_q")
+
+
 def test_rocm_non_gfx950_raises(_rocm_platform, monkeypatch):
     """MXFP4 on ROCm requires gfx950; any other arch must raise."""
     from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config
@@ -652,3 +983,221 @@ def test_rocm_create_weights_row_parallel_tp2(_rocm_platform):
     assert layer.weight.shape == (_TP2_N, _TP2_K // _TP2)
     assert layer.input_size_per_partition == _TP2_K // _TP2
     assert layer.output_size_per_partition == _TP2_N
+
+
+@pytest.mark.parametrize("method", ["mxfp4", "mxfp4_dualscale"])
+@pytest.mark.parametrize("layers", ["blocks.1.attn1.to_qkv", [1], [True], [""], [" a"], ["blocks.*"], ["a..b"]])
+def test_mxfp4_rejects_invalid_fallback_layers(method, layers):
+    from vllm_omni.quantization import build_quant_config
+
+    with pytest.raises(ValueError, match="exact runtime Linear paths"):
+        build_quant_config({"method": method, "w4a8_fallback_layers": layers})
+
+
+@pytest.mark.parametrize("method", ["mxfp4"])
+def test_mxfp4_layer_policy_from_checkpoint_and_component_config(method):
+    from vllm_omni.quantization import build_quant_config
+    from vllm_omni.quantization.component_config import resolve_component_quant_config
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+
+    names = ["blocks.10.attn1.to_qkv", "blocks.10.attn1.to_qkv"]
+    components = build_quant_config(
+        {"transformer": {"method": method, "w4a8_fallback_layers": names}, "transformer_2": {"method": method}}
+    )
+    names.append("blocks.11.attn1.to_qkv")
+    assert resolve_component_quant_config(components, "transformer").w4a8_fallback_layers == [names[0]]
+    assert resolve_component_quant_config(components, "transformer_2").w4a8_fallback_layers == []
+    detected = resolve_quant_config_from_disk(None, {"quant_method": method, "w4a8_fallback_layers": [names[0]]})
+    assert detected.w4a8_fallback_layers == [names[0]]
+    assert type(detected).from_config({"w4a8_fallback_layers": [names[0]]}).w4a8_fallback_layers == [names[0]]
+
+
+@pytest.mark.parametrize(
+    "kind, serialized_flag",
+    [("mxfp4", "is_checkpoint_mxfp4_serialized")],
+)
+@pytest.mark.parametrize("offline", [False, True])
+@pytest.mark.parametrize("scale_alg", [0, 2])
+def test_mxfp4_layer_and_step_union_routes_actual_methods(
+    kind, serialized_flag, offline, scale_alg, monkeypatch, mocker
+):
+    from vllm.model_executor.layers.linear import LinearBase, UnquantizedLinearMethod
+
+    from vllm_omni.diffusion.forward_context import ForwardContext, override_forward_context
+    from vllm_omni.quantization import build_quant_config, mxfp4_config
+
+    monkeypatch.setattr(mxfp4_config.current_omni_platform, "is_npu", lambda: True)
+    selected = "blocks.10.attn1.to_qkv"
+    other = "blocks.11.attn2.to_q"
+    preserved = "blocks.12.ffn.net_2"
+    config = build_quant_config(
+        {
+            "method": kind,
+            "mxfp4_scale_alg": scale_alg,
+            serialized_flag: offline,
+            "w4a8_fallback_layers": [selected, preserved],
+            "ignored_layers": [preserved],
+            "w4a8_fallback_steps": [1],
+        }
+    )
+    # Real config dispatch creates separate methods for selected and other layers.
+    linear = mocker.Mock(spec=LinearBase)
+    assert isinstance(config.get_quant_method(linear, preserved), UnquantizedLinearMethod)
+    x = torch.ones(2, 64, dtype=torch.bfloat16)
+    layer = torch.nn.Module()
+    for name in ("weight", "weight_scale", "mul_scale"):
+        layer.register_buffer(name, torch.ones(64, dtype=x.dtype))
+    calls = []
+
+    def record_a8(*args):
+        calls.append("A8")
+        return x
+
+    def record_a4(*args):
+        calls.append("A4")
+        return x
+
+    monkeypatch.setattr(mxfp4_config, "_npu_w4a8_matmul", record_a8)
+    for name in (selected, other):
+        method = config.get_quant_method(linear, name)
+        assert method.is_w4a8_fallback_layer == (name == selected)
+        scales = (x, x)
+        monkeypatch.setattr(method, "_quantize_activation", lambda *args: scales)
+        monkeypatch.setattr(method, "_quant_matmul", record_a4)
+        for step in (0, 1, 2):
+            with override_forward_context(ForwardContext(denoise_step_idx=step)):
+                method.apply(layer, x)
+    assert calls == ["A8", "A8", "A8", "A4", "A8", "A4"]
+    # A permanently selected layer works without a request context, even if steps are also configured.
+    with override_forward_context(None):
+        config.get_quant_method(linear, selected).apply(layer, x)
+    assert calls[-1] == "A8"
+
+
+@pytest.mark.parametrize("online", [False, True])
+@pytest.mark.parametrize("selected", [False, True])
+@pytest.mark.parametrize("scale_alg", [0, 2])
+def test_single_scale_prepares_one_weight_for_both_activation_precisions(online, selected, scale_alg, monkeypatch):
+    import sys
+    from types import SimpleNamespace
+
+    from vllm_omni.diffusion.forward_context import ForwardContext, override_forward_context
+    from vllm_omni.quantization import mxfp4_config
+
+    monkeypatch.setattr(torch.Tensor, "npu", lambda self: self, raising=False)
+    prepared = []
+    packed = []
+
+    def quantize(x, **kwargs):
+        prepared.append(kwargs)
+        return x.to(torch.int8), torch.full((x.shape[0], 2), 127, dtype=torch.uint8)
+
+    def pack(x, dtype):
+        packed.append(x)
+        return x.to(dtype)
+
+    fake_npu = SimpleNamespace(
+        float4_e2m1fn_x2=torch.int8,
+        float8_e8m0fnu=torch.uint8,
+        float8_e4m3fn=torch.float8_e4m3fn,
+        npu_dtype_cast=pack,
+        npu_dynamic_mx_quant=quantize,
+    )
+    monkeypatch.setitem(sys.modules, "torch_npu", fake_npu)
+    config = mxfp4_config.DiffusionMXFP4Config(
+        is_checkpoint_mxfp4_serialized=not online,
+        w4a8_fallback_layers=["blocks.0.attn1.to_qkv"] if selected else [],
+        w4a8_fallback_steps=[1],
+        mxfp4_scale_alg=scale_alg,
+    )
+    cls = mxfp4_config.NPUMxfp4OnlineLinearMethod if online else mxfp4_config.NPUMxfp4LinearMethod
+    method = cls(config, prefix="blocks.0.attn1.to_qkv")
+    layer = torch.nn.Linear(64, 2, bias=False, dtype=torch.bfloat16)
+    layer.orig_dtype = torch.bfloat16
+    if not online:
+        layer.register_parameter("weight_scale", torch.nn.Parameter(torch.full((2, 2), 127, dtype=torch.uint8), False))
+        layer.register_parameter("mul_scale", torch.nn.Parameter(torch.linspace(0.5, 2, 64), False))
+    method.process_weights_after_loading(layer)
+    pointers = (layer.weight.data_ptr(), layer.weight_scale.data_ptr())
+    method.process_weights_after_loading(layer)
+    assert len(prepared) == int(online)
+    expected = dict(dst_type=torch.int8, axis=-1, block_size=32, round_mode="rint", scale_alg=scale_alg)
+    if scale_alg == 2:
+        expected["dst_type_max"] = 7.25
+    assert prepared == ([expected] if online else [])
+    assert len(packed) == int(not online)
+    branches = []
+
+    def a4(x_q, x_scale, target, bias, dtype):
+        assert (target.weight.data_ptr(), target.weight_scale.data_ptr()) == pointers
+        branches.append("A4")
+        return torch.zeros(x_q.shape[0], 2, dtype=dtype)
+
+    def a8(x, weight, scale, bias, dtype):
+        assert (weight.data_ptr(), scale.data_ptr()) == pointers
+        branches.append("A8")
+        return torch.zeros(x.shape[0], 2, dtype=dtype)
+
+    monkeypatch.setattr(method, "_quant_matmul", a4)
+    monkeypatch.setattr(mxfp4_config, "_npu_w4a8_matmul", a8)
+    monkeypatch.setattr(method, "_quantize_activation", lambda x: (x, x))
+    monkeypatch.setattr(fake_npu, "npu_dynamic_mx_quant", lambda *a, **kw: pytest.fail("weight requantization"))
+    monkeypatch.setattr(fake_npu, "npu_dtype_cast", lambda *a, **kw: pytest.fail("weight repacking"))
+    for step in (0, 1, 2):
+        with override_forward_context(ForwardContext(denoise_step_idx=step)):
+            method.apply(layer, torch.ones(2, 64, dtype=torch.bfloat16))
+    assert branches == (["A8"] * 3 if selected else ["A4", "A8", "A4"])
+    assert (layer.weight.data_ptr(), layer.weight_scale.data_ptr()) == pointers
+    assert set(layer.state_dict()) == (
+        {"weight", "weight_scale"} if online else {"weight", "weight_scale", "mul_scale"}
+    )
+    assert not hasattr(layer, "w4a8_weight")
+    assert not hasattr(layer, "w4a8_weight_scale")
+
+
+@pytest.mark.parametrize("online", [False, True])
+def test_dualscale_without_fallback_keeps_original_a4_path(online, monkeypatch):
+    import sys
+    from types import SimpleNamespace
+
+    from vllm_omni.quantization import mxfp4_config
+
+    monkeypatch.setattr(torch.Tensor, "npu", lambda self: self, raising=False)
+    original_ones = torch.ones
+    monkeypatch.setattr(torch, "ones", lambda *args, **kw: original_ones(*args, **{**kw, "device": "cpu"}))
+    calls = []
+
+    def quantize_dual(x, **kw):
+        calls.append(kw.get("smooth_scale"))
+        return x.to(torch.int8), torch.ones(x.shape[0], 1), torch.ones(x.shape[0], 16, dtype=torch.uint8)
+
+    fake_npu = SimpleNamespace(
+        float4_e2m1fn_x2=torch.int8,
+        npu_dtype_cast=lambda x, dtype: x.to(dtype),
+        npu_format_cast=lambda x, *args, **kw: x,
+        npu_dynamic_dual_level_mx_quant=quantize_dual,
+    )
+    monkeypatch.setitem(sys.modules, "torch_npu", fake_npu)
+    config = mxfp4_config.DiffusionMXFP4DualScaleMixedConfig(
+        is_checkpoint_serialized=not online, w4a8_fallback_steps=[], w4a8_fallback_layers=[]
+    )
+    cls = mxfp4_config.NPUMxfp4DualScaleOnlineLinearMethod if online else mxfp4_config.NPUMxfp4DualScaleLinearMethod
+    method = cls(config)
+    layer = torch.nn.Module()
+    layer.input_size_per_partition = 512
+    for name, value in {
+        "weight": torch.ones(2, 512, dtype=torch.bfloat16),
+        "weight_scale": torch.full((2, 16), 127, dtype=torch.uint8),
+        "weight_dual_scale": torch.ones(2, 1, 1),
+        "mul_scale": torch.ones(512),
+    }.items():
+        layer.register_parameter(name, torch.nn.Parameter(value, requires_grad=False))
+    method.process_weights_after_loading(layer)
+    method.process_weights_after_loading(layer)
+    assert len(calls) == int(online)
+    assert set(layer.state_dict()) == {"weight", "weight_scale", "weight_dual_scale", "mul_scale"}
+    assert not hasattr(layer, "w4a8_weight")
+    monkeypatch.setattr(method, "_quant_matmul", lambda *args: torch.zeros(2, 2, dtype=torch.bfloat16))
+    method.apply(layer, torch.ones(2, 512, dtype=torch.bfloat16))
+    assert len(calls) == 1 + int(online)
+    torch.testing.assert_close(calls[-1], layer.mul_scale)
diff --git a/tests/diffusion/quantization/test_wan_mxfp4_loading.py b/tests/diffusion/quantization/test_wan_mxfp4_loading.py
new file mode 100644
index 00000000000..fc7a43d43ba
--- /dev/null
+++ b/tests/diffusion/quantization/test_wan_mxfp4_loading.py
@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Exercise Wan's real name mapping and vLLM's QKV parameter loaders on CPU."""
+
+import pytest
+import torch
+from vllm.config.load import LoadConfig
+from vllm.model_executor.layers.linear import QKVParallelLinear
+
+from vllm_omni.diffusion.data import OmniDiffusionConfig
+from vllm_omni.diffusion.model_loader.diffusers_loader import DiffusersPipelineLoader
+from vllm_omni.diffusion.models.wan2_2.wan2_2_transformer import WanTransformer3DModel
+from vllm_omni.quantization.mxfp4_config import DiffusionMXFP4Config, DiffusionMXFP4DualScaleMixedConfig
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+@pytest.fixture(autouse=True)
+def _patch_tp_state(monkeypatch):
+    monkeypatch.setattr("vllm.model_executor.parameter.get_tensor_model_parallel_rank", lambda: 0)
+    monkeypatch.setattr("vllm.model_executor.parameter.get_tensor_model_parallel_world_size", lambda: 1)
+    monkeypatch.setattr("vllm_omni.platforms.current_omni_platform.is_npu", lambda: True)
+    prefix = "vllm_omni.diffusion.models.wan2_2.wan2_2_transformer"
+    monkeypatch.setattr(f"{prefix}.get_tensor_model_parallel_rank", lambda: 0)
+    monkeypatch.setattr(f"{prefix}.get_tensor_model_parallel_world_size", lambda: 1)
+
+
+class _WanCheckpoint(torch.nn.Module):
+    load_weights = WanTransformer3DModel.load_weights
+    _log_w4a8_fallback_load_summary = WanTransformer3DModel._log_w4a8_fallback_load_summary
+
+    def __init__(self, config, *, num_blocks=1):
+        super().__init__()
+        blocks = []
+        for block_idx in range(num_blocks):
+            block = torch.nn.Module()
+            block.attn1 = torch.nn.Module()
+            block.attn1.to_qkv = QKVParallelLinear(
+                hidden_size=512,
+                head_size=32,
+                total_num_heads=4,
+                bias=False,
+                params_dtype=torch.bfloat16,
+                quant_config=config,
+                prefix=f"blocks.{block_idx}.attn1.to_qkv",
+                disable_tp=True,
+            )
+            blocks.append(block)
+        self.blocks = torch.nn.ModuleList(blocks)
+
+
+def _checkpoint(mode, fused):
+    if mode == "single":
+        config = DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True, require_smooth_scale=True)
+    elif mode == "dual":
+        config = DiffusionMXFP4DualScaleMixedConfig(is_checkpoint_serialized=True)
+    else:
+        config = None
+    model = _WanCheckpoint(config)
+    weights = {}
+    expected = {}
+    for name, param in model.named_parameters():
+        suffix = name.rsplit(".", 1)[1]
+        output_dim = getattr(param, "output_dim", None)
+        if output_dim is None:
+            value = torch.full_like(param, 2.5)
+            shards = [value] * 3
+        else:
+            parts = param.chunk(3, dim=output_dim)
+            shards = [
+                torch.full_like(part, (121 if suffix == "weight_scale" else 1) + i) for i, part in enumerate(parts)
+            ]
+            value = torch.cat(shards, dim=output_dim)
+        expected[name] = value
+        if fused:
+            weights[name] = value
+        else:
+            for shard_id, shard in zip(("q", "k", "v"), shards):
+                weights[f"blocks.0.attn1.to_{shard_id}.{suffix}"] = shard
+    return model, config, weights, expected
+
+
+def _load(model, config, weights, monkeypatch):
+    loader = DiffusersPipelineLoader(
+        LoadConfig(), OmniDiffusionConfig(model="", dtype=torch.bfloat16, quantization_config=config)
+    )
+    loader.counter_before_loading_weights = 0.0
+    monkeypatch.setattr(loader, "get_all_weights", lambda model: iter(weights.items()))
+    loader.load_weights(model)
+
+
+@pytest.mark.parametrize("mode", ["single", "dual", "bf16"])
+@pytest.mark.parametrize("fused", [False, True])
+def test_wan_qkv_loads_actual_weights_and_scales(mode, fused, monkeypatch):
+    model, config, weights, expected = _checkpoint(mode, fused)
+    _load(model, config, weights, monkeypatch)
+    for name, param in model.named_parameters():
+        torch.testing.assert_close(param, expected[name], rtol=0, atol=0)
+
+
+@pytest.mark.parametrize("mode", ["single", "dual", "bf16"])
+def test_wan_incomplete_qkv_weight_is_not_marked_fully_loaded(mode, monkeypatch):
+    model, config, weights, _ = _checkpoint(mode, fused=False)
+    weights.pop("blocks.0.attn1.to_k.weight")
+    weights.pop("blocks.0.attn1.to_v.weight")
+    with pytest.raises(ValueError, match="to_qkv.weight"):
+        _load(model, config, weights, monkeypatch)
+
+
+@pytest.mark.parametrize("mode", ["single", "dual"])
+def test_wan_incomplete_qkv_scale_is_not_marked_fully_loaded(mode, monkeypatch):
+    model, config, weights, _ = _checkpoint(mode, fused=False)
+    weights.pop("blocks.0.attn1.to_k.weight_scale")
+    weights.pop("blocks.0.attn1.to_v.weight_scale")
+    with pytest.raises(ValueError, match="to_qkv.weight_scale"):
+        _load(model, config, weights, monkeypatch)
+
+
+@pytest.mark.parametrize("mode", ["single", "dual"])
+@pytest.mark.parametrize("reverse", [False, True])
+def test_wan_split_qkv_rejects_different_smooth_scales(mode, reverse, monkeypatch):
+    model, config, weights, _ = _checkpoint(mode, fused=False)
+    weights["blocks.0.attn1.to_k.mul_scale"] = weights["blocks.0.attn1.to_k.mul_scale"] * 2
+    if reverse:
+        weights = dict(reversed(weights.items()))
+    with pytest.raises(ValueError, match="must share the same Smooth tensor"):
+        _load(model, config, weights, monkeypatch)
+
+
+@pytest.mark.parametrize("name", ["to_q.missing", "to_qkv.missing", "to_qkv_extra.weight", "to_query.weight"])
+def test_wan_unknown_qkv_key_is_not_reported_as_loaded(name):
+    model, _, _, _ = _checkpoint("single", fused=True)
+    loaded = model.load_weights([(f"blocks.0.attn1.{name}", torch.ones(2))])
+    assert loaded == set()
+
+
+@pytest.mark.parametrize("fused", [False, True])
+def test_wan_single_scale_rejects_relabelled_dualscale_checkpoint(fused, monkeypatch):
+    model, config, weights, _ = _checkpoint("single", fused=fused)
+    projection = "to_qkv" if fused else "to_q"
+    weights[f"blocks.0.attn1.{projection}.weight_dual_scale"] = torch.ones(128, 1, 1)
+    with pytest.raises(ValueError, match="cannot load DualScale tensor"):
+        _load(model, config, weights, monkeypatch)
+
+
+def test_wan_layer_policy_validates_runtime_qkv_and_bf16_override():
+    config = DiffusionMXFP4Config(w4a8_fallback_layers=["blocks.0.attn1.to_qkv"])
+    model = _WanCheckpoint(config)
+    # Uses the same validation called at the end of WanTransformer3DModel construction.
+    WanTransformer3DModel._validate_w4a8_fallback_layers(model, config)
+    for bad in ("blocks.0.attn1.to_q", "blocks.0.attn1", "blocks.99.attn1.to_qkv", "transformer.blocks.0.attn1.to_qkv"):
+        config.w4a8_fallback_layers = [bad]
+        with pytest.raises(ValueError, match="exact runtime Linear paths"):
+            WanTransformer3DModel._validate_w4a8_fallback_layers(model, config)
+
+
+def test_wan_layer_policy_defers_only_other_pp_stage_paths():
+    from vllm.model_executor.models.utils import PPMissingLayer
+
+    config = DiffusionMXFP4Config(w4a8_fallback_layers=["blocks.0.attn1.to_qkv", "blocks.1.attn1.to_qkv"])
+    model = _WanCheckpoint(config)
+    model.blocks.append(PPMissingLayer())
+    WanTransformer3DModel._validate_w4a8_fallback_layers(model, config)
+    config.w4a8_fallback_layers = ["blocks.1"]
+    with pytest.raises(ValueError, match="exact runtime Linear paths"):
+        WanTransformer3DModel._validate_w4a8_fallback_layers(model, config)
+
+
+@pytest.mark.parametrize("is_checkpoint_serialized", [False, True], ids=["online", "offline"])
+def test_loader_logs_wan_expert_summaries_after_weight_processing(is_checkpoint_serialized, mocker):
+    selected = "blocks.0.attn1.to_qkv"
+    bf16 = "blocks.1.attn1.to_qkv"
+    transformer_config = DiffusionMXFP4Config(
+        is_checkpoint_mxfp4_serialized=is_checkpoint_serialized,
+        w4a8_fallback_layers=[selected],
+    )
+    transformer_2_config = DiffusionMXFP4Config(
+        is_checkpoint_mxfp4_serialized=is_checkpoint_serialized,
+        ignored_layers=[bf16],
+        w4a8_fallback_layers=[selected, bf16],
+    )
+    pipeline = torch.nn.Module()
+    pipeline.transformer = _WanCheckpoint(transformer_config)
+    pipeline.transformer_2 = _WanCheckpoint(transformer_2_config, num_blocks=2)
+    WanTransformer3DModel._validate_w4a8_fallback_layers(pipeline.transformer, transformer_config)
+    WanTransformer3DModel._validate_w4a8_fallback_layers(pipeline.transformer_2, transformer_2_config)
+
+    loader = DiffusersPipelineLoader(
+        LoadConfig(),
+        OmniDiffusionConfig(model="", dtype=torch.bfloat16, quantization_config=transformer_config),
+    )
+    events = []
+    summaries = []
+
+    def process_weights(model, _target_device):
+        events.append("process")
+        for module in model.modules():
+            method = getattr(module, "quant_method", None)
+            if getattr(method, "is_w4a8_fallback_layer", False):
+                module._already_called_process_weights_after_loading = True
+
+    def capture_summary(message, *args):
+        rendered = message % args
+        summaries.append(rendered)
+        events.append(f"summary:{args[0]}")
+
+    loader._init_from_load_format = lambda *_args, **_kwargs: pipeline  # type: ignore[method-assign]
+    loader.load_weights = lambda _model: events.append("load")  # type: ignore[method-assign]
+    loader._process_weights_after_loading = process_weights  # type: ignore[method-assign]
+    loader._apply_skip_softmax_calibration = lambda _model: None  # type: ignore[method-assign]
+    mocker.patch(
+        "vllm_omni.diffusion.models.wan2_2.wan2_2_transformer.logger.info",
+        side_effect=capture_summary,
+    )
+
+    assert loader.load_model(load_device="cpu") is pipeline
+    assert events == ["load", "process", "summary:transformer", "summary:transformer_2"]
+    assert "component=transformer; selected=1 ['transformer.blocks.0.attn1.to_qkv']" in summaries[0]
+    assert "BF16 overrides=0 []" in summaries[0]
+    assert "weight/A8 processing state=ready (1/1 selected layers processed)" in summaries[0]
+    assert "component=transformer_2; selected=1 ['transformer_2.blocks.0.attn1.to_qkv']" in summaries[1]
+    assert "BF16 overrides=1 ['transformer_2.blocks.1.attn1.to_qkv']" in summaries[1]
+    assert "weight/A8 processing state=ready (1/1 selected layers processed)" in summaries[1]
+
+
+def test_wan_load_summary_does_not_claim_unprocessed_layer_is_ready(mocker):
+    selected = "blocks.0.attn1.to_qkv"
+    config = DiffusionMXFP4Config(w4a8_fallback_layers=[selected])
+    model = _WanCheckpoint(config)
+    WanTransformer3DModel._validate_w4a8_fallback_layers(model, config)
+    logger_info = mocker.patch("vllm_omni.diffusion.models.wan2_2.wan2_2_transformer.logger.info")
+
+    WanTransformer3DModel._log_w4a8_fallback_load_summary(model, "transformer")
+
+    message, *args = logger_info.call_args.args
+    rendered = message % tuple(args)
+    assert "weight/A8 processing state=not-ready (0/1 selected layers processed)" in rendered
diff --git a/tests/diffusion/test_diffusion_config_propagation.py b/tests/diffusion/test_diffusion_config_propagation.py
index 23ff796e208..6f37f823dc9 100644
--- a/tests/diffusion/test_diffusion_config_propagation.py
+++ b/tests/diffusion/test_diffusion_config_propagation.py
@@ -25,6 +25,12 @@
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
 
+@pytest.fixture(autouse=True)
+def _local_model_paths(monkeypatch):
+    # These tests exercise config transport, not model repository resolution.
+    monkeypatch.setattr("vllm_omni.diffusion.data.get_model_path", lambda model, revision: model)
+
+
 def _roundtrip_diffusion_config(**kwargs) -> OmniDiffusionConfig:
     """Simulate the real path: create_default_diffusion → OmniDiffusionConfig.
 
diff --git a/tests/examples/offline_inference/test_text_to_video_prompts.py b/tests/examples/offline_inference/test_text_to_video_prompts.py
index c588b7a38ee..e0c381bf341 100644
--- a/tests/examples/offline_inference/test_text_to_video_prompts.py
+++ b/tests/examples/offline_inference/test_text_to_video_prompts.py
@@ -1,10 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from __future__ import annotations
 
 import functools
 import importlib.util
+import sys
+from types import SimpleNamespace
 
 import pytest
 import torch
@@ -24,6 +26,51 @@ def _load_text_to_video():
     return module
 
 
+@pytest.mark.parametrize(
+    ("arguments", "expected"),
+    [
+        (["--quantization", "mxfp4"], {"quantization": "mxfp4"}),
+        (
+            ["--quantization-config", '{"method":"mxfp4","w4a8_fallback_steps":[0,2]}'],
+            {"quantization_config": {"method": "mxfp4", "w4a8_fallback_steps": [0, 2]}},
+        ),
+    ],
+)
+def test_quantization_cli_reaches_omni(arguments, expected, monkeypatch):
+    mod = _load_text_to_video()
+    captured = {}
+
+    class StopBeforeModelLoadError(Exception):
+        pass
+
+    def capture_omni(**kwargs):
+        captured.update(kwargs)
+        raise StopBeforeModelLoadError
+
+    monkeypatch.setattr(sys, "argv", ["text_to_video.py", "--model", "Wan-AI/Wan2.2-T2V-A14B-Diffusers", *arguments])
+    monkeypatch.setattr(mod, "current_omni_platform", SimpleNamespace(device_type="cpu"))
+    monkeypatch.setattr(mod, "Omni", capture_omni)
+
+    with pytest.raises(StopBeforeModelLoadError):
+        mod.main()
+
+    assert {key: captured[key] for key in ("quantization", "quantization_config") if key in captured} == expected
+
+
+def test_quantization_cli_options_are_mutually_exclusive(monkeypatch):
+    mod = _load_text_to_video()
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        ["text_to_video.py", "--quantization", "mxfp4", "--quantization-config", '{"method":"mxfp4"}'],
+    )
+
+    with pytest.raises(SystemExit) as exc:
+        mod.parse_args()
+
+    assert exc.value.code == 2
+
+
 @pytest.mark.parametrize(
     ("negative_prompt", "expected_negative_prompt"),
     [(None, None), ("", ""), ("blurry", "blurry")],
diff --git a/tests/platforms/npu/quant/test_mxfp4_step_fallback.py b/tests/platforms/npu/quant/test_mxfp4_step_fallback.py
new file mode 100644
index 00000000000..8431ebf1707
--- /dev/null
+++ b/tests/platforms/npu/quant/test_mxfp4_step_fallback.py
@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Real A5 kernels: step selection, bias, shape, and reuse of prepared W4 weights."""
+
+import pytest
+import torch
+
+pytestmark = [pytest.mark.advanced_model, pytest.mark.diffusion, pytest.mark.npu]
+
+torch_npu = pytest.importorskip("torch_npu")
+
+
+@torch.inference_mode()
+def _exercise_mxfp4_fallback(with_bias, dtype, input_shape, mode, monkeypatch, *, policy, scale_alg=2):
+    from vllm_omni.diffusion.forward_context import (
+        ForwardContext,
+        override_forward_context,
+        set_forward_context_denoise_step_idx,
+    )
+    from vllm_omni.quantization.mxfp4_config import (
+        DiffusionMXFP4Config,
+        NPUMxfp4LinearMethod,
+        NPUMxfp4OnlineLinearMethod,
+    )
+
+    prefix = "blocks.10.attn1.to_qkv"
+    steps = [1] if policy in ("step", "layer_and_step") else []
+    layers = [prefix] if policy in ("layer", "layer_and_step") else []
+    fallback = {"w4a8_fallback_steps": steps, "w4a8_fallback_layers": layers, "mxfp4_scale_alg": scale_alg}
+    torch.manual_seed(42)
+    layer = torch.nn.Linear(1024, 128, bias=with_bias, device="npu", dtype=dtype)
+    if mode == "single":
+        method = NPUMxfp4OnlineLinearMethod(DiffusionMXFP4Config(**fallback), prefix=prefix)
+    elif mode == "single_offline":
+        method = NPUMxfp4LinearMethod(
+            DiffusionMXFP4Config(is_checkpoint_mxfp4_serialized=True, **fallback), prefix=prefix
+        )
+        layer.orig_dtype = dtype
+        values = torch.tensor([-4.0, -2.0, -1.0, -0.5, 0.0, 0.5, 1.0, 2.0])
+        layer.weight.copy_(values[torch.randint(8, (128, 1024))].to(layer.weight))
+        layer.register_parameter(
+            "weight_scale", torch.nn.Parameter(torch.full((128, 32), 124, dtype=torch.uint8, device="npu"), False)
+        )
+        layer.register_parameter("mul_scale", torch.nn.Parameter((torch.rand(1024) * 1.5 + 0.5).npu(), False))
+    else:
+        raise ValueError(f"Unsupported single-scale test mode: {mode}")
+    method.process_weights_after_loading(layer)
+    x = torch.randn(input_shape, device="npu", dtype=dtype)
+    pointers = (layer.weight.data_ptr(), layer.weight_scale.data_ptr())
+    method.process_weights_after_loading(layer)
+    quantize = torch_npu.npu_dynamic_mx_quant
+    activation_types = []
+
+    def record_quantize(x, **kwargs):
+        dst = kwargs["dst_type"]
+        expected_alg = 0 if dst == torch_npu.float8_e4m3fn else scale_alg
+        assert kwargs["scale_alg"] == expected_alg
+        assert kwargs["axis"] == -1 and kwargs["block_size"] == 32 and kwargs["round_mode"] == "rint"
+        if expected_alg == 2:
+            assert kwargs["dst_type_max"] == 7.25
+        else:
+            assert "dst_type_max" not in kwargs
+        activation_types.append(dst)
+        return quantize(x, **kwargs)
+
+    monkeypatch.setattr(torch_npu, "npu_dynamic_mx_quant", record_quantize)
+    results = []
+    for _request in range(2):
+        with override_forward_context(ForwardContext()):
+            for step in range(3):
+                set_forward_context_denoise_step_idx(step)
+                output = method.apply(layer, x, layer.bias)
+                torch.npu.synchronize()
+                assert output.shape == (*input_shape[:-1], 128)
+                assert output.dtype == dtype
+                assert torch.isfinite(output).all()
+                results.append(output.cpu())
+    expected_types = [
+        torch_npu.float8_e4m3fn if layers or step in steps else torch_npu.float4_e2m1fn_x2 for step in range(3)
+    ]
+    assert activation_types == expected_types * 2
+    assert (layer.weight.data_ptr(), layer.weight_scale.data_ptr()) == pointers
+    assert not hasattr(layer, "w4a8_weight")
+    assert not hasattr(layer, "w4a8_weight_scale")
+    for first, second in zip(results[:3], results[3:]):
+        torch.testing.assert_close(first, second, rtol=0, atol=0)
+
+
+@pytest.mark.parametrize("with_bias", [False, True])
+@pytest.mark.parametrize("dtype", [torch.bfloat16, torch.float16])
+@pytest.mark.parametrize("input_shape", [(16, 1024), (2, 8, 1024)])
+@pytest.mark.parametrize("mode", ["single", "single_offline"])
+def test_mxfp4_step_fallback(with_bias, dtype, input_shape, mode, monkeypatch):
+    _exercise_mxfp4_fallback(with_bias, dtype, input_shape, mode, monkeypatch, policy="step")
+
+
+@pytest.mark.cards_1
+@pytest.mark.parametrize("dtype", [torch.bfloat16, torch.float16])
+@torch.inference_mode()
+def test_single_scale_step_fallback_matches_independent_dense_reference(dtype):
+    if not torch.npu.is_available() or "Ascend950" not in torch.npu.get_device_name():
+        pytest.skip("MXFP4 kernels require an Ascend950 NPU")
+
+    from vllm_omni.diffusion.forward_context import (
+        ForwardContext,
+        override_forward_context,
+        set_forward_context_denoise_step_idx,
+    )
+    from vllm_omni.quantization.mxfp4_config import (
+        DiffusionMXFP4Config,
+        NPUMxfp4LinearMethod,
+    )
+
+    # Synthetic serialized single-scale values and E8M0 exponent bytes.
+    # Powers of two make both activation precisions exact: this independent
+    # CPU dense oracle needs no production packing, dequantization or apply.
+    # Real UOS-quantized checkpoint validation remains a separate checkpoint/E2E gate.
+    values = torch.tensor([1.0, -1.0, 2.0, -2.0]).repeat(32).unsqueeze(1).expand(128, 512)
+    weight = torch.cat((values, values), dim=1)
+    fine = torch.cat((torch.full((128, 16), 127), torch.full((128, 16), 128)), dim=1).to(torch.uint8)
+    smooth = torch.cat((torch.full((512,), 0.5), torch.full((512,), 2.0)))
+    bias = torch.tensor([0.25, -0.25]).repeat(64)
+    x = torch.tensor([1.0, -1.0, 0.5, -0.5]).repeat(4).unsqueeze(1).expand(16, 1024) / 64
+    expected = torch.nn.functional.linear(x * smooth, torch.cat((values, 2 * values), dim=1), bias)
+
+    layer = torch.nn.Linear(1024, 128, bias=True, device="npu", dtype=dtype)
+    layer.weight.copy_(weight)
+    layer.bias.copy_(bias)
+    layer.orig_dtype = dtype
+    for name, value in {"weight_scale": fine, "mul_scale": smooth}.items():
+        layer.register_parameter(name, torch.nn.Parameter(value.npu(), requires_grad=False))
+    method = NPUMxfp4LinearMethod(
+        DiffusionMXFP4Config(
+            is_checkpoint_mxfp4_serialized=True, require_smooth_scale=True, w4a8_fallback_steps=[1], mxfp4_scale_alg=2
+        )
+    )
+    method.process_weights_after_loading(layer)
+    prepared_pointers = (layer.weight.data_ptr(), layer.weight_scale.data_ptr())
+    assert set(layer.state_dict()) == {"weight", "bias", "weight_scale", "mul_scale"}
+    assert not hasattr(layer, "w4a8_weight")
+    assert not hasattr(layer, "w4a8_weight_scale")
+    x = x.to(device="npu", dtype=dtype)
+
+    with override_forward_context(ForwardContext()):
+        for step in range(3):
+            set_forward_context_denoise_step_idx(step)
+            actual = method.apply(layer, x, layer.bias).cpu()
+            # A8's documented GEMM output is BF16 before restoring the caller
+            # dtype; the reference does not reuse quantization or unpacking.
+            reference = expected.bfloat16().to(dtype) if step == 1 else expected.to(dtype)
+            torch.testing.assert_close(actual, reference, rtol=0, atol=0)
+            assert actual.dtype == dtype
+    assert (layer.weight.data_ptr(), layer.weight_scale.data_ptr()) == prepared_pointers
+
+
+@pytest.mark.cards_1
+@pytest.mark.parametrize("mode", ["single", "single_offline"])
+@pytest.mark.parametrize("policy", ["layer", "layer_and_step"])
+def test_mxfp4_layer_fallback(mode, policy, monkeypatch):
+    """Reuse the kernel/shape/cache assertions without multiplying the full dtype/bias matrix."""
+    _exercise_mxfp4_fallback(False, torch.bfloat16, (16, 1024), mode, monkeypatch, policy=policy)
+
+
+@pytest.mark.cards_1
+@pytest.mark.parametrize("mode", ["single", "single_offline"])
+def test_mxfp4_ocp_compatibility(mode, monkeypatch):
+    """OCP compatibility: A4 -> A8 -> A4 with the same W4 across requests."""
+    _exercise_mxfp4_fallback(False, torch.bfloat16, (16, 1024), mode, monkeypatch, policy="step", scale_alg=0)
diff --git a/vllm_omni/config/omni_config.py b/vllm_omni/config/omni_config.py
index 56b40b8367c..c13935489a5 100644
--- a/vllm_omni/config/omni_config.py
+++ b/vllm_omni/config/omni_config.py
@@ -817,6 +817,8 @@ class keeps the diffusion-only knobs from ``OmniDiffusionConfig`` without
     enable_stage_verification: bool = True
     prompt_file_path: str | None = None
     quantization_config: _QuantizationConfigType = None
+    # Internal provenance, retained across config projection and worker transport.
+    quantization_config_is_auto_detected: bool = False
     extras: dict[str, Any] = field(default_factory=dict)
 
     @field_validator("kv_transfer_config", mode="before")
@@ -964,6 +966,8 @@ def _propagate_quantization_from_tf_config(self, tf_config: Any) -> None:
             or (is_checkpoint_nvfp4 and self._is_generic_nvfp4_quant_config(self.quantization_config))
         )
         if should_use_checkpoint_config:
+            if self.quantization_config is None:
+                self.quantization_config_is_auto_detected = True
             self.quantization_config = quant_config
             if quant_method is not None:
                 self.additional_config.setdefault("auto_detected_quant_method", quant_method)
diff --git a/vllm_omni/diffusion/data.py b/vllm_omni/diffusion/data.py
index e1ce550d467..0ffd0c54ea4 100644
--- a/vllm_omni/diffusion/data.py
+++ b/vllm_omni/diffusion/data.py
@@ -1021,6 +1021,8 @@ class OmniDiffusionConfig:
     # str is resolved to {"method": <str>} internally.
     # Per-component: {"transformer": {"method": "fp8"}, "vae": None}
     quantization_config: str | QuantizationConfig | dict[str, Any] | None = None
+    # Internal provenance, retained across config projection and worker transport.
+    quantization_config_is_auto_detected: bool = False
     # Explicit runtime override for ModelOpt FP8 diffusion checkpoints. This
     # does not enable FP8 by itself; it only selects CUTLASS once the checkpoint
     # has already resolved to vLLM's ModelOpt FP8 linear method.
@@ -1358,6 +1360,8 @@ def _propagate_quantization_from_tf_config(self, tf_config: "TransformerConfig")
             or (is_checkpoint_nvfp4 and self._is_generic_nvfp4_quant_config(self.quantization_config))
         )
         if should_use_checkpoint_config:
+            if self.quantization_config is None:
+                self.quantization_config_is_auto_detected = True
             self.quantization_config = tf_config.quant_config
             logger.info(
                 "Auto-detected quantization '%s' from model config",
diff --git a/vllm_omni/diffusion/model_loader/diffusers_loader.py b/vllm_omni/diffusion/model_loader/diffusers_loader.py
index 78247e7b968..834887f4150 100644
--- a/vllm_omni/diffusion/model_loader/diffusers_loader.py
+++ b/vllm_omni/diffusion/model_loader/diffusers_loader.py
@@ -7,7 +7,7 @@
 import os
 import re
 import time
-from collections.abc import Generator, Iterable, Sequence
+from collections.abc import Callable, Generator, Iterable, Sequence
 from pathlib import Path
 from typing import cast
 
@@ -481,8 +481,14 @@ def _get_weight_sources(self, model: nn.Module) -> tuple["ComponentSource", ...]
         )
 
     def _get_expected_parameter_names(self, model: nn.Module) -> set[str]:
-        """Return parameter names that should be covered by strict load checks."""
-        all_parameter_names = {name for name, _ in model.named_parameters()}
+        """Return parameter names that should be covered by strict load checks.
+
+        A parameter with an initialized checkpoint default can explicitly set
+        ``is_checkpoint_optional``. It is still loaded when present on disk.
+        """
+        all_parameter_names = {
+            name for name, param in model.named_parameters() if not getattr(param, "is_checkpoint_optional", False)
+        }
         sources = self._get_weight_sources(model)
 
         # Keep strict behavior if no source metadata exists.
@@ -853,9 +859,24 @@ def load_model(
                     del model
                     return self.load_fresh_canonical_model()
             raise
+        self._log_w4a8_fallback_load_summaries(model)
         self._attach_offload_startup_state(model)
         return model
 
+    @staticmethod
+    def _log_w4a8_fallback_load_summaries(model: nn.Module) -> None:
+        """Ask discovered DiTs to report W4A8 state at the common load exit.
+
+        Each DiT derives readiness from its processed layers, so a deferred
+        weight plan cannot be mistaken for the ordinary or HSDP load path.
+        """
+        components = ModuleDiscovery.discover(model)
+        for component_name, dit in zip(components.dit_names, components.dits):
+            candidate = getattr(dit, "_log_w4a8_fallback_load_summary", None)
+            if callable(candidate):
+                reporter = cast(Callable[[str], None], candidate)
+                reporter(component_name)
+
     @staticmethod
     def _request_offload_after_quant(model: nn.Module) -> int:
         """Ask online-quant layers to return to host memory once quantized.
@@ -1065,6 +1086,16 @@ def load_weights(
         # that have loaded weights tracking currently.
         if loaded_weights is not None:
             weights_not_loaded = weights_to_load - loaded_weights
+            # Offline formats can require scales that older online loaders
+            # were allowed to synthesize. Do not apply that legacy tolerance
+            # to an explicitly required checkpoint tensor.
+            required_missing = {
+                name
+                for name, param in model.named_parameters()
+                if name in weights_not_loaded and getattr(param, "is_checkpoint_required", False)
+            }
+            if required_missing:
+                raise ValueError(f"Required weights were not initialized from checkpoint: {required_missing}")
             # NOTE: if the model is quantized, ignore not_loaded check for scale
             # weights. ModelOpt FP8 carries a per-tensor `weight_scale` and a
             # static activation `input_scale`, which the quant method may
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
index 15b0368641b..915fb45f740 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
@@ -179,8 +179,36 @@ def load_transformer_config(model_path: str, subfolder: str = "transformer", loc
     return {}
 
 
+def resolve_wan_transformer_quant_config(
+    config: dict, quant_config: QuantizationConfig | None, component: str
+) -> QuantizationConfig | None:
+    """Resolve the expert before applying its checkpoint's storage contract."""
+    from vllm_omni.quantization.component_config import ComponentQuantizationConfig
+    from vllm_omni.quantization.factory import resolve_quant_config_from_disk
+
+    # Wan experts are siblings: "transformer_2" must not inherit "transformer"
+    # through the generic layer-prefix resolver. Select the whole expert name.
+    component_quant_config = (
+        quant_config.component_configs.get(component, quant_config.default_config)
+        if isinstance(quant_config, ComponentQuantizationConfig)
+        else quant_config
+    )
+    quantization_disabled = isinstance(quant_config, ComponentQuantizationConfig) and component_quant_config is None
+    resolved_quant_config = resolve_quant_config_from_disk(component_quant_config, config.get("quantization_config"))
+    if quantization_disabled and resolved_quant_config is not None:
+        raise ValueError(
+            f"Quantization is disabled for component {component!r}, but its checkpoint declares quantization. "
+            "Use a BF16 checkpoint for this component or enable its matching quantization method."
+        )
+    return resolved_quant_config
+
+
 def create_transformer_from_config(
-    config: dict, quant_config: QuantizationConfig | None = None, prefix: str = ""
+    config: dict,
+    quant_config: QuantizationConfig | None = None,
+    prefix: str = "",
+    *,
+    component: str = "transformer",
 ) -> WanTransformer3DModel:
     """Create WanTransformer3DModel from config dict."""
     kwargs: dict = {}
@@ -216,11 +244,7 @@ def create_transformer_from_config(
     if "pos_embed_seq_len" in config:
         kwargs["pos_embed_seq_len"] = config["pos_embed_seq_len"]
 
-    if "quantization_config" in config:
-        from vllm_omni.quantization.factory import resolve_quant_config_from_disk
-
-        quant_config = resolve_quant_config_from_disk(quant_config, config["quantization_config"])
-
+    quant_config = resolve_wan_transformer_quant_config(config, quant_config, component)
     if quant_config is not None:
         kwargs["quant_config"] = quant_config
     if prefix:
@@ -460,13 +484,13 @@ def __init__(
         # Initialize transformers with correct config (weights loaded via load_weights)
         if load_transformer:
             transformer_config = load_transformer_config(model, "transformer", local_files_only)
-            self.transformer = self._create_transformer(transformer_config)
+            self.transformer = self._create_transformer(transformer_config, component="transformer")
         else:
             self.transformer = None
 
         if load_transformer_2:
             transformer_2_config = load_transformer_config(model, "transformer_2", local_files_only)
-            self.transformer_2 = self._create_transformer(transformer_2_config)
+            self.transformer_2 = self._create_transformer(transformer_2_config, component="transformer_2")
         else:
             self.transformer_2 = None
 
@@ -504,10 +528,17 @@ def __init__(
             enable_diffusion_pipeline_profiler=self.od_config.enable_diffusion_pipeline_profiler
         )
 
-    def _create_transformer(self, config: dict) -> WanTransformer3DModel:
+    def _create_transformer(self, config: dict, component: str = "transformer") -> WanTransformer3DModel:
         """Create a transformer from a config dict. Respects od_config.quantization_config."""
         quant_config = getattr(self.od_config, "quantization_config", None)
-        return create_transformer_from_config(config, quant_config=quant_config)
+        # Startup metadata describes the first expert, not a user policy for both.
+        if getattr(self.od_config, "quantization_config_is_auto_detected", False):
+            quant_config = None
+        return create_transformer_from_config(
+            config,
+            quant_config=quant_config,
+            component=component,
+        )
 
     @property
     def guidance_scale(self):
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
index 01bd53bb89b..1a75c40da83 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
@@ -304,25 +304,10 @@ def __init__(
         # Transformers (weights loaded via load_weights)
         # Load config from model directory or HF Hub to get correct in_channels for I2V models
         transformer_config = load_transformer_config(model, "transformer", local_files_only)
-        self.transformer = create_transformer_from_config(
-            transformer_config,
-            quant_config=od_config.quantization_config,
-        )
+        self.transformer = self._create_transformer(transformer_config, component="transformer")
         if self.has_transformer_2:
             transformer_2_config = load_transformer_config(model, "transformer_2", local_files_only)
-            t2_quant = transformer_2_config.get("quantization_config")
-            if isinstance(t2_quant, dict) and "quant_method" in t2_quant:
-                from vllm_omni.quantization.factory import build_quant_config
-
-                method = t2_quant["quant_method"]
-                kwargs = {k: v for k, v in t2_quant.items() if k != "quant_method"}
-                t2_quant = build_quant_config(method, **kwargs)
-            else:
-                t2_quant = None
-            self.transformer_2 = create_transformer_from_config(
-                transformer_2_config,
-                quant_config=t2_quant,
-            )
+            self.transformer_2 = self._create_transformer(transformer_2_config, component="transformer_2")
         else:
             self.transformer_2 = None
 
@@ -462,10 +447,13 @@ def encode_image(
         image_embeds = self.image_encoder(pixel_values, output_hidden_states=True)
         return image_embeds.hidden_states[-2]
 
-    def _create_transformer(self, config: dict) -> WanTransformer3DModel:
+    def _create_transformer(self, config: dict, component: str = "transformer") -> WanTransformer3DModel:
         """Create a transformer from a config dict. Respects od_config.quantization_config."""
         quant_config = getattr(self.od_config, "quantization_config", None)
-        return create_transformer_from_config(config, quant_config=quant_config)
+        # Startup metadata describes the first expert, not a user policy for both.
+        if getattr(self.od_config, "quantization_config_is_auto_detected", False):
+            quant_config = None
+        return create_transformer_from_config(config, quant_config=quant_config, component=component)
 
     def forward(self, req: DiffusionRequestBatch) -> list[DiffusionOutput]:
         sampling_params_list = req.sampling_params_list
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_vace.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_vace.py
index aeecff60807..0d5f3cd676a 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_vace.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_vace.py
@@ -28,6 +28,7 @@
 from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import (
     Wan22Pipeline,
     load_wan_weights_with_optional_gate,
+    resolve_wan_transformer_quant_config,
     retrieve_latents,
 )
 from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import (
@@ -60,6 +61,8 @@ def create_vace_transformer_from_config(
     config: dict,
     quant_config: QuantizationConfig | None = None,
     prefix: str = "",
+    *,
+    component: str = "transformer",
 ) -> WanVACETransformer3DModel:
     """Create WanVACETransformer3DModel from config dict."""
     kwargs = {}
@@ -97,6 +100,7 @@ def create_vace_transformer_from_config(
         kwargs["vace_layers"] = config["vace_layers"]
     if "vace_in_channels" in config:
         kwargs["vace_in_channels"] = config["vace_in_channels"]
+    quant_config = resolve_wan_transformer_quant_config(config, quant_config, component)
     if quant_config is not None:
         kwargs["quant_config"] = quant_config
     if prefix:
@@ -205,10 +209,13 @@ def __init__(
 
         super().__init__(od_config=od_config, prefix=prefix)
 
-    def _create_transformer(self, config: dict) -> WanVACETransformer3DModel:
+    def _create_transformer(self, config: dict, component: str = "transformer") -> WanVACETransformer3DModel:
         """Build VACE transformer. Respects od_config.quantization_config."""
         quant_config = getattr(self.od_config, "quantization_config", None)
-        return create_vace_transformer_from_config(config, quant_config=quant_config)
+        # Startup metadata describes the first expert, not a user policy for both.
+        if getattr(self.od_config, "quantization_config_is_auto_detected", False):
+            quant_config = None
+        return create_vace_transformer_from_config(config, quant_config=quant_config, component=component)
 
     def diffuse(
         self,
diff --git a/vllm_omni/diffusion/models/wan2_2/wan2_2_transformer.py b/vllm_omni/diffusion/models/wan2_2/wan2_2_transformer.py
index dbc55560410..2808dcee7f1 100644
--- a/vllm_omni/diffusion/models/wan2_2/wan2_2_transformer.py
+++ b/vllm_omni/diffusion/models/wan2_2/wan2_2_transformer.py
@@ -18,7 +18,7 @@
 )
 from vllm.logger import init_logger
 from vllm.model_executor.layers.conv import Conv3dLayer
-from vllm.model_executor.layers.linear import ColumnParallelLinear, QKVParallelLinear, RowParallelLinear
+from vllm.model_executor.layers.linear import ColumnParallelLinear, LinearBase, QKVParallelLinear, RowParallelLinear
 from vllm.model_executor.layers.quantization.base_config import QuantizationConfig
 from vllm.model_executor.model_loader.weight_utils import default_weight_loader
 from vllm.model_executor.models.utils import (
@@ -45,6 +45,7 @@
 from vllm_omni.diffusion.layers.norm import LayerNorm, RMSNorm
 from vllm_omni.diffusion.layers.rope import RotaryEmbeddingWan
 from vllm_omni.platforms import current_omni_platform
+from vllm_omni.quantization.mxfp4_config import NPUMxfp4LinearMethod
 
 logger = init_logger(__name__)
 
@@ -985,6 +986,68 @@ def __init__(
         # ROPE helper
         self._cached_rope_emb = None
         self._cached_rope_resolution = None
+        self._validate_w4a8_fallback_layers(quant_config)
+
+    def _validate_w4a8_fallback_layers(self, quant_config: QuantizationConfig | None) -> None:
+        """Reject checkpoint aliases/typos before loading weights or running inference."""
+        requested = tuple(getattr(quant_config, "w4a8_fallback_layers", []))
+        self._w4a8_fallback_layers = requested
+        self._local_w4a8_fallback_layers: tuple[str, ...] = ()
+        if not requested:
+            return
+        modules = dict(self.named_modules())
+        missing_pp_prefixes = [name for name, module in modules.items() if isinstance(module, PPMissingLayer)]
+        local_layers = [
+            name for name in requested if not any(name.startswith(prefix + ".") for prefix in missing_pp_prefixes)
+        ]
+        self._local_w4a8_fallback_layers = tuple(local_layers)
+        invalid = [name for name in local_layers if not isinstance(modules.get(name), LinearBase)]
+        if invalid:
+            raise ValueError(
+                "w4a8_fallback_layers requires exact runtime Linear paths relative to each Wan transformer; "
+                f"unknown/non-Linear paths: {invalid}. Use attn1.to_qkv for fused self-attention, "
+                "not checkpoint attn1.to_q/to_k/to_v names."
+            )
+
+    def _log_w4a8_fallback_load_summary(self, component_name: str) -> None:
+        """Log post-load transforms/cache readiness, not numerical acceptance."""
+        requested = self._w4a8_fallback_layers
+        if not requested:
+            return
+        modules = dict(self.named_modules())
+        local_layers = self._local_w4a8_fallback_layers
+        selected_layers = [
+            name for name in local_layers if getattr(modules[name].quant_method, "is_w4a8_fallback_layer", False)
+        ]
+        bf16_overrides = [name for name in local_layers if name not in selected_layers]
+        processed = [
+            name
+            for name in selected_layers
+            if getattr(modules[name], "_already_called_process_weights_after_loading", False)
+        ]
+        if not selected_layers:
+            processing_state = "not-required"
+        elif len(processed) == len(selected_layers):
+            processing_state = "ready"
+        else:
+            processing_state = "not-ready"
+
+        def qualified(names: Iterable[str]) -> list[str]:
+            return [f"{component_name}.{name}" for name in names]
+
+        logger.info(
+            "Wan W4A8 post-load summary: component=%s; selected=%d %s; BF16 overrides=%d %s; "
+            "weight/A8 processing state=%s (%d/%d selected layers processed); other PP ranks=%d",
+            component_name,
+            len(selected_layers),
+            qualified(selected_layers),
+            len(bf16_overrides),
+            qualified(bf16_overrides),
+            processing_state,
+            len(processed),
+            len(selected_layers),
+            len(requested) - len(local_layers),
+        )
 
     @property
     def dtype(self) -> torch.dtype:
@@ -1155,7 +1218,22 @@ def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
         }
 
         params_dict = dict(self.named_parameters())
+        single_scale_prefixes = {
+            name
+            for name, module in self.named_modules()
+            if isinstance(getattr(module, "quant_method", None), NPUMxfp4LinearMethod)
+        }
+
+        def reject_dualscale_tensor(name: str) -> None:
+            if name.endswith(".weight_dual_scale") and name.rsplit(".", 1)[0] in single_scale_prefixes:
+                raise ValueError(
+                    f"Single-scale mxfp4 cannot load DualScale tensor {name}; "
+                    "changing quant_method does not convert a checkpoint."
+                )
+
         loaded_params: set[str] = set()
+        loaded_qkv_shards: dict[str, set[str]] = {}
+        qkv_smooth_scales: dict[str, torch.Tensor] = {}
 
         for name, loaded_weight in weights:
             name = weight_name_remapping.get(name, name)
@@ -1166,15 +1244,32 @@ def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
             # Pre-fused to_qkv tensors (from offline MXFP8 merged checkpoint) fall
             # through to the else branch and are loaded directly.
             for param_name, weight_name, shard_id in stacked_params_mapping:
-                if weight_name not in original_name:
+                if f"{weight_name}." not in original_name:
                     continue
-                lookup_name = original_name.replace(weight_name, param_name)
+                lookup_name = original_name.replace(f"{weight_name}.", f"{param_name}.", 1)
+                reject_dualscale_tensor(lookup_name)
                 # Skip weights that belong to PP stages other than this one
                 if is_pp_missing_parameter(lookup_name, self) or lookup_name not in params_dict:
                     break
                 param = params_dict[lookup_name]
+                if lookup_name.endswith(".mul_scale"):
+                    previous_scale = qkv_smooth_scales.get(lookup_name)
+                    if previous_scale is not None and not torch.equal(previous_scale, loaded_weight):
+                        raise ValueError(f"Fused Q/K/V must share the same Smooth tensor: {lookup_name}")
+                    if previous_scale is None:
+                        qkv_smooth_scales[lookup_name] = loaded_weight.clone()
                 weight_loader = param.weight_loader
                 weight_loader(param, loaded_weight, shard_id)
+                loaded_params.add(original_name)
+                if getattr(param, "output_dim", None) is None and not getattr(param, "needs_scalar_to_array", False):
+                    # Shared input-channel Smooth is a complete tensor even
+                    # when supplied under a single Q/K/V source name.
+                    loaded_params.add(lookup_name)
+                else:
+                    shards = loaded_qkv_shards.setdefault(lookup_name, set())
+                    shards.add(shard_id)
+                    if shards == {"q", "k", "v"}:
+                        loaded_params.add(lookup_name)
                 break
             else:
                 # diffusers: ffn.net.0.proj.weight -> our: ffn.net_0.proj.weight
@@ -1198,6 +1293,7 @@ def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
                 if is_pp_missing_parameter(lookup_name, self):
                     continue
 
+                reject_dualscale_tensor(lookup_name)
                 if lookup_name not in params_dict:
                     logger.warning(f"Skipping weight {original_name} -> {lookup_name}")
                     continue
@@ -1222,8 +1318,6 @@ def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
 
                 weight_loader = getattr(param, "weight_loader", default_weight_loader)
                 weight_loader(param, loaded_weight)
-
-            loaded_params.add(original_name)
-            loaded_params.add(lookup_name)
+                loaded_params.update((original_name, lookup_name))
 
         return loaded_params
diff --git a/vllm_omni/quantization/factory.py b/vllm_omni/quantization/factory.py
index 8f15aaf50dd..c0975f65106 100644
--- a/vllm_omni/quantization/factory.py
+++ b/vllm_omni/quantization/factory.py
@@ -446,6 +446,33 @@ def _disk_marks_serialized(qc_kwargs: dict[str, Any], quant_config: object) -> b
     return False
 
 
+_MXFP4_SERIALIZED_FLAGS = {
+    "mxfp4": "is_checkpoint_mxfp4_serialized",
+    "mxfp4_dualscale": "is_checkpoint_serialized",
+}
+
+
+def _normalize_serialized_mxfp4_layer_policy(qc_method: str, qc_kwargs: dict[str, Any]) -> None:
+    """Canonicalize the BF16 layer policy owned by serialized MXFP4 metadata.
+
+    A serialized checkpoint config is a complete storage contract: an omitted
+    layer list means no explicit BF16 layers. Method-only online metadata does
+    not carry that contract and must leave caller-provided layer policy intact.
+    """
+    method = _normalize_quant_method_alias(qc_method)
+    if method is None:
+        return
+    serialized_flag = _MXFP4_SERIALIZED_FLAGS.get(method)
+    if serialized_flag is None or not qc_kwargs.get(serialized_flag):
+        return
+
+    ignored_layers = qc_kwargs.get("ignored_layers")
+    if not ignored_layers:
+        ignored_layers = qc_kwargs.get("modules_to_not_convert")
+    qc_kwargs["ignored_layers"] = ignored_layers or []
+    qc_kwargs.pop("modules_to_not_convert", None)
+
+
 def resolve_quant_config_from_disk(
     quant_config: QuantizationConfig | None,
     disk_qc: dict[str, Any] | str | None,
@@ -460,22 +487,24 @@ def resolve_quant_config_from_disk(
       - quant_config is None: auto-detect from disk_qc (full build).
       - Methods mismatch: raise ValueError — prevents silent weight corruption.
       - Disk marks serialized but quant_config is online: rebuild from disk.
-      - ignored_layers differ: rebuild from disk (per-transformer BF16 routing).
+      - Serialized MXFP4 metadata owns the complete BF16 layer policy; omitted
+        ignored_layers means the checkpoint default (no explicit BF16 layers).
+      - Method-only metadata carries no storage policy and preserves caller
+        ignored_layers and runtime fallback policies.
     """
     if disk_qc is None:
         return quant_config
 
     if isinstance(disk_qc, str):
-        if quant_config is None:
-            logger.info("Auto-detected quantization from config.json: method=%s", disk_qc)
-            return build_quant_config(disk_qc)
-        return quant_config
-
-    if not isinstance(disk_qc, Mapping) or "quant_method" not in disk_qc:
-        return quant_config
+        qc_method = disk_qc
+        qc_kwargs: dict[str, Any] = {}
+    else:
+        if not isinstance(disk_qc, Mapping) or "quant_method" not in disk_qc:
+            return quant_config
+        qc_method = disk_qc["quant_method"]
+        qc_kwargs = {k: v for k, v in disk_qc.items() if k != "quant_method"}
 
-    qc_method: str = disk_qc["quant_method"]
-    qc_kwargs: dict[str, Any] = {k: v for k, v in disk_qc.items() if k != "quant_method"}
+    _normalize_serialized_mxfp4_layer_policy(qc_method, qc_kwargs)
 
     if quant_config is None:
         logger.info(
@@ -494,6 +523,26 @@ def resolve_quant_config_from_disk(
             "Pass a matching --quantization flag or omit it for auto-detection."
         )
 
+    if isinstance(disk_qc, str):
+        return quant_config
+
+    # Serialized checkpoint metadata owns storage and BF16 layer routing. The
+    # active config owns runtime step/layer policies, including explicit empty
+    # lists. Preserve them when each cascade transformer rebuilds from disk.
+    for policy in ("w4a8_fallback_steps", "w4a8_fallback_layers"):
+        if hasattr(quant_config, policy):
+            qc_kwargs[policy] = list(getattr(quant_config, policy))
+    if hasattr(quant_config, "mxfp4_scale_alg"):
+        # Runtime activation policy is independent of how offline W4 was made.
+        qc_kwargs["mxfp4_scale_alg"] = quant_config.mxfp4_scale_alg
+    if hasattr(quant_config, "require_smooth_scale"):
+        disk_requires_smooth = qc_kwargs.get("require_smooth_scale", False)
+        if not isinstance(disk_requires_smooth, bool):
+            raise ValueError("require_smooth_scale must be a boolean")
+        # Either a calibrated checkpoint or an explicit caller can require
+        # Smooth. Per-expert rebuilds must never weaken that requirement.
+        qc_kwargs["require_smooth_scale"] = quant_config.require_smooth_scale or disk_requires_smooth
+
     if _disk_marks_serialized(qc_kwargs, quant_config):
         logger.info(
             "config.json marks checkpoint as serialized; switching to offline %s mode.",
@@ -501,6 +550,14 @@ def resolve_quant_config_from_disk(
         )
         return build_quant_config(qc_method, **qc_kwargs)
 
+    if (
+        "require_smooth_scale" in qc_kwargs
+        and hasattr(quant_config, "require_smooth_scale")
+        and qc_kwargs["require_smooth_scale"] != quant_config.require_smooth_scale
+    ):
+        logger.info("config.json Smooth requirement differs from active config; rebuilding quant_config.")
+        return build_quant_config(qc_method, **qc_kwargs)
+
     # AutoRound MXFP checkpoints use data_type="mx_fp" instead of
     # is_checkpoint_*_serialized; rebuild so the offline MXFP4/MXFP8 path is
     # selected according to the checkpoint's bit width.
diff --git a/vllm_omni/quantization/mxfp4_config.py b/vllm_omni/quantization/mxfp4_config.py
index ac93eaa00a6..43f3efa9de2 100644
--- a/vllm_omni/quantization/mxfp4_config.py
+++ b/vllm_omni/quantization/mxfp4_config.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """W4A4 MXFP4 (Microscaling FP4) online/offline quantization for diffusion transformers.
 
 Architecture mirrors mxfp8_config.py:
@@ -41,7 +41,7 @@
   and npu_dual_level_quant_matmul. Weight stored in NZ hardware format via npu_format_cast.
 
   Checkpoint tensor shapes for dual-scale:
-    weight            : (N, K)          float8_e4m3fn     – FP4 packed
+    weight            : (N, K)         float8_e4m3fn     – numeric FP4 values (packed after loading)
     weight_scale      : (N, K//32)      uint8    – fine scale (float8_e8m0fnu bits)
     weight_dual_scale : (N, K//512, 1)  float32  – coarse scale (extra dim avoids shape assert)
     mul_scale         : (K,)            float32  – per-input-channel activation pre-scale
@@ -51,9 +51,9 @@
 
 from __future__ import annotations
 
-import re
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
+import regex as re
 import torch
 from torch.nn import Module
 from vllm.logger import init_logger
@@ -83,9 +83,54 @@
 if TYPE_CHECKING:
     from vllm.model_executor.models.utils import WeightsMapper
 
+
 logger = init_logger(__name__)
 
 
+def _validate_w4a8_fallback_steps(steps: list[int] | None) -> list[int]:
+    if steps is None:
+        return []
+    if not isinstance(steps, list) or any(type(step) is not int or step < 0 for step in steps):
+        raise ValueError("w4a8_fallback_steps must be a list of non-negative integer denoise step indices.")
+    return sorted(set(steps))
+
+
+def _validate_w4a8_fallback_layers(layers: list[str] | None) -> list[str]:
+    """Names are exact runtime Linear paths, not checkpoint aliases or patterns."""
+    if layers is None:
+        return []
+    if not isinstance(layers, list) or any(
+        not isinstance(name, str) or re.fullmatch(r"[A-Za-z_][A-Za-z_0-9]*(?:\.[A-Za-z_0-9]+)*", name) is None
+        for name in layers
+    ):
+        raise ValueError("w4a8_fallback_layers must be a list of non-empty exact runtime Linear paths.")
+    return sorted(set(layers))
+
+
+def _is_w4a8_fallback_step(steps: list[int]) -> bool:
+    """Read the request's zero-based denoise index; never keep state on a Linear."""
+    if not steps:
+        return False
+
+    from vllm_omni.diffusion.forward_context import (
+        get_forward_context,
+        is_forward_context_available,
+    )
+
+    step = get_forward_context().denoise_step_idx if is_forward_context_available() else None
+    if step is None:
+        raise RuntimeError("W4A8 step fallback requires a pipeline that publishes its denoise step in ForwardContext.")
+    return step in steps
+
+
+def _validate_smooth_scale(scale: torch.Tensor) -> None:
+    """Reject malformed calibration before loading or activation dtype conversion."""
+    if scale.ndim != 1 or not scale.is_floating_point():
+        raise ValueError("MXFP4 mul_scale must be a one-dimensional floating-point Smooth tensor.")
+    if not bool(torch.isfinite(scale).all()) or not bool((scale > 0).all()):
+        raise ValueError("MXFP4 mul_scale must contain finite, strictly positive Smooth values.")
+
+
 # ---------------------------------------------------------------------------
 # Config
 # ---------------------------------------------------------------------------
@@ -105,10 +150,24 @@ def __init__(
         self,
         is_checkpoint_mxfp4_serialized: bool = False,
         ignored_layers: list[str] | None = None,
+        w4a8_fallback_steps: list[int] | None = None,
+        require_smooth_scale: bool = False,
+        w4a8_fallback_layers: list[str] | None = None,
+        mxfp4_scale_alg: int = 0,
     ) -> None:
         super().__init__()
         self.is_checkpoint_mxfp4_serialized = is_checkpoint_mxfp4_serialized
         self.ignored_layers = ignored_layers or []
+        self.w4a8_fallback_steps = _validate_w4a8_fallback_steps(w4a8_fallback_steps)
+        self.w4a8_fallback_layers = _validate_w4a8_fallback_layers(w4a8_fallback_layers)
+        if not isinstance(require_smooth_scale, bool):
+            raise ValueError("require_smooth_scale must be a boolean")
+        if require_smooth_scale and not self.is_checkpoint_mxfp4_serialized:
+            raise ValueError("require_smooth_scale requires an offline MXFP4 checkpoint")
+        self.require_smooth_scale = require_smooth_scale
+        if type(mxfp4_scale_alg) is not int or mxfp4_scale_alg not in (0, 2):
+            raise ValueError("mxfp4_scale_alg must be 0 (OCP MX) or 2 (UOS with dst_type_max=7.25).")
+        self.mxfp4_scale_alg = mxfp4_scale_alg
 
     @classmethod
     def get_name(cls) -> QuantizationMethods:
@@ -139,6 +198,10 @@ def from_config(cls, config: dict[str, Any]) -> DiffusionMXFP4Config:
         return cls(
             is_checkpoint_mxfp4_serialized=is_serialized,
             ignored_layers=ignored_layers,
+            w4a8_fallback_steps=config.get("w4a8_fallback_steps"),
+            w4a8_fallback_layers=config.get("w4a8_fallback_layers"),
+            require_smooth_scale=config.get("require_smooth_scale", False),
+            mxfp4_scale_alg=config.get("mxfp4_scale_alg", 0),
         )
 
     def get_quant_method(
@@ -155,9 +218,15 @@ def get_quant_method(
                 return UnquantizedLinearMethod()
             if current_omni_platform.is_npu():
                 if self.is_checkpoint_mxfp4_serialized:
-                    return NPUMxfp4LinearMethod(self)
-                return NPUMxfp4OnlineLinearMethod(self)
+                    return NPUMxfp4LinearMethod(self, prefix=prefix)
+                return NPUMxfp4OnlineLinearMethod(self, prefix=prefix)
             if current_omni_platform.is_rocm():
+                if self.mxfp4_scale_alg != 0:
+                    raise NotImplementedError("MXFP4 UOS quantization is currently only supported on NPU (Ascend).")
+                if self.w4a8_fallback_steps or self.w4a8_fallback_layers:
+                    raise NotImplementedError(
+                        "MXFP4 W4A8 step/layer fallback is currently only supported on NPU (Ascend)."
+                    )
                 gcn_arch = torch.cuda.get_device_properties(torch.accelerator.current_device_index()).gcnArchName
                 if "gfx950" not in gcn_arch:
                     raise NotImplementedError(f"MXFP4 on ROCm requires gfx950 (MI355X). Detected: {gcn_arch}")
@@ -176,6 +245,56 @@ def get_quant_method(
 # ---------------------------------------------------------------------------
 
 
+def _npu_quantize_mxfp4(x: torch.Tensor, scale_alg: int) -> tuple[torch.Tensor, torch.Tensor]:
+    """Quantize weight or activation using the same explicit FP4 algorithm."""
+    import torch_npu
+
+    # Universal Optimal Scaling (Qmax=7.25), MXAttention Section 4.1:
+    # https://arxiv.org/abs/2607.24377
+    scale_kwargs = {"dst_type_max": 7.25} if scale_alg == 2 else {}
+    return torch_npu.npu_dynamic_mx_quant(
+        x,
+        dst_type=torch_npu.float4_e2m1fn_x2,
+        axis=-1,
+        block_size=32,
+        round_mode="rint",
+        scale_alg=scale_alg,
+        **scale_kwargs,
+    )
+
+
+def _npu_w4a8_matmul(
+    x: torch.Tensor,
+    weight: torch.Tensor,
+    weight_scale: torch.Tensor,
+    bias: torch.Tensor | None,
+    output_dtype: torch.dtype,
+) -> torch.Tensor:
+    """MXFP8 activations with prepared single-scale MXFP4 weights (N, K)."""
+    import torch_npu
+
+    x_q, x_scale = torch_npu.npu_dynamic_mx_quant(
+        x, dst_type=torch_npu.float8_e4m3fn, axis=-1, block_size=32, round_mode="rint", scale_alg=0
+    )
+    # Use the BF16 output/bias pair supported by the mixed FP8/FP4 kernel
+    # in the target A5 runtime. Restore the caller's dtype afterwards.
+    if bias is not None:
+        bias = bias.to(torch.bfloat16).reshape(1, -1)
+    output = torch_npu.npu_quant_matmul(
+        x_q,
+        weight.transpose(0, 1),
+        weight_scale.transpose(0, 1),
+        scale_dtype=torch_npu.float8_e8m0fnu,
+        x2_dtype=torch_npu.float4_e2m1fn_x2,
+        pertoken_scale=x_scale,
+        pertoken_scale_dtype=torch_npu.float8_e8m0fnu,
+        bias=bias,
+        output_dtype=torch.bfloat16,
+        group_sizes=[0, 0, 32],
+    )
+    return output.to(output_dtype)
+
+
 class NPUMxfp4LinearMethod(MXFPLinearMethodBase):
     """NPU W4A4 MXFP4 offline linear method for pre-quantized checkpoints.
 
@@ -187,7 +306,8 @@ class NPUMxfp4LinearMethod(MXFPLinearMethodBase):
     NPUMxfp4OnlineLinearMethod normalizes to the same layout so apply() is shared.
     """
 
-    def __init__(self, quant_config: DiffusionMXFP4Config) -> None:
+    def __init__(self, quant_config: DiffusionMXFP4Config, *, prefix: str = "") -> None:
+        self.is_w4a8_fallback_layer = prefix in quant_config.w4a8_fallback_layers
         self.quant_config = quant_config
         self.out_dtype = torch.get_default_dtype()
 
@@ -210,11 +330,14 @@ def create_weights(
         layer.orig_dtype = params_dtype
         layer.weight_block_size = None
 
-        # BF16 placeholder; cast to float4_e2m1fn_x2 in process_weights.
         layer.register_parameter(
             "weight",
             ModelWeightParameter(
-                data=torch.empty(output_size_per_partition, input_size_per_partition, dtype=params_dtype),
+                data=torch.empty(
+                    output_size_per_partition,
+                    input_size_per_partition,
+                    dtype=params_dtype,
+                ),
                 input_dim=1,
                 output_dim=0,
                 weight_loader=weight_loader,
@@ -234,12 +357,42 @@ def create_weights(
             ),
         )
 
+        # Older single-scale checkpoints have no Smooth tensor. Keep their
+        # identity transform while allowing calibrated checkpoints to load it.
+        def smooth_weight_loader(
+            param: ModelWeightParameter, loaded_weight: torch.Tensor, *args: Any, **kwargs: Any
+        ) -> None:
+            _validate_smooth_scale(loaded_weight)
+            if not callable(weight_loader):
+                raise ValueError("Loading MXFP4 Smooth requires a callable weight_loader")
+            weight_loader(param, loaded_weight, *args, **kwargs)
+
+        layer.register_parameter(
+            "mul_scale",
+            ModelWeightParameter(
+                data=torch.ones(input_size_per_partition, dtype=torch.float32),
+                input_dim=0,
+                output_dim=None,
+                weight_loader=smooth_weight_loader,
+            ),
+        )
+        setattr(layer.mul_scale, "ignore_warning", True)
+        setattr(layer.mul_scale, "is_checkpoint_optional", not self.quant_config.require_smooth_scale)
+        if self.quant_config.is_checkpoint_mxfp4_serialized:
+            setattr(layer.weight_scale, "is_checkpoint_required", True)
+
     def process_weights_after_loading(self, layer: Module) -> None:
         if getattr(layer, "_already_called_process_weights_after_loading", False):
             return
 
         import torch_npu
 
+        smooth_param = cast(torch.Tensor, layer.mul_scale)
+        _validate_smooth_scale(smooth_param)
+        smooth = smooth_param.data.to(dtype=cast(torch.dtype, layer.orig_dtype)).contiguous()
+        # Finite FP32 values can overflow or underflow in the activation dtype.
+        _validate_smooth_scale(smooth)
+
         # NPU: cast to float4_e2m1fn_x2. Weight stays (N, K) — no pre-transpose.
         w = layer.weight
         if w.dtype != torch_npu.float4_e2m1fn_x2:
@@ -258,15 +411,31 @@ def process_weights_after_loading(self, layer: Module) -> None:
 
         replace_parameter(layer, "weight", w)
         replace_parameter(layer, "weight_scale", s)
+        # Keep loader metadata while converting the calibration tensor once.
+        layer.mul_scale.data = smooth.to(device=cast(torch.Tensor, w).device)
         layer._already_called_process_weights_after_loading = True
 
     # --- NPU MXFP4 ops — shared with online path via inheritance ---
 
-    def _quantize_activation(self, x: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
-        import torch_npu
+    def _apply_inner(
+        self,
+        layer: torch.nn.Module,
+        x: torch.Tensor,
+        bias: torch.Tensor | None,
+        ori_dtype: torch.dtype,
+    ) -> torch.Tensor:
+        # Online quantization has no calibrated Smooth tensor. For offline
+        # weights the same pre-scale must precede both A4 and A8 quantization.
+        if (mul_scale := getattr(layer, "mul_scale", None)) is not None:
+            x = x * mul_scale.to(x.dtype)
+        if self.is_w4a8_fallback_layer or _is_w4a8_fallback_step(self.quant_config.w4a8_fallback_steps):
+            return _npu_w4a8_matmul(
+                x, cast(torch.Tensor, layer.weight), cast(torch.Tensor, layer.weight_scale), bias, ori_dtype
+            )
+        return super()._apply_inner(layer, x, bias, ori_dtype)
 
-        # No dst_type: npu_dynamic_mx_quant defaults to float4_e2m1fn_x2.
-        return torch_npu.npu_dynamic_mx_quant(x)
+    def _quantize_activation(self, x: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        return _npu_quantize_mxfp4(x, self.quant_config.mxfp4_scale_alg)
 
     def _quant_matmul(
         self,
@@ -318,8 +487,6 @@ def process_weights_after_loading(self, layer: Module) -> None:
         if getattr(layer, "_already_called_process_weights_after_loading", False):
             return
 
-        import torch_npu
-
         if layer.weight.device == torch.device("meta"):
             weight = ModelWeightParameter(
                 data=torch.empty_like(layer.weight, device=layer._load_device),
@@ -331,8 +498,10 @@ def process_weights_after_loading(self, layer: Module) -> None:
             layer.register_parameter("weight", weight)
             initialize_single_dummy_weight(layer.weight)
 
-        # NPU: quantize BF16/FP16 (N, K) → FP4. No dst_type → float4_e2m1fn_x2.
-        weight_fp4, weight_scale_raw = torch_npu.npu_dynamic_mx_quant(layer.weight)
+        # Prepare once; offline checkpoints keep their existing weight algorithm.
+        weight_fp4, weight_scale_raw = _npu_quantize_mxfp4(
+            cast(torch.Tensor, layer.weight), self.quant_config.mxfp4_scale_alg
+        )
 
         # Weight stays (N, K) — no pre-transpose for FP4 packed format.
         # Scale: (N, S) → (N, S/2, 2). Not pre-transposed; done inline in _quant_matmul.
@@ -497,7 +666,7 @@ class NPUMxfp4DualScaleLinearMethod(MXFPLinearMethodBase):
     """NPU W4A4 MXFP4 dual-scale offline method for pre-quantized checkpoints.
 
     Checkpoint tensors and their canonical post-load shapes:
-      weight            : (N, K) float8_e4m3fn       – FP4 packed (2 values per byte)
+      weight            : (N, K) float8_e4m3fn – numeric FP4 values; packed into NZ after loading
       weight_scale      : (N, K//32) uint8  – fine scale (float8_e8m0fnu bits); reshaped to (N, K//64, 2)
       weight_dual_scale : (N, K//512, 1) float32 – coarse scale; transposed to (K//512, N)
       mul_scale         : (K,) float32      – per-input-channel activation pre-scale (from calibration)
@@ -509,7 +678,7 @@ class NPUMxfp4DualScaleLinearMethod(MXFPLinearMethodBase):
     Reference: MindIE-SD W4A4MXFP4DualQuantLinear.
     """
 
-    def __init__(self, quant_config: Any) -> None:
+    def __init__(self, quant_config: DiffusionMXFP4DualScaleMixedConfig) -> None:
         self.quant_config = quant_config
         self.out_dtype = torch.get_default_dtype()
 
@@ -532,7 +701,7 @@ def create_weights(
         layer.orig_dtype = params_dtype
         layer.weight_block_size = None
 
-        # FP4 packed: 2 values per float8_e4m3fn byte → checkpoint stores as float8_e4m3fn; register as BF16
+        # Checkpoint FP4 values are stored numerically in FP8; BF16 preserves them exactly.
         layer.register_parameter(
             "weight",
             ModelWeightParameter(
@@ -587,6 +756,7 @@ def create_weights(
             ),
         )
         setattr(layer.mul_scale, "ignore_warning", True)
+        setattr(layer.weight_scale, "is_checkpoint_required", True)
 
     def process_weights_after_loading(self, layer: Module) -> None:
         if getattr(layer, "_already_called_process_weights_after_loading", False):
@@ -594,7 +764,7 @@ def process_weights_after_loading(self, layer: Module) -> None:
 
         import torch_npu
 
-        # float8_e4m3fn (FP4 packed) → float4_e2m1fn_x2 → NZ hardware format (format ID 29).
+        # Numeric FP4 values → packed float4_e2m1fn_x2 → NZ hardware format (format ID 29).
         # NZ layout is required by npu_dual_level_quant_matmul for FP4 weight matrices.
         w = torch_npu.npu_dtype_cast(layer.weight.data.npu(), torch_npu.float4_e2m1fn_x2)
         w = torch_npu.npu_format_cast(w.view(torch.int8), 29, customize_dtype=torch.int8)
@@ -631,7 +801,10 @@ def _apply_inner(
         """
         if ori_dtype not in (torch.bfloat16, torch.float16):
             x = x.to(torch.bfloat16)
-        x_q, l0_scale, l1_scale = self._quantize_activation(x, layer.mul_scale)
+        # The dual-level activation kernel requires x and Smooth to have the
+        # same dtype. Prepared calibration scales are BF16, including online.
+        smooth_scale = cast(torch.Tensor, layer.mul_scale).to(x.dtype)
+        x_q, l0_scale, l1_scale = self._quantize_activation(x, smooth_scale)
         return self._quant_matmul(x_q, l0_scale, l1_scale, layer, bias, ori_dtype)
 
     def _quantize_activation(  # type: ignore[override]
@@ -785,11 +958,20 @@ def __init__(
         is_checkpoint_serialized: bool = False,
         ignored_layers: list[str] | None = None,
         num_bf16_fallback_layers: int = 5,
+        w4a8_fallback_steps: list[int] | None = None,
+        w4a8_fallback_layers: list[str] | None = None,
     ) -> None:
         super().__init__()
         self.is_checkpoint_serialized = is_checkpoint_serialized
         self.ignored_layers = ignored_layers or []
         self.num_bf16_fallback_layers = num_bf16_fallback_layers
+        self.w4a8_fallback_steps = _validate_w4a8_fallback_steps(w4a8_fallback_steps)
+        self.w4a8_fallback_layers = _validate_w4a8_fallback_layers(w4a8_fallback_layers)
+        if self.w4a8_fallback_steps or self.w4a8_fallback_layers:
+            raise ValueError(
+                "mxfp4_dualscale does not support W4A8 fallback. Use mxfp4 with single-scale weights; "
+                "changing a DualScale checkpoint's method name does not convert its storage format."
+            )
 
     @classmethod
     def get_name(cls) -> QuantizationMethods:
@@ -822,6 +1004,8 @@ def from_config(cls, config: dict[str, Any]) -> DiffusionMXFP4DualScaleMixedConf
             is_checkpoint_serialized=is_serialized,
             ignored_layers=ignored_layers,
             num_bf16_fallback_layers=num_bf16_fallback_layers,
+            w4a8_fallback_steps=config.get("w4a8_fallback_steps"),
+            w4a8_fallback_layers=config.get("w4a8_fallback_layers"),
         )
 
     def get_quant_method(

From f1a6e7ce2a8fceb1417ec86b0b49a6386601ac65 Mon Sep 17 00:00:00 2001
From: maithilijoshi20 <97733343+maithilijoshi20@users.noreply.github.com>
Date: Thu, 17 Sep 2026 12:47:38 +0900
Subject: [PATCH 055/105] [Core] Retain structured configs through runtime
 startup (#6849)

Signed-off-by: maithilijoshi20 <97733343+maithilijoshi20@users.noreply.github.com>
---
 docs/design/architecture_overview.md          |  12 +-
 .../test_factory_integration.py               |  31 ++-
 tests/config/test_forced_aligner_injection.py |  36 ++++
 tests/config/test_omni_config.py              |  25 +++
 .../test_async_omni_qwen_image_generate.py    |  10 +
 .../offline_inference/test_hunyuanimage3.py   | 162 +++++++++++++---
 .../e2e/offline_inference/test_qwen3_omni.py  |  85 +++++++++
 tests/e2e/offline_inference/test_wan22_t2v.py |  26 +++
 .../test_async_omni_engine_abort_ack.py       |   5 +-
 .../test_async_omni_engine_stage_init.py      | 178 ++++++++++++++++++
 tests/engine/test_parallel_stage_init.py      |  17 ++
 tests/engine/test_single_stage_mode.py        |  21 ++-
 tests/engine/test_stage_device_layout.py      |  37 ++++
 tests/engine/test_stage_engine_args.py        |  16 ++
 .../openai_api/test_api_server_guards.py      |   7 +
 .../openai_api/test_audex_serving_guards.py   |  45 +++++
 .../openai_api/test_openpi_serving.py         |  30 +++
 ...serving_chat_minicpmo45_reference_audio.py |  33 +++-
 ...ing_chat_minicpmo45_stream_output_kinds.py |  22 +++
 .../openai_api/test_serving_speech.py         |  33 ++++
 .../openai_api/test_tts_adapter.py            |  26 +++
 .../openai_api/test_video_server.py           |  55 ++++++
 .../test_async_omni_diffusion_config.py       | 136 ++++++++++++-
 tests/entrypoints/test_omni_entrypoints.py    |  62 ++++--
 .../test_resolve_dreamzero_config.py          |   9 +-
 tests/entrypoints/test_serve.py               |  93 +++++++++
 tests/entrypoints/test_utils.py               | 174 ++++++++++++-----
 vllm_omni/config/composable_parallel/apply.py |  38 +++-
 vllm_omni/config/config_factory.py            |  92 ++++++++-
 vllm_omni/config/omni_config.py               | 136 ++++++++++++-
 vllm_omni/config/resolver.py                  |  51 ++---
 vllm_omni/engine/omni_engine_base.py          |   9 +-
 vllm_omni/engine/stage_admission.py           |   7 +-
 vllm_omni/engine/stage_engine_startup.py      |  17 +-
 vllm_omni/engine/stage_init_utils.py          | 116 ++++++++----
 vllm_omni/engine/stage_runtime.py             |  95 ++++++----
 vllm_omni/entrypoints/cli/serve.py            |  27 +--
 vllm_omni/entrypoints/openai/serving_chat.py  |  26 ++-
 .../entrypoints/openai/serving_speech.py      |  46 +++--
 vllm_omni/entrypoints/openai/serving_video.py |  50 ++---
 .../entrypoints/openai/tts_adapters/audex.py  |   6 +-
 .../entrypoints/openai/tts_adapters/base.py   |  15 ++
 .../openai/tts_adapters/higgs_audio_v2.py     |  19 +-
 .../openai/tts_adapters/higgs_audio_v3.py     |   9 +-
 .../openai/video/generation/helpers.py        |   7 +-
 vllm_omni/entrypoints/openpi/serving.py       |   8 +
 vllm_omni/entrypoints/serve/profile/utils.py  |  16 +-
 vllm_omni/entrypoints/stage_utils.py          |   6 +
 vllm_omni/entrypoints/utils.py                |   7 +
 49 files changed, 1857 insertions(+), 332 deletions(-)

diff --git a/docs/design/architecture_overview.md b/docs/design/architecture_overview.md
index 86251683124..8b7168824cf 100644
--- a/docs/design/architecture_overview.md
+++ b/docs/design/architecture_overview.md
@@ -323,7 +323,7 @@ inputs, fields, and ownership rules are described below.
 flowchart TB
     layer1["Layer 1 · Authoring inputs<br/>PipelineConfig + DeployConfig"]
     layer2["Layer 2 · Production resolution boundary<br/>resolve_omni_config()<br/>(StageConfigFactory + VllmOmniConfig internally)"]
-    layer3["Layer 3 · Startup hand-off<br/>OmniConfigResolution<br/>PipelineConfig + temporary OmegaConf stage bridge"]
+    layer3["Layer 3 · Startup hand-off<br/>OmniConfigResolution<br/>PipelineConfig + typed stage configs"]
     layer4["Layer 4 · Runtime launch planning<br/>StageRuntime"]
     layer5["Layer 5 · Engine materialization<br/>VllmConfig / OmniDiffusionConfig"]
 
@@ -335,10 +335,10 @@ The production resolution boundary is `resolve_omni_config()` in
 It delegates typed construction to `StageConfigFactory.create_from_model()` and
 `VllmOmniConfig.from_pipeline_config()`, then returns an
 `OmniConfigResolution` consumed by both `AsyncOmniEngine` and headless startup.
-Until `StageRuntime` consumes typed stage configs directly, this envelope carries
-the effective `PipelineConfig` alongside OmegaConf-compatible `stage_configs` as
-a temporary runtime bridge; both views describe the same resolved topology,
-including injected stages.
+This envelope carries the effective `PipelineConfig` alongside typed
+`stage_configs`, which `StageRuntime` consumes directly. Both views describe the
+same resolved topology, including injected stages. Backend arguments are
+projected from these typed stages when each engine is initialized.
 
 The legacy `stage_args` YAML path has been removed. Model topology now resolves
 through `PipelineConfig`, with runtime overrides supplied by `DeployConfig`.
@@ -360,7 +360,7 @@ The important ownership rules are:
 3. CLI and Python overrides are applied at the resolution boundary, with
    per-stage overrides taking precedence over global values where supported.
 4. `OmniConfigResolution` is the sole startup hand-off. Its `pipeline_config`
-   and temporary `stage_configs` compatibility view must describe the same
+   and typed `stage_configs` must describe the same
    topology.
 5. `StageRuntime` owns launch planning and replica lifecycle. `ReplicaInitPlan`
    is runtime-private state, not a user configuration object.
diff --git a/tests/config/composable_parallel/test_factory_integration.py b/tests/config/composable_parallel/test_factory_integration.py
index 468b3db2c4b..d49d3204275 100644
--- a/tests/config/composable_parallel/test_factory_integration.py
+++ b/tests/config/composable_parallel/test_factory_integration.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Integration tests: strategy overlay on the real merge_pipeline_deploy seam."""
 
 from __future__ import annotations
@@ -20,6 +20,7 @@
     apply_strategy_specs,
 )
 from vllm_omni.config.config_factory import StageConfigFactory
+from vllm_omni.config.omni_config import VllmOmniConfig
 from vllm_omni.config.pipeline_registry import OMNI_PIPELINES
 from vllm_omni.config.stage_config import load_deploy_config, merge_pipeline_deploy
 
@@ -137,3 +138,31 @@ def emit(self, record: logging.LogRecord) -> None:
     assert _resolved(stages, "talker").runtime.num_replicas == 3
     # ...and the override was warned about, naming the conflicting field.
     assert any("num_replicas" in m and "overrides the strategy-derived" in m for m in messages)
+
+
+def test_typed_cli_overrides_strategy():
+    pipeline = OMNI_PIPELINES["qwen2_5_omni"]
+    config = VllmOmniConfig.from_pipeline_config(
+        pipeline,
+        user_deploy_config=load_deploy_config(_DEPLOY),
+        cli_overrides={"stage_1_num_replicas": 3},
+        strategy_specs={"talker": [_stage_replica(2, "round_robin")]},
+    )
+
+    talker = next(stage for stage in config.stage_configs if stage.model_stage == "talker")
+    assert talker.runtime_config.num_replicas == 3
+    assert config.orchestrator_config.omni_lb_policy == "round-robin"
+    assert config.strategy_omni_lb_policy == "round-robin"
+
+
+def test_typed_tp_only_strategy_has_no_derived_lb_policy():
+    pipeline = OMNI_PIPELINES["qwen2_5_omni"]
+    config = VllmOmniConfig.from_pipeline_config(
+        pipeline,
+        user_deploy_config=load_deploy_config(_DEPLOY),
+        cli_overrides={"omni_lb_policy": "round-robin"},
+        strategy_specs={"thinker": [_tp(1)]},
+    )
+
+    assert config.orchestrator_config.omni_lb_policy == "round-robin"
+    assert config.strategy_omni_lb_policy is None
diff --git a/tests/config/test_forced_aligner_injection.py b/tests/config/test_forced_aligner_injection.py
index 65c31522985..2037b22f1dd 100644
--- a/tests/config/test_forced_aligner_injection.py
+++ b/tests/config/test_forced_aligner_injection.py
@@ -2,13 +2,19 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 import pytest
+from vllm.pooling_params import PoolingParams
 
 import vllm_omni.config.pipeline_registry  # noqa: F401  (populate registry)
+from vllm_omni.config.omni_config import VllmOmniConfig
 from vllm_omni.config.pipeline_registry import OMNI_PIPELINES as _PIPELINE_REGISTRY
 from vllm_omni.config.stage_config import (
     DeployConfig,
     StageExecutionType,
 )
+from vllm_omni.engine.stage_init_utils import (
+    build_engine_args_dict_from_omni_stage_config,
+    extract_stage_metadata_from_omni_stage_config,
+)
 from vllm_omni.model_executor.stage_input_processors.forced_aligner import (
     POOLING_OUTPUT_DECODER_PATH,
     TIMESTAMPS_MODALITY,
@@ -94,3 +100,33 @@ def test_aligner_uses_completed_audio_without_disabling_upstream_chunks(async_ch
     assert stages[2].engine_args.runner == "pooling"
     assert len(pipeline.stages) == 2
     assert deploy.stages == []
+
+
+def test_injected_aligner_survives_typed_config_and_runtime_projections():
+    pipeline, deploy = inject_forced_aligner_stage(
+        _PIPELINE_REGISTRY["qwen3_tts"],
+        DeployConfig(),
+        {"forced_aligner": "/models/Qwen3-ForcedAligner-0.6B"},
+    )
+    config = VllmOmniConfig.from_pipeline_config(
+        pipeline,
+        user_deploy_config=deploy,
+        cli_overrides={"model": "/models/Qwen3-TTS"},
+    )
+    stage = config.stage_configs[-1]
+
+    assert stage.pooling_config.runner == "pooling"
+    assert stage.pooling_config.pooling_output_decoder == POOLING_OUTPUT_DECODER_PATH
+    assert isinstance(stage.pooling_config.default_pooling_params, PoolingParams)
+    assert stage.pooling_config.default_pooling_params.task == deploy.stages[-1].default_pooling_params["task"]
+
+    metadata = extract_stage_metadata_from_omni_stage_config(stage)
+    assert isinstance(metadata.default_sampling_params, PoolingParams)
+    assert metadata.default_sampling_params.task == deploy.stages[-1].default_pooling_params["task"]
+
+    engine_args = build_engine_args_dict_from_omni_stage_config(
+        stage,
+        stage.model_config.model or "/models/Qwen3-ForcedAligner-0.6B",
+    )
+    assert engine_args["runner"] == "pooling"
+    assert engine_args["pooling_output_decoder"] == POOLING_OUTPUT_DECODER_PATH
diff --git a/tests/config/test_omni_config.py b/tests/config/test_omni_config.py
index 1ed62f7f1fc..97f9a53704f 100644
--- a/tests/config/test_omni_config.py
+++ b/tests/config/test_omni_config.py
@@ -11,6 +11,7 @@
 
 import msgspec
 import pytest
+import torch
 from pydantic import ValidationError
 from pydantic.fields import FieldInfo
 from transformers import Qwen3OmniMoeConfig
@@ -123,6 +124,18 @@ def test_non_duplex_deploy_keeps_model_session_capacity_at_one(tmp_path: Path) -
     assert [stage.model_config.session_mode for stage in omni_config.stage_configs] == ["turn", "turn"]
 
 
+def test_nested_stage_override_deep_merges_structured_model_config() -> None:
+    config = _from_pipeline_key(
+        "cosmos3_policy",
+        deploy_config_path=get_deploy_config_path("cosmos3_policy_droid.yaml"),
+        cli_overrides={"stage_0_model_config": {"guardrails": False}},
+    )
+
+    model_config = config.stage_by_id(0).diffusion_config.model_config
+    assert model_config["guardrails"] is False
+    assert model_config["policy_server_config"]["action_space"] == "joint_position"
+
+
 @pytest.mark.parametrize("model_type", sorted(OMNI_PIPELINES))
 def test_vllm_omni_config_from_pipeline_config_matches_merge_pipeline_deploy(model_type: str):
     pipeline = _resolve_pipeline_or_skip(model_type)
@@ -654,6 +667,7 @@ def test_vllm_omni_stage_config_public_fields_use_typed_stage_realizations():
         "load_config",
         "cache_config",
         "scheduler_config",
+        "pooling_config",
         "connector_config",
         "runtime_config",
         "parallel_config",
@@ -889,6 +903,17 @@ def test_structured_llm_stage_registration_payloads_remain_msgpack_transport_saf
         msgspec.msgpack.encode(payload)
 
 
+def test_structured_diffusion_torch_dtype_is_msgpack_transport_safe():
+    stage_config = _from_pipeline_key(
+        "hunyuan_image3_dit",
+        cli_overrides={"dtype": torch.bfloat16},
+    ).stage_by_id(0)
+
+    serialized = _serialize_stage_config(stage_config)
+    assert serialized["diffusion_config"]["dtype"] == "bfloat16"
+    msgspec.msgpack.encode(serialized)
+
+
 def test_diffusion_parallel_config_fields_cover_legacy_surface():
     from vllm_omni.diffusion.data import DiffusionParallelConfig
 
diff --git a/tests/e2e/features/custom_pipeline/test_async_omni_qwen_image_generate.py b/tests/e2e/features/custom_pipeline/test_async_omni_qwen_image_generate.py
index 56a9601212f..4bea6563bb4 100644
--- a/tests/e2e/features/custom_pipeline/test_async_omni_qwen_image_generate.py
+++ b/tests/e2e/features/custom_pipeline/test_async_omni_qwen_image_generate.py
@@ -21,6 +21,7 @@
 from transformers import AutoTokenizer
 
 from tests.helpers.mark import hardware_test
+from vllm_omni.config.omni_config import VllmOmniDiffusionStageConfig
 from vllm_omni.diffusion.executor.uniproc_executor import UniProcDiffusionExecutor
 from vllm_omni.diffusion.inline_stage_diffusion_client import InlineStageDiffusionClient
 from vllm_omni.entrypoints.async_omni import AsyncOmni
@@ -136,6 +137,15 @@ async def _generate_once(
 
 def _assert_live_uniproc_worker(engine: AsyncOmni) -> None:
     """Default single-GPU path must use the in-process executor, not mp IPC."""
+    stage_configs = engine.engine.stage_configs
+    assert len(stage_configs) == 1
+    stage_config = stage_configs[0]
+    assert isinstance(stage_config, VllmOmniDiffusionStageConfig)
+    assert stage_config.model_config.model == MODEL
+    assert stage_config.model_config.enforce_eager is True
+    assert stage_config.scheduler_config.max_num_seqs == 1
+    assert stage_config.diffusion_config.custom_pipeline_args == {"pipeline_class": CUSTOM_PIPELINE_CLASS}
+    assert stage_config.diffusion_config.worker_extension_cls == WORKER_EXTENSION_CLASS
     clients = engine.engine.stage_clients
     assert len(clients) == 1
     client = clients[0]
diff --git a/tests/e2e/offline_inference/test_hunyuanimage3.py b/tests/e2e/offline_inference/test_hunyuanimage3.py
index 8655bd63fdd..21bfe9b3944 100644
--- a/tests/e2e/offline_inference/test_hunyuanimage3.py
+++ b/tests/e2e/offline_inference/test_hunyuanimage3.py
@@ -1,5 +1,10 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 # ruff: noqa: E501
+import copy
 import importlib.util
+import os
 import sys
 from collections.abc import Generator
 from pathlib import Path
@@ -10,20 +15,37 @@
 from PIL import Image
 from transformers import CLIPModel, CLIPProcessor
 
+from tests.helpers.mark import hardware_test
 from tests.helpers.runtime import OmniRunner
-from tests.helpers.stage_config import get_deploy_config_path
+from tests.helpers.stage_config import get_deploy_config_path, modify_stage_config
 from vllm_omni import Omni
+from vllm_omni.config.omni_config import (
+    VllmOmniARStageConfig,
+    VllmOmniDiffusionStageConfig,
+)
+from vllm_omni.diffusion.models.hunyuan_image3.prompt_utils import build_prompt_tokens, resolve_stop_token_ids
 from vllm_omni.entrypoints.openai.stage_params import clone_sampling_params
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.model_extras import get_ar_input_builder, get_ar_tokenizer_validator, get_model_class_name
 from vllm_omni.platforms import current_omni_platform
 
 PROMPT = "A brown and white dog is running on the grass"
-MODEL_NAME = "tencent/HunyuanImage-3.0"
+MODEL_NAME = os.environ.get("HUNYUAN_IMAGE3_MODEL", "tencent/HunyuanImage-3.0-Instruct")
 LOCAL_CLIP_PATH = "openai/clip-vit-base-patch32"
-DEPLOY_CONFIG_PATH = get_deploy_config_path("hunyuan_image_3_moe.yaml")
+_PRODUCTION_DEPLOY_CONFIG_PATH = get_deploy_config_path("hunyuan_image_3_moe.yaml")
+# Keep the production Mooncake connector, but use its TCP transport for this
+# single-host test.  The shared server's RDMA device is not usable reliably;
+# TCP still exercises the Mooncake AR→DiT data plane without changing deploy
+# semantics in production.
+DEPLOY_CONFIG_PATH = modify_stage_config(
+    _PRODUCTION_DEPLOY_CONFIG_PATH,
+    updates={"connectors.rdma_connector.extra.protocol": "tcp"},
+)
 
-pytestmark = [pytest.mark.advanced_model, pytest.mark.diffusion]
+pytestmark = [
+    pytest.mark.advanced_model,
+    pytest.mark.diffusion,
+]
 
 # System prompt type. Options: None, dynamic, en_vanilla, en_recaption, en_think_recaption, en_unified
 # Below are the CLIP embedding tensors from the official HunyuanImage model (seed=1234, prompt: "A brown and white dog is running on the grass").
@@ -285,25 +307,97 @@ def omni() -> Generator[Omni, None, None]:
         yield runner.omni
 
 
+@pytest.mark.skipif(torch.accelerator.device_count() < 4, reason="Need at least 4 CUDA GPUs for this test.")
+@hardware_test(res={"cuda": "H100"}, num_cards=4)
+def test_structured_mixed_pipeline_config_reaches_runtime(omni: Omni) -> None:
+    """Mixed-pipeline deploy settings reach both terminal engine configs."""
+    engine = omni.engine
+
+    # Topology, connector selection, and placement remain Omni-owned.
+    resolved_stages = engine.stage_configs
+    assert len(resolved_stages) == 2
+    ar_stage, diffusion_stage = resolved_stages
+    assert isinstance(ar_stage, VllmOmniARStageConfig)
+    assert ar_stage.stage_id == 0
+    assert ar_stage.model_stage == "AR"
+    assert ar_stage.final_output_type == "text"
+    assert ar_stage.runtime_config.devices == "0,1"
+    assert ar_stage.connector_config.output_connectors == {"to_stage_1": "rdma_connector"}
+    assert isinstance(diffusion_stage, VllmOmniDiffusionStageConfig)
+    assert diffusion_stage.stage_id == 1
+    assert diffusion_stage.model_stage == "dit"
+    assert diffusion_stage.final_output_type == "image"
+    assert diffusion_stage.input_sources == [0]
+    assert diffusion_stage.runtime_config.devices == "2,3"
+    assert diffusion_stage.connector_config.input_connectors == {"from_stage_0": "rdma_connector"}
+
+    # Stage 0 is materialized as the VllmConfig actually passed to its engine.
+    ar_vllm_config, diffusion_vllm_config = engine.stage_vllm_configs
+    assert ar_vllm_config is not None
+    assert diffusion_vllm_config is None
+    assert ar_vllm_config.model_config.enforce_eager is True
+    assert ar_vllm_config.model_config.trust_remote_code is True
+    assert ar_vllm_config.parallel_config.tensor_parallel_size == 2
+    assert ar_vllm_config.scheduler_config.max_num_seqs == 1
+    assert ar_vllm_config.scheduler_config.max_num_batched_tokens == 32768
+    assert ar_vllm_config.cache_config.gpu_memory_utilization == 0.95
+    ar_omni_config = ar_vllm_config.model_config.omni_config
+    assert ar_omni_config.omni_kv_config["need_send_cache"] is True
+
+    expected_ar_sampling = {
+        "temperature": 0.0,
+        "top_p": 1,
+        "top_k": -1,
+        "max_tokens": 8192,
+        "detokenize": True,
+        "skip_special_tokens": False,
+        "include_stop_str_in_output": True,
+    }
+    ar_sampling, diffusion_sampling = engine.default_sampling_params_list
+    assert all(getattr(ar_sampling, name) == value for name, value in expected_ar_sampling.items())
+    assert diffusion_sampling.num_inference_steps == 50
+    assert diffusion_sampling.guidance_scale == 0
+
+    # Stage 1 is a diffusion engine, so its terminal owner is the launched
+    # OmniDiffusionConfig rather than a VllmConfig.
+    od_config = omni.get_diffusion_od_config()
+    assert od_config is not None
+    assert od_config.model == MODEL_NAME
+    assert od_config.enforce_eager is True
+    assert od_config.distributed_executor_backend == "mp"
+    assert od_config.parallel_config.tensor_parallel_size == 2
+    assert od_config.parallel_config.enable_expert_parallel is True
+    assert od_config.max_num_seqs == 1
+    diffusion_kv = od_config.omni_kv_config
+    assert diffusion_kv["need_recv_cache"] is True
+    assert diffusion_kv["enable_kv_async_prefetch"] is True
+    assert diffusion_kv["kv_prefetch_min_free_mem_ratio"] == 0.2
+
+
 def _extract_generated_image(outputs: list[object]) -> Image.Image:
     if not outputs:
         raise AssertionError("No outputs were returned from Omni.generate()")
 
-    first_output = outputs[0]
-    if images := getattr(first_output, "images", None):
-        return images[0]
-
-    request_output = first_output
-    if request_output is not None and (images := getattr(request_output, "images", None)):
-        return images[0]
+    for output in outputs:
+        if images := getattr(output, "images", None):
+            return images[0]
+        multimodal_output = getattr(output, "multimodal_output", None)
+        if isinstance(multimodal_output, dict) and (images := multimodal_output.get("images")):
+            return images[0]
 
     raise AssertionError("No generated image found in Omni output")
 
 
 def extract_embedding(image: Image.Image, clip_model: CLIPModel, clip_processor: CLIPProcessor) -> torch.Tensor:
-    inputs = clip_processor(images=image.convert("RGB"), return_tensors="pt")
+    # The full CLIP forward API is stable across supported Transformers
+    # versions, but it expects text inputs as well as pixels.  An empty text
+    # prompt is sufficient when only the projected image embedding is needed.
+    inputs = clip_processor(text=[""], images=[image.convert("RGB")], return_tensors="pt", padding=True)
     with torch.inference_mode():
-        features = clip_model.get_image_features(**inputs)
+        # Use the public CLIP forward output, matching the shared CLIPScorer
+        # helper.  ``get_image_features`` changed from Tensor to
+        # BaseModelOutputWithPooling in Transformers 5.x.
+        features = clip_model(**inputs).image_embeds
         features = F.normalize(features, p=2, dim=-1)
     return features.squeeze(0)
 
@@ -320,16 +414,36 @@ def compare_semantic(
 
 
 def _generate_image(omni: Omni, use_system_prompt: str | None) -> Image.Image:
-    generator_device = current_omni_platform.device_type or "cuda"
-    sampling_params = OmniDiffusionSamplingParams(
-        seed=1234,
-        generator=torch.Generator(device=generator_device).manual_seed(1234),
-        num_outputs_per_prompt=1,
+    from transformers import AutoTokenizer
+
+    tokenizer = AutoTokenizer.from_pretrained(MODEL_NAME, trust_remote_code=True)
+    prompt_tokens = build_prompt_tokens(
+        PROMPT,
+        tokenizer,
+        task="t2i",
+        bot_task="think",
+        sys_type=use_system_prompt or "None",
     )
-    if use_system_prompt is not None:
-        sampling_params.extra_args = {"use_system_prompt": use_system_prompt}
-
-    outputs = omni.generate({"prompt": PROMPT}, sampling_params)
+    stop_token_ids = resolve_stop_token_ids(task="t2i", bot_task="think", tokenizer=tokenizer, image_size="1024x1024")
+    params_list = copy.deepcopy(omni.default_sampling_params_list)
+    generator_device = current_omni_platform.device_type or "cuda"
+    for params in params_list:
+        if isinstance(params, OmniDiffusionSamplingParams):
+            params.seed = 1234
+            params.generator = torch.Generator(device=generator_device).manual_seed(1234)
+            params.num_outputs_per_prompt = 1
+        elif hasattr(params, "stop_token_ids"):
+            params.stop_token_ids = stop_token_ids
+
+    prompt = {
+        "prompt": PROMPT,
+        "prompt_token_ids": prompt_tokens.token_ids,
+        "use_system_prompt": prompt_tokens.system_prompt_type,
+        "modalities": ["image"],
+        "height": 1024,
+        "width": 1024,
+    }
+    outputs = omni.generate(prompt, params_list)
     return _extract_generated_image(outputs)
 
 
@@ -342,7 +456,7 @@ def _generate_image(omni: Omni, use_system_prompt: str | None) -> Image.Image:
 MIN_SEMANTIC_SIMILARITY = 0.5
 
 
-@pytest.mark.skipif(torch.accelerator.device_count() < 8, reason="Need at least 8 CUDA GPUs for this test.")
+@pytest.mark.skipif(torch.accelerator.device_count() < 4, reason="Need at least 4 CUDA GPUs for this test.")
 @pytest.mark.parametrize("system_prompt_name,use_system_prompt,expected_embedding", SYSTEM_PROMPT_CASES)
 def test_system_prompt_scores(
     omni: Omni,
@@ -378,7 +492,7 @@ def _load_text_to_image_module():
     return module
 
 
-@pytest.mark.skipif(torch.accelerator.device_count() < 8, reason="Need at least 8 CUDA GPUs for this test.")
+@pytest.mark.skipif(torch.accelerator.device_count() < 4, reason="Need at least 4 CUDA GPUs for this test.")
 def test_shared_script_ar_path_reaches_generation(
     omni: Omni,
     clip_bundle: tuple[CLIPModel, CLIPProcessor],
diff --git a/tests/e2e/offline_inference/test_qwen3_omni.py b/tests/e2e/offline_inference/test_qwen3_omni.py
index 32c34519444..f5937265c37 100644
--- a/tests/e2e/offline_inference/test_qwen3_omni.py
+++ b/tests/e2e/offline_inference/test_qwen3_omni.py
@@ -17,6 +17,10 @@
 from tests.helpers.mark import hardware_test
 from tests.helpers.media import generate_synthetic_video
 from tests.helpers.stage_config import get_deploy_config_path, modify_stage_config
+from vllm_omni.config.omni_config import (
+    VllmOmniARStageConfig,
+    VllmOmniGenerationStageConfig,
+)
 from vllm_omni.platforms import current_omni_platform
 
 models = ["Qwen/Qwen3-Omni-30B-A3B-Instruct"]
@@ -25,6 +29,7 @@
 # Single CI deploy YAML; rocm/xpu deltas are picked automatically via the
 # platforms: section. Only CUDA needs an extra enforce_eager tweak.
 _CI_DEPLOY = get_deploy_config_path("ci/qwen3_omni_moe.yaml")
+_PRODUCTION_DEPLOY = get_deploy_config_path("qwen3_omni_moe.yaml")
 
 
 def get_cuda_graph_config():
@@ -46,6 +51,7 @@ def get_cuda_graph_config():
 
 # Create parameter combinations for model and stage config
 test_params = [(model, stage_config) for model in models for stage_config in stage_configs]
+production_test_params = [(model, _PRODUCTION_DEPLOY) for model in models]
 # we can use the same config for a model that only has thinker (i.e., does not
 # enable audio output) because the resolver should figure out that it doesn't
 # need the full pipeline based on the HF config.
@@ -59,6 +65,85 @@ def get_question(prompt_type="video"):
     return prompts.get(prompt_type, prompts["video"])
 
 
+@pytest.mark.advanced_model
+@pytest.mark.omni
+@hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards=2)
+@pytest.mark.parametrize("omni_runner", production_test_params, indirect=True)
+def test_structured_multistage_config_reaches_runtime(omni_runner, offline_client) -> None:
+    """Deploy settings reach the materialized configs used by live stages."""
+    engine = omni_runner.omni.engine
+
+    # The resolved typed stages remain the Omni-owned source for topology and
+    # placement, which are not fields of the terminal vLLM config.
+    resolved_stages = engine.stage_configs
+    assert len(resolved_stages) == 3
+    thinker, talker, code2wav = resolved_stages
+    assert isinstance(thinker, VllmOmniARStageConfig)
+    assert isinstance(talker, VllmOmniARStageConfig)
+    assert isinstance(code2wav, VllmOmniGenerationStageConfig)
+    assert [stage.stage_id for stage in resolved_stages] == [0, 1, 2]
+    assert [stage.model_stage for stage in resolved_stages] == ["thinker", "talker", "code2wav"]
+    assert code2wav.final_output_type == "audio"
+    assert thinker.runtime_config.devices == "0"
+    assert talker.runtime_config.devices == code2wav.runtime_config.devices == "1"
+    assert talker.connector_config.input_connectors == {"from_stage_0": "connector_of_shared_memory"}
+    assert code2wav.connector_config.input_connectors == {"from_stage_1": "connector_of_shared_memory"}
+
+    # Engine-owned deploy settings must survive the startup projection into
+    # the actual VllmConfig objects retained by the stage pools.
+    assert len(engine.stage_vllm_configs) == 3
+    thinker_vllm, talker_vllm, code2wav_vllm = engine.stage_vllm_configs
+    assert thinker_vllm is not None
+    assert talker_vllm is not None
+    assert code2wav_vllm is not None
+    assert thinker_vllm.scheduler_config.max_num_seqs == 64
+    assert talker_vllm.scheduler_config.max_num_seqs == 64
+    assert code2wav_vllm.scheduler_config.max_num_seqs == 64
+    assert thinker_vllm.scheduler_config.max_num_batched_tokens == 32768
+    assert talker_vllm.scheduler_config.max_num_batched_tokens == 32768
+    assert code2wav_vllm.scheduler_config.max_num_batched_tokens == 65536
+    assert thinker_vllm.cache_config.gpu_memory_utilization == 0.9
+    assert talker_vllm.cache_config.gpu_memory_utilization == 0.6
+    assert code2wav_vllm.cache_config.gpu_memory_utilization == 0.1
+    assert all(config.cache_config.enable_prefix_caching is False for config in engine.stage_vllm_configs)
+    assert all(config.model_config.trust_remote_code is True for config in engine.stage_vllm_configs)
+    assert code2wav_vllm.scheduler_config.enable_chunked_prefill is False
+    assert code2wav_vllm.scheduler_config.async_scheduling is False
+
+    # Sampling defaults are consumed from StageClient metadata, rather than
+    # from either the resolver output or VllmConfig.
+    expected_sampling = (
+        {"temperature": 0.0, "max_tokens": 2048},
+        {"temperature": 0.9, "top_k": 50, "max_tokens": 4096, "repetition_penalty": 1.05},
+        {
+            "temperature": 0.0,
+            "top_p": 1.0,
+            "top_k": -1,
+            "max_tokens": 65536,
+            "repetition_penalty": 1.1,
+        },
+    )
+    assert len(engine.default_sampling_params_list) == len(expected_sampling)
+    for runtime_params, expected in zip(engine.default_sampling_params_list, expected_sampling, strict=True):
+        # SamplingParams normalization may add backend defaults (for example
+        # ``detokenize=True``). Verify deploy-owned values without rejecting
+        # those non-lossy normalized fields.
+        assert all(getattr(runtime_params, name) == value for name, value in expected.items())
+
+    if current_omni_platform.is_cuda():
+        assert thinker_vllm.model_config.enforce_eager is False
+        assert talker_vllm.model_config.enforce_eager is False
+
+    # Exercise the materialized stages and their connector path with a real
+    # request; the assertions above are not merely resolver-shape checks.
+    offline_client.send_omni_request(
+        {
+            "prompts": "Answer with one short sentence: what is the capital of China?",
+            "modalities": ["text"],
+        }
+    )
+
+
 @pytest.mark.advanced_model
 @pytest.mark.omni
 @hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards=2)
diff --git a/tests/e2e/offline_inference/test_wan22_t2v.py b/tests/e2e/offline_inference/test_wan22_t2v.py
index 805fbd1fea4..07ac5c8a64a 100644
--- a/tests/e2e/offline_inference/test_wan22_t2v.py
+++ b/tests/e2e/offline_inference/test_wan22_t2v.py
@@ -5,6 +5,7 @@
 
 from tests.helpers.mark import hardware_test
 from tests.helpers.runtime import OfflineOmniClient
+from vllm_omni.config.omni_config import VllmOmniDiffusionStageConfig
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 
 MODEL = "Wan-AI/Wan2.2-T2V-A14B-Diffusers"
@@ -12,6 +13,31 @@
 NEGATIVE_PROMPT = "low quality, blurry, watermark, text"
 
 
+@pytest.mark.advanced_model
+@pytest.mark.diffusion
+@hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards={"cuda": 1, "rocm": 1})
+@pytest.mark.parametrize("omni_runner", [(MODEL, None)], indirect=True)
+def test_structured_diffusion_config_reaches_runtime(omni_runner) -> None:
+    """The default WAN resolver launches the typed diffusion config itself."""
+    omni = omni_runner.omni
+    resolved_stages = omni.engine.stage_configs
+    assert len(resolved_stages) == 1
+    stage_config = resolved_stages[0]
+
+    assert isinstance(stage_config, VllmOmniDiffusionStageConfig)
+    assert stage_config.stage_id == 0
+    assert stage_config.model_stage == "dit"
+    assert stage_config.final_output_type == "video"
+
+    assert omni.engine.stage_vllm_configs == [None]
+    od_config = omni.get_diffusion_od_config()
+    assert od_config is not None
+    assert od_config.stage_id == 0
+    assert od_config.model == MODEL
+    assert od_config.model_class_name == "WanPipeline"
+    assert od_config.output_type == "pil"
+
+
 @pytest.mark.advanced_model
 @pytest.mark.diffusion
 @hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards={"cuda": 1, "rocm": 1})
diff --git a/tests/engine/test_async_omni_engine_abort_ack.py b/tests/engine/test_async_omni_engine_abort_ack.py
index 43a29bf3ae7..366e640f6b6 100644
--- a/tests/engine/test_async_omni_engine_abort_ack.py
+++ b/tests/engine/test_async_omni_engine_abort_ack.py
@@ -66,9 +66,10 @@ async def _run() -> None:
         assert msg.rpc_id == "abort-rpc-1"
         assert not task.done()
 
-        rpc_q.put(AbortResultMessage(rpc_id="abort-rpc-1", success=True))
+        partial_output = SimpleNamespace(request_id="req-a", finished=True)
+        rpc_q.put(AbortResultMessage(rpc_id="abort-rpc-1", success=True, abort_outputs=[partial_output]))
         result = await task
-        assert result == []
+        assert result == [partial_output]
 
     try:
         asyncio.run(_run())
diff --git a/tests/engine/test_async_omni_engine_stage_init.py b/tests/engine/test_async_omni_engine_stage_init.py
index 15d31cbbcd3..6378351229f 100644
--- a/tests/engine/test_async_omni_engine_stage_init.py
+++ b/tests/engine/test_async_omni_engine_stage_init.py
@@ -12,6 +12,7 @@
 import pytest
 from omegaconf import OmegaConf
 
+from vllm_omni.config.omni_config import OmniStageRuntimeConfig
 from vllm_omni.diffusion.data import AttentionConfig
 from vllm_omni.engine import omni_engine_base as async_omni_engine_module
 from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
@@ -21,12 +22,23 @@
     build_stage0_input_processor,
     compute_replica_layout,
     split_devices_for_replicas,
+    stage_runtime_env,
 )
 from vllm_omni.engine.stage_runtime import StageRuntime
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
 
+def test_stage_runtime_env_accepts_typed_runtime_config(monkeypatch):
+    env_key = "VLLM_OMNI_TEST_TYPED_STAGE_ENV"
+    monkeypatch.delenv(env_key, raising=False)
+
+    with stage_runtime_env(0, OmniStageRuntimeConfig(env={env_key: "typed-value"})):
+        assert os.environ[env_key] == "typed-value"
+
+    assert env_key not in os.environ
+
+
 def test_orchestrator_startup_timeout_warns_how_to_raise_limits(monkeypatch):
     engine = object.__new__(AsyncOmniEngine)
     engine.orchestrator_thread = types.SimpleNamespace(is_alive=lambda: True)
@@ -223,6 +235,50 @@ def _capture_create_stage_runtime(**kwargs):
     assert captured["log_stats"] is True
 
 
+def test_async_omni_engine_initialize_stages_retains_stage0_prompt_transform(monkeypatch):
+    import vllm_omni.engine.omni_engine_base as engine_mod
+
+    engine = object.__new__(AsyncOmniEngine)
+    engine.stage_configs = [types.SimpleNamespace()]
+    engine.model = "dummy-model"
+    engine.config_path = "dummy-config"
+    engine.single_stage_mode = False
+    engine.async_chunk = False
+    engine.tokenizer = None
+    engine._single_stage_id_filter = None
+    engine._omni_master_address = None
+    engine._omni_master_port = None
+    engine._omni_dp_size_local = 1
+    engine._omni_heartbeat_timeout = 30.0
+    engine._omni_lb_policy = "random"
+    engine.request_queue = types.SimpleNamespace()
+    engine._log_stats = False
+    engine._parallel_stage_init = False
+
+    prompt_transform = object()
+    client = types.SimpleNamespace(
+        prompt_transform_func=prompt_transform,
+        prompt_expand_func=None,
+        default_sampling_params=types.SimpleNamespace(),
+        final_output=True,
+        final_output_type="text",
+        stage_type="llm",
+        model_stage="text_encoder",
+        is_comprehension=True,
+    )
+    pool = types.SimpleNamespace(
+        stage_client=client,
+        stage_vllm_config=None,
+        output_processor=None,
+    )
+    runtime = types.SimpleNamespace(stage_pools=[pool], initialize=lambda: None)
+    monkeypatch.setattr(engine_mod, "create_stage_runtime", lambda **_kwargs: runtime)
+
+    engine._initialize_stages(stage_init_timeout=7)
+
+    assert engine.prompt_transform_func is prompt_transform
+
+
 def test_compute_replica_layout_splits_diffusion_devices_by_world_size():
     stage_cfg = types.SimpleNamespace(
         stage_id=0,
@@ -1715,6 +1771,51 @@ def test_inject_kv_stage_info_infers_receiver_tp_topology():
     assert stage1.engine_args["omni_kv_config"]["rank_mapping"] == {"from_tp": 4, "to_tp": 2}
 
 
+def test_inject_kv_stage_info_updates_typed_connector_config():
+    from vllm_omni.config.omni_config import (
+        OmniStageConnectorConfig,
+        OmniStageDiffusionParallelConfig,
+        VllmOmniDiffusionStageConfig,
+    )
+    from vllm_omni.config.stage_config import StageExecutionType, StagePipelineConfig
+    from vllm_omni.engine.stage_init_utils import inject_kv_stage_info
+    from vllm_omni.entrypoints.utils import inject_omni_kv_config
+
+    stage0 = VllmOmniDiffusionStageConfig(
+        stage_pipeline_config=StagePipelineConfig(
+            stage_id=0,
+            model_stage="diffusion",
+            execution_type=StageExecutionType.DIFFUSION,
+        ),
+        connector_config=OmniStageConnectorConfig(
+            omni_kv_config={
+                "need_send_cache": True,
+                "omni_from_stage": "0",
+                "omni_to_stage": "1",
+            }
+        ),
+        parallel_config=OmniStageDiffusionParallelConfig(tensor_parallel_size=4),
+    )
+    stage1 = VllmOmniDiffusionStageConfig(
+        stage_pipeline_config=StagePipelineConfig(
+            stage_id=1,
+            model_stage="diffusion",
+            execution_type=StageExecutionType.DIFFUSION,
+            input_sources=(0,),
+        ),
+        connector_config=OmniStageConnectorConfig(omni_kv_config={"need_recv_cache": True}),
+        parallel_config=OmniStageDiffusionParallelConfig(tensor_parallel_size=2),
+    )
+
+    inject_omni_kv_config(stage0, {"kv_connector": "P2pNcclConnector"}, "0", "1")
+    inject_kv_stage_info(stage0, 0, [stage0, stage1])
+
+    assert stage0.connector_config.omni_kv_config["stage_id"] == 0
+    assert stage0.connector_config.omni_kv_config["connector_config"] == {"kv_connector": "P2pNcclConnector"}
+    assert stage0.connector_config.omni_kv_config["engine_input_source"] == []
+    assert stage0.connector_config.omni_kv_config["rank_mapping"] == {"from_tp": 4, "to_tp": 2}
+
+
 def test_extract_legacy_stage_metadata_rocm_does_not_inject_diffusion_attention(monkeypatch):
     """ROCm default attention logic only applies to LLM stages, not diffusion."""
     from vllm_omni.engine.stage_init_utils import extract_legacy_stage_metadata
@@ -1852,3 +1953,80 @@ def stop_before_queues(*args, **kwargs):
     with pytest.raises(ConfigResolvedError):
         engine.__init__("test-model")
     assert engine.async_chunk is expected
+
+
+@pytest.mark.parametrize("typed", [False, True], ids=["legacy", "typed"])
+def test_dist_stage_runtime_applies_local_dp_to_stage_config(typed):
+    from vllm_omni.config.omni_config import VllmOmniARStageConfig
+    from vllm_omni.config.stage_config import StagePipelineConfig
+    from vllm_omni.engine.stage_runtime import DistStageRuntime
+
+    if typed:
+        stage = VllmOmniARStageConfig(stage_pipeline_config=StagePipelineConfig(stage_id=0, model_stage="ar"))
+        runtime_cfg = stage.runtime_config
+    else:
+        runtime_cfg = types.SimpleNamespace(num_replicas=1)
+        stage = types.SimpleNamespace(stage_id=0, runtime=runtime_cfg)
+    runtime = DistStageRuntime(
+        stage_configs=[stage],
+        model="dummy-model",
+        config_path="dummy-config",
+        stage_init_timeout=1,
+        async_chunk=False,
+        single_stage_id_filter=0,
+        omni_master_address="127.0.0.1",
+        omni_master_port=12345,
+        omni_dp_size_local=2,
+    )
+
+    runtime._validate_single_stage_mode_replica_constraints()
+
+    assert runtime_cfg.num_replicas == 2
+
+
+@pytest.mark.parametrize("num_replicas", [1, 2, 3])
+def test_typed_diffusion_replicas_share_one_config_between_planning_and_launch(mocker, num_replicas):
+    from vllm_omni.config.config_factory import StageConfigFactory
+    from vllm_omni.engine import stage_runtime as runtime_module
+
+    stage = StageConfigFactory.create_typed_default_diffusion(
+        "generic-diffusion", {"model_class_name": "QwenImagePipeline"}
+    ).stage_configs[0]
+    devices = ",".join(str(i) for i in range(num_replicas))
+    stage.runtime_config.devices = devices
+    stage.runtime_config.num_replicas = num_replicas
+    runtime = StageRuntime(
+        stage_configs=[stage],
+        model="dummy-model",
+        config_path="dummy-config",
+        stage_init_timeout=1,
+        async_chunk=False,
+    )
+    mocker.patch.object(runtime_module, "get_stage_connector_spec", return_value={})
+    mocker.patch.object(runtime_module, "resolve_omni_kv_config_for_stage", return_value=(None, None, None))
+    mocker.patch.object(runtime, "_stage_device_scope", side_effect=lambda *_: contextlib.nullcontext())
+    client = mocker.Mock()
+    launch = mocker.patch.object(runtime_module, "launch_diffusion_stage_replica", return_value=(client, None))
+
+    # Replanning must not inherit the first replica's narrowed device slice.
+    for _ in range(2):
+        counts, device_map = compute_replica_layout([stage])
+        plans = runtime._build_logical_stage_init_plans(
+            omni_transfer_config=None,
+            replicas_per_stage=counts,
+            replica_devices_map=device_map,
+        )
+        replicas = plans[0].replicas
+        assert stage.runtime_config.devices == devices
+        assert len({id(plan.stage_cfg) for plan in replicas}) == num_replicas
+        for i, plan in enumerate(replicas):
+            assert plan.metadata.runtime_cfg is plan.stage_cfg.runtime_config
+            assert plan.stage_cfg.runtime_config.devices == str(i)
+            if num_replicas > 1:
+                assert plan.stage_cfg is not stage
+            assert runtime._initialize_local_diffusion_replica(plan, stage_init_timeout=1) is client
+            assert launch.call_args.kwargs["stage_config"] is plan.stage_cfg
+            assert launch.call_args.kwargs["metadata"] is plan.metadata
+            assert launch.call_args.kwargs["use_inline"] is (num_replicas == 1)
+
+    assert launch.call_count == 2 * num_replicas
diff --git a/tests/engine/test_parallel_stage_init.py b/tests/engine/test_parallel_stage_init.py
index d88d49825af..9f89aabcad0 100644
--- a/tests/engine/test_parallel_stage_init.py
+++ b/tests/engine/test_parallel_stage_init.py
@@ -306,6 +306,23 @@ def test_check_admission_admits_diffusion_with_explicit_util():
     assert ledgers[0].kv_budget_bytes == int(cap * 0.3)
 
 
+def test_check_admission_reads_typed_diffusion_cache_config():
+    cap = 80 * 1024**3
+    diff = _local_diffusion_replica(0, 0, "0", util=None)
+    diff.stage_cfg.cache_config = types.SimpleNamespace(gpu_memory_utilization=0.35)
+    plan = LogicalStageInitPlan(stage_idx=0, stage_id=0, replicas=[diff])
+
+    ledgers = check_admission(
+        [plan],
+        resolve_physical_devices=lambda _r: [0],
+        device_total_memory=lambda _d: cap,
+        external_reserve_bytes=0,
+        safety_margin_bytes=0,
+    )
+
+    assert ledgers[0].kv_budget_bytes == int(cap * 0.35)
+
+
 def test_check_admission_unresolved_local_raises():
     """A local replica invisible to the ledger must fail admission, not skip it:
     it would otherwise initialize concurrently with unbounded demand."""
diff --git a/tests/engine/test_single_stage_mode.py b/tests/engine/test_single_stage_mode.py
index 41d63af9ead..9ce707dbc8d 100644
--- a/tests/engine/test_single_stage_mode.py
+++ b/tests/engine/test_single_stage_mode.py
@@ -16,7 +16,8 @@
 from vllm.v1.engine.utils import EngineZmqAddresses
 
 from vllm_omni.config.config_factory import StageConfigFactory
-from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.config.omni_config import VllmOmniARStageConfig, VllmOmniDiffusionStageConfig
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig, StageExecutionType, StagePipelineConfig
 from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
 from vllm_omni.engine.stage_engine_core_client import StageEngineCoreClientBase
 from vllm_omni.engine.stage_engine_startup import (
@@ -57,6 +58,10 @@ def _make_llm_plan(
     vllm_config: Any | None = None,
 ) -> LogicalStageInitPlan:
     stage_cfg = _make_stage_cfg(stage_id)
+    if launch_mode == "remote":
+        stage_cfg = VllmOmniARStageConfig(
+            stage_pipeline_config=StagePipelineConfig(stage_id=stage_id, model_stage="thinker"),
+        )
     metadata = SimpleNamespace(
         stage_id=stage_id,
         stage_type="llm",
@@ -98,6 +103,16 @@ def _make_diffusion_plan(
     launch_mode: str,
 ) -> LogicalStageInitPlan:
     stage_cfg = _make_stage_cfg(stage_id, stage_type="diffusion")
+    if launch_mode == "remote":
+        stage_cfg = VllmOmniDiffusionStageConfig(
+            stage_pipeline_config=StagePipelineConfig(
+                stage_id=stage_id,
+                model_stage="diffusion",
+                execution_type=StageExecutionType.DIFFUSION,
+                final_output=True,
+                final_output_type="image",
+            ),
+        )
     metadata = SimpleNamespace(
         stage_id=stage_id,
         stage_type="diffusion",
@@ -960,6 +975,7 @@ def _capture_make_async_mp_client(**kwargs):
         assert mock_connect.call_args.kwargs["stage_id"] == 1
         assert mock_connect.call_args.kwargs["replica_id"] == 0
         assert client_kwargs["log_stats"] is True
+        assert client_kwargs["metadata"].model_stage == "thinker"
         assert events == ["enter", "exit", "attach"]
 
     def test_initialize_llm_replica_remote_missing_registered_stage_config_raises(self, mocker: MockerFixture):
@@ -1125,11 +1141,9 @@ def _ctx():
 
             return _ctx()
 
-        remote_metadata = _make_diffusion_plan(1, stage_id=1, launch_mode="remote").replicas[0].metadata
         plan = _make_diffusion_plan(1, stage_id=1, launch_mode="remote").replicas[0]
         sentinel_client = SimpleNamespace()
 
-        mocker.patch.object(runtime_mod, "extract_legacy_stage_metadata", return_value=remote_metadata)
         mock_connect = mocker.patch.object(runtime_mod, "connect_remote_diffusion_proc", side_effect=_fake_connect)
         mock_from_addresses = mocker.patch(
             "vllm_omni.diffusion.stage_diffusion_client.StageDiffusionClient.from_addresses",
@@ -1146,6 +1160,7 @@ def _ctx():
             replica_id=0,
         )
         mock_from_addresses.assert_called_once()
+        assert mock_from_addresses.call_args.args[0].final_output_type == "image"
 
     def test_initialize_local_diffusion_replica_registers_with_master(self, mocker: MockerFixture):
         import vllm_omni.engine.stage_runtime as runtime_mod
diff --git a/tests/engine/test_stage_device_layout.py b/tests/engine/test_stage_device_layout.py
index 0473dc341d2..beb66dfba7f 100644
--- a/tests/engine/test_stage_device_layout.py
+++ b/tests/engine/test_stage_device_layout.py
@@ -156,6 +156,43 @@ def test_replica_guard_and_splitter_share_local_world_size(devices, expected):
     assert replica_devices_map == {0: expected}
 
 
+@pytest.mark.parametrize("typed", [False, True], ids=["legacy", "typed"])
+@pytest.mark.parametrize("local_dp", [None, 0, 1, 2])
+@pytest.mark.parametrize("pool_devices", [False, True], ids=["template", "pool"])
+def test_replica_layout_preserves_local_dp_semantics(typed, local_dp, pool_devices):
+    from vllm_omni.config.omni_config import VllmOmniConfig
+    from vllm_omni.config.stage_config import PipelineConfig, StagePipelineConfig
+    from vllm_omni.engine.stage_engine_startup import get_headless_replica_devices
+
+    engine_args = {
+        "tensor_parallel_size": 2,
+        "data_parallel_size": 4,
+        "data_parallel_size_local": local_dp,
+        "pipeline_parallel_size": 2,
+    }
+    width = 2 * max(1, local_dp if local_dp is not None else 4) * 2
+    devices = ",".join(str(i) for i in range(width * (2 if pool_devices else 1)))
+    if typed:
+        pipeline = PipelineConfig(
+            model_type="test",
+            model_arch="TestModel",
+            stages=(StagePipelineConfig(stage_id=0, model_stage="ar", final_output=True),),
+        )
+        stage = VllmOmniConfig.from_pipeline_config(
+            pipeline,
+            cli_overrides={
+                f"stage_0_{key}": value for key, value in {**engine_args, "devices": devices, "num_replicas": 2}.items()
+            },
+        ).stage_configs[0]
+    else:
+        stage = _stage(0, devices=devices, num_replicas=2, engine_args=engine_args)
+    expected = [",".join(str(i) for i in range(r * width, (r + 1) * width)) for r in range(2)]
+
+    assert get_stage_devices_per_replica(stage) == width
+    assert compute_replica_layout([stage]) == ([2], {0: expected})
+    assert get_headless_replica_devices(stage, stage_id=0, omni_dp_size_local=2) == expected
+
+
 def test_non_tp_layout_error_uses_generic_guidance():
     """A PP mismatch must not be reported as a top-level TP broadcast."""
     stage = _stage(0, devices="0")
diff --git a/tests/engine/test_stage_engine_args.py b/tests/engine/test_stage_engine_args.py
index 7ac5b6b6926..6650c8e45cb 100644
--- a/tests/engine/test_stage_engine_args.py
+++ b/tests/engine/test_stage_engine_args.py
@@ -95,6 +95,7 @@ def _effective_backend_values(config_cls: type, engine_args: dict) -> dict[str,
         "num_weight_load_threads",
         "omni_kv_config",
         "parallel_config",
+        "pooling_output_decoder",
         "silence_ban_frames",
         "subtalker_sampling_params",
         "task_type",
@@ -366,6 +367,21 @@ def test_typed_llm_projection_does_not_emit_inherited_upstream_defaults():
     assert inherited_defaults.isdisjoint(engine_args)
 
 
+def test_typed_llm_projection_omits_diffusion_only_and_process_only_defaults():
+    stage_config = VllmOmniARStageConfig(
+        stage_pipeline_config=StagePipelineConfig(stage_id=0, model_stage="test"),
+    )
+
+    engine_args = stage_init_utils._project_omni_stage_engine_args(stage_config)
+
+    assert {
+        "enable_multithread_weight_load",
+        "num_weight_load_threads",
+        "disable_autocast",
+        "log_level",
+    }.isdisjoint(engine_args)
+
+
 def test_mammoth_fp8_kv_deploy_projects_only_ar_stage(monkeypatch):
     monkeypatch.setattr(stage_init_utils, "resolve_worker_cls", lambda _engine_args: None)
 
diff --git a/tests/entrypoints/openai_api/test_api_server_guards.py b/tests/entrypoints/openai_api/test_api_server_guards.py
index 37e2dc4303e..6e28bb5b1e1 100644
--- a/tests/entrypoints/openai_api/test_api_server_guards.py
+++ b/tests/entrypoints/openai_api/test_api_server_guards.py
@@ -64,6 +64,13 @@
 # TODO: extend this set and the expected census if @router.head / @router.options appear.
 _HTTP_METHODS = {"GET", "POST", "DELETE", "PUT", "PATCH"}
 
+
+def test_profiler_endpoints_detect_typed_stage_config():
+    stage = SimpleNamespace(profiler_config=SimpleNamespace(profiler="torch"))
+
+    assert api_server._should_enable_profiler_endpoints([stage])
+
+
 # Exact Omni router census on main. Update intentionally when routes change.
 _EXPECTED_ROUTER_ROUTES = {
     ("POST", "/v1/chat/completions"),
diff --git a/tests/entrypoints/openai_api/test_audex_serving_guards.py b/tests/entrypoints/openai_api/test_audex_serving_guards.py
index 87524825e9b..141dd8cac43 100644
--- a/tests/entrypoints/openai_api/test_audex_serving_guards.py
+++ b/tests/entrypoints/openai_api/test_audex_serving_guards.py
@@ -15,6 +15,7 @@
 import pytest
 import torch
 
+from vllm_omni.config.stage_config import StagePipelineConfig
 from vllm_omni.entrypoints.openai.serving_speech import (
     _AUDEX_NO_AUDIO_GUARD_MODEL_TYPES,
     OmniOpenAIServingSpeech,
@@ -251,9 +252,28 @@ def test_tts_pipeline_still_detected(self):
         stage = serving._find_tts_stage()
         assert stage is not None and stage.engine_args.model_stage == "audex_thinker"
 
+    def test_typed_pipeline_detected_without_legacy_engine_args(self):
+        serving = OmniOpenAIServingSpeech.__new__(OmniOpenAIServingSpeech)
+        stages = [
+            SimpleNamespace(
+                stage_pipeline_config=StagePipelineConfig(stage_id=index, model_stage=model_stage),
+                model_config=SimpleNamespace(model_arch=None),
+                worker_type="generation",
+            )
+            for index, model_stage in enumerate(("audex_thinker", "audex_code2wav"))
+        ]
+        serving.engine_client = SimpleNamespace(stage_configs=stages)
+
+        stage = serving._find_tts_stage()
+        serving._tts_stage = stage
+
+        assert stage is stages[0]
+        assert serving._detect_tts_model_type() == "audex"
+
 
 def test_guided_injection_sets_guided_temperature():
     """Guided requests decode at the measured CFG temperature (0.05)."""
+
     serving = TestAudexCfgInjection()._serving_with_fake_tokenizer()
     cond = TestAudexCfgInjection()._cond_prompt()
     params = SimpleNamespace(extra_args={"cfg_scale": 1.5}, temperature=0.1)
@@ -265,6 +285,31 @@ def test_guided_injection_sets_guided_temperature():
     assert out.temperature == 0.1
 
 
+def test_typed_full_pipeline_uses_full_checkpoint_tokenizer(mocker):
+    from vllm_omni.entrypoints.openai.tts_adapters.base import SpeechServingContext
+
+    serving = OmniOpenAIServingSpeech.__new__(OmniOpenAIServingSpeech)
+    serving._tts_stage = SimpleNamespace(
+        stage_pipeline_config=StagePipelineConfig(stage_id=0, model_stage="audex_omni"),
+        model_config=SimpleNamespace(model_arch=None),
+        worker_type="ar",
+    )
+    serving.engine_client = SimpleNamespace(
+        model_config=SimpleNamespace(model="/models/audex"),
+    )
+    ensure_snapshot = mocker.patch(
+        "vllm_omni.model_executor.models.audex.checkpoint.ensure_audex_snapshot",
+        return_value="/snapshots/audex",
+    )
+    from_pretrained = mocker.patch("transformers.AutoTokenizer.from_pretrained", return_value=object())
+
+    adapter = AudexAdapter(SpeechServingContext(server=serving, engine_client=serving.engine_client))
+    adapter._get_tokenizer()
+
+    ensure_snapshot.assert_called_once_with("/models/audex", profile="full")
+    from_pretrained.assert_called_once_with("/snapshots/audex/checkpoint_folder_full")
+
+
 # ---------------------------------------------------------------- TTA serving surface
 
 from vllm_omni.entrypoints.openai.tts_adapters import resolve_adapter  # noqa: E402
diff --git a/tests/entrypoints/openai_api/test_openpi_serving.py b/tests/entrypoints/openai_api/test_openpi_serving.py
index 46ff0f822f7..d274eadda7a 100644
--- a/tests/entrypoints/openai_api/test_openpi_serving.py
+++ b/tests/entrypoints/openai_api/test_openpi_serving.py
@@ -138,6 +138,36 @@ def test_policy_server_config_reads_stage_config_model_config():
     assert serving.policy_server_config.to_dict() == policy_config
 
 
+@pytest.mark.parametrize("inline", [False, True], ids=["out_of_process", "inline"])
+def test_policy_server_config_reads_typed_runtime(inline):
+    from tests.helpers.stage_config import get_deploy_config_path
+    from vllm_omni.config.omni_config import VllmOmniConfig
+    from vllm_omni.diffusion.models.pi0_pipeline_config import PI0_PIPELINE
+    from vllm_omni.entrypoints.async_omni import AsyncOmni
+
+    typed_stage = VllmOmniConfig.from_pipeline_config(
+        PI0_PIPELINE, deploy_config_path=get_deploy_config_path("pi0.yaml")
+    ).stage_configs[0]
+    policy_config = typed_stage.diffusion_config.model_config["policy_server_config"]
+    stage_client = SimpleNamespace(stage_type="diffusion")
+    if inline:
+        # Worker-enriched inline metadata remains authoritative over the
+        # startup stage config; only the process client needs the fallback.
+        policy_config = {**policy_config, "worker_metadata": "loaded"}
+        stage_client.od_config = SimpleNamespace(model_config={"policy_server_config": policy_config})
+    engine_client = AsyncOmni.__new__(AsyncOmni)
+    engine_client.engine = SimpleNamespace(
+        stage_clients=[stage_client],
+        stage_configs=[typed_stage],
+        stage_vllm_configs=[None],
+        get_diffusion_od_config=lambda: SimpleNamespace(model_class_name="Pi0Pipeline"),
+    )
+
+    serving = openpi_serving.ServingRealtimeRobotOpenPI(engine_client=engine_client)
+
+    assert serving.policy_server_config.to_dict() == policy_config
+
+
 def test_policy_server_config_reads_omegaconf_stage_config():
     engine_client = SimpleNamespace(
         get_diffusion_od_config=lambda: None,
diff --git a/tests/entrypoints/openai_api/test_serving_chat_minicpmo45_reference_audio.py b/tests/entrypoints/openai_api/test_serving_chat_minicpmo45_reference_audio.py
index 59d070a3940..417f457d3ed 100644
--- a/tests/entrypoints/openai_api/test_serving_chat_minicpmo45_reference_audio.py
+++ b/tests/entrypoints/openai_api/test_serving_chat_minicpmo45_reference_audio.py
@@ -27,7 +27,7 @@
 
 @dataclass
 class _EngineClientStub:
-    stage_configs: list[dict[str, object]]
+    stage_configs: list[object]
 
 
 @dataclass
@@ -149,6 +149,37 @@ async def test_chat_reference_audio_reaches_code2wav_transport(
     assert code2wav_payload.meta.ref_audio_sr == 16000
 
 
+@pytest.mark.asyncio
+async def test_typed_stage_enables_reference_audio(
+    serving_chat: OmniOpenAIServingChat,
+    mocker: MockerFixture,
+) -> None:
+    reference_audio_url = "data:audio/wav;base64,AAAA"
+    reference_waveform = np.array([0.25, -0.5], dtype=np.float32)
+    serving_chat.engine_client = _EngineClientStub(
+        [
+            SimpleNamespace(
+                model_config=SimpleNamespace(model_arch="MiniCPMO45OmniForConditionalGeneration"),
+                model_stage="llm",
+            )
+        ]
+    )
+    serving_chat.model_config = _ModelConfigStub()
+    engine_prompt: TokensPrompt = {"type": "tokens", "prompt_token_ids": [1]}
+    media_connector = mocker.patch(
+        "vllm_omni.entrypoints.openai.serving_chat.MediaConnector",
+    ).return_value
+    media_connector.fetch_audio_async = mocker.AsyncMock(return_value=(reference_waveform, 16000))
+
+    await serving_chat._attach_minicpmo45_reference_audio(
+        engine_prompt,
+        _chat_request(reference_audio_url),
+    )
+
+    media_connector.fetch_audio_async.assert_awaited_once_with(reference_audio_url)
+    assert MINICPMO45_REFERENCE_AUDIO_KEY in cast(dict[str, object], engine_prompt)
+
+
 @pytest.mark.parametrize("request_shape", ["extra_body", "model_extra"])
 @pytest.mark.asyncio
 async def test_reference_audio_accepts_request_extra_mappings(
diff --git a/tests/entrypoints/openai_api/test_serving_chat_minicpmo45_stream_output_kinds.py b/tests/entrypoints/openai_api/test_serving_chat_minicpmo45_stream_output_kinds.py
index 1a3a4f22edd..5ce129d159e 100644
--- a/tests/entrypoints/openai_api/test_serving_chat_minicpmo45_stream_output_kinds.py
+++ b/tests/entrypoints/openai_api/test_serving_chat_minicpmo45_stream_output_kinds.py
@@ -1,4 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Regression tests for MiniCPM-o 4.5 audio-streaming output-kind coercion.
 
 Chat ``stream=true`` coerces every AR stage to DELTA. For MiniCPM-o 4.5 that
@@ -33,6 +34,13 @@ def _stage(model_arch: str, model_stage: str) -> SimpleNamespace:
     return SimpleNamespace(engine_args=SimpleNamespace(model_arch=model_arch, model_stage=model_stage))
 
 
+def _typed_stage(model_arch: str, model_stage: str) -> SimpleNamespace:
+    return SimpleNamespace(
+        model_config=SimpleNamespace(model_arch=model_arch),
+        model_stage=model_stage,
+    )
+
+
 def _minicpmo45_stages():
     return [_stage(MINICPMO45_ARCH, "llm"), _stage(MINICPMO45_ARCH, "tts")]
 
@@ -50,6 +58,20 @@ def test_thinker_forced_final_only_talker_stays_delta(serving_chat):
     assert out[1].output_kind is RequestOutputKind.DELTA
 
 
+def test_typed_stages_force_thinker_final_only(serving_chat):
+    serving_chat.engine_client = SimpleNamespace(
+        stage_configs=[
+            _typed_stage(MINICPMO45_ARCH, "llm"),
+            _typed_stage(MINICPMO45_ARCH, "tts"),
+        ]
+    )
+
+    out = serving_chat._fix_minicpmo45_audio_stream_output_kinds(_delta_params(), ["text", "audio"])
+
+    assert out[0].output_kind is RequestOutputKind.FINAL_ONLY
+    assert out[1].output_kind is RequestOutputKind.DELTA
+
+
 @pytest.mark.parametrize("modalities", [None, [], ["text"]])
 def test_non_audio_request_is_untouched(serving_chat, modalities):
     serving_chat.engine_client = SimpleNamespace(stage_configs=_minicpmo45_stages())
diff --git a/tests/entrypoints/openai_api/test_serving_speech.py b/tests/entrypoints/openai_api/test_serving_speech.py
index f8dfaafb608..5ac895d8646 100644
--- a/tests/entrypoints/openai_api/test_serving_speech.py
+++ b/tests/entrypoints/openai_api/test_serving_speech.py
@@ -27,6 +27,7 @@
 from pytest_mock import MockerFixture
 from vllm.entrypoints.serve.engine.protocol import ErrorInfo, ErrorResponse
 
+from vllm_omni.config.stage_config import StagePipelineConfig
 from vllm_omni.diffusion.request import OmniDiffusionRequest
 from vllm_omni.diffusion.sched.request_scheduler import RequestScheduler
 from vllm_omni.diffusion.sched.step_scheduler import StepScheduler
@@ -1039,6 +1040,38 @@ def test_prepare_speech_rejects_non_tts_omni_model(self, mocker: MockerFixture):
             asyncio.run(server._prepare_speech_generation(request))
         server.shutdown()
 
+    def test_prepare_speech_rejects_typed_non_tts_omni_model(self, mocker: MockerFixture):
+        """Typed Qwen3-Omni stages must hit the same talker guard as legacy stages."""
+        mock_engine_client = mocker.MagicMock()
+        mock_engine_client.errored = False
+        mock_engine_client.tts_max_instructions_length = None
+        mock_engine_client.stage_configs = [
+            SimpleNamespace(
+                stage_pipeline_config=StagePipelineConfig(stage_id=index, model_stage=model_stage),
+                model_config=SimpleNamespace(model_arch=None),
+                worker_type=worker_type,
+            )
+            for index, (model_stage, worker_type) in enumerate(
+                (
+                    ("thinker", "ar"),
+                    ("talker", "ar"),
+                    ("code2wav", "generation"),
+                )
+            )
+        ]
+
+        mock_models = mocker.MagicMock()
+        mock_models.is_base_model.return_value = True
+        server = OmniOpenAIServingSpeech(
+            engine_client=mock_engine_client,
+            models=mock_models,
+            request_logger=mocker.MagicMock(),
+        )
+        request = OpenAICreateSpeechRequest(input="Hello world")
+        with pytest.raises(ValueError, match="only supported for dedicated TTS models"):
+            asyncio.run(server._prepare_speech_generation(request))
+        server.shutdown()
+
     def test_estimate_prompt_len_fallback(self, speech_server):
         """Test prompt length estimation falls back to 2048 when model is unavailable."""
         tts_params = {"text": ["Hello"], "task_type": ["CustomVoice"]}
diff --git a/tests/entrypoints/openai_api/test_tts_adapter.py b/tests/entrypoints/openai_api/test_tts_adapter.py
index e0a165a5571..500feab3546 100644
--- a/tests/entrypoints/openai_api/test_tts_adapter.py
+++ b/tests/entrypoints/openai_api/test_tts_adapter.py
@@ -22,6 +22,7 @@
     detect_tts_model_type,
     resolve_adapter,
 )
+from vllm_omni.entrypoints.openai.tts_adapters.base import resolve_stage_model_path
 from vllm_omni.entrypoints.openai.tts_adapters.covo_audio import CovoAudioAdapter
 from vllm_omni.entrypoints.openai.tts_adapters.higgs_audio_v2 import HiggsAudioV2Adapter
 from vllm_omni.entrypoints.openai.tts_adapters.indextts2 import (
@@ -99,6 +100,31 @@ def test_resolve_unknown_returns_none():
     assert resolve_adapter(None) is None
 
 
+def test_stage_model_path_prefers_typed_override():
+    engine_client = SimpleNamespace(
+        stage_configs=[
+            SimpleNamespace(engine_args=SimpleNamespace(model="legacy-stage-model")),
+            SimpleNamespace(
+                model_config=SimpleNamespace(model="typed-stage-model"),
+            ),
+        ],
+        model="served-model",
+    )
+
+    assert resolve_stage_model_path(engine_client) == "typed-stage-model"
+
+
+def test_stage_model_path_falls_back_to_legacy_then_served_model():
+    legacy_client = SimpleNamespace(
+        stage_configs=[SimpleNamespace(engine_args=SimpleNamespace(model="legacy-stage-model"))],
+        model="served-model",
+    )
+    served_client = SimpleNamespace(stage_configs=[SimpleNamespace()], model="served-model")
+
+    assert resolve_stage_model_path(legacy_client) == "legacy-stage-model"
+    assert resolve_stage_model_path(served_client) == "served-model"
+
+
 def test_voxcpm2_resolves():
     """VoxCPM2 (the served ``latent_generator`` model) resolves cleanly.
 
diff --git a/tests/entrypoints/openai_api/test_video_server.py b/tests/entrypoints/openai_api/test_video_server.py
index 2de5c4056b7..0b44cabdf6b 100644
--- a/tests/entrypoints/openai_api/test_video_server.py
+++ b/tests/entrypoints/openai_api/test_video_server.py
@@ -1134,6 +1134,32 @@ def test_mixed_reference_capability_uses_model_metadata_when_config_defaults_fal
     assert handler.supports_mixed_reference_inputs
 
 
+def test_typed_stage_drives_video_capability_checks():
+    from vllm_omni.config.config_factory import StageConfigFactory
+
+    minimax_stage = StageConfigFactory.create_typed_default_diffusion(
+        "minimax-h3",
+        {"model_class_name": "MiniMaxH3Pipeline"},
+    ).stage_configs[0]
+    minimax_handler = OmniOpenAIServingVideo.for_diffusion(
+        SimpleNamespace(od_config=SimpleNamespace(model_class_name=None)),
+        model_name="minimax-h3",
+        stage_configs=[minimax_stage],
+    )
+    assert minimax_handler.supports_mixed_reference_inputs
+
+    cosmos_stage = StageConfigFactory.create_typed_default_diffusion(
+        "cosmos3",
+        {"model_class_name": "Cosmos3OmniDiffusersPipeline"},
+    ).stage_configs[0]
+    cosmos_handler = OmniOpenAIServingVideo.for_diffusion(
+        SimpleNamespace(od_config=SimpleNamespace(model_class_name=None)),
+        model_name="cosmos3",
+        stage_configs=[cosmos_stage],
+    )
+    assert cosmos_handler.supported_control_upload_types == frozenset({"edge", "blur", "depth", "seg", "wsm"})
+
+
 @pytest.mark.parametrize("model_class_name", ["Cosmos3OmniDiffusersPipeline", "Cosmos3OmniPipeline"])
 def test_control_upload_capability_is_declared_only_by_cosmos3(test_client, model_class_name):
     handler = test_client.app.state.openai_serving_video
@@ -1191,6 +1217,35 @@ def test_cosmos3_reference_video_limit_uses_v2v_condition_frames():
     assert spec.keep == "first"
 
 
+@pytest.mark.parametrize("typed", [False, True], ids=["legacy", "typed"])
+@pytest.mark.parametrize(
+    ("num_frames", "extra_params", "expected"),
+    [
+        (189, {"condition_frame_indexes_vision": [0, 2], "condition_video_keep": "last"}, (9, "last")),
+        (189, {"condition_frame_indexes_vision": [0, 2]}, (9, "first")),
+        (5, {"condition_frame_indexes_vision": [0, 20]}, (5, "first")),
+        (None, {"action_mode": "inverse_dynamics", "action_chunk_size": 16}, (17, "first")),
+    ],
+)
+def test_cosmos3_reference_video_decode_policy_with_runtime_configs(typed, num_frames, extra_params, expected):
+    from vllm_omni.config.config_factory import StageConfigFactory
+
+    if typed:
+        stages = list(
+            StageConfigFactory.create_typed_default_diffusion(
+                "cosmos3",
+                {"model_class_name": "Cosmos3OmniDiffusersPipeline"},
+            ).stage_configs
+        )
+    else:
+        stages = _cosmos3_stage_configs()
+    request = VideoGenerationRequest(prompt="Continue this motion.", num_frames=num_frames, extra_params=extra_params)
+
+    spec = _reference_video_decode_spec(request, stages)
+
+    assert (spec.max_frames, spec.keep) == expected
+
+
 def test_cosmos3_reference_video_limit_preserves_action_frames():
     request = VideoGenerationRequest(
         prompt="Predict the action.",
diff --git a/tests/entrypoints/test_async_omni_diffusion_config.py b/tests/entrypoints/test_async_omni_diffusion_config.py
index 3b378930ab3..9b99af71233 100644
--- a/tests/entrypoints/test_async_omni_diffusion_config.py
+++ b/tests/entrypoints/test_async_omni_diffusion_config.py
@@ -2,13 +2,15 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from types import SimpleNamespace
+from typing import Any
 
 import pytest
 import torch
 from pydantic import ValidationError
 
 from vllm_omni.config.config_factory import StageConfigFactory
-from vllm_omni.config.resolver import OmniConfigResolution
+from vllm_omni.config.omni_config import VllmOmniDiffusionStageConfig
+from vllm_omni.config.resolver import OmniConfigResolution, resolve_omni_config
 from vllm_omni.diffusion.data import AttentionConfig, OmniDiffusionConfig
 from vllm_omni.engine import stage_init_utils
 from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
@@ -117,7 +119,7 @@ def test_stage_override_preserves_model_extras_for_default_diffusion_stage(mocke
         trust_remote_code=False,
     )
 
-    assert stage_configs[0]["engine_args"]["extras"]["ltx2_use_conv_vae"] is True
+    assert stage_configs[0].diffusion_config.extras["ltx2_use_conv_vae"] is True
 
 
 def test_default_stage_rejects_unknown_nested_parallel_config_key():
@@ -239,6 +241,33 @@ def test_default_stage_config_includes_default_sampling_params():
     }
 
 
+@pytest.mark.parametrize("typed", [False, True], ids=["legacy", "typed"])
+@pytest.mark.parametrize("sampling_defaults", [{"0": {"guidance_scale": 7.5}}, '{"0":{"guidance_scale":7.5}}'])
+def test_generic_diffusion_sampling_defaults_remain_overridable(typed, sampling_defaults):
+    from vllm_omni.config.yaml_util import create_config
+    from vllm_omni.entrypoints.omni_base import OmniBase
+    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+    kwargs = {"model_class_name": "QwenImagePipeline", "default_sampling_params": sampling_defaults}
+    if typed:
+        stage = StageConfigFactory.create_typed_default_diffusion("generic-diffusion", kwargs).stage_configs[0]
+        metadata = stage_init_utils.extract_stage_metadata_from_omni_stage_config(stage)
+    else:
+        stage = create_config(StageConfigFactory.create_default_diffusion(kwargs))[0]
+        metadata = stage_init_utils.extract_legacy_stage_metadata(stage)
+    base = OmniBase.__new__(OmniBase)
+    base.engine = SimpleNamespace(num_stages=1, stage_configs=[stage])
+    base.default_sampling_params_list = [metadata.default_sampling_params]
+    base.sampling_constraints_list = base._get_sampling_constraints_list([stage])
+
+    assert base.resolve_sampling_params_list(None)[0].guidance_scale == 7.5
+    requested = OmniDiffusionSamplingParams(guidance_scale=2.0)
+    assert base.resolve_sampling_params_list(requested)[0].guidance_scale == 2.0
+    assert requested.guidance_scale == 2.0
+    assert base.default_sampling_params_list[0].guidance_scale == 7.5
+    assert base.sampling_constraints_list == [{}]
+
+
 def test_default_stage_config_includes_diffusion_attention_backend():
     """Ensure diffusion attention shorthand lands in engine_args.diffusion_attention_config."""
     stage_cfg = StageConfigFactory.create_default_diffusion(
@@ -726,3 +755,106 @@ def test_default_stage_config_includes_quantization_config():
     stage_cfg = StageConfigFactory.create_default_diffusion({"quantization_config": quantization_config})[0]
 
     assert stage_cfg["engine_args"]["quantization_config"] == quantization_config
+
+
+@pytest.mark.parametrize("model_class_name", ["HeliosPipeline", "HunyuanVideo15Pipeline"])
+def test_generic_diffusion_uses_canonical_video_output_type(model_class_name):
+    config = StageConfigFactory.create_typed_default_diffusion(
+        "generic-video",
+        {"model_class_name": model_class_name},
+    )
+
+    assert config.stage_configs[0].final_output_type == "video"
+
+
+def test_generic_diffusion_resolves_structured_stage_without_legacy_conversion(mocker):
+    """Generic diffusion reaches runtime as the structured stage itself."""
+    mocker.patch("vllm_omni.config.resolver.StageConfigFactory.create_from_model", return_value=None)
+    mocker.patch(
+        "vllm_omni.config.resolver._resolve_generic_diffusion_model_class",
+        return_value=(True, "FakeDiffusionPipeline"),
+    )
+
+    resolved = resolve_omni_config(
+        "generic-diffusion",
+        trust_remote_code=False,
+        deploy_config_path=None,
+        cli_overrides={
+            "num_gpus": 4,
+            "tensor_parallel_size": 2,
+            "default_sampling_params": '{"0": {"guidance_scale": 7.5}}',
+        },
+        stage_overrides=None,
+        strategy_config_path=None,
+    )
+
+    assert resolved.pipeline_config is not None
+    assert resolved.pipeline_config.model_type == "generic_diffusion"
+    assert len(resolved.stage_configs) == 1
+    stage = resolved.stage_configs[0]
+    assert isinstance(stage, VllmOmniDiffusionStageConfig)
+    assert stage.model_config.model == "generic-diffusion"
+    assert stage.model_config.default_sampling_params == {"guidance_scale": 7.5}
+    assert stage.parallel_config.tensor_parallel_size == 2
+    assert stage.parallel_config.data_parallel_size == 2
+    assert stage.parallel_config.world_size == 4
+    assert stage.runtime_config.devices == "0,1,2,3"
+
+
+def test_generic_diffusion_structured_stage_reaches_standard_startup(mocker):
+    """Standard runtime resolves and starts the typed stage through the real launcher."""
+    from vllm_omni.engine import stage_engine_startup as startup_module
+    from vllm_omni.engine import stage_runtime as runtime_module
+    from vllm_omni.engine.stage_runtime import StageRuntime
+
+    mocker.patch("vllm_omni.config.resolver.StageConfigFactory.create_from_model", return_value=None)
+    mocker.patch(
+        "vllm_omni.config.resolver._resolve_generic_diffusion_model_class",
+        return_value=(True, "FakeDiffusionPipeline"),
+    )
+    resolved = resolve_omni_config(
+        "generic-diffusion",
+        trust_remote_code=False,
+        deploy_config_path=None,
+        cli_overrides={"num_gpus": 1},
+        stage_overrides=None,
+        strategy_config_path=None,
+    )
+    stage = resolved.stage_configs[0]
+    launched: dict[str, Any] = {}
+    client = SimpleNamespace(input_address=None, shutdown=mocker.Mock())
+
+    mocker.patch.object(runtime_module, "prepare_engine_environment")
+    mocker.patch.object(runtime_module, "load_omni_transfer_config_for_model", return_value=None)
+    mocker.patch.object(runtime_module, "get_stage_connector_spec", return_value={})
+    mocker.patch.object(runtime_module, "resolve_omni_kv_config_for_stage", return_value=(None, None, None))
+
+    def _initialize_typed_stage(stage_id, model, stage_config, metadata, **kwargs):
+        launched.update(
+            stage_id=stage_id,
+            model=model,
+            stage_config=stage_config,
+            metadata=metadata,
+            **kwargs,
+        )
+        return client
+
+    mocker.patch.object(startup_module, "initialize_diffusion_stage", side_effect=_initialize_typed_stage)
+
+    runtime = StageRuntime(
+        stage_configs=list(resolved.stage_configs),
+        model="generic-diffusion",
+        config_path="",
+        stage_init_timeout=10,
+        async_chunk=False,
+    )
+    runtime.initialize()
+
+    assert launched["stage_config"] is stage
+    assert isinstance(launched["stage_config"], VllmOmniDiffusionStageConfig)
+    assert launched["metadata"].stage_type == "diffusion"
+    assert launched["metadata"].model_stage == "diffusion"
+    assert launched["use_inline"] is True
+    assert launched["model"] == "generic-diffusion"
+    assert launched["stage_id"] == 0
+    assert runtime.stage_pools[0].clients == [client]
diff --git a/tests/entrypoints/test_omni_entrypoints.py b/tests/entrypoints/test_omni_entrypoints.py
index ea57d07ab7a..969bbaf910b 100644
--- a/tests/entrypoints/test_omni_entrypoints.py
+++ b/tests/entrypoints/test_omni_entrypoints.py
@@ -17,6 +17,8 @@
 from vllm.sampling_params import RequestOutputKind, SamplingParams
 from vllm.v1.engine.exceptions import EngineDeadError, EngineGenerateError
 
+from vllm_omni.config.omni_config import VllmOmniConfig
+from vllm_omni.config.pipeline_registry import OMNI_PIPELINES
 from vllm_omni.config.stage_config import StageConfig
 from vllm_omni.engine.async_omni_engine import StageRuntimeInfo
 from vllm_omni.engine.messages import ErrorMessage, OutputMessage
@@ -202,6 +204,49 @@ def _make_base():
     return obj
 
 
+@pytest.mark.parametrize("typed", [False, True], ids=["legacy", "typed"])
+def test_resolve_sampling_params_list_preserves_stage_constraints(typed):
+    from vllm_omni.config.omni_config import VllmOmniARStageConfig
+    from vllm_omni.config.stage_config import StagePipelineConfig
+
+    base = _make_base()
+    base.engine.num_stages = 1
+    base.default_sampling_params_list = [SamplingParams(max_tokens=1000, detokenize=False, stop_token_ids=[42])]
+    if typed:
+        stage = VllmOmniARStageConfig(
+            stage_pipeline_config=StagePipelineConfig(
+                stage_id=0,
+                model_stage="dummy-model",
+                sampling_constraints={"detokenize": False, "stop_token_ids": [42]},
+            )
+        )
+    else:
+        stage = StageConfig(
+            stage_id=0,
+            model_stage="dummy-model",
+            sampling_constraints={"detokenize": False, "stop_token_ids": [42]},
+        ).to_omegaconf()
+    base.engine.stage_configs = [stage]
+    base.sampling_constraints_list = base._get_sampling_constraints_list(base.engine.stage_configs)
+    assert base.sampling_constraints_list == [{"detokenize": False, "stop_token_ids": [42]}]
+
+    resolved_defaults = base.resolve_sampling_params_list(None)
+    assert resolved_defaults[0].stop_token_ids == [42]
+
+    caller_params = SamplingParams(seed=1234, max_tokens=7, detokenize=True, stop_token_ids=[7])
+    resolved = base.resolve_sampling_params_list(caller_params)
+
+    assert resolved[0] is not caller_params
+    assert resolved[0].seed == 1234
+    assert resolved[0].max_tokens == 7
+    assert resolved[0].detokenize is False
+    assert resolved[0].stop_token_ids == [7, 42]
+    assert 7 in resolved[0]._all_stop_token_ids
+    assert 42 in resolved[0]._all_stop_token_ids
+    assert caller_params.detokenize is True
+    assert caller_params.stop_token_ids == [7]
+
+
 def test_resolve_sampling_params_list_merges_required_stop_tokens():
     base = _make_base()
     base.engine.num_stages = 1
@@ -219,22 +264,13 @@ def test_resolve_sampling_params_list_merges_required_stop_tokens():
     base.sampling_constraints_list = base._get_sampling_constraints_list(base.engine.stage_configs)
     assert base.sampling_constraints_list == [{"detokenize": False, "stop_token_ids": required_stop_ids}]
 
-    resolved_defaults = base.resolve_sampling_params_list(None)
-
-    assert resolved_defaults[0].stop_token_ids == [99, 151704, 151645]
 
-    caller_params = SamplingParams(seed=1234, max_tokens=7, detokenize=True, stop_token_ids=[100, 151704])
+def test_sampling_constraints_are_forwarded_by_typed_stage_configs():
+    config = VllmOmniConfig.from_pipeline_config(OMNI_PIPELINES["qwen3_tts"])
 
-    resolved = base.resolve_sampling_params_list(caller_params)
+    constraints = OmniBase._get_sampling_constraints_list(config.stage_configs)
 
-    assert resolved[0] is not caller_params
-    assert resolved[0].seed == 1234
-    assert resolved[0].max_tokens == 7
-    assert resolved[0].detokenize is False
-    assert resolved[0].stop_token_ids == [100, 151704, 151645]
-    assert {100, 151704, 151645}.issubset(resolved[0]._all_stop_token_ids)
-    assert caller_params.detokenize is True
-    assert caller_params.stop_token_ids == [100, 151704]
+    assert constraints == [dict(stage.stage_pipeline_config.sampling_constraints) for stage in config.stage_configs]
 
 
 @pytest.mark.parametrize("use_defaults", [False, True])
diff --git a/tests/entrypoints/test_resolve_dreamzero_config.py b/tests/entrypoints/test_resolve_dreamzero_config.py
index 450e1be392c..3cfa0f0e58d 100644
--- a/tests/entrypoints/test_resolve_dreamzero_config.py
+++ b/tests/entrypoints/test_resolve_dreamzero_config.py
@@ -32,15 +32,18 @@ def test_dreamzero_resolves_through_registry_with_model_defaults(monkeypatch):
         stage_overrides=None,
         strategy_config_path=None,
     )
-    engine_args = resolved.stage_configs[0].engine_args
+    stage = resolved.stage_configs[0]
 
     assert resolved.config_path is not None
     assert resolved.config_path.endswith("vllm_omni/deploy/dreamzero.yaml")
-    assert engine_args.model_class_name == "DreamZeroPipeline"
-    assert engine_args.model_config.policy_server_config.action_space == "joint_position"
+    assert stage.diffusion_config.model_class_name == "DreamZeroPipeline"
+    assert stage.diffusion_config.model_config["policy_server_config"]["action_space"] == "joint_position"
 
 
 def test_dreamzero_enrich_config_preserves_explicit_model_class_name(monkeypatch):
+    def _get_hf_config(path, _model):
+        return None if path == "model_index.json" else {"model_type": "vla", "architectures": ["VLA"]}
+
     monkeypatch.setattr(
         "vllm.transformers_utils.config.get_hf_file_to_dict",
         lambda path, _model, **_kwargs: (
diff --git a/tests/entrypoints/test_serve.py b/tests/entrypoints/test_serve.py
index 1f3b5817099..8d3766df00c 100644
--- a/tests/entrypoints/test_serve.py
+++ b/tests/entrypoints/test_serve.py
@@ -7,10 +7,12 @@
 
 import argparse
 from types import SimpleNamespace
+from typing import Any
 
 import pytest
 from pytest_mock import MockerFixture
 
+from vllm_omni.config.omni_config import VllmOmniDiffusionStageConfig
 from vllm_omni.config.resolver import OmniConfigResolution
 from vllm_omni.entrypoints.cli.serve import (
     OmniServeCommand,
@@ -334,6 +336,26 @@ def test_parse_stage_overrides_invalid_json_raises() -> None:
     assert f"Got: {bad!r}" in message
 
 
+@pytest.mark.parametrize(
+    "payload",
+    ['{"abc": {}}', '{"-1": {}}', '{"1.5": {}}', '{"\uff10": {}}'],
+)
+def test_parse_stage_overrides_rejects_invalid_stage_ids(payload: str) -> None:
+    with pytest.raises(argparse.ArgumentTypeError, match="non-negative integer stage ids"):
+        _parse_stage_overrides(payload)
+
+
+def test_parse_stage_overrides_preserves_arbitrary_override_fields() -> None:
+    parsed = _parse_stage_overrides(
+        '{"0": {"extras": {"ltx2_use_conv_vae": true}, "kv_cache_dtype": "fp8", "typo_field_xyz": 1}}'
+    )
+    assert parsed["0"] == {
+        "extras": {"ltx2_use_conv_vae": True},
+        "kv_cache_dtype": "fp8",
+        "typo_field_xyz": 1,
+    }
+
+
 def test_parse_stage_overrides_rejects_non_dict_top_level() -> None:
     """Top-level must be a JSON object (dict). A list, scalar, or non-dict
     mapping is rejected with a ValueError naming ``--stage-overrides`` and
@@ -706,6 +728,77 @@ def test_run_headless_diffusion_registers_and_spawns_proc(mocker: MockerFixture)
     assert manager_kwargs["omni_replica_id"] == 0
 
 
+def test_run_headless_generic_diffusion_launches_structured_stage(mocker: MockerFixture) -> None:
+    """Headless resolution starts the typed stage through the real group launcher."""
+    from vllm_omni.engine import stage_engine_startup as startup_module
+
+    mocker.patch("vllm_omni.config.resolver.StageConfigFactory.create_from_model", return_value=None)
+    mocker.patch(
+        "vllm_omni.config.resolver._resolve_generic_diffusion_model_class",
+        return_value=(True, "FakeDiffusionPipeline"),
+    )
+    mocker.patch("vllm_omni.engine.stage_init_utils.prepare_engine_environment")
+    mocker.patch.object(startup_module.stage_init_utils, "load_omni_transfer_config_for_model", return_value=None)
+    mocker.patch.object(
+        startup_module.initialization,
+        "resolve_omni_kv_config_for_stage",
+        return_value=(None, None, None),
+    )
+    captured: dict[str, Any] = {}
+    od_config = SimpleNamespace()
+
+    def _build_diffusion_config(model, stage_config, metadata):
+        captured.update(model=model, stage_config=stage_config, metadata=metadata)
+        return od_config
+
+    def _launch_replica_group(**kwargs):
+        captured.update(group_kwargs=kwargs)
+        captured["manager"] = kwargs["launch_one"](0)
+
+    def _launch_replica(**kwargs):
+        captured.update(replica_kwargs=kwargs)
+        return SimpleNamespace(exitcode=None)
+
+    mocker.patch.object(startup_module.stage_init_utils, "build_diffusion_config", side_effect=_build_diffusion_config)
+    mocker.patch.object(startup_module, "launch_headless_replica_group", side_effect=_launch_replica_group)
+    mocker.patch.object(startup_module, "launch_headless_diffusion_replica", side_effect=_launch_replica)
+
+    explicit_keys = frozenset(
+        {
+            "model",
+            "stage_id",
+            "omni_master_address",
+            "omni_master_port",
+            "worker_backend",
+            "model_class_name",
+            "num_gpus",
+        }
+    )
+    args = _make_headless_args(
+        explicit_keys=explicit_keys,
+        model="generic-diffusion",
+        model_class_name="FakeDiffusionPipeline",
+        num_gpus=1,
+    )
+
+    run_headless(args)
+
+    stage = captured["stage_config"]
+    assert isinstance(stage, VllmOmniDiffusionStageConfig)
+    assert captured["metadata"].stage_type == "diffusion"
+    assert captured["metadata"].model_stage == "diffusion"
+    assert captured["model"] == "generic-diffusion"
+    assert captured["group_kwargs"]["stage_id"] == 0
+    assert captured["group_kwargs"]["omni_dp_size_local"] == 1
+    assert captured["group_kwargs"]["per_replica_devices"] == ["0"]
+    assert captured["replica_kwargs"]["stage_config"] is stage
+    assert captured["replica_kwargs"]["stage_id"] == 0
+    assert captured["replica_kwargs"]["omni_master_address"] == "127.0.0.1"
+    assert captured["replica_kwargs"]["omni_master_port"] == 26000
+    assert captured["replica_kwargs"]["od_config"] is od_config
+    assert stage.runtime_config.devices == "0"
+
+
 def test_run_headless_diffusion_raises_on_nonzero_proc_exit(mocker: MockerFixture) -> None:
     """A diffusion replica that exits with a non-zero code must surface as a
     RuntimeError from ``run_headless`` (the head needs the signal to roll
diff --git a/tests/entrypoints/test_utils.py b/tests/entrypoints/test_utils.py
index 680bb110cf4..e7f94ffef70 100644
--- a/tests/entrypoints/test_utils.py
+++ b/tests/entrypoints/test_utils.py
@@ -13,6 +13,14 @@
 from pytest_mock import MockerFixture
 from vllm.sampling_params import RequestOutputKind, SamplingParams
 
+from vllm_omni.config.composable_parallel import (
+    Broadcast,
+    FanInByStage,
+    MeshAxisSpec,
+    RouteByStage,
+    StrategySpec,
+    TakeRank,
+)
 from vllm_omni.config.pipeline_registry import OMNI_PIPELINES
 from vllm_omni.config.resolver import (
     OmniConfigResolution,
@@ -21,7 +29,6 @@
     resolve_omni_config,
 )
 from vllm_omni.config.stage_config import PipelineConfig
-from vllm_omni.config.yaml_util import create_config
 from vllm_omni.diffusion.data import OmniDiffusionConfig
 from vllm_omni.engine.arg_utils import OmniEngineArgs
 from vllm_omni.entrypoints.utils import (
@@ -356,16 +363,12 @@ def test_load_and_resolve_with_kwargs(self, mocker: MockerFixture):
         )
         assert resolved.config_path is None
         assert len(resolved.stage_configs) == 1
-        engine_args = resolved.stage_configs[0]["engine_args"]
-        assert "dtype" in engine_args
-        assert engine_args["engine_backend"] == engine_backend
-        assert engine_args["revision"] == "pinned-revision"
+        assert resolved.stage_configs[0].diffusion_config.dtype is torch.float32
+        assert resolved.stage_configs[0].diffusion_config.engine_backend == engine_backend
+        assert resolved.stage_configs[0].diffusion_config.revision == "pinned-revision"
 
     def test_generic_diffusion_uses_registered_model_metadata(self, mocker: MockerFixture):
-        mocker.patch(
-            "vllm_omni.config.resolver.StageConfigFactory.create_from_model",
-            return_value=None,
-        )
+        mocker.patch("vllm_omni.config.resolver.StageConfigFactory.create_from_model", return_value=None)
         resolve_model_class = mocker.patch(
             "vllm_omni.config.resolver.resolve_model_class_name",
             return_value="WanImageToVideoPipeline",
@@ -374,59 +377,98 @@ def test_generic_diffusion_uses_registered_model_metadata(self, mocker: MockerFi
             "vllm_omni.config.resolver.DiffusionModelRegistry.get_supported_archs",
             return_value={"WanImageToVideoPipeline"},
         )
+        load_model_class = mocker.patch("vllm_omni.config.resolver.DiffusionModelRegistry._try_load_model_cls")
 
         resolved = resolve_omni_config(
             "/models/Wan2.2-I2V",
             trust_remote_code=False,
             deploy_config_path=None,
-            cli_overrides={
-                "diffusion_load_format": "diffusers",
-                "revision": "pinned-revision",
-            },
+            cli_overrides={"diffusion_load_format": "diffusers", "revision": "pinned-revision"},
             stage_overrides=None,
             strategy_config_path=None,
         )
 
+        resolve_model_class.assert_called_once_with("/models/Wan2.2-I2V", "diffusers", "pinned-revision")
+        load_model_class.assert_not_called()
         stage = resolved.stage_configs[0]
-        resolve_model_class.assert_called_once_with(
-            "/models/Wan2.2-I2V",
-            "diffusers",
-            "pinned-revision",
-        )
-        assert stage.engine_args.model_class_name == "WanImageToVideoPipeline"
+        assert stage.diffusion_config.model_class_name == "WanImageToVideoPipeline"
+        assert stage.diffusion_config.revision == "pinned-revision"
         assert stage.final_output_type == "video"
 
+    def test_generic_diffusion_stage_overrides_reach_typed_backend(self, mocker: MockerFixture):
+        from vllm_omni.engine.stage_init_utils import build_engine_args_dict_from_omni_stage_config
+
+        mocker.patch("vllm_omni.config.resolver.StageConfigFactory.create_from_model", return_value=None)
+        mocker.patch(
+            "vllm_omni.config.resolver._resolve_generic_diffusion_model_class",
+            return_value=(True, "LTX2Pipeline"),
+        )
+        resolved = resolve_omni_config(
+            "/models/LTX-2.5-Diffusers",
+            trust_remote_code=False,
+            deploy_config_path=None,
+            cli_overrides={
+                "extras": {"ltx2_use_conv_vae": False, "keep": "global"},
+                "tensor_parallel_size": 1,
+                "diffusion_streaming_output": True,
+            },
+            stage_overrides={
+                "0": {
+                    "extras": {"ltx2_use_conv_vae": True},
+                    "tensor_parallel_size": 2,
+                    "devices": "2,3",
+                    "engine_backend": "custom.backend",
+                },
+            },
+            strategy_config_path=None,
+        )
+        stage = resolved.stage_by_id(0)
+        engine_args = build_engine_args_dict_from_omni_stage_config(stage, model="/models/LTX-2.5-Diffusers")
+
+        assert stage.runtime_config.devices == "2,3"
+        assert stage.parallel_config.world_size == 2
+        assert engine_args["engine_backend"] == "custom.backend"
+        assert engine_args["extras"]["ltx2_use_conv_vae"] is True
+        assert engine_args["extras"]["keep"] == "global"
+        assert engine_args["streaming_output"] is True
+
     def test_registered_pipeline_uses_structured_metadata_and_preserves_override_trust(self, mocker: MockerFixture):
         endpoint_restriction = SimpleNamespace(name="chat")
+        typed_stage = SimpleNamespace(stage_id=1)
         structured_config = SimpleNamespace(
-            orchestrator_config=SimpleNamespace(deploy_config_path="/resolved/deploy.yaml"),
+            orchestrator_config=SimpleNamespace(
+                deploy_config_path="/resolved/deploy.yaml",
+                omni_lb_policy="round_robin",
+            ),
             pipeline_config=SimpleNamespace(endpoint_restrictions=(endpoint_restriction,)),
+            stage_configs=(typed_stage,),
+            strategy_omni_lb_policy="round-robin",
         )
-        runtime_stage = create_config(
-            {
-                "stage_id": 1,
-                "runtime": {"devices": "1,2,3", "num_replicas": 3},
-                "engine_args": {"model": "dummy-model"},
-            }
-        )
-        legacy_stage = SimpleNamespace(to_omegaconf=lambda: runtime_stage)
         create_structured = mocker.patch(
             "vllm_omni.config.resolver.StageConfigFactory.create_from_model",
             return_value=structured_config,
         )
         create_legacy = mocker.patch(
-            "vllm_omni.config.resolver.StageConfigFactory._resolve_legacy_from_registry",
-            return_value=SimpleNamespace(
-                stage_configs=[legacy_stage],
-                pipeline_config=structured_config.pipeline_config,
-                omni_lb_policy="round_robin",
-            ),
+            "vllm_omni.config.resolver.StageConfigFactory.create_legacy_stage_configs_from_model",
         )
-        strategy_specs = {"stage_1": {"dp": 3}}
+        strategy_specs = {
+            "stage_1": [
+                StrategySpec(
+                    "stage_replica",
+                    MeshAxisSpec("stage_replica", 2),
+                    RouteByStage("round_robin"),
+                    FanInByStage(),
+                )
+            ]
+        }
         load_strategy = mocker.patch(
             "vllm_omni.config.resolver._load_strategy_specs",
             return_value=strategy_specs,
         )
+        apply_strategy = mocker.patch(
+            "vllm_omni.config.composable_parallel.apply_strategy_specs",
+            return_value=SimpleNamespace(omni_lb_policy="round_robin"),
+        )
 
         resolved = resolve_omni_config(
             "dummy-model",
@@ -447,31 +489,63 @@ def test_registered_pipeline_uses_structured_metadata_and_preserves_override_tru
             trust_remote_code=None,
             cli_overrides=expected_overrides,
             deploy_config_path="deploy.yaml",
-        )
-        create_legacy.assert_called_once_with(
-            structured_config.pipeline_config,
-            expected_overrides,
-            "/resolved/deploy.yaml",
             strategy_specs=strategy_specs,
         )
+        create_legacy.assert_not_called()
         load_strategy.assert_called_once_with("strategy.yaml")
+        apply_strategy.assert_not_called()
         assert resolved.config_path == "/resolved/deploy.yaml"
         assert resolved.pipeline_config is structured_config.pipeline_config
-        assert resolved.omni_lb_policy == "round_robin"
+        assert resolved.omni_lb_policy == "round-robin"
         assert resolved.endpoint_restrictions == (endpoint_restriction,)
-        assert resolved.stage_configs == (runtime_stage,)
+        assert resolved.stage_configs == (typed_stage,)
 
-    def test_registered_resolution_exposes_forced_aligner_topology(self, mocker: MockerFixture):
-        pipeline = OMNI_PIPELINES["qwen3_tts"]
-        assert isinstance(pipeline, PipelineConfig)
+    def test_tp_only_strategy_does_not_report_default_lb_policy_as_derived(self, mocker: MockerFixture):
         structured_config = SimpleNamespace(
-            orchestrator_config=SimpleNamespace(deploy_config_path=None),
-            pipeline_config=pipeline,
+            orchestrator_config=SimpleNamespace(
+                deploy_config_path="/resolved/deploy.yaml",
+                omni_lb_policy="round-robin",
+            ),
+            pipeline_config=SimpleNamespace(endpoint_restrictions=()),
+            stage_configs=(SimpleNamespace(stage_id=0),),
+            strategy_omni_lb_policy=None,
         )
         mocker.patch(
             "vllm_omni.config.resolver.StageConfigFactory.create_from_model",
             return_value=structured_config,
         )
+        mocker.patch(
+            "vllm_omni.config.resolver._load_strategy_specs",
+            return_value={
+                "thinker": [
+                    StrategySpec(
+                        "tp",
+                        MeshAxisSpec("tp", 2),
+                        Broadcast(),
+                        TakeRank(),
+                    )
+                ]
+            },
+        )
+
+        resolved = resolve_omni_config(
+            "dummy-model",
+            trust_remote_code=True,
+            deploy_config_path="deploy.yaml",
+            cli_overrides={"omni_lb_policy": "round-robin"},
+            stage_overrides=None,
+            strategy_config_path="strategy.yaml",
+        )
+
+        assert resolved.omni_lb_policy is None
+
+    def test_registered_resolution_exposes_forced_aligner_topology(self, mocker: MockerFixture):
+        pipeline = OMNI_PIPELINES["qwen3_tts"]
+        assert isinstance(pipeline, PipelineConfig)
+        mocker.patch(
+            "vllm_omni.config.config_factory.StageConfigFactory.get_pipeline_config",
+            return_value=pipeline,
+        )
 
         resolved = resolve_omni_config(
             "Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice",
@@ -483,9 +557,9 @@ def test_registered_resolution_exposes_forced_aligner_topology(self, mocker: Moc
         )
 
         assert resolved.pipeline_config is not None
-        pipeline_stage_ids = [stage.stage_id for stage in resolved.pipeline_config.stages]
-        runtime_stage_ids = [stage.stage_id for stage in resolved.stage_configs]
-        assert pipeline_stage_ids == runtime_stage_ids
+        assert [stage.stage_id for stage in resolved.pipeline_config.stages] == [
+            stage.stage_id for stage in resolved.stage_configs
+        ]
         assert resolved.pipeline_config.stages[-1].model_stage == "forced_aligner"
         assert len(resolved.pipeline_config.stages) == len(pipeline.stages) + 1
 
diff --git a/vllm_omni/config/composable_parallel/apply.py b/vllm_omni/config/composable_parallel/apply.py
index 879c7aec3d8..acfb9e22923 100644
--- a/vllm_omni/config/composable_parallel/apply.py
+++ b/vllm_omni/config/composable_parallel/apply.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Apply declarative parallel strategies onto merged stage configs.
 
 This is the *override-after-merge* seam. ``merge_pipeline_deploy`` first fuses
@@ -198,10 +198,41 @@ def _check_devices(runtime: dict[str, Any], cfg: OmniParallelConfig, *, role: Ro
 
 
 def _apply_to_stage(stage: Any, cfg: OmniParallelConfig, *, role: RoleKey) -> None:
+    declared = set(cfg.l1_owners.keys())
+    if hasattr(stage, "parallel_config") and hasattr(stage, "runtime_config"):
+        parallel = stage.parallel_config
+        for kind, field_name in _ENGINE_FIELD_BY_KIND.items():
+            if kind in declared:
+                existing = getattr(parallel, field_name, None)
+                value = getattr(cfg, field_name)
+                if existing not in (None, 1, value):
+                    _fail(
+                        f"role {role!r}: strategy derives {field_name}={value} "
+                        f"but structured config already set {existing}"
+                    )
+                setattr(parallel, field_name, value)
+        if "ep" in declared and cfg.enable_expert_parallel:
+            setattr(parallel, "enable_expert_parallel", True)
+        if "stage_replica" in declared:
+            existing = stage.runtime_config.num_replicas
+            if existing not in (None, 1, cfg.stage_replica_size):
+                _fail(
+                    f"role {role!r}: strategy derives "
+                    f"num_replicas={cfg.stage_replica_size} but structured config already set {existing}"
+                )
+            stage.runtime_config.num_replicas = cfg.stage_replica_size
+        check_device_layout(
+            stage.runtime_config.devices,
+            tensor_parallel_size=cfg.tensor_parallel_size,
+            data_parallel_size=cfg.data_parallel_size,
+            pipeline_parallel_size=cfg.pipeline_parallel_size,
+            num_replicas=int(stage.runtime_config.num_replicas or 1),
+            role=role,
+        )
+        return
+
     engine_args = stage.yaml_engine_args
     runtime = stage.yaml_runtime
-
-    declared = set(cfg.l1_owners.keys())
     for kind, field_name in _ENGINE_FIELD_BY_KIND.items():
         if kind in declared:
             _set_explicit(engine_args, field_name, getattr(cfg, field_name), role=role)
@@ -209,7 +240,6 @@ def _apply_to_stage(stage: Any, cfg: OmniParallelConfig, *, role: RoleKey) -> No
         _set_explicit(engine_args, "enable_expert_parallel", True, role=role)
     if "stage_replica" in declared:
         _set_num_replicas(runtime, cfg.stage_replica_size, role=role)
-
     _check_devices(runtime, cfg, role=role)
 
 
diff --git a/vllm_omni/config/config_factory.py b/vllm_omni/config/config_factory.py
index 90108e7df9a..94decce9a73 100644
--- a/vllm_omni/config/config_factory.py
+++ b/vllm_omni/config/config_factory.py
@@ -25,6 +25,9 @@
     DeployConfig,
     PipelineConfig,
     StageConfig,
+    StageDeployConfig,
+    StageExecutionType,
+    StagePipelineConfig,
     StageType,
     build_stage_runtime_overrides,
     load_deploy_config,
@@ -373,6 +376,7 @@ def create_from_model(
         trust_remote_code: bool | None,
         cli_overrides: dict[str, Any],
         deploy_config_path: str | None,
+        strategy_specs: Mapping[Any, Any] | None = None,
     ) -> VllmOmniConfig | None:
         """Build the structured Omni config for a model/deploy pair."""
         user_deploy_config = cls._load_user_deploy_config(deploy_config_path)
@@ -387,6 +391,20 @@ def create_from_model(
         if pipeline_cfg is None:
             return None
 
+        # Keep the typed representation's topology in lockstep with the
+        # compatibility launch representation. The aligner is a real extra
+        # stage, not an engine-only setting, so it must be injected before
+        # either representation is built.
+        if user_deploy_config is None:
+            if pipeline_cfg.default_deploy_config_name is not None:
+                default_deploy_path = _DEPLOY_DIR / pipeline_cfg.default_deploy_config_name
+                user_deploy_config = load_deploy_config(default_deploy_path)
+                deploy_config_path = str(default_deploy_path)
+            else:
+                user_deploy_config = DeployConfig()
+        from vllm_omni.utils.forced_aligner import inject_forced_aligner_stage
+
+        pipeline_cfg, user_deploy_config = inject_forced_aligner_stage(pipeline_cfg, user_deploy_config, cli_overrides)
         registry_cli_overrides = with_trust_remote_code_override(
             {**cli_overrides, "model": model},
             trust_remote_code,
@@ -396,6 +414,7 @@ def create_from_model(
             user_deploy_config=user_deploy_config,
             deploy_config_path=deploy_config_path,
             cli_overrides=registry_cli_overrides,
+            strategy_specs=strategy_specs,
         )
 
     @classmethod
@@ -621,13 +640,11 @@ def _eff_degree(field_name: str, source: dict[str, Any]) -> int:
             )
 
     @classmethod
-    def create_default_diffusion(cls, kwargs: dict[str, Any]) -> list[dict[str, Any]]:
-        """Build the temporary runtime ABI for a generic diffusion stage.
-
-        The terminal diffusion config owns engine defaults and normalization;
-        this compatibility builder only adds Omni stage topology, request
-        defaults, and device placement.
-        """
+    def _normalize_default_diffusion(
+        cls,
+        kwargs: dict[str, Any],
+    ) -> tuple[dict[str, Any], DiffusionParallelConfig, dict[str, Any], str]:
+        """Normalize inputs shared by typed and compatibility diffusion builders."""
         raw_sampling_params = kwargs.get("default_sampling_params")
         if isinstance(raw_sampling_params, str):
             try:
@@ -643,8 +660,6 @@ def create_default_diffusion(cls, kwargs: dict[str, Any]) -> list[dict[str, Any]
         if kwargs.get("num_gpus") is not None:
             parallel_config.resolve_data_parallel_size(int(kwargs["num_gpus"]))
         engine_args = OmniDiffusionConfig.normalize_init_kwargs(kwargs)
-        engine_args["parallel_config"] = asdict(parallel_config)
-        engine_args["model_stage"] = "diffusion"
 
         extras = dict(engine_args.get("extras") or {})
         for key, default in (
@@ -665,6 +680,21 @@ def create_default_diffusion(cls, kwargs: dict[str, Any]) -> list[dict[str, Any]
             final_output_type,
             model_class_name,
         )
+        return engine_args, parallel_config, default_sampling_params, final_output_type
+
+    @classmethod
+    def create_default_diffusion(cls, kwargs: dict[str, Any]) -> list[dict[str, Any]]:
+        """Build the temporary runtime ABI for a generic diffusion stage.
+
+        The terminal diffusion config owns engine defaults and normalization;
+        this compatibility builder only adds Omni stage topology, request
+        defaults, and device placement.
+        """
+        engine_args, parallel_config, default_sampling_params, final_output_type = cls._normalize_default_diffusion(
+            kwargs
+        )
+        engine_args["parallel_config"] = asdict(parallel_config)
+        engine_args["model_stage"] = "diffusion"
 
         return [
             {
@@ -681,6 +711,50 @@ def create_default_diffusion(cls, kwargs: dict[str, Any]) -> list[dict[str, Any]
             }
         ]
 
+    @classmethod
+    def create_typed_default_diffusion(
+        cls,
+        model: str,
+        kwargs: dict[str, Any],
+    ) -> VllmOmniConfig:
+        """Build generic diffusion directly into the structured runtime config."""
+        engine_overrides, parallel_config, default_sampling_params, final_output_type = (
+            cls._normalize_default_diffusion(kwargs)
+        )
+        engine_overrides.update(asdict(parallel_config))
+        model_class_name = engine_overrides.get("model_class_name")
+        pipeline = PipelineConfig(
+            model_type="generic_diffusion",
+            model_arch=str(model_class_name or ""),
+            stages=(
+                StagePipelineConfig(
+                    stage_id=0,
+                    model_stage="diffusion",
+                    execution_type=StageExecutionType.DIFFUSION,
+                    final_output=True,
+                    final_output_type=final_output_type,
+                ),
+            ),
+        )
+
+        # These values have already been normalized for this diffusion stage.
+        # Scope them explicitly so diffusion-only fields such as engine_backend
+        # and extras are not filtered by the global LLM CLI argument surface.
+        stage_overrides = {
+            f"stage_0_{key}": value for key, value in engine_overrides.items() if key not in {"model", "stage_id"}
+        }
+        stage_overrides["stage_0_devices"] = (
+            kwargs.get("stage_0_devices")
+            or kwargs.get("devices")
+            or ",".join(str(i) for i in range(parallel_config.world_size))
+        )
+        # Caller defaults belong to deployment, not immutable pipeline constraints:
+        # explicit request sampling parameters must still be able to override them.
+        deploy = DeployConfig(stages=[StageDeployConfig(stage_id=0, default_sampling_params=default_sampling_params)])
+        return VllmOmniConfig.from_pipeline_config(
+            pipeline, user_deploy_config=deploy, cli_overrides={"model": model, **stage_overrides}
+        )
+
     @classmethod
     def _merge_cli_overrides(
         cls,
diff --git a/vllm_omni/config/omni_config.py b/vllm_omni/config/omni_config.py
index c13935489a5..1407615ab21 100644
--- a/vllm_omni/config/omni_config.py
+++ b/vllm_omni/config/omni_config.py
@@ -29,7 +29,9 @@
 from vllm.config import SchedulerConfig as VllmSchedulerConfig
 from vllm.config.utils import config
 from vllm.engine.arg_utils import EngineArgs as VllmEngineArgs
+from vllm.logger import init_logger
 from vllm.model_executor.layers.quantization.base_config import QuantizationConfig
+from vllm.pooling_params import PoolingParams
 
 from vllm_omni.config.stage_config import (
     _DEPLOY_DIR,
@@ -42,11 +44,13 @@
     StagePipelineConfig,
     StageType,
     _apply_platform_overrides,
+    _get_recursively_merged_dict,
     _resolve_scheduler,
     _scheduler_path,
     _select_processor_funcs,
     build_stage_runtime_overrides,
     load_deploy_config,
+    merge_pipeline_deploy,
     merge_sampling_constraints,
     normalize_pipeline_cli_overrides,
     reconcile_diffusion_attention_overrides,
@@ -55,6 +59,8 @@
 )
 from vllm_omni.diffusion.diffusion_kv.config import DiffusionKVCacheMode
 
+logger = init_logger(__name__)
+
 _EXECUTION_TYPE_TO_STAGE_WORKER: dict[StageExecutionType, tuple[StageType, str | None]] = {
     StageExecutionType.LLM_AR: (StageType.LLM, "ar"),
     StageExecutionType.LLM_GENERATION: (StageType.LLM, "generation"),
@@ -186,6 +192,11 @@ class _ModelEngineOverrides(TypedDict, total=False):
     enable_prompt_embeds: bool
 
 
+class _PoolingEngineOverrides(TypedDict, total=False):
+    runner: str
+    pooling_output_decoder: str
+
+
 class _LoadEngineOverrides(TypedDict, total=False):
     tokenizer: str
     download_dir: str
@@ -261,6 +272,7 @@ class _StageEngineValues:
     quantization: _QuantizationEngineOverrides
     model: _ModelEngineOverrides
     load: _LoadEngineOverrides
+    pooling: _PoolingEngineOverrides
     cache: _CacheEngineOverrides
     scheduler: _SchedulerEngineOverrides
     connector: _ConnectorEngineOverrides
@@ -476,6 +488,15 @@ class OmniStageModelConfig(_TrackExplicitConfigFields):
     enable_prompt_embeds: bool | None = None
 
 
+@config(config=ConfigDict(arbitrary_types_allowed=True))
+class OmniStagePoolingConfig:
+    """Typed inputs owned by vLLM pooling stages."""
+
+    runner: str | None = None
+    pooling_output_decoder: str | None = None
+    default_pooling_params: PoolingParams | None = None
+
+
 @_enforce_keyword_only_init
 @config(kw_only=True)
 class OmniStageLoadConfig(_TrackExplicitConfigFields, VllmLoadConfig):
@@ -833,12 +854,12 @@ def from_kwargs(cls, **kwargs: Any) -> _DiffusionConfigProjection:
         from vllm_omni.diffusion.data import normalize_omni_diffusion_kwargs
         from vllm_omni.diffusion.offloader.config import parse_diffusion_offload_config
 
-        normalized_kwargs = normalize_omni_diffusion_kwargs(kwargs)
+        config_kwargs = normalize_omni_diffusion_kwargs(kwargs)
         # Validate before stage construction while retaining the raw mapping
         # needed by dataclass/config serialization across process boundaries.
-        parse_diffusion_offload_config(normalized_kwargs.get("diffusion_offload_config"))
+        parse_diffusion_offload_config(config_kwargs.get("diffusion_offload_config"))
         valid_fields = {f.name for f in fields(cast(Any, cls))}
-        return cls(**{k: v for k, v in normalized_kwargs.items() if k in valid_fields})
+        return cls(**{k: v for k, v in config_kwargs.items() if k in valid_fields})
 
     def __post_init__(self) -> None:
         # Keep diffusion imports lazy so importing vllm_omni.config does not
@@ -1145,6 +1166,7 @@ def _upstream_engine_field_map(
 _LOAD_ENGINE_FIELDS = frozenset(_LoadEngineOverrides.__annotations__)
 _CACHE_ENGINE_FIELDS = frozenset(_CacheEngineOverrides.__annotations__)
 _SCHEDULER_ENGINE_FIELDS = frozenset(_SchedulerEngineOverrides.__annotations__)
+_POOLING_ENGINE_FIELDS = frozenset(_PoolingEngineOverrides.__annotations__)
 _CONNECTOR_ENGINE_FIELDS = frozenset(_ConnectorEngineOverrides.__annotations__)
 _RUNTIME_ENGINE_FIELDS = frozenset(_RuntimeEngineOverrides.__annotations__)
 _DIRECT_VLLM_CONFIG_ENGINE_FIELDS = frozenset({"compilation_config", "profiler_config"})
@@ -1175,6 +1197,7 @@ def _upstream_engine_field_map(
     | _LLM_CACHE_ENGINE_FIELDS
     | _LLM_SCHEDULER_ENGINE_FIELDS
     | _LLM_PARALLEL_CONFIG_ENGINE_FIELDS
+    | _POOLING_ENGINE_FIELDS
     | {"parallel_config"}
 )
 _DIFFUSION_OWNED_STAGE_ENGINE_FIELDS = (
@@ -1308,7 +1331,12 @@ def _stage_engine_values(
         if topology.execution_type == StageExecutionType.DIFFUSION:
             # Mirror StageConfig.to_omegaconf so both projections resolve alike.
             reconcile_diffusion_attention_overrides(engine, stage_cli_overrides)
-        engine.update(_copy_value(stage_cli_overrides))
+        for key, value in stage_cli_overrides.items():
+            existing = engine.get(key)
+            if key != "omni_kv_config" and isinstance(existing, dict) and isinstance(value, Mapping):
+                engine[key] = _get_recursively_merged_dict(existing, dict(value))
+            else:
+                engine[key] = _copy_value(value)
     _validate_stage_engine_override_ownership(
         topology.stage_id,
         topology.execution_type,
@@ -1334,6 +1362,10 @@ def _stage_engine_values(
         ),
         model=cast(_ModelEngineOverrides, _select_engine_overrides(engine, _MODEL_ENGINE_FIELDS)),
         load=cast(_LoadEngineOverrides, _select_engine_overrides(engine, load_engine_fields)),
+        pooling=cast(
+            _PoolingEngineOverrides,
+            _select_engine_overrides(engine, _POOLING_ENGINE_FIELDS),
+        ),
         cache=cast(_CacheEngineOverrides, _select_engine_overrides(engine, cache_engine_fields)),
         scheduler=cast(
             _SchedulerEngineOverrides,
@@ -1406,6 +1438,7 @@ class BaseVllmOmniStageConfig:
     cache_config: OmniStageCacheConfig = field(default_factory=OmniStageCacheConfig)
     scheduler_config: OmniStageSchedulerConfig = field(default_factory=OmniStageSchedulerConfig)
     connector_config: OmniStageConnectorConfig = field(default_factory=OmniStageConnectorConfig)
+    pooling_config: OmniStagePoolingConfig = field(default_factory=OmniStagePoolingConfig)
     runtime_config: OmniStageRuntimeConfig = field(default_factory=OmniStageRuntimeConfig)
     parallel_config: OmniStageParallelConfig = field(default_factory=OmniStageParallelConfig)
     compilation_config: VllmCompilationConfig | None = None
@@ -1490,6 +1523,10 @@ def prompt_expand_func(self) -> str | None:
     def prompt_transform_func(self) -> str | None:
         return self.stage_pipeline_config.prompt_transform_func
 
+    @property
+    def sampling_constraints(self) -> dict[str, Any]:
+        return dict(self.stage_pipeline_config.sampling_constraints)
+
     @property
     def cfg_kv_collect_func(self) -> str | None:
         return self.stage_pipeline_config.cfg_kv_collect_func
@@ -1543,6 +1580,7 @@ def _build_common_stage_config_kwargs(
                 model=model,
             ),
             "load_config": _build_load_config(topology, engine.load),
+            "pooling_config": _build_pooling_config(stage_deploy, engine.pooling),
             "cache_config": _build_cache_config(
                 deploy,
                 engine.cache,
@@ -1756,6 +1794,20 @@ def _build_model_config(
     )
 
 
+def _build_pooling_config(
+    stage_deploy: StageDeployConfig | None,
+    engine: _PoolingEngineOverrides,
+) -> OmniStagePoolingConfig:
+    default_pooling_params = None
+    if stage_deploy is not None and stage_deploy.default_pooling_params:
+        default_pooling_params = PoolingParams(**dict(stage_deploy.default_pooling_params))
+    return cast(Any, OmniStagePoolingConfig)(
+        runner=_copy_value(engine.get("runner")),
+        pooling_output_decoder=_copy_value(engine.get("pooling_output_decoder")),
+        default_pooling_params=default_pooling_params,
+    )
+
+
 def _build_load_config(
     topology: StagePipelineConfig,
     engine: _LoadEngineOverrides,
@@ -1934,6 +1986,10 @@ class VllmOmniConfig:
     pipeline_config: PipelineConfig
     stage_configs: tuple[StageConfigType, ...]
     orchestrator_config: VllmOmniOrchestratorConfig = field(default_factory=VllmOmniOrchestratorConfig)
+    # Keep strategy provenance separate from the effective orchestrator value:
+    # an explicit CLI policy may be present even when the strategy declares no
+    # stage-replica axis.
+    strategy_omni_lb_policy: str | None = None
 
     def stage_by_id(self, stage_id: int) -> StageConfigType:
         for stage in self.stage_configs:
@@ -1949,6 +2005,7 @@ def from_pipeline_config(
         user_deploy_config: DeployConfig | None = None,
         deploy_config_path: str | None = None,
         cli_overrides: dict[str, Any] | None = None,
+        strategy_specs: Mapping[Any, Any] | None = None,
     ) -> VllmOmniConfig:
         """Create a structured config from a resolved pipeline and deploy YAML."""
         if cli_overrides is None:
@@ -1973,6 +2030,62 @@ def from_pipeline_config(
             deploy.async_chunk = False
         _validate_async_chunk_support(pipeline_cfg, deploy)
         validate_stage_async_chunk_edges(pipeline_cfg, deploy)
+
+        strategy_result = None
+        if strategy_specs:
+            from vllm_omni.config.composable_parallel import apply_strategy_specs
+
+            strategy_stages = merge_pipeline_deploy(pipeline_cfg, copy.deepcopy(deploy), {})
+            strategy_result = apply_strategy_specs(strategy_stages, strategy_specs)
+            strategy_overrides: dict[str, Any] = {}
+            axis_fields = {
+                "tp": "tensor_parallel_size",
+                "dp": "data_parallel_size",
+                "pp": "pipeline_parallel_size",
+            }
+            for stage_id, parallel in strategy_result.per_stage_config.items():
+                declared = set(parallel.l1_owners)
+                explicit = build_stage_runtime_overrides(stage_id, cli_overrides)
+                for axis, field_name in axis_fields.items():
+                    if axis not in declared:
+                        continue
+                    derived = getattr(parallel, field_name)
+                    value = explicit.get(field_name)
+                    if value is None:
+                        value = derived
+                    elif value != derived:
+                        logger.warning(
+                            "[composable_parallel] stage %s: CLI %s=%s overrides the "
+                            "strategy-derived %s=%s. The CLI value wins; remove one to avoid ambiguity.",
+                            stage_id,
+                            field_name,
+                            value,
+                            field_name,
+                            derived,
+                        )
+                    strategy_overrides[f"stage_{stage_id}_{field_name}"] = value
+                if "ep" in declared and parallel.enable_expert_parallel:
+                    strategy_overrides[f"stage_{stage_id}_enable_expert_parallel"] = bool(
+                        explicit.get("enable_expert_parallel", True)
+                    )
+                if "stage_replica" in declared:
+                    derived = parallel.stage_replica_size
+                    value = explicit.get("num_replicas")
+                    if value is None:
+                        value = derived
+                    elif value != derived:
+                        logger.warning(
+                            "[composable_parallel] stage %s: CLI num_replicas=%s overrides the "
+                            "strategy-derived num_replicas=%s. The CLI value wins; remove one to avoid ambiguity.",
+                            stage_id,
+                            value,
+                            derived,
+                        )
+                    strategy_overrides[f"stage_{stage_id}_num_replicas"] = value
+            cli_overrides = {**strategy_overrides, **cli_overrides}
+            if strategy_result.omni_lb_policy is not None and cli_overrides.get("omni_lb_policy") is None:
+                cli_overrides["omni_lb_policy"] = strategy_result.omni_lb_policy
+
         deploy_by_id = {stage.stage_id: stage for stage in deploy.stages}
         model = cli_overrides.get("model")
 
@@ -1995,6 +2108,20 @@ def from_pipeline_config(
             )
             for topology in pipeline_cfg.stages
         )
+        if strategy_result is not None:
+            from vllm_omni.config.composable_parallel import check_device_layout
+
+            by_id = {stage.stage_id: stage for stage in stage_configs}
+            for stage_id in strategy_result.per_stage_config:
+                stage = by_id[stage_id]
+                check_device_layout(
+                    stage.runtime_config.devices,
+                    tensor_parallel_size=stage.parallel_config.tensor_parallel_size,
+                    data_parallel_size=stage.parallel_config.data_parallel_size,
+                    pipeline_parallel_size=stage.parallel_config.pipeline_parallel_size,
+                    num_replicas=stage.runtime_config.num_replicas,
+                    role=stage.model_stage,
+                )
 
         orchestrator_config = cast(Any, VllmOmniOrchestratorConfig)(
             deploy_config_path=loaded_deploy_config_path,
@@ -2004,6 +2131,7 @@ def from_pipeline_config(
             pipeline_config=pipeline_cfg,
             stage_configs=stage_configs,
             orchestrator_config=orchestrator_config,
+            strategy_omni_lb_policy=(strategy_result.omni_lb_policy if strategy_result is not None else None),
         )
 
 
diff --git a/vllm_omni/config/resolver.py b/vllm_omni/config/resolver.py
index 4f5ee8a6c61..0db43676881 100644
--- a/vllm_omni/config/resolver.py
+++ b/vllm_omni/config/resolver.py
@@ -14,7 +14,6 @@
 from vllm_omni.config.endpoint_policy import EndpointRestriction
 from vllm_omni.config.omni_config import VllmOmniConfig
 from vllm_omni.config.stage_config import PipelineConfig
-from vllm_omni.config.yaml_util import create_config
 from vllm_omni.diffusion.data import resolve_model_class_name
 from vllm_omni.diffusion.registry import DiffusionModelRegistry
 from vllm_omni.diffusion.utils.hf_utils import is_diffusion_model
@@ -24,19 +23,10 @@
 
 @dataclass(frozen=True)
 class OmniConfigResolution:
-    """Migration envelope returned by the production config resolver.
-
-    ``stage_configs`` intentionally carries the current OmegaConf-compatible
-    runtime ABI only until stage startup consumes ``VllmOmniConfig`` directly.
-    ``pipeline_config`` is the effective topology after runtime stage injection,
-    so both fields always describe the same set of stages.
-    It is not a stable authoring or extension API; new production callers
-    should resolve through :func:`resolve_omni_config` and must not construct or
-    merge this compatibility shape themselves.
-    """
+    """Canonical typed result returned by the production config resolver."""
 
     config_path: str | None
-    stage_configs: tuple[Any, ...]  # Temporary StageConfig/OmegaConf bridge.
+    stage_configs: tuple[Any, ...]
     pipeline_config: PipelineConfig | None = None
     omni_lb_policy: str | None = None
 
@@ -176,27 +166,13 @@ def _load_strategy_specs(strategy_config_path: str | None) -> Mapping[Any, Any]
 
 def _build_registered_resolution(
     structured_config: VllmOmniConfig,
-    *,
-    cli_overrides: dict[str, Any],
-    strategy_config_path: str | None,
 ) -> OmniConfigResolution:
-    """Build the temporary runtime view for an already-resolved pipeline."""
-    # Runtime consumers have not yet moved to typed per-stage configs. Use the
-    # factory-owned compatibility bridge instead of reimplementing legacy YAML
-    # discovery and merging in this resolver.
-    effective_deploy_path = structured_config.orchestrator_config.deploy_config_path
-    legacy_resolution = StageConfigFactory._resolve_legacy_from_registry(
-        structured_config.pipeline_config,
-        cli_overrides,
-        effective_deploy_path,
-        strategy_specs=_load_strategy_specs(strategy_config_path),
-    )
-
+    """Return the canonical structured runtime view for a resolved pipeline."""
     return OmniConfigResolution(
-        config_path=effective_deploy_path,
-        stage_configs=tuple(stage.to_omegaconf() for stage in legacy_resolution.stage_configs),
-        pipeline_config=legacy_resolution.pipeline_config,
-        omni_lb_policy=legacy_resolution.omni_lb_policy,
+        config_path=structured_config.orchestrator_config.deploy_config_path,
+        stage_configs=tuple(structured_config.stage_configs),
+        pipeline_config=structured_config.pipeline_config,
+        omni_lb_policy=getattr(structured_config, "strategy_omni_lb_policy", None),
     )
 
 
@@ -231,18 +207,16 @@ def resolve_omni_config(
     registry_overrides = dict(normalized_overrides)
     _flatten_stage_overrides(registry_overrides, stage_overrides)
 
+    strategy_specs = _load_strategy_specs(strategy_config_path)
     structured_config = StageConfigFactory.create_from_model(
         model,
         trust_remote_code=trust_remote_code,
         cli_overrides=registry_overrides,
         deploy_config_path=deploy_config_path,
+        strategy_specs=strategy_specs,
     )
     if structured_config is not None:
-        return _build_registered_resolution(
-            structured_config,
-            cli_overrides=registry_overrides,
-            strategy_config_path=strategy_config_path,
-        )
+        return _build_registered_resolution(structured_config)
 
     _apply_generic_stage_overrides(normalized_overrides, stage_overrides)
     supported, model_class_name = _resolve_generic_diffusion_model_class(model, normalized_overrides)
@@ -252,11 +226,12 @@ def resolve_omni_config(
         )
     if model_class_name is not None:
         normalized_overrides.setdefault("model_class_name", model_class_name)
-    default_stages = StageConfigFactory.create_default_diffusion(normalized_overrides)
+    default_config = StageConfigFactory.create_typed_default_diffusion(model, normalized_overrides)
 
     return OmniConfigResolution(
         config_path=deploy_config_path,
-        stage_configs=tuple(create_config(_convert_dataclasses_to_dict(default_stages))),
+        stage_configs=tuple(default_config.stage_configs),
+        pipeline_config=default_config.pipeline_config,
     )
 
 
diff --git a/vllm_omni/engine/omni_engine_base.py b/vllm_omni/engine/omni_engine_base.py
index 85310e9ddd5..d615ebca003 100644
--- a/vllm_omni/engine/omni_engine_base.py
+++ b/vllm_omni/engine/omni_engine_base.py
@@ -272,7 +272,14 @@ def __init__(
 
         self.num_stages = len(self.stage_configs)
         self.async_chunk = any(
-            bool(getattr(getattr(stage, "engine_args", None), "async_chunk", False)) for stage in self.stage_configs
+            bool(
+                getattr(
+                    getattr(stage, "connector_config", None),
+                    "async_chunk",
+                    getattr(getattr(stage, "engine_args", None), "async_chunk", False),
+                )
+            )
+            for stage in self.stage_configs
         )
         self.stage_pools: list[StagePool] = []
         self.stage_clients: list[StageClient] = []  # logical-stage view for external readers
diff --git a/vllm_omni/engine/stage_admission.py b/vllm_omni/engine/stage_admission.py
index 469787bca93..bd57f805da8 100644
--- a/vllm_omni/engine/stage_admission.py
+++ b/vllm_omni/engine/stage_admission.py
@@ -287,8 +287,13 @@ def check_admission(
 
 
 def _diffusion_utilization(replica: Any) -> float | None:
-    """Best-effort gpu_memory_utilization for a diffusion replica from raw args."""
+    """Resolve a diffusion replica's memory budget from typed or legacy config."""
     stage_cfg = getattr(replica, "stage_cfg", None)
+    cache_config = getattr(stage_cfg, "cache_config", None)
+    util = getattr(cache_config, "gpu_memory_utilization", None)
+    if util is not None:
+        return float(util)
+
     engine_args = getattr(stage_cfg, "engine_args", None)
     if isinstance(engine_args, dict):
         util = engine_args.get("gpu_memory_utilization")
diff --git a/vllm_omni/engine/stage_engine_startup.py b/vllm_omni/engine/stage_engine_startup.py
index 71ba17c7c85..612c7481fcd 100644
--- a/vllm_omni/engine/stage_engine_startup.py
+++ b/vllm_omni/engine/stage_engine_startup.py
@@ -17,6 +17,7 @@
 from typing import Any
 
 import msgspec
+import torch
 import zmq
 from omegaconf import OmegaConf
 from vllm.config import VllmConfig
@@ -33,6 +34,7 @@
 )
 from vllm.v1.executor import Executor
 
+from vllm_omni.config.omni_config import BaseVllmOmniStageConfig
 from vllm_omni.distributed.omni_connectors.utils import initialization
 from vllm_omni.engine import stage_init_utils
 from vllm_omni.engine.stage_init_utils import (
@@ -67,11 +69,13 @@ def _serialize_stage_config(stage_config: Any) -> Any:
     """Convert a stage config to msgpack-friendly builtins."""
     if stage_config is None or isinstance(stage_config, (str, bytes, int, float, bool)):
         return stage_config
+    if isinstance(stage_config, torch.dtype):
+        return str(stage_config).removeprefix("torch.")
 
     if OmegaConf.is_config(stage_config):
         return _serialize_stage_config(OmegaConf.to_container(stage_config, resolve=True))
 
-    if dataclasses.is_dataclass(stage_config):
+    if dataclasses.is_dataclass(stage_config) and not isinstance(stage_config, type):
         return _serialize_stage_config(dataclasses.asdict(stage_config))
 
     if isinstance(stage_config, dict):
@@ -1403,7 +1407,7 @@ def get_headless_replica_devices(
     omni_dp_size_local: int,
 ) -> list[str | None]:
     """Return per-replica device slices for a headless stage."""
-    runtime_cfg = getattr(stage_cfg, "runtime", None)
+    runtime_cfg = getattr(stage_cfg, "runtime_config", getattr(stage_cfg, "runtime", None))
     devices_str: str | None = None
     if runtime_cfg is not None:
         devices_str = (
@@ -1509,10 +1513,11 @@ def launch_headless_diffusion_replicas(
         stage_id,
     )
 
-    # Headless diffusion startup and its downstream helpers still consume the
-    # legacy StageConfig shape; switch this with the coordinated RFC #4021
-    # stage-init cutover.
-    metadata = stage_init_utils.extract_legacy_stage_metadata(stage_cfg)
+    metadata = (
+        stage_init_utils.extract_stage_metadata_from_omni_stage_config(stage_cfg)
+        if isinstance(stage_cfg, BaseVllmOmniStageConfig)
+        else stage_init_utils.extract_legacy_stage_metadata(stage_cfg)
+    )
     if omni_conn_cfg:
         inject_omni_kv_config(stage_cfg, omni_conn_cfg, omni_from, omni_to)
     # Headless single-stage launch must still infer cross-stage TP topology
diff --git a/vllm_omni/engine/stage_init_utils.py b/vllm_omni/engine/stage_init_utils.py
index 9668dfc99c8..06f916394b1 100644
--- a/vllm_omni/engine/stage_init_utils.py
+++ b/vllm_omni/engine/stage_init_utils.py
@@ -402,6 +402,11 @@ def _tp_size_for_stage(stage_configs: Sequence[Any], stage_id: Any) -> int | Non
     for stage_cfg in stage_configs:
         if str(getattr(stage_cfg, "stage_id", None)) not in id_strs:
             continue
+        if isinstance(stage_cfg, BaseVllmOmniStageConfig):
+            try:
+                return max(1, int(stage_cfg.parallel_config.tensor_parallel_size))
+            except (TypeError, ValueError):
+                return 1
         engine_args = getattr(stage_cfg, "engine_args", None)
         if engine_args is None:
             return 1
@@ -489,11 +494,15 @@ def inject_kv_stage_info(stage_cfg: Any, stage_id: int, stage_configs: Sequence[
     rank mappings automatically.
     """
     try:
-        engine_args = stage_cfg.engine_args
-        if hasattr(engine_args, "get"):
-            omni_kv = engine_args.get("omni_kv_config", None)
+        connector_config = getattr(stage_cfg, "connector_config", None)
+        if connector_config is not None:
+            omni_kv = connector_config.omni_kv_config
         else:
-            omni_kv = getattr(engine_args, "omni_kv_config", None)
+            engine_args = stage_cfg.engine_args
+            if hasattr(engine_args, "get"):
+                omni_kv = engine_args.get("omni_kv_config", None)
+            else:
+                omni_kv = getattr(engine_args, "omni_kv_config", None)
 
         if omni_kv is None:
             return
@@ -504,7 +513,11 @@ def inject_kv_stage_info(stage_cfg: Any, stage_id: int, stage_configs: Sequence[
             if "stage_id" not in omni_kv:
                 omni_kv["stage_id"] = stage_id
 
-        engine_input_source = getattr(stage_cfg, "engine_input_source", None)
+        engine_input_source = (
+            getattr(stage_cfg, "input_sources", None)
+            if connector_config is not None
+            else getattr(stage_cfg, "engine_input_source", None)
+        )
         if engine_input_source is not None:
             if hasattr(omni_kv, "setdefault"):
                 omni_kv.setdefault("engine_input_source", list(engine_input_source))
@@ -703,17 +716,16 @@ def _resolve_omni_metadata_hook(path: str | None) -> Callable | None:
 def extract_stage_metadata_from_omni_stage_config(
     stage_config: BaseVllmOmniStageConfig,
 ) -> StageMetadata:
-    """Project one typed stage config into metadata for a future cutover.
-
-    This projection is not used by production startup yet. Current replica
-    layout, engine-argument, remote-diffusion, and platform setup paths still
-    require the legacy StageConfig/OmegaConf shape.
-    """
+    """Project one typed stage config into production runtime metadata."""
     stage_type: Literal["llm", "diffusion"] = "diffusion" if stage_config.stage_type == StageType.DIFFUSION else "llm"
-    sampling_params_cls = SamplingParams if stage_type == "llm" else OmniDiffusionSamplingParams
-    sampling_params: OmniSamplingParams = sampling_params_cls(
-        **(stage_config.model_config.default_sampling_params or {})
-    )
+    pooling_config = stage_config.pooling_config
+    if stage_type == "llm" and (pooling_config.runner or "").lower() == "pooling":
+        sampling_params: OmniSamplingParams | PoolingParams = (
+            copy.deepcopy(pooling_config.default_pooling_params) or PoolingParams()
+        )
+    else:
+        sampling_params_cls = SamplingParams if stage_type == "llm" else OmniDiffusionSamplingParams
+        sampling_params = sampling_params_cls(**(stage_config.model_config.default_sampling_params or {}))
     custom_process_input_func = _resolve_omni_metadata_hook(stage_config.custom_process_input_func)
 
     if stage_type == "diffusion":
@@ -878,7 +890,9 @@ def _get_local_llm_parallel_sizes(
     unset.
     """
     if engine_args is None:
-        engine_args = getattr(stage_cfg, "engine_args", {})
+        engine_args = getattr(stage_cfg, "parallel_config", None)
+        if engine_args is None:
+            engine_args = getattr(stage_cfg, "engine_args", {})
     tp_size = int(_get_attr_or_item(engine_args, "tensor_parallel_size", 1) or 1)
     pp_size = int(_get_attr_or_item(engine_args, "pipeline_parallel_size", 1) or 1)
     local_dp_size = _get_attr_or_item(engine_args, "data_parallel_size_local", None)
@@ -889,9 +903,12 @@ def _get_local_llm_parallel_sizes(
 
 def get_stage_devices_per_replica(stage_cfg: Any, engine_args: Any | None = None) -> int:
     """Return the number of devices consumed by one replica of *stage_cfg*."""
-    if engine_args is None:
-        engine_args = getattr(stage_cfg, "engine_args", {})
     if getattr(stage_cfg, "stage_type", "llm") == "diffusion":
+        typed_parallel_config = getattr(stage_cfg, "parallel_config", None)
+        if typed_parallel_config is not None:
+            return max(1, int(typed_parallel_config.world_size))
+        if engine_args is None:
+            engine_args = getattr(stage_cfg, "engine_args", {})
         parallel_config = _get_attr_or_item(engine_args, "parallel_config")
         if parallel_config is None:
             return 1
@@ -933,7 +950,7 @@ def compute_replica_layout(
     """
     replicas_per_stage: list[int] = []
     for stage_cfg in stage_configs:
-        runtime_cfg = getattr(stage_cfg, "runtime", {})
+        runtime_cfg = getattr(stage_cfg, "runtime_config", getattr(stage_cfg, "runtime", {}))
         num_replicas = int(
             runtime_cfg.get("num_replicas", 1)
             if hasattr(runtime_cfg, "get")
@@ -948,7 +965,7 @@ def compute_replica_layout(
         num_replicas = replicas_per_stage[stage_id]
         if num_replicas <= 1:
             continue
-        runtime_cfg = getattr(stage_cfg, "runtime", {})
+        runtime_cfg = getattr(stage_cfg, "runtime_config", getattr(stage_cfg, "runtime", {}))
         devices_str = (
             runtime_cfg.get("devices") if hasattr(runtime_cfg, "get") else getattr(runtime_cfg, "devices", None)
         )
@@ -1086,15 +1103,31 @@ def _project_omni_stage_engine_args(
         diffusion_stage = cast(VllmOmniDiffusionStageConfig, stage_config)
         engine_args.update(_project_omni_config_fields(diffusion_stage.diffusion_config))
 
+    model_excluded_fields = {
+        "default_sampling_params",
+        "has_sampling_extra_args",
+    }
+    runtime_excluded_fields = {"devices", "num_replicas", "env", "num_gpus"}
+    if not is_diffusion:
+        # These values configure OmniDiffusionConfig or its worker process;
+        # OmniEngineArgs has no matching fields for LLM stages.
+        model_excluded_fields.update(
+            {
+                "disable_autocast",
+                "enable_multithread_weight_load",
+                "num_weight_load_threads",
+            }
+        )
+        runtime_excluded_fields.add("log_level")
+
     for config, excluded_fields in (
         (
             stage_config.model_config,
-            frozenset({"default_sampling_params", "has_sampling_extra_args"}),
+            frozenset(model_excluded_fields),
         ),
         (
             stage_config.runtime_config,
-            frozenset({"devices", "num_replicas", "env", "num_gpus"})
-            | (frozenset({"additional_config"}) if is_diffusion else frozenset()),
+            frozenset(runtime_excluded_fields) | (frozenset({"additional_config"}) if is_diffusion else frozenset()),
         ),
     ):
         engine_args.update(
@@ -1103,6 +1136,11 @@ def _project_omni_stage_engine_args(
                 exclude=excluded_fields,
             )
         )
+    pooling_config = stage_config.pooling_config
+    if pooling_config.runner is not None:
+        engine_args["runner"] = pooling_config.runner
+    if pooling_config.pooling_output_decoder is not None:
+        engine_args["pooling_output_decoder"] = pooling_config.pooling_output_decoder
 
     if is_diffusion:
         for config, field_map in (
@@ -1330,11 +1368,9 @@ def build_engine_args_dict(
     stage_connector_spec: dict[str, Any] | None = None,
     cli_tokenizer: str | None = None,
 ) -> dict[str, Any]:
-    """Build engine arguments through the stable production entry point.
+    """Preserve the legacy engine-argument API for compatibility callers.
 
-    Production inputs still use the legacy stage representation. Keep that
-    compatibility choice behind this function so callers do not bind directly
-    to a representation-specific implementation.
+    Typed runtime stages use ``build_engine_args_dict_from_omni_stage_config``.
     """
     return build_legacy_engine_args_dict(
         stage_config,
@@ -1350,13 +1386,7 @@ def build_engine_args_dict_from_omni_stage_config(
     stage_connector_spec: dict[str, Any] | None = None,
     cli_tokenizer: str | None = None,
 ) -> dict[str, Any]:
-    """Project one typed stage config into backend engine arguments.
-
-    This projection is prepared for the RFC #4021 stage-init cutover. Current
-    production startup reaches the legacy implementation through
-    ``build_engine_args_dict`` while strategy and startup-plan inputs still
-    use the legacy representation.
-    """
+    """Project one typed production stage config into backend engine arguments."""
     engine_args_dict = _project_omni_stage_engine_args(stage_config)
     _apply_rocm_attention_backend(engine_args_dict, stage_config.stage_type)
     return _finalize_engine_args_dict(
@@ -1391,7 +1421,7 @@ def _check_stage_device_layout(stage_config: Any, engine_args_dict: dict[str, An
     """
     from vllm_omni.config.composable_parallel import StrategyApplyError, check_device_layout
 
-    runtime = getattr(stage_config, "runtime", None)
+    runtime = getattr(stage_config, "runtime_config", getattr(stage_config, "runtime", None))
     devices = _get_attr_or_item(runtime, "devices", None) if runtime is not None else None
     if devices is None:
         # No explicit placement -> vLLM assigns devices itself; nothing to check.
@@ -1452,10 +1482,12 @@ def build_vllm_config(
         (vllm_config, executor_class)
     """
     if engine_args_dict is None:
-        engine_args_dict = build_engine_args_dict(
-            stage_config,
-            model,
-            stage_connector_spec=stage_connector_spec,
+        engine_args_dict = (
+            build_engine_args_dict_from_omni_stage_config(
+                stage_config, model, stage_connector_spec=stage_connector_spec
+            )
+            if isinstance(stage_config, BaseVllmOmniStageConfig)
+            else build_engine_args_dict(stage_config, model, stage_connector_spec=stage_connector_spec)
         )
 
     filtered_engine_args_dict = filter_dataclass_kwargs(OmniEngineArgs, engine_args_dict)
@@ -1927,7 +1959,11 @@ def build_diffusion_config(
 ) -> Any:
     """Build diffusion config for a stage."""
 
-    engine_args_dict = build_engine_args_dict(stage_cfg, model)
+    engine_args_dict = (
+        build_engine_args_dict_from_omni_stage_config(stage_cfg, model)
+        if isinstance(stage_cfg, BaseVllmOmniStageConfig)
+        else build_engine_args_dict(stage_cfg, model)
+    )
     od_config = OmniDiffusionConfig.from_kwargs(**engine_args_dict)
 
     num_devices_per_stage = od_config.parallel_config.world_size
diff --git a/vllm_omni/engine/stage_runtime.py b/vllm_omni/engine/stage_runtime.py
index 53400df5e4b..d17e3b08f8f 100644
--- a/vllm_omni/engine/stage_runtime.py
+++ b/vllm_omni/engine/stage_runtime.py
@@ -16,9 +16,9 @@
 from typing import Any, cast
 
 import janus
-from omegaconf import OmegaConf
 from vllm.logger import init_logger
 
+from vllm_omni.config.omni_config import BaseVllmOmniStageConfig
 from vllm_omni.distributed.omni_connectors.utils.initialization import (
     resolve_omni_kv_config_for_stage,
 )
@@ -49,11 +49,13 @@
     _inject_inferred_kv_tp_topology,
     acquire_device_locks,
     build_engine_args_dict,
+    build_engine_args_dict_from_omni_stage_config,
     build_llm_stage_output_processor,
     build_vllm_config,
     compute_replica_layout,
     device_overlap_group_keys,
     extract_legacy_stage_metadata,
+    extract_stage_metadata_from_omni_stage_config,
     get_stage_connector_spec,
     inject_kv_stage_info,
     inject_omni_kv_connector_config,
@@ -345,12 +347,12 @@ def _build_logical_stage_init_plans(
         """Build startup plans for every logical stage and replica."""
         stage_plans: list[LogicalStageInitPlan] = []
 
-        # RFC #4021 transition boundary: stage planning still relies on legacy
-        # StageConfig.runtime and StageConfig.engine_args for replica and engine
-        # setup. Keep metadata extraction on the legacy path until the
-        # coordinated stage-init cutover.
         for stage_idx, stage_cfg in enumerate(self._stage_configs):
-            base_metadata = extract_legacy_stage_metadata(stage_cfg)
+            base_metadata = (
+                extract_stage_metadata_from_omni_stage_config(stage_cfg)
+                if isinstance(stage_cfg, BaseVllmOmniStageConfig)
+                else extract_legacy_stage_metadata(stage_cfg)
+            )
             stage_id = int(base_metadata.stage_id)
             if stage_id != stage_idx:
                 raise ValueError(
@@ -374,14 +376,20 @@ def _build_logical_stage_init_plans(
             executor_class = None
             engine_args_dict = None
             if base_metadata.stage_type != "diffusion":
-                # The stable adapter entry point still receives the same
-                # legacy stage object as replica planning. Its implementation
-                # switches only at the coordinated RFC #4021 cutover.
-                engine_args_dict = build_engine_args_dict(
-                    stage_cfg,
-                    self._model,
-                    stage_connector_spec=stage_connector_spec,
-                    cli_tokenizer=self._tokenizer,
+                engine_args_dict = (
+                    build_engine_args_dict_from_omni_stage_config(
+                        stage_cfg,
+                        self._model,
+                        stage_connector_spec=stage_connector_spec,
+                        cli_tokenizer=self._tokenizer,
+                    )
+                    if isinstance(stage_cfg, BaseVllmOmniStageConfig)
+                    else build_engine_args_dict(
+                        stage_cfg,
+                        self._model,
+                        stage_connector_spec=stage_connector_spec,
+                        cli_tokenizer=self._tokenizer,
+                    )
                 )
                 inject_omni_kv_connector_config(
                     engine_args_dict,
@@ -401,11 +409,20 @@ def _build_logical_stage_init_plans(
                 )
 
             for replica_id in range(num_replicas):
-                replica_cfg = copy.deepcopy(stage_cfg) if replica_id > 0 else stage_cfg
+                # Keep the logical stage's device pool intact; each replica owns
+                # the same config throughout planning, metadata and launch.
+                replica_cfg = copy.deepcopy(stage_cfg) if num_replicas > 1 else stage_cfg
                 if stage_idx in replica_devices_map:
-                    replica_cfg.runtime.devices = replica_devices_map[stage_idx][replica_id]
-
-                replica_metadata = extract_legacy_stage_metadata(replica_cfg)
+                    devices = replica_devices_map[stage_idx][replica_id]
+                    runtime_cfg = getattr(replica_cfg, "runtime_config", getattr(replica_cfg, "runtime", None))
+                    if runtime_cfg is not None:
+                        runtime_cfg.devices = devices
+
+                replica_metadata = (
+                    extract_stage_metadata_from_omni_stage_config(replica_cfg)
+                    if isinstance(replica_cfg, BaseVllmOmniStageConfig)
+                    else extract_legacy_stage_metadata(replica_cfg)
+                )
                 replica_metadata.replica_id = replica_id
                 if launch_mode == "remote" and replica_metadata.stage_type != "diffusion":
                     replica_metadata.runtime_cfg = None
@@ -859,17 +876,25 @@ def _initialize_local_diffusion_replica(
                         raise RuntimeError("Omni KV connector requires source and destination stages")
                     inject_omni_kv_config(plan.stage_cfg, omni_conn_cfg, omni_from, omni_to)
                 inject_kv_stage_info(plan.stage_cfg, plan.metadata.stage_id, self._stage_configs)
-                engine_args = getattr(plan.stage_cfg, "engine_args", {})
-                inline_diffusion = (
-                    engine_args.get("inline_diffusion", False)
-                    if hasattr(engine_args, "get")
-                    else getattr(engine_args, "inline_diffusion", False)
-                )
-                custom_pipeline_args = (
-                    engine_args.get("custom_pipeline_args")
-                    if hasattr(engine_args, "get")
-                    else getattr(engine_args, "custom_pipeline_args", None)
-                )
+                if isinstance(plan.stage_cfg, BaseVllmOmniStageConfig):
+                    inline_diffusion = plan.stage_cfg.stage_pipeline_config.inline_diffusion
+                    custom_pipeline_args = getattr(
+                        getattr(plan.stage_cfg, "diffusion_config", None),
+                        "custom_pipeline_args",
+                        None,
+                    )
+                else:
+                    engine_args = getattr(plan.stage_cfg, "engine_args", {})
+                    inline_diffusion = (
+                        engine_args.get("inline_diffusion", False)
+                        if hasattr(engine_args, "get")
+                        else getattr(engine_args, "inline_diffusion", False)
+                    )
+                    custom_pipeline_args = (
+                        engine_args.get("custom_pipeline_args")
+                        if hasattr(engine_args, "get")
+                        else getattr(engine_args, "custom_pipeline_args", None)
+                    )
                 client, resources = launch_diffusion_stage_replica(
                     model=self._model,
                     stage_config=plan.stage_cfg,
@@ -1028,7 +1053,7 @@ def _validate_single_stage_mode_replica_constraints(self) -> None:
 
         for idx, stage_cfg in enumerate(self._stage_configs):
             stage_id = int(getattr(stage_cfg, "stage_id", idx))
-            runtime_cfg = getattr(stage_cfg, "runtime", None)
+            runtime_cfg = getattr(stage_cfg, "runtime_config", getattr(stage_cfg, "runtime", None))
             if runtime_cfg is None:
                 continue
             if stage_id == target_stage_id:
@@ -1100,13 +1125,9 @@ def _initialize_remote_replica(
         if registered_stage_cfg is None:
             raise ValueError(f"Remote stage {plan.metadata.stage_id} registered without stage config")
 
-        # Remote diffusion registration still transports the legacy mapping
-        # shape. Reconstruct and project that shape until its RFC #4021 cutover.
-        metadata = (
-            extract_legacy_stage_metadata(OmegaConf.create(registered_stage_cfg))
-            if plan.metadata.stage_type == "diffusion"
-            else copy.deepcopy(plan.metadata)
-        )
+        # Registration is transport-only: the head-side typed plan remains
+        # authoritative for metadata and topology.
+        metadata = extract_stage_metadata_from_omni_stage_config(plan.stage_cfg)
         metadata.replica_id = plan.replica_id
         ctx = StageRemoteFactoryContext(
             stage_id=plan.metadata.stage_id,
diff --git a/vllm_omni/entrypoints/cli/serve.py b/vllm_omni/entrypoints/cli/serve.py
index bc7f81132a7..a35f062023e 100644
--- a/vllm_omni/entrypoints/cli/serve.py
+++ b/vllm_omni/entrypoints/cli/serve.py
@@ -1048,6 +1048,7 @@ def run_headless(args: TrackingNamespace) -> None:
     )
     from vllm_omni.engine.stage_init_utils import (
         build_engine_args_dict,
+        build_engine_args_dict_from_omni_stage_config,
         build_vllm_config,
         get_stage_connector_spec,
         inject_omni_kv_connector_config,
@@ -1141,21 +1142,21 @@ def run_headless(args: TrackingNamespace) -> None:
     stage_connector_spec = get_stage_connector_spec(
         omni_transfer_config=omni_transfer_config,
         stage_id=stage_id,
-        async_chunk=bool(stage_cfg.engine_args.get("async_chunk", False)),
+        async_chunk=bool(
+            getattr(getattr(stage_cfg, "connector_config", None), "async_chunk", None)
+            if hasattr(stage_cfg, "connector_config")
+            else stage_cfg.engine_args.get("async_chunk", False)
+        ),
     )
 
-    # ``runtime_cfg`` is mostly inherited from the parent's
-    # CUDA_VISIBLE_DEVICES; when ``--omni-dp-size-local > 1`` we additionally
-    # bracket each replica's spawn below with setup_stage_devices so they
-    # don't all stack on cuda:0 (see ``per_replica_devices`` above).
-    # Headless startup still supplies the legacy OmegaConf stage shape through
-    # the stable adapter entry point. The implementation switches only when
-    # RFC #4021 threads structured stage configs through the launch plan.
-    engine_args_dict = build_engine_args_dict(
-        stage_cfg,
-        model,
-        stage_connector_spec=stage_connector_spec,
-        cli_tokenizer=getattr(args, "tokenizer", None),
+    engine_args_dict = (
+        build_engine_args_dict_from_omni_stage_config(
+            stage_cfg, model, stage_connector_spec=stage_connector_spec, cli_tokenizer=getattr(args, "tokenizer", None)
+        )
+        if hasattr(stage_cfg, "connector_config")
+        else build_engine_args_dict(
+            stage_cfg, model, stage_connector_spec=stage_connector_spec, cli_tokenizer=getattr(args, "tokenizer", None)
+        )
     )
 
     inject_omni_kv_connector_config(engine_args_dict, omni_kv_connector, stage_id)
diff --git a/vllm_omni/entrypoints/openai/serving_chat.py b/vllm_omni/entrypoints/openai/serving_chat.py
index 484d5d1702b..5b3f2d54ba9 100644
--- a/vllm_omni/entrypoints/openai/serving_chat.py
+++ b/vllm_omni/entrypoints/openai/serving_chat.py
@@ -248,10 +248,27 @@ def _stage_get(obj: Any, key: str, default: Any = None) -> Any:
             return obj.get(key, default)
         return getattr(obj, key, default)
 
+    @classmethod
+    def _stage_model_metadata(cls, stage: Any) -> tuple[str | None, str | None]:
+        """Return ``(model_arch, model_stage)`` for typed or legacy stages."""
+        model_config = cls._stage_get(stage, "model_config")
+        model_arch = cls._stage_get(model_config, "model_arch")
+        model_stage = cls._stage_get(stage, "model_stage")
+
+        topology = cls._stage_get(stage, "stage_pipeline_config")
+        if model_stage is None:
+            model_stage = cls._stage_get(topology, "model_stage")
+
+        engine_args = cls._stage_get(stage, "engine_args")
+        if model_arch is None:
+            model_arch = cls._stage_get(engine_args, "model_arch")
+        if model_stage is None:
+            model_stage = cls._stage_get(engine_args, "model_stage")
+        return model_arch, model_stage
+
     def _has_minicpmo45_stage(self) -> bool:
         for stage in getattr(self.engine_client, "stage_configs", []) or []:
-            engine_args = self._stage_get(stage, "engine_args")
-            model_arch = self._stage_get(engine_args, "model_arch")
+            model_arch, _ = self._stage_model_metadata(stage)
             if model_arch == "MiniCPMO45OmniForConditionalGeneration":
                 return True
         return False
@@ -324,11 +341,10 @@ def _fix_minicpmo45_audio_stream_output_kinds(
             if not hasattr(sp, "output_kind"):
                 continue
 
-            engine_args = self._stage_get(stage, "engine_args")
-            if self._stage_get(engine_args, "model_arch") != "MiniCPMO45OmniForConditionalGeneration":
+            model_arch, model_stage = self._stage_model_metadata(stage)
+            if model_arch != "MiniCPMO45OmniForConditionalGeneration":
                 continue
 
-            model_stage = self._stage_get(engine_args, "model_stage")
             if model_stage == "llm":
                 sp.output_kind = RequestOutputKind.FINAL_ONLY
             elif model_stage == "tts":
diff --git a/vllm_omni/entrypoints/openai/serving_speech.py b/vllm_omni/entrypoints/openai/serving_speech.py
index 80f357651f2..8aa32899ac4 100644
--- a/vllm_omni/entrypoints/openai/serving_speech.py
+++ b/vllm_omni/entrypoints/openai/serving_speech.py
@@ -36,6 +36,7 @@
 from vllm.utils import random_uuid
 from vllm.v1.engine.exceptions import EngineDeadError, EngineGenerateError
 
+from vllm_omni.config.stage_config import StagePipelineConfig
 from vllm_omni.entrypoints.openai.audio_utils_mixin import AudioMixin, StreamingAudioResampler
 from vllm_omni.entrypoints.openai.protocol.audio import (
     AudioResponse,
@@ -76,6 +77,24 @@
 _SPEECH_USAGE_INPUT_TEXT_TOKENS_HEADER = "X-VLLM-OMNI-INPUT-TEXT-TOKENS"
 _SPEECH_USAGE_INPUT_AUDIO_TOKENS_HEADER = "X-VLLM-OMNI-INPUT-AUDIO-TOKENS"
 
+
+def _stage_speech_metadata(stage: Any) -> tuple[str | None, str | None, str | None]:
+    """Return speech routing metadata from typed or legacy stage configs."""
+    topology = getattr(stage, "stage_pipeline_config", None)
+    if isinstance(topology, StagePipelineConfig):
+        return (
+            getattr(topology, "model_stage", None),
+            getattr(getattr(stage, "model_config", None), "model_arch", None),
+            getattr(stage, "worker_type", None),
+        )
+    engine_args = getattr(stage, "engine_args", None)
+    return (
+        getattr(engine_args, "model_stage", None),
+        getattr(engine_args, "model_arch", None),
+        getattr(engine_args, "worker_type", None),
+    )
+
+
 # TTS Configuration
 #
 # The stage-key -> model-type mapping is NOT declared here: it is derived from
@@ -472,12 +491,13 @@ def _find_tts_stage(self):
         """Find and return the TTS stage config, or None if not found."""
         tts_stage_keys = all_tts_stage_keys()
         entry_stage_archs = tts_entry_stage_archs()
-        all_stages = frozenset(stage.engine_args.model_stage for stage in self.engine_client.stage_configs)
+        all_stages = frozenset(
+            model_stage
+            for stage in self.engine_client.stage_configs
+            if (model_stage := _stage_speech_metadata(stage)[0]) is not None
+        )
         for stage in self.engine_client.stage_configs:
-            engine_args = stage.engine_args
-            model_stage = engine_args.model_stage
-            model_arch = getattr(engine_args, "model_arch", None)
-            worker_type = getattr(engine_args, "worker_type", None)
+            model_stage, model_arch, worker_type = _stage_speech_metadata(stage)
             if model_stage in tts_stage_keys:
                 # Owning the stage key is not always enough: a model may be
                 # speech-capable only in some deployment topologies. Ask the
@@ -501,10 +521,7 @@ def _detect_tts_model_type(self) -> str | None:
         """
         if self._tts_stage is None:
             return None
-        return detect_tts_model_type(
-            getattr(self._tts_stage.engine_args, "model_stage", None),
-            getattr(self._tts_stage.engine_args, "model_arch", None),
-        )
+        return detect_tts_model_type(*_stage_speech_metadata(self._tts_stage)[:2])
 
     def _compute_max_instructions_length(self) -> int:
         """Compute max instructions length with precedence: CLI > stage config > default.
@@ -518,7 +535,12 @@ def _compute_max_instructions_length(self) -> int:
 
         # 2. Try to get from TTS stage config
         if self._tts_stage is not None:
-            tts_args = getattr(self._tts_stage, "tts_args", {})
+            topology = getattr(self._tts_stage, "stage_pipeline_config", None)
+            tts_args = (
+                getattr(topology, "extras", {}).get("tts_args", {})
+                if isinstance(topology, StagePipelineConfig)
+                else getattr(self._tts_stage, "tts_args", {})
+            )
             if "max_instructions_length" in tts_args:
                 return tts_args["max_instructions_length"]
 
@@ -1896,9 +1918,7 @@ async def _prepare_speech_generation(
             # chat-template markers (im_start_token_id 151644).  A raw-text
             # prompt produces a 1-token placeholder that crashes the talker's
             # prefill/decode handoff.  Reject early with an actionable message.
-            stage_names = {
-                getattr(getattr(s, "engine_args", None), "model_stage", None) for s in self.engine_client.stage_configs
-            }
+            stage_names = {_stage_speech_metadata(s)[0] for s in self.engine_client.stage_configs}
             if "talker" in stage_names:
                 raise ValueError(
                     "The /v1/audio/speech endpoint is only supported for "
diff --git a/vllm_omni/entrypoints/openai/serving_video.py b/vllm_omni/entrypoints/openai/serving_video.py
index 9a24a1ef969..71749636225 100644
--- a/vllm_omni/entrypoints/openai/serving_video.py
+++ b/vllm_omni/entrypoints/openai/serving_video.py
@@ -53,6 +53,30 @@
 
 _VIDEO_RESPONSE_FRAME_CONVERSION_WORKERS = 8
 
+
+def _config_value(config: Any, key: str, default: Any = None) -> Any:
+    if isinstance(config, Mapping):
+        return config.get(key, default)
+    return getattr(config, key, default)
+
+
+def _stage_diffusion_model_class_name(stage_config: Any) -> str | None:
+    """Resolve a stage's diffusion class across typed and legacy shapes."""
+    diffusion_config = _config_value(stage_config, "diffusion_config")
+    model_class_name = _config_value(diffusion_config, "model_class_name")
+    if model_class_name:
+        return str(model_class_name)
+
+    model_config = _config_value(stage_config, "model_config")
+    model_arch = _config_value(model_config, "model_arch") or _config_value(stage_config, "model_arch")
+    if model_arch:
+        return str(model_arch)
+
+    engine_args = _config_value(stage_config, "engine_args", {})
+    model_class_name = _config_value(engine_args, "model_class_name")
+    return str(model_class_name) if model_class_name else None
+
+
 if TYPE_CHECKING:
     from vllm_omni.diffusion.data import OmniDiffusionConfig
 
@@ -195,18 +219,7 @@ def supports_mixed_reference_inputs(self) -> bool:
         model_class_name = getattr(od_config, "model_class_name", None)
         model_archs = [model_class_name]
         for stage_config in self.stage_configs or ():
-            stage_get = (
-                stage_config.get if isinstance(stage_config, Mapping) else lambda key: getattr(stage_config, key, None)
-            )
-            engine_args = stage_get("engine_args") or {}
-            model_archs.extend(
-                (
-                    stage_get("model_arch"),
-                    engine_args.get("model_class_name")
-                    if isinstance(engine_args, Mapping)
-                    else getattr(engine_args, "model_class_name", None),
-                )
-            )
+            model_archs.append(_stage_diffusion_model_class_name(stage_config))
         metadata_capability = any(
             get_diffusion_model_metadata(model_arch).supports_mixed_reference_inputs for model_arch in model_archs
         )
@@ -223,18 +236,7 @@ def supported_control_upload_types(self) -> frozenset[str]:
         od_config = self._resolve_diffusion_od_config()
         model_archs = [None if od_config is None else getattr(od_config, "model_class_name", None)]
         for stage_config in self.stage_configs or ():
-            stage_get = (
-                stage_config.get if isinstance(stage_config, Mapping) else lambda key: getattr(stage_config, key, None)
-            )
-            engine_args = stage_get("engine_args") or {}
-            model_archs.extend(
-                (
-                    stage_get("model_arch"),
-                    engine_args.get("model_class_name")
-                    if isinstance(engine_args, Mapping)
-                    else getattr(engine_args, "model_class_name", None),
-                )
-            )
+            model_archs.append(_stage_diffusion_model_class_name(stage_config))
 
         supported: set[str] = set()
         for model_arch in model_archs:
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/audex.py b/vllm_omni/entrypoints/openai/tts_adapters/audex.py
index 0e31b633f45..3b9e4a9a55e 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/audex.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/audex.py
@@ -42,7 +42,11 @@ def _get_tokenizer(self):
 
             from vllm_omni.model_executor.models.audex.checkpoint import ensure_audex_snapshot
 
-            stage = getattr(getattr(self.ctx.server._tts_stage, "engine_args", None), "model_stage", None)
+            stage_config = self.ctx.server._tts_stage
+            topology = getattr(stage_config, "stage_pipeline_config", None)
+            stage = getattr(topology, "model_stage", None)
+            if stage is None:
+                stage = getattr(getattr(stage_config, "engine_args", None), "model_stage", None)
             profile, folder = (
                 ("full", "checkpoint_folder_full") if stage == "audex_omni" else ("tts", "checkpoint_folder_audiogen")
             )
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/base.py b/vllm_omni/entrypoints/openai/tts_adapters/base.py
index ff43b27a508..cb760e865eb 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/base.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/base.py
@@ -39,6 +39,21 @@
 )
 
 
+def resolve_stage_model_path(engine_client: Any) -> str | None:
+    """Prefer typed stage model overrides, then legacy and served-model values."""
+    stages = getattr(engine_client, "stage_configs", ()) or ()
+    for stage in stages:
+        model_path = getattr(getattr(stage, "model_config", None), "model", None)
+        if model_path:
+            return str(model_path)
+    for stage in stages:
+        model_path = getattr(getattr(stage, "engine_args", None), "model", None)
+        if model_path:
+            return str(model_path)
+    model_path = getattr(engine_client, "model", None)
+    return str(model_path) if model_path else None
+
+
 def conditioning_cache_salt(request: "OpenAICreateSpeechRequest", tts_params: dict | None = None) -> str:
     """Stable hash of the real Stage 0 conditioning for the prefix cache.
 
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v2.py b/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v2.py
index 207d8b47b24..33f16cf0a9b 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v2.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v2.py
@@ -9,7 +9,12 @@
 from vllm.inputs import tokens_input
 
 from vllm_omni.entrypoints.openai.tts_adapters import register_tts_adapter
-from vllm_omni.entrypoints.openai.tts_adapters.base import ARTTSAdapter, PreparedRequest, apply_max_new_tokens
+from vllm_omni.entrypoints.openai.tts_adapters.base import (
+    ARTTSAdapter,
+    PreparedRequest,
+    apply_max_new_tokens,
+    resolve_stage_model_path,
+)
 
 if TYPE_CHECKING:
     from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
@@ -81,17 +86,7 @@ async def _resolve_higgs_audio_v2_processor(self):
 
         from transformers import AutoProcessor
 
-        model_path = None
-        for stage in self.engine_client.stage_configs:
-            model_path = getattr(getattr(stage, "engine_args", None), "model", None)
-            if model_path:
-                break
-        if model_path is None:
-            # Fallback: the orchestrator stores the served model id on the engine
-            # itself (set by AsyncOmniEngine.__init__). Stage-level engine_args
-            # may not surface ``model`` when the deploy yaml doesn't set it per
-            # stage (the CLI-passed model id is the single source of truth).
-            model_path = getattr(self.engine_client, "model", None)
+        model_path = resolve_stage_model_path(self.engine_client)
         if model_path is None:
             raise RuntimeError("higgs_audio_v2 serving could not resolve the model path from the engine stage configs")
         processor = AutoProcessor.from_pretrained(model_path)
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v3.py b/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v3.py
index 1e64f7a6373..d993a73952b 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v3.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v3.py
@@ -16,6 +16,7 @@
     PreparedRequest,
     apply_max_new_tokens,
     conditioning_cache_salt,
+    resolve_stage_model_path,
 )
 
 _REF_CODE_CACHE_MAX_ENTRIES = 256
@@ -170,13 +171,7 @@ async def _resolve_higgs_audio_v3_adapter(self):
             HiggsAudioV3TokenizerAdapter,
         )
 
-        model_path = None
-        for stage in self.engine_client.stage_configs:
-            model_path = getattr(getattr(stage, "engine_args", None), "model", None)
-            if model_path:
-                break
-        if model_path is None:
-            model_path = getattr(self.engine_client, "model", None)
+        model_path = resolve_stage_model_path(self.engine_client)
         if model_path is None:
             raise RuntimeError("higgs_audio_v3 serving could not resolve model path")
         tokenizer = AutoTokenizer.from_pretrained(model_path, trust_remote_code=True)
diff --git a/vllm_omni/entrypoints/openai/video/generation/helpers.py b/vllm_omni/entrypoints/openai/video/generation/helpers.py
index 4473fce071a..0ffd1ee83eb 100644
--- a/vllm_omni/entrypoints/openai/video/generation/helpers.py
+++ b/vllm_omni/entrypoints/openai/video/generation/helpers.py
@@ -58,6 +58,7 @@
     ReferenceAudio,
     ReferenceImage,
     ReferenceVideo,
+    _stage_diffusion_model_class_name,
 )
 from vllm_omni.entrypoints.openai.storage import STORAGE_MANAGER
 from vllm_omni.entrypoints.openai.stores import VIDEO_STORE
@@ -136,10 +137,6 @@ def _config_get(config: Any, key: str, default: Any = None) -> Any:
     return getattr(config, key, default)
 
 
-def _stage_engine_args(stage_cfg: Any) -> Any:
-    return _config_get(stage_cfg, "engine_args", {}) or {}
-
-
 def _diffusion_model_classes(stage_configs: list[Any] | None) -> list[type]:
     if not stage_configs:
         return []
@@ -150,7 +147,7 @@ def _diffusion_model_classes(stage_configs: list[Any] | None) -> list[type]:
     for stage_cfg in stage_configs:
         if get_stage_type(stage_cfg) != "diffusion":
             continue
-        model_class_name = _config_get(_stage_engine_args(stage_cfg), "model_class_name")
+        model_class_name = _stage_diffusion_model_class_name(stage_cfg)
         if not model_class_name:
             continue
         model_cls = DiffusionModelRegistry._try_load_model_cls(model_class_name)
diff --git a/vllm_omni/entrypoints/openpi/serving.py b/vllm_omni/entrypoints/openpi/serving.py
index 562ed70d476..11fde2bf8c1 100644
--- a/vllm_omni/entrypoints/openpi/serving.py
+++ b/vllm_omni/entrypoints/openpi/serving.py
@@ -103,6 +103,14 @@ def _get_policy_server_config(engine_client: Any) -> PolicyServerConfig:
             for stage_config in getattr(engine_client, "stage_configs", []) or []:
                 if getattr(stage_config, "stage_type", None) != "diffusion":
                     continue
+                # Typed diffusion stages keep model-owned OpenPI handshake
+                # metadata in diffusion_config.model_config. The out-of-process
+                # head only has this stage view because full od_config lives in
+                # the worker.
+                diffusion_config = getattr(stage_config, "diffusion_config", None)
+                model_config = getattr(diffusion_config, "model_config", None)
+                if model_config is not None:
+                    break
                 engine_args = getattr(stage_config, "engine_args", None)
                 model_config = getattr(engine_args, "model_config", None)
                 if model_config is not None:
diff --git a/vllm_omni/entrypoints/serve/profile/utils.py b/vllm_omni/entrypoints/serve/profile/utils.py
index f444a35341f..d91ef2cad9a 100644
--- a/vllm_omni/entrypoints/serve/profile/utils.py
+++ b/vllm_omni/entrypoints/serve/profile/utils.py
@@ -4,18 +4,20 @@
 
 
 def _should_enable_profiler_endpoints(stage_configs: list | None) -> bool:
-    """Check if any stage has profiler_config set in its engine_args."""
+    """Check whether any typed or legacy stage enables a profiler."""
     if not stage_configs:
         return False
     for stage in stage_configs:
-        engine_args = stage.get("engine_args") if isinstance(stage, dict) else getattr(stage, "engine_args", None)
-        if engine_args is None:
-            continue
         profiler_config = (
-            engine_args.get("profiler_config")
-            if isinstance(engine_args, dict)
-            else getattr(engine_args, "profiler_config", None)
+            stage.get("profiler_config") if isinstance(stage, dict) else getattr(stage, "profiler_config", None)
         )
+        if profiler_config is None:
+            engine_args = stage.get("engine_args") if isinstance(stage, dict) else getattr(stage, "engine_args", None)
+            profiler_config = (
+                engine_args.get("profiler_config")
+                if isinstance(engine_args, dict)
+                else getattr(engine_args, "profiler_config", None)
+            )
         if profiler_config is not None:
             profiler = (
                 profiler_config.get("profiler")
diff --git a/vllm_omni/entrypoints/stage_utils.py b/vllm_omni/entrypoints/stage_utils.py
index 281cbc55c77..8c2ba074786 100644
--- a/vllm_omni/entrypoints/stage_utils.py
+++ b/vllm_omni/entrypoints/stage_utils.py
@@ -1,7 +1,11 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from __future__ import annotations
 
 import logging
 import os
+from dataclasses import asdict, is_dataclass
 from multiprocessing import shared_memory as _shm
 from typing import Any
 
@@ -274,6 +278,8 @@ def _to_dict(x: Any) -> dict[str, Any]:
     try:
         if isinstance(x, dict):
             return dict(x)
+        if is_dataclass(x) and not isinstance(x, type):
+            return asdict(x)
         return _omega_to_dict(x)
     except Exception:
         try:
diff --git a/vllm_omni/entrypoints/utils.py b/vllm_omni/entrypoints/utils.py
index 39131fd58bd..74234d8d67b 100644
--- a/vllm_omni/entrypoints/utils.py
+++ b/vllm_omni/entrypoints/utils.py
@@ -18,6 +18,13 @@
 
 def inject_omni_kv_config(stage: Any, omni_conn_cfg: dict[str, Any], omni_from: str, omni_to: str) -> None:
     """Inject connector configuration into stage engine arguments."""
+    typed_connector_config = getattr(stage, "connector_config", None)
+    if typed_connector_config is not None:
+        omni_conf_dict = dict(typed_connector_config.omni_kv_config or {})
+        omni_conf_dict.update(connector_config=omni_conn_cfg, omni_from_stage=omni_from, omni_to_stage=omni_to)
+        typed_connector_config.omni_kv_config = omni_conf_dict
+        return
+
     # Prepare omni_kv_config dict
     omni_conf_dict = {}
     try:

From a769d9357b7800b521b25bc66b63a14020e647c1 Mon Sep 17 00:00:00 2001
From: Wallbreazzz <110282866+Wallbreazzz@users.noreply.github.com>
Date: Thu, 17 Sep 2026 12:50:38 +0800
Subject: [PATCH 056/105] [Bugfix][NPU] Fix talker_mtp ACL graph capture
 missing force_uniform_decode (#7008)

Signed-off-by: Wallbreazzz <wallbreazzz@users.noreply.github.com>
Signed-off-by: Wallbreazzz <110282866+Wallbreazzz@users.noreply.github.com>
Co-authored-by: Canlin Guo <canlinguosdu@gmail.com>
Co-authored-by: Hongsheng Liu <liuhongsheng4@huawei.com>
---
 vllm_omni/platforms/npu/worker/npu_ar_model_runner.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/vllm_omni/platforms/npu/worker/npu_ar_model_runner.py b/vllm_omni/platforms/npu/worker/npu_ar_model_runner.py
index 7bc6c21c61d..f78b777a564 100644
--- a/vllm_omni/platforms/npu/worker/npu_ar_model_runner.py
+++ b/vllm_omni/platforms/npu/worker/npu_ar_model_runner.py
@@ -177,6 +177,7 @@ def _capture_talker_mtp_graphs(self) -> None:
                         num_scheduled_tokens_np=np.ones(bsz, dtype=np.int32),
                         max_num_scheduled_tokens=1,
                         use_cascade_attn=False,
+                        force_uniform_decode=True,
                     )
                     n = batch_desc.num_tokens
                     ids = self.talker_mtp_input_ids.gpu[:n]

From 4200768f5923b13f7d2c54af7d687d479e929573 Mon Sep 17 00:00:00 2001
From: Sy03 <1370724210@qq.com>
Date: Wed, 16 Sep 2026 22:29:31 -0700
Subject: [PATCH 057/105] [Frontend] Scale Omni serving across API processes
 (#6923)

Signed-off-by: Sy03 <1370724210@qq.com>
---
 docs/cli/serve.md                             |  69 +++
 docs/design/module/entrypoints.md             |  10 +
 docs/design/module/stage_runtime.md           |  20 +
 .../examples/online_serving/qwen3_omni.md     |  44 +-
 .../examples/online_serving/text_to_speech.md |  20 +
 examples/online_serving/qwen3_omni/README.md  |  13 +-
 .../online_serving/text_to_speech/README.md   |  20 +-
 .../test_async_omni_engine_stage_init.py      | 414 ++++++++++++++++-
 tests/engine/test_stage_device_layout.py      |  39 +-
 .../openai_api/test_api_server_guards.py      | 191 ++++++++
 .../openai_api/test_omni_sleep_wakeup.py      |   2 +
 .../openai_api/test_serving_speech.py         |   1 +
 .../openai_api/test_video_server.py           |   3 +
 tests/entrypoints/test_serve.py               | 289 ++++++++++++
 tests/entrypoints/test_utils.py               |  18 +
 .../deploy/qwen3_tts_high_concurrency.yaml    |   9 +
 vllm_omni/engine/omni_engine_base.py          |  36 +-
 vllm_omni/engine/stage_engine_startup.py      |  31 +-
 vllm_omni/engine/stage_init_utils.py          |  13 +-
 vllm_omni/engine/stage_runtime.py             | 429 +++++++++++++-----
 vllm_omni/entrypoints/cli/serve.py            | 279 +++++++++++-
 vllm_omni/entrypoints/openai/api_server.py    | 138 +++++-
 vllm_omni/entrypoints/utils.py                |  62 ++-
 vllm_omni/utils/tracking_parser.py            |  20 +-
 .../worker/gpu_generation_model_runner.py     |   2 +-
 vllm_omni/worker/gpu_model_runner.py          |   6 +-
 26 files changed, 1974 insertions(+), 204 deletions(-)

diff --git a/docs/cli/serve.md b/docs/cli/serve.md
index cf3d068a62c..f77503091b1 100644
--- a/docs/cli/serve.md
+++ b/docs/cli/serve.md
@@ -1,5 +1,67 @@
 # vllm-omni serve
 
+## Multiple API frontends
+
+For local EngineCore pipelines with one or more stages, `--api-server-count` starts
+multiple API frontend processes that share one parent-owned set of stage
+engines:
+
+```bash
+vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
+    --api-server-count 2 \
+    --port 8091
+```
+
+This mode is intended for workloads whose request parsing, multimodal input
+processing, or response encoding can bottleneck a single frontend. It
+currently requires local multi-process EngineCore stages with one local
+process group per replica. A stage may still use multiple `num_replicas`.
+It cannot be combined with diffusion, headless or
+remote stages, intra-stage data parallelism, Ray, fault tolerance, elastic
+expert parallelism, sleep mode, or runtime LoRA updating. Runtime voice upload
+and deletion are also disabled because those mutations are process-local;
+built-in voices, inline reference audio, and voices restored at startup remain
+available. The `/v1/omni/sleep` and `/v1/omni/wakeup` control routes return HTTP
+409 for the same reason: their bookkeeping is process-local while stage engines
+are shared.
+
+A single-stage model pipeline is supported through the normal launch command;
+this is distinct from the distributed `--stage-id` / `--headless` launch mode.
+Every stage in the pipeline must be an EngineCore stage. Mixed AR-to-DiT
+pipelines, including MiniMax-H3, remain unsupported even when their first
+stage is an EngineCore stage. Diffusion support requires per-frontend channels
+and shared-engine lifecycle handling in the diffusion backend.
+
+### Workloads and performance validation
+
+Each API process owns its frontend processor, Orchestrator, request state,
+and per-replica EngineCore channels. Requests return through the channel of
+the originating API process; model weights and GPU stage engines are shared.
+This distributes frontend and orchestration work across CPU processes.
+
+| Workload | Potential benefit | Limitation |
+| ---------- | ------------------- | ------------ |
+| Concurrent cold image/video inputs on supported EngineCore pipelines | Parallel frontend processing when one API process is CPU-limited | A single cold request and GPU computation may be unchanged |
+| Many replicas producing frequent text/audio outputs | Less API/Orchestrator work and GIL contention per process | Routing remains serial within each Orchestrator |
+| Warm inputs or low-concurrency, GPU-limited generation | Additional frontend capacity | More API processes may add overhead without improving throughput |
+
+Here, a cold input means media or preprocessing caches miss, not that model
+weights must be loaded or GPU kernels compiled. Each frontend has its own
+processor/cache state, so cache duplication, CPU thread contention, and memory
+usage also matter. Multi-API serving does not itself change the output queue,
+move response encoding to an executor, or change the model's numerical scheduler.
+
+Compare `--api-server-count 1`, `2`, and higher counts with the same hardware,
+model/stage configuration, media, sampling parameters, output lengths, and
+offered load. Keep cold-cache and warmed-cache runs separate and report repeated
+measurements. Record CPU and request counts for every API worker, input and
+output queue delay, GPU utilization, first-output latency, and end-to-end latency.
+Confirm requests reach every worker: connection reuse can concentrate traffic
+on one process. Queue-only or single-API experiments do not establish a
+multi-API throughput gain. The multi-replica workload in
+[#4680](https://github.com/vllm-project/vllm-omni/issues/4680) remains a relevant
+validation target.
+
 ## Stage-based CLI quickstart
 
 The stage-based CLI is designed for deployments that require launching each pipeline stage in an isolated process
@@ -61,3 +123,10 @@ CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
 ## Arguments
 
 --8<-- "docs/generated/argparse_omni/omni_serve.inc.md"
+
+Async video jobs use process-local metadata and task handles. With multiple API
+workers, creating, listing, retrieving, downloading, and deleting these jobs
+returns HTTP 409. This restriction is independent of the current diffusion
+stage launch restriction: supporting multi-worker diffusion also requires a
+shared job lifecycle. Missing frontend topology state returns HTTP 503 for
+operations that require process-local state protection.
diff --git a/docs/design/module/entrypoints.md b/docs/design/module/entrypoints.md
index db62f9cb67e..f37ddc6baac 100644
--- a/docs/design/module/entrypoints.md
+++ b/docs/design/module/entrypoints.md
@@ -94,6 +94,13 @@ This document owns offline API semantics, CLI and serve composition,
 supported OpenAI-compatible routes, request validation and normalization,
 response conversion, streaming/session behavior, and engine handoff.
 
+When `--api-server-count` is greater than one, the serve composition root
+starts the frontend process manager while a parent-owned `StageRuntime`
+launches the shared local stage engines. Each frontend receives only its own
+stage-client channel configuration and does not launch or retire backend
+processes. CLI validation rejects unsupported distributed, diffusion,
+fault-tolerant, elastic-EP, Ray, and runtime-LoRA combinations before startup.
+
 It does not own configuration precedence, cross-stage routing, stage
 placement, payload implementation, or semantic error classification.
 `entrypoints/openai/errors.py` is an explicit primary-path exception owned by
@@ -141,6 +148,9 @@ stage so `wake_up(stage_ids=[0])` does not skip a later `wake_up(stage_ids=[1])`
 Streaming input pumps take an admission slot immediately before each EngineCore
 ADD or update, not while waiting for the next client chunk. Frontend abort
 keeps `request_states` until `generate()` consumes the terminal output.
+Multi-API serving must preserve one client rank and one channel set per
+frontend, include every frontend in readiness/failure observation, and keep
+stage lifecycle ownership in the parent composition root.
 
 ## Promotion gate
 
diff --git a/docs/design/module/stage_runtime.md b/docs/design/module/stage_runtime.md
index aefba5a4014..38255880fd1 100644
--- a/docs/design/module/stage_runtime.md
+++ b/docs/design/module/stage_runtime.md
@@ -77,6 +77,22 @@ readiness, one pool per logical stage, replica identity and membership,
 selection and affinity, stage-client/process lifecycle, liveness, draining,
 and shutdown.
 
+Local EngineCore initialization and multi-API serving use
+`StageRuntime.launch_stage_engines(num_api_servers=1)` as their common launch
+entry. It resolves plans when not supplied by the runtime's device-group
+scheduler, coordinates device locks and environment overlays, starts engines,
+and rolls back resources on startup or attachment failure. Single-API clients
+attach locally after readiness and take ownership of the engine resources;
+there is no additional API subprocess. Diffusion and remote attachment retain
+their backend-specific initialization.
+
+For local multi-API serving, the parent runtime owns and launches each stage
+engine once. It supplies a distinct input/output channel for every API
+frontend and stage replica; frontend workers attach clients to those engines
+without acquiring stage-process ownership. Readiness observation and shutdown
+remain parent-owned. This topology currently excludes diffusion and
+remote/headless stages, intra-stage data parallelism, and Ray backends.
+
 It does not own cross-stage request policy, model scheduler policy, connector
 transfer semantics, configuration precedence, or public error rendering.
 
@@ -114,6 +130,10 @@ affinity, membership changes, abort routing, process failure, draining, and
 repeated shutdown. Cross-stage policy changes belong in
 `engine_orchestration.md`.
 
+For multi-API changes, additionally exercise per-frontend channel assignment,
+shared-engine startup handshakes, frontend failure observation, and parent
+cleanup without duplicate stage shutdown.
+
 ## Promotion gate
 
 - Reconcile terminology and ownership after #5441 reaches a final state.
diff --git a/docs/user_guide/examples/online_serving/qwen3_omni.md b/docs/user_guide/examples/online_serving/qwen3_omni.md
index 2c85c33feb6..654802c5cde 100644
--- a/docs/user_guide/examples/online_serving/qwen3_omni.md
+++ b/docs/user_guide/examples/online_serving/qwen3_omni.md
@@ -2,7 +2,6 @@
 
 Source <https://github.com/vllm-project/vllm-omni/tree/main/examples/online_serving/qwen3_omni>.
 
-
 ## 🛠️ Installation
 
 Please refer to [README.md](https://github.com/vllm-project/vllm-omni/tree/main/README.md)
@@ -15,6 +14,19 @@ Please refer to [README.md](https://github.com/vllm-project/vllm-omni/tree/main/
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
 ```
 
+For a local deployment with multiple API frontend processes sharing one set
+of stage engines, add `--api-server-count`:
+
+```bash
+vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
+    --api-server-count 2 --port 8091
+```
+
+This mode supports local EngineCore stages with one local process group per
+replica, including stages configured with multiple `num_replicas`. Headless,
+remote, diffusion, intra-replica data-parallel, and Ray stage deployments
+remain single-frontend.
+
 The default deployment configuration situated at `vllm_omni/deploy/qwen3_omni_moe.yaml` is resolved and loaded
 automatically via the model registry, obviating the necessity for the `--deploy-config` flag in standard deployment topologies.
 The bundled Qwen3-Omni setup explicitly sets `moe_backend: triton` for the Thinker and Talker stages. This keeps
@@ -27,6 +39,7 @@ on the Thinker stage. Keep Talker and Code2Wav at `pipeline_parallel_size: 1`. T
 default asynchronous scheduling and audio chunk streaming can remain enabled.
 
 To explicitly utilize a custom deployment YAML, specify the configuration path:
+
 ```bash
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 \
     --deploy-config /path/to/deploy_config_file
@@ -50,7 +63,7 @@ Adopt the stage-based CLI architecture to independently instantiate execution pr
 The example below pins Stage 0 to GPU 0 and Stage 1/2 to GPU 1 via
 `CUDA_VISIBLE_DEVICES`.
 
-**1. Stage 0 (Thinker + API server)**
+#### 1. Stage 0 (Thinker + API server)
 
 ```bash
 CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
@@ -60,7 +73,7 @@ CUDA_VISIBLE_DEVICES=0 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
     --omni-master-port 26000
 ```
 
-**2. Stage 1 (Talker)**
+#### 2. Stage 1 (Talker)
 
 ```bash
 CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
@@ -70,7 +83,7 @@ CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
     --omni-master-port 26000
 ```
 
-**3. Stage 2 (Code2Wav)**
+#### 3. Stage 2 (Code2Wav)
 
 ```bash
 CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
@@ -95,6 +108,9 @@ To experiment with another supported MoE backend, set `moe_backend` in the
 deployment YAML for both the Thinker and Talker stages. For the stage-based
 CLI, pass `--moe-backend` directly on each stage command.
 
+For other stage settings, pass the option on that stage command. For example,
+to change its GPU memory utilization:
+
 ```bash
 CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
     --stage-id 1 \
@@ -107,11 +123,12 @@ CUDA_VISIBLE_DEVICES=1 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni \
 ### Send Multi-modal Request
 
 Get into the example folder
+
 ```bash
 cd examples/online_serving/qwen3_omni
 ```
 
-####  Send request via python
+#### Send request via python
 
 ```bash
 python openai_chat_completion_client_for_multimodal_generation.py --query-type use_image --port 8091 --host "localhost"
@@ -126,7 +143,6 @@ The Python client supports the following command-line arguments:
 - `--audio-path` (or `-a`): Path to local audio file or URL. If not provided and query-type is `use_audio`, uses default audio URL. Supports local file paths (automatically encoded to base64) or HTTP/HTTPS URLs and common audio formats: MP3, WAV, OGG, FLAC, M4A. Example: `--audio-path /path/to/audio.wav` or `--audio-path https://example.com/audio.mp3`
 - `--prompt` (or `-p`): Custom text prompt/question. If not provided, uses default prompt for the selected query type. Example: `--prompt "What are the main activities shown in this video?"`
 
-
 For example, to use a local video file with custom prompt:
 
 ```bash
@@ -136,19 +152,20 @@ python openai_chat_completion_client_for_multimodal_generation.py \
     --prompt "What are the main activities shown in this video?"
 ```
 
-####  Send request via curl
+#### Send request via curl
 
 ```bash
 bash run_curl_multimodal_generation.sh use_image
 ```
 
 ## Modality control
+
 You can control output modalities to specify which types of output the model should generate. This is useful when you only need text output and want to skip audio generation stages for better performance.
 
 ### Supported modalities
 
 | Modalities | Output |
-|------------|--------|
+| ------------ | -------- |
 | `["text"]` | Text only |
 | `["audio"]` | Audio only |
 | `["text", "audio"]` | Text + Audio |
@@ -226,7 +243,9 @@ print(response.choices[1].message.audio)    # Audio response
 ```
 
 ## Streaming Output
+
 If you want to enable streaming output, please set the argument as below. The final output will be obtained just after generated by corresponding stage. We support both text streaming output and audio streaming output. Other modalities can output normally.
+
 ```bash
 python openai_chat_completion_client_for_multimodal_generation.py \
     --query-type use_image \
@@ -259,12 +278,14 @@ The convenience script launches both the vLLM server and Gradio demo together:
 ```
 
 This script will:
+
 1. Start the vLLM server in the background
 2. Wait for the server to be ready
 3. Launch the Gradio demo
 4. Handle cleanup when you press Ctrl+C
 
 The script supports the following arguments:
+
 - `--model`: Model name/path (default: Qwen/Qwen3-Omni-30B-A3B-Instruct)
 - `--server-port`: Port for vLLM server (default: 8091)
 - `--gradio-port`: Port for Gradio demo (default: 7861)
@@ -275,18 +296,19 @@ The script supports the following arguments:
 
 #### Option 2: Manual Launch (Two-Step Process)
 
-**Step 1: Launch the vLLM API server**
+##### Step 1: Launch the vLLM API server
 
 ```bash
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
 ```
 
 If you have a custom deploy config file:
+
 ```bash
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 --deploy-config /path/to/deploy_config_file
 ```
 
-**Step 2: Run the Gradio demo**
+##### Step 2: Run the Gradio demo
 
 In a separate terminal:
 
@@ -299,7 +321,7 @@ Then open `http://localhost:7861/` on your local browser to interact with the we
 The gradio script supports the following arguments:
 
 - `--model`: Model name/path (should match the server model)
-- `--api-base`: Base URL for the vLLM API server (default: http://localhost:8091/v1)
+- `--api-base`: Base URL for the vLLM API server (default: <http://localhost:8091/v1>)
 - `--ip`: Host/IP for Gradio server (default: 127.0.0.1)
 - `--port`: Port for Gradio server (default: 7861)
 - `--share`: Share the Gradio demo publicly (creates a public link)
diff --git a/docs/user_guide/examples/online_serving/text_to_speech.md b/docs/user_guide/examples/online_serving/text_to_speech.md
index e9499551f8a..c1107ad60db 100644
--- a/docs/user_guide/examples/online_serving/text_to_speech.md
+++ b/docs/user_guide/examples/online_serving/text_to_speech.md
@@ -413,6 +413,22 @@ vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --omni --port 8091
 ./qwen3_tts/run_server.sh Base
 ```
 
+For a local deployment with multiple API frontend processes sharing one set
+of TTS stage engines, add `--api-server-count`:
+
+```bash
+vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
+    --omni --api-server-count 2 --port 8091
+```
+
+This mode supports local EngineCore stages with one local process group per
+replica, including stages configured with multiple `num_replicas`. Headless,
+remote, intra-replica data-parallel, and Ray stage deployments are not
+supported. Runtime voice upload and deletion are disabled with multiple
+API frontends because their registries are process-local. Built-in voices,
+inline `ref_audio`, and voices restored from `custom_voice_dir` at startup are
+supported.
+
 ### Executor backend
 
 Single-GPU serves now default to the uniproc executor (lower IPC overhead, the Base cloning use case from [#2603](https://github.com/vllm-project/vllm-omni/issues/2603) / [#2604](https://github.com/vllm-project/vllm-omni/pull/2604)). `vllm_omni/deploy/qwen3_tts.yaml` is the only Qwen3-TTS deploy config; pass `--deploy-config <path>` to override.
@@ -478,6 +494,10 @@ checkpoint. When a request names an uploaded voice, the server infers
 `task_type="Base"`. Built-in presets such as `vivian` and `ryan` remain
 CustomVoice speakers and require a CustomVoice checkpoint.
 
+The runtime upload and delete routes require a single API frontend; with
+`--api-server-count > 1`, use inline `ref_audio` or restore precomputed voices
+from `custom_voice_dir` at startup.
+
 ### Precomputed custom voices
 
 For reused Base voice-cloning speakers, precompute the reference artifacts once
diff --git a/examples/online_serving/qwen3_omni/README.md b/examples/online_serving/qwen3_omni/README.md
index 107e1f09815..8d6014db240 100644
--- a/examples/online_serving/qwen3_omni/README.md
+++ b/examples/online_serving/qwen3_omni/README.md
@@ -14,6 +14,17 @@ Please refer to [README.md](../../../README.md)
 vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
 ```
 
+For a local deployment with multiple API frontend processes sharing one set
+of stage engines, add `--api-server-count`:
+
+```bash
+vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --api-server-count 2 --port 8091
+```
+
+This mode currently supports local EngineCore stages. It is not available
+with headless or remote stage deployments, and pure diffusion stages remain
+single-frontend.
+
 The default deployment configuration, situated at `vllm_omni/deploy/qwen3_omni_moe.yaml`, is resolved and loaded
 automatically via the model registry, obviating the `--deploy-config` flag in standard deployment topologies.
 Asynchronous chunk streaming operates as **enabled by default** within this bundled configuration.
@@ -156,7 +167,7 @@ parser defaults). If you don't pass a flag, the YAML value wins.
 > chunked vs end-to-end modes (e.g. qwen3_tts code2wav) dispatch
 > automatically based on that bool — no extra flag or variant yaml is
 > needed.
-
+>
 > ⚠️ **For multi-stage models that share GPUs (qwen3_omni_moe by default
 > shares cuda:1 between stages 1 and 2), avoid using global memory flags.**
 > A global `--gpu-memory-utilization 0.85` would apply to every stage and
diff --git a/examples/online_serving/text_to_speech/README.md b/examples/online_serving/text_to_speech/README.md
index b749731e025..77e9ec4f152 100644
--- a/examples/online_serving/text_to_speech/README.md
+++ b/examples/online_serving/text_to_speech/README.md
@@ -13,7 +13,7 @@ For the full list of supported architectures across all modalities, see
 ## Supported Models
 
 | Model | HuggingFace repo | Voice cloning | Streaming | Voice presets / upload | Gradio demo |
-|---|---|---|---|---|---|
+| --- | --- | --- | --- | --- | --- |
 | Breeze-TTS-2 | `BreezeBlue/Breeze-TTS-2` | ✓ (`ref_audio`+`ref_text`) | ✓ (PCM stream) | speaker tags (`S0`..`S9`, default `S0`) | — |
 | Audio8 TTS Preview | `Audio8/Audio8-TTS-Preview-0.6b` | ✓ (`ref_audio`+`ref_text`) | ✓ (PCM stream) | uploaded audio voice only; no presets | ✓ |
 | Fish Speech S2 Pro | `fishaudio/s2-pro` | ✓ (`ref_audio`+`ref_text`) | ✓ (PCM stream) | — | ✓ |
@@ -781,6 +781,20 @@ vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice --omni --port 8091
 ./qwen3_tts/run_server.sh Base
 ```
 
+For a local deployment with multiple API frontend processes sharing one set
+of TTS stage engines, add `--api-server-count`:
+
+```bash
+vllm serve Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice \
+    --omni --api-server-count 2 --port 8091
+```
+
+This mode supports local EngineCore stages only; headless or remote stage
+deployments are not supported. Runtime voice upload and deletion are disabled
+with multiple API frontends because their registries are process-local.
+Built-in voices, inline `ref_audio`, and voices restored from `custom_voice_dir`
+at startup are supported.
+
 ### Executor backend
 
 Single-GPU serves now default to the uniproc executor (lower IPC overhead, the Base cloning use case from [#2603](https://github.com/vllm-project/vllm-omni/issues/2603) / [#2604](https://github.com/vllm-project/vllm-omni/pull/2604)). `vllm_omni/deploy/qwen3_tts.yaml` is the only Qwen3-TTS deploy config; pass `--deploy-config <path>` to override.
@@ -835,6 +849,10 @@ checkpoint. When a request names an uploaded voice, the server infers
 `task_type="Base"`. Built-in presets such as `vivian` and `ryan` remain
 CustomVoice speakers and require a CustomVoice checkpoint.
 
+The runtime upload and delete routes require a single API frontend; with
+`--api-server-count > 1`, use inline `ref_audio` or restore precomputed voices
+from `custom_voice_dir` at startup.
+
 ### Precomputed custom voices
 
 For reused Base voice-cloning speakers, precompute the reference artifacts once
diff --git a/tests/engine/test_async_omni_engine_stage_init.py b/tests/engine/test_async_omni_engine_stage_init.py
index 6378351229f..75301ee0aff 100644
--- a/tests/engine/test_async_omni_engine_stage_init.py
+++ b/tests/engine/test_async_omni_engine_stage_init.py
@@ -8,14 +8,17 @@
 import os
 import time
 import types
+from dataclasses import dataclass, field
 
 import pytest
 from omegaconf import OmegaConf
+from vllm.v1.engine.utils import EngineZmqAddresses
 
 from vllm_omni.config.omni_config import OmniStageRuntimeConfig
 from vllm_omni.diffusion.data import AttentionConfig
 from vllm_omni.engine import omni_engine_base as async_omni_engine_module
 from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
+from vllm_omni.engine.stage_engine_startup import StageReplicaResources
 from vllm_omni.engine.stage_init_utils import (
     LogicalStageInitPlan,
     ReplicaInitPlan,
@@ -29,6 +32,32 @@
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
 
+@dataclass
+class _FakeParallelConfig:
+    enable_fault_tolerance: bool = False
+    enable_elastic_ep: bool = False
+    data_parallel_size: int = 1
+    use_ray: bool = False
+
+
+@dataclass
+class _FakeVllmConfig:
+    parallel_config: _FakeParallelConfig = field(default_factory=_FakeParallelConfig)
+
+
+@dataclass
+class _FakeRuntimeConfig:
+    devices: str
+
+
+@dataclass
+class _FakeStageConfig:
+    stage_id: int
+    stage_type: str
+    engine_args: dict[str, object]
+    runtime: _FakeRuntimeConfig
+
+
 def test_stage_runtime_env_accepts_typed_runtime_config(monkeypatch):
     env_key = "VLLM_OMNI_TEST_TYPED_STAGE_ENV"
     monkeypatch.delenv(env_key, raising=False)
@@ -200,7 +229,7 @@ def test_stage_engine_core_client_module_reload_keeps_forward_refs_deferred():
     )
 
 
-def test_async_omni_engine_initialize_stages_passes_log_stats_to_runtime(monkeypatch):
+def test_async_omni_engine_initialize_stages_passes_log_stats_and_client_config_to_runtime(monkeypatch):
     import vllm_omni.engine.omni_engine_base as engine_mod
 
     engine = object.__new__(AsyncOmniEngine)
@@ -218,6 +247,7 @@ def test_async_omni_engine_initialize_stages_passes_log_stats_to_runtime(monkeyp
     engine._omni_lb_policy = "random"
     engine.request_queue = types.SimpleNamespace()
     engine._log_stats = True
+    engine._client_config = engine_mod.OmniClientConfig(client_count=2, client_index=1, stage_addresses={})
     engine._parallel_stage_init = False
 
     captured: dict[str, object] = {}
@@ -233,6 +263,7 @@ def _capture_create_stage_runtime(**kwargs):
 
     assert captured["stage_init_timeout"] == 7
     assert captured["log_stats"] is True
+    assert captured["client_config"] is engine._client_config
 
 
 def test_async_omni_engine_initialize_stages_retains_stage0_prompt_transform(monkeypatch):
@@ -833,6 +864,289 @@ def _make_async_mp_client(**kwargs):
     assert captured["client_log_stats"] is True
 
 
+def test_stage_runtime_attaches_external_llm_client_without_launching_engine(monkeypatch):
+    import vllm_omni.engine.stage_runtime as runtime_mod
+
+    client_addresses = {
+        "input_address": "ipc://stage0-input-1",
+        "output_address": "ipc://stage0-output-1",
+    }
+    client_config = {
+        "client_count": 2,
+        "client_index": 1,
+        "stage_addresses": {0: {0: client_addresses}},
+    }
+    runtime = StageRuntime(
+        stage_configs=[],
+        model="dummy-model",
+        config_path="dummy-config",
+        stage_init_timeout=1,
+        async_chunk=False,
+        client_config=client_config,
+    )
+    parallel_config = _FakeParallelConfig()
+    vllm_config = _FakeVllmConfig(parallel_config=parallel_config)
+    plan = _make_llm_plan(0, stage_id=0, vllm_config=vllm_config).replicas[0]
+    captured: dict[str, object] = {}
+    stage_client = object()
+
+    def _capture_client(**kwargs):
+        captured.update(kwargs)
+        return stage_client
+
+    monkeypatch.setattr(runtime_mod.StageEngineCoreClientBase, "make_async_mp_client", _capture_client)
+    monkeypatch.setattr(
+        runtime_mod,
+        "launch_stage_replica",
+        lambda **_kwargs: pytest.fail("external client must not launch a stage engine"),
+    )
+
+    assert runtime._initialize_local_llm_replica(plan, stage_init_timeout=1) is stage_client
+    assert captured["client_addresses"] == client_addresses
+    assert captured["client_count"] == 2
+    assert captured["client_index"] == 1
+    assert not hasattr(parallel_config, "_api_process_count")
+    assert not hasattr(parallel_config, "_api_process_rank")
+
+
+@pytest.mark.parametrize("stage_ids", [(0,), (0, 1)], ids=["single-stage", "multi-stage"])
+@pytest.mark.parametrize("client_count", [1, 2])
+def test_stage_runtime_launches_shared_engines_with_per_client_addresses(monkeypatch, stage_ids, client_count):
+    import vllm_omni.engine.stage_runtime as runtime_mod
+
+    runtime = _make_stage_runtime()
+    stage_plans = []
+    for stage_id in stage_ids:
+        parallel_config = _FakeParallelConfig()
+        plan = _make_llm_plan(
+            stage_id,
+            stage_id=stage_id,
+            vllm_config=_FakeVllmConfig(parallel_config=parallel_config),
+        )
+        plan.replicas[0].engine_args_dict = {}
+        stage_plans.append(plan)
+    stage_plans[0].replicas[0].metadata.runtime_cfg = {"env": {"VLLM_OMNI_TEST_STAGE_RUNTIME_ENV": "enabled"}}
+
+    monkeypatch.setattr(runtime, "_prepare_stage_plans", lambda: stage_plans)
+    monkeypatch.setattr(runtime, "_resolve_replica_physical_devices", lambda stage_id, _cfg: str(stage_id))
+    monkeypatch.setattr(runtime_mod, "acquire_device_locks", lambda *_args: [])
+
+    events: list[tuple[str, int]] = []
+    captured_launch_kwargs: list[dict[str, object]] = []
+    captured_launch_env: list[str | None] = []
+
+    @contextlib.contextmanager
+    def _fake_launch_stage_replica(**kwargs):
+        stage_id = kwargs["stage_id"]
+        events.append(("enter", stage_id))
+        captured_launch_kwargs.append(kwargs)
+        captured_launch_env.append(os.environ.get("VLLM_OMNI_TEST_STAGE_RUNTIME_ENV"))
+        yield StageReplicaResources(
+            addresses=EngineZmqAddresses(
+                inputs=[f"ipc://stage{stage_id}-input-{idx}" for idx in range(client_count)],
+                outputs=[f"ipc://stage{stage_id}-output-{idx}" for idx in range(client_count)],
+            ),
+        )
+        events.append(("exit", stage_id))
+
+    monkeypatch.setattr(runtime_mod, "launch_stage_replica", _fake_launch_stage_replica)
+
+    with runtime.launch_stage_engines(client_count) as launch:
+        expected = (
+            [("enter", stage_id) for stage_id in stage_ids]
+            if client_count > 1
+            else [(event, stage_id) for stage_id in stage_ids for event in ("enter", "exit")]
+        )
+        assert events == expected
+        for client_index, config in enumerate(launch.client_configs):
+            assert config["client_count"] == client_count
+            assert config["client_index"] == client_index
+            for stage_id in stage_ids:
+                assert config["stage_addresses"][stage_id][0] == {
+                    "input_address": f"ipc://stage{stage_id}-input-{client_index}",
+                    "output_address": f"ipc://stage{stage_id}-output-{client_index}",
+                }
+
+    assert events == (
+        [(event, stage_id) for event in ("enter", "exit") for stage_id in stage_ids] if client_count > 1 else expected
+    )
+    assert not hasattr(stage_plans[0].replicas[0].stage_vllm_config.parallel_config, "_api_process_count")
+    assert not hasattr(stage_plans[0].replicas[0].stage_vllm_config.parallel_config, "_api_process_rank")
+    assert all(
+        kwargs["watched_frontend_processes"] is (launch.watched_frontend_processes if client_count > 1 else None)
+        for kwargs in captured_launch_kwargs
+    )
+    assert captured_launch_env == ["enabled" if stage_id == 0 else None for stage_id in stage_ids]
+    assert os.environ.get("VLLM_OMNI_TEST_STAGE_RUNTIME_ENV") is None
+
+
+@pytest.mark.parametrize("client_count", [1, 2])
+def test_stage_runtime_overlapping_devices_acquire_real_locks_once(monkeypatch, tmp_path, client_count):
+    import fcntl
+
+    import vllm_omni.engine.stage_init_utils as init_utils
+    import vllm_omni.engine.stage_runtime as runtime_mod
+
+    runtime = _make_stage_runtime()
+    plans = [_make_llm_plan(stage_id, stage_id=stage_id, vllm_config=_FakeVllmConfig()) for stage_id in (0, 1)]
+    for stage_id, plan in enumerate(plans):
+        plan.replicas[0].engine_args_dict = {"tensor_parallel_size": stage_id + 1}
+    monkeypatch.setattr(runtime, "_prepare_stage_plans", lambda: plans)
+    monkeypatch.setattr(runtime, "_resolve_replica_physical_devices", lambda sid, _cfg: "0" if sid == 0 else "0,1")
+    monkeypatch.setattr(
+        init_utils, "device_init_lock_path", lambda device_id: str(tmp_path / f"device-{device_id}.lock")
+    )
+    monkeypatch.setattr(
+        init_utils.time, "sleep", lambda _: pytest.fail("Overlapping stages must not wait on their own lock")
+    )
+
+    @contextlib.contextmanager
+    def launch(**kwargs):
+        # Real flock on a separate descriptor proves the runtime holds each lock.
+        for device_id in range(kwargs["stage_id"] + 1):
+            with open(tmp_path / f"device-{device_id}.lock", "a") as probe:
+                with pytest.raises(BlockingIOError):
+                    fcntl.flock(probe, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        yield StageReplicaResources(
+            addresses=EngineZmqAddresses(
+                inputs=[f"ipc://input-{i}" for i in range(client_count)],
+                outputs=[f"ipc://output-{i}" for i in range(client_count)],
+            )
+        )
+
+    monkeypatch.setattr(runtime_mod, "launch_stage_replica", launch)
+    with runtime.launch_stage_engines(client_count):
+        pass
+    for device_id in (0, 1):
+        with open(tmp_path / f"device-{device_id}.lock", "a") as probe:
+            fcntl.flock(probe, fcntl.LOCK_EX | fcntl.LOCK_NB)
+            fcntl.flock(probe, fcntl.LOCK_UN)
+
+
+@pytest.mark.parametrize("diffusion_stage_id", [0, 1], ids=["diffusion-only", "enginecore-to-diffusion"])
+def test_stage_runtime_multi_api_rejects_diffusion_before_launch(monkeypatch, diffusion_stage_id):
+    import vllm_omni.engine.stage_runtime as runtime_mod
+
+    runtime = _make_stage_runtime()
+    stage_plans = [
+        _make_llm_plan(stage_id, stage_id=stage_id, vllm_config=_FakeVllmConfig())
+        for stage_id in range(diffusion_stage_id)
+    ]
+    stage_plans.append(_make_diffusion_plan(diffusion_stage_id, stage_id=diffusion_stage_id))
+    monkeypatch.setattr(runtime, "_prepare_stage_plans", lambda: stage_plans)
+    monkeypatch.setattr(
+        runtime_mod,
+        "acquire_device_locks",
+        lambda *_args: pytest.fail("unsupported topology must fail before acquiring devices"),
+    )
+    monkeypatch.setattr(
+        runtime_mod,
+        "launch_stage_replica",
+        lambda **_kwargs: pytest.fail("unsupported topology must not partially launch EngineCore stages"),
+    )
+
+    with pytest.raises(ValueError, match="diffusion stage\\(s\\) are not supported"):
+        with runtime.launch_stage_engines(2):
+            pytest.fail("unsupported topology must not yield a launch handle")
+
+
+def test_stage_runtime_multi_api_maps_stage_devices_from_launcher_visibility(monkeypatch):
+    import vllm_omni.engine.stage_runtime as runtime_mod
+
+    runtime = _make_stage_runtime()
+    stage_plan = _make_llm_plan(
+        0,
+        stage_id=0,
+        vllm_config=_FakeVllmConfig(),
+    )
+    replica = stage_plan.replicas[0]
+    replica.engine_args_dict = {}
+    replica.metadata.runtime_cfg = {"devices": "0"}
+
+    device_env = runtime_mod.current_omni_platform.device_control_env_var
+    monkeypatch.setenv(device_env, "5")
+    monkeypatch.setattr(runtime, "_prepare_stage_plans", lambda: [stage_plan])
+    monkeypatch.setattr(runtime_mod, "acquire_device_locks", lambda *_args: [])
+    captured_devices: list[str | None] = []
+
+    @contextlib.contextmanager
+    def _fake_launch_stage_replica(**kwargs):
+        captured_devices.append(kwargs["stage_visible_devices"])
+        yield StageReplicaResources(
+            addresses=EngineZmqAddresses(
+                inputs=["ipc://input-0", "ipc://input-1"],
+                outputs=["ipc://output-0", "ipc://output-1"],
+            ),
+        )
+
+    monkeypatch.setattr(runtime_mod, "launch_stage_replica", _fake_launch_stage_replica)
+
+    with runtime.launch_stage_engines(2):
+        pass
+
+    assert captured_devices == ["5"]
+    assert os.environ[device_env] == "5"
+
+
+def test_stage_runtime_multi_api_rejects_elastic_ep(monkeypatch):
+    runtime = _make_stage_runtime()
+    stage_plan = _make_llm_plan(
+        0,
+        stage_id=0,
+        vllm_config=_FakeVllmConfig(parallel_config=_FakeParallelConfig(enable_elastic_ep=True)),
+    )
+    stage_plan.replicas[0].engine_args_dict = {}
+    monkeypatch.setattr(runtime, "_prepare_stage_plans", lambda: [stage_plan])
+
+    with pytest.raises(ValueError, match="enable-elastic-ep"):
+        with runtime.launch_stage_engines(2):
+            pass
+
+
+def test_stage_runtime_multi_api_failure_shuts_down_before_exceptional_context_exit(monkeypatch):
+    import vllm_omni.engine.stage_runtime as runtime_mod
+
+    runtime = _make_stage_runtime()
+    stage_plan = _make_llm_plan(0, stage_id=0, vllm_config=_FakeVllmConfig())
+    stage_plan.replicas[0].engine_args_dict = {}
+    monkeypatch.setattr(runtime, "_prepare_stage_plans", lambda: [stage_plan])
+    monkeypatch.setattr(runtime, "_resolve_replica_physical_devices", lambda *_args: None)
+    monkeypatch.setattr(runtime_mod, "acquire_device_locks", lambda *_args: [])
+
+    events: list[str] = []
+
+    class _Manager:
+        def shutdown(self) -> None:
+            events.append("shutdown")
+
+    @contextlib.contextmanager
+    def _fake_launch_stage_replica(**_kwargs):
+        try:
+            yield StageReplicaResources(
+                manager=_Manager(),
+                addresses=EngineZmqAddresses(
+                    inputs=["tcp://127.0.0.1:0", "tcp://127.0.0.1:1"],
+                    outputs=["tcp://127.0.0.1:2", "tcp://127.0.0.1:3"],
+                ),
+            )
+        except RuntimeError as exc:
+            events.append(f"exceptional-exit:{exc}")
+            raise
+        else:
+            events.append("normal-exit")
+
+    monkeypatch.setattr(runtime_mod, "launch_stage_replica", _fake_launch_stage_replica)
+
+    with pytest.raises(RuntimeError, match="deferred TCP addresses"):
+        with runtime.launch_stage_engines(2):
+            pass
+
+    assert events == [
+        "shutdown",
+        "exceptional-exit:Stage 0 returned deferred TCP addresses; multi-API launch requires fixed ports or IPC addresses",
+    ]
+
+
 def test_stage_runtime_passes_log_stats_to_output_processor(monkeypatch):
     import vllm_omni.engine.stage_runtime as runtime_mod
 
@@ -1079,7 +1393,7 @@ def test_initialize_local_llm_replica_passes_stage_init_timeout_to_complete_stag
         num_replicas=1,
         launch_mode="local",
         stage_cfg=types.SimpleNamespace(engine_args={}, runtime=types.SimpleNamespace(devices="0")),
-        metadata=types.SimpleNamespace(stage_id=0, runtime_cfg={"devices": "0"}),
+        metadata=types.SimpleNamespace(stage_id=0, stage_type="llm", runtime_cfg={"devices": "0"}),
         stage_connector_spec={},
         omni_kv_connector=(None, None, None),
         stage_vllm_config=fake_vllm_config,
@@ -1933,6 +2247,102 @@ def test_port_from_zmq_address_parsing():
     assert _port_from_zmq_address("tcp://host:not-a-port") is None
 
 
+@pytest.mark.parametrize("parallel", [False, True])
+@pytest.mark.parametrize("failure", ["ready", "attach", None])
+def test_single_api_common_launch_ownership_and_rollback(monkeypatch, parallel, failure):
+    import vllm_omni.engine.stage_runtime as runtime_mod
+
+    runtime = _make_stage_runtime()
+    runtime._parallel_stage_init = parallel
+    plan = _make_llm_plan(0, stage_id=0, vllm_config=_FakeVllmConfig()).replicas[0]
+    plan.engine_args_dict = {}
+    events = []
+
+    class Manager:
+        def shutdown(self):
+            events.append("shutdown")
+
+    manager = Manager()
+    addresses = EngineZmqAddresses(inputs=["ipc://input"], outputs=["ipc://output"])
+    monkeypatch.setattr(runtime, "_resolve_replica_physical_devices", lambda *_: "0")
+
+    def acquire(*_):
+        events.append("lock")
+        return [42]
+
+    monkeypatch.setattr(runtime_mod, "acquire_device_locks", acquire)
+    monkeypatch.setattr(runtime_mod, "release_device_locks", lambda _: events.append("unlock"))
+
+    @contextlib.contextmanager
+    def launch(**kwargs):
+        assert kwargs["num_api_servers"] == 1
+        assert kwargs["omni_parallel_stage_init"] is parallel
+        events.append("spawn")
+        yield StageReplicaResources(manager=manager, addresses=addresses)
+        assert runtime._replica_launch_lock.locked() is False
+        events.append("ready")
+        if failure == "ready":
+            raise RuntimeError("ready")
+
+    def attach(**kwargs):
+        assert "ready" in events
+        assert kwargs["engine_manager"] is manager
+        events.append("attach")
+        if failure == "attach":
+            raise RuntimeError("attach")
+        return manager
+
+    monkeypatch.setattr(runtime_mod, "launch_stage_replica", launch)
+    monkeypatch.setattr(runtime_mod.StageEngineCoreClientBase, "make_async_mp_client", attach)
+    if failure:
+        with pytest.raises(RuntimeError, match=failure):
+            runtime._initialize_local_llm_replica(plan, 1)
+        assert events.count("shutdown") == 1
+    else:
+        assert runtime._initialize_local_llm_replica(plan, 1) is manager
+        assert "shutdown" not in events
+    assert events.count("lock") == events.count("unlock") == (0 if parallel else 1)
+
+
+@pytest.mark.parametrize("client_count", [1, 2])
+def test_common_launch_parallel_admission_before_spawn(monkeypatch, client_count):
+    import vllm_omni.engine.stage_runtime as runtime_mod
+
+    runtime = _make_stage_runtime()
+    runtime._parallel_stage_init = True
+    plan = _make_llm_plan(0, stage_id=0, vllm_config=_FakeVllmConfig())
+    plan.replicas[0].engine_args_dict = {}
+    events = []
+    monkeypatch.setattr(runtime, "_prepare_stage_plans", lambda: [plan])
+    monkeypatch.setattr(runtime, "_reject_unguardable_executors", lambda _: events.append("guard"))
+    monkeypatch.setattr(runtime, "_run_stage_admission", lambda _: events.append("admit"))
+    monkeypatch.setattr(runtime, "_resolve_replica_physical_devices", lambda *_: "0")
+
+    def forbidden_lock(*_):
+        pytest.fail("parallel initialization must use child phase locks")
+
+    monkeypatch.setattr(runtime_mod, "acquire_device_locks", forbidden_lock)
+
+    @contextlib.contextmanager
+    def launch(**kwargs):
+        assert events == ["guard", "admit"]
+        assert kwargs["omni_parallel_stage_init"] is True
+        events.append("spawn")
+        yield StageReplicaResources(
+            addresses=EngineZmqAddresses(
+                inputs=[f"ipc://in{i}" for i in range(client_count)],
+                outputs=[f"ipc://out{i}" for i in range(client_count)],
+            )
+        )
+        assert not runtime._replica_launch_lock.locked()
+        events.append("ready")
+
+    monkeypatch.setattr(runtime_mod, "launch_stage_replica", launch)
+    with runtime.launch_stage_engines(client_count):
+        pass
+    assert events == ["guard", "admit", "spawn", "ready"]
+
+
 @pytest.mark.parametrize(
     "stage_modes,expected", [([False, True, True], True), ([False, False], False), ([True, False], True)]
 )
diff --git a/tests/engine/test_stage_device_layout.py b/tests/engine/test_stage_device_layout.py
index beb66dfba7f..6dd30373d4a 100644
--- a/tests/engine/test_stage_device_layout.py
+++ b/tests/engine/test_stage_device_layout.py
@@ -18,6 +18,7 @@
 from unittest import mock
 
 import pytest
+from pytest_mock import MockerFixture
 
 from vllm_omni.engine import stage_init_utils
 from vllm_omni.engine.stage_init_utils import (
@@ -240,7 +241,7 @@ def test_build_vllm_config_fails_before_engine_config_on_mismatch():
     get_class.assert_not_called()
 
 
-def test_build_vllm_config_proceeds_on_consistent_layout():
+def test_build_vllm_config_proceeds_on_consistent_layout(mocker: MockerFixture) -> None:
     """The guard must not false-positive: a consistent single-GPU stage flows past
     it and reaches ``create_engine_config`` / ``Executor.get_class`` as usual."""
     stage = _stage(1, devices="1")
@@ -249,18 +250,30 @@ def test_build_vllm_config_proceeds_on_consistent_layout():
         model_config=types.SimpleNamespace(hf_config=types.SimpleNamespace()),
     )
     sentinel_executor = object()
-    with (
-        mock.patch.object(
-            stage_init_utils.OmniEngineArgs, "create_engine_config", return_value=fake_config
-        ) as create_engine_config,
-        mock.patch.object(stage_init_utils.Executor, "get_class", return_value=sentinel_executor),
-        mock.patch.object(stage_init_utils.OmniINCConfig, "maybe_upgrade", side_effect=lambda quant: quant),
-    ):
-        vllm_config, executor_class = build_vllm_config(
-            stage,
-            model="dummy-model",
-            engine_args_dict={"tensor_parallel_size": 1},
-        )
+    captured_api_process_config: dict[str, int] = {}
+
+    def capture_create_engine_config(engine_args, *args, **kwargs):
+        captured_api_process_config["count"] = engine_args._api_process_count
+        captured_api_process_config["rank"] = engine_args._api_process_rank
+        return fake_config
+
+    create_engine_config = mocker.patch.object(
+        stage_init_utils.OmniEngineArgs,
+        "create_engine_config",
+        autospec=True,
+        side_effect=capture_create_engine_config,
+    )
+    mocker.patch.object(stage_init_utils.Executor, "get_class", return_value=sentinel_executor)
+    mocker.patch.object(stage_init_utils.OmniINCConfig, "maybe_upgrade", side_effect=lambda quant: quant)
+
+    vllm_config, executor_class = build_vllm_config(
+        stage,
+        model="dummy-model",
+        engine_args_dict={"tensor_parallel_size": 1},
+        api_process_count=3,
+        api_process_rank=2,
+    )
     create_engine_config.assert_called_once()
     assert vllm_config is fake_config
     assert executor_class is sentinel_executor
+    assert captured_api_process_config == {"count": 3, "rank": 2}
diff --git a/tests/entrypoints/openai_api/test_api_server_guards.py b/tests/entrypoints/openai_api/test_api_server_guards.py
index 6e28bb5b1e1..ebc08662f50 100644
--- a/tests/entrypoints/openai_api/test_api_server_guards.py
+++ b/tests/entrypoints/openai_api/test_api_server_guards.py
@@ -42,7 +42,10 @@
 
 import asyncio
 import json
+import signal
+from argparse import Namespace
 from contextlib import asynccontextmanager
+from dataclasses import dataclass
 from types import SimpleNamespace
 
 import pytest
@@ -59,6 +62,66 @@
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
+
+@dataclass
+class _FakeParallelConfig:
+    _api_process_rank: int
+
+
+@dataclass
+class _FakeVllmConfig:
+    parallel_config: _FakeParallelConfig
+
+
+def test_omni_api_worker_sets_parent_death_signal_before_validation(mocker):
+    args = _minimal_args(_omni_stage_client_configs=[{"stage_addresses": {}}])
+    death_signal = mocker.patch.object(api_server, "set_death_signal")
+
+    with pytest.raises(RuntimeError, match="client configuration"):
+        api_server.run_omni_api_server_worker_proc(
+            "127.0.0.1:8000",
+            mocker.Mock(),
+            args,
+            {"client_count": 2, "client_index": -1},
+        )
+
+    death_signal.assert_called_once_with(signal.SIGTERM)
+
+
+@pytest.mark.asyncio
+async def test_omni_run_server_worker_forwards_client_config(monkeypatch):
+    captured: dict[str, object] = {}
+
+    @asynccontextmanager
+    async def fake_build_async_omni(*_args, **kwargs):
+        captured.update(kwargs)
+        yield _FakeEngineClient(vllm_config=_FakeVllmConfig(_FakeParallelConfig(_api_process_rank=1)))
+
+    monkeypatch.setattr(api_server, "build_async_omni", fake_build_async_omni)
+    monkeypatch.setattr(api_server, "build_openai_app", lambda *_args: FastAPI())
+    monkeypatch.setattr(api_server, "omni_init_app_state", lambda *_args: asyncio.sleep(0))
+    monkeypatch.setattr(api_server, "shutdown_unsupported_routes", lambda *_args: None)
+
+    async def fake_storage_start() -> None:
+        return None
+
+    monkeypatch.setattr(api_server.STORAGE_MANAGER, "start", fake_storage_start)
+
+    async def fake_serve_http(app, **_kwargs):
+        assert app.state.api_server_count == 2
+        task = asyncio.create_task(asyncio.sleep(0))
+        await asyncio.sleep(0)
+        return task
+
+    monkeypatch.setattr(api_server, "serve_http", fake_serve_http)
+
+    args = _minimal_args(model="dummy")
+    config = {"client_count": 2, "client_index": 1, "stage_addresses": {}}
+
+    await api_server.omni_run_server_worker("127.0.0.1:8000", _FakeSocket(), args, config)
+    assert captured["client_config"] is config
+
+
 # FastAPI/Starlette auto-adds HEAD on every GET route. Including HEAD here
 # would invent ("HEAD", path) entries for every GET and fail the current census.
 # TODO: extend this set and the expected census if @router.head / @router.options appear.
@@ -626,6 +689,48 @@ async def handle_connection(self) -> None:
     assert calls == [expected_handler]
 
 
+@pytest.mark.parametrize("path", ["/v1/duplex", "/v1/realtime", "/v1/realtime?duplex=1"])
+def test_multi_api_duplex_reconnect_rejected_on_each_worker(path: str) -> None:
+    class SessionHandler:
+        async def handle_realtime_session(self, _websocket) -> None:
+            pytest.fail("Multi-API requests must not access process-local sessions")
+
+    class PendingWarmup:
+        def is_set(self) -> bool:
+            raise AssertionError("Multi-API rejection must not wait for duplex warmup")
+
+    # Separate apps represent workers with independent frontend registries.
+    # Opening on A then reconnecting to B must reject at the same boundary.
+    for worker_index in (0, 1):
+        app = FastAPI()
+        app.state.api_server_count = 2
+        app.state.api_server_index = worker_index
+        app.state.openai_serving_duplex = SessionHandler()
+        app.state.duplex_warmup_done = PendingWarmup()
+        app.include_router(api_server.router)
+        with TestClient(app) as client, client.websocket_connect(path) as websocket:
+            assert websocket.receive_json()["code"] == "multi_api_duplex_unsupported"
+            with pytest.raises(WebSocketDisconnect) as exc:
+                websocket.receive_text()
+            assert exc.value.code == 1008
+
+
+@pytest.mark.parametrize("path", ["/v1/duplex", "/v1/realtime?duplex=1"])
+def test_single_api_duplex_session_still_reaches_handler(path: str) -> None:
+    class SessionHandler:
+        async def handle_realtime_session(self, websocket) -> None:
+            await websocket.accept()
+            await websocket.send_json({"type": "session.created"})
+            await websocket.close()
+
+    app = FastAPI()
+    app.state.api_server_count = 1
+    app.state.openai_serving_duplex = SessionHandler()
+    app.include_router(api_server.router)
+    with TestClient(app) as client, client.websocket_connect(path) as websocket:
+        assert websocket.receive_json() == {"type": "session.created"}
+
+
 def test_health_without_engine_returns_stable_unhealthy_response() -> None:
     """Lock ``/health`` with no engine initialized.
 
@@ -715,6 +820,38 @@ def test_speech_without_handler_preserves_not_found_http_error() -> None:
     assert exc_info.value.detail == "The model does not support Speech API"
 
 
+@pytest.mark.asyncio
+async def test_multi_api_rejects_runtime_voice_upload() -> None:
+    app = FastAPI()
+    app.state.api_server_count = 2
+    raw_request = _request_for(app, method="POST", path="/v1/audio/voices")
+
+    with pytest.raises(HTTPException) as exc_info:
+        await api_server.upload_voice(
+            raw_request,
+            audio_sample=None,
+            speaker_embedding=None,
+            consent="consent-id",
+            name="probe",
+        )
+
+    assert exc_info.value.status_code == 409
+    assert "process-local frontend state" in exc_info.value.detail
+
+
+@pytest.mark.asyncio
+async def test_multi_api_rejects_sleep_route() -> None:
+    app = FastAPI()
+    app.state.api_server_count = 2
+    raw_request = _request_for(app, method="POST", path="/v1/omni/sleep")
+
+    with pytest.raises(HTTPException) as exc_info:
+        await api_server.omni_sleep(api_server.OmniSleepRequest(stage_ids=[0]), raw_request)
+
+    assert exc_info.value.status_code == 409
+    assert "process-local frontend state" in exc_info.value.detail
+
+
 def test_engine_error_json_response_includes_request_and_stage_fields(monkeypatch) -> None:
     """Lock shared ``EngineGenerateError`` JSON fields used by Omni handlers.
 
@@ -937,3 +1074,57 @@ async def warmup(self):
         must_be_wired=_MULTISTAGE_MUST_BE_WIRED,
         must_be_none=_MULTISTAGE_MUST_BE_NONE,
     )
+
+
+@pytest.mark.parametrize("count", [None, 0, -1, "2", True])
+def test_process_local_guard_rejects_unknown_topology(count):
+    app = FastAPI()
+    if count is not None:
+        app.state.api_server_count = count
+    # CLI args cannot substitute for missing/invalid actual runtime state.
+    app.state.args = Namespace(api_server_count=1)
+    with pytest.raises(HTTPException) as exc:
+        api_server._reject_process_local_state_with_multiple_api_workers(_request_for(app), "Sleep")
+    assert exc.value.status_code == 503
+
+
+@pytest.mark.parametrize(
+    "requested,config,expected",
+    [(None, None, 1), (1, None, 1), (2, {"client_count": 2}, 2), (None, {"client_count": 2}, 2)],
+)
+def test_api_topology_resolved_from_launch(requested, config, expected):
+    assert api_server._resolve_api_server_count(Namespace(api_server_count=requested), config) == expected
+
+
+@pytest.mark.parametrize("requested,config", [(2, None), (2, {}), (2, {"client_count": 1}), (2, {"client_count": "2"})])
+def test_api_topology_rejects_inconsistent_launch(requested, config):
+    with pytest.raises(ValueError):
+        api_server._resolve_api_server_count(Namespace(api_server_count=requested), config)
+
+
+@pytest.mark.parametrize("count,status", [(2, 409), (None, 503)])
+@pytest.mark.parametrize(
+    "method,path",
+    [
+        ("POST", "/v1/videos"),
+        ("GET", "/v1/videos"),
+        ("GET", "/v1/videos/job"),
+        ("GET", "/v1/videos/job/content"),
+        ("DELETE", "/v1/videos/job"),
+    ],
+)
+def test_video_lifecycle_guard_precedes_processing(monkeypatch, count, status, method, path):
+    from fastapi.testclient import TestClient
+
+    app = FastAPI()
+    if count is not None:
+        app.state.api_server_count = count
+    app.include_router(api_server.router)
+
+    async def forbidden_form():
+        pytest.fail("video form processing must not run before topology rejection")
+
+    app.dependency_overrides[api_server._parse_video_form] = forbidden_form
+    with TestClient(app) as client:
+        response = client.request(method, path)
+    assert response.status_code == status
diff --git a/tests/entrypoints/openai_api/test_omni_sleep_wakeup.py b/tests/entrypoints/openai_api/test_omni_sleep_wakeup.py
index 615248fcfb3..ba5925d8fc8 100644
--- a/tests/entrypoints/openai_api/test_omni_sleep_wakeup.py
+++ b/tests/entrypoints/openai_api/test_omni_sleep_wakeup.py
@@ -20,6 +20,7 @@ def _make_app(engine_client):
     from vllm_omni.entrypoints.openai.api_server import router
 
     app = FastAPI()
+    app.state.api_server_count = 1
     app.include_router(router)
     app.state.engine_client = engine_client
     app.state.sleeping_stages = set()
@@ -253,6 +254,7 @@ def pure_diffusion_app(pure_diffusion_engine, mocker):
     )
 
     app = FastAPI()
+    app.state.api_server_count = 1
     app.include_router(router)
 
     mocker.patch(
diff --git a/tests/entrypoints/openai_api/test_serving_speech.py b/tests/entrypoints/openai_api/test_serving_speech.py
index 5ac895d8646..7cdeebc39b1 100644
--- a/tests/entrypoints/openai_api/test_serving_speech.py
+++ b/tests/entrypoints/openai_api/test_serving_speech.py
@@ -3826,6 +3826,7 @@ def test_api_server_create_speech_wraps_error_response_status(mocker: MockerFixt
 def _make_api_server_request(handler, *, method: str = "POST", path: str = "/v1/audio/voices") -> Request:
     app = FastAPI()
     app.state.openai_serving_speech = handler
+    app.state.api_server_count = 1
     scope = {
         "type": "http",
         "app": app,
diff --git a/tests/entrypoints/openai_api/test_video_server.py b/tests/entrypoints/openai_api/test_video_server.py
index 0b44cabdf6b..715c7ca0444 100644
--- a/tests/entrypoints/openai_api/test_video_server.py
+++ b/tests/entrypoints/openai_api/test_video_server.py
@@ -463,6 +463,7 @@ async def fake_init_app_state(engine_client, state, args):
 @pytest.fixture
 def test_client():
     app = FastAPI()
+    app.state.api_server_count = 1
     app.include_router(router)
     app.state.openai_serving_video = OmniOpenAIServingVideo.for_diffusion(
         diffusion_engine=FakeAsyncOmni(),
@@ -1804,6 +1805,7 @@ def test_action_extraction_accepts_multimodal_actions_payload():
 
 def test_missing_handler_returns_503():
     app = FastAPI()
+    app.state.api_server_count = 1
     app.include_router(router)
     app.state.openai_serving_video = None
     client = TestClient(app)
@@ -2790,6 +2792,7 @@ def test_cosmos3_control_upload_rejects_invalid_size(control_bytes, message, tes
 
 def test_sync_missing_handler_returns_503():
     app = FastAPI()
+    app.state.api_server_count = 1
     app.include_router(router)
     app.state.openai_serving_video = None
     client = TestClient(app)
diff --git a/tests/entrypoints/test_serve.py b/tests/entrypoints/test_serve.py
index 8d3766df00c..7f8b6a4a90f 100644
--- a/tests/entrypoints/test_serve.py
+++ b/tests/entrypoints/test_serve.py
@@ -6,14 +6,19 @@
 from __future__ import annotations
 
 import argparse
+from dataclasses import dataclass
+from multiprocessing.reduction import ForkingPickler
 from types import SimpleNamespace
 from typing import Any
 
 import pytest
 from pytest_mock import MockerFixture
+from vllm.v1.engine.utils import EngineZmqAddresses
 
 from vllm_omni.config.omni_config import VllmOmniDiffusionStageConfig
 from vllm_omni.config.resolver import OmniConfigResolution
+from vllm_omni.engine.stage_engine_startup import StageReplicaResources
+from vllm_omni.engine.stage_runtime import StageEngineLaunch
 from vllm_omni.entrypoints.cli.serve import (
     OmniServeCommand,
     _parse_stage_overrides,
@@ -25,6 +30,31 @@
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
 
+@dataclass(frozen=True)
+class _FakeProcess:
+    sentinel: str
+    exitcode: int | None
+    name: str
+    pid: int
+
+
+@dataclass
+class _FakeProcessOwner:
+    processes: list[_FakeProcess]
+
+
+@dataclass
+class _FakeStageEngineArgs:
+    async_chunk: bool
+    enable_sleep_mode: bool
+
+
+@dataclass
+class _FakeStageConfig:
+    stage_id: int
+    engine_args: _FakeStageEngineArgs
+
+
 def _resolved(*stages: SimpleNamespace) -> OmniConfigResolution:
     return OmniConfigResolution(config_path="/fake/stages.yaml", stage_configs=tuple(stages))
 
@@ -44,6 +74,8 @@ def test_serve_parser_accepts_no_async_chunk_and_marks_it_explicit() -> None:
     explicit = args.get_explicit_kwargs_dict()
     assert args.get_explicit_kwargs_dict()
     assert not explicit["async_chunk"]
+    assert (args.api_server_count or 1) == 1
+    assert "api_server_count" not in explicit
 
 
 def _parse_serve_args(argv: list[str]) -> TrackingNamespace:
@@ -169,6 +201,244 @@ def test_serve_parser_rejects_invalid_video_output_transport(value: str) -> None
         parser.parse_args(["serve", "fake-model", "--omni", "--video-output-transport", value])
 
 
+def test_tracking_namespace_is_picklable_for_spawned_api_workers() -> None:
+    parser = TrackingArgumentParser()
+    subparsers = parser.add_subparsers(dest="subcommand")
+    OmniServeCommand().subparser_init(subparsers)
+    args = parser.parse_args(["serve", "fake-model", "--omni", "--api-server-count", "2"])
+    args._omni_stage_client_configs = [{"stage_addresses": {0: {0: {"input_address": "ipc://input"}}}}]
+
+    restored = ForkingPickler.loads(ForkingPickler.dumps(args))
+
+    assert restored.api_server_count == 2
+    assert restored.get_explicit_kwargs_dict()["api_server_count"] == 2
+    assert restored._omni_stage_client_configs == args._omni_stage_client_configs
+
+
+def test_serve_validate_rejects_multiple_api_servers_for_diffusion(mocker: MockerFixture) -> None:
+    parser = TrackingArgumentParser()
+    subparsers = parser.add_subparsers(dest="subcommand")
+    cmd = OmniServeCommand()
+    cmd.subparser_init(subparsers)
+    args = parser.parse_args(["serve", "fake-diffusion-model", "--omni", "--api-server-count", "2"])
+
+    mocker.patch("vllm_omni.diffusion.utils.hf_utils.is_diffusion_model", return_value=True)
+    validate = mocker.patch("vllm_omni.entrypoints.cli.serve.validate_parsed_serve_args")
+
+    with pytest.raises(ValueError, match="not supported for diffusion"):
+        cmd.validate(args)
+
+    validate.assert_not_called()
+
+
+def test_serve_validate_rejects_sleep_mode_with_multiple_api_servers(mocker: MockerFixture) -> None:
+    parser = TrackingArgumentParser()
+    subparsers = parser.add_subparsers(dest="subcommand")
+    cmd = OmniServeCommand()
+    cmd.subparser_init(subparsers)
+    args = parser.parse_args(["serve", "fake-model", "--omni", "--api-server-count", "2", "--enable-sleep-mode"])
+
+    mocker.patch("vllm_omni.diffusion.utils.hf_utils.is_diffusion_model", return_value=False)
+    mocker.patch("vllm_omni.entrypoints.cli.serve.validate_parsed_serve_args")
+
+    with pytest.raises(ValueError, match="enable-sleep-mode"):
+        cmd.validate(args)
+
+
+@pytest.mark.parametrize("typed", [False, True])
+@pytest.mark.parametrize("downstream_async_chunk", [False, True])
+def test_build_multi_api_stage_runtime_matches_current_constructor(
+    mocker: MockerFixture, typed: bool, downstream_async_chunk: bool
+) -> None:
+    from vllm_omni.entrypoints.cli import serve as serve_module
+
+    args = TrackingNamespace(
+        argparse.Namespace(
+            model="dummy-model",
+            model_tag=None,
+            stage_init_timeout=1,
+            tokenizer=None,
+            disable_log_stats=False,
+        ),
+        frozenset({"model"}),
+    )
+    if typed:
+        from vllm_omni.config.omni_config import VllmOmniARStageConfig
+        from vllm_omni.config.stage_config import StagePipelineConfig
+
+        stages = [
+            VllmOmniARStageConfig(stage_pipeline_config=StagePipelineConfig(stage_id=i, model_stage="ar"))
+            for i in range(2)
+        ]
+        stages[1].connector_config.async_chunk = downstream_async_chunk
+    else:
+        stages = [
+            _FakeStageConfig(
+                stage_id=i,
+                engine_args=_FakeStageEngineArgs(
+                    async_chunk=bool(i and downstream_async_chunk), enable_sleep_mode=False
+                ),
+            )
+            for i in range(2)
+        ]
+    mocker.patch("vllm_omni.entrypoints.omni_base.omni_snapshot_download", return_value="dummy-model")
+    mocker.patch(
+        "vllm_omni.config.config_factory.with_trust_remote_code_override",
+        side_effect=lambda kwargs, _trust: kwargs,
+    )
+    mocker.patch("vllm_omni.entrypoints.utils.parse_stage_overrides", return_value={})
+    mocker.patch(
+        "vllm_omni.config.resolver.resolve_omni_config",
+        return_value=OmniConfigResolution(config_path="dummy-config", stage_configs=tuple(stages)),
+    )
+
+    runtime = serve_module._build_multi_api_stage_runtime(args, 2)
+
+    assert runtime._client_count == 1
+    assert runtime._client_index == 0
+    assert runtime._async_chunk is downstream_async_chunk
+
+
+@pytest.mark.parametrize("typed", [False, True])
+def test_build_multi_api_stage_runtime_rejects_sleep_enabled_in_stage_config(
+    mocker: MockerFixture, typed: bool
+) -> None:
+    from vllm_omni.entrypoints.cli import serve as serve_module
+
+    args = TrackingNamespace(
+        argparse.Namespace(
+            model="dummy-model",
+            model_tag=None,
+            stage_init_timeout=1,
+            tokenizer=None,
+            disable_log_stats=False,
+        ),
+        frozenset({"model"}),
+    )
+    stage_config = _FakeStageConfig(
+        stage_id=3,
+        engine_args=_FakeStageEngineArgs(async_chunk=False, enable_sleep_mode=True),
+    )
+    if typed:
+        from vllm_omni.config.omni_config import VllmOmniARStageConfig
+        from vllm_omni.config.stage_config import StagePipelineConfig
+
+        typed_stage = VllmOmniARStageConfig(stage_pipeline_config=StagePipelineConfig(stage_id=3, model_stage="ar"))
+        typed_stage.model_config.enable_sleep_mode = True
+        stage_config = typed_stage
+    mocker.patch("vllm_omni.entrypoints.omni_base.omni_snapshot_download", return_value="dummy-model")
+    mocker.patch(
+        "vllm_omni.config.config_factory.with_trust_remote_code_override",
+        side_effect=lambda kwargs, _trust: kwargs,
+    )
+    mocker.patch("vllm_omni.entrypoints.utils.parse_stage_overrides", return_value={})
+    mocker.patch(
+        "vllm_omni.config.resolver.resolve_omni_config",
+        return_value=OmniConfigResolution(config_path="dummy-config", stage_configs=(stage_config,)),
+    )
+
+    with pytest.raises(ValueError, match=r"sleep mode.*stage\(s\) \[3\]"):
+        serve_module._build_multi_api_stage_runtime(args, 2)
+
+
+def test_run_multi_api_server_omni_starts_workers_after_shared_engine_launch(mocker: MockerFixture) -> None:
+    from vllm_omni.entrypoints.cli import serve as serve_module
+
+    args = TrackingNamespace(
+        argparse.Namespace(api_server_count=2, shutdown_timeout=1),
+        frozenset({"api_server_count", "shutdown_timeout"}),
+    )
+    socket = mocker.Mock()
+    primary_addresses = EngineZmqAddresses(
+        inputs=["ipc://input-0", "ipc://input-1"],
+        outputs=["ipc://output-0", "ipc://output-1"],
+    )
+    engine_launch = StageEngineLaunch(
+        client_configs=[{"client_count": 2, "client_index": index, "stage_addresses": {}} for index in range(2)],
+        resources=[StageReplicaResources(addresses=primary_addresses)],
+    )
+    runtime = mocker.MagicMock()
+    runtime.launch_stage_engines.return_value.__enter__.return_value = engine_launch
+    runtime.launch_stage_engines.return_value.__exit__.return_value = False
+
+    manager = mocker.Mock()
+    manager.processes = [mocker.Mock()]
+    manager.gather_actual_addresses.return_value = (primary_addresses.inputs, primary_addresses.outputs)
+
+    mocker.patch.object(serve_module, "_build_multi_api_stage_runtime", return_value=runtime)
+    mocker.patch.object(serve_module, "_wait_for_multi_api_server_completion")
+    mocker.patch("signal.signal")
+    mocker.patch("vllm.entrypoints.openai.api_server.setup_server", return_value=("127.0.0.1:8000", socket))
+    mocker.patch("vllm.v1.metrics.prometheus.setup_multiprocess_prometheus")
+    start_manager = mocker.patch.object(serve_module, "_start_api_server_process_manager", return_value=manager)
+
+    serve_module.run_multi_api_server_omni(args)
+
+    assert args._omni_stage_client_configs is engine_launch.client_configs
+    start_manager.assert_called_once()
+    manager_kwargs = start_manager.call_args.kwargs
+    assert manager_kwargs["cleanup_timeout"] == 1
+    assert manager_kwargs["num_servers"] == 2
+    assert manager_kwargs["input_addresses"] == ["ipc://input-0", "ipc://input-1"]
+    assert manager_kwargs["target_server_fn"] is serve_module.run_omni_api_server_worker_proc
+    assert engine_launch.watched_frontend_processes == manager.processes
+    runtime.shutdown.assert_called_once_with()
+    socket.close.assert_called_once_with()
+
+
+def test_start_api_server_process_manager_cleans_up_partial_start(mocker: MockerFixture) -> None:
+    from vllm_omni.entrypoints.cli import serve as serve_module
+
+    first_process = mocker.Mock(name="first_process")
+    second_process = mocker.Mock(name="second_process")
+    first_process.pid = 1234
+    second_process.pid = None
+    second_process.start.side_effect = RuntimeError("spawn failed")
+    parent_pipes = [mocker.Mock(name="parent_pipe_0"), mocker.Mock(name="parent_pipe_1")]
+    child_pipes = [mocker.Mock(name="child_pipe_0"), mocker.Mock(name="child_pipe_1")]
+    spawn_context = mocker.Mock()
+    spawn_context.Process.side_effect = [first_process, second_process]
+    spawn_context.Pipe.side_effect = list(zip(parent_pipes, child_pipes))
+    mocker.patch("vllm.v1.utils.multiprocessing.get_context", return_value=spawn_context)
+    shutdown = mocker.patch("vllm.v1.utils.shutdown")
+
+    with pytest.raises(RuntimeError, match="spawn failed"):
+        serve_module._start_api_server_process_manager(
+            cleanup_timeout=1.5,
+            listen_address="127.0.0.1:8000",
+            sock=mocker.Mock(),
+            args=argparse.Namespace(),
+            num_servers=2,
+            input_addresses=["ipc://input-0", "ipc://input-1"],
+            output_addresses=["ipc://output-0", "ipc://output-1"],
+            target_server_fn=mocker.Mock(),
+        )
+
+    first_process.start.assert_called_once_with()
+    second_process.start.assert_called_once_with()
+    for pipe in parent_pipes:
+        pipe.close.assert_called_once_with()
+    shutdown.assert_called_once_with([first_process], timeout=1.5)
+
+
+def test_wait_for_multi_api_server_completion_rejects_engine_failure(
+    mocker: MockerFixture,
+) -> None:
+    from vllm_omni.entrypoints.cli import serve as serve_module
+
+    api_process = _FakeProcess(sentinel="api-0", exitcode=None, name="api-0", pid=10)
+    engine_process = _FakeProcess(sentinel="engine-0", exitcode=4, name="engine-0", pid=20)
+    manager = _FakeProcessOwner(processes=[api_process])
+    engine_launch = StageEngineLaunch(
+        client_configs=[],
+        resources=[StageReplicaResources(manager=_FakeProcessOwner(processes=[engine_process]))],
+    )
+    mocker.patch("multiprocessing.connection.wait", return_value=["engine-0"])
+
+    with pytest.raises(RuntimeError, match=r"Shared stage engine process engine-0 .* exited with code 4"):
+        serve_module._wait_for_multi_api_server_completion(manager, engine_launch)
+
+
 def test_serve_parser_rejects_stage_configs_path() -> None:
     parser = TrackingArgumentParser()
     subparsers = parser.add_subparsers(dest="subcommand")
@@ -847,3 +1117,22 @@ def test_run_headless_diffusion_raises_on_nonzero_proc_exit(mocker: MockerFixtur
 
     with pytest.raises(RuntimeError, match=r"exited with code 137"):
         run_headless(_make_headless_args(stage_id=1))
+
+
+@pytest.mark.parametrize("name", ["unfiltered_ns", "explicit_keys", "missing", "__dict__"])
+def test_tracking_namespace_uninitialized_access_raises_attribute_error(name):
+    namespace = object.__new__(TrackingNamespace)
+    with pytest.raises(AttributeError):
+        getattr(namespace, name)
+
+
+@pytest.mark.parametrize("deep", [False, True])
+def test_tracking_namespace_copy_preserves_tracking(deep):
+    import copy
+
+    namespace = TrackingNamespace(
+        argparse.Namespace(model="example", api_server_count=2), frozenset({"api_server_count"})
+    )
+    restored = copy.deepcopy(namespace) if deep else copy.copy(namespace)
+    assert restored.get_explicit_kwargs_dict() == {"api_server_count": 2}
+    assert restored.model == "example"
diff --git a/tests/entrypoints/test_utils.py b/tests/entrypoints/test_utils.py
index e7f94ffef70..65395265b9e 100644
--- a/tests/entrypoints/test_utils.py
+++ b/tests/entrypoints/test_utils.py
@@ -603,3 +603,21 @@ def test_coercion_applies_to_all_stages(self):
         assert all([isinstance(r, SamplingParams) for r in result])
         assert result[0].output_kind == RequestOutputKind.DELTA
         assert result[1].output_kind == RequestOutputKind.DELTA
+
+
+@pytest.mark.parametrize("api_server_count", [1, 2])
+def test_prepare_stage_config_inputs_filters_frontend_options(api_server_count):
+    from vllm_omni.entrypoints.utils import prepare_stage_config_inputs
+
+    kwargs = {
+        "api_server_count": api_server_count,
+        "disable_log_stats": True,
+        "model_tag": "example",
+        "max_num_seqs": 8,
+        "stage_overrides": '{"0": {"max_num_seqs": 4}}',
+    }
+    inputs = prepare_stage_config_inputs("example", kwargs, trust_remote_code=None)
+
+    assert inputs.kwargs == {"max_num_seqs": 8}
+    assert inputs.stage_overrides == {"0": {"max_num_seqs": 4}}
+    assert kwargs["api_server_count"] == api_server_count
diff --git a/vllm_omni/deploy/qwen3_tts_high_concurrency.yaml b/vllm_omni/deploy/qwen3_tts_high_concurrency.yaml
index 7914ecd5255..36c85e41d03 100644
--- a/vllm_omni/deploy/qwen3_tts_high_concurrency.yaml
+++ b/vllm_omni/deploy/qwen3_tts_high_concurrency.yaml
@@ -9,6 +9,15 @@
 # Profile validated for the c64 / PROMPTS=512 performance experiments:
 # Stage 0 talker on GPU 0 with S0=64, Stage 1 Code2Wav on GPU 1 with S1=10.
 #
+# For CPU-bound frontend or orchestration workloads, this profile can be used
+# with ``--api-server-count 2`` or higher to run multiple API frontends over
+# one shared set of local stage engines. This can improve request parsing,
+# multimodal/audio preprocessing, and response handling under concurrency;
+# it does not duplicate GPU engines or make a single GPU-bound request faster.
+# Each frontend keeps process-local state, so runtime voice mutations, sleep /
+# wakeup, async video jobs, and resumable duplex sessions are not supported
+# with more than one API worker. See docs/cli/serve.md for the full boundary.
+#
 async_chunk: true
 
 connectors:
diff --git a/vllm_omni/engine/omni_engine_base.py b/vllm_omni/engine/omni_engine_base.py
index d615ebca003..e22bfb241b9 100644
--- a/vllm_omni/engine/omni_engine_base.py
+++ b/vllm_omni/engine/omni_engine_base.py
@@ -61,11 +61,12 @@
 from vllm_omni.engine.stage_init_utils import build_stage0_input_processor
 from vllm_omni.engine.stage_pool import StagePool
 from vllm_omni.engine.stage_runtime import (
+    OmniClientConfig,
     StageRuntimeInfo,
     create_stage_runtime,
 )
 from vllm_omni.entrypoints.pd_utils import PDDisaggregationMixin
-from vllm_omni.entrypoints.utils import parse_stage_overrides
+from vllm_omni.entrypoints.utils import prepare_stage_config_inputs
 from vllm_omni.inputs.data import OmniSamplingParams
 from vllm_omni.metrics.prometheus import OmniRequestCounter
 
@@ -122,6 +123,7 @@ class OmniEngineBase:
     _transfer_emitter: Any = None
     _prom_metrics: Any = None
     _enable_orch_monitor: bool = False
+    _client_config: OmniClientConfig | None = None
     # Lazily created by get_output_blocking_async().
     _output_drain_executor: concurrent.futures.ThreadPoolExecutor | None = None
 
@@ -136,6 +138,7 @@ def __init__(
         log_stats: bool = False,
         tokenizer: str | None = None,
         trust_remote_code: bool | None = None,
+        client_config: OmniClientConfig | None = None,
         **kwargs: Any,
     ) -> None:
         self.model = model
@@ -155,6 +158,7 @@ def __init__(
         # --log-stats CLI flag set by the user via OmniBase.
         self._log_stats = log_stats
         self._enable_orch_monitor = bool(kwargs.pop("enable_orch_monitor", False))
+        self._client_config = client_config
 
         logger.info(f"[OmniEngine] Initializing with model {model}")
 
@@ -166,6 +170,8 @@ def __init__(
         _stage_id_kwarg = kwargs.get("stage_id")
         if isinstance(_stage_id_kwarg, int) and not single_stage_mode:
             single_stage_mode = True
+        if client_config is not None and int(client_config.get("client_count", 1)) > 1 and single_stage_mode:
+            raise ValueError("Multiple API servers cannot be combined with single-stage distributed mode")
 
         self.single_stage_mode: bool = single_stage_mode
         self._single_stage_id_filter: int | None = (
@@ -378,6 +384,7 @@ def _initialize_stages(self, stage_init_timeout: int) -> None:
             omni_lb_policy=self._omni_lb_policy,
             request_queue=self.request_queue,
             log_stats=self._log_stats,
+            client_config=self._client_config,
         )
         self._runtime.initialize()
 
@@ -892,24 +899,15 @@ def _resolve_stage_configs(
     ) -> tuple[str, list[Any]]:
         """Resolve stage configs and inject defaults shared by orchestrator/headless."""
 
-        for legacy_arg in ("stage_configs_path", "stage_configs"):
-            if legacy_arg in kwargs:
-                raise ValueError(f"`{legacy_arg}` is no longer supported; use `deploy_config` instead.")
-
-        # log_stats is captured by __init__; its CLI-only negative alias must
-        # not cross into per-stage structured config ownership validation.
-        kwargs.pop("disable_log_stats", None)
-        deploy_config_path = kwargs.pop("deploy_config", None)
-        strategy_config_path = kwargs.pop("strategy_config", None)
-        # CLI callers arrive pre-parsed; offline Python callers may use the
-        # JSON-string form documented in recipes.
-        stage_overrides = parse_stage_overrides(kwargs.pop("stage_overrides", None))
-
-        # ``diffusion_streaming_output`` is the public AsyncOmni/serve kwarg;
-        # stage configs know the field as ``streaming_output``. Mirror only a
-        # truthy value so the CLI's False default does not override deploy YAML.
-        if kwargs.get("diffusion_streaming_output") and kwargs.get("streaming_output") is None:
-            kwargs["streaming_output"] = True
+        config_inputs = prepare_stage_config_inputs(
+            model,
+            kwargs,
+            trust_remote_code=trust_remote_code,
+        )
+        kwargs = config_inputs.kwargs
+        deploy_config_path = config_inputs.deploy_config_path
+        strategy_config_path = config_inputs.strategy_config_path
+        stage_overrides = config_inputs.stage_overrides
 
         resolution = cast(
             _ConfigResolutionResult,
diff --git a/vllm_omni/engine/stage_engine_startup.py b/vllm_omni/engine/stage_engine_startup.py
index 612c7481fcd..1aaebc82bb8 100644
--- a/vllm_omni/engine/stage_engine_startup.py
+++ b/vllm_omni/engine/stage_engine_startup.py
@@ -13,6 +13,7 @@
 from collections.abc import Callable, Iterator
 from dataclasses import dataclass, field
 from multiprocessing import connection
+from multiprocessing.process import BaseProcess
 from types import SimpleNamespace
 from typing import Any
 
@@ -1138,6 +1139,8 @@ def launch_stage_replica(
     stage_visible_devices: str | None = None,
     spawn_device_lock: threading.Lock | None = None,
     omni_parallel_stage_init: bool = False,
+    num_api_servers: int = 1,
+    watched_frontend_processes: list[BaseProcess] | None = None,
 ) -> Iterator[StageReplicaResources]:
     """Launch a local LLM stage replica.
 
@@ -1148,6 +1151,8 @@ def launch_stage_replica(
     keep the same returned resource bundle.
     """
     if omni_master_server is not None:
+        if num_api_servers != 1:
+            raise ValueError("Multiple API servers are not supported with distributed stage launch")
         with _launch_omni_core_engines(
             vllm_config=vllm_config,
             executor_class=executor_class,
@@ -1173,7 +1178,16 @@ def launch_stage_replica(
 
     from vllm_omni.engine.stage_engine_core_proc_manager import StageEngineCoreProcManager
 
-    addresses = get_engine_zmq_addresses(vllm_config)
+    if num_api_servers > 1:
+        # Multi-API Omni is intentionally local-only. IPC paths avoid the
+        # bind-after-allocation race of tcp://host:0 and are stable for every
+        # stage, including stages that are not used by APIServerProcessManager.
+        addresses = EngineZmqAddresses(
+            inputs=[get_open_zmq_ipc_path() for _ in range(num_api_servers)],
+            outputs=[get_open_zmq_ipc_path() for _ in range(num_api_servers)],
+        )
+    else:
+        addresses = get_engine_zmq_addresses(vllm_config)
     handshake_address = get_open_zmq_ipc_path()
     engines_to_handshake = [CoreEngine(index=0, local=True)]
     with scoped_spawn_device_env(stage_visible_devices, spawn_device_lock, stage_id=stage_id, replica_id=replica_id):
@@ -1197,18 +1211,21 @@ def launch_stage_replica(
             manager=engine_manager,
             addresses=addresses,
         )
+        engine_launch = CoreEngineLaunch(
+            engine_manager=engine_manager,
+            coordinator=None,
+            addresses=addresses,
+            tensor_queue=None,
+        )
+        if watched_frontend_processes is not None:
+            engine_launch.watched_frontend_processes = watched_frontend_processes
         wait_for_engine_startup(
             handshake_socket,
             engines_to_handshake,
             vllm_config.parallel_config,
             False,  # coordinated_dp
             vllm_config.cache_config,
-            CoreEngineLaunch(
-                engine_manager=engine_manager,
-                coordinator=None,
-                addresses=addresses,
-                tensor_queue=None,
-            ),
+            engine_launch,
         )
 
 
diff --git a/vllm_omni/engine/stage_init_utils.py b/vllm_omni/engine/stage_init_utils.py
index 06f916394b1..a10cf5861c7 100644
--- a/vllm_omni/engine/stage_init_utils.py
+++ b/vllm_omni/engine/stage_init_utils.py
@@ -1475,6 +1475,8 @@ def build_vllm_config(
     stage_connector_spec: dict[str, Any] | None = None,
     engine_args_dict: dict[str, Any] | None = None,
     headless: bool = False,
+    api_process_count: int = 1,
+    api_process_rank: int = 0,
 ) -> tuple[Any, type]:
     """Build engine args, then create VllmConfig and executor_class.
 
@@ -1491,6 +1493,9 @@ def build_vllm_config(
         )
 
     filtered_engine_args_dict = filter_dataclass_kwargs(OmniEngineArgs, engine_args_dict)
+    if api_process_count != 1 or api_process_rank != 0:
+        filtered_engine_args_dict["_api_process_count"] = api_process_count
+        filtered_engine_args_dict["_api_process_rank"] = api_process_rank
 
     # _to_dict serializes dataclass fields (e.g. StructuredOutputsConfig) into
     # plain dicts.  When OmniEngineArgs is instantiated with the dict, these
@@ -1747,6 +1752,7 @@ def acquire_device_locks(
     stage_id: int,
     engine_args_dict: dict[str, Any],
     stage_init_timeout: int,
+    locked_devices: set[int] | None = None,
 ) -> list[int]:
     """Acquire exclusive file locks on devices needed by this stage.
 
@@ -1801,8 +1807,7 @@ def acquire_device_locks(
                 f"but only {len(physical_devices)} device(s) are available: {physical_devices}"
             )
 
-        num_devices_to_lock = num_devices_per_stage
-        devices_to_lock = sorted(physical_devices[:num_devices_to_lock])
+        devices_to_lock = sorted(set(physical_devices[:num_devices_per_stage]) - (locked_devices or set()))
 
         logger.debug(
             "Parallel config: TP=%d, PP=%d, DP=%d, PCP=%d, SP=%d, CFG=%d; will lock %d devices: %s",
@@ -1812,7 +1817,7 @@ def acquire_device_locks(
             prefill_context_parallel_size,
             sequence_parallel_size,
             cfg_parallel_size,
-            num_devices_to_lock,
+            len(devices_to_lock),
             devices_to_lock,
         )
 
@@ -1830,6 +1835,8 @@ def acquire_device_locks(
                         record_lock_holder_pid(lock_fd, lock_writable)
                         lock_acquired = True
                         lock_fds.append(lock_fd)
+                        if locked_devices is not None:
+                            locked_devices.add(device_id)
                         logger.debug("Acquired exclusive lock for device %s", device_id)
                     except BlockingIOError:
                         os.close(lock_fd)
diff --git a/vllm_omni/engine/stage_runtime.py b/vllm_omni/engine/stage_runtime.py
index d17e3b08f8f..ce958ba6d73 100644
--- a/vllm_omni/engine/stage_runtime.py
+++ b/vllm_omni/engine/stage_runtime.py
@@ -6,14 +6,15 @@
 from __future__ import annotations
 
 import concurrent.futures
+import contextlib
 import copy
 import os
 import threading
-import time
 from collections.abc import Callable, Iterator, Mapping, Sequence
-from contextlib import ExitStack, contextmanager
-from dataclasses import dataclass
-from typing import Any, cast
+from contextlib import AbstractContextManager, contextmanager
+from dataclasses import dataclass, field
+from multiprocessing.process import BaseProcess
+from typing import Any, TypedDict, cast
 
 import janus
 from vllm.logger import init_logger
@@ -94,6 +95,44 @@ class StageRemoteFactoryContext:
     executor_class: type | None = None
 
 
+class OmniClientConfig(TypedDict, total=False):
+    """Per-frontend transport/configuration passed across process boundaries."""
+
+    client_count: int
+    client_index: int
+    stage_addresses: dict[int | str, dict[int | str, dict[str, Any]]]
+    input_address: str
+    output_address: str
+    stats_update_address: str
+    actual_address_pipe: Any
+    tensor_queue: Any
+
+
+@dataclass
+class StageEngineLaunch:
+    """Engine resources handed to a local client or the serving parent.
+
+    Successful launch transfers resource ownership to the caller. Startup or
+    attachment failures are rolled back by ``launch_stage_engines``.
+    """
+
+    client_configs: list[OmniClientConfig]
+    resources: list[StageReplicaResources]
+    watched_frontend_processes: list[BaseProcess] = field(default_factory=list)
+
+    def shutdown(self) -> None:
+        seen: set[int] = set()
+        for stage_resources in reversed(self.resources):
+            for resource in (stage_resources.manager, stage_resources.coordinator):
+                if resource is None or id(resource) in seen:
+                    continue
+                seen.add(id(resource))
+                try:
+                    resource.shutdown()
+                except Exception:
+                    logger.warning("[StageEngineLaunch] resource shutdown failed", exc_info=True)
+
+
 def _build_load_balancer_factory(policy: str) -> Callable[[], LoadBalancer]:
     try:
         normalized = LoadBalancingPolicy(policy)
@@ -125,13 +164,14 @@ def __init__(
         self,
         stage_configs: list[Any],
         model: str,
-        config_path: str,
+        config_path: str | None,
         *,
         stage_init_timeout: int,
         async_chunk: bool,
         tokenizer: str | None = None,
         parallel_stage_init: bool = False,
         log_stats: bool = False,
+        client_config: OmniClientConfig | None = None,
     ) -> None:
         self._stage_configs = stage_configs
         self._model = model
@@ -146,6 +186,14 @@ def __init__(
         self._parallel_stage_init = parallel_stage_init
         self._log_stats = log_stats
         self._num_stages = len(stage_configs)
+        self._client_count = int((client_config or {}).get("client_count", 1))
+        self._client_index = int((client_config or {}).get("client_index", 0))
+        if self._client_count < 1:
+            raise ValueError(f"client_count must be >= 1, got {self._client_count}")
+        if self._client_index != -1 and not 0 <= self._client_index < self._client_count:
+            raise ValueError(f"client_index must be in [0, {self._client_count}), got {self._client_index}")
+        self._external_stage_addresses = (client_config or {}).get("stage_addresses")
+        self._api_process_rank = self._client_index
 
         # Populated by initialize()
         self.stage_pools: list[StagePool] = []
@@ -264,6 +312,205 @@ def initialize(self) -> None:
             self._cleanup_after_initialize_failure()
             raise exc
 
+    @contextmanager
+    def launch_stage_engines(
+        self,
+        num_api_servers: int = 1,
+        *,
+        stage_plans: Sequence[LogicalStageInitPlan] | None = None,
+        stage_init_timeout: int | None = None,
+    ) -> Iterator[StageEngineLaunch]:
+        """Launch EngineCore stages for local or subprocess client attachment.
+
+        The regular runtime supplies a replica plan from its device-group
+        scheduler; the serving parent resolves the whole pipeline here. Both
+        use the same device locks, spawn, readiness and rollback machinery.
+        One client completes readiness before attachment, preserving the
+        existing in-process frontend. Multiple clients attach in the caller's
+        ``with`` body before readiness completes on context exit.
+        """
+        if self._external_stage_addresses is not None:
+            raise ValueError("A runtime attached to external stage engines cannot launch engines")
+        if num_api_servers < 1:
+            raise ValueError(f"num_api_servers must be >= 1, got {num_api_servers}")
+        timeout = self._stage_init_timeout if stage_init_timeout is None else stage_init_timeout
+        resolve_plans = stage_plans is None
+        if stage_plans is None:
+            self._client_count = num_api_servers
+            self._api_process_rank = -1 if num_api_servers > 1 else self._client_index
+            self._init_visible_devices_baseline = os.environ.get(current_omni_platform.device_control_env_var)
+            stage_plans = self._prepare_stage_plans()
+
+        unsupported = [
+            plan.stage_id
+            for plan in stage_plans
+            if any(replica.metadata.stage_type == "diffusion" for replica in plan.replicas)
+        ]
+        if unsupported:
+            raise ValueError(
+                "--api-server-count currently supports EngineCore stages only; "
+                f"diffusion stage(s) are not supported: {unsupported}"
+            )
+        if any(replica.launch_mode != "local" for plan in stage_plans for replica in plan.replicas):
+            raise ValueError("--api-server-count is not supported with remote or headless stages")
+
+        if num_api_servers > 1:
+            parallel_configs: list[Any] = []
+            for plan in stage_plans:
+                for replica in plan.replicas:
+                    if replica.stage_vllm_config is None or replica.executor_class is None:
+                        raise RuntimeError(f"LLM stage {plan.stage_id} is missing its engine configuration")
+                    parallel_configs.append(replica.stage_vllm_config.parallel_config)
+            if any(getattr(parallel_config, "enable_fault_tolerance", False) for parallel_config in parallel_configs):
+                raise ValueError("--api-server-count > 1 cannot be combined with --enable-fault-tolerance")
+            if any(getattr(parallel_config, "enable_elastic_ep", False) for parallel_config in parallel_configs):
+                raise ValueError("--api-server-count > 1 cannot be combined with --enable-elastic-ep")
+            if any(
+                getattr(parallel_config, "data_parallel_size", 1) != 1 or getattr(parallel_config, "use_ray", False)
+                for parallel_config in parallel_configs
+            ):
+                raise ValueError(
+                    "--api-server-count > 1 currently supports one local process group per replica; "
+                    "intra-replica data parallelism and Ray backends are not supported"
+                )
+
+        if resolve_plans and self._parallel_stage_init:
+            self._reject_unguardable_executors(stage_plans)
+            self._run_stage_admission(stage_plans)
+
+        client_configs: list[OmniClientConfig] = [
+            OmniClientConfig(
+                client_count=num_api_servers,
+                client_index=client_index,
+                stage_addresses={},
+            )
+            for client_index in range(num_api_servers)
+        ]
+        entered_contexts: list[AbstractContextManager[StageReplicaResources]] = []
+        resources: list[StageReplicaResources] = []
+        watched_frontend_processes: list[BaseProcess] = []
+        # launch_stage_replica performs its readiness handshake in __exit__,
+        # after API workers are started, so initialization locks must remain
+        # held until all launch contexts have exited.
+        lock_fds: list[int] = []
+        locked_devices: set[int] = set()
+        launch: StageEngineLaunch | None = None
+        exited_contexts = 0
+
+        try:
+            for plan in stage_plans:
+                for replica in plan.replicas:
+                    if replica.stage_vllm_config is None or replica.executor_class is None:
+                        raise RuntimeError(f"LLM stage {plan.stage_id} is missing its engine configuration")
+                    if replica.engine_args_dict is None:
+                        raise RuntimeError(f"LLM stage {plan.stage_id} is missing engine args")
+
+                    physical_devices = self._resolve_replica_physical_devices(
+                        replica.metadata.stage_id,
+                        replica.metadata.runtime_cfg,
+                    )
+                    if not self._parallel_stage_init:
+                        with self._scoped_spawn_device_env(physical_devices):
+                            lock_fds.extend(
+                                acquire_device_locks(
+                                    replica.metadata.stage_id,
+                                    replica.engine_args_dict,
+                                    timeout,
+                                    locked_devices,
+                                )
+                            )
+
+                    launch_context = launch_stage_replica(
+                        vllm_config=replica.stage_vllm_config,
+                        executor_class=replica.executor_class,
+                        log_stats=self._log_stats,
+                        stage_id=replica.metadata.stage_id,
+                        replica_id=replica.replica_id,
+                        stage_config=replica.stage_cfg,
+                        omni_master_server=self._get_omni_master_server(),
+                        omni_coordinator_address=self._get_coordinator_address(),
+                        stage_visible_devices=physical_devices,
+                        spawn_device_lock=self._spawn_device_lock,
+                        omni_parallel_stage_init=self._parallel_stage_init,
+                        num_api_servers=num_api_servers,
+                        watched_frontend_processes=watched_frontend_processes if num_api_servers > 1 else None,
+                    )
+                    # Environment overlays are process-global. Serialize spawn;
+                    # parallel initialization waits for READY outside this lock.
+                    with self._replica_launch_lock:
+                        with stage_runtime_env(replica.metadata.stage_id, replica.metadata.runtime_cfg):
+                            stage_resources = launch_context.__enter__()
+                        entered_contexts.append(launch_context)
+                        if stage_resources is None:
+                            raise RuntimeError(f"LLM stage {plan.stage_id} launcher returned no resources")
+                        resources.append(stage_resources)
+                    if num_api_servers == 1:
+                        exited_contexts += 1
+                        launch_context.__exit__(None, None, None)
+                    addresses = stage_resources.addresses
+                    # The generic resource bundle allows no addresses (e.g.
+                    # diffusion), but EngineCore attachment requires them.
+                    if addresses is None:
+                        raise RuntimeError(f"LLM stage {plan.stage_id} launcher returned no addresses")
+                    # Unlike the single-client handshake, only stage 0 is
+                    # handed to APIServerProcessManager for address updates.
+                    # Other stages must already expose connectable endpoints.
+                    if num_api_servers > 1 and any(
+                        address.startswith("tcp://") and address.rsplit(":", 1)[-1] == "0"
+                        for address in (*addresses.inputs, *addresses.outputs)
+                    ):
+                        raise RuntimeError(
+                            f"Stage {plan.stage_id} returned deferred TCP addresses; "
+                            "multi-API launch requires fixed ports or IPC addresses"
+                        )
+                    if len(addresses.inputs) != num_api_servers or len(addresses.outputs) != num_api_servers:
+                        raise RuntimeError(
+                            f"Stage {plan.stage_id} returned {len(addresses.inputs)} input and "
+                            f"{len(addresses.outputs)} output addresses for {num_api_servers} API servers"
+                        )
+
+                    if num_api_servers == 1 and lock_fds:
+                        release_device_locks(lock_fds)
+                        lock_fds.clear()
+                        locked_devices.clear()
+
+                    for client_index, client_config in enumerate(client_configs):
+                        stage_addresses = client_config["stage_addresses"]
+                        replica_addresses = stage_addresses.setdefault(plan.stage_id, {})
+                        replica_addresses[replica.replica_id] = {
+                            "input_address": addresses.inputs[client_index],
+                            "output_address": addresses.outputs[client_index],
+                        }
+                        if addresses.frontend_stats_publish_address is not None:
+                            replica_addresses[replica.replica_id]["stats_update_address"] = (
+                                addresses.frontend_stats_publish_address
+                            )
+
+            launch = StageEngineLaunch(
+                client_configs=client_configs,
+                resources=resources,
+                watched_frontend_processes=watched_frontend_processes,
+            )
+            yield launch
+
+            while exited_contexts < len(entered_contexts):
+                entered_context = entered_contexts[exited_contexts]
+                exited_contexts += 1
+                entered_context.__exit__(None, None, None)
+        except BaseException as exc:
+            if launch is not None:
+                launch.shutdown()
+            else:
+                StageEngineLaunch(client_configs=client_configs, resources=resources).shutdown()
+            exc_info = (type(exc), exc, exc.__traceback__)
+            for pending_context in reversed(entered_contexts[exited_contexts:]):
+                with contextlib.suppress(BaseException):
+                    pending_context.__exit__(*exc_info)
+            raise
+        finally:
+            if lock_fds:
+                release_device_locks(lock_fds)
+
     def shutdown(self) -> None:
         for pool in self.stage_pools:
             for client in pool.clients:
@@ -406,6 +653,8 @@ def _build_logical_stage_init_plans(
                     self._model,
                     stage_connector_spec=stage_connector_spec,
                     engine_args_dict=engine_args_dict,
+                    api_process_count=self._client_count,
+                    api_process_rank=self._api_process_rank,
                 )
 
             for replica_id in range(num_replicas):
@@ -737,122 +986,70 @@ def _initialize_local_llm_replica(
         stage_init_timeout: int,
     ) -> StagePoolClient:
         """Initialize one local LLM replica using vLLM's launch/attach pattern."""
-        resources: StageReplicaResources | None = None
-        stage_client = None
-        lock_fds: list[int] = []
-        try:
-            physical_devices = self._resolve_replica_physical_devices(
-                plan.metadata.stage_id,
-                plan.metadata.runtime_cfg,
-            )
-            if physical_devices:
-                logger.info(
-                    "[stage_init] Stage-%s set runtime devices: %s",
-                    plan.metadata.stage_id,
-                    physical_devices,
-                )
-            vllm_config = plan.stage_vllm_config
-            executor_class = plan.executor_class
-            if vllm_config is None:
-                raise RuntimeError(f"LLM stage {plan.metadata.stage_id} is missing vllm_config")
-            if executor_class is None:
-                raise RuntimeError(f"LLM stage {plan.metadata.stage_id} is missing executor_class")
-            if plan.engine_args_dict is None:
-                raise RuntimeError(f"LLM stage {plan.metadata.stage_id} is missing engine args")
-            # G3 device locks: in the default (serial) path the parent holds a
-            # per-device LOCK_EX across the whole child init. When parallel stage
-            # init is enabled the engine-core child takes phased SH/EX locks
-            # itself (see stage_phase_lock), so the parent must NOT also hold the
-            # lock here — it would self-deadlock while waiting for the child's
-            # READY handshake.
-            if not self._parallel_stage_init:
-                g3_start = time.perf_counter()
-                with self._scoped_spawn_device_env(physical_devices):
-                    lock_fds = acquire_device_locks(
-                        plan.metadata.stage_id,
-                        plan.engine_args_dict,
-                        stage_init_timeout,
-                    )
-                logger.debug(
-                    "[stage_init] Stage-%s G3 device-lock acquire took %.3fs",
-                    plan.metadata.stage_id,
-                    time.perf_counter() - g3_start,
-                )
-
-            launch_cm = launch_stage_replica(
-                vllm_config=vllm_config,
-                executor_class=executor_class,
-                log_stats=self._log_stats,
-                stage_id=plan.metadata.stage_id,
-                replica_id=plan.replica_id,
-                stage_config=plan.stage_cfg,
-                omni_master_server=self._get_omni_master_server(),
-                omni_coordinator_address=self._get_coordinator_address(),
-                stage_visible_devices=physical_devices,
-                spawn_device_lock=self._spawn_device_lock,
-                omni_parallel_stage_init=self._parallel_stage_init,
-            )
-            # Only process spawning and the runtime.env overlay need the global
-            # launch lock. The launch context's exit waits for READY: holding the
-            # lock there serializes model loading and compilation even across
-            # different GPUs. Default initialization keeps its per-device EX
-            # locks until READY; parallel_stage_init uses child phase locks.
-            g2_start = time.perf_counter()
-            with ExitStack() as launch_stack:
-                with self._replica_launch_lock:
-                    g2_locked = time.perf_counter()
-                    with stage_runtime_env(plan.metadata.stage_id, plan.metadata.runtime_cfg):
-                        resources = launch_stack.enter_context(launch_cm)
-                g2_spawned = time.perf_counter()
-            logger.debug(
-                "[stage_init] Stage-%s G2 launch-lock wait=%.3fs, spawn=%.3fs, READY=%.3fs",
-                plan.metadata.stage_id,
-                g2_locked - g2_start,
-                g2_spawned - g2_locked,
-                time.perf_counter() - g2_spawned,
+        external_addresses = self._get_external_client_addresses(
+            plan.metadata.stage_id,
+            plan.replica_id,
+        )
+        if external_addresses is not None:
+            if plan.stage_vllm_config is None or plan.executor_class is None:
+                raise RuntimeError(f"LLM stage {plan.metadata.stage_id} is missing its engine configuration")
+            return cast(
+                StagePoolClient,
+                StageEngineCoreClientBase.make_async_mp_client(
+                    vllm_config=plan.stage_vllm_config,
+                    executor_class=plan.executor_class,
+                    log_stats=self._log_stats,
+                    metadata=plan.metadata,
+                    client_addresses=external_addresses,
+                    client_count=self._client_count,
+                    client_index=self._client_index,
+                ),
             )
 
-            logger.info("[StageRuntime] Stage %s engine startup completed", plan.metadata.stage_id)
-            if resources is None:
-                raise RuntimeError(f"LLM stage {plan.metadata.stage_id} launcher returned no resources")
-            if resources.addresses is None:
-                raise RuntimeError(f"LLM stage {plan.metadata.stage_id} launcher returned no addresses")
-            stage_client = StageEngineCoreClientBase.make_async_mp_client(
-                vllm_config=vllm_config,
-                executor_class=executor_class,
-                log_stats=self._log_stats,
-                metadata=plan.metadata,
-                client_addresses=self._client_addresses_from_zmq(resources.addresses),
-                engine_manager=resources.manager,
-                coordinator=resources.coordinator,
+        if plan.stage_vllm_config is None or plan.executor_class is None:
+            raise RuntimeError(f"LLM stage {plan.metadata.stage_id} is missing its engine configuration")
+        stage_plan = LogicalStageInitPlan(
+            stage_idx=plan.metadata.stage_id,
+            stage_id=plan.metadata.stage_id,
+            replicas=[plan],
+        )
+        with self.launch_stage_engines(
+            stage_plans=[stage_plan],
+            stage_init_timeout=stage_init_timeout,
+        ) as launch:
+            resources = launch.resources[0]
+            return cast(
+                StagePoolClient,
+                StageEngineCoreClientBase.make_async_mp_client(
+                    vllm_config=plan.stage_vllm_config,
+                    executor_class=plan.executor_class,
+                    log_stats=self._log_stats,
+                    metadata=plan.metadata,
+                    client_addresses=self._client_addresses_from_zmq(resources.addresses),
+                    engine_manager=resources.manager,
+                    coordinator=resources.coordinator,
+                ),
             )
 
-            logger.info("[StageRuntime] Stage %s initialized", plan.metadata.stage_id)
-            return cast(StagePoolClient, stage_client)
-        except Exception:
-            if stage_client is not None:
-                try:
-                    stage_client.shutdown()
-                except Exception as cleanup_error:
-                    logger.warning(
-                        "[StageRuntime] Failed to cleanup stage %s after init failure: %s",
-                        plan.metadata.stage_id,
-                        cleanup_error,
-                    )
-            else:
-                self._cleanup_launched_resources(
-                    stage_id=plan.metadata.stage_id,
-                    resources=resources,
-                )
-            raise
-        finally:
-            if lock_fds:
-                release_device_locks(lock_fds)
-
     def _get_coordinator_address(self) -> str | None:
         """Return coordinator router address. Overridden by DistStageRuntime."""
         return None
 
+    def _get_external_client_addresses(self, stage_id: int, replica_id: int) -> dict[str, Any] | None:
+        if self._external_stage_addresses is None:
+            return None
+        stage_addresses = self._external_stage_addresses.get(stage_id)
+        if stage_addresses is None:
+            stage_addresses = self._external_stage_addresses.get(str(stage_id))
+        if stage_addresses is None:
+            raise ValueError(f"Missing external addresses for stage {stage_id}")
+        replica_addresses = stage_addresses.get(replica_id)
+        if replica_addresses is None:
+            replica_addresses = stage_addresses.get(str(replica_id))
+        if replica_addresses is None:
+            raise ValueError(f"Missing external addresses for stage {stage_id} replica {replica_id}")
+        return dict(replica_addresses)
+
     def _get_omni_master_server(self) -> OmniMasterServer | None:
         """Return the master server for local distributed launches, if any."""
         return None
@@ -991,7 +1188,7 @@ def __init__(
         self,
         stage_configs: list[Any],
         model: str,
-        config_path: str,
+        config_path: str | None,
         *,
         stage_init_timeout: int,
         async_chunk: bool,
@@ -1324,7 +1521,7 @@ def _create_remote_replica_client(
 def create_stage_runtime(
     stage_configs: list[Any],
     model: str,
-    config_path: str,
+    config_path: str | None,
     *,
     single_stage_mode: bool,
     stage_init_timeout: int,
@@ -1340,6 +1537,7 @@ def create_stage_runtime(
     omni_lb_policy: str = "random",
     request_queue: janus.Queue[EngineQueueMessage] | None = None,
     log_stats: bool = False,
+    client_config: OmniClientConfig | None = None,
 ) -> StageRuntime:
     """Factory: select StageRuntime or DistStageRuntime."""
     if single_stage_mode:
@@ -1371,4 +1569,5 @@ def create_stage_runtime(
         tokenizer=tokenizer,
         parallel_stage_init=parallel_stage_init,
         log_stats=log_stats,
+        client_config=client_config,
     )
diff --git a/vllm_omni/entrypoints/cli/serve.py b/vllm_omni/entrypoints/cli/serve.py
index a35f062023e..493f2533e7b 100644
--- a/vllm_omni/entrypoints/cli/serve.py
+++ b/vllm_omni/entrypoints/cli/serve.py
@@ -8,13 +8,16 @@
 diffusion models (e.g., Qwen-Image) through the same CLI interface.
 """
 
+from __future__ import annotations
+
 import argparse
+import contextlib
 import json
 import math
 import os
 import signal
 from types import FrameType
-from typing import Any, cast
+from typing import TYPE_CHECKING, Any, cast
 
 import uvloop
 from vllm.entrypoints.cli.types import CLISubcommand
@@ -23,10 +26,18 @@
 from vllm.logger import init_logger
 
 from vllm_omni.entrypoints.cli.logo import log_logo
-from vllm_omni.entrypoints.openai.api_server import omni_run_server
-from vllm_omni.entrypoints.utils import parse_stage_overrides
+from vllm_omni.entrypoints.openai.api_server import (
+    omni_run_server,
+    run_omni_api_server_worker_proc,
+)
+from vllm_omni.entrypoints.utils import parse_stage_overrides, prepare_stage_config_inputs
 from vllm_omni.utils.tracking_parser import TrackingArgumentParser, TrackingNamespace
 
+if TYPE_CHECKING:
+    from vllm.v1.utils import APIServerProcessManager
+
+    from vllm_omni.engine.stage_runtime import StageEngineLaunch, StageRuntime
+
 logger = init_logger(__name__)
 
 DESCRIPTION = """Launch a local OpenAI-compatible API server to serve Omni models
@@ -141,6 +152,8 @@ def cmd(args: TrackingNamespace) -> None:
 
         if args.headless:
             run_headless(args)
+        elif (getattr(args, "api_server_count", None) or 1) > 1:
+            run_multi_api_server_omni(args)
         else:
             uvloop.run(omni_run_server(args))
 
@@ -198,6 +211,39 @@ def validate(self, args: argparse.Namespace) -> None:
         if getattr(args, "omni_replica_address", None) is not None and not args.headless:
             raise ValueError("--omni-replica-address requires --headless to be set")
 
+        api_server_count = getattr(args, "api_server_count", None)
+        if api_server_count is not None and api_server_count < 1 and not args.headless:
+            raise ValueError("--api-server-count must be >= 1 unless --headless is set")
+        if args.headless and api_server_count is not None and api_server_count > 0:
+            raise ValueError("--api-server-count cannot be used with --headless")
+        if api_server_count is not None and api_server_count > 1:
+            distributed_args = (
+                "stage_id",
+                "omni_master_address",
+                "omni_master_port",
+                "omni_replica_address",
+            )
+            if any(getattr(args, name, None) is not None for name in distributed_args):
+                raise ValueError(
+                    "--api-server-count > 1 cannot be combined with stage-based "
+                    "or distributed stage arguments (--stage-id/--omni-master-* / "
+                    "--omni-replica-address)"
+                )
+            if getattr(args, "omni_dp_size_local", 1) != 1:
+                raise ValueError("--api-server-count > 1 requires --omni-dp-size-local=1")
+            if getattr(args, "worker_backend", "multi_process") != "multi_process":
+                raise ValueError("--api-server-count > 1 requires --worker-backend=multi_process")
+            if getattr(args, "enable_fault_tolerance", False):
+                raise ValueError("--api-server-count > 1 cannot be combined with --enable-fault-tolerance")
+            if getattr(args, "enable_elastic_ep", False):
+                raise ValueError("--api-server-count > 1 cannot be combined with --enable-elastic-ep")
+            if getattr(args, "enable_sleep_mode", False):
+                raise ValueError("--api-server-count > 1 cannot be combined with --enable-sleep-mode")
+            from vllm import envs as vllm_envs
+
+            if getattr(vllm_envs, "VLLM_ALLOW_RUNTIME_LORA_UPDATING", False):
+                raise ValueError("--api-server-count > 1 cannot be combined with VLLM_ALLOW_RUNTIME_LORA_UPDATING")
+
         # --omni-dp-size-local is process-local. A value other than 1 only
         # makes sense when this process owns a stage (head or headless).
         omni_dp_size_local = getattr(args, "omni_dp_size_local", None)
@@ -221,7 +267,6 @@ def validate(self, args: argparse.Namespace) -> None:
                 "data_parallel_rpc_port": "--data-parallel-rpc-port",
                 "data_parallel_start_rank": "--data-parallel-start-rank",
                 "data_parallel_backend": "--data-parallel-backend",
-                "api_server_count": "--api-server-count",
                 "enable_expert_parallel": "--enable-expert-parallel",
             }
             offenders = sorted(flag for dest, flag in prohibited_with_omni.items() if dest in explicit_cli_keys)
@@ -261,6 +306,8 @@ def validate(self, args: argparse.Namespace) -> None:
 
         model = getattr(args, "model_tag", None) or getattr(args, "model", None)
         if model and is_diffusion_model(model):
+            if api_server_count is not None and api_server_count > 1:
+                raise ValueError("--api-server-count > 1 is not supported for diffusion models")
             logger.info("Detected diffusion model: %s", model)
             return
         validate_parsed_serve_args(args)
@@ -1027,6 +1074,207 @@ def subparser_init(self, subparsers: argparse._SubParsersAction) -> TrackingArgu
         return serve_parser
 
 
+def _build_multi_api_stage_runtime(args: TrackingNamespace, num_api_servers: int) -> StageRuntime:
+    """Resolve the local EngineCore stages that the parent process owns."""
+    from vllm_omni.config.resolver import resolve_omni_config
+    from vllm_omni.engine.stage_runtime import StageRuntime
+
+    kwargs = args.get_explicit_kwargs_dict()
+    model = kwargs.pop("model", None) or args.model
+
+    trust_remote_code = kwargs.get("trust_remote_code")
+    if trust_remote_code is False:
+        trust_remote_code = None
+    config_inputs = prepare_stage_config_inputs(
+        model,
+        kwargs,
+        trust_remote_code=trust_remote_code,
+        snapshot_model=True,
+    )
+    model = config_inputs.model
+    kwargs = config_inputs.kwargs
+    resolved = resolve_omni_config(
+        model,
+        cli_overrides=kwargs,
+        trust_remote_code=config_inputs.trust_remote_code,
+        deploy_config_path=config_inputs.deploy_config_path,
+        stage_overrides=config_inputs.stage_overrides,
+        strategy_config_path=config_inputs.strategy_config_path,
+    )
+
+    config_path = resolved.config_path
+    stage_configs = list(resolved.stage_configs)
+
+    sleep_stages = [
+        int(getattr(stage_config, "stage_id", stage_index))
+        for stage_index, stage_config in enumerate(stage_configs)
+        if bool(
+            getattr(
+                getattr(stage_config, "model_config", getattr(stage_config, "engine_args", None)),
+                "enable_sleep_mode",
+                False,
+            )
+        )
+    ]
+    if sleep_stages:
+        raise ValueError(
+            "--api-server-count > 1 cannot be combined with sleep mode; "
+            f"disable enable_sleep_mode for stage(s) {sleep_stages}"
+        )
+
+    async_chunk = any(
+        bool(
+            getattr(
+                getattr(stage, "connector_config", None),
+                "async_chunk",
+                getattr(getattr(stage, "engine_args", None), "async_chunk", False),
+            )
+        )
+        for stage in stage_configs
+    )
+    return StageRuntime(
+        stage_configs=stage_configs,
+        model=model,
+        config_path=config_path,
+        stage_init_timeout=int(getattr(args, "stage_init_timeout", 300)),
+        parallel_stage_init=bool(getattr(args, "parallel_stage_init", False)),
+        async_chunk=async_chunk,
+        tokenizer=getattr(args, "tokenizer", None),
+        log_stats=not bool(getattr(args, "disable_log_stats", False)),
+    )
+
+
+def _wait_for_multi_api_server_completion(
+    api_server_manager: APIServerProcessManager,
+    engine_launch: StageEngineLaunch,
+) -> None:
+    """Wait until API workers complete or any shared stage engine fails."""
+    from multiprocessing import connection
+
+    api_processes = list(api_server_manager.processes)
+    engine_processes = [
+        process
+        for resources in engine_launch.resources
+        if resources.manager is not None
+        for process in resources.manager.processes
+    ]
+    api_by_sentinel = {process.sentinel: process for process in api_processes}
+    engine_by_sentinel = {process.sentinel: process for process in engine_processes}
+
+    while api_by_sentinel:
+        ready = connection.wait([*api_by_sentinel, *engine_by_sentinel])
+        for sentinel in ready:
+            if sentinel in engine_by_sentinel:
+                process = engine_by_sentinel[sentinel]
+                raise RuntimeError(
+                    f"Shared stage engine process {process.name} (PID: {process.pid}) "
+                    f"exited with code {process.exitcode}"
+                )
+            process = api_by_sentinel.pop(sentinel)
+            if process.exitcode != 0:
+                raise RuntimeError(
+                    f"API server process {process.name} (PID: {process.pid}) exited with code {process.exitcode}"
+                )
+
+
+def _start_api_server_process_manager(
+    *,
+    cleanup_timeout: float,
+    **manager_kwargs: object,
+) -> APIServerProcessManager:
+    """Construct vLLM's manager with rollback for a partial ``__init__``.
+
+    ``APIServerProcessManager`` starts workers one by one in ``__init__`` and
+    installs its finalizer only after every ``Process.start`` succeeds. Keep a
+    reference to the partially initialized object so workers started before a
+    later failure are still terminated.
+    """
+    from vllm.v1.utils import APIServerProcessManager, shutdown
+
+    manager = APIServerProcessManager.__new__(APIServerProcessManager)
+    try:
+        APIServerProcessManager.__init__(manager, **manager_kwargs)
+    except BaseException:
+        try:
+            for pipe in getattr(manager, "_address_pipes", ()):
+                with contextlib.suppress(Exception):
+                    pipe.close()
+            # A Process whose start() raised is still present in the upstream
+            # manager's list, but calling is_alive() on it raises because it
+            # has no Popen object. Only hand successfully started children to
+            # vLLM's shutdown helper.
+            started_processes = [process for process in getattr(manager, "processes", ()) if process.pid is not None]
+            if started_processes:
+                shutdown(started_processes, timeout=cleanup_timeout)
+        except Exception:
+            logger.exception("Failed to clean up partially started API server processes")
+        raise
+    return manager
+
+
+def run_multi_api_server_omni(args: TrackingNamespace) -> None:
+    """Launch API subprocesses that share one set of local stage engines."""
+    from vllm.entrypoints.openai.api_server import setup_server
+    from vllm.v1.metrics.prometheus import setup_multiprocess_prometheus
+
+    num_api_servers = int(args.api_server_count)
+    if num_api_servers < 2:
+        raise ValueError(f"api_server_count must be >= 2, got {num_api_servers}")
+
+    setup_multiprocess_prometheus()
+    shutdown_requested = False
+
+    def signal_handler(signum: int, frame: FrameType | None) -> None:
+        nonlocal shutdown_requested
+        logger.debug("Received %d signal.", signum)
+        if not shutdown_requested:
+            shutdown_requested = True
+            raise SystemExit
+
+    signal.signal(signal.SIGTERM, signal_handler)
+    signal.signal(signal.SIGINT, signal_handler)
+
+    listen_address, sock = setup_server(args, reuse_port=True)
+    stage_runtime = None
+    api_server_manager = None
+    engine_launch = None
+    try:
+        stage_runtime = _build_multi_api_stage_runtime(args, num_api_servers)
+        with stage_runtime.launch_stage_engines(num_api_servers) as engine_launch:
+            args._omni_stage_client_configs = engine_launch.client_configs
+            primary_addresses = engine_launch.resources[0].addresses
+            if primary_addresses is None:
+                raise RuntimeError("Primary stage engine returned no addresses")
+            timeout = float(getattr(args, "shutdown_timeout", 5) or 5)
+            api_server_manager = _start_api_server_process_manager(
+                cleanup_timeout=timeout,
+                listen_address=listen_address,
+                sock=sock,
+                args=args,
+                num_servers=num_api_servers,
+                input_addresses=primary_addresses.inputs,
+                output_addresses=primary_addresses.outputs,
+                target_server_fn=run_omni_api_server_worker_proc,
+            )
+            engine_launch.watched_frontend_processes.extend(api_server_manager.processes)
+            actual_inputs, actual_outputs = api_server_manager.gather_actual_addresses()
+            primary_addresses.inputs = actual_inputs
+            primary_addresses.outputs = actual_outputs
+
+        _wait_for_multi_api_server_completion(api_server_manager, engine_launch)
+    finally:
+        timeout = float(getattr(args, "shutdown_timeout", 5) or 5)
+        if api_server_manager is not None:
+            api_server_manager.shutdown(timeout=timeout)
+        if engine_launch is not None:
+            engine_launch.shutdown()
+        if stage_runtime is not None:
+            stage_runtime.shutdown()
+        sock.close()
+        if shutdown_requested:
+            logger.info("Shared API server shutdown completed")
+
+
 def run_headless(args: TrackingNamespace) -> None:
     """Run a single stage in headless mode.
 
@@ -1075,15 +1323,6 @@ def run_headless(args: TrackingNamespace) -> None:
 
     # Filter down to a dict of things explicitly requested by the user
     args_dict = args.get_explicit_kwargs_dict()
-    # This controls only the API-process WebSocket and is not a stage-engine option.
-    args_dict.pop("robot_openpi_idle_timeout", None)
-    # This CLI-only negative alias is consumed below when selecting the
-    # launcher log_stats value; it is not a per-stage config override.
-    args_dict.pop("disable_log_stats", None)
-
-    deploy_config_path = args_dict.pop("deploy_config", None)
-    strategy_config_path = args_dict.pop("strategy_config", None)
-    stage_overrides = args_dict.pop("stage_overrides", None)
 
     # ``--replica-id`` is deprecated and ignored — replica ids are
     # auto-assigned by ``OmniMasterServer`` so headless processes carry
@@ -1099,15 +1338,21 @@ def run_headless(args: TrackingNamespace) -> None:
         )
         args_dict.pop("replica_id")
 
-    resolved = resolve_omni_config(
+    config_inputs = prepare_stage_config_inputs(
         model,
+        args_dict,
         # store_true cannot express an explicit False: absent maps to None
         # ("not specified") so the deploy yaml's per-stage value applies.
         trust_remote_code=getattr(args, "trust_remote_code", None) or None,
+    )
+    args_dict = config_inputs.kwargs
+    resolved = resolve_omni_config(
+        model,
+        trust_remote_code=config_inputs.trust_remote_code,
         cli_overrides=args_dict,
-        deploy_config_path=deploy_config_path,
-        stage_overrides=stage_overrides,
-        strategy_config_path=strategy_config_path,
+        deploy_config_path=config_inputs.deploy_config_path,
+        stage_overrides=config_inputs.stage_overrides,
+        strategy_config_path=config_inputs.strategy_config_path,
     )
     config_path = resolved.config_path
     stage_configs = list(resolved.stage_configs)
diff --git a/vllm_omni/entrypoints/openai/api_server.py b/vllm_omni/entrypoints/openai/api_server.py
index 20706396c0e..94f1ab51302 100644
--- a/vllm_omni/entrypoints/openai/api_server.py
+++ b/vllm_omni/entrypoints/openai/api_server.py
@@ -6,6 +6,7 @@
 and route bodies that have not yet moved to endpoint-owned modules."""
 
 import asyncio
+import copy
 import dataclasses
 import json
 import multiprocessing
@@ -14,6 +15,8 @@
 
 # Image generation API imports
 import random
+import signal
+import socket
 import time
 from argparse import Namespace
 from collections.abc import AsyncIterator
@@ -22,6 +25,7 @@
 from pathlib import Path
 from typing import Annotated, Any, Literal
 
+import uvloop
 import vllm.envs as envs
 from fastapi import APIRouter, Depends, File, Form, HTTPException, Query, Request, UploadFile, WebSocket
 from fastapi.responses import FileResponse, JSONResponse, Response, StreamingResponse
@@ -81,12 +85,14 @@
 from vllm.tasks import POOLING_TASKS
 from vllm.tool_parsers import ToolParserManager
 from vllm.utils import random_uuid
-from vllm.utils.system_utils import decorate_logs
+from vllm.utils.system_utils import decorate_logs, set_process_title
 from vllm.v1.engine.exceptions import EngineDeadError, EngineGenerateError
 
 from vllm_omni.config.endpoint_policy import (
     shutdown_unsupported_routes,
 )
+from vllm_omni.engine.stage_init_utils import set_death_signal
+from vllm_omni.engine.stage_runtime import OmniClientConfig
 from vllm_omni.entrypoints.async_omni import ABORT_TIMEOUT_S, AsyncOmni
 from vllm_omni.entrypoints.duplex.serving import OmniDuplexSessionHandler
 from vllm_omni.entrypoints.duplex.warmup import _warmup_duplex_realtime
@@ -232,8 +238,55 @@ async def omni_run_server(args, **uvicorn_kwargs) -> None:
     await omni_run_server_worker(listen_address, sock, args, **uvicorn_kwargs)
 
 
-async def omni_run_server_worker(listen_address, sock, args, client_config=None, **uvicorn_kwargs) -> None:
+def run_omni_api_server_worker_proc(
+    listen_address: str,
+    sock: socket.socket,
+    args: TrackingNamespace,
+    client_config: dict[str, Any] | None = None,
+    **uvicorn_kwargs: object,
+) -> None:
+    """Entrypoint used by vLLM's API server process manager."""
+    set_death_signal(signal.SIGTERM)
+    manager_config = client_config or {}
+    client_index = int(manager_config.get("client_index", 0))
+    all_client_configs = getattr(args, "_omni_stage_client_configs", None)
+    if not all_client_configs or not 0 <= client_index < len(all_client_configs):
+        raise RuntimeError(f"Missing Omni stage client configuration for API server {client_index}")
+
+    omni_client_config: OmniClientConfig = copy.deepcopy(all_client_configs[client_index])
+    omni_client_config["client_count"] = int(manager_config.get("client_count", 1))
+    omni_client_config["client_index"] = client_index
+
+    stage_addresses = omni_client_config["stage_addresses"]
+    first_stage_id = min(stage_addresses)
+    first_replica_id = min(stage_addresses[first_stage_id])
+    first_addresses = stage_addresses[first_stage_id][first_replica_id]
+    for key in ("input_address", "output_address", "actual_address_pipe", "tensor_queue"):
+        if key in manager_config:
+            first_addresses[key] = manager_config[key]
+
+    set_process_title("APIServer", str(client_index))
+    decorate_logs("APIServer", skip_if_decorated=True)
+    uvloop.run(
+        omni_run_server_worker(
+            listen_address,
+            sock,
+            args,
+            client_config=omni_client_config,
+            **uvicorn_kwargs,
+        )
+    )
+
+
+async def omni_run_server_worker(
+    listen_address: str,
+    sock: socket.socket,
+    args: TrackingNamespace,
+    client_config: OmniClientConfig | None = None,
+    **uvicorn_kwargs: object,
+) -> None:
     """Run a single API server worker."""
+    api_server_count = _resolve_api_server_count(args, client_config)
 
     if args.tool_parser_plugin and len(args.tool_parser_plugin) > 3:
         ToolParserManager.import_tool_parser(args.tool_parser_plugin)
@@ -273,6 +326,7 @@ async def omni_run_server_worker(listen_address, sock, args, client_config=None,
 
         # OMNI: Pass supported_tasks to build_app (required by upstream vLLM)
         app = build_openai_app(args, supported_tasks)
+        app.state.api_server_count = api_server_count
 
         # OMNI: Remove upstream routes that we override with omni-specific handlers
         remove_route_from_app(app, "/v1/chat/completions", {"POST"})
@@ -348,6 +402,7 @@ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
                 if scope["type"] == "http":
                     scope.setdefault("state", {})
                     scope["state"]["request_timestamp"] = time.time()
+
                 await self._inner(scope, receive, send)
 
         # Startup duplex warmup (duplex_session.warmup_frames in the deploy
@@ -406,7 +461,7 @@ async def build_async_omni(
     args: TrackingNamespace,
     *,
     disable_frontend_multiprocessing: bool | None = None,
-    client_config: dict[str, Any] | None = None,
+    client_config: OmniClientConfig | None = None,
 ) -> AsyncIterator[EngineClient]:
     """Build an AsyncOmni instance from command-line arguments.
 
@@ -437,6 +492,7 @@ async def build_async_omni(
     async with build_async_omni_from_stage_config(
         args,
         disable_frontend_multiprocessing=disable_frontend_multiprocessing,
+        client_config=client_config,
     ) as async_omni:
         yield async_omni
 
@@ -476,6 +532,7 @@ async def build_async_omni_from_stage_config(
     args: TrackingNamespace,
     *,
     disable_frontend_multiprocessing: bool = False,
+    client_config: OmniClientConfig | None = None,
 ) -> AsyncIterator[EngineClient]:
     """Create AsyncOmni from stage configuration.
 
@@ -532,6 +589,8 @@ async def build_async_omni_from_stage_config(
         kwargs.pop("robot_openpi_idle_timeout", None)
         model = kwargs.pop("model", None) or args.model
         kwargs.setdefault("log_stats", not args.disable_log_stats)
+        if client_config is not None:
+            kwargs["client_config"] = client_config
         if _should_serve_duplex(model, kwargs):
             async_omni = DuplexOmni(model=model, **kwargs)
         else:
@@ -1430,6 +1489,42 @@ async def list_voices(raw_request: Request):
     return JSONResponse(content={"voices": speakers, "uploaded_voices": uploaded_speakers})
 
 
+def _resolve_api_server_count(args: Namespace, client_config: OmniClientConfig | None) -> int:
+    """Resolve frontend topology once, from the launcher's client configuration."""
+    requested = getattr(args, "api_server_count", None)
+    actual = 1 if client_config is None else client_config.get("client_count")
+    if type(actual) is not int or actual < 1:
+        raise ValueError("API client configuration requires a positive integer client_count")
+    if requested is not None and (type(requested) is not int or requested < 1 or requested != actual):
+        raise ValueError("API server count does not match the frontend launch configuration")
+    return actual
+
+
+def _reject_process_local_state_with_multiple_api_workers(raw_request: Request, operation: str) -> None:
+    """Reject access to frontend state that is not shared across API workers."""
+    api_server_count = getattr(raw_request.app.state, "api_server_count", None)
+    if type(api_server_count) is not int or api_server_count < 1:
+        raise HTTPException(
+            status_code=HTTPStatus.SERVICE_UNAVAILABLE.value,
+            detail="API worker topology is not initialized.",
+        )
+    if api_server_count > 1:
+        raise HTTPException(
+            status_code=HTTPStatus.CONFLICT.value,
+            detail=(
+                f"{operation} is not supported with --api-server-count > 1 because "
+                "the operation uses process-local frontend state"
+            ),
+        )
+
+
+async def _require_single_api_video_store(raw_request: Request) -> None:
+    # VIDEO_STORE and VIDEO_TASKS are process-local, including reads and
+    # cancellation. Keep this independent of the temporary diffusion launch
+    # restriction: enabling multi-API diffusion alone cannot make jobs shared.
+    _reject_process_local_state_with_multiple_api_workers(raw_request, "Asynchronous video jobs")
+
+
 @router.post(
     "/v1/audio/voices",
     responses={
@@ -1475,6 +1570,7 @@ async def upload_voice(
     Returns:
         JSON response with voice information
     """
+    _reject_process_local_state_with_multiple_api_workers(raw_request, "Runtime voice upload")
     handler = Omnispeech(raw_request)
     if handler is None:
         return _create_speech_error_json_response(
@@ -1540,6 +1636,7 @@ async def delete_voice(name: str, raw_request: Request):
     Returns:
         JSON response indicating success or failure
     """
+    _reject_process_local_state_with_multiple_api_workers(raw_request, "Runtime voice deletion")
     handler = Omnispeech(raw_request)
     if handler is None:
         return _create_speech_error_json_response(
@@ -1633,13 +1730,15 @@ async def streaming_video_output(websocket: WebSocket):
 @router.websocket("/v1/realtime")
 async def realtime_websocket(websocket: WebSocket):
     """WebSocket endpoint for OpenAI-style realtime interactions."""
-    await _wait_for_duplex_warmup(websocket)
     duplex_handler = getattr(websocket.app.state, "openai_serving_duplex", None)
     duplex_query = websocket.query_params.get("duplex")
     use_duplex_realtime = duplex_handler is not None and (
         duplex_query is None or (isinstance(duplex_query, str) and duplex_query.lower() in {"1", "true", "on"})
     )
     if use_duplex_realtime and duplex_handler is not None:
+        if await _reject_multi_api_duplex(websocket):
+            return
+        await _wait_for_duplex_warmup(websocket)
         await duplex_handler.handle_realtime_session(websocket)
         return
 
@@ -1669,6 +1768,8 @@ async def _wait_for_duplex_warmup(websocket: WebSocket) -> None:
 @router.websocket("/v1/duplex")
 async def duplex_websocket(websocket: WebSocket):
     """Alias of ``/v1/realtime?duplex=1``: the same Realtime duplex session protocol."""
+    if await _reject_multi_api_duplex(websocket):
+        return
     await _wait_for_duplex_warmup(websocket)
     handler = getattr(websocket.app.state, "openai_serving_duplex", None)
     if handler is None:
@@ -1709,6 +1810,24 @@ async def realtime_robot_openpi(websocket: WebSocket):
     await connection.handle_connection()
 
 
+async def _reject_multi_api_duplex(websocket: WebSocket) -> bool:
+    # Session credentials and replay state are local to each frontend; a shared
+    # listening socket cannot route reconnects back to the session owner.
+    count = getattr(websocket.app.state, "api_server_count", None)
+    if count is None or (type(count) is int and count == 1):
+        return False
+    await websocket.accept()
+    await websocket.send_json(
+        {
+            "type": "error",
+            "error": "Duplex sessions require a single API worker with initialized topology.",
+            "code": "multi_api_duplex_unsupported",
+        }
+    )
+    await websocket.close(code=1008)
+    return True
+
+
 # RL Rollout serving (RFC #3747, P0)
 
 
@@ -2476,6 +2595,7 @@ async def edit_images(
 
 @router.post(
     "/v1/videos",
+    dependencies=[Depends(_require_single_api_video_store)],
     responses={
         HTTPStatus.OK.value: {"model": VideoResponse},
         HTTPStatus.BAD_REQUEST.value: {"model": ErrorResponse},
@@ -2617,7 +2737,7 @@ async def create_video_sync(
     )
 
 
-@router.get("/v1/videos", response_model=VideoListResponse)
+@router.get("/v1/videos", response_model=VideoListResponse, dependencies=[Depends(_require_single_api_video_store)])
 async def list_videos(
     after: str | None = None,
     limit: int | None = Query(None, ge=0, le=100),
@@ -2654,7 +2774,7 @@ async def list_videos(
     return VideoListResponse(data=jobs, has_more=has_more, first_id=first_id, last_id=last_id)
 
 
-@router.get("/v1/videos/{video_id}", response_model=None)
+@router.get("/v1/videos/{video_id}", response_model=None, dependencies=[Depends(_require_single_api_video_store)])
 async def retrieve_video(video_id: str) -> VideoResponse | JSONResponse:
     """Retrieve metadata for a previously created video job.
 
@@ -2682,7 +2802,7 @@ async def retrieve_video(video_id: str) -> VideoResponse | JSONResponse:
     return job
 
 
-@router.delete("/v1/videos/{video_id}")
+@router.delete("/v1/videos/{video_id}", dependencies=[Depends(_require_single_api_video_store)])
 async def delete_video(video_id: str, raw_request: Request) -> VideoDeleteResponse:
     """Delete a stored video job and any generated output.
 
@@ -2752,7 +2872,7 @@ async def delete_video(video_id: str, raw_request: Request) -> VideoDeleteRespon
     return VideoDeleteResponse(id=job.id, deleted=True)
 
 
-@router.get("/v1/videos/{video_id}/content")
+@router.get("/v1/videos/{video_id}/content", dependencies=[Depends(_require_single_api_video_store)])
 async def download_video(video_id: str) -> Response:
     """Download the generated file for a completed video job.
 
@@ -2845,6 +2965,7 @@ async def stop_profile(raw_request: Request, request: ProfileRequest | None = No
 
 @router.post("/v1/omni/sleep")
 async def omni_sleep(request: OmniSleepRequest, raw_request: Request):
+    _reject_process_local_state_with_multiple_api_workers(raw_request, "Sleep")
     engine_client = raw_request.app.state.engine_client
     sleeping_set = raw_request.app.state.sleeping_stages
     if not hasattr(engine_client, "sleep"):
@@ -2857,6 +2978,7 @@ async def omni_sleep(request: OmniSleepRequest, raw_request: Request):
 
 @router.post("/v1/omni/wakeup")
 async def omni_wakeup(request: OmniWakeupRequest, raw_request: Request):
+    _reject_process_local_state_with_multiple_api_workers(raw_request, "Wakeup")
     engine_client = raw_request.app.state.engine_client
     sleeping_set = raw_request.app.state.sleeping_stages
     if not any(sid in sleeping_set for sid in request.stage_ids):
diff --git a/vllm_omni/entrypoints/utils.py b/vllm_omni/entrypoints/utils.py
index 74234d8d67b..c091ae5e8c9 100644
--- a/vllm_omni/entrypoints/utils.py
+++ b/vllm_omni/entrypoints/utils.py
@@ -4,12 +4,14 @@
 import json
 import os
 import types
-from dataclasses import fields, is_dataclass
+from collections.abc import Mapping
+from dataclasses import dataclass, fields, is_dataclass
 from typing import Any, get_args, get_origin
 
 from vllm.logger import init_logger
 from vllm.sampling_params import RequestOutputKind, SamplingParams
 
+from vllm_omni.config.config_factory import with_trust_remote_code_override
 from vllm_omni.entrypoints.stage_utils import _to_dict
 from vllm_omni.inputs.data import OmniSamplingParams
 
@@ -86,6 +88,64 @@ def parse_stage_overrides(value: Any) -> dict[str, dict[str, Any]] | None:
     return parsed
 
 
+@dataclass(frozen=True)
+class StageConfigInputs:
+    """Normalized inputs shared by all stage-config loading paths."""
+
+    model: str
+    kwargs: dict[str, Any]
+    trust_remote_code: bool | None
+    deploy_config_path: str | None
+    stage_overrides: dict[str, dict[str, Any]] | None
+    strategy_config_path: str | None
+
+
+def prepare_stage_config_inputs(
+    model: str,
+    kwargs: Mapping[str, Any],
+    *,
+    trust_remote_code: bool | None,
+    snapshot_model: bool = False,
+) -> StageConfigInputs:
+    """Normalize model/config arguments before resolving stage configs.
+
+    The standard API worker, multi-API parent, and headless entrypoint must
+    apply the same legacy-key filtering, trust-remote-code precedence, and
+    config-file extraction before calling :func:`resolve_omni_config`.
+    """
+    resolved_model = model
+    if snapshot_model:
+        # Keep model materialization at the CLI boundary for the parent-owned
+        # launch path. The API worker's OmniBase has already done this work.
+        from vllm_omni.entrypoints.omni_base import omni_snapshot_download
+
+        resolved_model = omni_snapshot_download(model)
+
+    resolved_kwargs = dict(kwargs)
+    for legacy_arg in ("stage_configs_path", "stage_configs"):
+        if legacy_arg in resolved_kwargs:
+            raise ValueError(f"`{legacy_arg}` is no longer supported; use `deploy_config` instead.")
+    # Frontend process count is not a stage engine override.
+    resolved_kwargs.pop("api_server_count", None)
+    resolved_kwargs.pop("disable_log_stats", None)
+    if resolved_kwargs.get("diffusion_streaming_output") and resolved_kwargs.get("streaming_output") is None:
+        resolved_kwargs["streaming_output"] = True
+    resolved_kwargs.pop("model_tag", None)
+
+    resolved_kwargs = with_trust_remote_code_override(resolved_kwargs, trust_remote_code)
+    deploy_config_path = resolved_kwargs.pop("deploy_config", None)
+    strategy_config_path = resolved_kwargs.pop("strategy_config", None)
+    stage_overrides = parse_stage_overrides(resolved_kwargs.pop("stage_overrides", None))
+    return StageConfigInputs(
+        model=resolved_model,
+        kwargs=resolved_kwargs,
+        trust_remote_code=trust_remote_code,
+        deploy_config_path=deploy_config_path,
+        stage_overrides=stage_overrides,
+        strategy_config_path=strategy_config_path,
+    )
+
+
 def get_final_stage_id_for_e2e(
     output_modalities: list[str] | None, default_modalities: list[str], stage_list: list
 ) -> int:
diff --git a/vllm_omni/utils/tracking_parser.py b/vllm_omni/utils/tracking_parser.py
index 64849a5aa09..8e5f5832a07 100644
--- a/vllm_omni/utils/tracking_parser.py
+++ b/vllm_omni/utils/tracking_parser.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 import argparse
 from typing import Any
@@ -52,12 +52,28 @@ def __setattr__(self, name: str, value: Any) -> None:
         else:
             setattr(self.unfiltered_ns, name, value)
 
+    def __getstate__(self) -> dict[str, Any]:
+        """Preserve wrapper state when API workers use ``spawn``.
+
+        Our __dict__ property exposes the inner namespace, so default state
+        serialization would lose unfiltered_ns and explicit_keys.
+        """
+        return {
+            "unfiltered_ns": self.unfiltered_ns,
+            "explicit_keys": self.explicit_keys,
+        }
+
+    def __setstate__(self, state: dict[str, Any]) -> None:
+        object.__setattr__(self, "unfiltered_ns", state["unfiltered_ns"])
+        object.__setattr__(self, "explicit_keys", state["explicit_keys"])
+
     def get_explicit_kwargs_dict(self):
         """Return a dict containing only the explicitly passed key-value pairs."""
         return {k: v for k, v in vars(self.unfiltered_ns).items() if k in self.explicit_keys}
 
     def __getattr__(self, name: str) -> Any:
-        return getattr(self.unfiltered_ns, name)
+        namespace = object.__getattribute__(self, "unfiltered_ns")
+        return getattr(namespace, name)
 
     @property
     def __dict__(self):
diff --git a/vllm_omni/worker/gpu_generation_model_runner.py b/vllm_omni/worker/gpu_generation_model_runner.py
index e43c6f608c8..4d80d3f8d28 100644
--- a/vllm_omni/worker/gpu_generation_model_runner.py
+++ b/vllm_omni/worker/gpu_generation_model_runner.py
@@ -812,7 +812,7 @@ def _dummy_run(
 
             if self.uses_mrope:
                 positions = self.mrope_positions.gpu[:, :num_tokens_padded]
-            elif self.uses_xdrope_dim > 0:
+            elif getattr(self, "uses_xdrope_dim", 0) > 0:
                 positions = self.xdrope_positions.gpu[:, :num_tokens_padded]
             else:
                 positions = self.positions[:num_tokens_padded]
diff --git a/vllm_omni/worker/gpu_model_runner.py b/vllm_omni/worker/gpu_model_runner.py
index d3ee8de02ed..37d2ac12206 100644
--- a/vllm_omni/worker/gpu_model_runner.py
+++ b/vllm_omni/worker/gpu_model_runner.py
@@ -690,7 +690,7 @@ def _update_states(self, scheduler_output: "SchedulerOutput") -> Callable | None
                 self._init_mrope_positions(req_state)
 
             # Only relevant for models using XD-RoPE (e.g, HunYuan-VL)
-            if self.uses_xdrope_dim > 0:
+            if getattr(self, "uses_xdrope_dim", 0) > 0:
                 self._init_xdrope_positions(req_state)
 
             reqs_to_add.append(self.requests[req_id])
@@ -1164,7 +1164,7 @@ def _dummy_run(
 
             if self.uses_mrope:
                 positions = self.mrope_positions.gpu[:, :num_tokens_padded]
-            elif self.uses_xdrope_dim > 0:
+            elif getattr(self, "uses_xdrope_dim", 0) > 0:
                 positions = self.xdrope_positions.gpu[:, :num_tokens_padded]
             else:
                 positions = self.positions[:num_tokens_padded]
@@ -1701,7 +1701,7 @@ def _preprocess(
 
         if self.uses_mrope:
             positions = self.mrope_positions.gpu[:, :num_input_tokens]
-        elif self.uses_xdrope_dim > 0:
+        elif getattr(self, "uses_xdrope_dim", 0) > 0:
             positions = self.xdrope_positions.gpu[:, :num_input_tokens]
         else:
             positions = self.positions[:num_input_tokens]

From 224152566a705dd0347e4b4c3c3e74ce7e19ed8f Mon Sep 17 00:00:00 2001
From: LOGO127 <luozijian0924@gmail.com>
Date: Thu, 17 Sep 2026 14:04:37 +0800
Subject: [PATCH 058/105] [Model][PersonaPlex] Add paced multi-session
 validation (#7428)

Signed-off-by: luozijian <luozijian0924@gmail.com>
---
 docs/design/fullduplex-personaplex.md         | 108 ++++
 .../personaplex_realtime_duplex.py            | 567 ++++++++++++++---
 .../test_personaplex_load_driver.py           | 568 ++++++++++++++++++
 3 files changed, 1155 insertions(+), 88 deletions(-)
 create mode 100644 tests/e2e/online_serving/test_personaplex_load_driver.py

diff --git a/docs/design/fullduplex-personaplex.md b/docs/design/fullduplex-personaplex.md
index 33d125c9716..6d32cd8e3a0 100644
--- a/docs/design/fullduplex-personaplex.md
+++ b/docs/design/fullduplex-personaplex.md
@@ -271,3 +271,111 @@ The required evidence is:
 
 Audio that is empty, all zero, non-finite, or only a protocol `listen` event is
 not a successful end-to-end result.
+
+### Paced multi-session load driver
+
+The existing driver keeps its two-session admission and slot-reuse validation
+when `--sessions` is omitted. Passing `--sessions N` selects a separate,
+bounded load mode; it does not replace the lifecycle test or change server
+admission capacity. Start an existing PersonaPlex server configured to admit
+the requested number of sessions, then run from a source checkout with the
+vLLM-Omni client dependencies installed:
+
+```bash
+python -m tests.e2e.online_serving.personaplex_realtime_duplex \
+  --model nvidia/personaplex-7b-v1 \
+  --input-wav /path/to/input.wav \
+  --sessions 2 --load-frames 1000 --drain-s 2 \
+  --server-revision SERVER_COMMIT --server-hardware A100-80GB \
+  --output-dir /tmp/personaplex-load-n2
+```
+
+Use a new output directory for every run. The driver refuses to overwrite an
+existing `load-result.json`. The server labels are supplied by the operator,
+not detected or verified by the client. Record the server command, package
+versions, checkpoint revision and hardware alongside a published measurement.
+
+All attempted sessions finish admission before admitted sessions share a
+common input start. A rejected session remains a failed row in the report;
+it is not removed from the denominator. Each session receives at most
+`--load-frames` input frames, without looping the WAV, and uses 80 ms pacing.
+A stalled send cannot cause a catch-up burst. The timeline records send
+schedule lateness so an overloaded client is visible rather than mistaken
+for a faster server. This mode measures steady concurrency, not join/leave
+interference; the original lifecycle mode still checks slot reuse.
+Load mode does not probe an additional N+1 session for `resource_exhausted`;
+the lifecycle mode owns that admission-limit check. A per-session
+`client_pacing_warning` and the summary's `client_pacing_warning_sessions`
+identify send-lateness p99 above one nominal frame (80 ms). This is a warning,
+not an extra acceptance gate: read it alongside server-facing measurements
+so a slow client is not mistaken for a slow server.
+
+The fixed drain window is part of the measurement configuration. Audio
+arriving during cleanup is excluded, so closing cannot rescue a session that
+missed its observation deadline. Cleanup is attempted for admitted sessions
+even when audio validation fails. Protocol errors, missing/invalid audio,
+shared response IDs and cleanup failures make the report fail and the CLI
+exit nonzero. Cancellation closes transports and propagates to the caller.
+`--cleanup-timeout-s` (default 5 s) bounds session-close send and acknowledgement
+together, independently of `--timeout-s`. The subsequent WebSocket close
+handshake has the same separate bound; an unresponsive close acknowledgement
+cannot hold cancellation for the full inference timeout.
+
+`load-result.json` retains per-session send and audio-packet timelines using
+the client's monotonic clock. It does not export handshake credentials or
+raw audio payloads. Metric definitions are explicit:
+
+Both modes validate each nonempty audio packet's strict base64 encoding, PCM16
+sample alignment, 24 kHz sample rate and response identity. Valid aggregate
+audio cannot hide a malformed packet. In load mode, rejected packets make the session fail
+and appear in `invalid_audio_packets` with their event index, receive time and
+fixed diagnostic code; they do not contribute samples or timing intervals.
+Empty audio deltas remain legal and contribute no samples. This check does
+not change the public client's decoding. The lifecycle scenario and dispatch
+remain the same, but malformed packets that aggregate checks once tolerated
+now fail that mode as well.
+
+The probe accepts both the current OpenAI Realtime audio event name
+`response.output_audio.delta` and the legacy `response.audio.delta`. Validation
+uses the wire payload directly rather than relying on a particular client
+library's alias table, so a server-side event-name migration cannot silently
+turn real audio into a zero-output measurement.
+
+| Field | Meaning |
+| --- | --- |
+| `client_audio_packet_interval_ms` | Consecutive nonempty packet arrivals: median, linear p99, max, and zero-based index of the first maximal interval. Interval index 0 ends at packet 1. One packet can contain multiple codec frames; this is not server tick latency. |
+| `client_first_audio_after_stream_start_ms` | First audio receipt minus first input send start; admission is excluded. |
+| `client_stream_rtf` | First input send start to last audio receipt, divided by received audio duration. This includes real-time input pacing and is not an inference-only RTF. |
+| `client_send_lateness_ms` | Send start minus its original shared schedule, clipped at zero. |
+| `frame_deficit` | Integer input-frame minus output-frame count from the shared session validation; missing when valid whole-frame accounting is unavailable. |
+| `output_frames`, `voiced_frames`, `silent_frames`, `frame_coverage_ratio`, `audio_rms`, `audio_chunks` | Session-validation statistics retained on success and on acceptance failure once computed. |
+| `acceptance_check` | Failed local check, with numeric diagnostics in `error`; other exceptions retain phase/type only, without remote handshake or metadata text. |
+| `audio_underrun_s`, `audio_underrun_event_count`, `audio_continuity_ok` | Shared `compute_continuity_stats` on valid PCM16 packet arrivals, with its default 100 ms underrun threshold; absent audio gives missing values rather than a continuity pass. |
+
+No output gives missing latency/RTF values, not zero. By default RTF is
+diagnostic; `--max-client-rtf` adds an explicit ceiling. The existing frame
+coverage, audible-frame and scheduler-data-plane checks still apply. A longer
+`--drain-s` can demonstrate eventual completion under backlog, but it must not
+be reported as real-time capacity when the fixed-window run failed or client
+RTF exceeded the stated target. Likewise, the first live session can pay
+one-time model/codec/JIT costs; either use the server's configured duplex
+warmup path or label that run as cold-start evidence before comparing steady
+capacity. Passing client-only metrics does not certify model quality or a
+real-time capacity target on another GPU. Begin with N=1 and N=2; higher N is a
+capacity experiment, not a promised property of an A100 or of this patch.
+Continuity is a client-arrival diagnostic, not proof of speaker playback and
+not an additional pass/fail gate. Packet-interval and send-lateness summaries
+retain their documented linear p99; the older client interval helper reports
+rounded nearest-rank p95 instead and is not substituted for that schema.
+
+Deterministic driver and localhost WebSocket checks need no model or GPU:
+
+```bash
+python -m pytest tests/e2e/online_serving/test_personaplex_load_driver.py \
+  -m 'core_model and cpu' --run-level core_model -q
+```
+
+These checks test the driver against controlled protocol responses. Run the
+load-driver command against real weights separately before reporting model-serving
+performance. Server tick timestamps and generic TTFT/TPOT aggregation remain
+the responsibility of the existing duplex metrics paths, not this driver.
diff --git a/tests/e2e/online_serving/personaplex_realtime_duplex.py b/tests/e2e/online_serving/personaplex_realtime_duplex.py
index 20da1598d27..78f01254899 100644
--- a/tests/e2e/online_serving/personaplex_realtime_duplex.py
+++ b/tests/e2e/online_serving/personaplex_realtime_duplex.py
@@ -10,24 +10,24 @@
 import hashlib
 import json
 import math
+import time
 import uuid
 import wave
-from collections.abc import Sequence
+from collections.abc import Awaitable, Callable, Sequence
 from pathlib import Path
+from typing import Protocol
 from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
 import numpy as np
 
 try:
     import websockets
-    from websockets.exceptions import ConnectionClosed
+    from websockets.exceptions import ConnectionClosed, WebSocketException
 except ImportError as exc:  # pragma: no cover - driver dependency.
     raise SystemExit("Install websockets first: pip install websockets") from exc
 
-from vllm_omni.clients.duplex import (
-    EventCollector,
-    write_pcm16_wav,
-)
+from vllm_omni.benchmarks.audio_continuity import compute_continuity_stats
+from vllm_omni.clients.duplex import EventCollector, write_pcm16_wav
 from vllm_omni.clients.duplex import (
     wait_for_condition as wait_for,
 )
@@ -35,6 +35,24 @@
 SAMPLE_RATE_HZ = 24_000
 FRAME_SAMPLES = 1_920
 FRAME_PERIOD_S = FRAME_SAMPLES / SAMPLE_RATE_HZ
+AUDIO_DELTA_EVENT_TYPES = frozenset({"response.audio.delta", "response.output_audio.delta"})
+
+
+class _AudioAcceptanceError(AssertionError):
+    """A local acceptance failure with numeric diagnostics safe to report."""
+
+    def __init__(self, check: str, message: str, stats: dict[str, object]) -> None:
+        super().__init__(message)
+        self.check = check
+        self.stats = dict(stats)
+
+
+class _ProbeTransport(Protocol):
+    async def recv(self) -> str | bytes: ...
+
+    async def send(self, message: str) -> None: ...
+
+    async def close(self) -> None: ...
 
 
 class RawRealtimeProbe:
@@ -46,29 +64,33 @@ class RawRealtimeProbe:
     keeps a transport-only client and reads everything from ``.events``.
     """
 
-    def __init__(self, url: str, *, max_size: int = 64 * 1024 * 1024) -> None:
+    def __init__(self, url: str, *, max_size: int = 64 * 1024 * 1024, close_timeout_s: float = 10.0) -> None:
         self.url = url
         self.max_size = max_size
+        self.close_timeout_s = close_timeout_s
         self.events = EventCollector()
-        self._ws = None
+        self._ws: _ProbeTransport | None = None
         self._reader_task: asyncio.Task[None] | None = None
 
     async def __aenter__(self) -> RawRealtimeProbe:
-        self._ws = await websockets.connect(self.url, max_size=self.max_size)
+        self._ws = await websockets.connect(self.url, max_size=self.max_size, close_timeout=self.close_timeout_s)
         self._reader_task = asyncio.create_task(self._read_events())
         return self
 
     async def __aexit__(self, exc_type, exc, traceback) -> None:
-        if self._ws is not None:
-            await self._ws.close()
-        if self._reader_task is not None:
-            self._reader_task.cancel()
-            try:
-                await self._reader_task
-            except asyncio.CancelledError:
-                pass
+        try:
+            if self._ws is not None:
+                await self._ws.close()
+        finally:
+            if self._reader_task is not None:
+                self._reader_task.cancel()
+                try:
+                    await self._reader_task
+                except asyncio.CancelledError:
+                    pass
 
     async def _read_events(self) -> None:
+        assert self._ws is not None
         try:
             while True:
                 raw = await self._ws.recv()
@@ -81,6 +103,7 @@ async def _read_events(self) -> None:
             return
 
     async def send(self, event: dict[str, object]) -> None:
+        assert self._ws is not None
         await self._ws.send(json.dumps(event))
 
 
@@ -142,6 +165,38 @@ def _events(client: RawRealtimeProbe, event_type: str) -> list[dict[str, object]
     return [event for event in client.events.events if event.get("type") == event_type]
 
 
+def _audio_events(client: RawRealtimeProbe) -> list[dict[str, object]]:
+    """Return audio deltas from both current and legacy Realtime event names."""
+    return [event for event in client.events.events if event.get("type") in AUDIO_DELTA_EVENT_TYPES]
+
+
+def _validated_audio_event(event: dict[str, object]) -> bytes:
+    """Decode one wire audio delta without depending on client event aliases."""
+    encoded = event.get("delta")
+    if not isinstance(encoded, str):
+        raise ValueError("missing_audio_delta")
+    try:
+        chunk = base64.b64decode(encoded, validate=True)
+    except ValueError:
+        raise ValueError("invalid_audio_base64") from None
+    if chunk:
+        if len(chunk) % 2:
+            raise ValueError("unaligned_pcm16_packet")
+        if event.get("sample_rate_hz") != SAMPLE_RATE_HZ:
+            raise ValueError("invalid_audio_sample_rate")
+        if not isinstance(event.get("response_id"), str) or not event.get("response_id"):
+            raise ValueError("missing_audio_response_id")
+    return chunk
+
+
+def _validated_audio_chunks(client: RawRealtimeProbe) -> list[tuple[dict[str, object], bytes]]:
+    return [(event, _validated_audio_event(event)) for event in _audio_events(client)]
+
+
+def _audio_bytes(client: RawRealtimeProbe) -> bytes:
+    return b"".join(chunk for _, chunk in _validated_audio_chunks(client) if chunk)
+
+
 async def _open_session(
     args: argparse.Namespace,
     *,
@@ -151,22 +206,7 @@ async def _open_session(
 ) -> tuple[RawRealtimeProbe, dict[str, object]]:
     client = RawRealtimeProbe(_realtime_url(args.url, args.model, session_id))
     await client.__aenter__()
-    await client.send(
-        {
-            "type": "session.update",
-            "session": {
-                "session_id": session_id,
-                "model": args.model,
-                "modalities": ["audio", "text"],
-                "input_audio_format": "pcm_f32le",
-                "output_audio_format": "pcm16",
-                "voice": args.voice,
-                "instructions": persona,
-                "turn_detection": None,
-                "extra_body": {"auto_response": True},
-            },
-        }
-    )
+    await client.send(_session_update(args, session_id=session_id, persona=persona))
     event_type = "error" if expect_error else "session.created"
     await wait_for(
         lambda: client.events.count(event_type) > 0,
@@ -176,6 +216,23 @@ async def _open_session(
     return client, _events(client, event_type)[-1]
 
 
+def _session_update(args: argparse.Namespace, *, session_id: str, persona: str) -> dict[str, object]:
+    return {
+        "type": "session.update",
+        "session": {
+            "session_id": session_id,
+            "model": args.model,
+            "modalities": ["audio", "text"],
+            "input_audio_format": "pcm_f32le",
+            "output_audio_format": "pcm16",
+            "voice": args.voice,
+            "instructions": persona,
+            "turn_detection": None,
+            "extra_body": {"auto_response": True},
+        },
+    }
+
+
 async def _close_session(client: RawRealtimeProbe, *, timeout_s: float) -> None:
     await client.send({"type": "session.close"})
     await wait_for(
@@ -200,23 +257,24 @@ async def _stream_frames(
             frame_count = min(frame_count, max_frames)
     for seq in range(frame_count):
         frame = pcm[seq * FRAME_SAMPLES : (seq + 1) * FRAME_SAMPLES]
-        frame = np.pad(frame, (0, FRAME_SAMPLES - frame.size))
-        frame = np.ascontiguousarray(frame, dtype="<f4")
-        await client.send(
-            {
-                "type": "input_audio_buffer.append",
-                "audio": base64.b64encode(frame).decode("ascii"),
-                "format": "pcm_f32le",
-                "sample_rate_hz": SAMPLE_RATE_HZ,
-                "duration_ms": 80,
-                "audio_end_ms": (seq + 1) * 80,
-                "is_speech": bool(np.sqrt(np.mean(np.square(frame))) >= 1e-4),
-            }
-        )
+        await client.send(_frame_event(frame, seq))
         await asyncio.sleep(FRAME_PERIOD_S)
     return frame_count
 
 
+def _frame_event(frame: np.ndarray, seq: int) -> dict[str, object]:
+    frame = np.ascontiguousarray(np.pad(frame, (0, FRAME_SAMPLES - frame.size)), dtype="<f4")
+    return {
+        "type": "input_audio_buffer.append",
+        "audio": base64.b64encode(frame).decode("ascii"),
+        "format": "pcm_f32le",
+        "sample_rate_hz": SAMPLE_RATE_HZ,
+        "duration_ms": 80,
+        "audio_end_ms": (seq + 1) * 80,
+        "is_speech": bool(np.sqrt(np.mean(np.square(frame))) >= 1e-4),
+    }
+
+
 def _audio_frame_stats(
     raw: bytes,
     *,
@@ -242,11 +300,7 @@ def _audio_frame_stats(
 
 
 def _response_ids(client: RawRealtimeProbe) -> set[str]:
-    return {
-        str(event["response_id"])
-        for event in _events(client, "response.output_audio.delta")
-        if isinstance(event.get("response_id"), str)
-    }
+    return {str(event["response_id"]) for event in _audio_events(client) if isinstance(event.get("response_id"), str)}
 
 
 def _session_result(
@@ -256,40 +310,66 @@ def _session_result(
     args: argparse.Namespace,
     minimum_chunks: int,
 ) -> tuple[bytes, set[str], dict[str, object]]:
-    chunks = sum(len(items) for items in client.events.response_audio.values())
-    raw = client.events.audio_bytes()
-    if chunks < minimum_chunks or not raw or len(raw) % 2:
-        raise AssertionError(f"invalid PCM16 output: chunks={chunks}, bytes={len(raw)}")
+    if isinstance(client, RawRealtimeProbe):
+        audio_chunks = _validated_audio_chunks(client)
+        chunks = sum(bool(chunk) for _, chunk in audio_chunks)
+        raw = b"".join(chunk for _, chunk in audio_chunks if chunk)
+    else:
+        # Unit fixtures may provide an already-decoded EventCollector without
+        # retaining the base64 wire field. Real websocket probes always take
+        # the strict wire-validation path above.
+        chunks = sum(len(items) for items in client.events.response_audio.values())
+        raw = client.events.audio_bytes()
+    stats: dict[str, object] = {"audio_chunks": chunks, "audio_samples": len(raw) // 2}
+    if not raw or len(raw) % 2:
+        raise _AudioAcceptanceError("pcm16_output", f"invalid PCM16 output: chunks={chunks}, bytes={len(raw)}", stats)
     pcm = np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768.0
     rms = float(np.sqrt(np.mean(np.square(pcm))))
+    stats["audio_rms"] = rms
     # This low floor only catches corrupt, non-finite, or effectively zero PCM.
     # Audible speech is checked per frame below with the higher 1e-3 default.
     if not np.isfinite(pcm).all() or rms <= 1e-5:
-        raise AssertionError(f"output audio is non-finite or silent: samples={pcm.size}, rms={rms}")
-    rates = {
-        int(event["sample_rate_hz"])
-        for event in _events(client, "response.output_audio.delta")
-        if isinstance(event.get("sample_rate_hz"), int)
-    }
+        raise _AudioAcceptanceError(
+            "audio_rms", f"output audio is non-finite or silent: samples={pcm.size}, rms={rms}", stats
+        )
+    rates = {rate for event in _audio_events(client) if isinstance(rate := event.get("sample_rate_hz"), int)}
     if rates != {SAMPLE_RATE_HZ}:
-        raise AssertionError(f"unexpected output sample rates: {sorted(rates)}")
-    stats = _audio_frame_stats(
-        raw,
-        input_frames=input_frames,
-        voiced_frame_rms_threshold=args.voiced_frame_rms_threshold,
-    )
-    if not 0 <= int(stats["frame_deficit"]) <= args.max_frame_deficit:
-        raise AssertionError(f"invalid synchronous frame accounting: input={input_frames}, stats={stats}")
+        raise _AudioAcceptanceError("sample_rate", f"unexpected output sample rates: {sorted(rates)}", stats)
+    if input_frames < 1:
+        raise _AudioAcceptanceError("input_frames", f"audio received without input frames: input={input_frames}", stats)
+    try:
+        frame_stats = _audio_frame_stats(
+            raw,
+            input_frames=input_frames,
+            voiced_frame_rms_threshold=args.voiced_frame_rms_threshold,
+        )
+    except AssertionError as exc:
+        # _audio_frame_stats only formats local sample counts, not wire data.
+        raise _AudioAcceptanceError("whole_codec_frames", str(exc), stats) from exc
+    stats.update(frame_stats)
+    if chunks < minimum_chunks:
+        raise _AudioAcceptanceError(
+            "audio_chunks", f"insufficient audio chunks: chunks={chunks}, minimum={minimum_chunks}", stats
+        )
+    if not 0 <= int(frame_stats["frame_deficit"]) <= args.max_frame_deficit:
+        raise _AudioAcceptanceError(
+            "frame_deficit",
+            f"invalid synchronous frame accounting: input={input_frames}, maximum_deficit={args.max_frame_deficit}, "
+            f"stats={stats}",
+            stats,
+        )
     min_voiced_frames = int(args.min_voiced_frames)
     if min_voiced_frames < 1:
         raise ValueError(f"min_voiced_frames must be positive, got {min_voiced_frames}")
-    if int(stats["voiced_frames"]) < min_voiced_frames:
-        raise AssertionError(
-            f"output contained insufficient audible speech: minimum_voiced_frames={min_voiced_frames}, stats={stats}"
+    if int(frame_stats["voiced_frames"]) < min_voiced_frames:
+        raise _AudioAcceptanceError(
+            "voiced_frames",
+            f"output contained insufficient audible speech: minimum_voiced_frames={min_voiced_frames}, stats={stats}",
+            stats,
         )
     runtime_metadata = [
         metadata["vllm_omni"]
-        for event in _events(client, "response.output_audio.delta")
+        for event in _audio_events(client)
         if isinstance((metadata := event.get("metadata")), dict) and isinstance(metadata.get("vllm_omni"), dict)
     ]
     if not any(
@@ -298,18 +378,19 @@ def _session_result(
         and item.get("runner_kv_backed") is True
         for item in runtime_metadata
     ):
-        raise AssertionError(f"audio events did not prove the scheduler data plane: {runtime_metadata}")
+        raise _AudioAcceptanceError(
+            "scheduler_data_plane", "audio events did not prove the scheduler data plane", stats
+        )
     response_ids = _response_ids(client)
     if len(response_ids) != 1:
-        raise AssertionError(f"continuous stream used multiple responses: {sorted(response_ids)}")
+        raise _AudioAcceptanceError(
+            "response_identity", f"continuous stream requires one response: count={len(response_ids)}", stats
+        )
     return (
         raw,
         response_ids,
         {
             **stats,
-            "audio_chunks": chunks,
-            "audio_samples": len(raw) // 2,
-            "audio_rms": rms,
             "response_ids": sorted(response_ids),
         },
     )
@@ -332,6 +413,8 @@ def _save(output_dir: Path, name: str, client: RawRealtimeProbe, raw: bytes) ->
 
 
 async def run(args: argparse.Namespace) -> dict[str, object]:
+    if getattr(args, "sessions", None) is not None:
+        return await run_load(args)
     input_path = Path(args.input_wav)
     input_identity = _input_identity(
         input_path,
@@ -381,14 +464,12 @@ async def run(args: argparse.Namespace) -> dict[str, object]:
     )
     await asyncio.gather(
         wait_for(
-            lambda: len(primary.events.audio_bytes()) // (2 * FRAME_SAMPLES) >= primary_frames - args.max_frame_deficit,
+            lambda: len(_audio_bytes(primary)) // (2 * FRAME_SAMPLES) >= primary_frames - args.max_frame_deficit,
             timeout_s=args.timeout_s,
             label="primary frame coverage",
         ),
         wait_for(
-            lambda: (
-                len(secondary.events.audio_bytes()) // (2 * FRAME_SAMPLES) >= secondary_frames - args.max_frame_deficit
-            ),
+            lambda: (len(_audio_bytes(secondary)) // (2 * FRAME_SAMPLES) >= secondary_frames - args.max_frame_deficit),
             timeout_s=args.timeout_s,
             label="secondary frame coverage",
         ),
@@ -426,16 +507,14 @@ async def run(args: argparse.Namespace) -> dict[str, object]:
     await asyncio.gather(
         wait_for(
             lambda: (
-                len(secondary.events.audio_bytes()) // (2 * FRAME_SAMPLES)
-                >= secondary_total_frames - args.max_frame_deficit
+                len(_audio_bytes(secondary)) // (2 * FRAME_SAMPLES) >= secondary_total_frames - args.max_frame_deficit
             ),
             timeout_s=args.timeout_s,
             label="survivor frame coverage after slot recycle",
         ),
         wait_for(
             lambda: (
-                len(replacement.events.audio_bytes()) // (2 * FRAME_SAMPLES)
-                >= replacement_frames - args.max_frame_deficit
+                len(_audio_bytes(replacement)) // (2 * FRAME_SAMPLES) >= replacement_frames - args.max_frame_deficit
             ),
             timeout_s=args.timeout_s,
             label="replacement frame coverage",
@@ -493,6 +572,284 @@ async def run(args: argparse.Namespace) -> dict[str, object]:
     return result
 
 
+def _distribution(values: list[float]) -> dict[str, int | float | None]:
+    if not values:
+        return {"count": 0, "median": None, "p99": None, "max": None, "argmax_index": None}
+    return {
+        "count": len(values),
+        "median": float(np.median(values)),
+        "p99": float(np.quantile(values, 0.99)),
+        "max": max(values),
+        "argmax_index": int(np.argmax(values)),
+    }
+
+
+def _load_metrics(client: RawRealtimeProbe, sends: list[tuple[float, float, float]]) -> dict[str, object]:
+    # Use the collector's local clock, never a timestamp supplied by the server.
+    packets: list[dict[str, object]] = []
+    response_ids: set[str] = set()
+    packet_times: list[float] = []
+    packet_bytes: list[int] = []
+    invalid_packets: list[dict[str, object]] = []
+    samples = 0
+    for index, (raw, received) in enumerate(zip(client.events.events, client.events.event_received_at_s, strict=True)):
+        if raw.get("type") not in AUDIO_DELTA_EVENT_TYPES:
+            continue
+        try:
+            chunk = _validated_audio_event(raw)
+        except ValueError as exc:
+            # Only fixed diagnostic codes from the validator are exported,
+            # never audio payloads or details from the remote endpoint.
+            invalid_packets.append({"event_index": index, "received_at_s": received, "code": str(exc)})
+            continue
+        if chunk:
+            samples += len(chunk) // 2
+            packet_times.append(received)
+            packet_bytes.append(len(chunk))
+            response_id = raw.get("response_id")
+            packets.append({"received_at_s": received, "samples": len(chunk) // 2, "response_id": response_id})
+            if isinstance(response_id, str) and response_id:
+                response_ids.add(response_id)
+    intervals = [(b - a) * 1000 for a, b in zip(packet_times, packet_times[1:])]
+    first_send = sends[0][1] if sends else None
+    audio_duration = samples / SAMPLE_RATE_HZ
+    first_audio_ms = (packet_times[0] - first_send) * 1000 if packet_times and first_send is not None else None
+    client_rtf = (packet_times[-1] - first_send) / audio_duration if audio_duration and first_send is not None else None
+    continuity = compute_continuity_stats(packet_times, packet_bytes, SAMPLE_RATE_HZ) if packet_times else None
+    lateness = _distribution([max(0.0, sent - planned) * 1000 for planned, sent, _ in sends])
+    p99_lateness = lateness["p99"]
+    return {
+        "input_frames": len(sends),
+        "output_samples": samples,
+        # Populate frame accounting from _session_result, including on failure.
+        "frame_deficit": None,
+        "response_ids": sorted(response_ids),
+        "client_first_audio_after_stream_start_ms": first_audio_ms,
+        "client_stream_rtf": client_rtf,
+        "client_audio_packet_interval_ms": _distribution(intervals),
+        "client_send_lateness_ms": lateness,
+        "client_pacing_warning": isinstance(p99_lateness, float) and p99_lateness > FRAME_PERIOD_S * 1000,
+        "audio_underrun_s": continuity.max_underrun_s if continuity else None,
+        "audio_underrun_event_count": continuity.underrun_event_count if continuity else None,
+        "audio_continuity_ok": continuity.is_continuous if continuity else None,
+        "input_timeline": [
+            {"frame_index": i, "planned_at_s": planned, "send_started_at_s": sent, "send_completed_at_s": completed}
+            for i, (planned, sent, completed) in enumerate(sends)
+        ],
+        "audio_packet_timeline": packets,
+        "invalid_audio_packets": invalid_packets,
+    }
+
+
+def _check_load_connection(client: RawRealtimeProbe) -> None:
+    if client.events.errors():
+        raise RuntimeError("server emitted a Realtime error (see the session error count)")
+    if client._reader_task is not None and client._reader_task.done():
+        client._reader_task.result()  # Propagate malformed JSON/reader failures.
+        raise RuntimeError("connection closed before session completion")
+
+
+async def _wait_load_event(client: RawRealtimeProbe, event_type: str, timeout_s: float) -> None:
+    def received() -> bool:
+        if client.events.count(event_type):
+            return True
+        _check_load_connection(client)
+        return False
+
+    await wait_for(received, timeout_s=timeout_s, label=event_type)
+
+
+async def _paced_load_frames(
+    client: RawRealtimeProbe,
+    pcm: np.ndarray,
+    *,
+    epoch: float,
+    timeout_s: float,
+    sends: list[tuple[float, float, float]],
+    clock: Callable[[], float] = time.monotonic,
+    sleep: Callable[[float], Awaitable[None]] = asyncio.sleep,
+) -> None:
+    next_send = epoch
+    for seq in range(math.ceil(pcm.size / FRAME_SAMPLES)):
+        await sleep(max(0.0, next_send - clock()))
+        _check_load_connection(client)
+        event = _frame_event(pcm[seq * FRAME_SAMPLES : (seq + 1) * FRAME_SAMPLES], seq)
+        started = clock()
+        await asyncio.wait_for(client.send(event), timeout=timeout_s)
+        completed = clock()
+        sends.append((epoch + seq * FRAME_PERIOD_S, started, completed))
+        # Do not burst to catch up after a stalled send; report accumulated lag.
+        next_send = max(epoch + (seq + 1) * FRAME_PERIOD_S, completed + FRAME_PERIOD_S)
+
+
+async def _request_load_close(client: RawRealtimeProbe, timeout_s: float) -> None:
+    await client.send({"type": "session.close"})
+    await _wait_load_event(client, "session.closed", timeout_s)
+
+
+async def _run_load_session(
+    args: argparse.Namespace,
+    pcm: np.ndarray,
+    index: int,
+    ready: asyncio.Future[None],
+    start: asyncio.Future[float],
+) -> dict[str, object]:
+    session_id = f"personaplex-load-{index}-{uuid.uuid4().hex}"
+    client = RawRealtimeProbe(_realtime_url(args.url, args.model, session_id), close_timeout_s=args.cleanup_timeout_s)
+    sends: list[tuple[float, float, float]] = []
+    error: str | None = None
+    cleanup_error: str | None = None
+    metrics: dict[str, object] | None = None
+    session_stats: dict[str, object] = {}
+    acceptance_check: str | None = None
+    phase = "admission"
+    try:
+        async with client:
+            try:
+                await asyncio.wait_for(
+                    client.send(_session_update(args, session_id=session_id, persona=args.persona)), args.timeout_s
+                )
+                await _wait_load_event(client, "session.created", args.timeout_s)
+                capabilities = _capabilities(_events(client, "session.created")[-1])
+                if (
+                    capabilities.get("chunk_period_ms") != 80
+                    or capabilities.get("supports_multi_session_same_replica") is not True
+                ):
+                    raise AssertionError("server did not advertise PersonaPlex multi-session capabilities")
+                ready.set_result(None)
+                phase = "stream"
+                epoch = await asyncio.shield(start)
+                await _paced_load_frames(client, pcm, epoch=epoch, timeout_s=args.timeout_s, sends=sends)
+                phase = "drain"
+                # Fixed, reported observation window. Closing must not extend
+                # it and let a slow session pass by flushing after the cutoff.
+                await asyncio.sleep(args.drain_s)
+                _check_load_connection(client)
+                _, _, session_stats = _session_result(
+                    client, input_frames=len(sends), args=args, minimum_chunks=args.minimum_audio_chunks
+                )
+            finally:
+                metrics = _load_metrics(client, sends)
+                if client.events.count("session.created") and not client.events.count("session.closed"):
+                    try:
+                        # Send and acknowledgement share one short cleanup budget,
+                        # independent of the potentially long inference timeout.
+                        await asyncio.wait_for(
+                            _request_load_close(client, args.cleanup_timeout_s), args.cleanup_timeout_s
+                        )
+                    except (OSError, asyncio.TimeoutError, ValueError, RuntimeError, WebSocketException) as exc:
+                        cleanup_error = f"cleanup: {type(exc).__name__}"
+    except (OSError, asyncio.TimeoutError, ValueError, RuntimeError, AssertionError, WebSocketException) as exc:
+        if isinstance(exc, _AudioAcceptanceError):
+            acceptance_check = exc.check
+            session_stats = exc.stats
+            error = f"{phase}: AssertionError: {exc}"
+        else:
+            # Other assertions/errors may embed handshake credentials or wire
+            # metadata. Only our local numeric acceptance diagnostics are safe.
+            error = f"{phase}: {type(exc).__name__}"
+    finally:
+        # Admission failure must not leave the other sessions at the barrier.
+        if not ready.done():
+            ready.set_result(None)
+    if metrics is None:
+        metrics = _load_metrics(client, sends)
+    if cleanup_error:
+        error = f"{error}; {cleanup_error}" if error else cleanup_error
+    if client.events.errors():
+        error = error or "server emitted a Realtime error"
+    if metrics["invalid_audio_packets"]:
+        error = error or "invalid audio packets"
+    first_audio = metrics["client_first_audio_after_stream_start_ms"]
+    if isinstance(first_audio, float) and first_audio < 0:
+        error = error or "audio arrived before the first input frame"
+    rtf = metrics["client_stream_rtf"]
+    if args.max_client_rtf is not None and isinstance(rtf, float) and rtf > args.max_client_rtf:
+        error = error or f"client_stream_rtf exceeds {args.max_client_rtf}"
+    return {
+        "index": index,
+        "session_id": session_id,
+        "ok": error is None,
+        "error": error,
+        "acceptance_check": acceptance_check,
+        "server_error_count": len(client.events.errors()),
+        "server_error_codes": [
+            str(body.get("code", "unknown")) if isinstance(body := event.get("error"), dict) else "unknown"
+            for event in client.events.errors()
+        ],
+        **metrics,
+        **session_stats,
+    }
+
+
+async def run_load(args: argparse.Namespace) -> dict[str, object]:
+    input_path = Path(args.input_wav)
+    identity = _input_identity(input_path, expected_sha256=args.expected_input_sha256)
+    pcm = _read_wav_as_float32(input_path)
+    if args.tail_s:
+        pcm = np.concatenate([pcm, np.zeros(round(args.tail_s * SAMPLE_RATE_HZ), dtype=np.float32)])
+    pcm = pcm[: args.load_frames * FRAME_SAMPLES]
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    # Refuse to silently overwrite evidence from a previous sweep.
+    result_path = output_dir / "load-result.json"
+    if result_path.exists():
+        raise FileExistsError(result_path)
+    loop = asyncio.get_running_loop()
+    start: asyncio.Future[float] = loop.create_future()
+    ready: list[asyncio.Future[None]] = [loop.create_future() for _ in range(args.sessions)]
+    tasks = [asyncio.create_task(_run_load_session(args, pcm, i, r, start)) for i, r in enumerate(ready)]
+    try:
+        await asyncio.gather(*ready)
+        start.set_result(time.monotonic())
+        rows = await asyncio.gather(*tasks)
+    finally:
+        for task in tasks:
+            if not task.done():
+                task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+    seen: set[str] = set()
+    shared: set[str] = set()
+    for row in rows:
+        assert isinstance(row["response_ids"], list)
+        response_ids = set(row["response_ids"])
+        shared.update(seen & response_ids)
+        seen.update(response_ids)
+    for row in rows:
+        assert isinstance(row["response_ids"], list)
+        if shared.intersection(row["response_ids"]):
+            row.update(ok=False, error="concurrent sessions shared a response id")
+    result = {
+        "schema_version": 1,
+        "mode": "paced_multi_session",
+        "model": args.model,
+        "requested_sessions": args.sessions,
+        "passed_sessions": sum(row["ok"] is True for row in rows),
+        "ok": all(row["ok"] is True for row in rows),
+        "input": {**identity, "tail_s": args.tail_s, "load_frames": args.load_frames},
+        "frame_period_s": FRAME_PERIOD_S,
+        "drain_s": args.drain_s,
+        "cleanup_timeout_s": args.cleanup_timeout_s,
+        "client_pacing_warning_threshold_ms": FRAME_PERIOD_S * 1000,
+        "client_pacing_warning_sessions": [row["index"] for row in rows if row["client_pacing_warning"]],
+        "max_client_rtf": args.max_client_rtf,
+        "acceptance": {
+            "max_frame_deficit": args.max_frame_deficit,
+            "min_voiced_frames": args.min_voiced_frames,
+            "minimum_audio_chunks": args.minimum_audio_chunks,
+            "voiced_frame_rms_threshold": args.voiced_frame_rms_threshold,
+        },
+        "shared_response_ids": sorted(shared),
+        "sessions": rows,
+        "reported_server": {"revision": args.server_revision, "hardware": args.server_hardware},
+        "measurement_origin": "client monotonic clock; admission excluded; streaming and drain retained",
+        "interval_definition": "nonempty audio packet arrivals, not server ticks or per-frame inference latency",
+    }
+    with result_path.open("x", encoding="utf-8") as stream:
+        json.dump(result, stream, ensure_ascii=False, indent=2, allow_nan=False)
+    return result
+
+
 def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
     parser = argparse.ArgumentParser()
     parser.add_argument("--url", default="ws://127.0.0.1:8099/v1/realtime?duplex=1")
@@ -510,6 +867,12 @@ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
     parser.add_argument("--tail-s", type=float, default=2.0)
     parser.add_argument("--drain-s", type=float, default=2.0)
     parser.add_argument("--timeout-s", type=float, default=180.0)
+    parser.add_argument(
+        "--cleanup-timeout-s",
+        type=float,
+        default=5.0,
+        help="Load mode: shared session-close/ack budget; also bounds the websocket close handshake.",
+    )
     parser.add_argument(
         "--max-frame-deficit",
         type=int,
@@ -536,11 +899,39 @@ def parse_args(argv: Sequence[str] | None = None) -> argparse.Namespace:
         default=0,
         help="Frames sent after slot reuse; 0 replays the full input so the replacement must produce audible output.",
     )
-    return parser.parse_args(argv)
+    parser.add_argument(
+        "--sessions", type=int, help="Opt into paced load mode with N sessions; omit for the lifecycle test."
+    )
+    parser.add_argument(
+        "--load-frames", type=int, default=1000, help="Maximum input frames per load session (no repetition)."
+    )
+    parser.add_argument("--max-client-rtf", type=float, help="Optional client stream-window RTF acceptance ceiling.")
+    parser.add_argument("--server-revision", help="User-reported server commit/version; not verified by this client.")
+    parser.add_argument(
+        "--server-hardware", help="User-reported server hardware; not inferred from the client machine."
+    )
+    args = parser.parse_args(argv)
+    if args.sessions is not None:
+        if not 1 <= args.sessions <= 64 or not 1 <= args.load_frames <= 10000:
+            parser.error("load mode requires sessions in [1,64] and load-frames in [1,10000]")
+        for name in ("timeout_s", "cleanup_timeout_s", "drain_s", "tail_s"):
+            value = getattr(args, name)
+            if not math.isfinite(value) or value < 0 or (name in ("timeout_s", "cleanup_timeout_s") and value == 0):
+                parser.error(f"{name} must be finite and non-negative (timeout must be positive)")
+        if args.max_client_rtf is not None and (not math.isfinite(args.max_client_rtf) or args.max_client_rtf <= 0):
+            parser.error("max-client-rtf must be finite and positive")
+        if args.max_frame_deficit < 0 or args.min_voiced_frames < 1 or args.minimum_audio_chunks < 1:
+            parser.error("frame-deficit must be non-negative; voiced frames and audio chunks must be positive")
+        if not math.isfinite(args.voiced_frame_rms_threshold) or args.voiced_frame_rms_threshold < 0:
+            parser.error("voiced-frame-rms-threshold must be finite and non-negative")
+    return args
 
 
 def main() -> None:
-    print(json.dumps(asyncio.run(run(parse_args())), ensure_ascii=False, indent=2))
+    result = asyncio.run(run(parse_args()))
+    print(json.dumps(result, ensure_ascii=False, indent=2, allow_nan=False))
+    if result.get("mode") == "paced_multi_session" and not result["ok"]:
+        raise SystemExit(1)
 
 
 if __name__ == "__main__":
diff --git a/tests/e2e/online_serving/test_personaplex_load_driver.py b/tests/e2e/online_serving/test_personaplex_load_driver.py
new file mode 100644
index 00000000000..8e9a6a28d90
--- /dev/null
+++ b/tests/e2e/online_serving/test_personaplex_load_driver.py
@@ -0,0 +1,568 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import asyncio
+import base64
+import json
+import wave
+from contextlib import asynccontextmanager
+from typing import TypedDict
+
+import numpy as np
+import pytest
+import websockets
+
+from tests.e2e.online_serving import personaplex_realtime_duplex as driver
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+class _ServerState(TypedDict):
+    index: int
+    closed: bool
+    frames: int
+    close_requested: bool
+
+
+def _args(tmp_path, *extra):
+    wav_path = tmp_path / "input.wav"
+    with wave.open(str(wav_path), "wb") as stream:
+        stream.setnchannels(1)
+        stream.setsampwidth(2)
+        stream.setframerate(driver.SAMPLE_RATE_HZ)
+        stream.writeframes(np.full(driver.FRAME_SAMPLES * 2, 2000, dtype="<i2").tobytes())
+    return driver.parse_args(
+        [
+            "--model",
+            "fixture-only",
+            "--input-wav",
+            str(wav_path),
+            "--output-dir",
+            str(tmp_path / "out"),
+            "--sessions",
+            "2",
+            "--load-frames",
+            "2",
+            "--tail-s",
+            "0",
+            "--drain-s",
+            "0.04",
+            "--timeout-s",
+            "3",
+            "--cleanup-timeout-s",
+            "1",
+            "--min-voiced-frames",
+            "1",
+            "--minimum-audio-chunks",
+            "1",
+            "--max-frame-deficit",
+            "0",
+            *extra,
+        ]
+    )
+
+
+def _audio(response_id="r", samples=1920, event_type="response.output_audio.delta"):
+    return {
+        "type": event_type,
+        "response_id": response_id,
+        "delta": base64.b64encode(np.full(samples, 2000, dtype="<i2").tobytes()).decode("ascii"),
+        "sample_rate_hz": driver.SAMPLE_RATE_HZ,
+        "metadata": {
+            "vllm_omni": {
+                "runtime_impl": "scheduler_data_plane",
+                "uses_model_runner_scheduler": True,
+                "runner_kv_backed": True,
+            }
+        },
+    }
+
+
+@asynccontextmanager
+async def _server(mode="success"):
+    states: list[_ServerState] = []
+
+    async def handle(ws):
+        index = len(states)
+        state: _ServerState = {"index": index, "closed": False, "frames": 0, "close_requested": False}
+        states.append(state)
+        response_id = "shared" if mode == "shared_response" else f"r-{index}"
+        try:
+            async for raw in ws:
+                message = json.loads(raw)
+                if message["type"] == "session.update":
+                    if mode == "reject_second" and index == 1:
+                        await ws.send(json.dumps({"type": "error", "error": {"code": "resource_exhausted"}}))
+                        continue
+                    if mode == "missing_capabilities":
+                        await ws.send(
+                            json.dumps(
+                                {
+                                    "type": "session.created",
+                                    "session": {"resume_token": "must-not-be-exported"},
+                                }
+                            )
+                        )
+                        continue
+                    await ws.send(
+                        json.dumps(
+                            {
+                                "type": "session.created",
+                                "session": {
+                                    "resume_token": "must-not-be-exported",
+                                    "capabilities": {
+                                        "chunk_period_ms": 80,
+                                        "supports_multi_session_same_replica": True,
+                                    },
+                                },
+                            }
+                        )
+                    )
+                    await ws.send(json.dumps({"type": "response.created", "response": {"id": response_id}}))
+                elif message["type"] == "input_audio_buffer.append":
+                    state["frames"] += 1
+                    if mode == "short_audio" and state["frames"] == 2:
+                        continue
+                    if mode == "disconnect":
+                        await ws.close()
+                        return
+                    if mode == "bad_json":
+                        await ws.send("{")
+                    elif mode not in ("silent", "late_on_close"):
+                        event_type = (
+                            "response.audio.delta" if mode == "legacy_audio_event" else "response.output_audio.delta"
+                        )
+                        packet = _audio(response_id, event_type=event_type)
+                        if mode == "private_metadata":
+                            packet["metadata"] = {"vllm_omni": {"private": "remote-detail-must-not-be-exported"}}
+                        if mode == "odd_packet":
+                            raw_audio = base64.b64decode(packet["delta"])
+                            raw_audio = raw_audio + b"\x00" if state["frames"] == 1 else raw_audio[:-1]
+                            packet["delta"] = base64.b64encode(raw_audio).decode("ascii")
+                        if state["frames"] == 2:
+                            if mode == "missing_packet_rate":
+                                packet.pop("sample_rate_hz")
+                            elif mode == "string_packet_rate":
+                                packet["sample_rate_hz"] = "24000"
+                            elif mode == "invalid_base64":
+                                packet["delta"] = "!" + packet["delta"]
+                            elif mode == "orphan_audio":
+                                orphan = _audio(response_id)
+                                orphan.pop("response_id")
+                                await ws.send(json.dumps(orphan))
+                        await ws.send(json.dumps(packet))
+                elif message["type"] == "session.close":
+                    state["close_requested"] = True
+                    if mode == "late_on_close":
+                        await ws.send(json.dumps(_audio(response_id, samples=driver.FRAME_SAMPLES * state["frames"])))
+                    if mode == "error_on_close":
+                        await ws.send(json.dumps({"type": "error", "error": {"code": "cleanup_failed"}}))
+                    if mode != "no_close_ack":
+                        await ws.send(json.dumps({"type": "session.closed"}))
+        finally:
+            state["closed"] = True
+
+    async with websockets.serve(handle, "127.0.0.1", 0) as server:
+        port = server.sockets[0].getsockname()[1]
+        yield f"ws://127.0.0.1:{port}/v1/realtime", states
+
+
+def test_omitted_sessions_preserves_lifecycle_mode():
+    args = driver.parse_args(["--model", "unused", "--input-wav", "unused.wav"])
+    assert args.sessions is None
+
+
+@pytest.mark.parametrize(
+    "options",
+    [
+        ["--sessions", "0"],
+        ["--sessions", "65"],
+        ["--load-frames", "0"],
+        ["--load-frames", "10001"],
+        ["--drain-s", "nan"],
+        ["--tail-s", "-1"],
+        ["--timeout-s", "0"],
+        ["--timeout-s", "inf"],
+        ["--cleanup-timeout-s", "0"],
+        ["--cleanup-timeout-s", "nan"],
+        ["--max-client-rtf", "-1"],
+        ["--max-frame-deficit", "-1"],
+        ["--minimum-audio-chunks", "0"],
+        ["--min-voiced-frames", "0"],
+        ["--voiced-frame-rms-threshold", "nan"],
+    ],
+)
+def test_load_rejects_invalid_configuration(tmp_path, options):
+    with pytest.raises(SystemExit):
+        _args(tmp_path, *options)
+
+
+def test_metric_clock_and_packet_frame_distinction():
+    client = driver.RawRealtimeProbe("ws://unused")
+    client.events.add({"type": "session.created", "session": {"resume_token": "secret"}}, received_at_s=7)
+    for when in (10.4, 10.8, 11.6):
+        event = _audio(samples=driver.FRAME_SAMPLES * 5)
+        event["_client_received_at_s"] = -999.0
+        client.events.add(event, received_at_s=when)
+    report = driver._load_metrics(client, [(10, 10, 10.01)])
+    intervals = report["client_audio_packet_interval_ms"]
+    assert isinstance(intervals, dict)
+    assert intervals["count"] == 2
+    assert intervals["median"] == pytest.approx(600)
+    assert intervals["p99"] == pytest.approx(796)
+    assert intervals["max"] == pytest.approx(800)
+    assert intervals["argmax_index"] == 1
+    assert report["client_first_audio_after_stream_start_ms"] == pytest.approx(400)
+    assert report["output_samples"] == 15 * driver.FRAME_SAMPLES
+    assert report["audio_underrun_s"] == pytest.approx(0.4)
+    assert report["audio_continuity_ok"] is False
+    underruns = report["audio_underrun_event_count"]
+    assert isinstance(underruns, int) and underruns >= 1
+    assert report["client_pacing_warning"] is False
+    assert "secret" not in json.dumps(report)
+    assert "-999" not in json.dumps(report)
+
+
+def test_empty_output_has_missing_not_zero_latency():
+    report = driver._load_metrics(driver.RawRealtimeProbe("ws://unused"), [])
+    assert report["client_stream_rtf"] is None
+    assert report["audio_continuity_ok"] is None
+    assert report["audio_underrun_s"] is None
+    intervals = report["client_audio_packet_interval_ms"]
+    assert isinstance(intervals, dict)
+    assert intervals["p99"] is None
+
+
+def test_failed_acceptance_retains_frame_counts_without_remote_data():
+    client = driver.RawRealtimeProbe("ws://unused")
+    client.events.add(_audio(), received_at_s=1.0)
+    args = driver.parse_args(
+        ["--model", "unused", "--input-wav", "unused.wav", "--max-frame-deficit", "0", "--min-voiced-frames", "1"]
+    )
+    with pytest.raises(AssertionError) as raised:
+        driver._session_result(client, input_frames=2, args=args, minimum_chunks=1)
+    assert getattr(raised.value, "check", None) == "frame_deficit"
+    stats = getattr(raised.value, "stats", {})
+    assert stats["frame_deficit"] == 1 and type(stats["frame_deficit"]) is int
+    assert stats["output_frames"] == stats["voiced_frames"] == 1
+    assert stats["frame_coverage_ratio"] == 0.5
+
+
+@pytest.mark.parametrize("event_type", sorted(driver.AUDIO_DELTA_EVENT_TYPES))
+def test_session_result_accepts_current_and_legacy_audio_event_names(tmp_path, event_type):
+    client = driver.RawRealtimeProbe("ws://unused")
+    client.events.add(_audio(samples=driver.FRAME_SAMPLES, event_type=event_type), received_at_s=1.0)
+    raw, response_ids, stats = driver._session_result(
+        client,
+        input_frames=1,
+        args=_args(tmp_path, "--sessions", "1"),
+        minimum_chunks=1,
+    )
+    assert len(raw) == driver.FRAME_SAMPLES * 2
+    assert response_ids == {"r"}
+    assert stats["frame_deficit"] == 0
+
+
+def test_legacy_audio_event_name_contributes_load_metrics():
+    client = driver.RawRealtimeProbe("ws://unused")
+    client.events.add(_audio(samples=driver.FRAME_SAMPLES * 5, event_type="response.audio.delta"), received_at_s=10.4)
+    report = driver._load_metrics(client, [(10.0, 10.0, 10.01)])
+    assert report["output_samples"] == driver.FRAME_SAMPLES * 5
+    assert report["response_ids"] == ["r"]
+    assert report["invalid_audio_packets"] == []
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("sessions", [1, 2, 4])
+async def test_real_websocket_load_success(tmp_path, sessions):
+    args = _args(tmp_path, "--sessions", str(sessions))
+    async with _server() as (url, states):
+        args.url = url
+        result = await driver.run(args)
+    assert result["ok"] is True
+    assert result["passed_sessions"] == sessions
+    rows = result["sessions"]
+    assert isinstance(rows, list)
+    assert len(rows) == sessions
+    assert all(row["frame_deficit"] == 0 for row in rows)
+    for row in rows:
+        assert type(row["frame_deficit"]) is int
+        assert row["output_frames"] == row["voiced_frames"] == row["audio_chunks"] == 2
+        assert row["silent_frames"] == 0
+        assert row["frame_coverage_ratio"] == 1.0
+        assert row["audio_rms"] == pytest.approx(2000 / 32768)
+        assert row["acceptance_check"] is None
+        assert isinstance(row["audio_continuity_ok"], bool)
+    assert all(s["closed"] and s["close_requested"] for s in states)
+    assert "must-not-be-exported" not in json.dumps(result)
+    saved = json.loads((tmp_path / "out/load-result.json").read_text())
+    assert saved == result
+    origins = [row["input_timeline"][0]["planned_at_s"] for row in rows]
+    assert len(set(origins)) == 1
+
+
+@pytest.mark.asyncio
+async def test_real_websocket_load_accepts_legacy_audio_event_name(tmp_path):
+    args = _args(tmp_path, "--sessions", "2")
+    async with _server("legacy_audio_event") as (url, states):
+        args.url = url
+        result = await driver.run(args)
+    assert result["ok"] is True
+    assert result["passed_sessions"] == 2
+    assert result["shared_response_ids"] == []
+    assert all(s["closed"] and s["close_requested"] for s in states)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+    "mode",
+    [
+        "reject_second",
+        "silent",
+        "disconnect",
+        "no_close_ack",
+        "shared_response",
+        "late_on_close",
+        "error_on_close",
+        "bad_json",
+        "missing_capabilities",
+    ],
+)
+async def test_real_websocket_failures_remain_in_results(tmp_path, mode):
+    args = _args(tmp_path)
+    async with _server(mode) as (url, states):
+        args.url = url
+        result = await asyncio.wait_for(driver.run(args), timeout=4)
+    assert result["ok"] is False
+    assert "must-not-be-exported" not in json.dumps(result)
+    assert result["requested_sessions"] == 2
+    rows = result["sessions"]
+    assert isinstance(rows, list)
+    assert len(rows) == 2
+    assert all(s["closed"] for s in states)
+    if mode == "reject_second":
+        assert result["passed_sessions"] == 1
+        rejected = next(row for row in rows if not row["ok"])
+        assert rejected["input_frames"] == 0
+        assert rejected["client_stream_rtf"] is None
+        assert rejected["server_error_codes"] == ["resource_exhausted"]
+    if mode == "silent":
+        # A failed measurement must still release its admitted session.
+        assert all(s["close_requested"] for s in states)
+    if mode == "late_on_close":
+        assert all(row["output_samples"] == 0 for row in rows)
+    if mode == "shared_response":
+        assert result["passed_sessions"] == 0
+
+
+@pytest.mark.asyncio
+async def test_existing_report_is_not_overwritten(tmp_path):
+    args = _args(tmp_path)
+    path = tmp_path / "out/load-result.json"
+    path.parent.mkdir()
+    path.write_text("previous measurement")
+    with pytest.raises(FileExistsError):
+        await driver.run(args)
+    assert path.read_text() == "previous measurement"
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mode", ["success", "no_close_ack"])
+async def test_cancellation_closes_all_connections(tmp_path, mode):
+    args = _args(tmp_path, "--drain-s", "10", "--timeout-s", "30")
+    async with _server(mode) as (url, states):
+        args.url = url
+        task = asyncio.create_task(driver.run(args))
+
+        async def started():
+            while len(states) < 2 or not all(state["frames"] for state in states):
+                await asyncio.sleep(0.01)
+
+        await asyncio.wait_for(started(), timeout=3)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            await asyncio.wait_for(task, timeout=3)
+    assert all(s["closed"] for s in states)
+
+
+@pytest.mark.asyncio
+async def test_client_rtf_ceiling_marks_slow_sessions_failed(tmp_path):
+    args = _args(tmp_path, "--max-client-rtf", "0.001")
+    async with _server() as (url, _):
+        args.url = url
+        result = await driver.run(args)
+    assert result["passed_sessions"] == 0
+    rows = result["sessions"]
+    assert isinstance(rows, list)
+    assert all("client_stream_rtf exceeds" in row["error"] for row in rows)
+
+
+@pytest.mark.asyncio
+async def test_stalled_send_does_not_cause_catchup_burst():
+    class Clock:
+        now = 10.0
+
+        def monotonic(self):
+            return self.now
+
+        async def sleep(self, delay):
+            self.now += delay
+
+    class Client(driver.RawRealtimeProbe):
+        async def send(self, event):
+            if event["audio_end_ms"] == 80:
+                clock.now += 0.25
+
+    clock = Clock()
+    sends: list[tuple[float, float, float]] = []
+    await driver._paced_load_frames(
+        Client("ws://unused"),
+        np.zeros(driver.FRAME_SAMPLES * 3, dtype="<f4"),
+        epoch=10.0,
+        timeout_s=1.0,
+        sends=sends,
+        clock=clock.monotonic,
+        sleep=clock.sleep,
+    )
+    assert len(sends) == 3
+    assert sends[1][1] >= sends[0][2] + driver.FRAME_PERIOD_S
+    assert sends[1][1] - sends[1][0] == pytest.approx(0.25)
+    assert sends[2][1] >= sends[1][2] + driver.FRAME_PERIOD_S
+    metrics = driver._load_metrics(Client("ws://unused"), sends)
+    assert metrics["client_pacing_warning"] is True
+    assert asyncio.sleep != clock.sleep
+
+
+@pytest.mark.asyncio
+async def test_failed_frame_acceptance_preserves_numeric_diagnostics(tmp_path):
+    args = _args(tmp_path, "--sessions", "1")
+    async with _server("short_audio") as (url, states):
+        args.url = url
+        result = await driver.run(args)
+    rows = result["sessions"]
+    assert isinstance(rows, list)
+    row = rows[0]
+    assert row["ok"] is False
+    assert row["acceptance_check"] == "frame_deficit"
+    assert row["frame_deficit"] == 1 and type(row["frame_deficit"]) is int
+    assert row["output_frames"] == row["voiced_frames"] == row["audio_chunks"] == 1
+    assert row["frame_coverage_ratio"] == 0.5
+    assert row["audio_rms"] == pytest.approx(2000 / 32768)
+    assert "input=2" in row["error"] and "maximum_deficit=0" in row["error"]
+    assert all(state["closed"] and state["close_requested"] for state in states)
+    assert json.loads((tmp_path / "out/load-result.json").read_text()) == result
+
+
+@pytest.mark.asyncio
+async def test_acceptance_failure_does_not_export_remote_metadata(tmp_path):
+    args = _args(tmp_path, "--sessions", "1")
+    async with _server("private_metadata") as (url, _):
+        args.url = url
+        result = await driver.run(args)
+    rows = result["sessions"]
+    assert isinstance(rows, list)
+    row = rows[0]
+    assert row["ok"] is False
+    assert row["acceptance_check"] == "scheduler_data_plane"
+    assert "remote-detail" not in json.dumps(result)
+    assert "must-not-be-exported" not in json.dumps(result)
+
+
+@pytest.mark.parametrize("ok", [True, False])
+def test_load_main_exit_status(tmp_path, monkeypatch, ok):
+    args = _args(tmp_path)
+
+    async def completed(_args):
+        return {"mode": "paced_multi_session", "ok": ok}
+
+    monkeypatch.setattr(driver, "parse_args", lambda: args)
+    monkeypatch.setattr(driver, "run", completed)
+    if ok:
+        driver.main()
+    else:
+        with pytest.raises(SystemExit) as exc:
+            driver.main()
+        assert exc.value.code == 1
+
+
+@pytest.mark.asyncio
+async def test_handshake_rejection_is_retained_without_server_details(tmp_path, monkeypatch):
+    from websockets.exceptions import InvalidHandshake
+
+    async def rejected(_self):
+        raise InvalidHandshake("credentials-in-remote-handshake-detail")
+
+    monkeypatch.setattr(driver.RawRealtimeProbe, "__aenter__", rejected)
+    result = await asyncio.wait_for(driver.run(_args(tmp_path)), timeout=3)
+    assert result["ok"] is False
+    rows = result["sessions"]
+    assert isinstance(rows, list) and len(rows) == 2
+    assert all(row["error"] == "admission: InvalidHandshake" for row in rows)
+    assert "credentials-in-remote-handshake-detail" not in json.dumps(result)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("sessions", [1, 2])
+@pytest.mark.parametrize(
+    "mode",
+    [
+        "missing_packet_rate",
+        "string_packet_rate",
+        "invalid_base64",
+        "orphan_audio",
+        "odd_packet",
+    ],
+)
+async def test_load_rejects_invalid_individual_audio_packets(tmp_path, sessions, mode):
+    # The concatenated PCM can still meet coverage/voicing thresholds, so the
+    # validator must also check each packet before accepting the whole run.
+    args = _args(tmp_path, "--sessions", str(sessions))
+    async with _server(mode) as (url, states):
+        args.url = url
+        result = await asyncio.wait_for(driver.run(args), timeout=4)
+    assert result["ok"] is False
+    assert result["passed_sessions"] == 0
+    rows = result["sessions"]
+    assert isinstance(rows, list) and len(rows) == sessions
+    assert all(row["error"] is not None for row in rows)
+    expected_code = {
+        "missing_packet_rate": "invalid_audio_sample_rate",
+        "string_packet_rate": "invalid_audio_sample_rate",
+        "invalid_base64": "invalid_audio_base64",
+        "orphan_audio": "missing_audio_response_id",
+        "odd_packet": "unaligned_pcm16_packet",
+    }[mode]
+    assert all({packet["code"] for packet in row["invalid_audio_packets"]} == {expected_code} for row in rows)
+    assert all(
+        sum(packet["samples"] for packet in row["audio_packet_timeline"]) == row["output_samples"] for row in rows
+    )
+    assert all(state["closed"] and state["close_requested"] for state in states)
+    assert json.loads((tmp_path / "out/load-result.json").read_text()) == result
+
+
+def test_load_allows_empty_and_multi_frame_audio_packets():
+    client = driver.RawRealtimeProbe("ws://unused")
+    client.events.add(_audio(samples=0), received_at_s=1.0)
+    client.events.add(_audio(samples=driver.FRAME_SAMPLES * 5), received_at_s=1.4)
+    metrics = driver._load_metrics(client, [(1.0, 1.0, 1.001)])
+    assert metrics["invalid_audio_packets"] == []
+    assert metrics["output_samples"] == driver.FRAME_SAMPLES * 5
+    packets = metrics["audio_packet_timeline"]
+    assert isinstance(packets, list) and len(packets) == 1
+
+
+def test_load_packet_diagnostics_do_not_copy_remote_payload():
+    client = driver.RawRealtimeProbe("ws://unused")
+    event = _audio()
+    event["delta"] = "private-remote-payload!"
+    client.events.add(event, received_at_s=1.4)
+    metrics = driver._load_metrics(client, [])
+    assert metrics["output_samples"] == 0
+    assert metrics["invalid_audio_packets"] == [
+        {
+            "event_index": 0,
+            "received_at_s": 1.4,
+            "code": "invalid_audio_base64",
+        }
+    ]
+    assert "private-remote-payload" not in json.dumps(metrics)

From 8c3d3407d1bc9b1b538d2196f4ed2d802a15cfc3 Mon Sep 17 00:00:00 2001
From: Alex Brooks <albrooks@redhat.com>
Date: Thu, 17 Sep 2026 01:01:01 -0600
Subject: [PATCH 059/105] [CI] Fix Structured Structured Diffusion Config Wan
 Test (#7707)

Signed-off-by: Alex Brooks <albrooks@redhat.com>
---
 tests/e2e/offline_inference/test_wan22_t2v.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/tests/e2e/offline_inference/test_wan22_t2v.py b/tests/e2e/offline_inference/test_wan22_t2v.py
index 07ac5c8a64a..b3c7d6aabf0 100644
--- a/tests/e2e/offline_inference/test_wan22_t2v.py
+++ b/tests/e2e/offline_inference/test_wan22_t2v.py
@@ -6,6 +6,7 @@
 from tests.helpers.mark import hardware_test
 from tests.helpers.runtime import OfflineOmniClient
 from vllm_omni.config.omni_config import VllmOmniDiffusionStageConfig
+from vllm_omni.diffusion.data import OmniDiffusionConfig
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 
 MODEL = "Wan-AI/Wan2.2-T2V-A14B-Diffusers"
@@ -21,17 +22,19 @@ def test_structured_diffusion_config_reaches_runtime(omni_runner) -> None:
     """The default WAN resolver launches the typed diffusion config itself."""
     omni = omni_runner.omni
     resolved_stages = omni.engine.stage_configs
+    stage_clients = omni.engine.stage_clients
     assert len(resolved_stages) == 1
+    assert len(stage_clients) == 1
     stage_config = resolved_stages[0]
+    od_config = stage_clients[0].od_config
 
     assert isinstance(stage_config, VllmOmniDiffusionStageConfig)
+    assert isinstance(od_config, OmniDiffusionConfig)
     assert stage_config.stage_id == 0
     assert stage_config.model_stage == "dit"
     assert stage_config.final_output_type == "video"
 
     assert omni.engine.stage_vllm_configs == [None]
-    od_config = omni.get_diffusion_od_config()
-    assert od_config is not None
     assert od_config.stage_id == 0
     assert od_config.model == MODEL
     assert od_config.model_class_name == "WanPipeline"

From cb439f3e84394c0cdfc252eaff3303fb099cc67d Mon Sep 17 00:00:00 2001
From: WeiQing Chen <40507679+david6666666@users.noreply.github.com>
Date: Thu, 17 Sep 2026 16:41:52 +0800
Subject: [PATCH 060/105] [Diffusion][Model] Add direct FastH3 8-Step V2
 checkpoint loading (#7610)

Signed-off-by: david6666666 <530634352@qq.com>
---
 recipes/MiniMaxAI/MiniMax-H3.md               |  62 ++
 .../minimax_h3/test_fasth3_checkpoint.py      | 679 ++++++++++++++++++
 .../minimax_h3/test_minimax_h3_contract.py    |   1 +
 .../minimax_h3/test_minimax_h3_fasth3.py      |   5 +-
 .../test_minimax_h3_quantization.py           |  23 +-
 .../test_minimax_h3_quantization_quality.py   |   6 +-
 .../diffusion/models/minimax_h3/fasth3.py     |   3 +
 .../models/minimax_h3/fasth3_checkpoint.py    | 131 ++++
 .../minimax_h3/minimax_h3_transformer.py      |  76 +-
 .../models/minimax_h3/pipeline_minimax_h3.py  |  52 +-
 .../models/minimax_h3/checkpoint.py           |  29 +-
 11 files changed, 1053 insertions(+), 14 deletions(-)
 create mode 100644 tests/diffusion/models/minimax_h3/test_fasth3_checkpoint.py
 create mode 100644 vllm_omni/diffusion/models/minimax_h3/fasth3_checkpoint.py

diff --git a/recipes/MiniMaxAI/MiniMax-H3.md b/recipes/MiniMaxAI/MiniMax-H3.md
index b48a1f47229..934e882f78a 100644
--- a/recipes/MiniMaxAI/MiniMax-H3.md
+++ b/recipes/MiniMaxAI/MiniMax-H3.md
@@ -1106,6 +1106,68 @@ generations move the end-to-end figure toward the denoising one. Fusing the
 adapter does not measurably change startup: weight loading took 77.3 s with it
 against 85.8 s without.
 
+### FastH3 8-Step V2 full checkpoint
+
+[FastH3 8-Step V2](https://huggingface.co/FastVideo/FastVideo-FastH3-8-Step-V2)
+ships a full Diffusers-format transformer, including learned VSA compression
+gates. Serve the Hugging Face model ID or a downloaded snapshot directly:
+
+```bash
+export FASTH3_V2_MODEL=FastVideo/FastVideo-FastH3-8-Step-V2
+```
+
+Use a Hugging Face account with access to the release, and pin `--revision`
+when reproducing a result. The existing component loader reads its safetensors
+shards; the H3 weight loader maps names and loads Q/K/V and MLP projections into
+native parameters in memory. No conversion command or second transformer
+checkpoint is needed.
+
+The transformer and text components come from the V2 release. To retain Omni's
+native tiled and parallel VAE execution, the loader fetches only the video/audio
+VAEs from the `MiniMaxAI/MiniMax-H3` revision pinned in V2's `provenance.json`.
+Those components use the normal Hugging Face cache. No separate base-model
+argument or full base-transformer download is required. Download time is a
+preparation cost, separate from warmup and request latency.
+
+Install the optional `fastvideo-kernel` build required by the
+`FASTVIDEO_VSA` backend, including its H3 block-map entry point. A four-GPU
+configuration is:
+
+```bash
+CUDA_VISIBLE_DEVICES=0,1,2,3 vllm serve "${FASTH3_V2_MODEL}" --omni \
+  --host 127.0.0.1 --port 8095 --trust-remote-code --task-type fl2va \
+  --served-model-name FastH3-V2 \
+  --num-gpus 4 --usp 4 --ring 1 \
+  --vae-patch-parallel-size 4 --vae-parallel-mode tile --vae-use-tiling \
+  --diffusion-attention-backend FASTVIDEO_VSA
+
+curl --fail-with-body -sS http://127.0.0.1:8095/v1/videos/sync \
+  -F 'model=FastH3-V2' \
+  -F 'prompt=A red fox runs through fresh snow at dawn, with fast pawsteps, winter wind and distant birds.' \
+  -F 'width=1344' -F 'height=768' -F 'aspect_ratio=16:9' -F 'fps=24' \
+  -F 'num_inference_steps=8' -F 'guidance_scale=1' -F 'flow_shift=10' \
+  -F 'seed=1101' \
+  -F 'extra_params={"task":"t2va","duration":4.4,"audio_flow_shift":3.0}' \
+  -o fasth3_v2.mp4
+```
+
+V2 pins video/audio shifts **10/3**, guidance **1**, and the unshifted ladder
+`[0.999, 0.874, 0.749, 0.624, 0.5, 0.375, 0.25, 0.125, 0.0]`.
+Use **`num_inference_steps=8`** in Omni: these nine nodes bound eight model
+evaluations. FastVideo's `--steps 9` counts nodes instead. The existing H3 ODE
+update is reused without stochastic re-noising.
+
+The trained attention policy is **80% sparsity with 64-token video tiles**.
+Omni derives the number of selected video tiles from each request's geometry;
+do not supply a fixed `--fastvideo-vsa-topk`. Text/condition/audio prefix keys
+remain available to every query, and prefix queries remain dense. Missing VSA
+geometry or a failed H3 kernel raises an error instead of serving the student
+with dense attention.
+
+This release supports T2VA only, with local or pure Ulysses attention. Additional
+LoRA adapters, Ref2VA and FL2VA conditioning are unsupported. The legacy
+four-step adapter keeps its original sampling and fixed-top-k behavior.
+
 ## Key parameters
 
 | Parameter | Recommended value | Notes |
diff --git a/tests/diffusion/models/minimax_h3/test_fasth3_checkpoint.py b/tests/diffusion/models/minimax_h3/test_fasth3_checkpoint.py
new file mode 100644
index 00000000000..9a530bf9006
--- /dev/null
+++ b/tests/diffusion/models/minimax_h3/test_fasth3_checkpoint.py
@@ -0,0 +1,679 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterable
+
+import pytest
+import torch
+import torch.nn as nn
+
+from vllm_omni.diffusion.data import AttentionConfig, AttentionSpec, DiffusionParallelConfig, OmniDiffusionConfig
+from vllm_omni.diffusion.models.minimax_h3.fasth3_checkpoint import (
+    FASTH3_BASE_MODEL,
+    FASTH3_V2_BASE_SCHEDULE,
+    FASTH3_V2_MODEL_ID,
+    FastH3CheckpointSpec,
+)
+from vllm_omni.diffusion.models.minimax_h3.minimax_h3_transformer import (
+    MiniMaxH3DiTArchConfig,
+    MiniMaxH3DiTModel,
+)
+from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import (
+    resolve_minimax_h3_diffusion_model_path,
+)
+from vllm_omni.diffusion.sched.sigma_schedule import DMD2SigmaSchedule
+from vllm_omni.errors import OmniClientError
+from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+from vllm_omni.lora.request import LoRARequest
+from vllm_omni.model_executor.models.minimax_h3.checkpoint import (
+    is_minimax_h3_modular,
+    resolve_minimax_h3_model_root,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+def _fastvideo_metadata() -> dict[str, object]:
+    """Return the release-owned metadata read from fastvideo_inference.json."""
+    return {
+        "model_id": FASTH3_V2_MODEL_ID,
+        "schema_version": "fasth3-inference-contract-v1",
+        "dmd_denoising_steps": [999, 874, 749, 624, 500, 375, 250, 125],
+        "transformer_forwards": 8,
+        "video_scheduler_shift": 10.0,
+        "audio_scheduler_shift": 3.0,
+        "guidance_scale": 1.0,
+        "attention_backend": "VIDEO_SPARSE_ATTN_H3",
+        "vsa_sparsity": 0.8,
+        "vsa_tile_size": 64,
+        "task": "t2av",
+    }
+
+
+def _sampling(
+    *,
+    num_inference_steps: int | str | None = 8,
+    guidance_scale: float | None = 1.0,
+    extra_args: dict[str, object] | None = None,
+    lora_request: LoRARequest | None = None,
+    timesteps: torch.Tensor | None = None,
+    sigmas: list[float] | None = None,
+) -> OmniDiffusionSamplingParams:
+    return OmniDiffusionSamplingParams(
+        # Keep the string form to exercise malformed client input validation.
+        num_inference_steps=num_inference_steps,  # type: ignore[arg-type]
+        guidance_scale=guidance_scale,
+        extra_args=extra_args or {},
+        lora_request=lora_request,
+        timesteps=timesteps,
+        sigmas=sigmas,
+    )
+
+
+def _od_config(
+    *,
+    backend: str = "FASTVIDEO_VSA",
+    topk: int | None = None,
+    per_role: dict[str, AttentionSpec] | None = None,
+    lora_path: str | None = None,
+    ring_degree: int = 1,
+    allgather_degree: int = 1,
+) -> OmniDiffusionConfig:
+    attention_config = AttentionConfig(
+        default=AttentionSpec(backend=backend, fastvideo_vsa_topk=topk),
+        per_role=per_role or {},
+    )
+    return OmniDiffusionConfig(
+        diffusion_attention_config=attention_config,
+        lora_path=lora_path,
+        parallel_config=DiffusionParallelConfig(ring_degree=ring_degree, allgather_degree=allgather_degree),
+    )
+
+
+def test_v2_release_has_nine_sigma_nodes_and_eight_intervals():
+    assert FASTH3_V2_BASE_SCHEDULE.base_schedule == (
+        0.999,
+        0.874,
+        0.749,
+        0.624,
+        0.5,
+        0.375,
+        0.25,
+        0.125,
+        0.0,
+    )
+    assert len(FASTH3_V2_BASE_SCHEDULE.base_schedule) == 9
+    assert FASTH3_V2_BASE_SCHEDULE.num_inference_steps == 8
+    assert FASTH3_V2_BASE_SCHEDULE.shifted_sigmas(10.0) == pytest.approx(
+        [
+            0.9998999099189271,
+            0.985788405143244,
+            0.9675752486758817,
+            0.94316807738815,
+            0.9090909090909091,
+            0.8571428571428571,
+            0.7692307692307693,
+            0.5882352941176471,
+            0.0,
+        ],
+        abs=1e-12,
+    )
+    assert FASTH3_V2_BASE_SCHEDULE.shifted_sigmas(3.0) == pytest.approx(
+        [
+            0.9996664442961973,
+            0.9541484716157204,
+            0.8995196156925539,
+            0.8327402135231315,
+            0.75,
+            0.6428571428571429,
+            0.5,
+            0.3,
+            0.0,
+        ],
+        abs=1e-12,
+    )
+
+
+def test_fastvideo_metadata_builds_release_sampling_metadata():
+    spec = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+
+    assert spec.vsa_sparsity == 0.8
+    assert spec.release_metadata() == {
+        "partition": "fl2va",
+        "tasks": ["t2va"],
+        "sigma_shift_scales": {"video": 10.0, "audio": 3.0},
+        "base_schedule": list(FASTH3_V2_BASE_SCHEDULE.base_schedule),
+    }
+
+
+@pytest.mark.parametrize(
+    ("field", "value"),
+    [
+        ("model_id", "FastVideo/FastH3-other"),
+        ("schema_version", "fasth3-inference-contract-v0"),
+        ("dmd_denoising_steps", [999, 749, 500, 250]),
+        ("transformer_forwards", 4),
+        ("video_scheduler_shift", 12.0),
+        ("audio_scheduler_shift", 4.0),
+        ("guidance_scale", 2.0),
+        ("attention_backend", "FLASH_ATTN"),
+        ("vsa_sparsity", 0.9),
+        ("vsa_tile_size", 32),
+        ("task", "t2va"),
+    ],
+)
+def test_fastvideo_metadata_rejects_contract_drift(field, value):
+    metadata = _fastvideo_metadata()
+    metadata[field] = value
+
+    with pytest.raises(ValueError, match=field):
+        FastH3CheckpointSpec.from_metadata(metadata)
+
+
+def test_fastvideo_metadata_rejects_missing_contract_field():
+    metadata = _fastvideo_metadata()
+    metadata.pop("task")
+
+    with pytest.raises(ValueError, match="task"):
+        FastH3CheckpointSpec.from_metadata(metadata)
+
+
+def test_legacy_h3_metadata_is_not_treated_as_fastvideo_release():
+    with pytest.raises(ValueError, match="model_id"):
+        FastH3CheckpointSpec.from_metadata(
+            {
+                "schema_version": 1,
+                "partition": "fl2va",
+                "tasks": ["t2va", "fl2va"],
+                "sigma_shift_scales": {"video": 12.0, "audio": 3.0},
+            }
+        )
+
+
+def test_v2_serving_contract_accepts_backend_selected_for_h3_self_role():
+    config = _od_config(
+        backend="TORCH_SDPA",
+        per_role={"self": AttentionSpec(backend="FASTVIDEO_VSA")},
+    )
+    FastH3CheckpointSpec.from_metadata(_fastvideo_metadata()).check_serving_contract(
+        partition="fl2va", od_config=config
+    )
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "partition", "match"),
+    [
+        ({}, "ref2va", "task-type fl2va"),
+        ({"lora_path": "/tmp/adapter"}, "fl2va", "LoRA"),
+        ({"backend": "TORCH_SDPA"}, "fl2va", "FASTVIDEO_VSA"),
+        ({"topk": 2}, "fl2va", "fixed fastvideo_vsa_topk"),
+        ({"ring_degree": 2}, "fl2va", "local attention"),
+        ({"allgather_degree": 2}, "fl2va", "local attention"),
+    ],
+)
+def test_v2_serving_contract_rejects_incompatible_runtime(kwargs, partition, match):
+    spec = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+    with pytest.raises(ValueError, match=match):
+        spec.check_serving_contract(partition=partition, od_config=_od_config(**kwargs))
+
+
+def test_v2_serving_contract_reads_a_per_role_fixed_topk_override():
+    spec = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+    config = _od_config(
+        per_role={"self": AttentionSpec(backend="FASTVIDEO_VSA", fastvideo_vsa_topk=1)},
+    )
+    with pytest.raises(ValueError, match="fixed fastvideo_vsa_topk"):
+        spec.check_serving_contract(partition="fl2va", od_config=config)
+
+
+def test_v2_request_contract_accepts_omitted_steps_and_default_shifts():
+    spec = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+    spec.check_request(_sampling(num_inference_steps=None))
+    spec.check_request(_sampling(extra_args={"flow_shift": 10, "audio_flow_shift": 3}, guidance_scale=1))
+
+
+@pytest.mark.parametrize(
+    "sampling",
+    [
+        _sampling(num_inference_steps=None),
+        _sampling(timesteps=torch.tensor([0.9, 0.5, 0.0])),
+        _sampling(sigmas=[1.0, 0.5, 0.0]),
+    ],
+)
+def test_v2_step_execution_requires_pinned_count_and_schedule(sampling):
+    spec = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+    with pytest.raises(OmniClientError, match="step execution"):
+        spec.check_request(sampling, step_execution=True)
+
+
+def test_v2_step_execution_accepts_only_explicit_pinned_count():
+    spec = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+    spec.check_request(_sampling(num_inference_steps=8), step_execution=True)
+
+
+@pytest.mark.parametrize(
+    ("kwargs", "match"),
+    [
+        ({"num_inference_steps": 7}, "num_inference_steps=8"),
+        ({"num_inference_steps": 9}, "num_inference_steps=8"),
+        ({"num_inference_steps": "8"}, "num_inference_steps=8"),
+        ({"extra_args": {"flow_shift": 9}}, "flow_shift=10"),
+        ({"extra_args": {"audio_flow_shift": 4}}, "audio_flow_shift=3"),
+        ({"extra_args": {"flow_shift": "bad"}}, "flow_shift=10"),
+        ({"guidance_scale": 2.0}, "guidance_scale=1"),
+        (
+            {"lora_request": LoRARequest(lora_name="test", lora_int_id=1, lora_path="/tmp/test.safetensors")},
+            "per-request LoRA",
+        ),
+    ],
+)
+def test_v2_request_contract_rejects_sampling_drift(kwargs, match):
+    spec = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+    with pytest.raises(OmniClientError, match=match):
+        spec.check_request(_sampling(**kwargs))
+
+
+def test_resolve_native_vaes_uses_pinned_revision_and_only_vae_patterns(tmp_path, monkeypatch):
+    model_root = tmp_path / "FastH3"
+    model_root.mkdir()
+    revision = "base-revision-123"
+    (model_root / "provenance.json").write_text(
+        json.dumps({"base_model": f"hf://{FASTH3_BASE_MODEL}@{revision}"}),
+        encoding="utf-8",
+    )
+    snapshot = tmp_path / "hf-snapshot"
+    calls: dict[str, object] = {}
+
+    def fake_download(**kwargs: object) -> str:
+        calls.update(kwargs)
+        snapshot.mkdir()
+        return str(snapshot)
+
+    monkeypatch.setattr(
+        "vllm_omni.diffusion.models.minimax_h3.fasth3_checkpoint.download_weights_from_hf_specific",
+        fake_download,
+    )
+
+    result = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata()).resolve_native_vaes(model_root)
+
+    assert result == snapshot / "FL2VA"
+    assert calls == {
+        "model_name_or_path": FASTH3_BASE_MODEL,
+        "cache_dir": None,
+        "allow_patterns": ["FL2VA/video_vae/**", "FL2VA/audio_vae/**"],
+        "revision": revision,
+        "require_all": True,
+    }
+    assert sorted(path.name for path in model_root.iterdir()) == ["provenance.json"]
+    assert not (model_root / "model_index.json").exists()
+    assert not (model_root / "conversion.json").exists()
+
+
+@pytest.mark.parametrize(
+    "base_model",
+    [
+        "MiniMaxAI/MiniMax-H3@main",
+        "hf://MiniMaxAI/MiniMax-H3@",
+        "hf://Other/MiniMax-H3@revision",
+        "",
+        None,
+    ],
+)
+def test_resolve_native_vaes_rejects_unpinned_provenance(tmp_path, base_model):
+    model_root = tmp_path / "FastH3"
+    model_root.mkdir()
+    (model_root / "provenance.json").write_text(json.dumps({"base_model": base_model}), encoding="utf-8")
+
+    with pytest.raises(ValueError, match="provenance"):
+        FastH3CheckpointSpec.from_metadata(_fastvideo_metadata()).resolve_native_vaes(model_root)
+
+
+def test_modular_local_model_root_uses_text_encoder_without_partition_files(tmp_path):
+    root = tmp_path / "FastH3"
+    (root / "text_encoder").mkdir(parents=True)
+    (root / "text_encoder" / "config.json").write_text("{}", encoding="utf-8")
+    (root / "modular_model_index.json").write_text(
+        json.dumps({"_class_name": "MiniMaxH3ModularPipeline"}),
+        encoding="utf-8",
+    )
+
+    assert is_minimax_h3_modular(str(root)) is True
+    assert resolve_minimax_h3_model_root(str(root), None, "fl2va") == str(root / "text_encoder")
+    assert not (root / "FL2VA").exists()
+
+
+def test_modular_hub_model_root_downloads_only_text_encoder(monkeypatch, tmp_path):
+    from vllm_omni.model_executor.models.minimax_h3 import checkpoint as checkpoint_module
+
+    snapshot = tmp_path / "modular-snapshot"
+    calls: dict[str, object] = {}
+
+    def fake_index(model: str, *, revision: str | None = None) -> dict[str, str]:
+        assert model == "FastVideo/FastVideo-FastH3-8-Step-V2"
+        assert revision == "release-revision"
+        return {"_class_name": "MiniMaxH3ModularPipeline"}
+
+    def fake_download(**kwargs: object) -> str:
+        calls.update(kwargs)
+        snapshot.mkdir()
+        return str(snapshot)
+
+    monkeypatch.setattr(checkpoint_module, "get_diffusion_model_index", fake_index)
+    monkeypatch.setattr(checkpoint_module, "download_weights_from_hf_specific", fake_download)
+
+    result = resolve_minimax_h3_model_root(
+        "FastVideo/FastVideo-FastH3-8-Step-V2",
+        "release-revision",
+        "fl2va",
+    )
+
+    assert result == str(snapshot / "text_encoder")
+    assert calls == {
+        "model_name_or_path": "FastVideo/FastVideo-FastH3-8-Step-V2",
+        "cache_dir": None,
+        "allow_patterns": ["text_encoder/**"],
+        "revision": "release-revision",
+        "require_all": True,
+    }
+
+
+def test_native_hub_model_with_modular_class_keeps_partition_layout(monkeypatch):
+    from vllm_omni.model_executor.models.minimax_h3 import checkpoint as checkpoint_module
+
+    monkeypatch.setattr(
+        checkpoint_module,
+        "get_diffusion_model_index",
+        lambda _model, *, revision=None: {"_class_name": "MiniMaxH3ModularPipeline"},
+    )
+
+    assert checkpoint_module.is_minimax_h3_modular("MiniMaxAI/MiniMax-H3") is False
+
+
+def test_native_local_model_root_keeps_partition_layout(tmp_path):
+    root = tmp_path / "MiniMax-H3"
+    (root / "FL2VA" / "text_encoder").mkdir(parents=True)
+    (root / "FL2VA" / "text_encoder" / "config.json").write_text("{}", encoding="utf-8")
+
+    assert is_minimax_h3_modular(str(root)) is False
+    assert resolve_minimax_h3_model_root(str(root), None, "fl2va") == str(root / "FL2VA" / "text_encoder")
+
+
+def test_diffusion_resolver_returns_local_modular_root_without_partition_files(tmp_path):
+    root = tmp_path / "FastH3"
+    root.mkdir()
+    (root / "modular_model_index.json").write_text(
+        json.dumps({"_class_name": "MiniMaxH3ModularPipeline"}),
+        encoding="utf-8",
+    )
+
+    assert resolve_minimax_h3_diffusion_model_path(str(root), None, "fl2va") == str(root)
+    assert not (root / "FL2VA").exists()
+    assert not (root / "Ref2VA").exists()
+
+
+def test_diffusion_resolver_hub_modular_downloads_transformer_contract_only(monkeypatch, tmp_path):
+    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as pipeline_module
+
+    snapshot = tmp_path / "modular-snapshot"
+    calls: dict[str, object] = {}
+
+    def fake_modular(_model: str, _revision: str | None = None) -> bool:
+        return True
+
+    def fake_download(**kwargs: object) -> str:
+        calls.update(kwargs)
+        snapshot.mkdir()
+        return str(snapshot)
+
+    monkeypatch.setattr(pipeline_module, "is_minimax_h3_modular", fake_modular)
+    monkeypatch.setattr(pipeline_module, "download_weights_from_hf_specific", fake_download)
+
+    result = resolve_minimax_h3_diffusion_model_path(
+        "FastVideo/FastVideo-FastH3-8-Step-V2", "release-revision", "fl2va"
+    )
+
+    assert result == str(snapshot)
+    assert calls == {
+        "model_name_or_path": "FastVideo/FastVideo-FastH3-8-Step-V2",
+        "cache_dir": None,
+        "allow_patterns": [
+            "modular_model_index.json",
+            "fastvideo_inference.json",
+            "provenance.json",
+            "transformer/**",
+        ],
+        "revision": "release-revision",
+        "require_all": True,
+    }
+    patterns = calls["allow_patterns"]
+    assert isinstance(patterns, list)
+    assert all("video_vae" not in pattern and "audio_vae" not in pattern for pattern in patterns)
+
+
+def test_diffusers_arch_config_normalizes_all_aliases():
+    arch = MiniMaxH3DiTArchConfig.from_mapping(
+        {
+            "num_refiner_layers": 3,
+            "ffn_dim": 12,
+            "in_channels": 4,
+            "audio_in_channels": 6,
+            "freq_dim": 8,
+            "time_embed_hidden_dim": 10,
+            "rope_freq_dim": 5,
+            "patch_size": [1, 2, 2],
+        }
+    )
+
+    assert arch.token_refiner_num_layers == 3
+    assert arch.ffn_hidden_size == 12
+    assert arch.latents_dim == 4
+    assert arch.audio_latents_dim == 6
+    assert arch.timestep_input_dim == 8
+    assert arch.time_embed_hidden_size == 10
+    assert arch.rope_inv_freq_len == 5
+    assert arch.patch_size == (1, 2, 2)
+
+
+class _WeightTarget(nn.Module):
+    def __init__(self, shape: tuple[int, ...], loader: Callable[..., None]) -> None:
+        super().__init__()
+        self.weight = nn.Parameter(torch.zeros(shape))
+        self.weight.weight_loader = loader
+
+
+class _PipelineLoadTransformer(nn.Module):
+    def __init__(self, loaded: set[str]) -> None:
+        super().__init__()
+        self.arch = MiniMaxH3DiTArchConfig(num_layers=1)
+        self._loaded = loaded
+
+    def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
+        list(weights)
+        return self._loaded
+
+    def post_load_weights(self) -> None:
+        pass
+
+
+def test_pipeline_load_weights_rejects_missing_fast_h3_compression_gate():
+    from vllm_omni.diffusion.models.minimax_h3.pipeline_minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    nn.Module.__init__(pipeline)
+    pipeline.transformer = _PipelineLoadTransformer({"blocks.0.attn.qkv_proj.weight"})
+    pipeline.video_vae = None
+    pipeline.audio_vae = None
+    pipeline._fasth3 = None
+    pipeline._fasth3_checkpoint = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+
+    with pytest.raises(ValueError, match="missing compression gates"):
+        pipeline.load_weights([("transformer.blocks.0.attn.qkv_proj.weight", torch.zeros(1))])
+
+
+def _load_fixture(
+    *, diffusers_weights: bool
+) -> tuple[MiniMaxH3DiTModel, list[tuple[str | None, torch.Tensor]], list[tuple[int, torch.Tensor]]]:
+    model = object.__new__(MiniMaxH3DiTModel)
+    nn.Module.__init__(model)
+    model.arch = MiniMaxH3DiTArchConfig(
+        num_layers=1,
+        hidden_size=3,
+        num_attention_heads=2,
+        attention_head_dim=2,
+        ffn_hidden_size=6,
+        rope_inv_freq_len=2,
+    )
+    model._diffusers_weights = diffusers_weights
+    model._rope_theta = 10000.0
+    qkv_calls: list[tuple[str | None, torch.Tensor]] = []
+    fc1_calls: list[tuple[int, torch.Tensor]] = []
+
+    def qkv_loader(param: nn.Parameter, loaded_weight: torch.Tensor, shard_id: str | None = None) -> None:
+        if shard_id is None:
+            assert loaded_weight.shape == (12, 3)
+            param.data.copy_(loaded_weight)
+            qkv_calls.append((None, loaded_weight.clone()))
+            return
+        assert loaded_weight.shape == (4, 3)
+        assert shard_id in {"q", "k", "v"}
+        offset = {"q": 0, "k": 4, "v": 8}[shard_id]
+        param.data[offset : offset + 4].copy_(loaded_weight)
+        qkv_calls.append((shard_id, loaded_weight.clone()))
+
+    def fc1_loader(param: nn.Parameter, loaded_weight: torch.Tensor, shard_id: int) -> None:
+        assert loaded_weight.shape == (3, 3)
+        param.data[shard_id * 3 : (shard_id + 1) * 3].copy_(loaded_weight)
+        fc1_calls.append((shard_id, loaded_weight.clone()))
+
+    model.blocks = nn.ModuleList([nn.Module()])
+    model.blocks[0].attn = nn.Module()
+    model.blocks[0].attn.qkv_proj = _WeightTarget((12, 3), qkv_loader)
+    model.blocks[0].mlp = nn.Module()
+    model.blocks[0].mlp.fc1 = _WeightTarget((6, 3), fc1_loader)
+    model.rope = nn.Module()
+    model.rope.register_buffer("inv_freq", torch.zeros(2))
+    return model, qkv_calls, fc1_calls
+
+
+def test_diffusers_load_weights_uses_shape_aware_qkv_and_mlp_slices():
+    model, qkv_calls, fc1_calls = _load_fixture(diffusers_weights=True)
+    q = torch.arange(12, dtype=torch.float32).reshape(4, 3) + 10
+    k = torch.arange(12, dtype=torch.float32).reshape(4, 3) + 100
+    v = torch.arange(12, dtype=torch.float32).reshape(4, 3) + 200
+    mlp = torch.arange(18, dtype=torch.float32).reshape(6, 3) + 300
+
+    loaded = model.load_weights(
+        [
+            ("transformer_blocks.0.attn.to_q.weight", q),
+            ("transformer_blocks.0.attn.to_k.weight", k),
+            ("transformer_blocks.0.attn.to_v.weight", v),
+            ("transformer_blocks.0.ff.net.0.proj.weight", mlp),
+        ]
+    )
+
+    assert loaded == {
+        "blocks.0.attn.qkv_proj.weight",
+        "blocks.0.mlp.fc1.weight",
+        "rope.inv_freq",
+    }
+    assert [shard_id for shard_id, _ in qkv_calls] == ["q", "k", "v"]
+    assert [shard_id for shard_id, _ in fc1_calls] == [0, 1]
+    torch.testing.assert_close(model.blocks[0].attn.qkv_proj.weight, torch.cat((q, k, v)))
+    torch.testing.assert_close(model.blocks[0].mlp.fc1.weight, torch.cat((mlp[3:], mlp[:3])))
+    torch.testing.assert_close(
+        model.rope.inv_freq,
+        1.0 / (10000.0 ** (torch.arange(0, 4, 2, dtype=torch.float32) / 4)),
+        rtol=0,
+        atol=0,
+    )
+
+
+def test_native_load_weights_keeps_grouped_qkv_and_gate_first_layouts():
+    model, qkv_calls, fc1_calls = _load_fixture(diffusers_weights=False)
+    grouped_qkv = torch.arange(36, dtype=torch.float32).reshape(12, 3)
+    fc1 = torch.arange(18, dtype=torch.float32).reshape(6, 3)
+
+    loaded = model.load_weights(
+        [
+            ("blocks.0.attn.qkv_proj.weight", grouped_qkv),
+            ("blocks.0.mlp.fc1.weight", fc1),
+        ]
+    )
+
+    expected_qkv = torch.cat(
+        (
+            grouped_qkv[:2],
+            grouped_qkv[6:8],
+            grouped_qkv[2:4],
+            grouped_qkv[8:10],
+            grouped_qkv[4:6],
+            grouped_qkv[10:],
+        )
+    )
+    assert loaded == {"blocks.0.attn.qkv_proj.weight", "blocks.0.mlp.fc1.weight"}
+    assert [shard_id for shard_id, _ in qkv_calls] == [None]
+    assert [shard_id for shard_id, _ in fc1_calls] == [0, 1]
+    torch.testing.assert_close(model.blocks[0].attn.qkv_proj.weight, expected_qkv)
+    torch.testing.assert_close(model.blocks[0].mlp.fc1.weight, fc1)
+    assert torch.equal(model.rope.inv_freq, torch.zeros(2))
+
+
+def test_diffusers_load_weights_rejects_unknown_name():
+    model, _, _ = _load_fixture(diffusers_weights=True)
+
+    with pytest.raises(ValueError, match="unsupported Diffusers H3 weight"):
+        model.load_weights([("transformer_blocks.0.attn.not_a_projection.weight", torch.zeros(4, 3))])
+
+
+def test_diffusers_load_weights_rejects_duplicate_source_name():
+    model, _, _ = _load_fixture(diffusers_weights=True)
+    weight = torch.zeros(4, 3)
+
+    with pytest.raises(ValueError, match="duplicate Diffusers H3 weight"):
+        model.load_weights(
+            [
+                ("transformer_blocks.0.attn.to_q.weight", weight),
+                ("transformer_blocks.0.attn.to_q.weight", weight),
+            ]
+        )
+
+
+def test_diffusers_load_weights_rejects_incomplete_qkv_group():
+    model, _, _ = _load_fixture(diffusers_weights=True)
+
+    with pytest.raises(ValueError, match="incomplete Diffusers H3 QKV"):
+        model.load_weights(
+            [
+                ("transformer_blocks.0.attn.to_q.weight", torch.zeros(4, 3)),
+                ("transformer_blocks.0.attn.to_k.weight", torch.zeros(4, 3)),
+            ]
+        )
+
+
+def test_diffusers_load_weights_rejects_missing_compression_gate_parameter():
+    model, _, _ = _load_fixture(diffusers_weights=True)
+
+    with pytest.raises(ValueError, match="has no model parameter"):
+        model.load_weights([("transformer_blocks.0.attn.to_gate_compress.weight", torch.zeros(4, 3))])
+
+
+def test_resolve_sigma_positions_uses_release_metadata_schedule():
+    from vllm_omni.diffusion.models.minimax_h3 import MiniMaxH3Pipeline
+
+    pipeline = object.__new__(MiniMaxH3Pipeline)
+    nn.Module.__init__(pipeline)
+    pipeline._fasth3 = None
+    pipeline._lora_sigma_schedules = {}
+    spec = FastH3CheckpointSpec.from_metadata(_fastvideo_metadata())
+    pipeline._base_schedule_by_partition = {
+        "fl2va": DMD2SigmaSchedule.from_metadata(spec.release_metadata()),
+    }
+
+    positions, steps = pipeline._resolve_sigma_positions("t2va", _sampling())
+    assert positions == FASTH3_V2_BASE_SCHEDULE.base_schedule
+    assert steps == 8 == len(positions) - 1
+    with pytest.raises(OmniClientError, match="must be 8"):
+        pipeline._resolve_sigma_positions("t2va", _sampling(num_inference_steps=9))
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
index 4b6fc0d8820..cea4862d15c 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
@@ -423,6 +423,7 @@ def fake_download(**kwargs):
     assert pipeline.partition == expected_partition
     assert pipeline.supported_tasks == expected_tasks
     assert len(created["dit"]) == expected_dits
+    assert all(kwargs["diffusers_weights"] is False for _, kwargs in created["dit"])
     component_path = tmp_path / component_partition
     assert created["video_vae"] == [str(component_path / "video_vae")]
     assert created["audio_vae"] == [str(component_path / "audio_vae")]
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_fasth3.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_fasth3.py
index 5c874ff02d1..c89c37db9a2 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_fasth3.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_fasth3.py
@@ -262,7 +262,10 @@ def test_a_vsa_variant_is_recognised_by_its_compression_gates(tmp_path):
 
 def test_a_tensor_naming_no_h3_parameter_is_an_error(tmp_path):
     path = tmp_path / "fasth3" / "adapter_model.safetensors"
-    _write_adapter(path, tensors={"transformer_blocks.0.attn.norm_q.lora_A.weight": torch.ones((_RANK, _HIDDEN))})
+    _write_adapter(
+        path,
+        tensors={"transformer_blocks.0.attn.not_a_projection.lora_A.weight": torch.ones((_RANK, _HIDDEN))},
+    )
     # Dropping it silently would load a model that is not the distilled student.
     with pytest.raises(FastH3AdapterError, match="name no known"):
         _load(path.parent)
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization.py
index 92bd09ac270..e1f83fd014f 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization.py
@@ -1,4 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from types import SimpleNamespace
 from unittest.mock import Mock
@@ -41,7 +42,7 @@ def __init__(self, **kwargs):
         super().__init__()
 
 
-def _small_od_config():
+def _small_od_config(*, class_name=None):
     arch = {
         "num_layers": 1,
         "token_refiner_num_layers": 1,
@@ -60,6 +61,8 @@ def _small_od_config():
         "final_adaln_out_features": 2 * 8,
         "rope_inv_freq_len": 2,
     }
+    if class_name is not None:
+        arch["_class_name"] = class_name
     return SimpleNamespace(
         tf_model_config=arch,
         parallel_config=SimpleNamespace(ulysses_degree=1),
@@ -133,6 +136,24 @@ def test_fp8_scope_and_prefix_propagation(monkeypatch):
     )
 
 
+def test_explicit_native_weight_format_overrides_diffusers_class_name(monkeypatch):
+    from vllm_omni.diffusion.models.minimax_h3 import minimax_h3_transformer as h3
+
+    monkeypatch.setattr(h3, "ColumnParallelLinear", _FakeLinear)
+    monkeypatch.setattr(h3, "MergedColumnParallelLinear", _FakeLinear)
+    monkeypatch.setattr(h3, "QKVParallelLinear", _FakeLinear)
+    monkeypatch.setattr(h3, "RowParallelLinear", _FakeLinear)
+    monkeypatch.setattr(h3, "Attention", _FakeAttention)
+    monkeypatch.setattr(h3, "get_tensor_model_parallel_world_size", lambda: 1)
+
+    model = h3.MiniMaxH3DiTModel(
+        _small_od_config(class_name="MiniMaxH3Transformer3DModel"),
+        diffusers_weights=False,
+    )
+
+    assert model._diffusers_weights is False
+
+
 class _WeightTarget(nn.Module):
     def __init__(self, loader):
         super().__init__()
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
index 87b04613a14..3beda5acca9 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_quantization_quality.py
@@ -187,7 +187,11 @@ def test_minimax_h3_quantization_quality(config: QualityTestConfig):
         "model": model_ref,
         "enforce_eager": True,
         # The fused BF16 baseline only fits on H100-80GB with encoder TP.
-        "stage_0_tensor_parallel_size": 2,
+        # This test loads the direct FL2VA diffusion pipeline (not the
+        # disaggregated two-stage MiniMax-H3 pipeline), so configure both the
+        # DiT world and the Qwen3-VL encoder TP explicitly.
+        "tensor_parallel_size": 2,
+        "text_encoder_tp_size": 2,
         "vae_use_tiling": True,
         # MiniMax H3's VAE is implemented by code shipped with the checkpoint.
         "trust_remote_code": True,
diff --git a/vllm_omni/diffusion/models/minimax_h3/fasth3.py b/vllm_omni/diffusion/models/minimax_h3/fasth3.py
index c4860c57ec4..dcc51302867 100644
--- a/vllm_omni/diffusion/models/minimax_h3/fasth3.py
+++ b/vllm_omni/diffusion/models/minimax_h3/fasth3.py
@@ -102,6 +102,7 @@
     "time_embedder.linear_2": "time_embedder.proj_out",
     "norm_out.linear": "final_layer.adaln_proj.linear",
     "norm_out.norm": "final_layer.norm",
+    "token_refiner.final_norm": "token_refiner.final_norm",
 }
 
 # Per-block adapter suffix -> (native suffix, how a delta enters the native
@@ -115,6 +116,8 @@
     "attn.to_v": ("attn.qkv_proj", _QKV_V),
     "attn.to_out.0": ("attn.out_proj", _PLAIN),
     "attn.to_gate_compress": ("attn.to_gate_compress", _PLAIN),
+    "attn.norm_q": ("attn.q_norm", _PLAIN),
+    "attn.norm_k": ("attn.k_norm", _PLAIN),
     "ff.net.0.proj": ("mlp.fc1", _SWAP_HALVES),
     "ff.net.2": ("mlp.fc2", _PLAIN),
     "adaln_proj.linear": ("adaln_proj.linear", _PLAIN),
diff --git a/vllm_omni/diffusion/models/minimax_h3/fasth3_checkpoint.py b/vllm_omni/diffusion/models/minimax_h3/fasth3_checkpoint.py
new file mode 100644
index 00000000000..0382e92208b
--- /dev/null
+++ b/vllm_omni/diffusion/models/minimax_h3/fasth3_checkpoint.py
@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Sampling contract for FastVideo FastH3 full checkpoints."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from vllm_omni.diffusion.sched.sigma_schedule import DMD2SigmaSchedule
+from vllm_omni.errors import OmniClientError
+from vllm_omni.model_executor.model_loader.weight_utils import download_weights_from_hf_specific
+
+from .fasth3 import FASTH3_BASE_MODEL, _resolve_dit_attention_backend
+
+if TYPE_CHECKING:
+    from vllm_omni.diffusion.data import OmniDiffusionConfig
+    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+FASTH3_V2_MODEL_ID = "FastVideo/FastVideo-FastH3-8-Step-V2"
+FASTH3_V2_BASE_SCHEDULE = DMD2SigmaSchedule.from_positions((0.999, 0.874, 0.749, 0.624, 0.5, 0.375, 0.25, 0.125, 0.0))
+
+
+@dataclass(frozen=True)
+class FastH3CheckpointSpec:
+    """The full V2 release has its own schedule and trained attention policy.
+
+    This is independent of ``FastH3WeightFusion``: the released weights already
+    contain the entire student, including its learned compression gates.
+    """
+
+    vsa_sparsity: float = 0.8
+
+    @classmethod
+    def from_metadata(cls, metadata: Mapping[str, object]) -> FastH3CheckpointSpec:
+        """Validate the release's own fastvideo_inference.json."""
+        required = {
+            "model_id": FASTH3_V2_MODEL_ID,
+            "schema_version": "fasth3-inference-contract-v1",
+            "dmd_denoising_steps": [999, 874, 749, 624, 500, 375, 250, 125],
+            "transformer_forwards": 8,
+            "video_scheduler_shift": 10.0,
+            "audio_scheduler_shift": 3.0,
+            "guidance_scale": 1.0,
+            "attention_backend": "VIDEO_SPARSE_ATTN_H3",
+            "vsa_sparsity": 0.8,
+            "vsa_tile_size": 64,
+            "task": "t2av",
+        }
+        for key, expected in required.items():
+            if metadata.get(key) != expected:
+                raise ValueError(f"unsupported FastH3 contract: {key}={metadata.get(key)!r}, expected {expected!r}")
+        return cls()
+
+    def release_metadata(self) -> dict[str, Any]:
+        """Express the sampling policy in the existing H3 pipeline schema."""
+        return {
+            "partition": "fl2va",
+            "tasks": ["t2va"],
+            "sigma_shift_scales": {"video": 10.0, "audio": 3.0},
+            "base_schedule": list(FASTH3_V2_BASE_SCHEDULE.base_schedule),
+        }
+
+    def resolve_native_vaes(self, model_root: Path) -> Path:
+        """Reuse the frozen base VAEs with Omni's native tiled/parallel runtime.
+
+        Only VAE components are fetched; the student and text encoder come
+        directly from the FastVideo release. The release pins the base revision.
+        """
+        provenance = json.loads((model_root / "provenance.json").read_text(encoding="utf-8"))
+        base = provenance.get("base_model", "")
+        prefix = f"hf://{FASTH3_BASE_MODEL}@"
+        if not isinstance(base, str) or not base.startswith(prefix) or not base[len(prefix) :]:
+            raise ValueError("FastH3 V2 provenance must pin a MiniMaxAI/MiniMax-H3 base revision")
+        return (
+            Path(
+                download_weights_from_hf_specific(
+                    model_name_or_path=FASTH3_BASE_MODEL,
+                    cache_dir=None,
+                    allow_patterns=["FL2VA/video_vae/**", "FL2VA/audio_vae/**"],
+                    revision=base[len(prefix) :],
+                    require_all=True,
+                )
+            )
+            / "FL2VA"
+        )
+
+    def check_serving_contract(self, *, partition: str, od_config: OmniDiffusionConfig) -> None:
+        if partition != "fl2va":
+            raise ValueError("FastH3 V2 requires --task-type fl2va (T2VA requests only)")
+        if getattr(od_config, "lora_path", None):
+            raise ValueError("FastH3 V2 is a full checkpoint; additional LoRA adapters are unsupported")
+        if _resolve_dit_attention_backend(od_config) != "FASTVIDEO_VSA":
+            raise ValueError("FastH3 V2 requires --diffusion-attention-backend FASTVIDEO_VSA")
+        attention_config = getattr(od_config, "diffusion_attention_config", None)
+        per_role = getattr(attention_config, "per_role", None) or {}
+        spec = per_role.get("self") or getattr(attention_config, "default", None)
+        if getattr(spec, "fastvideo_vsa_topk", None) is not None:
+            raise ValueError("FastH3 V2 pins VSA sparsity=0.8; remove the fixed fastvideo_vsa_topk override")
+        parallel = getattr(od_config, "parallel_config", None)
+        if any(int(getattr(parallel, key, 1) or 1) != 1 for key in ("ring_degree", "allgather_degree")):
+            raise ValueError("FastH3 V2 supports local attention or pure Ulysses sequence parallelism")
+
+    def check_request(self, sampling: OmniDiffusionSamplingParams, *, step_execution: bool = False) -> None:
+        if step_execution:
+            # StepScheduler admits requests before the pipeline hook runs and
+            # derives its lifetime from these fields.  The pinned schedule must
+            # therefore be explicit and cannot be overridden by custom arrays.
+            if sampling.num_inference_steps != FASTH3_V2_BASE_SCHEDULE.num_inference_steps:
+                raise OmniClientError("FastH3 V2 step execution requires num_inference_steps=8")
+            if sampling.timesteps is not None or sampling.sigmas is not None:
+                raise OmniClientError("FastH3 V2 step execution does not support custom timesteps or sigmas")
+        if sampling.lora_request is not None:
+            raise OmniClientError("FastH3 V2 does not support per-request LoRA adapters")
+        steps = sampling.num_inference_steps
+        if steps is not None and steps != FASTH3_V2_BASE_SCHEDULE.num_inference_steps:
+            raise OmniClientError("FastH3 V2 requires num_inference_steps=8 (nine sigma points), or omitted")
+        extra = sampling.extra_args or {}
+        for key, expected in (("flow_shift", 10.0), ("audio_flow_shift", 3.0)):
+            try:
+                value = float(extra.get(key, expected))
+            except (TypeError, ValueError) as exc:
+                raise OmniClientError(f"FastH3 V2 requires {key}={expected:g}") from exc
+            if not math.isclose(value, expected):
+                raise OmniClientError(f"FastH3 V2 requires {key}={expected:g}, got {value:g}")
+        if sampling.guidance_scale is not None and sampling.guidance_scale != 1.0:
+            raise OmniClientError("FastH3 V2 requires guidance_scale=1")
diff --git a/vllm_omni/diffusion/models/minimax_h3/minimax_h3_transformer.py b/vllm_omni/diffusion/models/minimax_h3/minimax_h3_transformer.py
index e26493931b6..5662a964119 100644
--- a/vllm_omni/diffusion/models/minimax_h3/minimax_h3_transformer.py
+++ b/vllm_omni/diffusion/models/minimax_h3/minimax_h3_transformer.py
@@ -55,6 +55,8 @@
 from vllm_omni.diffusion.models.host_weight_contract import FinalLayoutModelContract
 from vllm_omni.platforms import current_omni_platform
 
+from .fasth3 import _resolve_native_target
+
 if TYPE_CHECKING:
     from vllm.model_executor.layers.quantization.base_config import (
         QuantizationConfig,
@@ -118,6 +120,18 @@ class MiniMaxH3DiTArchConfig:
 
     @classmethod
     def from_mapping(cls, config: Mapping[str, Any]) -> MiniMaxH3DiTArchConfig:
+        # The modular Diffusers checkpoint uses these spellings for the same
+        # architecture. Normalize before constructing the existing native DiT.
+        aliases = {
+            "num_refiner_layers": "token_refiner_num_layers",
+            "ffn_dim": "ffn_hidden_size",
+            "in_channels": "latents_dim",
+            "audio_in_channels": "audio_latents_dim",
+            "freq_dim": "timestep_input_dim",
+            "time_embed_hidden_dim": "time_embed_hidden_size",
+            "rope_freq_dim": "rope_inv_freq_len",
+        }
+        config = {aliases.get(name, name): value for name, value in config.items()}
         fields = cls.__dataclass_fields__
         values = {name: config[name] for name in fields if name in config}
         if "patch_size" in values:
@@ -394,6 +408,9 @@ def _sdpa_varlen_attention(
 
 
 class MiniMaxH3Attention(nn.Module):
+    # Full sparse checkpoints pin a ratio; legacy adapters use backend top-k.
+    vsa_sparsity: float | None = None
+
     def __init__(
         self,
         arch: MiniMaxH3DiTArchConfig,
@@ -588,6 +605,7 @@ def _run_packed_attention(
                 # (see MINIMAX_H3_LASER_INPUT_SCALE). Ignored by every other
                 # backend/path.
                 "laser_input_scale": MINIMAX_H3_LASER_INPUT_SCALE,
+                **({"vsa_h3_sparsity": self.vsa_sparsity} if self.vsa_sparsity is not None else {}),
                 # Present only for a VSA artifact; the VSA backend reads it as
                 # the learned compression gate and every other backend ignores it.
                 **({"gate_compress": gate_compress.unsqueeze(0)} if gate_compress is not None else {}),
@@ -1127,10 +1145,23 @@ def __init__(
         self,
         od_config: OmniDiffusionConfig,
         quant_config: QuantizationConfig | None = None,
+        *,
+        diffusers_weights: bool | None = None,
     ) -> None:
         super().__init__()
         tf_config = od_config.tf_model_config
         config_mapping = tf_config.to_dict() if hasattr(tf_config, "to_dict") else dict(tf_config)
+        # The native MiniMax-H3 Hub snapshot advertises the Diffusers
+        # transformer class in its root config, while its FL2VA/Ref2VA
+        # components still contain native weights.  The pipeline has already
+        # resolved the actual source format, so let it override the
+        # class-name heuristic.  Keep the heuristic for standalone callers.
+        self._diffusers_weights = (
+            config_mapping.get("_class_name") == "MiniMaxH3Transformer3DModel"
+            if diffusers_weights is None
+            else diffusers_weights
+        )
+        self._rope_theta = float(config_mapping.get("rope_theta", 10000.0))
         arch = MiniMaxH3DiTArchConfig.from_mapping(config_mapping)
         self.arch = arch
         self.od_config = od_config
@@ -1211,7 +1242,7 @@ def __init__(
         )
         self._mark_missing_params_required()
 
-    def enable_vsa_gates(self) -> None:
+    def enable_vsa_gates(self, *, sparsity: float | None = None) -> None:
         """Give every DiT block's attention a VSA compression gate.
 
         A FastH3 VSA artifact assigns these projections rather than adding to
@@ -1223,6 +1254,9 @@ def enable_vsa_gates(self) -> None:
             return
         for block in self.blocks:
             block.attn.enable_vsa_gate()
+            block.attn.vsa_sparsity = sparsity
+            if sparsity is not None:
+                block.attn.to_gate_compress.weight.missing_param_init = "error"
         self.vsa_gates_enabled = True
 
     def _mark_missing_params_required(self) -> None:
@@ -1293,17 +1327,37 @@ def load_weights(
         self,
         weights: Iterable[tuple[str, torch.Tensor]],
     ) -> set[str]:
-        """Load exact H3 checkpoint names with logical TP-aware loaders."""
+        """Load native or Diffusers H3 weights with the existing TP-aware loaders."""
         params = dict(self.named_parameters())
         params.update(dict(self.named_buffers()))
         loaded: set[str] = set()
+        diffusers_weights = getattr(self, "_diffusers_weights", False)
+        qkv_parts: dict[str, set[str]] = {}
+        source_names: set[str] = set()
         for name, loaded_weight in weights:
+            layout = "plain"
+            if diffusers_weights:
+                if name in source_names:
+                    raise ValueError(f"duplicate Diffusers H3 weight: {name}")
+                source_names.add(name)
+                module, _, kind = name.rpartition(".")
+                target = _resolve_native_target(module)
+                if target is None or kind not in {"weight", "bias"}:
+                    raise ValueError(f"unsupported Diffusers H3 weight: {name}")
+                name, layout = f"{target[0]}.{kind}", target[1]
             param = params.get(name)
             if param is None:
+                if diffusers_weights:
+                    raise ValueError(f"Diffusers H3 weight has no model parameter: {name}")
                 logger.warning("Skipping MiniMax H3 weight not present in model: %s", name)
                 continue
             weight_loader = getattr(param, "weight_loader", default_weight_loader)
-            if name.endswith(".attn.qkv_proj.weight"):
+            if layout in {"q", "k", "v"}:
+                # vLLM can load each projection directly into its packed QKV
+                # parameter, including TP slicing and online quantization.
+                weight_loader(param, loaded_weight, layout)
+                qkv_parts.setdefault(name, set()).add(layout)
+            elif name.endswith(".attn.qkv_proj.weight"):
                 # Transform checkpoint layout before entering vLLM's loader so
                 # online FP8 can keep ``online_process_loader`` outermost.
                 loaded_weight = _reorder_grouped_qkv_to_qkv(
@@ -1319,12 +1373,26 @@ def load_weights(
                         "MiniMax H3 fc1 checkpoint rows must split evenly into "
                         f"gate/up matrices, got {tuple(loaded_weight.shape)}"
                     )
-                gate, up = loaded_weight.chunk(2, dim=0)
+                first, second = loaded_weight.chunk(2, dim=0)
+                gate, up = (second, first) if layout == "swap_halves" else (first, second)
                 weight_loader(param, gate, 0)
                 weight_loader(param, up, 1)
             else:
                 weight_loader(param, loaded_weight)
             loaded.add(name)
+        if diffusers_weights:
+            for name, parts in qkv_parts.items():
+                if parts != {"q", "k", "v"}:
+                    raise ValueError(f"incomplete Diffusers H3 QKV group {name}: {sorted(parts)}")
+            # Diffusers reconstructs RoPE from config instead of storing this
+            # native checkpoint buffer. Compute on CPU for identical values.
+            freq_dim = self.arch.rope_inv_freq_len
+            rope = 1.0 / (
+                self._rope_theta
+                ** (torch.arange(0, 2 * freq_dim, 2, dtype=torch.float32, device="cpu") / (2 * freq_dim))
+            )
+            default_weight_loader(params["rope.inv_freq"], rope)
+            loaded.add("rope.inv_freq")
         return loaded
 
     @staticmethod
diff --git a/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py b/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
index 1b8bd7feabb..60d6f412538 100644
--- a/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
+++ b/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
@@ -67,6 +67,7 @@
     download_weights_from_hf_specific,
 )
 from vllm_omni.model_executor.models.minimax_h3.checkpoint import (
+    is_minimax_h3_modular,
     resolve_minimax_h3_partition,
 )
 from vllm_omni.model_executor.models.minimax_h3.conditioning import (
@@ -106,6 +107,7 @@
 )
 from .encoder import MiniMaxH3Qwen3VLEncoder
 from .fasth3 import FastH3WeightFusion, resolve_fasth3_fusion
+from .fasth3_checkpoint import FastH3CheckpointSpec
 from .lora import TurboSpec, load_minimax_h3_turbo_lora
 from .minimax_h3_transformer import (
     MiniMaxH3Attention,
@@ -213,7 +215,11 @@ def _resolve_minimax_h3_model_root(
         if path.name in {"FL2VA", "Ref2VA"}:
             return path.parent
         return path
-    if load_text_encoder:
+    if is_minimax_h3_modular(model, revision):
+        allow_patterns = ["modular_model_index.json", "fastvideo_inference.json", "provenance.json", "transformer/**"]
+        if load_text_encoder:
+            allow_patterns += ["text_encoder/**", "tokenizer/**", "processor/**"]
+    elif load_text_encoder:
         allow_patterns = (
             MINIMAX_H3_DOWNLOAD_PATTERNS if partition == "combined" else MINIMAX_H3_TASK_DOWNLOAD_PATTERNS[partition]
         )
@@ -314,6 +320,8 @@ def resolve_minimax_h3_diffusion_model_path(
         partition,
         load_text_encoder=False,
     )
+    if is_minimax_h3_modular(str(model_root), revision):
+        return str(model_root)
     if partition == "combined":
         return str(model_root)
     subdir = "Ref2VA" if partition == "ref2va" else "FL2VA"
@@ -575,6 +583,7 @@ class MiniMaxH3Pipeline(
     _base_schedule_by_partition: ClassVar[Mapping[str, DMD2SigmaSchedule | None]] = {}
     # Set from --lora-path during construction; absent means no FastH3 adapter.
     _fasth3: FastH3WeightFusion | None = None
+    _fasth3_checkpoint: FastH3CheckpointSpec | None = None
 
     def _load_diffusion_lora_adapter(
         self,
@@ -800,10 +809,13 @@ def __init__(
             self._PROFILER_TARGETS.remove("encode_prompt")
         if not self.load_vae_encoder:
             self._PROFILER_TARGETS.remove("_encode_local_media")
+        modular = is_minimax_h3_modular(str(od_config.model), od_config.revision)
         self.partition = _minimax_h3_partition_for_task(
             getattr(od_config, "task_type", None),
             str(od_config.model),
         )
+        if modular and str(od_config.task_type or "auto").lower() == "auto":
+            self.partition = "fl2va"
         self._turbo_lora_specs: dict[int, TurboSpec] = {}
         self._native_lora_adapter_ids: set[int] = set()
         self._lora_sigma_schedules: dict[int, DMD2SigmaSchedule] = {}
@@ -813,9 +825,19 @@ def __init__(
             self.partition,
             load_text_encoder=self.load_text_encoder,
         )
-        model_path = model_root / ("Ref2VA" if self.partition == "ref2va" else "FL2VA")
-        model_index = json.loads((model_path / "model_index.json").read_text(encoding="utf-8"))
-        release = model_index.get("_minimax_h3") or {}
+        if modular:
+            model_path = model_root
+            self._fasth3_checkpoint = FastH3CheckpointSpec.from_metadata(
+                json.loads((model_root / "fastvideo_inference.json").read_text(encoding="utf-8"))
+            )
+            self._fasth3_checkpoint.check_serving_contract(partition=self.partition, od_config=od_config)
+            release = self._fasth3_checkpoint.release_metadata()
+            vae_model_path = self._fasth3_checkpoint.resolve_native_vaes(model_root)
+        else:
+            model_path = model_root / ("Ref2VA" if self.partition == "ref2va" else "FL2VA")
+            model_index = json.loads((model_path / "model_index.json").read_text(encoding="utf-8"))
+            release = model_index.get("_minimax_h3") or {}
+            vae_model_path = model_path
         partition = str(release.get("partition", "")).lower()
         expected_partition = "ref2va" if self.partition == "ref2va" else "fl2va"
         if partition != expected_partition:
@@ -876,11 +898,18 @@ def __init__(
         self.transformer = MiniMaxH3DiTModel(
             od_config,
             quant_config=transformer_quant_config,
+            diffusers_weights=modular,
         )
+        if self._fasth3_checkpoint is not None:
+            self.transformer.enable_vsa_gates(sparsity=self._fasth3_checkpoint.vsa_sparsity)
+            logger.info(
+                "FastH3 V2 full checkpoint: 8 transformer forwards, video/audio shifts 10/3, VSA sparsity=0.8 tile=64"
+            )
         if ref2va_model_path is not None:
             self.transformers_ref = MiniMaxH3DiTModel(
                 od_config,
                 quant_config=transformer_quant_config,
+                diffusers_weights=modular,
             )
 
         self._fasth3 = resolve_fasth3_fusion(od_config, self.transformer)
@@ -963,14 +992,14 @@ def __init__(
         # so VAEs stay resident for new configurations.
         component_load_device = torch.device("cpu") if legacy_manual_components else self.device
         self.video_vae = MiniMaxH3VideoVAE(
-            os.path.join(model_path, "video_vae"),
+            os.path.join(vae_model_path, "video_vae"),
             device=self.device,
             load_device=component_load_device,
             decode_only=not self.load_vae_encoder,
             trust_remote_code=od_config.trust_remote_code,
         )
         self.audio_vae = MiniMaxH3AudioVAE(
-            os.path.join(model_path, "audio_vae"),
+            os.path.join(vae_model_path, "audio_vae"),
             device=self.device,
             load_device=component_load_device,
             decode_only=not self.load_vae_encoder,
@@ -1046,6 +1075,12 @@ def source_prefix(item: tuple[str, torch.Tensor]) -> str:
             # load_weights only warns on a parameter the model does not have, so
             # close the adapter against what the DiT actually consumed.
             self._fasth3.validate_fully_applied(transformer_loaded)
+        if self._fasth3_checkpoint is not None:
+            required_gates = {
+                f"blocks.{i}.attn.to_gate_compress.weight" for i in range(self.transformer.arch.num_layers)
+            }
+            if missing_gates := required_gates - transformer_loaded:
+                raise ValueError(f"FastH3 V2 checkpoint is missing compression gates: {sorted(missing_gates)}")
         return loaded_with_prefix
 
     @property
@@ -2056,6 +2091,11 @@ def _prepare_encoder_conditioning_inputs(
             self._validate_turbo_sampling(sampling, turbo_spec)
         if has_native_lora:
             self._validate_native_sampling(sampling, task=task)
+        if self._fasth3_checkpoint is not None:
+            self._fasth3_checkpoint.check_request(
+                sampling,
+                step_execution=bool(getattr(self.od_config, "step_execution", False)),
+            )
         if self._fasth3 is not None:
             self._fasth3.check_request(
                 sampling,
diff --git a/vllm_omni/model_executor/models/minimax_h3/checkpoint.py b/vllm_omni/model_executor/models/minimax_h3/checkpoint.py
index 0143e9675b6..b39af5cf860 100644
--- a/vllm_omni/model_executor/models/minimax_h3/checkpoint.py
+++ b/vllm_omni/model_executor/models/minimax_h3/checkpoint.py
@@ -1,10 +1,16 @@
 # SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""MiniMax H3 checkpoint resolution for the AR text-encoder stage."""
+
 from pathlib import Path
 
+from vllm_omni.diffusion.utils.hf_utils import get_diffusion_model_index
 from vllm_omni.model_executor.model_loader.weight_utils import (
     download_weights_from_hf_specific,
 )
 
+_FASTH3_MODULAR_MODEL_PREFIX = "FastVideo/"
+
 MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS = {
     partition: [
         f"{subdir}/text_encoder/**",
@@ -16,6 +22,22 @@
 MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS["combined"] = MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS["fl2va"]
 
 
+def is_minimax_h3_modular(model: str, revision: str | None = None) -> bool:
+    path = Path(model)
+    if path.is_dir():
+        # Native MiniMax-H3 snapshots can advertise the Diffusers modular
+        # class in ``model_index.json`` while retaining the legacy FL2VA /
+        # Ref2VA layout.  FastH3 modular releases carry this marker file.
+        return (path / "modular_model_index.json").is_file() or (path / "fastvideo_inference.json").is_file()
+    # The FastVideo release is the modular checkpoint handled by this
+    # resolver.  Do not classify the native MiniMax-H3 Hub repository from
+    # its class name alone; its partition files are still required here.
+    if not model.startswith(_FASTH3_MODULAR_MODEL_PREFIX):
+        return False
+    index = get_diffusion_model_index(model, revision=revision) or {}
+    return index.get("_class_name") == "MiniMaxH3ModularPipeline"
+
+
 def resolve_minimax_h3_partition(
     model: str,
     task_type: str | None,
@@ -42,10 +64,13 @@ def resolve_minimax_h3_encoder_model_root(
 ) -> str:
     path = Path(model)
     partition = resolve_minimax_h3_partition(model, task_type, auto_partition="fl2va")
+    modular = is_minimax_h3_modular(model, revision)
 
     if path.is_dir():
         if path.name == "text_encoder" and (path / "config.json").is_file():
             return str(path)
+        if modular:
+            return str(path / "text_encoder")
         if path.name in {"FL2VA", "Ref2VA"}:
             path = path.parent
         subdir = "Ref2VA" if partition == "ref2va" else "FL2VA"
@@ -53,11 +78,13 @@ def resolve_minimax_h3_encoder_model_root(
     snapshot = download_weights_from_hf_specific(
         model_name_or_path=model,
         cache_dir=None,
-        allow_patterns=MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS[partition],
+        allow_patterns=["text_encoder/**"] if modular else MINIMAX_H3_ENCODER_DOWNLOAD_PATTERNS[partition],
         revision=revision,
         require_all=True,
     )
 
+    if modular:
+        return str(Path(snapshot) / "text_encoder")
     subdir = "Ref2VA" if partition == "ref2va" else "FL2VA"
     return str(Path(snapshot) / subdir / "text_encoder")
 

From 825ab20b07268050015516f9a65c733d7d089d28 Mon Sep 17 00:00:00 2001
From: MrDongsls <dhy1042542469@126.com>
Date: Thu, 17 Sep 2026 16:50:40 +0800
Subject: [PATCH 061/105] [Model][PersonaPlex] add per-row RingKV offsets and
 active rows (#7670)

Signed-off-by: Mr.Dong <1042542469@qq.com>
Co-authored-by: Mr.Dong <1042542469@qq.com>
---
 .../personaplex/test_ring_per_row_offsets.py  | 369 ++++++++++++++++++
 .../models/personaplex/personaplex_mimi.py    |  94 +++--
 .../personaplex/personaplex_temporal.py       |  76 ++--
 3 files changed, 483 insertions(+), 56 deletions(-)
 create mode 100644 tests/model_executor/models/personaplex/test_ring_per_row_offsets.py

diff --git a/tests/model_executor/models/personaplex/test_ring_per_row_offsets.py b/tests/model_executor/models/personaplex/test_ring_per_row_offsets.py
new file mode 100644
index 00000000000..fce42f40c50
--- /dev/null
+++ b/tests/model_executor/models/personaplex/test_ring_per_row_offsets.py
@@ -0,0 +1,369 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from types import SimpleNamespace
+
+import pytest
+import torch
+import torch.nn as nn
+from pytest_mock import MockerFixture
+
+from vllm_omni.model_executor.models.personaplex.personaplex_mimi import (
+    PersonaPlexMimiCodec,
+    _MimiStreamingTransformer,
+    _StreamConv1d,
+    _StreamConvTr1d,
+)
+from vllm_omni.model_executor.models.personaplex.personaplex_temporal import (
+    PersonaPlexTemporalStreaming,
+    _RingKV,
+)
+
+pytestmark = pytest.mark.core_model
+
+SEED = 1234
+CUDA_DEVICE = torch.device("cuda")
+
+
+def _mask(*rows: bool, device: torch.device | str = "cpu") -> torch.Tensor:
+    return torch.tensor(rows, dtype=torch.bool, device=device)
+
+
+def _inputs(shape: tuple[int, ...], seed: int, device: torch.device) -> torch.Tensor:
+    generator = torch.Generator(device="cpu").manual_seed(seed)
+    return torch.randn(*shape, generator=generator).to(device)
+
+
+def _make_mimi_transformer(
+    batch_size: int,
+    device: torch.device,
+    context: int = 6,
+) -> _MimiStreamingTransformer:
+    torch.manual_seed(SEED)
+    transformer = _MimiStreamingTransformer(
+        num_layers=2,
+        dim=32,
+        num_heads=4,
+        context=context,
+    ).to(device)
+    for parameter in transformer.parameters():
+        if parameter.dtype.is_floating_point:
+            nn.init.normal_(parameter, std=0.1)
+    transformer.streaming_init(batch_size)
+    return transformer
+
+
+def _make_temporal(
+    batch_size: int,
+    device: torch.device,
+    context: int = 6,
+) -> PersonaPlexTemporalStreaming:
+    torch.manual_seed(SEED)
+    temporal = PersonaPlexTemporalStreaming(
+        dim=16,
+        num_layers=2,
+        num_heads=4,
+        hidden=32,
+        context=context,
+        text_card=11,
+    ).to(device)
+    for parameter in temporal.parameters():
+        if parameter.dtype.is_floating_point:
+            nn.init.normal_(parameter, std=0.1)
+    temporal.streaming_init(batch_size)
+    return temporal
+
+
+def _assert_valid_ring_row_matches(
+    batched: _RingKV,
+    reference: _RingKV,
+    batched_positions: torch.Tensor,
+    reference_positions: torch.Tensor,
+    row: int,
+) -> None:
+    assert torch.equal(batched_positions[row], reference_positions)
+    assert torch.equal(batched.end_offset[row], reference.end_offset[0])
+
+    # The active mask covers the physical write as well as offset advancement,
+    # so the complete per-row ring state remains singleton-identical.
+    assert torch.equal(batched.cache[:, row], reference.cache[:, 0])
+
+
+def _stream_carry(stream: _StreamConv1d | _StreamConvTr1d) -> torch.Tensor:
+    if isinstance(stream, _StreamConv1d):
+        assert stream.prev is not None
+        return stream.prev
+    assert stream.partial is not None
+    return stream.partial
+
+
+def _make_passthrough_stage(mocker: MockerFixture):
+    stage = mocker.Mock(spec=["reset", "reset_slot"])
+    stage.side_effect = lambda x, active: x
+    return stage
+
+
+def _make_passthrough_transformer(mocker: MockerFixture):
+    transformer = mocker.Mock(spec=["streaming_init", "reset_streaming", "reset_slot", "step"])
+    transformer.step.side_effect = lambda x, active: x
+    return transformer
+
+
+def _active_args(call_args_list) -> torch.Tensor:
+    return torch.stack([call.args[1] for call in call_args_list])
+
+
+def _make_codec_stub(mocker: MockerFixture) -> PersonaPlexMimiCodec:
+    codec = PersonaPlexMimiCodec.__new__(PersonaPlexMimiCodec)
+    nn.Module.__init__(codec)
+
+    quantizer = mocker.Mock(spec=["encode", "decode"])
+    quantizer.encode.side_effect = lambda x: torch.zeros(8, x.shape[0], x.shape[-1], dtype=torch.long)
+    quantizer.decode.side_effect = lambda codes: torch.zeros(codes.shape[0], 1, codes.shape[-1])
+
+    codec.device = torch.device("cpu")
+    codec.dtype = torch.float32
+    codec.model = SimpleNamespace(quantizer=quantizer)
+    codec._enc_stages = []
+    codec._dec_stages = []
+    codec._downsample = _make_passthrough_stage(mocker)
+    codec._upsample = _make_passthrough_stage(mocker)
+    codec.encoder_transformer = _make_passthrough_transformer(mocker)
+    codec.decoder_transformer = _make_passthrough_transformer(mocker)
+    codec.streaming_init(batch_size=2)
+    return codec
+
+
+@pytest.mark.cpu
+def test_codec_entrypoints_forward_active_mask(mocker: MockerFixture) -> None:
+    codec = _make_codec_stub(mocker)
+    active = _mask(True, False)
+    all_active = torch.ones_like(active)
+
+    codec.encode_frame(torch.zeros(2, 1920), active)
+    codec.decode_frame(torch.zeros(2, 8), active)
+    codec.decode_frames(torch.zeros(2, 8, 3), active)
+    codec.decode_frames(torch.zeros(2, 8, 3), active=None)
+
+    assert torch.equal(_active_args(codec._downsample.call_args_list), active[None])
+    assert torch.equal(_active_args(codec._upsample.call_args_list), torch.stack((active, active, all_active)))
+    assert torch.equal(_active_args(codec.encoder_transformer.step.call_args_list), active[None])
+    assert torch.equal(
+        _active_args(codec.decoder_transformer.step.call_args_list),
+        torch.stack((active, active, all_active)),
+    )
+
+
+@pytest.mark.cpu
+def test_ring_mixed_offsets_match_singleton_streams() -> None:
+    batch_size, heads, head_dim, capacity, tokens = 3, 2, 3, 6, 2
+    batched = _RingKV(batch_size, heads, head_dim, capacity, torch.device("cpu"), torch.float32)
+    singletons = [_RingKV(1, heads, head_dim, capacity, torch.device("cpu"), torch.float32) for _ in range(batch_size)]
+    reference_positions: list[torch.Tensor | None] = [None] * batch_size
+    active_schedule = [
+        _mask(True, True, True),
+        _mask(True, False, False),
+        _mask(False, False, True),
+        _mask(True, True, False),
+        _mask(False, True, True),
+        _mask(True, False, True),
+        _mask(True, True, True),
+    ] * 2
+
+    torch.manual_seed(SEED)
+    for active in active_schedule:
+        keys = torch.randn(batch_size, heads, tokens, head_dim)
+        values = torch.randn_like(keys)
+        _, _, positions = batched.complete(keys, values, active)
+
+        for row, is_active in enumerate(active.tolist()):
+            if is_active:
+                _, _, singleton_positions = singletons[row].complete(
+                    keys[row : row + 1],
+                    values[row : row + 1],
+                    _mask(True),
+                )
+                reference_positions[row] = singleton_positions[0].clone()
+
+            assert reference_positions[row] is not None
+            _assert_valid_ring_row_matches(
+                batched,
+                singletons[row],
+                positions,
+                reference_positions[row],
+                row,
+            )
+
+    assert any(int(offset) > capacity for offset in batched.end_offset)
+    assert not torch.equal(batched.end_offset[0], batched.end_offset[1])
+
+
+@pytest.mark.cpu
+def test_ring_slot_recycle_masks_old_history() -> None:
+    ring = _RingKV(2, 1, 1, 8, torch.device("cpu"), torch.float32)
+    for _ in range(4):
+        ring.complete(torch.randn(2, 1, 2, 1), torch.randn(2, 1, 2, 1), _mask(True, True))
+
+    old_end = ring.end_offset.clone()
+    ring.reset_slot(1)
+    _, _, positions = ring.complete(
+        torch.randn(2, 1, 2, 1),
+        torch.randn(2, 1, 2, 1),
+        _mask(False, True),
+    )
+    visible = positions[1] >= 0
+    assert torch.all(positions[1][visible] >= old_end[1])
+
+    ring.reset_slot(0)
+    ring.bump_slot_start(0)
+    _, _, positions = ring.complete(
+        torch.randn(2, 1, 2, 1),
+        torch.randn(2, 1, 2, 1),
+        _mask(True, False),
+    )
+    visible = positions[0] >= 0
+    assert torch.all(positions[0][visible] >= old_end[0] + 1)
+
+
+@pytest.mark.cpu
+def test_temporal_streaming_rejects_invalid_active_shape() -> None:
+    temporal = _make_temporal(2, torch.device("cpu"))
+
+    with pytest.raises(ValueError, match=r"active must have shape \(2,\)"):
+        temporal.step(torch.zeros(2, 1, 16), torch.ones(1))
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+def test_mimi_transformer_mixed_offsets_match_singletons() -> None:
+    batch_size, tokens, dim = 3, 2, 32
+    batched = _make_mimi_transformer(batch_size, CUDA_DEVICE)
+    singletons = [_make_mimi_transformer(1, CUDA_DEVICE) for _ in range(batch_size)]
+    active_schedule = [
+        _mask(True, True, True, device=CUDA_DEVICE),
+        _mask(True, False, False, device=CUDA_DEVICE),
+        _mask(False, False, True, device=CUDA_DEVICE),
+        _mask(True, True, False, device=CUDA_DEVICE),
+        _mask(False, True, True, device=CUDA_DEVICE),
+        _mask(True, False, True, device=CUDA_DEVICE),
+        _mask(True, True, True, device=CUDA_DEVICE),
+    ] * 2
+
+    for step, active in enumerate(active_schedule):
+        inputs = _inputs((batch_size, tokens, dim), SEED + step, CUDA_DEVICE)
+        offsets_before = batched._offset.clone()
+        cache_before = [kv.cache.clone() for kv in batched._kv]
+        output = batched.step(inputs, active)
+
+        for row, is_active in enumerate(active.tolist()):
+            if is_active:
+                expected = singletons[row].step(
+                    inputs[row : row + 1],
+                    _mask(True, device=CUDA_DEVICE),
+                )
+                torch.testing.assert_close(output[row : row + 1], expected, rtol=0.0, atol=0.0)
+                assert torch.equal(batched._offset[row], singletons[row]._offset[0])
+                for batched_kv, singleton_kv in zip(batched._kv, singletons[row]._kv):
+                    assert torch.equal(batched_kv.end_offset[row], singleton_kv.end_offset[0])
+                    torch.testing.assert_close(batched_kv.cache[:, row], singleton_kv.cache[:, 0], rtol=0.0, atol=0.0)
+            else:
+                assert torch.equal(batched._offset[row], offsets_before[row])
+                for kv, previous_cache in zip(batched._kv, cache_before):
+                    assert torch.equal(kv.end_offset[row], offsets_before[row])
+                    assert torch.equal(kv.cache[:, row], previous_cache[:, row])
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+def test_temporal_streaming_mixed_offsets_match_isolated_rows() -> None:
+    # Keep the reference shape at B=2 so exact comparisons use the same CUDA
+    # kernel shape while the target row runs independently.
+    batched = _make_temporal(2, CUDA_DEVICE)
+    references = [_make_temporal(2, CUDA_DEVICE) for _ in range(2)]
+    active_schedule = [
+        _mask(True, True, device=CUDA_DEVICE),
+        _mask(True, False, device=CUDA_DEVICE),
+        _mask(False, False, device=CUDA_DEVICE),
+        _mask(False, True, device=CUDA_DEVICE),
+        _mask(True, True, device=CUDA_DEVICE),
+        _mask(True, False, device=CUDA_DEVICE),
+        _mask(False, True, device=CUDA_DEVICE),
+        _mask(True, True, device=CUDA_DEVICE),
+    ] * 2
+
+    for step, active in enumerate(active_schedule):
+        inputs = _inputs((2, 1, 16), SEED + 100 + step, CUDA_DEVICE)
+        offsets_before = batched._offset.clone()
+        cache_before = [kv.cache.clone() for kv in batched._kv]
+        output, logits = batched.step(inputs, active)
+
+        for row, (reference, is_active) in enumerate(zip(references, active.tolist())):
+            if is_active:
+                reference_inputs = torch.zeros_like(inputs)
+                reference_inputs[row] = inputs[row]
+                reference_active = torch.zeros_like(active)
+                reference_active[row] = True
+                expected_output, expected_logits = reference.step(reference_inputs, reference_active)
+                torch.testing.assert_close(output[row : row + 1], expected_output[row : row + 1], rtol=0.0, atol=0.0)
+                torch.testing.assert_close(logits[row : row + 1], expected_logits[row : row + 1], rtol=0.0, atol=0.0)
+                assert torch.equal(batched._offset[row], reference._offset[row])
+                for batched_kv, reference_kv in zip(batched._kv, reference._kv):
+                    assert torch.equal(batched_kv.end_offset[row], reference_kv.end_offset[row])
+                    torch.testing.assert_close(batched_kv.cache[:, row], reference_kv.cache[:, row], rtol=0.0, atol=0.0)
+            else:
+                assert torch.equal(batched._offset[row], offsets_before[row])
+                for kv, previous_cache in zip(batched._kv, cache_before):
+                    assert torch.equal(kv.end_offset[row], offsets_before[row])
+                    assert torch.equal(kv.cache[:, row], previous_cache[:, row])
+
+
+@pytest.mark.parametrize("kind", ["conv", "convtr"])
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+def test_mimi_conv_carries_preserve_inactive_rows(kind: str) -> None:
+    if kind == "conv":
+        conv = nn.Conv1d(1, 2, kernel_size=3, stride=2, device=CUDA_DEVICE)
+        batched = _StreamConv1d(conv, pad_mode="replicate")
+        row0 = _StreamConv1d(conv, pad_mode="replicate")
+        row1 = _StreamConv1d(conv, pad_mode="replicate")
+        samples = 4
+    else:
+        conv = nn.ConvTranspose1d(1, 2, kernel_size=4, stride=2, device=CUDA_DEVICE)
+        batched = _StreamConvTr1d(conv)
+        row0 = _StreamConvTr1d(conv)
+        row1 = _StreamConvTr1d(conv)
+        samples = 2
+
+    for stream, batch_size in ((batched, 2), (row0, 1), (row1, 1)):
+        stream.reset(batch_size, CUDA_DEVICE, torch.float32)
+
+    singletons = [row0, row1]
+    active_schedule = [
+        _mask(False, False, device=CUDA_DEVICE),
+        _mask(True, False, device=CUDA_DEVICE),
+        _mask(True, True, device=CUDA_DEVICE),
+        _mask(False, True, device=CUDA_DEVICE),
+        _mask(True, True, device=CUDA_DEVICE),
+    ]
+
+    for step, active in enumerate(active_schedule):
+        inputs = _inputs((2, 1, samples), SEED + 200 + step, CUDA_DEVICE)
+        carry_before = _stream_carry(batched).clone()
+        fresh_before = batched._fresh.clone()
+        output = PersonaPlexMimiCodec._run_stages(inputs, [(kind, batched)], active)
+
+        for row, is_active in enumerate(active.tolist()):
+            if is_active:
+                expected = PersonaPlexMimiCodec._run_stages(
+                    inputs[row : row + 1],
+                    [(kind, singletons[row])],
+                    _mask(True, device=CUDA_DEVICE),
+                )
+                torch.testing.assert_close(output[row : row + 1], expected, rtol=0.0, atol=0.0)
+                torch.testing.assert_close(
+                    _stream_carry(batched)[row], _stream_carry(singletons[row])[0], rtol=0.0, atol=0.0
+                )
+                assert torch.equal(batched._fresh[row], singletons[row]._fresh[0])
+            else:
+                assert torch.equal(_stream_carry(batched)[row], carry_before[row])
+                assert torch.equal(batched._fresh[row], fresh_before[row])
diff --git a/vllm_omni/model_executor/models/personaplex/personaplex_mimi.py b/vllm_omni/model_executor/models/personaplex/personaplex_mimi.py
index 3b8813faf70..35669438063 100644
--- a/vllm_omni/model_executor/models/personaplex/personaplex_mimi.py
+++ b/vllm_omni/model_executor/models/personaplex/personaplex_mimi.py
@@ -43,6 +43,19 @@
 CODEBOOKS = 8
 
 
+def _normalize_active(active: torch.Tensor | None, all_active: torch.Tensor) -> torch.Tensor:
+    # Stage 0 and Code2Wav currently use one B=1 codec per session and omit
+    # `active`, so preserve that API by treating None as all rows active. When
+    # they switch to shared B>1 codecs, their batch builders must pass bool[B]:
+    # True advances that row's streaming state; False keeps an absent or padded
+    # row's offsets and convolution carries unchanged.
+    if active is None:
+        return all_active
+    if active.shape != all_active.shape:
+        raise ValueError(f"active must have shape {tuple(all_active.shape)}, got {tuple(active.shape)}")
+    return active.to(device=all_active.device, dtype=torch.bool)
+
+
 def _map_moshi_codec_weights(
     state_dict: dict[str, torch.Tensor],
 ) -> dict[str, torch.Tensor]:
@@ -107,23 +120,24 @@ def __init__(self, conv: nn.Conv1d, pad_mode: str = "constant") -> None:
     def reset(self, batch_size: int, device, dtype) -> None:
         pad = self.kernel - self.stride
         self.prev = torch.zeros(batch_size, self.conv.in_channels, pad, device=device, dtype=dtype)
-        self._fresh = torch.ones(batch_size, dtype=torch.bool)
+        self._fresh = torch.ones(batch_size, dtype=torch.bool, device=device)
 
     def reset_slot(self, b: int) -> None:
         self.prev[b].zero_()
         self._fresh[b] = True
 
-    def __call__(self, x: torch.Tensor) -> torch.Tensor:
-        if self.pad_mode == "replicate" and bool(self._fresh.any()):
+    def __call__(self, x: torch.Tensor, active: torch.Tensor) -> torch.Tensor:
+        if self.pad_mode == "replicate":
             pad = self.prev.shape[-1]
             edge = x[..., 0:1].expand(-1, -1, pad)
-            fresh = self._fresh.to(x.device).view(-1, 1, 1)
+            fresh = (self._fresh & active).view(-1, 1, 1)
             self.prev = torch.where(fresh, edge.to(self.prev.dtype), self.prev)
-        self._fresh[:] = False
+        self._fresh[active] = False
         x = torch.cat([self.prev, x], dim=-1)
         t = x.shape[-1]
         num_frames = max(0, (t - self.kernel) // self.stride + 1)
-        self.prev = x[..., num_frames * self.stride :]
+        prev = x[..., num_frames * self.stride :]
+        self.prev = torch.where(active.view(-1, 1, 1), prev, self.prev)
         if num_frames == 0:
             return x.new_zeros(x.shape[0], self.conv.out_channels, 0)
         return self.conv(x[..., : (num_frames - 1) * self.stride + self.kernel])
@@ -137,18 +151,19 @@ def __init__(self, conv: nn.ConvTranspose1d) -> None:
         self.kernel = conv.kernel_size[0]
         self.stride = conv.stride[0]
         self.partial: torch.Tensor | None = None
+        self._fresh: torch.Tensor | None = None
 
     def reset(self, batch_size: int, device, dtype) -> None:
         self.partial = torch.zeros(
             batch_size, self.conv.out_channels, self.kernel - self.stride, device=device, dtype=dtype
         )
-        self._fresh = torch.ones(batch_size, dtype=torch.bool)
+        self._fresh = torch.ones(batch_size, dtype=torch.bool, device=device)
 
     def reset_slot(self, b: int) -> None:
         self.partial[b].zero_()
         self._fresh[b] = True
 
-    def __call__(self, x: torch.Tensor) -> torch.Tensor:
+    def __call__(self, x: torch.Tensor, active: torch.Tensor) -> torch.Tensor:
         out = self.conv(x)
         length = out.shape[-1]
         tail = self.kernel - self.stride
@@ -159,10 +174,11 @@ def __call__(self, x: torch.Tensor) -> torch.Tensor:
             # it again, so subtract one copy -- except on a row's very first
             # frame, where the carry is zeros by construction.
             merge = merge - self.conv.bias[:, None]
-            merge[self._fresh] = 0.0
-            self._fresh[:] = False
+            merge[self._fresh & active] = 0.0
+            self._fresh[active] = False
         out[..., :pt] += merge
-        self.partial = out[..., length - tail :].clone()
+        partial = out[..., length - tail :].clone()
+        self.partial = torch.where(active.view(-1, 1, 1), partial, self.partial)
         return out[..., : length - tail]
 
 
@@ -183,16 +199,23 @@ def __init__(self, dim: int = 512, num_heads: int = 8, ffn: int = 2048) -> None:
         self.scale1 = nn.Parameter(torch.empty(dim))
         self.scale2 = nn.Parameter(torch.empty(dim))
 
-    def forward(self, x: torch.Tensor, kv: _RingKV, offset: torch.Tensor, context: int) -> torch.Tensor:
+    def forward(
+        self,
+        x: torch.Tensor,
+        kv: _RingKV,
+        offset: torch.Tensor,
+        context: int,
+        active: torch.Tensor,
+    ) -> torch.Tensor:
         B, T, _ = x.shape
         h = self.norm1(x)
         qkv = F.linear(h, self.in_proj_weight)
         qkv = qkv.view(B, T, 3, self.num_heads, self.head_dim).permute(2, 0, 3, 1, 4)
         q, k, v = qkv[0], qkv[1], qkv[2]
         q, k = _apply_rope(q, k, offset)
-        keys, values, pos_k = kv.complete(k, v)
+        keys, values, pos_k = kv.complete(k, v, active=active)
         pos_k = pos_k.view(pos_k.shape[0], 1, pos_k.shape[1])
-        pos_q = offset + torch.arange(T, device=q.device, dtype=torch.long).view(1, -1, 1)
+        pos_q = offset.view(-1, 1, 1) + torch.arange(T, device=q.device, dtype=torch.long).view(1, -1, 1)
         delta = pos_q - pos_k
         attn_bias = (pos_k >= 0) & (delta >= 0) & (delta < context)
         attn = F.scaled_dot_product_attention(q, keys, values, attn_bias.unsqueeze(1), dropout_p=0.0)
@@ -218,7 +241,7 @@ def streaming_init(self, batch_size: int) -> None:
         heads = self.layers[0].num_heads
         hd = self.layers[0].head_dim
         self._kv = [_RingKV(batch_size, heads, hd, self.context, p.device, p.dtype) for _ in self.layers]
-        self._offset = torch.zeros(1, device=p.device, dtype=torch.long)
+        self._offset = torch.zeros(batch_size, device=p.device, dtype=torch.long)
 
     def reset_streaming(self) -> None:
         for kv in self._kv:
@@ -229,11 +252,11 @@ def reset_slot(self, b: int) -> None:
         for kv in self._kv:
             kv.reset_slot(b)
 
-    def step(self, x: torch.Tensor) -> torch.Tensor:
+    def step(self, x: torch.Tensor, active: torch.Tensor) -> torch.Tensor:
         """``x`` is ``[B, T, dim]`` (T = positions this frame, typically 2)."""
         for layer, kv in zip(self.layers, self._kv):
-            x = layer(x, kv, self._offset, self.context)
-        self._offset.add_(x.shape[1])
+            x = layer(x, kv, self._offset, self.context, active)
+        self._offset.add_(x.shape[1] * active.to(self._offset.dtype))
         return x
 
     def load_weights(self, state_dict: dict[str, torch.Tensor], prefix: str) -> int:
@@ -339,6 +362,7 @@ def __init__(self, hf_repo: str = DEFAULT_HF_REPO, checkpoint: str | None = None
         self._upsample = _StreamConvTr1d(m.upsample.conv)
         self._dec_stages = _walk_seanet(m.decoder.layers)
         self._batch_size: int | None = None
+        self._all_active: torch.Tensor
 
     # -- streaming state ------------------------------------------------------
 
@@ -354,6 +378,7 @@ def _conv_states(self):
 
     def streaming_init(self, batch_size: int) -> None:
         self._batch_size = batch_size
+        self._all_active = torch.ones(batch_size, dtype=torch.bool, device=self.device)
         for s in self._conv_states():
             s.reset(batch_size, self.device, self.dtype)
         self.encoder_transformer.streaming_init(batch_size)
@@ -376,39 +401,42 @@ def reset_slot(self, b: int) -> None:
     # -- per-frame codec -------------------------------------------------------
 
     @staticmethod
-    def _run_stages(x: torch.Tensor, stages) -> torch.Tensor:
+    def _run_stages(x: torch.Tensor, stages, active: torch.Tensor) -> torch.Tensor:
         for kind, stage in stages:
             if kind == "res":
                 act0, conv1, act2, conv3 = stage
-                x = x + conv3(act2(conv1(act0(x))))
+                x = x + conv3(act2(conv1(act0(x), active)), active)
             else:
-                x = stage(x)
+                x = stage(x, active) if kind in {"conv", "convtr"} else stage(x)
         return x
 
     @torch.no_grad()
-    def encode_frame(self, pcm: torch.Tensor) -> torch.Tensor:
+    def encode_frame(self, pcm: torch.Tensor, active: torch.Tensor | None = None) -> torch.Tensor:
         """``[B, frame_size]`` float PCM -> ``[B, 8]`` codes."""
         x = pcm.to(self.device, self.dtype).view(-1, 1, FRAME_SIZE)
-        x = self._run_stages(x, self._enc_stages)
-        x = self.encoder_transformer.step(x.transpose(1, 2)).transpose(1, 2)
-        x = self._downsample(x)
+        active = _normalize_active(active, self._all_active)
+        x = self._run_stages(x, self._enc_stages, active)
+        x = self.encoder_transformer.step(x.transpose(1, 2), active).transpose(1, 2)
+        x = self._downsample(x, active)
         codes = self.model.quantizer.encode(x)  # [Q, B, T]
         return codes[:CODEBOOKS, :, 0].transpose(0, 1).contiguous()
 
     @torch.no_grad()
-    def decode_frame(self, codes: torch.Tensor) -> torch.Tensor:
+    def decode_frame(self, codes: torch.Tensor, active: torch.Tensor | None = None) -> torch.Tensor:
         """``[B, 8]`` codes -> ``[B, frame_size]`` float PCM."""
         emb = self.model.quantizer.decode(codes.to(self.device).view(-1, CODEBOOKS, 1))
-        emb = self._upsample(emb)
-        emb = self.decoder_transformer.step(emb.transpose(1, 2)).transpose(1, 2)
-        x = self._run_stages(emb, self._dec_stages)
+        active = _normalize_active(active, self._all_active)
+        emb = self._upsample(emb, active)
+        emb = self.decoder_transformer.step(emb.transpose(1, 2), active).transpose(1, 2)
+        x = self._run_stages(emb, self._dec_stages, active)
         return x[:, 0, :]
 
     @torch.no_grad()
-    def decode_frames(self, codes: torch.Tensor) -> torch.Tensor:
+    def decode_frames(self, codes: torch.Tensor, active: torch.Tensor | None = None) -> torch.Tensor:
         """``[B, 8, F]`` codes -> ``[B, F * frame_size]`` float PCM."""
         emb = self.model.quantizer.decode(codes.to(self.device))
-        emb = self._upsample(emb)
-        emb = self.decoder_transformer.step(emb.transpose(1, 2)).transpose(1, 2)
-        x = self._run_stages(emb, self._dec_stages)
+        active = _normalize_active(active, self._all_active)
+        emb = self._upsample(emb, active)
+        emb = self.decoder_transformer.step(emb.transpose(1, 2), active).transpose(1, 2)
+        x = self._run_stages(emb, self._dec_stages, active)
         return x[:, 0, :]
diff --git a/vllm_omni/model_executor/models/personaplex/personaplex_temporal.py b/vllm_omni/model_executor/models/personaplex/personaplex_temporal.py
index 717e4d50575..28759dafb84 100644
--- a/vllm_omni/model_executor/models/personaplex/personaplex_temporal.py
+++ b/vllm_omni/model_executor/models/personaplex/personaplex_temporal.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Streaming Helium temporal transformer for PersonaPlex (moshi-free, plain torch).
 
 Frame-clocked duplex needs a stateful per-frame forward: one 80 ms step consumes
@@ -49,8 +49,8 @@ def _apply_rope(q: torch.Tensor, k: torch.Tensor, offset: torch.Tensor, max_peri
     B, H, T, D = q.shape
     ds = torch.arange(D // 2, device=q.device, dtype=torch.float32)
     freqs = torch.exp(ds * (-math.log(max_period) * 2 / D))
-    ts = offset.float() + torch.arange(T, device=q.device, dtype=torch.float32)
-    ts = ts.view(1, -1, 1)
+    ts = offset.float().view(-1, 1) + torch.arange(T, device=q.device, dtype=torch.float32)
+    ts = ts.view(-1, 1, T, 1)
 
     dims = q.shape[:-1]
     q = q.view(*dims, D // 2, 2)
@@ -80,7 +80,7 @@ class _RingKV:
     def __init__(self, batch_size: int, num_heads: int, dim_per_head: int, capacity: int, device, dtype):
         self.capacity = capacity
         self.cache = torch.zeros((2, batch_size, num_heads, capacity, dim_per_head), device=device, dtype=dtype)
-        self.end_offset = torch.zeros(1, device=device, dtype=torch.long)
+        self.end_offset = torch.zeros(batch_size, device=device, dtype=torch.long)
         self.start_offset = torch.zeros(batch_size, device=device, dtype=torch.long)
 
     def reset(self) -> None:
@@ -90,23 +90,36 @@ def reset(self) -> None:
     def reset_slot(self, b: int) -> None:
         # Mask everything written so far for row b; the row's next write is its
         # first visible entry. (LM sacrifice-tick +1 is applied by the caller.)
-        self.start_offset[b] = self.end_offset.clone()
+        self.start_offset[b] = self.end_offset[b]
 
     def bump_slot_start(self, b: int) -> None:
         self.start_offset[b] += 1
 
-    def complete(self, k: torch.Tensor, v: torch.Tensor):
+    def complete(self, k: torch.Tensor, v: torch.Tensor, active: torch.Tensor):
         B, H, T, D = k.shape
-        indexes = torch.arange(T, device=self.end_offset.device, dtype=self.end_offset.dtype) + self.end_offset
-        indexes = indexes % self.capacity
-        self.cache[0].index_copy_(2, indexes, k)
-        self.cache[1].index_copy_(2, indexes, v)
-        self.end_offset.add_(T)
+        indexes = (
+            torch.arange(T, device=self.end_offset.device, dtype=self.end_offset.dtype).view(1, -1)
+            + self.end_offset.view(-1, 1)
+        ) % self.capacity
+        idx4 = indexes.view(B, 1, T, 1).expand(-1, H, -1, D)
+        # Keep inactive rows completely inert. Once the ring is full, the
+        # physical future-write slot is also addressable by the position mask;
+        # writing it for an inactive row would therefore leak padded data into
+        # its next attention step.
+        active_view = active.view(B, 1, 1, 1)
+        old_k = self.cache[0].gather(2, idx4)
+        old_v = self.cache[1].gather(2, idx4)
+        k = torch.where(active_view, k, old_k)
+        v = torch.where(active_view, v, old_v)
+        self.cache[0].scatter_(2, idx4, k)
+        self.cache[1].scatter_(2, idx4, v)
+        self.end_offset.add_(T * active.to(self.end_offset.dtype))
 
         idx = torch.arange(self.capacity, device=self.end_offset.device, dtype=torch.long)
-        invalid = idx >= self.end_offset
-        end_index = self.end_offset % self.capacity
-        delta = idx - end_index
+        end_offset = self.end_offset.view(-1, 1)
+        invalid = idx.view(1, -1) >= end_offset
+        end_index = end_offset % self.capacity
+        delta = idx.view(1, -1) - end_index
         # `delta <= 0` (not `< 0`) is moshi's exact convention (transformer.py
         # RingKVCache.complete). It labels the just-past-newest slot as the future
         # write position, so once the ring has wrapped the single oldest in-window
@@ -114,14 +127,19 @@ def complete(self, k: torch.Tensor, v: torch.Tensor):
         # verbatim from the reference and only shows after the window fills (Helium
         # ~3000 frames / 240 s); it costs one frame out of thousands. Do NOT change
         # this to `< 0`: it would diverge from moshi and break greedy bit-parity.
-        positions = torch.where(delta <= 0, self.end_offset + delta, self.end_offset + delta - self.capacity)
+        positions = torch.where(delta <= 0, end_offset + delta, end_offset + delta - self.capacity)
         positions = torch.where(invalid, torch.full_like(positions, -1), positions)
-        positions = positions.view(1, -1)  # [1, capacity]
         below = positions < self.start_offset.view(-1, 1)  # [B, capacity]
         positions = torch.where(below, torch.full_like(positions, -1), positions)
         return self.cache[0], self.cache[1], positions
 
 
+def _normalize_temporal_active(active: torch.Tensor, reference: torch.Tensor) -> torch.Tensor:
+    if active.shape != reference.shape:
+        raise ValueError(f"active must have shape {tuple(reference.shape)}, got {tuple(active.shape)}")
+    return active.to(device=reference.device, dtype=torch.bool)
+
+
 class _TemporalLayer(nn.Module):
     """One Helium decoder layer in the checkpoint's fused layout."""
 
@@ -137,7 +155,14 @@ def __init__(self, dim: int, num_heads: int, hidden: int) -> None:
         self.norm1_alpha = nn.Parameter(torch.ones(1, 1, dim))
         self.norm2_alpha = nn.Parameter(torch.ones(1, 1, dim))
 
-    def forward(self, x: torch.Tensor, kv: _RingKV, offset: torch.Tensor, context: int) -> torch.Tensor:
+    def forward(
+        self,
+        x: torch.Tensor,
+        kv: _RingKV,
+        offset: torch.Tensor,
+        context: int,
+        active: torch.Tensor,
+    ) -> torch.Tensor:
         B, T, _ = x.shape
         h = _rms_norm_f32(x, self.norm1_alpha, 1e-8)
         qkv = F.linear(h, self.in_proj_weight)
@@ -147,9 +172,9 @@ def forward(self, x: torch.Tensor, kv: _RingKV, offset: torch.Tensor, context: i
         q, k, v = qkv[0], qkv[1], qkv[2]
         q, k = _apply_rope(q, k, offset)
 
-        keys, values, pos_k = kv.complete(k, v)
+        keys, values, pos_k = kv.complete(k, v, active)
         pos_k = pos_k.view(pos_k.shape[0], 1, pos_k.shape[1])  # [B, 1, cap]
-        pos_q = offset + torch.arange(T, device=q.device, dtype=torch.long).view(1, -1, 1)
+        pos_q = offset.view(-1, 1, 1) + torch.arange(T, device=q.device, dtype=torch.long).view(1, -1, 1)
         delta = pos_q - pos_k
         attn_bias = (pos_k >= 0) & (delta >= 0) & (delta < context)
         attn_bias = attn_bias.unsqueeze(1)  # [B, 1, T, cap]
@@ -199,7 +224,7 @@ def streaming_init(self, batch_size: int) -> None:
         head_dim = self.layers[0].head_dim
         # Capacity = context window (the mask truncates at `context` anyway).
         self._kv = [_RingKV(batch_size, heads, head_dim, self.context, p.device, p.dtype) for _ in self.layers]
-        self._offset = torch.zeros(1, device=p.device, dtype=torch.long)
+        self._offset = torch.zeros(batch_size, device=p.device, dtype=torch.long)
 
     def reset_streaming(self) -> None:
         assert self._kv is not None, "call streaming_init first"
@@ -221,12 +246,17 @@ def bump_slot_start(self, b: int) -> None:
     # -- per-frame step -------------------------------------------------------
 
     @torch.no_grad()
-    def step(self, frame_embedding: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+    def step(
+        self,
+        frame_embedding: torch.Tensor,
+        active: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
         assert self._kv is not None, "call streaming_init first"
+        active = _normalize_temporal_active(active, self._offset)
         x = frame_embedding
         for layer, kv in zip(self.layers, self._kv):
-            x = layer(x, kv, self._offset, self.context)
-        self._offset.add_(x.shape[1])
+            x = layer(x, kv, self._offset, self.context, active)
+        self._offset.add_(x.shape[1] * active.to(self._offset.dtype))
         out = _rms_norm_f32(x, self.out_norm_alpha, 1e-8)
         text_logits = F.linear(out, self.text_linear)
         return out, text_logits[:, None]

From e3be42e052e88d052d21cf7a24ee84c70f020fd6 Mon Sep 17 00:00:00 2001
From: psv666 <150513104+psv666@users.noreply.github.com>
Date: Thu, 17 Sep 2026 17:33:40 +0800
Subject: [PATCH 062/105] [Core] Give the OpenAI Realtime wire codec a reusable
 home (RFC #6592 P0a) (#7640)

Signed-off-by: psv666 <2693925048@qq.com>
---
 .../common/ci_source_file_dependencies.yml    |   2 +
 .github/CODEOWNERS                            |   5 +
 docs/design/fullduplex.md                     |  77 +-
 docs/design/module/entrypoints.md             |  43 +
 tests/protocol/__init__.py                    |   2 +
 tests/protocol/duplex/__init__.py             |   2 +
 .../duplex/test_duplex_protocol_facade.py     | 144 ++++
 tests/protocol/realtime/__init__.py           |   2 +
 .../realtime/test_protocol_import_boundary.py | 106 +++
 .../realtime/test_realtime_capabilities.py    |  91 +++
 .../test_realtime_codec_single_source.py      | 256 ++++++
 tools/pre_commit/check_forbidden_imports.py   |   7 +-
 vllm_omni/clients/inline_duplex.py            |   4 +-
 vllm_omni/engine/duplex/audio.py              | 250 +-----
 vllm_omni/engine/duplex/commands.py           | 232 +++---
 vllm_omni/engine/duplex/config.py             |  36 +-
 vllm_omni/engine/duplex/events.py             | 741 ++----------------
 vllm_omni/engine/duplex/realtime_commands.py  | 671 ++--------------
 vllm_omni/engine/duplex/realtime_events.py    |  12 +-
 vllm_omni/engine/duplex/session/runner.py     |   2 +-
 .../entrypoints/duplex/realtime_input.py      |  10 +-
 vllm_omni/entrypoints/duplex/serving.py       |   2 +-
 vllm_omni/protocol/__init__.py                |  17 +
 vllm_omni/protocol/duplex/__init__.py         | 159 ++++
 vllm_omni/protocol/duplex/commands.py         | 164 ++++
 vllm_omni/protocol/duplex/errors.py           |  75 ++
 vllm_omni/protocol/duplex/events.py           | 419 ++++++++++
 vllm_omni/protocol/realtime/__init__.py       | 163 ++++
 vllm_omni/protocol/realtime/audio.py          | 218 ++++++
 vllm_omni/protocol/realtime/audio_input.py    | 243 ++++++
 vllm_omni/protocol/realtime/capabilities.py   | 105 +++
 vllm_omni/protocol/realtime/commands.py       | 126 +++
 vllm_omni/protocol/realtime/errors.py         |  37 +
 vllm_omni/protocol/realtime/events.py         | 467 +++++++++++
 vllm_omni/protocol/realtime/formats.py        | 177 +++++
 vllm_omni/protocol/realtime/items.py          | 197 +++++
 vllm_omni/protocol/realtime/session.py        | 163 ++++
 37 files changed, 3795 insertions(+), 1632 deletions(-)
 create mode 100644 tests/protocol/__init__.py
 create mode 100644 tests/protocol/duplex/__init__.py
 create mode 100644 tests/protocol/duplex/test_duplex_protocol_facade.py
 create mode 100644 tests/protocol/realtime/__init__.py
 create mode 100644 tests/protocol/realtime/test_protocol_import_boundary.py
 create mode 100644 tests/protocol/realtime/test_realtime_capabilities.py
 create mode 100644 tests/protocol/realtime/test_realtime_codec_single_source.py
 create mode 100644 vllm_omni/protocol/__init__.py
 create mode 100644 vllm_omni/protocol/duplex/__init__.py
 create mode 100644 vllm_omni/protocol/duplex/commands.py
 create mode 100644 vllm_omni/protocol/duplex/errors.py
 create mode 100644 vllm_omni/protocol/duplex/events.py
 create mode 100644 vllm_omni/protocol/realtime/__init__.py
 create mode 100644 vllm_omni/protocol/realtime/audio.py
 create mode 100644 vllm_omni/protocol/realtime/audio_input.py
 create mode 100644 vllm_omni/protocol/realtime/capabilities.py
 create mode 100644 vllm_omni/protocol/realtime/commands.py
 create mode 100644 vllm_omni/protocol/realtime/errors.py
 create mode 100644 vllm_omni/protocol/realtime/events.py
 create mode 100644 vllm_omni/protocol/realtime/formats.py
 create mode 100644 vllm_omni/protocol/realtime/items.py
 create mode 100644 vllm_omni/protocol/realtime/session.py

diff --git a/.buildkite/common/ci_source_file_dependencies.yml b/.buildkite/common/ci_source_file_dependencies.yml
index e29001d9a46..c101db48d25 100644
--- a/.buildkite/common/ci_source_file_dependencies.yml
+++ b/.buildkite/common/ci_source_file_dependencies.yml
@@ -44,6 +44,7 @@ x-minicpmo-4-5-duplex: &minicpmo_4_5_duplex
   - vllm_omni/entrypoints/duplex/
   - vllm_omni/entrypoints/duplex_omni.py
   - vllm_omni/entrypoints/async_omni_base.py
+  - vllm_omni/protocol/
   - vllm_omni/clients/
   - vllm_omni/outputs/duplex.py
   - vllm_omni/model_executor/duplex_sampling.py
@@ -259,6 +260,7 @@ source_file_dependencies:
     - tests/entrypoints/test_duplex_omni.py
     - tests/entrypoints/openai_api/test_duplex_api_server.py
     - tests/model_executor/models/minicpmo_4_5/duplex/
+    - tests/protocol/
 
   omni_minicpmo_4_5_duplex_perf:
     - *minicpmo_4_5
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index c92c7b22f8c..e77f7091448 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -67,6 +67,11 @@
 # File-level overrides within entrypoints/
 /vllm_omni/entrypoints/openai/errors.py @alex-jw-brooks @NickCao
 /vllm_omni/entrypoints/cli/benchmark/ @alex-jw-brooks @Bounty-hunter
+# Shared wire codec: protocol/realtime (OpenAI Realtime GA) and protocol/duplex
+# (vLLM-Omni's extension of it) — RFC #6592 P0a. Layer-neutral by design — the
+# engine depends on it — so it is owned by the serving-boundary document rather
+# than by any one consumer. — docs/design/module/entrypoints.md
+/vllm_omni/protocol/ @alex-jw-brooks @linyueqian @NickCao
 
 # Error contracts — docs/design/module/error_contracts.md
 /vllm_omni/errors.py @alex-jw-brooks @NickCao
diff --git a/docs/design/fullduplex.md b/docs/design/fullduplex.md
index 41a050a47e6..324cd5bdcad 100644
--- a/docs/design/fullduplex.md
+++ b/docs/design/fullduplex.md
@@ -9,6 +9,12 @@ the owner document for `vllm_omni/engine/duplex/**`,
 `vllm_omni/entrypoints/duplex_omni.py`, `vllm_omni/entrypoints/duplex/**`,
 `vllm_omni/clients/**` and the per-model `duplex/` packages.
 
+`vllm_omni/protocol/realtime/**` (the OpenAI Realtime API) and
+`vllm_omni/protocol/duplex/**` (vLLM-Omni's extension of it) are the shared
+wire codec duplex is built on. Duplex is its first consumer but not its owner: the codec
+is deliberately runtime-agnostic so a second Realtime surface can reuse it
+(RFC #6592 P0a).
+
 The public wire contract lives in
 [`docs/serving/realtime_duplex_api.md`](../serving/realtime_duplex_api.md);
 this page describes how it is produced.
@@ -124,6 +130,40 @@ plugin and the session runtime config to `DuplexOrchestrator` directly.
    attachment/resume/replay bookkeeping; it holds no session state.
 6. **No `typing.Protocol`** in the duplex surfaces: the plugin, data plane,
    session state, PCM buffer, stage port and client transport seams are ABCs.
+7. **The wire codec is not duplex, and a wire type is not a mailbox message.**
+   The event and command *vocabulary* plus its wire rendering, the audio format
+   negotiation, the conversation-item rules and the error envelope are model-
+   and runtime-agnostic, and split along the three tiers
+   [`docs/serving/realtime_duplex_api.md`](../serving/realtime_duplex_api.md)
+   already defines: **Tier 1** (identical to OpenAI) is
+   `vllm_omni/protocol/realtime/**`; **Tier 2** (OpenAI names carrying our
+   extensions) and **Tier 3** (ours alone) are `vllm_omni/protocol/duplex/**`.
+   A Tier 2 class *subclasses* its Tier 1 twin and declares only what it adds,
+   so the OpenAI surface stays honestly pure --- `session.created` without
+   `resume_token`, `input_audio_buffer.append` without `video_frames`. Our
+   error **codes** are Tier 3 (`protocol/duplex/errors.py`); only the envelope
+   shape and OpenAI's three `error.type` classes are Tier 1.
+   What stays engine-side is everything that is *internal representation*
+   rather than contract: `DuplexCommand.payload()` renders the session runner's
+   mailbox dictionary, whose channel genuinely differs from the client event
+   (`session.update` and the three `conversation.item.*` commands all travel on
+   `turn.signal`); `engine/duplex/realtime_commands.py` decides which command a
+   decoded event becomes; `engine/duplex/realtime_events.py` holds the
+   session's projection state. The codec may not import the engine, the
+   entrypoints, `model_executor` or the clients
+   (`tests/protocol/realtime/test_protocol_import_boundary.py`), and there is
+   exactly one implementation of each codec behaviour
+   (`tests/protocol/realtime/test_realtime_codec_single_source.py`).
+   The dependency chain is `protocol/realtime` <- `protocol/duplex` <- engine /
+   entrypoints / clients, and a duplex consumer uses **only** the middle link:
+   `protocol/duplex/**` re-exports the Tier 1 names it does not extend, so a
+   helper that later needs a duplex-specific version (`convert_input_audio_with_rate`
+   resamples to MiniCPM-o's 16 kHz rather than the client's rate) is overridden
+   in one file instead of at every call site
+   (`tests/protocol/duplex/test_duplex_protocol_facade.py`).
+   `DuplexEvent` is therefore a plain alias of `RealtimeEvent` --- an event has
+   no engine-internal half --- while `DuplexCommand` is a real class, because a
+   command does.
 
 ## Package layout
 
@@ -142,6 +182,31 @@ vllm_omni/
 │   │   ├── chat_completions.py      DuplexChatCompletionsAdapter (/v1/chat/completions on a session per request)
 │   │   └── websocket.py             websocket send/close/receive helpers
 │   └── openai/api_server.py         builds DuplexOmni for duplex models; session-backed app state
+├── protocol/                        SHARED WIRE CODEC (no engine / no model / no transport)
+│   ├── realtime/                    the OpenAI Realtime API itself
+│   │   ├── events.py                RealtimeEvent + OpenAI's 30 server events (22 ship as Tier 1;
+│   │   │                            8 have a Tier 2 twin in protocol/duplex)
+│   │   ├── commands.py              RealtimeCommand + OpenAI's 10 client commands (8 Tier 1,
+│   │   │                            2 with a Tier 2 twin) --- wire_type + fields, no payload()
+│   │   ├── formats.py               audio format spellings, what is supported, per-session validation
+│   │   ├── session.py               session-object readers; RealtimeInputDefaults (append defaults)
+│   │   ├── items.py                 conversation item shape, truncation, transcripts, camera frames
+│   │   ├── audio_input.py           decode_audio_append -> RealtimeAudioAppend; client speech hints
+│   │   ├── audio.py                 PCM / G.711 / WAV decode, resample, re-encode
+│   │   ├── errors.py                RealtimeProtocolError (the envelope's exception type)
+│   │   └── capabilities.py          RealtimeProtocolCapabilities: what one consumer can serve
+│   └── duplex/                      Tier 2 + Tier 3, and the one door a duplex consumer uses
+│       ├── __init__.py              re-exports the Tier 1 helper functions (audio, formats,
+│       │                            items, session, capabilities) so the engine never
+│       │                            imports protocol/realtime directly
+│       ├── events.py                the whole 42-event vocabulary: 22 Tier-1 re-exports,
+│       │                            8 Tier-2 subclasses (session.created + resume_token, ...),
+│       │                            12 Tier-3 events (listen/speak, playback, resume, ...);
+│       │                            DuplexEvent = RealtimeEvent
+│       ├── commands.py              the whole 17-command vocabulary: 8 Tier-1 re-exports,
+│       │                            2 Tier-2 subclasses (append + hints, commit + final),
+│       │                            7 Tier-3 commands (barge_in, playback.ack, ...)
+│       └── errors.py                our error-code vocabulary (Tier 3) + RealtimeProtocolError
 ├── engine/
 │   ├── omni_engine_base.py          OmniEngineBase (stage processes, orchestrator thread, queues, RPC)
 │   ├── async_omni_engine.py         AsyncOmniEngine (turn-based request building)
@@ -149,16 +214,20 @@ vllm_omni/
 │   ├── orchestrator.py              OrchestratorBase + Orchestrator
 │   ├── duplex_orchestrator.py       DuplexOrchestrator (+ DuplexOrchestratorRequestState; implements DuplexStagePort)
 │   └── duplex/
-│       ├── commands.py              DuplexCommand dataclasses, command_from_realtime
-│       ├── realtime_commands.py     Realtime client event -> DuplexCommand translation
-│       ├── events.py                DuplexEvent dataclasses (+ to_realtime), REALTIME_ERROR_TYPES_BY_CODE
+│       ├── commands.py              mailbox half: DuplexCommand.payload() + the mailbox `type`,
+│       │                            paired with each protocol command; command_from_realtime
+│       ├── realtime_commands.py     duplex binding of the codec: decoded event -> DuplexCommand,
+│       │                            DUPLEX_REALTIME_CAPABILITIES, duplex_response_format
+│       ├── events.py                re-export shim (DuplexEvent = RealtimeEvent) + the runner's
+│       │                            epoch-filter sets DOMAIN_TERMINAL_EVENTS / MODEL_OUTPUT_EVENTS
 │       ├── realtime_events.py       RealtimeProjectionState: internal event -> typed events
 │       ├── messages.py              queue envelopes (Open/Close/Resume/Touch/Command/Result/Event), DuplexSessionError
 │       ├── config.py                DuplexSessionConfig, DuplexCapabilities, ResponseCreateOptions
 │       ├── contracts.py             DuplexFence (session_id, epoch, turn_id), stage request records, DuplexStagePort
 │       ├── plugin.py                DuplexModelPlugin, DuplexModelSessionState, DuplexDataPlane, PcmAppendBuffer ABCs
 │       ├── turn_detection.py        server-side VAD turn detector used by the session
-│       ├── audio.py / vad.py / intermediate.py
+│       ├── audio.py                 compatibility re-export, via protocol/duplex
+│       ├── vad.py / intermediate.py
 │       └── session/                 one engine-resident session and everything that runs it
 │           ├── engine_session.py    DuplexEngineSession: ledgers, lease, fence, stage resources, append sequencing
 │           ├── runner.py            DuplexSessionRunner (per-session mailbox on the orchestrator loop)
diff --git a/docs/design/module/entrypoints.md b/docs/design/module/entrypoints.md
index f37ddc6baac..0c0ba8439a3 100644
--- a/docs/design/module/entrypoints.md
+++ b/docs/design/module/entrypoints.md
@@ -30,6 +30,7 @@ primary_code_paths:
   - vllm_omni/entrypoints/utils.py
   - vllm_omni/entrypoints/duplex/**
   - vllm_omni/clients/**
+  - vllm_omni/protocol/**
 primary_path_exceptions:
   - path: vllm_omni/entrypoints/openai/errors.py
     owner: error_contracts.md
@@ -53,6 +54,7 @@ depends_on:
   - error_contracts.md
   - engine_orchestration.md
 validation_paths:
+  - tests/protocol/**
   - tests/entrypoints/test_omni_entrypoints.py
   - tests/entrypoints/test_async_omni.py
   - tests/entrypoints/test_async_omni_pause_sleep_routing.py
@@ -106,6 +108,31 @@ placement, payload implementation, or semantic error classification.
 `entrypoints/openai/errors.py` is an explicit primary-path exception owned by
 `error_contracts.md`.
 
+It also owns `vllm_omni/protocol/**`, the shared wire codec promoted by RFC
+[#6592](https://github.com/vllm-project/vllm-omni/issues/6592) P0a. It follows the three tiers
+`docs/serving/realtime_duplex_api.md` already defines. `protocol/realtime/**`
+is Tier 1, identical to OpenAI: 30 server events, 10 client commands, their
+typed fields and pure wire rendering, audio-format negotiation,
+conversation-item rules and the error-envelope shape. `protocol/duplex/**` is
+Tier 2 (OpenAI names carrying vLLM-Omni extensions, each a subclass of its
+Tier 1 twin declaring only what it adds) and Tier 3 (ours alone, including our
+error-code vocabulary), kept separate so a GA-only consumer is not handed a
+vocabulary its clients never send. That package sits
+outside `entrypoints/` on purpose --- the engine depends on it, so it belongs
+to neither layer --- but deciding what a Realtime client may put on the wire is
+this document's subject, and the same reasoning already places
+`vllm_omni/errors.py`, `inputs/` and `outputs/` under contract documents rather
+than under a consumer.
+
+It is deliberately **not** owned by `../fullduplex.md`, even though duplex is
+the codec's only consumer today. RFC #6592 asks for a named owner precisely so
+a second Realtime consumer does not need duplex review to change the codec
+(#6592 open question 8). Ownership here is review scope, not a dependency: the
+codec may not import the engine, the entrypoints or the model code, which
+`tests/protocol/realtime/test_protocol_import_boundary.py` enforces. When a
+second consumer lands (#6592 P0b) the package is expected to graduate to its
+own module document with owners drawn from both consumers.
+
 ## Candidate invariants
 
 These identifiers are proposals while the document is `draft`.
@@ -115,6 +142,22 @@ These identifiers are proposals while the document is `draft`.
 **Rule:** Entrypoints MUST NOT implement cross-stage routing or stage lifecycle
 policy.
 
+### ENTRY-INV-002: The shared Realtime codec does not depend on its consumers
+
+**Rule:** `vllm_omni/protocol/**` MUST NOT import `vllm_omni.engine`,
+`vllm_omni.entrypoints`, `vllm_omni.model_executor`, `vllm_omni.worker` or
+`vllm_omni.clients`; `protocol/duplex/**` MAY depend on `protocol/realtime/**`
+but never the reverse, and a Tier 1 class MUST NOT carry a vLLM-Omni extension
+field; and each protocol/codec behavior MUST have exactly one
+implementation that every consumer uses. A wire type MUST NOT carry a
+consumer's internal representation: the duplex mailbox rendering
+(`DuplexCommand.payload()`, whose channel differs from the client event for
+`session.update` and the `conversation.item.*` commands) stays engine-side.
+A duplex consumer (`engine/duplex/**`, `entrypoints/duplex/**`, the duplex
+clients) MUST import `vllm_omni.protocol.duplex` and MUST NOT import
+`vllm_omni.protocol.realtime` directly, so the tier boundary has exactly one
+extension point.
+
 ### ENTRY-INV-100: Public requests are normalized once
 
 **Rule:** Public protocol values MUST be validated and converted to internal
diff --git a/tests/protocol/__init__.py b/tests/protocol/__init__.py
new file mode 100644
index 00000000000..4244ce4b4e1
--- /dev/null
+++ b/tests/protocol/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
diff --git a/tests/protocol/duplex/__init__.py b/tests/protocol/duplex/__init__.py
new file mode 100644
index 00000000000..4244ce4b4e1
--- /dev/null
+++ b/tests/protocol/duplex/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
diff --git a/tests/protocol/duplex/test_duplex_protocol_facade.py b/tests/protocol/duplex/test_duplex_protocol_facade.py
new file mode 100644
index 00000000000..61dd15fe147
--- /dev/null
+++ b/tests/protocol/duplex/test_duplex_protocol_facade.py
@@ -0,0 +1,144 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""``protocol.duplex`` is the only door a duplex consumer uses.
+
+The layering is a chain::
+
+    protocol.realtime  <-  protocol.duplex  <-  engine / entrypoints / clients
+
+The middle link only earns its keep if the last arrow is the *only* one. If the
+engine may also reach past it straight into ``protocol.realtime``, then giving a
+Tier 1 helper a duplex-specific version later means touching every call site
+instead of one file --- which is exactly the change
+``convert_input_audio_with_rate`` is expected to need (it resamples to
+MiniCPM-o's 16 kHz, not the client's rate).
+
+So this asserts two things: nobody skips the middle link, and the middle link is
+complete enough that nobody has to.
+"""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+import pytest
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+
+#: Every module that speaks the duplex protocol. These import
+#: ``vllm_omni.protocol.duplex``; reaching into ``vllm_omni.protocol.realtime``
+#: from here skips the extension point.
+CONSUMER_PATHS = (
+    "vllm_omni/engine/duplex",
+    "vllm_omni/engine/duplex_omni_engine.py",
+    "vllm_omni/entrypoints/duplex",
+    "vllm_omni/entrypoints/duplex_omni.py",
+    "vllm_omni/clients/duplex.py",
+    "vllm_omni/clients/inline_duplex.py",
+)
+
+
+def _consumer_modules() -> list[Path]:
+    found: list[Path] = []
+    for entry in CONSUMER_PATHS:
+        path = REPO_ROOT / entry
+        found.extend(sorted(path.rglob("*.py")) if path.is_dir() else [path])
+    assert found, "consumer list is stale"
+    return found
+
+
+@pytest.mark.parametrize("module", _consumer_modules(), ids=lambda p: p.name)
+def test_a_duplex_consumer_does_not_skip_the_duplex_protocol_package(module: Path) -> None:
+    # Source-level, so a lazy import inside a function body is caught too.
+    tree = ast.parse(module.read_text())
+    offenders = []
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom) and (node.module or "").startswith("vllm_omni.protocol.realtime"):
+            offenders.append(f"line {node.lineno}: from {node.module} import ...")
+        elif isinstance(node, ast.Import):
+            offenders.extend(
+                f"line {node.lineno}: import {alias.name}"
+                for alias in node.names
+                if alias.name.startswith("vllm_omni.protocol.realtime")
+            )
+    assert not offenders, (
+        f"{module.relative_to(REPO_ROOT)} imports the Tier 1 package directly; "
+        f"import from vllm_omni.protocol.duplex instead:\n  " + "\n  ".join(offenders)
+    )
+
+
+def test_the_duplex_package_carries_the_whole_command_vocabulary() -> None:
+    from vllm_omni.engine.duplex import commands as engine_commands
+    from vllm_omni.protocol.duplex import commands as duplex_wire
+
+    # Every command the engine handles is nameable through the one door.
+    engine_names = {
+        name
+        for name in engine_commands.__all__
+        if isinstance(getattr(engine_commands, name), type)
+        and issubclass(getattr(engine_commands, name), engine_commands.DuplexCommand)
+        and getattr(engine_commands, name) is not engine_commands.DuplexCommand
+    }
+    assert engine_names <= set(duplex_wire.__all__)
+
+
+def test_the_duplex_package_carries_the_whole_event_vocabulary() -> None:
+    from vllm_omni.engine.duplex import events as engine_events
+    from vllm_omni.protocol.duplex import events as duplex_wire
+
+    engine_names = {
+        name
+        for name in engine_events.__all__
+        if isinstance(getattr(engine_events, name), type)
+        and issubclass(getattr(engine_events, name), engine_events.DuplexEvent)
+    }
+    assert engine_names <= set(duplex_wire.__all__)
+
+
+@pytest.mark.parametrize(
+    "module_pair",
+    [("events", "events"), ("commands", "commands")],
+    ids=["events", "commands"],
+)
+def test_a_reexported_tier1_name_is_the_tier1_object(module_pair: tuple[str, str]) -> None:
+    """Re-export, not re-declaration: the Tier 1 class is one object."""
+    import importlib
+
+    duplex_mod = importlib.import_module(f"vllm_omni.protocol.duplex.{module_pair[0]}")
+    realtime_mod = importlib.import_module(f"vllm_omni.protocol.realtime.{module_pair[1]}")
+
+    shared = [n for n in duplex_mod.__all__ if hasattr(realtime_mod, n)]
+    assert shared, "nothing re-exported --- the facade is not doing its job"
+    for name in shared:
+        duplex_obj = getattr(duplex_mod, name)
+        realtime_obj = getattr(realtime_mod, name)
+        if duplex_obj is realtime_obj:
+            continue
+        # The only permitted divergence is a Tier 2 class extending its twin.
+        assert isinstance(duplex_obj, type) and issubclass(duplex_obj, realtime_obj), (
+            f"{name} in protocol.duplex is neither the Tier 1 object nor a subclass of it"
+        )
+
+
+def test_duplex_event_is_an_alias_but_duplex_command_is_not() -> None:
+    """The asymmetry is deliberate, and a later reader should not 'fix' it.
+
+    An event has no engine-internal half --- what the session emits is what the
+    socket sends --- so ``DuplexEvent`` is simply ``RealtimeEvent``. A command
+    does: ``payload()`` renders the session runner's mailbox dictionary, and for
+    four of the seventeen the mailbox channel is not even the client event type.
+    """
+    from vllm_omni.engine.duplex.commands import DuplexCommand
+    from vllm_omni.protocol.duplex.events import DuplexEvent
+    from vllm_omni.protocol.realtime.commands import RealtimeCommand
+    from vllm_omni.protocol.realtime.events import RealtimeEvent
+
+    assert DuplexEvent is RealtimeEvent
+
+    assert DuplexCommand is not RealtimeCommand
+    assert issubclass(DuplexCommand, RealtimeCommand)
+    assert hasattr(DuplexCommand, "payload") and not hasattr(RealtimeCommand, "payload")
diff --git a/tests/protocol/realtime/__init__.py b/tests/protocol/realtime/__init__.py
new file mode 100644
index 00000000000..4244ce4b4e1
--- /dev/null
+++ b/tests/protocol/realtime/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
diff --git a/tests/protocol/realtime/test_protocol_import_boundary.py b/tests/protocol/realtime/test_protocol_import_boundary.py
new file mode 100644
index 00000000000..a00d4da6244
--- /dev/null
+++ b/tests/protocol/realtime/test_protocol_import_boundary.py
@@ -0,0 +1,106 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The shared Realtime codec must not depend on any runtime that uses it.
+
+``vllm_omni.protocol.realtime`` exists so a second Realtime surface can reuse
+the wire codec without adopting the duplex session control plane. That only
+holds while the arrows point one way: the engine, the entrypoints and the model
+code import the protocol, never the reverse. Nothing in the package's own code
+enforces that, so it is asserted here --- once on the source (which catches a
+lazy import inside a function body) and once on a real import (which catches a
+dependency arriving through a third module).
+"""
+
+from __future__ import annotations
+
+import ast
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+PROTOCOL_DIR = REPO_ROOT / "vllm_omni" / "protocol"
+
+#: Packages that consume the protocol. A dependency on any of them would make
+#: the codec unusable outside the runtime it accidentally reached into.
+#: ``vllm_omni.utils`` is deliberately absent: it is leaf helpers (the audio
+#: resampler) that consume nothing, so depending on it costs a reuser nothing.
+FORBIDDEN_PREFIXES = (
+    "vllm_omni.engine",
+    "vllm_omni.entrypoints",
+    "vllm_omni.model_executor",
+    "vllm_omni.worker",
+    "vllm_omni.clients",
+)
+
+
+def _protocol_sources() -> list[Path]:
+    sources = sorted(PROTOCOL_DIR.rglob("*.py"))
+    assert sources, f"no python sources under {PROTOCOL_DIR}"
+    return sources
+
+
+def _imported_modules(source: Path) -> set[str]:
+    """Every module name imported anywhere in the file, lazy imports included."""
+    names: set[str] = set()
+    for node in ast.walk(ast.parse(source.read_text())):
+        if isinstance(node, ast.Import):
+            names.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            names.add(node.module)
+    return names
+
+
+@pytest.mark.parametrize("source", _protocol_sources(), ids=lambda path: path.name)
+def test_protocol_sources_do_not_import_a_consumer(source: Path) -> None:
+    offenders = sorted(
+        name
+        for name in _imported_modules(source)
+        if any(name == prefix or name.startswith(prefix + ".") for prefix in FORBIDDEN_PREFIXES)
+    )
+    assert not offenders, f"{source.relative_to(REPO_ROOT)} imports {', '.join(offenders)}"
+
+
+def test_importing_the_protocol_package_loads_no_consumer() -> None:
+    # A child interpreter, because this test session has already imported the
+    # duplex engine: only a fresh process can tell what the package pulls in.
+    # ``vllm_omni`` itself is imported first, because its ``__init__`` loads a
+    # baseline graph (patches, the model registry) that has nothing to do with
+    # this package; only what the protocol import *adds* is measured.
+    env = os.environ.copy()
+    env.pop("CUDA_VISIBLE_DEVICES", None)
+    env.pop("HIP_VISIBLE_DEVICES", None)
+    script = f"""
+import sys
+
+import vllm_omni  # noqa: F401
+
+baseline = set(sys.modules)
+
+import vllm_omni.protocol.realtime  # noqa: F401
+
+forbidden_prefixes = {FORBIDDEN_PREFIXES!r}
+added = sorted(
+    name
+    for name in set(sys.modules) - baseline
+    if any(name == prefix or name.startswith(prefix + ".") for prefix in forbidden_prefixes)
+)
+if added:
+    raise SystemExit("the realtime protocol package loaded consumers: " + ", ".join(added))
+"""
+    result = subprocess.run(
+        [sys.executable, "-c", script],
+        cwd=REPO_ROOT,
+        env=env,
+        capture_output=True,
+        text=True,
+        timeout=180,
+        check=False,
+    )
+    assert result.returncode == 0, result.stderr
diff --git a/tests/protocol/realtime/test_realtime_capabilities.py b/tests/protocol/realtime/test_realtime_capabilities.py
new file mode 100644
index 00000000000..2a05fc0a910
--- /dev/null
+++ b/tests/protocol/realtime/test_realtime_capabilities.py
@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""``RealtimeProtocolCapabilities``: one consumer's answers, the codec's checking.
+
+This is the seam that lets a non-duplex Realtime surface validate a
+``session.update`` without a ``DuplexModelPlugin``. What it has to get right is
+narrow: the order the checks run in (formats before turn detection, because
+that is the order clients already see), the error codes, and that a consumer
+which declares a narrower format set is actually narrowed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import pytest
+
+from vllm_omni.protocol.realtime.capabilities import (
+    RealtimeProtocolCapabilities,
+    RealtimeSessionRejection,
+    validate_session_payload,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+_DEFAULT = RealtimeProtocolCapabilities()
+
+
+def test_a_consumer_without_a_turn_detection_check_accepts_a_plain_session():
+    assert (
+        validate_session_payload({"model": "m", "audio": {"input": {"format": "pcm16"}}}, capabilities=_DEFAULT) is None
+    )
+
+
+def test_a_consumer_without_a_turn_detection_check_ignores_turn_detection():
+    payload = {"turn_detection": {"type": "semantic_vad"}}
+
+    assert validate_session_payload(payload, capabilities=_DEFAULT) is None
+
+
+def test_an_unsupported_input_format_is_rejected_with_the_realtime_code():
+    rejection = validate_session_payload({"input_audio_format": "opus"}, capabilities=_DEFAULT)
+
+    assert rejection == RealtimeSessionRejection(
+        code="unsupported_audio_format", message="Unsupported input_audio_format: opus"
+    )
+
+
+def test_a_consumer_may_declare_a_narrower_format_set():
+    pcm_only = RealtimeProtocolCapabilities(input_audio_formats=frozenset({"pcm16"}))
+
+    assert validate_session_payload({"input_audio_format": "pcm16"}, capabilities=pcm_only) is None
+    rejection = validate_session_payload({"input_audio_format": "g711_ulaw"}, capabilities=pcm_only)
+    assert rejection is not None
+    assert rejection.code == "unsupported_audio_format"
+    # The default capabilities still accept it: the narrowing is per consumer.
+    assert validate_session_payload({"input_audio_format": "g711_ulaw"}, capabilities=_DEFAULT) is None
+
+
+def test_the_turn_detection_check_runs_and_reports_its_own_code():
+    def reject_everything(session_payload: Mapping[str, object]) -> str | None:
+        del session_payload
+        return "server_vad is not available"
+
+    capabilities = RealtimeProtocolCapabilities(validate_turn_detection=reject_everything)
+
+    rejection = validate_session_payload({"turn_detection": {"type": "server_vad"}}, capabilities=capabilities)
+
+    assert rejection == RealtimeSessionRejection(
+        code="unsupported_turn_detection", message="server_vad is not available", param="turn_detection"
+    )
+
+
+def test_a_bad_format_is_reported_before_a_bad_turn_detection():
+    calls: list[Mapping[str, object]] = []
+
+    def record(session_payload: Mapping[str, object]) -> str | None:
+        calls.append(session_payload)
+        return "turn detection is wrong too"
+
+    capabilities = RealtimeProtocolCapabilities(validate_turn_detection=record)
+
+    rejection = validate_session_payload(
+        {"input_audio_format": "opus", "turn_detection": {"type": "semantic_vad"}},
+        capabilities=capabilities,
+    )
+
+    assert rejection is not None
+    assert rejection.code == "unsupported_audio_format"
+    assert calls == []
diff --git a/tests/protocol/realtime/test_realtime_codec_single_source.py b/tests/protocol/realtime/test_realtime_codec_single_source.py
new file mode 100644
index 00000000000..2f719750b06
--- /dev/null
+++ b/tests/protocol/realtime/test_realtime_codec_single_source.py
@@ -0,0 +1,256 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""There is one Realtime codec, and the duplex engine uses it.
+
+RFC #6592 P0a rejects the "copy the codec and fix it up" option because the two
+copies drift. The extraction is only worth anything while the duplex names are
+*the same objects* as the protocol ones, not lookalikes --- so assert identity,
+which a re-implementation cannot satisfy.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+
+import pytest
+
+from vllm_omni.engine.duplex import audio as duplex_audio
+from vllm_omni.engine.duplex import events as duplex_events
+from vllm_omni.engine.duplex import realtime_commands as duplex_codec
+from vllm_omni.engine.duplex.commands import DuplexCommandError
+from vllm_omni.protocol import realtime as protocol
+from vllm_omni.protocol.realtime.errors import RealtimeProtocolError
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+#: Names ``engine.duplex.realtime_commands`` re-exports for its existing importers.
+_REEXPORTED_FROM_PROTOCOL = (
+    "REALTIME_INPUT_AUDIO_FORMATS",
+    "REALTIME_INPUT_HINT_KEYS",
+    "REALTIME_OUTPUT_AUDIO_FORMATS",
+    "RealtimeInputDefaults",
+    "apply_realtime_session_defaults",
+    "copy_realtime_input_hints",
+    "input_audio_transcription_config",
+    "input_explicitly_non_speech",
+    "input_looks_like_speech",
+    "input_transcript_from_item",
+    "is_supported_realtime_input_format",
+    "json_safe_realtime_payload",
+    "normalize_conversation_item",
+    "parse_realtime_audio_format",
+    "realtime_audio_format_object",
+    "realtime_max_output_tokens",
+    "realtime_output_format",
+    "realtime_overlap_fields",
+    "text_chars_for_audio_ms_from_marks",
+    "truncate_realtime_item_content",
+    "validate_conversation_item_audio_formats",
+    "validate_realtime_item_truncate",
+    "validate_realtime_response_audio_formats",
+    "validate_realtime_session_audio_formats",
+    "validate_realtime_video_frames",
+)
+
+
+@pytest.mark.parametrize("name", _REEXPORTED_FROM_PROTOCOL)
+def test_the_duplex_codec_name_is_the_protocol_object(name: str) -> None:
+    assert getattr(duplex_codec, name) is getattr(protocol, name)
+
+
+@pytest.mark.parametrize(
+    "name",
+    ("convert_input_audio_with_rate", "convert_output_audio", "resample_pcm16_mono", "wav_payload_to_pcm16"),
+)
+def test_the_duplex_audio_shim_is_the_protocol_object(name: str) -> None:
+    assert getattr(duplex_audio, name) is getattr(protocol, name)
+
+
+def test_a_duplex_command_error_is_a_realtime_protocol_error() -> None:
+    # The duplex binding converts the codec's error into its own type; both
+    # carry the same code/event_id, which is what the error envelope renders.
+    error = DuplexCommandError("bad", code="bad_audio", event_id="event_1")
+
+    assert isinstance(error, RealtimeProtocolError)
+    assert (error.code, error.event_id) == ("bad_audio", "event_1")
+
+
+def test_the_duplex_append_command_is_built_from_the_shared_decoder() -> None:
+    defaults = protocol.RealtimeInputDefaults()
+    event = {"event_id": "event_1", "audio": "", "format": "pcm16", "duration_ms": 40}
+
+    decoded = protocol.decode_audio_append(event, defaults=defaults)
+    command = duplex_codec.build_append_audio(event, defaults=defaults)
+
+    assert (command.audio, command.format, command.sample_rate_hz) == (
+        decoded.audio,
+        decoded.format,
+        decoded.sample_rate_hz,
+    )
+    assert (command.is_speech, command.video_frames, command.duration_ms) == (
+        decoded.is_speech,
+        decoded.video_frames,
+        decoded.duration_ms,
+    )
+    assert (command.audio_end_ms, dict(command.hints), command.event_id) == (
+        decoded.audio_end_ms,
+        decoded.hints,
+        decoded.event_id,
+    )
+
+
+def test_the_shared_decoder_error_reaches_the_client_as_a_duplex_command_error() -> None:
+    defaults = protocol.RealtimeInputDefaults()
+    event = {"event_id": "event_1", "audio": "AAAA", "format": "opus"}
+
+    with pytest.raises(RealtimeProtocolError) as shared:
+        protocol.decode_audio_append(event, defaults=defaults)
+    with pytest.raises(DuplexCommandError) as duplex:
+        duplex_codec.build_append_audio(event, defaults=defaults)
+
+    assert (duplex.value.code, str(duplex.value)) == (shared.value.code, str(shared.value))
+    assert duplex.value.event_id == shared.value.event_id == "event_1"
+
+
+def test_the_duplex_capabilities_reject_unimplemented_turn_detection() -> None:
+    # The duplex answer comes from engine.duplex.turn_detection, reached through
+    # the capability object rather than imported by the codec.
+    rejection = protocol.validate_session_payload(
+        {"turn_detection": {"type": "semantic_vad"}},
+        capabilities=duplex_codec.DUPLEX_REALTIME_CAPABILITIES,
+    )
+
+    assert rejection is not None
+    assert rejection.code == "unsupported_turn_detection"
+
+
+# ---- the class split (RFC #6592 P0a, second half) ----
+#
+# The event and command classes moved out of the engine too. The same identity
+# rule applies: the duplex names must BE the protocol objects, and the mailbox
+# half must have stayed behind.
+
+# `docs/serving/realtime_duplex_api.md` sorts every message into three tiers.
+# Tier 1 is pure OpenAI and lives in protocol/realtime; Tier 2 (OpenAI names
+# carrying our extensions) and Tier 3 (ours alone) live in protocol/duplex.
+_TIER1_EVENTS = ("SessionUpdated", "ItemAdded", "ItemCreated", "TextDelta", "OutputItemAdded")
+_TIER2_EVENTS = (
+    "SessionCreated",
+    "ResponseCreated",
+    "ResponseDone",
+    "AudioDelta",
+    "InputCommitted",
+    "ItemDeleted",
+    "ItemTruncated",
+    "ErrorEvent",
+)
+_TIER3_EVENTS = ("Listen", "Speak", "OverlapDecision", "PlaybackAcknowledged", "SessionResumed")
+_TIER1_COMMANDS = ("UpdateSession", "CreateItem", "CancelResponse", "ClearInput")
+_TIER2_COMMANDS = ("AppendAudio", "Commit")
+_TIER3_COMMANDS = ("BargeIn", "AckPlayback", "Heartbeat", "SignalTurn", "CloseSession")
+
+
+@pytest.mark.parametrize("name", _TIER1_EVENTS)
+def test_tier1_events_are_the_pure_openai_objects(name: str) -> None:
+    from vllm_omni.protocol.realtime import events as realtime_events
+
+    assert duplex_events.__dict__[name] is getattr(realtime_events, name)
+
+
+@pytest.mark.parametrize("name", _TIER2_EVENTS + _TIER3_EVENTS)
+def test_tier2_and_tier3_events_come_from_protocol_duplex(name: str) -> None:
+    from vllm_omni.protocol.duplex import events as duplex_wire_events
+
+    assert duplex_events.__dict__[name] is getattr(duplex_wire_events, name)
+
+
+@pytest.mark.parametrize("name", _TIER2_EVENTS)
+def test_tier2_extends_its_tier1_twin_rather_than_replacing_it(name: str) -> None:
+    """A Tier 2 class must be its Tier 1 class plus fields, never a fork of it."""
+    from vllm_omni.protocol.duplex import events as duplex_wire_events
+    from vllm_omni.protocol.realtime import events as realtime_events
+
+    tier1 = getattr(realtime_events, name)
+    tier2 = getattr(duplex_wire_events, name)
+
+    assert issubclass(tier2, tier1)
+    assert tier2.wire_type == tier1.wire_type
+    tier1_fields = {f.name for f in dataclasses.fields(tier1)}
+    tier2_fields = {f.name for f in dataclasses.fields(tier2)}
+    # Purely additive: Tier 2 adds, never drops or renames.
+    assert tier1_fields < tier2_fields
+
+
+@pytest.mark.parametrize("name", _TIER1_EVENTS + _TIER1_COMMANDS)
+def test_tier1_carries_no_vllm_omni_extension_fields(name: str) -> None:
+    """The point of the split: protocol/realtime must be honestly pure OpenAI."""
+    from vllm_omni.protocol.realtime import commands as realtime_commands
+    from vllm_omni.protocol.realtime import events as realtime_events
+
+    cls = getattr(realtime_events, name, None) or getattr(realtime_commands, name)
+    fields = {f.name for f in dataclasses.fields(cls)}
+    # Extension fields catalogued as Tier 2 in the serving doc.
+    assert not (
+        fields
+        & {
+            "attachment_generation",
+            "resume_token",
+            "details",
+            "extra",
+            "is_speech",
+            "video_frames",
+            "hints",
+            "realtime_item_id",
+        }
+    )
+
+
+def test_the_error_code_vocabulary_is_tier3() -> None:
+    """OpenAI standardises the error classes, not our codes (doc: Tier 3)."""
+    from vllm_omni.protocol.duplex.errors import REALTIME_ERROR_TYPES_BY_CODE
+    from vllm_omni.protocol.realtime import errors as realtime_errors
+
+    assert duplex_events.REALTIME_ERROR_TYPES_BY_CODE is REALTIME_ERROR_TYPES_BY_CODE
+    assert not hasattr(realtime_errors, "REALTIME_ERROR_TYPES_BY_CODE")
+
+
+def test_the_tier1_error_event_reports_only_openai_classes() -> None:
+    from vllm_omni.protocol.duplex import events as duplex_wire_events
+    from vllm_omni.protocol.realtime import events as realtime_events
+
+    # Tier 1 knows the envelope shape but not our code vocabulary.
+    assert realtime_events.ErrorEvent(code="resource_exhausted").error_type == "invalid_request_error"
+    # Tier 2 resolves it through our table.
+    assert duplex_wire_events.ErrorEvent(code="resource_exhausted").error_type == "rate_limit_error"
+
+
+@pytest.mark.parametrize("name", _TIER1_COMMANDS + _TIER2_COMMANDS + _TIER3_COMMANDS)
+def test_engine_commands_subclass_their_protocol_wire_type(name: str) -> None:
+    from vllm_omni.engine.duplex import commands as engine_commands
+    from vllm_omni.protocol.duplex import commands as duplex_wire_commands
+    from vllm_omni.protocol.realtime import commands as realtime_commands
+
+    engine_cls = getattr(engine_commands, name)
+    wire_cls = getattr(duplex_wire_commands, name, None) or getattr(realtime_commands, name)
+
+    assert issubclass(engine_cls, wire_cls)
+    assert engine_cls.wire_type == wire_cls.wire_type
+
+
+def test_the_mailbox_channel_stayed_engine_side() -> None:
+    """``payload()``'s ``type`` is the runner's channel, not the client event.
+
+    These four are the proof that the two halves are genuinely different, and
+    so the reason the classes were split rather than relocated wholesale.
+    """
+    from vllm_omni.engine.duplex import commands as engine_commands
+    from vllm_omni.protocol.realtime import commands as realtime_commands
+
+    for name in ("UpdateSession", "CreateItem", "DeleteItem", "TruncateItem"):
+        engine_cls = getattr(engine_commands, name)
+        wire_cls = getattr(realtime_commands, name)
+        assert engine_cls.type == "turn.signal"
+        assert wire_cls.wire_type != "turn.signal"
+        # The wire class carries no mailbox vocabulary at all.
+        assert "type" not in vars(wire_cls)
diff --git a/tools/pre_commit/check_forbidden_imports.py b/tools/pre_commit/check_forbidden_imports.py
index 959007c30ce..5f19123bc1d 100644
--- a/tools/pre_commit/check_forbidden_imports.py
+++ b/tools/pre_commit/check_forbidden_imports.py
@@ -79,11 +79,12 @@ class ForbiddenImport:
             "vllm_omni/entrypoints/openai/video_stream_base.py",
             "vllm_omni/entrypoints/openai/video_stream_session.py",
             "vllm_omni/experimental/fullduplex/client.py",
-            "vllm_omni/engine/duplex/audio.py",
             "vllm_omni/engine/duplex/commands.py",
             "vllm_omni/engine/duplex/contracts.py",
-            "vllm_omni/engine/duplex/events.py",
-            "vllm_omni/engine/duplex/realtime_commands.py",
+            "vllm_omni/protocol/realtime/audio.py",
+            "vllm_omni/protocol/realtime/audio_input.py",
+            "vllm_omni/protocol/realtime/events.py",
+            "vllm_omni/protocol/realtime/items.py",
             "vllm_omni/experimental/fullduplex/joyvl/memory/memory.py",
             "vllm_omni/model_executor/models/minicpmo_4_5/duplex/input.py",
             "vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py",
diff --git a/vllm_omni/clients/inline_duplex.py b/vllm_omni/clients/inline_duplex.py
index 79c09e014fe..5af8efc5ff4 100644
--- a/vllm_omni/clients/inline_duplex.py
+++ b/vllm_omni/clients/inline_duplex.py
@@ -32,8 +32,8 @@
 from vllm_omni.clients.duplex import DuplexClientBase, DuplexConnectionError, SessionConfig
 
 if TYPE_CHECKING:
-    from vllm_omni.engine.duplex.realtime_commands import RealtimeInputDefaults
     from vllm_omni.entrypoints.duplex_omni import DuplexOmni, DuplexSessionHandle
+    from vllm_omni.protocol.duplex import RealtimeInputDefaults
 
 __all__ = ["InlineDuplexClient"]
 
@@ -71,7 +71,7 @@ async def _open(self) -> None:
 
     def _input_defaults(self) -> RealtimeInputDefaults:
         """Audio format / sample-rate / VAD defaults declared by this session's object."""
-        from vllm_omni.engine.duplex.realtime_commands import RealtimeInputDefaults
+        from vllm_omni.protocol.duplex import RealtimeInputDefaults
 
         session_payload = self.session_info or self.config.to_session_payload(model=self.model)
         return RealtimeInputDefaults().with_session_payload(session_payload)
diff --git a/vllm_omni/engine/duplex/audio.py b/vllm_omni/engine/duplex/audio.py
index 5f163826a6a..2d46e8edb69 100644
--- a/vllm_omni/engine/duplex/audio.py
+++ b/vllm_omni/engine/duplex/audio.py
@@ -1,218 +1,44 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-from __future__ import annotations
-
-import base64
-import binascii
-import io
-import math
-import wave
-
-import numpy as np
-
-from vllm_omni.utils.audio_resample import StreamingAudioResampler
-
-try:
-    from audioop import alaw2lin, lin2alaw, lin2ulaw, ulaw2lin
-except ImportError:  # pragma: no cover - audioop is removed in newer Python.
-    alaw2lin = lin2alaw = lin2ulaw = ulaw2lin = None
-
-
-MIN_INPUT_SAMPLE_RATE_HZ = 8_000
-MAX_INPUT_SAMPLE_RATE_HZ = 192_000
-
-
-def validate_input_sample_rate_hz(sample_rate_hz: object) -> int:
-    if (
-        isinstance(sample_rate_hz, bool)
-        or not isinstance(sample_rate_hz, int | float)
-        or (isinstance(sample_rate_hz, float) and not math.isfinite(sample_rate_hz))
-    ):
-        raise ValueError("sample_rate_hz must be a finite integer")
-    rate = int(sample_rate_hz)
-    if rate != sample_rate_hz:
-        raise ValueError("sample_rate_hz must be an integer")
-    if not MIN_INPUT_SAMPLE_RATE_HZ <= rate <= MAX_INPUT_SAMPLE_RATE_HZ:
-        raise ValueError(f"sample_rate_hz must be between {MIN_INPUT_SAMPLE_RATE_HZ} and {MAX_INPUT_SAMPLE_RATE_HZ}")
-    return rate
-
-
-def resample_pcm16_mono(raw: bytes, *, source_rate_hz: int, target_rate_hz: int) -> bytes:
-    if source_rate_hz <= 0 or target_rate_hz <= 0 or source_rate_hz == target_rate_hz:
-        return raw
-    samples = np.frombuffer(raw, dtype="<i2")
-    rate_gcd = math.gcd(source_rate_hz, target_rate_hz)
-    reduced_factor = max(source_rate_hz // rate_gcd, target_rate_hz // rate_gcd)
-    if reduced_factor > StreamingAudioResampler.max_polyphase_factor:
-        # The FIR size scales with the reduced ratio. Keep unusual client
-        # rates bounded while common audio rates use the high-quality path.
-        if samples.size <= 1:
-            return raw
-        target_size = max(1, int(round(samples.size * target_rate_hz / source_rate_hz)))
-        source_x = np.linspace(0.0, 1.0, num=samples.size, endpoint=True)
-        target_x = np.linspace(0.0, 1.0, num=target_size, endpoint=True)
-        resampled = np.interp(target_x, source_x, samples)
-        return np.clip(resampled, -32_768, 32_767).astype("<i2").tobytes()
-    resampler = StreamingAudioResampler(source_rate_hz, target_rate_hz)
-    normalized = samples.astype(np.float32) * np.float32(1.0 / 32768.0)
-    resampled = resampler.process(normalized, final=True)
-    return np.clip(np.rint(resampled * 32768.0), -32768, 32767).astype("<i2").tobytes()
-
-
-def decode_g711_ulaw(raw: bytes) -> bytes:
-    if ulaw2lin is not None:
-        return ulaw2lin(raw, 2)
-    data = np.frombuffer(raw, dtype=np.uint8)
-    value = np.bitwise_not(data).astype(np.int16)
-    sign = value & 0x80
-    exponent = (value >> 4) & 0x07
-    mantissa = value & 0x0F
-    sample = ((mantissa << 3) + 0x84) << exponent
-    return np.where(sign != 0, -(sample - 0x84), sample - 0x84).astype("<i2").tobytes()
+"""Compatibility re-export: the Realtime audio codec moved out of the duplex engine.
 
+Decoding PCM / G.711 / WAV, resampling and re-encoding are wire-format work with
+no duplex session in them, so the implementation now lives in
+``vllm_omni.protocol.realtime.audio`` where a non-duplex Realtime surface can
+use it too. Duplex code reaches it through ``vllm_omni.protocol.duplex``, the
+one door the engine uses --- which is also where a duplex-specific conversion
+would be introduced. Import from there in new code.
+"""
 
-def decode_g711_alaw(raw: bytes) -> bytes:
-    if alaw2lin is not None:
-        return alaw2lin(raw, 2)
-    data = np.bitwise_xor(np.frombuffer(raw, dtype=np.uint8), 0x55).astype(np.int16)
-    sign = data & 0x80
-    exponent = (data >> 4) & 0x07
-    mantissa = data & 0x0F
-    sample = np.where(exponent == 0, (mantissa << 4) + 8, ((mantissa << 4) + 0x108) << (exponent - 1))
-    return np.where(sign != 0, sample, -sample).astype("<i2").tobytes()
-
-
-def encode_g711_ulaw(raw: bytes) -> bytes:
-    if lin2ulaw is not None:
-        return lin2ulaw(raw, 2)
-    pcm = np.clip(np.frombuffer(raw, dtype="<i2").astype(np.int32), -32635, 32635)
-    sign = np.where(pcm < 0, 0x80, 0)
-    magnitude = np.abs(pcm) + 0x84
-    exponent = np.zeros_like(magnitude)
-    for exp in range(7):
-        exponent = np.where(magnitude > (0xFF << exp), exp + 1, exponent)
-    mantissa = (magnitude >> (exponent + 3)) & 0x0F
-    return (np.bitwise_not(sign | (exponent << 4) | mantissa) & 0xFF).astype(np.uint8).tobytes()
-
-
-def encode_g711_alaw(raw: bytes) -> bytes:
-    if lin2alaw is not None:
-        return lin2alaw(raw, 2)
-    pcm = np.frombuffer(raw, dtype="<i2").astype(np.int32)
-    sign = np.where(pcm >= 0, 0x80, 0x00)
-    magnitude = np.abs(pcm)
-    exponent = np.zeros_like(magnitude)
-    for exp in range(1, 8):
-        exponent = np.where(magnitude >= (1 << (exp + 7)), exp, exponent)
-    mantissa = np.where(
-        exponent == 0,
-        (magnitude >> 4) & 0x0F,
-        (magnitude >> (exponent + 3)) & 0x0F,
-    )
-    return ((sign | (exponent << 4) | mantissa) ^ 0x55).astype(np.uint8).tobytes()
-
-
-def wav_payload_to_pcm16(raw: bytes) -> tuple[bytes | None, int | None]:
-    try:
-        with wave.open(io.BytesIO(raw), "rb") as wav_file:
-            channels = wav_file.getnchannels()
-            sample_width = wav_file.getsampwidth()
-            sample_rate_hz = wav_file.getframerate()
-            frames = wav_file.readframes(wav_file.getnframes())
-        if sample_width != 2:
-            return None, sample_rate_hz
-        if channels <= 1:
-            return frames, sample_rate_hz
-        pcm = np.frombuffer(frames, dtype="<i2").reshape(-1, channels)
-        mono = np.mean(pcm.astype(np.float32), axis=1)
-        return np.clip(mono, -32768, 32767).astype("<i2").tobytes(), sample_rate_hz
-    except (EOFError, ValueError, wave.Error):
-        return None, None
-
-
-def encode_float32_mono_wav_base64(
-    samples: np.ndarray,
-    *,
-    sample_rate_hz: int,
-) -> str:
-    """Package normalized mono float32 samples as a PCM16 WAV data payload."""
-    rate = validate_input_sample_rate_hz(sample_rate_hz)
-    normalized = np.ascontiguousarray(samples, dtype=np.float32).reshape(-1)
-    pcm16 = np.clip(np.rint(normalized * 32768.0), -32768, 32767).astype("<i2")
-    with io.BytesIO() as buffer:
-        with wave.open(buffer, "wb") as wav_file:
-            wav_file.setnchannels(1)
-            wav_file.setsampwidth(2)
-            wav_file.setframerate(rate)
-            wav_file.writeframes(pcm16.tobytes())
-        return base64.b64encode(buffer.getvalue()).decode("ascii")
-
-
-def convert_input_audio_with_rate(
-    audio: object,
-    fmt: object,
-    *,
-    sample_rate_hz: int | float | None = None,
-    target_sample_rate_hz: int = 16_000,
-) -> tuple[object, object, int | float | None]:
-    if not isinstance(audio, str) or not isinstance(fmt, str):
-        return audio, fmt, sample_rate_hz
-    normalized = fmt.lower()
-    if normalized not in {"pcm16", "pcm_s16le", "s16le", "g711_ulaw", "g711_alaw"}:
-        return audio, fmt, sample_rate_hz
-    if isinstance(sample_rate_hz, int | float):
-        sample_rate_hz = validate_input_sample_rate_hz(sample_rate_hz)
-    try:
-        raw = base64.b64decode(audio.strip(), validate=False)
-    except (binascii.Error, ValueError):
-        return audio, fmt, sample_rate_hz
-    if normalized == "g711_ulaw":
-        raw = decode_g711_ulaw(raw)
-        sample_rate_hz = sample_rate_hz if isinstance(sample_rate_hz, int | float) else 8_000
-    elif normalized == "g711_alaw":
-        raw = decode_g711_alaw(raw)
-        sample_rate_hz = sample_rate_hz if isinstance(sample_rate_hz, int | float) else 8_000
-    elif len(raw) % 2:
-        return audio, fmt, sample_rate_hz
-    if isinstance(sample_rate_hz, int | float) and int(sample_rate_hz) != target_sample_rate_hz:
-        raw = resample_pcm16_mono(
-            raw,
-            source_rate_hz=int(sample_rate_hz),
-            target_rate_hz=target_sample_rate_hz,
-        )
-        sample_rate_hz = target_sample_rate_hz
-    pcm = np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768.0
-    encoded = base64.b64encode(np.ascontiguousarray(pcm, dtype="<f4").tobytes()).decode("ascii")
-    return encoded, "pcm_f32le", sample_rate_hz
-
+from __future__ import annotations
 
-def convert_output_audio(
-    audio: str,
-    *,
-    source_fmt: str,
-    target_fmt: str,
-    source_sample_rate_hz: int | None = None,
-    target_sample_rate_hz: int | None = None,
-) -> tuple[str, str, int | None]:
-    target = target_fmt.lower()
-    if target not in {"g711_ulaw", "g711_alaw"}:
-        return audio, source_fmt, source_sample_rate_hz
-    try:
-        raw = base64.b64decode(audio, validate=False)
-    except (binascii.Error, ValueError):
-        return audio, source_fmt, source_sample_rate_hz
-    source = source_fmt.lower()
-    if source == "wav":
-        pcm_raw, wav_rate = wav_payload_to_pcm16(raw)
-        if pcm_raw is None:
-            return audio, source_fmt, source_sample_rate_hz
-        raw = pcm_raw
-        source_sample_rate_hz = source_sample_rate_hz or wav_rate
-    elif source not in {"pcm", "pcm16", "pcm_s16le", "s16le"} or len(raw) % 2:
-        return audio, source_fmt, source_sample_rate_hz
-    target_rate = target_sample_rate_hz or 8_000
-    if source_sample_rate_hz is not None:
-        raw = resample_pcm16_mono(raw, source_rate_hz=source_sample_rate_hz, target_rate_hz=target_rate)
-    encoded = encode_g711_ulaw(raw) if target == "g711_ulaw" else encode_g711_alaw(raw)
-    return base64.b64encode(encoded).decode("ascii"), target, target_rate
+from vllm_omni.protocol.duplex import (
+    MAX_INPUT_SAMPLE_RATE_HZ,
+    MIN_INPUT_SAMPLE_RATE_HZ,
+    convert_input_audio_with_rate,
+    convert_output_audio,
+    decode_g711_alaw,
+    decode_g711_ulaw,
+    encode_float32_mono_wav_base64,
+    encode_g711_alaw,
+    encode_g711_ulaw,
+    resample_pcm16_mono,
+    validate_input_sample_rate_hz,
+    wav_payload_to_pcm16,
+)
+
+__all__ = [
+    "MAX_INPUT_SAMPLE_RATE_HZ",
+    "MIN_INPUT_SAMPLE_RATE_HZ",
+    "convert_input_audio_with_rate",
+    "convert_output_audio",
+    "decode_g711_alaw",
+    "decode_g711_ulaw",
+    "encode_float32_mono_wav_base64",
+    "encode_g711_alaw",
+    "encode_g711_ulaw",
+    "resample_pcm16_mono",
+    "validate_input_sample_rate_hz",
+    "wav_payload_to_pcm16",
+]
diff --git a/vllm_omni/engine/duplex/commands.py b/vllm_omni/engine/duplex/commands.py
index 90d48d05055..19674948cd9 100644
--- a/vllm_omni/engine/duplex/commands.py
+++ b/vllm_omni/engine/duplex/commands.py
@@ -1,41 +1,62 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-"""Typed commands accepted by a duplex session.
+"""The command vocabulary one duplex session accepts, plus its mailbox rendering.
 
 ``DuplexSessionHandle.submit()`` takes one of these; the websocket handler and
-``InlineDuplexClient`` build them with :func:`command_from_realtime` from the
-OpenAI Realtime client event vocabulary. Every command can also render the
-session-internal mailbox payload (``payload()``), which is the dictionary
-vocabulary the session runner bodies were written against.
+``InlineDuplexClient`` build them with :func:`command_from_realtime`.
+
+The *wire* half of each command --- which client event it decodes from and what
+fields survive decoding --- now lives in ``vllm_omni.protocol.duplex.commands``,
+which carries the whole vocabulary: the eight Tier 1 classes re-exported from
+``vllm_omni.protocol.realtime.commands``, the two Tier 2 ones and the seven
+Tier 3 ones. The engine imports that module and never the Tier 1 one directly,
+so a command that later grows a duplex extension changes one file
+(RFC #6592 P0a).
+
+The *engine* half stays here, because it is not wire contract at all:
+``payload()`` renders the session-internal mailbox dictionary the runner bodies
+were written against, and its ``type`` is the mailbox channel rather than the
+client event. Those two genuinely differ --- ``session.update`` and
+``conversation.item.create`` / ``.delete`` / ``.truncate`` all travel on the
+``turn.signal`` channel --- which is why the halves are separated instead of
+the classes being relocated wholesale.
 """
 
 from __future__ import annotations
 
 import base64
 from collections.abc import Mapping
-from dataclasses import dataclass, field, fields
+from dataclasses import dataclass, fields
 from typing import TYPE_CHECKING, ClassVar
 
+from vllm_omni.protocol.duplex import RealtimeProtocolError
+from vllm_omni.protocol.duplex import commands as _duplex_wire
+from vllm_omni.protocol.duplex.commands import RealtimeCommand
+
 if TYPE_CHECKING:
-    from vllm_omni.engine.duplex.realtime_commands import RealtimeInputDefaults
+    from vllm_omni.protocol.duplex import RealtimeInputDefaults
 
 
-class DuplexCommandError(ValueError):
-    """A client payload could not be turned into a command."""
+class DuplexCommandError(RealtimeProtocolError):
+    """A client payload could not be turned into a duplex command.
 
-    def __init__(self, message: str, *, code: str = "bad_event", event_id: str | None = None) -> None:
-        super().__init__(message)
-        self.code = code
-        self.event_id = event_id
+    The duplex name for a Realtime protocol error: same ``code`` /
+    ``event_id`` contract, so the error envelope is rendered identically
+    whichever consumer raised it.
+    """
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class DuplexCommand:
+class DuplexCommand(RealtimeCommand):
+    """A Realtime command as the duplex engine handles it.
+
+    Adds the mailbox channel (``type``) and its rendering on top of the wire
+    command; every concrete class below pairs this with its protocol twin.
+    """
+
     #: Mailbox event type this command renders to (see ``payload()``).
     type: ClassVar[str] = ""
-    #: Client correlation id (OpenAI ``event_id``), echoed on error events.
-    event_id: str | None = None
 
     def payload(self) -> dict[str, object]:
         """Render the session-internal mailbox dictionary."""
@@ -56,19 +77,23 @@ def payload(self) -> dict[str, object]:
         return data
 
 
+# ---- GA commands ----
+
+
 @dataclass(frozen=True, slots=True, kw_only=True)
-class AppendAudio(DuplexCommand):
+class UpdateSession(DuplexCommand, _duplex_wire.UpdateSession):
+    type: ClassVar[str] = "turn.signal"
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        data["event"] = "session.update"
+        data["payload"] = dict(data.pop("patch", {}) or {})
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppendAudio(DuplexCommand, _duplex_wire.AppendAudio):
     type: ClassVar[str] = "input_audio_buffer.append"
-    #: Raw audio bytes in ``format`` at ``sample_rate_hz`` (base64 only on the wire).
-    audio: bytes
-    format: str = "pcm16"
-    sample_rate_hz: int | None = None
-    is_speech: bool | None = None
-    video_frames: tuple[str, ...] = ()
-    duration_ms: int | None = None
-    audio_end_ms: int | None = None
-    #: Model-neutral hints carried through from the wire (rms, vad, transcript hints ...).
-    hints: Mapping[str, object] = field(default_factory=dict)
 
     def payload(self) -> dict[str, object]:
         data = DuplexCommand.payload(self)
@@ -90,21 +115,8 @@ def payload(self) -> dict[str, object]:
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class AppendText(DuplexCommand):
-    type: ClassVar[str] = "input.text.append"
-    text: str
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class Commit(DuplexCommand):
+class Commit(DuplexCommand, _duplex_wire.Commit):
     type: ClassVar[str] = "input_audio_buffer.commit"
-    final: bool = True
-    #: ``None`` means "no explicit request": the runner decides on commit (auto-response
-    #: sessions answer on their own); ``True`` / ``False`` force it.
-    create_response: bool | None = None
-    is_speech: bool | None = None
-    #: Realtime conversation item created for this commit (wire correlation only).
-    realtime_item_id: str | None = None
 
     def payload(self) -> dict[str, object]:
         data = DuplexCommand.payload(self)
@@ -114,98 +126,35 @@ def payload(self) -> dict[str, object]:
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class CreateResponse(DuplexCommand):
-    type: ClassVar[str] = "response.create"
-    #: Raw Realtime ``response`` object (instructions, voice, modalities, ...).
-    options: Mapping[str, object] = field(default_factory=dict)
-
-    def payload(self) -> dict[str, object]:
-        data = DuplexCommand.payload(self)
-        options = data.pop("options", None)
-        if isinstance(options, Mapping):
-            data["response"] = dict(options)
-        return data
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ClearInput(DuplexCommand):
+class ClearInput(DuplexCommand, _duplex_wire.ClearInput):
     type: ClassVar[str] = "input_audio_buffer.clear"
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class CancelInput(DuplexCommand):
-    type: ClassVar[str] = "input.cancel"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class CancelResponse(DuplexCommand):
-    type: ClassVar[str] = "response.cancel"
-    response_id: str | None = None
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class BargeIn(DuplexCommand):
-    type: ClassVar[str] = "barge_in"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ClearOutputAudio(DuplexCommand):
+class ClearOutputAudio(DuplexCommand, _duplex_wire.ClearOutputAudio):
     type: ClassVar[str] = "output_audio_buffer.clear"
-    #: Explicit response to clear; ``None`` targets the active/last response.
-    response_id: str | None = None
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class SignalTurn(DuplexCommand):
-    """Generic ``turn.signal`` (local turn transitions such as ``user_started``)."""
-
-    type: ClassVar[str] = "turn.signal"
-    event: str
-    signal_payload: Mapping[str, object] = field(default_factory=dict)
-
-    def payload(self) -> dict[str, object]:
-        data = DuplexCommand.payload(self)
-        signal_payload = data.pop("signal_payload", None)
-        if isinstance(signal_payload, Mapping) and signal_payload:
-            data["payload"] = dict(signal_payload)
-        return data
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class UpdateSession(DuplexCommand):
-    """``session.update``: a Realtime ``session`` object patch."""
-
-    type: ClassVar[str] = "turn.signal"
-    patch: Mapping[str, object] = field(default_factory=dict)
+class CreateResponse(DuplexCommand, _duplex_wire.CreateResponse):
+    type: ClassVar[str] = "response.create"
 
     def payload(self) -> dict[str, object]:
         data = DuplexCommand.payload(self)
-        data["event"] = "session.update"
-        data["payload"] = dict(data.pop("patch", {}) or {})
+        options = data.pop("options", None)
+        if isinstance(options, Mapping):
+            data["response"] = dict(options)
         return data
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class AckPlayback(DuplexCommand):
-    type: ClassVar[str] = "playback.ack"
-    played_ms: int
-    committed_ms: int | None = None
-    response_id: str | None = None
-    item_id: str | None = None
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class Heartbeat(DuplexCommand):
-    type: ClassVar[str] = "session.heartbeat"
+class CancelResponse(DuplexCommand, _duplex_wire.CancelResponse):
+    type: ClassVar[str] = "response.cancel"
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class CreateItem(DuplexCommand):
-    """``conversation.item.create`` (history injection or function-call output)."""
-
+class CreateItem(DuplexCommand, _duplex_wire.CreateItem):
     type: ClassVar[str] = "turn.signal"
-    item: Mapping[str, object]
-    previous_item_id: str | None = None
 
     def payload(self) -> dict[str, object]:
         data = DuplexCommand.payload(self)
@@ -219,9 +168,8 @@ def payload(self) -> dict[str, object]:
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class DeleteItem(DuplexCommand):
+class DeleteItem(DuplexCommand, _duplex_wire.DeleteItem):
     type: ClassVar[str] = "turn.signal"
-    item_id: str
 
     def payload(self) -> dict[str, object]:
         data = DuplexCommand.payload(self)
@@ -231,11 +179,8 @@ def payload(self) -> dict[str, object]:
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class TruncateItem(DuplexCommand):
+class TruncateItem(DuplexCommand, _duplex_wire.TruncateItem):
     type: ClassVar[str] = "turn.signal"
-    item_id: str
-    audio_end_ms: int
-    content_index: int = 0
 
     def payload(self) -> dict[str, object]:
         data = DuplexCommand.payload(self)
@@ -248,15 +193,51 @@ def payload(self) -> dict[str, object]:
         return data
 
 
+# ---- duplex extension commands ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppendText(DuplexCommand, _duplex_wire.AppendText):
+    type: ClassVar[str] = "input.text.append"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CancelInput(DuplexCommand, _duplex_wire.CancelInput):
+    type: ClassVar[str] = "input.cancel"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BargeIn(DuplexCommand, _duplex_wire.BargeIn):
+    type: ClassVar[str] = "barge_in"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SignalTurn(DuplexCommand, _duplex_wire.SignalTurn):
+    type: ClassVar[str] = "turn.signal"
+
+    def payload(self) -> dict[str, object]:
+        data = DuplexCommand.payload(self)
+        signal_payload = data.pop("signal_payload", None)
+        if isinstance(signal_payload, Mapping) and signal_payload:
+            data["payload"] = dict(signal_payload)
+        return data
+
+
 @dataclass(frozen=True, slots=True, kw_only=True)
-class CloseSession(DuplexCommand):
-    """Graceful close requested through the command stream (``session.close``)."""
+class AckPlayback(DuplexCommand, _duplex_wire.AckPlayback):
+    type: ClassVar[str] = "playback.ack"
+
 
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Heartbeat(DuplexCommand, _duplex_wire.Heartbeat):
+    type: ClassVar[str] = "session.heartbeat"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CloseSession(DuplexCommand, _duplex_wire.CloseSession):
     type: ClassVar[str] = "session.close"
-    reason: str = "client_close"
 
 
-#: Realtime client event types that map onto commands (wire vocabulary).
 REALTIME_COMMAND_TYPES: frozenset[str] = frozenset(
     {
         "input_audio_buffer.append",
@@ -300,7 +281,6 @@ def command_from_realtime(
 
 
 __all__ = [
-    "REALTIME_COMMAND_TYPES",
     "AckPlayback",
     "AppendAudio",
     "AppendText",
@@ -317,6 +297,8 @@ def command_from_realtime(
     "DuplexCommand",
     "DuplexCommandError",
     "Heartbeat",
+    "REALTIME_COMMAND_TYPES",
+    "RealtimeCommand",
     "SignalTurn",
     "TruncateItem",
     "UpdateSession",
diff --git a/vllm_omni/engine/duplex/config.py b/vllm_omni/engine/duplex/config.py
index aab0fb1c5b6..a898a2cf5f7 100644
--- a/vllm_omni/engine/duplex/config.py
+++ b/vllm_omni/engine/duplex/config.py
@@ -339,26 +339,26 @@ def from_realtime(
         ``_session_create_from_realtime``.
         """
         from vllm_omni.engine.duplex.realtime_commands import (
-            RealtimeInputDefaults,
+            DUPLEX_REALTIME_CAPABILITIES,
             duplex_response_format,
+        )
+        from vllm_omni.engine.duplex.turn_detection import normalize_turn_detection_session_payload
+        from vllm_omni.protocol.duplex import (
+            RealtimeInputDefaults,
             input_audio_transcription_config,
             json_safe_realtime_payload,
             realtime_max_output_tokens,
             realtime_overlap_fields,
-            validate_realtime_session_audio_formats,
-        )
-        from vllm_omni.engine.duplex.turn_detection import (
-            normalize_turn_detection_session_payload,
-            validate_realtime_turn_detection,
+            validate_session_payload,
         )
 
         payload: dict[str, object] = dict(session_payload)
-        format_error = validate_realtime_session_audio_formats(payload)
-        if format_error is not None:
-            raise DuplexConfigError(format_error, code="unsupported_audio_format")
-        turn_detection_error = validate_realtime_turn_detection(payload)
-        if turn_detection_error is not None:
-            raise DuplexConfigError(turn_detection_error, code="unsupported_turn_detection", param="turn_detection")
+        # One session check for every consumer (ENTRY-INV-002): the same
+        # capability object ``translate_realtime_command`` uses, so a session
+        # object is accepted or refused identically whichever door it came in.
+        rejection = validate_session_payload(payload, capabilities=DUPLEX_REALTIME_CAPABILITIES)
+        if rejection is not None:
+            raise DuplexConfigError(rejection.message, code=rejection.code, param=rejection.param)
         normalize_turn_detection_session_payload(payload)
         defaults = RealtimeInputDefaults().with_session_payload(payload)
         payload.update(realtime_overlap_fields(payload))
@@ -446,9 +446,9 @@ def apply_realtime_update(
         when the patch changes something a live session cannot change.
         ``audio_started`` is ``playback.generated_ms > 0 or playback.sent_ms > 0``.
         """
-        from vllm_omni.engine.duplex.realtime_commands import (
+        from vllm_omni.engine.duplex.realtime_commands import duplex_response_format
+        from vllm_omni.protocol.duplex import (
             REALTIME_OUTPUT_AUDIO_FORMATS,
-            duplex_response_format,
             input_audio_transcription_config,
             json_safe_realtime_payload,
             parse_realtime_audio_format,
@@ -629,9 +629,9 @@ def from_realtime(
         for options a model-native duplex session cannot apply per response.
         Private runtime keys in ``extra_body`` are dropped.
         """
-        from vllm_omni.engine.duplex.realtime_commands import (
+        from vllm_omni.engine.duplex.realtime_commands import duplex_response_format
+        from vllm_omni.protocol.duplex import (
             REALTIME_OUTPUT_AUDIO_FORMATS,
-            duplex_response_format,
             parse_realtime_audio_format,
             realtime_max_output_tokens,
         )
@@ -782,14 +782,14 @@ def realtime_item_to_history_message(item: object) -> dict[str, object] | None:
 
 def realtime_max_output_tokens(value: object) -> int | None:
     """Normalize Realtime max output tokens (``"inf"`` -> ``None``)."""
-    from vllm_omni.engine.duplex.realtime_commands import realtime_max_output_tokens as _impl
+    from vllm_omni.protocol.duplex import realtime_max_output_tokens as _impl
 
     return _impl(value)
 
 
 def input_audio_transcription_config(session_payload: Mapping[str, object]) -> dict[str, object] | None:
     """Return the ``input_audio_transcription`` object of a Realtime session payload."""
-    from vllm_omni.engine.duplex.realtime_commands import input_audio_transcription_config as _impl
+    from vllm_omni.protocol.duplex import input_audio_transcription_config as _impl
 
     return _impl(session_payload)
 
diff --git a/vllm_omni/engine/duplex/events.py b/vllm_omni/engine/duplex/events.py
index 9c131a893e2..197dec613c0 100644
--- a/vllm_omni/engine/duplex/events.py
+++ b/vllm_omni/engine/duplex/events.py
@@ -1,677 +1,79 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-"""Typed events emitted by a duplex session.
-
-Every public event is a frozen dataclass with explicit fields. The Realtime
-wire JSON is *derived* from those fields by :meth:`DuplexEvent.to_realtime`,
-which is pure: it never consults session state. The stateful part (response /
-item ids, content-part bookkeeping) lives in
-``vllm_omni.engine.duplex.realtime_events`` on the session runner and is
-consumed when the events are *constructed*.
-
-``session_id`` / ``epoch`` are bound by
-``DuplexSessionManager.emit`` when an event leaves the runner; producers
-(projector, serving handshake helpers) build events with the defaults.
+"""The event vocabulary one duplex session speaks, assembled from two layers.
+
+The classes themselves no longer live here. ``vllm_omni.protocol.duplex.events``
+carries the whole vocabulary --- 22 Tier 1 classes re-exported from
+``vllm_omni.protocol.realtime.events``, 8 Tier 2 ones and 12 Tier 3 ones --- so
+a non-duplex Realtime consumer can take the Tier 1 half and its wire rendering
+without the duplex session control plane (RFC #6592 P0a). The engine imports
+the duplex module and never the Tier 1 one directly.
+
+What is genuinely engine-side stays: :data:`DOMAIN_TERMINAL_EVENTS` and
+:data:`MODEL_OUTPUT_EVENTS` are the session runner's epoch-filter policy, not
+wire contract --- they name *internal* event types, and which of them may never
+be dropped as stale is a runtime decision.
+
+``DuplexEvent`` is re-exported as the name the engine and the clients already
+use. It is an alias of
+:class:`~vllm_omni.protocol.realtime.events.RealtimeEvent`, not a subclass,
+because an event has no engine-internal half --- what the session emits is
+exactly what the socket sends. A *command* does have one (``payload()`` renders
+the runner's mailbox), which is why ``DuplexCommand`` is a real class.
 """
 
 from __future__ import annotations
 
-import base64
-from collections.abc import Mapping
-from dataclasses import dataclass, field, fields
-from typing import ClassVar, cast
-from uuid import uuid4
-
-
-def new_event_id() -> str:
-    return f"event_{uuid4().hex}"
-
-
-#: OpenAI Realtime ``error.type`` for each internal error code.
-REALTIME_ERROR_TYPES_BY_CODE: dict[str, str] = {
-    "bad_event": "invalid_request_error",
-    "bad_audio": "invalid_request_error",
-    "config_timeout": "invalid_request_error",
-    "invalid_json": "invalid_request_error",
-    "event_too_large": "invalid_request_error",
-    "unknown_event": "invalid_request_error",
-    "internal_error": "server_error",
-    "runtime_append_failed": "server_error",
-    "runtime_append_task_failed": "server_error",
-    "runtime_signal_failed": "server_error",
-    "runtime_abort_failed": "server_error",
-    "runtime_data_plane_stream_failed": "server_error",
-    "runtime_data_plane_text_without_audio": "server_error",
-    "resource_exhausted": "rate_limit_error",
-    "session_exists": "invalid_request_error",
-    "session_closed": "invalid_request_error",
-    "unknown_session": "invalid_request_error",
-    "invalid_duplex_runtime_config": "invalid_request_error",
-    "instructions_update_unsupported": "invalid_request_error",
-    "persona_update_unsupported": "invalid_request_error",
-    "voice_update_unsupported": "invalid_request_error",
-    "unsupported_nemotron_duplex_mode": "invalid_request_error",
-    "unsupported_native_response_options": "invalid_request_error",
-    "runtime_touch_failed": "server_error",
-    "engine_error": "server_error",
-    "input_backpressure": "rate_limit_error",
-    "response_already_active": "invalid_request_error",
-    "response_not_active": "invalid_request_error",
-    "response_create_without_input": "invalid_request_error",
-    "text_only_turn_unsupported": "invalid_request_error",
-    "commit_aborted": "server_error",
-    "input_audio_buffer_empty": "invalid_request_error",
-    "missing_item_id": "invalid_request_error",
-    "item_not_found": "invalid_request_error",
-    "playback_item_mismatch": "invalid_request_error",
-    "playback_item_not_found": "invalid_request_error",
-    "playback_ack_too_late": "invalid_request_error",
-    "unsupported_audio_format": "invalid_request_error",
-    "unsupported_turn_detection": "invalid_request_error",
-    "unsupported_ref_audio_path": "invalid_request_error",
-    "ref_audio_required": "invalid_request_error",
-    "model_update_unsupported": "invalid_request_error",
-    "voice_update_after_audio_unsupported": "invalid_request_error",
-    "ref_audio_update_unsupported": "invalid_request_error",
-    "native_text_append_unsupported": "invalid_request_error",
-    "invalid_video_frames": "invalid_request_error",
-    "invalid_function_call_output": "invalid_request_error",
-    "server_vad_unavailable": "server_error",
-}
-
-_IDENTITY_FIELDS = frozenset({"session_id", "epoch", "event_id"})
-
-
-def _wire_value(value: object) -> object:
-    if isinstance(value, Mapping):
-        return {str(k): _wire_value(v) for k, v in value.items()}
-    if isinstance(value, tuple | list):
-        return [_wire_value(v) for v in value]
-    return value
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class DuplexEvent:
-    """Base of every public session event."""
-
-    #: Realtime ``type`` this class renders to.
-    wire_type: ClassVar[str] = ""
-    #: Fields that are omitted from the wire object when ``None``.
-    optional_wire_fields: ClassVar[frozenset[str]] = frozenset()
-
-    session_id: str = ""
-    epoch: int | None = None
-    #: Server event id (OpenAI ``event_id``); generated at construction.
-    event_id: str = field(default_factory=new_event_id)
-
-    # ---- identity ----
-
-    @property
-    def type(self) -> str:
-        return self.wire_type
-
-    @property
-    def is_terminal(self) -> bool:
-        return False
-
-    # ---- generic accessors (None when the class has no such field) ----
-
-    @property
-    def response_id(self) -> str | None:
-        return None
-
-    @property
-    def item_id(self) -> str | None:
-        return None
-
-    @property
-    def text(self) -> str | None:
-        return None
-
-    @property
-    def audio(self) -> bytes | None:
-        return None
-
-    # ---- wire rendering (pure) ----
-
-    def _wire_fields(self) -> dict[str, object]:
-        data: dict[str, object] = {}
-        for f in fields(self):
-            if f.name in _IDENTITY_FIELDS:
-                continue
-            value = getattr(self, f.name)
-            if value is None and f.name in self.optional_wire_fields:
-                continue
-            data[f.name] = _wire_value(value)
-        return data
-
-    def to_realtime(self) -> dict[str, object]:
-        """The Realtime wire JSON object for this event (derived from the fields)."""
-        return {"type": self.wire_type, "event_id": self.event_id, **self._wire_fields()}
-
-    def __repr__(self) -> str:  # pragma: no cover - debugging aid
-        return f"{type(self).__name__}(type={self.wire_type!r}, session_id={self.session_id!r}, epoch={self.epoch!r})"
-
-
-# ---- session lifecycle ----
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SessionCreated(DuplexEvent):
-    wire_type = "session.created"
-    optional_wire_fields = frozenset({"attachment_generation", "resume_token"})
-
-    session: Mapping[str, object] = field(default_factory=dict)
-    #: Transport resume credentials (set by the websocket handler when resume is supported).
-    attachment_generation: int | None = None
-    resume_token: str | None = None
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SessionUpdated(DuplexEvent):
-    wire_type = "session.updated"
-
-    session: Mapping[str, object] = field(default_factory=dict)
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SessionResumed(SessionCreated):
-    wire_type = "session.resumed"
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"session_id": self.session_id, **DuplexEvent._wire_fields(self)}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SessionReplaced(DuplexEvent):
-    """A newer connection took the session over (sent to the replaced socket)."""
-
-    wire_type = "session.replaced"
-
-    attachment_generation: int = 0
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"session_id": self.session_id, **DuplexEvent._wire_fields(self)}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SessionResyncRequired(DuplexEvent):
-    """The replay journal cannot bridge the gap; the client must start over."""
-
-    wire_type = "session.resync_required"
-
-    reason: str = "journal_gap"
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"session_id": self.session_id, **DuplexEvent._wire_fields(self)}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SessionClosed(DuplexEvent):
-    wire_type = "session.closed"
-
-    reason: str = "closed"
-    #: The session-internal close event (kept for clients that inspect it).
-    details: Mapping[str, object] = field(default_factory=dict)
-
-    @property
-    def is_terminal(self) -> bool:
-        return True
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"session_id": self.session_id, "reason": self.reason, "event": _wire_value(self.details)}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SessionExpired(SessionClosed):
-    wire_type = "session.expired"
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"session_id": self.session_id, "reason": self.reason}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SessionHeartbeatAck(DuplexEvent):
-    wire_type = "session.heartbeat_ack"
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"session_id": self.session_id}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class TurnEvent(DuplexEvent):
-    """Turn-state transition (``turn.event``)."""
-
-    wire_type = "turn.event"
-
-    event: str = ""
-    turn_state: str = ""
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"session_id": self.session_id, "event": self.event, "turn_state": self.turn_state, "epoch": self.epoch}
-
-
-# ---- response lifecycle ----
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class _ResponseEvent(DuplexEvent):
-    """Events addressed to one response (and usually one output item / content part)."""
-
-    response_id: str | None = None  # type: ignore[assignment]
-    item_id: str | None = None  # type: ignore[assignment]
-    output_index: int = 0
-    content_index: int = 0
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ResponseCreated(DuplexEvent):
-    wire_type = "response.created"
-
-    response_id: str | None = None  # type: ignore[assignment]
-    response: Mapping[str, object] = field(default_factory=dict)
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class Listen(DuplexEvent):
-    """The model decided to keep listening (no spoken response for this turn)."""
-
-    wire_type = "response.listen"
-    optional_wire_fields = frozenset({"response_id"})
-
-    response_id: str | None = None  # type: ignore[assignment]
-    details: Mapping[str, object] = field(default_factory=dict)
-
-    def _wire_fields(self) -> dict[str, object]:
-        response: dict[str, object] = {
-            "object": "realtime.response",
-            "status": "listening",
-            "metadata": _wire_value(self.details),
-        }
-        data: dict[str, object] = {"session_id": self.session_id, "epoch": self.epoch, "response": response}
-        if self.response_id:
-            response["id"] = self.response_id
-            data["response_id"] = self.response_id
-        return data
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class Speak(_ResponseEvent):
-    wire_type = "response.speak"
-
-    metadata: Mapping[str, object] = field(default_factory=dict)
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class OverlapDecision(DuplexEvent):
-    wire_type = "overlap.decision"
-
-    policy: str | None = None
-    action: str | None = None
-    reason: str | None = None
-    details: Mapping[str, object] = field(default_factory=dict)
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {
-            "session_id": self.session_id,
-            "epoch": self.epoch,
-            "policy": self.policy,
-            "action": self.action,
-            "reason": self.reason,
-            "metadata": _wire_value(self.details),
-        }
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class OutputItemAdded(DuplexEvent):
-    wire_type = "response.output_item.added"
-
-    response_id: str | None = None  # type: ignore[assignment]
-    output_index: int = 0
-    item: Mapping[str, object] = field(default_factory=dict)
-
-    @property
-    def item_id(self) -> str | None:
-        value = self.item.get("id")
-        return value if isinstance(value, str) else None
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class OutputItemDone(OutputItemAdded):
-    wire_type = "response.output_item.done"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ContentPartAdded(_ResponseEvent):
-    wire_type = "response.content_part.added"
-
-    part: Mapping[str, object] = field(default_factory=dict)
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ContentPartDone(ContentPartAdded):
-    wire_type = "response.content_part.done"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class AudioDelta(_ResponseEvent):
-    wire_type = "response.output_audio.delta"
-    optional_wire_fields = frozenset({"sample_rate_hz", "metadata"})
-
-    #: Base64 audio in ``format``.
-    delta: str = ""
-    format: str = "pcm16"
-    sample_rate_hz: int | None = None
-    metadata: Mapping[str, object] | None = None
-
-    @property
-    def audio(self) -> bytes | None:
-        try:
-            return base64.b64decode(self.delta)
-        except (ValueError, TypeError):
-            return None
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class AudioDone(_ResponseEvent):
-    wire_type = "response.output_audio.done"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class TranscriptDelta(_ResponseEvent):
-    wire_type = "response.output_audio_transcript.delta"
-
-    delta: str = ""
-
-    @property
-    def text(self) -> str | None:
-        return self.delta
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class TranscriptDone(_ResponseEvent):
-    wire_type = "response.output_audio_transcript.done"
-
-    transcript: str = ""
-
-    @property
-    def text(self) -> str | None:
-        return self.transcript
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class TextDelta(_ResponseEvent):
-    wire_type = "response.output_text.delta"
-
-    delta: str = ""
-
-    @property
-    def text(self) -> str | None:
-        return self.delta
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class TextDone(_ResponseEvent):
-    wire_type = "response.output_text.done"
-
-    text: str = ""  # type: ignore[assignment]
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class FunctionCallArgumentsDelta(DuplexEvent):
-    wire_type = "response.function_call_arguments.delta"
-
-    response_id: str | None = None  # type: ignore[assignment]
-    item_id: str | None = None  # type: ignore[assignment]
-    output_index: int = 0
-    call_id: str = ""
-    delta: str = ""
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class FunctionCallArgumentsDone(DuplexEvent):
-    wire_type = "response.function_call_arguments.done"
-
-    response_id: str | None = None  # type: ignore[assignment]
-    item_id: str | None = None  # type: ignore[assignment]
-    output_index: int = 0
-    call_id: str = ""
-    arguments: str = ""
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ResponseDone(DuplexEvent):
-    wire_type = "response.done"
-
-    response_id: str | None = None  # type: ignore[assignment]
-    response: Mapping[str, object] = field(default_factory=dict)
-
-    @property
-    def status(self) -> str | None:
-        value = self.response.get("status")
-        return value if isinstance(value, str) else None
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class RateLimitsUpdated(DuplexEvent):
-    wire_type = "rate_limits.updated"
-
-    rate_limits: tuple[Mapping[str, object], ...] = ()
-
-
-# ---- input buffer / conversation ----
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class InputCommitted(DuplexEvent):
-    wire_type = "input_audio_buffer.committed"
-
-    previous_item_id: str | None = None
-    item_id: str | None = None  # type: ignore[assignment]
-    #: The session-internal ``input.committed`` event.
-    details: Mapping[str, object] = field(default_factory=dict)
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {
-            "previous_item_id": self.previous_item_id,
-            "item_id": self.item_id,
-            "event": _wire_value(self.details),
-        }
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class InputCleared(DuplexEvent):
-    wire_type = "input_audio_buffer.cleared"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SpeechStarted(DuplexEvent):
-    wire_type = "input_audio_buffer.speech_started"
-
-    audio_start_ms: int = 0
-    item_id: str | None = None  # type: ignore[assignment]
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class SpeechStopped(DuplexEvent):
-    wire_type = "input_audio_buffer.speech_stopped"
-
-    audio_end_ms: int = 0
-    item_id: str | None = None  # type: ignore[assignment]
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class _ItemEvent(DuplexEvent):
-    previous_item_id: str | None = None
-    item: Mapping[str, object] = field(default_factory=dict)
-
-    @property
-    def item_id(self) -> str | None:
-        value = self.item.get("id")
-        return value if isinstance(value, str) else None
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ItemAdded(_ItemEvent):
-    wire_type = "conversation.item.added"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ItemCreated(_ItemEvent):
-    wire_type = "conversation.item.created"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ItemDone(_ItemEvent):
-    wire_type = "conversation.item.done"
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ItemRetrieved(DuplexEvent):
-    wire_type = "conversation.item.retrieved"
-
-    item: Mapping[str, object] = field(default_factory=dict)
-
-    @property
-    def item_id(self) -> str | None:
-        value = self.item.get("id")
-        return value if isinstance(value, str) else None
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ItemDeleted(DuplexEvent):
-    wire_type = "conversation.item.deleted"
-
-    item_id: str | None = None  # type: ignore[assignment]
-    details: Mapping[str, object] = field(default_factory=dict)
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"item_id": self.item_id, "event": _wire_value(self.details)}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ItemTruncated(DuplexEvent):
-    wire_type = "conversation.item.truncated"
-
-    item_id: str | None = None  # type: ignore[assignment]
-    content_index: int = 0
-    audio_end_ms: int = 0
-    details: Mapping[str, object] = field(default_factory=dict)
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {
-            "item_id": self.item_id,
-            "content_index": self.content_index,
-            "audio_end_ms": self.audio_end_ms,
-            "event": _wire_value(self.details),
-        }
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class InputTranscriptionCompleted(DuplexEvent):
-    wire_type = "conversation.item.input_audio_transcription.completed"
-
-    item_id: str | None = None  # type: ignore[assignment]
-    content_index: int = 0
-    transcript: str = ""
-
-    @property
-    def text(self) -> str | None:
-        return self.transcript
-
-
-# ---- playback / control ----
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class OutputAudioCleared(DuplexEvent):
-    wire_type = "output_audio_buffer.cleared"
-
-    response_id: str | None = None  # type: ignore[assignment]
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class PlaybackAcknowledged(DuplexEvent):
-    wire_type = "playback.acknowledged"
-
-    #: The session-internal ``playback.acknowledged`` event (cursor, committed_ms ...).
-    details: Mapping[str, object] = field(default_factory=dict)
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"event": _wire_value(self.details)}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class ErrorEvent(DuplexEvent):
-    wire_type = "error"
-
-    code: str = "internal_error"
-    message: str = ""
-    #: Client ``event_id`` this error answers (OpenAI ``error.event_id``).
-    related_event_id: str | None = None
-    param: str | None = None
-    #: Extra keys merged into the wire ``error`` object (``retryable`` ...).
-    extra: Mapping[str, object] = field(default_factory=dict)
-
-    @property
-    def error_type(self) -> str:
-        return REALTIME_ERROR_TYPES_BY_CODE.get(self.code, "invalid_request_error")
-
-    @property
-    def error(self) -> dict[str, object]:
-        error: dict[str, object] = {"type": self.error_type, "code": self.code, "message": self.message}
-        if self.related_event_id:
-            error["event_id"] = self.related_event_id
-        if self.param:
-            error["param"] = self.param
-        error.update(cast("Mapping[str, object]", _wire_value(self.extra)))
-        return error
-
-    @property
-    def text(self) -> str | None:
-        return self.message
-
-    def _wire_fields(self) -> dict[str, object]:
-        return {"error": self.error}
-
-
-@dataclass(frozen=True, slots=True, kw_only=True)
-class DuplexRawEvent(DuplexEvent):
-    """A session-internal event with no dedicated Realtime type (``duplex.<internal type>``)."""
-
-    wire_type = "duplex.raw"
-
-    internal_type: str = ""
-    details: Mapping[str, object] = field(default_factory=dict)
-
-    @property
-    def type(self) -> str:
-        return f"duplex.{self.internal_type}"
-
-    def to_realtime(self) -> dict[str, object]:
-        return {"type": self.type, "event_id": self.event_id, "event": _wire_value(self.details)}
-
-
-def error_event(
-    code: str,
-    message: str,
-    *,
-    event_id: object | None = None,
-    param: object | None = None,
-    extra: Mapping[str, object] | None = None,
-) -> ErrorEvent:
-    """Build the error event for an internal code; ``event_id`` is the *client* event id."""
-    return ErrorEvent(
-        code=code,
-        message=message,
-        related_event_id=event_id if isinstance(event_id, str) and event_id else None,
-        param=param if isinstance(param, str) and param else None,
-        extra=dict(extra or {}),
-    )
-
+from vllm_omni.protocol.duplex.errors import REALTIME_ERROR_TYPES_BY_CODE
+from vllm_omni.protocol.duplex.events import (
+    AudioDelta,
+    AudioDone,
+    ContentPartAdded,
+    ContentPartDone,
+    DuplexEvent,
+    DuplexRawEvent,
+    ErrorEvent,
+    FunctionCallArgumentsDelta,
+    FunctionCallArgumentsDone,
+    InputCleared,
+    InputCommitted,
+    InputTranscriptionCompleted,
+    ItemAdded,
+    ItemCreated,
+    ItemDeleted,
+    ItemDone,
+    ItemRetrieved,
+    ItemTruncated,
+    Listen,
+    OutputAudioCleared,
+    OutputItemAdded,
+    OutputItemDone,
+    OverlapDecision,
+    PlaybackAcknowledged,
+    RateLimitsUpdated,
+    ResponseCreated,
+    ResponseDone,
+    SessionClosed,
+    SessionCreated,
+    SessionExpired,
+    SessionHeartbeatAck,
+    SessionReplaced,
+    SessionResumed,
+    SessionResyncRequired,
+    SessionUpdated,
+    Speak,
+    SpeechStarted,
+    SpeechStopped,
+    TextDelta,
+    TextDone,
+    TranscriptDelta,
+    TranscriptDone,
+    TurnEvent,
+    error_event,
+    new_event_id,
+)
 
-#: Internal events that terminate a response/session and must never be dropped as stale.
 DOMAIN_TERMINAL_EVENTS = frozenset(
     {
         "response.done",
@@ -682,7 +84,6 @@ def error_event(
     }
 )
 
-#: Internal streaming model-output events subject to epoch/close stale filtering.
 MODEL_OUTPUT_EVENTS = frozenset(
     {
         "response.created",
@@ -705,13 +106,11 @@ def error_event(
 
 
 __all__ = [
-    "DOMAIN_TERMINAL_EVENTS",
-    "MODEL_OUTPUT_EVENTS",
-    "REALTIME_ERROR_TYPES_BY_CODE",
     "AudioDelta",
     "AudioDone",
     "ContentPartAdded",
     "ContentPartDone",
+    "DOMAIN_TERMINAL_EVENTS",
     "DuplexEvent",
     "DuplexRawEvent",
     "ErrorEvent",
@@ -727,11 +126,13 @@ def error_event(
     "ItemRetrieved",
     "ItemTruncated",
     "Listen",
+    "MODEL_OUTPUT_EVENTS",
     "OutputAudioCleared",
     "OutputItemAdded",
     "OutputItemDone",
     "OverlapDecision",
     "PlaybackAcknowledged",
+    "REALTIME_ERROR_TYPES_BY_CODE",
     "RateLimitsUpdated",
     "ResponseCreated",
     "ResponseDone",
diff --git a/vllm_omni/engine/duplex/realtime_commands.py b/vllm_omni/engine/duplex/realtime_commands.py
index 37036401779..31b1c0949f2 100644
--- a/vllm_omni/engine/duplex/realtime_commands.py
+++ b/vllm_omni/engine/duplex/realtime_commands.py
@@ -3,26 +3,31 @@
 
 """OpenAI Realtime client events -> :class:`DuplexCommand` (stateless).
 
-This is the mapping half of the former ``entrypoints/duplex/realtime_input.py``
-translator. Everything that needed per-session state in the old translator
-(input-buffer emptiness for commits, response-id fallbacks for cancels,
-conversation-item lookups, VAD) is resolved by the session runner through the
-helpers on :class:`~vllm_omni.engine.duplex.realtime_events.RealtimeProjectionState`;
+This module is the *duplex binding* of the shared Realtime codec. Parsing,
+validating and decoding a client event is not duplex-specific and lives in
+``vllm_omni.protocol.realtime``, reached through ``vllm_omni.protocol.duplex``;
+what lives here is the part that is: which
+:class:`~vllm_omni.engine.duplex.commands.DuplexCommand` a decoded event
+becomes, what the duplex engine can serve
+(:data:`DUPLEX_REALTIME_CAPABILITIES`), and the mapping between a Realtime
+output format and the duplex ``response_format`` vocabulary.
+
+Everything that needs per-session state (input-buffer emptiness for commits,
+response-id fallbacks for cancels, conversation-item lookups, VAD) is resolved
+by the session runner through the helpers on
+:class:`~vllm_omni.engine.duplex.realtime_events.RealtimeProjectionState`;
 the commands produced here carry the raw client intent only.
+
+The shared names re-exported at the bottom are a compatibility surface for
+existing importers. The canonical definitions are in
+``vllm_omni.protocol.realtime`` and there is exactly one of each.
 """
 
 from __future__ import annotations
 
-import base64
-import binascii
 from collections.abc import Mapping
-from dataclasses import dataclass, replace
-from typing import Any, cast
-from uuid import uuid4
-
-import numpy as np
+from typing import cast
 
-from vllm_omni.engine.duplex.audio import convert_input_audio_with_rate
 from vllm_omni.engine.duplex.commands import (
     AckPlayback,
     AppendAudio,
@@ -44,93 +49,58 @@
     TruncateItem,
     UpdateSession,
 )
-
-REALTIME_INPUT_AUDIO_FORMATS = {
-    "pcm16",
-    "pcm_s16le",
-    "s16le",
-    "pcm_f32le",
-    "g711_ulaw",
-    "g711_alaw",
-}
-REALTIME_OUTPUT_AUDIO_FORMATS = {
-    "pcm16",
-    "pcm_s16le",
-    "s16le",
-    "wav",
-    "pcm",
-    "g711_ulaw",
-    "g711_alaw",
-}
-
-#: Wire hint keys copied verbatim from a client append onto the internal payload.
-REALTIME_INPUT_HINT_KEYS = (
-    "duration_ms",
-    "audio_duration_ms",
-    "audio_start_ms",
-    "audio_end_ms",
-    "is_speech",
-    "speech",
-    "speech_probability",
-    "vad",
-    "overlap_action",
-    "overlap",
-    "force_barge_in",
-    "force_listen",
-    "text",
-    "transcript",
+from vllm_omni.protocol.duplex import (
+    REALTIME_INPUT_AUDIO_FORMATS,
+    REALTIME_INPUT_HINT_KEYS,
+    REALTIME_OUTPUT_AUDIO_FORMATS,
+    RealtimeInputDefaults,
+    RealtimeProtocolCapabilities,
+    RealtimeProtocolError,
+    apply_realtime_session_defaults,
+    copy_realtime_input_hints,
+    decode_audio_append,
+    input_audio_transcription_config,
+    input_explicitly_non_speech,
+    input_looks_like_speech,
+    input_transcript_from_item,
+    is_supported_realtime_input_format,
+    json_safe_realtime_payload,
+    normalize_conversation_item,
+    parse_realtime_audio_format,
+    realtime_audio_format_object,
+    realtime_max_output_tokens,
+    realtime_output_format,
+    realtime_overlap_fields,
+    text_chars_for_audio_ms_from_marks,
+    truncate_realtime_item_content,
+    validate_conversation_item_audio_formats,
+    validate_realtime_item_truncate,
+    validate_realtime_response_audio_formats,
+    validate_realtime_session_audio_formats,
+    validate_realtime_video_frames,
+    validate_session_payload,
 )
 
 
-@dataclass(frozen=True, slots=True)
-class RealtimeInputDefaults:
-    """Session-level wire defaults an append may omit (derived from the session object)."""
-
-    input_audio_format: str = "pcm16"
-    input_sample_rate_hz: int = 16000
-    output_audio_format: str = "pcm16"
-    output_sample_rate_hz: int | None = None
-    overlap_silence_rms: float = 0.003
-
-    def with_session_payload(self, session_payload: Mapping[str, object]) -> RealtimeInputDefaults:
-        """Return defaults updated from a Realtime ``session`` object (session.update)."""
-        values = apply_realtime_session_defaults(self, session_payload)
-        return values
-
-
-# ---- audio format helpers ----
-
-
-def parse_realtime_audio_format(raw_format: object) -> tuple[object, int | None]:
-    def normalize_format(fmt: str) -> str:
-        normalized = fmt.lower()
-        if normalized in {"audio/pcm", "pcm"}:
-            return "pcm16"
-        if normalized in {"audio/wav", "wav"}:
-            return "wav"
-        if normalized in {"audio/pcm16", "pcm16", "pcm_s16le", "s16le"}:
-            return "pcm16"
-        if normalized in {"audio/pcm_f32le", "pcm_f32le", "f32le"}:
-            return "pcm_f32le"
-        if normalized in {"audio/g711_ulaw", "g711_ulaw", "g711-ulaw", "ulaw", "mulaw"}:
-            return "g711_ulaw"
-        if normalized in {"audio/g711_alaw", "g711_alaw", "g711-alaw", "alaw"}:
-            return "g711_alaw"
-        return fmt
-
-    if isinstance(raw_format, str):
-        return normalize_format(raw_format), None
-    if not isinstance(raw_format, dict):
-        return raw_format, None
-    rate = raw_format.get("rate") or raw_format.get("sample_rate_hz") or raw_format.get("sample_rate")
-    sample_rate_hz = int(rate) if isinstance(rate, int | float) and rate > 0 else None
-    fmt = raw_format.get("type") or raw_format.get("format")
-    if not isinstance(fmt, str):
-        return raw_format, sample_rate_hz
-    return normalize_format(fmt), sample_rate_hz
+def _validate_duplex_turn_detection(session_payload: Mapping[str, object]) -> str | None:
+    """The duplex engine's answer for ``turn_detection`` on a session object.
+
+    Imported lazily: the validator lives with the Silero VAD backend, and a
+    connection that never sends a session object should not pay for loading it.
+    """
+    from vllm_omni.engine.duplex.turn_detection import validate_realtime_turn_detection
+
+    return validate_realtime_turn_detection(session_payload)
+
+
+#: What the duplex engine can serve, for the shared session-object validator.
+DUPLEX_REALTIME_CAPABILITIES = RealtimeProtocolCapabilities(
+    validate_turn_detection=_validate_duplex_turn_detection,
+)
 
 
 def duplex_response_format(realtime_format: str) -> str:
+    """A Realtime output format -> the duplex ``response_format`` vocabulary."""
     normalized = realtime_format.lower()
     if normalized in {"pcm16", "pcm_s16le", "s16le"}:
         return "pcm"
@@ -141,433 +111,6 @@ def duplex_response_format(realtime_format: str) -> str:
     return "wav"
 
 
-def realtime_output_format(duplex_format: object) -> str:
-    if isinstance(duplex_format, str) and duplex_format.lower() in {"g711_ulaw", "g711_alaw"}:
-        return duplex_format.lower()
-    if isinstance(duplex_format, str) and duplex_format.lower() == "pcm":
-        return "pcm16"
-    return str(duplex_format or "wav")
-
-
-def is_supported_realtime_input_format(fmt: object) -> bool:
-    return isinstance(fmt, str) and fmt.lower() in REALTIME_INPUT_AUDIO_FORMATS
-
-
-def realtime_audio_format_object(fmt: object, *, sample_rate_hz: int | None = None) -> dict[str, object]:
-    if isinstance(fmt, str) and fmt.lower() in {"pcm16", "pcm_s16le", "s16le", "pcm"}:
-        payload: dict[str, object] = {"type": "audio/pcm"}
-    elif isinstance(fmt, str) and fmt.lower() == "pcm_f32le":
-        payload = {"type": "audio/pcm_f32le"}
-    elif isinstance(fmt, str) and fmt.lower() == "g711_ulaw":
-        payload = {"type": "audio/g711_ulaw"}
-    elif isinstance(fmt, str) and fmt.lower() == "g711_alaw":
-        payload = {"type": "audio/g711_alaw"}
-    else:
-        payload = {"type": "audio/wav"}
-    if sample_rate_hz is not None:
-        payload["rate"] = int(sample_rate_hz)
-    return payload
-
-
-def validate_realtime_session_audio_formats(session_payload: Mapping[str, object]) -> str | None:
-    audio_config = session_payload.get("audio")
-    input_format: object = session_payload.get("input_audio_format")
-    if input_format is None and isinstance(audio_config, dict):
-        audio_input = audio_config.get("input")
-        if isinstance(audio_input, dict):
-            input_format = audio_input.get("format")
-    parsed_input, _ = parse_realtime_audio_format(input_format)
-    if input_format is not None and not (
-        isinstance(parsed_input, str) and parsed_input.lower() in REALTIME_INPUT_AUDIO_FORMATS
-    ):
-        return f"Unsupported input_audio_format: {input_format}"
-
-    output_format: object = session_payload.get("output_audio_format") or session_payload.get("response_format")
-    if output_format is None and isinstance(audio_config, dict):
-        audio_output = audio_config.get("output")
-        if isinstance(audio_output, dict):
-            output_format = audio_output.get("format")
-    parsed_output, _ = parse_realtime_audio_format(output_format)
-    if output_format is not None and not (
-        isinstance(parsed_output, str) and parsed_output.lower() in REALTIME_OUTPUT_AUDIO_FORMATS
-    ):
-        return f"Unsupported output_audio_format: {output_format}"
-    return None
-
-
-def validate_realtime_response_audio_formats(response_payload: Mapping[str, object]) -> str | None:
-    output_format: object = response_payload.get("output_audio_format") or response_payload.get("response_format")
-    audio_config = response_payload.get("audio")
-    if output_format is None and isinstance(audio_config, dict):
-        audio_output = audio_config.get("output")
-        if isinstance(audio_output, dict):
-            output_format = audio_output.get("format")
-    parsed_output, _ = parse_realtime_audio_format(output_format)
-    if output_format is not None and not (
-        isinstance(parsed_output, str) and parsed_output.lower() in REALTIME_OUTPUT_AUDIO_FORMATS
-    ):
-        return f"Unsupported output_audio_format: {output_format}"
-    return None
-
-
-def validate_conversation_item_audio_formats(item: object) -> str | None:
-    if not isinstance(item, dict):
-        return None
-    content = item.get("content")
-    if not isinstance(content, list):
-        return None
-    for part in content:
-        if not isinstance(part, dict):
-            continue
-        if part.get("type") not in {"input_audio", "audio"}:
-            continue
-        raw_format = part.get("format")
-        parsed_format, _ = parse_realtime_audio_format(raw_format)
-        if raw_format is not None and not (
-            isinstance(parsed_format, str) and parsed_format.lower() in REALTIME_INPUT_AUDIO_FORMATS
-        ):
-            return f"Unsupported input_audio format in conversation.item.create: {raw_format}"
-    return None
-
-
-def apply_realtime_session_defaults(
-    defaults: RealtimeInputDefaults,
-    session_payload: Mapping[str, object],
-) -> RealtimeInputDefaults:
-    """Derive the wire defaults a Realtime ``session`` object declares."""
-    input_format: object = session_payload.get("input_audio_format")
-    audio_config = session_payload.get("audio")
-    if input_format is None and isinstance(audio_config, dict):
-        audio_input = audio_config.get("input")
-        if isinstance(audio_input, dict):
-            input_format = audio_input.get("format")
-    input_format, input_rate = parse_realtime_audio_format(input_format)
-    # Any: heterogeneous field values splatted into ``dataclasses.replace`` below.
-    updates: dict[str, Any] = {}
-    if isinstance(input_format, str) and input_format.lower() in REALTIME_INPUT_AUDIO_FORMATS:
-        updates["input_audio_format"] = input_format
-    output_format: object = session_payload.get("output_audio_format") or session_payload.get("response_format")
-    output_rate_raw: object | None = None
-    if output_format is None and isinstance(audio_config, dict):
-        audio_output = audio_config.get("output")
-        if isinstance(audio_output, dict):
-            output_format = audio_output.get("format")
-            output_rate_raw = audio_output.get("sample_rate_hz") or audio_output.get("sample_rate")
-    output_format, output_rate = parse_realtime_audio_format(output_format)
-    if output_rate is None and isinstance(output_rate_raw, int | float) and output_rate_raw > 0:
-        output_rate = int(output_rate_raw)
-    if isinstance(output_format, str) and output_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
-        updates["output_audio_format"] = realtime_output_format(output_format)
-    sample_rate = session_payload.get("sample_rate_hz") or session_payload.get("sample_rate")
-    if sample_rate is None and isinstance(audio_config, dict):
-        audio_input = audio_config.get("input")
-        if isinstance(audio_input, dict):
-            sample_rate = audio_input.get("sample_rate_hz") or audio_input.get("sample_rate")
-    if sample_rate is None:
-        sample_rate = input_rate
-    if isinstance(sample_rate, int | float) and sample_rate > 0:
-        updates["input_sample_rate_hz"] = int(sample_rate)
-    if isinstance(output_rate, int | float) and output_rate > 0:
-        updates["output_sample_rate_hz"] = int(output_rate)
-    overlap_fields = realtime_overlap_fields(session_payload)
-    overlap_silence_rms = overlap_fields.get("overlap_silence_rms")
-    if isinstance(overlap_silence_rms, int | float):
-        updates["overlap_silence_rms"] = max(0.0, float(overlap_silence_rms))
-    return replace(defaults, **updates) if updates else defaults
-
-
-def realtime_overlap_fields(session_payload: Mapping[str, object]) -> dict[str, object]:
-    fields: dict[str, object] = {}
-    if isinstance(session_payload.get("overlap_policy"), str):
-        fields["overlap_policy"] = session_payload["overlap_policy"]
-    for key in ("overlap_short_ack_ms", "overlap_barge_in_ms", "overlap_silence_rms"):
-        value = session_payload.get(key)
-        if isinstance(value, int | float):
-            fields[key] = value
-    if isinstance(session_payload.get("playback_commit_policy"), str):
-        fields["playback_commit_policy"] = session_payload["playback_commit_policy"]
-    return fields
-
-
-def json_safe_realtime_payload(payload: Mapping[str, object]) -> dict[str, object]:
-    clean: dict[str, object] = {}
-    for key, value in payload.items():
-        if key == "extra_body":
-            continue
-        if isinstance(value, str | int | float | bool) or value is None:
-            clean[key] = value
-        elif isinstance(value, dict):
-            clean[key] = json_safe_realtime_payload(value)
-        elif isinstance(value, list):
-            clean[key] = [
-                (json_safe_realtime_payload(item) if isinstance(item, dict) else item)
-                for item in value
-                if isinstance(item, str | int | float | bool | dict) or item is None
-            ]
-    return clean
-
-
-def input_audio_transcription_config(session_payload: Mapping[str, object]) -> dict[str, object] | None:
-    transcription = session_payload.get("input_audio_transcription")
-    if isinstance(transcription, dict):
-        return transcription
-    audio_config = session_payload.get("audio")
-    if not isinstance(audio_config, dict):
-        return None
-    audio_input = audio_config.get("input")
-    if not isinstance(audio_input, dict):
-        return None
-    transcription = audio_input.get("transcription")
-    return transcription if isinstance(transcription, dict) else None
-
-
-def realtime_max_output_tokens(value: object) -> int | None:
-    """Normalize Realtime max output tokens (``"inf"`` -> ``None``)."""
-    if value is None:
-        return None
-    if isinstance(value, str) and value.strip().lower() in {"inf", "infinity", "unlimited"}:
-        return None
-    if isinstance(value, int) and value > 0:
-        return int(value)
-    return None
-
-
-# ---- speech hints ----
-
-
-def input_explicitly_non_speech(event: Mapping[str, object]) -> bool:
-    for key in ("is_speech", "speech"):
-        value = event.get(key)
-        if isinstance(value, bool):
-            return not value
-    vad = event.get("vad")
-    if isinstance(vad, dict):
-        value = vad.get("is_speech")
-        if isinstance(value, bool):
-            return not value
-        probability = vad.get("speech_probability", vad.get("probability"))
-        if isinstance(probability, int | float):
-            return float(probability) < 0.5
-    probability = event.get("speech_probability")
-    return isinstance(probability, int | float) and float(probability) < 0.5
-
-
-def input_looks_like_speech(
-    event: Mapping[str, object],
-    *,
-    audio: object,
-    fmt: object,
-    overlap_silence_rms: float,
-) -> bool:
-    if input_explicitly_non_speech(event):
-        return False
-    for key in ("is_speech", "speech"):
-        value = event.get(key)
-        if isinstance(value, bool):
-            return value
-    vad = event.get("vad")
-    if isinstance(vad, dict):
-        probability = vad.get("speech_probability", vad.get("probability"))
-        if isinstance(probability, int | float):
-            return float(probability) >= 0.5
-    probability = event.get("speech_probability")
-    if isinstance(probability, int | float):
-        return float(probability) >= 0.5
-    if fmt != "pcm_f32le":
-        return True
-    if isinstance(audio, bytes | bytearray):
-        raw = bytes(audio)
-    elif isinstance(audio, str):
-        try:
-            raw = base64.b64decode(audio, validate=True)
-        except (binascii.Error, ValueError):
-            return True
-    else:
-        return True
-    if len(raw) < 4 or len(raw) % 4 != 0:
-        return True
-    samples = np.frombuffer(raw, dtype=np.float32)
-    if samples.size == 0:
-        return False
-    rms = float(np.sqrt(np.mean(np.square(samples.astype(np.float32)))))
-    threshold = event.get("overlap_silence_rms")
-    if not isinstance(threshold, int | float):
-        vad = event.get("vad")
-        if isinstance(vad, dict):
-            threshold = vad.get("silence_rms")
-    silence_rms = float(threshold) if isinstance(threshold, int | float) else overlap_silence_rms
-    return rms >= max(0.0, silence_rms)
-
-
-def copy_realtime_input_hints(source: Mapping[str, object], target: dict[str, object]) -> None:
-    for key in REALTIME_INPUT_HINT_KEYS:
-        if key in source:
-            target[key] = source[key]
-
-
-def validate_realtime_video_frames(video_frames: object, max_slice_nums: object) -> str | None:
-    """Validate omni-duplex camera frames on input_audio_buffer.append.
-
-    Wire contract matches the official MiniCPM-o duplex loop: one base
-    base64 JPEG per ~1 s audio chunk, optionally followed by that unit's
-    stacked composite tiling the sub-frames captured inside it (at most 2
-    images either way). A caller-supplied ``max_slice_nums`` is rejected rather
-    than silently ignored: slicing is Stage 0's decision here, and Stage 0
-    already applies the official HD suggestion for a stacked unit
-    (``max_slice_nums=[2, 1]``). The wire simply does not let the client choose
-    it.
-    """
-    if max_slice_nums not in (None, 1):
-        return "max_slice_nums is not selectable on the wire; Stage0 slices stacked units itself"
-    if not isinstance(video_frames, list):
-        return "video_frames must be a list of base64-encoded images"
-    frames = [frame for frame in video_frames if frame is not None]
-    if len(frames) > 2:
-        return "video_frames carries more than 2 frames for one append; send ~1 frame per 1 s chunk"
-    for frame in frames:
-        if not isinstance(frame, str) or not frame:
-            return "video_frames entries must be non-empty base64 strings"
-        if len(frame) > 4_000_000:
-            return "video_frames entry exceeds 4MB base64; reduce capture resolution or JPEG quality"
-        try:
-            header = base64.b64decode(frame[:64] + "=" * (-len(frame[:64]) % 4))
-        except (binascii.Error, ValueError):
-            return "video_frames entries must be valid base64"
-        if not (header.startswith(b"\xff\xd8") or header.startswith(b"\x89PNG")):
-            return "video_frames entries must be JPEG or PNG images"
-    return None
-
-
-# ---- conversation items ----
-
-
-def normalize_conversation_item(item: Mapping[str, object]) -> dict[str, object]:
-    normalized = dict(item)
-    normalized.setdefault("id", f"item_{uuid4().hex}")
-    normalized.setdefault("object", "realtime.item")
-    normalized.setdefault("type", "message")
-    normalized.setdefault("status", "completed")
-    if "role" not in normalized and normalized.get("type") == "message":
-        normalized["role"] = "user"
-    if not isinstance(normalized.get("content"), list):
-        normalized["content"] = []
-    return normalized
-
-
-def text_chars_for_audio_ms_from_marks(
-    audio_end_ms: int,
-    text_len: int,
-    marks: list[object],
-    *,
-    final_ms: object | None = None,
-) -> int:
-    if text_len <= 0:
-        return 0
-    clean_marks: list[tuple[int, int]] = []
-    for mark in marks:
-        if not isinstance(mark, dict):
-            continue
-        raw_text_chars = mark.get("text_chars")
-        raw_audio_end_ms = mark.get("audio_end_ms", mark.get("audio_ms"))
-        if not isinstance(raw_text_chars, int | float) or not isinstance(raw_audio_end_ms, int | float):
-            continue
-        clean_marks.append((max(0, int(raw_audio_end_ms)), min(text_len, max(0, int(raw_text_chars)))))
-    if not clean_marks:
-        return 0 if audio_end_ms <= 0 else text_len
-    clean_marks.sort(key=lambda item: item[0])
-    audio_end_ms = max(0, int(audio_end_ms))
-    if audio_end_ms <= 0:
-        return 0
-    previous_ms = 0
-    previous_chars = 0
-    for mark_ms, mark_chars in clean_marks:
-        mark_ms = max(previous_ms, mark_ms)
-        mark_chars = max(previous_chars, min(text_len, mark_chars))
-        if audio_end_ms <= mark_ms:
-            if mark_ms <= previous_ms:
-                return mark_chars
-            ratio = (audio_end_ms - previous_ms) / max(1, mark_ms - previous_ms)
-            return int(previous_chars + (mark_chars - previous_chars) * max(0.0, min(1.0, ratio)))
-        previous_ms = mark_ms
-        previous_chars = mark_chars
-    if isinstance(final_ms, int | float) and int(final_ms) > previous_ms:
-        if audio_end_ms >= int(final_ms):
-            return text_len
-        ratio = (audio_end_ms - previous_ms) / max(1, int(final_ms) - previous_ms)
-        return int(previous_chars + (text_len - previous_chars) * max(0.0, min(1.0, ratio)))
-    return text_len if audio_end_ms >= previous_ms else previous_chars
-
-
-def truncate_realtime_item_content(item: dict[str, object], *, content_index: int, audio_end_ms: int) -> None:
-    content = item.get("content")
-    if not isinstance(content, list) or not content:
-        return
-    index = max(0, int(content_index))
-    if index >= len(content):
-        return
-    part = content[index]
-    if not isinstance(part, dict):
-        return
-    transcript = part.get("transcript")
-    if not isinstance(transcript, str) or not transcript:
-        return
-    marks = part.get("audio_text_marks")
-    if isinstance(marks, list):
-        keep_chars = text_chars_for_audio_ms_from_marks(
-            audio_end_ms,
-            len(transcript),
-            marks,
-            final_ms=part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms"),
-        )
-        part["transcript"] = transcript[:keep_chars].rstrip()
-        return
-    duration_ms = part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms")
-    if isinstance(duration_ms, int | float) and duration_ms > 0:
-        keep_chars = int(len(transcript) * max(0.0, min(1.0, int(audio_end_ms) / float(duration_ms))))
-        part["transcript"] = transcript[:keep_chars].rstrip()
-    elif audio_end_ms <= 0:
-        part["transcript"] = ""
-
-
-def validate_realtime_item_truncate(item: Mapping[str, object], *, content_index: int, audio_end_ms: int) -> str | None:
-    if item.get("type") != "message" or item.get("role") != "assistant":
-        return "conversation.item.truncate only supports assistant message items"
-    if audio_end_ms < 0:
-        return "conversation.item.truncate requires non-negative audio_end_ms"
-    content = item.get("content")
-    if not isinstance(content, list) or not content:
-        return None
-    index = max(0, int(content_index))
-    if index >= len(content):
-        return f"conversation.item.truncate content_index out of range: {content_index}"
-    part = content[index]
-    if not isinstance(part, dict):
-        return "conversation.item.truncate target content part is invalid"
-    if part.get("type") not in {"audio", "output_audio"}:
-        return "conversation.item.truncate target content part must be audio"
-    duration_ms = part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms")
-    if isinstance(duration_ms, int | float) and int(duration_ms) >= 0 and audio_end_ms > int(duration_ms):
-        return "conversation.item.truncate audio_end_ms exceeds item audio duration"
-    return None
-
-
-def input_transcript_from_item(item: Mapping[str, object]) -> str:
-    content = item.get("content")
-    if not isinstance(content, list):
-        return ""
-    parts: list[str] = []
-    for part in content:
-        if not isinstance(part, dict):
-            continue
-        for key in ("transcript", "text"):
-            value = part.get(key)
-            if isinstance(value, str) and value:
-                if part.get("type") in {"input_audio", "audio", "audio_transcript", "transcript"}:
-                    parts.append(value)
-                    break
-    return "".join(parts).strip()
-
-
 # ---- append / item audio conversion ----
 
 
@@ -577,67 +120,21 @@ def build_append_audio(
     defaults: RealtimeInputDefaults,
     hints_source: Mapping[str, object] | None = None,
 ) -> AppendAudio:
-    """Validate, convert (to 16 kHz ``pcm_f32le`` base64) and pack one audio append.
-
-    Speech classification without VAD (``is_speech`` on the command) uses the
-    explicit wire hints and the RMS fallback exactly like the old translator.
-    """
-    event_id = cast("str", event.get("event_id")) if isinstance(event.get("event_id"), str) else None
-    audio = event.get("audio") or event.get("delta")
-    fmt, format_rate = parse_realtime_audio_format(
-        event.get("format") or event.get("input_audio_format") or defaults.input_audio_format
-    )
-    sample_rate_hz = (
-        event.get("sample_rate_hz") or event.get("sample_rate") or format_rate or defaults.input_sample_rate_hz
-    )
-    if not is_supported_realtime_input_format(fmt):
-        raise DuplexCommandError(
-            f"Unsupported input_audio_format: {fmt}",
-            code="unsupported_audio_format",
-            event_id=event_id,
-        )
-    try:
-        audio, fmt, sample_rate_hz = convert_input_audio_with_rate(
-            audio,
-            fmt,
-            sample_rate_hz=sample_rate_hz if isinstance(sample_rate_hz, int | float) else None,
-        )
-    except ValueError as exc:
-        raise DuplexCommandError(str(exc), code="bad_event", event_id=event_id) from exc
-    hints: dict[str, object] = {}
-    if hints_source is not None:
-        copy_realtime_input_hints(hints_source, hints)
-    copy_realtime_input_hints(event, hints)
-    looks_like_speech = input_looks_like_speech(
-        {**(hints_source or {}), **event},
-        audio=audio,
-        fmt=fmt,
-        overlap_silence_rms=defaults.overlap_silence_rms,
-    )
-    video_frames: tuple[str, ...] = ()
-    raw_frames = event.get("video_frames")
-    if raw_frames is not None:
-        frames_error = validate_realtime_video_frames(raw_frames, event.get("max_slice_nums"))
-        if frames_error is not None:
-            raise DuplexCommandError(frames_error, code="invalid_video_frames", event_id=event_id)
-        if isinstance(raw_frames, list):
-            video_frames = tuple(frame for frame in raw_frames if isinstance(frame, str) and frame)
-    duration_ms = hints.get("duration_ms", hints.get("audio_duration_ms"))
-    audio_end_ms = hints.get("audio_end_ms")
+    """Decode one audio append (shared codec) and pack it as the duplex command."""
     try:
-        audio_bytes = base64.b64decode(audio, validate=True) if isinstance(audio, str) and audio else b""
-    except (binascii.Error, ValueError) as exc:
-        raise DuplexCommandError("input audio is not valid base64", code="bad_audio", event_id=event_id) from exc
+        decoded = decode_audio_append(event, defaults=defaults, hints_source=hints_source)
+    except RealtimeProtocolError as exc:
+        raise DuplexCommandError(str(exc), code=exc.code, event_id=exc.event_id) from exc
     return AppendAudio(
-        event_id=event_id,
-        audio=audio_bytes,
-        format=str(fmt),
-        sample_rate_hz=int(sample_rate_hz) if isinstance(sample_rate_hz, int | float) else None,
-        is_speech=looks_like_speech,
-        video_frames=video_frames,
-        duration_ms=int(duration_ms) if isinstance(duration_ms, int | float) else None,
-        audio_end_ms=int(audio_end_ms) if isinstance(audio_end_ms, int | float) else None,
-        hints=hints,
+        event_id=decoded.event_id,
+        audio=decoded.audio,
+        format=decoded.format,
+        sample_rate_hz=decoded.sample_rate_hz,
+        is_speech=decoded.is_speech,
+        video_frames=decoded.video_frames,
+        duration_ms=decoded.duration_ms,
+        audio_end_ms=decoded.audio_end_ms,
+        hints=decoded.hints,
     )
 
 
@@ -664,14 +161,9 @@ def translate_realtime_command(
     if event_type == "session.update":
         session = payload.get("session")
         session_payload: Mapping[str, object] = session if isinstance(session, dict) else payload
-        format_error = validate_realtime_session_audio_formats(session_payload)
-        if format_error is not None:
-            raise DuplexCommandError(format_error, code="unsupported_audio_format", event_id=event_id)
-        from vllm_omni.engine.duplex.turn_detection import validate_realtime_turn_detection
-
-        turn_detection_error = validate_realtime_turn_detection(session_payload)
-        if turn_detection_error is not None:
-            raise DuplexCommandError(turn_detection_error, code="unsupported_turn_detection", event_id=event_id)
+        rejection = validate_session_payload(session_payload, capabilities=DUPLEX_REALTIME_CAPABILITIES)
+        if rejection is not None:
+            raise DuplexCommandError(rejection.message, code=rejection.code, event_id=event_id)
         return UpdateSession(event_id=event_id, patch=dict(session_payload))
 
     if event_type == "conversation.item.create":
@@ -855,7 +347,10 @@ def translate_realtime_command(
     raise DuplexCommandError(f"Unknown duplex event type: {event_type}", code="unknown_event", event_id=event_id)
 
 
+#: Names this module used to define, re-exported so existing importers keep
+#: working. The canonical definitions live in ``vllm_omni.protocol.realtime``.
 __all__ = [
+    "DUPLEX_REALTIME_CAPABILITIES",
     "REALTIME_INPUT_AUDIO_FORMATS",
     "REALTIME_INPUT_HINT_KEYS",
     "REALTIME_OUTPUT_AUDIO_FORMATS",
diff --git a/vllm_omni/engine/duplex/realtime_events.py b/vllm_omni/engine/duplex/realtime_events.py
index 91359f297e5..f67abbbc9fb 100644
--- a/vllm_omni/engine/duplex/realtime_events.py
+++ b/vllm_omni/engine/duplex/realtime_events.py
@@ -15,6 +15,12 @@
 flags, conversation items, response-id fallbacks); the ``resolve_*`` /
 ``note_*`` helpers give the runner the same behaviour for the corresponding
 commands.
+
+What is *not* here is the model- and runtime-agnostic half of the codec ---
+audio format negotiation, conversation-item shape and truncation, transcript
+extraction, audio conversion. That lives in ``vllm_omni.protocol.realtime`` so
+a non-duplex Realtime surface can use it without the duplex session; this
+module is the duplex consumer of it (RFC #6592 P0a).
 """
 
 from __future__ import annotations
@@ -24,7 +30,6 @@
 from typing import TYPE_CHECKING, cast
 from uuid import uuid4
 
-from vllm_omni.engine.duplex.audio import convert_output_audio
 from vllm_omni.engine.duplex.commands import (
     AppendAudio,
     CancelResponse,
@@ -74,10 +79,11 @@
     TranscriptDone,
     error_event,
 )
-from vllm_omni.engine.duplex.realtime_commands import (
+from vllm_omni.engine.duplex.realtime_commands import build_append_audio
+from vllm_omni.protocol.duplex import (
     RealtimeInputDefaults,
     apply_realtime_session_defaults,
-    build_append_audio,
+    convert_output_audio,
     copy_realtime_input_hints,
     input_looks_like_speech,
     input_transcript_from_item,
diff --git a/vllm_omni/engine/duplex/session/runner.py b/vllm_omni/engine/duplex/session/runner.py
index 7915500b739..0b8af49abfc 100644
--- a/vllm_omni/engine/duplex/session/runner.py
+++ b/vllm_omni/engine/duplex/session/runner.py
@@ -28,7 +28,6 @@
 
 from vllm.logger import init_logger
 
-from vllm_omni.engine.duplex.audio import convert_input_audio_with_rate
 from vllm_omni.engine.duplex.commands import (
     AckPlayback,
     AppendAudio,
@@ -103,6 +102,7 @@
     TurnDetectionResult,
 )
 from vllm_omni.metrics.stats import StageRequestStats
+from vllm_omni.protocol.duplex import convert_input_audio_with_rate
 
 if TYPE_CHECKING:
     from vllm.config import ModelConfig
diff --git a/vllm_omni/entrypoints/duplex/realtime_input.py b/vllm_omni/entrypoints/duplex/realtime_input.py
index be700ef6279..79a0816963c 100644
--- a/vllm_omni/entrypoints/duplex/realtime_input.py
+++ b/vllm_omni/entrypoints/duplex/realtime_input.py
@@ -5,7 +5,9 @@
 
 Everything that needed session state now lives engine-side
 (``vllm_omni.engine.duplex.realtime_commands`` for the command mapping,
-``vllm_omni.engine.duplex.realtime_events`` for the projection state). What is
+``vllm_omni.engine.duplex.realtime_events`` for the projection state), and the
+model-agnostic parsing both of those build on lives in
+``vllm_omni.protocol.realtime``. What is
 left here is the per-connection handshake policy (query-param defaults,
 autostart / resume-only rules, ``session.resume`` parsing), the wire defaults
 used to translate appends, and error rendering through the typed
@@ -20,10 +22,8 @@
 
 from vllm_omni.engine.duplex.commands import DuplexCommand, DuplexCommandError
 from vllm_omni.engine.duplex.events import error_event
-from vllm_omni.engine.duplex.realtime_commands import (
-    RealtimeInputDefaults,
-    translate_realtime_command,
-)
+from vllm_omni.engine.duplex.realtime_commands import translate_realtime_command
+from vllm_omni.protocol.duplex import RealtimeInputDefaults
 
 if TYPE_CHECKING:
     from starlette.websockets import WebSocket
diff --git a/vllm_omni/entrypoints/duplex/serving.py b/vllm_omni/entrypoints/duplex/serving.py
index 364f715c057..ff1abbe25d4 100644
--- a/vllm_omni/entrypoints/duplex/serving.py
+++ b/vllm_omni/entrypoints/duplex/serving.py
@@ -36,7 +36,6 @@
     SessionResyncRequired,
 )
 from vllm_omni.engine.duplex.messages import DuplexSessionError
-from vllm_omni.engine.duplex.realtime_commands import RealtimeInputDefaults
 from vllm_omni.entrypoints.duplex.realtime_input import RealtimeEnvelope, parse_resume_request
 from vllm_omni.entrypoints.duplex.session_attachment import (
     DuplexJournalGapError,
@@ -52,6 +51,7 @@
     receive_text_with_timeout,
 )
 from vllm_omni.entrypoints.duplex_omni import DuplexOmni, DuplexSessionHandle
+from vllm_omni.protocol.duplex import RealtimeInputDefaults
 
 logger = init_logger(__name__)
 
diff --git a/vllm_omni/protocol/__init__.py b/vllm_omni/protocol/__init__.py
new file mode 100644
index 00000000000..e241a7924b2
--- /dev/null
+++ b/vllm_omni/protocol/__init__.py
@@ -0,0 +1,17 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Wire protocols vLLM-Omni speaks, independent of who serves or runs them.
+
+A module under ``vllm_omni.protocol`` describes *what is on the wire*: how a
+client payload is parsed and validated, and what shape a server payload has.
+It never decides how a request is executed, which model answers it, or where
+the session state lives. That keeps one protocol implementation usable by more
+than one runtime (see ``vllm_omni.protocol.realtime``).
+
+Dependency rule, asserted by ``tests/protocol/realtime/test_protocol_import_boundary.py``:
+nothing here may import ``vllm_omni.engine``, ``vllm_omni.entrypoints``,
+``vllm_omni.model_executor``, ``vllm_omni.worker`` or ``vllm_omni.clients``.
+The arrows point inwards --- those packages import the protocol, never the
+other way round.
+"""
diff --git a/vllm_omni/protocol/duplex/__init__.py b/vllm_omni/protocol/duplex/__init__.py
new file mode 100644
index 00000000000..d89a01322e5
--- /dev/null
+++ b/vllm_omni/protocol/duplex/__init__.py
@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""vLLM-Omni's full-duplex extension of the OpenAI Realtime wire protocol.
+
+OpenAI's Realtime API assumes one turn at a time: the client commits input, the
+server answers. A full-duplex session does not --- the model listens while it
+speaks, it decides when to take a turn, the client reports playback progress,
+and a dropped socket re-attaches to a session that kept running. Those need
+events and commands the GA vocabulary does not have.
+
+This package is that delta. It builds on ``vllm_omni.protocol.realtime`` (same
+base classes, same pure wire rendering, no duplication) and, like it, owns no
+session and imports no runtime: the duplex engine depends on this package, not
+the other way round.
+
+The one door
+------------
+It is also the *only* door a duplex consumer uses. ``protocol.duplex.commands``
+and ``protocol.duplex.events`` carry the complete vocabulary --- Tier 1 classes
+re-exported unchanged alongside the Tier 2 and Tier 3 ones --- and this module
+re-exports the Tier 1 helper functions. So the layering is a chain, not a mesh::
+
+    protocol.realtime   (OpenAI's surface)
+        ^
+        | imports
+        |
+    protocol.duplex     (this package: re-exports Tier 1, adds Tier 2 and 3)
+        ^
+        | imports
+        |
+    duplex engine / entrypoints / clients
+
+``tests/protocol/duplex/test_duplex_protocol_facade.py`` asserts that the last
+arrow is the only one: no duplex consumer imports ``protocol.realtime``
+directly. The payoff is that a helper which later needs a duplex-specific
+version --- ``convert_input_audio_with_rate`` is the standing example, it
+resamples to MiniCPM-o's 16 kHz rather than the client's rate --- is overridden
+in one file instead of at every call site.
+
+What stays outside
+------------------
+The *mailbox* half of a command does not live here. A duplex command carries
+two different things: the client event it decodes from (wire, this package) and
+the dictionary the session runner consumes (engine). They genuinely differ ---
+``session.update``, ``conversation.item.create`` / ``.delete`` / ``.truncate``
+all travel on the runner's ``turn.signal`` channel --- so ``payload()`` and its
+``type`` stay in ``vllm_omni.engine.duplex.commands``. Events have no such
+half, which is why :data:`~vllm_omni.protocol.duplex.events.DuplexEvent` can be
+a plain alias of ``RealtimeEvent`` while ``DuplexCommand`` cannot.
+"""
+
+from vllm_omni.protocol.duplex.errors import (
+    REALTIME_ERROR_TYPES_BY_CODE,
+    RealtimeProtocolError,
+    realtime_error_type,
+)
+from vllm_omni.protocol.realtime.audio import (
+    MAX_INPUT_SAMPLE_RATE_HZ,
+    MIN_INPUT_SAMPLE_RATE_HZ,
+    convert_input_audio_with_rate,
+    convert_output_audio,
+    decode_g711_alaw,
+    decode_g711_ulaw,
+    encode_float32_mono_wav_base64,
+    encode_g711_alaw,
+    encode_g711_ulaw,
+    resample_pcm16_mono,
+    validate_input_sample_rate_hz,
+    wav_payload_to_pcm16,
+)
+from vllm_omni.protocol.realtime.audio_input import (
+    REALTIME_INPUT_HINT_KEYS,
+    RealtimeAudioAppend,
+    copy_realtime_input_hints,
+    decode_audio_append,
+    input_explicitly_non_speech,
+    input_looks_like_speech,
+)
+from vllm_omni.protocol.realtime.capabilities import (
+    RealtimeProtocolCapabilities,
+    RealtimeSessionRejection,
+    validate_session_payload,
+)
+from vllm_omni.protocol.realtime.formats import (
+    REALTIME_INPUT_AUDIO_FORMATS,
+    REALTIME_OUTPUT_AUDIO_FORMATS,
+    is_supported_realtime_input_format,
+    parse_realtime_audio_format,
+    realtime_audio_format_object,
+    realtime_output_format,
+    validate_conversation_item_audio_formats,
+    validate_realtime_response_audio_formats,
+    validate_realtime_session_audio_formats,
+)
+from vllm_omni.protocol.realtime.items import (
+    input_transcript_from_item,
+    normalize_conversation_item,
+    text_chars_for_audio_ms_from_marks,
+    truncate_realtime_item_content,
+    validate_realtime_item_truncate,
+    validate_realtime_video_frames,
+)
+from vllm_omni.protocol.realtime.session import (
+    RealtimeInputDefaults,
+    apply_realtime_session_defaults,
+    input_audio_transcription_config,
+    json_safe_realtime_payload,
+    realtime_max_output_tokens,
+    realtime_overlap_fields,
+)
+
+__all__ = [
+    "MAX_INPUT_SAMPLE_RATE_HZ",
+    "MIN_INPUT_SAMPLE_RATE_HZ",
+    "REALTIME_ERROR_TYPES_BY_CODE",
+    "REALTIME_INPUT_AUDIO_FORMATS",
+    "REALTIME_INPUT_HINT_KEYS",
+    "REALTIME_OUTPUT_AUDIO_FORMATS",
+    "RealtimeAudioAppend",
+    "RealtimeInputDefaults",
+    "RealtimeProtocolCapabilities",
+    "RealtimeProtocolError",
+    "RealtimeSessionRejection",
+    "apply_realtime_session_defaults",
+    "convert_input_audio_with_rate",
+    "convert_output_audio",
+    "copy_realtime_input_hints",
+    "decode_audio_append",
+    "decode_g711_alaw",
+    "decode_g711_ulaw",
+    "encode_float32_mono_wav_base64",
+    "encode_g711_alaw",
+    "encode_g711_ulaw",
+    "input_audio_transcription_config",
+    "input_explicitly_non_speech",
+    "input_looks_like_speech",
+    "input_transcript_from_item",
+    "is_supported_realtime_input_format",
+    "json_safe_realtime_payload",
+    "normalize_conversation_item",
+    "parse_realtime_audio_format",
+    "realtime_audio_format_object",
+    "realtime_error_type",
+    "realtime_max_output_tokens",
+    "realtime_output_format",
+    "realtime_overlap_fields",
+    "resample_pcm16_mono",
+    "text_chars_for_audio_ms_from_marks",
+    "truncate_realtime_item_content",
+    "validate_conversation_item_audio_formats",
+    "validate_input_sample_rate_hz",
+    "validate_realtime_item_truncate",
+    "validate_realtime_response_audio_formats",
+    "validate_realtime_session_audio_formats",
+    "validate_realtime_video_frames",
+    "validate_session_payload",
+    "wav_payload_to_pcm16",
+]
diff --git a/vllm_omni/protocol/duplex/commands.py b/vllm_omni/protocol/duplex/commands.py
new file mode 100644
index 00000000000..1dbb9bf25c0
--- /dev/null
+++ b/vllm_omni/protocol/duplex/commands.py
@@ -0,0 +1,164 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The client-event vocabulary a full-duplex session accepts.
+
+Seven of the seventeen are events OpenAI's Realtime API has no equivalent for,
+because they only make sense when the model and the user can talk at the same
+time: the user cuts in (``barge_in``), the client reports how much audio it
+played (``playback.ack``), a turn transition is signalled locally
+(``turn.signal``), input is abandoned without committing (``input.cancel``),
+text is pushed into a live turn (``input.text.append``), and the session is
+kept alive or closed explicitly (``session.heartbeat`` / ``session.close``).
+Two more are OpenAI commands carrying duplex-only fields (Tier 2).
+
+The remaining eight are OpenAI's, unchanged, and re-exported from
+``vllm_omni.protocol.realtime.commands`` rather than redeclared --- they are
+the same objects. They are re-exported so this module is the *whole*
+vocabulary and a duplex consumer never has to import the Tier 1 package
+directly; keeping them declared there means a GA-only consumer is still not
+handed events its clients never send.
+
+None of these carries the engine's mailbox rendering: ``payload()`` and its
+channel live in ``vllm_omni.engine.duplex.commands``, because for four of the
+seventeen the runner's channel is not the client event type at all.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from vllm_omni.protocol.realtime import commands as realtime_commands
+from vllm_omni.protocol.realtime.commands import (
+    CancelResponse,
+    ClearInput,
+    ClearOutputAudio,
+    CreateItem,
+    CreateResponse,
+    DeleteItem,
+    RealtimeCommand,
+    TruncateItem,
+    UpdateSession,
+)
+
+# ---- Tier 2: OpenAI names carrying vLLM-Omni extensions ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppendAudio(realtime_commands.AppendAudio):
+    """Tier 2: OpenAI's ``input_audio_buffer.append`` plus the duplex hints.
+
+    OpenAI's append is just base64 audio. The duplex lane also lets a client
+    declare this chunk's own format and rate, whether it believes the chunk is
+    speech, camera frames captured alongside it, and its timing --- all
+    additive, all ignored by a stock client.
+    """
+
+    #: Model-neutral hints carried through from the wire (rms, vad, transcript hints ...).
+    format: str = "pcm16"
+    sample_rate_hz: int | None = None
+    is_speech: bool | None = None
+    video_frames: tuple[str, ...] = ()
+    duration_ms: int | None = None
+    audio_end_ms: int | None = None
+    hints: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Commit(realtime_commands.Commit):
+    """Tier 2: OpenAI's ``input_audio_buffer.commit`` plus duplex turn control.
+
+    OpenAI's commit carries nothing and always produces an item. Here a commit
+    may be non-final, may decline to start a response, and may declare itself
+    silence --- the semantic divergence documented in
+    ``docs/serving/realtime_duplex_api.md`` ("Commit != response").
+    """
+
+    #: Realtime conversation item created for this commit (wire correlation only).
+    #: ``None`` means "no explicit request": the runner decides on commit (auto-response
+    #: sessions answer on their own); ``True`` / ``False`` force it.
+    create_response: bool | None = None
+    is_speech: bool | None = None
+    realtime_item_id: str | None = None
+
+
+# ---- Tier 3: vLLM-Omni only ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppendText(RealtimeCommand):
+    wire_type: ClassVar[str] = "input.text.append"
+    text: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CancelInput(RealtimeCommand):
+    wire_type: ClassVar[str] = "input.cancel"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BargeIn(RealtimeCommand):
+    wire_type: ClassVar[str] = "barge_in"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SignalTurn(RealtimeCommand):
+    """Generic ``turn.signal`` (local turn transitions such as ``user_started``)."""
+
+    wire_type: ClassVar[str] = "turn.signal"
+    event: str
+    signal_payload: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AckPlayback(RealtimeCommand):
+    wire_type: ClassVar[str] = "playback.ack"
+    played_ms: int
+    committed_ms: int | None = None
+    response_id: str | None = None
+    item_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Heartbeat(RealtimeCommand):
+    wire_type: ClassVar[str] = "session.heartbeat"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CloseSession(RealtimeCommand):
+    """Graceful close requested through the command stream (``session.close``)."""
+
+    wire_type: ClassVar[str] = "session.close"
+    reason: str = "client_close"
+
+
+#: The complete command vocabulary a duplex client may send: the eight Tier 1
+#: classes re-exported unchanged, the two Tier 2 classes defined above, and the
+#: seven Tier 3 ones. A duplex consumer imports from here and never reaches
+#: past this module into ``vllm_omni.protocol.realtime``, so a command that
+#: later grows a duplex extension changes only this file.
+__all__ = [
+    # Tier 1 --- re-exported from ``vllm_omni.protocol.realtime.commands``.
+    "CancelResponse",
+    "ClearInput",
+    "ClearOutputAudio",
+    "CreateItem",
+    "CreateResponse",
+    "DeleteItem",
+    "RealtimeCommand",
+    "TruncateItem",
+    "UpdateSession",
+    # Tier 2 --- an OpenAI command plus duplex-only fields.
+    "AppendAudio",
+    "Commit",
+    # Tier 3 --- vLLM-Omni only.
+    "AckPlayback",
+    "AppendText",
+    "BargeIn",
+    "CancelInput",
+    "CloseSession",
+    "Heartbeat",
+    "SignalTurn",
+]
diff --git a/vllm_omni/protocol/duplex/errors.py b/vllm_omni/protocol/duplex/errors.py
new file mode 100644
index 00000000000..418c9871212
--- /dev/null
+++ b/vllm_omni/protocol/duplex/errors.py
@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""vLLM-Omni's Realtime error-code vocabulary.
+
+OpenAI's Realtime API standardises the ``error.type`` classes
+(``invalid_request_error`` / ``server_error`` / ``rate_limit_error``) but not
+the ``code`` values inside them. Ours are listed here --- Tier 3 in
+``docs/serving/realtime_duplex_api.md``, "the full error-code vocabulary" ---
+so ``protocol/realtime`` stays the OpenAI surface and nothing more.
+"""
+
+from __future__ import annotations
+
+from vllm_omni.protocol.realtime.errors import RealtimeProtocolError
+
+__all__ = ["REALTIME_ERROR_TYPES_BY_CODE", "RealtimeProtocolError", "realtime_error_type"]
+
+
+#: OpenAI Realtime ``error.type`` for each internal error code.
+REALTIME_ERROR_TYPES_BY_CODE: dict[str, str] = {
+    "bad_event": "invalid_request_error",
+    "bad_audio": "invalid_request_error",
+    "config_timeout": "invalid_request_error",
+    "invalid_json": "invalid_request_error",
+    "event_too_large": "invalid_request_error",
+    "unknown_event": "invalid_request_error",
+    "internal_error": "server_error",
+    "runtime_append_failed": "server_error",
+    "runtime_append_task_failed": "server_error",
+    "runtime_signal_failed": "server_error",
+    "runtime_abort_failed": "server_error",
+    "runtime_data_plane_stream_failed": "server_error",
+    "runtime_data_plane_text_without_audio": "server_error",
+    "resource_exhausted": "rate_limit_error",
+    "session_exists": "invalid_request_error",
+    "session_closed": "invalid_request_error",
+    "unknown_session": "invalid_request_error",
+    "invalid_duplex_runtime_config": "invalid_request_error",
+    "instructions_update_unsupported": "invalid_request_error",
+    "persona_update_unsupported": "invalid_request_error",
+    "voice_update_unsupported": "invalid_request_error",
+    "unsupported_nemotron_duplex_mode": "invalid_request_error",
+    "unsupported_native_response_options": "invalid_request_error",
+    "runtime_touch_failed": "server_error",
+    "engine_error": "server_error",
+    "input_backpressure": "rate_limit_error",
+    "response_already_active": "invalid_request_error",
+    "response_not_active": "invalid_request_error",
+    "response_create_without_input": "invalid_request_error",
+    "text_only_turn_unsupported": "invalid_request_error",
+    "commit_aborted": "server_error",
+    "input_audio_buffer_empty": "invalid_request_error",
+    "missing_item_id": "invalid_request_error",
+    "item_not_found": "invalid_request_error",
+    "playback_item_mismatch": "invalid_request_error",
+    "playback_item_not_found": "invalid_request_error",
+    "playback_ack_too_late": "invalid_request_error",
+    "unsupported_audio_format": "invalid_request_error",
+    "unsupported_turn_detection": "invalid_request_error",
+    "unsupported_ref_audio_path": "invalid_request_error",
+    "ref_audio_required": "invalid_request_error",
+    "model_update_unsupported": "invalid_request_error",
+    "voice_update_after_audio_unsupported": "invalid_request_error",
+    "ref_audio_update_unsupported": "invalid_request_error",
+    "native_text_append_unsupported": "invalid_request_error",
+    "invalid_video_frames": "invalid_request_error",
+    "invalid_function_call_output": "invalid_request_error",
+    "server_vad_unavailable": "server_error",
+}
+
+
+def realtime_error_type(code: str) -> str:
+    """The OpenAI ``error.type`` bucket for an internal error code."""
+    return REALTIME_ERROR_TYPES_BY_CODE.get(code, "invalid_request_error")
diff --git a/vllm_omni/protocol/duplex/events.py b/vllm_omni/protocol/duplex/events.py
new file mode 100644
index 00000000000..f2abe748e8b
--- /dev/null
+++ b/vllm_omni/protocol/duplex/events.py
@@ -0,0 +1,419 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""vLLM-Omni's half of the Realtime server-event vocabulary.
+
+``docs/serving/realtime_duplex_api.md`` sorts every message into three tiers.
+Tier 1 --- identical to OpenAI --- is ``vllm_omni.protocol.realtime.events``.
+The other two are here:
+
+**Tier 2, OpenAI names carrying vLLM-Omni extensions.** Same wire type, same
+OpenAI fields, plus additive keys a stock client ignores. Each one subclasses
+its Tier 1 twin and declares only what it adds, so the OpenAI surface stays
+honest: a consumer that wants pure GA takes ``protocol/realtime`` and gets
+exactly OpenAI's fields.
+
+**Tier 3, vLLM-Omni only.** Events OpenAI has no equivalent for, because they
+only make sense when the model and the user can talk at the same time: the
+model decides when to listen and when to speak, the client reports how much
+audio it played, overlapping speech needs a recorded decision, and a dropped
+socket can re-attach to a live session.
+
+Same-named classes are deliberate --- ``duplex.events.SessionCreated`` *is*
+``realtime.events.SessionCreated`` with our extensions. Import whichever
+surface you mean.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import cast
+
+from vllm_omni.protocol.duplex.errors import REALTIME_ERROR_TYPES_BY_CODE
+from vllm_omni.protocol.realtime import events as realtime_events
+from vllm_omni.protocol.realtime.events import (
+    AudioDone,
+    ContentPartAdded,
+    ContentPartDone,
+    FunctionCallArgumentsDelta,
+    FunctionCallArgumentsDone,
+    InputCleared,
+    InputTranscriptionCompleted,
+    ItemAdded,
+    ItemCreated,
+    ItemDone,
+    ItemRetrieved,
+    OutputAudioCleared,
+    OutputItemAdded,
+    OutputItemDone,
+    RateLimitsUpdated,
+    RealtimeEvent,
+    ResponseScopedEvent,
+    SessionUpdated,
+    SpeechStarted,
+    SpeechStopped,
+    TextDelta,
+    TextDone,
+    TranscriptDelta,
+    TranscriptDone,
+    new_event_id,
+    wire_value,
+)
+
+#: The duplex event base class *is* the Realtime one: unlike a command, an
+#: event has no engine-internal half to carry --- what the session emits is
+#: exactly what the socket sends. Named here rather than in the engine so the
+#: duplex vocabulary is described in one place, and kept as an alias rather
+#: than an empty subclass so ``isinstance`` and the class identity tests in
+#: ``tests/protocol/`` stay meaningful.
+DuplexEvent = RealtimeEvent
+
+# ---- Tier 2: OpenAI names carrying vLLM-Omni extensions ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionCreated(realtime_events.SessionCreated):
+    """Tier 2: OpenAI's ``SessionCreated`` plus the resume credentials a reconnecting client needs."""
+
+    #: Transport resume credentials (set by the websocket handler when resume is supported).
+    optional_wire_fields = frozenset({"attachment_generation", "resume_token"})
+    attachment_generation: int | None = None
+    resume_token: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResponseCreated(realtime_events.ResponseCreated):
+    """Tier 2: OpenAI's ``ResponseCreated`` plus a top-level ``response_id``.
+
+    OpenAI carries the id nested as ``response.id``; the duplex lane also
+    reports it at the top level, where every other response-scoped event
+    already has one.
+    """
+
+    response_id: str | None = None  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResponseDone(realtime_events.ResponseDone):
+    """Tier 2: OpenAI's ``ResponseDone`` plus a top-level ``response_id``.
+
+    OpenAI carries the id nested as ``response.id``; the duplex lane also
+    reports it at the top level, where every other response-scoped event
+    already has one.
+    """
+
+    response_id: str | None = None  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AudioDelta(realtime_events.AudioDelta):
+    """Tier 2: OpenAI's ``AudioDelta`` plus the chunk's own format/rate and the duplex playback metadata."""
+
+    optional_wire_fields = frozenset({"sample_rate_hz", "metadata"})
+    format: str = "pcm16"
+    sample_rate_hz: int | None = None
+    metadata: Mapping[str, object] | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InputCommitted(realtime_events.InputCommitted):
+    """Tier 2: OpenAI's ``InputCommitted`` plus the native ``input.committed`` event echoed under ``event``."""
+
+    #: The session-internal ``input.committed`` event.
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        # Explicit parent call, not ``super()``: ``@dataclass(slots=True)``
+        # rebuilds the class, so the zero-argument form's ``__class__`` cell
+        # points at the pre-slots class and is no longer in the MRO.
+        base = realtime_events.__dict__[type(self).__name__]._wire_fields(self)
+        return {**base, "event": wire_value(self.details)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemDeleted(realtime_events.ItemDeleted):
+    """Tier 2: OpenAI's ``ItemDeleted`` plus the originating event echoed under ``event``."""
+
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        # Explicit parent call, not ``super()``: ``@dataclass(slots=True)``
+        # rebuilds the class, so the zero-argument form's ``__class__`` cell
+        # points at the pre-slots class and is no longer in the MRO.
+        base = realtime_events.__dict__[type(self).__name__]._wire_fields(self)
+        return {**base, "event": wire_value(self.details)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemTruncated(realtime_events.ItemTruncated):
+    """Tier 2: OpenAI's ``ItemTruncated`` plus the originating event echoed under ``event``."""
+
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        # Explicit parent call, not ``super()``: ``@dataclass(slots=True)``
+        # rebuilds the class, so the zero-argument form's ``__class__`` cell
+        # points at the pre-slots class and is no longer in the MRO.
+        base = realtime_events.__dict__[type(self).__name__]._wire_fields(self)
+        return {**base, "event": wire_value(self.details)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ErrorEvent(realtime_events.ErrorEvent):
+    """Tier 2: OpenAI's ``ErrorEvent`` plus vLLM-Omni's error codes and any extra keys merged into the envelope."""
+
+    #: Extra keys merged into the wire ``error`` object (``retryable`` ...).
+    extra: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def error_type(self) -> str:
+        return REALTIME_ERROR_TYPES_BY_CODE.get(self.code, "invalid_request_error")
+
+    @property
+    def error(self) -> dict[str, object]:
+        # Explicit parent call, not ``super()``: ``@dataclass(slots=True)``
+        # rebuilds the class, so the zero-argument form's ``__class__`` cell
+        # points at the pre-slots class and is no longer in the MRO. Reached
+        # through ``__dict__`` because attribute access on the class gives the
+        # getter function, not the ``property`` that owns it.
+        error = dict(realtime_events.ErrorEvent.__dict__["error"].fget(self))
+        error.update(cast("Mapping[str, object]", wire_value(self.extra)))
+        return error
+
+
+# ---- Tier 3: vLLM-Omni only ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionResumed(SessionCreated):
+    wire_type = "session.resumed"
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, **RealtimeEvent._wire_fields(self)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionReplaced(RealtimeEvent):
+    """A newer connection took the session over (sent to the replaced socket)."""
+
+    wire_type = "session.replaced"
+
+    attachment_generation: int = 0
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, **RealtimeEvent._wire_fields(self)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionResyncRequired(RealtimeEvent):
+    """The replay journal cannot bridge the gap; the client must start over."""
+
+    wire_type = "session.resync_required"
+
+    reason: str = "journal_gap"
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, **RealtimeEvent._wire_fields(self)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionClosed(RealtimeEvent):
+    wire_type = "session.closed"
+
+    reason: str = "closed"
+    #: The session-internal close event (kept for clients that inspect it).
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def is_terminal(self) -> bool:
+        return True
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, "reason": self.reason, "event": wire_value(self.details)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionExpired(SessionClosed):
+    wire_type = "session.expired"
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, "reason": self.reason}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionHeartbeatAck(RealtimeEvent):
+    wire_type = "session.heartbeat_ack"
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TurnEvent(RealtimeEvent):
+    """Turn-state transition (``turn.event``)."""
+
+    wire_type = "turn.event"
+
+    event: str = ""
+    turn_state: str = ""
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"session_id": self.session_id, "event": self.event, "turn_state": self.turn_state, "epoch": self.epoch}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Listen(RealtimeEvent):
+    """The model decided to keep listening (no spoken response for this turn)."""
+
+    wire_type = "response.listen"
+    optional_wire_fields = frozenset({"response_id"})
+
+    response_id: str | None = None  # type: ignore[assignment]
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        response: dict[str, object] = {
+            "object": "realtime.response",
+            "status": "listening",
+            "metadata": wire_value(self.details),
+        }
+        data: dict[str, object] = {"session_id": self.session_id, "epoch": self.epoch, "response": response}
+        if self.response_id:
+            response["id"] = self.response_id
+            data["response_id"] = self.response_id
+        return data
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Speak(ResponseScopedEvent):
+    wire_type = "response.speak"
+
+    metadata: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OverlapDecision(RealtimeEvent):
+    wire_type = "overlap.decision"
+
+    policy: str | None = None
+    action: str | None = None
+    reason: str | None = None
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {
+            "session_id": self.session_id,
+            "epoch": self.epoch,
+            "policy": self.policy,
+            "action": self.action,
+            "reason": self.reason,
+            "metadata": wire_value(self.details),
+        }
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class PlaybackAcknowledged(RealtimeEvent):
+    wire_type = "playback.acknowledged"
+
+    #: The session-internal ``playback.acknowledged`` event (cursor, committed_ms ...).
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"event": wire_value(self.details)}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DuplexRawEvent(RealtimeEvent):
+    """A session-internal event with no dedicated Realtime type (``duplex.<internal type>``)."""
+
+    wire_type = "duplex.raw"
+
+    internal_type: str = ""
+    details: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def type(self) -> str:
+        return f"duplex.{self.internal_type}"
+
+    def to_realtime(self) -> dict[str, object]:
+        return {"type": self.type, "event_id": self.event_id, "event": wire_value(self.details)}
+
+
+def error_event(
+    code: str,
+    message: str,
+    *,
+    event_id: object | None = None,
+    param: object | None = None,
+    extra: Mapping[str, object] | None = None,
+) -> ErrorEvent:
+    """Build the error event for an internal code; ``event_id`` is the *client* event id."""
+    return ErrorEvent(
+        code=code,
+        message=message,
+        related_event_id=event_id if isinstance(event_id, str) and event_id else None,
+        param=param if isinstance(param, str) and param else None,
+        extra=dict(extra or {}),
+    )
+
+
+#: The complete event vocabulary a duplex client may receive: 22 Tier 1
+#: classes re-exported unchanged, the 8 Tier 2 ones defined above, and 12
+#: Tier 3 ones. A duplex consumer imports from here and never reaches past
+#: this module into ``vllm_omni.protocol.realtime``.
+__all__ = [
+    # Tier 1 --- re-exported from ``vllm_omni.protocol.realtime.events``.
+    "AudioDone",
+    "ContentPartAdded",
+    "ContentPartDone",
+    "FunctionCallArgumentsDelta",
+    "FunctionCallArgumentsDone",
+    "InputCleared",
+    "InputTranscriptionCompleted",
+    "ItemAdded",
+    "ItemCreated",
+    "ItemDone",
+    "ItemRetrieved",
+    "OutputAudioCleared",
+    "OutputItemAdded",
+    "OutputItemDone",
+    "RateLimitsUpdated",
+    "SessionUpdated",
+    "SpeechStarted",
+    "SpeechStopped",
+    "TextDelta",
+    "TextDone",
+    "TranscriptDelta",
+    "TranscriptDone",
+    # Tier 2 --- an OpenAI event plus duplex-only fields.
+    "AudioDelta",
+    "ErrorEvent",
+    "InputCommitted",
+    "ItemDeleted",
+    "ItemTruncated",
+    "ResponseCreated",
+    "ResponseDone",
+    "SessionCreated",
+    # Tier 3 --- vLLM-Omni only.
+    "DuplexRawEvent",
+    "Listen",
+    "OverlapDecision",
+    "PlaybackAcknowledged",
+    "SessionClosed",
+    "SessionExpired",
+    "SessionHeartbeatAck",
+    "SessionReplaced",
+    "SessionResumed",
+    "SessionResyncRequired",
+    "Speak",
+    "TurnEvent",
+    # Bases and helpers shared with the Tier 1 surface.
+    "DuplexEvent",
+    "REALTIME_ERROR_TYPES_BY_CODE",
+    "RealtimeEvent",
+    "ResponseScopedEvent",
+    "error_event",
+    "new_event_id",
+    "wire_value",
+]
diff --git a/vllm_omni/protocol/realtime/__init__.py b/vllm_omni/protocol/realtime/__init__.py
new file mode 100644
index 00000000000..af7194cb506
--- /dev/null
+++ b/vllm_omni/protocol/realtime/__init__.py
@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The OpenAI Realtime wire codec, shared by every vLLM-Omni Realtime surface.
+
+What this is
+------------
+The model-agnostic half of ``WS /v1/realtime``: how a client event is parsed,
+which audio formats and session fields are accepted, what a conversation item
+means, how audio is decoded and resampled, and the shape of the error envelope
+(the *codes* inside it are a consumer's own --- ours are in
+``vllm_omni.protocol.duplex.errors``). It is a library of pure functions and value objects.
+
+What it is not
+--------------
+It owns no session. It does not decide when a response starts, what a model is
+prompted with, whether a turn is over, or where committed audio goes. Those are
+runtime decisions, and after PR #7413 a duplex session's runtime decisions all
+belong to ``vllm_omni.engine.duplex`` --- the session runner, the typed
+``DuplexCommand`` / ``DuplexEvent`` boundary and the ``DuplexModelPlugin`` seam.
+This package sits *under* that: the duplex engine binds the codec to its own
+command and event vocabulary in
+``vllm_omni.engine.duplex.realtime_commands`` and
+``vllm_omni.engine.duplex.realtime_events``.
+
+Why it is separate (RFC #6592, P0a)
+-----------------------------------
+So that a second Realtime surface --- a Qwen3-Omni GA profile, say --- can reuse
+the parsing, validation, format negotiation and error envelope without adopting
+the duplex session control plane (lease manager, commit policy, model channel),
+and without a second copy of the codec drifting away from this one. A consumer
+states what it can serve through
+:class:`~vllm_omni.protocol.realtime.capabilities.RealtimeProtocolCapabilities`
+and keeps its own session state.
+
+Known duplex-shaped defaults
+----------------------------
+This package is model-agnostic in its *dependencies*, not yet in every
+*default*. Two constants still carry the assumptions of its first consumer and
+a second one will have to parameterize them:
+
+* :func:`~vllm_omni.protocol.realtime.audio.convert_input_audio_with_rate`
+  resamples to 16 kHz, which is MiniCPM-o's feature-extractor rate. A GA client
+  sending 24 kHz is converted down rather than served at its own rate.
+* :func:`~vllm_omni.protocol.realtime.items.validate_realtime_video_frames`
+  encodes the MiniCPM-o duplex camera contract (at most two frames per append,
+  ``max_slice_nums`` not selectable on the wire).
+
+Both are behaviour this extraction deliberately did **not** change (RFC #6592
+P0a is behaviour-preserving); making them per-consumer is P0b/P1 work.
+
+Dependency rule
+---------------
+Nothing here may import ``vllm_omni.engine``, ``vllm_omni.entrypoints``,
+``vllm_omni.model_executor``, ``vllm_omni.worker`` or ``vllm_omni.clients``;
+``tests/protocol/realtime/test_protocol_import_boundary.py`` asserts it.
+"""
+
+from vllm_omni.protocol.realtime.audio import (
+    MAX_INPUT_SAMPLE_RATE_HZ,
+    MIN_INPUT_SAMPLE_RATE_HZ,
+    convert_input_audio_with_rate,
+    convert_output_audio,
+    encode_float32_mono_wav_base64,
+    resample_pcm16_mono,
+    validate_input_sample_rate_hz,
+    wav_payload_to_pcm16,
+)
+from vllm_omni.protocol.realtime.audio_input import (
+    REALTIME_INPUT_HINT_KEYS,
+    RealtimeAudioAppend,
+    copy_realtime_input_hints,
+    decode_audio_append,
+    input_explicitly_non_speech,
+    input_looks_like_speech,
+)
+from vllm_omni.protocol.realtime.capabilities import (
+    RealtimeProtocolCapabilities,
+    RealtimeSessionRejection,
+    validate_session_payload,
+)
+from vllm_omni.protocol.realtime.commands import RealtimeCommand
+from vllm_omni.protocol.realtime.errors import RealtimeProtocolError
+from vllm_omni.protocol.realtime.events import (
+    RealtimeEvent,
+    ResponseScopedEvent,
+    new_event_id,
+    wire_value,
+)
+from vllm_omni.protocol.realtime.formats import (
+    REALTIME_INPUT_AUDIO_FORMATS,
+    REALTIME_OUTPUT_AUDIO_FORMATS,
+    is_supported_realtime_input_format,
+    parse_realtime_audio_format,
+    realtime_audio_format_object,
+    realtime_output_format,
+    validate_conversation_item_audio_formats,
+    validate_realtime_response_audio_formats,
+    validate_realtime_session_audio_formats,
+)
+from vllm_omni.protocol.realtime.items import (
+    input_transcript_from_item,
+    normalize_conversation_item,
+    text_chars_for_audio_ms_from_marks,
+    truncate_realtime_item_content,
+    validate_realtime_item_truncate,
+    validate_realtime_video_frames,
+)
+from vllm_omni.protocol.realtime.session import (
+    RealtimeInputDefaults,
+    apply_realtime_session_defaults,
+    input_audio_transcription_config,
+    json_safe_realtime_payload,
+    realtime_max_output_tokens,
+    realtime_overlap_fields,
+)
+
+__all__ = [
+    "MAX_INPUT_SAMPLE_RATE_HZ",
+    "MIN_INPUT_SAMPLE_RATE_HZ",
+    "REALTIME_INPUT_AUDIO_FORMATS",
+    "REALTIME_INPUT_HINT_KEYS",
+    "REALTIME_OUTPUT_AUDIO_FORMATS",
+    "RealtimeAudioAppend",
+    "RealtimeCommand",
+    "RealtimeEvent",
+    "RealtimeInputDefaults",
+    "RealtimeProtocolCapabilities",
+    "RealtimeProtocolError",
+    "RealtimeSessionRejection",
+    "ResponseScopedEvent",
+    "apply_realtime_session_defaults",
+    "convert_input_audio_with_rate",
+    "convert_output_audio",
+    "copy_realtime_input_hints",
+    "decode_audio_append",
+    "encode_float32_mono_wav_base64",
+    "input_audio_transcription_config",
+    "input_explicitly_non_speech",
+    "input_looks_like_speech",
+    "input_transcript_from_item",
+    "is_supported_realtime_input_format",
+    "json_safe_realtime_payload",
+    "new_event_id",
+    "normalize_conversation_item",
+    "parse_realtime_audio_format",
+    "realtime_audio_format_object",
+    "realtime_max_output_tokens",
+    "realtime_output_format",
+    "realtime_overlap_fields",
+    "resample_pcm16_mono",
+    "text_chars_for_audio_ms_from_marks",
+    "truncate_realtime_item_content",
+    "validate_conversation_item_audio_formats",
+    "validate_input_sample_rate_hz",
+    "validate_realtime_item_truncate",
+    "validate_realtime_response_audio_formats",
+    "validate_realtime_session_audio_formats",
+    "validate_realtime_video_frames",
+    "validate_session_payload",
+    "wav_payload_to_pcm16",
+    "wire_value",
+]
diff --git a/vllm_omni/protocol/realtime/audio.py b/vllm_omni/protocol/realtime/audio.py
new file mode 100644
index 00000000000..5f163826a6a
--- /dev/null
+++ b/vllm_omni/protocol/realtime/audio.py
@@ -0,0 +1,218 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import base64
+import binascii
+import io
+import math
+import wave
+
+import numpy as np
+
+from vllm_omni.utils.audio_resample import StreamingAudioResampler
+
+try:
+    from audioop import alaw2lin, lin2alaw, lin2ulaw, ulaw2lin
+except ImportError:  # pragma: no cover - audioop is removed in newer Python.
+    alaw2lin = lin2alaw = lin2ulaw = ulaw2lin = None
+
+
+MIN_INPUT_SAMPLE_RATE_HZ = 8_000
+MAX_INPUT_SAMPLE_RATE_HZ = 192_000
+
+
+def validate_input_sample_rate_hz(sample_rate_hz: object) -> int:
+    if (
+        isinstance(sample_rate_hz, bool)
+        or not isinstance(sample_rate_hz, int | float)
+        or (isinstance(sample_rate_hz, float) and not math.isfinite(sample_rate_hz))
+    ):
+        raise ValueError("sample_rate_hz must be a finite integer")
+    rate = int(sample_rate_hz)
+    if rate != sample_rate_hz:
+        raise ValueError("sample_rate_hz must be an integer")
+    if not MIN_INPUT_SAMPLE_RATE_HZ <= rate <= MAX_INPUT_SAMPLE_RATE_HZ:
+        raise ValueError(f"sample_rate_hz must be between {MIN_INPUT_SAMPLE_RATE_HZ} and {MAX_INPUT_SAMPLE_RATE_HZ}")
+    return rate
+
+
+def resample_pcm16_mono(raw: bytes, *, source_rate_hz: int, target_rate_hz: int) -> bytes:
+    if source_rate_hz <= 0 or target_rate_hz <= 0 or source_rate_hz == target_rate_hz:
+        return raw
+    samples = np.frombuffer(raw, dtype="<i2")
+    rate_gcd = math.gcd(source_rate_hz, target_rate_hz)
+    reduced_factor = max(source_rate_hz // rate_gcd, target_rate_hz // rate_gcd)
+    if reduced_factor > StreamingAudioResampler.max_polyphase_factor:
+        # The FIR size scales with the reduced ratio. Keep unusual client
+        # rates bounded while common audio rates use the high-quality path.
+        if samples.size <= 1:
+            return raw
+        target_size = max(1, int(round(samples.size * target_rate_hz / source_rate_hz)))
+        source_x = np.linspace(0.0, 1.0, num=samples.size, endpoint=True)
+        target_x = np.linspace(0.0, 1.0, num=target_size, endpoint=True)
+        resampled = np.interp(target_x, source_x, samples)
+        return np.clip(resampled, -32_768, 32_767).astype("<i2").tobytes()
+    resampler = StreamingAudioResampler(source_rate_hz, target_rate_hz)
+    normalized = samples.astype(np.float32) * np.float32(1.0 / 32768.0)
+    resampled = resampler.process(normalized, final=True)
+    return np.clip(np.rint(resampled * 32768.0), -32768, 32767).astype("<i2").tobytes()
+
+
+def decode_g711_ulaw(raw: bytes) -> bytes:
+    if ulaw2lin is not None:
+        return ulaw2lin(raw, 2)
+    data = np.frombuffer(raw, dtype=np.uint8)
+    value = np.bitwise_not(data).astype(np.int16)
+    sign = value & 0x80
+    exponent = (value >> 4) & 0x07
+    mantissa = value & 0x0F
+    sample = ((mantissa << 3) + 0x84) << exponent
+    return np.where(sign != 0, -(sample - 0x84), sample - 0x84).astype("<i2").tobytes()
+
+
+def decode_g711_alaw(raw: bytes) -> bytes:
+    if alaw2lin is not None:
+        return alaw2lin(raw, 2)
+    data = np.bitwise_xor(np.frombuffer(raw, dtype=np.uint8), 0x55).astype(np.int16)
+    sign = data & 0x80
+    exponent = (data >> 4) & 0x07
+    mantissa = data & 0x0F
+    sample = np.where(exponent == 0, (mantissa << 4) + 8, ((mantissa << 4) + 0x108) << (exponent - 1))
+    return np.where(sign != 0, sample, -sample).astype("<i2").tobytes()
+
+
+def encode_g711_ulaw(raw: bytes) -> bytes:
+    if lin2ulaw is not None:
+        return lin2ulaw(raw, 2)
+    pcm = np.clip(np.frombuffer(raw, dtype="<i2").astype(np.int32), -32635, 32635)
+    sign = np.where(pcm < 0, 0x80, 0)
+    magnitude = np.abs(pcm) + 0x84
+    exponent = np.zeros_like(magnitude)
+    for exp in range(7):
+        exponent = np.where(magnitude > (0xFF << exp), exp + 1, exponent)
+    mantissa = (magnitude >> (exponent + 3)) & 0x0F
+    return (np.bitwise_not(sign | (exponent << 4) | mantissa) & 0xFF).astype(np.uint8).tobytes()
+
+
+def encode_g711_alaw(raw: bytes) -> bytes:
+    if lin2alaw is not None:
+        return lin2alaw(raw, 2)
+    pcm = np.frombuffer(raw, dtype="<i2").astype(np.int32)
+    sign = np.where(pcm >= 0, 0x80, 0x00)
+    magnitude = np.abs(pcm)
+    exponent = np.zeros_like(magnitude)
+    for exp in range(1, 8):
+        exponent = np.where(magnitude >= (1 << (exp + 7)), exp, exponent)
+    mantissa = np.where(
+        exponent == 0,
+        (magnitude >> 4) & 0x0F,
+        (magnitude >> (exponent + 3)) & 0x0F,
+    )
+    return ((sign | (exponent << 4) | mantissa) ^ 0x55).astype(np.uint8).tobytes()
+
+
+def wav_payload_to_pcm16(raw: bytes) -> tuple[bytes | None, int | None]:
+    try:
+        with wave.open(io.BytesIO(raw), "rb") as wav_file:
+            channels = wav_file.getnchannels()
+            sample_width = wav_file.getsampwidth()
+            sample_rate_hz = wav_file.getframerate()
+            frames = wav_file.readframes(wav_file.getnframes())
+        if sample_width != 2:
+            return None, sample_rate_hz
+        if channels <= 1:
+            return frames, sample_rate_hz
+        pcm = np.frombuffer(frames, dtype="<i2").reshape(-1, channels)
+        mono = np.mean(pcm.astype(np.float32), axis=1)
+        return np.clip(mono, -32768, 32767).astype("<i2").tobytes(), sample_rate_hz
+    except (EOFError, ValueError, wave.Error):
+        return None, None
+
+
+def encode_float32_mono_wav_base64(
+    samples: np.ndarray,
+    *,
+    sample_rate_hz: int,
+) -> str:
+    """Package normalized mono float32 samples as a PCM16 WAV data payload."""
+    rate = validate_input_sample_rate_hz(sample_rate_hz)
+    normalized = np.ascontiguousarray(samples, dtype=np.float32).reshape(-1)
+    pcm16 = np.clip(np.rint(normalized * 32768.0), -32768, 32767).astype("<i2")
+    with io.BytesIO() as buffer:
+        with wave.open(buffer, "wb") as wav_file:
+            wav_file.setnchannels(1)
+            wav_file.setsampwidth(2)
+            wav_file.setframerate(rate)
+            wav_file.writeframes(pcm16.tobytes())
+        return base64.b64encode(buffer.getvalue()).decode("ascii")
+
+
+def convert_input_audio_with_rate(
+    audio: object,
+    fmt: object,
+    *,
+    sample_rate_hz: int | float | None = None,
+    target_sample_rate_hz: int = 16_000,
+) -> tuple[object, object, int | float | None]:
+    if not isinstance(audio, str) or not isinstance(fmt, str):
+        return audio, fmt, sample_rate_hz
+    normalized = fmt.lower()
+    if normalized not in {"pcm16", "pcm_s16le", "s16le", "g711_ulaw", "g711_alaw"}:
+        return audio, fmt, sample_rate_hz
+    if isinstance(sample_rate_hz, int | float):
+        sample_rate_hz = validate_input_sample_rate_hz(sample_rate_hz)
+    try:
+        raw = base64.b64decode(audio.strip(), validate=False)
+    except (binascii.Error, ValueError):
+        return audio, fmt, sample_rate_hz
+    if normalized == "g711_ulaw":
+        raw = decode_g711_ulaw(raw)
+        sample_rate_hz = sample_rate_hz if isinstance(sample_rate_hz, int | float) else 8_000
+    elif normalized == "g711_alaw":
+        raw = decode_g711_alaw(raw)
+        sample_rate_hz = sample_rate_hz if isinstance(sample_rate_hz, int | float) else 8_000
+    elif len(raw) % 2:
+        return audio, fmt, sample_rate_hz
+    if isinstance(sample_rate_hz, int | float) and int(sample_rate_hz) != target_sample_rate_hz:
+        raw = resample_pcm16_mono(
+            raw,
+            source_rate_hz=int(sample_rate_hz),
+            target_rate_hz=target_sample_rate_hz,
+        )
+        sample_rate_hz = target_sample_rate_hz
+    pcm = np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768.0
+    encoded = base64.b64encode(np.ascontiguousarray(pcm, dtype="<f4").tobytes()).decode("ascii")
+    return encoded, "pcm_f32le", sample_rate_hz
+
+
+def convert_output_audio(
+    audio: str,
+    *,
+    source_fmt: str,
+    target_fmt: str,
+    source_sample_rate_hz: int | None = None,
+    target_sample_rate_hz: int | None = None,
+) -> tuple[str, str, int | None]:
+    target = target_fmt.lower()
+    if target not in {"g711_ulaw", "g711_alaw"}:
+        return audio, source_fmt, source_sample_rate_hz
+    try:
+        raw = base64.b64decode(audio, validate=False)
+    except (binascii.Error, ValueError):
+        return audio, source_fmt, source_sample_rate_hz
+    source = source_fmt.lower()
+    if source == "wav":
+        pcm_raw, wav_rate = wav_payload_to_pcm16(raw)
+        if pcm_raw is None:
+            return audio, source_fmt, source_sample_rate_hz
+        raw = pcm_raw
+        source_sample_rate_hz = source_sample_rate_hz or wav_rate
+    elif source not in {"pcm", "pcm16", "pcm_s16le", "s16le"} or len(raw) % 2:
+        return audio, source_fmt, source_sample_rate_hz
+    target_rate = target_sample_rate_hz or 8_000
+    if source_sample_rate_hz is not None:
+        raw = resample_pcm16_mono(raw, source_rate_hz=source_sample_rate_hz, target_rate_hz=target_rate)
+    encoded = encode_g711_ulaw(raw) if target == "g711_ulaw" else encode_g711_alaw(raw)
+    return base64.b64encode(encoded).decode("ascii"), target, target_rate
diff --git a/vllm_omni/protocol/realtime/audio_input.py b/vllm_omni/protocol/realtime/audio_input.py
new file mode 100644
index 00000000000..634d32c349a
--- /dev/null
+++ b/vllm_omni/protocol/realtime/audio_input.py
@@ -0,0 +1,243 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Decoding one ``input_audio_buffer.append``.
+
+An append is the hottest client event on a Realtime connection and the one with
+the most wire surface: base64 audio in any accepted format, an optional rate,
+optional camera frames, and a set of optional hints (``duration_ms``,
+``is_speech``, a VAD probability, a transcript) that clients attach and servers
+are free to use or ignore.
+
+:func:`decode_audio_append` turns that into :class:`RealtimeAudioAppend`, a
+value object: bytes at 16 kHz ``pcm_f32le``, the surviving hints, and a speech
+verdict. It is a pure function of the event plus the session's
+:class:`~vllm_omni.protocol.realtime.session.RealtimeInputDefaults`, so any
+consumer decodes an append the same way. Building a consumer's own command
+object out of it is one constructor call --- see
+``vllm_omni.engine.duplex.realtime_commands.build_append_audio``, which wraps it
+for the duplex ``AppendAudio``.
+
+The speech verdict here is the *client-declared* one (explicit flags, a VAD
+probability the client sent, or an RMS floor as a last resort). It is not
+server-side VAD; that is a runtime concern and lives with whoever owns the
+session.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import cast
+
+import numpy as np
+
+from vllm_omni.protocol.realtime.audio import convert_input_audio_with_rate
+from vllm_omni.protocol.realtime.errors import RealtimeProtocolError
+from vllm_omni.protocol.realtime.formats import (
+    is_supported_realtime_input_format,
+    parse_realtime_audio_format,
+)
+from vllm_omni.protocol.realtime.items import validate_realtime_video_frames
+from vllm_omni.protocol.realtime.session import RealtimeInputDefaults
+
+__all__ = [
+    "REALTIME_INPUT_HINT_KEYS",
+    "RealtimeAudioAppend",
+    "copy_realtime_input_hints",
+    "decode_audio_append",
+    "input_explicitly_non_speech",
+    "input_looks_like_speech",
+]
+
+#: Wire hint keys copied verbatim from a client append onto the internal payload.
+REALTIME_INPUT_HINT_KEYS = (
+    "duration_ms",
+    "audio_duration_ms",
+    "audio_start_ms",
+    "audio_end_ms",
+    "is_speech",
+    "speech",
+    "speech_probability",
+    "vad",
+    "overlap_action",
+    "overlap",
+    "force_barge_in",
+    "force_listen",
+    "text",
+    "transcript",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RealtimeAudioAppend:
+    """One decoded ``input_audio_buffer.append``.
+
+    ``audio`` is raw bytes in ``format`` at ``sample_rate_hz`` --- after
+    :func:`decode_audio_append` that is 16 kHz ``pcm_f32le`` for every input
+    format the codec converts.
+    """
+
+    audio: bytes
+    format: str
+    sample_rate_hz: int | None = None
+    is_speech: bool | None = None
+    video_frames: tuple[str, ...] = ()
+    duration_ms: int | None = None
+    audio_end_ms: int | None = None
+    #: Model-neutral hints carried through from the wire (rms, vad, transcript hints ...).
+    hints: dict[str, object] = field(default_factory=dict)
+    #: Client correlation id (OpenAI ``event_id``), echoed on error events.
+    event_id: str | None = None
+
+
+# ---- speech hints ----
+
+
+def input_explicitly_non_speech(event: Mapping[str, object]) -> bool:
+    for key in ("is_speech", "speech"):
+        value = event.get(key)
+        if isinstance(value, bool):
+            return not value
+    vad = event.get("vad")
+    if isinstance(vad, dict):
+        value = vad.get("is_speech")
+        if isinstance(value, bool):
+            return not value
+        probability = vad.get("speech_probability", vad.get("probability"))
+        if isinstance(probability, int | float):
+            return float(probability) < 0.5
+    probability = event.get("speech_probability")
+    return isinstance(probability, int | float) and float(probability) < 0.5
+
+
+def input_looks_like_speech(
+    event: Mapping[str, object],
+    *,
+    audio: object,
+    fmt: object,
+    overlap_silence_rms: float,
+) -> bool:
+    if input_explicitly_non_speech(event):
+        return False
+    for key in ("is_speech", "speech"):
+        value = event.get(key)
+        if isinstance(value, bool):
+            return value
+    vad = event.get("vad")
+    if isinstance(vad, dict):
+        probability = vad.get("speech_probability", vad.get("probability"))
+        if isinstance(probability, int | float):
+            return float(probability) >= 0.5
+    probability = event.get("speech_probability")
+    if isinstance(probability, int | float):
+        return float(probability) >= 0.5
+    if fmt != "pcm_f32le":
+        return True
+    if isinstance(audio, bytes | bytearray):
+        raw = bytes(audio)
+    elif isinstance(audio, str):
+        try:
+            raw = base64.b64decode(audio, validate=True)
+        except (binascii.Error, ValueError):
+            return True
+    else:
+        return True
+    if len(raw) < 4 or len(raw) % 4 != 0:
+        return True
+    samples = np.frombuffer(raw, dtype=np.float32)
+    if samples.size == 0:
+        return False
+    rms = float(np.sqrt(np.mean(np.square(samples.astype(np.float32)))))
+    threshold = event.get("overlap_silence_rms")
+    if not isinstance(threshold, int | float):
+        vad = event.get("vad")
+        if isinstance(vad, dict):
+            threshold = vad.get("silence_rms")
+    silence_rms = float(threshold) if isinstance(threshold, int | float) else overlap_silence_rms
+    return rms >= max(0.0, silence_rms)
+
+
+def copy_realtime_input_hints(source: Mapping[str, object], target: dict[str, object]) -> None:
+    for key in REALTIME_INPUT_HINT_KEYS:
+        if key in source:
+            target[key] = source[key]
+
+
+# ---- append decoding ----
+
+
+def decode_audio_append(
+    event: Mapping[str, object],
+    *,
+    defaults: RealtimeInputDefaults,
+    hints_source: Mapping[str, object] | None = None,
+) -> RealtimeAudioAppend:
+    """Validate, convert (to 16 kHz ``pcm_f32le``) and pack one audio append.
+
+    ``hints_source`` is the enclosing payload when the audio arrives inside
+    something larger than a bare append --- a ``conversation.item.create``
+    audio part, say --- so its hints apply unless the part overrides them.
+
+    Raises :class:`RealtimeProtocolError` for an unsupported format, undecodable
+    audio or invalid camera frames.
+    """
+    event_id = cast("str", event.get("event_id")) if isinstance(event.get("event_id"), str) else None
+    audio = event.get("audio") or event.get("delta")
+    fmt, format_rate = parse_realtime_audio_format(
+        event.get("format") or event.get("input_audio_format") or defaults.input_audio_format
+    )
+    sample_rate_hz = (
+        event.get("sample_rate_hz") or event.get("sample_rate") or format_rate or defaults.input_sample_rate_hz
+    )
+    if not is_supported_realtime_input_format(fmt):
+        raise RealtimeProtocolError(
+            f"Unsupported input_audio_format: {fmt}",
+            code="unsupported_audio_format",
+            event_id=event_id,
+        )
+    try:
+        audio, fmt, sample_rate_hz = convert_input_audio_with_rate(
+            audio,
+            fmt,
+            sample_rate_hz=sample_rate_hz if isinstance(sample_rate_hz, int | float) else None,
+        )
+    except ValueError as exc:
+        raise RealtimeProtocolError(str(exc), code="bad_event", event_id=event_id) from exc
+    hints: dict[str, object] = {}
+    if hints_source is not None:
+        copy_realtime_input_hints(hints_source, hints)
+    copy_realtime_input_hints(event, hints)
+    looks_like_speech = input_looks_like_speech(
+        {**(hints_source or {}), **event},
+        audio=audio,
+        fmt=fmt,
+        overlap_silence_rms=defaults.overlap_silence_rms,
+    )
+    video_frames: tuple[str, ...] = ()
+    raw_frames = event.get("video_frames")
+    if raw_frames is not None:
+        frames_error = validate_realtime_video_frames(raw_frames, event.get("max_slice_nums"))
+        if frames_error is not None:
+            raise RealtimeProtocolError(frames_error, code="invalid_video_frames", event_id=event_id)
+        if isinstance(raw_frames, list):
+            video_frames = tuple(frame for frame in raw_frames if isinstance(frame, str) and frame)
+    duration_ms = hints.get("duration_ms", hints.get("audio_duration_ms"))
+    audio_end_ms = hints.get("audio_end_ms")
+    try:
+        audio_bytes = base64.b64decode(audio, validate=True) if isinstance(audio, str) and audio else b""
+    except (binascii.Error, ValueError) as exc:
+        raise RealtimeProtocolError("input audio is not valid base64", code="bad_audio", event_id=event_id) from exc
+    return RealtimeAudioAppend(
+        event_id=event_id,
+        audio=audio_bytes,
+        format=str(fmt),
+        sample_rate_hz=int(sample_rate_hz) if isinstance(sample_rate_hz, int | float) else None,
+        is_speech=looks_like_speech,
+        video_frames=video_frames,
+        duration_ms=int(duration_ms) if isinstance(duration_ms, int | float) else None,
+        audio_end_ms=int(audio_end_ms) if isinstance(audio_end_ms, int | float) else None,
+        hints=hints,
+    )
diff --git a/vllm_omni/protocol/realtime/capabilities.py b/vllm_omni/protocol/realtime/capabilities.py
new file mode 100644
index 00000000000..658a57e56bb
--- /dev/null
+++ b/vllm_omni/protocol/realtime/capabilities.py
@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""What a Realtime consumer can serve, and the session check that reads it.
+
+``session.update`` is the one client event whose acceptance depends on who is
+behind the socket. The audio formats a server can decode, and whether it can do
+server-side turn detection at all, are properties of the *consumer* --- the
+duplex engine, or some other runtime --- not of the protocol. The codec still
+has to do the checking, because it owns the error envelope and the order the
+checks run in.
+
+:class:`RealtimeProtocolCapabilities` is how a consumer states those answers.
+It is the post-#7413 form of the ``supports(turn_detection, formats)`` half of
+RFC #6592's proposed ``RealtimeModelAdapter``. The other three halves of that
+proposal --- building a prompt, starting a response, cancelling one --- are not
+here and must not come here: for a duplex model they are already owned by
+``DuplexModelPlugin`` together with ``DuplexSessionRunner``, and a second
+interface over the same responsibility is exactly the fork this layer exists to
+prevent.
+
+The duplex binding of this object is
+``vllm_omni.engine.duplex.realtime_commands.DUPLEX_REALTIME_CAPABILITIES``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+
+from vllm_omni.protocol.realtime.formats import (
+    REALTIME_INPUT_AUDIO_FORMATS,
+    REALTIME_OUTPUT_AUDIO_FORMATS,
+    validate_realtime_session_audio_formats,
+)
+
+__all__ = [
+    "RealtimeProtocolCapabilities",
+    "RealtimeSessionRejection",
+    "validate_session_payload",
+]
+
+#: A consumer's answer to "can you do this turn detection?": an error message, or None.
+TurnDetectionValidator = Callable[[Mapping[str, object]], str | None]
+
+
+@dataclass(frozen=True, slots=True)
+class RealtimeProtocolCapabilities:
+    """One consumer's answer to what a ``session`` object may ask for.
+
+    The defaults are permissive, not restrictive: every format the codec can
+    decode, and **no turn-detection validation at all**. A consumer that leaves
+    ``validate_turn_detection`` at ``None`` therefore accepts whatever
+    ``turn_detection`` the session object carries --- including values it cannot
+    actually serve, such as ``semantic_vad``. A consumer that supports only some
+    turn-detection modes (or none) must supply its own validator; see
+    ``vllm_omni.engine.duplex.realtime_commands.DUPLEX_REALTIME_CAPABILITIES``.
+    """
+
+    input_audio_formats: frozenset[str] = field(default_factory=lambda: frozenset(REALTIME_INPUT_AUDIO_FORMATS))
+    output_audio_formats: frozenset[str] = field(default_factory=lambda: frozenset(REALTIME_OUTPUT_AUDIO_FORMATS))
+    #: Consumer-specific ``turn_detection`` validation. ``None`` means the
+    #: consumer takes whatever the session object says without a check of its own.
+    validate_turn_detection: TurnDetectionValidator | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RealtimeSessionRejection:
+    """Why a session object was refused: the internal error code and the message.
+
+    ``param`` names the offending session field where there is one, for the
+    ``error.param`` slot of the OpenAI error envelope.
+    """
+
+    code: str
+    message: str
+    param: str | None = None
+
+
+def validate_session_payload(
+    session_payload: Mapping[str, object],
+    *,
+    capabilities: RealtimeProtocolCapabilities,
+) -> RealtimeSessionRejection | None:
+    """Check a ``session`` object against one consumer; ``None`` when it is acceptable.
+
+    Audio formats are checked before turn detection, so a session object that
+    is wrong in both ways reports the format problem --- keep that order, it is
+    what clients already see.
+    """
+    format_error = validate_realtime_session_audio_formats(
+        session_payload,
+        input_audio_formats=capabilities.input_audio_formats,
+        output_audio_formats=capabilities.output_audio_formats,
+    )
+    if format_error is not None:
+        return RealtimeSessionRejection(code="unsupported_audio_format", message=format_error)
+    validate_turn_detection = capabilities.validate_turn_detection
+    if validate_turn_detection is not None:
+        turn_detection_error = validate_turn_detection(session_payload)
+        if turn_detection_error is not None:
+            return RealtimeSessionRejection(
+                code="unsupported_turn_detection", message=turn_detection_error, param="turn_detection"
+            )
+    return None
diff --git a/vllm_omni/protocol/realtime/commands.py b/vllm_omni/protocol/realtime/commands.py
new file mode 100644
index 00000000000..590f3ee93a6
--- /dev/null
+++ b/vllm_omni/protocol/realtime/commands.py
@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""OpenAI Realtime client events as typed commands.
+
+A Realtime server's first job is turning a client JSON event into something
+typed. These are the 10 client events OpenAI's Realtime API defines, as frozen
+dataclasses carrying the fields that survive decoding.
+
+vLLM-Omni's own client events (barge-in, playback acknowledgement, text append,
+heartbeat, explicit close, generic turn signals) are a separate vocabulary in
+``vllm_omni.protocol.duplex.commands``.
+
+Decoding a payload *into* these stays with the consumer, because which command
+a given event becomes can depend on what that consumer supports --- see
+``vllm_omni.engine.duplex.realtime_commands.translate_realtime_command``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RealtimeCommand:
+    """One decoded OpenAI Realtime client event.
+
+    ``wire_type`` is the event type the client sent; the typed fields are what
+    survived decoding, so a consumer reads them instead of re-parsing JSON.
+
+    There is deliberately no rendering method here. A server receives commands,
+    it does not emit them, and how a runtime represents one internally is its
+    own business --- the duplex engine renders its mailbox dictionary in
+    ``vllm_omni.engine.duplex.commands``.
+    """
+
+    #: OpenAI Realtime client event this command decodes from.
+    wire_type: ClassVar[str] = ""
+    #: Client correlation id (OpenAI ``event_id``), echoed on error events.
+    event_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class UpdateSession(RealtimeCommand):
+    """``session.update``: a Realtime ``session`` object patch."""
+
+    wire_type: ClassVar[str] = "session.update"
+    patch: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AppendAudio(RealtimeCommand):
+    wire_type: ClassVar[str] = "input_audio_buffer.append"
+    #: Raw audio bytes in ``format`` at ``sample_rate_hz`` (base64 only on the wire).
+    audio: bytes
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Commit(RealtimeCommand):
+    wire_type: ClassVar[str] = "input_audio_buffer.commit"
+    final: bool = True
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClearInput(RealtimeCommand):
+    wire_type: ClassVar[str] = "input_audio_buffer.clear"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ClearOutputAudio(RealtimeCommand):
+    wire_type: ClassVar[str] = "output_audio_buffer.clear"
+    #: Explicit response to clear; ``None`` targets the active/last response.
+    response_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CreateResponse(RealtimeCommand):
+    wire_type: ClassVar[str] = "response.create"
+    #: Raw Realtime ``response`` object (instructions, voice, modalities, ...).
+    options: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CancelResponse(RealtimeCommand):
+    wire_type: ClassVar[str] = "response.cancel"
+    response_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CreateItem(RealtimeCommand):
+    """``conversation.item.create`` (history injection or function-call output)."""
+
+    wire_type: ClassVar[str] = "conversation.item.create"
+    item: Mapping[str, object]
+    previous_item_id: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class DeleteItem(RealtimeCommand):
+    wire_type: ClassVar[str] = "conversation.item.delete"
+    item_id: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TruncateItem(RealtimeCommand):
+    wire_type: ClassVar[str] = "conversation.item.truncate"
+    item_id: str
+    audio_end_ms: int
+    content_index: int = 0
+
+
+__all__ = [
+    "AppendAudio",
+    "CancelResponse",
+    "ClearInput",
+    "ClearOutputAudio",
+    "Commit",
+    "CreateItem",
+    "CreateResponse",
+    "DeleteItem",
+    "RealtimeCommand",
+    "TruncateItem",
+    "UpdateSession",
+]
diff --git a/vllm_omni/protocol/realtime/errors.py b/vllm_omni/protocol/realtime/errors.py
new file mode 100644
index 00000000000..f9ba67bf4ed
--- /dev/null
+++ b/vllm_omni/protocol/realtime/errors.py
@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""The OpenAI Realtime error envelope.
+
+A Realtime server reports a rejected client event as one ``error`` event whose
+``error`` object carries ``type`` / ``code`` / ``message`` (plus the client's
+``event_id`` and an optional ``param``). ``type`` is not free-form: it is one
+of OpenAI's four buckets, derived from our internal code by
+:data:`REALTIME_ERROR_TYPES_BY_CODE`.
+
+OpenAI standardises the three ``type`` classes but not the *codes*, so the code
+vocabulary is a consumer's own. vLLM-Omni's lives in
+``vllm_omni.protocol.duplex.errors`` (Tier 3 in
+``docs/serving/realtime_duplex_api.md``); what stays here is the exception type
+every consumer raises, so the envelope is rendered identically whoever built it.
+"""
+
+from __future__ import annotations
+
+__all__ = ["RealtimeProtocolError"]
+
+
+class RealtimeProtocolError(ValueError):
+    """A client payload could not be decoded into a valid Realtime intent.
+
+    ``code`` is the internal error code that :data:`REALTIME_ERROR_TYPES_BY_CODE`
+    maps to an OpenAI ``error.type``; ``event_id`` is the *client* event id the
+    error answers. ``vllm_omni.engine.duplex.commands.DuplexCommandError`` is
+    the duplex specialization, so a consumer catching either sees the same
+    three attributes.
+    """
+
+    def __init__(self, message: str, *, code: str = "bad_event", event_id: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.event_id = event_id
diff --git a/vllm_omni/protocol/realtime/events.py b/vllm_omni/protocol/realtime/events.py
new file mode 100644
index 00000000000..47bab63724a
--- /dev/null
+++ b/vllm_omni/protocol/realtime/events.py
@@ -0,0 +1,467 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""OpenAI Realtime server events: typed classes and their wire rendering.
+
+Every event is a frozen dataclass with explicit fields, and the Realtime wire
+JSON is *derived* from those fields by :meth:`RealtimeEvent.to_realtime`. That
+rendering is pure --- it never consults session state --- which is why it can
+live here, away from whoever owns the session. The stateful part (response and
+item ids, content-part bookkeeping) is consumed when the events are
+*constructed*, by the consumer.
+
+This module holds the 30 events OpenAI's Realtime API defines. vLLM-Omni's own
+additions to the wire (listen/speak turn-taking, playback acknowledgement,
+session resume) are a separate vocabulary in
+``vllm_omni.protocol.duplex.events``, so a consumer that only speaks GA does
+not inherit them.
+
+``session_id`` / ``epoch`` are bound by the consumer when an event leaves it;
+producers build events with the defaults.
+"""
+
+from __future__ import annotations
+
+import base64
+from collections.abc import Mapping
+from dataclasses import dataclass, field, fields
+from typing import ClassVar
+from uuid import uuid4
+
+
+def new_event_id() -> str:
+    return f"event_{uuid4().hex}"
+
+
+_IDENTITY_FIELDS = frozenset({"session_id", "epoch", "event_id"})
+
+
+def wire_value(value: object) -> object:
+    if isinstance(value, Mapping):
+        return {str(k): wire_value(v) for k, v in value.items()}
+    if isinstance(value, tuple | list):
+        return [wire_value(v) for v in value]
+    return value
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RealtimeEvent:
+    """Base of every public session event."""
+
+    #: Realtime ``type`` this class renders to.
+    wire_type: ClassVar[str] = ""
+    #: Fields that are omitted from the wire object when ``None``.
+    optional_wire_fields: ClassVar[frozenset[str]] = frozenset()
+
+    session_id: str = ""
+    epoch: int | None = None
+    #: Server event id (OpenAI ``event_id``); generated at construction.
+    event_id: str = field(default_factory=new_event_id)
+
+    # ---- identity ----
+
+    @property
+    def type(self) -> str:
+        return self.wire_type
+
+    @property
+    def is_terminal(self) -> bool:
+        return False
+
+    # ---- generic accessors (None when the class has no such field) ----
+
+    @property
+    def response_id(self) -> str | None:
+        return None
+
+    @property
+    def item_id(self) -> str | None:
+        return None
+
+    @property
+    def text(self) -> str | None:
+        return None
+
+    @property
+    def audio(self) -> bytes | None:
+        return None
+
+    # ---- wire rendering (pure) ----
+
+    def _wire_fields(self) -> dict[str, object]:
+        data: dict[str, object] = {}
+        for f in fields(self):
+            if f.name in _IDENTITY_FIELDS:
+                continue
+            value = getattr(self, f.name)
+            if value is None and f.name in self.optional_wire_fields:
+                continue
+            data[f.name] = wire_value(value)
+        return data
+
+    def to_realtime(self) -> dict[str, object]:
+        """The Realtime wire JSON object for this event (derived from the fields)."""
+        return {"type": self.wire_type, "event_id": self.event_id, **self._wire_fields()}
+
+    def __repr__(self) -> str:  # pragma: no cover - debugging aid
+        return f"{type(self).__name__}(type={self.wire_type!r}, session_id={self.session_id!r}, epoch={self.epoch!r})"
+
+
+# ---- shared bases ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResponseScopedEvent(RealtimeEvent):
+    """Events addressed to one response (and usually one output item / content part)."""
+
+    response_id: str | None = None  # type: ignore[assignment]
+    item_id: str | None = None  # type: ignore[assignment]
+    output_index: int = 0
+    content_index: int = 0
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class _ItemEvent(RealtimeEvent):
+    previous_item_id: str | None = None
+    item: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def item_id(self) -> str | None:
+        value = self.item.get("id")
+        return value if isinstance(value, str) else None
+
+
+# ---- GA server events ----
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionCreated(RealtimeEvent):
+    wire_type = "session.created"
+
+    session: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SessionUpdated(RealtimeEvent):
+    wire_type = "session.updated"
+
+    session: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResponseCreated(RealtimeEvent):
+    wire_type = "response.created"
+
+    response: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OutputItemAdded(RealtimeEvent):
+    wire_type = "response.output_item.added"
+
+    response_id: str | None = None  # type: ignore[assignment]
+    output_index: int = 0
+    item: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def item_id(self) -> str | None:
+        value = self.item.get("id")
+        return value if isinstance(value, str) else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OutputItemDone(OutputItemAdded):
+    wire_type = "response.output_item.done"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ContentPartAdded(ResponseScopedEvent):
+    wire_type = "response.content_part.added"
+
+    part: Mapping[str, object] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ContentPartDone(ContentPartAdded):
+    wire_type = "response.content_part.done"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AudioDelta(ResponseScopedEvent):
+    wire_type = "response.output_audio.delta"
+
+    #: Base64 audio in ``format``.
+    delta: str = ""
+
+    @property
+    def audio(self) -> bytes | None:
+        try:
+            return base64.b64decode(self.delta)
+        except (ValueError, TypeError):
+            return None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AudioDone(ResponseScopedEvent):
+    wire_type = "response.output_audio.done"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TranscriptDelta(ResponseScopedEvent):
+    wire_type = "response.output_audio_transcript.delta"
+
+    delta: str = ""
+
+    @property
+    def text(self) -> str | None:
+        return self.delta
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TranscriptDone(ResponseScopedEvent):
+    wire_type = "response.output_audio_transcript.done"
+
+    transcript: str = ""
+
+    @property
+    def text(self) -> str | None:
+        return self.transcript
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TextDelta(ResponseScopedEvent):
+    wire_type = "response.output_text.delta"
+
+    delta: str = ""
+
+    @property
+    def text(self) -> str | None:
+        return self.delta
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TextDone(ResponseScopedEvent):
+    wire_type = "response.output_text.done"
+
+    text: str = ""  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FunctionCallArgumentsDelta(RealtimeEvent):
+    wire_type = "response.function_call_arguments.delta"
+
+    response_id: str | None = None  # type: ignore[assignment]
+    item_id: str | None = None  # type: ignore[assignment]
+    output_index: int = 0
+    call_id: str = ""
+    delta: str = ""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class FunctionCallArgumentsDone(RealtimeEvent):
+    wire_type = "response.function_call_arguments.done"
+
+    response_id: str | None = None  # type: ignore[assignment]
+    item_id: str | None = None  # type: ignore[assignment]
+    output_index: int = 0
+    call_id: str = ""
+    arguments: str = ""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ResponseDone(RealtimeEvent):
+    wire_type = "response.done"
+
+    response: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def status(self) -> str | None:
+        value = self.response.get("status")
+        return value if isinstance(value, str) else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RateLimitsUpdated(RealtimeEvent):
+    wire_type = "rate_limits.updated"
+
+    rate_limits: tuple[Mapping[str, object], ...] = ()
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InputCommitted(RealtimeEvent):
+    wire_type = "input_audio_buffer.committed"
+
+    previous_item_id: str | None = None
+    item_id: str | None = None  # type: ignore[assignment]
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"previous_item_id": self.previous_item_id, "item_id": self.item_id}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InputCleared(RealtimeEvent):
+    wire_type = "input_audio_buffer.cleared"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SpeechStarted(RealtimeEvent):
+    wire_type = "input_audio_buffer.speech_started"
+
+    audio_start_ms: int = 0
+    item_id: str | None = None  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SpeechStopped(RealtimeEvent):
+    wire_type = "input_audio_buffer.speech_stopped"
+
+    audio_end_ms: int = 0
+    item_id: str | None = None  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemAdded(_ItemEvent):
+    wire_type = "conversation.item.added"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemCreated(_ItemEvent):
+    wire_type = "conversation.item.created"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemDone(_ItemEvent):
+    wire_type = "conversation.item.done"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemRetrieved(RealtimeEvent):
+    wire_type = "conversation.item.retrieved"
+
+    item: Mapping[str, object] = field(default_factory=dict)
+
+    @property
+    def item_id(self) -> str | None:
+        value = self.item.get("id")
+        return value if isinstance(value, str) else None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemDeleted(RealtimeEvent):
+    wire_type = "conversation.item.deleted"
+
+    item_id: str | None = None  # type: ignore[assignment]
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"item_id": self.item_id}
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ItemTruncated(RealtimeEvent):
+    wire_type = "conversation.item.truncated"
+
+    item_id: str | None = None  # type: ignore[assignment]
+    content_index: int = 0
+    audio_end_ms: int = 0
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {
+            "item_id": self.item_id,
+            "content_index": self.content_index,
+            "audio_end_ms": self.audio_end_ms,
+        }
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class InputTranscriptionCompleted(RealtimeEvent):
+    wire_type = "conversation.item.input_audio_transcription.completed"
+
+    item_id: str | None = None  # type: ignore[assignment]
+    content_index: int = 0
+    transcript: str = ""
+
+    @property
+    def text(self) -> str | None:
+        return self.transcript
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class OutputAudioCleared(RealtimeEvent):
+    wire_type = "output_audio_buffer.cleared"
+
+    response_id: str | None = None  # type: ignore[assignment]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class ErrorEvent(RealtimeEvent):
+    wire_type = "error"
+
+    code: str = "internal_error"
+    message: str = ""
+    #: Client ``event_id`` this error answers (OpenAI ``error.event_id``).
+    related_event_id: str | None = None
+    param: str | None = None
+
+    @property
+    def error_type(self) -> str:
+        """OpenAI's error class for this error.
+
+        OpenAI standardises only the three classes, not the codes, so the base
+        reports the default. A consumer with its own code vocabulary overrides
+        this --- see ``vllm_omni.protocol.duplex.events.ErrorEvent``.
+        """
+        return "invalid_request_error"
+
+    @property
+    def error(self) -> dict[str, object]:
+        error: dict[str, object] = {"type": self.error_type, "code": self.code, "message": self.message}
+        if self.related_event_id:
+            error["event_id"] = self.related_event_id
+        if self.param:
+            error["param"] = self.param
+        return error
+
+    @property
+    def text(self) -> str | None:
+        return self.message
+
+    def _wire_fields(self) -> dict[str, object]:
+        return {"error": self.error}
+
+
+__all__ = [
+    "AudioDelta",
+    "AudioDone",
+    "ContentPartAdded",
+    "ContentPartDone",
+    "ErrorEvent",
+    "FunctionCallArgumentsDelta",
+    "FunctionCallArgumentsDone",
+    "InputCleared",
+    "InputCommitted",
+    "InputTranscriptionCompleted",
+    "ItemAdded",
+    "ItemCreated",
+    "ItemDeleted",
+    "ItemDone",
+    "ItemRetrieved",
+    "ItemTruncated",
+    "OutputAudioCleared",
+    "OutputItemAdded",
+    "OutputItemDone",
+    "RateLimitsUpdated",
+    "RealtimeEvent",
+    "ResponseCreated",
+    "ResponseDone",
+    "ResponseScopedEvent",
+    "SessionCreated",
+    "SessionUpdated",
+    "SpeechStarted",
+    "SpeechStopped",
+    "TextDelta",
+    "TextDone",
+    "TranscriptDelta",
+    "TranscriptDone",
+    "new_event_id",
+    "wire_value",
+]
diff --git a/vllm_omni/protocol/realtime/formats.py b/vllm_omni/protocol/realtime/formats.py
new file mode 100644
index 00000000000..161aab11bea
--- /dev/null
+++ b/vllm_omni/protocol/realtime/formats.py
@@ -0,0 +1,177 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Realtime audio-format negotiation: what a client may declare and how it is read.
+
+A Realtime client declares audio formats in three places --- the session object
+(``session.audio.input.format`` and the older flat ``input_audio_format``), a
+``response.create`` override, and a ``conversation.item.create`` audio part ---
+and may spell one format several ways (``audio/pcm``, ``pcm16``, ``s16le``).
+This module is the single place that normalizes those spellings and says which
+are supported. Folding a session's declaration into the per-connection append
+defaults is the job of ``session.py``, which builds on this module.
+
+Everything here is a pure function of wire payloads: no session state, no model,
+no engine.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Collection, Mapping
+
+__all__ = [
+    "REALTIME_INPUT_AUDIO_FORMATS",
+    "REALTIME_OUTPUT_AUDIO_FORMATS",
+    "is_supported_realtime_input_format",
+    "parse_realtime_audio_format",
+    "realtime_audio_format_object",
+    "realtime_output_format",
+    "validate_conversation_item_audio_formats",
+    "validate_realtime_response_audio_formats",
+    "validate_realtime_session_audio_formats",
+]
+
+REALTIME_INPUT_AUDIO_FORMATS = {
+    "pcm16",
+    "pcm_s16le",
+    "s16le",
+    "pcm_f32le",
+    "g711_ulaw",
+    "g711_alaw",
+}
+REALTIME_OUTPUT_AUDIO_FORMATS = {
+    "pcm16",
+    "pcm_s16le",
+    "s16le",
+    "wav",
+    "pcm",
+    "g711_ulaw",
+    "g711_alaw",
+}
+
+
+def parse_realtime_audio_format(raw_format: object) -> tuple[object, int | None]:
+    def normalize_format(fmt: str) -> str:
+        normalized = fmt.lower()
+        if normalized in {"audio/pcm", "pcm"}:
+            return "pcm16"
+        if normalized in {"audio/wav", "wav"}:
+            return "wav"
+        if normalized in {"audio/pcm16", "pcm16", "pcm_s16le", "s16le"}:
+            return "pcm16"
+        if normalized in {"audio/pcm_f32le", "pcm_f32le", "f32le"}:
+            return "pcm_f32le"
+        if normalized in {"audio/g711_ulaw", "g711_ulaw", "g711-ulaw", "ulaw", "mulaw"}:
+            return "g711_ulaw"
+        if normalized in {"audio/g711_alaw", "g711_alaw", "g711-alaw", "alaw"}:
+            return "g711_alaw"
+        return fmt
+
+    if isinstance(raw_format, str):
+        return normalize_format(raw_format), None
+    if not isinstance(raw_format, dict):
+        return raw_format, None
+    rate = raw_format.get("rate") or raw_format.get("sample_rate_hz") or raw_format.get("sample_rate")
+    sample_rate_hz = int(rate) if isinstance(rate, int | float) and rate > 0 else None
+    fmt = raw_format.get("type") or raw_format.get("format")
+    if not isinstance(fmt, str):
+        return raw_format, sample_rate_hz
+    return normalize_format(fmt), sample_rate_hz
+
+
+def realtime_output_format(duplex_format: object) -> str:
+    if isinstance(duplex_format, str) and duplex_format.lower() in {"g711_ulaw", "g711_alaw"}:
+        return duplex_format.lower()
+    if isinstance(duplex_format, str) and duplex_format.lower() == "pcm":
+        return "pcm16"
+    return str(duplex_format or "wav")
+
+
+def is_supported_realtime_input_format(fmt: object) -> bool:
+    return isinstance(fmt, str) and fmt.lower() in REALTIME_INPUT_AUDIO_FORMATS
+
+
+def realtime_audio_format_object(fmt: object, *, sample_rate_hz: int | None = None) -> dict[str, object]:
+    if isinstance(fmt, str) and fmt.lower() in {"pcm16", "pcm_s16le", "s16le", "pcm"}:
+        payload: dict[str, object] = {"type": "audio/pcm"}
+    elif isinstance(fmt, str) and fmt.lower() == "pcm_f32le":
+        payload = {"type": "audio/pcm_f32le"}
+    elif isinstance(fmt, str) and fmt.lower() == "g711_ulaw":
+        payload = {"type": "audio/g711_ulaw"}
+    elif isinstance(fmt, str) and fmt.lower() == "g711_alaw":
+        payload = {"type": "audio/g711_alaw"}
+    else:
+        payload = {"type": "audio/wav"}
+    if sample_rate_hz is not None:
+        payload["rate"] = int(sample_rate_hz)
+    return payload
+
+
+def validate_realtime_session_audio_formats(
+    session_payload: Mapping[str, object],
+    *,
+    input_audio_formats: Collection[str] | None = None,
+    output_audio_formats: Collection[str] | None = None,
+) -> str | None:
+    """Reject a session object that declares an audio format we cannot serve.
+
+    The format sets default to everything the codec can decode; a consumer that
+    serves a narrower set passes its own (see
+    ``vllm_omni.protocol.realtime.capabilities``).
+    """
+    supported_input = REALTIME_INPUT_AUDIO_FORMATS if input_audio_formats is None else input_audio_formats
+    supported_output = REALTIME_OUTPUT_AUDIO_FORMATS if output_audio_formats is None else output_audio_formats
+    audio_config = session_payload.get("audio")
+    input_format: object = session_payload.get("input_audio_format")
+    if input_format is None and isinstance(audio_config, dict):
+        audio_input = audio_config.get("input")
+        if isinstance(audio_input, dict):
+            input_format = audio_input.get("format")
+    parsed_input, _ = parse_realtime_audio_format(input_format)
+    if input_format is not None and not (isinstance(parsed_input, str) and parsed_input.lower() in supported_input):
+        return f"Unsupported input_audio_format: {input_format}"
+
+    output_format: object = session_payload.get("output_audio_format") or session_payload.get("response_format")
+    if output_format is None and isinstance(audio_config, dict):
+        audio_output = audio_config.get("output")
+        if isinstance(audio_output, dict):
+            output_format = audio_output.get("format")
+    parsed_output, _ = parse_realtime_audio_format(output_format)
+    if output_format is not None and not (isinstance(parsed_output, str) and parsed_output.lower() in supported_output):
+        return f"Unsupported output_audio_format: {output_format}"
+    return None
+
+
+def validate_realtime_response_audio_formats(response_payload: Mapping[str, object]) -> str | None:
+    output_format: object = response_payload.get("output_audio_format") or response_payload.get("response_format")
+    audio_config = response_payload.get("audio")
+    if output_format is None and isinstance(audio_config, dict):
+        audio_output = audio_config.get("output")
+        if isinstance(audio_output, dict):
+            output_format = audio_output.get("format")
+    parsed_output, _ = parse_realtime_audio_format(output_format)
+    if output_format is not None and not (
+        isinstance(parsed_output, str) and parsed_output.lower() in REALTIME_OUTPUT_AUDIO_FORMATS
+    ):
+        return f"Unsupported output_audio_format: {output_format}"
+    return None
+
+
+def validate_conversation_item_audio_formats(item: object) -> str | None:
+    if not isinstance(item, dict):
+        return None
+    content = item.get("content")
+    if not isinstance(content, list):
+        return None
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        if part.get("type") not in {"input_audio", "audio"}:
+            continue
+        raw_format = part.get("format")
+        parsed_format, _ = parse_realtime_audio_format(raw_format)
+        if raw_format is not None and not (
+            isinstance(parsed_format, str) and parsed_format.lower() in REALTIME_INPUT_AUDIO_FORMATS
+        ):
+            return f"Unsupported input_audio format in conversation.item.create: {raw_format}"
+    return None
diff --git a/vllm_omni/protocol/realtime/items.py b/vllm_omni/protocol/realtime/items.py
new file mode 100644
index 00000000000..cbcb9c6527f
--- /dev/null
+++ b/vllm_omni/protocol/realtime/items.py
@@ -0,0 +1,197 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Realtime conversation items: shape, truncation and the transcript inside one.
+
+A Realtime conversation is a list of *items* --- a user message, an assistant
+message, a function call --- each with a ``content`` list of typed parts. The
+client creates them (``conversation.item.create``), truncates an assistant
+item's audio after a barge-in (``conversation.item.truncate``), and the server
+echoes them back inside ``conversation.item.*`` and ``response.done`` events.
+
+The rules in this module are the ones both sides have to agree on: which
+defaults a bare item gets, how far a transcript is cut when the client says it
+only heard N milliseconds of audio, and what makes a truncate request invalid.
+Item *storage* --- which items a session currently holds, in what order --- is
+the consumer's state, not this module's.
+
+``validate_realtime_video_frames`` sits here too: camera frames ride along an
+``input_audio_buffer.append`` in the vLLM-Omni extension of the protocol, and
+validating them is the same kind of wire-shape check.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from collections.abc import Mapping
+from uuid import uuid4
+
+__all__ = [
+    "input_transcript_from_item",
+    "normalize_conversation_item",
+    "text_chars_for_audio_ms_from_marks",
+    "truncate_realtime_item_content",
+    "validate_realtime_item_truncate",
+    "validate_realtime_video_frames",
+]
+
+
+def validate_realtime_video_frames(video_frames: object, max_slice_nums: object) -> str | None:
+    """Validate omni-duplex camera frames on input_audio_buffer.append.
+
+    Wire contract matches the official MiniCPM-o duplex loop: one base
+    base64 JPEG per ~1 s audio chunk, optionally followed by that unit's
+    stacked composite tiling the sub-frames captured inside it (at most 2
+    images either way). A caller-supplied ``max_slice_nums`` is rejected rather
+    than silently ignored: slicing is Stage 0's decision here, and Stage 0
+    already applies the official HD suggestion for a stacked unit
+    (``max_slice_nums=[2, 1]``). The wire simply does not let the client choose
+    it.
+    """
+    if max_slice_nums not in (None, 1):
+        return "max_slice_nums is not selectable on the wire; Stage0 slices stacked units itself"
+    if not isinstance(video_frames, list):
+        return "video_frames must be a list of base64-encoded images"
+    frames = [frame for frame in video_frames if frame is not None]
+    if len(frames) > 2:
+        return "video_frames carries more than 2 frames for one append; send ~1 frame per 1 s chunk"
+    for frame in frames:
+        if not isinstance(frame, str) or not frame:
+            return "video_frames entries must be non-empty base64 strings"
+        if len(frame) > 4_000_000:
+            return "video_frames entry exceeds 4MB base64; reduce capture resolution or JPEG quality"
+        try:
+            header = base64.b64decode(frame[:64] + "=" * (-len(frame[:64]) % 4))
+        except (binascii.Error, ValueError):
+            return "video_frames entries must be valid base64"
+        if not (header.startswith(b"\xff\xd8") or header.startswith(b"\x89PNG")):
+            return "video_frames entries must be JPEG or PNG images"
+    return None
+
+
+def normalize_conversation_item(item: Mapping[str, object]) -> dict[str, object]:
+    normalized = dict(item)
+    normalized.setdefault("id", f"item_{uuid4().hex}")
+    normalized.setdefault("object", "realtime.item")
+    normalized.setdefault("type", "message")
+    normalized.setdefault("status", "completed")
+    if "role" not in normalized and normalized.get("type") == "message":
+        normalized["role"] = "user"
+    if not isinstance(normalized.get("content"), list):
+        normalized["content"] = []
+    return normalized
+
+
+def text_chars_for_audio_ms_from_marks(
+    audio_end_ms: int,
+    text_len: int,
+    marks: list[object],
+    *,
+    final_ms: object | None = None,
+) -> int:
+    if text_len <= 0:
+        return 0
+    clean_marks: list[tuple[int, int]] = []
+    for mark in marks:
+        if not isinstance(mark, dict):
+            continue
+        raw_text_chars = mark.get("text_chars")
+        raw_audio_end_ms = mark.get("audio_end_ms", mark.get("audio_ms"))
+        if not isinstance(raw_text_chars, int | float) or not isinstance(raw_audio_end_ms, int | float):
+            continue
+        clean_marks.append((max(0, int(raw_audio_end_ms)), min(text_len, max(0, int(raw_text_chars)))))
+    if not clean_marks:
+        return 0 if audio_end_ms <= 0 else text_len
+    clean_marks.sort(key=lambda item: item[0])
+    audio_end_ms = max(0, int(audio_end_ms))
+    if audio_end_ms <= 0:
+        return 0
+    previous_ms = 0
+    previous_chars = 0
+    for mark_ms, mark_chars in clean_marks:
+        mark_ms = max(previous_ms, mark_ms)
+        mark_chars = max(previous_chars, min(text_len, mark_chars))
+        if audio_end_ms <= mark_ms:
+            if mark_ms <= previous_ms:
+                return mark_chars
+            ratio = (audio_end_ms - previous_ms) / max(1, mark_ms - previous_ms)
+            return int(previous_chars + (mark_chars - previous_chars) * max(0.0, min(1.0, ratio)))
+        previous_ms = mark_ms
+        previous_chars = mark_chars
+    if isinstance(final_ms, int | float) and int(final_ms) > previous_ms:
+        if audio_end_ms >= int(final_ms):
+            return text_len
+        ratio = (audio_end_ms - previous_ms) / max(1, int(final_ms) - previous_ms)
+        return int(previous_chars + (text_len - previous_chars) * max(0.0, min(1.0, ratio)))
+    return text_len if audio_end_ms >= previous_ms else previous_chars
+
+
+def truncate_realtime_item_content(item: dict[str, object], *, content_index: int, audio_end_ms: int) -> None:
+    content = item.get("content")
+    if not isinstance(content, list) or not content:
+        return
+    index = max(0, int(content_index))
+    if index >= len(content):
+        return
+    part = content[index]
+    if not isinstance(part, dict):
+        return
+    transcript = part.get("transcript")
+    if not isinstance(transcript, str) or not transcript:
+        return
+    marks = part.get("audio_text_marks")
+    if isinstance(marks, list):
+        keep_chars = text_chars_for_audio_ms_from_marks(
+            audio_end_ms,
+            len(transcript),
+            marks,
+            final_ms=part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms"),
+        )
+        part["transcript"] = transcript[:keep_chars].rstrip()
+        return
+    duration_ms = part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms")
+    if isinstance(duration_ms, int | float) and duration_ms > 0:
+        keep_chars = int(len(transcript) * max(0.0, min(1.0, int(audio_end_ms) / float(duration_ms))))
+        part["transcript"] = transcript[:keep_chars].rstrip()
+    elif audio_end_ms <= 0:
+        part["transcript"] = ""
+
+
+def validate_realtime_item_truncate(item: Mapping[str, object], *, content_index: int, audio_end_ms: int) -> str | None:
+    if item.get("type") != "message" or item.get("role") != "assistant":
+        return "conversation.item.truncate only supports assistant message items"
+    if audio_end_ms < 0:
+        return "conversation.item.truncate requires non-negative audio_end_ms"
+    content = item.get("content")
+    if not isinstance(content, list) or not content:
+        return None
+    index = max(0, int(content_index))
+    if index >= len(content):
+        return f"conversation.item.truncate content_index out of range: {content_index}"
+    part = content[index]
+    if not isinstance(part, dict):
+        return "conversation.item.truncate target content part is invalid"
+    if part.get("type") not in {"audio", "output_audio"}:
+        return "conversation.item.truncate target content part must be audio"
+    duration_ms = part.get("audio_duration_ms") or part.get("duration_ms") or part.get("audio_ms")
+    if isinstance(duration_ms, int | float) and int(duration_ms) >= 0 and audio_end_ms > int(duration_ms):
+        return "conversation.item.truncate audio_end_ms exceeds item audio duration"
+    return None
+
+
+def input_transcript_from_item(item: Mapping[str, object]) -> str:
+    content = item.get("content")
+    if not isinstance(content, list):
+        return ""
+    parts: list[str] = []
+    for part in content:
+        if not isinstance(part, dict):
+            continue
+        for key in ("transcript", "text"):
+            value = part.get(key)
+            if isinstance(value, str) and value:
+                if part.get("type") in {"input_audio", "audio", "audio_transcript", "transcript"}:
+                    parts.append(value)
+                    break
+    return "".join(parts).strip()
diff --git a/vllm_omni/protocol/realtime/session.py b/vllm_omni/protocol/realtime/session.py
new file mode 100644
index 00000000000..1c73ea9267e
--- /dev/null
+++ b/vllm_omni/protocol/realtime/session.py
@@ -0,0 +1,163 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Reading the Realtime ``session`` object.
+
+``session.update`` carries one JSON object that a client may spell in either of
+two shapes: the GA nest (``session.audio.input.format``,
+``session.audio.output.sample_rate_hz``) or the older flat beta keys
+(``input_audio_format``, ``sample_rate_hz``). Everything downstream --- the
+append decoder, the projection that renders ``session.created`` back out, a
+model's runtime configuration --- has to agree on what a given session object
+means, so the readers live here once.
+
+:class:`RealtimeInputDefaults` is the resolved answer for the input path: the
+format, sample rate and silence threshold an ``input_audio_buffer.append``
+inherits when it omits them. A connection keeps one of these and re-derives it
+on every ``session.update``.
+
+``overlap_policy`` / ``playback_commit_policy`` are vLLM-Omni extension fields
+on the session object rather than GA OpenAI fields. They are read here because
+this module owns what the wire may say; what a server *does* with them is the
+consumer's business.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, replace
+from typing import Any
+
+from vllm_omni.protocol.realtime.formats import (
+    REALTIME_INPUT_AUDIO_FORMATS,
+    REALTIME_OUTPUT_AUDIO_FORMATS,
+    parse_realtime_audio_format,
+    realtime_output_format,
+)
+
+__all__ = [
+    "RealtimeInputDefaults",
+    "apply_realtime_session_defaults",
+    "input_audio_transcription_config",
+    "json_safe_realtime_payload",
+    "realtime_max_output_tokens",
+    "realtime_overlap_fields",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class RealtimeInputDefaults:
+    """Session-level wire defaults an append may omit (derived from the session object)."""
+
+    input_audio_format: str = "pcm16"
+    input_sample_rate_hz: int = 16000
+    output_audio_format: str = "pcm16"
+    output_sample_rate_hz: int | None = None
+    overlap_silence_rms: float = 0.003
+
+    def with_session_payload(self, session_payload: Mapping[str, object]) -> RealtimeInputDefaults:
+        """Return defaults updated from a Realtime ``session`` object (session.update)."""
+        values = apply_realtime_session_defaults(self, session_payload)
+        return values
+
+
+def apply_realtime_session_defaults(
+    defaults: RealtimeInputDefaults,
+    session_payload: Mapping[str, object],
+) -> RealtimeInputDefaults:
+    """Derive the wire defaults a Realtime ``session`` object declares."""
+    input_format: object = session_payload.get("input_audio_format")
+    audio_config = session_payload.get("audio")
+    if input_format is None and isinstance(audio_config, dict):
+        audio_input = audio_config.get("input")
+        if isinstance(audio_input, dict):
+            input_format = audio_input.get("format")
+    input_format, input_rate = parse_realtime_audio_format(input_format)
+    # Any: heterogeneous field values splatted into ``dataclasses.replace`` below.
+    updates: dict[str, Any] = {}
+    if isinstance(input_format, str) and input_format.lower() in REALTIME_INPUT_AUDIO_FORMATS:
+        updates["input_audio_format"] = input_format
+    output_format: object = session_payload.get("output_audio_format") or session_payload.get("response_format")
+    output_rate_raw: object | None = None
+    if output_format is None and isinstance(audio_config, dict):
+        audio_output = audio_config.get("output")
+        if isinstance(audio_output, dict):
+            output_format = audio_output.get("format")
+            output_rate_raw = audio_output.get("sample_rate_hz") or audio_output.get("sample_rate")
+    output_format, output_rate = parse_realtime_audio_format(output_format)
+    if output_rate is None and isinstance(output_rate_raw, int | float) and output_rate_raw > 0:
+        output_rate = int(output_rate_raw)
+    if isinstance(output_format, str) and output_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
+        updates["output_audio_format"] = realtime_output_format(output_format)
+    sample_rate = session_payload.get("sample_rate_hz") or session_payload.get("sample_rate")
+    if sample_rate is None and isinstance(audio_config, dict):
+        audio_input = audio_config.get("input")
+        if isinstance(audio_input, dict):
+            sample_rate = audio_input.get("sample_rate_hz") or audio_input.get("sample_rate")
+    if sample_rate is None:
+        sample_rate = input_rate
+    if isinstance(sample_rate, int | float) and sample_rate > 0:
+        updates["input_sample_rate_hz"] = int(sample_rate)
+    if isinstance(output_rate, int | float) and output_rate > 0:
+        updates["output_sample_rate_hz"] = int(output_rate)
+    overlap_fields = realtime_overlap_fields(session_payload)
+    overlap_silence_rms = overlap_fields.get("overlap_silence_rms")
+    if isinstance(overlap_silence_rms, int | float):
+        updates["overlap_silence_rms"] = max(0.0, float(overlap_silence_rms))
+    return replace(defaults, **updates) if updates else defaults
+
+
+def realtime_overlap_fields(session_payload: Mapping[str, object]) -> dict[str, object]:
+    fields: dict[str, object] = {}
+    if isinstance(session_payload.get("overlap_policy"), str):
+        fields["overlap_policy"] = session_payload["overlap_policy"]
+    for key in ("overlap_short_ack_ms", "overlap_barge_in_ms", "overlap_silence_rms"):
+        value = session_payload.get(key)
+        if isinstance(value, int | float):
+            fields[key] = value
+    if isinstance(session_payload.get("playback_commit_policy"), str):
+        fields["playback_commit_policy"] = session_payload["playback_commit_policy"]
+    return fields
+
+
+def json_safe_realtime_payload(payload: Mapping[str, object]) -> dict[str, object]:
+    clean: dict[str, object] = {}
+    for key, value in payload.items():
+        if key == "extra_body":
+            continue
+        if isinstance(value, str | int | float | bool) or value is None:
+            clean[key] = value
+        elif isinstance(value, dict):
+            clean[key] = json_safe_realtime_payload(value)
+        elif isinstance(value, list):
+            clean[key] = [
+                (json_safe_realtime_payload(item) if isinstance(item, dict) else item)
+                for item in value
+                if isinstance(item, str | int | float | bool | dict) or item is None
+            ]
+    return clean
+
+
+def input_audio_transcription_config(session_payload: Mapping[str, object]) -> dict[str, object] | None:
+    transcription = session_payload.get("input_audio_transcription")
+    if isinstance(transcription, dict):
+        return transcription
+    audio_config = session_payload.get("audio")
+    if not isinstance(audio_config, dict):
+        return None
+    audio_input = audio_config.get("input")
+    if not isinstance(audio_input, dict):
+        return None
+    transcription = audio_input.get("transcription")
+    return transcription if isinstance(transcription, dict) else None
+
+
+def realtime_max_output_tokens(value: object) -> int | None:
+    """Normalize Realtime max output tokens (``"inf"`` -> ``None``)."""
+    if value is None:
+        return None
+    if isinstance(value, str) and value.strip().lower() in {"inf", "infinity", "unlimited"}:
+        return None
+    if isinstance(value, int) and value > 0:
+        return int(value)
+    return None

From f5e4f5fa429ae3b5a8c50e83785900faea1ecc7b Mon Sep 17 00:00:00 2001
From: Tianyao Wu <54675599+twu3202@users.noreply.github.com>
Date: Thu, 17 Sep 2026 18:35:46 +0800
Subject: [PATCH 063/105] [Bugfix][MiniCPM-o] Size the duplex HD slice
 reservation from the frame (#7654)

Signed-off-by: Tianyao Wu <rayroy31@gmail.com>
Co-authored-by: Claude <noreply@anthropic.com>
---
 .../duplex/test_scheduler_token_budget.py     | 245 ++++++++++++++++++
 .../models/minicpmo_4_5/duplex/plugin.py      | 111 ++++++--
 2 files changed, 339 insertions(+), 17 deletions(-)
 create mode 100644 tests/model_executor/models/minicpmo_4_5/duplex/test_scheduler_token_budget.py

diff --git a/tests/model_executor/models/minicpmo_4_5/duplex/test_scheduler_token_budget.py b/tests/model_executor/models/minicpmo_4_5/duplex/test_scheduler_token_budget.py
new file mode 100644
index 00000000000..03072cb33d4
--- /dev/null
+++ b/tests/model_executor/models/minicpmo_4_5/duplex/test_scheduler_token_budget.py
@@ -0,0 +1,245 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""What a duplex append reserves in the scheduler, and why that number.
+
+The reservation is not advisory: ``build_duplex_data_plane_prompt`` turns it
+into ``[scheduler_token_id] * budget``, and a unit whose embeddings outnumber
+its slots has its tail dropped with a warning rather than failing
+(``MiniCPMO45OmniModel.get_input_embeddings``). Over-reserving only wastes
+slots, so every uncertainty here has to resolve upwards.
+
+The camera side depends on HD slicing, which depends on the frame size
+*relative to the checkpoint's normalization tile*. The tile is configuration,
+not a constant, so the cases below drive the arithmetic at more than one tile
+size and check it against ``MiniCPMVImageProcessor.get_sliced_grid`` -- the
+same grid search the checkpoint's own processor runs.
+"""
+
+from __future__ import annotations
+
+import base64
+import io
+from dataclasses import dataclass
+
+import pytest
+from PIL import Image
+
+from vllm_omni.engine.duplex.config import DuplexSessionConfig
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.plugin import (
+    PRIVATE_RUNTIME_CONFIG_KEYS,
+    _apply_default_scheduler_policy,
+    _duplex_vision_tile_pixels,
+    _duplex_vision_tokens,
+    _model_vision_tile_pixels,
+    duplex_scheduler_token_budget,
+)
+from vllm_omni.model_executor.models.minicpmo_4_5.minicpmo_4_5_omni_llm import MiniCPMVImageProcessor
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+TOKENS_PER_BLOCK = 66
+#: ``_official_max_slice_nums`` gives the first frame of a stacked pair 2 and
+#: every other frame 1.
+BASE_FRAME_MAX_SLICES = 2
+#: What the released MiniCPM-o 4.5 checkpoint configures.
+TILE_448 = 448 * 448
+
+SIZES = [(224, 224), (320, 180), (448, 448), (448, 449), (640, 480), (960, 540), (1280, 720), (540, 960)]
+
+
+def _frame(size: tuple[int, int], fmt: str = "JPEG") -> str:
+    buffer = io.BytesIO()
+    Image.new("RGB", size).save(buffer, format=fmt)
+    return base64.b64encode(buffer.getvalue()).decode()
+
+
+def _blocks_the_model_makes(size: tuple[int, int], max_slice_nums: int, scale_resolution: int) -> int:
+    """Source tile plus the HD patches, straight from the model's grid search."""
+    processor = MiniCPMVImageProcessor(scale_resolution=scale_resolution)
+    grid = processor.get_sliced_grid(image_size=size, max_slice_nums=max_slice_nums)
+    return 1 + grid[0] * grid[1] if grid else 1
+
+
+@pytest.mark.parametrize("scale_resolution", [336, 448, 560])
+@pytest.mark.parametrize("size", SIZES, ids=[f"{w}x{h}" for w, h in SIZES])
+@pytest.mark.parametrize("fmt", ["JPEG", "PNG"])
+def test_a_stacked_pair_reserves_what_the_model_slices_it_into(
+    size: tuple[int, int], fmt: str, scale_resolution: int
+) -> None:
+    """The tile comes from the checkpoint, so the arithmetic has to follow it."""
+    frame = _frame(size, fmt)
+    expected_blocks = _blocks_the_model_makes(size, BASE_FRAME_MAX_SLICES, scale_resolution) + _blocks_the_model_makes(
+        size, 1, scale_resolution
+    )
+
+    reserved = _duplex_vision_tokens({"video_frames": [frame, frame]}, tile_pixels=scale_resolution**2)
+
+    assert reserved == expected_blocks * TOKENS_PER_BLOCK
+
+
+def test_a_small_frame_no_longer_reserves_three_hd_blocks() -> None:
+    """A 448x448 frame is one tile, so a stacked pair is two blocks, not four.
+
+    The size-independent count reserved 264 tokens for this pair. 132 of them
+    were for patches the model never produces.
+    """
+    frame = _frame((448, 448))
+
+    assert _duplex_vision_tokens({"video_frames": [frame, frame]}, tile_pixels=TILE_448) == 2 * TOKENS_PER_BLOCK
+
+
+def test_one_tile_is_the_whole_slicing_decision() -> None:
+    """``ceil(w * h / tile)`` capped at 2: a single pixel over the tile slices."""
+
+    def pair(size: tuple[int, int]) -> int:
+        frame = _frame(size)
+        return _duplex_vision_tokens({"video_frames": [frame, frame]}, tile_pixels=TILE_448)
+
+    assert pair((448, 448)) == 2 * TOKENS_PER_BLOCK
+    assert pair((448, 449)) == 4 * TOKENS_PER_BLOCK
+
+
+def test_only_the_first_frame_of_a_pair_is_hd_sliced() -> None:
+    """``_official_max_slice_nums`` is ``[2, 1]``: the composite is never sliced.
+
+    Sizing the wrong half of the pair would pass every same-size case, so the
+    two orders have to disagree.
+    """
+    small, large = _frame((448, 448)), _frame((1280, 720))
+
+    assert _duplex_vision_tokens({"video_frames": [small, large]}, tile_pixels=TILE_448) == 2 * TOKENS_PER_BLOCK
+    assert _duplex_vision_tokens({"video_frames": [large, small]}, tile_pixels=TILE_448) == 4 * TOKENS_PER_BLOCK
+
+
+def test_a_lone_frame_is_never_hd_sliced() -> None:
+    """``_official_max_slice_nums(1)`` is ``[1]``: one frame is one tile at any size."""
+    assert _duplex_vision_tokens({"video_frames": [_frame((1280, 720))]}, tile_pixels=TILE_448) == TOKENS_PER_BLOCK
+
+
+def test_extra_frames_past_the_pair_each_cost_one_block() -> None:
+    """The wire caps a frame list at two; the in-process API does not."""
+    small, large = _frame((448, 448)), _frame((1280, 720))
+
+    assert _duplex_vision_tokens({"video_frames": [small] * 3}, tile_pixels=TILE_448) == 3 * TOKENS_PER_BLOCK
+    assert _duplex_vision_tokens({"video_frames": [large] * 3}, tile_pixels=TILE_448) == 5 * TOKENS_PER_BLOCK
+
+
+def test_an_unknown_tile_size_keeps_the_sliced_reservation() -> None:
+    """No tile, no shrinking. A checkpoint whose config cannot be read keeps the old number."""
+    frame = _frame((224, 224))
+
+    assert _duplex_vision_tokens({"video_frames": [frame, frame]}) == 4 * TOKENS_PER_BLOCK
+    assert _duplex_vision_tokens({"video_frames": [frame, frame]}, tile_pixels=None) == 4 * TOKENS_PER_BLOCK
+
+
+@pytest.mark.parametrize(
+    "first_frame",
+    [
+        pytest.param("data:image/jpeg;base64," + _frame((224, 224)), id="data url"),
+        pytest.param("!!! not base64 !!!", id="corrupt base64"),
+        pytest.param(base64.b64encode(b"\x00" * 64).decode(), id="base64 of something else"),
+        pytest.param(base64.b64encode(base64.b64decode(_frame((224, 224)))[:8]).decode(), id="truncated jpeg"),
+    ],
+)
+def test_a_frame_whose_header_will_not_parse_keeps_the_sliced_reservation(first_frame: str) -> None:
+    """The Realtime wire screens most of these; the in-process API does not.
+
+    ``validate_realtime_video_frames`` rejects bad base64 and anything whose
+    magic bytes are not JPEG or PNG, so on a websocket session only a truncated
+    but well-headed frame gets this far. ``DuplexOmni.append_audio`` submits
+    without that screen, so the reservation still has to hold on its own.
+    """
+    good = _frame((224, 224))
+
+    assert _duplex_vision_tokens({"video_frames": [first_frame, good]}, tile_pixels=TILE_448) == 4 * TOKENS_PER_BLOCK
+
+
+def test_no_camera_track_reserves_nothing() -> None:
+    for payload in ({}, {"video_frames": []}, {"video_frames": "not a list"}, {"video_frames": [None, ""]}, None):
+        assert _duplex_vision_tokens(payload, tile_pixels=TILE_448) == 0
+
+
+def test_the_audio_budget_is_untouched_by_the_camera_track() -> None:
+    """One second of pcm_f32le is 12 slots; the frames are added on top."""
+    one_second = base64.b64encode(b"\x00" * 4 * 16000).decode()
+    audio_only = {"audio": one_second, "format": "pcm_f32le"}
+    with_frames = {**audio_only, "video_frames": [_frame((448, 448)), _frame((448, 448))]}
+
+    assert duplex_scheduler_token_budget(audio_only, tile_pixels=TILE_448) == 12
+    assert duplex_scheduler_token_budget(with_frames, tile_pixels=TILE_448) == 12 + 2 * TOKENS_PER_BLOCK
+
+
+# ---- where the tile comes from ----
+
+
+@dataclass(frozen=True)
+class _SliceConfig:
+    scale_resolution: int
+
+
+@dataclass(frozen=True)
+class _HFConfig:
+    slice_config: object = None
+    image_size: object = None
+
+
+@dataclass(frozen=True)
+class _ModelConfig:
+    hf_config: object = None
+
+
+@pytest.mark.parametrize(
+    ("hf_config", "expected"),
+    [
+        (_HFConfig(slice_config={"max_slice_nums": 1, "scale_resolution": 448}, image_size=448), TILE_448),
+        (_HFConfig(slice_config=_SliceConfig(scale_resolution=336), image_size=448), 336 * 336),
+        (_HFConfig(image_size=560), 560 * 560),
+        (_HFConfig(), None),
+        (_HFConfig(slice_config={"scale_resolution": 0}, image_size=0), None),
+    ],
+    ids=["released-checkpoint", "attribute", "image-size-fallback", "nothing-to-read", "nonsense"],
+)
+def test_the_tile_is_read_from_the_checkpoint(hf_config: object, expected: int | None) -> None:
+    """First row is the released MiniCPM-o 4.5 ``config.json``, where ``slice_config`` is a dict."""
+    assert _model_vision_tile_pixels(_ModelConfig(hf_config=hf_config)) == expected
+
+
+def test_no_model_config_means_no_tile() -> None:
+    assert _model_vision_tile_pixels(None) is None
+    assert _model_vision_tile_pixels(_ModelConfig()) is None
+
+
+def test_the_tile_reaches_the_budget_through_the_runtime_config() -> None:
+    """``_apply_default_scheduler_policy`` writes it; ``build_duplex_data_plane_prompt`` reads it back."""
+    runtime_config: dict[str, object] = {}
+
+    _apply_default_scheduler_policy(
+        runtime_config,
+        config=DuplexSessionConfig(),
+        tokenizer=None,
+        model_config=_ModelConfig(hf_config=_HFConfig(slice_config={"scale_resolution": 448})),
+    )
+
+    assert runtime_config["duplex_vision_tile_pixels"] == TILE_448
+    assert _duplex_vision_tile_pixels(runtime_config) == TILE_448
+
+
+def test_a_checkpoint_that_cannot_be_read_leaves_the_key_out() -> None:
+    """No key, no tile, and no tile is the sliced reservation."""
+    runtime_config: dict[str, object] = {}
+
+    _apply_default_scheduler_policy(runtime_config, config=DuplexSessionConfig(), tokenizer=None)
+
+    assert "duplex_vision_tile_pixels" not in runtime_config
+    assert _duplex_vision_tile_pixels(runtime_config) is None
+
+
+def test_a_junk_tile_in_the_runtime_config_is_ignored() -> None:
+    for value in (0, -1, "448", 448.0, None):
+        assert _duplex_vision_tile_pixels({"duplex_vision_tile_pixels": value}) is None
+
+
+def test_the_tile_is_server_owned() -> None:
+    """A client that could set the tile could shrink the reservation under the worker."""
+    assert "duplex_vision_tile_pixels" in PRIVATE_RUNTIME_CONFIG_KEYS
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py
index 6736404610d..e5737776639 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/plugin.py
@@ -63,6 +63,15 @@
 # Official stacked pair uses max_slice_nums=[2, 1]: the current frame is HD
 # sliced (1 source + 2 patches on 960x540) and the composite is not.
 _DUPLEX_HD_SLICES_PER_BASE_FRAME = 3
+# How many blocks that slicing costs depends on the frame, and at
+# ``max_slice_nums=2`` the processor's grid search has only two outcomes.
+# ``MiniCPMVImageProcessor.get_sliced_grid`` takes
+# ``multiple = min(ceil(w * h / scale_resolution**2), max_slice_nums)`` and
+# returns no grid at all for ``multiple <= 1``; at 2 the only candidate split
+# is 2, so a frame is either unsliced or a 2-cell grid. One normalization tile
+# is therefore the whole decision -- but ``scale_resolution`` is the
+# checkpoint's, not a constant, so it is read from the model rather than
+# assumed.
 
 PRIVATE_RUNTIME_CONFIG_KEYS = frozenset(
     {
@@ -70,6 +79,7 @@
         "duplex_stage_max_tokens",
         "duplex_stage0_max_tokens",
         "duplex_scheduler_token_id",
+        "duplex_vision_tile_pixels",
         "duplex_first_append_context_tokens",
         "ref_audio_data",
         "ref_audio_format",
@@ -86,29 +96,68 @@ class MiniCPMO45ClientRuntimeConfigError(DuplexRuntimeConfigError):
 # ---- engine policy helpers: scheduler token budget ----
 
 
-def _duplex_frame_count(payload: object) -> int:
+def _duplex_frames(payload: object) -> list[str]:
     if not isinstance(payload, dict):
-        return 0
+        return []
     frames = payload.get("video_frames")
     if not isinstance(frames, list):
-        return 0
-    return sum(1 for frame in frames if isinstance(frame, str) and frame)
+        return []
+    return [frame for frame in frames if isinstance(frame, str) and frame]
+
+
+def _duplex_base_frame_blocks(frame: str, tile_pixels: int | None) -> int:
+    """Blocks the HD-sliced frame of a stacked pair costs, read from the frame.
 
+    Wire format is the one Stage0 decodes: bare base64 JPEG/PNG, and only the
+    header is parsed -- the pixels are the worker's job.
 
-def _duplex_vision_tokens(payload: object) -> int:
+    Every uncertainty resolves to the sliced count, because the two directions
+    are not symmetric. Over-reserving wastes scheduler slots. Under-reserving
+    hands the worker fewer prompt slots than it has embeddings, and
+    ``MiniCPMO45OmniModel`` then drops the tail of the unit with a warning
+    rather than failing, which is silent audio loss.
+    """
+    if tile_pixels is None:
+        return _DUPLEX_HD_SLICES_PER_BASE_FRAME
+
+    from io import BytesIO
+
+    from PIL import Image
+
+    try:
+        raw = b64decode(frame, validate=True)
+        with Image.open(BytesIO(raw)) as image:
+            width, height = image.size
+    except (BinasciiError, ValueError, OSError, Image.DecompressionBombError):
+        return _DUPLEX_HD_SLICES_PER_BASE_FRAME
+    if width * height <= tile_pixels:
+        return 1
+    return _DUPLEX_HD_SLICES_PER_BASE_FRAME
+
+
+def _duplex_vision_tile_pixels(runtime_config: object) -> int | None:
+    """Area of the tile this model normalizes a frame to, or ``None`` if unknown."""
+    if not isinstance(runtime_config, dict):
+        return None
+    value = runtime_config.get("duplex_vision_tile_pixels")
+    return value if isinstance(value, int) and value > 0 else None
+
+
+def _duplex_vision_tokens(payload: object, *, tile_pixels: int | None = None) -> int:
     """Scheduler slots for this append's camera track.
 
     Audio is never stacked: a unit still carries one second of soundtrack.
     ``stack_frames`` only adds a second *image*. Official HD on that pair is
-    ``[2, 1]``, so the base frame reserves three 66-token blocks and every
-    extra frame reserves one.
+    ``[2, 1]``, so only the first frame is sliced and every other frame
+    reserves one 66-token block.
     """
-    count = _duplex_frame_count(payload)
-    if count <= 0:
+    frames = _duplex_frames(payload)
+    if not frames:
         return 0
-    if count >= 2:
-        return (_DUPLEX_HD_SLICES_PER_BASE_FRAME + (count - 1)) * _DUPLEX_VISION_TOKENS_PER_FRAME
-    return count * _DUPLEX_VISION_TOKENS_PER_FRAME
+    if len(frames) == 1:
+        return _DUPLEX_VISION_TOKENS_PER_FRAME
+    blocks = _duplex_base_frame_blocks(frames[0], tile_pixels) + (len(frames) - 1)
+    return blocks * _DUPLEX_VISION_TOKENS_PER_FRAME
 
 
 def _duplex_pcm_sample_count(payload: object) -> int | None:
@@ -136,8 +185,8 @@ def duplex_first_append_unit_count(payload: object) -> int | None:
     return max(1, sample_count // _DUPLEX_CHUNK_SAMPLES - 1)
 
 
-def duplex_scheduler_token_budget(payload: object, *, default: int = 64) -> int:
-    vision_tokens = _duplex_vision_tokens(payload)
+def duplex_scheduler_token_budget(payload: object, *, default: int = 64, tile_pixels: int | None = None) -> int:
+    vision_tokens = _duplex_vision_tokens(payload, tile_pixels=tile_pixels)
     sample_count = _duplex_pcm_sample_count(payload)
     if sample_count is None:
         return max(1, int(default)) + vision_tokens
@@ -185,13 +234,15 @@ def build_duplex_data_plane_prompt(
     payload: object,
     final: bool,
 ) -> dict[str, object]:
-    token_budget = duplex_scheduler_token_budget(payload)
+    tile_pixels = _duplex_vision_tile_pixels(runtime_config)
+    token_budget = duplex_scheduler_token_budget(payload, tile_pixels=tile_pixels)
     if seq <= 1:
         context_reserve = duplex_first_append_context_reserve(runtime_config)
         token_budget += context_reserve
         first_units = duplex_first_append_unit_count(payload)
         if first_units is not None:
-            token_budget = context_reserve + first_units * 12 - 1 + _duplex_vision_tokens(payload)
+            vision_tokens = _duplex_vision_tokens(payload, tile_pixels=tile_pixels)
+            token_budget = context_reserve + first_units * 12 - 1 + vision_tokens
     if seq > 1 and duplex_payload_is_exact_chunks(payload):
         token_budget += 1
     if final and duplex_payload_is_exact_chunks(payload):
@@ -466,11 +517,34 @@ def _apply_first_append_context_tokens(
     runtime_config["duplex_first_append_context_tokens"] = len(prefix_ids) + ref_tokens + len(suffix_ids)
 
 
+def _model_vision_tile_pixels(model_config: ModelConfig | None) -> int | None:
+    """Area of one normalization tile, from the checkpoint that will do the slicing.
+
+    ``MiniCPMVImageProcessor`` is built with ``scale_resolution=config.image_size``
+    and Stage0 loads the checkpoint's own processor, so this is per-checkpoint
+    configuration. ``None`` when it cannot be read, which keeps the reservation
+    at the sliced count.
+    """
+    hf_config = getattr(model_config, "hf_config", None)
+    if hf_config is None:
+        return None
+    slice_config = getattr(hf_config, "slice_config", None)
+    side = getattr(slice_config, "scale_resolution", None)
+    if not isinstance(side, int):
+        side = slice_config.get("scale_resolution") if isinstance(slice_config, dict) else None
+    if not isinstance(side, int):
+        side = getattr(hf_config, "image_size", None)
+    if not isinstance(side, int) or side <= 0:
+        return None
+    return side * side
+
+
 def _apply_default_scheduler_policy(
     runtime_config: dict[str, object],
     *,
     config: DuplexSessionConfig,
     tokenizer: PreTrainedTokenizerBase | None,
+    model_config: ModelConfig | None = None,
 ) -> None:
     stage0_max_tokens = config.max_tokens if isinstance(config.max_tokens, int) and config.max_tokens > 0 else 20
     runtime_config["duplex_stage_max_tokens"] = {"0": stage0_max_tokens, "1": 8192}
@@ -491,6 +565,9 @@ def _apply_default_scheduler_policy(
     scheduler_token_id = _scheduler_token_id(tokenizer)
     if scheduler_token_id is not None:
         runtime_config["duplex_scheduler_token_id"] = scheduler_token_id
+    tile_pixels = _model_vision_tile_pixels(model_config)
+    if tile_pixels is not None:
+        runtime_config["duplex_vision_tile_pixels"] = tile_pixels
 
 
 class MiniCPMO45DuplexPlugin(DuplexModelPlugin):
@@ -653,7 +730,7 @@ async def prepare_runtime_config(
         if isinstance(initial_user_text, str) and initial_user_text:
             runtime_config["initial_user_text"] = initial_user_text
         tokenizer = await self._tokenizer_for(model_config)
-        _apply_default_scheduler_policy(runtime_config, config=config, tokenizer=tokenizer)
+        _apply_default_scheduler_policy(runtime_config, config=config, tokenizer=tokenizer, model_config=model_config)
 
         ref_audio = config.ref_audio
         extra_ref_audio = extra_body.get("ref_audio")

From bf74544a35bb45d6092fb2b568e01fc51859b09b Mon Sep 17 00:00:00 2001
From: Clodagh Walsh <42538837+clodaghwalsh17@users.noreply.github.com>
Date: Thu, 17 Sep 2026 11:56:58 +0100
Subject: [PATCH 064/105] [Voxtral] Follow up to raise BadRequest for ref_audio
 (#7649)

Signed-off-by: Clodagh Walsh <clodaghwalsh17@gmail.com>
---
 vllm_omni/entrypoints/openai/tts_adapters/voxtral.py | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/vllm_omni/entrypoints/openai/tts_adapters/voxtral.py b/vllm_omni/entrypoints/openai/tts_adapters/voxtral.py
index 5ea82babd86..4cdf990f2d7 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/voxtral.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/voxtral.py
@@ -99,9 +99,10 @@ async def build(
     ) -> PreparedRequest:
         # Cache encoder_loaded property to avoid RPC call on every request with ref_audio
         if self._encoder_loaded is None:
-            loaded = await self.ctx.server.engine_client.collective_rpc("encoder_loaded")
-            #  Flatten results before checking if encoder loaded property is set
-            self._encoder_loaded = any(sum(loaded, []))
+            result = await self.ctx.server.engine_client.collective_rpc("encoder_loaded")
+            self._encoder_loaded = any(
+                bool(x) for r in result if not isinstance(r, dict) for x in (r if isinstance(r, list) else [r])
+            )
 
         prompt = await self._build_prompt_async(request)
         return PreparedRequest(prompt=prompt, tts_params={}, model_type="voxtral_tts")

From 873e9bff7c545c5cda79fdb93a867f09e443b61d Mon Sep 17 00:00:00 2001
From: ooooooye <53851298+brandneway@users.noreply.github.com>
Date: Thu, 17 Sep 2026 19:05:15 +0800
Subject: [PATCH 065/105] [Doc][NPU] Refresh MiniMax-H3 Ascend recipes for
 0.28-era configurations (#7720)

Signed-off-by: brandneway <gyuan4892@gmail.com>
---
 recipes/MiniMaxAI/MiniMax-H3-NPU-950PR.md | 341 +++++++++--------
 recipes/MiniMaxAI/MiniMax-H3-NPU.md       | 424 ++++++++++++++--------
 2 files changed, 463 insertions(+), 302 deletions(-)

diff --git a/recipes/MiniMaxAI/MiniMax-H3-NPU-950PR.md b/recipes/MiniMaxAI/MiniMax-H3-NPU-950PR.md
index 36eb78a5ddf..039b4027263 100644
--- a/recipes/MiniMaxAI/MiniMax-H3-NPU-950PR.md
+++ b/recipes/MiniMaxAI/MiniMax-H3-NPU-950PR.md
@@ -1,195 +1,224 @@
-# MiniMax-H3 on a single NPU 950PR
+# MiniMax H3 on Ascend 950PR / 950DT
 
-This recipe runs MiniMax-H3 with online INT8 quantization on one NPU 950PR
-NPU (128 GB HiBL 1.0 HBM). It covers the single-card T2VA configuration at
-1024x576. For the eight-card Atlas 800I A3 BF16 route at 768P, see
-[MiniMax-H3-NPU.md](MiniMax-H3-NPU.md).
+> Joint video and audio generation — Ascend NPU deployment guide for the
+> four-card Ascend 950PR / 950DT route
 
-## Capacity requirements
+## Summary
 
-| Resource | Requirement |
-| --- | ---: |
-| NPU | 1x NPU 950PR |
-| NPU HBM | 128 GiB (131,072 MiB reported by `npu-smi`) |
-| Observed HBM high-water mark | 118,442 MiB (90.4% of capacity) |
-| Checkpoint storage | 135 GiB per partition, local disk strongly preferred |
-| Container shared memory | 8 GiB, or a writable local filesystem for spill |
+- Vendor: MiniMaxAI
+- Model: [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3)
+- Tasks: T2VA, FL2VA, and Ref2VA
+- Mode: OpenAI-compatible `/v1/videos` HTTP serving
+- Hardware: Ascend 950PR / Ascend 950DT, 4x NPU (128 GB HBM per device)
+- Maintainer: Community
 
-The observed high-water mark leaves about 12.3 GiB of headroom, so this card is
-sized for exactly one resident task partition at 1024x576. Do not expect a
-larger output shape or concurrency greater than one to fit.
+This recipe covers the four-card 950PR / 950DT configuration at 1344x768.
+For the eight-card Atlas 800I A2 / A3 route, see
+[MiniMax-H3-NPU.md](MiniMax-H3-NPU.md); checkpoint layout, container
+preparation, MindIE-SD installation, and the ffmpeg/decord dependencies are
+described there and apply unchanged.
 
-Because a single 950PR holds the whole partition in HBM, this route does not
-need layerwise offload, and the 200 GiB system-RAM floor carried by the 72 GiB
-GPU recipes does not apply. The validated run completed inside a container
-limited to 32 GiB of RAM. Passing `--enable-layerwise-offload` on this card is
-actively harmful: it stages weights in non-reclaimable host memory and the
-container's OOM killer terminates the server with exit code -9.
+## Environment
 
+Use the A5 variant of the official vLLM-Omni NPU images (see
+[NPU installation](../../docs/getting_started/installation/npu.md)):
 
-## Environment
+```bash
+export IMAGE=quay.io/ascend/vllm-omni:v0.29.0-a5
+```
+
+Check the [tag list](https://quay.io/repository/ascend/vllm-omni?tab=tags)
+for newer releases. Inside the container, install MindIE-SD and the optional
+Ref2VA media dependencies as described in
+[MiniMax-H3-NPU.md § Environment](MiniMax-H3-NPU.md#environment).
 
-- Host architecture: x86_64
--  driver: 25.7.rc1.6 (hal 7.35.23)
--  firmware: 9.0.0.105.229
-- CANN toolkit: 9.1.0 (`/usr/local//cann-9.1.0`)
-- npu-smi: 25.7.rc1.6
-- Python: 3.12.13
-- PyTorch: 2.10.0+cpu
-- torch_npu: 2.10.0.post2
-- vLLM: 0.26.0
-- vLLM-Omni: 0.26.1.dev103+g584d78c67.npu (commit `584d78c6`)
+## Start a server
 
-Install vLLM-Omni from a checkout with MiniMax-H3 support:
+Task selection follows the eight-card recipe: pass `--task-type fl2va` or
+`--task-type ref2va` to pick the task partition. The configurations below use
+4-card USP, 4-card text-encoder TP, and VAE `tile` parallelism.
+
+The two recommended configurations differ in how they fit memory: the
+lossless configuration enables distributed layerwise offload (DLO) to avoid
+activation OOM at longer durations, while the lossy configuration fits the
+maximum supported MiniMax-H3 workload shape without OOM, so DLO is omitted
+for performance.
+
+### Recommended lossless configuration (Ascend 950PR / 950DT)
 
 ```bash
-uv venv
-source .venv/bin/activate
-uv pip install -e .
+export PORT=9098
+export MODEL=/path/to/MiniMax-H3
+export VLLM_WORKER_MULTIPROC_METHOD=spawn
+export VLLM_OMNI_VIDEO_SYNC_TIMEOUT=4000
+export PYTHONDONTWRITEBYTECODE=1
+export HF_HUB_OFFLINE=1
+export TRANSFORMERS_OFFLINE=1
+export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
+export HCCL_NPU_SOCKET_PORT_RANGE="auto"
+
+vllm serve "${MODEL}" \
+  --omni \
+  --host 0.0.0.0 \
+  --port "${PORT}" \
+  --trust-remote-code \
+  --task-type fl2va \
+  --num-gpus 4 \
+  --usp 4 \
+  --ring 1 \
+  --text-encoder-tp-size 4 \
+  --vae-parallel-mode tile \
+  --vae-use-tiling \
+  --vae-patch-parallel-size 4 \
+  --enable-diffusion-pipeline-profiler \
+  --enable-distributed-layerwise-offload \
+  --diffusion-attention-backend FLASH_ATTN
 ```
 
-## Start a server
+H3 is CFG-distilled, so `--cfg-parallel-size` must remain 1. The first
+request includes regional compilation; warm the server once before measuring
+steady-state latency.
+
+### Recommended lossy configuration (Ascend 950PR / 950DT)
+
+Adds EQBSA sparse attention (block-sparse with Q/K INT8 + V FP8 mixed
+precision) and MXFP8 online quantization, and drops DLO:
 
 ```bash
-export MODEL=/path/to/MiniMax-H3/FL2VA
-export PORT=8000
+export PORT=9098
+export MODEL=/path/to/MiniMax-H3
 export VLLM_WORKER_MULTIPROC_METHOD=spawn
-export VLLM_OMNI_VIDEO_SYNC_TIMEOUT=14400
+export VLLM_OMNI_VIDEO_SYNC_TIMEOUT=4000
+export PYTHONDONTWRITEBYTECODE=1
+export HF_HUB_OFFLINE=1
+export TRANSFORMERS_OFFLINE=1
+export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
+export HCCL_NPU_SOCKET_PORT_RANGE="auto"
 
 vllm serve "${MODEL}" \
   --omni \
   --host 0.0.0.0 \
   --port "${PORT}" \
   --trust-remote-code \
-  --num-gpus 1 \
-  --tensor-parallel-size 1 \
-  --usp 1 \
+  --task-type fl2va \
+  --num-gpus 4 \
+  --usp 4 \
   --ring 1 \
-  --text-encoder-tp-size 1 \
-  --vae-patch-parallel-size 1 \
+  --text-encoder-tp-size 4 \
   --vae-parallel-mode tile \
   --vae-use-tiling \
-  --init-timeout 14400 \
-  --stage-init-timeout 14400 \
-  --quantization int8
+  --vae-patch-parallel-size 4 \
+  --enable-diffusion-pipeline-profiler \
+  --diffusion-attention-config '{"default":{"backend":"RAINFUSION_ATTN","block_sparse":{"sparsity":0.8,"precision":"mix","start_step":8,"end_step":12}}}' \
+  --diffusion-quantization-config '{"transformer":{"method":"mxfp8"}}'
 ```
 
-Do not pass `--diffusion-attention-backend CUDNN_ATTN`. cuDNN attention has no
-NPU implementation and fails at the first denoise step. Leave the backend
-unset: it resolves to `TORCH_SDPA`, or to `FLASH_ATTN` when MindIE-SD is
-installed (see [MiniMax-H3-NPU.md § Environment](MiniMax-H3-NPU.md#environment)).
-
-H3 is CFG-distilled, so `--cfg-parallel-size` must remain 1.
-
-## Validated evidence
-
-Measured on one NPU 950PR with the server command above plus
-`--enable-diffusion-pipeline-profiler`, generating a 5 s 1024x576 T2VA clip from
-the request in [§ T2VA request example](#t2va-request-example). MiniMax-H3
-requested 60 denoise steps and executed 59 denoise updates, so per-step latency
-is `denoise / 59`. `ffprobe` confirms every returned MP4 is 1024x576, 24 fps,
-124 video frames, 5.175 s, with a 32 kHz audio track of 165,600 samples.
-
-Five requests were issued back to back with no idle time between them. The card
-is measurably faster on the first request than in steady state, so both regimes
-are reported.
-
-| Stage | First request, cold card | Thermal steady state |
-| --- | ---: | ---: |
-| End-to-end request | 462.13 s | 506.38 s |
-| Text encode | 0.55 s | 0.05 s |
-| Denoise (59 updates) | 429.29 s | 471.74 s |
-| Per denoise update | 7,276 ms | 7,996 ms |
-| VAE decode | 8.43 s | 8.14 s |
-| Worker-to-server handoff | 24 s | 27 s |
-| MP4 muxing | 0.57 s | 0.50 s |
-| Server-reported `denoise_step_latency_ms` | 7,702 ms | 8,440 ms |
-| Peak HBM (`npu-smi`) | 118,442 MiB | 118,442 MiB |
-| Average NPU power | 566.9 W | 556.9 W |
-| Peak NPU temperature | 104 C | 104 C |
-
-Sample counts differ per row. The cold column is a single request. In the steady
-column, text encode, denoise and VAE decode are means over the four subsequent
-requests — denoise spanned 470.37 to 473.21 s, a 0.60% spread — while
-end-to-end, handoff and muxing are means over the two of those four that
-survived the handoff timeout described above.
-
-**Report the steady-state column.** The cold card completes denoise 9.9% faster
-while drawing only 1.8% more average power, and both regimes reach the same
-104 C ceiling, so the first request is buying a short window of higher clocks
-before the die saturates. Any benchmark that issues a single request against an
-idle card will overstate throughput by about 10%.
-
-**Do not read `denoise_step_latency_ms` as a per-step time.** The server divides
-the entire stage wall time by the 60 *requested* steps, so it absorbs text
-encoding, VAE decode and the 837 MiB handoff. All three successful requests
-satisfy `denoise_step_latency_ms == e2e_stage_wall_time_ms / 60` exactly. The
-per-update figure in the table is `diffuse / 59` from the pipeline profiler.
-
-Denoise accounts for 93% of the steady-state request and the handoff accounts
-for 5.3%, so keeping the transfer in shared memory should bring end-to-end down
-to roughly 480 s.
-
-Peak HBM is sampled externally with `npu-smi` at a 3 s interval. It is a
-reserved high-water mark rather than live allocation: it reads 111,272 MiB after
-weight loading and before the first request, and does not fall back after
-requests complete. Re-measure for longer outputs, a different output shape, or
-concurrency greater than one.
-
-### Startup
-
-Weight loading took **31 min 50 s** on the validated host (first log line
-08:04:59, `Application startup complete` 08:36:49), with the checkpoint on a
-shared GlusterFS network mount. This is why the server command sets
-`--init-timeout 14400` and `--stage-init-timeout 14400`; the stock 600 s and
-1800 s timeouts both abort mid-load with `TimeoutError` and exit code 143.
-Reduce both timeouts when the partition is staged on local disk.
-
-## T2VA request example
+The recommended lossy configuration uses a **start=8 / end=12** dense-fallback
+window; see below for more aggressive settings.
+
+### Optional optimizations
+
+The following sections list only the **increment or replacement** relative to
+the recommended lossless configuration; environment variables and the
+remaining flags stay unchanged.
+
+#### Tuning the EQBSA dense-fallback window
+
+`start_step` and `end_step` are the numbers of leading/trailing steps that
+fall back to dense attention — not step indices. `precision` defaults to
+`bf16`; EQBSA requires setting it to `mix` explicitly. For 1344x768, 50-step
+T2VA:
+
+| Configuration | `start_step` | `end_step` | Notes |
+| --- | ---: | ---: | --- |
+| Quality first (recommended) | 8 | 13 | General and complex-motion scenes |
+| Balanced | 0 | 13 | Balanced |
+| Speed first | 0 | 0 | Simple, low-motion scenes |
+
+When frames look discontinuous or details unstable, increase `end_step`
+first, then `start_step`; do not compensate by lowering `sparsity` alone.
+These pairings were validated at 1344x768 / 50 steps only; re-evaluate for
+other resolutions or step counts.
+
+#### Cache-DiT
+
+Append to enable DiT block caching with TaylorSeer extrapolation — see the
+[Cache-DiT guide](../../docs/user_guide/diffusion/cache_acceleration/cache_dit.md):
+
+```bash
+  --cache-backend cache_dit \
+  --enable-cache-dit-summary \
+  --cache-config '{"Fn_compute_blocks":2,"Bn_compute_blocks":1,"max_warmup_steps":4,"residual_diff_threshold":0.4,"max_continuous_cached_steps":4,"enable_taylorseer":true,"taylorseer_order":2}'
+```
+
+#### MXFP4 online quantization
+
+Append to switch the DiT to MXFP4 online quantization:
 
 ```bash
-export API_URL="http://127.0.0.1:${PORT}/v1/videos/sync"
-
-curl -sS --max-time 1800 -X POST "${API_URL}" \
-  -F 'prompt=At night, three cats march into a bedroom playing tiny brass instruments, then abruptly file out, with synchronized room ambience.' \
-  -F 'width=1024' \
-  -F 'height=576' \
-  -F 'aspect_ratio=16:9' \
-  -F 'fps=24' \
-  -F 'num_inference_steps=60' \
-  -F 'flow_shift=12' \
-  -F 'seed=1101' \
-  -F 'extra_params={"task":"t2va","duration":5,"audio_flow_shift":3.0}' \
-  -o t2va.mp4
+  --diffusion-quantization-config '{"transformer":{"method":"mxfp4"}}'
 ```
 
+and remove `--enable-distributed-layerwise-offload`.
+
+## Request examples
+
+Identical to the eight-card recipe; see
+[MiniMax-H3-NPU.md § HTTP API examples](MiniMax-H3-NPU.md#http-api-examples)
+and the GPU recipe's full parameter table.
+
+## Benchmarks (Ascend 950PR)
+
+Measured with `--enable-diffusion-pipeline-profiler` on vLLM-Omni 0.28.0:
+lossless rows use the recommended lossless configuration (with DLO), lossy
+rows the recommended lossy configuration (EQBSA + MXFP8, without DLO). Memory
+figures are per device.
+
+| Task | Resolution | Frames | Duration (s) | Config | E2E (s) | DiT total (s) | DiT per-step (s) | DiT steps | Text encode (s) | Ref video encode (s) | Ref audio encode (s) | VAE decode (s) | Ref preprocess (s) | Post-process (s) | CPU MP4 (s) | Resident weights (GB) | Peak memory (GB) |
+| ---- | ---- | ---- | ---: | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| t2va | 1344x768 | 124 | 5 | lossless | 203.95 | 198.10 | 4.04 | 49 | 0.57 | NA | NA | 5.05 | NA | 0.001 | 0.23 | 3.97 | 22.2 |
+| t2va | 1344x768 | 362 | 15 | lossless | 1489.17 | 1474.35 | 30.08 | 49 | 0.69 | NA | NA | 13.45 | NA | 0.001 | 0.82 | 3.97 | 32.14 |
+| t2va | 1344x768 | 124 | 5 | lossy | 113.86 | 109.81 | 2.24 | 49 | 0.03 | NA | NA | 3.82 | NA | 0.001 | 0.21 | 56.99 | 64.38 |
+| t2va | 1344x768 | 362 | 15 | lossy | 762.17 | 749.40 | 15.29 | 49 | 0.03 | NA | NA | 12.19 | NA | 0.001 | 0.61 | 56.99 | 74.26 |
+| ref2va | 1344x768 | 124 | 5 | lossless | 745.43 | 730.22 | 14.9 | 49 | 1.16 | 8.15 | 0.13 | 5.12 | 0.41 | 0.001 | 0.28 | 3.97 | 23.82 |
+| ref2va | 1344x768 | 362 | 15 | lossless | 5887.24 | 5847.57 | 119.33 | 49 | 2.54 | 22.07 | 0.23 | 13.34 | 0.81 | 0.001 | 0.70 | 3.97 | 32.53 |
+| ref2va | 1344x768 | 124 | 5 | lossy | 400.40 | 387.82 | 7.91 | 49 | 0.95 | 7.05 | 0.09 | 3.91 | 0.41 | 0.001 | 0.21 | 56.6 | 66.03 |
+| ref2va | 1344x768 | 362 | 15 | lossy | 3037.84 | 3001.31 | 61.24 | 49 | 2.28 | 20.64 | 0.15 | 12.1 | 0.81 | 0.001 | 0.70 | 56.6 | 74.76 |
+
+The resident-weight figures reflect the DLO strategy difference: with DLO
+(lossless rows) DiT weights live in host memory and only the active layer
+stays on the device, while without DLO (lossy rows) the quantized weights are
+resident in HBM. Peak memory stays well inside the 128 GB per-device capacity
+in both cases. These numbers describe the validated shapes rather than a
+general throughput guarantee.
+
 ## Known limitations
 
-- INT8 online quantization is validated for T2VA on this card. Use BF16 for
-  FL2VA and Ref2VA, or re-measure before relying on it.
-- Single-card serving loads one task partition at a time. For Ref2VA, stop the
-  server and restart it against the `Ref2VA` directory.
-- Sustained load drives the die to 104 C and costs about 10% of denoise
-  throughput relative to a cold card. Warm the server with at least one full
-  request before measuring, and treat steady state as the reportable number.
-- Requests can fail during result handoff on hosts where the IPC spill path is
-  slow. See [§ Result handoff and shared
-  memory](#result-handoff-and-shared-memory).
-- Loading the checkpoint from a network mount takes over 30 minutes and forces
-  very large init timeouts. Stage the partition on local disk when possible.
-- The configuration measured here is 1024x576 at 60 steps, which differs from
-  the 1344x768 at 50 steps used by the GPU recipes in this directory. Denoise
-  cost scales superlinearly with token count, so the numbers are not directly
-  comparable across recipes.
-- The image ships a `triton` package whose  backend is not built
-  (`No module named 'triton._C.libtriton.'`). vLLM logs this as an error
-  at startup and disables Triton; the diffusion path does not need it and the
-  run completes normally.
+- Task serving is partitioned by `--task-type`: T2VA/FL2VA and Ref2VA load
+  different DiTs, so switching between them requires a restart with the other
+  partition.
+- H3 currently executes one generation request per diffusion batch.
+- The first regional-compile request is a warmup and should not be included
+  in steady-state performance measurements.
+- VAE patch parallelism requires size 1 or the full DiT group size and
+  supports the H3 native `tile` mode only.
+- The lossy configuration (EQBSA + MXFP8) is validated for T2VA and Ref2VA;
+  use the lossless configuration for FL2VA or re-validate first.
+- The lossless configuration trades throughput for activation headroom via
+  DLO; if your workload never approaches the maximum duration, dropping
+  `--enable-distributed-layerwise-offload` may improve latency at the risk of
+  OOM on longer durations.
 
 ## Additional resources
 
 - [MiniMax-H3.md](MiniMax-H3.md) — full GPU guide
-- [MiniMax-H3-NPU.md](MiniMax-H3-NPU.md) — eight-card Atlas 800I A3 BF16 guide
-- [Int8 quantization](../../docs/user_guide/quantization/int8.md)
+- [MiniMax-H3-NPU.md](MiniMax-H3-NPU.md) — eight-card Atlas 800I A2 / A3
+  guide (checkpoint, container, and dependency details)
+- [NPU installation](../../docs/getting_started/installation/npu.md)
+- [RainFusion attention](../../docs/user_guide/diffusion/attention_backends/rainfusion.md)
+  — block-sparse knobs and tuning
+- [Online quantization](../../docs/user_guide/quantization/online.md)
+  — INT8 / MXFP8 / MXFP4
+- [Cache-DiT guide](../../docs/user_guide/diffusion/cache_acceleration/cache_dit.md)
 - [Supported models](../../docs/models/supported_models.md)
 - [Video API](../../docs/serving/videos_api.md)
diff --git a/recipes/MiniMaxAI/MiniMax-H3-NPU.md b/recipes/MiniMaxAI/MiniMax-H3-NPU.md
index c6ee0904b84..971be278d5e 100755
--- a/recipes/MiniMaxAI/MiniMax-H3-NPU.md
+++ b/recipes/MiniMaxAI/MiniMax-H3-NPU.md
@@ -1,7 +1,8 @@
 # MiniMax H3 on Ascend NPU
 
 > Joint video and audio generation with text, first/last keyframes, and mixed
-> image/video/audio references — Ascend NPU deployment guide
+> image/video/audio references — Ascend NPU deployment guide for Atlas 800I A2
+> and Atlas 800I A3
 
 ## Summary
 
@@ -9,7 +10,7 @@
 - Model: [`MiniMaxAI/MiniMax-H3`](https://huggingface.co/MiniMaxAI/MiniMax-H3)
 - Tasks: T2VA, FL2VA, and Ref2VA
 - Mode: OpenAI-compatible `/v1/videos` HTTP serving
-- Hardware: Atlas 800I A3
+- Hardware: Atlas 800I A2 / Atlas 800I A3, 8x NPU
 - Maintainer: Community
 
 This recipe adapts [MiniMax-H3.md](MiniMax-H3.md) for Ascend NPU
@@ -22,226 +23,355 @@ environments. Differences from the GPU path:
   automatically falls back to soundfile / ffmpeg for wav/mp3/m4a/mp4 audio
   inputs.
 
+For the four-card Ascend 950PR / 950DT route, see
+[MiniMax-H3-NPU-950PR.md](MiniMax-H3-NPU-950PR.md).
+
 ## Prerequisites
 
 ### Checkpoint
 
-Same as the GPU recipe — Hugging Face access approval is required. Authenticate
-once; `vllm serve` downloads the required nested components automatically:
+Download the weights once; `vllm serve` accepts the repository ID or a local
+path and resolves the nested components automatically:
 
 ```bash
-hf auth login
-export MODEL=MiniMaxAI/MiniMax-H3
+export MODEL=/path/to/MiniMax-H3
+hf download MiniMaxAI/MiniMax-H3 --local-dir "${MODEL}"
+```
+
+The checkpoint directory layout is:
+
+```text
+MiniMax-H3/
+├── FL2VA/          # shared by T2VA/FL2VA tasks
+├── Ref2VA/         # Ref2VA task weights
+└── model_index.json
 ```
 
 ### Environment
 
-- Ascend driver & firmware: 25.5.1
-- CANN toolkit: 9.0.1
-- Python: 3.12
-- PyTorch: 2.10.0+cpu
-- torch_npu: 2.10.0.post2
-- Install vLLM-Omni from a checkout with MiniMax H3 support:
+The recommended deployment uses the official vLLM-Omni NPU images, which ship
+the matching vLLM / vLLM-Ascend / vLLM-Omni stack (see
+[NPU installation](../../docs/getting_started/installation/npu.md)). Pick the
+image matching the hardware — `quay.io/ascend/vllm-omni:v0.29.0` for
+Atlas 800I A2, `quay.io/ascend/vllm-omni:v0.29.0-a3` for Atlas 800I A3 — and
+check the
+[tag list](https://quay.io/repository/ascend/vllm-omni?tab=tags) for newer
+releases:
 
 ```bash
-uv venv
-source .venv/bin/activate
-uv pip install -e .
+export IMAGE=quay.io/ascend/vllm-omni:v0.29.0-a3
+export CONTAINER_NAME=h3
+
+docker run -it -u root --name ${CONTAINER_NAME} \
+  --privileged=true \
+  --shm-size=2000g \
+  --net=host \
+  --device /dev/davinci0 \
+  --device /dev/davinci1 \
+  --device /dev/davinci2 \
+  --device /dev/davinci3 \
+  --device /dev/davinci4 \
+  --device /dev/davinci5 \
+  --device /dev/davinci6 \
+  --device /dev/davinci7 \
+  --device /dev/davinci_manager \
+  --device /dev/devmm_svm \
+  --device /dev/hisi_hdc \
+  -v /home:/home \
+  -v /usr/local/dcmi:/usr/local/dcmi \
+  -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
+  -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
+  -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
+  -v /etc/ascend_install.info:/etc/ascend_install.info \
+  -v /root/.cache:/root/.cache \
+  ${IMAGE} \
+  /bin/bash
 ```
 
-Install the **mindie-sd** operator library to enable Ascend-optimized fused
-operators (`adalayernorm`, etc.) and the RainFusion `rf_v2` block-sparse
-attention kernel:
+Inside the container:
+
+- **MindIE-SD** provides the Ascend-optimized fused operators
+  (`adalayernorm`, etc.), the LaserAttention kernel, and the RainFusion
+  block-sparse attention kernel. If the image does not ship it, build it from
+  source:
 
 ```bash
-git clone https://gitcode.com/Ascend/MindIE-SD.git && cd MindIE-SD
+git clone https://gitcode.com/Ascend/MindIE-SD.git
+cd MindIE-SD
+python setup.py bdist_wheel
+pip install dist/mindiesd-*.whl
+```
 
-# Comment out the tik_ops build step (not needed for this use case)
-sed -i 's|^\(\s*\)source ${current_script_dir}/build_tik_ops.sh|\1# source ${current_script_dir}/build_tik_ops.sh|' build/build_ops.sh
+- To track the latest vLLM-Omni, install it from a checkout:
 
-python setup.py bdist_wheel
-cd dist
-pip install mindiesd-*.whl
+```bash
+git clone https://github.com/vllm-project/vllm-omni.git
+cd vllm-omni
+VLLM_OMNI_TARGET_DEVICE=npu pip install -e . --no-build-isolation
 ```
 
-- `ffmpeg` and `ffprobe` must be available on `PATH`. They are used for
-  reference-video preparation and MP4 output.
-- Reference-video decoding uses `decord` when available and falls back to
-  PyAV otherwise.
-- Audio inputs do not require TorchCodec: wav/mp3/m4a/mp4 files are loaded
-  at native sample rate through the soundfile / ffmpeg fallback.
+- `ffmpeg` and `ffprobe` must be available on `PATH` (reference-video
+  preparation and MP4 output). Reference-video decoding uses `decord` when
+  available and falls back to PyAV otherwise; `decord` is required only for
+  the Ref2VA workflow and can be built with:
+
+```bash
+apt update
+apt install -y ffmpeg pkg-config libavcodec-dev libavformat-dev \
+  libavutil-dev libswscale-dev libavfilter-dev libavdevice-dev
+git clone --depth 1 --recursive https://github.com/dmlc/decord.git
+cd decord
+mkdir -p build && cd build
+cmake .. -DUSE_CUDA=0 -DDECODE_FFMPEG=1 -DCMAKE_BUILD_TYPE=Release
+make
+cd ../python
+pip3 install . --no-build-isolation
+```
 
 ## Start a server
 
-Pass the repository ID directly. The pipeline loads the two nested DiTs while
-sharing the tokenizer, processor, text encoder, and VAEs from `FL2VA`.
+T2VA and FL2VA share one set of weights; the Ref2VA weights differ. Select
+the task partition at startup with **`--task-type`** (`fl2va` or `ref2va`).
+When unset, only the T2VA/FL2VA weights are loaded. All remaining flags are
+task-agnostic.
 
-### Multi-NPU: 768P combined-service configuration
+### Recommended lossless configuration (Atlas 800I A2 / A3)
 
-Use Ulysses sequence parallelism degree 8, text-encoder tensor parallelism
-degree 8, native tiled VAE patch parallelism degree 8, and distributed
-layerwise offload:
+Lossless means fused operators plus the high-performance FLASH_ATTN backend
+only. The configuration uses 8-card USP, 8-card text-encoder TP, distributed
+layerwise offload (DLO), and VAE `tile` parallelism:
 
 ```bash
-export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7
 export PORT=9098
-export MODEL=MiniMaxAI/MiniMax-H3
+export MODEL=/path/to/MiniMax-H3
 export VLLM_WORKER_MULTIPROC_METHOD=spawn
-export VLLM_OMNI_VIDEO_SYNC_TIMEOUT=1800
+export VLLM_OMNI_VIDEO_SYNC_TIMEOUT=4000
 export PYTHONDONTWRITEBYTECODE=1
+export HF_HUB_OFFLINE=1
+export TRANSFORMERS_OFFLINE=1
+export PYTORCH_NPU_ALLOC_CONF=expandable_segments:True
+export MINDIE_SD_FA_TYPE="ascend_laser_attention"
+export HCCL_NPU_SOCKET_PORT_RANGE="auto"
 
 vllm serve "${MODEL}" \
   --omni \
   --host 0.0.0.0 \
   --port "${PORT}" \
   --trust-remote-code \
+  --task-type fl2va \
   --num-gpus 8 \
   --usp 8 \
   --ring 1 \
   --text-encoder-tp-size 8 \
-  --enable-distributed-layerwise-offload \
   --vae-parallel-mode tile \
   --vae-use-tiling \
   --vae-patch-parallel-size 8 \
+  --enable-distributed-layerwise-offload \
+  --enable-diffusion-pipeline-profiler \
   --diffusion-attention-backend FLASH_ATTN
 ```
 
-Do not add `--enforce-eager`. The first request includes regional
-compilation; warm the server once before measuring steady-state latency.
-H3 is CFG-distilled, so `--cfg-parallel-size` must remain 1.
+Notes:
 
-The same endpoint accepts `task=t2va`, `task=fl2va`, and `task=ref2va`; no
-partition restart is required. Layerwise offload applies to both DiTs.
+- Do not add `--enforce-eager`. The first request includes regional
+  compilation; warm the server once before measuring steady-state latency.
+- H3 is CFG-distilled, so `--cfg-parallel-size` must remain 1.
+- Keep `--ring 1` when switching to RainFusion attention (below): the
+  block-sparse kernel ranks key blocks over the whole sequence, so ring
+  parallelism would split away the keys it needs. Scale with `--usp` instead.
+- DLO offloads DiT layers with parameters gathered across the parallel group
+  instead of replicated per rank, which is what fits the combined 768P
+  service into 64 GB HBM per device (Atlas 800I A3). Host (CPU) memory usage
+  is high with this option.
 
-On Atlas 800I A3 (64 GB HBM per device) the combined service does not fit at
-768P without offloading or sharding: use distributed layerwise offload (as
-above) or HSDP — see
-[§ Memory and attention optimizations](#memory-and-attention-optimizations-a3).
+### Recommended lossy configuration (Atlas 800I A2 / A3)
 
-### CPU MP4 response encoding (Atlas A2)
-
-Non-streaming MP4 responses use one public automatic encoder. It checks the
-runtime frame shape, common dtype, and RGB channel-plane contiguity for every
-request; compatible inputs use direct planar PyAV frames, while unsupported
-inputs fall back to the legacy muxer before opening the PyAV container. No CLI
-flag, model declaration, or user configuration is required. Streaming fMP4
-output remains on its existing incremental path.
-
-Current performance and correctness validation is limited to one Atlas A2 host
-with 8x Ascend 910B4-1 NPUs, the `FL2VA`/`t2va` partition, one request at a
-time, 1344x768 at 24 fps, and 5, 8.7, and 15 second requests. This optimization
-only changes CPU MP4 response encoding; it does not change DiT execution or
-stage 0.
-
-### Optional optimizations
-
-Two independent optimizations may be enabled on top of the configuration
-above. Both are validated for T2VA only.
-
-**RainFusion block-sparse attention** — switch the attention backend, keeping
-every other flag unchanged:
+Adds RainFusion block-sparse attention and INT8 online quantization on top of
+the lossless configuration. Validated for T2VA and Ref2VA; see
+[Benchmarks](#benchmarks-atlas-800i-a2--a3):
 
 ```bash
-  --diffusion-attention-backend RAINFUSION_ATTN
-```
-
-**INT8 online quantization** — add one flag to the server command above:
-
-```bash
-  --quantization int8
+vllm serve "${MODEL}" \
+  --omni \
+  --host 0.0.0.0 \
+  --port "${PORT}" \
+  --trust-remote-code \
+  --task-type fl2va \
+  --num-gpus 8 \
+  --usp 8 \
+  --ring 1 \
+  --text-encoder-tp-size 8 \
+  --vae-parallel-mode tile \
+  --vae-use-tiling \
+  --vae-patch-parallel-size 8 \
+  --enable-distributed-layerwise-offload \
+  --enable-diffusion-pipeline-profiler \
+  --diffusion-quantization-config '{"transformer":{"method":"int8"}}' \
+  --diffusion-attention-config '{"default": {"backend": "RAINFUSION_ATTN",
+      "block_sparse": {"sparsity": 0.8, "start_step": 12}}}'
 ```
 
-Keep `--ring 1` when using RainFusion: the `rf_v2` kernel ranks key blocks
-over the whole sequence, so ring parallelism would split away the keys it
-needs. Scale with `--usp` instead.
+Online INT8 quantization can be combined with distributed layerwise offload
+while AllGather is enabled. Keep AllGather enabled for SP>1; use
+`--dlo-no-use-allgather` only when collective communication is unavailable.
 
-## Memory and attention optimizations (A3)
+### Optional optimizations
 
-### Fitting 768P into 64 GB HBM: distributed layerwise offload or HSDP
+The following sections list only the **increment or replacement** relative to
+the recommended lossless configuration; environment variables and the
+remaining flags stay unchanged.
 
-Each Atlas 800I A3 NPU has 64 GB of HBM, which is not enough for the
-combined MiniMax-H3 service at 768P. Enable **one** of the following at
-server startup:
+#### Cache-DiT
 
-**Distributed layerwise offload** — DiT layers are offloaded with parameters
-gathered across the parallel group instead of replicated per rank:
+Append to enable DiT block caching with TaylorSeer extrapolation — see the
+[Cache-DiT guide](../../docs/user_guide/diffusion/cache_acceleration/cache_dit.md):
 
 ```bash
-  --enable-distributed-layerwise-offload
+  --cache-backend cache_dit \
+  --enable-cache-dit-summary \
+  --cache-config '{"Fn_compute_blocks":2,"Bn_compute_blocks":1,"max_warmup_steps":4,"residual_diff_threshold":0.4,"max_continuous_cached_steps":4,"enable_taylorseer":true,"taylorseer_order":2}'
 ```
 
-Measured peak NPU memory is about 45 GB per device for Ref2VA with a 13.88 s
-input video generating a 15 s 768P (1344x768) output video. Host (CPU) memory
-usage is high with this option.
+#### EQBSA sparse attention
 
-**HSDP** — hybrid sharded data parallelism for the DiT parameters. The
-multi-stream memory-reuse knob is mandatory with this flag:
+EQBSA applies Q/K INT8 with V FP8 mixed quantization on top of block-sparse
+attention. Replace `--diffusion-attention-backend FLASH_ATTN` with:
 
 ```bash
-export MULTI_STREAM_MEMORY_REUSE=2
+  --diffusion-attention-config '{"default":{"backend":"RAINFUSION_ATTN","block_sparse":{"sparsity":0.8,"start_step":8,"end_step":13,"precision":"mix"}}}'
 ```
 
-```bash
-  --use-hsdp
-```
+`precision` defaults to `bf16`; enabling EQBSA requires setting it to `mix`
+explicitly. `start_step` and `end_step` are the numbers of leading/trailing
+steps that fall back to dense attention — not step indices. For 1344x768,
+50-step T2VA:
 
-Host memory usage is small, but large shapes may still OOM; HBM usage
-optimizations for this path are ongoing.
+| Configuration | `start_step` | `end_step` | Notes |
+| --- | ---: | ---: | --- |
+| Quality first (recommended) | 8 | 13 | General and complex-motion scenes |
+| Balanced | 0 | 13 | Balanced |
+| Speed first | 0 | 0 | Simple, low-motion scenes |
 
-### FLASH_ATTN backend with MindIE-SD
+When frames look discontinuous or details unstable, increase `end_step`
+first, then `start_step`; do not compensate by lowering `sparsity` alone.
+These pairings were validated at 1344x768 / 50 steps only; re-evaluate for
+other resolutions or step counts.
 
-Keep `--diffusion-attention-backend FLASH_ATTN` and install MindIE-SD (see
-[§ Environment](#environment)). On NPU this backend carries most of the
-memory-reduction and performance work: a mask-free packed varlen path that
-never materializes the quadratic `full_qk` padding mask, and K/V prefix
-slicing, both driven by the packed `cu_seqlens` metadata emitted by the H3
-transformer.
-
-### Optional: LaserAttention fused kernel
+## HTTP API examples
 
-For an additional attention speedup, select the Ascend LaserAttention fused
-kernel before starting the server:
+The request contract is identical to the GPU recipe; see
+[MiniMax-H3.md § HTTP API examples](MiniMax-H3.md#http-api-examples). Use the
+validated 768P shapes (e.g. `width=1344 height=768`) on NPU. Quick start
+against the synchronous endpoint:
 
 ```bash
-export MINDIE_SD_FA_TYPE="ascend_laser_attention"
+export API_URL="http://127.0.0.1:${PORT}/v1/videos/sync"
+
+curl -sS -X POST "${API_URL}" \
+  -F 'prompt=In a snowy blue-purple forest, Ori carefully walks past a sleeping giant; footsteps crunch in the snow while the creature breathes and softly snorts.' \
+  -F 'width=1344' \
+  -F 'height=768' \
+  -F 'aspect_ratio=16:9' \
+  -F 'fps=24' \
+  -F 'num_inference_steps=50' \
+  -F 'flow_shift=12.0' \
+  -F 'audio_flow_shift=3.0' \
+  -F 'seed=1101' \
+  -F 'extra_params={"task":"t2va","duration":5.0}' \
+  -o t2va.mp4
 ```
 
-This requires the FLASH_ATTN backend and MindIE-SD. H3 automatically applies
-exact power-of-two input pre-scaling (`laser_input_scale=256`) so the
-kernel's fp16 workspace cannot overflow on outlier activations. Measured
-speedup numbers will be added here.
-
-
-## HTTP API examples
+Switch tasks via `extra_params.task` (`t2va` / `fl2va` / `ref2va`); FL2VA and
+Ref2VA additionally pass `input_references` (first-frame image, reference
+video/audio). The full parameter table lives in the GPU recipe.
 
-The request format is identical to the GPU recipe; see
-[MiniMax-H3.md § HTTP API examples](MiniMax-H3.md#http-api-examples).
-Use the validated 768P shapes (e.g. `width=1344 height=768`) on NPU.
+## FlashGen 4-step online LoRA (T2VA)
 
-## Key parameters
+The FlashGen 4-step weights are a native-layout LoRA single file
+(`key_format=minimax-h3-native`) loaded at runtime — no merge into the base
+checkpoint. Download them from
+[FlashGen/Minimax-H3-4step-lora-flashgen](https://modelscope.cn/models/FlashGen/Minimax-H3-4step-lora-flashgen),
+then on top of the recommended configuration above:
 
-Same as the GPU recipe; see
-[MiniMax-H3.md § Key parameters](MiniMax-H3.md#key-parameters).
-The validated resolution on NPU is 768P (e.g. 1344x768).
+- append `--lora-backend peft --lora-path "${FLASHGEN_LORA}"`,
+- use `--diffusion-attention-backend FLASH_ATTN` (dense; drop the RainFusion
+  attention config),
+- issue T2VA requests with `num_inference_steps=4` and the `lora` request
+  field (`name` / `path` / `scale`) — see
+  [MiniMax-H3.md § FlashGen native LoRA](MiniMax-H3.md#flashgen-native-lora).
 
-## Validated NPU evidence
+T2VA only; FL2VA and Ref2VA are not supported, and neither
+`--enable-cpu-offload` nor `--enable-layerwise-offload` may be combined with
+it.
 
-Measured on an Atlas 800I A3 server (8x NPU) with CANN 9.0.1,
-PyTorch 2.10.0+cpu, and torch_npu 2.10.0.post2, using the multi-NPU
-configuration above:
+## CPU MP4 response encoding (Atlas A2)
 
-| Workload | Configuration |
-|----------|---------------|
-| T2VA, 209 frames, 1344x768 | TE TP8, distributed layerwise offload, Ulysses 8, VPP8 tile, regional compile |
-| Ref2VA (prompt + video), 124 frames, 1344x768 | TE TP8, distributed layerwise offload, Ulysses 8, VPP8 tile, regional compile |
+Non-streaming MP4 responses use one public automatic encoder. It checks the
+runtime frame shape, common dtype, and RGB channel-plane contiguity for every
+request; compatible inputs use direct planar PyAV frames, while unsupported
+inputs fall back to the legacy muxer before opening the PyAV container. No CLI
+flag, model declaration, or user configuration is required. Streaming fMP4
+output remains on its existing incremental path.
 
-These measurements describe the validated shapes rather than a general
-throughput guarantee.
+## Ascend-optimized components
+
+The optimizations stacked by the recommended configurations above:
+
+1. Ascend-friendly attention: the MindIE-SD `ascend_laser_attention` fused
+   kernel selected through `MINDIE_SD_FA_TYPE`, carried by the FLASH_ATTN
+   backend with a mask-free packed varlen path and K/V prefix slicing driven
+   by the packed `cu_seqlens` metadata.
+2. Ascend-friendly fused operators: RMSNorm, AddRMSNorm, GQA, SwiGLU, and
+   rotary position embedding from MindIE-SD.
+3. RainFusion block-sparse attention, optionally with EQBSA mixed INT8/FP8
+   precision — see
+   [RainFusion](../../docs/user_guide/diffusion/attention_backends/rainfusion.md).
+4. Online quantization: INT8, MXFP8, and MXFP4 — see
+   [online quantization](../../docs/user_guide/quantization/online.md).
+5. Parallelism: USP, text-encoder TP, and native VAE `tile` patch
+   parallelism, plus distributed layerwise offload.
+6. Post-training: few-step distillation via the FlashGen online LoRA.
+
+## Benchmarks (Atlas 800I A2 / A3)
+
+Measured with `--enable-diffusion-pipeline-profiler` on vLLM-Omni 0.28.0:
+lossless rows use the recommended lossless configuration, lossy rows the
+recommended lossy configuration. Memory figures are per device.
+
+### Atlas 800I A2
+
+| Task | Resolution | Frames | Duration (s) | Config | E2E (s) | DiT total (s) | DiT per-step (s) | DiT steps | Text encode (s) | Ref video encode (s) | Ref audio encode (s) | VAE decode (s) | Ref preprocess (s) | Post-process (s) | CPU MP4 (s) | Resident weights (GB) | Peak memory (GB) |
+| ---- | ---- | ---- | ---: | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| t2va | 1344x768 | 124 | 5 | lossless | 150.06 | 139.9 | 2.85 | 49 | 0.83 | NA | NA | 6.76 | NA | 0.462 | 1.18 | 2.97 | 24.7 |
+| t2va | 1344x768 | 362 | 15 | lossless | 786.24 | 761.36 | 15.53 | 49 | 1.20 | NA | NA | 15.87 | NA | 1.98 | 2.95 | 2.97 | 36.21 |
+| t2va | 1344x768 | 124 | 5 | lossy | 108.1 | 95.85 | 1.95 | 49 | 0.9 | NA | NA | 6.73 | NA | 0.745 | 1.04 | 2.55 | 22.47 |
+| t2va | 1344x768 | 362 | 15 | lossy | 552.51 | 526.04 | 10.73 | 49 | 1.28 | NA | NA | 16.07 | NA | 1.90 | 3.76 | 2.55 | 35.11 |
+| ref2va | 1344x768 | 124 | 5 | lossless | 474.89 | 421.68 | 8.6 | 49 | 2.42 | 13.31 | 0.38 | 6.47 | 3.94 | 0.489 | 1.16 | 3.4 | 23.45 |
+| ref2va | 1344x768 | 362 | 15 | lossless | 3414.18 | 3336.98 | 68.08 | 49 | 6.48 | 30.85 | 0.59 | 15.8 | 12.59 | 1.99 | 3.08 | 3.4 | 36.28 |
+| ref2va | 1344x768 | 124 | 5 | lossy | 380.92 | 326.50 | 6.66 | 49 | 2.47 | 13.48 | 0.38 | 6.36 | 4.68 | 0.591 | 1.22 | 2.55 | 22.57 |
+| ref2va | 1344x768 | 362 | 15 | lossy | 2332.04 | 2249.63 | 45.89 | 49 | 6.33 | 35.1 | 0.59 | 15.72 | 11.07 | 1.35 | 2.3 | 2.55 | 35.58 |
+
+### Atlas 800I A3
+
+| Task | Resolution | Frames | Duration (s) | Config | E2E (s) | DiT total (s) | DiT per-step (s) | DiT steps | Text encode (s) | Ref video encode (s) | Ref audio encode (s) | VAE decode (s) | Ref preprocess (s) | Post-process (s) | CPU MP4 (s) | Resident weights (GB) | Peak memory (GB) |
+| ---- | ---- | ---- | ---: | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| t2va | 1344x768 | 124 | 5 | lossless | 114.19 | 105.87 | 2.16 | 49 | 0.48 | NA | NA | 6.56 | NA | 0.001 | 0.46 | 3.49 | 24.7 |
+| t2va | 1344x768 | 362 | 15 | lossless | 599.29 | 580.38 | 11.84 | 49 | 1.83 | NA | NA | 14.95 | NA | 0.001 | 1.02 | 3.49 | 36.21 |
+| t2va | 1344x768 | 124 | 5 | lossy | 84.82 | 77.47 | 1.58 | 49 | 0.57 | NA | NA | 6.23 | NA | 0.001 | 0.61 | 2.63 | 22.47 |
+| t2va | 1344x768 | 362 | 15 | lossy | 401.43 | 383.56 | 7.82 | 49 | 1.72 | NA | NA | 14.83 | NA | 0.001 | 1.14 | 2.63 | 35.11 |
+| ref2va | 1344x768 | 124 | 5 | lossless | 355.53 | 311.86 | 6.36 | 49 | 1.89 | 12.37 | 0.24 | 5.55 | 2.49 | 0.001 | 0.43 | 3.49 | 23.45 |
+| ref2va | 1344x768 | 362 | 15 | lossless | 2339.56 | 2277.61 | 46.47 | 49 | 5.61 | 34.46 | 0.36 | 13.61 | 6.83 | 0.001 | 1.11 | 3.49 | 36.28 |
+| ref2va | 1344x768 | 124 | 5 | lossy | 306.82 | 247.72 | 5.05 | 49 | 1.88 | 12.71 | 0.24 | 5.24 | 2.45 | 0.001 | 0.54 | 2.63 | 22.57 |
+| ref2va | 1344x768 | 362 | 15 | lossy | 1695.26 | 1634.58 | 33.35 | 49 | 5.57 | 33.27 | 0.36 | 13.51 | 6.96 | 0.001 | 1.22 | 2.63 | 35.58 |
+
+These numbers describe the validated shapes rather than a general throughput
+guarantee.
 
 ## Known limitations
 
-- Combined serving requires sibling `FL2VA` and `Ref2VA` directories, loads
-  both task-specific DiTs, and loads one copy of every shared component.
+- Task serving is partitioned by `--task-type`: T2VA/FL2VA and Ref2VA load
+  different DiTs, so switching between them requires a restart with the other
+  partition.
 - H3 currently executes one generation request per diffusion batch.
 - The first regional-compile request is a warmup and should not be included
   in steady-state performance measurements.
@@ -250,17 +380,19 @@ throughput guarantee.
   the same HTTP request contract.
 - VAE patch parallelism requires size 1 or the full DiT group size and
   supports the H3 native `tile` mode only.
-- RainFusion block-sparse attention and INT8 quantization are validated for
-  T2VA only; use the BF16 dense configuration for FL2VA and Ref2VA.
-- Online INT8 quantization can be combined with distributed layerwise offload
-  while AllGather is enabled. Keep AllGather enabled for SP>1; use
-  `--dlo-no-use-allgather` only when collective communication is unavailable.
+- The lossy configuration (RainFusion + INT8) is validated for T2VA and
+  Ref2VA; use the lossless configuration for FL2VA or re-validate first.
 
 ## Additional resources
 
 - [MiniMax-H3.md](MiniMax-H3.md) — full GPU guide
-- [Attention backends § RAINFUSION_ATTN](../../docs/user_guide/diffusion/attention_backends.md#rainfusion_attn-backend-and-block-sparse-video-attention)
-  — RainFusion knobs and tuning
-- [Int8 quantization](../../docs/user_guide/quantization/int8.md)
+- [MiniMax-H3-NPU-950PR.md](MiniMax-H3-NPU-950PR.md) — four-card
+  Ascend 950PR / 950DT guide
+- [NPU installation](../../docs/getting_started/installation/npu.md)
+- [RainFusion attention](../../docs/user_guide/diffusion/attention_backends/rainfusion.md)
+  — block-sparse knobs and tuning
+- [Online quantization](../../docs/user_guide/quantization/online.md)
+  — INT8 / MXFP8 / MXFP4
+- [Cache-DiT guide](../../docs/user_guide/diffusion/cache_acceleration/cache_dit.md)
 - [Supported models](../../docs/models/supported_models.md)
 - [Video API](../../docs/serving/videos_api.md)

From d0755b57169352c07416ad925385bdc907781e8c Mon Sep 17 00:00:00 2001
From: Chenchao Xu <chenchaox@nvidia.com>
Date: Thu, 17 Sep 2026 20:18:51 +0800
Subject: [PATCH 066/105] =?UTF-8?q?[Model]=20Add=20=CF=800.5=20(Pi0.5)=20V?=
 =?UTF-8?q?LA=20model=20support=20(#6950)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: chenchaox <chenchaox@nvidia.com>
---
 .buildkite/cuda/test-nightly.yml              |   11 +
 docs/models/supported_models.md               |    1 +
 recipes/README.md                             |    3 +
 recipes/lerobot/Pi05.md                       |  154 +++
 tests/diffusion/models/pi05/__init__.py       |    2 +
 .../diffusion/models/pi05/test_pi05_parity.py |  500 ++++++++
 .../diffusion/models/pi05/test_pi05_units.py  | 1107 +++++++++++++++++
 .../e2e/online_serving/test_pi05_expansion.py |   86 ++
 .../openai_api/test_openpi_serving.py         |   52 +-
 tests/helpers/runtime.py                      |    3 +
 tests/model_tests/diffusion/test_alignment.py |    1 +
 vllm_omni/config/pipeline_registry.py         |    2 +
 vllm_omni/deploy/pi05.yaml                    |   51 +
 vllm_omni/diffusion/data.py                   |    5 +
 vllm_omni/diffusion/models/pi05/__init__.py   |   71 ++
 vllm_omni/diffusion/models/pi05/config.py     |  471 +++++++
 .../diffusion/models/pi05/modeling_pi05.py    |  898 +++++++++++++
 .../diffusion/models/pi05/pipeline_pi05.py    |  311 +++++
 .../diffusion/models/pi05/processor_pi05.py   |  568 +++++++++
 .../diffusion/models/pi05_pipeline_config.py  |   30 +
 vllm_omni/diffusion/registry.py               |    7 +
 vllm_omni/entrypoints/openpi/serving.py       |   14 +-
 22 files changed, 4342 insertions(+), 6 deletions(-)
 create mode 100644 recipes/lerobot/Pi05.md
 create mode 100644 tests/diffusion/models/pi05/__init__.py
 create mode 100644 tests/diffusion/models/pi05/test_pi05_parity.py
 create mode 100644 tests/diffusion/models/pi05/test_pi05_units.py
 create mode 100644 tests/e2e/online_serving/test_pi05_expansion.py
 create mode 100644 vllm_omni/deploy/pi05.yaml
 create mode 100644 vllm_omni/diffusion/models/pi05/__init__.py
 create mode 100644 vllm_omni/diffusion/models/pi05/config.py
 create mode 100644 vllm_omni/diffusion/models/pi05/modeling_pi05.py
 create mode 100644 vllm_omni/diffusion/models/pi05/pipeline_pi05.py
 create mode 100644 vllm_omni/diffusion/models/pi05/processor_pi05.py
 create mode 100644 vllm_omni/diffusion/models/pi05_pipeline_config.py

diff --git a/.buildkite/cuda/test-nightly.yml b/.buildkite/cuda/test-nightly.yml
index 1fdb1ef4a3f..adc94f9e9d6 100644
--- a/.buildkite/cuda/test-nightly.yml
+++ b/.buildkite/cuda/test-nightly.yml
@@ -223,6 +223,17 @@ steps:
             -m "full_model and diffusion and H100 and B200 and cards_1"
             --run-level "full_model"
 
+      - label: ":robot_face: Robot Policy OpenPI · π0.5 · H100 · Single-GPU"
+        timeout_in_minutes: 120
+        commands:
+          - pip install --no-deps "openpi-client @ git+https://github.com/Physical-Intelligence/openpi.git@215abfb217dbac7d5f1273282331b9b1866c0479#subdirectory=packages/openpi-client"
+          - >-
+            pytest -sv
+            tests/e2e/online_serving/test_pi05_expansion.py
+            -m "full_model and diffusion and H100 and cards_1"
+            --run-level "full_model"
+        mirror_hardwares: h100_1
+
       - label: ":full_moon: Diffusion X2I(&A&T) · Function Test with H100 · 2-GPU"
         source_file_dependencies: diffusion_qwen_image_function
         timeout_in_minutes: 120
diff --git a/docs/models/supported_models.md b/docs/models/supported_models.md
index 42971ed979b..f481154fb18 100644
--- a/docs/models/supported_models.md
+++ b/docs/models/supported_models.md
@@ -58,6 +58,7 @@ th {
 | `Magi2Pipeline` | MAGI-2 native Preview-stage T2VA and I2VA (272p/540p) | `sand-ai/MAGI-2-preview` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/SandAI/MAGI-2-preview-L20X.md) |
 | `DreamZeroPipeline` | DreamZero-DROID | `GEAR-Dreams/DreamZero-DROID` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
 | `Pi0Pipeline` | π0 (Pi-Zero) VLA | `lerobot/pi0_base` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/lerobot/Pi0.md) |
+| `Pi05Pipeline` | π0.5 VLA | `lerobot/pi05_base` | ✅︎ | | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/lerobot/Pi05.md) |
 | `HeliosPipeline`, `HeliosPyramidPipeline` | Helios | `BestWishYsh/Helios-Base`, `BestWishYsh/Helios-Mid`, `BestWishYsh/Helios-Distilled` | ✅︎ | ✅︎ | ✅︎ | | — |
 | `OvisImagePipeline` | Ovis-Image | `OvisAI/Ovis-Image` | ✅︎ | ✅︎ | | ✅︎ | — |
 | `LongcatImagePipeline` | LongCat-Image | `meituan-longcat/LongCat-Image` | ✅︎ | ✅︎ | ✅︎ | ✅︎ | — |
diff --git a/recipes/README.md b/recipes/README.md
index 078466e804a..a7c10ca145a 100644
--- a/recipes/README.md
+++ b/recipes/README.md
@@ -29,6 +29,8 @@ Example layout:
 
 ```text
 recipes/
+  lerobot/
+    Pi05.md
   Qwen/
     Qwen3-Omni-H100.md
     Qwen3-TTS-A100.md
@@ -53,6 +55,7 @@ recipes/
 | [`inclusionAI/Ming-flash-omni-2.0.md`](./inclusionAI/Ming-flash-omni-2.0.md) | Online serving for multimodal chat + standalone TTS | 4x H100 / 1x H100 80GB |
 | [`inclusionAI/Ming-omni-tts.md`](./inclusionAI/Ming-omni-tts.md) | Offline + online dense Ming TTS/audio generation | 1x H100 80GB / 1x AMD MI300X (ROCm 7.2) |
 | [`k2-fsa/OmniVoice.md`](./k2-fsa/OmniVoice.md) | Offline and online multilingual text-to-speech | 1x AMD MI300X (ROCm 7.2) |
+| [`lerobot/Pi05.md`](./lerobot/Pi05.md) | Online OpenPI serving for the π0.5 vision-language-action policy | 1x H100 80GB |
 | [`IndexTeam/IndexTTS-2.md`](./IndexTeam/IndexTTS-2.md) | Online serving for voice-cloned TTS with optional emotion control | 1x L4 24GB or larger CUDA GPU |
 | [`IndexTeam/IndexTTS-2_5.md`](./IndexTeam/IndexTTS-2_5.md) | Online + offline multilingual voice-cloned TTS with native speed and emotion control | 1x NVIDIA H20 96GB |
 | [`MiniMaxAI/MiniMax-H3.md`](./MiniMaxAI/MiniMax-H3.md) | T2VA, FL2VA, image+audio Ref2VA, and multi-video Ref2VA serving | 1x GPU with CPU offload / 4x B300 |
diff --git a/recipes/lerobot/Pi05.md b/recipes/lerobot/Pi05.md
new file mode 100644
index 00000000000..af648f5ad33
--- /dev/null
+++ b/recipes/lerobot/Pi05.md
@@ -0,0 +1,154 @@
+# Pi0.5 (π0.5) VLA
+
+> Vision-Language-Action policy serving over the OpenPI realtime websocket
+
+## Summary
+
+- Vendor: Physical Intelligence (checkpoint redistributed by LeRobot)
+- Model: `lerobot/pi05_base`
+- Task: Vision-Language-Action — multi-camera images + a language instruction +
+  robot proprioceptive state → a continuous action chunk
+  `[action_horizon, action_dim] = [50, 32]` via flow-matching denoising. π0.5
+  does **not** emit text tokens.
+- Mode: Online serving via the OpenPI realtime robot API
+  (`/v1/realtime/robot/openpi` websocket)
+- Maintainer: Community
+
+## When to use this recipe
+
+Use this recipe to deploy `lerobot/pi05_base` as a robot policy server: a robot
+client connects over the OpenPI websocket and, per control step, sends an
+observation (camera frames + state + instruction) and receives an action chunk.
+
+A single pipeline class (`Pi05Pipeline`) serves the policy. π0.5 is stateless
+across calls (first-order Markov, no KV reuse), so the protocol's `session_id` /
+`reset` are accepted but ignored.
+
+This recipe covers the functional path only. Serving runs in eager mode, with no
+CUDA Graph capture, no Triton kernels and no prefix or encoder caching, and both
+`float32` and `bfloat16` are supported. Two π0.5 capabilities are not
+implemented, and a checkpoint that declares either is rejected when it loads:
+
+- **MEM** short-horizon observation memory (`use_visual_memory`,
+  `use_proprioceptive_memory`)
+- **RTC** real-time chunking (`rtc_config`)
+
+A checkpoint with `use_relative_actions` must also carry `action_feature_names`
+in `config.json`.
+
+## Weights
+
+| Component | Params | Part of |
+| --- | ---: | --- |
+| Vision tower, SigLIP So400m/14 | 412 M | PaliGemma |
+| Language model, Gemma-2B, with the multimodal projector | 2.51 B | PaliGemma |
+| Action expert, Gemma-300M, with AdaRMS and the action/time heads | 693 M | π0.5 |
+| Total | 3.62 B | 13.5 GiB in float32 |
+
+| Artifact | Repository |
+| --- | --- |
+| `model.safetensors`, 812 tensors, ~14.5 GB | `lerobot/pi05_base` |
+| `policy_preprocessor.json` + `policy_preprocessor_step_*.safetensors` | `lerobot/pi05_base` |
+| Tokenizer, gated | `google/paligemma-3b-pt-224` |
+
+## Hardware Support
+
+### 1x H100 80GB (Online serving)
+
+The nightly end-to-end job runs on one H100, and serving was also verified on an
+RTX 4090 and an RTX PRO 5000.
+
+#### Environment
+
+- OS: Ubuntu 22.04+
+- Python: 3.12+
+- Driver / runtime: NVIDIA CUDA environment
+- vLLM / vLLM-Omni: use the commit you are deploying from
+- Hugging Face: `google/paligemma-3b-pt-224` license accepted, `hf auth login`
+- OpenPI client extras (robot side, and for the e2e test): `openpi-client`,
+  `websockets`, `msgpack`, `msgpack-numpy`. CI pins `openpi-client` to OpenPI
+  revision `215abfb217dbac7d5f1273282331b9b1866c0479`.
+
+#### Command
+
+```bash
+vllm serve lerobot/pi05_base \
+  --omni \
+  --host 0.0.0.0 --port 8000 \
+  --deploy-config vllm_omni/deploy/pi05.yaml \
+  --enforce-eager --disable-log-stats
+```
+
+The deploy config (`vllm_omni/deploy/pi05.yaml`) declares a single diffusion
+stage (`Pi05Pipeline`), `float32`, `max_num_seqs: 1`, `tokenizer_max_length: 200`
+and `state_num_bins: 256`, together with the `policy_server_config` handshake
+metadata (3 cameras, `joint_position`, action horizon 50, action dim 32) that
+enables the OpenPI realtime serving layer. Keep `action_horizon`, `action_dim`
+and `image_resolution` in that block in sync with `model_config`.
+
+To serve in bfloat16, set `dtype: bfloat16` in the same file.
+
+#### Verification
+
+The observation is a flat dict per inference:
+
+```python
+{
+    "observation.images.base_0_rgb":        np.uint8[H, W, 3],  # or float32 in [0, 1]
+    "observation.images.left_wrist_0_rgb":  np.uint8[H, W, 3],
+    "observation.images.right_wrist_0_rgb": np.uint8[H, W, 3],
+    "state":   np.float32[state_dim],   # must match the checkpoint's declared width
+    "prompt":  "pick up the red block",
+    "session_id": "<uuid>",             # accepted but ignored (π0.5 is stateless)
+    "sampling_params": {"num_inference_steps": 4},   # optional engine knobs
+}
+```
+
+Camera keys must match the server's `image_feature_keys`, which is the
+checkpoint's `input_features` order. If your robot uses different camera names,
+set `model_config.image_key_map` in `pi05.yaml` to map raw obs keys → feature
+keys. Every request needs at least one configured camera and a non-null state.
+
+`state` must have the width `input_features["observation.state"]` declares, 32
+for `lerobot/pi05_base`. That checkpoint ships no normalization statistics, so
+its values must already be normalized.
+
+PIL and uint8 images use the `[0, 255]` domain, while floating ndarray and
+tensor images must be finite and in `[0, 1]`. Both are converted with
+`x * 2 - 1`.
+
+Engine knobs live under `sampling_params`. It currently holds
+`num_inference_steps`, which overrides the deploy-config denoising steps for a
+single request.
+
+### Target-hardware validation
+
+Client E2E round trip over the OpenPI websocket: msgpack pack, send, engine,
+denoise, unpack. Eager, batch 1, 10 denoising steps, p50 of 30 round
+trips after 3 warmup.
+
+| GPU | dtype | Client E2E p50 (ms), 1 / 2 / 3 cameras | Device peak (GiB) |
+| --- | --- | ---: | ---: |
+| H100 80 GB HBM3 (sm_90) | float32 | 282 / 356 / 398 | 15.0 |
+| H100 80 GB HBM3 (sm_90) | bfloat16 | 290 / 301 / 312 | 9.1 |
+| RTX PRO 5000 72 GB (sm_120) | float32 | 185 / 231 / 281 | 14.8 |
+| RTX PRO 5000 72 GB (sm_120) | bfloat16 | 156 / 177 / 203 | 8.9 |
+
+## Correctness
+
+π0.5's flow-matching kernel reproduces the LeRobot `PI05Policy` reference
+exactly (`max|Δ| = 0`, CPU/float32, fixed noise, 1/2/3 cameras). The same file
+also compares the prompt tokens carrying the discretized state, the
+relative-action path, and a bfloat16 run against LeRobot in bfloat16:
+`tests/diffusion/models/pi05/test_pi05_parity.py`.
+
+## References
+
+- Model blog: <https://www.physicalintelligence.company/blog/pi05>
+- LeRobot π0.5 docs: <https://github.com/huggingface/lerobot/blob/main/docs/source/policy_pi05_README.md>
+- Checkpoint: <https://huggingface.co/lerobot/pi05_base>
+- Pipeline: [`vllm_omni/diffusion/models/pi05/pipeline_pi05.py`](../../vllm_omni/diffusion/models/pi05/pipeline_pi05.py)
+- Deploy config: [`vllm_omni/deploy/pi05.yaml`](../../vllm_omni/deploy/pi05.yaml)
+- Tests: CPU units + LeRobot parity in [`tests/diffusion/models/pi05/`](../../tests/diffusion/models/pi05/),
+  OpenPI websocket e2e in
+  [`tests/e2e/online_serving/test_pi05_expansion.py`](../../tests/e2e/online_serving/test_pi05_expansion.py)
diff --git a/tests/diffusion/models/pi05/__init__.py b/tests/diffusion/models/pi05/__init__.py
new file mode 100644
index 00000000000..4244ce4b4e1
--- /dev/null
+++ b/tests/diffusion/models/pi05/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
diff --git a/tests/diffusion/models/pi05/test_pi05_parity.py b/tests/diffusion/models/pi05/test_pi05_parity.py
new file mode 100644
index 00000000000..fb30cb44518
--- /dev/null
+++ b/tests/diffusion/models/pi05/test_pi05_parity.py
@@ -0,0 +1,500 @@
+#!/usr/bin/env python
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""π0.5 parity against LeRobot.
+
+Reference: **lerobot 0.6.1**, transformers 5.5.4, torch 2.11.0+cpu. The oracle
+is LeRobot's own code, so a later version changing its π0.5 implementation
+fails this without anything here regressing — diff ``policies/pi05/`` first.
+
+Compares final action chunks under fixed noise: float32 exactly, bfloat16
+against LeRobot's own bfloat16 layout within ``BF16_ATOL``.
+
+Needs a separate ``lerobot[pi]`` venv (its dependencies conflict with
+vllm-omni's) with the vllm-omni ``pi05`` package importable::
+
+    python -m pytest tests/diffusion/models/pi05/test_pi05_parity.py -v -s
+
+Skips itself when LeRobot is absent. ``PI05_PARITY_MODEL_PATH`` points at a
+local checkpoint to skip the HF download.
+"""
+
+from __future__ import annotations
+
+import copy
+import importlib.util
+import os
+
+import pytest
+import torch
+
+# local_model: needs real weights + a lerobot venv, so it runs locally rather
+# than in the ready-CI. Additionally gated on lerobot being importable.
+_HAS_LEROBOT = importlib.util.find_spec("lerobot") is not None
+
+# cpu: the comparison runs on CPU in float32 so both implementations see
+# identical numerics; local_model: it needs a lerobot venv that CI does not have.
+pytestmark = [pytest.mark.local_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+# ─── Config (fixed; matches LeRobot defaults for a π0.5 checkpoint) ────
+DEVICE = "cpu"
+DTYPE_STR = "float32"
+ATOL = 1e-4
+BF16_ATOL = 5e-2  # measured 2.95e-2, reproducible; margin is for version drift
+NUM_STEPS = 10
+BATCH_SIZE = 2
+ACTION_DIM = 32
+STATE_DIM = 32
+ACTION_HORIZON = 50
+MAX_TOKEN_LEN = 200  # π0 uses 48
+NUM_STATE_BINS = 256
+
+MODEL_PATH = os.environ.get("PI05_PARITY_MODEL_PATH", "lerobot/pi05_base")
+
+CAMERAS = ("base_0_rgb", "left_wrist_0_rgb", "right_wrist_0_rgb")
+
+
+def _resolve_checkpoint_dir() -> str:
+    if os.path.isdir(MODEL_PATH):
+        return MODEL_PATH
+    from huggingface_hub import snapshot_download
+
+    return snapshot_download(repo_id=MODEL_PATH, repo_type="model")
+
+
+# ─── Dummy dataset stats ──────────────────────────────────────────────
+def _dummy_dataset_stats() -> dict:
+    """Identity-ish stats. π0.5 normalizes with QUANTILES by default, so q01/q99
+    carry the load here where π0's mean/std would.
+
+    Using dummy stats means this test needs no checkpoint with real
+    ``norm_stats`` — it verifies numerical equivalence, not calibration.
+    """
+    return {
+        "observation.state": {
+            "mean": torch.zeros(STATE_DIM),
+            "std": torch.ones(STATE_DIM),
+            "q01": -torch.ones(STATE_DIM),
+            "q99": torch.ones(STATE_DIM),
+        },
+        "action": {
+            "mean": torch.zeros(ACTION_DIM),
+            "std": torch.ones(ACTION_DIM),
+            "q01": -torch.ones(ACTION_DIM),
+            "q99": torch.ones(ACTION_DIM),
+        },
+        "images": {
+            cam: {
+                "mean": torch.zeros(3, 224, 224),
+                "std": torch.ones(3, 224, 224),
+                "q01": torch.zeros(3, 224, 224),
+                "q99": torch.ones(3, 224, 224),
+            }
+            for cam in CAMERAS
+        },
+    }
+
+
+def _create_dummy_batch(batch_size: int = BATCH_SIZE, num_views: int = 3, device: str = DEVICE) -> dict:
+    """Reproducible dummy inputs — identical across both implementations."""
+    g = torch.Generator(device="cpu").manual_seed(0)
+    prompt = "Pick up the red block and place it in the bin"
+    batch = {
+        "observation.state": torch.randn(batch_size, STATE_DIM, generator=g, dtype=torch.float32).to(device),
+        "action": torch.randn(batch_size, ACTION_HORIZON, ACTION_DIM, generator=g, dtype=torch.float32).to(device),
+        "task": [prompt for _ in range(batch_size)],
+    }
+    for cam in CAMERAS[:num_views]:
+        batch[f"observation.images.{cam}"] = torch.rand(batch_size, 3, 224, 224, generator=g, dtype=torch.float32).to(
+            device
+        )
+    return batch
+
+
+# ─── Instantiation ────────────────────────────────────────────────────
+def _instantiate_lerobot(use_relative_actions: bool = False, action_feature_names=None, dtype: str = DTYPE_STR):
+    from lerobot.policies.pi05 import PI05Policy
+    from lerobot.policies.pi05.processor_pi05 import make_pi05_pre_post_processors
+
+    policy = PI05Policy.from_pretrained(MODEL_PATH, strict=True, dtype=dtype)
+    policy.to(DEVICE)
+    policy.config.device = DEVICE
+    policy.config.use_relative_actions = use_relative_actions
+    if action_feature_names is not None:
+        # Must land on the config *before* the processors are built:
+        # make_pi05_pre_post_processors captures action_feature_names into
+        # RelativeActionsProcessorStep at construction time, and its _build_mask
+        # treats ``action_names is None`` as "shift every dim" — including the
+        # gripper that relative_exclude_joints is supposed to hold back. Setting
+        # it afterwards leaves the step with the all-True mask and silently
+        # compares two different transforms.
+        policy.config.action_feature_names = action_feature_names
+    policy.eval()
+
+    pre, post = make_pi05_pre_post_processors(config=policy.config, dataset_stats=_dummy_dataset_stats())
+    return policy, pre, post
+
+
+def _instantiate_vllm_omni(
+    use_relative_actions: bool = False,
+    action_feature_names=None,
+    dtype: str = DTYPE_STR,
+):
+    """Build the vllm-omni π0.5 model in isolation (no pipeline, no engine)."""
+    from vllm_omni.diffusion.models.pi05 import Pi05Config, Pi05ForActionPrediction
+    from vllm_omni.diffusion.models.pi05.pipeline_pi05 import _set_inference_dtype
+
+    cfg = Pi05Config(
+        max_action_dim=ACTION_DIM,
+        max_state_dim=STATE_DIM,
+        chunk_size=ACTION_HORIZON,
+        num_inference_steps=NUM_STEPS,
+        tokenizer_max_length=MAX_TOKEN_LEN,
+        state_num_bins=NUM_STATE_BINS,
+        dtype=dtype,
+        use_relative_actions=use_relative_actions,
+        relative_exclude_joints=["gripper"] if action_feature_names else [],
+        action_feature_names=action_feature_names,
+    )
+    model = Pi05ForActionPrediction(cfg)
+    _set_inference_dtype(model, getattr(torch, dtype))
+    model.to(device=DEVICE)
+    _load_lerobot_weights(model)
+    model.eval()
+    return model, cfg
+
+
+def _load_lerobot_weights(model):
+    import safetensors.torch
+
+    path = os.path.join(_resolve_checkpoint_dir(), "model.safetensors")
+    state = safetensors.torch.load_file(path)
+    filled = model.load_weights(list(state.items()))
+    assert filled, "no weights were loaded — the remap rules are broken"
+
+
+def _extract_lerobot_model_inputs(lerobot_policy, processed_batch):
+    """Mimic what ``PI05Policy.predict_action_chunk`` feeds into
+    ``self.model.sample_actions``. Using these *exact* tensors for vllm-omni
+    means any divergence must come from the core model, not preprocessing.
+
+    Note π0.5 has no ``prepare_state`` step: the state is already inside
+    ``lang_tokens``.
+    """
+    from lerobot.utils.constants import (
+        OBS_LANGUAGE_ATTENTION_MASK,
+        OBS_LANGUAGE_TOKENS,
+    )
+
+    images, img_masks = lerobot_policy._preprocess_images(processed_batch)
+    return images, img_masks, processed_batch[OBS_LANGUAGE_TOKENS], processed_batch[OBS_LANGUAGE_ATTENTION_MASK]
+
+
+def _make_fixed_noise(batch_size: int, device: str) -> torch.Tensor:
+    g = torch.Generator(device="cpu").manual_seed(42)
+    return torch.randn(batch_size, ACTION_HORIZON, ACTION_DIM, generator=g, dtype=torch.float32).to(device)
+
+
+# ─── Main parity test ─────────────────────────────────────────────────
+@pytest.mark.skipif(not _HAS_LEROBOT, reason="lerobot not installed (run in a lerobot venv).")
+@pytest.mark.parametrize("num_views", [1, 2, 3])
+def test_pi05_vllm_omni_vs_lerobot(num_views):
+    lerobot_policy, lerobot_pre, _ = _instantiate_lerobot()
+    omni_model, _ = _instantiate_vllm_omni()
+
+    raw_batch = _create_dummy_batch(num_views=num_views)
+    processed = lerobot_pre(copy.deepcopy(raw_batch))
+    images, img_masks, lang_tokens, lang_masks = _extract_lerobot_model_inputs(lerobot_policy, processed)
+    noise = _make_fixed_noise(raw_batch["observation.state"].shape[0], DEVICE)
+
+    # The input contract: 256 tokens per view + a constant 200 text tokens.
+    assert lang_tokens.shape[1] == MAX_TOKEN_LEN, "π0.5 must pad text to exactly 200 tokens"
+
+    with torch.no_grad():
+        lerobot_actions = lerobot_policy.model.sample_actions(
+            images, img_masks, lang_tokens, lang_masks, noise=noise, num_steps=NUM_STEPS
+        )
+        omni_actions = omni_model.sample_actions(
+            images=images,
+            image_masks=img_masks,
+            lang_tokens=lang_tokens,
+            lang_masks=lang_masks,
+            noise=noise,
+            num_steps=NUM_STEPS,
+        )
+
+    diff = (lerobot_actions.float() - omni_actions.float()).abs()
+    print(f"[parity] views={num_views} |Δ| max={diff.max().item():.2e} mean={diff.mean().item():.2e}")
+    if not torch.allclose(lerobot_actions.float(), omni_actions.float(), atol=ATOL):
+        _diagnose_divergence(lerobot_policy.model, omni_model, images, img_masks, lang_tokens, lang_masks, noise)
+    assert torch.allclose(lerobot_actions.float(), omni_actions.float(), atol=ATOL), (
+        f"actions differ beyond atol={ATOL}; max_diff={diff.max().item():.2e}"
+    )
+
+
+@pytest.mark.skipif(not _HAS_LEROBOT, reason="lerobot not installed (run in a lerobot venv).")
+def test_pi05_bfloat16_matches_lerobot_bfloat16():
+    """Both sides in bfloat16, so this compares implementations rather than
+    measuring bfloat16's drift from float32."""
+    # LeRobot applies the layout in PaliGemmaWithExpertModel.__init__ from
+    # config.dtype, so the policy must be built as bfloat16 rather than cast after.
+    lerobot_policy, lerobot_pre, _ = _instantiate_lerobot(dtype="bfloat16")
+
+    omni_model, _ = _instantiate_vllm_omni(dtype="bfloat16")
+
+    raw_batch = _create_dummy_batch(num_views=3)
+    processed = lerobot_pre(copy.deepcopy(raw_batch))
+    images, img_masks, lang_tokens, lang_masks = _extract_lerobot_model_inputs(lerobot_policy, processed)
+    noise = _make_fixed_noise(raw_batch["observation.state"].shape[0], DEVICE)
+
+    with torch.no_grad():
+        lerobot_actions = lerobot_policy.model.sample_actions(
+            images, img_masks, lang_tokens, lang_masks, noise=noise, num_steps=NUM_STEPS
+        )
+        omni_actions = omni_model.sample_actions(
+            images=images,
+            image_masks=img_masks,
+            lang_tokens=lang_tokens,
+            lang_masks=lang_masks,
+            noise=noise,
+            num_steps=NUM_STEPS,
+        )
+
+    diff = (lerobot_actions.float() - omni_actions.float()).abs()
+    print(f"[parity] bfloat16 |Δ| max={diff.max().item():.2e} mean={diff.mean().item():.2e}")
+    assert torch.allclose(lerobot_actions.float(), omni_actions.float(), atol=BF16_ATOL), (
+        f"bfloat16 actions differ beyond atol={BF16_ATOL}; max_diff={diff.max().item():.2e}"
+    )
+
+
+@pytest.mark.skipif(not _HAS_LEROBOT, reason="lerobot not installed (run in a lerobot venv).")
+def test_pi05_prompt_parity():
+    """π0.5's state is carried as prompt tokens, so the tokenized prompt is
+    itself part of the contract. A bin-index mismatch here (e.g. from running
+    the discretizer before the normalizer) would otherwise only surface as a
+    small, plausible-looking action difference.
+    """
+    from transformers import AutoTokenizer
+
+    from vllm_omni.diffusion.models.pi05.processor_pi05 import (
+        apply_norm,
+        build_norm_stats,
+        build_pi05_prompt,
+        tokenize_prompt,
+    )
+
+    lerobot_policy, lerobot_pre, _ = _instantiate_lerobot()
+    raw_batch = _create_dummy_batch(batch_size=1)
+    processed = lerobot_pre(copy.deepcopy(raw_batch))
+
+    from lerobot.utils.constants import OBS_LANGUAGE_TOKENS
+
+    lerobot_tokens = processed[OBS_LANGUAGE_TOKENS][0]
+
+    stats = _dummy_dataset_stats()["observation.state"]
+    norm = build_norm_stats({"state": {"q01": stats["q01"], "q99": stats["q99"]}}, "state")
+    normalized = apply_norm(raw_batch["observation.state"][0].float(), norm)
+    prompt = build_pi05_prompt(
+        task=raw_batch["task"][0],
+        normalized_state=normalized.numpy(),
+        state_num_bins=NUM_STATE_BINS,
+    )
+    tokenizer = AutoTokenizer.from_pretrained("google/paligemma-3b-pt-224", padding_side="right")
+    ids, _ = tokenize_prompt(tokenizer, prompt, MAX_TOKEN_LEN)
+
+    assert len(ids) == MAX_TOKEN_LEN
+    assert torch.equal(torch.tensor(ids), lerobot_tokens.cpu()), "π0.5 prompt tokens diverge from LeRobot"
+
+
+@pytest.mark.skipif(not _HAS_LEROBOT, reason="lerobot not installed (run in a lerobot venv).")
+@pytest.mark.parametrize("state_dim", [7, STATE_DIM])
+def test_pi05_prompt_parity_across_state_widths(state_dim):
+    """``pi05_base`` declares a 32-dim state, which is exactly ``max_state_dim``,
+    so the full-policy parity above cannot tell padding apart from the real
+    width. This drives LeRobot's tokenizer step directly, at both widths.
+    """
+    from lerobot.lerobot_types import TransitionKey
+    from lerobot.policies.pi05.processor_pi05 import Pi05PrepareStateTokenizerProcessorStep
+    from lerobot.utils.constants import OBS_STATE
+
+    from vllm_omni.diffusion.models.pi05.processor_pi05 import build_pi05_prompt
+
+    g = torch.Generator().manual_seed(state_dim)
+    state = torch.randn(state_dim, generator=g, dtype=torch.float32)
+    task = "pick up the red block"
+
+    step = Pi05PrepareStateTokenizerProcessorStep(max_state_dim=STATE_DIM)
+    transition = step(
+        {
+            TransitionKey.OBSERVATION: {OBS_STATE: state.unsqueeze(0)},
+            TransitionKey.COMPLEMENTARY_DATA: {"task": [task]},
+        }
+    )
+    lerobot_prompt = transition[TransitionKey.COMPLEMENTARY_DATA]["task"][0]
+
+    prompt = build_pi05_prompt(task=task, normalized_state=state.numpy())
+
+    assert prompt == lerobot_prompt
+    assert len(prompt.split("State: ")[1].split(";")[0].split()) == state_dim
+
+
+@pytest.mark.skipif(not _HAS_LEROBOT, reason="lerobot not installed (run in a lerobot venv).")
+@pytest.mark.parametrize(
+    "lerobot_mode,stats,ours,state,state_dim",
+    [
+        ("MEAN_STD", {"mean": [0.0], "std": [1e-7]}, {"mode": "mean_std", "mean": [0.0], "std": [1e-7]}, [1e-7], 1),
+        ("QUANTILES", {"q01": [0.0], "q99": [1e-7]}, {"mode": "quantile", "q01": [0.0], "q99": [1e-7]}, [1e-7], 1),
+        ("QUANTILES", {"q01": [2.0], "q99": [2.0]}, {"mode": "quantile", "q01": [2.0], "q99": [2.0]}, [2.0], 1),
+        (
+            "QUANTILES",
+            {"q01": [0.0] * 4, "q99": [10.0] * 4},
+            {"mode": "quantile", "q01": [0.0] * 4, "q99": [10.0] * 4},
+            [-10.0, 0.0, 5.0, 20.0],
+            4,
+        ),
+        (
+            "MEAN_STD",
+            {"mean": [1.0, 2.0], "std": [0.5, 4.0]},
+            {"mode": "mean_std", "mean": [1.0, 2.0], "std": [0.5, 4.0]},
+            [3.0, -6.0],
+            2,
+        ),
+        ("MIN_MAX", {"min": [-1.0], "max": [3.0]}, {"mode": "min_max", "min": [-1.0], "max": [3.0]}, [2.0], 1),
+    ],
+)
+def test_pi05_state_normalization_parity(lerobot_mode, stats, ours, state, state_dim):
+    """State normalization against LeRobot's ``NormalizerProcessorStep``.
+
+    The full-policy parity test feeds both sides stats with a wide range, so it
+    cannot see the denominator rule. A wrongly normalized state still discretizes
+    into a well-formed prompt: for ``q01=0, q99=1e-7`` a threshold substitution
+    moves the state token from bin 255 to bin 0.
+    """
+    from lerobot.configs.types import FeatureType, NormalizationMode, PolicyFeature
+    from lerobot.processor.normalize_processor import NormalizerProcessorStep
+    from lerobot.utils.constants import OBS_STATE
+
+    from vllm_omni.diffusion.models.pi05.processor_pi05 import apply_norm, build_norm_stats
+
+    step = NormalizerProcessorStep(
+        features={OBS_STATE: PolicyFeature(type=FeatureType.STATE, shape=(state_dim,))},
+        norm_map={FeatureType.STATE: getattr(NormalizationMode, lerobot_mode)},
+        stats={OBS_STATE: {k: torch.tensor(v, dtype=torch.float32) for k, v in stats.items()}},
+    )
+    expected = step._apply_transform(
+        torch.tensor(state, dtype=torch.float32), OBS_STATE, FeatureType.STATE, inverse=False
+    )
+
+    actual = apply_norm(torch.tensor(state, dtype=torch.float32), build_norm_stats({"state": ours}, "state"))
+
+    assert torch.allclose(actual, expected, atol=1e-6)
+
+
+@pytest.mark.skipif(not _HAS_LEROBOT, reason="lerobot not installed (run in a lerobot venv).")
+def test_pi05_relative_actions_parity():
+    """With ``use_relative_actions=True`` the checkpoint's norm_stats live in
+    relative space, so the post-pipeline must add the raw state back. Compares
+    the full pre → model → post path against LeRobot's."""
+    from lerobot.utils.constants import (
+        OBS_LANGUAGE_ATTENTION_MASK,
+        OBS_LANGUAGE_TOKENS,
+    )
+
+    from vllm_omni.diffusion.models.pi05.processor_pi05 import (
+        Pi05RelativeActions,
+        apply_norm,
+        build_norm_stats,
+    )
+
+    action_names = [f"joint_{i}" for i in range(ACTION_DIM - 1)] + ["gripper"]
+    lerobot_policy, lerobot_pre, lerobot_post = _instantiate_lerobot(
+        use_relative_actions=True, action_feature_names=action_names
+    )
+    omni_model, cfg = _instantiate_vllm_omni(use_relative_actions=True, action_feature_names=action_names)
+
+    raw_batch = _create_dummy_batch()
+    processed = lerobot_pre(copy.deepcopy(raw_batch))
+    images, img_masks = lerobot_policy._preprocess_images(processed)
+    lang_tokens = processed[OBS_LANGUAGE_TOKENS]
+    lang_masks = processed[OBS_LANGUAGE_ATTENTION_MASK]
+    noise = _make_fixed_noise(raw_batch["observation.state"].shape[0], DEVICE)
+
+    with torch.no_grad():
+        lerobot_actions = lerobot_post(
+            lerobot_policy.model.sample_actions(
+                images, img_masks, lang_tokens, lang_masks, noise=noise, num_steps=NUM_STEPS
+            )
+        )
+        omni_raw = omni_model.sample_actions(
+            images=images,
+            image_masks=img_masks,
+            lang_tokens=lang_tokens,
+            lang_masks=lang_masks,
+            noise=noise,
+            num_steps=NUM_STEPS,
+        )
+
+    rel = Pi05RelativeActions(
+        enabled=True,
+        exclude_joints=cfg.relative_exclude_joints,
+        action_names=action_names,
+        max_action_dim=ACTION_DIM,
+    )
+    omni_actions = apply_norm(omni_raw, build_norm_stats(cfg.norm_stats, "action"), inverse=True)
+    # Per-sample reference state, matching LeRobot: its
+    # RelativeActionsProcessorStep caches the whole (B, D) state on the input
+    # side and shifts each sample by its own row. Passing a single row here
+    # would shift every sample by sample 0's state, which only agrees for B=1.
+    omni_actions = rel.to_absolute(omni_actions, raw_batch["observation.state"])
+
+    lerobot_actions = torch.as_tensor(lerobot_actions).float()
+    assert torch.allclose(lerobot_actions, omni_actions.float(), atol=ATOL), (
+        "relative-action path diverges from LeRobot; "
+        f"max_diff={(lerobot_actions - omni_actions.float()).abs().max().item():.2e}"
+    )
+
+
+# ─── Per-stage divergence diagnostics ─────────────────────────────────
+@torch.no_grad()
+def _diagnose_divergence(lerobot_flow_model, omni_model, images, img_masks, lang_tokens, lang_masks, noise):
+    """Localize a numerical mismatch to a specific stage:
+    1. Prefix embeddings (SigLIP / embed_tokens / projector) — image vs lang.
+    2. Prefix KV cache layer 0 — PaliGemma LM attention.
+    3. The AdaRMS timestep conditioning vector.
+    4. A single denoise_step velocity at t=1.0 — action expert forward.
+    """
+    from vllm_omni.diffusion.models.pi05.modeling_pi05 import (
+        make_att_2d_masks,
+        prepare_attention_masks_4d,
+    )
+
+    lr_embs, lr_pad, lr_att = lerobot_flow_model.embed_prefix(images, img_masks, lang_tokens, lang_masks)
+    sg_embs, sg_pad, sg_att = omni_model.embed_prefix(images, img_masks, lang_tokens, lang_masks)
+    print(f"[diag] prefix_embs max|Δ| = {(lr_embs.float() - sg_embs.float()).abs().max().item():.2e}")
+    print(f"[diag] prefix_pad_masks equal: {torch.equal(lr_pad, sg_pad)}")
+
+    img_len = 256 * len(images)
+    print(f"[diag]   image slice max|Δ| = {(lr_embs[:, :img_len] - sg_embs[:, :img_len]).abs().max().item():.2e}")
+    print(f"[diag]   lang  slice max|Δ| = {(lr_embs[:, img_len:] - sg_embs[:, img_len:]).abs().max().item():.2e}")
+
+    prefix_att_4d = prepare_attention_masks_4d(make_att_2d_masks(sg_pad, sg_att))
+    prefix_pos = torch.cumsum(sg_pad, dim=1) - 1
+    _, sg_kv = omni_model.paligemma_with_expert.forward(
+        attention_mask=prefix_att_4d,
+        position_ids=prefix_pos,
+        past_key_values=None,
+        inputs_embeds=[sg_embs, None],
+        use_cache=True,
+    )
+
+    t = torch.ones(noise.shape[0], dtype=torch.float32)
+    sg_cond = omni_model.embed_timestep(t)
+    print(f"[diag] adarms cond: shape={tuple(sg_cond.shape)} mean={sg_cond.mean().item():+.4f}")
+
+    sg_vt = omni_model.denoise_step(sg_pad, sg_kv, noise, t)
+    print(f"[diag] denoise_step(t=1) v_t mean={sg_vt.mean().item():+.6f}")
+
+
+if __name__ == "__main__":
+    test_pi05_vllm_omni_vs_lerobot(3)
diff --git a/tests/diffusion/models/pi05/test_pi05_units.py b/tests/diffusion/models/pi05/test_pi05_units.py
new file mode 100644
index 00000000000..26671a59c0a
--- /dev/null
+++ b/tests/diffusion/models/pi05/test_pi05_units.py
@@ -0,0 +1,1107 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""CPU unit tests for the π0.5 VLA model.
+
+Deliberately lightweight: config plumbing and the checkpoint-boundary rule, the
+state discretization path, relative actions, and the weight-load remap. Runs on
+CPU with no weights and no lerobot. The full LeRobot parity check lives in
+``tests/diffusion/models/pi05/test_pi05_parity.py``.
+
+Most assertions here guard *silent* failure modes — cases where the wrong
+behaviour still produces a well-shaped, finite action chunk:
+
+  * normalization must run before state discretization;
+  * the normalization mode comes from the checkpoint, since π0.5 defaults to
+    quantile where π0 defaults to ``mean_std``;
+  * relative-action checkpoints must be honoured, and an unresolvable
+    ``relative_exclude_joints`` must raise rather than silently make every
+    dimension relative;
+  * MEM / RTC checkpoints must be rejected rather than served incorrectly.
+
+    pytest tests/diffusion/models/pi05/test_pi05_units.py -v
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+import numpy as np
+import pytest
+import torch
+
+from vllm_omni.diffusion.models.pi05 import modeling_pi05
+from vllm_omni.diffusion.models.pi05.config import (
+    Pi05Config,
+    UnsupportedCheckpointCapabilityError,
+    load_lerobot_norm_stats,
+    resolve_excluded_action_indices,
+)
+from vllm_omni.diffusion.models.pi05.modeling_pi05 import (
+    GemmaVariantConfig,
+    Pi05AdaRMSNorm,
+    Pi05ForActionPrediction,
+    create_sinusoidal_pos_embedding,
+    get_gemma_config,
+    make_att_2d_masks,
+)
+from vllm_omni.diffusion.models.pi05.processor_pi05 import (
+    Pi05ImageProcessor,
+    Pi05Processor,
+    Pi05RelativeActions,
+    _assemble_model_inputs,
+    apply_norm,
+    as_state_vector,
+    build_norm_stats,
+    build_pi05_prompt,
+    discretize_state,
+    resize_with_pad,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+# ----------------------------------------------------------------------------
+# Pi05Config dataclass + checkpoint resolver
+# ----------------------------------------------------------------------------
+_LEROBOT_CFG: dict[str, Any] = {
+    "type": "pi05",
+    "paligemma_variant": "gemma_2b",
+    "action_expert_variant": "gemma_300m",
+    "chunk_size": 50,
+    "max_action_dim": 32,
+    "max_state_dim": 32,
+    "num_inference_steps": 10,
+    "image_resolution": [224, 224],
+    "tokenizer_max_length": 200,
+    "dtype": "float32",
+    "input_features": {
+        "observation.images.base_0_rgb": {"type": "VISUAL", "shape": [3, 224, 224]},
+        "observation.images.left_wrist_0_rgb": {"type": "VISUAL", "shape": [3, 224, 224]},
+        "observation.images.right_wrist_0_rgb": {"type": "VISUAL", "shape": [3, 224, 224]},
+        "observation.state": {"type": "STATE", "shape": [32]},
+    },
+    "output_features": {"action": {"type": "ACTION", "shape": [32]}},
+}
+
+_EXPECTED_CAMERA_ORDER = [
+    "observation.images.base_0_rgb",
+    "observation.images.left_wrist_0_rgb",
+    "observation.images.right_wrist_0_rgb",
+]
+
+_ACTION_NAMES = ["joint_0", "joint_1", "joint_2", "joint_3", "joint_4", "joint_5", "gripper"]
+
+
+def test_config_parses_lerobot_pi05_json():
+    """``_LEROBOT_CFG`` mirrors the runtime keys of a real checkpoint."""
+    c = Pi05Config.from_model_config(_LEROBOT_CFG)
+    assert c.tokenizer_max_length == 200
+    assert c.state_num_bins == 256
+    assert c.image_feature_keys == _EXPECTED_CAMERA_ORDER
+    assert c.image_resolution == (224, 224)
+
+
+def test_config_rejects_wrong_model_type():
+    with pytest.raises(ValueError, match="type='pi05'"):
+        Pi05Config.from_model_config(dict(_LEROBOT_CFG, type="pi0"))
+
+
+def test_config_rejects_unsupported_partial_action_chunk():
+    with pytest.raises(UnsupportedCheckpointCapabilityError, match="n_action_steps"):
+        Pi05Config.from_model_config(dict(_LEROBOT_CFG, n_action_steps=10))
+
+
+@pytest.mark.parametrize(
+    "key,value",
+    [
+        ("output_features", {"action": {"type": "ACTION", "shape": [33]}}),
+        ("input_features", {**_LEROBOT_CFG["input_features"], "observation.state": {"type": "STATE", "shape": [33]}}),
+    ],
+    ids=["action", "state"],
+)
+def test_config_rejects_a_schema_wider_than_the_model(key, value):
+    """``max_action_dim`` / ``max_state_dim`` are the widths the weights were
+    built for, so a wider checkpoint schema cannot be served."""
+    with pytest.raises(ValueError, match="over max_state_dim"):
+        Pi05Config.from_model_config(dict(_LEROBOT_CFG, **{key: value}))
+
+
+@pytest.mark.parametrize(
+    "key,value,attribute",
+    [
+        ("output_features", {"action": {"type": "ACTION", "shape": [7]}}, "action_dim"),
+        (
+            "input_features",
+            {**_LEROBOT_CFG["input_features"], "observation.state": {"type": "STATE", "shape": [7]}},
+            "state_dim",
+        ),
+    ],
+    ids=["action", "state"],
+)
+def test_config_derives_the_real_width_from_the_schema(key, value, attribute):
+    """The declared width decides how many values reach the prompt and how many
+    columns come back, so a 7-joint checkpoint must not be padded out to 32."""
+    config = Pi05Config.from_model_config(dict(_LEROBOT_CFG, **{key: value}))
+    assert getattr(config, attribute) == 7
+
+
+def test_config_rejects_inconsistent_openpi_metadata():
+    with pytest.raises(ValueError, match="policy_server_config.action_dim"):
+        Pi05Config.from_model_config(
+            dict(
+                _LEROBOT_CFG,
+                output_features={"action": {"type": "ACTION", "shape": [7]}},
+                policy_server_config={"action_dim": 32},
+            )
+        )
+
+
+def test_config_non_square_resolution_raises():
+    with pytest.raises(ValueError):
+        Pi05Config(image_resolution=(224, 256))
+
+
+@pytest.mark.parametrize("key", ["max_cameras", "num_inference_steps"])
+def test_config_rejects_counts_below_one(key):
+    """``build_model_inputs`` emits one image slot per camera and the Euler loop
+    steps ``-1 / num_inference_steps``; neither is defined at zero."""
+    with pytest.raises(ValueError, match=f"{key} must be at least 1"):
+        Pi05Config.from_model_config(dict(_LEROBOT_CFG, **{key: 0}))
+
+
+@pytest.mark.parametrize("key", ["state", "action"])
+def test_config_rejects_norm_stats_that_do_not_match_the_declared_width(key):
+    """A checkpoint's statistics and its feature schema come from different
+    files, so they can disagree."""
+    stats = {key: {"mode": "quantile", "q01": [0.0] * 2, "q99": [1.0] * 2}}
+    with pytest.raises(ValueError, match=rf"norm_stats\[{key}\]\[q01\] has 2 entries, expected 32"):
+        Pi05Config.from_model_config(dict(_LEROBOT_CFG, norm_stats=stats))
+
+
+# ----------------------------------------------------------------------------
+# LeRobot normalization-stats sidecar
+# ----------------------------------------------------------------------------
+# LeRobot keeps stats out of config.json: policy_preprocessor.json holds the
+# structure and one safetensors file per stateful step holds the numbers.
+def _normalized(raw, stats):
+    """The serving path's state normalization, without the pipeline."""
+    return apply_norm(torch.as_tensor(raw, dtype=torch.float32), build_norm_stats({"state": stats}, "state")).numpy()
+
+
+def _write_lerobot_checkpoint(
+    tmp_path,
+    *,
+    norm_map: dict[str, str] | None = None,
+    stats: dict[str, dict[str, list[float]]] | None = None,
+    write_state_file: bool = True,
+) -> str:
+    """Write a minimal LeRobot-shaped checkpoint dir; return its path."""
+    import json as _json
+
+    import safetensors.torch as _st
+
+    tmp_path.mkdir(parents=True, exist_ok=True)
+    state_file = "policy_preprocessor_step_3_normalizer_processor.safetensors"
+    step: dict = {
+        "registry_name": "normalizer_processor",
+        "config": {
+            "eps": 1e-08,
+            "features": {},
+            "norm_map": norm_map if norm_map is not None else {"STATE": "QUANTILES", "ACTION": "QUANTILES"},
+        },
+    }
+    if write_state_file:
+        step["state_file"] = state_file
+        flat = {
+            f"{feature}.{stat}": torch.tensor(values, dtype=torch.float32)
+            for feature, entry in (stats or {}).items()
+            for stat, values in entry.items()
+        }
+        _st.save_file(flat, str(tmp_path / state_file))
+
+    (tmp_path / "policy_preprocessor.json").write_text(
+        _json.dumps({"name": "policy_preprocessor", "steps": [step]}), encoding="utf-8"
+    )
+    (tmp_path / "config.json").write_text(_json.dumps(_config_for(stats)), encoding="utf-8")
+    return str(tmp_path)
+
+
+def _config_for(stats: dict | None) -> dict:
+    """``_LEROBOT_CFG`` with the state/action widths the stats actually cover."""
+    if not stats:
+        return _LEROBOT_CFG
+    config = dict(_LEROBOT_CFG)
+    state = next(iter(stats.get("observation.state", {}).values()), None)
+    action = next(iter(stats.get("action", {}).values()), None)
+    if state is not None:
+        features = dict(config["input_features"])
+        features["observation.state"] = {"type": "STATE", "shape": [len(state)]}
+        config["input_features"] = features
+    if action is not None:
+        config["output_features"] = {"action": {"type": "ACTION", "shape": [len(action)]}}
+    return config
+
+
+# A LeRobot state_dict carries every stat compute_stats emits, not just the two
+# the norm_map selects.
+_FULL_DATASET_STATS = {
+    "observation.state": {
+        "mean": [10.0, 20.0],
+        "std": [1.0, 2.0],
+        "min": [-5.0, -5.0],
+        "max": [5.0, 5.0],
+        "q01": [-1.0, -2.0],
+        "q99": [1.0, 2.0],
+    },
+    "action": {
+        "mean": [0.5, 0.5],
+        "std": [0.1, 0.1],
+        "min": [-1.0, -1.0],
+        "max": [1.0, 1.0],
+        "q01": [-0.25, -0.5],
+        "q99": [0.25, 0.5],
+    },
+}
+
+
+@pytest.mark.parametrize(
+    "declared,expected",
+    [
+        ("QUANTILES", {"mode": "quantile", "q01": [-1.0, -2.0], "q99": [1.0, 2.0]}),
+        ("MEAN_STD", {"mode": "mean_std", "mean": [10.0, 20.0], "std": [1.0, 2.0]}),
+        ("IDENTITY", None),
+    ],
+)
+def test_load_lerobot_norm_stats_takes_the_mode_from_norm_map(tmp_path, declared, expected):
+    """The regression guard. ``_FULL_DATASET_STATS`` carries all six statistics,
+    as a real state_dict does, so an implementation that sniffed the present keys
+    would answer mean_std for every case here. Only norm_map distinguishes them.
+    """
+    path = _write_lerobot_checkpoint(
+        tmp_path, norm_map={"STATE": declared, "ACTION": "QUANTILES"}, stats=_FULL_DATASET_STATS
+    )
+    stats = load_lerobot_norm_stats(path)
+
+    if expected is None:
+        assert "state" not in stats
+    else:
+        assert stats["state"] == expected
+    assert stats["action"]["mode"] == "quantile"
+
+
+@pytest.mark.parametrize("shape", ["no_sidecar", "no_state_file"])
+def test_load_lerobot_norm_stats_absent_stats_are_none(tmp_path, shape):
+    """``lerobot/pi05_base`` is the second shape: a normalizer step with no
+    stats attached. Neither is an error — the client is then expected to send an
+    already-normalized state."""
+    if shape == "no_sidecar":
+        path = str(tmp_path)
+    else:
+        path = _write_lerobot_checkpoint(tmp_path, write_state_file=False)
+
+    assert load_lerobot_norm_stats(path) is None
+
+
+def test_load_lerobot_norm_stats_missing_declared_state_file_raises(tmp_path):
+    path = _write_lerobot_checkpoint(tmp_path, stats=_FULL_DATASET_STATS)
+    (tmp_path / "policy_preprocessor_step_3_normalizer_processor.safetensors").unlink()
+
+    with pytest.raises(FileNotFoundError, match="normalizer state"):
+        load_lerobot_norm_stats(path)
+
+
+def test_pipeline_rejects_missing_model_weights_before_initialization(tmp_path):
+    from vllm_omni.diffusion.models.pi05.pipeline_pi05 import Pi05Pipeline
+
+    pipeline = object.__new__(Pi05Pipeline)
+    pipeline.model_dir = str(tmp_path)
+
+    with pytest.raises(FileNotFoundError, match="model.safetensors"):
+        pipeline._initialize_model()
+
+
+def test_build_config_merges_the_deploy_yaml_over_the_checkpoint(tmp_path):
+    """The deploy yaml carries the runtime knobs and the checkpoint carries the
+    feature schema and the stats. Both have to land on one config."""
+    from types import SimpleNamespace
+
+    from vllm_omni.diffusion.models.pi05.pipeline_pi05 import Pi05Pipeline
+
+    pipeline = object.__new__(Pi05Pipeline)
+    pipeline.model_dir = _write_lerobot_checkpoint(tmp_path, stats=_FULL_DATASET_STATS)
+
+    config = pipeline._build_config(SimpleNamespace(model_config={"type": "pi05", "num_inference_steps": 4}))
+
+    assert config.num_inference_steps == 4
+    assert (config.state_dim, config.action_dim) == (2, 2)
+    assert config.image_feature_keys == _EXPECTED_CAMERA_ORDER
+    assert config.norm_stats["state"]["mode"] == "quantile"
+
+
+class _WideActionModel:
+    """Stands in for the 3.6B model, which is the one collaborator here that is
+    genuinely expensive to build. It returns the padded ``max_action_dim`` width
+    the real model emits, so the assertion is about the pipeline's cropping."""
+
+    def __init__(self, chunk_size: int, max_action_dim: int):
+        self._shape = (1, chunk_size, max_action_dim)
+
+    def sample_actions(self, **kwargs):
+        del kwargs
+        return torch.ones(self._shape)
+
+
+def test_pipeline_crops_actions_to_checkpoint_output_schema(monkeypatch):
+    from vllm_omni.diffusion.models.pi05 import pipeline_pi05
+    from vllm_omni.diffusion.request import OmniDiffusionRequest
+    from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+    config = Pi05Config.from_model_config(
+        dict(_LEROBOT_CFG, output_features={"action": {"type": "ACTION", "shape": [7]}})
+    )
+    pipeline = object.__new__(pipeline_pi05.Pi05Pipeline)
+    pipeline.config = config
+    pipeline.tokenizer = object()
+    pipeline._device = torch.device("cpu")
+    pipeline.processor = Pi05Processor(config, object(), torch.device("cpu"))
+    pipeline.model = _WideActionModel(config.chunk_size, config.max_action_dim)
+    monkeypatch.setattr(
+        pipeline.processor,
+        "build_model_inputs",
+        lambda robot_obs: ([torch.empty(0)], [torch.empty(0)], torch.empty(0), torch.empty(0)),
+    )
+    request = OmniDiffusionRequest(
+        prompt="",
+        sampling_params=OmniDiffusionSamplingParams(
+            extra_args={"robot_obs": {"state": np.zeros(config.max_state_dim)}},
+        ),
+        request_id="crop-test",
+    )
+
+    result = pipeline.forward(request)
+
+    assert result.output["actions"].shape == (config.chunk_size, 7)
+
+
+def test_load_lerobot_norm_stats_unknown_mode_raises(tmp_path):
+    """Fail loud: an unreproducible mode served anyway is silently wrong."""
+    path = _write_lerobot_checkpoint(
+        tmp_path, norm_map={"STATE": "SOMETHING_NEW", "ACTION": "QUANTILES"}, stats=_FULL_DATASET_STATS
+    )
+    with pytest.raises(ValueError, match="SOMETHING_NEW"):
+        load_lerobot_norm_stats(path)
+
+
+def test_from_pretrained_backfills_sidecar_stats(tmp_path):
+    """End to end: the stats reach norm_stats without any deploy yaml."""
+    path = _write_lerobot_checkpoint(tmp_path, stats=_FULL_DATASET_STATS)
+    config = Pi05Config.from_pretrained(path)
+
+    assert config.norm_stats["state"]["mode"] == "quantile"
+    assert config.norm_stats["action"]["mode"] == "quantile"
+
+
+def test_from_pretrained_does_not_override_explicit_norm_stats(tmp_path):
+    """config.json wins over the sidecar, matching LeRobot's override rule."""
+    import json as _json
+
+    path = _write_lerobot_checkpoint(tmp_path, stats=_FULL_DATASET_STATS)
+    explicit = {"state": {"mode": "min_max", "min": [0.0] * 32, "max": [1.0] * 32}}
+    (tmp_path / "config.json").write_text(_json.dumps({**_LEROBOT_CFG, "norm_stats": explicit}), encoding="utf-8")
+
+    assert Pi05Config.from_pretrained(path).norm_stats == explicit
+
+
+# ----------------------------------------------------------------------------
+# Checkpoint boundary: declared-but-unconsumed capabilities must raise
+# ----------------------------------------------------------------------------
+@pytest.mark.parametrize(
+    "key,value",
+    [
+        ("use_visual_memory", True),
+        ("use_proprioceptive_memory", True),
+        ("rtc_config", {"mode": "trained", "inference_delay": 2}),
+        ("n_obs_steps", 6),
+    ],
+)
+def test_config_rejects_unsupported_capability(key, value):
+    """MEM and RTC change what a correct action chunk looks like and are not
+    visible in the weights. Serving such a checkpoint must fail loudly."""
+    with pytest.raises(UnsupportedCheckpointCapabilityError, match=key):
+        Pi05Config.from_model_config(dict(_LEROBOT_CFG, **{key: value}))
+
+
+# ----------------------------------------------------------------------------
+# Relative actions
+# ----------------------------------------------------------------------------
+def test_relative_actions_without_action_names_raises():
+    """``action_feature_names`` is populated from dataset metadata at training
+    time. There is no dataset at serving time, so a relative-action checkpoint
+    that omits it cannot resolve ``relative_exclude_joints`` and must fail."""
+    with pytest.raises(UnsupportedCheckpointCapabilityError, match="action_feature_names"):
+        Pi05Config.from_model_config(dict(_LEROBOT_CFG, use_relative_actions=True, action_feature_names=None))
+
+
+def test_relative_actions_empty_exclude_list_needs_no_action_names():
+    c = Pi05Config.from_model_config(dict(_LEROBOT_CFG, use_relative_actions=True, relative_exclude_joints=[]))
+    assert c.use_relative_actions
+
+
+def test_resolve_excluded_action_indices_unresolvable_raises():
+    with pytest.raises(UnsupportedCheckpointCapabilityError):
+        resolve_excluded_action_indices(["no_such_joint"], _ACTION_NAMES)
+
+
+def _relative_step(enabled=True):
+    return Pi05RelativeActions(
+        enabled=enabled,
+        exclude_joints=["gripper"],
+        action_names=_ACTION_NAMES,
+        max_action_dim=32,
+    )
+
+
+def test_relative_mask_excludes_gripper_and_padding():
+    rel = _relative_step()
+    assert rel.relative_mask[0]
+    assert not rel.relative_mask[6], "gripper must stay absolute"
+    assert not rel.relative_mask[len(_ACTION_NAMES) :].any(), "padded dims carry no signal"
+    assert rel.num_relative_dims == 6
+
+
+def test_relative_absolute_round_trip_is_exact():
+    """The two directions are one object precisely so they cannot disagree."""
+    rel = _relative_step()
+    g = torch.Generator().manual_seed(0)
+    actions = torch.randn(1, 50, 32, generator=g)
+    state = torch.randn(32, generator=g)
+    assert torch.allclose(rel.to_absolute(rel.to_relative(actions, state), state), actions, atol=1e-6)
+
+
+def test_relative_rejects_mismatched_action_dim():
+    rel = _relative_step()
+    with pytest.raises(ValueError, match="max_action_dim"):
+        rel.to_absolute(torch.zeros(1, 4, 8), torch.zeros(32))
+
+
+# ----------------------------------------------------------------------------
+# State discretization — π0.5's defining input path
+# ----------------------------------------------------------------------------
+def test_discretize_underflows_to_minus_one_and_saturates_at_the_top():
+    """Out-of-range input is asymmetric, and that asymmetry is LeRobot's.
+
+    ``np.digitize`` returns 0 for anything below the first bin edge, so the
+    ``- 1`` makes a below-range state land in bin ``-1``; above-range input
+    saturates at ``num_bins - 1`` on its own. The checkpoint was trained with
+    ``" -1"`` in the state prompt for under-range dims, so clipping that to 0
+    would change the tokens the model sees — LeRobot parity catches it.
+    """
+    out = discretize_state(np.array([-9.0, 9.0], dtype=np.float32), num_bins=256)
+    assert out.tolist() == [-1, 255]
+
+
+def test_normalize_state_does_not_clip_out_of_range():
+    """The parity-critical contract: normalization is affine and nothing else.
+
+    Clamping to [-1, 1] here would hide an under-range dimension from
+    ``discretize_state``, turning LeRobot's ``-1`` bin into ``0`` and changing
+    the state tokens in the prompt. LeRobot applies
+    ``2.0 * (x - q01) / (q99 - q01) - 1.0`` with no clip.
+    """
+    stats = {"q01": [0.0] * 32, "q99": [10.0] * 32}
+    out = _normalized([-10.0, 20.0] + [5.0] * 30, stats)
+    assert out[0] == pytest.approx(-3.0)  # would be -1.0 if clipped
+    assert out[1] == pytest.approx(3.0)  # would be 1.0 if clipped
+    # and the under-range dim must reach the -1 bin end to end
+    assert discretize_state(out, num_bins=256)[0] == -1
+
+
+def test_prompt_serializes_the_declared_state_width():
+    """LeRobot's tokenizer step discretizes the state at its real width and
+    never pads to ``max_state_dim``."""
+    prompt = build_pi05_prompt(task="x", normalized_state=np.zeros(7, dtype=np.float32))
+    bins = prompt.split("State: ")[1].split(";")[0].split()
+    assert len(bins) == 7
+
+
+def test_prompt_template_matches_lerobot():
+    prompt = build_pi05_prompt(
+        task="  pick_up the red\nblock ",
+        normalized_state=np.zeros(4, dtype=np.float32),
+    )
+    assert prompt.startswith("Task: pick up the red block, State: ")
+    assert prompt.endswith(";\nAction: ")
+
+
+# ----------------------------------------------------------------------------
+# Input contract: fixed camera slots x 256 tokens + constant 200 text tokens
+# ----------------------------------------------------------------------------
+@pytest.mark.parametrize("views,expected", [(1, 456), (2, 712), (3, 968)])
+def test_prefix_length_is_fixed_by_max_cameras(views, expected):
+    """``max_cameras × 256`` image tokens plus a constant ``tokenizer_max_length``.
+
+    The text segment is padded to its maximum and the camera slots are padded to
+    ``max_cameras``, so the prefix shape does not vary with the request — only
+    the attention mask does.
+    """
+    keys = _EXPECTED_CAMERA_ORDER[:views]
+    config = Pi05Config(max_cameras=views, tokenizer_max_length=200, image_feature_keys=keys)
+    observation = {
+        "state": np.zeros(32, dtype=np.float32),
+        "images": {key: np.zeros((4, 4, 3), dtype=np.uint8) for key in keys},
+    }
+
+    images, masks, lang_tokens, _ = _assemble_model_inputs(
+        observation, config, _FakeTokenizer(), torch.device("cpu"), None
+    )
+
+    assert len(images) == views
+    assert all(bool(mask) for mask in masks)
+    assert lang_tokens.shape[-1] == 200
+    assert 256 * len(images) + lang_tokens.shape[-1] == expected
+
+
+# ----------------------------------------------------------------------------
+# Shared math helpers (same contracts as π0)
+# ----------------------------------------------------------------------------
+def test_gemma_variant_dims():
+    vlm = get_gemma_config("gemma_2b")
+    assert (vlm.width, vlm.depth, vlm.mlp_dim, vlm.num_kv_heads, vlm.head_dim) == (2048, 18, 16384, 1, 256)
+    expert = get_gemma_config("gemma_300m")
+    assert (expert.width, expert.depth, expert.mlp_dim) == (1024, 18, 4096)
+
+
+def test_sinusoidal_embedding_shape_and_oddity():
+    out = create_sinusoidal_pos_embedding(torch.tensor([0.0, 1.0]), 64)
+    assert out.shape == (2, 64)
+    with pytest.raises(ValueError):
+        create_sinusoidal_pos_embedding(torch.tensor([0.0]), 63)
+
+
+def test_make_att_2d_masks_respects_padding():
+    pad = torch.tensor([[True, True, False]])
+    att = torch.tensor([[0, 0, 0]])
+    out = make_att_2d_masks(pad, att)
+    assert not out[0, :, 2].any()
+
+
+def test_build_norm_stats_rejects_unknown_mode():
+    with pytest.raises(ValueError, match="Unsupported normalization mode"):
+        build_norm_stats({"action": {"mode": "qunatile"}}, "action")
+
+
+@pytest.mark.parametrize(
+    "entry",
+    [
+        {"mode": "mean_std", "mean": [0.0]},
+        {"mode": "min_max", "min": [0.0]},
+        {"mode": "quantile", "q01": [0.0]},
+    ],
+)
+def test_build_norm_stats_rejects_incomplete_stats(entry):
+    with pytest.raises(ValueError, match="requires"):
+        build_norm_stats({"action": entry}, "action")
+
+
+def test_normalize_quantile_round_trip_and_padded_tail():
+    stats = build_norm_stats({"action": {"q01": [0.0, 0.0], "q99": [2.0, 4.0]}}, "action")
+    x = torch.tensor([[0.5, -0.5, 7.0]])  # third entry is padding beyond the stats
+    back = apply_norm(apply_norm(x, stats), stats, inverse=True)
+    assert torch.allclose(back, x, atol=1e-5)
+    assert back[0, 2] == 7.0, "padded tail must pass through untouched"
+
+
+# ----------------------------------------------------------------------------
+# Image processor
+# ----------------------------------------------------------------------------
+@pytest.mark.parametrize("value,expected", [(0.0, -1.0), (0.25, -0.5), (1.0, 1.0)])
+@pytest.mark.parametrize("container", ["numpy", "torch"])
+def test_float_image_uses_lerobot_zero_one_domain(value, expected, container):
+    if container == "numpy":
+        image = np.full((4, 4, 3), value, dtype=np.float32)
+    else:
+        image = torch.full((3, 4, 4), value, dtype=torch.float32)
+
+    out = Pi05ImageProcessor(image_size=4).preprocess_single(image)
+
+    assert out.shape == (1, 3, 4, 4)
+    assert torch.allclose(out, torch.full_like(out, expected))
+
+
+@pytest.mark.parametrize("bad", [-0.01, 1.01, np.nan, np.inf])
+@pytest.mark.parametrize("container", ["numpy", "torch"])
+def test_float_image_rejects_values_outside_lerobot_domain(bad, container):
+    if container == "numpy":
+        image = np.full((4, 4, 3), bad, dtype=np.float32)
+    else:
+        image = torch.full((3, 4, 4), bad, dtype=torch.float32)
+
+    with pytest.raises(ValueError):
+        Pi05ImageProcessor(image_size=4).preprocess_single(image)
+
+
+def test_resize_with_pad_pads_with_minus_one():
+    out = resize_with_pad(torch.zeros(1, 3, 100, 200), 224, 224)
+    assert out.shape == (1, 3, 224, 224)
+    assert out[0, 0, 0, 0] == -1.0
+
+
+class _FakeTokenizer:
+    def __call__(self, text, **kwargs):
+        del text
+        length = kwargs["max_length"]
+        return {"input_ids": [0] * length, "attention_mask": [1] * length}
+
+
+@pytest.mark.parametrize("explicit_none", [False, True])
+def test_build_model_inputs_preserves_missing_middle_camera_slot(explicit_none):
+    config = Pi05Config(image_feature_keys=_EXPECTED_CAMERA_ORDER, max_cameras=3)
+    images = {
+        _EXPECTED_CAMERA_ORDER[0]: np.zeros((4, 4, 3), dtype=np.uint8),
+        _EXPECTED_CAMERA_ORDER[2]: np.full((4, 4, 3), 255, dtype=np.uint8),
+    }
+    if explicit_none:
+        images[_EXPECTED_CAMERA_ORDER[1]] = None
+    observation = {
+        "images": images,
+        "state": np.zeros(32, dtype=np.float32),
+    }
+
+    slots, masks, _, _ = _assemble_model_inputs(observation, config, _FakeTokenizer(), torch.device("cpu"), None)
+
+    assert [bool(mask.item()) for mask in masks] == [True, False, True]
+    torch.testing.assert_close(slots[0], torch.full_like(slots[0], -1.0))
+    torch.testing.assert_close(slots[1], torch.full_like(slots[1], -1.0))
+    torch.testing.assert_close(slots[2], torch.full_like(slots[2], 1.0))
+
+
+def test_build_model_inputs_requires_configured_camera():
+    config = Pi05Config(image_feature_keys=_EXPECTED_CAMERA_ORDER)
+    observation = {
+        "unknown_camera": np.zeros((4, 4, 3), dtype=np.uint8),
+        "state": np.zeros(32, dtype=np.float32),
+    }
+    with pytest.raises(ValueError, match="configured camera"):
+        _assemble_model_inputs(observation, config, _FakeTokenizer(), torch.device("cpu"), None)
+
+
+# ----------------------------------------------------------------------------
+# Model behaviour + weight-load remap (tiny action dims; full Gemma backbone)
+# ----------------------------------------------------------------------------
+# Module *structure* (no ``state_proj``, ``time_mlp_{in,out}`` widths, AdaRMS on
+# the expert norms but not the prefix) is not asserted here: ``load_weights``
+# audits every model parameter against the checkpoint and raises on a missing,
+# unmatched or π0-shaped key, so a structural drift fails loudly at load time
+# rather than silently. ``test_pi0_shaped_keys_are_not_silently_loaded`` guards
+# that audit, and ``test_pi05_parity.py`` is the numerical oracle.
+# Both Gemma towers keep their real widths but drop from 18 layers to 2 for
+# every test in this section. Nothing here depends on depth: the weight remap
+# matches by name, and the AR mask, prefix length and ODE determinism are
+# shape-driven. Full-scale numerical correctness is ``test_pi05_parity.py``'s
+# job, against the real checkpoint.
+#
+# Two dimensions must NOT be shrunk, both because something outside these
+# configs is sized against them:
+#
+# * ``width`` — the vision tower's ``multi_modal_projector`` projects image
+#   embeddings to the PaliGemma text width so the two can be concatenated.
+#   Narrowing the text tower alone makes that concat fail.
+# * the vision tower itself — So400m/14 on 224x224 is what yields exactly 256
+#   tokens per view, which ``test_prefix_length_and_valid_len_for_each_view_count``
+#   exists to verify.
+#
+# Depths are equal across the two towers on purpose: the action expert runs
+# layer-by-layer alongside the VLM, so a mismatch would not be a valid model.
+_SHRUNK_GEMMA = {
+    "gemma_2b": GemmaVariantConfig(2048, 2, 1024, 8, 1, 256),
+    "gemma_300m": GemmaVariantConfig(1024, 2, 512, 8, 1, 256),
+}
+
+
+@pytest.fixture(scope="module", autouse=True)
+def _shrink_gemma_backbones():
+    """Patch the module-level lookup ``Pi05ForActionPrediction.__init__`` calls."""
+    patch = pytest.MonkeyPatch()
+    patch.setattr(modeling_pi05, "get_gemma_config", lambda variant: _SHRUNK_GEMMA[variant])
+    yield
+    patch.undo()
+
+
+def _tiny_pi05_model():
+    """A fresh model. Use for tests that load weights or otherwise mutate it."""
+    return Pi05ForActionPrediction(Pi05Config(max_action_dim=8, max_state_dim=8, chunk_size=4, n_action_steps=4))
+
+
+@pytest.fixture(scope="module")
+def tiny_model():
+    """Shared read-only model, so the tests that only inspect it pay for one
+    construction between them rather than one each."""
+    return _tiny_pi05_model()
+
+
+@pytest.fixture(autouse=True)
+def _silence_pi05_loader():
+    logging.getLogger("vllm_omni.diffusion.models.pi05.modeling_pi05").setLevel(logging.CRITICAL)
+    yield
+
+
+@pytest.mark.slow
+def test_suffix_has_no_state_token(tiny_model):
+    """π0's suffix is ``[state, actions...]`` with AR mask ``[1, 1, 0...]``;
+    π0.5's is actions only with ``[1, 0...]``."""
+    embs, pad, att, cond = tiny_model.embed_suffix(torch.randn(1, 4, 8), torch.tensor([1.0]))
+    assert embs.shape[1] == 4
+    assert att[0].tolist() == [1, 0, 0, 0]
+    assert cond.shape == (1, tiny_model.expert_width)
+
+
+# Not marked slow: constructs one small norm layer, no backbone.
+def test_adarms_norm_returns_gate_only_when_conditioned():
+    norm = Pi05AdaRMSNorm(8, cond_dim=4)
+    out, gate = norm(torch.randn(1, 3, 8), torch.randn(1, 4))
+    assert gate is not None and gate.shape == (1, 1, 8)
+
+    plain = Pi05AdaRMSNorm(8, cond_dim=None)
+    out, gate = plain(torch.randn(1, 3, 8))
+    assert gate is None
+
+
+@pytest.mark.slow
+def test_lm_head_remap_to_embed_tokens():
+    model = _tiny_pi05_model()
+    target = "paligemma_with_expert.paligemma.model.language_model.embed_tokens.weight"
+    payload = torch.full(dict(model.named_parameters())[target].shape, 0.5)
+    model.load_weights([("model.paligemma_with_expert.paligemma.lm_head.weight", payload)], strict=False)
+    assert torch.allclose(dict(model.named_parameters())[target], payload)
+
+
+@pytest.mark.slow
+def test_pi0_shaped_keys_are_not_silently_loaded():
+    """A π0 checkpoint pointed at the π0.5 class would leave the AdaRMS expert
+    randomly initialized. ``state_proj`` is the tell."""
+    model = _tiny_pi05_model()
+    with pytest.raises(RuntimeError, match="π0-shaped"):
+        model.load_weights([("model.state_proj.weight", torch.zeros(1024, 8))])
+
+
+@pytest.mark.slow
+@pytest.mark.parametrize("num_real_views", [1, 2, 3])
+def test_prefix_length_is_fixed_and_valid_len_tracks_masks(num_real_views, tiny_model):
+    """The deployed model has three slots; only their validity varies."""
+    live_text = 120
+    images = [torch.zeros(1, 3, 224, 224) for _ in range(3)]
+    masks = [torch.tensor([index < num_real_views]) for index in range(3)]
+    lang = torch.zeros(1, 200, dtype=torch.long)
+    lang_mask = torch.zeros(1, 200, dtype=torch.bool)
+    lang_mask[:, :live_text] = True
+
+    embs, pad_masks, _ = tiny_model.embed_prefix(images, masks, lang, lang_mask)
+    assert embs.shape[1] == 256 * 3 + 200
+    assert int(pad_masks.sum()) == 256 * num_real_views + live_text
+
+
+@pytest.mark.slow
+def test_sample_actions_shape_and_determinism(tiny_model):
+    """Flow matching is an ODE: fixed noise must give a bit-identical chunk."""
+    model = tiny_model.eval()
+    images = [torch.zeros(1, 3, 224, 224) for _ in range(3)]
+    masks = [torch.tensor([True]), torch.tensor([False]), torch.tensor([False])]
+    lang = torch.zeros(1, 200, dtype=torch.long)
+    lang_mask = torch.ones(1, 200, dtype=torch.bool)
+    noise = torch.randn(1, 4, 8, generator=torch.Generator().manual_seed(42))
+
+    with torch.no_grad():
+        a1 = model.sample_actions(
+            images=images, image_masks=masks, lang_tokens=lang, lang_masks=lang_mask, noise=noise, num_steps=2
+        )
+        a2 = model.sample_actions(
+            images=images, image_masks=masks, lang_tokens=lang, lang_masks=lang_mask, noise=noise, num_steps=2
+        )
+    assert a1.shape == (1, 4, 8)
+    assert torch.isfinite(a1).all()
+    assert torch.equal(a1, a2)
+
+
+@pytest.mark.slow
+def test_sample_actions_uses_request_generator(tiny_model):
+    model = tiny_model.eval()
+    images = [torch.zeros(1, 3, 224, 224) for _ in range(3)]
+    masks = [torch.tensor([True]), torch.tensor([False]), torch.tensor([False])]
+    lang = torch.zeros(1, 200, dtype=torch.long)
+    lang_mask = torch.ones(1, 200, dtype=torch.bool)
+
+    def run(seed):
+        return model.sample_actions(
+            images=images,
+            image_masks=masks,
+            lang_tokens=lang,
+            lang_masks=lang_mask,
+            num_steps=2,
+            generator=torch.Generator().manual_seed(seed),
+        )
+
+    with torch.no_grad():
+        first = run(42)
+        repeated = run(42)
+        different = run(43)
+
+    assert torch.equal(first, repeated)
+    assert not torch.equal(first, different)
+
+
+# ----------------------------------------------------------------------------
+# Serving dtype
+# ----------------------------------------------------------------------------
+# The check that decides what runs lives on the pipeline, not on Pi05Config:
+# Pi05Config.dtype records what the checkpoint declares and never reaches a
+# cast, while _initialize_model casts using the top-level OmniDiffusionConfig.
+@pytest.mark.parametrize(
+    "declared,expected",
+    [
+        ("float32", torch.float32),
+        ("bfloat16", torch.bfloat16),
+        (torch.float32, torch.float32),
+        (torch.bfloat16, torch.bfloat16),
+    ],
+)
+def test_resolve_dtype_accepts_supported_serving_dtypes(declared, expected):
+    from vllm_omni.diffusion.data import OmniDiffusionConfig
+    from vllm_omni.diffusion.models.pi05.pipeline_pi05 import Pi05Pipeline
+
+    assert Pi05Pipeline._resolve_dtype(OmniDiffusionConfig(dtype=declared)) is expected
+
+
+@pytest.mark.parametrize("declared", ["float16", "fp16", torch.float16])
+def test_resolve_dtype_rejects_unvalidated_dtypes(declared):
+    """float16 resolves to a real torch dtype, so a permissive lookup would run
+    the model in a precision nothing here has been checked in.
+
+    Only dtypes that survive ``OmniDiffusionConfig`` normalization are worth
+    asserting on: it maps a string it does not recognize onto bfloat16 with a
+    warning, so e.g. ``"float64"`` never reaches this guard as float64.
+    """
+    from vllm_omni.diffusion.data import OmniDiffusionConfig
+    from vllm_omni.diffusion.models.pi05.pipeline_pi05 import Pi05Pipeline
+
+    with pytest.raises(ValueError, match="Unsupported π0.5 dtype"):
+        Pi05Pipeline._resolve_dtype(OmniDiffusionConfig(dtype=declared))
+
+
+def test_bfloat16_layout_is_applied_before_checkpoint_load(monkeypatch, tmp_path):
+    """Checkpoint tensors must be copied directly into their final dtypes.
+
+    LeRobot casts only the inner PaliGemma/expert module; the outer action and
+    time projections remain float32. The layout is established before loading
+    so float32-retained weights never pass through bfloat16.
+    """
+    from vllm_omni.diffusion.models.pi05 import pipeline_pi05
+
+    class _TinyPi05(torch.nn.Module):
+        def __init__(self):
+            super().__init__()
+            self.paligemma_with_expert = torch.nn.Module()
+            self.paligemma_with_expert.backbone = torch.nn.Linear(2, 2)
+            self.paligemma_with_expert.vision_tower = torch.nn.Linear(2, 2)
+            self.paligemma_with_expert.input_layernorm = torch.nn.LayerNorm(2)
+            self.paligemma_with_expert.register_buffer("floating_buffer", torch.ones(1))
+            self.action_in_proj = torch.nn.Linear(2, 2)
+            self.action_out_proj = torch.nn.Linear(2, 2)
+            self.time_mlp_in = torch.nn.Linear(2, 2)
+            self.time_mlp_out = torch.nn.Linear(2, 2)
+
+    # DiffusersLoader constructs custom pipelines under the requested default
+    # dtype. Start fully in bfloat16 to verify that the helper restores every
+    # float32-retained tensor rather than relying on the construction default.
+    model = _TinyPi05().to(dtype=torch.bfloat16)
+    observed_dtypes = {}
+
+    def fake_load_checkpoint(_self, model_to_load):
+        observed_dtypes.update({name: param.dtype for name, param in model_to_load.named_parameters()})
+
+    (tmp_path / "model.safetensors").touch()
+    pipeline = object.__new__(pipeline_pi05.Pi05Pipeline)
+    pipeline.model_dir = str(tmp_path)
+    pipeline.config = object()
+    pipeline._device = torch.device("cpu")
+    pipeline._torch_dtype = torch.bfloat16
+    monkeypatch.setattr(pipeline_pi05, "Pi05ForActionPrediction", lambda _config: model)
+    monkeypatch.setattr(pipeline_pi05.Pi05Pipeline, "_load_checkpoint", fake_load_checkpoint)
+
+    initialized = pipeline._initialize_model()
+
+    assert observed_dtypes["paligemma_with_expert.backbone.weight"] is torch.bfloat16
+    assert model.paligemma_with_expert.floating_buffer.dtype is torch.bfloat16
+    for name in (
+        "paligemma_with_expert.vision_tower.weight",
+        "paligemma_with_expert.input_layernorm.weight",
+        "action_in_proj.weight",
+        "action_out_proj.weight",
+        "time_mlp_in.weight",
+        "time_mlp_out.weight",
+    ):
+        assert observed_dtypes[name] is torch.float32
+    assert initialized is model
+    assert not initialized.training
+
+
+@pytest.mark.slow
+def test_bfloat16_runs_and_tracks_float32(tiny_model):
+    """bfloat16 is a supported serving dtype, so it has to produce a usable
+    chunk — and one that still resembles float32.
+
+    The bound is deliberately loose. This is not a parity check (bfloat16
+    deviates from float32 by ~1-2% of the action range on the real checkpoint,
+    which is why recipes/lerobot/Pi05.md tells operators to validate it on their
+    own task). What it catches is gross breakage: a cast that silently did not
+    happen, activations overflowing to inf, or a dtype mismatch that would make
+    the two outputs unrelated.
+    """
+    import copy
+
+    images = [torch.zeros(1, 3, 224, 224) for _ in range(3)]
+    masks = [torch.tensor([True]), torch.tensor([False]), torch.tensor([False])]
+    lang = torch.zeros(1, 200, dtype=torch.long)
+    lang_mask = torch.ones(1, 200, dtype=torch.bool)
+    noise = torch.randn(1, 4, 8, generator=torch.Generator().manual_seed(7))
+
+    def run(model, dtype):
+        with torch.no_grad():
+            return model.sample_actions(
+                images=[img.to(dtype) for img in images],
+                image_masks=masks,
+                lang_tokens=lang,
+                lang_masks=lang_mask,
+                noise=noise.to(dtype),
+                num_steps=2,
+            ).float()
+
+    reference = run(tiny_model.eval(), torch.float32)
+    from vllm_omni.diffusion.models.pi05.pipeline_pi05 import _set_inference_dtype
+
+    bf16_model = copy.deepcopy(tiny_model).eval()
+    _set_inference_dtype(bf16_model, torch.bfloat16)
+
+    # The cast actually happened — otherwise everything below passes trivially.
+    assert any(param.dtype is torch.bfloat16 for param in bf16_model.parameters())
+    assert bf16_model.action_in_proj.weight.dtype is torch.float32
+    assert bf16_model.action_out_proj.weight.dtype is torch.float32
+    assert bf16_model.time_mlp_in.weight.dtype is torch.float32
+    assert bf16_model.time_mlp_out.weight.dtype is torch.float32
+
+    actual = run(bf16_model, torch.bfloat16)
+    assert actual.shape == reference.shape
+    assert torch.isfinite(actual).all()
+
+    scale = float(reference.abs().max())
+    assert float((actual - reference).abs().max()) < max(0.5 * scale, 1e-2)
+
+
+# ----------------------------------------------------------------------------
+# State normalization runs π0's stats path
+# ----------------------------------------------------------------------------
+@pytest.mark.parametrize(
+    "stats,state,expected",
+    [
+        # A denominator that is small but not zero. ``normalize`` divides by
+        # ``std + eps``; replacing a small std with 1.0 would be a different map.
+        ({"mode": "mean_std", "mean": [0.0], "std": [1e-7]}, [1e-7], 1e-7 / (1e-7 + 1e-8)),
+        ({"mode": "quantile", "q01": [0.0], "q99": [1e-7]}, [1e-7], 1.0),
+        ({"mode": "quantile", "q01": [0.0], "q99": [1e-9]}, [1e-9], 1.0),
+        # An exactly zero range maps the bound to -1 instead of dividing by zero.
+        ({"mode": "quantile", "q01": [2.0], "q99": [2.0]}, [2.0], -1.0),
+    ],
+)
+def test_normalize_state_uses_the_shared_denominator_rule(stats, state, expected):
+    """State normalization and action unnormalization are the same affine map,
+    so a narrow range keeps producing LeRobot's answer."""
+    assert _normalized(state, stats)[0] == pytest.approx(expected, rel=1e-5)
+
+
+# ----------------------------------------------------------------------------
+# State wire contract
+# ----------------------------------------------------------------------------
+@pytest.mark.parametrize("bad", [float("nan"), float("inf"), float("-inf")])
+def test_state_rejects_non_finite_values(bad):
+    """``np.digitize`` maps nan and inf to the top bin and -inf to -1, all legal
+    state tokens, so a dead sensor would reach the model as an ordinary prompt."""
+    with pytest.raises(ValueError, match="NaN or Inf"):
+        as_state_vector([0.0, bad], 2)
+
+
+def test_state_rejects_a_multi_row_matrix():
+    """Flattening would read a (2, 16) request as a 32-value state."""
+    with pytest.raises(ValueError, match=r"\(D,\) or \(1, D\)"):
+        as_state_vector(np.zeros((2, 16), dtype=np.float32), 32)
+
+
+# ----------------------------------------------------------------------------
+# Per-request denoising steps reach the model
+# ----------------------------------------------------------------------------
+class _SpyModel:
+    """Records the ``num_steps`` ``forward`` hands to ``sample_actions``."""
+
+    def __init__(self):
+        self.seen: list = []
+        self.generators: list = []
+
+    def sample_actions(self, *, images, image_masks, lang_tokens, lang_masks, num_steps, generator):
+        del images, image_masks, lang_tokens, lang_masks
+        self.seen.append(num_steps)
+        self.generators.append(generator)
+        return torch.zeros(1, 50, 32)
+
+
+def _spy_pipeline(spy: _SpyModel):
+    from vllm_omni.diffusion.models.pi05.pipeline_pi05 import Pi05Pipeline
+
+    pipeline = object.__new__(Pi05Pipeline)
+    pipeline.config = Pi05Config.from_model_config(_LEROBOT_CFG)
+    pipeline.tokenizer = _FakeTokenizer()
+    pipeline._device = torch.device("cpu")
+    pipeline.model = spy
+    pipeline.processor = Pi05Processor(pipeline.config, _FakeTokenizer(), torch.device("cpu"))
+    return pipeline
+
+
+def _spy_request(num_inference_steps, generator=None):
+    params = type("_Params", (), {})()
+    params.extra_args = {
+        "robot_obs": {
+            "state": np.zeros(32, dtype=np.float32),
+            "images": {key: np.zeros((4, 4, 3), dtype=np.uint8) for key in _EXPECTED_CAMERA_ORDER},
+        }
+    }
+    params.num_inference_steps = num_inference_steps
+    params.generator = generator
+    request = type("_Request", (), {})()
+    request.sampling_params = params
+    return request
+
+
+@pytest.mark.parametrize("requested", [None, 2, 25])
+def test_request_denoising_steps_reach_sample_actions(requested):
+    """The OpenPI E2E cannot see this: a pipeline that ignored the override and
+    ran the static default would still return a finite chunk of the right shape."""
+    spy = _SpyModel()
+    output = _spy_pipeline(spy).forward(_spy_request(requested))
+
+    assert spy.seen == [requested]
+    assert output.output["actions"].shape == (50, 32)
+
+
+def test_request_generator_reaches_sample_actions():
+    generator = torch.Generator().manual_seed(42)
+    spy = _SpyModel()
+
+    _spy_pipeline(spy).forward(_spy_request(2, generator))
+
+    assert spy.generators == [generator]
+
+
+@pytest.mark.parametrize("bad", [0, -1, 2.5, True, "4"])
+def test_request_denoising_steps_must_be_a_positive_integer(bad):
+    spy = _SpyModel()
+    with pytest.raises(ValueError, match="num_inference_steps must be a positive integer"):
+        _spy_pipeline(spy).forward(_spy_request(bad))
+    assert spy.seen == []
diff --git a/tests/e2e/online_serving/test_pi05_expansion.py b/tests/e2e/online_serving/test_pi05_expansion.py
new file mode 100644
index 00000000000..0c6fbfd34c2
--- /dev/null
+++ b/tests/e2e/online_serving/test_pi05_expansion.py
@@ -0,0 +1,86 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""E2E online serving test for π0.5 OpenPI websocket serving.
+
+Boots ``vllm serve --omni --deploy-config pi05.yaml`` and drives the real OpenPI
+websocket (``/v1/realtime/robot/openpi``) — the same wire path a robot uses
+(handshake metadata → send observation → receive action chunk). Mirrors
+``tests/e2e/online_serving/test_pi0_expansion.py``. Needs one H100 and the full
+π0.5 checkpoint.
+
+The ``pi0_openpi_*`` helpers are protocol-level (handshake, send obs, receive
+chunk) and not π0-specific, so π0.5 reuses them; only the deploy config and the
+expected metadata differ. This file is selected explicitly by the nightly H100
+robot-policy job.
+
+The in-process LeRobot parity oracle lives separately in
+``tests/diffusion/models/pi05/test_pi05_parity.py``.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+from tests.helpers.mark import hardware_test
+from tests.helpers.runtime import (
+    OmniServerParams,
+    get_open_port,
+    pi0_openpi_require_dependencies,
+    pi0_openpi_run_policy_session,
+    pi0_openpi_validate_session_result,
+)
+
+os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"
+os.environ["VLLM_TEST_CLEAN_GPU_MEMORY"] = "0"
+
+MODEL = "lerobot/pi05_base"
+
+
+test_params = [
+    OmniServerParams(
+        model=MODEL,
+        port=8093,
+        server_args=[
+            "--deploy-config",
+            "vllm_omni/deploy/pi05.yaml",
+            "--enforce-eager",
+            "--disable-log-stats",
+        ],
+        env_dict={
+            "ATTENTION_BACKEND": "torch",
+            "DIFFUSION_ATTENTION_BACKEND": "TORCH_SDPA",
+            "VLLM_DISABLE_COMPILE_CACHE": "1",
+            "MASTER_PORT": str(get_open_port()),
+        },
+    )
+]
+
+
+@pytest.mark.full_model
+@pytest.mark.diffusion
+@hardware_test(res={"cuda": "H100"})
+@pytest.mark.parametrize("omni_server", test_params, indirect=True)
+def test_pi05_openpi_online(omni_server):
+    pi0_openpi_require_dependencies()
+
+    result = pi0_openpi_run_policy_session(
+        host=omni_server.host,
+        port=omni_server.port,
+        prompt="pick up the red block and place it in the bin",
+        session_id="pi05-online-e2e",
+        num_steps=2,
+        num_inference_steps=2,
+    )
+
+    # Asserts every returned chunk is [50, 32] + finite, and the handshake
+    # metadata matches pi05.yaml's policy_server_config.
+    pi0_openpi_validate_session_result(result)
+
+    metadata = result["metadata"]
+    assert tuple(metadata["image_resolution"]) == (224, 224)
+    assert metadata["needs_wrist_camera"] is True
+    assert metadata["needs_session_id"] is False
+    assert metadata["action_space"] == "joint_position"
diff --git a/tests/entrypoints/openai_api/test_openpi_serving.py b/tests/entrypoints/openai_api/test_openpi_serving.py
index d274eadda7a..fa01485991d 100644
--- a/tests/entrypoints/openai_api/test_openpi_serving.py
+++ b/tests/entrypoints/openai_api/test_openpi_serving.py
@@ -270,12 +270,14 @@ def test_build_request_uses_unique_engine_request_id_per_inference():
 
 def test_build_request_clones_stage_defaults_before_protocol_fields():
     default_params = OmniDiffusionSamplingParams(
+        num_inference_steps=12,
+        output_type="latent",
         extra_args={
             "format_prompt_as_json": True,
             "session_id": "configured-session-must-not-win",
             "reset": False,
             "nested": {"values": []},
-        }
+        },
     )
     od_config = SimpleNamespace(model_config={"policy_server_config": {}})
     engine_client = SimpleNamespace(
@@ -297,10 +299,18 @@ def test_build_request_clones_stage_defaults_before_protocol_fields():
         session_id="wire-session",
         reset=False,
     )
+    request_c = serving._build_request(
+        {"prompt": "pick up the object", "sampling_params": {"num_inference_steps": 4}},
+        session_id="wire-session",
+        reset=False,
+    )
 
     assert request_a.sampling_params.extra_args["format_prompt_as_json"] is True
     assert request_a.sampling_params.extra_args["session_id"] == "wire-session"
     assert request_a.sampling_params.extra_args["reset"] is True
+    assert request_a.sampling_params.num_inference_steps == 12
+    assert request_a.sampling_params.output_type == "latent"
+    assert request_c.sampling_params.num_inference_steps == 4
     request_a.sampling_params.extra_args["nested"]["values"].append("request-a")
     assert request_b.sampling_params.extra_args["nested"] == {"values": []}
     assert default_params.extra_args["nested"] == {"values": []}
@@ -318,6 +328,46 @@ def test_build_request_forwards_seed_to_sampling_params():
     assert isinstance(unseeded.sampling_params.seed, int)
 
 
+# Per-request inference parameters live in their own namespace so robot feature
+# names stay open-ended. Unknown keys inside it are ignored rather than rejected.
+def test_build_request_forwards_num_inference_steps():
+    serving = openpi_serving.ServingRealtimeRobotOpenPI(engine_client=_engine_with_policy_config())
+
+    request = serving._build_request(
+        {"prompt": "pick up the object", "sampling_params": {"num_inference_steps": 4}},
+        session_id="session-a",
+        reset=True,
+    )
+
+    assert request.sampling_params.num_inference_steps == 4
+    # The namespace is an engine concern; the pipeline must not see it as a feature.
+    assert "sampling_params" not in request.sampling_params.extra_args["robot_obs"]
+
+
+def test_build_request_omits_num_inference_steps_when_not_sent():
+    """Absent must stay absent: the pipeline reads None as "use the configured
+    default", so materialising a null here would be a different request."""
+    serving = openpi_serving.ServingRealtimeRobotOpenPI(engine_client=_engine_with_policy_config())
+
+    request = serving._build_request({"prompt": "x"}, session_id="s", reset=True)
+
+    assert request.sampling_params.num_inference_steps is None
+
+
+def test_build_request_does_not_forward_arbitrary_observation_keys():
+    """A robot observation may carry any feature name; none of them become
+    engine parameters."""
+    serving = openpi_serving.ServingRealtimeRobotOpenPI(engine_client=_engine_with_policy_config())
+
+    request = serving._build_request(
+        {"prompt": "x", "state": np.zeros(32), "guidance_scale": 7.5}, session_id="s", reset=True
+    )
+
+    extra_args = request.sampling_params.extra_args
+    assert set(extra_args) == {"reset", "session_id", "robot_obs"}
+    assert extra_args["robot_obs"]["guidance_scale"] == 7.5
+
+
 def test_infer_keeps_session_state_but_uses_unique_engine_request_ids():
     engine = RecordingEngine()
     serving = openpi_serving.ServingRealtimeRobotOpenPI(engine_client=engine)
diff --git a/tests/helpers/runtime.py b/tests/helpers/runtime.py
index 0632db55d9e..975a6ddd25b 100644
--- a/tests/helpers/runtime.py
+++ b/tests/helpers/runtime.py
@@ -1166,6 +1166,7 @@ def pi0_openpi_run_policy_session(
     prompt: str = PI0_OPENPI_DEFAULT_PROMPT,
     session_id: str | None = None,
     num_steps: int = 2,
+    num_inference_steps: int | None = None,
 ) -> dict[str, Any]:
     """Connect, read handshake metadata, send ``num_steps`` observations."""
     import uuid
@@ -1184,6 +1185,8 @@ def pi0_openpi_run_policy_session(
         actions = []
         for _ in range(num_steps):
             payload = pi0_make_dummy_obs(prompt=prompt, session_id=session_id)
+            if num_inference_steps is not None:
+                payload["sampling_params"] = {"num_inference_steps": num_inference_steps}
             payload["endpoint"] = "infer"
             conn.send(packer.pack(payload))
             actions.append(_pi0_decode_action_response(conn.recv()))
diff --git a/tests/model_tests/diffusion/test_alignment.py b/tests/model_tests/diffusion/test_alignment.py
index f0a1285bc77..ed266d73434 100644
--- a/tests/model_tests/diffusion/test_alignment.py
+++ b/tests/model_tests/diffusion/test_alignment.py
@@ -82,6 +82,7 @@
     "StableDiffusionXLPipeline",
     "Gr00tN1d7Pipeline",
     "Pi0Pipeline",
+    "Pi05Pipeline",
     "SanaWmPipeline",
     # Audio pipeline conditioned by a separate Qwen2.5-Omni encoder stage;
     # covered by tests/diffusion/models/auk (CPU pipeline tests, parity) and
diff --git a/vllm_omni/config/pipeline_registry.py b/vllm_omni/config/pipeline_registry.py
index 92aad9f4d24..eada1019d6d 100644
--- a/vllm_omni/config/pipeline_registry.py
+++ b/vllm_omni/config/pipeline_registry.py
@@ -33,6 +33,7 @@
     PipelineConfig,
 )
 from vllm_omni.diffusion.models.pi0_pipeline_config import PI0_PIPELINE
+from vllm_omni.diffusion.models.pi05_pipeline_config import PI05_PIPELINE
 from vllm_omni.model_executor.models.audex.pipeline import (
     AUDEX_S2S_PIPELINE,
     AUDEX_THINKER_ONLY_PIPELINE,
@@ -153,6 +154,7 @@
     "lingbot_world": LINGBOT_WORLD_PIPELINE,
     "Gr00tN1d7": GR00T_N1D7_PIPELINE,
     "pi0": PI0_PIPELINE,
+    "pi05": PI05_PIPELINE,
     # Cosmos3 policy checkpoints share HF metadata with the T2I/video Cosmos3
     # checkpoints (which stay on the single-stage diffusion fallback), so this
     # entry is only reachable through a deploy yaml's ``pipeline:`` key
diff --git a/vllm_omni/deploy/pi05.yaml b/vllm_omni/deploy/pi05.yaml
new file mode 100644
index 00000000000..aec8e88f0b6
--- /dev/null
+++ b/vllm_omni/deploy/pi05.yaml
@@ -0,0 +1,51 @@
+# π0.5 VLA: one diffusion stage, one GPU, eager, bsz 1 (OpenPI policy serving is
+# one observation -> one action reply). Every key below is documented in
+# recipes/lerobot/Pi05.md.
+
+pipeline: pi05
+async_chunk: false
+distributed_executor_backend: mp
+# float32 or bfloat16. bfloat16 is faster and halves memory at a numerical cost;
+# read "Choosing a dtype" in the recipe before switching.
+dtype: float32
+
+stages:
+  - stage_id: 0
+    devices: "0"
+    max_num_seqs: 1
+    enforce_eager: true
+    model_class_name: Pi05Pipeline
+    model_config:
+      paligemma_variant: gemma_2b
+      action_expert_variant: gemma_300m
+      chunk_size: 50
+      # Must equal chunk_size: this endpoint returns the whole chunk and keeps no
+      # action queue, so "execute the first N steps, then replan" is not available.
+      n_action_steps: 50
+      max_action_dim: 32
+      max_state_dim: 32
+      num_inference_steps: 10
+      image_resolution: [224, 224]
+      tokenizer_max_length: 200
+      state_num_bins: 256
+      max_cameras: 3
+      image_feature_keys:
+        - observation.images.base_0_rgb
+        - observation.images.left_wrist_0_rgb
+        - observation.images.right_wrist_0_rgb
+      image_key_map: {}
+      use_relative_actions: false
+      relative_exclude_joints:
+        - gripper
+      # OpenPI handshake metadata advertised to the robot client.
+      policy_server_config:
+        image_resolution: [224, 224]
+        n_external_cameras: 1
+        needs_wrist_camera: true
+        needs_stereo_camera: false
+        needs_session_id: false
+        action_space: joint_position
+        action_horizon: 50
+        action_dim: 32
+        max_action_dim: 32
+        max_cameras: 3
diff --git a/vllm_omni/diffusion/data.py b/vllm_omni/diffusion/data.py
index 0ffd0c54ea4..6aa1a27d95f 100644
--- a/vllm_omni/diffusion/data.py
+++ b/vllm_omni/diffusion/data.py
@@ -1615,6 +1615,11 @@ def enrich_config(self) -> None:
                         self.model_class_name = "Pi0Pipeline"
                     self.set_tf_model_config(TransformerConfig())
                     self.update_multimodal_support()
+                elif cfg.get("type") == "pi05":
+                    if self.model_class_name is None:
+                        self.model_class_name = "Pi05Pipeline"
+                    self.set_tf_model_config(TransformerConfig())
+                    self.update_multimodal_support()
                 elif architectures and len(architectures) == 1:
                     architecture = architectures[0]
                     from vllm_omni.diffusion.registry import DiffusionModelRegistry
diff --git a/vllm_omni/diffusion/models/pi05/__init__.py b/vllm_omni/diffusion/models/pi05/__init__.py
new file mode 100644
index 00000000000..ccd19acde6f
--- /dev/null
+++ b/vllm_omni/diffusion/models/pi05/__init__.py
@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""π0.5 VLA model for vllm-omni.
+
+PaliGemma (SigLIP vision + Gemma-2B LM) + Gemma-300M action expert with AdaRMS
+timestep conditioning + a flow-matching action head. Outputs a continuous action
+chunk ``[horizon, action_dim]`` rather than tokens.
+
+Differs from π0 in five places: AdaRMS timestep conditioning (``time_mlp_*``
+instead of ``action_time_mlp_*``), AdaRMS norms throughout the action expert, a
+200-token tokenizer budget, a discretized state carried in the prompt (no
+``state_proj``), and relative-action support.
+"""
+
+from vllm_omni.diffusion.models.pi05.config import (
+    Pi05Config,
+    UnsupportedCheckpointCapabilityError,
+    resolve_excluded_action_indices,
+)
+from vllm_omni.diffusion.models.pi05.modeling_pi05 import (
+    GemmaVariantConfig,
+    PaliGemmaWithActionExpertPi05,
+    Pi05AdaRMSNorm,
+    Pi05ForActionPrediction,
+    create_sinusoidal_pos_embedding,
+    get_gemma_config,
+    make_att_2d_masks,
+    prepare_attention_masks_4d,
+)
+from vllm_omni.diffusion.models.pi05.pipeline_pi05 import (
+    Pi05Pipeline,
+    get_pi05_post_process_func,
+)
+from vllm_omni.diffusion.models.pi05.processor_pi05 import (
+    Pi05ImageProcessor,
+    Pi05Processor,
+    Pi05RelativeActions,
+    apply_norm,
+    build_norm_stats,
+    build_pi05_prompt,
+    discretize_state,
+    pil_image_to_tensor,
+    resize_with_pad,
+    tokenize_prompt,
+)
+
+__all__ = [
+    "Pi05Config",
+    "UnsupportedCheckpointCapabilityError",
+    "resolve_excluded_action_indices",
+    "Pi05ForActionPrediction",
+    "PaliGemmaWithActionExpertPi05",
+    "Pi05AdaRMSNorm",
+    "GemmaVariantConfig",
+    "get_gemma_config",
+    "create_sinusoidal_pos_embedding",
+    "make_att_2d_masks",
+    "prepare_attention_masks_4d",
+    "Pi05ImageProcessor",
+    "Pi05Processor",
+    "Pi05RelativeActions",
+    "build_pi05_prompt",
+    "discretize_state",
+    "apply_norm",
+    "build_norm_stats",
+    "pil_image_to_tensor",
+    "resize_with_pad",
+    "tokenize_prompt",
+    "Pi05Pipeline",
+    "get_pi05_post_process_func",
+]
diff --git a/vllm_omni/diffusion/models/pi05/config.py b/vllm_omni/diffusion/models/pi05/config.py
new file mode 100644
index 00000000000..e86ddbae93e
--- /dev/null
+++ b/vllm_omni/diffusion/models/pi05/config.py
@@ -0,0 +1,471 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Config surface for the π0.5 VLA model in vllm-omni.
+
+Deliberately shaped exactly like ``pi0/config.py``: a small dataclass that
+consumes the raw LeRobot ``config.json`` (the field surface of
+``lerobot.policies.pi05.PI05Config``) and keeps only the runtime-relevant
+fields. Transformer dimensions are derived from ``paligemma_variant`` /
+``action_expert_variant`` inside the model via ``get_gemma_config``.
+
+What π0.5 adds on top of the π0 config surface:
+
+* ``tokenizer_max_length = 200`` (π0 uses 48).
+* ``state_num_bins`` — state is discretized into language tokens instead of
+  going through a ``state_proj`` layer.
+* ``use_relative_actions`` / ``relative_exclude_joints`` /
+  ``action_feature_names`` — the relative-action contract. See
+  ``processor_pi05.Pi05RelativeActions``.
+* Quantile normalization stats. LeRobot's π0.5 defaults ``STATE`` and
+  ``ACTION`` to ``NormalizationMode.QUANTILES`` where π0 uses ``MEAN_STD``.
+
+**Checkpoint boundary rule.** A capability that the checkpoint *declares* but
+this implementation does not *consume* must raise, not be silently dropped.
+π0.5 checkpoints can declare MEM (short-horizon observation memory) and RTC
+(real-time chunking); neither is supported here, and serving such a checkpoint
+anyway would produce plausible-looking wrong actions. See
+``_reject_unsupported_capabilities``.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from dataclasses import fields as dataclass_fields
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Serving dtypes, by name. Kept in sync with ``Pi05Pipeline.SUPPORTED_DTYPES``,
+# which guards the path that performs the actual cast. Defined here rather than
+# imported to keep config.py free of a pipeline import cycle.
+SUPPORTED_DTYPE_NAMES = frozenset({"float32", "bfloat16"})
+
+# LeRobot / OpenPI observation key conventions.
+ACTION = "action"
+OBS_STR = "observation"
+OBS_STATE = OBS_STR + ".state"
+OBS_IMAGES = OBS_STR + ".images"
+
+
+class UnsupportedCheckpointCapabilityError(ValueError):
+    """A checkpoint declares a capability this implementation does not consume.
+
+    Raised at load time rather than silently ignored: every one of these
+    capabilities changes what a *correct* action chunk looks like, and none of
+    them is visible in the weights alone.
+    """
+
+
+def resolve_excluded_action_indices(
+    exclude_joints: list[str] | None,
+    action_names: list[str] | None,
+) -> list[int]:
+    """Map ``relative_exclude_joints`` names onto action-vector indices.
+
+    Matching is exact name first, then substring (a checkpoint may name the
+    gripper dimension ``gripper_position`` while the config just says
+    ``gripper``). Single source of truth for both the config-time validation
+    and the runtime mask in ``processor_pi05.Pi05RelativeActions``.
+
+    Returns an empty list when there is nothing to exclude. Raises when a name
+    cannot be resolved — an unresolvable exclusion would otherwise silently
+    become "make this dimension relative too".
+    """
+    if not [name for name in (exclude_joints or []) if name]:
+        return []
+    if not action_names:
+        raise UnsupportedCheckpointCapabilityError(
+            f"Cannot resolve relative_exclude_joints={exclude_joints!r} without action_feature_names."
+        )
+
+    # LeRobot walks the action names and excludes each one any token equals or is
+    # contained in, both lowercased. Walking the tokens instead and stopping at the
+    # first exact hit misses a second name the token is a substring of.
+    tokens = [str(name).lower() for name in exclude_joints if name]
+    lowered = [str(name).lower() for name in action_names]
+    indices = [i for i, name in enumerate(lowered) if any(t == name or t in name for t in tokens)]
+    unresolved = [t for t in tokens if not any(t == name or t in name for name in lowered)]
+
+    if unresolved:
+        raise UnsupportedCheckpointCapabilityError(
+            f"relative_exclude_joints entries {unresolved!r} match no entry in action_feature_names={action_names!r}."
+        )
+    return sorted(set(indices))
+
+
+@dataclass
+class Pi05Config:
+    """π0.5 VLA config (dataclass, not an HF ``PretrainedConfig``)."""
+
+    # Backbone variants — mapped to Gemma dimensions by ``get_gemma_config``.
+    paligemma_variant: str = "gemma_2b"
+    action_expert_variant: str = "gemma_300m"
+
+    # Action chunk shape.
+    chunk_size: int = 50
+    # The stateless OpenPI endpoint returns one complete predicted chunk.
+    n_action_steps: int = 50
+    max_action_dim: int = 32
+    max_state_dim: int = 32
+
+    # Flow-matching denoising schedule.
+    num_inference_steps: int = 10
+    # Sinusoidal timestep embedding periods (must match OpenPI/LeRobot).
+    min_period: float = 4e-3
+    max_period: float = 4.0
+
+    # Image preprocessing. π0.5/SigLIP only support square inputs.
+    image_resolution: tuple[int, int] = (224, 224)
+    # π0.5 pads text to 200 tokens (π0 uses 48). The prompt now also carries the
+    # serialized state, which is why it is so much longer.
+    tokenizer_max_length: int = 200
+    # Number of camera slots the model attends to (real + padded).
+    max_cameras: int = 3
+
+    # Bins the normalized state is discretized into before it enters the prompt.
+    # Ref: openpi PaliGemmaTokenizer.tokenize().
+    state_num_bins: int = 256
+
+    # Weight dtype the checkpoint was saved in.
+    dtype: str = "float32"
+
+    # ── Relative actions ──────────────────────────────────────────────
+    # True when the checkpoint was trained on actions relative to the current
+    # state. Its ``norm_stats`` are then in relative space, so serving it without
+    # the transform silently yields wrong actions — the weights look identical
+    # either way.
+    use_relative_actions: bool = False
+    # Joint names kept absolute (gripper open/close is an absolute quantity).
+    relative_exclude_joints: list[str] = field(default_factory=lambda: ["gripper"])
+    # Needed to resolve ``relative_exclude_joints``; there is no dataset to
+    # fall back on at serving time.
+    action_feature_names: list[str] | None = None
+
+    # Per-dataset normalization stats (schema matches LeRobot's
+    # ``NormalizerProcessorStep``). ``None`` means identity / pass-through.
+    # π0.5 defaults to quantile mode; see ``processor_pi05.build_norm_stats``.
+    norm_stats: dict | None = None
+
+    # Ordered camera-slot identities. Missing keys retain their slot and are
+    # represented by an empty image with a false mask during preprocessing.
+    image_feature_keys: list[str] | None = None
+    # Optional map from raw OpenPI obs keys → ``image_feature_keys`` entries.
+    image_key_map: dict[str, str] = field(default_factory=dict)
+
+    # Checkpoint feature schemas. The input schema determines camera order and
+    # the state width serialized into the prompt; the output schema determines
+    # the unpadded action width returned on the wire.
+    input_features: dict[str, Any] = field(default_factory=dict)
+    output_features: dict[str, Any] = field(default_factory=dict)
+    # OpenPI handshake metadata from the deploy config. Construction validates
+    # it against the resolved checkpoint contract.
+    policy_server_config: dict[str, Any] = field(default_factory=dict)
+
+    # Derived from output_features[ACTION].shape; never accepted as a second
+    # source of truth in config.json.
+    action_dim: int = field(init=False)
+    # Derived from input_features[OBS_STATE].shape — the number of values the
+    # prompt serializes, not a padding target. See processor_pi05.as_state_vector.
+    state_dim: int = field(init=False)
+
+    def __post_init__(self) -> None:
+        # Coerce list → tuple (JSON has no tuples). Squareness is a real
+        # constraint: SigLIP only takes square inputs.
+        res = self.image_resolution
+        if not isinstance(res, (tuple, list)) or len(res) != 2 or res[0] != res[1]:
+            raise ValueError(f"π0.5 expects a square image_resolution (H == W); got {res!r}.")
+        self.image_resolution = (int(res[0]), int(res[1]))
+
+        if self.n_action_steps != self.chunk_size:
+            raise UnsupportedCheckpointCapabilityError(
+                "The stateless OpenPI serving path returns one complete action chunk and "
+                f"does not support n_action_steps={self.n_action_steps} with "
+                f"chunk_size={self.chunk_size}."
+            )
+        # Mirrors Pi05Pipeline.SUPPORTED_DTYPES. This field records what the
+        # *checkpoint* declares; the dtype the weights are actually cast to comes
+        # from the top-level OmniDiffusionConfig and is validated there.
+        if self.dtype not in SUPPORTED_DTYPE_NAMES:
+            raise ValueError(f"dtype must be one of {sorted(SUPPORTED_DTYPE_NAMES)}, got {self.dtype!r}.")
+
+        # Derive the camera order from input_features if not given explicitly.
+        if self.image_feature_keys is None and self.input_features:
+            self.image_feature_keys = [key for key in self.input_features if key.startswith(OBS_IMAGES + ".")]
+
+        if self.max_cameras < 1:
+            raise ValueError(f"max_cameras must be at least 1, got {self.max_cameras!r}.")
+        if self.num_inference_steps < 1:
+            # ``dt = -1 / num_steps`` in the Euler loop.
+            raise ValueError(f"num_inference_steps must be at least 1, got {self.num_inference_steps!r}.")
+
+        self._derive_widths()
+        self._validate_norm_stats()
+        self._validate_policy_server_config()
+        self._validate_relative_actions()
+
+    def _validate_norm_stats(self) -> None:
+        """Statistics have to cover the widths the checkpoint declares."""
+        for key, width in (("state", self.state_dim), ("action", self.action_dim)):
+            for name, value in (self.norm_stats or {}).get(key, {}).items():
+                if name != "mode" and len(value) != width:
+                    raise ValueError(f"norm_stats[{key}][{name}] has {len(value)} entries, expected {width}.")
+
+    # ------------------------------------------------------------------
+    # Validation
+    # ------------------------------------------------------------------
+    def _derive_widths(self) -> None:
+        """Read the real state and action widths off the checkpoint schema.
+
+        π0.5 serializes the state into the prompt at its real width, so a 7-joint
+        checkpoint must not be padded out to ``max_state_dim``. The action chunk
+        is cropped to ``action_dim`` on the way out.
+        """
+        state = self.input_features.get(OBS_STATE) or {}
+        action = self.output_features.get(ACTION) or {}
+        if state.get("type", "STATE").upper() != "STATE":
+            raise ValueError(f"input_features[{OBS_STATE!r}].type must be STATE, got {state['type']!r}.")
+        if action.get("type", "ACTION").upper() != "ACTION":
+            raise ValueError(f"output_features[{ACTION!r}].type must be ACTION, got {action['type']!r}.")
+        self.state_dim = int(state["shape"][0]) if state else self.max_state_dim
+        self.action_dim = int(action["shape"][0]) if action else self.max_action_dim
+        if self.state_dim > self.max_state_dim or self.action_dim > self.max_action_dim:
+            raise ValueError(
+                f"Checkpoint declares state_dim={self.state_dim} / action_dim={self.action_dim}, "
+                f"over max_state_dim={self.max_state_dim} / max_action_dim={self.max_action_dim}."
+            )
+
+    def _validate_policy_server_config(self) -> None:
+        """The OpenPI handshake has to advertise the resolved contract."""
+        expected = {
+            "action_horizon": self.chunk_size,
+            "action_dim": self.action_dim,
+            "max_action_dim": self.max_action_dim,
+            "max_cameras": self.max_cameras,
+            "image_resolution": list(self.image_resolution),
+        }
+        for key, value in expected.items():
+            declared = (self.policy_server_config or {}).get(key)
+            if declared is None:
+                continue
+            if key == "image_resolution":
+                declared = list(declared)
+            if declared != value:
+                raise ValueError(
+                    f"policy_server_config.{key}={declared!r} does not match the resolved value {value!r}."
+                )
+
+    def _validate_relative_actions(self) -> None:
+        """Resolve the excluded joints at load, so a bad name fails before serving."""
+        if not self.use_relative_actions or not self.relative_exclude_joints:
+            return
+        if not self.action_feature_names:
+            raise UnsupportedCheckpointCapabilityError(
+                f"relative_exclude_joints={self.relative_exclude_joints!r} needs action_feature_names, "
+                "which the checkpoint does not carry."
+            )
+        resolve_excluded_action_indices(self.relative_exclude_joints, self.action_feature_names)
+
+    # ------------------------------------------------------------------
+    # Constructors
+    # ------------------------------------------------------------------
+    @classmethod
+    def from_pretrained(cls, checkpoint_dir: str | Path) -> Pi05Config:
+        """Build from a checkpoint directory's ``config.json``.
+
+        Normalization stats are *not* in ``config.json``. LeRobot keeps them in
+        the processor sidecar, so they are loaded separately and backfilled
+        here — see :func:`load_lerobot_norm_stats`.
+        """
+        checkpoint_dir = Path(checkpoint_dir)
+        config_path = checkpoint_dir / "config.json"
+        if not config_path.exists():
+            raise FileNotFoundError(f"π0.5 checkpoint is missing required config: {config_path}.")
+        with open(config_path, encoding="utf-8") as f:
+            raw = json.load(f)
+        config = cls.from_model_config(raw)
+
+        if config.norm_stats is None:
+            stats = load_lerobot_norm_stats(checkpoint_dir)
+            if stats:
+                config.norm_stats = stats
+                config._validate_norm_stats()
+        return config
+
+    @classmethod
+    def from_model_config(cls, model_config: dict[str, Any] | None) -> Pi05Config:
+        """Build from a config dict (LeRobot ``config.json`` or deploy yaml)."""
+        if not model_config:
+            return cls()
+
+        raw = dict(model_config)
+        _reject_unsupported_capabilities(raw)
+
+        model_type = raw.pop("type", "pi05")
+        if model_type != "pi05":
+            raise ValueError(f"Expected a π0.5 checkpoint (type='pi05'), got type={model_type!r}.")
+
+        if "image_resolution" in raw:
+            raw["image_resolution"] = tuple(raw["image_resolution"])
+
+        # A config.json carries the whole training recipe; none of it reaches
+        # inference. Capabilities we cannot serve are rejected above instead.
+        allowed = {item.name for item in dataclass_fields(cls) if item.init}
+        filtered = {key: value for key, value in raw.items() if key in allowed}
+        dropped = sorted(set(raw) - allowed)
+        if dropped:
+            logger.debug("π0.5 config: ignoring %d non-runtime key(s): %s", len(dropped), dropped)
+        return cls(**filtered)
+
+
+# ----------------------------------------------------------------------
+# LeRobot normalization-stats sidecar
+# ----------------------------------------------------------------------
+# Stats live beside config.json: ``policy_preprocessor.json`` names a
+# safetensors file per stateful step, keyed ``"<feature_name>.<stat_name>"``.
+_PREPROCESSOR_JSON = "policy_preprocessor.json"
+
+# The mode must come from ``norm_map``: a state_dict carries all of
+# mean/std/min/max/q01/q99 regardless, so guessing from the present keys would
+# read a QUANTILES checkpoint as mean_std and apply a wrong affine map.
+_NORM_MODE_FROM_LEROBOT: dict[str, tuple[str, str, str] | None] = {
+    "IDENTITY": None,
+    "MEAN_STD": ("mean_std", "mean", "std"),
+    "MIN_MAX": ("min_max", "min", "max"),
+    "QUANTILES": ("quantile", "q01", "q99"),
+}
+# Renaming happens in an earlier processor step, so these names are canonical
+# here. VISUAL is absent by design: images are normalized in the processor.
+_NORM_STATS_FEATURES = {OBS_STATE: ("STATE", "state"), ACTION: ("ACTION", "action")}
+
+
+def load_lerobot_norm_stats(checkpoint_dir: str | Path) -> dict[str, dict[str, Any]] | None:
+    """Load normalization stats from a LeRobot checkpoint's processor sidecar.
+
+    Returns a ``norm_stats``-shaped dict (``{"state": {...}, "action": {...}}``)
+    carrying an **explicit** ``mode``, or ``None`` when the checkpoint ships no
+    stats. ``lerobot/pi05_base`` is the latter case: its normalizer step has no
+    ``state_file``, i.e. normalization is identity and the client is expected to
+    send an already-normalized state.
+
+    Raises on a mode we cannot reproduce rather than serving the checkpoint with
+    the wrong transform, which fails silently — a wrongly normalized state still
+    yields a plausible-looking action chunk.
+    """
+    checkpoint_dir = Path(checkpoint_dir)
+    preprocessor_path = checkpoint_dir / _PREPROCESSOR_JSON
+    if not preprocessor_path.exists():
+        return None
+    with open(preprocessor_path, encoding="utf-8") as f:
+        steps = json.load(f).get("steps", [])
+
+    step = next((s for s in steps if s.get("registry_name") == "normalizer_processor"), {})
+    state_file = step.get("state_file")
+    if not state_file:
+        logger.info(
+            "π0.5 config: %s declares no normalizer state file; the state passes through.",
+            _PREPROCESSOR_JSON,
+        )
+        return None
+    state_path = checkpoint_dir / state_file
+    if not state_path.exists():
+        raise FileNotFoundError(f"{preprocessor_path} declares normalizer state {state_file!r}, which is missing.")
+
+    norm_map = {str(k).upper(): str(v).upper() for k, v in ((step.get("config") or {}).get("norm_map") or {}).items()}
+
+    import safetensors.torch
+
+    flat = safetensors.torch.load_file(str(state_path))
+
+    stats: dict[str, dict[str, Any]] = {}
+    for feature_name, (feature_type, stats_key) in _NORM_STATS_FEATURES.items():
+        lerobot_mode = norm_map.get(feature_type, "IDENTITY")
+        if lerobot_mode not in _NORM_MODE_FROM_LEROBOT:
+            raise ValueError(
+                f"π0.5 cannot reproduce normalization mode {lerobot_mode!r} for {feature_type}. "
+                f"Expected one of {sorted(_NORM_MODE_FROM_LEROBOT)}."
+            )
+        selected = _NORM_MODE_FROM_LEROBOT[lerobot_mode]
+        if selected is None:
+            continue
+
+        mode, *stat_names = selected
+        missing = [name for name in stat_names if f"{feature_name}.{name}" not in flat]
+        if missing:
+            raise ValueError(
+                f"{feature_type} declares {lerobot_mode} normalization but the state file is missing {missing}."
+            )
+        stats[stats_key] = {"mode": mode} | {name: flat[f"{feature_name}.{name}"].tolist() for name in stat_names}
+
+    if not stats:
+        return None
+    logger.info(
+        "π0.5 config: loaded normalization stats from %s — %s.",
+        state_file,
+        ", ".join(f"{key}={value['mode']}" for key, value in sorted(stats.items())),
+    )
+    return stats
+
+
+# ----------------------------------------------------------------------
+# Checkpoint-boundary rule
+# ----------------------------------------------------------------------
+# Each entry: config key → (is this value *enabled*?, why we cannot serve it).
+# Every capability here changes what a *correct* action chunk looks like, and
+# none is visible in the weights, so a checkpoint that enables one is refused
+# rather than served plausibly wrong. See recipes/lerobot/Pi05.md for the
+# longer explanations.
+#
+# The predicate is per key because these are not all flags: ``n_obs_steps`` is
+# a count whose supported value is 1, and an empty ``rtc_config`` still selects
+# RTC — LeRobot's ``RTCConfig`` defaults ``enabled=True``.
+_UNSUPPORTED: dict[str, tuple[Callable[[Any], bool], str]] = {
+    "use_peft": (bool, "adapter-aware loading; this loader takes a merged checkpoint only"),
+    "empty_cameras": (bool, "mutates the input schema; declare camera features explicitly instead"),
+    "use_visual_memory": (bool, "MEM needs a per-session observation history, which this path does not keep"),
+    "use_proprioceptive_memory": (
+        bool,
+        "MEM sends the state as a projected token, not the discretized prompt built here",
+    ),
+    "rtc_config": (
+        lambda value: value is not None,
+        "RTC needs prefix guidance in the denoising loop and per-request chunk carry-over",
+    ),
+    "n_obs_steps": (
+        lambda value: bool(value) and value > 1,
+        "an observation history; this path is first-order Markov",
+    ),
+}
+
+
+def _reject_unsupported_capabilities(raw: dict[str, Any]) -> None:
+    """Raise if the checkpoint enables something we do not consume.
+
+    Scope note: this validates that we correctly consume *the checkpoint we were
+    handed*. Choosing which checkpoint to load belongs to the caller.
+    """
+    problems = [
+        f"  - {key}={raw[key]!r}: {why}"
+        for key, (is_enabled, why) in _UNSUPPORTED.items()
+        if key in raw and is_enabled(raw[key])
+    ]
+    if problems:
+        raise UnsupportedCheckpointCapabilityError(
+            "This checkpoint declares capabilities the vllm-omni π0.5 implementation "
+            "does not support:\n" + "\n".join(problems) + "\nServing it anyway would "
+            "produce plausible-looking but wrong actions."
+        )
+
+    # Not an error: it records that the checkpoint was trained with clean action
+    # prefixes sampled in, which is a property of training rather than a request
+    # to run RTC. Such a checkpoint is still correct to serve without RTC.
+    delay = raw.get("rtc_training_max_delay")
+    if delay:
+        logger.info(
+            "π0.5 config: checkpoint was trained with rtc_training_max_delay=%s. "
+            "Real-Time Chunking is not implemented here; serving proceeds without it.",
+            delay,
+        )
diff --git a/vllm_omni/diffusion/models/pi05/modeling_pi05.py b/vllm_omni/diffusion/models/pi05/modeling_pi05.py
new file mode 100644
index 00000000000..a792ae0ef1b
--- /dev/null
+++ b/vllm_omni/diffusion/models/pi05/modeling_pi05.py
@@ -0,0 +1,898 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Inference-only π0.5 VLA math kernel for vllm-omni.
+
+Only the math that turns a robot observation into an action chunk; no serving or
+request glue. Deliberately shaped like ``models/pi0/modeling_pi0.py`` so the two
+can later be factored into a shared Pi-family module (RFC step 2) on a
+"behaviour unchanged" review.
+
+π0.5 = PaliGemma (SigLIP vision + Gemma 2B LM) prefix + Gemma 300M action expert
+suffix + flow-matching head. Where π0 projects the robot state through
+``state_proj``, π0.5 discretizes it into prompt tokens — so there is no
+``state_proj`` layer, ``sample_actions`` takes no ``state`` argument, and the
+suffix is action tokens only, which drops π0's leading state-token boundary from
+the suffix attention mask and leaves ``[1] + [0] * (horizon - 1)``.
+
+π0.5 is nonetheless the *larger* model: the 37 AdaRMS ``dense`` projections add
+~116M parameters against the ~8K that ``state_proj`` saves. (LeRobot's README
+says otherwise; the checkpoint disagrees.)
+
+Reference implementations:
+   - OpenPI: openpi/src/openpi/models_pytorch/pi0_pytorch.py, gemma_pytorch.py
+   - LeRobot: lerobot/src/lerobot/policies/pi05/modeling_pi05.py
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+from collections.abc import Iterable
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from transformers.models.auto import CONFIG_MAPPING
+from transformers.models.gemma.modeling_gemma import (
+    GemmaForCausalLM,
+    apply_rotary_pos_emb,
+)
+from transformers.models.paligemma.modeling_paligemma import (
+    PaliGemmaForConditionalGeneration,
+)
+from vllm.model_executor.model_loader.weight_utils import default_weight_loader
+
+logger = logging.getLogger(__name__)
+
+# ──────────────────────────────────────────────────────────────────────
+# Constants
+# ──────────────────────────────────────────────────────────────────────
+DEFAULT_ACTION_DIM = 32
+DEFAULT_ACTION_HORIZON = 50
+DEFAULT_MAX_TOKEN_LEN = 200  # π0 uses 48
+DEFAULT_NUM_INFERENCE_STEPS = 10
+DEFAULT_IMAGE_RESOLUTION = (224, 224)  # openpi/models/model.py IMAGE_RESOLUTION
+DEFAULT_STATE_NUM_BINS = 256  # openpi PaliGemmaTokenizer.tokenize()
+
+# Large negative value to fill masked-out positions in a float attention mask.
+# Matches OpenPI's constant exactly so that numerics line up during parity.
+# Ref: openpi/src/openpi/models/gemma.py
+OPENPI_ATTENTION_MASK_VALUE = -2.3819763e38
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Gemma variant configs (matches openpi/models/gemma.py get_config)
+# ──────────────────────────────────────────────────────────────────────
+class GemmaVariantConfig:
+    def __init__(self, width, depth, mlp_dim, num_heads, num_kv_heads, head_dim):
+        self.width = width
+        self.depth = depth
+        self.mlp_dim = mlp_dim
+        self.num_heads = num_heads
+        self.num_kv_heads = num_kv_heads
+        self.head_dim = head_dim
+
+
+def get_gemma_config(variant: str) -> GemmaVariantConfig:
+    if variant == "gemma_2b":
+        return GemmaVariantConfig(2048, 18, 16384, 8, 1, 256)
+    elif variant == "gemma_300m":
+        return GemmaVariantConfig(1024, 18, 4096, 8, 1, 256)
+    else:
+        raise ValueError(f"Unknown variant: {variant}")
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Utility functions (match openpi/models_pytorch/pi0_pytorch.py)
+# ──────────────────────────────────────────────────────────────────────
+def create_sinusoidal_pos_embedding(
+    time: torch.Tensor,
+    dimension: int,
+    min_period: float = 4e-3,
+    max_period: float = 4.0,
+    device: torch.device = None,
+) -> torch.Tensor:
+    """Compute a sine/cosine positional embedding for scalar timesteps.
+
+    Ref: openpi/models_pytorch/pi0_pytorch.py create_sinusoidal_pos_embedding
+    """
+    if dimension % 2 != 0:
+        raise ValueError(f"dimension ({dimension}) must be divisible by 2")
+    if time.ndim != 1:
+        raise ValueError("time tensor must be 1-D (batch_size,)")
+    if device is None:
+        device = time.device
+
+    # Use float64 for the log-linear sweep and for the inner products, to
+    # match the reference implementation's numerical behaviour exactly.
+    dtype = torch.float64
+    fraction = torch.linspace(0.0, 1.0, dimension // 2, dtype=dtype, device=device)
+    period = min_period * (max_period / min_period) ** fraction
+    scaling_factor = 1.0 / period * 2 * math.pi
+    sin_input = scaling_factor[None, :] * time[:, None].to(dtype)
+    return torch.cat([torch.sin(sin_input), torch.cos(sin_input)], dim=1)
+
+
+def make_att_2d_masks(pad_masks: torch.Tensor, att_masks: torch.Tensor) -> torch.Tensor:
+    """Build a 2D attention mask from a padding mask and an autoregressive mask.
+
+    Ref: openpi/models_pytorch/pi0_pytorch.py make_att_2d_masks
+    """
+    if att_masks.ndim != 2:
+        raise ValueError(f"att_masks must be 2-D, got {att_masks.ndim}-D")
+    if pad_masks.ndim != 2:
+        raise ValueError(f"pad_masks must be 2-D, got {pad_masks.ndim}-D")
+
+    cumsum = torch.cumsum(att_masks, dim=1)
+    att_2d_masks = cumsum[:, None, :] <= cumsum[:, :, None]
+    pad_2d_masks = pad_masks[:, None, :] * pad_masks[:, :, None]
+    return att_2d_masks & pad_2d_masks
+
+
+def prepare_attention_masks_4d(att_2d_masks: torch.Tensor) -> torch.Tensor:
+    """Convert ``(B, S, S)`` bool masks to ``(B, 1, S, S)`` float masks.
+
+    ``True`` → 0.0 (attend), ``False`` → ``OPENPI_ATTENTION_MASK_VALUE``.
+    """
+    att_2d_masks_4d = att_2d_masks[:, None, :, :]
+    return torch.where(att_2d_masks_4d, 0.0, OPENPI_ATTENTION_MASK_VALUE)
+
+
+class Pi05AdaRMSNorm(nn.Module):
+    """Adaptive RMSNorm conditioned on the flow-matching timestep.
+
+    π0 conditions on time by *concatenating* a time embedding onto each action
+    embedding. π0.5 instead feeds the time embedding into every action-expert
+    norm, which produces a per-layer ``(scale, shift, gate)`` triple::
+
+        y    = norm(x) * (1 + scale) + shift
+        out  = residual + gate * sublayer(y)
+
+    ``dense`` is zero-initialized, so an untrained model starts as the identity
+    modulation with a closed gate — matching OpenPI's parameterization.
+
+    Note the shape of the unconditioned branch: ``normed * (1 + weight)`` with
+    ``weight`` zero-initialized, which is exactly ``transformers``'
+    ``GemmaRMSNorm``. That equivalence is why only the *expert* norms need
+    replacing here and the PaliGemma prefix can keep stock Gemma layers.
+    """
+
+    def __init__(self, dim: int, eps: float = 1e-6, cond_dim: int | None = None):
+        super().__init__()
+        self.eps = eps
+        self.dim = dim
+        self.cond_dim = cond_dim
+        if cond_dim is not None:
+            self.dense = nn.Linear(cond_dim, dim * 3, bias=True)
+            nn.init.zeros_(self.dense.weight)
+            nn.init.zeros_(self.dense.bias)
+            self.weight = None
+        else:
+            self.weight = nn.Parameter(torch.zeros(dim))
+            self.dense = None
+
+    def _norm(self, x: torch.Tensor) -> torch.Tensor:
+        var = torch.mean(torch.square(x.float()), dim=-1, keepdim=True)
+        return x.float() * torch.rsqrt(var + self.eps)
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        cond: torch.Tensor | None = None,
+    ) -> tuple[torch.Tensor, torch.Tensor | None]:
+        """Return ``(normed, gate)``; ``gate`` is ``None`` in the unconditioned case."""
+        dtype = x.dtype
+        normed = self._norm(x)
+        if self.dense is None:
+            normed = normed * (1.0 + self.weight.float())
+            return normed.to(dtype), None
+
+        if cond is None:
+            # A conditioned norm silently falling back to an unconditioned one
+            # would drop the entire timestep signal and still return a
+            # well-shaped, finite tensor.
+            raise ValueError(
+                "Pi05AdaRMSNorm was built with cond_dim="
+                f"{self.cond_dim} but called without an AdaRMS conditioning vector."
+            )
+
+        if cond.shape[-1] != self.cond_dim:
+            raise ValueError(f"Expected AdaRMS cond dim {self.cond_dim}, got {cond.shape[-1]}")
+
+        modulation = self.dense(cond.to(self.dense.weight.dtype))
+        if x.ndim == 3:
+            # (B, 3*dim) → (B, 1, 3*dim), broadcast across the token axis: the
+            # timestep is a per-sample scalar, identical for every action token.
+            modulation = modulation.unsqueeze(1)
+        scale, shift, gate = modulation.chunk(3, dim=-1)
+        normed = normed * (1.0 + scale.float()) + shift.float()
+        return normed.to(dtype), gate.to(dtype)
+
+
+def _gated_residual(residual: torch.Tensor, out: torch.Tensor, gate: torch.Tensor | None) -> torch.Tensor:
+    if gate is None:
+        return residual + out
+    return residual + gate * out
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Dual-backbone: PaliGemma + AdaRMS action expert
+# ──────────────────────────────────────────────────────────────────────
+def _repeat_kv(hidden_states: torch.Tensor, n_rep: int) -> torch.Tensor:
+    """Repeat KV heads for grouped-query attention.
+
+    ``(B, num_kv_heads, S, D) → (B, num_kv_heads * n_rep, S, D)``.
+    """
+    if n_rep == 1:
+        return hidden_states
+    b, nh, s, d = hidden_states.shape
+    hidden_states = hidden_states[:, :, None, :, :].expand(b, nh, n_rep, s, d)
+    return hidden_states.reshape(b, nh * n_rep, s, d)
+
+
+def _attend(query_states, key_states, value_states, attention_mask, num_kv_groups, scaling):
+    """Manual eager attention: ``softmax(Q Kᵀ · scale + mask) · V``.
+
+    The mask is sliced to ``key_states.shape[-2]`` so the same
+    ``(B, 1, Q, prefix+suffix)`` mask works in both the prefix pass (K length =
+    prefix) and the suffix pass (K length = prefix + suffix).
+    """
+    k = _repeat_kv(key_states, num_kv_groups)
+    v = _repeat_kv(value_states, num_kv_groups)
+    attn_weights = torch.matmul(query_states, k.transpose(2, 3)) * scaling
+    if attention_mask is not None:
+        attn_weights = attn_weights + attention_mask[:, :, :, : k.shape[-2]]
+    attn_weights = F.softmax(attn_weights, dim=-1, dtype=torch.float32).to(query_states.dtype)
+    return torch.matmul(attn_weights, v)
+
+
+def _match(tensor: torch.Tensor, module: nn.Module) -> torch.Tensor:
+    """Cast ``tensor`` to the dtype ``module``'s weight expects."""
+    return tensor.to(module.weight.dtype) if tensor.dtype != module.weight.dtype else tensor
+
+
+def _compute_layer_prefix_only(layer_idx, hidden_states, attention_mask, position_ids, paligemma):
+    """Run one PaliGemma LM layer on the prefix, returning the layer output and
+    the post-RoPE ``(k, v)`` for the suffix pass.
+
+    Identical to π0: the prefix backbone is unchanged in π0.5 (no AdaRMS —
+    there is no timestep in the prefix).
+    """
+    model = paligemma.model.language_model
+    layer = model.layers[layer_idx]
+    residual = hidden_states
+    x = _match(layer.input_layernorm(hidden_states), layer.self_attn.q_proj)
+
+    hidden_shape = (*x.shape[:-1], -1, layer.self_attn.head_dim)
+    q = layer.self_attn.q_proj(x).view(hidden_shape).transpose(1, 2)
+    k = layer.self_attn.k_proj(x).view(hidden_shape).transpose(1, 2)
+    v = layer.self_attn.v_proj(x).view(hidden_shape).transpose(1, 2)
+
+    cos, sin = model.rotary_emb(v, position_ids)
+    q, k = apply_rotary_pos_emb(q, k, cos, sin, unsqueeze_dim=1)
+
+    att = _attend(
+        q,
+        k,
+        v,
+        attention_mask,
+        num_kv_groups=layer.self_attn.num_key_value_groups,
+        scaling=1.0 / math.sqrt(layer.self_attn.head_dim),
+    )
+    att = att.transpose(1, 2).reshape(q.shape[0], -1, q.shape[1] * layer.self_attn.head_dim)
+
+    out = layer.self_attn.o_proj(_match(att, layer.self_attn.o_proj)) + residual
+    after_resid = out
+    normed = layer.post_attention_layernorm(out)
+    out = layer.mlp(_match(normed, layer.mlp.up_proj)) + after_resid
+    return out, (k, v)
+
+
+def _compute_layer_suffix_only(
+    layer_idx,
+    hidden_states,
+    prefix_kv,
+    attention_mask,
+    position_ids,
+    gemma_expert,
+    adarms_cond,
+):
+    """Run one action-expert layer on the suffix with AdaRMS conditioning.
+
+    This is where π0.5 diverges from π0. Both norms are
+    :class:`Pi05AdaRMSNorm` and each returns a gate that scales its sublayer's
+    contribution to the residual stream.
+    """
+    layer = gemma_expert.model.layers[layer_idx]
+
+    residual = hidden_states
+    x, gate = layer.input_layernorm(hidden_states, adarms_cond)
+    x = _match(x, layer.self_attn.q_proj)
+
+    hidden_shape = (*x.shape[:-1], -1, layer.self_attn.head_dim)
+    q = layer.self_attn.q_proj(x).view(hidden_shape).transpose(1, 2)
+    k_suf = layer.self_attn.k_proj(x).view(hidden_shape).transpose(1, 2)
+    v_suf = layer.self_attn.v_proj(x).view(hidden_shape).transpose(1, 2)
+
+    # RoPE frequencies are shared between PaliGemma and the expert.
+    cos, sin = gemma_expert.model.rotary_emb(v_suf, position_ids)
+    q, k_suf = apply_rotary_pos_emb(q, k_suf, cos, sin, unsqueeze_dim=1)
+
+    # Concatenate cached prefix K/V (possibly different dtype) with suffix K/V.
+    k_prefix, v_prefix = prefix_kv
+    k = torch.cat([k_prefix.to(k_suf.dtype), k_suf], dim=2)
+    v = torch.cat([v_prefix.to(v_suf.dtype), v_suf], dim=2)
+
+    att = _attend(
+        q,
+        k,
+        v,
+        attention_mask,
+        num_kv_groups=layer.self_attn.num_key_value_groups,
+        scaling=1.0 / math.sqrt(layer.self_attn.head_dim),
+    )
+    att = att.transpose(1, 2).reshape(q.shape[0], -1, q.shape[1] * layer.self_attn.head_dim)
+
+    hidden_states = _gated_residual(residual, layer.self_attn.o_proj(_match(att, layer.self_attn.o_proj)), gate)
+
+    residual = hidden_states
+    x, gate = layer.post_attention_layernorm(hidden_states, adarms_cond)
+    return _gated_residual(residual, layer.mlp(_match(x, layer.mlp.up_proj)), gate)
+
+
+class PaliGemmaWithActionExpertPi05(nn.Module):
+    """Dual-backbone transformer: PaliGemma (Gemma 2B) + AdaRMS expert (300M).
+
+    Same two-mode dispatch as π0 (``prefix_only`` / ``suffix_only``), with one
+    structural change: after building a stock ``GemmaForCausalLM`` expert, every
+    norm in it is swapped for a :class:`Pi05AdaRMSNorm` carrying a ``dense``
+    conditioning projection.
+
+    Swapping in place — rather than subclassing ``GemmaModel`` as #4419 does —
+    keeps the module tree, and therefore the checkpoint key layout, identical to
+    the expert's stock layout apart from the norms themselves.
+    """
+
+    def __init__(self, vlm_config, action_expert_config):
+        super().__init__()
+
+        # PaliGemma prefix: identical to π0. It sees no timestep, so no AdaRMS.
+        vlm_config_hf = CONFIG_MAPPING["paligemma"]()
+        vlm_config_hf._vocab_size = 257152
+        vlm_config_hf.image_token_index = 257152
+        vlm_config_hf.text_config.hidden_size = vlm_config.width
+        vlm_config_hf.text_config.intermediate_size = vlm_config.mlp_dim
+        vlm_config_hf.text_config.num_attention_heads = vlm_config.num_heads
+        vlm_config_hf.text_config.head_dim = vlm_config.head_dim
+        vlm_config_hf.text_config.num_hidden_layers = vlm_config.depth
+        vlm_config_hf.text_config.num_key_value_heads = vlm_config.num_kv_heads
+        vlm_config_hf.text_config.hidden_activation = "gelu_pytorch_tanh"
+        vlm_config_hf.text_config.dtype = "float32"
+        vlm_config_hf.text_config.vocab_size = 257152
+        vlm_config_hf.vision_config.intermediate_size = 4304
+        vlm_config_hf.vision_config.projection_dim = 2048
+        vlm_config_hf.vision_config.projector_hidden_act = "gelu_fast"
+        vlm_config_hf.vision_config.dtype = "float32"
+
+        action_expert_config_hf = CONFIG_MAPPING["gemma"](
+            head_dim=action_expert_config.head_dim,
+            hidden_size=action_expert_config.width,
+            intermediate_size=action_expert_config.mlp_dim,
+            num_attention_heads=action_expert_config.num_heads,
+            num_hidden_layers=action_expert_config.depth,
+            num_key_value_heads=action_expert_config.num_kv_heads,
+            vocab_size=257152,
+            hidden_activation="gelu_pytorch_tanh",
+            dtype="float32",
+        )
+
+        self.paligemma = PaliGemmaForConditionalGeneration(config=vlm_config_hf)
+        self.gemma_expert = GemmaForCausalLM(config=action_expert_config_hf)
+        # The action expert doesn't embed tokens — it only consumes the
+        # suffix action embeddings we feed in.
+        self.gemma_expert.model.embed_tokens = None
+
+        self.adarms_cond_dim = action_expert_config.width
+        self._install_adarms_norms(action_expert_config)
+
+    def _install_adarms_norms(self, action_expert_config) -> None:
+        """Replace every action-expert RMSNorm with a conditioned AdaRMS norm."""
+        expert = self.gemma_expert.model
+        eps = getattr(self.gemma_expert.config, "rms_norm_eps", 1e-6)
+        width = action_expert_config.width
+        for layer in expert.layers:
+            layer.input_layernorm = Pi05AdaRMSNorm(width, eps=eps, cond_dim=self.adarms_cond_dim)
+            layer.post_attention_layernorm = Pi05AdaRMSNorm(width, eps=eps, cond_dim=self.adarms_cond_dim)
+        expert.norm = Pi05AdaRMSNorm(width, eps=eps, cond_dim=self.adarms_cond_dim)
+
+    def embed_image(self, pixel_values: torch.Tensor) -> torch.Tensor:
+        """Encode images with SigLIP vision tower + PaliGemma projector.
+
+        The two steps are run explicitly rather than via
+        ``PaliGemmaModel.get_image_features`` because that helper divides the
+        projector output by ``sqrt(text_hidden_size)``. Being explicit keeps the
+        scale unambiguous and matches π0 exactly (SigLIP is unchanged in π0.5).
+        """
+        # Shapes: pixel_values (B, 3, 224, 224) → SigLIP (B, 256, 1152)
+        #                                      → projector (B, 256, 2048)
+        vision_outputs = self.paligemma.model.vision_tower(pixel_values)
+        image_features = vision_outputs.last_hidden_state
+        return self.paligemma.model.multi_modal_projector(image_features)
+
+    def embed_language_tokens(self, tokens: torch.Tensor) -> torch.Tensor:
+        """Embed language tokens, returning the ``* sqrt(hidden)``-scaled embedding.
+
+        The scaling location moved across transformers releases: at ≤5.3 the
+        normalizer lives inside ``GemmaModel.forward`` (which we bypass), and at
+        ≥5.4 ``GemmaTextScaledWordEmbedding`` self-applies it. Detect and avoid
+        double-scaling.
+        """
+        embed_tokens = self.paligemma.model.language_model.embed_tokens
+        lang_emb = embed_tokens(tokens)
+        if getattr(embed_tokens, "embed_scale", None) is None:
+            lang_emb = lang_emb * math.sqrt(lang_emb.shape[-1])
+        return lang_emb
+
+    def forward(
+        self,
+        attention_mask: torch.Tensor | None = None,
+        position_ids: torch.LongTensor | None = None,
+        past_key_values=None,
+        inputs_embeds: list[torch.Tensor | None] | None = None,
+        use_cache: bool = False,
+        adarms_cond: torch.Tensor | None = None,
+    ):
+        """Dispatch to prefix_only / suffix_only and return
+        ``([prefix_out, suffix_out], past_key_values_or_None)``.
+        """
+        num_layers = self.paligemma.config.text_config.num_hidden_layers
+        pali_lm = self.paligemma.model.language_model
+        expert_lm = self.gemma_expert.model
+
+        if inputs_embeds[1] is None:
+            hidden_states = inputs_embeds[0]
+            kv_list: list[tuple[torch.Tensor, torch.Tensor]] = []
+            for layer_idx in range(num_layers):
+                hidden_states, kv = _compute_layer_prefix_only(
+                    layer_idx,
+                    hidden_states,
+                    attention_mask,
+                    position_ids,
+                    paligemma=self.paligemma,
+                )
+                kv_list.append(kv)
+            hidden_states = pali_lm.norm(hidden_states)
+            return [hidden_states, None], (kv_list if use_cache else None)
+
+        if inputs_embeds[0] is not None:
+            raise ValueError(
+                "PaliGemmaWithActionExpertPi05.forward only supports prefix-only "
+                "or suffix-only dispatch; got both inputs_embeds populated."
+            )
+        if not isinstance(past_key_values, list):
+            raise TypeError(
+                "suffix_only forward expects past_key_values to be the "
+                "list[(k, v)] produced by a previous prefix_only forward; "
+                f"got {type(past_key_values)}"
+            )
+        hidden_states = inputs_embeds[1]
+        for layer_idx in range(num_layers):
+            hidden_states = _compute_layer_suffix_only(
+                layer_idx,
+                hidden_states,
+                past_key_values[layer_idx],
+                attention_mask,
+                position_ids,
+                gemma_expert=self.gemma_expert,
+                adarms_cond=adarms_cond,
+            )
+        hidden_states, _ = expert_lm.norm(hidden_states, adarms_cond)
+        return [None, hidden_states], None
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Main π0.5 Model
+# ──────────────────────────────────────────────────────────────────────
+class Pi05ForActionPrediction(nn.Module):
+    """π0.5 VLA model for robot action prediction via flow matching.
+
+    Inference flow:
+      1. Embed prefix (images + language, where the language already carries the
+         discretized state) → prefix tokens.
+      2. Forward prefix through PaliGemma → layer-wise KV cache.
+      3. For each denoising step ``t = 1.0, 1-dt, ..., 0``:
+         a. Embed the timestep → an AdaRMS conditioning vector.
+         b. Embed the suffix (action tokens only).
+         c. Forward the suffix through the AdaRMS action expert.
+         d. ``x_t = x_t + dt * v_t`` (Euler integration).
+      4. Return ``x_0`` as the predicted action chunk.
+    """
+
+    def __init__(self, config, quant_config=None, prefix: str = ""):
+        super().__init__()
+        # ``quant_config`` is accepted for interface compatibility but unused —
+        # quant_config is not plumbed through; the weight dtype comes from the pipeline.
+        del quant_config
+        self.config = config
+
+        self.action_dim = getattr(config, "max_action_dim", DEFAULT_ACTION_DIM)
+        self.max_state_dim = getattr(config, "max_state_dim", self.action_dim)
+        self.action_horizon = getattr(config, "chunk_size", DEFAULT_ACTION_HORIZON)
+        self.num_inference_steps = getattr(config, "num_inference_steps", DEFAULT_NUM_INFERENCE_STEPS)
+
+        paligemma_variant = getattr(config, "paligemma_variant", "gemma_2b")
+        action_expert_variant = getattr(config, "action_expert_variant", "gemma_300m")
+        vlm_config = get_gemma_config(paligemma_variant)
+        expert_config = get_gemma_config(action_expert_variant)
+        self.vlm_width = vlm_config.width
+        self.expert_width = expert_config.width
+
+        # Dual backbone
+        self.paligemma_with_expert = PaliGemmaWithActionExpertPi05(vlm_config, expert_config)
+
+        # Action chunk projections.
+        self.action_in_proj = nn.Linear(self.action_dim, self.expert_width)
+        self.action_out_proj = nn.Linear(self.expert_width, self.action_dim)
+
+        # π0.5 timestep MLP: (W → W → W) with SiLU, feeding AdaRMS.
+        # π0 instead has action_time_mlp_{in,out} of shape (2W → W → W) because
+        # it concatenates the time embedding onto the action embedding.
+        # NOTE: there is deliberately **no** ``state_proj`` here — that is the
+        # π0-only continuous-state path.
+        self.time_mlp_in = nn.Linear(self.expert_width, self.expert_width)
+        self.time_mlp_out = nn.Linear(self.expert_width, self.expert_width)
+
+    # ── Prefix embedding ─────────────────────────────────────────────
+    def embed_prefix(
+        self,
+        images: list[torch.Tensor],
+        image_masks: list[torch.Tensor],
+        lang_tokens: torch.Tensor,
+        lang_masks: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        """Build prefix embeddings, per-token padding mask, and AR mask.
+
+        Prefix tokens form ``[img_cam_0..., ..., lang_tokens...]`` with fully
+        bidirectional attention (all-zero ``att_masks``). Identical to π0 — the
+        state is inside ``lang_tokens``, so nothing here changes shape-wise.
+
+        Cameras are embedded one at a time; each call is ``(B, 3, 224, 224)``.
+        The number of slots is fixed by ``config.max_cameras`` for the deployed
+        model; missing cameras occupy their slot with a false image mask.
+        """
+        num_views = len(images)
+        if len(image_masks) != num_views:
+            raise ValueError(
+                f"images and image_masks must contain the same number of views, got {num_views} and {len(image_masks)}."
+            )
+        max_cameras = int(self.config.max_cameras)
+        if num_views != max_cameras:
+            raise ValueError(f"Expected exactly max_cameras={max_cameras} image views, got {num_views}.")
+
+        embs: list[torch.Tensor] = []
+        pad_masks: list[torch.Tensor] = []
+        att_masks: list[int] = []
+
+        for img, img_mask in zip(images, image_masks):
+            img_emb = self.paligemma_with_expert.embed_image(img)
+            bsize, num_img_embs = img_emb.shape[:2]
+            embs.append(img_emb)
+            pad_masks.append(img_mask[:, None].expand(bsize, num_img_embs))
+            att_masks += [0] * num_img_embs
+
+        lang_emb = self.paligemma_with_expert.embed_language_tokens(lang_tokens)
+        embs.append(lang_emb)
+        pad_masks.append(lang_masks)
+        att_masks += [0] * lang_emb.shape[1]
+
+        embs = torch.cat(embs, dim=1)
+        pad_masks = torch.cat(pad_masks, dim=1)
+        att_masks = torch.tensor(att_masks, dtype=torch.bool, device=embs.device)
+        att_masks = att_masks[None, :].expand(pad_masks.shape[0], -1)
+
+        return embs, pad_masks, att_masks
+
+    # ── Timestep + suffix embedding ──────────────────────────────────
+    def embed_timestep(self, timestep: torch.Tensor) -> torch.Tensor:
+        """Timestep → AdaRMS conditioning vector ``(B, expert_width)``.
+
+        ``silu(time_mlp_out(silu(time_mlp_in(sinusoid(t)))))``. The trailing
+        SiLU is part of the reference implementation — dropping it is a silent
+        numerical error, not a crash.
+        """
+        model_dtype = self.action_in_proj.weight.dtype
+        time_emb = create_sinusoidal_pos_embedding(
+            timestep,
+            self.action_in_proj.out_features,
+            min_period=getattr(self.config, "min_period", 4e-3),
+            max_period=getattr(self.config, "max_period", 4.0),
+            device=timestep.device,
+        ).to(dtype=model_dtype)
+        time_cond = self.time_mlp_in(time_emb)
+        time_cond = F.silu(time_cond)
+        time_cond = self.time_mlp_out(time_cond)
+        return F.silu(time_cond)
+
+    def embed_suffix(
+        self,
+        noisy_actions: torch.Tensor,
+        timestep: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]:
+        """Build the suffix: **action tokens only**, plus the AdaRMS condition.
+
+        π0's suffix is ``[state_token, action_tokens×H]`` with an AR mask of
+        ``[1, 1, 0...]``. π0.5 has no state token, so the suffix is
+        ``[action_tokens×H]`` and the mask is ``[1] + [0]*(H-1)``: the first
+        action token opens a causal block and the rest attend bidirectionally
+        within it.
+        """
+        model_dtype = self.action_in_proj.weight.dtype
+        noisy_actions = noisy_actions.to(dtype=model_dtype)
+
+        time_cond = self.embed_timestep(timestep)
+        action_emb = self.action_in_proj(noisy_actions)  # (B, H, W)
+
+        bsize, action_len = action_emb.shape[:2]
+        pad_masks = torch.ones(bsize, action_len, dtype=torch.bool, device=action_emb.device)
+        att_masks = torch.tensor(
+            [1] + [0] * (self.action_horizon - 1),
+            dtype=action_emb.dtype,
+            device=action_emb.device,
+        )[None, :].expand(bsize, -1)
+        return action_emb, pad_masks, att_masks, time_cond
+
+    # ── Denoising step ───────────────────────────────────────────────
+    def denoise_step(
+        self,
+        prefix_pad_masks: torch.Tensor,
+        past_key_values,
+        x_t: torch.Tensor,
+        timestep: torch.Tensor,
+    ) -> torch.Tensor:
+        """Apply one flow-matching denoising step: predict ``v_t`` from ``x_t``.
+
+        Signature differs from π0's by exactly one argument: no ``state``.
+        """
+        suffix_embs, suffix_pad_masks, suffix_att_masks, time_cond = self.embed_suffix(x_t, timestep)
+
+        batch_size = prefix_pad_masks.shape[0]
+        suffix_len = suffix_pad_masks.shape[1]
+        prefix_len = prefix_pad_masks.shape[1]
+
+        prefix_pad_2d_masks = prefix_pad_masks[:, None, :].expand(batch_size, suffix_len, prefix_len)
+        suffix_att_2d_masks = make_att_2d_masks(suffix_pad_masks, suffix_att_masks)
+        full_att_2d_masks = torch.cat([prefix_pad_2d_masks, suffix_att_2d_masks], dim=2)
+
+        # Position IDs continue from where the prefix's last valid token left off.
+        prefix_offsets = torch.sum(prefix_pad_masks, dim=-1)[:, None]
+        position_ids = prefix_offsets + torch.cumsum(suffix_pad_masks, dim=1) - 1
+
+        full_att_2d_masks_4d = prepare_attention_masks_4d(full_att_2d_masks)
+
+        outputs_embeds, _ = self.paligemma_with_expert.forward(
+            attention_mask=full_att_2d_masks_4d,
+            position_ids=position_ids,
+            past_key_values=past_key_values,
+            inputs_embeds=[None, suffix_embs],
+            use_cache=False,
+            adarms_cond=time_cond,
+        )
+
+        # Every suffix token is an action token in π0.5 (no state token to drop).
+        suffix_out = outputs_embeds[1][:, -self.action_horizon :]
+        suffix_out = suffix_out.to(dtype=self.action_out_proj.weight.dtype)
+        return self.action_out_proj(suffix_out)
+
+    # ── Full action generation ───────────────────────────────────────
+    @torch.no_grad()
+    def sample_actions(
+        self,
+        images: list[torch.Tensor],
+        image_masks: list[torch.Tensor],
+        lang_tokens: torch.Tensor,
+        lang_masks: torch.Tensor,
+        noise: torch.Tensor | None = None,
+        num_steps: int | None = None,
+        generator: torch.Generator | list[torch.Generator] | None = None,
+    ) -> torch.Tensor:
+        """Generate an action chunk via iterative flow-matching denoising.
+
+        Convention: ``t=1`` is noise, ``t=0`` is the target — opposite of the
+        published π0 paper but matching both OpenPI and LeRobot.
+
+        Takes no ``state``: π0.5's state rides inside ``lang_tokens``.
+        """
+        if num_steps is None:
+            num_steps = self.num_inference_steps
+
+        bsize = lang_tokens.shape[0]
+        device = lang_tokens.device
+        if noise is None:
+            noise_shape = (self.action_horizon, self.action_dim)
+            if isinstance(generator, list):
+                if len(generator) != bsize:
+                    raise ValueError(f"Expected {bsize} generators, got {len(generator)}.")
+                noise = torch.stack(
+                    [torch.randn(noise_shape, dtype=torch.float32, device=device, generator=item) for item in generator]
+                )
+            else:
+                noise = torch.randn(
+                    bsize,
+                    *noise_shape,
+                    dtype=torch.float32,
+                    device=device,
+                    generator=generator,
+                )
+
+        # 1. Prefix embeddings + mask building.
+        prefix_embs, prefix_pad_masks, prefix_att_masks = self.embed_prefix(
+            images, image_masks, lang_tokens, lang_masks
+        )
+        prefix_att_2d_masks = make_att_2d_masks(prefix_pad_masks, prefix_att_masks)
+        prefix_position_ids = torch.cumsum(prefix_pad_masks, dim=1) - 1
+        prefix_att_2d_masks_4d = prepare_attention_masks_4d(prefix_att_2d_masks)
+
+        # 2. Forward prefix through PaliGemma LM, producing a list[(k, v)] cache.
+        _, past_key_values = self.paligemma_with_expert.forward(
+            attention_mask=prefix_att_2d_masks_4d,
+            position_ids=prefix_position_ids,
+            past_key_values=None,
+            inputs_embeds=[prefix_embs, None],
+            use_cache=True,
+        )
+
+        # 3. Euler-integrated denoising from t=1 down to t=0.
+        dt = -1.0 / num_steps
+        x_t = noise
+        for step in range(num_steps):
+            t = 1.0 + step * dt
+            time_tensor = torch.full((bsize,), t, dtype=torch.float32, device=device)
+            v_t = self.denoise_step(
+                prefix_pad_masks=prefix_pad_masks,
+                past_key_values=past_key_values,
+                x_t=x_t,
+                timestep=time_tensor,
+            )
+            x_t = x_t + dt * v_t
+        return x_t
+
+    # ── Weight loading ───────────────────────────────────────────────
+    def load_weights(
+        self,
+        weights: Iterable[tuple[str, torch.Tensor]],
+        *,
+        strict: bool = True,
+    ):
+        """Load and audit a LeRobot π0.5 safetensors checkpoint.
+
+        Same remap rules as π0 (strip the ``model.`` prefix, flatten→nested
+        PaliGemma submodules, tied ``lm_head`` → ``embed_tokens``, version-robust
+        SigLIP nesting), plus two π0.5-specific ones:
+
+          * ``action_time_mlp_{in,out}`` → ``time_mlp_{in,out}``: some
+            checkpoints were exported under the π0 parameter names.
+          * ``state_proj.*`` is reported, not silently dropped. A π0.5
+            checkpoint should not contain it; its presence usually means a π0
+            checkpoint was pointed at the π0.5 model class, which would
+            otherwise run happily with a randomly-initialized action expert.
+
+        The action-expert norms are AdaRMS here, so they expose ``dense.weight``
+        / ``dense.bias`` and no plain ``weight``. A checkpoint that carries a
+        plain expert-norm ``weight`` is a π0-shaped checkpoint; that too is
+        rejected rather than skipped. ``strict=False`` exists only for focused
+        remapping unit tests that intentionally provide a partial state dict;
+        the serving path always uses the strict default.
+        """
+        params_dict = dict(self.named_parameters())
+        buffers_dict = dict(self.named_buffers())
+
+        _PALIGEMMA_SUBMODULES = ("vision_tower", "multi_modal_projector", "language_model")
+        _EXPERT_PREFIX = "paligemma_with_expert.gemma_expert.model."
+
+        def _remap(name: str) -> str:
+            # Strip the leading "model." that LeRobot's PI05Policy wrapper adds.
+            if name.startswith("model."):
+                name = name[len("model.") :]
+
+            # π0-style timestep MLP names → π0.5 names.
+            if name.startswith("action_time_mlp_in."):
+                name = "time_mlp_in." + name[len("action_time_mlp_in.") :]
+            elif name.startswith("action_time_mlp_out."):
+                name = "time_mlp_out." + name[len("action_time_mlp_out.") :]
+
+            # Nested PaliGemma layout.
+            for sub in _PALIGEMMA_SUBMODULES:
+                flat = f"paligemma_with_expert.paligemma.{sub}."
+                nested = f"paligemma_with_expert.paligemma.model.{sub}."
+                if name.startswith(flat) and not name.startswith(nested):
+                    return nested + name[len(flat) :]
+
+            if name == "paligemma_with_expert.paligemma.lm_head.weight":
+                return "paligemma_with_expert.paligemma.model.language_model.embed_tokens.weight"
+
+            return name
+
+        def _fix_vision_tower(name: str) -> str:
+            """Reconcile SigLIP nesting across transformers versions (≤5.3 wraps
+            the encoder in ``vision_tower.vision_model.*``; ≥5.4 flattens it)."""
+            vt = "paligemma_with_expert.paligemma.model.vision_tower."
+            if not name.startswith(vt):
+                return name
+            rest = name[len(vt) :]
+            if name in params_dict or name in buffers_dict:
+                return name
+            if rest.startswith("vision_model."):
+                candidate = vt + rest[len("vision_model.") :]
+            else:
+                candidate = vt + "vision_model." + rest
+            return candidate if (candidate in params_dict or candidate in buffers_dict) else name
+
+        loaded = 0
+        skipped: list[str] = []
+        pi0_shaped: list[str] = []
+        filled_params: set = set()
+
+        for name, loaded_weight in weights:
+            mapped = _fix_vision_tower(_remap(name))
+
+            # Diagnose π0-shaped keys instead of dropping them quietly.
+            is_expert_norm_weight = mapped.startswith(_EXPERT_PREFIX) and (
+                mapped.endswith("input_layernorm.weight")
+                or mapped.endswith("post_attention_layernorm.weight")
+                or mapped == _EXPERT_PREFIX + "norm.weight"
+            )
+            if mapped.startswith("state_proj.") or is_expert_norm_weight:
+                pi0_shaped.append(mapped)
+                continue
+
+            if mapped in params_dict:
+                param = params_dict[mapped]
+                weight_loader = getattr(param, "weight_loader", default_weight_loader)
+                weight_loader(param, loaded_weight)
+                loaded += 1
+                filled_params.add(mapped)
+            elif mapped in buffers_dict:
+                buffers_dict[mapped].copy_(loaded_weight)
+                loaded += 1
+                filled_params.add(mapped)
+            else:
+                skipped.append(mapped)
+
+        # LeRobot stores PaliGemma's tied text embedding as lm_head.weight; keep
+        # lm_head filled so the tied-weight state stays consistent.
+        embed_key = "paligemma_with_expert.paligemma.model.language_model.embed_tokens.weight"
+        lm_head_key = "paligemma_with_expert.paligemma.lm_head.weight"
+        if embed_key in filled_params and lm_head_key in params_dict and lm_head_key not in filled_params:
+            params_dict[lm_head_key].data.copy_(params_dict[embed_key].data)
+            filled_params.add(lm_head_key)
+
+        # Reverse audit: any model param that got no checkpoint tensor at all
+        # would be running with random init.
+        missing_params: list[str] = []
+        for pname in params_dict:
+            if pname in filled_params:
+                continue
+            if "rotary_emb" in pname or pname.endswith(".inv_freq"):
+                continue
+            missing_params.append(pname)
+
+        parts: list[str] = []
+        if pi0_shaped:
+            parts.append(
+                f"{len(pi0_shaped)} checkpoint key(s) are π0-shaped, not π0.5-shaped (first 5: {pi0_shaped[:5]})"
+            )
+        if skipped:
+            parts.append(f"{len(skipped)} checkpoint key(s) had no model target (first 5: {skipped[:5]})")
+        if missing_params:
+            parts.append(f"{len(missing_params)} model param(s) received no weight (first 5: {missing_params[:5]})")
+
+        if parts and strict:
+            raise RuntimeError("Incomplete or incompatible π0.5 checkpoint: " + "; ".join(parts))
+        if parts:
+            logger.debug("π0.5 partial test load: %d tensors loaded — %s.", loaded, "; ".join(parts))
+        else:
+            logger.info("π0.5 load_weights: %d tensors loaded, 0 skipped, 0 missing.", loaded)
+        return filled_params
+
+
+EntryClass = Pi05ForActionPrediction
diff --git a/vllm_omni/diffusion/models/pi05/pipeline_pi05.py b/vllm_omni/diffusion/models/pi05/pipeline_pi05.py
new file mode 100644
index 00000000000..a4d32ed8168
--- /dev/null
+++ b/vllm_omni/diffusion/models/pi05/pipeline_pi05.py
@@ -0,0 +1,311 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""π0.5 VLA pipeline for vllm-omni.
+
+Entry point for ``DiffusionEngine.step() → pipeline.forward(req)``. Mirrors the
+DreamZero contract and the π0 pipeline: the pipeline owns ALL preprocessing. It
+reads the raw robot observation from
+``req.sampling_params.extra_args["robot_obs"]`` (delivered by the OpenPI
+realtime serving layer), builds model inputs, runs flow-matching denoising, and
+returns ``DiffusionOutput(output={"actions": ndarray})``.
+
+π0.5 is stateless across calls (no KV reuse, first-order Markov), so
+``session_id`` / ``reset`` from the OpenPI protocol are accepted but ignored.
+
+The post-processing order is load-bearing and matches LeRobot::
+
+    unnormalize → absolute actions → to_cpu
+
+``AbsoluteActionsProcessorStep`` must run *after* unnormalization, because a
+relative-action checkpoint's ``norm_stats`` are computed in relative space.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import fields as dataclass_fields
+
+import numpy as np
+import torch
+from torch import nn
+from vllm.logger import init_logger
+
+from vllm_omni.diffusion.data import DiffusionOutput, OmniDiffusionConfig
+from vllm_omni.diffusion.models.pi05.config import SUPPORTED_DTYPE_NAMES, Pi05Config
+from vllm_omni.diffusion.models.pi05.modeling_pi05 import Pi05ForActionPrediction
+from vllm_omni.diffusion.models.pi05.processor_pi05 import Pi05Processor
+from vllm_omni.diffusion.models.pi05_pipeline_config import PI05_PIPELINE as PI05_PIPELINE
+from vllm_omni.diffusion.request import OmniDiffusionRequest
+
+logger = init_logger(__name__)
+
+# π0.5 pins the PaliGemma tokenizer (LeRobot hardcodes it too).
+DEFAULT_PI05_TOKENIZER = "google/paligemma-3b-pt-224"
+
+# float16 is absent deliberately, not by oversight: nothing here has been
+# validated against it. The float32/bfloat16 trade-off is in the deploy config
+# and recipes/lerobot/Pi05.md.
+SUPPORTED_DTYPES = (torch.float32, torch.bfloat16)
+
+# The two lists guard different entry points — what the checkpoint declares
+# versus the dtype actually cast to — so they must not drift apart.
+assert {str(dtype).split(".")[-1] for dtype in SUPPORTED_DTYPES} == set(SUPPORTED_DTYPE_NAMES)
+
+
+def _checkpoint_declared_keys(model_dir: str) -> set[str]:
+    """The keys the checkpoint's config.json actually carries."""
+    path = os.path.join(model_dir, "config.json")
+    if not os.path.exists(path):
+        return set()
+    with open(path, encoding="utf-8") as f:
+        return set(json.load(f))
+
+
+def _comparable(value):
+    """Compare yaml and checkpoint values without tripping on list/tuple."""
+    return list(value) if isinstance(value, (list, tuple)) else value
+
+
+def _pi05_post_process(x):
+    """Module-level identity post-process (picklable across the orchestrator's
+    multiprocess boundary — a local closure is not)."""
+    return x
+
+
+def get_pi05_post_process_func(od_config: OmniDiffusionConfig):
+    """π0.5 returns actions directly; post-processing is identity."""
+    del od_config
+    return _pi05_post_process
+
+
+_LEROBOT_FLOAT32_IN_BFLOAT16 = (
+    "vision_tower",
+    "multi_modal_projector",
+    "input_layernorm",
+    "post_attention_layernorm",
+    "model.norm",
+)
+
+
+def _to_bfloat16_for_inference(model: Pi05ForActionPrediction) -> None:
+    """Apply LeRobot's mixed-precision inference layout explicitly."""
+    inner_model = model.paligemma_with_expert
+    for name, param in inner_model.named_parameters():
+        target_dtype = (
+            torch.float32 if any(selector in name for selector in _LEROBOT_FLOAT32_IN_BFLOAT16) else torch.bfloat16
+        )
+        param.data = param.data.to(dtype=target_dtype)
+    for buffer in inner_model.buffers():
+        if buffer.is_floating_point():
+            buffer.data = buffer.data.to(dtype=torch.bfloat16)
+
+    for name, param in model.named_parameters():
+        if not name.startswith("paligemma_with_expert."):
+            param.data = param.data.to(dtype=torch.float32)
+    for name, buffer in model.named_buffers():
+        if not name.startswith("paligemma_with_expert.") and buffer.is_floating_point():
+            buffer.data = buffer.data.to(dtype=torch.float32)
+
+
+def _set_inference_dtype(model: Pi05ForActionPrediction, dtype: torch.dtype) -> None:
+    if dtype == torch.float32:
+        model.to(dtype=torch.float32)
+    elif dtype == torch.bfloat16:
+        _to_bfloat16_for_inference(model)
+    else:
+        raise ValueError(f"Unsupported π0.5 inference dtype: {dtype!r}.")
+
+
+class Pi05Pipeline(nn.Module):
+    """π0.5 VLA pipeline: raw robot obs → continuous action chunk.
+
+    Registered as ``"Pi05Pipeline"`` in the diffusion registry.
+    """
+
+    def __init__(self, *, od_config: OmniDiffusionConfig, prefix: str = ""):
+        super().__init__()
+        self.od_config = od_config
+        self.prefix = prefix
+        self.model_dir = self._resolve_model_dir(od_config.model)
+        self.config = self._build_config(od_config)
+
+        custom_args = od_config.custom_pipeline_args or {}
+        self.tokenizer_source = str(custom_args.get("tokenizer", self._resolve_tokenizer_source()))
+
+        self._torch_dtype = self._resolve_dtype(od_config)
+        self._device = self._resolve_device(od_config)
+
+        self.tokenizer = self._load_tokenizer()
+        self.model = self._initialize_model()
+
+        self.processor = Pi05Processor(self.config, self.tokenizer, self._device)
+
+    # ------------------------------------------------------------------
+    # Construction helpers
+    # ------------------------------------------------------------------
+    @staticmethod
+    def _resolve_model_dir(model: str | None) -> str | None:
+        """Return a local directory for ``model``; download an HF repo id if needed."""
+        if not model:
+            return None
+        if os.path.isdir(model):
+            return model
+        # Via repo_utils' shared HfApi rather than huggingface_hub directly, so
+        # the download carries vLLM-Omni's user agent like every other repo access.
+        from vllm_omni.transformers_utils.repo_utils import hf_api
+
+        return hf_api().snapshot_download(
+            repo_id=model,
+            allow_patterns=["*.json", "*.safetensors", "*.model", "tokenizer*"],
+        )
+
+    def _build_config(self, od_config: OmniDiffusionConfig) -> Pi05Config:
+        """Read the config from the checkpoint, then let the deploy yaml override it."""
+        checkpoint_config = Pi05Config.from_pretrained(self.model_dir) if self.model_dir else None
+        if checkpoint_config is None:
+            return Pi05Config.from_model_config(od_config.model_config)
+        if not od_config.model_config:
+            return checkpoint_config
+
+        resolved = {
+            item.name: getattr(checkpoint_config, item.name) for item in dataclass_fields(Pi05Config) if item.init
+        }
+        # Only a key the checkpoint actually declares can disagree with the yaml.
+        # Comparing against the dataclass default instead would report every
+        # serving-only field, such as policy_server_config, on every start.
+        declared_keys = _checkpoint_declared_keys(self.model_dir)
+        for key, value in od_config.model_config.items():
+            if key in resolved and key in declared_keys and _comparable(value) != _comparable(resolved[key]):
+                logger.warning(
+                    "Pi05Pipeline: the deploy config sets %s=%r, overriding %r from the checkpoint.",
+                    key,
+                    value,
+                    resolved[key],
+                )
+        resolved.update(od_config.model_config)
+        return Pi05Config.from_model_config(resolved)
+
+    def _resolve_tokenizer_source(self) -> str:
+        """Prefer the checkpoint dir if it ships tokenizer files; else PaliGemma."""
+        if self.model_dir and os.path.isdir(self.model_dir):
+            if os.path.exists(os.path.join(self.model_dir, "tokenizer_config.json")):
+                return self.model_dir
+        return DEFAULT_PI05_TOKENIZER
+
+    @staticmethod
+    def _resolve_dtype(od_config: OmniDiffusionConfig) -> torch.dtype:
+        """Resolve the dtype the weights are actually cast to.
+
+        This is the load-bearing check, not ``Pi05Config.dtype``: the cast in
+        :meth:`_initialize_model` reads the *top-level* ``OmniDiffusionConfig``
+        field, so a guard on the model config alone would let an unsupported
+        dtype through. See :data:`SUPPORTED_DTYPES` for why float16 is excluded.
+        """
+        dt = od_config.dtype
+        resolved = dt if isinstance(dt, torch.dtype) else getattr(torch, str(dt).split(".")[-1], None)
+        if resolved not in SUPPORTED_DTYPES:
+            raise ValueError(
+                f"Unsupported π0.5 dtype: {dt!r}. Supported: "
+                f"{', '.join(sorted(str(d).split('.')[-1] for d in SUPPORTED_DTYPES))}."
+            )
+        return resolved
+
+    @staticmethod
+    def _resolve_device(od_config: OmniDiffusionConfig) -> torch.device:
+        from vllm_omni.diffusion.distributed.utils import get_local_device
+
+        try:
+            return get_local_device()
+        except Exception:  # noqa: BLE001
+            return torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+    def _load_tokenizer(self):
+        from transformers import AutoTokenizer
+
+        # padding_side="right" is part of the π0.5 spec: the prefix is a fixed
+        # 200-token block whose live tokens must start at index 0.
+        return AutoTokenizer.from_pretrained(self.tokenizer_source, padding_side="right")
+
+    def has_real_checkpoint(self) -> bool:
+        return bool(self.model_dir) and os.path.exists(os.path.join(self.model_dir, "model.safetensors"))
+
+    def _initialize_model(self) -> Pi05ForActionPrediction:
+        if not self.has_real_checkpoint():
+            expected = os.path.join(self.model_dir or "<missing-model-dir>", "model.safetensors")
+            raise FileNotFoundError(f"π0.5 serving requires checkpoint weights at {expected}.")
+        model = Pi05ForActionPrediction(self.config)
+        _set_inference_dtype(model, self._torch_dtype)
+        model.to(device=self._device)
+        self._load_checkpoint(model)
+        model.eval()
+        return model
+
+    def _load_checkpoint(self, model: Pi05ForActionPrediction) -> None:
+        import safetensors.torch
+
+        path = os.path.join(self.model_dir, "model.safetensors")
+        logger.info("Pi05Pipeline: loading π0.5 weights from %s", path)
+        try:
+            state = safetensors.torch.load_file(path)
+            model.load_weights(state.items())
+        except Exception as exc:
+            raise RuntimeError(f"Failed to load complete π0.5 checkpoint {path}: {exc}") from exc
+
+    # ------------------------------------------------------------------
+    # Framework weight-loading hook
+    # ------------------------------------------------------------------
+    def load_weights(self, weights=()):  # noqa: D401
+        """No-op for the diffusion loader: π0.5 self-loads its checkpoint."""
+        for _ in weights:
+            pass
+        return None
+
+    # ------------------------------------------------------------------
+    # Inference
+    # ------------------------------------------------------------------
+    @torch.inference_mode()
+    def forward(self, req: OmniDiffusionRequest, **kwargs) -> DiffusionOutput:
+        extra_args = getattr(req.sampling_params, "extra_args", None) or {}
+        robot_obs = extra_args.get("robot_obs")
+
+        if robot_obs is None:
+            # Dummy warmup path (no obs): return zeros so engine warmup/capture
+            # doesn't crash. Mirrors DreamZero's dummy-run handling.
+            first_prompt = req.prompts[0] if req.prompts else ""
+            prompt = first_prompt if isinstance(first_prompt, str) else (first_prompt.get("prompt") or "")
+            num_steps = getattr(req.sampling_params, "num_inference_steps", None)
+            if prompt == "dummy run" or num_steps == 1:
+                logger.info("Pi05Pipeline: dummy warmup request without robot_obs — returning zeros.")
+                return DiffusionOutput(
+                    output={
+                        "actions": np.zeros(
+                            (self.config.chunk_size, self.config.action_dim),
+                            dtype=np.float32,
+                        )
+                    },
+                )
+            return DiffusionOutput(
+                error="Pi05Pipeline.forward requires sampling_params.extra_args['robot_obs'].",
+            )
+
+        images, image_masks, lang_tokens, lang_masks = self.processor.build_model_inputs(robot_obs)
+
+        num_steps = getattr(req.sampling_params, "num_inference_steps", None)
+        if num_steps is not None and (
+            isinstance(num_steps, bool) or not isinstance(num_steps, (int, np.integer)) or int(num_steps) < 1
+        ):
+            raise ValueError(f"num_inference_steps must be a positive integer, got {num_steps!r}.")
+        if num_steps is not None:
+            num_steps = int(num_steps)
+
+        actions = self.model.sample_actions(
+            images=images,
+            image_masks=image_masks,
+            lang_tokens=lang_tokens,
+            lang_masks=lang_masks,
+            num_steps=num_steps,
+            generator=req.sampling_params.generator,
+        )
+
+        return DiffusionOutput(output={"actions": self.processor.build_model_outputs(actions, robot_obs)})
diff --git a/vllm_omni/diffusion/models/pi05/processor_pi05.py b/vllm_omni/diffusion/models/pi05/processor_pi05.py
new file mode 100644
index 00000000000..11ebad2db17
--- /dev/null
+++ b/vllm_omni/diffusion/models/pi05/processor_pi05.py
@@ -0,0 +1,568 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+r"""Preprocessing for the π0.5 VLA model.
+
+Converts a raw robot observation (multi-camera images + language instruction +
+proprioceptive state) into the tensors ``Pi05ForActionPrediction.sample_actions``
+consumes.
+
+**The defining π0.5 difference:** the state is not projected by a ``state_proj``
+layer. It is normalized to ``[-1, 1]``, discretized into ``state_num_bins`` bins,
+and serialized into the language prompt::
+
+    "Task: <instruction>, State: <b0> <b1> ... <bN>;\nAction: "
+
+so ``sample_actions`` receives no state tensor at all.
+
+**Normalization must precede discretization.** The discretizer bins over
+``[-1, 1]`` and assumes the state is already in that range. Reversed, every bin
+index is wrong and nothing raises.
+
+Reference:
+  - OpenPI: openpi/src/openpi/shared/image_tools.py (resize_with_pad)
+  - OpenPI: openpi/src/openpi/models/pi0_config.py (PaliGemmaTokenizer.tokenize)
+  - LeRobot: lerobot/src/lerobot/policies/pi05/processor_pi05.py
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+import torch
+import torch.nn.functional as F
+from PIL import Image
+from vllm.logger import init_logger
+
+from vllm_omni.diffusion.models.pi05.config import resolve_excluded_action_indices
+from vllm_omni.diffusion.models.pi05.modeling_pi05 import (
+    DEFAULT_IMAGE_RESOLUTION,
+    DEFAULT_MAX_TOKEN_LEN,
+    DEFAULT_STATE_NUM_BINS,
+)
+
+logger = init_logger(__name__)
+
+# LeRobot NormalizerProcessorStep.eps.
+NORM_EPS = 1e-8
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Image preprocessing (identical to π0 — SigLIP is unchanged in π0.5)
+# ──────────────────────────────────────────────────────────────────────
+def resize_with_pad(
+    images: torch.Tensor,
+    target_height: int,
+    target_width: int,
+    mode: str = "bilinear",
+) -> torch.Tensor:
+    """Resize ``(B, C, H, W)`` images to the target shape, preserving aspect
+    ratio with -1 padding on the short side.
+
+    Matches openpi ``image_tools.resize_with_pad_torch`` — the clamp to
+    [-1, 1] is what lets the padded region blend with SigLIP-normalized
+    pixels without adding signal at the boundary.
+    """
+    if images.ndim != 4:
+        raise ValueError(f"Expected 4-D (B,C,H,W), got {images.ndim}-D")
+    _, _, cur_h, cur_w = images.shape
+    ratio = max(cur_w / target_width, cur_h / target_height)
+    rh, rw = int(cur_h / ratio), int(cur_w / ratio)
+    align_corners = False if mode == "bilinear" else None
+    resized = F.interpolate(images, size=(rh, rw), mode=mode, align_corners=align_corners)
+    resized = resized.clamp(-1.0, 1.0)
+    ph, rem_h = divmod(target_height - rh, 2)
+    pw, rem_w = divmod(target_width - rw, 2)
+    return F.pad(resized, (pw, pw + rem_w, ph, ph + rem_h), value=-1.0)
+
+
+def pil_image_to_tensor(image: Image.Image) -> torch.Tensor:
+    """PIL → ``(1, C, H, W)`` float32 in ``[-1, 1]`` (SigLIP normalization)."""
+    if image.mode != "RGB":
+        image = image.convert("RGB")
+    arr = np.array(image, dtype=np.float32) / 255.0 * 2.0 - 1.0
+    return torch.from_numpy(arr).permute(2, 0, 1).unsqueeze(0)
+
+
+class Pi05ImageProcessor:
+    """Minimal image preprocessor: image → normalized + padded ``[-1,1]`` tensor."""
+
+    def __init__(self, image_size: int = DEFAULT_IMAGE_RESOLUTION[0]):
+        self.image_size = image_size
+
+    def preprocess_single(self, image: Any) -> torch.Tensor:
+        """Convert one LeRobot-domain image to a normalized model tensor.
+
+        PIL and uint8 inputs have domain ``[0, 255]``. Floating ndarray/tensor
+        inputs must be finite and in ``[0, 1]``. Values are converted
+        deterministically to ``[-1, 1]``; the pixel content is never used to
+        guess its input domain.
+        """
+        t = self._to_tensor(image)
+        if t.shape[2] != self.image_size or t.shape[3] != self.image_size:
+            t = resize_with_pad(t, self.image_size, self.image_size)
+        return t
+
+    def _to_tensor(self, image: Any) -> torch.Tensor:
+        if isinstance(image, Image.Image):
+            return pil_image_to_tensor(image)
+        if isinstance(image, np.ndarray):
+            if image.ndim != 3 or image.shape[-1] != 3:
+                raise ValueError(f"Expected an HWC ndarray with 3 channels, got shape {image.shape}.")
+            t = torch.from_numpy(np.ascontiguousarray(image)).permute(2, 0, 1).unsqueeze(0)
+        elif isinstance(image, torch.Tensor):
+            t = image.unsqueeze(0) if image.ndim == 3 else image
+            if t.ndim != 4 or t.shape[0] != 1 or t.shape[1] != 3:
+                raise ValueError(f"Expected a CHW tensor (optionally batched once), got shape {tuple(t.shape)}.")
+        else:
+            raise TypeError(f"Unsupported image type for π0.5 preprocessing: {type(image)}")
+
+        if t.dtype == torch.uint8:
+            return t.to(dtype=torch.float32) / 255.0 * 2.0 - 1.0
+        if not t.is_floating_point():
+            raise TypeError(f"π0.5 images must use uint8 or floating dtype, got {t.dtype}.")
+        if not torch.isfinite(t).all():
+            raise ValueError("Floating π0.5 image contains NaN or Inf.")
+        low, high = float(t.amin()), float(t.amax())
+        if low < 0.0 or high > 1.0:
+            raise ValueError(f"Floating π0.5 images must be in [0, 1]; observed min={low}, max={high}.")
+        return t.to(dtype=torch.float32) * 2.0 - 1.0
+
+    def make_empty_image(self) -> torch.Tensor:
+        """Fill tensor for an unused camera slot — pure -1, matches OpenPI/LeRobot."""
+        return torch.full((1, 3, self.image_size, self.image_size), -1.0)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Normalization (LeRobot NormalizerProcessorStep)
+# ──────────────────────────────────────────────────────────────────────
+@dataclass(frozen=True)
+class NormStats:
+    """The affine map a checkpoint's statistics define.
+
+    ``mean_std`` carries mean and std; the two range modes carry the lower and
+    upper bound (``min``/``max``, or the ``q01``/``q99`` quantiles π0.5 ships).
+    """
+
+    mode: str
+    lower: torch.Tensor
+    upper: torch.Tensor
+
+
+def build_norm_stats(norm_stats: dict | None, key: str) -> NormStats | None:
+    """Read ``norm_stats[key]`` into tensors, or ``None`` when it carries none.
+
+    The mode comes from the entry. A LeRobot state_dict ships mean, std, min,
+    max, q01 and q99 at once, so the statistic names present cannot select it.
+    Missing modes default to quantile, which is what LeRobot defaults π0.5's
+    STATE and ACTION to (π0 defaults to mean_std).
+    """
+    entry = (norm_stats or {}).get(key)
+    if not entry:
+        return None
+
+    mode = str(entry.get("mode", "quantile")).lower()
+    if mode == "mean_std":
+        names = ("mean", "std")
+    elif mode == "min_max":
+        names = ("min", "max")
+    elif mode == "quantile":
+        mode, names = "min_max", ("q01", "q99")
+    else:
+        raise ValueError(f"Unsupported normalization mode for {key!r}: {mode!r}.")
+
+    bounds = [entry.get(name) for name in names]
+    if any(bound is None for bound in bounds):
+        raise ValueError(f"Normalization mode {mode!r} for {key!r} requires {names[0]!r} and {names[1]!r}.")
+    lower, upper = (torch.as_tensor(bound, dtype=torch.float32) for bound in bounds)
+    return NormStats(mode=mode, lower=lower, upper=upper)
+
+
+def apply_norm(x: torch.Tensor, stats: NormStats | None, *, inverse: bool = False) -> torch.Tensor:
+    """Map raw units to the model's normalized space, or back with ``inverse``.
+
+    Actions are padded to ``max_action_dim`` while the statistics cover only the
+    real width, so the tail passes through untouched. The eps rules are
+    LeRobot's: ``mean_std`` always divides by ``std + eps``, and the range modes
+    substitute ``eps`` only for an exactly zero range.
+    """
+    if stats is None:
+        return x
+    lower = stats.lower.to(device=x.device, dtype=x.dtype)
+    upper = stats.upper.to(device=x.device, dtype=x.dtype)
+    valid = lower.shape[0]
+    head = x[..., :valid]
+
+    if stats.mode == "mean_std":
+        head = head * upper + lower if inverse else (head - lower) / (upper + NORM_EPS)
+    else:
+        span = upper - lower
+        span = torch.where(span == 0, NORM_EPS, span)
+        head = (head + 1.0) * 0.5 * span + lower if inverse else 2.0 * (head - lower) / span - 1.0
+
+    if valid == x.shape[-1]:
+        return head
+    return torch.cat([head, x[..., valid:]], dim=-1)
+
+
+# ──────────────────────────────────────────────────────────────────────
+# State: normalize → discretize → prompt  (π0.5's defining path)
+# ──────────────────────────────────────────────────────────────────────
+def _pad_or_truncate(raw_state: Any, width: int) -> np.ndarray:
+    """Zero-pad / truncate a vector to ``(width,)`` float32."""
+    if raw_state is None:
+        return np.zeros((width,), dtype=np.float32)
+    if isinstance(raw_state, torch.Tensor):
+        raw_state = raw_state.detach().cpu().numpy()
+    state = np.asarray(raw_state, dtype=np.float32).reshape(-1)
+    if state.shape[0] < width:
+        state = np.pad(state, (0, width - state.shape[0]))
+    elif state.shape[0] > width:
+        state = state[:width]
+    return state.astype(np.float32)
+
+
+def as_state_vector(raw_state: Any, state_dim: int) -> np.ndarray:
+    """Coerce a request's raw state to ``(state_dim,)`` float32, or raise.
+
+    LeRobot's ``Pi05PrepareStateTokenizerProcessorStep`` discretizes whatever
+    width it is handed and never pads to ``max_state_dim``, so zero-filling a
+    7-dim state up to 32 would append 25 state tokens the checkpoint never saw
+    in training.
+    """
+    if raw_state is None:
+        raise ValueError("π0.5 requires a state; there is no default to fall back on.")
+    if isinstance(raw_state, torch.Tensor):
+        raw_state = raw_state.detach().cpu().numpy()
+    state = np.asarray(raw_state, dtype=np.float32)
+    if state.ndim == 2 and state.shape[0] == 1:
+        state = state[0]
+    if state.ndim != 1:
+        raise ValueError(f"π0.5 state must be shaped (D,) or (1, D); got {tuple(state.shape)}.")
+    if not np.isfinite(state).all():
+        raise ValueError("π0.5 state contains NaN or Inf.")
+    if state.shape[0] != state_dim:
+        raise ValueError(
+            f"π0.5 state has {state.shape[0]} dimension(s), but the checkpoint declares "
+            f"{state_dim}. The state is serialized into the prompt at its real width, so "
+            "padding or truncating it would change the tokens the model sees."
+        )
+    return state
+
+
+def discretize_state(state: np.ndarray, *, num_bins: int = DEFAULT_STATE_NUM_BINS) -> np.ndarray:
+    """Discretize a ``[-1, 1]`` state into ``num_bins`` integer bins.
+
+    Byte-for-byte LeRobot's ``processor_pi05.py``::
+
+        np.digitize(state_np, bins=np.linspace(-1, 1, 256 + 1)[:-1]) - 1
+
+    A state below ``-1`` lands in bin ``-1``, and that negative bin is part of
+    the contract: the checkpoint was trained with ``" -1"`` in the state prompt
+    for those dimensions. Clipping it to ``0`` changes the tokens the model
+    sees, so this must not clip.
+
+    ``bins`` stays float64, matching LeRobot's default ``linspace`` dtype, so
+    boundary values fall on the same side.
+
+    **Assumes the state is already normalized** — see the module docstring.
+    """
+    bins = np.linspace(-1.0, 1.0, num_bins + 1)[:-1]
+    return (np.digitize(np.asarray(state, dtype=np.float32), bins=bins) - 1).astype(np.int64)
+
+
+def build_pi05_prompt(
+    *,
+    task: str,
+    normalized_state: np.ndarray,
+    state_num_bins: int = DEFAULT_STATE_NUM_BINS,
+) -> str:
+    """Build the π0.5 prompt: instruction + serialized discretized state.
+
+    Matches LeRobot's ``Pi05PrepareStateTokenizerProcessorStep``, including the
+    task cleanup (``strip``, ``_`` → space, newline → space), the exact template
+    and the state values it serializes. The template already ends in a newline,
+    so — unlike π0 — there is no separate newline-appending step.
+
+    ``normalized_state`` comes from ``Pi05ForActionPrediction._normalize_state``.
+    """
+    cleaned_task = (task or "").strip().replace("_", " ").replace("\n", " ")
+    bins = discretize_state(normalized_state, num_bins=state_num_bins)
+    state_str = " ".join(str(int(x)) for x in bins.tolist())
+    return f"Task: {cleaned_task}, State: {state_str};\nAction: "
+
+
+def tokenize_prompt(tokenizer, text: str, max_token_len: int = DEFAULT_MAX_TOKEN_LEN):
+    """Return ``(input_ids, attention_mask)`` lists, length exactly ``max_token_len``.
+
+    ``padding="max_length"`` is what makes the prefix a constant shape: the text
+    segment is always ``max_token_len`` tokens regardless of the instruction, so
+    only ``attention_mask.sum()`` varies per request.
+    """
+    enc = tokenizer(
+        text,
+        padding="max_length",
+        max_length=max_token_len,
+        truncation=True,
+        add_special_tokens=True,
+        return_tensors=None,
+    )
+    return list(enc["input_ids"]), list(enc["attention_mask"])
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Relative actions
+# ──────────────────────────────────────────────────────────────────────
+class Pi05RelativeActions:
+    """The relative/absolute action transform, as a single paired object.
+
+    LeRobot builds one ``RelativeActionsProcessorStep`` and hands *the same
+    instance* to ``AbsoluteActionsProcessorStep``; the two directions must
+    agree on ``enabled`` and on which dimensions are excluded, so they are one
+    object here too.
+
+    **Deviation from LeRobot, on purpose.** LeRobot's step keeps the reference
+    state on ``self`` between the pre- and post-pass. That is safe for a
+    single-threaded training loop and unsafe for a server: two in-flight
+    requests would share one reference state and silently corrupt each other's
+    actions. Here the state is passed explicitly to :meth:`to_absolute`, so the
+    object stays immutable after construction and is safe to share across
+    requests.
+
+    Transform (LeRobot / OpenPI): ``relative = action - state`` on the way in,
+    ``absolute = relative + state`` on the way out, applied only to the
+    dimensions *not* named in ``exclude_joints``. Gripper open/close is an
+    absolute command, which is why it is excluded by default.
+    """
+
+    def __init__(
+        self,
+        *,
+        enabled: bool,
+        exclude_joints: list[str] | None = None,
+        action_names: list[str] | None = None,
+        max_action_dim: int = 32,
+    ):
+        self.enabled = bool(enabled)
+        self.exclude_joints = list(exclude_joints or [])
+        self.action_names = list(action_names) if action_names else None
+        self.max_action_dim = int(max_action_dim)
+
+        # Boolean mask over action dims: True = this dim is relative to state.
+        mask = np.ones((self.max_action_dim,), dtype=bool)
+        if self.enabled:
+            for idx in resolve_excluded_action_indices(self.exclude_joints, self.action_names):
+                if 0 <= idx < self.max_action_dim:
+                    mask[idx] = False
+            # Padding beyond the real action dimensions carries no signal;
+            # leaving it "relative" would add state noise into dead channels.
+            if self.action_names:
+                mask[len(self.action_names) :] = False
+        else:
+            mask[:] = False
+        self.relative_mask = mask
+
+    @property
+    def num_relative_dims(self) -> int:
+        return int(self.relative_mask.sum())
+
+    def _state_row(self, state: Any, device, dtype) -> torch.Tensor:
+        """Raw state → ``(B, max_action_dim)`` aligned with the action dims.
+
+        Accepts one state for the whole batch (``(D,)``, the serving path,
+        where the pipeline runs B=1) or one state per sample (``(B, D)``).
+        LeRobot caches the batched state and shifts each sample by its own row,
+        so the per-sample form has to be honoured: ``_pad_or_truncate``
+        flattens, which would silently reduce ``(B, D)`` to sample 0's state and
+        apply it to every sample — wrong answers, no error.
+        """
+        if isinstance(state, torch.Tensor):
+            state = state.detach().cpu().numpy()
+        arr = np.asarray(0.0 if state is None else state, dtype=np.float32)
+        if arr.ndim > 2:
+            raise ValueError(f"Expected state shaped (D,) or (B, D), got {tuple(arr.shape)}")
+        rows = arr if arr.ndim == 2 else arr[None, :]
+        padded = np.stack([_pad_or_truncate(row, self.max_action_dim) for row in rows])
+        return torch.as_tensor(padded, device=device, dtype=dtype)
+
+    def to_relative(self, actions: torch.Tensor, state: Any) -> torch.Tensor:
+        """``absolute → relative``. Input side (step 3).
+
+        Not used on the inference path — there are no input actions to convert
+        at serving time — but it is what the transform *means*, and the parity
+        test exercises it as the inverse of :meth:`to_absolute`.
+        """
+        if not self.enabled:
+            return actions
+        return self._shift(actions, state, sign=-1.0)
+
+    def to_absolute(self, actions: torch.Tensor, state: Any) -> torch.Tensor:
+        """``relative → absolute``. Output side (step 2 of the post-pipeline).
+
+        ``state`` must be the **raw** state — the same one the model was given
+        before normalization — because relative actions live in raw action space.
+        """
+        if not self.enabled:
+            return actions
+        return self._shift(actions, state, sign=+1.0)
+
+    def _shift(self, actions: torch.Tensor, state: Any, *, sign: float) -> torch.Tensor:
+        if actions.ndim != 3:
+            raise ValueError(f"Expected actions shaped (B, horizon, action_dim), got {tuple(actions.shape)}")
+        action_dim = actions.shape[-1]
+        if action_dim != self.max_action_dim:
+            raise ValueError(
+                f"Action dim {action_dim} does not match max_action_dim={self.max_action_dim}; "
+                "the relative mask would be misaligned."
+            )
+        state_row = self._state_row(state, actions.device, actions.dtype)  # (1, D)
+        mask = torch.as_tensor(self.relative_mask, device=actions.device)
+        delta = torch.where(mask, state_row, torch.zeros_like(state_row))
+        # Broadcast over the action horizon: every step of the chunk is
+        # expressed relative to the same current state.
+        return actions + sign * delta[:, None, :]
+
+
+# ──────────────────────────────────────────────────────────────────────
+# Model input assembly
+# ──────────────────────────────────────────────────────────────────────
+def _extract_images(robot_obs: dict, config) -> dict[str, Any]:
+    """Pull a ``{feature_key: image}`` map out of a raw robot obs.
+
+    This is functional step 1 (``rename_observations``): keys are translated
+    through ``config.image_key_map`` so serving wire names map onto the
+    checkpoint's ``input_features`` identities.
+    """
+    images = robot_obs.get("images")
+    if not isinstance(images, dict):
+        images = {k: v for k, v in robot_obs.items() if _is_image_like(v)}
+    key_map = config.image_key_map or {}
+    return {key_map.get(k, k): v for k, v in images.items() if _is_image_like(v)}
+
+
+def _is_image_like(value: Any) -> bool:
+    if isinstance(value, (Image.Image, torch.Tensor)):
+        return True
+    if isinstance(value, np.ndarray):
+        return value.ndim >= 3
+    if isinstance(value, (list, tuple)):
+        try:
+            return np.asarray(value).ndim >= 3
+        except Exception:  # noqa: BLE001
+            return False
+    return False
+
+
+def _assemble_model_inputs(robot_obs: dict, config, tokenizer, device: torch.device, state_norm: NormStats | None):
+    """Convert a raw robot observation into ``sample_actions`` inputs.
+
+    Returns ``(images, image_masks, lang_tokens, lang_masks)`` — note there is
+    **no state tensor**: π0.5 carries the state inside ``lang_tokens``.
+
+    Camera slots follow ``config.image_feature_keys`` order. A missing key keeps
+    its semantic slot and receives an empty image with a false mask. The output
+    always contains exactly ``max_cameras`` slots for the deployed model.
+    """
+    image_size = int(config.image_resolution[0])
+    img_proc = Pi05ImageProcessor(image_size=image_size)
+    max_cameras = config.max_cameras
+
+    feature_keys = config.image_feature_keys or []
+    obs_images = _extract_images(robot_obs, config)
+    if not feature_keys:
+        # No declared camera order — fall back to whatever the obs provides,
+        # preserving insertion order.
+        feature_keys = list(obs_images.keys())[:max_cameras]
+
+    camera_keys = feature_keys[:max_cameras]
+    if all(obs_images.get(key) is None for key in camera_keys):
+        raise ValueError("π0.5 observation must provide at least one configured camera image.")
+    if not config.image_feature_keys and len(obs_images) > max_cameras:
+        raise ValueError(
+            f"π0.5 observation provides {len(obs_images)} cameras, which exceeds max_cameras={max_cameras}."
+        )
+
+    images: list[torch.Tensor] = []
+    image_masks: list[torch.Tensor] = []
+    for key in camera_keys:
+        image = obs_images.get(key)
+        if image is None:
+            tensor = img_proc.make_empty_image().to(device=device)
+            mask = False
+        else:
+            tensor = img_proc.preprocess_single(image).to(device=device)
+            mask = True
+        images.append(tensor)
+        image_masks.append(torch.tensor([mask], dtype=torch.bool, device=device))
+
+    # A checkpoint may declare fewer named slots than the serving graph.
+    while len(images) < max_cameras:
+        images.append(img_proc.make_empty_image().to(device=device))
+        image_masks.append(torch.tensor([False], dtype=torch.bool, device=device))
+
+    # Normalize and serialize the state into the tokenized prompt.
+    raw_state = as_state_vector(robot_obs.get("state"), config.state_dim)
+    normalized_state = apply_norm(torch.from_numpy(raw_state), state_norm).numpy()
+    prompt = build_pi05_prompt(
+        task=robot_obs.get("prompt", "") or "",
+        normalized_state=normalized_state,
+        state_num_bins=config.state_num_bins,
+    )
+    ids, attn = tokenize_prompt(tokenizer, prompt, config.tokenizer_max_length)
+    lang_tokens = torch.tensor([ids], dtype=torch.long, device=device)
+    lang_masks = torch.tensor([attn], dtype=torch.bool, device=device)
+
+    return images, image_masks, lang_tokens, lang_masks
+
+
+# ──────────────────────────────────────────────────────────────────────
+# The interface the pipeline uses
+# ──────────────────────────────────────────────────────────────────────
+class Pi05Processor:
+    """Everything between the OpenPI wire and the model.
+
+    Owns the normalization statistics and the relative-action transform, so the
+    pipeline holds no preprocessing state of its own.
+    """
+
+    def __init__(self, config, tokenizer, device: torch.device):
+        self.config = config
+        self.tokenizer = tokenizer
+        self.device = device
+        self._state_norm = build_norm_stats(config.norm_stats, "state")
+        self._action_norm = build_norm_stats(config.norm_stats, "action")
+        self.relative_actions = Pi05RelativeActions(
+            enabled=config.use_relative_actions,
+            exclude_joints=config.relative_exclude_joints,
+            action_names=config.action_feature_names,
+            max_action_dim=config.max_action_dim,
+        )
+        if self._action_norm is None:
+            logger.info("π0.5: no action normalization stats; returned actions stay in normalized space.")
+        if self.relative_actions.enabled:
+            logger.info(
+                "π0.5: relative actions enabled — %d of %d action dims are state-relative (excluded joints: %s).",
+                self.relative_actions.num_relative_dims,
+                config.max_action_dim,
+                config.relative_exclude_joints,
+            )
+
+    def build_model_inputs(self, robot_obs: dict):
+        """Raw observation → ``sample_actions`` inputs.
+
+        No state tensor comes back: π0.5 carries the state inside ``lang_tokens``.
+        """
+        return _assemble_model_inputs(robot_obs, self.config, self.tokenizer, self.device, self._state_norm)
+
+    def build_model_outputs(self, actions: torch.Tensor, robot_obs: dict) -> np.ndarray:
+        """Model output → the action chunk the robot receives.
+
+        ``AbsoluteActionsProcessorStep`` runs after unnormalization, because a
+        relative-action checkpoint's statistics are computed in relative space.
+        The raw state is the one the prompt encoded, before normalization.
+        """
+        actions = apply_norm(actions, self._action_norm, inverse=True)
+        if self.relative_actions.enabled:
+            actions = self.relative_actions.to_absolute(actions, robot_obs.get("state"))
+        return actions.squeeze(0)[..., : self.config.action_dim].float().cpu().numpy()
diff --git a/vllm_omni/diffusion/models/pi05_pipeline_config.py b/vllm_omni/diffusion/models/pi05_pipeline_config.py
new file mode 100644
index 00000000000..27035d509ef
--- /dev/null
+++ b/vllm_omni/diffusion/models/pi05_pipeline_config.py
@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Lightweight pipeline topology for π0.5."""
+
+from vllm_omni.config.stage_config import (
+    PipelineConfig,
+    StageExecutionType,
+    StagePipelineConfig,
+)
+
+# π0.5 is one diffusion stage (robot observation -> action chunk via flow
+# matching). It is registered in ``OMNI_PIPELINES`` because π0.5 is online-served
+# via ``vllm serve --deploy-config pi05.yaml``. Keep this topology outside the
+# ``pi05`` package: importing a package submodule executes ``pi05.__init__``,
+# which imports the runtime pipeline and ``diffusion.data``.
+PI05_PIPELINE = PipelineConfig(
+    model_type="pi05",
+    model_arch="Pi05Pipeline",
+    stages=(
+        StagePipelineConfig(
+            stage_id=0,
+            model_stage="diffusion",
+            execution_type=StageExecutionType.DIFFUSION,
+            input_sources=(),
+            final_output=True,
+            final_output_type="action",
+            model_arch="Pi05Pipeline",
+        ),
+    ),
+)
diff --git a/vllm_omni/diffusion/registry.py b/vllm_omni/diffusion/registry.py
index 26b052a3ab2..f94952b1dcf 100644
--- a/vllm_omni/diffusion/registry.py
+++ b/vllm_omni/diffusion/registry.py
@@ -206,6 +206,11 @@
         "pipeline_pi0",
         "Pi0Pipeline",
     ),
+    "Pi05Pipeline": (
+        "pi05",
+        "pipeline_pi05",
+        "Pi05Pipeline",
+    ),
     "LongCatImageEditPipeline": (
         "longcat_image",
         "pipeline_longcat_image_edit",
@@ -382,6 +387,7 @@
     # to it; list it here so a stray cache_backend override disables gracefully
     # instead of erroring.
     "Pi0Pipeline",
+    "Pi05Pipeline",
     "LingBotWorldCausalDMDPipeline",
 }
 
@@ -586,6 +592,7 @@ def _apply_sequence_parallel_if_enabled(model, od_config: OmniDiffusionConfig) -
     "MingImagePipeline": "get_ming_image_post_process_func",
     "InternVLAA1Pipeline": "get_internvla_a1_post_process_func",
     "Pi0Pipeline": "get_pi0_post_process_func",
+    "Pi05Pipeline": "get_pi05_post_process_func",
     "LongCatImageEditPipeline": "get_longcat_image_post_process_func",
     "StableDiffusion3Pipeline": "get_sd3_image_post_process_func",
     "FluxKontextPipeline": "get_flux_kontext_post_process_func",
diff --git a/vllm_omni/entrypoints/openpi/serving.py b/vllm_omni/entrypoints/openpi/serving.py
index 11fde2bf8c1..450cfbb7936 100644
--- a/vllm_omni/entrypoints/openpi/serving.py
+++ b/vllm_omni/entrypoints/openpi/serving.py
@@ -194,6 +194,9 @@ def _build_request(self, obs: dict, *, session_id: str, reset: bool) -> Any:
         # (e.g. a policy deploy yaml's ``extra_args``) and layer the OpenPI
         # protocol fields on top.
         seed = obs.pop("seed", None)
+        # Nested so engine knobs cannot collide with robot-defined obs keys.
+        sampling = obs.get("sampling_params") or {}
+        robot_obs = {key: value for key, value in obs.items() if key != "sampling_params"}
         sampling_params = OmniDiffusionSamplingParams()
         for default_params in get_default_sampling_params_list(self.engine_client):
             if isinstance(default_params, OmniDiffusionSamplingParams):
@@ -205,15 +208,16 @@ def _build_request(self, obs: dict, *, session_id: str, reset: bool) -> Any:
             {
                 "reset": reset,
                 "session_id": session_id,
-                "robot_obs": obs,
+                "robot_obs": robot_obs,
             }
         )
 
         prompt = obs.get("prompt", "")
-        sampling_params = OmniDiffusionSamplingParams(
-            seed=int(seed) if seed is not None else None,
-            extra_args=extra_args,
-        )
+        if seed is not None:
+            sampling_params.seed = int(seed)
+        if "num_inference_steps" in sampling:
+            sampling_params.num_inference_steps = sampling["num_inference_steps"]
+        sampling_params.extra_args = extra_args
         return OmniDiffusionRequest(
             prompt=prompt,
             sampling_params=sampling_params,

From 5b22f5562f630ba571cc70d99f104ff01ba87f49 Mon Sep 17 00:00:00 2001
From: Tiago de Souza Fernandes <43066400+Tiagosf00@users.noreply.github.com>
Date: Thu, 17 Sep 2026 20:26:34 +0800
Subject: [PATCH 067/105] fix(minicpmo45): deadline-align native duplex silence
 continuation (#7059)

Signed-off-by: Tiagosf00 <tiagotsf2000@gmail.com>
---
 tests/engine/duplex/test_deadline_pacing.py   |  88 +++++
 .../duplex/test_deadline_pacing_scheduler.py  | 370 ++++++++++++++++++
 tests/engine/duplex/test_session_manager.py   |   4 +
 vllm_omni/engine/duplex/plugin.py             |   5 +
 .../engine/duplex/session/append_task.py      |   6 +-
 .../engine/duplex/session/model_channel.py    |   9 +
 vllm_omni/engine/duplex/session/runner.py     | 108 ++++-
 .../models/minicpmo_4_5/duplex/session.py     |   7 +
 8 files changed, 580 insertions(+), 17 deletions(-)
 create mode 100644 tests/engine/duplex/test_deadline_pacing.py
 create mode 100644 tests/engine/duplex/test_deadline_pacing_scheduler.py

diff --git a/tests/engine/duplex/test_deadline_pacing.py b/tests/engine/duplex/test_deadline_pacing.py
new file mode 100644
index 00000000000..2b1bf09d6f8
--- /dev/null
+++ b/tests/engine/duplex/test_deadline_pacing.py
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Deterministic unit tests for deadline-aligned silence continuation.
+
+The engine-resident duplex scheduler in
+``vllm_omni/engine/duplex/session/runner.py`` aligns each silence
+continuation to ``submission_time_N + chunk_period`` and sleeps only the
+remaining budget. These tests cover the pure deadline arithmetic and the
+per-session reset semantics of the shared ``DuplexModelSessionState``
+contract.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from vllm_omni.engine.duplex.session.runner import (
+    compute_silence_continuation_deadline,
+)
+from vllm_omni.model_executor.models.minicpmo_4_5.duplex.session import (
+    MiniCPMO45ServingSessionState,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+@pytest.mark.parametrize(
+    ("chunk_period_s", "now", "last_submit", "current_deadline", "delay_s", "next_silence_deadline"),
+    [
+        # First continuation anchors to the last real submission: unit N was
+        # submitted at t=1.0, audio N produced at 1.4 -> 0.6 s of sleep left.
+        (1.0, 1.4, 1.0, None, 0.6, 3.0),
+        # Only the remaining budget is slept (audio produced at 1.7).
+        (1.0, 1.7, 1.0, None, 0.3, 3.0),
+        # Overdue deadline: no sleep; the chain still advances by the period.
+        (1.0, 2.5, 1.0, None, 0.0, 3.0),
+        # No submission yet (None): the first continuation anchors to now.
+        (1.0, 0.4, None, None, 1.0, 2.4),
+        # Deadlines advance from the current deadline, not from now, so pipeline
+        # processing time does not accumulate as timer drift.
+        (1.0, 4.2, 3.0, 5.0, 0.8, 6.0),
+        # Two consecutive units that overrun their deadline by 0.2 s keep the
+        # 1 s cadence: no sleep, and the chain advances one period each.
+        (1.0, 2.2, 1.0, None, 0.0, 3.0),
+        (1.0, 3.2, 2.0, 3.0, 0.0, 4.0),
+        # A short overshoot (within one period of the current deadline) still
+        # chases the stale deadline: immediate submit, chain advances.
+        (1.0, 2.5, 1.0, 2.0, 0.0, 3.0),
+        # A long stall (more than one period past the current deadline) submits
+        # one continuation immediately and restarts from that submission.
+        (1.0, 5.0, 1.0, 2.0, 0.0, 6.0),
+        # The same recovery applies to the first continuation after a stall.
+        (1.0, 5.0, 1.0, None, 0.0, 6.0),
+        # Zero chunk period (guarded upstream): total, no sleep.
+        (0.0, 10.0, None, None, 0.0, 10.0),
+    ],
+)
+def test_compute_silence_continuation_deadline(
+    chunk_period_s: float,
+    now: float,
+    last_submit: float | None,
+    current_deadline: float | None,
+    delay_s: float,
+    next_silence_deadline: float,
+) -> None:
+    delay, next_dl = compute_silence_continuation_deadline(
+        chunk_period_s=chunk_period_s,
+        now=now,
+        last_submit=last_submit,
+        current_deadline=current_deadline,
+    )
+    assert delay == pytest.approx(delay_s)
+    assert next_dl == pytest.approx(next_silence_deadline)
+
+
+class TestSilenceDeadlineSessionState:
+    def test_clear_continuation_resets_the_deadline_chain(self) -> None:
+        # The native-duplex session state feeds the shared runner, so it must
+        # start with an unset chain and drop it at turn boundaries.
+        state = MiniCPMO45ServingSessionState()
+        assert state.last_native_submit_monotonic is None
+        assert state.silence_deadline_monotonic is None
+        state.last_native_submit_monotonic = 5.0
+        state.silence_deadline_monotonic = 6.0
+        state.clear_continuation()
+        assert state.last_native_submit_monotonic is None
+        assert state.silence_deadline_monotonic is None
diff --git a/tests/engine/duplex/test_deadline_pacing_scheduler.py b/tests/engine/duplex/test_deadline_pacing_scheduler.py
new file mode 100644
index 00000000000..451af0bfd17
--- /dev/null
+++ b/tests/engine/duplex/test_deadline_pacing_scheduler.py
@@ -0,0 +1,370 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Focused scheduler tests for deadline-aligned silence continuation.
+
+These tests exercise the production ``_schedule_silence_continuation`` path
+(and the append acceptance callback it installs) rather than copying the
+scheduling arithmetic. The monotonic clock is a fake so the deadline math is
+deterministic, and ``asyncio.sleep`` is simulated by advancing that clock.
+Append completion is controlled by gating the stage port's ``submit``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable
+from typing import Any
+
+import pytest
+
+import vllm_omni.engine.duplex.session.model_channel as model_channel_module
+import vllm_omni.engine.duplex.session.runner as runner_module
+from tests.engine.duplex.test_session_runner import (
+    Harness,
+    append_audio,
+    close_harness,
+    open_harness,
+    tts_output,
+)
+from vllm_omni.engine.duplex.contracts import DuplexStageSubmission
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+CHUNK_PERIOD_S = 1.0
+
+
+class FakeClock:
+    """A monotonic clock whose value the test controls directly."""
+
+    def __init__(self, start: float = 0.0) -> None:
+        self.value = start
+
+    def __call__(self) -> float:
+        return self.value
+
+
+async def _active_response_harness() -> Harness:
+    """Open a harness and drive a TTS segment so a response is active."""
+    h = await open_harness()
+    await h.run(append_audio())
+    request_id = h.stage0_request_id()
+    await h.deliver_and_settle(tts_output(request_id, samples=24000, text="hello"))
+    assert h.session.active_response_id is not None
+    return h
+
+
+def _continuation_kwargs(h: Harness) -> dict[str, object]:
+    """The scheduler arguments the model channel would pass for this session."""
+    return {
+        "request_id": h.session.active_request_id,
+        "owner_id": f"response:{h.session.active_response_id}",
+        "response_id": h.session.active_response_id,
+        "response_owned": True,
+        "expected_epoch": h.session.epoch,
+        "expected_model_turn_id": h.session.turn_id,
+    }
+
+
+def _install_fake_clock(
+    monkeypatch: pytest.MonkeyPatch,
+    *,
+    clock: FakeClock,
+    real_sleep: Callable[..., Any],
+) -> list[float]:
+    """Point both modules at the fake clock and simulate ``asyncio.sleep``.
+
+    ``real_sleep`` is the unpatched ``asyncio.sleep`` captured before patching;
+    the simulated sleep advances the fake clock by the requested delay and then
+    yields control so the append task can run. The returned ``stall`` list is
+    added once to the next *positive* sleep so a test can model a wake that
+    happens late (after the planned deadline); zero-duration scheduling yields
+    do not consume it.
+    """
+    monkeypatch.setattr(runner_module.time, "monotonic", clock)
+    monkeypatch.setattr(model_channel_module.time, "monotonic", clock)
+    stall: list[float] = [0.0]
+
+    async def fake_sleep(delay: float) -> None:
+        clock.value += delay
+        if delay > 0:
+            clock.value += stall[0]
+            stall[0] = 0.0
+        await real_sleep(0)
+
+    monkeypatch.setattr(asyncio, "sleep", fake_sleep)
+    return stall
+
+
+@pytest.mark.asyncio
+async def test_normal_cadence_keeps_deadlines_aligned(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Processing time reduces the remaining sleep; consecutive deadlines align.
+
+    Each accepted unit becomes the new anchor (its submission time), and the
+    following continuation advances from the stored deadline rather than
+    resetting to now.
+    """
+    clock = FakeClock(start=100.0)
+    real_sleep = asyncio.sleep
+    _install_fake_clock(monkeypatch, clock=clock, real_sleep=real_sleep)
+    h = await _active_response_harness()
+    try:
+        # Real input accepted at t=100.0; the model processes for 0.4 s.
+        h.runner.model_state.last_native_submit_monotonic = 100.0
+        clock.value = 100.4
+
+        # First continuation: due at 101.0, so only 0.6 s of sleep remains.
+        scheduled = await h.runner._schedule_silence_continuation(
+            h.runner.model.silence_unit_payload(),
+            **_continuation_kwargs(h),
+        )
+        assert scheduled is True
+        first_task = h.runner.tasks.append_tail
+        assert first_task is not None
+        assert await first_task
+        # The accepted unit re-anchored the chain to its own submission time
+        # (101.0) and stored the following deadline (102.0).
+        assert h.runner.model_state.last_native_submit_monotonic == pytest.approx(101.0)
+        assert h.runner.model_state.silence_deadline_monotonic == pytest.approx(102.0)
+
+        # Model produces the continuation's audio; the next unit is planned
+        # from the stored deadline (no drift): the following deadline is 103.0.
+        clock.value = 101.3
+        scheduled = await h.runner._schedule_silence_continuation(
+            h.runner.model.silence_unit_payload(),
+            **_continuation_kwargs(h),
+        )
+        assert scheduled is True
+        second_task = h.runner.tasks.append_tail
+        assert second_task is not None
+        assert await second_task
+        assert h.runner.model_state.silence_deadline_monotonic == pytest.approx(103.0)
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_in_flight_real_append_skips_outdated_silence(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A real append accepted after the silence was planned re-anchors the chain.
+
+    The planned silence queues behind the real append; once the real append
+    completes and re-anchors, ``before_append`` detects the changed anchor
+    (numeric timestamp) and the outdated silence is skipped (no submission,
+    no callback overwrite).
+    """
+    clock = FakeClock(start=200.0)
+    real_sleep = asyncio.sleep
+    _install_fake_clock(monkeypatch, clock=clock, real_sleep=real_sleep)
+    h = await _active_response_harness()
+    state = h.runner.model_state
+    submissions_before = len(h.port.submissions)
+
+    original_submit = h.port.submit
+    entered = asyncio.Event()
+    release = asyncio.Event()
+
+    async def gated_submit(submission: DuplexStageSubmission) -> Any:
+        entered.set()
+        await release.wait()
+        return await original_submit(submission)
+
+    monkeypatch.setattr(h.port, "submit", gated_submit)
+    try:
+        # Existing anchor at t=200.0.
+        state.last_native_submit_monotonic = 200.0
+        state.silence_deadline_monotonic = None
+
+        # The real append starts at t+0.8 and blocks inside the gate.
+        clock.value = 200.8
+        real_append_task = await h.runner._start_append(
+            h.runner.model.silence_unit_payload(),
+            final=False,
+            silence_continuation=False,
+        )
+        await entered.wait()
+        assert not real_append_task.done()
+
+        # At t+1.0 the silence is planned using the existing anchor; its append
+        # task waits behind the real append.
+        clock.value = 201.0
+        scheduled = await h.runner._schedule_silence_continuation(
+            h.runner.model.silence_unit_payload(),
+            **_continuation_kwargs(h),
+        )
+        assert scheduled is True
+        silence_task = h.runner.tasks.append_tail
+        assert silence_task is not None
+        assert not silence_task.done()
+
+        # At t+1.1 the real append is released; both appends finish.
+        clock.value = 201.1
+        release.set()
+        assert await real_append_task
+        assert await silence_task
+
+        # Exactly one additional submission happened: the real append. The
+        # outdated silence was skipped, so its callback never overwrote the
+        # new anchor (the real append's submission time t+0.8), and the
+        # deadline the real append cleared stays cleared.
+        assert len(h.port.submissions) == submissions_before + 1
+        assert state.last_native_submit_monotonic == pytest.approx(200.8)
+        assert state.silence_deadline_monotonic is None
+
+        # A fresh continuation uses the new anchor. The clock is left at t+1.1:
+        # the scheduler sleeps the remaining 0.7 s (deadline t+1.8), which
+        # verifies re-anchoring controls the wait. Following deadline t+2.8.
+        scheduled = await h.runner._schedule_silence_continuation(
+            h.runner.model.silence_unit_payload(),
+            **_continuation_kwargs(h),
+        )
+        assert scheduled is True
+        fresh_task = h.runner.tasks.append_tail
+        assert fresh_task is not None
+        assert await fresh_task
+        assert state.last_native_submit_monotonic == pytest.approx(201.8)
+        assert state.silence_deadline_monotonic == pytest.approx(202.8)
+    finally:
+        release.set()
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_long_stall_saves_future_deadline_from_actual_submission(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """A submission more than one period past the planned deadline restarts.
+
+    The schedule plans the following deadline at ``planned + period``, but the
+    actual submission happens much later. The accepted continuation must save
+    ``submit_time + period`` so the next unit is not immediately due.
+    """
+    clock = FakeClock(start=300.0)
+    real_sleep = asyncio.sleep
+    stall = _install_fake_clock(monkeypatch, clock=clock, real_sleep=real_sleep)
+    h = await _active_response_harness()
+    state = h.runner.model_state
+    try:
+        # Plan a continuation whose deadline is 1.0 s in the future. The wake
+        # is delayed 2 s past the planned submission (anchor + 3.0 during the
+        # scheduler's sleep), so the append accepts 2 s late.
+        anchor = clock.value
+        state.last_native_submit_monotonic = anchor
+        state.silence_deadline_monotonic = None
+        stall[0] = 2.0
+        scheduled = await h.runner._schedule_silence_continuation(
+            h.runner.model.silence_unit_payload(),
+            **_continuation_kwargs(h),
+        )
+        assert scheduled is True
+        append_task = h.runner.tasks.append_tail
+        assert append_task is not None
+        assert await append_task
+        # anchor + 3.0 > anchor + 2.0 (planned deadline + period) -> save
+        # submit_time + period = anchor + 4.0.
+        assert state.last_native_submit_monotonic == pytest.approx(anchor + 3.0)
+        assert state.silence_deadline_monotonic == pytest.approx(anchor + 4.0)
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_small_wakeup_delay_preserves_planned_deadline(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Ordinary wakeup jitter (within one period) keeps the planned cadence.
+
+    A submission 0.2 s past the planned deadline must not reset the chain: the
+    stored deadline stays at ``planned + period`` so drift does not accumulate.
+    """
+    clock = FakeClock(start=400.0)
+    real_sleep = asyncio.sleep
+    stall = _install_fake_clock(monkeypatch, clock=clock, real_sleep=real_sleep)
+    h = await _active_response_harness()
+    state = h.runner.model_state
+    try:
+        anchor = clock.value
+        state.last_native_submit_monotonic = anchor
+        state.silence_deadline_monotonic = None
+        stall[0] = 0.2
+
+        scheduled = await h.runner._schedule_silence_continuation(
+            h.runner.model.silence_unit_payload(),
+            **_continuation_kwargs(h),
+        )
+        assert scheduled is True
+        append_task = h.runner.tasks.append_tail
+        assert append_task is not None
+        assert await append_task
+
+        # Submitted at anchor + period + 0.2 (within one period): the planned
+        # following deadline is kept.
+        assert state.last_native_submit_monotonic == pytest.approx(anchor + CHUNK_PERIOD_S + 0.2)
+        assert state.silence_deadline_monotonic == pytest.approx(anchor + 2 * CHUNK_PERIOD_S)
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_exact_one_period_late_preserves_planned_deadline(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Exactly one period late is not "more than one period late".
+
+    The strict ``>`` comparison means a submission exactly at the planned
+    following deadline keeps the planned cadence (no extra catch-up unit).
+    """
+    clock = FakeClock(start=500.0)
+    real_sleep = asyncio.sleep
+    stall = _install_fake_clock(monkeypatch, clock=clock, real_sleep=real_sleep)
+    h = await _active_response_harness()
+    state = h.runner.model_state
+    try:
+        anchor = clock.value
+        state.last_native_submit_monotonic = anchor
+        state.silence_deadline_monotonic = None
+        stall[0] = 1.0
+
+        scheduled = await h.runner._schedule_silence_continuation(
+            h.runner.model.silence_unit_payload(),
+            **_continuation_kwargs(h),
+        )
+        assert scheduled is True
+        append_task = h.runner.tasks.append_tail
+        assert append_task is not None
+        assert await append_task
+
+        # Submitted exactly at the planned following deadline: kept.
+        assert state.last_native_submit_monotonic == pytest.approx(anchor + 2 * CHUNK_PERIOD_S)
+        assert state.silence_deadline_monotonic == pytest.approx(anchor + 2 * CHUNK_PERIOD_S)
+    finally:
+        await close_harness(h)
+
+
+@pytest.mark.asyncio
+async def test_failed_append_leaves_timing_unchanged(monkeypatch: pytest.MonkeyPatch) -> None:
+    """A failed append never advances the timing chain."""
+    clock = FakeClock(start=600.0)
+    real_sleep = asyncio.sleep
+    _install_fake_clock(monkeypatch, clock=clock, real_sleep=real_sleep)
+    h = await _active_response_harness()
+    state = h.runner.model_state
+    try:
+        state.last_native_submit_monotonic = 600.0
+        state.silence_deadline_monotonic = 601.0
+        before_anchor = state.last_native_submit_monotonic
+        before_deadline = state.silence_deadline_monotonic
+        h.port.fail_submit = RuntimeError("boom")
+
+        scheduled = await h.runner._schedule_silence_continuation(
+            h.runner.model.silence_unit_payload(),
+            **_continuation_kwargs(h),
+        )
+        assert scheduled is True
+        append_task = h.runner.tasks.append_tail
+        assert append_task is not None
+        # The append fails: its task reports failure, and timing is untouched.
+        assert await append_task is False
+        assert state.last_native_submit_monotonic == before_anchor
+        assert state.silence_deadline_monotonic == before_deadline
+    finally:
+        await close_harness(h)
diff --git a/tests/engine/duplex/test_session_manager.py b/tests/engine/duplex/test_session_manager.py
index 0323f16d8d4..4f1962ee599 100644
--- a/tests/engine/duplex/test_session_manager.py
+++ b/tests/engine/duplex/test_session_manager.py
@@ -120,6 +120,8 @@ def __init__(self) -> None:
         self.continuation_units = 0
         self.pending_silence_task = None
         self.pending_silence_owner_id = None
+        self.last_native_submit_monotonic = None
+        self.silence_deadline_monotonic = None
 
     def retain_committed_audio(self, payload, *, operation_id, reserved_bytes=0) -> None:
         self.committed_audio_payload = payload
@@ -136,6 +138,8 @@ def clear_committed_audio(self) -> int:
     def clear_continuation(self) -> None:
         self.continuation_owner_id = None
         self.continuation_units = 0
+        self.last_native_submit_monotonic = None
+        self.silence_deadline_monotonic = None
 
 
 class FakeDataPlane(DuplexDataPlane):
diff --git a/vllm_omni/engine/duplex/plugin.py b/vllm_omni/engine/duplex/plugin.py
index 130d5204d6a..f9f9be283c6 100644
--- a/vllm_omni/engine/duplex/plugin.py
+++ b/vllm_omni/engine/duplex/plugin.py
@@ -123,6 +123,11 @@ class DuplexModelSessionState(ABC):
     continuation_units: int
     pending_silence_task: asyncio.Task[bool] | None
     pending_silence_owner_id: str | None
+    # Deadline-aligned silence continuation state: the monotonic submission
+    # time of the most recent native input unit and the next silence
+    # continuation deadline. A real (non-silence) input resets the chain.
+    last_native_submit_monotonic: float | None
+    silence_deadline_monotonic: float | None
 
     @abstractmethod
     def retain_committed_audio(
diff --git a/vllm_omni/engine/duplex/session/append_task.py b/vllm_omni/engine/duplex/session/append_task.py
index 724dc7f8224..2bc060d63ec 100644
--- a/vllm_omni/engine/duplex/session/append_task.py
+++ b/vllm_omni/engine/duplex/session/append_task.py
@@ -53,8 +53,11 @@ class AppendAttempt:
     retained_committed_payload: dict[str, object] | None
     #: Response reserved before submission, to be failed if submission does not happen.
     precreated_response_id: str | None
+    #: Commits timing state once the runtime accepts the append (before any
+    #: returned output event can clear the continuation chain).
+    on_append_accepted: Callable[[float], None] | None = None
     #: Last chance to call the append off, checked once the predecessor is done.
-    before_append: Callable[[], bool] | None
+    before_append: Callable[[], bool] | None = None
 
     # ------------------------------------------------------------------ #
     # Compensation                                                       #
@@ -140,6 +143,7 @@ async def _submit(self) -> bool:
                 ),
                 final=self.final,
                 expected_epoch=self.epoch,
+                on_append_accepted=self.on_append_accepted,
             )
             if append_ok:
                 model_state.context_locked = True
diff --git a/vllm_omni/engine/duplex/session/model_channel.py b/vllm_omni/engine/duplex/session/model_channel.py
index 322db7edeaf..13f0f77819f 100644
--- a/vllm_omni/engine/duplex/session/model_channel.py
+++ b/vllm_omni/engine/duplex/session/model_channel.py
@@ -22,6 +22,7 @@
 from __future__ import annotations
 
 import asyncio
+import time
 import uuid
 from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import replace
@@ -146,12 +147,16 @@ async def append_runtime_input(
         operation_id: str | None = None,
         final: bool,
         expected_epoch: int | None = None,
+        on_append_accepted: Callable[[float], None] | None = None,
     ) -> tuple[bool, bool]:
         session = self._ctx.session
         if not session.capabilities.supports_input_append:
             return True, False
         if expected_epoch is not None and session.epoch != expected_epoch:
             return True, False
+        # Anchor the submission time before the RPC; the acceptance callback
+        # commits timing state only if the append actually submitted.
+        submit_time = time.monotonic()
         try:
             result = await self._append_via_data_plane(
                 payload,
@@ -169,6 +174,10 @@ async def append_runtime_input(
             return True, False
         if expected_epoch is not None and session.epoch != expected_epoch:
             return True, False
+        # Commit timing state before returned output events can clear the
+        # silence-continuation chain (e.g. a terminal turn-end).
+        if on_append_accepted is not None:
+            on_append_accepted(submit_time)
         request_id, _ = duplex_data_plane_request_info(result)
         if request_id is not None:
             self._ctx.plugin.data_plane.begin_request(request_id)
diff --git a/vllm_omni/engine/duplex/session/runner.py b/vllm_omni/engine/duplex/session/runner.py
index 0b8af49abfc..ef464a5fa19 100644
--- a/vllm_omni/engine/duplex/session/runner.py
+++ b/vllm_omni/engine/duplex/session/runner.py
@@ -21,6 +21,7 @@
 from __future__ import annotations
 
 import asyncio
+import time
 import uuid
 from collections.abc import Awaitable, Callable, Mapping
 from dataclasses import dataclass, field
@@ -126,6 +127,38 @@ class _Internal:
 _CANCEL_EVENTS = frozenset({"input.cancel", "response.cancel", "barge_in", "output_audio_buffer.clear"})
 
 
+def compute_silence_continuation_deadline(
+    *,
+    chunk_period_s: float,
+    now: float,
+    last_submit: float | None,
+    current_deadline: float | None,
+) -> tuple[float, float]:
+    """Return the silence continuation schedule ``(delay_s, next_silence_deadline)``.
+
+    The first continuation anchors to the latest accepted append's submission
+    time (``last_submit + chunk_period_s``), falling back to ``now`` when no
+    submission exists. Later continuations advance from the current deadline
+    instead of from ``now``, so pipeline processing time does not accumulate
+    as timer drift. When the schedule is more than one period overdue it is
+    stale: one continuation submits immediately and the schedule restarts
+    from ``now`` (``next_silence_deadline = now + chunk_period_s``) instead of
+    firing a burst of catch-ups.
+
+    ``delay_s`` is the wait before this continuation and
+    ``next_silence_deadline`` the deadline for the following one.
+    """
+    if current_deadline is None:
+        base = last_submit if last_submit is not None else now
+        deadline = base + chunk_period_s
+    else:
+        deadline = current_deadline
+    if now - deadline > chunk_period_s:
+        deadline = now
+    delay_s = max(0.0, deadline - now)
+    return delay_s, deadline + chunk_period_s
+
+
 class DuplexSessionRunner:
     """Owns one ``DuplexEngineSession`` on the orchestrator loop (see module docstring)."""
 
@@ -918,12 +951,22 @@ async def _start_append(
         operation_id: str | None = None,
         retained_committed_payload: dict[str, object] | None = None,
         silence_continuation: bool = False,
+        on_append_accepted: Callable[[float], None] | None = None,
         before_append: Callable[[], bool] | None = None,
     ) -> asyncio.Task[bool]:
         session = self.session
         model_state = self.model_state
         if not silence_continuation:
             self._mark_pending_silence_superseded()
+            if on_append_accepted is None:
+                # A real (non-silence) input re-anchors the silence pacing
+                # chain: its submission becomes the anchor and the stored
+                # deadline is cleared until the next continuation sets one.
+                def _reanchor_chain(submit_time: float) -> None:
+                    model_state.last_native_submit_monotonic = submit_time
+                    model_state.silence_deadline_monotonic = None
+
+                on_append_accepted = _reanchor_chain
         append_epoch = session.epoch
         append_turn_id = payload_turn_id(payload)
         if append_turn_id is None:
@@ -949,6 +992,7 @@ async def _start_append(
             operation_id=operation_id,
             retained_committed_payload=retained_committed_payload,
             precreated_response_id=session.active_response_id if precreate_response else None,
+            on_append_accepted=on_append_accepted,
             before_append=before_append,
         )
 
@@ -1032,29 +1076,60 @@ async def _schedule_silence_continuation(
         append_tail = self.tasks.append_tail
         if (append_tail is None or append_tail.done()) and self._real_input_waiting():
             return False
-        continuation_delay_s = max(0.0, float(session.capabilities.chunk_period_ms or 1000) / 1000.0)
-        if continuation_delay_s > 0:
-            await asyncio.sleep(continuation_delay_s)
-            if (
-                self.tasks.append_tail is not append_tail
-                or ((append_tail is None or append_tail.done()) and self._real_input_waiting())
-                or self.model.silence_continuation_is_stale(
+        chunk_period_s = max(0.0, float(session.capabilities.chunk_period_ms or 1000) / 1000.0)
+        # Snapshot the anchor after any wait for pending silence. A real append
+        # accepted between the snapshot and this continuation's submission
+        # re-anchors the chain; _still_valid() then skips the stale unit.
+        anchor = model_state.last_native_submit_monotonic
+        # Align the next silence unit to submission_time_N + chunk_period and
+        # sleep only the remaining budget. The deadline is stored by the
+        # acceptance callback when the append actually submits, so skipped or
+        # stale continuations never advance the clock.
+        delay_s, next_silence_deadline = compute_silence_continuation_deadline(
+            chunk_period_s=chunk_period_s,
+            now=time.monotonic(),
+            last_submit=anchor,
+            current_deadline=model_state.silence_deadline_monotonic,
+        )
+        if delay_s > 0:
+            await asyncio.sleep(delay_s)
+        if (
+            self.tasks.append_tail is not append_tail
+            or ((append_tail is None or append_tail.done()) and self._real_input_waiting())
+            or self.model.silence_continuation_is_stale(
+                request_id=request_id,
+                response_id=response_id,
+                response_owned=response_owned,
+                expected_epoch=expected_epoch,
+                expected_model_turn_id=expected_model_turn_id,
+            )
+        ):
+            return False
+
+        def _still_valid() -> bool:
+            return (
+                # The anchor changed (a real append was accepted) after this
+                # continuation was planned; the unit is outdated.
+                model_state.last_native_submit_monotonic == anchor
+                and not self._real_input_waiting()
+                and not self.model.silence_continuation_is_stale(
                     request_id=request_id,
                     response_id=response_id,
                     response_owned=response_owned,
                     expected_epoch=expected_epoch,
                     expected_model_turn_id=expected_model_turn_id,
                 )
-            ):
-                return False
+            )
 
-        def _still_valid() -> bool:
-            return not self._real_input_waiting() and not self.model.silence_continuation_is_stale(
-                request_id=request_id,
-                response_id=response_id,
-                response_owned=response_owned,
-                expected_epoch=expected_epoch,
-                expected_model_turn_id=expected_model_turn_id,
+        def _on_append_accepted(submit_time: float) -> None:
+            # Commit timing state once the runtime accepts the append. If the
+            # submission is more than one chunk period past the planned
+            # deadline, the schedule is stale: restart from the actual
+            # submission. Small delays keep the planned cadence so ordinary
+            # jitter does not accumulate as drift.
+            model_state.last_native_submit_monotonic = submit_time
+            model_state.silence_deadline_monotonic = (
+                submit_time + chunk_period_s if submit_time > next_silence_deadline else next_silence_deadline
             )
 
         model_state.pending_silence_owner_id = owner_id
@@ -1062,6 +1137,7 @@ def _still_valid() -> bool:
             dict(payload) if isinstance(payload, dict) else {},
             final=False,
             silence_continuation=True,
+            on_append_accepted=_on_append_accepted,
             before_append=_still_valid,
         )
         return task is not None
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/session.py b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/session.py
index 49d0caab6f8..fe53ec6530f 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/duplex/session.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/duplex/session.py
@@ -29,6 +29,11 @@ class MiniCPMO45ServingSessionState(DuplexModelSessionState):
     continuation_units: int = 0
     pending_silence_task: asyncio.Task[bool] | None = None
     pending_silence_owner_id: str | None = None
+    # Deadline-aligned silence continuation state: the monotonic submission
+    # time of the most recent native input unit and the next silence
+    # continuation deadline. A real (non-silence) input resets the chain.
+    last_native_submit_monotonic: float | None = None
+    silence_deadline_monotonic: float | None = None
 
     def retain_committed_audio(
         self,
@@ -55,3 +60,5 @@ def clear_continuation(self) -> None:
         self.continuation_units = 0
         self.pending_silence_task = None
         self.pending_silence_owner_id = None
+        self.last_native_submit_monotonic = None
+        self.silence_deadline_monotonic = None

From c61b30255bc2099a947ccf7bf0955f73c139d277 Mon Sep 17 00:00:00 2001
From: "howard.shan" <shanwenhao668@gmail.com>
Date: Thu, 17 Sep 2026 20:47:10 +0800
Subject: [PATCH 068/105] [Qwen3-Omni] Remove redundant text embedding in
 DeepStack path (#7573)

Signed-off-by: howard-shan <shanwenhao668@gmail.com>
Signed-off-by: howard.shan <shanwenhao668@gmail.com>
---
 benchmarks/qwen3_omni/embedding_harness.py    | 226 ++++++++++++++++++
 .../qwen3_omni/test_qwen3_omni_embed.py       | 214 +++++++++++++++++
 .../qwen3_omni/qwen3_omni_moe_thinker.py      |  57 ++---
 3 files changed, 470 insertions(+), 27 deletions(-)
 create mode 100644 benchmarks/qwen3_omni/embedding_harness.py
 create mode 100644 tests/model_executor/models/qwen3_omni/test_qwen3_omni_embed.py

diff --git a/benchmarks/qwen3_omni/embedding_harness.py b/benchmarks/qwen3_omni/embedding_harness.py
new file mode 100644
index 00000000000..63d14ef0dbf
--- /dev/null
+++ b/benchmarks/qwen3_omni/embedding_harness.py
@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Small fixtures for the real Qwen3 thinker embedding method and its oracle."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from types import SimpleNamespace
+
+import torch
+from torch import nn
+from torch.nn import functional as F
+
+SCENARIOS = ("text", "empty", "audio", "image", "video", "mixed", "interleaved", "vision_no_deepstack")
+
+
+@dataclass(frozen=True)
+class ModelShape:
+    vocab_size: int = 152064
+    hidden_size: int = 2048
+    deepstack_levels: int = 3
+    image_token_id: int = 151655
+    video_token_id: int = 151656
+    audio_token_id: int = 151675
+
+    def __post_init__(self):
+        if min(self.vocab_size, self.hidden_size, self.deepstack_levels) <= 0:
+            raise ValueError("vocab_size, hidden_size and deepstack_levels must be positive")
+        ids = (self.image_token_id, self.video_token_id, self.audio_token_id)
+        if len(set(ids)) != 3 or not all(0 < token < self.vocab_size for token in ids):
+            raise ValueError("Provide three distinct, positive, in-vocabulary modality IDs; use oov=True to test OOV")
+
+    def token_ids(self, oov=False):
+        if oov:
+            return dict(zip(("image", "video", "audio"), range(self.vocab_size, self.vocab_size + 3)))
+        return {name: getattr(self, f"{name}_token_id") for name in ("image", "video", "audio")}
+
+
+@dataclass
+class Feature:
+    modality: str
+    positions: torch.Tensor
+    main: torch.Tensor
+    deepstack: torch.Tensor | None
+    combined: torch.Tensor
+
+
+@dataclass
+class EmbeddingCase:
+    name: str
+    input_ids: torch.Tensor
+    is_multimodal: torch.Tensor | None
+    features: tuple[Feature, ...]
+    fingerprint: str
+
+    def fresh_embeddings(self):
+        # The thinker replaces list entries with main-scale views.
+        return None if self.name == "text" else [feature.combined for feature in self.features]
+
+
+def _tensor_bytes(tensor):
+    return tensor.detach().contiguous().view(torch.uint8).cpu().numpy().tobytes()
+
+
+def build_case(
+    name,
+    num_tokens,
+    num_mm_tokens,
+    shape,
+    *,
+    device="cuda",
+    dtype=torch.bfloat16,
+    mask_device="cpu",
+    seed=42,
+    oov=False,
+):
+    """Build known feature placements; no model merge is used to define them."""
+    if name not in SCENARIOS:
+        raise ValueError(f"Unknown scenario: {name}")
+    if num_tokens <= 0 or not 0 <= num_mm_tokens < num_tokens:
+        raise ValueError("Require N > 0 and 0 <= M < N")
+    if (name in {"text", "empty"}) != (num_mm_tokens == 0):
+        raise ValueError("Only text/empty scenarios accept M=0")
+    if name in {"mixed", "interleaved"} and (num_mm_tokens < 4 or num_mm_tokens % 2):
+        raise ValueError("Mixed/interleaved scenarios require an even M >= 4")
+    token_ids = shape.token_ids(oov)
+    generator = torch.Generator().manual_seed(seed)
+    ids = torch.randint(0, min(shape.vocab_size, *token_ids.values()), (num_tokens,), generator=generator)
+    mask = torch.zeros(num_tokens, dtype=torch.bool)
+    positions = torch.arange((num_tokens - num_mm_tokens) // 2, (num_tokens - num_mm_tokens) // 2 + num_mm_tokens)
+    groups = []
+    if name == "mixed":
+        groups = [("audio", positions[: num_mm_tokens // 2]), ("image", positions[num_mm_tokens // 2 :])]
+    elif name == "interleaved":
+        groups = [("video", positions[::2]), ("audio", positions[1::2])]
+    elif num_mm_tokens:
+        groups = [("image" if name == "vision_no_deepstack" else name, positions)]
+    features = []
+    for modality, indexes in groups:
+        ids[indexes] = token_ids[modality]
+        mask[indexes] = True
+        rows = torch.arange(len(indexes), dtype=torch.float32)[:, None].remainder(31) / 32
+        cols = torch.arange(shape.hidden_size, dtype=torch.float32)[None, :].remainder(7) / 16
+        main_cpu = rows + cols + {"audio": 2, "image": 4, "video": 6}[modality]
+        main = main_cpu.to(device=device, dtype=dtype)
+        deepstack = None
+        parts = [main]
+        if modality != "audio" and name != "vision_no_deepstack":
+            deepstack = torch.stack(
+                [(main_cpu + 16 + 4 * level).to(device=device, dtype=dtype) for level in range(shape.deepstack_levels)]
+            )
+            parts.extend(deepstack.unbind(0))
+        combined = torch.cat(parts, dim=-1)
+        # set_mm_embedding_modality simply attaches this attribute. Tag only
+        # after cat/to: views and copies do not preserve arbitrary attributes.
+        combined.modality = modality
+        features.append(Feature(modality, indexes, main, deepstack, combined))
+    digest = hashlib.sha256(json.dumps({"name": name, "shape": asdict(shape), "seed": seed, "oov": oov}).encode())
+    digest.update(_tensor_bytes(ids))
+    digest.update(_tensor_bytes(mask))
+    for feature in features:
+        digest.update(feature.modality.encode())
+        digest.update(_tensor_bytes(feature.combined))
+    return EmbeddingCase(
+        name,
+        ids.to(device=device),
+        None if name == "text" else mask.to(device=mask_device),
+        tuple(features),
+        digest.hexdigest(),
+    )
+
+
+class LanguageModelAdapter(nn.Module):
+    def __init__(self, embedding):
+        super().__init__()
+        self.embedding = embedding
+
+    def embed_input_ids(self, input_ids):
+        return self.embedding(input_ids)
+
+    def forward(self, input_ids):
+        return self.embed_input_ids(input_ids)
+
+
+def make_thinker(
+    shape,
+    *,
+    device="cuda",
+    dtype=torch.bfloat16,
+    seed=42,
+    backend="torch",
+    deepstack=True,
+    buffer_capacity=32,
+    oov=False,
+):
+    """Skip checkpoint construction, preserving the real class and its MRO."""
+    from tests.model_executor.helpers import bootstrap_vllm_layer_custom_op_modules
+
+    bootstrap_vllm_layer_custom_op_modules()
+    from vllm_omni.model_executor.models.qwen3_omni.qwen3_omni_moe_thinker import (
+        Qwen3OmniMoeThinkerForConditionalGeneration,
+    )
+
+    if buffer_capacity <= 0:
+        raise ValueError("buffer_capacity must be positive")
+    device = torch.device(device)
+    if backend == "torch":
+        embedding = nn.Embedding(shape.vocab_size, shape.hidden_size, device=device, dtype=dtype)
+    elif backend == "vllm":
+        from vllm.model_executor.layers.vocab_parallel_embedding import VocabParallelEmbedding
+
+        with torch.device(device):
+            embedding = VocabParallelEmbedding(shape.vocab_size, shape.hidden_size, params_dtype=dtype, disable_tp=True)
+    else:
+        raise ValueError(f"Unknown embedding backend: {backend}")
+    with torch.no_grad():
+        embedding.weight.uniform_(-0.5, 0.5, generator=torch.Generator(device=device).manual_seed(seed))
+    thinker = object.__new__(Qwen3OmniMoeThinkerForConditionalGeneration)
+    nn.Module.__init__(thinker)
+    thinker.config = SimpleNamespace(text_config=SimpleNamespace(hidden_size=shape.hidden_size))
+    for modality, token_id in shape.token_ids(oov).items():
+        setattr(thinker.config, f"{modality}_token_id", token_id)
+    thinker.visual = SimpleNamespace(
+        deepstack_visual_indexes=list(range(shape.deepstack_levels)) if deepstack else None
+    )
+    thinker.language_model = LanguageModelAdapter(embedding)
+    thinker._has_oov_mm_tokens = oov
+    thinker.use_deepstack = deepstack
+    thinker.deepstack_num_level = shape.deepstack_levels if deepstack else 0
+    thinker.deepstack_input_embeds = [
+        torch.zeros(buffer_capacity, shape.hidden_size, device=device, dtype=dtype)
+        for _ in range(thinker.deepstack_num_level)
+    ]
+    thinker.deepstack_input_embeds_num_tokens = 0
+    return thinker.eval()
+
+
+@torch.inference_mode()
+def expected_outputs(model, case):
+    """Independent oracle: direct lookup and explicit positions, not merge helpers."""
+    ids = case.input_ids
+    if model._has_oov_mm_tokens and case.is_multimodal is not None:
+        ids = ids.masked_fill(case.is_multimodal.to(ids.device), 0)
+    main = F.embedding(ids, model.language_model.embedding.weight)
+    has_deepstack = any(feature.deepstack is not None for feature in case.features)
+    deepstack = main.new_zeros((model.deepstack_num_level, *main.shape)) if has_deepstack else None
+    for feature in case.features:
+        indexes = feature.positions.to(main.device)
+        main[indexes] = feature.main
+        if feature.deepstack is not None:
+            deepstack[:, indexes, :] = feature.deepstack
+    return main, deepstack
+
+
+@torch.inference_mode()
+def assert_case_output(model, case, result):
+    expected, deepstack = expected_outputs(model, case)
+    torch.testing.assert_close(result, expected, rtol=0, atol=0)
+    if deepstack is None:
+        assert model.deepstack_input_embeds_num_tokens == 0, "Unexpected stale DeepStack buffer"
+    else:
+        assert model.deepstack_input_embeds_num_tokens == case.input_ids.numel()
+        actual = torch.stack([buffer[: case.input_ids.numel()] for buffer in model.deepstack_input_embeds])
+        torch.testing.assert_close(actual, deepstack, rtol=0, atol=0)
diff --git a/tests/model_executor/models/qwen3_omni/test_qwen3_omni_embed.py b/tests/model_executor/models/qwen3_omni/test_qwen3_omni_embed.py
new file mode 100644
index 00000000000..d041eace013
--- /dev/null
+++ b/tests/model_executor/models/qwen3_omni/test_qwen3_omni_embed.py
@@ -0,0 +1,214 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Run Qwen3-Omni embedding regressions on a Linux/CUDA environment.
+
+The oracle assigns features to token positions independently of the model's
+merge helpers. LM call counts additionally catch issue #7451: ordinary
+multimodal inputs must not repeat the text embedding lookup. Small synthetic
+weights suffice; no checkpoint is downloaded or loaded.
+"""
+
+import sys
+
+import pytest
+import torch
+from pytest_mock import MockerFixture
+
+from benchmarks.qwen3_omni.embedding_harness import (
+    ModelShape,
+    assert_case_output,
+    build_case,
+    expected_outputs,
+    make_thinker,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cuda]
+
+_SHAPE = ModelShape(
+    vocab_size=64,
+    hidden_size=8,
+    deepstack_levels=3,
+    image_token_id=60,
+    video_token_id=61,
+    audio_token_id=62,
+)
+
+_SCENARIOS = (
+    "text",
+    "empty",
+    "audio",
+    "image",
+    "video",
+    "mixed",
+    "interleaved",
+    "vision_no_deepstack",
+)
+
+
+@pytest.fixture(scope="module", autouse=True)
+def require_cuda_environment():
+    if sys.platform != "linux" or torch.version.cuda is None or not torch.cuda.is_available():
+        pytest.fail(
+            "This validation suite requires a Linux/CUDA environment; "
+            "CPU execution and an all-skipped result are not valid substitutes.",
+            pytrace=False,
+        )
+    if not torch.cuda.is_bf16_supported(including_emulation=False):
+        pytest.fail("This validation suite requires native BF16 support on the current CUDA device.", pytrace=False)
+
+
+@torch.inference_mode()
+def _embed(model, case):
+    return model.embed_input_ids(
+        case.input_ids,
+        multimodal_embeddings=case.fresh_embeddings(),
+        is_multimodal=case.is_multimodal,
+    )
+
+
+@pytest.mark.parametrize(
+    ("scenario", "dtype"),
+    [pytest.param(scenario, torch.bfloat16, id=f"{scenario}-bf16") for scenario in _SCENARIOS]
+    + [pytest.param(scenario, torch.float32, id=f"{scenario}-fp32") for scenario in ("image", "mixed", "interleaved")],
+)
+def test_embedding_positions_and_single_lm_lookup(mocker: MockerFixture, scenario: str, dtype: torch.dtype):
+    model = make_thinker(_SHAPE, device="cuda", dtype=dtype, deepstack=scenario != "vision_no_deepstack")
+    case = build_case(
+        scenario,
+        16,
+        0 if scenario in {"text", "empty"} else 8,
+        _SHAPE,
+        device="cuda",
+        dtype=dtype,
+        mask_device="cpu",
+    )
+    lm_embed = mocker.spy(model.language_model, "embed_input_ids")
+
+    result = _embed(model, case)
+
+    # Unlike upstream-only mocks, make_thinker returns an instance of Omni's
+    # actual thinker class, so its zero-argument super() follows the real MRO.
+    lm_embed.assert_called_once()
+    assert_case_output(model, case, result)
+
+
+@pytest.mark.parametrize("scenario", ["image", "mixed", "interleaved"])
+def test_repeated_calls_keep_original_deepstack_features(mocker: MockerFixture, scenario: str):
+    model = make_thinker(_SHAPE, device="cuda", dtype=torch.bfloat16)
+    case = build_case(scenario, 16, 8, _SHAPE, device="cuda", dtype=torch.bfloat16, mask_device="cpu")
+    original_embeddings = case.fresh_embeddings()
+    assert original_embeddings
+    original_shapes = [tensor.shape for tensor in original_embeddings]
+    original_modalities = [getattr(tensor, "modality", None) for tensor in original_embeddings]
+    lm_embed = mocker.spy(model.language_model, "embed_input_ids")
+    previous_list = None
+
+    for _ in range(3):
+        embeddings = case.fresh_embeddings()
+        assert embeddings is not original_embeddings
+        assert embeddings is not previous_list
+        assert [tensor.shape for tensor in embeddings] == original_shapes
+        assert [getattr(tensor, "modality", None) for tensor in embeddings] == original_modalities
+        lm_embed.reset_mock()
+
+        with torch.inference_mode():
+            result = model.embed_input_ids(
+                case.input_ids,
+                multimodal_embeddings=embeddings,
+                is_multimodal=case.is_multimodal,
+            )
+
+        lm_embed.assert_called_once()
+        assert_case_output(model, case, result)
+        # torch.split replaces entries in the supplied list with main-scale
+        # views. The next call must receive the original multiscale tensors.
+        assert [tensor.shape for tensor in original_embeddings] == original_shapes
+        model._clear_deepstack_input_embeds(case.input_ids.numel())
+        previous_list = embeddings
+
+
+@pytest.mark.parametrize("scenario", ["audio", "image", "mixed", "interleaved"])
+def test_oov_multimodal_ids_are_masked_before_lm_lookup(mocker: MockerFixture, scenario: str):
+    model = make_thinker(_SHAPE, device="cuda", dtype=torch.bfloat16, oov=True)
+    case = build_case(scenario, 16, 8, _SHAPE, device="cuda", dtype=torch.bfloat16, mask_device="cpu", oov=True)
+    original_ids = case.input_ids.clone()
+    mask = case.is_multimodal.to(device=case.input_ids.device)
+    assert torch.all(case.input_ids[mask] >= _SHAPE.vocab_size)
+    lm_embed = mocker.spy(model.language_model, "embed_input_ids")
+
+    result = _embed(model, case)
+
+    lm_embed.assert_called_once()
+    received_ids = lm_embed.call_args.args[0]
+    torch.testing.assert_close(received_ids, original_ids.masked_fill(mask, 0), rtol=0, atol=0)
+    torch.testing.assert_close(case.input_ids, original_ids, rtol=0, atol=0)
+    assert_case_output(model, case, result)
+
+
+@pytest.mark.parametrize("next_scenario", ["text", "empty"])
+def test_padded_deepstack_read_and_clear_do_not_leak_into_decode(mocker: MockerFixture, next_scenario: str):
+    model = make_thinker(_SHAPE, device="cuda", dtype=torch.bfloat16, buffer_capacity=32)
+    image_case = build_case("image", 16, 8, _SHAPE, device="cuda", dtype=torch.bfloat16, mask_device="cpu")
+    image_result = _embed(model, image_case)
+    assert_case_output(model, image_case, image_result)
+    _, expected_deepstack = expected_outputs(model, image_case)
+    assert expected_deepstack is not None
+
+    num_valid = image_case.input_ids.numel()
+    num_padded = 24
+    # Padding may contain old buffer contents. _get must zero the tail while
+    # retaining all valid visual features, as the real forward requires.
+    for buffer in model.deepstack_input_embeds:
+        buffer[num_valid:num_padded].fill_(77)
+    padded = model._get_deepstack_input_embeds(num_padded)
+    assert padded is not None
+    for level in range(_SHAPE.deepstack_levels):
+        actual = padded[f"deepstack_input_embeds_{level}"]
+        torch.testing.assert_close(actual[:num_valid], expected_deepstack[level])
+        assert torch.count_nonzero(actual[num_valid:]).item() == 0
+
+    model._clear_deepstack_input_embeds(num_padded)
+    assert model.deepstack_input_embeds_num_tokens == 0
+    for buffer in model.deepstack_input_embeds:
+        assert torch.count_nonzero(buffer[:num_padded]).item() == 0
+
+    decode_case = build_case(next_scenario, 1, 0, _SHAPE, device="cuda", dtype=torch.bfloat16, mask_device="cpu")
+    lm_embed = mocker.spy(model.language_model, "embed_input_ids")
+    decode_result = _embed(model, decode_case)
+    lm_embed.assert_called_once()
+    assert_case_output(model, decode_case, decode_result)
+    decode_deepstack = model._get_deepstack_input_embeds(2)
+    assert decode_deepstack is not None
+    for level in range(_SHAPE.deepstack_levels):
+        assert torch.count_nonzero(decode_deepstack[f"deepstack_input_embeds_{level}"]).item() == 0
+
+
+@torch.inference_mode()
+def test_deepstack_set_resizes_for_larger_scheduled_windows(mocker: MockerFixture):
+    model = make_thinker(_SHAPE, device="cuda", dtype=torch.bfloat16, buffer_capacity=4)
+    lm_embed = mocker.spy(model.language_model, "embed_input_ids")
+
+    for num_tokens in (16, 24):
+        case = build_case("mixed", num_tokens, 8, _SHAPE, device="cuda", dtype=torch.bfloat16, mask_device="cpu")
+        lm_embed.reset_mock()
+        result = _embed(model, case)
+
+        lm_embed.assert_called_once()
+        assert_case_output(model, case, result)
+        assert model.deepstack_input_embeds_num_tokens == num_tokens
+        assert all(buffer.size(0) >= num_tokens for buffer in model.deepstack_input_embeds)
+        model._clear_deepstack_input_embeds(num_tokens)
+
+
+@pytest.mark.parametrize("mask_device", ["cpu", "cuda"])
+@pytest.mark.parametrize("scenario", ["image", "interleaved"])
+def test_cuda_embeddings_accept_cpu_or_cuda_mask(mocker: MockerFixture, scenario: str, mask_device: str):
+    model = make_thinker(_SHAPE, device="cuda", dtype=torch.bfloat16)
+    case = build_case(scenario, 16, 8, _SHAPE, device="cuda", dtype=torch.bfloat16, mask_device=mask_device)
+    lm_embed = mocker.spy(model.language_model, "embed_input_ids")
+
+    result = _embed(model, case)
+
+    lm_embed.assert_called_once()
+    assert result.device.type == "cuda"
+    assert_case_output(model, case, result)
diff --git a/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py b/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py
index c78679c55d9..5d5edf0df79 100644
--- a/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py
+++ b/vllm_omni/model_executor/models/qwen3_omni/qwen3_omni_moe_thinker.py
@@ -1273,14 +1273,12 @@ def embed_input_ids(
         *,
         is_multimodal: torch.Tensor | None = None,
     ) -> torch.Tensor:
-        inputs_embeds = self._embed_text_input_ids(
-            input_ids,
-            self.language_model.embed_input_ids,
-            is_multimodal=is_multimodal,
-        )
-
         if multimodal_embeddings is None or len(multimodal_embeddings) == 0:
-            return inputs_embeds
+            return self._embed_text_input_ids(
+                input_ids,
+                self.language_model.embed_input_ids,
+                is_multimodal=is_multimodal,
+            )
 
         # Detect interleaved audio-in-video early, since it affects
         # both the deepstack path and the final embedding merge.
@@ -1295,12 +1293,12 @@ def embed_input_ids(
 
         is_interleaved = check_interleaved_audio_video(is_video, is_audio, num_video, num_audio)
 
-        deepstack_input_embeds = None
         # split the feat dim to obtain multi-scale visual feature
         has_vision_embeddings = [
             embeddings.shape[-1] != self.config.text_config.hidden_size for embeddings in multimodal_embeddings
         ]
-        if self.visual.deepstack_visual_indexes is not None and any(has_vision_embeddings):
+        has_deepstack_embeddings = self.visual.deepstack_visual_indexes is not None and any(has_vision_embeddings)
+        if has_deepstack_embeddings:
             multiscale_len = len(self.visual.deepstack_visual_indexes)
             multimodal_embeddings_multiscale = []
 
@@ -1343,6 +1341,28 @@ def embed_input_ids(
                 if not is_interleaved:
                     mm_position_idx += num_tokens
 
+        if is_interleaved:
+            inputs_embeds = self._embed_text_input_ids(
+                input_ids,
+                self.language_model.embed_input_ids,
+                is_multimodal=is_multimodal,
+            )
+            inputs_embeds = merge_interleaved_embeddings(
+                inputs_embeds,
+                multimodal_embeddings,
+                is_video,
+                is_audio,
+                is_mm_device,
+            )
+        else:
+            # multimodal_embeddings now contains the main-scale features.
+            inputs_embeds = super().embed_input_ids(
+                input_ids,
+                multimodal_embeddings=multimodal_embeddings,
+                is_multimodal=is_multimodal,
+            )
+
+        if has_deepstack_embeddings:
             deepstack_input_embeds = inputs_embeds.new_zeros(
                 inputs_embeds.size(0), multiscale_len * inputs_embeds.size(1)
             )
@@ -1358,24 +1378,7 @@ def embed_input_ids(
             )
             self._set_deepstack_input_embeds(deepstack_input_embeds)
 
-        if is_interleaved:
-            return merge_interleaved_embeddings(
-                inputs_embeds,
-                multimodal_embeddings,
-                is_video,
-                is_audio,
-                is_mm_device,
-            )
-
-        # Default: standard merge (no interleaving), same as parent class.
-        # multimodal_embeddings may have been updated above (deepstack
-        # main-scale). Use super() to stay consistent with the parent
-        # implementation and avoid issues seen in Qwen2.5-Omni (#34506).
-        return super().embed_input_ids(
-            input_ids,
-            multimodal_embeddings=multimodal_embeddings,
-            is_multimodal=is_multimodal,
-        )
+        return inputs_embeds
 
     def forward(
         self,

From eb1abbadf832c625a9560cb6e0142d2cec4998ce Mon Sep 17 00:00:00 2001
From: Canlin Guo <canlinguosdu@gmail.com>
Date: Thu, 17 Sep 2026 20:51:26 +0800
Subject: [PATCH 069/105] [Feature][TTS] MOSS-TTS: place the reference-audio
 encoder on the code2wav stage's GPU (#7724)

Signed-off-by: Canlin Guo <canlinguosdu@gmail.com>
---
 .../openai_api/test_tts_adapter.py            | 109 ++++++++++++++++++
 .../openai/tts_adapters/moss_tts.py           |  96 ++++++++++++---
 2 files changed, 192 insertions(+), 13 deletions(-)

diff --git a/tests/entrypoints/openai_api/test_tts_adapter.py b/tests/entrypoints/openai_api/test_tts_adapter.py
index 500feab3546..a2507a056ac 100644
--- a/tests/entrypoints/openai_api/test_tts_adapter.py
+++ b/tests/entrypoints/openai_api/test_tts_adapter.py
@@ -255,6 +255,115 @@ def test_moss_reference_transcript_mode(variant, ref_text, mode, mocker):
     assert request.input == "Target."
 
 
+def _moss_adapter_with_stage_configs(stage_configs, mocker):
+    engine_client = SimpleNamespace(
+        model_config=SimpleNamespace(model="OpenMOSS-Team/MOSS-TTS-Local-Transformer-v1.5"),
+        stage_configs=stage_configs,
+    )
+    return MossTTSAdapter(SpeechServingContext(server=mocker.Mock(), engine_client=engine_client))
+
+
+def _moss_cuda_available(mocker, device_count=8):
+    mocker.patch("torch.cuda.is_available", return_value=True)
+    mocker.patch("torch.accelerator.device_count", return_value=device_count)
+
+
+@pytest.mark.parametrize(
+    "stage_configs,expected",
+    [
+        # Follows the code2wav stage's first device.
+        (
+            [
+                SimpleNamespace(model_stage="moss_tts_local", runtime_config=SimpleNamespace(devices="0")),
+                SimpleNamespace(model_stage="moss_tts_local_codec", runtime_config=SimpleNamespace(devices="3")),
+            ],
+            "cuda:3",
+        ),
+        # No codec-named stage: anchors on the last stage of the pipeline.
+        (
+            [
+                SimpleNamespace(model_stage="talker", runtime_config=SimpleNamespace(devices="1")),
+                SimpleNamespace(model_stage="decoder", runtime_config=SimpleNamespace(devices="2")),
+            ],
+            "cuda:2",
+        ),
+        # Multi-device codec stage pins replica 0 on the first device.
+        (
+            [
+                SimpleNamespace(model_stage="moss_tts_local_codec", runtime_config=SimpleNamespace(devices="5,6")),
+            ],
+            "cuda:5",
+        ),
+        # No explicit pinning anywhere: stage worker defaults to cuda:0.
+        (
+            [SimpleNamespace(model_stage="moss_tts_local_codec", runtime_config=SimpleNamespace(devices=None))],
+            "cuda:0",
+        ),
+    ],
+)
+def test_moss_ref_encoder_device_follows_codec_stage(stage_configs, expected, mocker):
+    import torch
+
+    _moss_cuda_available(mocker)
+    adapter = _moss_adapter_with_stage_configs(stage_configs, mocker)
+    assert adapter._resolve_ref_encoder_device() == torch.device(expected)
+
+
+def test_moss_ref_encoder_device_accepts_dict_runtime(mocker):
+    import torch
+
+    _moss_cuda_available(mocker)
+    adapter = _moss_adapter_with_stage_configs(
+        [SimpleNamespace(model_stage="moss_tts_local_codec", runtime={"devices": "2"})],
+        mocker,
+    )
+    assert adapter._resolve_ref_encoder_device() == torch.device("cuda:2")
+
+
+def test_moss_ref_encoder_device_cpu_when_cuda_unavailable(mocker):
+    import torch
+
+    mocker.patch("torch.cuda.is_available", return_value=False)
+    adapter = _moss_adapter_with_stage_configs(
+        [SimpleNamespace(model_stage="moss_tts_local_codec", runtime_config=SimpleNamespace(devices="3"))],
+        mocker,
+    )
+    assert adapter._resolve_ref_encoder_device() == torch.device("cpu")
+
+
+def test_moss_ref_encoder_device_cpu_when_index_out_of_range(mocker):
+    import torch
+
+    _moss_cuda_available(mocker, device_count=2)
+    adapter = _moss_adapter_with_stage_configs(
+        [SimpleNamespace(model_stage="moss_tts_local_codec", runtime_config=SimpleNamespace(devices="5"))],
+        mocker,
+    )
+    assert adapter._resolve_ref_encoder_device() == torch.device("cpu")
+
+
+def test_moss_get_processor_places_audio_tokenizer_on_codec_stage_device(mocker):
+    import torch
+
+    _moss_cuda_available(mocker)
+    adapter = _moss_adapter_with_stage_configs(
+        [SimpleNamespace(model_stage="moss_tts_local_codec", runtime_config=SimpleNamespace(devices="3"))],
+        mocker,
+    )
+    audio_tokenizer = mocker.Mock()
+    audio_tokenizer.to.return_value = audio_tokenizer
+    processor = SimpleNamespace(audio_tokenizer=audio_tokenizer)
+    from_pretrained = mocker.patch("transformers.AutoProcessor.from_pretrained", return_value=processor)
+
+    assert adapter._get_moss_processor() is processor
+    audio_tokenizer.to.assert_called_once_with(torch.device("cuda", 3))
+    audio_tokenizer.eval.assert_called_once_with()
+    # Lazy cache: no re-load / re-placement on the second call.
+    assert adapter._get_moss_processor() is processor
+    from_pretrained.assert_called_once()
+    audio_tokenizer.to.assert_called_once()
+
+
 def test_qwen3_tts_metadata():
     assert Qwen3TTSAdapter.backend == "ar"
     assert issubclass(Qwen3TTSAdapter, ARTTSAdapter)
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py b/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
index 555fec42d56..5f5d8ecb9ed 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/moss_tts.py
@@ -13,6 +13,7 @@
 from transformers import AutoModel, AutoTokenizer
 from transformers.dynamic_module_utils import get_class_from_dynamic_module
 from vllm.inputs import tokens_input
+from vllm.logger import init_logger
 
 from vllm_omni.entrypoints.openai.tts_adapters import register_tts_adapter
 from vllm_omni.entrypoints.openai.tts_adapters.base import (
@@ -27,6 +28,8 @@
 if TYPE_CHECKING:
     from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
 
+logger = init_logger(__name__)
+
 
 class _MossTTSAdapterBase(ARTTSAdapter):
     accumulate_nonstreaming: bool = False
@@ -143,13 +146,81 @@ def _detect_moss_variant(self) -> str:
             return "voice_generator"
         return "tts"
 
+    def _codec_stage_devices(self) -> str | None:
+        """Read the runtime ``devices`` entry of this pipeline's codec stage.
+
+        The codec (code2wav) stage is the final stage of every MOSS pipeline
+        (``moss_tts_local_codec`` / ``moss_tts_codec``); prefer a stage whose
+        ``model_stage`` mentions "codec", else anchor on the last stage. The
+        runtime mapping accepts the resolved ``runtime_config`` object, the
+        omegaconf ``runtime`` mapping, and the legacy ``yaml_runtime`` dict.
+        """
+        stages = list(getattr(self.engine_client, "stage_configs", None) or ())
+        if not stages:
+            return None
+        codec_stages = [s for s in stages if "codec" in str(getattr(s, "model_stage", "") or "")]
+        anchor = codec_stages[-1] if codec_stages else stages[-1]
+        for attr in ("runtime_config", "runtime", "yaml_runtime"):
+            runtime_cfg = getattr(anchor, attr, None)
+            if runtime_cfg is None:
+                continue
+            devices = (
+                runtime_cfg.get("devices") if hasattr(runtime_cfg, "get") else getattr(runtime_cfg, "devices", None)
+            )
+            if devices is not None and str(devices).strip():
+                return str(devices)
+        devices = getattr(anchor, "devices", None)
+        return str(devices) if devices is not None and str(devices).strip() else None
+
+    def _resolve_ref_encoder_device(self):
+        """Pick the device of the API-process reference-audio encoder.
+
+        The encoder follows the code2wav stage onto its first GPU: the stage
+        worker remaps its ``devices`` entry through ``CUDA_VISIBLE_DEVICES``
+        and sees it as logical index 0, while replica launch restores the
+        parent environment, so the same index names the same physical GPU in
+        this process. When the stage pins no devices the stage worker and the
+        encoder both default to the first visible GPU. Falls back to CPU when
+        CUDA is unavailable or the stage device is not parseable.
+        """
+        import torch  # local to avoid pulling torch at module import time
+
+        if not torch.cuda.is_available():
+            return torch.device("cpu")
+        devices_str = self._codec_stage_devices()
+        if devices_str is None:
+            # No explicit pinning: the stage worker lands on the first visible
+            # GPU (vLLM picks cuda:0 of the un-remapped environment).
+            return torch.device("cuda", 0)
+        first = devices_str.split(",")[0].strip()
+        if not first:
+            return torch.device("cuda", 0)
+        if first == "cpu":
+            return torch.device("cpu")
+        if not first.isdigit():
+            logger.warning("MOSS ref encoder: codec stage devices %r not parseable; keeping CPU", devices_str)
+            return torch.device("cpu")
+        index = int(first)
+        device_count = torch.accelerator.device_count()
+        if index >= device_count:
+            logger.warning(
+                "MOSS ref encoder: codec stage device cuda:%d out of range (%d visible); keeping CPU",
+                index,
+                device_count,
+            )
+            return torch.device("cpu")
+        return torch.device("cuda", index)
+
     def _get_moss_processor(self):
         """Lazily load the upstream MOSS-TTS processor once per server.
 
         Cached on ``self._moss_processor_cache``. The processor owns its own
-        audio_tokenizer (~1.6 B params); we keep it on CPU so it doesn't
-        compete with the talker (~8 GiB) and codec (~7 GiB) for our 96 GiB
-        GPU — per-request ref-audio encoding is fast enough on CPU.
+        audio_tokenizer (~1.6 B params) used for per-request reference-audio
+        encoding; it is placed on the code2wav stage's GPU (see
+        ``_resolve_ref_encoder_device``) so cold encodes run on device instead
+        of paying a CPU forward per request. Note this memory is charged to
+        the API process, outside each stage's ``gpu_memory_utilization``
+        budget — keep some headroom on the codec GPU.
         """
         cached = getattr(self, "_moss_processor_cache", None)
         if cached is not None:
@@ -159,7 +230,9 @@ def _get_moss_processor(self):
         model_id = self.engine_client.model_config.model
         proc = AutoProcessor.from_pretrained(model_id, trust_remote_code=True)
         if hasattr(proc, "audio_tokenizer"):
-            proc.audio_tokenizer = proc.audio_tokenizer.to("cpu").eval()
+            device = self._resolve_ref_encoder_device()
+            proc.audio_tokenizer = proc.audio_tokenizer.to(device).eval()
+            logger.info("MOSS reference-audio encoder (audio_tokenizer) placed on %s", device)
         self._moss_processor_cache = proc
         return proc
 
@@ -188,16 +261,13 @@ def _get_moss_realtime_components(self):
                     ),
                 )
             )
-            codec = (
-                AutoModel.from_pretrained(
-                    codec_path,
-                    trust_remote_code=True,
-                )
-                # Reference encoding runs in the API process. Keep the codec on CPU
-                # so it does not reserve accelerator memory outside the model workers.
-                .to("cpu")
-                .eval()
+            codec = AutoModel.from_pretrained(
+                codec_path,
+                trust_remote_code=True,
             )
+            # Reference encoding runs in the API process; follow the codec
+            # (code2wav) stage's GPU like the processor path above.
+            codec = codec.to(self._resolve_ref_encoder_device()).eval()
             cached = (tokenizer, processor, codec)
             self._moss_realtime_components = cached
             return cached

From 882bf8bc95b1a9a08af667a7edd006ebd21e4b57 Mon Sep 17 00:00:00 2001
From: amy-why-3459 <wuhaiyan17@huawei.com>
Date: Thu, 17 Sep 2026 23:32:31 +0800
Subject: [PATCH 070/105] [Frontend] Add a shared realtime web UI for MiniCPM-o
 and Qwen3-Omni (#7222) (#7585)

Signed-off-by: amy-why-3459 <wuhaiyan17@huawei.com>
---
 docs/serving/realtime_duplex_api.md           |   5 +-
 examples/online_serving/minicpmo/README.md    |   9 +
 .../minicpmo/realtime_web/server.py           | 190 +-----
 examples/online_serving/qwen3_omni/README.md  |  71 +-
 .../qwen3_omni/openai_realtime_client.py      |   3 +-
 .../qwen3_omni/realtime_web/__init__.py       |   4 +
 .../qwen3_omni/realtime_web/__main__.py       |   7 +
 .../online_serving/realtime_web/README.md     | 221 +++++++
 .../online_serving/realtime_web/__init__.py   |   4 +
 .../online_serving/realtime_web/__main__.py   |   7 +
 .../realtime_web/app/index.html               |  23 +-
 .../realtime_web/app/static/app.js            | 434 ++++++++----
 .../realtime_web/app/static/pcm_worklet.js    |   0
 .../app/static/playback_worklet.js            |   7 +
 .../app/static/profiles/common.js             |  56 ++
 .../app/static/profiles/minicpm_native.js     |  55 ++
 .../app/static/profiles/qwen3_turn.js         | 100 +++
 .../realtime_web/app/static/styles.css        |   3 +
 .../online_serving/realtime_web/server.py     | 229 +++++++
 tests/config/test_environment_variables.py    |   4 +-
 tests/engine/duplex/test_engine_session.py    |   4 +-
 tests/engine/duplex/test_session_manager.py   |   6 +-
 tests/engine/duplex/test_vad_backend.py       |  31 +-
 tests/engine/test_duplex_orchestrator.py      |  45 ++
 .../openai_api/test_api_server_guards.py      |  16 +-
 .../openai_api/test_duplex_api_server.py      |  28 +
 .../test_minicpmo_realtime_web_server.py      |  48 +-
 .../test_minicpmo_realtime_web_static.py      |  69 +-
 tests/examples/test_realtime_web_profiles.cjs | 412 ++++++++++++
 tests/examples/test_realtime_web_profiles.py  |  24 +
 .../models/qwen3_omni/test_duplex_plugin.py   | 625 ++++++++++++++++++
 .../config/environment_variable_inventory.py  |   1 +
 vllm_omni/config/stage_config.py              |   2 +
 vllm_omni/deploy/qwen3_omni_duplex.yaml       |   8 +
 vllm_omni/engine/duplex/config.py             |  65 +-
 vllm_omni/engine/duplex/plugin.py             |  25 +-
 vllm_omni/engine/duplex/realtime_events.py    | 117 ++--
 .../engine/duplex/session/append_task.py      |   9 +-
 vllm_omni/engine/duplex/session/control.py    |  54 ++
 .../engine/duplex/session/engine_session.py   | 162 +++--
 vllm_omni/engine/duplex/session/helpers.py    |  33 +-
 vllm_omni/engine/duplex/session/manager.py    |  11 +-
 .../engine/duplex/session/model_channel.py    |  63 +-
 vllm_omni/engine/duplex/session/runner.py     |  99 ++-
 vllm_omni/engine/duplex/vad.py                |  10 +-
 vllm_omni/engine/duplex_orchestrator.py       |  53 +-
 vllm_omni/entrypoints/duplex/warmup.py        |   5 +-
 vllm_omni/entrypoints/openai/api_server.py    |  52 +-
 .../models/qwen3_omni/duplex/__init__.py      |   2 +
 .../models/qwen3_omni/duplex/input.py         | 103 +++
 .../models/qwen3_omni/duplex/plugin.py        | 390 +++++++++++
 .../models/qwen3_omni/duplex/session.py       |  59 ++
 .../models/qwen3_omni/pipeline.py             |   4 +-
 53 files changed, 3436 insertions(+), 631 deletions(-)
 create mode 100644 examples/online_serving/qwen3_omni/realtime_web/__init__.py
 create mode 100644 examples/online_serving/qwen3_omni/realtime_web/__main__.py
 create mode 100644 examples/online_serving/realtime_web/README.md
 create mode 100644 examples/online_serving/realtime_web/__init__.py
 create mode 100644 examples/online_serving/realtime_web/__main__.py
 rename examples/online_serving/{minicpmo => }/realtime_web/app/index.html (76%)
 rename examples/online_serving/{minicpmo => }/realtime_web/app/static/app.js (59%)
 rename examples/online_serving/{minicpmo => }/realtime_web/app/static/pcm_worklet.js (100%)
 rename examples/online_serving/{minicpmo => }/realtime_web/app/static/playback_worklet.js (95%)
 create mode 100644 examples/online_serving/realtime_web/app/static/profiles/common.js
 create mode 100644 examples/online_serving/realtime_web/app/static/profiles/minicpm_native.js
 create mode 100644 examples/online_serving/realtime_web/app/static/profiles/qwen3_turn.js
 rename examples/online_serving/{minicpmo => }/realtime_web/app/static/styles.css (98%)
 create mode 100644 examples/online_serving/realtime_web/server.py
 create mode 100644 tests/examples/test_realtime_web_profiles.cjs
 create mode 100644 tests/examples/test_realtime_web_profiles.py
 create mode 100644 tests/model_executor/models/qwen3_omni/test_duplex_plugin.py
 create mode 100644 vllm_omni/deploy/qwen3_omni_duplex.yaml
 create mode 100644 vllm_omni/model_executor/models/qwen3_omni/duplex/__init__.py
 create mode 100644 vllm_omni/model_executor/models/qwen3_omni/duplex/input.py
 create mode 100644 vllm_omni/model_executor/models/qwen3_omni/duplex/plugin.py
 create mode 100644 vllm_omni/model_executor/models/qwen3_omni/duplex/session.py

diff --git a/docs/serving/realtime_duplex_api.md b/docs/serving/realtime_duplex_api.md
index c18b416c7d5..a20750090cb 100644
--- a/docs/serving/realtime_duplex_api.md
+++ b/docs/serving/realtime_duplex_api.md
@@ -768,7 +768,10 @@ events with `server_event_seq > 40` are replayed in order)
 ```
 
 with camera frames (omni video; rides the append that closes a 1 s model
-unit; each entry is a **bare** base64 JPEG/PNG — no `data:` URL prefix)
+unit; each entry is a **bare** base64 JPEG/PNG — no `data:` URL prefix).
+Only a model whose Stage 0 interleaves a frame track at unit boundaries takes
+this field; a turn model has no such boundary and rejects it, expecting
+`conversation.item.create` with `input_image` content instead.
 
 ```json
 {
diff --git a/examples/online_serving/minicpmo/README.md b/examples/online_serving/minicpmo/README.md
index 67b268a773a..ffd50167f0c 100644
--- a/examples/online_serving/minicpmo/README.md
+++ b/examples/online_serving/minicpmo/README.md
@@ -316,3 +316,12 @@ them unless `--allow-invalid-clock` is explicit.
   [`examples/offline_inference/minicpmo/`](../../offline_inference/minicpmo/)
 - Recipe:
   [`recipes/OpenBMB/MiniCPM-o-4_5.md`](../../../recipes/OpenBMB/MiniCPM-o-4_5.md)
+
+### Shared realtime UI implementation
+
+The `python -m examples.online_serving.minicpmo.realtime_web` command remains
+available with the same MiniCPM defaults and required `--ref-audio`. Its assets
+now live in [the shared realtime UI](../realtime_web/README.md), with a dedicated
+`minicpm-native` profile preserving native duplex input, playback ACKs and camera
+frames. Qwen3 uses a separate profile in the same shell, supporting manual STT
+turns or Server VAD turns with speech interruption.
diff --git a/examples/online_serving/minicpmo/realtime_web/server.py b/examples/online_serving/minicpmo/realtime_web/server.py
index ee78fff746b..1ef12d18649 100644
--- a/examples/online_serving/minicpmo/realtime_web/server.py
+++ b/examples/online_serving/minicpmo/realtime_web/server.py
@@ -1,185 +1,23 @@
-"""Static host and same-origin Realtime proxy for the full-duplex demo."""
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-from __future__ import annotations
+"""Backward-compatible MiniCPM entry point for the shared realtime UI."""
 
-import argparse
-import asyncio
-import base64
-import contextlib
-import hashlib
-import json
-import logging
-from pathlib import Path
-from urllib.parse import urlencode
+from examples.online_serving.realtime_web.server import (
+    APP_DIR,
+    STATIC_DIR,
+    _join_ws_url,
+    build_app,
+)
+from examples.online_serving.realtime_web.server import (
+    main as _main,
+)
 
-import uvicorn
-import websockets
-from fastapi import FastAPI, WebSocket, WebSocketDisconnect
-from fastapi.responses import HTMLResponse, Response
-from fastapi.staticfiles import StaticFiles
-
-logger = logging.getLogger(__name__)
-APP_DIR = Path(__file__).parent / "app"
-STATIC_DIR = APP_DIR / "static"
-
-
-def _join_ws_url(base: str, path: str, query: str) -> str:
-    return base.rstrip("/") + path + (("?" + query) if query else "")
-
-
-async def _pump_client_to_backend(client: WebSocket, backend) -> None:
-    try:
-        while True:
-            message = await client.receive()
-            if message["type"] == "websocket.disconnect":
-                await backend.close()
-                return
-            if message.get("text") is not None:
-                await backend.send(message["text"])
-            elif message.get("bytes") is not None:
-                await backend.send(message["bytes"])
-    except (WebSocketDisconnect, websockets.ConnectionClosed):
-        with contextlib.suppress(Exception):
-            await backend.close()
-
-
-async def _pump_backend_to_client(client: WebSocket, backend) -> None:
-    try:
-        async for message in backend:
-            if isinstance(message, bytes):
-                await client.send_bytes(message)
-            else:
-                await client.send_text(message)
-    except (WebSocketDisconnect, websockets.ConnectionClosed):
-        return
-    except RuntimeError as exc:
-        if "websocket.send" in str(exc) and "websocket.close" in str(exc):
-            return
-        raise
-
-
-def _expected_proxy_close(exc: BaseException) -> bool:
-    if isinstance(exc, (WebSocketDisconnect, websockets.ConnectionClosed, asyncio.CancelledError)):
-        return True
-    return isinstance(exc, RuntimeError) and "websocket.send" in str(exc) and "websocket.close" in str(exc)
-
-
-def build_app(
-    *,
-    ws_backend: str = "ws://127.0.0.1:8099",
-    model: str = "openbmb/MiniCPM-o-4_5",
-    public_realtime_url: str | None = None,
-    ref_audio: str | None = None,
-) -> FastAPI:
-    app = FastAPI(title="Experimental Full-Duplex Web Demo")
-    index_path = APP_DIR / "index.html"
-    app_version_hash = hashlib.sha256()
-    for asset_path in (
-        STATIC_DIR / "app.js",
-        STATIC_DIR / "pcm_worklet.js",
-        STATIC_DIR / "playback_worklet.js",
-    ):
-        app_version_hash.update(asset_path.read_bytes())
-    app_version = app_version_hash.hexdigest()[:12]
-
-    ref_audio_uri: str | None = None
-    if ref_audio:
-        ref_path = Path(ref_audio)
-        if not ref_path.is_file():
-            raise SystemExit(f"--ref-audio not found: {ref_audio}")
-        encoded = base64.b64encode(ref_path.read_bytes()).decode("ascii")
-        ref_audio_uri = f"data:audio/wav;base64,{encoded}"
-
-    @app.get("/", response_class=HTMLResponse)
-    def index() -> HTMLResponse:
-        config = json.dumps(
-            {
-                "model": model,
-                "realtimePath": public_realtime_url or "v1/realtime",
-                "refAudio": ref_audio_uri,
-                "appVersion": app_version,
-            },
-            ensure_ascii=True,
-        )
-        html = (
-            index_path.read_text(encoding="utf-8")
-            .replace("__FULL_DUPLEX_CONFIG__", config)
-            .replace("__FULL_DUPLEX_APP_VERSION__", app_version)
-        )
-        return HTMLResponse(html, headers={"Cache-Control": "no-store"})
-
-    @app.get("/healthz")
-    def healthz() -> Response:
-        return Response(content="ok", media_type="text/plain")
-
-    @app.websocket("/v1/realtime")
-    async def realtime_proxy(websocket: WebSocket) -> None:
-        await websocket.accept()
-        query = urlencode(websocket.query_params.multi_items())
-        backend_url = _join_ws_url(ws_backend, "/v1/realtime", query)
-        logger.info("Proxying Realtime WebSocket to %s", backend_url)
-        try:
-            async with websockets.connect(
-                backend_url,
-                max_size=64 * 1024 * 1024,
-            ) as backend:
-                tasks = {
-                    asyncio.create_task(_pump_client_to_backend(websocket, backend)),
-                    asyncio.create_task(_pump_backend_to_client(websocket, backend)),
-                }
-                done, pending = await asyncio.wait(
-                    tasks,
-                    return_when=asyncio.FIRST_COMPLETED,
-                )
-                for task in pending:
-                    task.cancel()
-                await asyncio.gather(*pending, return_exceptions=True)
-                for result in await asyncio.gather(*done, return_exceptions=True):
-                    if isinstance(result, BaseException) and not _expected_proxy_close(result):
-                        raise result
-        except (WebSocketDisconnect, websockets.ConnectionClosed):
-            return
-        except Exception:
-            logger.exception("Realtime WebSocket proxy failed")
-            with contextlib.suppress(Exception):
-                await websocket.close(code=1011)
-
-    app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
-    return app
+__all__ = ["APP_DIR", "STATIC_DIR", "_join_ws_url", "build_app", "main"]
 
 
 def main() -> None:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument("--host", default="0.0.0.0")
-    parser.add_argument("--port", type=int, default=7862)
-    parser.add_argument("--ws-backend", default="ws://127.0.0.1:8099")
-    parser.add_argument(
-        "--public-realtime-url",
-        help="Browser-visible ws:// or wss:// Realtime URL; defaults to the same-origin proxy.",
-    )
-    parser.add_argument("--model", default="openbmb/MiniCPM-o-4_5")
-    parser.add_argument(
-        "--ref-audio",
-        required=True,
-        help=(
-            "Reference voice wav for TTS voice cloning, e.g. the "
-            "official MiniCPM-o-Demo assets/ref_audio/ref_minicpm_signature.wav"
-        ),
-    )
-    args = parser.parse_args()
-
-    logging.basicConfig(level=logging.INFO)
-    uvicorn.run(
-        build_app(
-            ws_backend=args.ws_backend,
-            model=args.model,
-            public_realtime_url=args.public_realtime_url,
-            ref_audio=args.ref_audio,
-        ),
-        host=args.host,
-        port=args.port,
-        log_level="info",
-    )
+    _main(default_profile="minicpm-native")
 
 
 if __name__ == "__main__":
diff --git a/examples/online_serving/qwen3_omni/README.md b/examples/online_serving/qwen3_omni/README.md
index 8d6014db240..5eb9a2042e7 100644
--- a/examples/online_serving/qwen3_omni/README.md
+++ b/examples/online_serving/qwen3_omni/README.md
@@ -320,24 +320,17 @@ python openai_realtime_client.py \
 Server VAD uses the pinned Silero v6.2 ONNX artifact from `istupakov/silero-vad-onnx` and never downloads model files while processing a session. Make the artifact available in the Hugging Face cache before startup, or configure a local artifact in the deployment YAML:
 
 ```yaml
+base_config: /path/to/vllm-omni/vllm_omni/deploy/qwen3_omni_duplex.yaml
 duplex_session:
   server_vad_model_path: /models/silero_vad.onnx
 ```
 
-Start from the bundled Qwen3-Omni deployment YAML, add the fields above at the top level, and serve that complete configuration:
-
-```bash
-cp vllm_omni/deploy/qwen3_omni_moe.yaml /path/to/qwen3_omni_server_vad.yaml
-# Edit /path/to/qwen3_omni_server_vad.yaml and add duplex_session.
-vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct \
-  --omni \
-  --port 8091 \
-  --deploy-config /path/to/qwen3_omni_server_vad.yaml
-```
-
-Keep Qwen's default `session_mode: turn`; `duplex_session` enables the Realtime handler without changing scheduler
-semantics. Bare `/v1/realtime` selects that handler. The client uses `?duplex=0` only for the existing non-Server-VAD
-wire flow; `?duplex=1` remains a supported compatibility alias.
+For the engine-owned plugin, use an overlay based on
+`vllm_omni/deploy/qwen3_omni_duplex.yaml`, with `duplex_session.server_vad_model_path`
+pointing to your local artifact. See the [complete duplex setup](../realtime_web/README.md#qwen3-with-server-vad-automatic-turns).
+The default `qwen3_omni_moe.yaml` remains a turn deployment. Duplex mode serves
+`/v1/realtime?duplex=1` and `/v1/chat/completions`; the legacy STT handler requires
+a turn deployment.
 
 The Python client supports the following command-line arguments:
 
@@ -584,3 +577,53 @@ The gradio script supports the following arguments:
 - `--ip`: Host/IP for Gradio server (default: 127.0.0.1)
 - `--port`: Port for Gradio server (default: 7861)
 - `--share`: Share the Gradio demo publicly (creates a public link)
+
+## Browser voice call (shared realtime UI)
+
+Run these commands from the repository root with the vLLM-Omni environment activated.
+
+### Without VAD: manually submit each turn
+
+Start the backend:
+
+```bash
+vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
+```
+
+In another terminal, check backend readiness and start the UI:
+
+```bash
+curl --fail http://127.0.0.1:8091/health
+python -m examples.online_serving.qwen3_omni.realtime_web \
+    --backend ws://127.0.0.1:8091 --stt --port 7863
+```
+
+Open `http://localhost:7863`, start a session, speak, and press **Send turn**.
+`--stt` is the default. Each turn uses a separate connection without shared model
+history; the conversation shown in the browser is a local log.
+
+### With VAD: automatically submit after silence
+
+Start the backend with a Server VAD deployment overlay and a compatible Silero
+ONNX artifact, following the
+[complete VAD setup](../realtime_web/README.md#qwen3-with-server-vad-automatic-turns).
+After its health check succeeds, start the UI:
+
+```bash
+python -m examples.online_serving.qwen3_omni.realtime_web \
+    --backend ws://127.0.0.1:8091 --vad --port 7863
+```
+
+Speak and pause for 500 ms to submit automatically. `--vad` configures the client;
+it does not load a VAD model or change the backend deployment by itself.
+
+VAD mode keeps uploading audio during replies and supports speech interruption.
+The engine-owned Qwen duplex plugin maintains conversation history and tracks
+played replies through playback acknowledgements. Each committed utterance starts
+a new generation request; the model does not use native streaming-input KV decoding.
+STT mode pauses microphone upload while the reply is generated and played.
+In VAD mode, click **Camera** to upload sampled frames with your spoken question;
+see [camera setup and limits](../realtime_web/README.md#qwen-vad-camera-input).
+STT remains audio-only. To switch back to manual turns, use the default turn
+deployment, restart the UI with `--stt`, refresh the page, and reconnect. Stop the existing UI before reusing port 7863.
+See the [shared UI guide](../realtime_web/README.md) for HTTPS access and testing.
diff --git a/examples/online_serving/qwen3_omni/openai_realtime_client.py b/examples/online_serving/qwen3_omni/openai_realtime_client.py
index 0a98d69a0ac..2a6bca0fe5e 100644
--- a/examples/online_serving/qwen3_omni/openai_realtime_client.py
+++ b/examples/online_serving/qwen3_omni/openai_realtime_client.py
@@ -130,7 +130,7 @@ async def run_client(
                                 "prefix_padding_ms": 300,
                                 "silence_duration_ms": 500,
                                 "create_response": True,
-                                "interrupt_response": False,
+                                "interrupt_response": True,
                             },
                         }
                     },
@@ -233,6 +233,7 @@ async def run_client(
                 continue
 
             if event_type == "response.done" and server_vad:
+                await ws.send(json.dumps({"type": "session.close"}))
                 break
 
             if event_type == "error":
diff --git a/examples/online_serving/qwen3_omni/realtime_web/__init__.py b/examples/online_serving/qwen3_omni/realtime_web/__init__.py
new file mode 100644
index 00000000000..14c5daad216
--- /dev/null
+++ b/examples/online_serving/qwen3_omni/realtime_web/__init__.py
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Qwen3-Omni turn-based browser call UI."""
diff --git a/examples/online_serving/qwen3_omni/realtime_web/__main__.py b/examples/online_serving/qwen3_omni/realtime_web/__main__.py
new file mode 100644
index 00000000000..698179528c2
--- /dev/null
+++ b/examples/online_serving/qwen3_omni/realtime_web/__main__.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from examples.online_serving.realtime_web.server import main
+
+if __name__ == "__main__":
+    main(default_profile="qwen3-turn")
diff --git a/examples/online_serving/realtime_web/README.md b/examples/online_serving/realtime_web/README.md
new file mode 100644
index 00000000000..854aa4718c8
--- /dev/null
+++ b/examples/online_serving/realtime_web/README.md
@@ -0,0 +1,221 @@
+# Shared Realtime Web UI
+
+One browser shell provides microphone capture, speaker playback, a level meter,
+conversation text, and an event log. Model profiles own the wire protocol.
+This implements [RFC #7222](https://github.com/vllm-project/vllm-omni/issues/7222).
+
+| Profile | Turn control | Camera | Playback acknowledgement |
+| --- | --- | --- | --- |
+| `minicpm-native` | Model-controlled listen/speak, continuous audio input | Frames accompany audio | Yes |
+| `qwen3-turn --stt` (default) | User presses **Send turn** | No | No |
+| `qwen3-turn --vad` | Server detects trailing silence; speech interrupts replies | Sampled frames with each spoken turn | Yes |
+
+Qwen3 VAD uses an engine-owned duplex plugin: microphone upload continues
+while replies stream, and speech can interrupt generation and playback. The
+checkpoint still generates committed turns; this is not native streaming-input
+KV decoding. STT remains explicit-turn and audio-only.
+
+## MiniCPM: existing command stays valid
+
+Start your MiniCPM backend using the [existing deployment instructions](../minicpmo/README.md), then:
+
+```bash
+python -m examples.online_serving.minicpmo.realtime_web \
+    --ws-backend ws://127.0.0.1:8099 \
+    --ref-audio /path/to/ref_minicpm_signature.wav
+```
+
+The compatibility wrapper serves the shared assets with `minicpm-native`.
+The current native query, `extra_body`, reference voice, continuous microphone
+upload, camera frames and playback acknowledgements are retained.
+
+## Qwen3: explicit-turn STT adapter
+
+Start the backend, then the UI in a second terminal:
+
+```bash
+vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091
+
+python -m examples.online_serving.qwen3_omni.realtime_web \
+    --backend ws://127.0.0.1:8091 --stt --port 7863
+```
+
+Open `http://localhost:7863`, start a session, speak, and press **Send turn**.
+Wait for the answer to finish playing before speaking again. The UI opens a
+fresh STT connection for each turn; the displayed conversation is a local log,
+and **previous turns are not provided as model history**. The STT endpoint
+accepts only model selection, so system-prompt controls are hidden in this mode.
+
+The adapter follows the shipped `qwen3_omni/openai_realtime_client.py` and
+`vllm_omni/entrypoints/openai/realtime_connection.py`:
+
+1. Explicit `duplex=0` selects the legacy STT handler on a turn deployment.
+   It does not enable STT on a duplex deployment.
+2. Send `{type: "session.update", model: ...}` and `commit(final=false)`.
+3. Stream mono PCM16 at 16 kHz; **Send turn** flushes buffered audio, then sends `commit(final=true)`.
+4. `response.output_audio.delta.audio` contains PCM; `response.output_audio.done`
+   terminates this adapter, including a response with no audio.
+5. The local implementation emits **model output** on `transcription.*`, so the
+   UI displays it as assistant text. This differs from the early RFC's suggested
+   user-transcript mapping. The VAD adapter also supports `response.output_text.*`
+   and audio-transcript events without duplicating the answer.
+
+## Qwen3 with Server VAD (automatic turns)
+
+Run commands from the repository root with the vLLM-Omni environment activated.
+Prepare the pinned Silero v6.2 ONNX artifact as described in the
+[Qwen3 Server VAD instructions](../qwen3_omni/README.md#realtime-websocket-client-openai_realtime_clientpy).
+The backend requires ONNX Runtime and a compatible local artifact; setting
+`--vad` on the UI alone does not enable VAD on the backend.
+
+Create an overlay named `qwen3_vad.yaml`, replacing both paths with absolute paths
+on the backend host:
+
+```yaml
+base_config: /path/to/vllm-omni/vllm_omni/deploy/qwen3_omni_duplex.yaml
+duplex_session:
+  server_vad_model_path: /path/to/silero_vad.onnx
+```
+
+The base configuration enables duplex mode and sets the per-prompt audio and image limits.
+
+Start the backend:
+
+```bash
+vllm serve Qwen/Qwen3-Omni-30B-A3B-Instruct --omni --port 8091 \
+    --deploy-config qwen3_vad.yaml
+```
+
+In a second terminal, wait until the health check succeeds, then start the UI:
+
+```bash
+curl --fail http://127.0.0.1:8091/health
+python -m examples.online_serving.qwen3_omni.realtime_web \
+    --backend ws://127.0.0.1:8091 --vad --port 7863
+```
+
+Open `http://localhost:7863` and start a session. Speak and pause: the server
+commits the turn automatically after 500 ms of silence. No **Send turn** action
+is needed. Defaults are a speech threshold of 0.5 and 300 ms of prefix padding.
+Speak again to interrupt an answer. The engine owns input buffering, VAD,
+request cancellation, playback acknowledgements, and conversation history.
+Each committed utterance starts a normal Thinker → Talker → Code2Wav request;
+it does not append input to a live Qwen KV cache. The capability response reports
+`implementation_level: turn_based_duplex` and `supports_core_resumable_request: false`.
+
+The plugin retains up to four audio inputs (including the current turn), pruning
+older audio at an 8 MiB base64 budget; one current utterance is bounded by the
+engine's pending-input limit. The UI reports playback progress both on normal
+drain and on interruption. Qwen does not provide text/audio alignment, so assistant
+text enters history only after the complete audio response has been generated and
+acknowledged as played. A partially played answer contributes no guessed text
+prefix. Image conversation items remain available until deleted. Model context limits still apply.
+The bundled duplex deploy allows four audio inputs and eight images per prompt.
+Use headphones to avoid speaker audio triggering VAD interruption. Reference
+voices and tool calls are not supported by this plugin.
+
+### Switching between VAD and manual turns
+
+| Mode | Backend | UI flag | Submit a turn |
+| --- | --- | --- | --- |
+| Without VAD | Default Qwen turn deployment | `--stt` (default) | Press **Send turn** |
+| With VAD | Server VAD configuration and Silero artifact | `--vad` | Pause after speaking |
+
+Stop the existing UI process before starting another on the same port, then
+refresh the browser and reconnect. To use STT, start a backend with the default
+turn deployment and restart the UI with `--stt`. The duplex backend exposes
+Realtime duplex and ChatCompletion; it does not expose the legacy STT handler.
+To enable VAD on a default backend, first restart that backend with the overlay.
+Make `--backend` match the actual backend port; the UI and backend use separate
+ports. `Connection refused` means the target backend is unavailable: check its
+startup log and `/health` before connecting.
+
+VAD connects with `duplex=1` and sends nested `session.audio.input` configuration
+with `create_response: true` and `interrupt_response: true`. It sends playback
+ACKs when speaker audio drains. `response.audio.done` / `response.output_audio.done`
+only drain playback; `response.done` terminates a turn. Backpressure displays a
+notice without pausing the microphone. Failed handshakes time out after 15 seconds;
+Silero initialization failures display a specific error.
+
+After updating the backend Python code, restart the backend, refresh the UI, and
+start a new session so the plugin and browser assets use the updated code. A
+successful `/health` check confirms readiness, not which deployment mode is active.
+
+## Qwen VAD camera input
+
+After starting a session with `--vad`, click **Camera** and allow access. The UI
+sends one JPEG per second, resized to a longest side of 448 pixels, independently
+of microphone uploads (including while muted). Each frame is a user conversation
+item using the [OpenAI Realtime image input](https://developers.openai.com/api/docs/guides/realtime-conversations#image-inputs) shape:
+
+```json
+{"type":"conversation.item.create","item":{"id":"camera_1","type":"message","role":"user","content":[{"type":"input_image","image_url":"data:image/jpeg;base64,..."}]}}
+```
+
+Images become conversation context immediately; they do not start a response.
+Speak and let VAD commit your audio, or send `response.create` after adding an
+image/text item. A manual `input_audio_buffer.commit` only commits audio; follow
+it with `response.create` to generate. Images persist across audio commits,
+interruptions, and audio-buffer clears. Remove them with `conversation.item.delete`.
+The browser retains eight camera items and deletes the oldest before adding a
+ninth. Camera-off stops capture but leaves those items in the conversation.
+
+This deployment accepts JPEG/PNG Base64 data URLs with a total image-context
+budget of eight images and 4 MiB; external image URLs are not supported. Clients
+must delete old image items when reaching the limit. There is no precise
+video/audio timestamp alignment or native streaming-video KV update.
+
+### Protocol compatibility boundary
+
+Qwen VAD uses `session.update`, 24 kHz PCM16 `input_audio_buffer.append`,
+`conversation.item.create` with `input_image`/`input_text`, and `response.create`.
+The engine resamples input to Qwen's 16 kHz processing rate. Qwen rejects the
+custom `video_frames` field on an append: it answers whole turns, so it has no
+audio unit for a frame track to align to. MiniCPM keeps that field for its
+native camera protocol, where Stage 0 interleaves frames at unit boundaries.
+
+This is a supported subset, not full OpenAI Realtime API compatibility.
+`duplex=1`, `overlap_policy`, `playback.ack`, and `session.close` remain vLLM-Omni
+extensions. The legacy `--stt` mode is unchanged and is not the standard Realtime
+conversation API. This demo does not add WebRTC, semantic VAD, or tool calling.
+
+## Shared host options
+
+The shared entry point can select either profile explicitly:
+
+```bash
+python -m examples.online_serving.realtime_web --profile qwen3-turn \
+    --backend ws://127.0.0.1:8091 --stt --port 7863
+```
+
+- `--backend` / `--ws-backend`: backend WebSocket origin (not the full `/v1/realtime` URL).
+- `--model`: override the wrapper's model name.
+- `--public-realtime-url`: optional browser-visible WebSocket URL; otherwise the
+  static host proxies `/v1/realtime` on the same origin.
+- `--host`, `--port`: UI bind address and port (default port 7862).
+- `--ref-audio`: required for MiniCPM; rejected for Qwen3.
+
+Microphone and camera access require `localhost` or HTTPS. For a remote backend,
+use an SSH tunnel to the UI host or an HTTPS reverse proxy with WebSocket support.
+An explicit `wss://` public URL retains its scheme.
+
+## Validation
+
+```bash
+node --test tests/examples/test_realtime_web_profiles.cjs
+pytest tests/examples/test_minicpmo_realtime_web_server.py \
+       tests/examples/test_minicpmo_realtime_web_static.py \
+       tests/examples/test_realtime_web_profiles.py
+pytest -m cpu tests/model_executor/models/qwen3_omni/test_duplex_plugin.py \
+       tests/engine/duplex/test_session_runner.py \
+       tests/engine/test_duplex_orchestrator.py
+```
+
+These CPU tests cover profile messages, two STT turns, VAD terminal/drain ordering,
+backpressure, native capture during playback, server config injection, and shared
+worklets. Backend regressions cover current audio inclusion in history-based
+prompts, delayed playback ACK ordering, and no extra generation during silence
+after a completed VAD turn. Hardware acceptance still requires a MiniCPM call
+with camera/barge-in and two Qwen turns against each enabled backend, including
+speech interruption in VAD mode; simulated tests do not
+establish model quality or hardware latency.
diff --git a/examples/online_serving/realtime_web/__init__.py b/examples/online_serving/realtime_web/__init__.py
new file mode 100644
index 00000000000..9e82f896712
--- /dev/null
+++ b/examples/online_serving/realtime_web/__init__.py
@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Shared browser audio UI and model-specific realtime profiles."""
diff --git a/examples/online_serving/realtime_web/__main__.py b/examples/online_serving/realtime_web/__main__.py
new file mode 100644
index 00000000000..618f3c542fd
--- /dev/null
+++ b/examples/online_serving/realtime_web/__main__.py
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from .server import main
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/online_serving/minicpmo/realtime_web/app/index.html b/examples/online_serving/realtime_web/app/index.html
similarity index 76%
rename from examples/online_serving/minicpmo/realtime_web/app/index.html
rename to examples/online_serving/realtime_web/app/index.html
index 46ab1590772..a38a731e4bc 100644
--- a/examples/online_serving/minicpmo/realtime_web/app/index.html
+++ b/examples/online_serving/realtime_web/app/index.html
@@ -4,37 +4,35 @@
     <meta charset="utf-8">
     <meta name="viewport" content="width=device-width, initial-scale=1">
     <meta name="color-scheme" content="light">
-    <title>MiniCPM-o 4.5 Voice</title>
+    <title>Omni Realtime Voice</title>
     <link rel="stylesheet" href="static/styles.css">
   </head>
   <body>
     <header class="app-header">
       <div>
-        <p class="eyebrow">Experimental full-duplex runtime</p>
-        <h1>MiniCPM-o 4.5 Voice</h1>
+        <p id="pageEyebrow" class="eyebrow"></p>
+        <h1 id="pageTitle">Omni Realtime Voice</h1>
       </div>
       <span id="connectionState" class="status status-offline">Offline</span>
     </header>
 
     <main>
+      <p id="profileDescription" role="note"></p>
       <section class="call-bar" aria-label="Session controls">
         <div class="call-actions">
           <button id="callButton" class="primary" type="button">Start session</button>
+          <button id="sendTurnButton" class="secondary" type="button" hidden disabled>Send turn</button>
           <button id="muteButton" class="secondary" type="button" disabled>Mute</button>
           <button id="cameraButton" class="secondary" type="button" disabled>Camera</button>
           <video id="cameraPreview" muted playsinline style="display:none;width:96px;height:72px;border-radius:8px;object-fit:cover;background:#000"></video>
         </div>
-        <div style="display:flex;gap:8px;align-items:flex-start;margin-top:8px;width:100%">
+        <div id="promptControls" style="display:flex;gap:8px;align-items:flex-start;margin-top:8px;width:100%">
           <label style="display:inline-flex;flex-direction:column;gap:4px;font-size:13px;opacity:.85;white-space:nowrap">
             Prompt preset
             <select id="promptPreset" style="font-size:13px;padding:4px 6px;border-radius:6px">
-              <option value="omni" selected>Omni (official omni preset)</option>
-              <option value="chinese_call">中文通话 (official audio preset)</option>
-              <option value="english_call">English Call (official audio preset)</option>
-              <option value="custom">Custom</option>
             </select>
           </label>
-          <textarea id="systemPrompt" rows="2" placeholder="System prompt" style="flex:1;font-size:13px;padding:6px 8px;border-radius:6px;resize:vertical">Streaming Omni Conversation.</textarea>
+          <textarea id="systemPrompt" rows="2" placeholder="System prompt" style="flex:1;font-size:13px;padding:6px 8px;border-radius:6px;resize:vertical"></textarea>
         </div>
         <div class="meter" aria-label="Microphone level">
           <span>Mic</span>
@@ -53,7 +51,7 @@ <h1>MiniCPM-o 4.5 Voice</h1>
             <p class="eyebrow">Live transcript</p>
             <h2 id="conversationTitle">Conversation</h2>
           </div>
-          <span class="policy-label">Model-controlled listen / speak</span>
+          <span id="policyLabel" class="policy-label"></span>
         </div>
         <div id="conversation" class="conversation" aria-live="polite">
           <p id="emptyConversation" class="empty-state">Start a session and speak naturally.</p>
@@ -73,7 +71,10 @@ <h2 id="conversationTitle">Conversation</h2>
       </details>
     </main>
 
-    <script>window.FULL_DUPLEX_CONFIG = __FULL_DUPLEX_CONFIG__;</script>
+    <script>window.OMNI_REALTIME_CONFIG = __FULL_DUPLEX_CONFIG__; window.FULL_DUPLEX_CONFIG = window.OMNI_REALTIME_CONFIG;</script>
+    <script src="static/profiles/common.js?v=__FULL_DUPLEX_APP_VERSION__"></script>
+    <script src="static/profiles/minicpm_native.js?v=__FULL_DUPLEX_APP_VERSION__"></script>
+    <script src="static/profiles/qwen3_turn.js?v=__FULL_DUPLEX_APP_VERSION__"></script>
     <script src="static/app.js?v=__FULL_DUPLEX_APP_VERSION__"></script>
   </body>
 </html>
diff --git a/examples/online_serving/minicpmo/realtime_web/app/static/app.js b/examples/online_serving/realtime_web/app/static/app.js
similarity index 59%
rename from examples/online_serving/minicpmo/realtime_web/app/static/app.js
rename to examples/online_serving/realtime_web/app/static/app.js
index 4d2b782474c..4d9215ba0ac 100644
--- a/examples/online_serving/minicpmo/realtime_web/app/static/app.js
+++ b/examples/online_serving/realtime_web/app/static/app.js
@@ -1,8 +1,10 @@
 (() => {
   'use strict';
 
-  const config = window.FULL_DUPLEX_CONFIG || {};
+  const config = window.OMNI_REALTIME_CONFIG || window.FULL_DUPLEX_CONFIG || {};
+  const profile = window.OmniRealtimeProfiles[config.profile || 'minicpm-native'](config);
   const callButton = document.getElementById('callButton');
+  const sendTurnButton = document.getElementById('sendTurnButton');
   const muteButton = document.getElementById('muteButton');
   const cameraButton = document.getElementById('cameraButton');
   const cameraPreview = document.getElementById('cameraPreview');
@@ -27,20 +29,26 @@
   const INITIAL_PLAYBACK_BUFFER_MS = 400;
   const SESSION_CLOSE_TIMEOUT_MS = 1000;
 
-  // Default prompts mirroring the official MiniCPM-o-Demo presets
-  // (assets/presets/{omni,audio_duplex}/*.yaml).
-  const PROMPT_PRESETS = {
-    omni: 'Streaming Omni Conversation.',
-    chinese_call: '扮演一个具有以上声音特征的助手。请认真、高质量地回复用户的问题。'
-      + '请用高自然度的方式和用户聊天。你处于双工模式，可以一边听、一边说。'
-      + '你是由面壁智能开发的人工智能助手：面壁小钢炮。',
-    english_call: 'Replicate the tone and style from the input audio. Your task is to be '
-      + 'a helpful assistant using this voice pattern. Please answer the user\'s questions '
-      + 'seriously and in a high quality. Please chat with the user in a high naturalness '
-      + 'style. You are in duplex mode, where you can listen and speak at the same time.',
-  };
+  const PROMPT_PRESETS = profile.presets;
+  document.title = profile.title;
+  document.getElementById('pageTitle').textContent = profile.title;
+  document.getElementById('pageEyebrow').textContent = profile.eyebrow;
+  document.getElementById('profileDescription').textContent = profile.description;
+  document.getElementById('policyLabel').textContent = profile.policy;
+  cameraButton.hidden = !profile.camera;
+  sendTurnButton.hidden = !profile.clientCommit;
+  promptPreset.replaceChildren();
+  for (const name of [...Object.keys(PROMPT_PRESETS), 'custom']) {
+    const option = document.createElement('option');
+    option.value = name;
+    option.textContent = name.replaceAll('_', ' ');
+    promptPreset.appendChild(option);
+  }
+  systemPromptInput.value = Object.values(PROMPT_PRESETS)[0];
+  document.getElementById('promptControls').hidden = !profile.instructions;
 
   let socket = null;
+  let closingSocket = null;
   let mediaStream = null;
   let captureContext = null;
   let captureNode = null;
@@ -65,6 +73,63 @@
   let liveUserTurn = null;
   let liveAssistantTurn = null;
   let sessionCloseResolver = null;
+  let responseComplete = false;
+  let playbackComplete = true;
+  let turnSubmitted = false;
+  let echoTimer = null;
+  let sessionGeneration = 0;
+  let audioChain = Promise.resolve();
+  let assistantTextChannel = null;
+  let connectionReady = false;
+  let turnCounter = 0;
+  let stopping = null;
+  let turnTimeout = null;
+
+  function markBusy() {
+    assistantActive = true;
+    if (profile.halfDuplex) pendingCapture = [];
+  }
+
+  function armTurnTimeout() {
+    clearTimeout(turnTimeout);
+    turnTimeout = window.setTimeout(() => {
+      failSession('Timed out waiting for the model response. Check the backend event log and restart the session.');
+    }, 120000);
+  }
+
+  async function failSession(message) {
+    appendLog(message, true);
+    await stopSession({ terminal: false });
+    setConnection('Error', 'error');
+    runtimeDetail.textContent = message;
+  }
+
+  function finishResponseIfReady() {
+    if (!responseComplete || !playbackComplete || echoTimer !== null) return;
+    const generation = sessionGeneration;
+    echoTimer = window.setTimeout(async () => {
+      echoTimer = null;
+      if (!running || generation !== sessionGeneration) return;
+      if (profile.reconnectEachTurn) {
+        connectionReady = false;
+        const previous = socket;
+        socket = null;
+        if (previous) { previous.onclose = null; previous.onmessage = null; previous.close(); }
+        try { await openSocket(); }
+        catch (error) { await failSession(error.message); return; }
+        if (!running || generation !== sessionGeneration) return;
+      }
+      assistantActive = false;
+      responseComplete = false;
+      turnSubmitted = false;
+      currentResponseId = null;
+      responseHasAudio = false;
+      assistantTextChannel = null;
+      if (profile.halfDuplex) pendingCapture = [];
+      sendTurnButton.disabled = !profile.clientCommit;
+      setModel(profile.waiting);
+    }, ECHO_GUARD_MS);
+  }
 
   function staticAssetUrl(path) {
     const version = String(config.appVersion || '').trim();
@@ -82,12 +147,7 @@
   }
 
   function realtimeUrl() {
-    const url = new URL(config.realtimePath, window.location.href);
-    url.protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
-    url.searchParams.set('duplex', '1');
-    url.searchParams.set('model', config.model || 'openbmb/MiniCPM-o-4_5');
-    url.searchParams.set('autostart', '0');
-    return url.toString();
+    return profile.url(config, window.location.href);
   }
 
   function setConnection(label, kind) {
@@ -250,7 +310,7 @@
   }
 
   function microphoneUploadEnabled() {
-    return running && !muted;
+    return running && connectionReady && !muted && (!profile.halfDuplex || !assistantActive);
   }
 
   function flushCapture() {
@@ -267,19 +327,9 @@
       offset += chunk.length;
     }
     pendingCapture = [];
-    const pcm = resampleInt16(merged, captureRate, INPUT_RATE);
-    const appendEvent = {
-      type: 'input_audio_buffer.append',
-      audio: int16ToBase64(pcm),
-      format: 'pcm16',
-      sample_rate_hz: INPUT_RATE,
-    };
-    // Omni duplex: ~1 fps camera frame rides the audio append (official
-    // MiniCPM-o-Demo contract: one base64 JPEG per ~1 s chunk).
-    if (cameraPendingFrame) {
-      appendEvent.video_frames = [cameraPendingFrame];
-      cameraPendingFrame = null;
-    }
+    const pcm = resampleInt16(merged, captureRate, profile.inputSampleRate || INPUT_RATE);
+    const appendEvent = profile.append(int16ToBase64(pcm), cameraPendingFrame);
+    cameraPendingFrame = null;
     socket.send(JSON.stringify(appendEvent));
   }
 
@@ -287,13 +337,17 @@
     currentResponseId = responseId || currentResponseId;
     responseHasAudio = false;
     assistantActive = true;
-    setModel('Speaking');
+    responseComplete = false;
+    playbackComplete = true;
+    if (profile.halfDuplex) pendingCapture = [];
+    setModel(profile.halfDuplex ? 'Thinking' : 'Speaking');
   }
 
   function feedPlayback(decoded, responseId) {
     if (!decoded || !decoded.pcm || decoded.pcm.length === 0 || !playbackNode) return;
     const pcm = resampleInt16(decoded.pcm, decoded.sourceRate, playbackRate);
     responseHasAudio = true;
+    playbackComplete = false;
     assistantActive = true;
     setPlayback('Buffering');
     playbackNode.port.postMessage({
@@ -305,6 +359,7 @@
   }
 
   function requestPlaybackDrain(responseId) {
+    if (!responseHasAudio) { playbackComplete = true; finishResponseIfReady(); return; }
     if (!playbackNode) return;
     playbackNode.port.postMessage({ type: 'drain', responseId: responseId || currentResponseId });
   }
@@ -314,90 +369,118 @@
       if (!responseId && playedMs > 0) appendLog('playback ack skipped: missing response id', true);
       return;
     }
-    socket.send(JSON.stringify({
-      type: 'playback.ack',
-      response_id: responseId,
-      item_id: `item_${responseId}`,
-      played_ms: playedMs,
-      committed_ms: playedMs,
-    }));
+    const ack = profile.ack(responseId, playedMs);
+    if (ack) socket.send(JSON.stringify(ack));
   }
 
   function playbackDrained(message) {
     const responseId = message.responseId || currentResponseId;
-    sendPlaybackAck(responseId, Number(message.playedMs) || 0);
+    if (currentResponseId && responseId !== currentResponseId) return;
+    if (profile.playbackAck) sendPlaybackAck(responseId, Number(message.playedMs) || 0);
     setPlayback('Idle');
-    if (message.underrunMs > 0) {
-      appendLog(`playback underrun ${message.underrunMs} ms`);
+    playbackComplete = true;
+    if (message.underrunMs > 0) appendLog(`playback underrun ${message.underrunMs} ms`);
+    if (!profile.halfDuplex && !profile.waitForResponseDone) responseComplete = true;
+    finishResponseIfReady();
+  }
+
+  async function handleAudioEvent(action) {
+    markBusy();
+    currentResponseId = action.responseId || currentResponseId || `turn-${turnCounter}`;
+    setModel('Speaking');
+    const generation = sessionGeneration;
+    const decoded = await decodeAudioDelta(action.event);
+    if (generation === sessionGeneration) feedPlayback(decoded, currentResponseId);
+  }
+
+  function handleTranscriptEvent(action) {
+    if (action.role === 'assistant') {
+      // Qwen may emit both text and audio-transcript representations.
+      // Display one channel per response instead of duplicating the answer.
+      if (profile.deduplicateTranscript && assistantTextChannel && action.channel !== assistantTextChannel) return;
+      if (action.text) assistantTextChannel = action.channel || assistantTextChannel;
     }
-    window.setTimeout(() => {
-      assistantActive = false;
-      currentResponseId = null;
-      responseHasAudio = false;
-      if (running) setModel('Listening');
-    }, ECHO_GUARD_MS);
+    if (action.kind === 'text') addTranscript(action.role, action.text);
+    else if (profile.deduplicateTranscript && action.role === 'assistant') {
+      if (action.text) {
+        const turn = ensureTurn('assistant');
+        turn.value = action.text;
+        turn.text.textContent = action.text;
+      }
+    } else finishTranscript(action.role, action.text);
   }
 
-  function handleEvent(event) {
+  async function handleEvent(event) {
     appendEventLog(event);
-    const responseId = responseIdOf(event);
-    switch (event.type) {
-      case 'session.created':
-      case 'session.updated':
+    const action = profile.mapEvent(event);
+    const responseId = action.responseId;
+    switch (action.kind) {
+      case 'connected':
         setConnection('Connected', 'online');
-        setModel('Listening');
+        if (!assistantActive) setModel(profile.waiting);
         break;
-      case 'response.listen':
+      case 'interrupt':
+        sessionGeneration += 1;
+        // A cancelled response never reaches 'done', so nothing else would
+        // disarm the turn watchdog it left armed.
+        clearTimeout(turnTimeout);
+        if (playbackNode) playbackNode.port.postMessage({ type: 'clear' });
+        responseComplete = true;
+        playbackComplete = true;
+        responseHasAudio = false;
         assistantActive = false;
-        setModel('Listening');
+        currentResponseId = null;
+        assistantTextChannel = null;
+        finishTranscript('assistant');
+        setPlayback('Idle');
+        setModel(profile.waiting);
         break;
-      case 'response.created':
-      case 'response.speak':
+      case 'listen':
+        assistantActive = false;
+        setModel(profile.waiting);
+        break;
+      case 'begin':
+        if (profile.halfDuplex) armTurnTimeout();
+        if (echoTimer !== null) { clearTimeout(echoTimer); echoTimer = null; }
         beginAssistant(responseId);
         break;
-      case 'response.output_audio.delta':
-        currentResponseId = responseId || currentResponseId;
-        assistantActive = true;
-        setModel('Speaking');
-        decodeAudioDelta(event)
-          .then((decoded) => feedPlayback(decoded, responseId))
-          .catch((error) => appendLog(`audio decode failed: ${error.message || error}`, true));
+      case 'audio':
+        await handleAudioEvent(action);
         break;
-      case 'response.output_audio.done':
+      case 'drain':
         requestPlaybackDrain(responseId);
         break;
-      case 'response.output_audio_transcript.delta':
-        addTranscript('assistant', event.delta || '');
-        break;
-      case 'response.output_audio_transcript.done':
-        finishTranscript('assistant', event.transcript || '');
+      case 'text': case 'text-final':
+        handleTranscriptEvent(action);
         break;
-      case 'conversation.item.input_audio_transcription.delta':
-        addTranscript('user', event.delta || '');
-        break;
-      case 'conversation.item.input_audio_transcription.completed':
-        finishTranscript('user', event.transcript || '');
-        break;
-      case 'response.done':
+      case 'done':
+        clearTimeout(turnTimeout);
+        responseComplete = true;
         finishTranscript('assistant');
-        if (!responseHasAudio) requestPlaybackDrain(responseId);
+        requestPlaybackDrain(responseId);
+        finishResponseIfReady();
         break;
-      case 'playback.acknowledged':
-        {
-          const acknowledgement = event.event || event;
-          runtimeDetail.textContent = `Playback committed ${acknowledgement.committed_ms || 0} ms`;
-        }
+      case 'backpressure':
+        armTurnTimeout();
+        markBusy();
+        setModel('Thinking / Speaking');
+        runtimeDetail.textContent = action.message;
+        break;
+      case 'ack':
+        runtimeDetail.textContent = `Playback committed ${action.committedMs} ms`;
         break;
-      case 'session.closed':
+      case 'closed':
         if (sessionCloseResolver) sessionCloseResolver();
         sessionCloseResolver = null;
         break;
       case 'error':
-        setConnection('Error', 'error');
-        runtimeDetail.textContent = String(event.error || event.code || 'Server error');
-        break;
-      default:
+        if (action.fatal) { await failSession(action.message); break; }
+        // A rejected frame or a refused update costs one operation, not the
+        // call: report it and keep listening.
+        appendLog(action.message, true);
+        runtimeDetail.textContent = action.message;
         break;
+      default: break;
     }
   }
 
@@ -406,8 +489,15 @@
     playbackRate = playbackContext.sampleRate;
     await playbackContext.audioWorklet.addModule(staticAssetUrl('static/playback_worklet.js'));
     playbackNode = new AudioWorkletNode(playbackContext, 'fullduplex-pcm-playback');
+    const currentPlaybackNode = playbackNode;
     playbackNode.port.onmessage = (message) => {
+      if (playbackNode !== currentPlaybackNode) return;
       if (message.data.type === 'playback-started') setPlayback('Playing');
+      else if (message.data.type === 'playback-stopped') {
+        // The old response may report after the next one has started. ACK its
+        // own cursor without changing the current response's UI state.
+        if (profile.playbackAck) sendPlaybackAck(message.data.responseId, Number(message.data.playedMs) || 0);
+      }
       else if (message.data.type === 'playback-drained') playbackDrained(message.data);
       else if (message.data.type === 'playback-underrun') {
         runtimeDetail.textContent = `Playback underrun ${message.data.underrunMs || 0} ms`;
@@ -451,48 +541,69 @@
   function openSocket() {
     return new Promise((resolve, reject) => {
       const url = realtimeUrl();
-      socket = new WebSocket(url);
+      const current = new WebSocket(url);
+      socket = current;
+      connectionReady = false;
+      turnCounter += 1;
       let settled = false;
-      socket.onopen = () => {
+      const timer = window.setTimeout(() => {
+        if (settled) return;
         settled = true;
-        const extraBody = {
-          auto_response: true,
-        };
-        const session = {
-          modalities: ['audio', 'text'],
-          voice: 'default',
-          extra_body: extraBody,
-        };
-        // Reference voice for TTS cloning, provided by the server via
-        // --ref-audio (mirrors the official demo's default ref audio).
-        if (config.refAudio) session.ref_audio = config.refAudio;
-        const instructions = systemPromptInput ? systemPromptInput.value.trim() : '';
-        if (instructions) session.instructions = instructions;
-        socket.send(JSON.stringify({ type: 'session.update', session }));
-        runtimeDetail.textContent = `${captureRate} Hz capture / ${playbackRate} Hz playback`;
+        current.onclose = null;
+        current.close();
+        reject(new Error(`Session handshake timed out. ${profile.connectionHint}`));
+      }, 15000);
+      const rejectOnce = (message) => {
+        clearTimeout(timer);
+        if (!settled) { settled = true; reject(new Error(message)); }
+      };
+      current.onopen = () => {
+        const instructions = systemPromptInput.value.trim();
+        for (const event of profile.initialMessages(config, instructions)) current.send(JSON.stringify(event));
         appendLog(`websocket open  ${url}`);
-        resolve();
       };
-      socket.onmessage = (message) => {
-        if (typeof message.data !== 'string') return;
-        try {
-          handleEvent(JSON.parse(message.data));
-        } catch (error) {
-          appendLog(`invalid server event: ${error.message || error}`, true);
+      current.onmessage = (message) => {
+        if (typeof message.data !== 'string' || (socket !== current && closingSocket !== current)) return;
+        let event;
+        try { event = JSON.parse(message.data); }
+        catch (error) {
+          if (socket !== current) return;
+          const detail = `Invalid server event: ${error.message}`;
+          if (!settled) rejectOnce(detail);
+          else void failSession(detail);
+          return;
         }
-      };
-      socket.onerror = () => {
-        if (!settled) {
+        // Shutdown has detached the active socket. Only its close acknowledgement
+        // may pass, directly: the event queue can itself be awaiting cleanup.
+        if (closingSocket === current) {
+          if (event?.type === 'session.closed' && sessionCloseResolver) sessionCloseResolver();
+          return;
+        }
+        const action = profile.mapEvent(event);
+        if (action.kind === 'error' && !settled) {
+          rejectOnce(action.message);
+          return;
+        }
+        if (event.type === profile.readyEvent && !settled) {
+          clearTimeout(timer);
           settled = true;
-          reject(new Error(`WebSocket connection failed: ${url}`));
+          connectionReady = true;
+          runtimeDetail.textContent = `${captureRate} Hz capture / ${playbackRate} Hz playback`;
+          resolve();
         }
+        // Serialize decoding with terminal events: a drain must never overtake
+        // an asynchronously decoded WAV chunk.
+        audioChain = audioChain.then(() => {
+          if (socket === current || action.kind === 'closed') return handleEvent(event);
+        }).catch((error) => failSession(`Server event failed: ${error.message}`));
       };
-      socket.onclose = (event) => {
+      current.onerror = () => rejectOnce(`WebSocket connection failed. ${profile.connectionHint}`);
+      current.onclose = (event) => {
+        clearTimeout(timer);
+        connectionReady = false;
         appendLog(`websocket closed  code=${event.code}`);
-        if (running) {
-          setConnection('Disconnected', 'error');
-          stopSession();
-        }
+        if (!settled) rejectOnce(`Connection closed before session ready. ${profile.connectionHint}`);
+        else if (running && socket === current) failSession(`Backend disconnected (${event.code}). ${profile.connectionHint}`);
       };
     });
   }
@@ -515,46 +626,59 @@
     setConnection('Connecting', 'connecting');
     runtimeDetail.textContent = 'Requesting microphone access';
     try {
+      sessionGeneration += 1;
+      audioChain = Promise.resolve();
       await openPlayback();
       await openCapture();
       await openSocket();
       running = true;
       muted = false;
       assistantActive = false;
-      sendTimer = window.setInterval(flushCapture, SEND_INTERVAL_MS);
+      sendTimer = window.setInterval(flushCapture, profile.sendIntervalMs || SEND_INTERVAL_MS);
       startClock();
       callButton.textContent = 'End session';
       callButton.classList.add('is-active');
       muteButton.disabled = false;
-      cameraButton.disabled = false;
+      cameraButton.disabled = !profile.camera;
+      sendTurnButton.disabled = !profile.clientCommit;
       setConnection('Connected', 'online');
-      setModel('Listening');
+      setModel(profile.waiting);
       appendLog('session started');
     } catch (error) {
       appendLog(`start failed: ${error.message || error}`, true);
+      await stopSession({ terminal: false });
       setConnection('Error', 'error');
       runtimeDetail.textContent = String(error.message || error);
-      await stopSession();
     } finally {
       callButton.disabled = false;
     }
   }
 
   async function startCamera() {
-    if (cameraStream) return;
+    if (!profile.camera || cameraStream) return;
     cameraStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
     cameraPreview.srcObject = cameraStream;
     cameraPreview.style.display = '';
     await cameraPreview.play().catch(() => {});
     // Official omni-duplex cadence: one JPEG (quality 0.7) per ~1 s chunk,
     // no client-side resize (the server normalizes at scale_resolution=448).
-    cameraTimer = window.setInterval(() => {
+    const captureCameraFrame = () => {
       if (!cameraStream || cameraPreview.videoWidth === 0) return;
-      cameraCanvas.width = cameraPreview.videoWidth;
-      cameraCanvas.height = cameraPreview.videoHeight;
-      cameraCanvas.getContext('2d').drawImage(cameraPreview, 0, 0);
-      cameraPendingFrame = cameraCanvas.toDataURL('image/jpeg', 0.7).split(',')[1];
-    }, 1000);
+      const scale = profile.cameraMaxDimension
+        ? Math.min(1, profile.cameraMaxDimension / Math.max(cameraPreview.videoWidth, cameraPreview.videoHeight)) : 1;
+      cameraCanvas.width = Math.max(1, Math.round(cameraPreview.videoWidth * scale));
+      cameraCanvas.height = Math.max(1, Math.round(cameraPreview.videoHeight * scale));
+      cameraCanvas.getContext('2d').drawImage(cameraPreview, 0, 0, cameraCanvas.width, cameraCanvas.height);
+      const frame = cameraCanvas.toDataURL('image/jpeg', 0.7).split(',')[1];
+      if (profile.imageMessages) {
+        if (connectionReady && socket?.readyState === WebSocket.OPEN) {
+          for (const event of profile.imageMessages(frame)) socket.send(JSON.stringify(event));
+        }
+      } else cameraPendingFrame = frame;
+    };
+    // Do not make the first spoken turn race a one-second timer.
+    captureCameraFrame();
+    cameraTimer = window.setInterval(captureCameraFrame, 1000);
     cameraButton.textContent = 'Camera off';
     cameraButton.classList.add('is-active');
     appendLog('camera on (1 fps omni frames)');
@@ -590,15 +714,32 @@
       const finish = () => {
         if (done) return;
         done = true;
+        clearTimeout(timer);
         if (sessionCloseResolver === finish) sessionCloseResolver = null;
         resolve();
       };
       sessionCloseResolver = finish;
-      window.setTimeout(finish, timeoutMs);
+      const timer = window.setTimeout(finish, timeoutMs);
     });
   }
 
-  async function stopSession({ terminal = true } = {}) {
+  function stopSession(options = {}) {
+    if (stopping) return stopping;
+    stopping = cleanupSession(options).finally(() => { stopping = null; });
+    return stopping;
+  }
+
+  async function cleanupSession({ terminal = true } = {}) {
+    sessionGeneration += 1;
+    connectionReady = false;
+    clearTimeout(echoTimer);
+    clearTimeout(turnTimeout);
+    echoTimer = null;
+    responseComplete = false;
+    playbackComplete = true;
+    turnSubmitted = false;
+    assistantTextChannel = null;
+    sendTurnButton.disabled = true;
     running = false;
     assistantActive = false;
     pendingCapture = [];
@@ -607,15 +748,16 @@
     sendTimer = null;
     clockTimer = null;
     if (socket) {
-      const closingSocket = socket;
+      closingSocket = socket;
       socket = null;
       closingSocket.onclose = null;
-      if (terminal && closingSocket.readyState === WebSocket.OPEN) {
+      if (terminal && profile.closeSession && closingSocket.readyState === WebSocket.OPEN) {
         const closed = waitForSessionClosed(closingSocket, SESSION_CLOSE_TIMEOUT_MS);
         closingSocket.send(JSON.stringify({ type: 'session.close' }));
         await closed;
       }
       closingSocket.close(1000, 'client stop');
+      closingSocket = null;
     }
     if (playbackNode) playbackNode.port.postMessage({ type: 'clear' });
     if (mediaStream) {
@@ -632,6 +774,8 @@
     playbackNode = null;
     currentResponseId = null;
     responseHasAudio = false;
+    finishTranscript('user');
+    finishTranscript('assistant');
     meterFill.style.width = '0%';
     sessionTimer.textContent = '00:00';
     callButton.textContent = 'Start session';
@@ -659,6 +803,18 @@
     if (running) stopSession();
     else startSession();
   });
+  sendTurnButton.addEventListener('click', () => {
+    if (!running || !connectionReady || !profile.clientCommit || turnSubmitted) return;
+    flushCapture();
+    for (const event of profile.commitMessages()) socket.send(JSON.stringify(event));
+    turnSubmitted = true;
+    responseComplete = false;
+    markBusy();
+    armTurnTimeout();
+    sendTurnButton.disabled = true;
+    setModel('Thinking');
+    appendLog('turn submitted');
+  });
   muteButton.addEventListener('click', toggleMute);
   clearLogButton.addEventListener('click', () => {
     eventLog.textContent = '';
diff --git a/examples/online_serving/minicpmo/realtime_web/app/static/pcm_worklet.js b/examples/online_serving/realtime_web/app/static/pcm_worklet.js
similarity index 100%
rename from examples/online_serving/minicpmo/realtime_web/app/static/pcm_worklet.js
rename to examples/online_serving/realtime_web/app/static/pcm_worklet.js
diff --git a/examples/online_serving/minicpmo/realtime_web/app/static/playback_worklet.js b/examples/online_serving/realtime_web/app/static/playback_worklet.js
similarity index 95%
rename from examples/online_serving/minicpmo/realtime_web/app/static/playback_worklet.js
rename to examples/online_serving/realtime_web/app/static/playback_worklet.js
index f0d3d42ae33..8aaa131c67a 100644
--- a/examples/online_serving/minicpmo/realtime_web/app/static/playback_worklet.js
+++ b/examples/online_serving/realtime_web/app/static/playback_worklet.js
@@ -39,6 +39,13 @@ class FullDuplexPcmPlayback extends AudioWorkletProcessor {
       }
       this.notifyIfDrained();
     } else if (message.type === 'clear') {
+      if (this.activeResponseId) {
+        this.port.postMessage({
+          type: 'playback-stopped',
+          responseId: this.activeResponseId,
+          playedMs: Math.round((this.playedFrames * 1000) / sampleRate),
+        });
+      }
       this.queue = [];
       this.offset = 0;
       this.playedFrames = 0;
diff --git a/examples/online_serving/realtime_web/app/static/profiles/common.js b/examples/online_serving/realtime_web/app/static/profiles/common.js
new file mode 100644
index 00000000000..feefbaa74b6
--- /dev/null
+++ b/examples/online_serving/realtime_web/app/static/profiles/common.js
@@ -0,0 +1,56 @@
+/* Shared wire helpers. Profiles translate server events into shell actions. */
+(function (root) {
+  'use strict';
+  const profiles = root.OmniRealtimeProfiles = root.OmniRealtimeProfiles || {};
+  profiles.url = (config, location) => {
+    const url = new URL(config.realtimePath || 'v1/realtime', location);
+    if (url.protocol === 'http:') url.protocol = 'ws:';
+    if (url.protocol === 'https:') url.protocol = 'wss:';
+    return url;
+  };
+  /* Errors that leave the session unusable, so the shell has to tear it down.
+     Everything else costs one operation --- a rejected image, a refused
+     session.update, a late playback ack --- and the call carries on.
+     'runtime_append_failed' is deliberately absent: the engine reports it and
+     keeps the session, unlike 'runtime_append_task_failed' which kills it. */
+  profiles.fatalErrorCodes = new Set([
+    'unknown_session',
+    'session_closed',
+    'resource_exhausted',
+    'unsupported',
+    'unsupported_turn_detection',
+    'server_vad_unavailable',
+    'runtime_append_task_failed',
+    'internal_error',
+  ]);
+  profiles.event = (event) => {
+    const responseId = event.response_id || event.response?.id || null;
+    const action = (kind, extra = {}) => ({ kind, responseId, ...extra });
+    switch (event.type) {
+      case 'session.created': case 'session.updated': return action('connected');
+      case 'response.created': return action('begin');
+      case 'response.audio.delta': case 'response.output_audio.delta':
+        return action('audio', { event: { ...event, delta: event.delta || event.audio || event.response?.audio } });
+      case 'response.audio.done': case 'response.output_audio.done': return action('drain');
+      case 'response.audio_transcript.delta': case 'response.output_audio_transcript.delta':
+        return action('text', { role: 'assistant', channel: 'audio', text: event.delta || '' });
+      case 'response.audio_transcript.done': case 'response.output_audio_transcript.done':
+        return action('text-final', { role: 'assistant', channel: 'audio', text: event.transcript || '' });
+      case 'conversation.item.input_audio_transcription.delta':
+        return action('text', { role: 'user', text: event.delta || '' });
+      case 'conversation.item.input_audio_transcription.completed':
+        return action('text-final', { role: 'user', text: event.transcript || '' });
+      case 'response.done': return action('done');
+      case 'session.closed': return action('closed');
+      case 'error': {
+        const code = event.code || event.error?.code;
+        return action('error', {
+          code,
+          fatal: profiles.fatalErrorCodes.has(code),
+          message: typeof event.error === 'string' ? event.error : event.error?.message || event.message || code || 'Server error',
+        });
+      }
+      default: return action('ignore');
+    }
+  };
+})(globalThis);
diff --git a/examples/online_serving/realtime_web/app/static/profiles/minicpm_native.js b/examples/online_serving/realtime_web/app/static/profiles/minicpm_native.js
new file mode 100644
index 00000000000..801d549be7a
--- /dev/null
+++ b/examples/online_serving/realtime_web/app/static/profiles/minicpm_native.js
@@ -0,0 +1,55 @@
+(function (root) {
+  'use strict';
+  const profiles = root.OmniRealtimeProfiles;
+  profiles['minicpm-native'] = () => ({
+    title: 'MiniCPM-o 4.5 Voice', eyebrow: 'Experimental full-duplex runtime',
+    policy: 'Model-controlled listen / speak',
+    description: 'Speak naturally. The model can listen and speak at the same time. Camera frames are sent with your audio.',
+    waiting: 'Listening', camera: true, playbackAck: true, clientCommit: false,
+    halfDuplex: false, closeSession: true, reconnectEachTurn: false,
+    readyEvent: 'session.updated', instructions: true, sendIntervalMs: 200,
+    presets: {
+      omni: 'Streaming Omni Conversation.',
+      chinese_call: '扮演一个具有以上声音特征的助手。请认真、高质量地回复用户的问题。'
+        + '请用高自然度的方式和用户聊天。你处于双工模式，可以一边听、一边说。'
+        + '你是由面壁智能开发的人工智能助手：面壁小钢炮。',
+      english_call: 'Replicate the tone and style from the input audio. Your task is to be '
+        + 'a helpful assistant using this voice pattern. Please answer the user\'s questions '
+        + 'seriously and in a high quality. Please chat with the user in a high naturalness '
+        + 'style. You are in duplex mode, where you can listen and speak at the same time.',
+    },
+    url(config, location) {
+      const url = profiles.url(config, location);
+      url.searchParams.set('duplex', '1');
+      url.searchParams.set('model', config.model || 'openbmb/MiniCPM-o-4_5');
+      url.searchParams.set('autostart', '0');
+      return url.toString();
+    },
+    initialMessages(config, instructions) {
+      const session = { modalities: ['audio', 'text'], voice: 'default',
+        extra_body: { auto_response: true } };
+      if (config.refAudio) session.ref_audio = config.refAudio;
+      if (instructions) session.instructions = instructions;
+      return [{ type: 'session.update', session }];
+    },
+    append(audio, frame) {
+      const event = { type: 'input_audio_buffer.append', audio, format: 'pcm16', sample_rate_hz: 16000 };
+      if (frame) event.video_frames = [frame];
+      return event;
+    },
+    commitMessages: () => [],
+    ack(responseId, playedMs) {
+      return { type: 'playback.ack', response_id: responseId, item_id: `item_${responseId}`,
+        played_ms: playedMs, committed_ms: playedMs };
+    },
+    mapEvent(event) {
+      if (event.type === 'response.listen') return { kind: 'listen' };
+      if (event.type === 'response.speak') return { kind: 'begin', responseId: event.response_id || event.response?.id };
+      if (event.type === 'playback.acknowledged') {
+        return { kind: 'ack', committedMs: (event.event || event).committed_ms || 0 };
+      }
+      return profiles.event(event);
+    },
+    connectionHint: 'Check the MiniCPM duplex deployment and reference voice configuration.',
+  });
+})(globalThis);
diff --git a/examples/online_serving/realtime_web/app/static/profiles/qwen3_turn.js b/examples/online_serving/realtime_web/app/static/profiles/qwen3_turn.js
new file mode 100644
index 00000000000..d6df32eddde
--- /dev/null
+++ b/examples/online_serving/realtime_web/app/static/profiles/qwen3_turn.js
@@ -0,0 +1,100 @@
+(function (root) {
+  'use strict';
+  const profiles = root.OmniRealtimeProfiles;
+  profiles['qwen3-turn'] = (config) => {
+    const vad = config.adapter === 'vad';
+    let imageSeq = 0;
+    let imageItems = [];
+    // The engine refuses a ninth image (or 4 MiB of them) for the whole
+    // session, so the camera track retires its own oldest frame instead.
+    const MAX_IMAGE_ITEMS = 8;
+    const hint = 'This Qwen deploy needs session_mode: duplex and Server VAD support; use --stt or enable Server VAD.';
+    return {
+      title: 'Qwen3-Omni Voice', eyebrow: vad ? 'Engine-owned duplex call' : 'Turn-based realtime call',
+      policy: vad ? 'Server VAD • interruptible responses' : 'Send turn • one response at a time',
+      description: vad
+        ? 'Pause to send your turn; speak again to interrupt. Microphone upload continues during playback. Requires the Qwen duplex plugin and Silero. Optional camera frames accompany each spoken turn.'
+        : 'Speak, then press Send turn. Microphone upload pauses while the model answers. Each turn uses a fresh connection; conversation history is not carried between turns. No barge-in or camera input.',
+      waiting: 'Waiting for you', camera: vad, cameraMaxDimension: 448, playbackAck: vad, clientCommit: !vad,
+      waitForResponseDone: true, halfDuplex: !vad, deduplicateTranscript: true, closeSession: vad, reconnectEachTurn: !vad,
+      inputSampleRate: vad ? 24000 : 16000,
+      readyEvent: vad ? 'session.updated' : 'session.created', instructions: vad, sendIntervalMs: 200,
+      presets: { assistant: 'You are a helpful assistant. Answer clearly and concisely.' },
+      url(config, location) {
+        const url = profiles.url(config, location);
+        for (const key of ['native_duplex', 'minicpmo45_native_duplex', 'autostart']) url.searchParams.delete(key);
+        // Explicit opt-out matches the local file client, including servers
+        // that auto-select the duplex endpoint when the query is omitted.
+        url.searchParams.set('duplex', vad ? '1' : '0');
+        url.searchParams.set('model', config.model || 'Qwen/Qwen3-Omni-30B-A3B-Instruct');
+        return url.toString();
+      },
+      initialMessages(config, instructions) {
+        imageItems = [];
+        if (!vad) return [
+          { type: 'session.update', model: config.model },
+          { type: 'input_audio_buffer.commit', final: false },
+        ];
+        const session = { model: config.model, overlap_policy: 'barge_in_on_speech', audio: { input: {
+          format: { type: 'audio/pcm', rate: 24000 },
+          turn_detection: { type: 'server_vad', threshold: 0.5, prefix_padding_ms: 300,
+            silence_duration_ms: 500, create_response: true, interrupt_response: true },
+        } } };
+        if (instructions) session.instructions = instructions;
+        return [{ type: 'session.update', session }];
+      },
+      append(audio) {
+        return vad ? { type: 'input_audio_buffer.append', audio }
+          : { type: 'input_audio_buffer.append', audio, format: 'pcm16', sample_rate_hz: 16000 };
+      },
+      // Qwen is a turn model: a frame is a picture added to the conversation,
+      // not a track interleaved into the audio. That is exactly the OpenAI
+      // Realtime image interface, so the camera sends conversation items
+      // rather than an extension field on the append.
+      imageMessages(frame) {
+        if (!vad) return [];
+        const messages = [];
+        if (imageItems.length >= MAX_IMAGE_ITEMS) {
+          // Retire before creating: the engine counts what is already stored.
+          messages.push({ type: 'conversation.item.delete', item_id: imageItems.shift() });
+        }
+        const id = `camera_${++imageSeq}`;
+        imageItems.push(id);
+        messages.push({ type: 'conversation.item.create', item: {
+          id, type: 'message', role: 'user',
+          content: [{ type: 'input_image', image_url: `data:image/jpeg;base64,${frame}` }],
+        } });
+        return messages;
+      },
+      commitMessages: () => vad ? [] : [{ type: 'input_audio_buffer.commit', final: true }],
+      ack: (responseId, playedMs) => vad ? { type: 'playback.ack', response_id: responseId,
+        item_id: `item_${responseId}`, played_ms: playedMs, committed_ms: playedMs } : null,
+      mapEvent(event) {
+        if (event.type === 'playback.acknowledged') return { kind: 'ack', committedMs: (event.event || event).committed_ms || 0 };
+        if (event.type === 'response.output_text.delta' || event.type === 'transcription.delta') {
+          // On the shipped STT route transcription.* is model-generated text,
+          // not a separate ASR transcript of the user. See realtime_connection.py.
+          return { kind: 'text', role: 'assistant', channel: 'text', text: event.delta || '' };
+        }
+        if (event.type === 'response.output_text.done' || event.type === 'transcription.done') {
+          return { kind: 'text-final', role: 'assistant', channel: 'text', text: event.text || '' };
+        }
+        if (vad && (event.type === 'output_audio_buffer.cleared' ||
+            (event.type === 'response.done' && event.response?.status === 'cancelled'))) {
+          return { kind: 'interrupt' };
+        }
+        if (event.type === 'input_audio_buffer.committed') return { kind: 'begin' };
+        if (event.type === 'input_audio_buffer.cleared') return { kind: 'backpressure', message: 'Input cleared. Model is answering; please wait.' };
+        if (!vad && event.type === 'response.output_audio.done') return { kind: 'done' };
+        const action = profiles.event(event);
+        if (action.kind === 'error') {
+          if (action.code === 'input_backpressure') return { ...action, kind: 'backpressure', message: 'Input buffer is full; please repeat dropped speech after the response.' };
+          if (action.code === 'server_vad_initialization_failed') action.message = 'Server VAD could not load Silero. Configure the server artifact or restart this UI with --stt.';
+          else if (vad && action.code === 'unsupported') action.message += ` ${hint}`;
+        }
+        return action;
+      },
+      connectionHint: vad ? hint : 'Check the Qwen /v1/realtime STT endpoint and model name.',
+    };
+  };
+})(globalThis);
diff --git a/examples/online_serving/minicpmo/realtime_web/app/static/styles.css b/examples/online_serving/realtime_web/app/static/styles.css
similarity index 98%
rename from examples/online_serving/minicpmo/realtime_web/app/static/styles.css
rename to examples/online_serving/realtime_web/app/static/styles.css
index 9b080176b85..bf25c3effcc 100644
--- a/examples/online_serving/minicpmo/realtime_web/app/static/styles.css
+++ b/examples/online_serving/realtime_web/app/static/styles.css
@@ -125,3 +125,6 @@ button:disabled { opacity: .46; cursor: default; }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: .01ms !important; animation-iteration-count: 1 !important; }
 }
+
+/* Profile-specific controls may have inline flex styles. */
+[hidden] { display: none !important; }
diff --git a/examples/online_serving/realtime_web/server.py b/examples/online_serving/realtime_web/server.py
new file mode 100644
index 00000000000..85e4b63d54b
--- /dev/null
+++ b/examples/online_serving/realtime_web/server.py
@@ -0,0 +1,229 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Static host and same-origin proxy for the shared realtime browser UI."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import base64
+import contextlib
+import hashlib
+import json
+import logging
+from pathlib import Path
+from urllib.parse import urlencode
+
+import uvicorn
+import websockets
+from fastapi import FastAPI, WebSocket, WebSocketDisconnect
+from fastapi.responses import HTMLResponse, Response
+from fastapi.staticfiles import StaticFiles
+
+logger = logging.getLogger(__name__)
+APP_DIR = Path(__file__).parent / "app"
+STATIC_DIR = APP_DIR / "static"
+
+
+def _join_ws_url(base: str, path: str, query: str) -> str:
+    return base.rstrip("/") + path + (("?" + query) if query else "")
+
+
+async def _pump_client_to_backend(client: WebSocket, backend) -> None:
+    try:
+        while True:
+            message = await client.receive()
+            if message["type"] == "websocket.disconnect":
+                await backend.close()
+                return
+            if message.get("text") is not None:
+                await backend.send(message["text"])
+            elif message.get("bytes") is not None:
+                await backend.send(message["bytes"])
+    except (WebSocketDisconnect, websockets.ConnectionClosed):
+        with contextlib.suppress(Exception):
+            await backend.close()
+
+
+async def _pump_backend_to_client(client: WebSocket, backend) -> None:
+    try:
+        async for message in backend:
+            if isinstance(message, bytes):
+                await client.send_bytes(message)
+            else:
+                await client.send_text(message)
+    except (WebSocketDisconnect, websockets.ConnectionClosed):
+        return
+    except RuntimeError as exc:
+        if "websocket.send" in str(exc) and "websocket.close" in str(exc):
+            return
+        raise
+
+
+def _expected_proxy_close(exc: BaseException) -> bool:
+    if isinstance(exc, (WebSocketDisconnect, websockets.ConnectionClosed, asyncio.CancelledError)):
+        return True
+    return isinstance(exc, RuntimeError) and "websocket.send" in str(exc) and "websocket.close" in str(exc)
+
+
+def build_app(
+    *,
+    ws_backend: str | None = None,
+    model: str | None = None,
+    public_realtime_url: str | None = None,
+    ref_audio: str | None = None,
+    profile: str = "minicpm-native",
+    adapter: str = "stt",
+) -> FastAPI:
+    if profile not in {"minicpm-native", "qwen3-turn"}:
+        raise ValueError(f"Unknown profile: {profile}")
+    if adapter not in {"stt", "vad"}:
+        raise ValueError(f"Unknown adapter: {adapter}")
+    if profile == "qwen3-turn" and ref_audio:
+        raise ValueError("Qwen3 profile does not accept --ref-audio")
+    native = profile == "minicpm-native"
+    ws_backend = ws_backend or ("ws://127.0.0.1:8099" if native else "ws://127.0.0.1:8091")
+    model = model or ("openbmb/MiniCPM-o-4_5" if native else "Qwen/Qwen3-Omni-30B-A3B-Instruct")
+    app = FastAPI(title="Omni Realtime Web UI")
+    index_path = APP_DIR / "index.html"
+    app_version_hash = hashlib.sha256()
+    for asset_path in (
+        STATIC_DIR / "app.js",
+        STATIC_DIR / "pcm_worklet.js",
+        STATIC_DIR / "playback_worklet.js",
+        *sorted((STATIC_DIR / "profiles").glob("*.js")),
+    ):
+        app_version_hash.update(asset_path.read_bytes())
+    app_version = app_version_hash.hexdigest()[:12]
+
+    ref_audio_uri: str | None = None
+    if ref_audio:
+        ref_path = Path(ref_audio)
+        if not ref_path.is_file():
+            raise SystemExit(f"--ref-audio not found: {ref_audio}")
+        encoded = base64.b64encode(ref_path.read_bytes()).decode("ascii")
+        ref_audio_uri = f"data:audio/wav;base64,{encoded}"
+
+    @app.get("/", response_class=HTMLResponse)
+    def index() -> HTMLResponse:
+        config = json.dumps(
+            {
+                "model": model,
+                "profile": profile,
+                "adapter": adapter,
+                "realtimePath": public_realtime_url or "v1/realtime",
+                "refAudio": ref_audio_uri,
+                "appVersion": app_version,
+            },
+            ensure_ascii=True,
+        ).replace("<", "\\u003c")
+        html = (
+            index_path.read_text(encoding="utf-8")
+            .replace("__FULL_DUPLEX_CONFIG__", config)
+            .replace("__FULL_DUPLEX_APP_VERSION__", app_version)
+        )
+        return HTMLResponse(html, headers={"Cache-Control": "no-store"})
+
+    @app.get("/healthz")
+    def healthz() -> Response:
+        return Response(content="ok", media_type="text/plain")
+
+    @app.websocket("/v1/realtime")
+    async def realtime_proxy(websocket: WebSocket) -> None:
+        await websocket.accept()
+        query = urlencode(websocket.query_params.multi_items())
+        backend_url = _join_ws_url(ws_backend, "/v1/realtime", query)
+        logger.info("Proxying Realtime WebSocket to %s", backend_url)
+        try:
+            async with websockets.connect(
+                backend_url,
+                max_size=64 * 1024 * 1024,
+            ) as backend:
+                tasks = {
+                    asyncio.create_task(_pump_client_to_backend(websocket, backend)),
+                    asyncio.create_task(_pump_backend_to_client(websocket, backend)),
+                }
+                done, pending = await asyncio.wait(
+                    tasks,
+                    return_when=asyncio.FIRST_COMPLETED,
+                )
+                for task in pending:
+                    task.cancel()
+                await asyncio.gather(*pending, return_exceptions=True)
+                for result in await asyncio.gather(*done, return_exceptions=True):
+                    if isinstance(result, BaseException) and not _expected_proxy_close(result):
+                        raise result
+        except (WebSocketDisconnect, websockets.ConnectionClosed):
+            return
+        except (OSError, TimeoutError) as exc:
+            message = (
+                f"Cannot connect to realtime backend {ws_backend}. "
+                "Check that vllm serve is running and --backend matches its --port. "
+                "For containers or remote hosts, use the backend address reachable from the UI server."
+            )
+            logger.warning("%s (%s)", message, exc)
+            with contextlib.suppress(Exception):
+                await websocket.send_json({"type": "error", "code": "backend_unavailable", "error": message})
+                await websocket.close(code=1011)
+        except Exception:
+            logger.exception("Realtime WebSocket proxy failed")
+            with contextlib.suppress(Exception):
+                await websocket.close(code=1011)
+        finally:
+            with contextlib.suppress(Exception):
+                await websocket.close()
+
+    app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+    return app
+
+
+def main(default_profile: str = "minicpm-native") -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=7862)
+    parser.add_argument("--profile", choices=("minicpm-native", "qwen3-turn"), default=default_profile)
+    parser.add_argument("--ws-backend", "--backend", dest="ws_backend")
+    mode = parser.add_mutually_exclusive_group()
+    mode.add_argument("--stt", dest="adapter", action="store_const", const="stt")
+    mode.add_argument("--vad", dest="adapter", action="store_const", const="vad")
+    parser.set_defaults(adapter="stt")
+    parser.add_argument(
+        "--public-realtime-url",
+        help="Browser-visible ws:// or wss:// Realtime URL; defaults to the same-origin proxy.",
+    )
+    parser.add_argument("--model")
+    parser.add_argument(
+        "--ref-audio",
+        help=(
+            "Reference voice wav for TTS voice cloning, e.g. the "
+            "official MiniCPM-o-Demo assets/ref_audio/ref_minicpm_signature.wav"
+        ),
+    )
+    args = parser.parse_args()
+    native = args.profile == "minicpm-native"
+    if native and not args.ref_audio:
+        parser.error("--ref-audio is required for the minicpm-native profile")
+    if not native and args.ref_audio:
+        parser.error("--ref-audio is only supported by minicpm-native")
+    args.model = args.model or ("openbmb/MiniCPM-o-4_5" if native else "Qwen/Qwen3-Omni-30B-A3B-Instruct")
+    args.ws_backend = args.ws_backend or ("ws://127.0.0.1:8099" if native else "ws://127.0.0.1:8091")
+
+    logging.basicConfig(level=logging.INFO)
+    uvicorn.run(
+        build_app(
+            ws_backend=args.ws_backend,
+            model=args.model,
+            public_realtime_url=args.public_realtime_url,
+            ref_audio=args.ref_audio,
+            profile=args.profile,
+            adapter=args.adapter,
+        ),
+        host=args.host,
+        port=args.port,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/config/test_environment_variables.py b/tests/config/test_environment_variables.py
index b7306268903..eb073f0c72a 100644
--- a/tests/config/test_environment_variables.py
+++ b/tests/config/test_environment_variables.py
@@ -167,7 +167,7 @@ def test_inventory_matches_reviewed_snapshot_counts():
         EnvironmentVariableCategory.PUBLIC_OMNI: 28,
         EnvironmentVariableCategory.INHERITED_VLLM: 20,
         EnvironmentVariableCategory.PLATFORM_EXTERNAL: 27,
-        EnvironmentVariableCategory.MODEL_SPECIFIC: 64,
+        EnvironmentVariableCategory.MODEL_SPECIFIC: 65,
         EnvironmentVariableCategory.BENCHMARK_TRANSITIONAL: 20,
         EnvironmentVariableCategory.INTERNAL: 2,
     }
@@ -181,7 +181,7 @@ def test_inventory_matches_reviewed_snapshot_counts():
         ModelEnvironmentVariableDisposition.PROMOTE: 38,
         ModelEnvironmentVariableDisposition.REQUEST_SCOPE: 6,
         ModelEnvironmentVariableDisposition.EXTERNAL: 0,
-        ModelEnvironmentVariableDisposition.INTERNALIZE: 15,
+        ModelEnvironmentVariableDisposition.INTERNALIZE: 16,
         ModelEnvironmentVariableDisposition.DEPRECATE_REMOVE: 5,
     }
 
diff --git a/tests/engine/duplex/test_engine_session.py b/tests/engine/duplex/test_engine_session.py
index fccaa59e887..c90291a8130 100644
--- a/tests/engine/duplex/test_engine_session.py
+++ b/tests/engine/duplex/test_engine_session.py
@@ -567,10 +567,10 @@ def test_overlap_policy_defaults_and_invalid_values_to_listen_only():
     assert DuplexSessionConfig.from_event({"session": {"overlap_policy": "bogus"}}).overlap_policy == "listen_only"
 
 
-def test_capabilities_as_dict_reports_model_native_duplex_constants():
+def test_capabilities_as_dict_reports_declared_implementation():
     caps = DuplexCapabilities().as_dict()
 
-    assert caps["implementation_level"] == "model_native_duplex"
+    assert caps["implementation_level"] == "turn_based_duplex"
     assert caps["input_modes"] == ["append_audio_chunk"]
     assert caps["supports_kv_lease"] is False
     assert caps["supports_core_kv_lease"] is False
diff --git a/tests/engine/duplex/test_session_manager.py b/tests/engine/duplex/test_session_manager.py
index 4f1962ee599..bccce18f1b6 100644
--- a/tests/engine/duplex/test_session_manager.py
+++ b/tests/engine/duplex/test_session_manager.py
@@ -196,7 +196,7 @@ def create_session_state(self) -> DuplexModelSessionState:
 
     def capabilities(self, *, max_sessions: int) -> DuplexCapabilities:
         del max_sessions
-        return DuplexCapabilities(supports_input_append=True)
+        return DuplexCapabilities(supports_input_append=True, supports_core_resumable_request=True)
 
     def validate_client_extra_body(self, extra_body: object) -> None:
         pass
@@ -408,7 +408,9 @@ async def test_open_answers_with_capabilities_and_emits_session_created() -> Non
         assert result.control_id == "open-sid-open"
         assert result.session_id == "sid-open"
         assert result.lease_generation == 0
-        assert result.capabilities == DuplexCapabilities(supports_input_append=True)
+        assert result.capabilities == DuplexCapabilities(
+            supports_input_append=True, supports_core_resumable_request=True
+        )
         assert result.public_session is not None
         assert result.public_session["id"] == "sid-open"
         assert result.public_session["voice"] == "test"
diff --git a/tests/engine/duplex/test_vad_backend.py b/tests/engine/duplex/test_vad_backend.py
index 8a22259acb4..f3163ff4e28 100644
--- a/tests/engine/duplex/test_vad_backend.py
+++ b/tests/engine/duplex/test_vad_backend.py
@@ -107,8 +107,8 @@ def test_endpoint_decisions_match_the_serving_side_policy(
 # --------------------------------------------------------------------------- #
 
 
-def test_a_loud_frame_does_not_restart_the_silence_timer() -> None:
-    """Silero v6.2 hysteresis: once silence is running, a loud frame only delays it.
+def test_hysteresis_band_does_not_restart_the_silence_timer() -> None:
+    """Scores between the negative and activation thresholds preserve the timer.
 
     The frame at 0.45 sits above the negative threshold (0.35) but below the
     activation threshold. It must not cancel the pending endpoint, or a speaker
@@ -164,9 +164,14 @@ def _pcm16_b64(samples: np.ndarray) -> str:
 
 def test_pcm16_input_is_accepted_alongside_float32() -> None:
     config = SileroVADConfig(threshold=0.5)
-    tone = np.zeros(FRAME * 2, dtype=np.float32)
+    tone: np.ndarray = np.zeros(FRAME * 2, dtype=np.float32)
     seen: list[int] = []
-    vad = SileroStreamingVAD(config, frame_scorer=lambda frame: seen.append(frame.size) or 0.0)
+
+    def _score_frame(frame: np.ndarray) -> float:
+        seen.append(frame.size)
+        return 0.0
+
+    vad = SileroStreamingVAD(config, frame_scorer=_score_frame)
     vad.process_base64(_pcm16_b64(tone), fmt="pcm16", sample_rate_hz=SAMPLE_RATE_HZ)
     assert seen == [FRAME, FRAME]
 
@@ -272,7 +277,7 @@ class FakeSessionOptions:
         intra_op_num_threads = 0
 
     class FakeInferenceSession:
-        def __init__(self, path: str, *, providers: list[str], sess_options: object) -> None:
+        def __init__(self, path: str, *, providers: list[str], sess_options: FakeSessionOptions) -> None:
             self.providers = providers
             self.sess_options = sess_options
             self.calls: list[dict[str, np.ndarray]] = []
@@ -313,7 +318,7 @@ def run(self, _outputs: object, inputs: dict[str, np.ndarray]) -> list[np.ndarra
     assert session.calls[0]["sr"].item() == SAMPLE_RATE_HZ
 
     state = backend.new_state()
-    first_frame = np.arange(backend.frame_samples, dtype=np.float32)
+    first_frame: np.ndarray = np.arange(backend.frame_samples, dtype=np.float32)
     probability, state = backend.infer(first_frame, state)
     first_call = session.calls[1]
 
@@ -377,3 +382,17 @@ def test_the_documented_server_vad_fields_are_all_accepted() -> None:
         )
         is None
     )
+
+
+@pytest.mark.parametrize("speech_probability", [0.5, 0.9])
+def test_resumed_speech_cancels_pending_silence(speech_probability):
+    config = SileroVADConfig(threshold=0.5, prefix_padding_ms=0, silence_duration_ms=96, min_speech_duration_ms=32)
+    # 32 ms pause, resumed speech, then a full 96 ms pause: one utterance.
+    scores = [0.9, 0.1, speech_probability, speech_probability, 0.1, 0.1, 0.1]
+    assert _drive(config, scores) == [("start", 0), ("stop", 224)]
+
+
+def test_short_pauses_do_not_split_continuous_speech_into_repeated_turns():
+    config = SileroVADConfig(threshold=0.5, prefix_padding_ms=0, silence_duration_ms=500, min_speech_duration_ms=32)
+    scores = [0.9] + [0.1, 0.9, 0.9, 0.9] * 20
+    assert _drive(config, scores) == [("start", 0)]
diff --git a/tests/engine/test_duplex_orchestrator.py b/tests/engine/test_duplex_orchestrator.py
index 5b8130c36a1..703af6a3558 100644
--- a/tests/engine/test_duplex_orchestrator.py
+++ b/tests/engine/test_duplex_orchestrator.py
@@ -515,3 +515,48 @@ async def test_a_dead_replica_closes_the_sessions_it_was_serving() -> None:
     messages = [output_q.get_nowait() for _ in range(output_q.qsize())]
     types = [getattr(getattr(m, "event", None), "type", type(m).__name__) for m in messages]
     assert types[-1] in {"session.expired", "session.closed"}, f"the client needs a terminal event, got {types}"
+
+
+@pytest.mark.asyncio
+async def test_turn_plugin_processes_multimodal_prompt_before_stage_submission(monkeypatch):
+    from vllm_omni.engine.orchestrator import build_engine_core_request_from_tokens
+    from vllm_omni.model_executor.models.qwen3_omni.duplex.plugin import Qwen3OmniDuplexPlugin
+
+    orchestrator, clients, rpc_q, _ = _build()
+    plugin = Qwen3OmniDuplexPlugin(_encode_audio)
+    plugin.processor = SimpleNamespace(apply_chat_template=lambda messages, **kwargs: "audio prompt")
+    orchestrator.plugin = orchestrator.session_manager.plugin = plugin
+    seen = []
+
+    def process_inputs(**kwargs):
+        seen.append(kwargs)
+        return build_engine_core_request_from_tokens(
+            request_id=kwargs["request_id"],
+            prompt={"prompt_token_ids": [1, 2]},
+            params=kwargs["params"],
+            model_config=orchestrator.stage_pools[0].stage_vllm_config.model_config,
+            resumable=kwargs["resumable"],
+        )
+
+    monkeypatch.setattr(
+        orchestrator, "_get_stage_input_processor", lambda stage_id: SimpleNamespace(process_inputs=process_inputs)
+    )
+    await orchestrator._dispatch_message(
+        OpenDuplexSessionMessage(
+            control_id="open-qwen",
+            session_id=SESSION_ID,
+            session_config=DuplexSessionConfig(model="qwen", modalities=["text", "audio"]),
+        )
+    )
+    assert (await rpc_q.get()).ok
+    try:
+        await _submit(orchestrator, _append_audio())
+        assert not clients[0].add_request_calls
+        await _submit(orchestrator, commands.Commit(final=True, create_response=True))
+        assert len(seen) == 1
+        assert seen[0]["prompt"]["multi_modal_data"]["audio"][0][0].shape == (16000,)
+        submitted = clients[0].add_request_calls[0][0]
+        assert submitted.resumable is False
+        assert not orchestrator.request_states[submitted.request_id].streaming.enabled
+    finally:
+        await _close(orchestrator, rpc_q)
diff --git a/tests/entrypoints/openai_api/test_api_server_guards.py b/tests/entrypoints/openai_api/test_api_server_guards.py
index ebc08662f50..43d88d6925c 100644
--- a/tests/entrypoints/openai_api/test_api_server_guards.py
+++ b/tests/entrypoints/openai_api/test_api_server_guards.py
@@ -47,6 +47,7 @@
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from types import SimpleNamespace
+from typing import Any
 
 import pytest
 from fastapi import FastAPI, HTTPException
@@ -564,7 +565,7 @@ async def test_timestamp_middleware_stamps_http_and_passes_websocket(monkeypatch
     Fails if HTTP requests lose ``request_timestamp``, or WebSocket scopes
     start getting stamped / mutated incorrectly.
     """
-    captured: dict[str, object] = {}
+    captured: dict[str, Any] = {}
 
     def fake_build_openai_app(args, supported_tasks):
         return FastAPI()
@@ -592,8 +593,8 @@ async def fake_serve_http(app, **_kwargs):
     await api_server.omni_run_server_worker("127.0.0.1:8000", _FakeSocket(), _minimal_args())
     middleware = captured["served_app"]
 
-    http_scope = {"type": "http", "state": {}}
-    ws_scope = {"type": "websocket"}
+    http_scope: dict[str, Any] = {"type": "http", "state": {}}
+    ws_scope: dict[str, Any] = {"type": "websocket"}
 
     async def _receive():
         return {"type": "http.disconnect"}
@@ -920,11 +921,10 @@ async def test_pure_diffusion_app_state_key_snapshot(monkeypatch) -> None:
     engine = _FakeEngineClient(stage_configs=[stage])
 
     def _for_diffusion_factory(label: str):
-        @classmethod
         def _factory(cls, *args, **kwargs):
             return _marker(label)
 
-        return _factory
+        return classmethod(_factory)
 
     monkeypatch.setattr(api_server.OmniOpenAIServingChat, "for_diffusion", _for_diffusion_factory("chat"))
     monkeypatch.setattr(api_server.OmniOpenAIServingChatBatch, "for_diffusion", _for_diffusion_factory("chat_batch"))
@@ -965,13 +965,11 @@ async def test_pure_diffusion_speech_forwards_media_access_args(monkeypatch) ->
     speech_kwargs = {}
 
     def _for_diffusion_factory(label: str):
-        @classmethod
         def _factory(cls, *args, **kwargs):
             return _marker(label)
 
-        return _factory
+        return classmethod(_factory)
 
-    @classmethod
     def _speech_factory(cls, *args, **kwargs):
         speech_kwargs.update(kwargs)
         return _marker("speech")
@@ -985,7 +983,7 @@ def _speech_factory(cls, *args, **kwargs):
     )
     monkeypatch.setattr(api_server.OmniOpenAIServingVideo, "for_diffusion", _for_diffusion_factory("video"))
     monkeypatch.setattr(api_server.OmniStreamingVideoOutputHandler, "__init__", lambda self, *a, **k: None)
-    monkeypatch.setattr(api_server.OmniOpenAIServingSpeech, "for_diffusion", _speech_factory)
+    monkeypatch.setattr(api_server.OmniOpenAIServingSpeech, "for_diffusion", classmethod(_speech_factory))
     monkeypatch.setattr(
         api_server.ServingRealtimeRobotOpenPI,
         "create_policy_server",
diff --git a/tests/entrypoints/openai_api/test_duplex_api_server.py b/tests/entrypoints/openai_api/test_duplex_api_server.py
index 9cf58b114b8..0d9eebe5bba 100644
--- a/tests/entrypoints/openai_api/test_duplex_api_server.py
+++ b/tests/entrypoints/openai_api/test_duplex_api_server.py
@@ -490,3 +490,31 @@ async def test_a_model_that_does_not_declare_chat_completions_does_not_get_the_r
 
     assert state.openai_serving_chat is None
     assert isinstance(state.openai_serving_duplex, OmniDuplexSessionHandler)
+
+
+def test_qwen_plugin_preserves_custom_turn_deployment_default(monkeypatch, tmp_path):
+    from vllm_omni.model_executor.models.qwen3_omni.pipeline import QWEN3_OMNI_PIPELINE
+
+    monkeypatch.setattr(StageConfigFactory, "get_pipeline_config", lambda **kwargs: QWEN3_OMNI_PIPELINE)
+    deploy = tmp_path / "qwen.yaml"
+    deploy.write_text("stages: []\n")
+    assert not api_server._should_serve_duplex("qwen", {"deploy_config": str(deploy)})
+    deploy.write_text("session_mode: duplex\nstages: []\n")
+    assert api_server._should_serve_duplex("qwen", {"deploy_config": str(deploy)})
+
+
+@pytest.mark.parametrize("flag", ["1", "true", "on"])
+def test_turn_deployment_rejects_explicit_duplex_without_falling_back_to_stt(flag: str) -> None:
+    app = _duplex_app(None)
+    # Even an available STT service must not silently accept a duplex request.
+    app.state.openai_serving_realtime = object()
+    with TestClient(app) as client:
+        with client.websocket_connect(f"/v1/realtime?duplex={flag}") as websocket:
+            assert websocket.receive_json() == {
+                "type": "error",
+                "code": "unsupported",
+                "error": "VAD realtime is not enabled",
+            }
+            with pytest.raises(WebSocketDisconnect) as exc:
+                websocket.receive_text()
+            assert exc.value.code == 1008
diff --git a/tests/examples/test_minicpmo_realtime_web_server.py b/tests/examples/test_minicpmo_realtime_web_server.py
index 6c35760a7ec..44f04eb1b1a 100644
--- a/tests/examples/test_minicpmo_realtime_web_server.py
+++ b/tests/examples/test_minicpmo_realtime_web_server.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 import hashlib
 import importlib.util
 import sys
@@ -70,7 +73,12 @@ def test_build_app_injects_public_realtime_url():
 def test_build_app_versions_client_bundle_and_disables_index_cache():
     client = TestClient(build_app())
     expected_version_hash = hashlib.sha256()
-    for asset_name in ("app.js", "pcm_worklet.js", "playback_worklet.js"):
+    for asset_name in (
+        "app.js",
+        "pcm_worklet.js",
+        "playback_worklet.js",
+        *[str(p.relative_to(STATIC_DIR)) for p in sorted((STATIC_DIR / "profiles").glob("*.js"))],
+    ):
         expected_version_hash.update((STATIC_DIR / asset_name).read_bytes())
     expected_version = expected_version_hash.hexdigest()[:12]
 
@@ -97,3 +105,41 @@ def test_build_app_exposes_realtime_websocket_and_static_assets():
     assert client.get("/static/app.js").status_code == 200
     assert client.get("/static/pcm_worklet.js").status_code == 200
     assert client.get("/static/playback_worklet.js").status_code == 200
+
+
+def test_qwen_config_does_not_inject_reference_voice():
+    client = TestClient(build_app(profile="qwen3-turn", adapter="vad", model="Qwen/Qwen3-Omni-30B-A3B-Instruct"))
+    page = client.get("/").text
+    assert '"profile": "qwen3-turn"' in page
+    assert '"adapter": "vad"' in page
+    assert '"refAudio": null' in page
+    for name in ("common", "minicpm_native", "qwen3_turn"):
+        assert client.get(f"/static/profiles/{name}.js").status_code == 200
+    with pytest.raises(ValueError, match="ref-audio"):
+        build_app(profile="qwen3-turn", ref_audio="unused.wav")
+
+
+def test_config_cannot_close_its_script_element():
+    page = TestClient(build_app(model="</script><script>alert(1)</script>")).get("/").text
+    assert "</script><script>alert(1)" not in page
+    assert "\\u003c/script>" in page
+
+
+def test_proxy_reports_unreachable_backend(monkeypatch):
+    from examples.online_serving.realtime_web import server as shared_server
+
+    class RefusedConnection:
+        async def __aenter__(self):
+            raise ConnectionRefusedError(111, "Connection refused")
+
+        async def __aexit__(self, *args):
+            pass
+
+    monkeypatch.setattr(shared_server.websockets, "connect", lambda *args, **kwargs: RefusedConnection())
+    client = TestClient(build_app(ws_backend="ws://127.0.0.1:8091"))
+    with client.websocket_connect("/v1/realtime?duplex=0") as ws:
+        event = ws.receive_json()
+        assert event["type"] == "error"
+        assert event["code"] == "backend_unavailable"
+        assert "ws://127.0.0.1:8091" in event["error"]
+        assert "--port" in event["error"]
diff --git a/tests/examples/test_minicpmo_realtime_web_static.py b/tests/examples/test_minicpmo_realtime_web_static.py
index 2027d5aa3ad..e96be408d12 100644
--- a/tests/examples/test_minicpmo_realtime_web_static.py
+++ b/tests/examples/test_minicpmo_realtime_web_static.py
@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
-import re
 import shutil
 import subprocess
 import textwrap
@@ -9,7 +8,7 @@
 
 import pytest
 
-ROOT = Path(__file__).resolve().parents[2] / "examples" / "online_serving" / "minicpmo" / "realtime_web"
+ROOT = Path(__file__).resolve().parents[2] / "examples" / "online_serving" / "realtime_web"
 APP_ROOT = ROOT / "app"
 STATIC_ROOT = APP_ROOT / "static"
 
@@ -30,73 +29,37 @@ def test_page_exposes_focused_call_conversation_and_log_surfaces():
     assert "Server VAD" not in html
 
 
-def test_client_uses_proxy_relative_realtime_url_and_model_policy_session():
+def test_shared_shell_delegates_wire_contract_to_profiles():
     source = (STATIC_ROOT / "app.js").read_text(encoding="utf-8")
-
-    assert "new URL(config.realtimePath, window.location.href)" in source
-    assert "url.protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:'" in source
-    assert "url.searchParams.set('autostart', '0')" in source
+    assert "profile.url(config, window.location.href)" in source
+    assert "profile.initialMessages(config, instructions)" in source
+    assert "profile.append(" in source
+    assert "profile.mapEvent(event)" in source
     assert "native_duplex" not in source
-    assert "auto_response: true" in source
-    assert "input_audio_buffer.append" in source
-    assert "input_audio_buffer.commit" not in source
-    assert "playback.ack" in source
-    assert "event.event || event" in source
-    assert "response.output_audio.delta" in source
-    assert "response.output_audio_transcript.delta" in source
-    assert "conversation.item.input_audio_transcription" in source
-    assert "force_barge_in" not in source
     assert "server_vad" not in source
-    assert "type: 'response.create'" not in source
-    assert 'type: "response.create"' not in source
-
-
-def test_web_server_requires_ref_audio_for_audio_output_session():
-    source = (ROOT / "server.py").read_text(encoding="utf-8")
 
-    ref_audio_arg = re.search(
-        r"parser\.add_argument\(\s*\"--ref-audio\",(?P<body>.*?)\n\s*\)",
-        source,
-        re.DOTALL,
-    )
-    assert ref_audio_arg is not None
-    assert "required=True" in ref_audio_arg.group("body")
-    assert "Optional reference voice" not in ref_audio_arg.group("body")
-
-
-def test_client_sends_ref_audio_in_realtime_session_contract():
-    source = (STATIC_ROOT / "app.js").read_text(encoding="utf-8")
 
+def test_native_profile_preserves_session_and_capture_policy():
+    source = (STATIC_ROOT / "profiles/minicpm_native.js").read_text(encoding="utf-8")
+    assert "native_duplex" not in source
+    assert "auto_response: true" in source
     assert "if (config.refAudio) session.ref_audio = config.refAudio;" in source
-    assert "extraBody.ref_audio" not in source
+    assert "halfDuplex: false" in source
+    assert "commitMessages: () => []" in source
+    assert "video_frames" in source
+    assert "playback.ack" in source
 
 
 def test_client_has_transactional_cleanup_and_visible_event_logging():
     source = (STATIC_ROOT / "app.js").read_text(encoding="utf-8")
-
-    assert "async function stopSession" in source
-    assert "type: 'session.close'" in source
+    assert "async function cleanupSession" in source
     assert "waitForSessionClosed" in source
-    assert "SESSION_CLOSE_TIMEOUT_MS" in source
-    assert "case 'session.closed':" in source
     assert "track.stop()" in source
     assert "clearInterval(sendTimer)" in source
     assert "appendEventLog(event)" in source
     assert "stopSession({ terminal: false })" in source
 
 
-def test_client_keeps_microphone_upload_active_during_assistant_playback():
-    source = (STATIC_ROOT / "app.js").read_text(encoding="utf-8")
-    upload_gate = re.search(r"function microphoneUploadEnabled\(\) \{(?P<body>.*?)\n  \}", source, re.DOTALL)
-    begin_assistant = re.search(r"function beginAssistant\(responseId\) \{(?P<body>.*?)\n  \}", source, re.DOTALL)
-
-    assert upload_gate is not None
-    assert "return running && !muted;" in upload_gate.group("body")
-    assert "assistantActive" not in upload_gate.group("body")
-    assert begin_assistant is not None
-    assert "pendingCapture = []" not in begin_assistant.group("body")
-
-
 def test_audio_worklets_define_capture_and_playback_processors():
     capture = (STATIC_ROOT / "pcm_worklet.js").read_text(encoding="utf-8")
     playback = (STATIC_ROOT / "playback_worklet.js").read_text(encoding="utf-8")
@@ -138,6 +101,7 @@ def test_playback_worklet_waits_before_playing_and_rebuffers_after_underrun():
     node = shutil.which("node")
     if node is None:
         pytest.skip("node is required for the AudioWorklet regression test")
+    assert node is not None
 
     script = textwrap.dedent(
         """
@@ -216,6 +180,7 @@ def test_playback_worklet_fades_terminal_drain_to_zero():
     node = shutil.which("node")
     if node is None:
         pytest.skip("node is required for the AudioWorklet regression test")
+    assert node is not None
 
     script = textwrap.dedent(
         """
diff --git a/tests/examples/test_realtime_web_profiles.cjs b/tests/examples/test_realtime_web_profiles.cjs
new file mode 100644
index 00000000000..51d4b3972eb
--- /dev/null
+++ b/tests/examples/test_realtime_web_profiles.cjs
@@ -0,0 +1,412 @@
+const assert = require('node:assert/strict');
+const { test } = require('node:test');
+const fs = require('node:fs');
+const path = require('node:path');
+const vm = require('node:vm');
+const root = path.resolve(__dirname, '../../examples/online_serving/realtime_web/app/static');
+const context = vm.createContext({ URL });
+for (const name of ['common', 'minicpm_native', 'qwen3_turn']) {
+  vm.runInContext(fs.readFileSync(path.join(root, `profiles/${name}.js`), 'utf8'), context);
+}
+const profiles = context.OmniRealtimeProfiles;
+const plain = (value) => JSON.parse(JSON.stringify(value));
+const config = { model: 'Qwen/Qwen3-Omni-30B-A3B-Instruct', realtimePath: 'v1/realtime' };
+
+test('MiniCPM keeps native flags, reference voice, camera, acknowledgements and no commits', () => {
+  const native = profiles['minicpm-native']();
+  const url = new URL(native.url({ ...config, model: 'MiniCPM' }, 'https://localhost/ui/'));
+  assert.equal(url.protocol, 'wss:');
+  assert.equal(url.searchParams.get('duplex'), '1');
+  assert.equal(url.searchParams.has('native_duplex'), false);
+  const [update] = native.initialMessages({ refAudio: 'data:audio/wav;base64,AA==' }, 'Prompt');
+  assert.equal(update.session.ref_audio, 'data:audio/wav;base64,AA==');
+  assert.equal(update.session.extra_body.native_duplex, undefined);
+  assert.equal(update.session.instructions, 'Prompt');
+  assert.deepEqual(plain(native.commitMessages()), []);
+  assert.equal(native.append('PCM', 'JPEG').video_frames[0], 'JPEG');
+  assert.equal(native.ack('r1', 200).type, 'playback.ack');
+  assert.equal(native.halfDuplex, false);
+});
+
+test('STT uses the shipped commit sequence and audio payload, including each new turn', () => {
+  const stt = profiles['qwen3-turn'](config);
+  for (let turn = 0; turn < 2; turn++) {
+    assert.deepEqual(plain(stt.initialMessages(config, 'ignored')), [
+      { type: 'session.update', model: config.model },
+      { type: 'input_audio_buffer.commit', final: false },
+    ]);
+    assert.deepEqual(plain(stt.commitMessages()), [{ type: 'input_audio_buffer.commit', final: true }]);
+  }
+  assert.equal(stt.reconnectEachTurn, true);
+  assert.equal(stt.mapEvent({ type: 'response.output_audio.delta', audio: 'PCM' }).event.delta, 'PCM');
+  assert.equal(stt.mapEvent({ type: 'response.output_audio.done' }).kind, 'done');
+  assert.equal(stt.mapEvent({ type: 'transcription.delta', delta: 'hello' }).role, 'assistant');
+});
+
+test('Qwen enables camera and playback ACK only for the duplex VAD profile', () => {
+  for (const adapter of ['stt', 'vad']) {
+    const p = profiles['qwen3-turn']({ ...config, adapter });
+    const url = new URL(p.url({ ...config, realtimePath: 'wss://backend/v1/realtime?native_duplex=1&minicpmo45_native_duplex=1' }, 'http://localhost/'));
+    assert.equal(url.protocol, 'wss:');
+    assert.equal(url.searchParams.get('duplex'), adapter === 'vad' ? '1' : '0');
+    assert.equal(url.searchParams.has('native_duplex'), false);
+    assert.equal(url.searchParams.has('minicpmo45_native_duplex'), false);
+    assert.equal(p.append('PCM', 'JPEG').video_frames, undefined);
+    assert.equal(plain(p.imageMessages('JPEG')).length, adapter === 'vad' ? 1 : 0);
+    assert.equal(p.ack('r', 100)?.type || null, adapter === 'vad' ? 'playback.ack' : null);
+    assert.equal(p.camera, adapter === 'vad');
+    assert.equal(p.mapEvent({ type: 'response.listen' }).kind, 'ignore');
+  }
+});
+
+test('VAD uses nested format and interruptible endpoint detection', () => {
+  const vad = profiles['qwen3-turn']({ ...config, adapter: 'vad' });
+  const [update] = vad.initialMessages(config, 'help');
+  assert.deepEqual(plain(update.session.audio.input), {
+    format: { type: 'audio/pcm', rate: 24000 },
+    turn_detection: { type: 'server_vad', threshold: 0.5, prefix_padding_ms: 300,
+      silence_duration_ms: 500, create_response: true, interrupt_response: true },
+  });
+  assert.equal(update.session.extra_body, undefined);
+  assert.deepEqual(plain(vad.commitMessages()), []);
+  assert.equal(vad.mapEvent({ type: 'response.audio.done' }).kind, 'drain');
+  assert.equal(vad.mapEvent({ type: 'response.done' }).kind, 'done');
+  assert.equal(vad.mapEvent({ type: 'response.output_text.delta', delta: 'hello' }).text, 'hello');
+  assert.equal(vad.mapEvent({ type: 'error', error: { code: 'input_backpressure' } }).kind, 'backpressure');
+  assert.equal(vad.mapEvent({ type: 'input_audio_buffer.cleared' }).kind, 'backpressure');
+  assert.match(vad.mapEvent({ type: 'error', code: 'unsupported', error: 'Unavailable' }).message, /session_mode: duplex/);
+  assert.match(vad.mapEvent({ type: 'error', code: 'server_vad_initialization_failed' }).message, /Silero/);
+});
+
+function shell(profileName, adapter = 'stt', options = {}) {
+  const elements = new Map();
+  class Element {
+    constructor() { this.style = {}; this.listeners = {}; this.children = []; this.value = ''; this.textContent = ''; this.classList = { add() {}, remove() {}, toggle() {} }; }
+    addEventListener(name, callback) { this.listeners[name] = callback; }
+    append(...children) { this.children.push(...children); }
+    appendChild(child) { this.children.push(child); }
+    replaceChildren() { this.children = []; }
+    remove() {}
+  }
+  const document = {
+    getElementById(id) { if (!elements.has(id)) elements.set(id, new Element()); return elements.get(id); },
+    createElement() { return new Element(); },
+  };
+  const timers = new Map();
+  let timerId = 0;
+  const sockets = [];
+  const nodes = [];
+  class Socket {
+    static OPEN = 1;
+    constructor() {
+      this.readyState = 1; this.sent = []; sockets.push(this);
+      queueMicrotask(() => {
+        this.onopen?.();
+        if (!options.silent) this.onmessage?.({ data: JSON.stringify(options.error || { type: adapter === 'stt' && profileName === 'qwen3-turn' ? 'session.created' : 'session.updated' }) });
+      });
+    }
+    send(value) { this.sent.push(JSON.parse(value)); }
+    close() { this.readyState = 3; this.onclose?.({ code: 1000 }); }
+  }
+  class AudioContext {
+    constructor(options) { this.sampleRate = options.sampleRate; this.audioWorklet = { addModule: async () => {} }; this.destination = {}; }
+    createMediaStreamSource() { return { connect() {} }; }
+    createGain() { return { gain: {}, connect() {} }; }
+    async resume() {}
+    async close() {}
+  }
+  class AudioWorkletNode {
+    constructor(_context, name) { this.name = name; this.sent = []; nodes.push(this); this.port = { postMessage: (message) => this.sent.push(message) }; }
+    connect(target) { return target; }
+  }
+  const ctx = vm.createContext({
+    URL, document, AudioContext, AudioWorkletNode, WebSocket: Socket,
+    navigator: { mediaDevices: { getUserMedia: async () => ({ getTracks: () => [{ stop() {} }] }) } },
+    location: { href: 'https://localhost/' },
+    OMNI_REALTIME_CONFIG: { ...config, profile: profileName, adapter },
+    addEventListener() {},
+    setTimeout(fn, ms) { const id = ++timerId; timers.set(id, { fn, ms }); return id; },
+    clearTimeout(id) { timers.delete(id); },
+    setInterval() { return ++timerId; }, clearInterval() {},
+    btoa: (value) => Buffer.from(value, 'binary').toString('base64'),
+    atob: (value) => Buffer.from(value, 'base64').toString('binary'),
+  });
+  ctx.window = ctx;
+  for (const name of ['common', 'minicpm_native', 'qwen3_turn']) {
+    vm.runInContext(fs.readFileSync(path.join(root, `profiles/${name}.js`), 'utf8'), ctx);
+  }
+  // Expose closure controls only in the test VM; production has no test API.
+  const source = fs.readFileSync(path.join(root, 'app.js'), 'utf8').replace(/\}\)\(\);\s*$/, `
+    globalThis.testUI = { startSession, stopSession, handleEvent, playbackDrained,
+      microphoneUploadEnabled, flushCapture,
+      capture() { pendingCapture.push(new Int16Array([100, 200])); },
+      state() { return { running, connectionReady, assistantActive }; }
+    };
+  })();`);
+  vm.runInContext(source, ctx);
+  return { ui: ctx.testUI, elements, sockets, nodes,
+    timeout() { for (const timer of timers.values()) if (timer.ms === 15000) timer.fn(); },
+    async echo() {
+      for (const [id, timer] of timers) if (timer.ms === 300) { timers.delete(id); await timer.fn(); }
+    },
+    async turnWatchdog() {
+      for (const [id, timer] of timers) if (timer.ms === 120000) { timers.delete(id); await timer.fn(); }
+    },
+  };
+}
+
+test('shared shell STT sends final commit and starts a fresh second turn only after playback', async () => {
+  const app = shell('qwen3-turn');
+  await app.ui.startSession();
+  assert.equal(app.ui.microphoneUploadEnabled(), true);
+  app.ui.capture(); app.ui.flushCapture();
+  app.elements.get('sendTurnButton').listeners.click();
+  assert.equal(app.sockets[0].sent.at(-1).final, true);
+  assert.equal(app.ui.microphoneUploadEnabled(), false);
+  await app.ui.handleEvent({ type: 'response.output_audio.delta', audio: 'AAAAAA==' });
+  await app.ui.handleEvent({ type: 'response.output_audio.done' });
+  await app.echo();
+  assert.equal(app.sockets.length, 1, 'wait for actual speaker drain');
+  app.ui.playbackDrained({ responseId: 'turn-1', playedMs: 1 });
+  await app.echo();
+  assert.equal(app.sockets.length, 2);
+  assert.equal(app.sockets[1].sent[1].final, false);
+  assert.equal(app.ui.microphoneUploadEnabled(), true);
+  assert.equal(app.elements.get('cameraButton').hidden, true);
+  assert.equal(app.sockets.flatMap(s => s.sent).some(e => e.type === 'playback.ack'), false);
+  await app.ui.stopSession({ terminal: false });
+});
+
+test('VAD keeps uploading while generating and waits for response.done after audio drain', async () => {
+  const app = shell('qwen3-turn', 'vad');
+  await app.ui.startSession();
+  await app.ui.handleEvent({ type: 'error', code: 'input_backpressure' });
+  assert.equal(app.ui.microphoneUploadEnabled(), true);
+  await app.ui.handleEvent({ type: 'response.created', response: { id: 'r1' } });
+  await app.ui.handleEvent({ type: 'response.audio.delta', delta: 'AAAAAA==', response_id: 'r1' });
+  await app.ui.handleEvent({ type: 'response.audio.done', response_id: 'r1' });
+  app.ui.playbackDrained({ responseId: 'r1', playedMs: 1 });
+  await app.echo();
+  assert.equal(app.ui.microphoneUploadEnabled(), true, 'continuous capture remains enabled');
+  assert.equal(app.ui.state().assistantActive, true, 'audio drain must wait for response.done');
+  assert.equal(app.sockets[0].sent.at(-1).type, 'playback.ack');
+  await app.ui.handleEvent({ type: 'response.done', response: { id: 'r1' } });
+  await app.echo();
+  assert.equal(app.ui.microphoneUploadEnabled(), true);
+  assert.equal(app.sockets.length, 1, 'VAD keeps its session');
+  assert.equal(app.sockets[0].sent.some(e => e.type === 'input_audio_buffer.commit'), false);
+  await app.ui.stopSession({ terminal: false });
+});
+
+test('a rejected operation is reported without hanging up the call', async () => {
+  const app = shell('qwen3-turn', 'vad');
+  await app.ui.startSession();
+  await app.ui.handleEvent({ type: 'error', code: 'invalid_image', error: 'input_image requires a JPEG or PNG base64 data URL' });
+  assert.equal(app.ui.state().running, true, 'one refused image must not end the session');
+  assert.equal(app.ui.state().connectionReady, true);
+  assert.match(app.elements.get('runtimeDetail').textContent, /JPEG or PNG/);
+  await app.ui.stopSession({ terminal: false });
+});
+
+test('a session-level error still tears the call down', async () => {
+  const app = shell('qwen3-turn', 'vad');
+  await app.ui.startSession();
+  await app.ui.handleEvent({ type: 'error', code: 'unknown_session', error: 'Unknown or closed duplex session' });
+  assert.equal(app.ui.state().running, false);
+  assert.equal(app.elements.get('connectionState').textContent, 'Error');
+});
+
+test('an interrupted response disarms the turn watchdog it left armed', async () => {
+  const app = shell('qwen3-turn', 'vad');
+  await app.ui.startSession();
+  await app.ui.handleEvent({ type: 'response.created', response: { id: 'r1' } });
+  await app.ui.handleEvent({ type: 'error', code: 'input_backpressure' });
+  await app.ui.handleEvent({ type: 'response.done', response: { id: 'r1', status: 'cancelled' } });
+  await app.turnWatchdog();
+  assert.equal(app.ui.state().running, true, 'barge-in must not time the session out two minutes later');
+  await app.ui.stopSession({ terminal: false });
+});
+
+test('MiniCPM retains microphone upload while speaking and acknowledges speaker drain', async () => {
+  const app = shell('minicpm-native');
+  await app.ui.startSession();
+  await app.ui.handleEvent({ type: 'response.speak', response_id: 'native-r1' });
+  assert.equal(app.ui.microphoneUploadEnabled(), true);
+  await app.ui.handleEvent({ type: 'response.output_audio.delta', delta: 'AAAAAA==', response_id: 'native-r1' });
+  app.ui.playbackDrained({ responseId: 'native-r1', playedMs: 100 });
+  assert.equal(app.sockets[0].sent.at(-1).type, 'playback.ack');
+  assert.equal(app.sockets[0].sent.some(e => e.type === 'input_audio_buffer.commit'), false);
+  await app.ui.stopSession({ terminal: false });
+  await app.echo();
+  assert.equal(app.ui.state().running, false);
+});
+
+test('VAD handshake errors remain visible after resource cleanup', async () => {
+  const app = shell('qwen3-turn', 'vad', { error: { type: 'error', code: 'unsupported', error: 'Realtime API is not available' } });
+  await app.ui.startSession();
+  assert.equal(app.ui.state().running, false);
+  assert.equal(app.elements.get('connectionState').textContent, 'Error');
+  assert.match(app.elements.get('runtimeDetail').textContent, /session_mode: duplex/);
+  assert.equal(app.sockets[0].readyState, 3);
+});
+
+test('missing session acknowledgement fails instead of leaving Start disabled forever', async () => {
+  const app = shell('qwen3-turn', 'vad', { silent: true });
+  const starting = app.ui.startSession();
+  for (let i = 0; i < 20; i++) await Promise.resolve();
+  app.timeout();
+  await starting;
+  assert.equal(app.ui.state().running, false);
+  assert.equal(app.elements.get('callButton').disabled, false);
+  assert.match(app.elements.get('runtimeDetail').textContent, /handshake timed out/);
+});
+
+test('Qwen does not duplicate text and audio-transcript channels', async () => {
+  const app = shell('qwen3-turn', 'vad');
+  await app.ui.startSession();
+  await app.ui.handleEvent({ type: 'response.audio_transcript.delta', delta: '' });
+  await app.ui.handleEvent({ type: 'response.output_text.delta', delta: 'Hello' });
+  await app.ui.handleEvent({ type: 'response.audio_transcript.delta', delta: 'Hello' });
+  await app.ui.handleEvent({ type: 'response.output_text.done', text: 'Hello' });
+  await app.ui.handleEvent({ type: 'response.done' });
+  const turns = app.elements.get('conversation').children;
+  assert.equal(turns.length, 1);
+  assert.equal(turns[0].children[1].textContent, 'Hello');
+  await app.ui.stopSession({ terminal: false });
+});
+
+const flushTasks = async () => { for (let i = 0; i < 40; i++) await Promise.resolve(); };
+
+test('closing socket accepts only session.closed and completes without the fallback timer', async () => {
+  const app = shell('minicpm-native');
+  await app.ui.startSession();
+  const old = app.sockets[0];
+  let stopped = false;
+  const stopping = app.ui.stopSession().then(() => { stopped = true; });
+  assert.equal(old.sent.at(-1).type, 'session.close');
+  old.onmessage({ data: JSON.stringify({ type: 'session.updated' }) });
+  await flushTasks();
+  assert.equal(stopped, false);
+  old.onmessage({ data: JSON.stringify({ type: 'session.closed' }) });
+  await flushTasks();
+  assert.equal(stopped, true, 'must finish without firing the timeout');
+  await stopping;
+  await app.ui.startSession();
+  old.onmessage({ data: JSON.stringify({ type: 'session.closed' }) });
+  old.onmessage({ data: '{broken' });
+  await flushTasks();
+  assert.equal(app.ui.state().running, true, 'stale socket cannot affect a new session');
+  await app.ui.stopSession({ terminal: false });
+});
+
+test('malformed JSON before readiness rejects the handshake and cleans up', async () => {
+  const app = shell('qwen3-turn', 'vad', { silent: true });
+  const starting = app.ui.startSession();
+  await flushTasks();
+  app.sockets[0].onmessage({ data: '{broken' });
+  await starting;
+  assert.equal(app.ui.state().running, false);
+  assert.equal(app.sockets[0].readyState, 3);
+  assert.equal(app.elements.get('connectionState').textContent, 'Error');
+  assert.match(app.elements.get('runtimeDetail').textContent, /Invalid server event/);
+});
+
+test('malformed JSON after readiness fails the session and releases resources', async () => {
+  const app = shell('qwen3-turn', 'vad');
+  await app.ui.startSession();
+  app.sockets[0].onmessage({ data: '{broken' });
+  await flushTasks();
+  assert.equal(app.ui.state().running, false);
+  assert.equal(app.ui.microphoneUploadEnabled(), false);
+  assert.equal(app.sockets[0].readyState, 3);
+  assert.equal(app.elements.get('connectionState').textContent, 'Error');
+  assert.match(app.elements.get('runtimeDetail').textContent, /Invalid server event/);
+});
+
+
+test('Qwen VAD interruption clears playback while continuing microphone upload', async () => {
+  const app = shell('qwen3-turn', 'vad');
+  await app.ui.startSession();
+  await app.ui.handleEvent({ type: 'response.created', response: { id: 'r1' } });
+  await app.ui.handleEvent({ type: 'response.audio.delta', delta: 'AAAAAA==', response_id: 'r1' });
+  await app.ui.handleEvent({ type: 'output_audio_buffer.cleared', response_id: 'r1' });
+  assert.equal(app.ui.state().assistantActive, false);
+  assert.equal(app.ui.microphoneUploadEnabled(), true);
+  assert.ok(app.nodes.some(node => node.sent.some(message => message.type === 'clear')));
+  await app.ui.stopSession({ terminal: false });
+});
+
+
+test('Qwen runtime errors do not suggest changing a working deployment', () => {
+  const p = profiles['qwen3-turn']({ adapter: 'vad' });
+  const message = 'playback.ack arrived after a later user input was committed.';
+  assert.equal(p.mapEvent({ type: 'error', code: 'playback_ack_too_late', error: message }).message, message);
+});
+
+test('interrupted playback reports its cursor before clear resets it', () => {
+  let Playback;
+  const messages = [];
+  const ctx = vm.createContext({
+    sampleRate: 24000,
+    AudioWorkletProcessor: class { constructor() { this.port = { postMessage: m => messages.push(m) }; } },
+    registerProcessor: (_name, cls) => { Playback = cls; },
+  });
+  vm.runInContext(fs.readFileSync(path.join(root, 'playback_worklet.js'), 'utf8'), ctx);
+  const player = new Playback();
+  player.handleMessage({ type: 'audio', responseId: 'old', pcm: new Int16Array(24000), initialBufferMs: 0 });
+  player.process([], [[new Float32Array(2400)]]);
+  player.handleMessage({ type: 'clear' });
+  const report = messages.find(m => m.type === 'playback-stopped');
+  assert.equal(report.responseId, 'old');
+  assert.equal(report.playedMs, 100);
+  assert.equal(player.playedFrames, 0);
+  assert.equal(player.bufferedFrames(), 0);
+  player.handleMessage({ type: 'clear' });
+  assert.equal(messages.filter(m => m.type === 'playback-stopped').length, 1);
+});
+
+test('late interruption cursor acknowledges old response without finishing the new response', async () => {
+  const app = shell('qwen3-turn', 'vad');
+  await app.ui.startSession();
+  const player = app.nodes.find(n => n.name === 'fullduplex-pcm-playback');
+  await app.ui.handleEvent({ type: 'response.created', response: { id: 'old' } });
+  await app.ui.handleEvent({ type: 'output_audio_buffer.cleared', response_id: 'old' });
+  await app.ui.handleEvent({ type: 'response.created', response: { id: 'new' } });
+  player.port.onmessage({ data: { type: 'playback-stopped', responseId: 'old', playedMs: 100 } });
+  const ack = app.sockets[0].sent.find(m => m.type === 'playback.ack');
+  assert.equal(ack.response_id, 'old');
+  assert.equal(ack.played_ms, 100);
+  assert.equal(app.ui.state().assistantActive, true);
+});
+
+
+test('Qwen camera frames ride the OpenAI image interface, not the audio append', () => {
+  const p = profiles['qwen3-turn']({ ...config, adapter: 'vad' });
+  assert.deepEqual(plain(p.append('PCM', 'JPEG')), { type: 'input_audio_buffer.append', audio: 'PCM' });
+
+  const [created] = plain(p.imageMessages('JPEG'));
+  assert.equal(created.type, 'conversation.item.create');
+  assert.equal(created.item.role, 'user');
+  assert.deepEqual(created.item.content, [
+    { type: 'input_image', image_url: 'data:image/jpeg;base64,JPEG' },
+  ]);
+});
+
+test('the camera retires its oldest image instead of exhausting the session budget', () => {
+  const p = profiles['qwen3-turn']({ ...config, adapter: 'vad' });
+  const ids = [];
+  for (let i = 0; i < 8; i++) {
+    const messages = plain(p.imageMessages('JPEG'));
+    assert.equal(messages.length, 1, 'nothing to retire while under the budget');
+    ids.push(messages[0].item.id);
+  }
+  // The engine counts what it already stores, so the delete has to lead.
+  const ninth = plain(p.imageMessages('JPEG'));
+  assert.deepEqual(ninth[0], { type: 'conversation.item.delete', item_id: ids[0] });
+  assert.equal(ninth[1].type, 'conversation.item.create');
+  assert.equal(new Set(ids).size, 8, 'item ids must be distinct to be deletable');
+
+  // A new call reopens the budget; stale ids from the old one must not linger.
+  assert.equal(plain(p.initialMessages(config, 'x')).length > 0, true);
+  assert.equal(plain(p.imageMessages('JPEG')).length, 1);
+});
diff --git a/tests/examples/test_realtime_web_profiles.py b/tests/examples/test_realtime_web_profiles.py
new file mode 100644
index 00000000000..6b21d86a09e
--- /dev/null
+++ b/tests/examples/test_realtime_web_profiles.py
@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_realtime_profiles_and_shell_lifecycle():
+    node = shutil.which("node")
+    if node is None:
+        pytest.skip("node is required for browser protocol tests")
+    assert node is not None
+    subprocess.run(
+        [node, "--test", str(Path(__file__).with_suffix(".cjs"))],
+        check=True,
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
diff --git a/tests/model_executor/models/qwen3_omni/test_duplex_plugin.py b/tests/model_executor/models/qwen3_omni/test_duplex_plugin.py
new file mode 100644
index 00000000000..c57d5ff149e
--- /dev/null
+++ b/tests/model_executor/models/qwen3_omni/test_duplex_plugin.py
@@ -0,0 +1,625 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+import asyncio
+import base64
+from types import SimpleNamespace
+from typing import Any
+
+import numpy as np
+import pytest
+
+from tests.engine.duplex.test_session_runner import (
+    SESSION_ID,
+    Harness,
+    RecordingStagePort,
+    _speech_then_stop,
+    append_audio,
+    tts_output,
+)
+from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine.duplex.commands import AckPlayback, CancelResponse, Commit, UpdateSession
+from vllm_omni.engine.duplex.config import DuplexSessionConfig
+from vllm_omni.engine.duplex.messages import OpenDuplexSessionMessage
+from vllm_omni.engine.duplex.plugin import DuplexRuntimeConfigError
+from vllm_omni.engine.duplex.session.manager import DuplexSessionManager
+from vllm_omni.model_executor.models.qwen3_omni.duplex.input import QwenPcmBuffer
+from vllm_omni.model_executor.models.qwen3_omni.duplex.plugin import MAX_PROMPT_IMAGES, Qwen3OmniDuplexPlugin
+from vllm_omni.outputs import OmniRequestOutput
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_buffer_commit_and_rollback_preserve_all_samples():
+    buffer = QwenPcmBuffer()
+    raw = np.ones(101, dtype="<f4").tobytes()
+    payload = {"audio": base64.b64encode(raw).decode(), "format": "pcm_f32le", "sample_rate_hz": 16000}
+    assert buffer.prepare_append(payload, operation_id="a", chunk_period_ms=1000, allow_emit=True) is None
+    reservation = buffer.prepare_commit(operation_id="c", chunk_period_ms=1000)
+    assert base64.b64decode(reservation.payload["audio"]) == raw
+    reservation.rollback()
+    assert buffer.pending_byte_count == len(raw)
+    final = buffer.prepare_commit(operation_id="d", chunk_period_ms=1000)
+    final.commit()
+    assert not buffer.has_pending() and not buffer.has_reserved()
+
+
+def test_buffer_refuses_video_frames_and_points_at_the_openai_interface():
+    buffer = QwenPcmBuffer()
+    payload = {
+        "audio": base64.b64encode(np.ones(16, dtype="<f4").tobytes()).decode(),
+        "format": "pcm_f32le",
+        "sample_rate_hz": 16000,
+        "video_frames": ["a-frame"],
+    }
+    with pytest.raises(ValueError, match="input_image"):
+        buffer.prepare_append(payload, operation_id="first", chunk_period_ms=200, allow_emit=True)
+    # The refusal must not swallow the audio it was sent with.
+    assert not buffer.has_pending()
+
+    del payload["video_frames"]
+    buffer.prepare_append(payload, operation_id="second", chunk_period_ms=200, allow_emit=True)
+    committed = buffer.prepare_commit(operation_id="second-commit", chunk_period_ms=200)
+    assert "video_frames" not in committed.payload
+    committed.commit()
+
+
+async def open_qwen():
+    plugin = Qwen3OmniDuplexPlugin(lambda audio, *args: "AAAA")
+    plugin.processor = SimpleNamespace(apply_chat_template=lambda messages, **kw: repr(messages))
+    port = RecordingStagePort(stage_count=3)
+    output: asyncio.Queue[Any] = asyncio.Queue()
+    results: asyncio.Queue[Any] = asyncio.Queue()
+    manager = DuplexSessionManager(
+        plugin=plugin,
+        stage_port=port,
+        output_sink=output,
+        result_sink=results,
+        runtime_config=DuplexSessionRuntimeConfig(),
+        model_config=None,
+    )
+    config = DuplexSessionConfig(model="qwen", modalities=["text", "audio"], overlap_policy="barge_in_on_speech")
+    await manager.handle(OpenDuplexSessionMessage(control_id="open", session_id=SESSION_ID, session_config=config))
+    result = await results.get()
+    assert result.ok, result
+    harness = Harness(manager, port, output, results, manager.runners[SESSION_ID])
+    await harness.settle()
+    return harness
+
+
+@pytest.mark.asyncio
+async def test_two_committed_turns_stream_text_and_audio_and_release_requests():
+    h = await open_qwen()
+    try:
+        ids = []
+        for i in range(2):
+            await h.run(append_audio())
+            assert len(h.port.submissions) == i
+            await h.run(Commit(final=True, create_response=True))
+            assert len(h.port.submissions) == i + 1, [e.to_realtime() for e in h.events]
+            request_id = h.port.submissions[-1].context.request_id
+            ids.append(request_id)
+            assert h.session.active_request_id == request_id
+            assert len(h.port.submissions[-1].prompt["multi_modal_data"]["audio"]) == i + 1
+            text = OmniRequestOutput.from_stage_output(
+                tts_output(request_id, samples=0, text="hello", finished=True),
+                request_id=request_id,
+                stage_id=None,
+            )
+            assert not h.deliver(text, stage_id=0), "Thinker output must still forward to Talker"
+            await h.settle()
+            assert text.finished, "projection must not mutate the output forwarded to Talker"
+            assert h.session.active_response_id is not None, "Thinker finished must not end the response"
+            response_id = h.session.active_response_id
+            await h.deliver_and_settle(tts_output(request_id, finished=True), stage_id=2)
+            await h.run(AckPlayback(response_id=response_id, played_ms=1000))
+            assert h.session.active_response_id is None
+            assert h.port.cleanups[-1][0] == [request_id]
+        assert len(set(ids)) == 2
+        assert h.session.capabilities.as_dict()["implementation_level"] == "turn_based_duplex"
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_cancel_drops_old_output_and_accepts_next_turn():
+    h = await open_qwen()
+    try:
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        old = h.port.submissions[-1].context
+        await h.run(CancelResponse())
+        await h.deliver_and_settle(tts_output(old.request_id, finished=True), stage_id=2, epoch=old.fence.epoch)
+        assert h.session.active_response_id is None
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        assert len(h.port.submissions) == 2
+        assert h.port.submissions[-1].context.request_id != old.request_id
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_vad_commits_and_speech_interrupts_active_qwen_response():
+    h = await open_qwen()
+    try:
+        h.runner.control._detector = _speech_then_stop()
+        await h.run(append_audio())
+        await h.run(append_audio(is_speech=False, value=0.0))
+        assert len(h.port.submissions) == 1
+        old = h.port.submissions[-1].context
+        h.runner.control._detector = _speech_then_stop()
+        await h.run(append_audio())
+        assert h.session.epoch > old.fence.epoch
+        await h.run(append_audio(is_speech=False, value=0.0))
+        assert len(h.port.submissions) == 2
+        assert h.port.submissions[-1].context.request_id != old.request_id
+    finally:
+        await h.manager.shutdown()
+
+
+def test_audio_projector_handles_delta_tensor_lists_and_sample_rate():
+    import torch
+
+    encoded: list[tuple[Any, object]] = []
+
+    def _encode(audio: object, rate: int, *_args: object) -> str:
+        encoded.append((audio, rate))
+        return "encoded"
+
+    plugin = Qwen3OmniDuplexPlugin(_encode)
+    output = SimpleNamespace(
+        request_id="r",
+        stage_id=2,
+        finished=True,
+        outputs=[],
+        multimodal_output={"audio": [torch.ones(8), torch.ones(16)], "sr": [torch.tensor(24000)]},
+    )
+    events = list(plugin.data_plane.project({"data_plane_outputs": [output]}, context={"modalities": ["audio"]}))
+    assert len(encoded) == 1 and encoded[0][0].shape == (24,)
+    assert events[0]["audio_duration_ms"] == 1
+    assert events[0]["end_of_turn"] is True
+
+
+def test_audio_history_is_bounded_and_does_not_cross_sessions():
+    plugin = Qwen3OmniDuplexPlugin(lambda *args: None)
+    state, other = plugin.create_session_state(), plugin.create_session_state()
+    history = []
+    for i in range(6):
+        history.append({"role": "user", "content": [{"type": "audio_url"}]})
+        config = plugin.prepare_prompt_config({"conversation": history}, state=state, payload={"audio": str(i)})
+        history.append({"role": "assistant", "content": f"reply-{i}"})
+    assert len(state.audio_history) == 4
+    assert [m["audio_payload"]["audio"] for m in config["qwen_messages"] if "audio_payload" in m] == [
+        "2",
+        "3",
+        "4",
+        "5",
+    ]
+    assert other.audio_history == []
+
+
+@pytest.mark.asyncio
+async def test_late_playback_ack_keeps_answer_before_new_user_input():
+    h = await open_qwen()
+    try:
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        request_id = h.port.submissions[-1].context.request_id
+        response_id = h.session.active_response_id
+        await h.deliver_and_settle(tts_output(request_id, samples=0, text="first answer", finished=True), stage_id=0)
+        await h.deliver_and_settle(tts_output(request_id, finished=True), stage_id=2)
+        # Playback has not drained yet. A new utterance commits first.
+        assert [m["role"] for m in h.session.history] == ["user"]
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        current_response = h.session.active_response_id
+        events = await h.run(AckPlayback(response_id=response_id, played_ms=1000))
+        assert not any(e.to_realtime().get("type") == "error" for e in events)
+        assert [m["role"] for m in h.session.history] == ["user", "assistant", "user"]
+        assert h.session.history[1]["content"] == "first answer"
+        assert h.session.active_response_id == current_response
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("streaming_vad", [False, True])
+async def test_finished_qwen_response_does_not_repeat_during_silence(streaming_vad):
+    h = await open_qwen()
+    try:
+        if streaming_vad:
+            from vllm_omni.engine.duplex.turn_detection import ServerTurnDetector, TurnDetectionConfig
+
+            detector = ServerTurnDetector(TurnDetectionConfig())
+            # Exercise framing, endpointing and reset across the entire response.
+            # A deterministic scorer avoids requiring an ONNX artifact in CPU tests.
+            detector.vad._frame_scorer = lambda frame: float(np.max(np.abs(frame)) > 0.01)
+            h.runner.control._detector = detector
+        else:
+            h.runner.control._detector = _speech_then_stop()
+        await h.run(append_audio())
+        await h.run(append_audio(is_speech=False, value=0.0))
+        if not streaming_vad:
+            h.runner.control._detector = None
+        assert len(h.port.submissions) == 1
+        request_id = h.port.submissions[0].context.request_id
+        response_id = h.session.active_response_id
+        await h.deliver_and_settle(tts_output(request_id, samples=0, text="story", finished=True), stage_id=0)
+        for _ in range(3):
+            await h.run(append_audio(is_speech=False, value=0.0))
+        await h.deliver_and_settle(tts_output(request_id, finished=True), stage_id=2)
+        for _ in range(3):
+            await h.run(append_audio(is_speech=False, value=0.0))
+        await h.run(AckPlayback(response_id=response_id, played_ms=1000))
+        await h.settle()
+        assert len(h.port.submissions) == 1
+        assert not h.runner.model_state.audio_buffer.has_pending()
+        assert h.runner.model_state.committed_audio_payload is None
+    finally:
+        await h.manager.shutdown()
+
+
+def test_current_audio_is_not_replaced_by_history_ending_with_assistant():
+    plugin = Qwen3OmniDuplexPlugin(lambda *args: None)
+    plugin.processor = SimpleNamespace(apply_chat_template=lambda messages, **kwargs: repr(messages))
+    state = plugin.create_session_state()
+    first = {"audio": base64.b64encode(np.full(160, 0.1, dtype="<f4").tobytes()).decode()}
+    current = {"audio": base64.b64encode(np.full(320, 0.2, dtype="<f4").tobytes()).decode()}
+    history = [{"role": "user", "content": [{"type": "audio_url"}]}]
+    plugin.prepare_prompt_config({"conversation": history}, state=state, payload=first)
+    history.append({"role": "assistant", "content": "Previous answer"})
+    config = plugin.prepare_prompt_config({"conversation": history}, state=state, payload=current)
+    plan = plugin.plan_append(
+        request_id="new",
+        fence=None,
+        session_config=config,
+        runtime_config={},
+        seq=1,
+        turn_seq=1,
+        payload=current,
+        final=True,
+        sampling_params=None,
+    )
+    audios = plan.prompt["multi_modal_data"]["audio"]
+    assert len(audios) == 2
+    np.testing.assert_allclose(audios[-1][0], np.full(320, 0.2, dtype="<f4"))
+    assert config["qwen_messages"][-1]["audio_payload"] is current
+
+
+@pytest.mark.asyncio
+async def test_partial_playback_does_not_commit_unaligned_thinker_text():
+    h = await open_qwen()
+    try:
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        request_id = h.port.submissions[-1].context.request_id
+        response_id = h.session.active_response_id
+        await h.deliver_and_settle(tts_output(request_id, samples=0, text="entire answer", finished=True), stage_id=0)
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, finished=False), stage_id=2)
+        await h.run(AckPlayback(response_id=response_id, played_ms=1000))
+        assert not any(m["role"] == "assistant" for m in h.session.history)
+        await h.deliver_and_settle(tts_output(request_id, samples=216000, finished=True), stage_id=2)
+        await h.run(AckPlayback(response_id=response_id, played_ms=1000))
+        assert not any(m["role"] == "assistant" for m in h.session.history)
+        await h.run(AckPlayback(response_id=response_id, played_ms=10000))
+        assert h.session.history[-1]["content"] == "entire answer"
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_prompt_preparation_runs_off_loop_and_cancellation_prevents_submission():
+    import threading
+
+    h = await open_qwen()
+    entered, release = threading.Event(), threading.Event()
+    thread_ids = []
+    original = h.manager.plugin.plan_append
+
+    def slow_plan(**kwargs):
+        thread_ids.append(threading.get_ident())
+        entered.set()
+        assert release.wait(5)
+        return original(**kwargs)
+
+    h.manager.plugin.plan_append = slow_plan
+    try:
+        await h.run(append_audio())
+        commit = asyncio.create_task(h.run(Commit(final=True, create_response=True)))
+        for _ in range(100):
+            if entered.is_set():
+                break
+            await asyncio.sleep(0.01)
+        assert entered.is_set()
+        assert thread_ids != [threading.get_ident()]
+        await h.run(CancelResponse())
+        release.set()
+        await commit
+        await h.settle()
+        assert not h.port.submissions
+    finally:
+        release.set()
+        await h.manager.shutdown()
+
+
+def camera_frame():
+    import io
+
+    from PIL import Image
+
+    buf = io.BytesIO()
+    Image.new("RGB", (16, 16), "red").save(buf, format="JPEG")
+    return base64.b64encode(buf.getvalue()).decode()
+
+
+def pcm16_base64(samples=16000):
+    """Loud PCM16, so the projection reads it as speech rather than silence."""
+    pcm = (np.sin(np.arange(samples) * 0.05) * 20000).astype("<i2")
+    return base64.b64encode(pcm.tobytes()).decode()
+
+
+def image_item(item_id="camera"):
+    return {
+        "id": item_id,
+        "type": "message",
+        "role": "user",
+        "content": [
+            {"type": "input_image", "image_url": "data:image/jpeg;base64," + camera_frame()},
+            {"type": "input_text", "text": "What color is this?"},
+        ],
+    }
+
+
+@pytest.mark.asyncio
+async def test_image_item_is_context_until_response_create_and_delete_removes_it():
+    from vllm_omni.engine.duplex.commands import CreateResponse, DeleteItem
+
+    h = await open_qwen()
+    try:
+        from vllm_omni.engine.duplex.realtime_commands import translate_realtime_command
+
+        await h.run(translate_realtime_command({"type": "conversation.item.create", "item": image_item()}))
+        assert not h.port.submissions
+        await h.run(CreateResponse())
+        assert len(h.port.submissions) == 1
+        prompt = h.port.submissions[-1].prompt
+        assert len(prompt["multi_modal_data"]["image"]) == 1
+        assert "audio" not in prompt["multi_modal_data"]
+        assert "What color is this?" in prompt["prompt"]
+        await h.run(CancelResponse())
+        await h.run(DeleteItem(item_id="camera"))
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=False))
+        assert len(h.port.submissions) == 1
+        await h.run(CreateResponse())
+        assert "image" not in h.port.submissions[-1].prompt["multi_modal_data"]
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_image_context_reaches_audio_turn_and_survives_commit():
+    from vllm_omni.engine.duplex.commands import CreateItem
+
+    h = await open_qwen()
+    try:
+        await h.run(CreateItem(item=image_item()))
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        mm = h.port.submissions[-1].prompt["multi_modal_data"]
+        assert len(mm["image"]) == 1 and len(mm["audio"]) == 1
+        assert any(
+            isinstance(m["content"], list) and any(p.get("type") == "image_url" for p in m["content"])
+            for m in h.session.history
+        )
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_image_only_item_reaches_the_prompt_the_way_the_camera_sends_it():
+    """The camera sends each frame as its own item, with no text part.
+
+    A user item used to be forwarded to the session only when it carried text
+    or audio, so an image-only item was acknowledged to the client and then
+    dropped. Nothing reported it and every prompt that followed was blind.
+    """
+    from vllm_omni.engine.duplex.realtime_commands import translate_realtime_command
+
+    h = await open_qwen()
+    try:
+        item = {
+            "id": "camera_1",
+            "type": "message",
+            "role": "user",
+            "content": [{"type": "input_image", "image_url": "data:image/jpeg;base64," + camera_frame()}],
+        }
+        await h.run(translate_realtime_command({"type": "conversation.item.create", "item": item}))
+        assert [
+            part
+            for message in h.session.history
+            if isinstance(message.get("content"), list)
+            for part in message["content"]
+            if part.get("type") == "image_url"
+        ], "an image-only item never reached the session history"
+
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        mm = h.port.submissions[-1].prompt["multi_modal_data"]
+        assert len(mm["image"]) == 1 and len(mm["audio"]) == 1
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_one_item_carrying_both_speech_and_a_picture_keeps_both():
+    """Audio and images leave the same item by different routes.
+
+    The audio becomes buffered appends that a commit seals under this item's
+    id; registering the spoken message there would overwrite an image stored
+    under the same id, so the picture has to become its own item.
+    """
+    from vllm_omni.engine.duplex.commands import CreateResponse
+    from vllm_omni.engine.duplex.realtime_commands import translate_realtime_command
+
+    h = await open_qwen()
+    try:
+        item = {
+            "id": "mixed_1",
+            "type": "message",
+            "role": "user",
+            "content": [
+                {"type": "input_image", "image_url": "data:image/jpeg;base64," + camera_frame()},
+                {"type": "input_audio", "audio": pcm16_base64(), "format": "pcm16", "sample_rate_hz": 16000},
+            ],
+        }
+        await h.run(translate_realtime_command({"type": "conversation.item.create", "item": item}))
+        await h.run(CreateResponse())
+        mm = h.port.submissions[-1].prompt["multi_modal_data"]
+        assert len(mm["image"]) == 1, "the picture was dropped on its way out of a mixed item"
+        assert len(mm["audio"]) == 1
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_image_limit_rejects_atomically_and_delete_reclaims_capacity():
+    from vllm_omni.engine.duplex.commands import CreateItem, DeleteItem
+
+    h = await open_qwen()
+    try:
+        for i in range(8):
+            await h.run(CreateItem(item=image_item(f"camera_{i}")))
+        events = await h.run(CreateItem(item=image_item("overflow")))
+        assert any(e.to_realtime()["type"] == "error" for e in events)
+        assert len(h.session.history) == 8
+        await h.run(DeleteItem(item_id="camera_0"))
+        await h.run(CreateItem(item=image_item("replacement")))
+        assert len(h.session.history) == 8
+        assert not h.port.submissions
+    finally:
+        await h.manager.shutdown()
+
+
+def test_prompt_holds_stored_images_to_the_stage_limit():
+    """The prompt is the last guard before ``limit_mm_per_prompt``.
+
+    A dropped image has to take its ``{"type": "image"}`` placeholder with
+    it, because the processor pairs placeholders with ``mm["image"]``
+    positionally.
+    """
+    plugin = Qwen3OmniDuplexPlugin(lambda *args: None)
+    plugin.processor = SimpleNamespace(apply_chat_template=lambda messages, **kwargs: repr(messages))
+    url = "data:image/jpeg;base64," + camera_frame()
+    history: list[dict[str, Any]] = [
+        {
+            "role": "user",
+            "content": [{"type": "image_url", "image_url": {"url": url}}, {"type": "text", "text": f"i{i}"}],
+        }
+        for i in range(MAX_PROMPT_IMAGES + 2)
+    ]
+    audio = base64.b64encode(np.full(160, 0.1, dtype="<f4").tobytes()).decode()
+    history.append({"role": "user", "audio_payload": {"audio": audio}})
+
+    plan = plugin.plan_append(
+        request_id="r",
+        fence=None,
+        session_config={"qwen_messages": history},
+        runtime_config={},
+        seq=1,
+        turn_seq=1,
+        payload={"audio": audio},
+        final=True,
+        sampling_params=None,
+    )
+
+    prompt = plan.prompt
+    assert len(prompt["multi_modal_data"]["image"]) == MAX_PROMPT_IMAGES
+    assert prompt["prompt"].count("{'type': 'image'}") == MAX_PROMPT_IMAGES
+    # Only the image part is retired; the message keeps what it said.
+    assert "'i0'" in prompt["prompt"]
+
+
+def test_text_only_turn_without_prepared_messages_is_refused_not_crashed():
+    plugin = Qwen3OmniDuplexPlugin(lambda *args: None)
+    plugin.processor = SimpleNamespace(apply_chat_template=lambda messages, **kwargs: repr(messages))
+    with pytest.raises(DuplexRuntimeConfigError):
+        plugin.plan_append(
+            request_id="r",
+            fence=None,
+            # An empty prepared list is not a missing one: it must not fall
+            # back to a payload that has no audio to read.
+            session_config={"qwen_messages": []},
+            runtime_config={},
+            seq=1,
+            turn_seq=1,
+            payload={"is_speech": True},
+            final=True,
+            sampling_params=None,
+        )
+
+
+@pytest.mark.asyncio
+async def test_commit_all_on_done_keeps_unaligned_text_the_client_never_acks():
+    h = await open_qwen()
+    try:
+        # The runner starts every session ack-gated; this client opts out.
+        await h.run(UpdateSession(patch={"playback_commit_policy": "commit_all_on_done"}))
+        assert h.session.config.playback_commit_policy == "commit_all_on_done"
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        request_id = h.port.submissions[-1].context.request_id
+        await h.deliver_and_settle(tts_output(request_id, samples=0, text="entire answer", finished=True), stage_id=0)
+        await h.deliver_and_settle(tts_output(request_id, samples=24000, finished=True), stage_id=2)
+        # Qwen text is unaligned to its audio, but waiting for an ACK this
+        # client will never send would drop the turn from history entirely.
+        assert h.session.active_response_id is None
+        assert h.session.history[-1]["content"] == "entire answer"
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_the_bound_request_id_is_the_one_the_stage_received():
+    h = await open_qwen()
+    try:
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        submitted = h.port.submissions[-1].context.request_id
+        # Qwen has no resumable core request, so every turn gets its own stage
+        # id. The runner names that id before the append runs and the model
+        # channel names it again when it submits; they have to agree.
+        assert submitted.endswith(".r.stage0-turn0"), submitted
+        assert h.session.active_request_id == submitted
+    finally:
+        await h.manager.shutdown()
+
+
+@pytest.mark.asyncio
+async def test_visual_capture_records_submitted_pixels_and_request(tmp_path, monkeypatch):
+    import json
+
+    from PIL import Image
+
+    from vllm_omni.engine.duplex.commands import CreateItem
+
+    monkeypatch.setenv("VLLM_OMNI_QWEN_VISUAL_DEBUG_DIR", str(tmp_path))
+    h = await open_qwen()
+    try:
+        await h.run(CreateItem(item=image_item()))
+        await h.run(append_audio())
+        await h.run(Commit(final=True, create_response=True))
+        submission = h.port.submissions[-1]
+        captures = list(tmp_path.glob("*/input.json"))
+        assert len(captures) == 1
+        metadata = json.loads(captures[0].read_text())
+        assert metadata["request_id"] == submission.context.request_id
+        assert metadata["audio_count"] == 1
+        assert metadata["prompt"] == submission.prompt["prompt"]
+        assert len(metadata["images"]) == 1
+        with Image.open(captures[0].parent / metadata["images"][0]) as saved:
+            actual = submission.prompt["multi_modal_data"]["image"][0]
+            assert saved.size == actual.size
+            assert saved.tobytes() == actual.tobytes()
+    finally:
+        await h.manager.shutdown()
diff --git a/vllm_omni/config/environment_variable_inventory.py b/vllm_omni/config/environment_variable_inventory.py
index 97782328d95..27b1a2ac2c4 100644
--- a/vllm_omni/config/environment_variable_inventory.py
+++ b/vllm_omni/config/environment_variable_inventory.py
@@ -203,6 +203,7 @@ def is_public_omni(self) -> bool:
     "MOSS_TTS_DEBUG_STOP",
     "NEMOTRON_VOICECHAT_DEBUG_FUNCTION_TIMELINE",
     "VLLM_OMNI_BREEZE_GOLDEN_DIR",
+    "VLLM_OMNI_QWEN_VISUAL_DEBUG_DIR",
     "VLLM_OMNI_QWEN3_CODE2WAV_BATCH_STATS",
     "VLLM_OMNI_QWEN3_CODE2WAV_BATCH_STATS_LOG_EVERY",
     "VLLM_OMNI_QWEN3_CODE2WAV_CUDAGRAPH_STATS",
diff --git a/vllm_omni/config/stage_config.py b/vllm_omni/config/stage_config.py
index 24453ae88b5..9f45d357dc7 100644
--- a/vllm_omni/config/stage_config.py
+++ b/vllm_omni/config/stage_config.py
@@ -312,6 +312,8 @@ class PipelineConfig:
     # Dotted path of the model's ``DuplexModelPlugin``. Online serving uses
     # DuplexOmni only when the deploy configuration selects session_mode: duplex.
     duplex_plugin: str | None = None
+    # Preserve legacy turn deployments when adding an optional duplex plugin.
+    default_session_mode: str | None = None
     # Legacy duplex wiring of the models that are not ported to the plugin
     # framework yet (PersonaPlex, Nemotron VoiceChat). Nothing reads them: a
     # pipeline that only declares these is served turn-based. Each field goes
diff --git a/vllm_omni/deploy/qwen3_omni_duplex.yaml b/vllm_omni/deploy/qwen3_omni_duplex.yaml
new file mode 100644
index 00000000000..31bfcaadbc5
--- /dev/null
+++ b/vllm_omni/deploy/qwen3_omni_duplex.yaml
@@ -0,0 +1,8 @@
+# Concurrent input / interruptible VAD turns; not native streaming input KV.
+base_config: qwen3_omni_moe.yaml
+session_mode: duplex
+stages:
+  - stage_id: 0
+    limit_mm_per_prompt:
+      audio: 4
+      image: 8
diff --git a/vllm_omni/engine/duplex/config.py b/vllm_omni/engine/duplex/config.py
index a898a2cf5f7..f343a5233dd 100644
--- a/vllm_omni/engine/duplex/config.py
+++ b/vllm_omni/engine/duplex/config.py
@@ -111,6 +111,8 @@ class DuplexCapabilities:
     #: seeding a text prompt has no representation and the turn never
     #: completes. ``text_turn_priming_units`` is how many silence units such a
     #: seeded turn must be given to generate on -- it still speaks per unit.
+    supports_image_input: bool = False
+    supports_text_only_turn: bool = False
     supports_chat_completions: bool = False
     text_turn_priming_units: int = 0
     requires_model_runner_kv: bool = False
@@ -149,11 +151,13 @@ def as_dict(self) -> dict[str, object]:
             "supports_session_resume": self.supports_session_resume,
             "session_admission_mode": self.session_admission_mode,
             "supports_audio_truncate": self.supports_audio_truncate,
+            "supports_image_input": self.supports_image_input,
+            "supports_text_only_turn": self.supports_text_only_turn,
             "requires_model_runner_kv": self.requires_model_runner_kv,
             "requires_native_stage_role": self.requires_native_stage_role,
-            # Every duplex model is model-native and appends audio chunks (§7 D4);
-            # kept on the wire as constants for clients that still read them.
-            "implementation_level": "model_native_duplex",
+            "implementation_level": (
+                "model_native_duplex" if self.supports_model_native_turn_policy else "turn_based_duplex"
+            ),
             "adapter_patterns": self.adapter_patterns,
             "input_modes": ["append_audio_chunk"],
             "signal_sources": self.signal_sources,
@@ -169,6 +173,8 @@ class DuplexPlaybackCursor:
     sent_ms: int = 0
     played_ms: int = 0
     committed_ms: int = 0
+    text_requires_complete_audio: bool = False
+    audio_complete: bool = False
 
     def acknowledge(self, played_ms: int, committed_ms: int | None = None) -> None:
         self.played_ms = max(self.played_ms, max(0, int(played_ms)))
@@ -188,7 +194,11 @@ def as_dict(self) -> dict[str, int]:
         }
 
     def snapshot(self) -> DuplexPlaybackView:
-        return DuplexPlaybackView(**self.as_dict())
+        return DuplexPlaybackView(
+            **self.as_dict(),
+            text_requires_complete_audio=self.text_requires_complete_audio,
+            audio_complete=self.audio_complete,
+        )
 
 
 @dataclass(frozen=True, slots=True)
@@ -197,6 +207,8 @@ class DuplexPlaybackView:
     sent_ms: int = 0
     played_ms: int = 0
     committed_ms: int = 0
+    text_requires_complete_audio: bool = False
+    audio_complete: bool = False
 
     def as_dict(self) -> dict[str, int]:
         return {
@@ -310,16 +322,21 @@ def from_event(cls, event: dict[str, object]) -> DuplexSessionConfig:
         if isinstance(source.get("extra_body"), dict):
             config.extra_body = dict(source["extra_body"])
             extra = config.extra_body
-            if isinstance(extra.get("overlap_policy"), str):
-                config.overlap_policy = cls._normalize_overlap_policy(extra["overlap_policy"])
-            if isinstance(extra.get("overlap_short_ack_ms"), int | float):
-                config.overlap_short_ack_ms = max(0, int(extra["overlap_short_ack_ms"]))
-            if isinstance(extra.get("overlap_barge_in_ms"), int | float):
-                config.overlap_barge_in_ms = max(0, int(extra["overlap_barge_in_ms"]))
-            if isinstance(extra.get("overlap_silence_rms"), int | float):
-                config.overlap_silence_rms = max(0.0, float(extra["overlap_silence_rms"]))
-            if isinstance(extra.get("playback_commit_policy"), str):
-                config.playback_commit_policy = cls._normalize_playback_commit_policy(extra["playback_commit_policy"])
+            overlap_policy = extra.get("overlap_policy")
+            if isinstance(overlap_policy, str):
+                config.overlap_policy = cls._normalize_overlap_policy(overlap_policy)
+            short_ack_ms = extra.get("overlap_short_ack_ms")
+            if isinstance(short_ack_ms, int | float):
+                config.overlap_short_ack_ms = max(0, int(short_ack_ms))
+            barge_in_ms = extra.get("overlap_barge_in_ms")
+            if isinstance(barge_in_ms, int | float):
+                config.overlap_barge_in_ms = max(0, int(barge_in_ms))
+            silence_rms = extra.get("overlap_silence_rms")
+            if isinstance(silence_rms, int | float):
+                config.overlap_silence_rms = max(0.0, float(silence_rms))
+            playback_commit_policy = extra.get("playback_commit_policy")
+            if isinstance(playback_commit_policy, str):
+                config.playback_commit_policy = cls._normalize_playback_commit_policy(playback_commit_policy)
         return config
 
     @classmethod
@@ -633,7 +650,6 @@ def from_realtime(
         from vllm_omni.protocol.duplex import (
             REALTIME_OUTPUT_AUDIO_FORMATS,
             parse_realtime_audio_format,
-            realtime_max_output_tokens,
         )
 
         payload: dict[str, object] = dict(response_payload)
@@ -665,11 +681,12 @@ def from_realtime(
         response_format = payload.get("output_audio_format") or payload.get("response_format")
         if response_format is None and isinstance(audio_output, dict):
             response_format = audio_output.get("format")
-        response_format, _ = parse_realtime_audio_format(response_format)
-        if isinstance(response_format, str) and response_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
-            response_format = duplex_response_format(response_format)
+        parsed_format, _ = parse_realtime_audio_format(response_format)
+        output_audio_format: str | None
+        if isinstance(parsed_format, str) and parsed_format.lower() in REALTIME_OUTPUT_AUDIO_FORMATS:
+            output_audio_format = str(duplex_response_format(parsed_format))
         else:
-            response_format = None
+            output_audio_format = None
         temperature = (
             float(cast("int | float", payload["temperature"]))
             if isinstance(payload.get("temperature"), int | float)
@@ -687,9 +704,9 @@ def from_realtime(
             else payload.get("max_tokens")
         )
         if "max_response_output_tokens" in payload or "max_output_tokens" in payload or "max_tokens" in payload:
-            max_tokens = realtime_max_output_tokens(max_tokens)
+            token_limit = realtime_max_output_tokens(max_tokens)
         else:
-            max_tokens = None
+            token_limit = None
         modalities = payload.get("modalities") or payload.get("output_modalities")
         if isinstance(modalities, list) and all(isinstance(item, str) for item in modalities):
             modalities = tuple(modalities)
@@ -717,9 +734,9 @@ def from_realtime(
         return cls(
             instructions=instructions,
             voice=voice,
-            response_format=response_format,
+            response_format=output_audio_format,
             temperature=temperature,
-            max_tokens=max_tokens,
+            max_tokens=token_limit,
             speed=speed,
             modalities=modalities,
             extra_body=response_extra,
@@ -761,6 +778,8 @@ def realtime_item_to_history_message(item: object) -> dict[str, object] | None:
         part_type = part.get("type")
         if part_type in {"input_text", "text", "output_text"} and isinstance(part.get("text"), str):
             text_chunks.append(str(part["text"]))
+        elif part_type == "input_image" and isinstance(part.get("image_url"), str):
+            audio_chunks.append({"type": "image_url", "image_url": {"url": part["image_url"]}})
         elif part_type in {"input_audio", "audio"}:
             audio = part.get("audio") or part.get("data")
             fmt = part.get("format") if isinstance(part.get("format"), str) else "wav"
diff --git a/vllm_omni/engine/duplex/plugin.py b/vllm_omni/engine/duplex/plugin.py
index f9f9be283c6..1e2517ef640 100644
--- a/vllm_omni/engine/duplex/plugin.py
+++ b/vllm_omni/engine/duplex/plugin.py
@@ -179,6 +179,7 @@ class DuplexModelPlugin(ABC):
     two halves is impossible by construction.
     """
 
+    projects_intermediate_outputs: bool = False
     plugin_id: str = ""
     private_runtime_config_keys: frozenset[str] = frozenset()
     #: Samples per silence unit the runner appends to keep a model turn going.
@@ -199,6 +200,16 @@ def configure_sampling_params(
         defaults: tuple[object, ...],
     ) -> tuple[object, ...]: ...
 
+    def prepare_prompt_config(
+        self, config: dict[str, object], *, state: DuplexModelSessionState, payload: dict[str, object]
+    ) -> dict[str, object]:
+        """Add model-owned context before planning an append on the session loop."""
+        return config
+
+    async def prepare_append_plan(self, **kwargs) -> DuplexAppendPlan:
+        """Prepare a plan; plugins may offload expensive work on owned snapshots."""
+        return self.plan_append(**kwargs)
+
     @abstractmethod
     def plan_append(
         self,
@@ -312,10 +323,16 @@ def payload_turn_id(payload: object) -> int | None:
 
 
 def coerce_int(value: object) -> int | None:
-    try:
-        return int(value) if value is not None else None
-    except (TypeError, ValueError):
-        return None
+    if isinstance(value, bool):
+        return int(value)
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float | str | bytes | bytearray):
+        try:
+            return int(value)
+        except (TypeError, ValueError, OverflowError):
+            return None
+    return None
 
 
 __all__ = [
diff --git a/vllm_omni/engine/duplex/realtime_events.py b/vllm_omni/engine/duplex/realtime_events.py
index f67abbbc9fb..a6a619ac807 100644
--- a/vllm_omni/engine/duplex/realtime_events.py
+++ b/vllm_omni/engine/duplex/realtime_events.py
@@ -327,7 +327,7 @@ def _response_done_output_item(
         )
     if text:
         content.append(_response_item_text_content_part(text=text))
-    item = {
+    item: dict[str, object] = {
         "id": item_id,
         "object": "realtime.item",
         "type": "message",
@@ -796,7 +796,7 @@ def _project(state: RealtimeProjectionState, event: dict[str, object]) -> list[D
         item_id = _response_item_id(state, response_id)
         modalities = event.get("modalities")
         has_audio_modality = not isinstance(modalities, list) or "audio" in modalities
-        item = {
+        item: dict[str, object] = {
             "id": item_id,
             "object": "realtime.item",
             "type": "message",
@@ -900,13 +900,13 @@ def _project(state: RealtimeProjectionState, event: dict[str, object]) -> list[D
         item_id = (
             event_item_id if isinstance(event_item_id, str) and event_item_id else _pop_pending_commit_item_id(state)
         )
-        item = state.conversation_items.get(item_id)
-        events = []
-        if item is None:
+        committed_item = state.conversation_items.get(item_id)
+        commit_events: list[DuplexEvent] = []
+        if committed_item is None:
             message = event.get("message")
             no_response = event.get("no_response") is True
             is_speech = event.get("is_speech")
-            item = {
+            created_commit_item: dict[str, object] = {
                 "id": item_id,
                 "object": "realtime.item",
                 "type": "message",
@@ -918,17 +918,18 @@ def _project(state: RealtimeProjectionState, event: dict[str, object]) -> list[D
                     else _user_item_content_from_duplex_message(message)
                 ),
             }
-            state.conversation_items[item_id] = item
-            events.extend(_conversation_item_added_events(state, item))
-        item["status"] = "completed"
-        events.append(
+            committed_item = created_commit_item
+            state.conversation_items[item_id] = committed_item
+            commit_events.extend(_conversation_item_added_events(state, committed_item))
+        committed_item["status"] = "completed"
+        commit_events.append(
             InputCommitted(previous_item_id=_previous_item_id(state, item_id), item_id=item_id, details=event)
         )
-        transcription_event = _input_audio_transcription_completed_event(item_id, item)
+        transcription_event = _input_audio_transcription_completed_event(item_id, committed_item)
         if transcription_event is not None:
-            events.append(transcription_event)
-        events.append(_conversation_item_done_event(state, item))
-        return events
+            commit_events.append(transcription_event)
+        commit_events.append(_conversation_item_done_event(state, committed_item))
+        return commit_events
     if event_type == "input.cancelled":
         return [InputCleared()]
     if event_type == "audio.cancelled":
@@ -951,9 +952,9 @@ def _project(state: RealtimeProjectionState, event: dict[str, object]) -> list[D
             item_id = _response_item_id(state, response_id)
             committed_audio_ms = max(0, int(committed_ms))
             state.item_truncation_cursors[item_id] = (0, committed_audio_ms)
-            item = state.conversation_items.get(item_id)
-            if item is not None:
-                truncate_realtime_item_content(item, content_index=0, audio_end_ms=committed_audio_ms)
+            cancelled_item = state.conversation_items.get(item_id)
+            if cancelled_item is not None:
+                truncate_realtime_item_content(cancelled_item, content_index=0, audio_end_ms=committed_audio_ms)
         events.extend(_realtime_audio_done_events(state, event, response_id))
         events.extend(
             _realtime_response_terminal_events(
@@ -968,48 +969,49 @@ def _project(state: RealtimeProjectionState, event: dict[str, object]) -> list[D
             state.active_response_id = None
         return events
     if event_type == "conversation.item.created":
-        item = event.get("item")
-        if isinstance(item, dict) and isinstance(item.get("id"), str):
-            item_id = str(item["id"])
-            already_known = item_id in state.conversation_items
-            state.conversation_items[item_id] = item
+        created_raw = event.get("item")
+        if isinstance(created_raw, dict) and isinstance(created_raw.get("id"), str):
+            created_item_id = str(created_raw["id"])
+            created_item = cast("dict[str, object]", created_raw)
+            already_known = created_item_id in state.conversation_items
+            state.conversation_items[created_item_id] = created_item
             if already_known:
-                if item.get("status") == "completed":
-                    return [_conversation_item_done_event(state, item)]
+                if created_item.get("status") == "completed":
+                    return [_conversation_item_done_event(state, created_item)]
                 return []
-            events = _conversation_item_added_events(state, item)
-            if item.get("status") == "completed":
-                events.append(_conversation_item_done_event(state, item))
-            return events
-        return [ItemCreated(item=item if isinstance(item, Mapping) else {})]
+            created_events = _conversation_item_added_events(state, created_item)
+            if created_item.get("status") == "completed":
+                created_events.append(_conversation_item_done_event(state, created_item))
+            return created_events
+        return [ItemCreated(item=created_raw if isinstance(created_raw, Mapping) else {})]
     if event_type == "conversation.item.deleted":
-        item_id = event.get("item_id")
-        if isinstance(item_id, str):
-            _remove_conversation_item(state, item_id)
-        return [ItemDeleted(item_id=_str_or_none(item_id), details=event)]
+        deleted_item_id = event.get("item_id")
+        if isinstance(deleted_item_id, str):
+            _remove_conversation_item(state, deleted_item_id)
+        return [ItemDeleted(item_id=_str_or_none(deleted_item_id), details=event)]
     if event_type == "conversation.item.truncated":
-        item_id = event.get("item_id")
+        truncated_item_id = event.get("item_id")
         audio_end_ms = event.get("audio_end_ms")
         content_index = event.get("content_index", 0)
-        if isinstance(item_id, str):
-            item = state.conversation_items.get(item_id)
-            if item is not None:
+        if isinstance(truncated_item_id, str):
+            truncated_item = state.conversation_items.get(truncated_item_id)
+            if truncated_item is not None:
                 truncate_realtime_item_content(
-                    item,
+                    truncated_item,
                     content_index=_int_or(content_index),
                     audio_end_ms=_int_or(audio_end_ms),
                 )
         return [
             ItemTruncated(
-                item_id=_str_or_none(item_id),
+                item_id=_str_or_none(truncated_item_id),
                 content_index=_int_or(content_index),
                 audio_end_ms=_int_or(audio_end_ms),
                 details=event,
             )
         ]
     if event_type == "conversation.item.retrieved":
-        item = event.get("item")
-        return [ItemRetrieved(item=item if isinstance(item, Mapping) else {})]
+        retrieved_item = event.get("item")
+        return [ItemRetrieved(item=retrieved_item if isinstance(retrieved_item, Mapping) else {})]
     if event_type == "response.output_item.done":
         response_id = event.get("response_id")
         return _realtime_response_terminal_events(
@@ -1044,7 +1046,7 @@ def _function_call_done_events(state: RealtimeProjectionState, event: dict[str,
         arguments = str(arguments)
     response_id = f"resp_{uuid4().hex}"
     item_id = f"item_{uuid4().hex}"
-    item = {
+    item: dict[str, object] = {
         "id": item_id,
         "object": "realtime.item",
         "type": "function_call",
@@ -1431,7 +1433,7 @@ def resolve_create_item(state: RealtimeProjectionState, command: CreateItem) ->
                 ],
             )
     ack_events = register_user_item(state, item) if item_type == "message" and role == "user" else []
-    signal_payload = {
+    signal_payload: dict[str, object] = {
         "type": "turn.signal",
         "event": "conversation.item.create",
         "payload": {"item": item},
@@ -1444,12 +1446,15 @@ def resolve_create_item(state: RealtimeProjectionState, command: CreateItem) ->
     if not isinstance(content, list):
         return ResolvedControl(payloads=[], events=ack_events)
     text_chunks: list[str] = []
+    image_parts: list[Mapping[str, object]] = []
     audio_payloads: list[dict[str, object]] = []
     for part in content:
         if not isinstance(part, dict):
             continue
         if part.get("type") in {"input_text", "text"} and isinstance(part.get("text"), str):
             text_chunks.append(str(part["text"]))
+        if part.get("type") == "input_image":
+            image_parts.append(part)
         if part.get("type") in {"input_audio", "audio"}:
             audio = part.get("audio") or part.get("data")
             if not isinstance(audio, str) or not audio:
@@ -1494,12 +1499,28 @@ def resolve_create_item(state: RealtimeProjectionState, command: CreateItem) ->
         }
         if transcript:
             commit_payload["transcript"] = transcript
-        return ResolvedControl(payloads=[*audio_payloads, commit_payload], events=ack_events)
-    if not text_chunks:
+        payloads: list[dict[str, object]] = []
+        if image_parts:
+            # The audio leaves as buffered appends that the commit seals, and
+            # that commit registers *this* item id against the spoken message.
+            # Images cannot ride it: the commit would overwrite them. So they
+            # travel as their own item, stored ahead of the audio describing
+            # them, under an id derived from the one the client named.
+            image_item = dict(item)
+            image_item["id"] = f"{item_id}_image"
+            image_item["status"] = "completed"
+            image_item["content"] = list(image_parts)
+            payloads.append({**signal_payload, "payload": {"item": image_item}})
+        payloads.extend([*audio_payloads, commit_payload])
+        return ResolvedControl(payloads=payloads, events=ack_events)
+    if not text_chunks and not image_parts:
         return ResolvedControl(payloads=[], events=ack_events)
-    text_item = dict(item)
-    text_item["status"] = "completed"
-    signal_payload["payload"] = {"item": text_item}
+    # An image is content in its own right, not a decoration on text. Dropping
+    # the payload here would still ack the item to the client, so the picture
+    # would be silently missing from every prompt that followed.
+    stored_item = dict(item)
+    stored_item["status"] = "completed"
+    signal_payload["payload"] = {"item": stored_item}
     return ResolvedControl(payloads=[signal_payload], events=ack_events)
 
 
diff --git a/vllm_omni/engine/duplex/session/append_task.py b/vllm_omni/engine/duplex/session/append_task.py
index 2bc060d63ec..6092f26cf83 100644
--- a/vllm_omni/engine/duplex/session/append_task.py
+++ b/vllm_omni/engine/duplex/session/append_task.py
@@ -110,8 +110,7 @@ async def run_in_wire_order(self, predecessor: asyncio.Task[bool] | None) -> boo
             try:
                 predecessor_ok = await predecessor
             except asyncio.CancelledError:
-                current = asyncio.current_task()
-                if current is not None and current.cancelling():
+                if helpers.task_is_cancelling(asyncio.current_task()):
                     raise
                 predecessor_ok = False
             except Exception:
@@ -159,8 +158,10 @@ async def _submit(self) -> bool:
                 self.ctx.run.runtime_closed = True
                 return False
             if not emitted_response and session.epoch == self.epoch:
-                if session.active_request_id == helpers.stage0_request_id(session, self.epoch):
-                    session.clear_request(self.request_id)
+                # Only if the session still points at this append's request:
+                # ``clear_request`` compares before it clears, and the id
+                # carries a turn suffix when the core request is not resumable.
+                session.clear_request(self.request_id)
                 if self.final:
                     self.out.emit_events([session.signal_turn(DuplexTurnEventType.USER_STARTED.value)])
             return append_ok
diff --git a/vllm_omni/engine/duplex/session/control.py b/vllm_omni/engine/duplex/session/control.py
index 2d46154fe49..5de703acd54 100644
--- a/vllm_omni/engine/duplex/session/control.py
+++ b/vllm_omni/engine/duplex/session/control.py
@@ -113,6 +113,19 @@ async def run_turn_detection(self, event: dict[str, object]) -> TurnDetectionRes
         except ValueError as exc:
             self._out.emit_error("bad_audio", str(exc))
             return None
+        if result.speech_started or result.speech_stopped:
+            logger.info(
+                "Duplex VAD session=%s started=%s stopped=%s active=%s probability=%.3f "
+                "start_ms=%s end_ms=%s commit=%s",
+                self._ctx.session.session_id,
+                result.speech_started,
+                result.speech_stopped,
+                result.speech_active,
+                result.speech_probability,
+                result.audio_start_ms,
+                result.audio_end_ms,
+                result.should_commit,
+            )
         apply_turn_detection_result(event, result)
         return result
 
@@ -310,6 +323,47 @@ async def _on_conversation_item_create(self, event: dict[str, object]) -> None:
                 name="duplex-continue",
             )
             return
+        item_payload = item if isinstance(item, dict) else None
+        raw_parts = item_payload.get("content", []) if item_payload is not None else []
+        parts: list[object] = [part for part in raw_parts] if isinstance(raw_parts, list) else []
+        images = [p for p in parts if isinstance(p, dict) and p.get("type") == "input_image"]
+        if images:
+            if item_payload is None or item_payload.get("role") != "user":
+                self._out.emit_error("invalid_image", "input_image is supported only in user messages")
+                return
+            if not session.capabilities.supports_image_input:
+                self._out.emit_error("unsupported", "This model does not support input_image conversation items")
+                return
+            from vllm_omni.engine.duplex.realtime_commands import validate_realtime_video_frames
+
+            urls: list[str] = []
+            for part in images:
+                url = part.get("image_url")
+                if not isinstance(url, str) or not url.startswith(
+                    ("data:image/jpeg;base64,", "data:image/png;base64,")
+                ):
+                    self._out.emit_error("invalid_image", "input_image requires a JPEG or PNG base64 data URL")
+                    return
+                error = validate_realtime_video_frames([url.split(",", 1)[1]], None)
+                if error:
+                    self._out.emit_error("invalid_image", error)
+                    return
+                urls.append(url)
+            existing: list[str] = []
+            for history_message in session.history:
+                content = history_message.get("content")
+                if not isinstance(content, list):
+                    continue
+                for part in content:
+                    if not isinstance(part, dict) or part.get("type") != "image_url":
+                        continue
+                    image_url = part.get("image_url")
+                    nested_url = image_url.get("url") if isinstance(image_url, dict) else None
+                    if isinstance(nested_url, str):
+                        existing.append(nested_url)
+            if len(existing) + len(urls) > 8 or sum(map(len, existing + urls)) > 4 * 1024 * 1024:
+                self._out.emit_error("input_backpressure", "Image context exceeds 8 images or 4 MiB; delete old items")
+                return
         message = realtime_item_to_history_message(item)
         item_id = item.get("id") if isinstance(item, dict) else None
         if message is not None:
diff --git a/vllm_omni/engine/duplex/session/engine_session.py b/vllm_omni/engine/duplex/session/engine_session.py
index bb5c3851594..f64ad1f937a 100644
--- a/vllm_omni/engine/duplex/session/engine_session.py
+++ b/vllm_omni/engine/duplex/session/engine_session.py
@@ -20,7 +20,7 @@
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field
 from types import MappingProxyType
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 from uuid import uuid4
 
 from vllm_omni.engine.duplex.config import (
@@ -53,6 +53,42 @@ def _default_lease() -> DuplexLeaseState:
     return DuplexLeaseState(config=DuplexLeaseConfig(), generation=0, last_activity=time.monotonic())
 
 
+def _object_dict(**fields: object) -> dict[str, object]:
+    return dict(fields)
+
+
+def _as_int(value: object, default: int = 0) -> int:
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    return default
+
+
+def _as_optional_int(value: object) -> int | None:
+    if value is None or isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(value)
+    return None
+
+
+def _copy_mapping(value: object) -> dict[str, object] | None:
+    if not isinstance(value, dict):
+        return None
+    return {str(key): item for key, item in value.items()}
+
+
+def _copy_list(value: object) -> list[object] | None:
+    if not isinstance(value, list):
+        return None
+    return [item for item in value]
+
+
 @dataclass
 class InputBufferState:
     commit_seq: int = 0
@@ -624,7 +660,7 @@ def commit_audio_input(
             input_audio_part["transcript"] = transcript
         self._bind_active_response_to_input_commit(self._input.commit_seq + 1)
         self._input.commit_seq += 1
-        message = {"role": "user", "content": [input_audio_part]}
+        message = _object_dict(role="user", content=[input_audio_part])
         if transcript:
             message["transcript"] = transcript
         self._conversation.messages.append(message)
@@ -694,7 +730,7 @@ def _clear_response_metrics(self) -> None:
         self._response.stage_metric_tpot_weighted_ms.clear()
         self._response.stage_metric_tpot_weight.clear()
 
-    def stash_stage_metrics(self, stage_metrics: Mapping[object, object] | None) -> None:
+    def stash_stage_metrics(self, stage_metrics: Mapping[Any, Any] | None) -> None:
         """Hold a stage snapshot until a response exists to attribute it to.
 
         A stage that hands its output to the next stage instead of the client
@@ -706,9 +742,10 @@ def stash_stage_metrics(self, stage_metrics: Mapping[object, object] | None) ->
         """
         if not isinstance(stage_metrics, Mapping):
             return
-        snapshot = {
-            str(stage_id): dict(values) for stage_id, values in stage_metrics.items() if isinstance(values, Mapping)
-        }
+        snapshot: dict[str, dict[str, object]] = {}
+        for stage_id, values in stage_metrics.items():
+            if isinstance(values, Mapping):
+                snapshot[str(stage_id)] = {str(key): value for key, value in values.items()}
         if not snapshot:
             return
         if self.active_response_id is not None:
@@ -718,7 +755,7 @@ def stash_stage_metrics(self, stage_metrics: Mapping[object, object] | None) ->
 
     def accumulate_response_stage_metrics(
         self,
-        stage_metrics: Mapping[object, object] | None,
+        stage_metrics: Mapping[Any, Any] | None,
     ) -> dict[str, dict[str, object]]:
         if self.active_response_id is None:
             return copy.deepcopy(self._response.stage_metrics)
@@ -762,7 +799,9 @@ def accumulate_response_stage_metrics(
             for name in additive_fields:
                 value = raw_values.get(name)
                 if isinstance(value, int | float) and not isinstance(value, bool):
-                    current[name] = current.get(name, 0) + value
+                    previous = current.get(name, 0)
+                    addend = previous if isinstance(previous, int | float) and not isinstance(previous, bool) else 0
+                    current[name] = addend + value
             for name in first_positive_fields:
                 value = raw_values.get(name)
                 current_value = current.get(name)
@@ -776,7 +815,8 @@ def accumulate_response_stage_metrics(
             for list_name, mean_name in interval_fields:
                 values = raw_values.get(list_name)
                 if isinstance(values, list):
-                    combined = list(current.get(list_name, []))
+                    existing = current.get(list_name, [])
+                    combined = list(existing) if isinstance(existing, list) else []
                     combined.extend(
                         value for value in values if isinstance(value, int | float) and not isinstance(value, bool)
                     )
@@ -805,7 +845,7 @@ def accumulate_response_stage_metrics(
 
     def replace_response_stage_metric_snapshots(
         self,
-        stage_metrics: Mapping[object, object] | None,
+        stage_metrics: Mapping[Any, Any] | None,
     ) -> dict[str, dict[str, object]]:
         """Merge cumulative chat snapshots by replacing each stage's latest value."""
         if self.active_response_id is None or not isinstance(stage_metrics, Mapping):
@@ -839,8 +879,12 @@ def mark_audio_sent(
         *,
         text_chars: int | None = None,
         audio_text_marks: list[dict[str, object]] | None = None,
+        text_requires_complete_audio: bool = False,
+        audio_complete: bool = False,
     ) -> None:
         playback = self._playback.current
+        playback.text_requires_complete_audio |= text_requires_complete_audio
+        playback.audio_complete |= audio_complete
         if duration_ms is not None:
             playback.generated_ms = max(playback.generated_ms, duration_ms)
             playback.sent_ms = max(playback.sent_ms, duration_ms)
@@ -925,9 +969,9 @@ def end_response(
             response_input_commit_seq = self.input_commit_seq
         response_history_is_late = self.input_commit_seq > response_input_commit_seq
         assistant_text = "".join(self._response.assistant_text_buffer).strip()
-        message = None
+        message: dict[str, object] | None = None
         if assistant_text:
-            self._conversation.last_assistant_full_message = {"role": "assistant", "content": assistant_text}
+            self._conversation.last_assistant_full_message = _object_dict(role="assistant", content=assistant_text)
             self._conversation.last_assistant_audio_text_marks = list(self._response.assistant_audio_text_marks)
             if response_id is not None:
                 self._conversation.assistant_response_snapshots[response_id] = (
@@ -943,7 +987,7 @@ def end_response(
         else:
             committed_text = ""
         if commit_text and committed_text:
-            message = {"role": "assistant", "content": committed_text}
+            message = _object_dict(role="assistant", content=committed_text)
             item_id = f"item_{response_id}" if response_id is not None else None
             if item_id is not None and item_id in self._conversation.history_item_placeholders:
                 self._store_history_item_message(item_id, message)
@@ -1078,8 +1122,8 @@ def truncate_history_item(
             self._conversation.pending_truncations_ms.pop(item_id, None)
             return True
 
-        message = self._conversation.item_ids.get(item_id)
-        if message is None:
+        stored_message = self._conversation.item_ids.get(item_id)
+        if stored_message is None:
             pending = self._conversation.pending_item_ids.get(item_id)
             if pending is None:
                 self._conversation.pending_truncations_ms[item_id] = max(0, int(audio_end_ms))
@@ -1113,6 +1157,7 @@ def truncate_history_item(
             if item_id.startswith("item_"):
                 self._conversation.assistant_response_snapshots.pop(item_id.removeprefix("item_"), None)
             return True
+        message = stored_message
         changed = self._truncate_message_to_audio_ms(
             message,
             audio_end_ms=audio_end_ms,
@@ -1209,12 +1254,20 @@ def _playback_committed_text(
         sent_ms = max(self.playback.sent_ms, self.playback.generated_ms)
         committed_ms = self.playback.committed_ms
         policy = playback_commit_policy or self.config.playback_commit_policy
+        commit_all = policy == DuplexPlaybackCommitPolicy.COMMIT_ALL_ON_DONE.value
+        if self.playback.text_requires_complete_audio:
+            # Unaligned text has no spoken prefix to cut at, so history gets
+            # the whole answer or none of it. Under commit_all_on_done that
+            # choice is the whole answer --- which is also the only thing a
+            # client that never acks playback can be credited with.
+            if commit_all:
+                return assistant_text
+            keep_chars = self._text_chars_for_audio_ms(committed_ms, len(assistant_text))
+            return assistant_text[:keep_chars].rstrip()
         if sent_ms <= 0 or committed_ms >= sent_ms:
             return assistant_text
         if committed_ms <= 0:
-            if policy == DuplexPlaybackCommitPolicy.COMMIT_ALL_ON_DONE.value:
-                return assistant_text
-            return ""
+            return assistant_text if commit_all else ""
         keep_chars = self._text_chars_for_audio_ms(committed_ms, len(assistant_text))
         if keep_chars <= 0:
             return ""
@@ -1233,6 +1286,11 @@ def _text_chars_for_audio_ms(
         audio_end_ms = max(0, int(audio_end_ms))
         marks = marks if marks is not None else self._response.assistant_audio_text_marks
         playback = playback or self._playback.current
+        if playback.text_requires_complete_audio:
+            # Unaligned streams cannot establish a spoken prefix. A terminal
+            # boundary plus its playback ACK can establish the whole answer.
+            total_ms = max(playback.sent_ms, playback.generated_ms)
+            return text_len if playback.audio_complete and total_ms > 0 and audio_end_ms >= total_ms else 0
         if not marks:
             sent_ms = max(1, playback.sent_ms, playback.generated_ms)
             return int(text_len * max(0.0, min(1.0, audio_end_ms / sent_ms)))
@@ -1307,11 +1365,9 @@ def signal_turn(self, event_type: str, payload: Mapping[str, object] | None = No
         elif event_type == DuplexTurnEventType.ASSISTANT_DONE.value:
             self.transition_turn(DuplexTurnState.IDLE)
         elif event_type == DuplexTurnEventType.PLAYBACK_ACK.value:
-            played_ms = int(payload.get("played_ms", 0) or 0)
-            committed_ms = payload.get("committed_ms")
             self.acknowledge_playback(
-                played_ms,
-                int(committed_ms) if isinstance(committed_ms, int | float) else None,
+                _as_int(payload.get("played_ms", 0)),
+                _as_optional_int(payload.get("committed_ms")),
             )
         elif event_type == DuplexTurnEventType.BARGE_IN.value:
             self.transition_turn(DuplexTurnState.BARGE_IN)
@@ -1346,29 +1402,45 @@ def as_public_dict(self) -> dict[str, object]:
             "playback": self.playback.as_dict(),
             "capabilities": self.capabilities.as_dict(),
         }
-        if isinstance(self.config.extra_body.get("realtime_tools"), list):
-            payload["tools"] = self.config.extra_body["realtime_tools"]
-        if isinstance(self.config.extra_body.get("realtime_tool_choice"), str | dict):
-            payload["tool_choice"] = self.config.extra_body["realtime_tool_choice"]
-        if isinstance(self.config.extra_body.get("realtime_metadata"), dict):
-            payload["metadata"] = dict(self.config.extra_body["realtime_metadata"])
-        if isinstance(self.config.extra_body.get("realtime_include"), list):
-            payload["include"] = list(self.config.extra_body["realtime_include"])
-        if isinstance(self.config.extra_body.get("realtime_prompt"), dict):
-            payload["prompt"] = dict(self.config.extra_body["realtime_prompt"])
-        if isinstance(self.config.extra_body.get("realtime_input_audio_transcription"), dict):
-            payload["input_audio_transcription"] = dict(self.config.extra_body["realtime_input_audio_transcription"])
-        if isinstance(self.config.extra_body.get("realtime_input_audio_noise_reduction"), dict):
-            payload["input_audio_noise_reduction"] = dict(
-                self.config.extra_body["realtime_input_audio_noise_reduction"]
-            )
-        if isinstance(self.config.extra_body.get("realtime_audio"), dict):
-            payload["audio"] = dict(self.config.extra_body["realtime_audio"])
-        if isinstance(self.config.extra_body.get("realtime_tracing"), str | dict):
-            payload["tracing"] = self.config.extra_body["realtime_tracing"]
-        raw_realtime_session = self.config.extra_body.get("realtime_session_payload")
-        if isinstance(raw_realtime_session, dict):
-            for key, value in raw_realtime_session.items():
+        extra_body = self.config.extra_body
+        realtime_tools = _copy_list(extra_body.get("realtime_tools"))
+        if realtime_tools is not None:
+            payload["tools"] = realtime_tools
+        realtime_tool_choice = extra_body.get("realtime_tool_choice")
+        if isinstance(realtime_tool_choice, str):
+            payload["tool_choice"] = realtime_tool_choice
+        else:
+            copied_tool_choice = _copy_mapping(realtime_tool_choice)
+            if copied_tool_choice is not None:
+                payload["tool_choice"] = copied_tool_choice
+        realtime_metadata = _copy_mapping(extra_body.get("realtime_metadata"))
+        if realtime_metadata is not None:
+            payload["metadata"] = realtime_metadata
+        realtime_include = _copy_list(extra_body.get("realtime_include"))
+        if realtime_include is not None:
+            payload["include"] = realtime_include
+        realtime_prompt = _copy_mapping(extra_body.get("realtime_prompt"))
+        if realtime_prompt is not None:
+            payload["prompt"] = realtime_prompt
+        realtime_transcription = _copy_mapping(extra_body.get("realtime_input_audio_transcription"))
+        if realtime_transcription is not None:
+            payload["input_audio_transcription"] = realtime_transcription
+        realtime_noise_reduction = _copy_mapping(extra_body.get("realtime_input_audio_noise_reduction"))
+        if realtime_noise_reduction is not None:
+            payload["input_audio_noise_reduction"] = realtime_noise_reduction
+        realtime_audio = _copy_mapping(extra_body.get("realtime_audio"))
+        if realtime_audio is not None:
+            payload["audio"] = realtime_audio
+        realtime_tracing = extra_body.get("realtime_tracing")
+        if isinstance(realtime_tracing, str):
+            payload["tracing"] = realtime_tracing
+        else:
+            copied_tracing = _copy_mapping(realtime_tracing)
+            if copied_tracing is not None:
+                payload["tracing"] = copied_tracing
+        copied_session = _copy_mapping(extra_body.get("realtime_session_payload"))
+        if copied_session is not None:
+            for key, value in copied_session.items():
                 if key not in payload and key != "extra_body":
                     payload[key] = value
         return payload
diff --git a/vllm_omni/engine/duplex/session/helpers.py b/vllm_omni/engine/duplex/session/helpers.py
index f8b705e6d2e..02ae1b7ca02 100644
--- a/vllm_omni/engine/duplex/session/helpers.py
+++ b/vllm_omni/engine/duplex/session/helpers.py
@@ -13,14 +13,16 @@
 
 from __future__ import annotations
 
+import asyncio
 import binascii
 from typing import TYPE_CHECKING
 
 import pybase64 as base64
 
 from vllm_omni.engine.duplex.config import DuplexPlaybackCommitPolicy
-from vllm_omni.engine.duplex.contracts import DuplexFence, duplex_resource_request_id
+from vllm_omni.engine.duplex.contracts import DuplexFence
 from vllm_omni.engine.duplex.events import ErrorEvent, OverlapDecision, error_event
+from vllm_omni.engine.duplex.plugin import payload_turn_id
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
@@ -29,13 +31,38 @@
     from vllm_omni.engine.duplex.session.engine_session import DuplexCommittedInput, DuplexEngineSession
 
 
+def task_is_cancelling(task: asyncio.Task[object] | None) -> bool:
+    """True when *task* has a pending cancellation (Python 3.11+ ``Task.cancelling``)."""
+    if task is None:
+        return False
+    cancelling = getattr(task, "cancelling", None)
+    return bool(cancelling()) if callable(cancelling) else False
+
+
 # --------------------------------------------------------------------------- #
 # Questions about the session                                                 #
 # --------------------------------------------------------------------------- #
 
 
-def stage0_request_id(session: DuplexEngineSession, epoch: int) -> str:
-    return duplex_resource_request_id(DuplexFence(session.session_id, epoch=epoch), "stage0")
+def append_fence(session: DuplexEngineSession, payload: object, *, epoch: int | None = None) -> DuplexFence:
+    """The fence one append is submitted under.
+
+    A model without a resumable core request gets one stage request per turn,
+    so the turn this resolves to is part of the request id. The runner names
+    that id when it queues the append and the model channel names it again
+    when it submits, and the two must not disagree --- otherwise the session
+    binds a request id it never submitted.
+    """
+    turn_id = payload_turn_id(payload)
+    if turn_id is None:
+        turn_id = session.active_response_turn_id
+    if turn_id is None:
+        turn_id = session.turn_id
+    return DuplexFence(
+        session.session_id,
+        epoch=session.epoch if epoch is None else epoch,
+        turn_id=turn_id,
+    )
 
 
 def response_in_progress(session: DuplexEngineSession, tasks: DuplexSessionTasks) -> bool:
diff --git a/vllm_omni/engine/duplex/session/manager.py b/vllm_omni/engine/duplex/session/manager.py
index 0b7a7a07ea0..e09881abe3e 100644
--- a/vllm_omni/engine/duplex/session/manager.py
+++ b/vllm_omni/engine/duplex/session/manager.py
@@ -408,8 +408,11 @@ def sampling_params_for(self, session: DuplexEngineSession) -> tuple[object, ...
         return configured
 
     @staticmethod
-    def stage_request_id(fence: DuplexFence, *, stage_id: int) -> str:
-        return duplex_resource_request_id(fence, f"stage{stage_id}")
+    def stage_request_id(fence: DuplexFence, *, stage_id: int, resumable: bool = True) -> str:
+        role = f"stage{stage_id}"
+        if not resumable:
+            role += f"-turn{fence.turn_id}"
+        return duplex_resource_request_id(fence, role)
 
     def ensure_stage_request(
         self,
@@ -422,7 +425,9 @@ def ensure_stage_request(
         if stage_id >= self.stage_port.stage_count:
             return None
         effective_fence = fence or session.fence
-        request_id = self.stage_request_id(effective_fence, stage_id=stage_id)
+        request_id = self.stage_request_id(
+            effective_fence, stage_id=stage_id, resumable=session.capabilities.supports_core_resumable_request
+        )
         session.reserve_stage_request(stage_id, request_id, fence=effective_fence)
         context = DuplexStageRequestContext(
             request_id=request_id,
diff --git a/vllm_omni/engine/duplex/session/model_channel.py b/vllm_omni/engine/duplex/session/model_channel.py
index 13f0f77819f..f244a68597f 100644
--- a/vllm_omni/engine/duplex/session/model_channel.py
+++ b/vllm_omni/engine/duplex/session/model_channel.py
@@ -22,6 +22,7 @@
 from __future__ import annotations
 
 import asyncio
+import copy
 import time
 import uuid
 from collections.abc import Awaitable, Callable, Mapping
@@ -43,8 +44,8 @@
 from vllm_omni.engine.duplex.plugin import (
     DuplexRuntimeConfigError,
     coerce_int,
-    payload_turn_id,
 )
+from vllm_omni.engine.duplex.session import helpers
 from vllm_omni.engine.duplex.session.context import DuplexSessionContext, StageOutput
 from vllm_omni.engine.duplex.session.emitter import SessionEmitter
 from vllm_omni.engine.duplex.session.engine_session import DuplexEngineSession, DuplexFenceMismatchError
@@ -114,6 +115,13 @@ def response_created_payload(
     ) -> dict[str, object]:
         session = self._ctx.session
         response_config = session.response_config
+        if not session.capabilities.supports_core_resumable_request and self.should_commit_response_to_history(
+            session, response_id
+        ):
+            # Committed-turn models can receive the next utterance before the
+            # speaker drains. Reserve the response's chronological slot now;
+            # an ACK fills it later without moving it past newer user input.
+            session.reserve_history_item(f"item_{response_id}")
         payload: dict[str, object] = {
             "type": "response.created",
             "session_id": session.session_id,
@@ -202,22 +210,13 @@ async def _append_via_data_plane(
         session = self._ctx.session
         if self._ctx.stage_port.stage_count == 0:
             raise RuntimeError("duplex_data_plane_has_no_stage")
-        payload_turn = payload_turn_id(payload)
-        fence = DuplexFence(
-            session.session_id,
-            epoch=session.epoch,
-            turn_id=(
-                payload_turn
-                if payload_turn is not None
-                else (
-                    session.active_response_turn_id if session.active_response_turn_id is not None else session.turn_id
-                )
-            ),
-        )
+        fence = helpers.append_fence(session, payload)
         lease_operation_id = f"append:{operation_id or uuid.uuid4().hex}"
         operation_started = False
         stage_id = 0
-        request_id = self._ctx.manager.stage_request_id(fence, stage_id=stage_id)
+        request_id = self._ctx.manager.stage_request_id(
+            fence, stage_id=stage_id, resumable=session.capabilities.supports_core_resumable_request
+        )
         try:
             session.begin_lease_operation(fence, lease_operation_id)
             operation_started = True
@@ -226,10 +225,17 @@ async def _append_via_data_plane(
             request_context = self._ctx.manager.ensure_stage_request(session, stage_id=stage_id, fence=fence)
             if request_context is None:
                 raise RuntimeError("duplex_data_plane_has_no_stage")
-            append_plan = self._ctx.plugin.plan_append(
+            prompt_payload: dict[str, object] = (
+                {str(key): value for key, value in payload.items()} if isinstance(payload, Mapping) else {}
+            )
+            append_plan = await self._ctx.plugin.prepare_append_plan(
                 request_id=request_id,
                 fence=fence,
-                session_config=dict(request_context.session_config),
+                session_config=self._ctx.plugin.prepare_prompt_config(
+                    {**request_context.session_config, "conversation": list(session.history)},
+                    state=self._ctx.model_state,
+                    payload=prompt_payload,
+                ),
                 runtime_config=dict(request_context.runtime_config),
                 seq=reservation.update.seq,
                 turn_seq=reservation.update.turn_seq,
@@ -237,6 +243,10 @@ async def _append_via_data_plane(
                 final=final,
                 sampling_params=request_context.stage_sampling_params,
             )
+            # Preparation may yield while cancellation or session teardown runs.
+            # Never submit the worker's stale result to the model.
+            if session.epoch != fence.epoch or session.state != DuplexSessionState.OPEN:
+                raise DuplexFenceMismatchError(session.fence, fence)
             if not isinstance(append_plan, DuplexAppendPlan):
                 raise TypeError("duplex plugin plan_append() must return DuplexAppendPlan")
             submission = DuplexStageSubmission(
@@ -279,7 +289,7 @@ async def _append_via_data_plane(
                             "seq": update.seq,
                             "turn_id": update.turn_id,
                             "turn_seq": update.turn_seq,
-                            "resumable": True,
+                            "resumable": session.capabilities.supports_core_resumable_request,
                         },
                     }
                 ],
@@ -413,7 +423,7 @@ def _build_stage_output(self, item: StageOutput) -> OmniRequestOutput:
             engine_output.finished = True
             engine_output = attach_duplex_output_decision(engine_output, item.decision)
         elif isinstance(output, OmniRequestOutput):
-            engine_output = output
+            engine_output = copy.copy(output)
             if finished:
                 engine_output.finished = True
         else:
@@ -425,6 +435,9 @@ def _build_stage_output(self, item: StageOutput) -> OmniRequestOutput:
                 stage_id=item.stage_id,
                 final_output_type=final_output_type if isinstance(final_output_type, str) else "audio",
             )
+        engine_output.stage_id = item.stage_id
+        if self._ctx.plugin.projects_intermediate_outputs and item.stage_id < item.context.final_stage_id:
+            engine_output.finished = False
         snapshot = self.stage_metrics_snapshot(item.stage_id, item.metrics, output)
         if snapshot is not None:
             existing = engine_output.metrics if isinstance(engine_output.metrics, dict) else {}
@@ -461,6 +474,11 @@ async def on_stage_output_item(self, item: StageOutput) -> None:
             await self._close_from_runtime(close_reason)
             return
         finished = self._data_plane_outputs_finished(drain_result)
+        if finished and not session.capabilities.supports_core_resumable_request:
+            if self._ctx.run.stream_request_id == item.request_id:
+                self._ctx.run.stream_request_id = None
+            await self._ctx.stage_port.cleanup([item.request_id])
+            return
         if finished and emitted_response and not self._out.auto_responds():
             # A finished, emitted response releases the per-request projector
             # cursor on its way out and offers the model another
@@ -759,8 +777,9 @@ async def _send_one_model_output_event(
             response_id = session.begin_response(turn_id=model_turn_id)
             response_created = True
             self._out.emit(self.response_created_payload(response_id, epoch=session.epoch))
+        stage_metrics = model_result.get("stage_metrics")
         response_stage_metrics = session.accumulate_response_stage_metrics(
-            model_result.get("stage_metrics") if isinstance(model_result.get("stage_metrics"), Mapping) else None
+            stage_metrics if isinstance(stage_metrics, Mapping) else None
         )
         if response_created:
             speak_payload = {
@@ -805,6 +824,8 @@ async def _send_one_model_output_event(
             mark_duration_ms,
             text_chars=mark_text_chars if mark_duration_ms is not None else None,
             audio_text_marks=audio_text_marks,
+            text_requires_complete_audio=model_result.get("text_requires_complete_audio") is True,
+            audio_complete=model_result.get("audio_complete") is True,
         )
         payload = {
             "type": "response.output_audio.delta",
@@ -904,10 +925,10 @@ def _normalize_audio_text_marks(
         *,
         audio_offset_ms: int,
         text_offset_chars: int,
-    ) -> list[dict[str, int]] | None:
+    ) -> list[dict[str, object]] | None:
         if not audio_text_marks:
             return None
-        normalized: list[dict[str, int]] = []
+        normalized: list[dict[str, object]] = []
         for raw_mark in audio_text_marks:
             if not isinstance(raw_mark, dict):
                 continue
diff --git a/vllm_omni/engine/duplex/session/runner.py b/vllm_omni/engine/duplex/session/runner.py
index ef464a5fa19..24e99d28a13 100644
--- a/vllm_omni/engine/duplex/session/runner.py
+++ b/vllm_omni/engine/duplex/session/runner.py
@@ -71,7 +71,6 @@
     DuplexModelPlugin,
     DuplexModelSessionState,
     PcmAppendReservation,
-    payload_turn_id,
 )
 from vllm_omni.engine.duplex.realtime_events import (
     RealtimeProjectionState,
@@ -251,7 +250,8 @@ def on_stage_output(
         if stage_id < context.final_stage_id:
             decision = self.model.decide_output(stage_id, output, context)
         consume = decision is not None or stage_id >= context.final_stage_id
-        if not consume:
+        project_intermediate = self.plugin.projects_intermediate_outputs and stage_id == 0
+        if not consume and not project_intermediate:
             # Stage0 text without a direct decision feeds the TTS stage as before.
             # Its metrics still have to reach the client: before sessions moved
             # into the engine the orchestrator published them as a standalone
@@ -274,7 +274,7 @@ def on_stage_output(
                 decision=decision,
             )
         )
-        return True
+        return consume
 
     def on_stage_failure(self, stage_id: int, exc: BaseException) -> None:
         """A stage rejected this session's request: fail the active response now.
@@ -434,12 +434,11 @@ async def _stop_worker(self) -> None:
             worker.cancel()
             await asyncio.gather(worker, return_exceptions=True)
 
-    def spawn(self, coro: Awaitable[None], *, name: str) -> asyncio.Task[None]:
+    def spawn(self, coro: Awaitable[None], *, name: str) -> None:
         task = asyncio.ensure_future(coro)
         task.set_name(name)
         self._background_tasks.add(task)
         task.add_done_callback(self._background_tasks.discard)
-        return task
 
     async def offload(self, fn: Callable[..., _OffloadT], *args: object, **kwargs: object) -> _OffloadT:
         loop = self._loop or asyncio.get_running_loop()
@@ -539,14 +538,14 @@ async def _on_command(self, command: DuplexCommand) -> None:
         elif isinstance(command, ClearInput):
             self._on_clear_input()
         elif isinstance(command, CancelResponse):
-            resolved = resolve_cancel_response(projector, command)
-            self._emit_events(resolved.events)
-            for payload in resolved.payloads:
+            control = resolve_cancel_response(projector, command)
+            self._emit_events(control.events)
+            for payload in control.payloads:
                 await self._on_cancel(payload)
         elif isinstance(command, ClearOutputAudio):
-            resolved = resolve_clear_output_audio(projector, command)
-            self._emit_events(resolved.events)
-            for payload in resolved.payloads:
+            control = resolve_clear_output_audio(projector, command)
+            self._emit_events(control.events)
+            for payload in control.payloads:
                 await self._on_cancel(payload)
         elif isinstance(command, CancelInput | BargeIn):
             await self._on_cancel(command.payload())
@@ -564,7 +563,8 @@ async def _on_command(self, command: DuplexCommand) -> None:
                 return
             payload = command.payload()
             if command.event in _CANCEL_EVENTS:
-                normalized = dict(payload.get("payload") or {})
+                inner = payload.get("payload")
+                normalized: dict[str, object] = dict(inner) if isinstance(inner, Mapping) else {}
                 normalized.update(payload)
                 normalized["type"] = command.event
                 await self._on_cancel(normalized)
@@ -577,19 +577,19 @@ async def _on_command(self, command: DuplexCommand) -> None:
         elif isinstance(command, Heartbeat):
             self._on_heartbeat(command)
         elif isinstance(command, CreateItem):
-            resolved = resolve_create_item(projector, command)
-            self._emit_events(resolved.events)
-            for payload in resolved.payloads:
+            control = resolve_create_item(projector, command)
+            self._emit_events(control.events)
+            for payload in control.payloads:
                 await self._run_internal_payload(payload)
         elif isinstance(command, DeleteItem):
-            resolved = resolve_delete_item(projector, command)
-            self._emit_events(resolved.events)
-            for payload in resolved.payloads:
+            control = resolve_delete_item(projector, command)
+            self._emit_events(control.events)
+            for payload in control.payloads:
                 await self.control.on_turn_signal(payload)
         elif isinstance(command, TruncateItem):
-            resolved = resolve_truncate_item(projector, command)
-            self._emit_events(resolved.events)
-            for payload in resolved.payloads:
+            control = resolve_truncate_item(projector, command)
+            self._emit_events(control.events)
+            for payload in control.payloads:
                 await self._run_internal_payload(payload)
         elif isinstance(command, CloseSession):
             await self._on_close_command(command.reason)
@@ -776,7 +776,7 @@ async def _on_append_audio(self, event: dict[str, object]) -> None:
         sr_raw = event.get("sample_rate_hz") or event.get("sample_rate")
         sample_rate_hz = sr_raw if isinstance(sr_raw, int | float) else 16000
         try:
-            audio, fmt, sample_rate_hz = await self.offload(
+            converted: tuple[object, object, int | float | None] = await self.offload(
                 convert_input_audio_with_rate,
                 audio,
                 fmt,
@@ -785,13 +785,25 @@ async def _on_append_audio(self, event: dict[str, object]) -> None:
         except ValueError as exc:
             self._emit_error("bad_event", str(exc))
             return
+        audio, fmt, converted_rate = converted
+        if converted_rate is not None:
+            sample_rate_hz = converted_rate
         if isinstance(fmt, str) and fmt.lower() in {"pcm16", "pcm_s16le", "s16le"}:
             self._emit_error("bad_audio", "input_audio_buffer.append pcm16 audio could not be decoded")
             return
         event["audio"] = audio
         event["format"] = fmt
         event["sample_rate_hz"] = sample_rate_hz
+        client_force_listen = bool(event.get("force_listen", False))
         vad_result = await self.control.run_turn_detection(event)
+        if (
+            vad_result is not None
+            and not session.capabilities.supports_core_resumable_request
+            and not client_force_listen
+        ):
+            # VAD's force_listen hint controls native model decoding. Committed
+            # turn models already buffer speech; it must not suppress barge-in.
+            event.pop("force_listen", None)
         projector = self._require_projector()
         self._emit_events(note_input_append(projector, event, vad_result=vad_result))
         if self.run.closing or session.state != DuplexSessionState.OPEN:
@@ -896,8 +908,11 @@ async def _on_append_audio(self, event: dict[str, object]) -> None:
             return
         if pcm_reservation.byte_count == 0:
             session.release_input_bytes(raw_audio_bytes)
-        payload = pcm_reservation.payload
-        await self._start_append(payload, final=False, pcm_reservation=pcm_reservation)
+        append_payload = pcm_reservation.payload
+        if append_payload is None:
+            self._maybe_schedule_vad_commit(vad_result)
+            return
+        await self._start_append(append_payload, final=False, pcm_reservation=pcm_reservation)
         self._maybe_schedule_vad_commit(vad_result)
 
     def _maybe_schedule_vad_commit(self, vad_result: TurnDetectionResult | None) -> None:
@@ -968,10 +983,13 @@ def _reanchor_chain(submit_time: float) -> None:
 
                 on_append_accepted = _reanchor_chain
         append_epoch = session.epoch
-        append_turn_id = payload_turn_id(payload)
-        if append_turn_id is None:
-            append_turn_id = session.turn_id
-        request_id = helpers.stage0_request_id(self.session, append_epoch)
+        append_fence = helpers.append_fence(session, payload, epoch=append_epoch)
+        append_turn_id = append_fence.turn_id
+        request_id = self.ctx.manager.stage_request_id(
+            append_fence,
+            stage_id=0,
+            resumable=session.capabilities.supports_core_resumable_request,
+        )
         if final or precreate_response:
             session.bind_request(request_id)
         if precreate_response:
@@ -979,6 +997,14 @@ def _reanchor_chain(submit_time: float) -> None:
         if precreate_response and session.active_response_id is None:
             response_id = session.begin_response(turn_id=append_turn_id)
             self.emit(self.model.response_created_payload(response_id, epoch=append_epoch))
+        if final and not session.capabilities.supports_core_resumable_request:
+            logger.info(
+                "Duplex committed turn session=%s request=%s response=%s audio_bytes=%s",
+                session.session_id,
+                request_id,
+                session.active_response_id,
+                helpers.audio_payload_size_bytes(payload),
+            )
         attempt = AppendAttempt(
             ctx=self.ctx,
             out=self.out,
@@ -1034,8 +1060,7 @@ async def _wait_for_append_tail(self) -> bool:
         try:
             return await predecessor
         except asyncio.CancelledError:
-            current = asyncio.current_task()
-            if current is not None and current.cancelling():
+            if helpers.task_is_cancelling(asyncio.current_task()):
                 raise
             return False
         except Exception:
@@ -1063,8 +1088,7 @@ async def _schedule_silence_continuation(
                 if not await pending_silence:
                     return False
             except asyncio.CancelledError:
-                current = asyncio.current_task()
-                if current is not None and current.cancelling():
+                if helpers.task_is_cancelling(asyncio.current_task()):
                     raise
                 return False
             except Exception:
@@ -1523,6 +1547,10 @@ async def _start_response_from_committed_audio(self) -> None:
                 retained_committed_payload=committed_payload,
             )
             return
+        if session.unanswered_user_items() and session.capabilities.supports_text_only_turn:
+            session.reset_unanswered_user_items()
+            await self._start_append({"type": "conversation"}, final=True, precreate_response=True)
+            return
         if session.unanswered_user_items():
             # Conversation items are context, not a turn. A model-native model
             # decides to speak from the audio it hears, and there is no audio
@@ -1601,13 +1629,16 @@ def _defer_commit_behind_active_response(
         if deferred_payload is None:
             commit_reservation.commit()
             return False
+        retained_payload: dict[str, object]
         if model_state.committed_audio_payload is not None:
-            deferred_payload = overlap_policy.merge_audio_payloads(
+            retained_payload = overlap_policy.merge_audio_payloads(
                 model_state.committed_audio_payload,
                 deferred_payload,
             )
+        else:
+            retained_payload = deferred_payload
         model_state.retain_committed_audio(
-            deferred_payload,
+            retained_payload,
             operation_id=commit_reservation.operation_id,
             reserved_bytes=commit_reservation.byte_count,
         )
diff --git a/vllm_omni/engine/duplex/vad.py b/vllm_omni/engine/duplex/vad.py
index ad3c2682015..9c19c43559e 100644
--- a/vllm_omni/engine/duplex/vad.py
+++ b/vllm_omni/engine/duplex/vad.py
@@ -428,11 +428,17 @@ def process(self, samples: np.ndarray) -> StreamingVADResult:
 
             if self._speech_active:
                 contained_speech = True
+                if probability >= self.config.threshold:
+                    # Confirmed speech cancels a pending endpoint. Otherwise a
+                    # brief pause can age through resumed speech and split the
+                    # utterance at the next low-probability frame.
+                    self._silence_samples = 0
+                    continue
                 below_negative_threshold = probability < negative_threshold
                 if not below_negative_threshold and self._silence_samples == 0:
                     continue
-                # A silence candidate is running: louder frames keep its clock
-                # moving but cannot themselves close the turn.
+                # Scores inside the hysteresis band keep the pending timer,
+                # but cannot themselves close the turn.
                 self._silence_samples += self._WINDOW_SAMPLES
                 if not below_negative_threshold or self._silence_samples < min_silence_samples:
                     continue
diff --git a/vllm_omni/engine/duplex_orchestrator.py b/vllm_omni/engine/duplex_orchestrator.py
index 09a767fb135..9814927d18f 100644
--- a/vllm_omni/engine/duplex_orchestrator.py
+++ b/vllm_omni/engine/duplex_orchestrator.py
@@ -12,6 +12,8 @@
 
 from __future__ import annotations
 
+import asyncio
+import threading
 import time as _time
 from collections.abc import Coroutine
 from dataclasses import dataclass, field
@@ -20,6 +22,7 @@
 from vllm.logger import init_logger
 
 from vllm_omni.config.stage_config import DuplexSessionRuntimeConfig
+from vllm_omni.engine import OmniEngineCoreRequest
 from vllm_omni.engine.duplex.contracts import (
     DuplexFence,
     DuplexOutputContext,
@@ -77,6 +80,7 @@ def __init__(
         **kwargs: Any,
     ) -> None:
         super().__init__(*args, **kwargs)
+        self._prompt_processing_lock = threading.Lock()
         self.plugin = plugin
         self.duplex_session_config = duplex_session_config
         self.session_manager = DuplexSessionManager(
@@ -288,7 +292,9 @@ def ensure_request(self, context: DuplexStageRequestContext) -> None:
                 fence=context.fence,
                 config_generation=context.config_generation,
             )
-            request_state.streaming.enabled = True
+            request_state.streaming.enabled = self.plugin.capabilities(
+                max_sessions=self.duplex_session_config.max_sessions
+            ).supports_core_resumable_request
             self.request_states[context.request_id] = request_state
         elif isinstance(request_state, DuplexOrchestratorRequestState):
             if request_state.config_generation != context.config_generation:
@@ -301,18 +307,49 @@ def ensure_request(self, context: DuplexStageRequestContext) -> None:
         self._sync_bridge_state(request_state, context)
         self.session_manager.register_request(context.request_id, context.session_id)
 
+    def _upgrade_processed_stage_request(self, request, raw_prompt):
+        request = super()._upgrade_processed_stage_request(request, raw_prompt)
+        if not self.plugin.capabilities(
+            max_sessions=self.duplex_session_config.max_sessions
+        ).supports_core_resumable_request and not isinstance(request, OmniEngineCoreRequest):
+            request = OmniEngineCoreRequest.from_request(request)
+        return request
+
+    def _process_turn_prompt(self, *args, **kwargs):
+        # Input processors own mutable caches. Hold a thread lock even if the
+        # awaiting session is cancelled while its preprocessing is still running.
+        with self._prompt_processing_lock:
+            return self._build_next_stage_request(*args, **kwargs)
+
     async def submit(self, submission: DuplexStageSubmission) -> DuplexStageSubmissionResult:
         context = submission.context
         request_state = self.request_states.get(context.request_id)
         if not isinstance(request_state, DuplexOrchestratorRequestState):
             raise RuntimeError(f"duplex request was not preregistered: {context.request_id}")
-        request = build_engine_core_request_from_tokens(
-            request_id=context.request_id,
-            prompt=dict(submission.prompt),
-            params=context.stage_sampling_params,
-            model_config=self.stage_pools[context.stage_id].stage_vllm_config.model_config,
-            resumable=True,
-        )
+        if self.plugin.capabilities(
+            max_sessions=self.duplex_session_config.max_sessions
+        ).supports_core_resumable_request:
+            request = build_engine_core_request_from_tokens(
+                request_id=context.request_id,
+                prompt=dict(submission.prompt),
+                params=context.stage_sampling_params,
+                model_config=self.stage_pools[context.stage_id].stage_vllm_config.model_config,
+                resumable=True,
+            )
+        else:
+            # Use the ordinary multimodal input processor for turn-model plugins.
+            # Its CPU preprocessing runs off the session/orchestrator event loop.
+            request = await asyncio.to_thread(
+                self._process_turn_prompt,
+                context.request_id,
+                context.stage_id,
+                dict(submission.prompt),
+                context.stage_sampling_params,
+                resumable=False,
+            )
+            if self.request_states.get(context.request_id) is not request_state:
+                raise RuntimeError("duplex request cancelled during input preprocessing")
+            request_state.prompt = dict(submission.prompt)
         request.external_req_id = request.request_id
         pool = self.stage_pools[context.stage_id]
         if submission.already_submitted:
diff --git a/vllm_omni/entrypoints/duplex/warmup.py b/vllm_omni/entrypoints/duplex/warmup.py
index 2c138096d8f..f711cfccbfc 100644
--- a/vllm_omni/entrypoints/duplex/warmup.py
+++ b/vllm_omni/entrypoints/duplex/warmup.py
@@ -46,6 +46,7 @@ async def _warmup_duplex_realtime(app, args, warmup_frames: int) -> None:
         # One silence unit as the engine-side plugin defines it (DuplexOmniEngine.plugin).
         plugin = getattr(getattr(app.state.engine_client, "engine", None), "plugin", None)
         frame_samples = int(getattr(plugin, "silence_continuation_samples", 16000))
+        native_append = plugin.capabilities(max_sessions=1).supports_core_resumable_request if plugin else True
         silence = base64.b64encode(bytes(frame_samples * 4)).decode("ascii")
         from vllm_omni.clients.duplex import build_realtime_url
 
@@ -81,7 +82,7 @@ async def _warmup_duplex_realtime(app, args, warmup_frames: int) -> None:
                             "output_audio_format": "pcm16",
                             "idle_timeout_s": 60,
                             "turn_detection": None,
-                            "extra_body": {"auto_response": True},
+                            "extra_body": {"auto_response": native_append},
                         },
                     }
                 )
@@ -108,6 +109,8 @@ async def _recv_until(predicate, timeout_s: float) -> bool:
                 await ws.send(json.dumps({"type": "input_audio_buffer.append", "audio": silence}))
                 sent += 1
                 await asyncio.sleep(0.08)
+            if not native_append:
+                await ws.send(json.dumps({"type": "input_audio_buffer.commit", "final": True}))
             # Wait for the pipeline's first audio output so every stage ran.
             saw_audio = await _recv_until(lambda e: e.get("type") == "response.output_audio.delta", 30)
             # Close the session EXPLICITLY: a bare websocket close parks the
diff --git a/vllm_omni/entrypoints/openai/api_server.py b/vllm_omni/entrypoints/openai/api_server.py
index 94f1ab51302..7100bf67f8f 100644
--- a/vllm_omni/entrypoints/openai/api_server.py
+++ b/vllm_omni/entrypoints/openai/api_server.py
@@ -521,7 +521,9 @@ def _should_serve_duplex(model: str, kwargs: dict[str, Any]) -> bool:
             deploy_path = _DEPLOY_DIR / deploy_path
 
     # Resolve base_config too, so the API and stage workers use the same mode.
-    session_mode = resolve_deploy_yaml(deploy_path).get("session_mode")
+    session_mode = resolve_deploy_yaml(deploy_path).get(
+        "session_mode", getattr(pipeline_config, "default_session_mode", None)
+    )
     if session_mode not in ("turn", "duplex"):
         raise ValueError("A duplex-capable model requires session_mode: turn or duplex in its deploy config")
     return session_mode == "duplex"
@@ -1742,6 +1744,12 @@ async def realtime_websocket(websocket: WebSocket):
         await duplex_handler.handle_realtime_session(websocket)
         return
 
+    if isinstance(duplex_query, str) and duplex_query.lower() in {"1", "true", "on"}:
+        await websocket.accept()
+        await websocket.send_json({"type": "error", "code": "unsupported", "error": "VAD realtime is not enabled"})
+        await websocket.close(code=1008)
+        return
+
     serving = getattr(websocket.app.state, "openai_serving_realtime", None)
     if serving is None:
         await websocket.accept()
@@ -2042,6 +2050,8 @@ async def generate_images(
         )
 
     try:
+        width: int | None = None
+        height: int | None = None
         # Unify request construction for any multi-stage pipeline to avoid
         # divergence between /v1/images and /v1/chat/completions.
         if len(stage_configs) > 1:
@@ -2059,7 +2069,6 @@ async def generate_images(
                 "num_outputs_per_prompt": request.n,
             }
             if request.size is not None:
-                parse_size(request.size)
                 width, height = parse_size(request.size)
                 app_state_args = getattr(raw_request.app.state, "args", None)
                 _check_max_generated_image_size(app_state_args, width, height)
@@ -2113,7 +2122,7 @@ async def generate_images(
             )
 
         # Build params - pass through user values directly
-        prompt: OmniTextPrompt = {"prompt": request.prompt, "modalities": ["image"]}
+        prompt = OmniTextPrompt(prompt=request.prompt, modalities=["image"])
         if request.negative_prompt is not None:
             prompt["negative_prompt"] = request.negative_prompt
         gen_params = OmniDiffusionSamplingParams(num_outputs_per_prompt=request.n)
@@ -2129,12 +2138,11 @@ async def generate_images(
         if extra_args:
             gen_params.extra_args = extra_args
         # Parse per-request LoRA (compatible with chat's extra_body.lora shape).
-        lora_request, lora_scale = _parse_lora_request(request.lora)
+        lora_request, lora_scale = _parse_lora_request(request.lora) if request.lora is not None else (None, None)
         _update_if_not_none(gen_params, "lora_request", lora_request)
         _update_if_not_none(gen_params, "lora_scale", lora_scale)
 
         # Parse and add size if provided
-        width, height = None, None
         if request.size:
             width, height = parse_size(request.size)
             size_str = f"{width}x{height}"
@@ -2300,9 +2308,9 @@ async def edit_images(
     try:
         # 2. Build prompt & images params
         cot_output = None
-        prompt: OmniTextPrompt = {"prompt": prompt, "modalities": ["image"]}
+        omni_prompt = OmniTextPrompt(prompt=prompt, modalities=["image"])
         if negative_prompt is not None:
-            prompt["negative_prompt"] = negative_prompt
+            omni_prompt["negative_prompt"] = negative_prompt
         input_images_list = []
         images = image or image_array
         urls = url or url_array
@@ -2333,17 +2341,17 @@ async def edit_images(
         # Hunyuan-aware behavior. RGBA/P uploads otherwise diverge from offline.
         normalize_edit_images_rgb = bot_task is not None or sys_type is not None
         pil_images = await _load_input_images(input_images_list, normalize_rgb=normalize_edit_images_rgb)
-        prompt["multi_modal_data"] = {}
-        prompt["multi_modal_data"]["image"] = pil_images
+        omni_prompt["multi_modal_data"] = {}
+        omni_prompt["multi_modal_data"]["image"] = pil_images
 
         if mask_image is not None:
             # Mask role is different (alpha channel matters); never normalize.
             loaded = await _load_input_images([mask_image], normalize_rgb=False)
-            prompt["multi_modal_data"]["mask_image"] = loaded[0]
+            omni_prompt["multi_modal_data"]["mask_image"] = loaded[0]
 
         if reference_image is not None:
             loaded = await _load_input_images([reference_image], normalize_rgb=normalize_edit_images_rgb)
-            prompt["multi_modal_data"]["reference_image"] = loaded[0]
+            omni_prompt["multi_modal_data"]["reference_image"] = loaded[0]
 
         # 3 Build sample params
         gen_params = OmniDiffusionSamplingParams()
@@ -2409,13 +2417,13 @@ async def edit_images(
         # Keep AR stage target grid in sync with requested output size.
         # GLM-Image consumes target_h/target_w via mm_processor_kwargs.
         if width is not None and height is not None:
-            prompt["mm_processor_kwargs"] = {
+            omni_prompt["mm_processor_kwargs"] = {
                 "target_h": height,
                 "target_w": width,
             }
             # Backward-compatible fallback for processors reading top-level fields.
-            prompt["height"] = height
-            prompt["width"] = width
+            omni_prompt["height"] = height
+            omni_prompt["width"] = width
 
         _update_if_not_none(gen_params, "width", width)
         _update_if_not_none(gen_params, "height", height)
@@ -2513,7 +2521,7 @@ async def edit_images(
             if return_stage_metrics is not None:
                 extra_body["return_stage_metrics"] = return_stage_metrics
 
-            prompt_text = prompt.get("prompt", "")
+            prompt_text = omni_prompt.get("prompt", "")
             generation_result = await chat_handler.generate_diffusion_images(
                 prompt=prompt_text,
                 extra_body=extra_body,
@@ -2544,7 +2552,7 @@ async def edit_images(
                 engine_client=engine_client,
                 gen_params=gen_params,
                 stage_configs=stage_configs,
-                prompt=prompt,
+                prompt=omni_prompt,
                 request_id=request_id,
             )
             images = _extract_images_from_result(result)
@@ -2552,6 +2560,8 @@ async def edit_images(
             peak_memory_mb = getattr(result, "peak_memory_mb", None)
             response_metrics = getattr(result, "metrics", None) if return_stage_metrics else None
 
+        if images is None:
+            images = []
         logger.debug(f"Successfully generated {len(images)} image(s)")
 
         # Encode images to base64
@@ -2973,7 +2983,10 @@ async def omni_sleep(request: OmniSleepRequest, raw_request: Request):
     acks = await engine_client.sleep(stage_ids=request.stage_ids, level=request.level)
     for sid in request.stage_ids:
         sleeping_set.add(sid)
-    return {"status": "SUCCESS", "acks": [dataclasses.asdict(a) if dataclasses.is_dataclass(a) else a for a in acks]}
+    return {
+        "status": "SUCCESS",
+        "acks": [dataclasses.asdict(a) if dataclasses.is_dataclass(a) and not isinstance(a, type) else a for a in acks],
+    }
 
 
 @router.post("/v1/omni/wakeup")
@@ -2989,7 +3002,10 @@ async def omni_wakeup(request: OmniWakeupRequest, raw_request: Request):
     for sid in request.stage_ids:
         if sid in sleeping_set:
             sleeping_set.remove(sid)
-    return {"status": "SUCCESS", "acks": [dataclasses.asdict(a) if dataclasses.is_dataclass(a) else a for a in acks]}
+    return {
+        "status": "SUCCESS",
+        "acks": [dataclasses.asdict(a) if dataclasses.is_dataclass(a) and not isinstance(a, type) else a for a in acks],
+    }
 
 
 if __name__ == "__main__":
diff --git a/vllm_omni/model_executor/models/qwen3_omni/duplex/__init__.py b/vllm_omni/model_executor/models/qwen3_omni/duplex/__init__.py
new file mode 100644
index 00000000000..4244ce4b4e1
--- /dev/null
+++ b/vllm_omni/model_executor/models/qwen3_omni/duplex/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
diff --git a/vllm_omni/model_executor/models/qwen3_omni/duplex/input.py b/vllm_omni/model_executor/models/qwen3_omni/duplex/input.py
new file mode 100644
index 00000000000..caba0b174d3
--- /dev/null
+++ b/vllm_omni/model_executor/models/qwen3_omni/duplex/input.py
@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Transactional PCM buffering for committed Qwen speech turns."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import pybase64 as base64
+
+from vllm_omni.engine.duplex.plugin import PcmAppendBuffer, PcmAppendReservation
+
+
+@dataclass
+class Reservation(PcmAppendReservation):
+    owner: QwenPcmBuffer
+    operation_id: str
+    payload: dict[str, object] | None
+    raw: bytes
+    _active: bool = True
+
+    @property
+    def active(self):
+        return self._active
+
+    @property
+    def byte_count(self):
+        return len(self.raw)
+
+    def commit(self):
+        if self._active:
+            self._active = False
+            self.owner.reservations.remove(self)
+
+    def rollback(self):
+        if self._active:
+            self.owner.buffer[:0] = self.raw
+            self.commit()
+
+
+@dataclass
+class QwenPcmBuffer(PcmAppendBuffer):
+    buffer: bytearray = field(default_factory=bytearray)
+    reservations: list[Reservation] = field(default_factory=list)
+
+    @property
+    def pending_byte_count(self):
+        return len(self.buffer)
+
+    def clear(self):
+        for reservation in self.reservations:
+            reservation._active = False
+        self.reservations.clear()
+        self.buffer.clear()
+
+    def clear_force_listen(self):
+        pass
+
+    def has_pending(self):
+        return bool(self.buffer)
+
+    def has_reserved(self):
+        return bool(self.reservations)
+
+    def prepare_append(self, payload, *, operation_id, chunk_period_ms, allow_emit):
+        if payload.get("format") != "pcm_f32le" or payload.get("sample_rate_hz") != 16000:
+            raise ValueError("Qwen duplex requires normalized 16 kHz pcm_f32le")
+        if payload.get("video_frames"):
+            # Qwen answers whole turns, so it has no audio unit for a frame
+            # track to interleave against. Images arrive the OpenAI way, as
+            # input_image conversation items, and stay until deleted.
+            raise ValueError(
+                "Qwen duplex does not take video_frames on an audio append; "
+                "send images as conversation.item.create items with input_image content"
+            )
+        raw = base64.b64decode(payload.get("audio", ""), validate=True)
+        if len(raw) % 4:
+            raise ValueError("Invalid float32 PCM length")
+        self.buffer.extend(raw)
+        # Qwen inference starts on commit, never on an individual audio chunk.
+        return None
+
+    def prepare_commit(self, *, operation_id, chunk_period_ms):
+        raw = bytes(self.buffer)
+        payload = (
+            {
+                "audio": base64.b64encode(raw).decode(),
+                "format": "pcm_f32le",
+                "sample_rate_hz": 16000,
+                "is_speech": True,
+            }
+            if raw
+            else None
+        )
+        self.buffer.clear()
+        reservation = Reservation(self, operation_id, payload, raw)
+        self.reservations.append(reservation)
+        return reservation
+
+    def flush(self, *, chunk_period_ms):
+        reservation = self.prepare_commit(operation_id="flush", chunk_period_ms=chunk_period_ms)
+        reservation.commit()
+        return reservation.payload
diff --git a/vllm_omni/model_executor/models/qwen3_omni/duplex/plugin.py b/vllm_omni/model_executor/models/qwen3_omni/duplex/plugin.py
new file mode 100644
index 00000000000..90cb41f8cbd
--- /dev/null
+++ b/vllm_omni/model_executor/models/qwen3_omni/duplex/plugin.py
@@ -0,0 +1,390 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Engine-owned VAD/commit turns with concurrent input and interruptible output.
+
+Qwen3-Omni is a turn model: this plugin does not advertise native streaming KV
+or model-driven turn decisions. Each committed utterance is a fresh request.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import copy
+import hashlib
+import io
+import json
+import os
+from collections.abc import Mapping
+from pathlib import Path
+
+import numpy as np
+import pybase64 as base64
+from PIL import Image
+from vllm.logger import init_logger
+from vllm.sampling_params import RequestOutputKind
+
+from vllm_omni.engine.duplex.config import DuplexCapabilities
+from vllm_omni.engine.duplex.contracts import DuplexAppendPlan, duplex_resource_request_belongs_to_session
+from vllm_omni.engine.duplex.plugin import DuplexDataPlane, DuplexModelPlugin, DuplexRuntimeConfigError
+from vllm_omni.model_executor.models.qwen3_omni.duplex.session import QwenDuplexSessionState
+
+logger = init_logger(__name__)
+
+#: Mirrors ``limit_mm_per_prompt.image`` in ``deploy/qwen3_omni_duplex.yaml``.
+#: The session already refuses a ninth stored image, but that budget lives in
+#: the engine and this one in the deploy config; the prompt is the only place
+#: that can keep them from drifting apart into a rejected submission.
+MAX_PROMPT_IMAGES = 8
+
+
+class QwenDataPlane(DuplexDataPlane):
+    def __init__(self, encode_audio):
+        self.encode_audio = encode_audio
+        self.terminal: set[str] = set()
+
+    def begin_request(self, request_id):
+        self.terminal.discard(request_id)
+
+    def is_terminal(self, request_id):
+        return request_id in self.terminal
+
+    def mark_terminal(self, request_id):
+        self.terminal.add(request_id)
+
+    def close_stream(self, request_id):
+        pass
+
+    def close_session(self, session_id, *, active_request_id=None):
+        self.terminal = {
+            rid for rid in self.terminal if not duplex_resource_request_belongs_to_session(rid, session_id)
+        }
+
+    def project(self, result, *, context=None):
+        if not isinstance(result, dict):
+            return
+        context = context or {}
+        for output in result.get("data_plane_outputs", []):
+            rid = output.request_id
+            if self.is_terminal(rid):
+                continue
+            completion = next(iter(getattr(output, "outputs", ()) or ()), None)
+            stage_id = getattr(output, "stage_id", 0)
+            text = getattr(completion, "text", "") if stage_id == 0 else ""
+            mm = getattr(output, "multimodal_output", None)
+            if not isinstance(mm, Mapping) or "audio" not in mm:
+                mm = getattr(completion, "multimodal_output", {}) or {}
+            audio = mm.get("audio")
+            encoded = None
+            duration_ms = 0
+            rate = mm.get("sr", mm.get("sample_rate", mm.get("sample_rate_hz", 24000)))
+            if isinstance(rate, (list, tuple)):
+                rate = next((value for value in rate if value is not None), 24000)
+            rate = int(rate)
+            if rate <= 0:
+                raise ValueError("Invalid output audio sample rate")
+            if audio is not None and "audio" in context.get("modalities", ()):
+                chunks = audio if isinstance(audio, (list, tuple)) else [audio]
+                arrays = [
+                    np.asarray(
+                        chunk.detach().float().cpu().numpy() if hasattr(chunk, "detach") else chunk, dtype=np.float32
+                    ).reshape(-1)
+                    for chunk in chunks
+                ]
+                audio = np.concatenate(arrays) if arrays else np.empty(0, dtype=np.float32)
+                duration_ms = audio.size * 1000 / rate
+                if audio.size:
+                    encoded = self.encode_audio(
+                        audio, rate, context.get("response_format", "pcm16"), context.get("speed")
+                    )
+            yield {
+                "supported": True,
+                "data_plane_request_id": rid,
+                "text": text or "",
+                "audio_data": encoded or "",
+                "audio_format": context.get("response_format", "pcm16"),
+                "audio_duration_ms": duration_ms,
+                # Thinker text and codec chunks are independent streams. Only
+                # the final audio boundary can conservatively attest all text.
+                "audio_text_mark": False,
+                "text_requires_complete_audio": "audio" in context.get("modalities", ()),
+                "audio_complete": bool(output.finished) and stage_id == 2,
+                "sample_rate_hz": rate,
+                "end_of_turn": bool(output.finished),
+                "model_turn_id": context.get("active_response_turn_id")
+                if context.get("active_response_turn_id") is not None
+                else context.get("turn_id", 0),
+                "runtime_impl": "qwen3_commit",
+                "uses_model_runner_scheduler": True,
+                "runner_kv_backed": True,
+            }
+
+
+class Qwen3OmniDuplexPlugin(DuplexModelPlugin):
+    plugin_id = "qwen3-omni"
+    projects_intermediate_outputs = True
+
+    def __init__(self, encode_audio):
+        self.data_plane = QwenDataPlane(encode_audio)
+        self.processor = None
+        self._processor_lock = asyncio.Lock()
+
+    def capabilities(self, *, max_sessions):
+        return DuplexCapabilities(
+            supports_model_native_turn_policy=False,
+            supports_input_append=True,
+            supports_barge_in=True,
+            supports_replace_latest_chunk=False,
+            supports_reencode_context=True,
+            supports_turn_commit_only=True,
+            supports_core_resumable_request=False,
+            supports_independent_io_streams=True,
+            supports_realtime_endpoint=True,
+            supports_multi_session=max_sessions > 1,
+            supports_multi_session_same_replica=max_sessions > 1,
+            supports_session_lease=True,
+            supports_session_resume=True,
+            session_admission_mode="engine_managed",
+            supports_audio_truncate=True,
+            supports_chat_completions=True,
+            supports_image_input=True,
+            supports_text_only_turn=True,
+            adapter_patterns=["turn_commit"],
+            signal_sources=["client_event", "server_policy"],
+            stage_handoff_transport="scheduler_data_plane",
+            target_barge_in_latency_ms=None,
+        )
+
+    def create_session_state(self):
+        return QwenDuplexSessionState()
+
+    def validate_client_extra_body(self, extra_body):
+        if not isinstance(extra_body, Mapping):
+            return
+        if extra_body.get("auto_response") or extra_body.get("full_duplex"):
+            raise DuplexRuntimeConfigError(
+                "Qwen requires server VAD or explicit commits; native auto_response is unsupported"
+            )
+        if extra_body.get("realtime_tools"):
+            raise DuplexRuntimeConfigError("Qwen duplex tool calls are not implemented")
+
+    async def prepare_runtime_config(self, config, *, model_config):
+        self.validate_client_extra_body(config.extra_body)
+        if config.ref_audio:
+            raise DuplexRuntimeConfigError("Qwen duplex does not support reference voice audio")
+        if model_config is None and self.processor is None:
+            raise DuplexRuntimeConfigError("Qwen duplex requires the stage-0 model configuration")
+        async with self._processor_lock:
+            if self.processor is None:
+                from transformers import AutoProcessor
+
+                self.processor = await asyncio.to_thread(
+                    AutoProcessor.from_pretrained,
+                    model_config.model,
+                    trust_remote_code=model_config.trust_remote_code,
+                    revision=getattr(model_config, "revision", None),
+                )
+        return self.runtime_config_for_update(config, {})
+
+    def runtime_config_for_update(self, config, current):
+        self.validate_client_extra_body(config.extra_body)
+        if config.ref_audio:
+            raise DuplexRuntimeConfigError("Qwen duplex does not support reference voice audio")
+        return {
+            "instructions": config.instructions,
+            "initial_user_text": config.initial_user_text,
+            "temperature": config.temperature,
+            "max_tokens": config.max_tokens,
+        }
+
+    def configure_sampling_params(self, *, runtime_config, defaults):
+        params = copy.deepcopy(defaults)
+        for value in params:
+            if value is not None:
+                value.output_kind = RequestOutputKind.DELTA
+        if params and params[0] is not None:
+            if runtime_config.get("temperature") is not None:
+                params[0].temperature = float(runtime_config["temperature"])
+            if isinstance(runtime_config.get("max_tokens"), int):
+                params[0].max_tokens = runtime_config["max_tokens"]
+        return params
+
+    def prepare_prompt_config(self, config, *, state, payload):
+        history = config.get("conversation", [])
+        # The history accessor copies message dicts but preserves content identity.
+        # Keep payloads privately, never put PCM into public conversation events.
+        has_audio = bool(payload.get("audio"))
+        last_content = history[-1].get("content") if history else None
+        current_is_in_history = (
+            has_audio
+            and isinstance(last_content, list)
+            and any(part.get("type") == "audio_url" for part in last_content)
+        )
+        if current_is_in_history:
+            content = history[-1].get("content")
+            state.audio_history = [(key, value) for key, value in state.audio_history if key is not content]
+            state.audio_history.append((content, payload))
+        # Reserve one of the four audio slots for the actual submitted input,
+        # including when deferred input has no trailing user history entry.
+        history_limit = 4 if current_is_in_history or not has_audio else 3
+        retained = state.audio_history[-history_limit:]
+        while len(retained) > 1 and sum(len(value.get("audio", "")) for _, value in retained) > 8 * 1024 * 1024:
+            retained.pop(0)
+        state.audio_history = retained
+        messages = []
+
+        def has_image(message):
+            content = message.get("content")
+            return isinstance(content, list) and any(p.get("type") == "image_url" for p in content)
+
+        selected = [m for m in history[:-16] if has_image(m)] + history[-16:]
+        for message in selected:
+            content = message.get("content")
+            audio = next((value for key, value in retained if key is content), None)
+            if audio is not None:
+                messages.append({"role": "user", "audio_payload": audio})
+            elif isinstance(content, list) and any(part.get("type") == "image_url" for part in content):
+                messages.append(message)
+            elif isinstance(content, str) and content:
+                messages.append(message)
+            elif message.get("role") == "user":
+                # Do not keep an assistant answer after dropping its user audio.
+                messages = [m for m in messages if has_image(m)]
+        while messages and messages[0].get("role") == "assistant":
+            messages.pop(0)
+        if has_audio and not current_is_in_history:
+            # History is context, not a replacement for the current request.
+            # Re-encoding only history here makes Qwen answer an old question.
+            messages.append({"role": "user", "audio_payload": payload})
+        return {**config, "qwen_messages": messages}
+
+    @staticmethod
+    def _trim_prompt_images(messages, images):
+        """Drop the oldest images, with their placeholders, down to the prompt limit.
+
+        The processor pairs ``{"type": "image"}`` parts with ``mm["image"]``
+        positionally, and the placeholders read across *messages* in the same
+        order as *images*, so a dropped image has to take its placeholder with
+        it. Oldest first keeps what the client shared most recently.
+        """
+        excess = len(images) - MAX_PROMPT_IMAGES
+        if excess <= 0:
+            return messages, images
+        logger.warning(
+            "Qwen duplex prompt carries %d images; dropping the %d oldest to stay within %d",
+            len(images),
+            excess,
+            MAX_PROMPT_IMAGES,
+        )
+        remaining = excess
+        for message in messages:
+            if remaining <= 0:
+                break
+            content = message.get("content")
+            if not isinstance(content, list):
+                continue
+            kept = []
+            for part in content:
+                if remaining > 0 and isinstance(part, dict) and part.get("type") == "image":
+                    remaining -= 1
+                    continue
+                kept.append(part)
+            message["content"] = kept
+        return [message for message in messages if message.get("content") != []], images[excess:]
+
+    @staticmethod
+    def _audio_content(payload):
+        raw = base64.b64decode(payload["audio"], validate=True)
+        audio = np.frombuffer(raw, dtype="<f4").copy()
+        if not audio.size or not np.isfinite(audio).all():
+            raise DuplexRuntimeConfigError("Audio must contain finite PCM samples")
+        return [{"type": "audio"}], audio
+
+    async def prepare_append_plan(self, **kwargs):
+        # History mutation has already happened on the session loop. The worker
+        # owns this snapshot and never reads or mutates live session state.
+        snapshot = copy.deepcopy(kwargs)
+        return await asyncio.to_thread(self.plan_append, **snapshot)
+
+    def plan_append(
+        self, *, request_id, fence, session_config, runtime_config, seq, turn_seq, payload, final, sampling_params
+    ):
+        if not final or not isinstance(payload, dict):
+            raise DuplexRuntimeConfigError("Qwen generation requires a committed audio turn")
+        messages = []
+        if runtime_config.get("instructions"):
+            messages.append({"role": "system", "content": runtime_config["instructions"]})
+        history = session_config.get("qwen_messages")
+        if history is None and payload.get("audio"):
+            # Nothing prepared the conversation, so the committed payload is
+            # the whole turn. An empty prepared list is not that: it means the
+            # preparation ran and found nothing to say.
+            history = [{"role": "user", "audio_payload": payload}]
+        if not history:
+            raise DuplexRuntimeConfigError("Qwen generation requires committed audio or conversation history")
+        audios = []
+        images = []
+        for index, message in enumerate(history):
+            if "audio_payload" not in message:
+                content = message.get("content")
+                if isinstance(content, list):
+                    parts = []
+                    for part in content:
+                        if part.get("type") == "image_url":
+                            encoded = part["image_url"]["url"].split(",", 1)[1]
+                            with Image.open(io.BytesIO(base64.b64decode(encoded, validate=True))) as image:
+                                image.thumbnail((448, 448))
+                                images.append(image.convert("RGB").copy())
+                            parts.append({"type": "image"})
+                        elif part.get("type") == "text":
+                            parts.append(part)
+                    messages.append({"role": message["role"], "content": parts})
+                else:
+                    messages.append(message)
+                continue
+            content, audio = self._audio_content(message["audio_payload"])
+            audios.append((audio, 16000))
+            if runtime_config.get("initial_user_text") and index == len(history) - 1:
+                content.append({"type": "text", "text": runtime_config["initial_user_text"]})
+            messages.append({"role": "user", "content": content})
+        messages, images = self._trim_prompt_images(messages, images)
+        prompt = self.processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+        mm = {"audio": audios} if audios else {}
+        if images:
+            mm["image"] = images
+        logger.info(
+            "Qwen duplex visual input request=%s images=%d sizes=%s audios=%d",
+            request_id,
+            len(images),
+            [image.size for image in images],
+            len(audios),
+        )
+        # Opt-in capture of the exact decoded images submitted to the processor.
+        # Request IDs are hashed because they need not be safe path components.
+        debug_dir = os.environ.get("VLLM_OMNI_QWEN_VISUAL_DEBUG_DIR")
+        if debug_dir:
+            try:
+                target = Path(debug_dir) / hashlib.sha256(request_id.encode()).hexdigest()[:24]
+                target.mkdir(parents=True, exist_ok=True)
+                filenames = []
+                for index, image in enumerate(images):
+                    filename = f"image_{index:02d}.png"
+                    image.save(target / filename)
+                    filenames.append(filename)
+                (target / "input.json").write_text(
+                    json.dumps(
+                        {"request_id": request_id, "images": filenames, "audio_count": len(audios), "prompt": prompt},
+                        ensure_ascii=False,
+                        indent=2,
+                    ),
+                    encoding="utf-8",
+                )
+                logger.info("Qwen duplex visual input capture request=%s path=%s", request_id, target)
+            except (OSError, ValueError):
+                logger.exception("Failed to capture Qwen visual input request=%s", request_id)
+        return DuplexAppendPlan(prompt={"prompt": prompt, "multi_modal_data": mm})
+
+    def decide_output(self, **kwargs):
+        return None
+
+    def data_plane_context(self, **kwargs):
+        return kwargs
diff --git a/vllm_omni/model_executor/models/qwen3_omni/duplex/session.py b/vllm_omni/model_executor/models/qwen3_omni/duplex/session.py
new file mode 100644
index 00000000000..de19e404c16
--- /dev/null
+++ b/vllm_omni/model_executor/models/qwen3_omni/duplex/session.py
@@ -0,0 +1,59 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+
+from vllm_omni.engine.duplex.plugin import DuplexModelSessionState
+from vllm_omni.model_executor.models.qwen3_omni.duplex.input import (
+    QwenPcmBuffer,
+)
+
+
+@dataclass(slots=True)
+class QwenDuplexSessionState(DuplexModelSessionState):
+    """Mutable model-owned state of one Qwen duplex session (owned by the session runner)."""
+
+    audio_buffer: QwenPcmBuffer = field(default_factory=QwenPcmBuffer)
+    # Keep content objects alongside payloads so identity survives history copies.
+    audio_history: list[tuple[object, dict]] = field(default_factory=list)
+    input_since_commit: bool = False
+    speech_since_commit: bool = False
+    context_locked: bool = False
+    committed_audio_payload: dict[str, object] | None = None
+    committed_audio_operation_id: str | None = None
+    committed_audio_reserved_bytes: int = 0
+    deferred_response_create: bool = False
+    deferred_precreate_response: bool = False
+    continuation_owner_id: str | None = None
+    continuation_units: int = 0
+    pending_silence_task: asyncio.Task[bool] | None = None
+    pending_silence_owner_id: str | None = None
+
+    def retain_committed_audio(
+        self,
+        payload: dict[str, object],
+        *,
+        operation_id: str | None,
+        reserved_bytes: int = 0,
+    ) -> None:
+        self.committed_audio_payload = payload
+        self.committed_audio_operation_id = operation_id
+        self.committed_audio_reserved_bytes += max(0, int(reserved_bytes))
+
+    def clear_committed_audio(self) -> int:
+        reserved_bytes = self.committed_audio_reserved_bytes
+        self.committed_audio_payload = None
+        self.committed_audio_operation_id = None
+        self.committed_audio_reserved_bytes = 0
+        self.deferred_response_create = False
+        self.deferred_precreate_response = False
+        return reserved_bytes
+
+    def clear_continuation(self) -> None:
+        self.continuation_owner_id = None
+        self.continuation_units = 0
+        self.pending_silence_task = None
+        self.pending_silence_owner_id = None
diff --git a/vllm_omni/model_executor/models/qwen3_omni/pipeline.py b/vllm_omni/model_executor/models/qwen3_omni/pipeline.py
index 1e515d0ddbb..9caff6d2791 100644
--- a/vllm_omni/model_executor/models/qwen3_omni/pipeline.py
+++ b/vllm_omni/model_executor/models/qwen3_omni/pipeline.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Qwen3-Omni-MoE pipeline topology (frozen).
 
 Stage 0: Thinker — multimodal understanding + text generation
@@ -21,6 +21,8 @@
 
 QWEN3_OMNI_PIPELINE = PipelineConfig(
     model_type="qwen3_omni_moe",
+    default_session_mode="turn",
+    duplex_plugin="vllm_omni.model_executor.models.qwen3_omni.duplex.plugin.Qwen3OmniDuplexPlugin",
     default_deploy_config_name="qwen3_omni_moe.yaml",
     model_arch="Qwen3OmniMoeForConditionalGeneration",
     endpoint_restrictions=(

From 2ab5d1701a98502ab1f0ebe48c90b45d31eeb8fe Mon Sep 17 00:00:00 2001
From: Anjie Hou <149605198+specture724@users.noreply.github.com>
Date: Thu, 17 Sep 2026 23:33:56 +0800
Subject: [PATCH 071/105] [4/N] Unify worker-side MP4 encoding and wire Wan
 into it (#7048)

Signed-off-by: specture724 <specture724@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Hongsheng Liu <liuhongsheng4@huawei.com>
---
 docs/serving/videos_api.md                    |  22 +-
 .../minimax_h3/test_minimax_h3_contract.py    |  81 +++-
 .../models/wan2_2/test_wan22_chunked_mp4.py   | 165 ++++++++
 .../models/wan2_2/test_wan22_s2v_pipeline.py  | 242 ++++++++++++
 tests/diffusion/utils/test_chunked_video.py   | 118 ++++++
 .../models/minimax_h3/pipeline_minimax_h3.py  |  85 ++--
 .../diffusion/models/wan2_2/chunked_mp4.py    |  87 +++++
 .../models/wan2_2/pipeline_wan2_2.py          |  60 ++-
 .../models/wan2_2/pipeline_wan2_2_i2v.py      |  24 +-
 .../models/wan2_2/pipeline_wan2_2_s2v.py      | 364 ++++++++++--------
 vllm_omni/diffusion/utils/chunked_video.py    | 160 ++++++++
 vllm_omni/diffusion/utils/media_utils.py      |   7 +-
 12 files changed, 1180 insertions(+), 235 deletions(-)
 create mode 100644 tests/diffusion/models/wan2_2/test_wan22_chunked_mp4.py
 create mode 100644 tests/diffusion/utils/test_chunked_video.py
 create mode 100644 vllm_omni/diffusion/models/wan2_2/chunked_mp4.py
 create mode 100644 vllm_omni/diffusion/utils/chunked_video.py

diff --git a/docs/serving/videos_api.md b/docs/serving/videos_api.md
index 1152ebce376..f48f2ca99f1 100644
--- a/docs/serving/videos_api.md
+++ b/docs/serving/videos_api.md
@@ -251,6 +251,7 @@ These `extra_params` control how the server turns decoded frames into MP4 bytes.
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
 | `preencode_mp4` | boolean | false | Encode the MP4 on the worker while the VAE is still decoding, instead of after the full video is materialized |
+| `preencode_batch_frames` | positive integer | 17 (H3, Wan T2V/I2V); 1 (Wan S2V) | Minimum accumulated frames per worker transfer/encoding batch; used only with `preencode_mp4=true` |
 | `video_codec_options` | object | null | Encoder options passed through to the H.264 encoder, such as `{"preset": "ultrafast", "threads": "0"}` |
 
 With `preencode_mp4` enabled, each committed VAE chunk leaves the accelerator and
@@ -261,16 +262,29 @@ unchanged: the same complete MP4, byte-for-byte equivalent frames.
 ```bash
 curl -X POST http://localhost:8091/v1/videos/sync \
   -F "prompt=A small robot walking through a neon city" \
-  -F 'extra_params={"preencode_mp4": true, "video_codec_options": {"preset": "ultrafast"}}' \
+  -F 'extra_params={"preencode_mp4": true, "preencode_batch_frames": 33, "video_codec_options": {"preset": "ultrafast"}}' \
   -o output.mp4
 ```
 
+Set `preencode_batch_frames` in `extra_params` (or `extra_args` for offline
+sampling) to tune batching. The worker accumulates complete VAE chunks until
+it has at least this many frames, then transfers and encodes them together.
+It always flushes the final partial batch. This is a threshold, not an exact
+chunk length: a value of 1 submits every native chunk immediately, and a value
+smaller than a native chunk does not split it. Larger values reduce transfers
+but retain more frames on the accelerator and delay encoding. The VAE decode
+window and output frame count stay unchanged. Wan S2V keeps its existing
+per-clip behavior by default. Zero, negative, fractional, boolean, string, and
+null values are rejected when pre-encoding is enabled.
+
 `preencode_mp4` applies to the complete-MP4 response paths only. The
 `/v1/realtime/video` WebSocket endpoint rejects it, because that path already
-overlaps encoding through its own incremental fragmented-MP4 encoder.
+overlaps encoding through its own incremental fragmented-MP4 encoder. Wan also
+rejects it together with `enable_frame_interpolation`, which needs the decoded
+frames the pre-encoded path no longer materializes.
 
-Support is per model: MiniMax-H3 implements it, and other models ignore the flag
-and take the full-decode path.
+Support is per model: MiniMax-H3 and Wan 2.2 (T2V, I2V, and S2V) implement it,
+and other models ignore the flag and take the full-decode path.
 
 ## Storage
 
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
index cea4862d15c..7d2d8715f78 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
@@ -2852,7 +2852,7 @@ def test_decode_to_mp4_batches_consumer_transfers(monkeypatch):
     from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
 
     class FakeEncoder:
-        instances = []
+        instances: list["FakeEncoder"] = []
 
         def __init__(self, **kwargs):
             self.pushes = []
@@ -2873,6 +2873,8 @@ def decode_latent(self, latent):
             return torch.zeros(1, 1, 2)
 
     class FakeVideoVAE:
+        chunk_value_range = (0.0, 1.0)
+
         def decode_with_chunks(self, latent, *, on_chunk):
             for value in (0.0, 0.25, 0.5):
                 on_chunk(torch.full((1, 3, 3, 2, 2), value))
@@ -2884,7 +2886,7 @@ def decode_with_chunks(self, latent, *, on_chunk):
     pipeline.device = torch.device("cpu")
     monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_uses_manual_component_offload", lambda self, component: False)
     monkeypatch.setattr(
-        "vllm_omni.diffusion.utils.media_utils.ChunkedMP4Encoder",
+        "vllm_omni.diffusion.utils.chunked_video.ChunkedMP4Encoder",
         FakeEncoder,
     )
 
@@ -2904,12 +2906,81 @@ def decode_with_chunks(self, latent, *, on_chunk):
     assert encoder.pushes[1].shape == (3, 2, 2, 3)
 
 
+def _peer_rank_preencode_pipeline(monkeypatch):
+    """An H3 pipeline whose video VAE is a distributed rank that owns no output.
+
+    Every rank of the VAE group must call ``decode_with_chunks`` to keep the
+    temporal collectives in lockstep, but only the owner receives chunks, so a
+    peer's callback is never invoked.
+    """
+    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
+
+    class FakeAudioVAE:
+        def decode_latent(self, latent):
+            return torch.zeros(1, 1, 2)
+
+    class PeerRankVideoVAE:
+        chunk_value_range = (0.0, 1.0)
+
+        def decode_with_chunks(self, latent, *, on_chunk):
+            del latent, on_chunk
+
+    pipeline = object.__new__(mod.MiniMaxH3Pipeline)
+    torch.nn.Module.__init__(pipeline)
+    pipeline.audio_vae = FakeAudioVAE()
+    pipeline.video_vae = PeerRankVideoVAE()
+    pipeline.device = torch.device("cpu")
+    pipeline.od_config = SimpleNamespace()
+    monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_uses_manual_component_offload", lambda self, component: False)
+    return pipeline
+
+
+def test_peer_vae_rank_returns_no_preencoded_output_instead_of_failing(monkeypatch):
+    """A rank that owns no output must not turn its silence into a request error."""
+    pipeline = _peer_rank_preencode_pipeline(monkeypatch)
+
+    output = pipeline.decode_to_mp4(torch.zeros(1), torch.zeros(1), height=2, width=2)
+
+    assert output == b""
+
+
+def test_peer_vae_rank_post_decode_reaches_post_processing(monkeypatch):
+    """The real H3 post_decode chain, not just the shared consumer, tolerates a peer rank."""
+    from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
+    from vllm_omni.diffusion.worker.utils import StepRequestState
+
+    pipeline = _peer_rank_preencode_pipeline(monkeypatch)
+    monkeypatch.setattr(pipeline, "_unpack_denoised_rows", lambda *args, **kwargs: (torch.zeros(1), torch.zeros(1)))
+    state = StepRequestState(
+        request_id="peer-rank",
+        sampling=SimpleNamespace(num_outputs_per_prompt=1),
+        prompt="a prompt",
+    )
+    state.latents = torch.zeros(1)
+    state.extra[mod._STEP_BRANCH] = object()
+    state.extra[mod._STEP_AUDIO_ROWS] = torch.zeros(1)
+    state.extra[mod._STEP_SHAPE] = {
+        "latent_t": 1,
+        "latent_h": 1,
+        "latent_w": 1,
+        "audio_t": 1,
+        "height": 2,
+        "width": 2,
+        "preencode_mp4": True,
+    }
+
+    output = pipeline.post_decode(state)
+
+    assert output.output == (b"", None)
+    assert mod._minimax_h3_post_process(output.output)["video"] == [b""]
+
+
 def test_request_video_codec_options_reach_the_preencoded_mp4_encoder(monkeypatch):
     """A client's encoder options must survive the worker-side pre-encode path."""
     from vllm_omni.diffusion.models.minimax_h3 import pipeline_minimax_h3 as mod
 
     class FakeEncoder:
-        instances = []
+        instances: list["FakeEncoder"] = []
 
         def __init__(self, **kwargs):
             self.kwargs = kwargs
@@ -2929,6 +3000,8 @@ def decode_latent(self, latent):
             return torch.zeros(1, 1, 2)
 
     class FakeVideoVAE:
+        chunk_value_range = (0.0, 1.0)
+
         def decode_with_chunks(self, latent, *, on_chunk):
             on_chunk(torch.zeros(1, 3, 1, 2, 2))
 
@@ -2938,7 +3011,7 @@ def decode_with_chunks(self, latent, *, on_chunk):
     pipeline.video_vae = FakeVideoVAE()
     pipeline.device = torch.device("cpu")
     monkeypatch.setattr(mod.MiniMaxH3Pipeline, "_uses_manual_component_offload", lambda self, component: False)
-    monkeypatch.setattr("vllm_omni.diffusion.utils.media_utils.ChunkedMP4Encoder", FakeEncoder)
+    monkeypatch.setattr("vllm_omni.diffusion.utils.chunked_video.ChunkedMP4Encoder", FakeEncoder)
 
     pipeline.decode_to_mp4(
         torch.zeros(1),
diff --git a/tests/diffusion/models/wan2_2/test_wan22_chunked_mp4.py b/tests/diffusion/models/wan2_2/test_wan22_chunked_mp4.py
new file mode 100644
index 00000000000..a919d1727fb
--- /dev/null
+++ b/tests/diffusion/models/wan2_2/test_wan22_chunked_mp4.py
@@ -0,0 +1,165 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import io
+from types import SimpleNamespace
+
+import av
+import pytest
+import torch
+
+from vllm_omni.diffusion.models.wan2_2.chunked_mp4 import (
+    WAN_DEFAULT_OUTPUT_FPS,
+    resolve_wan_output_fps,
+    resolve_wan_preencode_batch_frames,
+    resolve_wan_preencode_mp4,
+    resolve_wan_video_codec_options,
+    wan_preencoded_mp4_payload,
+)
+from vllm_omni.diffusion.utils.chunked_video import decode_to_mp4
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
+
+
+class _FakeWanVAE:
+    """Publish temporal chunks the way the Wan VAE seam does."""
+
+    chunk_value_range = (-1.0, 1.0)
+
+    def __init__(self, *, batch: int, chunks: int, frames_per_chunk: int, height: int, width: int):
+        self.batch = batch
+        self.chunks = chunks
+        self.frames_per_chunk = frames_per_chunk
+        self.height = height
+        self.width = width
+        self.chunk_calls = 0
+
+    def decode_with_chunks(self, latents, *, on_chunk):
+        del latents
+        assert on_chunk is not None
+        for index in range(self.chunks):
+            self.chunk_calls += 1
+            value = -1.0 + 2.0 * index / max(self.chunks - 1, 1)
+            on_chunk(torch.full((self.batch, 3, self.frames_per_chunk, self.height, self.width), value))
+
+
+def _decoded_frame_count(data: bytes) -> int:
+    with av.open(io.BytesIO(data)) as container:
+        return sum(1 for _ in container.decode(video=0))
+
+
+def test_decode_wan_latents_to_mp4_emits_one_playable_mp4_per_batch_entry():
+    vae = _FakeWanVAE(batch=2, chunks=6, frames_per_chunk=2, height=16, width=32)
+
+    videos = decode_to_mp4(vae, torch.zeros(1), fps=24, batch_frames=4)
+
+    assert len(videos) == 2
+    for data in videos:
+        assert data[:4] and _decoded_frame_count(data) == 12
+
+
+def test_decode_wan_latents_to_mp4_coalesces_transfers_without_losing_frames():
+    """batch_frames only changes how many transfers carry the same frames."""
+    unbatched = _FakeWanVAE(batch=1, chunks=8, frames_per_chunk=1, height=16, width=32)
+    batched = _FakeWanVAE(batch=1, chunks=8, frames_per_chunk=1, height=16, width=32)
+
+    per_chunk = decode_to_mp4(unbatched, torch.zeros(1), fps=24, batch_frames=1)
+    coalesced = decode_to_mp4(batched, torch.zeros(1), fps=24, batch_frames=4)
+
+    assert _decoded_frame_count(per_chunk[0]) == _decoded_frame_count(coalesced[0]) == 8
+
+
+def test_decode_wan_latents_to_mp4_returns_nothing_for_a_rank_without_output():
+    class SilentVAE:
+        chunk_value_range = (-1.0, 1.0)
+
+        def decode_with_chunks(self, latents, *, on_chunk):
+            del latents, on_chunk
+
+    assert decode_to_mp4(SilentVAE(), torch.zeros(1), fps=24) == []
+
+
+def test_decode_wan_latents_to_mp4_rejects_a_non_positive_batch():
+    with pytest.raises(ValueError, match="batch_frames"):
+        decode_to_mp4(
+            _FakeWanVAE(batch=1, chunks=1, frames_per_chunk=1, height=16, width=16), None, fps=24, batch_frames=0
+        )
+
+
+def test_decode_wan_latents_to_mp4_rejects_a_vae_without_the_capability():
+    class PlainVAE:
+        chunk_value_range = (-1.0, 1.0)
+
+        def decode(self, z, return_dict=True):
+            del z, return_dict
+
+    with pytest.raises(TypeError, match="chunked VAE decode capability"):
+        decode_to_mp4(PlainVAE(), torch.zeros(1), fps=24)
+
+
+def test_preencode_flag_is_off_unless_the_request_asks_for_it():
+    assert resolve_wan_preencode_mp4(SimpleNamespace(extra_args=None), output_type="np") is False
+    assert resolve_wan_preencode_mp4(SimpleNamespace(extra_args={}), output_type="np") is False
+    assert resolve_wan_preencode_mp4(SimpleNamespace(extra_args={"preencode_mp4": True}), output_type="np") is True
+
+
+def test_preencode_rejects_combinations_it_cannot_serve():
+    interpolating = SimpleNamespace(extra_args={"preencode_mp4": True}, enable_frame_interpolation=True)
+    with pytest.raises(ValueError, match="enable_frame_interpolation"):
+        resolve_wan_preencode_mp4(interpolating, output_type="np")
+
+    with pytest.raises(ValueError, match="output_type"):
+        resolve_wan_preencode_mp4(SimpleNamespace(extra_args={"preencode_mp4": True}), output_type="pil")
+
+
+def test_output_fps_mirrors_the_serving_fallback():
+    assert resolve_wan_output_fps(SimpleNamespace(fps=16)) == 16
+    assert resolve_wan_output_fps(SimpleNamespace(fps=[16])) == 16
+    assert resolve_wan_output_fps(SimpleNamespace(fps=None)) == WAN_DEFAULT_OUTPUT_FPS
+    assert resolve_wan_output_fps(SimpleNamespace()) == WAN_DEFAULT_OUTPUT_FPS
+
+
+def test_codec_options_reach_the_encoder_as_strings():
+    params = SimpleNamespace(extra_args={"video_codec_options": {"preset": "ultrafast", "threads": 0}})
+    assert resolve_wan_video_codec_options(params) == {"preset": "ultrafast", "threads": "0"}
+    assert resolve_wan_video_codec_options(SimpleNamespace(extra_args={})) == {"preset": "ultrafast", "threads": "0"}
+    assert resolve_wan_video_codec_options(SimpleNamespace(extra_args={"video_codec_options": None})) is None
+    assert resolve_wan_video_codec_options(SimpleNamespace(extra_args={"video_codec_options": {}})) == {}
+
+
+def test_preencoded_payload_passes_bytes_through_and_ignores_tensors():
+    assert wan_preencoded_mp4_payload(torch.zeros(1, 3, 2, 4, 4)) is None
+    assert wan_preencoded_mp4_payload([b"one", b"two"]) == {"payload": {"video": [b"one", b"two"]}, "metadata": {}}
+    assert wan_preencoded_mp4_payload(b"one") == {"payload": {"video": [b"one"]}, "metadata": {}}
+
+
+@pytest.mark.parametrize("value", [1, 5, 33])
+def test_request_batch_threshold_controls_transfers_without_losing_frames(monkeypatch, value):
+    from vllm_omni.diffusion.utils import chunked_video
+
+    transfers = []
+    quantize = chunked_video.chunk_to_uint8_frames
+
+    def capture(chunk, value_range):
+        transfers.append(chunk.shape[2])
+        return quantize(chunk, value_range)
+
+    monkeypatch.setattr(chunked_video, "chunk_to_uint8_frames", capture)
+    params = SimpleNamespace(extra_args={"preencode_mp4": True, "preencode_batch_frames": value})
+    vae = _FakeWanVAE(batch=1, chunks=4, frames_per_chunk=3, height=16, width=32)
+    videos = decode_to_mp4(vae, torch.zeros(1), fps=24, batch_frames=resolve_wan_preencode_batch_frames(params))
+
+    assert transfers == {1: [3, 3, 3, 3], 5: [6, 6], 33: [12]}[value]
+    assert _decoded_frame_count(videos[0]) == 12
+
+
+@pytest.mark.parametrize("value", [0, -1, True, 1.5, "17", None])
+def test_request_batch_threshold_rejects_invalid_values(value):
+    with pytest.raises(ValueError, match="preencode_batch_frames"):
+        resolve_wan_preencode_batch_frames(SimpleNamespace(extra_args={"preencode_batch_frames": value}))
+
+
+def test_request_batch_threshold_preserves_model_defaults():
+    params = SimpleNamespace(extra_args=None)
+    assert resolve_wan_preencode_batch_frames(params) == 17
+    assert resolve_wan_preencode_batch_frames(params, default=1) == 1
diff --git a/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py b/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
index 94f8b86fd20..ab8cd132c88 100644
--- a/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
+++ b/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
@@ -647,3 +647,245 @@ def test_s2v_pipeline_hsdp_forward_complete_process():
     assert video.shape[1] == 3  # channels
     assert audio_waveform is not None
     assert audio_sr == 16000
+
+
+def _make_s2v_preencode_pipeline() -> Wan22S2VPipeline:
+    """Build the same stub pipeline the batching test drives, for preencode runs."""
+    pipeline = object.__new__(Wan22S2VPipeline)
+    nn.Module.__init__(pipeline)
+    pipeline.device = torch.device("cpu")
+    pipeline.transformer = MagicMock()
+    pipeline.transformer.dtype = torch.float32
+    # A fresh iterator per call: the clip loop reads this once per clip.
+    pipeline.transformer.parameters.side_effect = lambda: iter([torch.zeros(1, dtype=torch.float32)])
+    pipeline.transformer.casual_audio_encoder = None
+    pipeline.transformer.encode_audio.side_effect = lambda audio, _motion: {"audio_emb": audio}
+    pipeline.vae = MagicMock()
+    pipeline.vae.dtype = torch.float32
+    # The shared consumer reads the published pixel range off the VAE.
+    pipeline.vae.chunk_value_range = (-1.0, 1.0)
+    # One decoded clip: [B, C, T, H, W] for a batch of four (2 requests x 2 outputs).
+    pipeline.vae.decode.return_value = (torch.zeros(4, 3, 8, 16, 16),)
+    pipeline.od_config = SimpleNamespace(
+        enable_cpu_offload=False,
+        parallel_config=SimpleNamespace(use_hsdp=False),
+    )
+    pipeline.scheduler = MagicMock(timesteps=torch.tensor([1.0]))
+    pipeline._flow_shift = 3.0
+    pipeline.vae_scale_factor_spatial = 8
+    pipeline.resolution_divisor = 16
+    pipeline.motion_frames = 7
+    pipeline.drop_first_motion = True
+    pipeline._DEFAULT_INFER_FRAMES = 8
+    pipeline._guidance_scale = None
+    pipeline._num_timesteps = None
+    pipeline.check_inputs = lambda *args, **kwargs: None
+    pipeline.encode_prompt = MagicMock(return_value=(torch.zeros(4, 2, 3), torch.ones(4, 2, 3)))
+    pipeline.encode_audio = MagicMock(return_value=(torch.zeros(1, 1, 2, 8), 1, 8))
+    pipeline.encode_ref_image = MagicMock(return_value=torch.zeros(1, 16, 1, 2, 2))
+    pipeline.prepare_motion_latents = MagicMock(
+        side_effect=lambda pixels, **_: torch.zeros(pixels.shape[0], 16, 2, 2, 2)
+    )
+    pipeline._denormalize_latents = lambda latents: latents
+    pipeline.diffuse = MagicMock(side_effect=lambda **kwargs: kwargs["latents"])
+    return pipeline
+
+
+def _make_s2v_preencode_batch(audio_a, audio_b, **sampling_overrides) -> DiffusionRequestBatch:
+    image = PIL.Image.new("RGB", (16, 16))
+    return DiffusionRequestBatch(
+        requests=[
+            SimpleNamespace(
+                request_id="a",
+                prompt={"prompt": "first", "multi_modal_data": {"image": image, "audio": audio_a}},
+                sampling_params=_make_s2v_sampling(
+                    num_outputs_per_prompt=2,
+                    latents=torch.zeros(2, 16, 2, 2, 2),
+                    output_type="np",
+                    **sampling_overrides,
+                ),
+            ),
+            SimpleNamespace(
+                request_id="b",
+                prompt={"prompt": "second", "multi_modal_data": {"image": image, "audio": audio_b}},
+                sampling_params=_make_s2v_sampling(
+                    num_outputs_per_prompt=2,
+                    latents=torch.ones(2, 16, 2, 2, 2),
+                    output_type="np",
+                    **sampling_overrides,
+                ),
+            ),
+        ]
+    )
+
+
+def _decode_mp4(data: bytes):
+    """Return (video frame count, first audio samples) for one encoded container."""
+    import io
+
+    import av
+
+    with av.open(io.BytesIO(data)) as container:
+        frames = sum(1 for _ in container.decode(video=0))
+    with av.open(io.BytesIO(data)) as container:
+        assert container.streams.audio, "the worker must mux the waveform into the container"
+        samples = np.concatenate(
+            [frame.to_ndarray().reshape(-1) for frame in container.decode(audio=0)][:4],
+        )
+    return frames, samples
+
+
+@pytest.mark.parametrize("batch_frames", [1, 1000])
+def test_s2v_preencode_returns_playable_mp4_bytes_per_request(monkeypatch, batch_frames) -> None:
+    """The clip loop hands finished clips to the encoder instead of concatenating."""
+    pipeline = _make_s2v_preencode_pipeline()
+    # Two clips, so the autoregressive motion feedback runs between pushes.
+    pipeline.encode_audio = MagicMock(return_value=(torch.zeros(1, 1, 2, 8), 2, 16))
+    audio_a = np.zeros(16000, dtype=np.float32)
+    audio_b = np.full(16000, 0.5, dtype=np.float32)
+    batch = _make_s2v_preencode_batch(
+        audio_a, audio_b, extra_args={"preencode_mp4": True, "preencode_batch_frames": batch_frames}
+    )
+    from vllm_omni.diffusion.utils import chunked_video
+
+    transfers = []
+    quantize = chunked_video.chunk_to_uint8_frames
+
+    def capture(chunk, value_range):
+        transfers.append(chunk.shape[2])
+        return quantize(chunk, value_range)
+
+    monkeypatch.setattr(chunked_video, "chunk_to_uint8_frames", capture)
+
+    with patch("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v.current_omni_platform") as platform:
+        platform.is_available.return_value = False
+        outputs = pipeline.forward(batch)
+
+    assert len(outputs) == 2
+    assert pipeline.vae.decode.call_count == 2, "both clips must reach the encoder"
+    assert len(transfers) == (2 if batch_frames == 1 else 1)
+
+    decoded = []
+    for request_output in outputs:
+        # Two outputs per prompt, each already a complete container.
+        assert isinstance(request_output.output, list)
+        assert len(request_output.output) == 2
+        for data in request_output.output:
+            assert isinstance(data, bytes)
+            frames, samples = _decode_mp4(data)
+            assert frames > 0
+            decoded.append(samples)
+
+    # Four entries: request a's waveform for its two outputs, then request b's.
+    # A silent and a non-silent waveform must not land on the same request.
+    assert np.abs(decoded[0]).max() == pytest.approx(0.0, abs=1e-3)
+    assert np.abs(decoded[1]).max() == pytest.approx(0.0, abs=1e-3)
+    assert np.abs(decoded[2]).max() > 0.1
+    assert np.abs(decoded[3]).max() > 0.1
+
+
+def test_s2v_preencode_aborts_encoders_when_a_later_clip_fails(monkeypatch) -> None:
+    """A failure after the first push must not strand encoder worker threads."""
+    pipeline = _make_s2v_preencode_pipeline()
+    pipeline.encode_audio = MagicMock(return_value=(torch.zeros(1, 1, 2, 8), 2, 16))
+    batch = _make_s2v_preencode_batch(
+        np.zeros(16000, dtype=np.float32),
+        np.ones(16000, dtype=np.float32),
+        extra_args={"preencode_mp4": True, "preencode_batch_frames": 1},
+    )
+    sessions = []
+
+    from vllm_omni.diffusion.utils.chunked_video import ChunkedVideoMP4Session
+
+    def capture_session(**kwargs):
+        session = ChunkedVideoMP4Session(**kwargs)
+        sessions.append(session)
+        return session
+
+    def fail_on_second_clip(**kwargs):
+        if pipeline.vae.decode.call_count:
+            raise RuntimeError("second clip failed")
+        return kwargs["latents"]
+
+    pipeline.diffuse = fail_on_second_clip
+    monkeypatch.setattr("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v.ChunkedVideoMP4Session", capture_session)
+
+    with patch("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v.current_omni_platform") as platform:
+        platform.is_available.return_value = False
+        with pytest.raises(RuntimeError, match="second clip failed"):
+            pipeline.forward(batch)
+
+    assert len(sessions) == 1
+    assert len(sessions[0]._encoders) == 4
+    assert all(not encoder._thread.is_alive() for encoder in sessions[0]._encoders)
+
+
+def test_s2v_preencode_skips_encoding_on_a_vae_patch_parallel_peer(monkeypatch) -> None:
+    """A peer still receives every clip for the motion loop but encodes none of them."""
+    pipeline = _make_s2v_preencode_pipeline()
+    pipeline.encode_audio = MagicMock(return_value=(torch.zeros(1, 1, 2, 8), 2, 16))
+    # A peer's patch-parallel decode returns an empty placeholder.
+    pipeline.vae.decode.return_value = (torch.empty(0),)
+    pipeline.vae._vae_pp_group = object()
+    broadcasts = []
+    monkeypatch.setattr(
+        "torch.distributed.broadcast",
+        lambda tensor, src, group: broadcasts.append(tensor.zero_()),
+    )
+    batch = _make_s2v_preencode_batch(
+        np.zeros(16000, dtype=np.float32),
+        np.ones(16000, dtype=np.float32),
+        extra_args={"preencode_mp4": True, "preencode_batch_frames": 1},
+    )
+    sessions = []
+
+    from vllm_omni.diffusion.utils.chunked_video import ChunkedVideoMP4Session
+
+    def capture_session(**kwargs):
+        session = ChunkedVideoMP4Session(**kwargs)
+        sessions.append(session)
+        return session
+
+    monkeypatch.setattr("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v.ChunkedVideoMP4Session", capture_session)
+
+    with patch("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v.current_omni_platform") as platform:
+        platform.is_available.return_value = False
+        outputs = pipeline.forward(batch)
+
+    assert len(broadcasts) == 2, "the peer must still join the broadcast for both clips"
+    # Once for the initial motion latents, once more from the peer's broadcast clip.
+    assert pipeline.prepare_motion_latents.call_count == 2, "the motion loop still consumes the peer's frames"
+    assert sessions[0]._encoders == []
+    assert [request_output.output for request_output in outputs] == [[], []]
+
+
+@pytest.mark.parametrize("output_type", ["pil", "pt", "latent"])
+def test_s2v_preencode_rejects_request_output_types_it_cannot_serve(output_type) -> None:
+    """Pre-encoding returns MP4 bytes, so a request asking for frames must fail."""
+    pipeline = _make_s2v_preencode_pipeline()
+    batch = _make_s2v_preencode_batch(
+        np.zeros(16000, dtype=np.float32),
+        np.ones(16000, dtype=np.float32),
+        extra_args={"preencode_mp4": True},
+    )
+    for request in batch.requests:
+        request.sampling_params.output_type = output_type
+
+    with pytest.raises(ValueError, match="output_type"):
+        pipeline.forward(batch)
+
+
+def test_s2v_preencode_keeps_the_full_decode_path_untouched() -> None:
+    """Without the flag the loop still returns the (video, audio, rate) tuple."""
+    pipeline = _make_s2v_preencode_pipeline()
+    audio_a = np.zeros(16000, dtype=np.float32)
+    audio_b = np.ones(16000, dtype=np.float32)
+    batch = _make_s2v_preencode_batch(audio_a, audio_b)
+
+    with patch("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v.current_omni_platform") as platform:
+        platform.is_available.return_value = False
+        outputs = pipeline.forward(batch)
+
+    assert outputs[0].output[0].shape[0] == 2
+    np.testing.assert_array_equal(outputs[0].output[1], audio_a)
+    np.testing.assert_array_equal(outputs[1].output[1], audio_b)
diff --git a/tests/diffusion/utils/test_chunked_video.py b/tests/diffusion/utils/test_chunked_video.py
new file mode 100644
index 00000000000..849b49290dd
--- /dev/null
+++ b/tests/diffusion/utils/test_chunked_video.py
@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import io
+
+import av
+import numpy as np
+import pytest
+import torch
+
+from vllm_omni.diffusion.utils.chunked_video import (
+    ChunkedVideoMP4Session,
+    chunk_to_uint8_frames,
+    decode_to_mp4,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
+
+
+class _FakeVAE:
+    """Publish committed chunks the way a chunked-decode VAE does."""
+
+    def __init__(self, value_range, *, batch=1, chunks=4, frames=2, height=16, width=32):
+        self.chunk_value_range = value_range
+        self._shape = (batch, 3, frames, height, width)
+        self._chunks = chunks
+
+    def decode_with_chunks(self, z, *, on_chunk):
+        del z
+        low, high = self.chunk_value_range
+        for index in range(self._chunks):
+            value = low + (high - low) * index / max(self._chunks - 1, 1)
+            on_chunk(torch.full(self._shape, value))
+
+
+def _decoded(data: bytes):
+    with av.open(io.BytesIO(data)) as container:
+        return np.stack([f.to_ndarray(format="rgb24") for f in container.decode(video=0)])
+
+
+def test_quantization_maps_each_producer_range_onto_the_same_pixels():
+    """A model's published range is what makes chunks comparable across models."""
+    wan = torch.tensor([-1.0, 0.0, 1.0]).view(1, 1, 3, 1, 1).expand(1, 3, 3, 1, 1)
+    h3 = torch.tensor([0.0, 0.5, 1.0]).view(1, 1, 3, 1, 1).expand(1, 3, 3, 1, 1)
+
+    from_wan = chunk_to_uint8_frames(wan.contiguous(), (-1.0, 1.0))
+    from_h3 = chunk_to_uint8_frames(h3.contiguous(), (0.0, 1.0))
+
+    # Same physical pixels, different published ranges.
+    assert np.array_equal(from_wan, from_h3)
+    assert from_wan.reshape(-1, 3)[:, 0].tolist() == [0, 128, 255]
+
+
+def test_quantization_rejects_a_degenerate_range():
+    with pytest.raises(ValueError, match="increasing"):
+        chunk_to_uint8_frames(torch.zeros(1, 3, 1, 2, 2), (1.0, 1.0))
+
+
+@pytest.mark.parametrize("value_range", [(-1.0, 1.0), (0.0, 1.0)])
+def test_decode_to_mp4_drives_any_declared_range(value_range):
+    videos = decode_to_mp4(_FakeVAE(value_range), torch.zeros(1), fps=24, batch_frames=4)
+
+    assert len(videos) == 1
+    assert _decoded(videos[0]).shape[0] == 8
+
+
+def test_decode_to_mp4_emits_one_container_per_batch_entry():
+    videos = decode_to_mp4(_FakeVAE((-1.0, 1.0), batch=3), torch.zeros(1), fps=24)
+
+    assert len(videos) == 3
+    assert all(_decoded(v).shape[0] == 8 for v in videos)
+
+
+def test_decode_to_mp4_rejects_a_vae_without_the_capability():
+    class PlainVAE:
+        def decode(self, z):
+            del z
+
+    with pytest.raises(TypeError, match="chunked VAE decode capability"):
+        decode_to_mp4(PlainVAE(), torch.zeros(1), fps=24)
+
+
+def test_decode_to_mp4_returns_nothing_for_a_rank_without_output():
+    class SilentVAE:
+        chunk_value_range = (-1.0, 1.0)
+
+        def decode_with_chunks(self, z, *, on_chunk):
+            del z, on_chunk
+
+    assert decode_to_mp4(SilentVAE(), torch.zeros(1), fps=24) == []
+
+
+def test_session_crops_the_decoder_padding_away():
+    session = ChunkedVideoMP4Session(value_range=(0.0, 1.0), fps=24, crop=(8, 16))
+    session.push(torch.zeros(1, 3, 4, 16, 32))
+
+    assert _decoded(session.finish()[0]).shape[1:3] == (8, 16)
+
+
+def test_session_muxes_one_waveform_per_batch_entry():
+    audio = [np.zeros(8000, dtype=np.float32), np.full(8000, 0.5, dtype=np.float32)]
+    session = ChunkedVideoMP4Session(value_range=(0.0, 1.0), fps=24, audio_waveforms=audio, audio_sample_rate=16000)
+    session.push(torch.zeros(2, 3, 4, 16, 16))
+
+    for data in session.finish():
+        with av.open(io.BytesIO(data)) as container:
+            assert container.streams.audio
+
+
+def test_session_rejects_a_waveform_count_that_does_not_match_the_batch():
+    session = ChunkedVideoMP4Session(value_range=(0.0, 1.0), fps=24, audio_waveforms=[np.zeros(8000, dtype=np.float32)])
+    with pytest.raises(ValueError, match="one audio waveform per batch entry"):
+        session.push(torch.zeros(2, 3, 4, 16, 16))
+
+
+def test_session_rejects_a_non_positive_batch():
+    with pytest.raises(ValueError, match="batch_frames"):
+        ChunkedVideoMP4Session(value_range=(0.0, 1.0), fps=24, batch_frames=0)
diff --git a/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py b/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
index 60d6f412538..1a8395e5ca2 100644
--- a/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
+++ b/vllm_omni/diffusion/models/minimax_h3/pipeline_minimax_h3.py
@@ -1726,66 +1726,47 @@ def decode_to_mp4(
     ) -> bytes:
         """Decode and encode one output on the worker without full-video materialization.
 
-        Audio is decoded first so the incremental mux session can attach its audio
-        stream before temporal video chunks arrive. The callback receives committed
-        float32 ``BCTHW`` frames, performs the requested-size crop and uint8
-        conversion in the worker, then applies bounded backpressure to the encoder.
+        Audio is decoded first so the incremental mux session can attach its
+        audio stream before temporal video chunks arrive. Everything after a
+        chunk is committed -- crop, quantization, transfer, encoding -- is the
+        shared consumer's job; this method only supplies what is specific to
+        H3: the audio waveform, the requested-size crop, and the fixed rate.
+
+        Every rank of a distributed VAE group drives the temporal collectives,
+        but only the output owner receives chunks, so a peer rank returns empty
+        bytes -- the pre-encoded counterpart of the empty tensor the full
+        decode leaves there.
         """
-        from vllm_omni.diffusion.utils.media_utils import ChunkedMP4Encoder
-
-        if batch_frames <= 0:
-            raise ValueError("batch_frames must be positive")
+        from vllm_omni.diffusion.utils.chunked_video import decode_to_mp4 as decode_chunks_to_mp4
 
         with self._component_on_device(self.audio_vae):
             audio = self.audio_vae.decode_latent(audio_latent)
         audio_np = audio.detach().float().cpu().numpy()
         if audio_np.ndim == 3 and audio_np.shape[0] == 1:
             audio_np = audio_np[0]
-        encoder = ChunkedMP4Encoder(
-            width=width,
-            height=height,
-            fps=MINIMAX_H3_FPS,
-            audio_waveform=audio_np,
-            audio_sample_rate=MINIMAX_H3_AUDIO_SAMPLE_RATE,
-            max_pending=max_pending,
-            video_codec_options=video_codec_options,
-        )
-
-        pending_chunks: list[torch.Tensor] = []
-        pending_frames = 0
-
-        def flush_pending() -> None:
-            nonlocal pending_frames
-            if not pending_chunks:
-                return
-            batched = torch.cat(pending_chunks, dim=1)
-            encoder.push(batched[0].cpu().numpy())
-            pending_chunks.clear()
-            pending_frames = 0
-
-        def on_chunk(frames: torch.Tensor) -> None:
-            nonlocal pending_frames
-            prepared = _prepare_minimax_h3_video_output(frames[..., :height, :width])
-            if prepared.shape[0] != 1:
-                raise ValueError("MiniMax H3 chunked MP4 encoding currently expects one output per decoder")
-            pending_chunks.append(prepared)
-            pending_frames += int(prepared.shape[1])
-            if pending_frames >= batch_frames:
-                flush_pending()
 
-        try:
-            with self._component_on_device(self.video_vae):
-                with current_omni_platform.create_autocast_context(
-                    device_type=self.device.type,
-                    dtype=torch.float16,
-                    enabled=True,
-                ):
-                    self.video_vae.decode_with_chunks(video_latent, on_chunk=on_chunk)
-            flush_pending()
-            return encoder.finish()
-        except BaseException:
-            encoder.abort()
-            raise
+        with self._component_on_device(self.video_vae):
+            with current_omni_platform.create_autocast_context(
+                device_type=self.device.type,
+                dtype=torch.float16,
+                enabled=True,
+            ):
+                videos = decode_chunks_to_mp4(
+                    self.video_vae,
+                    video_latent,
+                    fps=MINIMAX_H3_FPS,
+                    audio_waveforms=[audio_np],
+                    audio_sample_rate=MINIMAX_H3_AUDIO_SAMPLE_RATE,
+                    batch_frames=batch_frames,
+                    max_pending=max_pending,
+                    video_codec_options=video_codec_options,
+                    crop=(height, width),
+                )
+        if not videos:
+            return b""
+        if len(videos) != 1:
+            raise ValueError("MiniMax H3 chunked MP4 encoding currently expects one output per decoder")
+        return videos[0]
 
     def decode(
         self,
diff --git a/vllm_omni/diffusion/models/wan2_2/chunked_mp4.py b/vllm_omni/diffusion/models/wan2_2/chunked_mp4.py
new file mode 100644
index 00000000000..5b16a7a135f
--- /dev/null
+++ b/vllm_omni/diffusion/models/wan2_2/chunked_mp4.py
@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Worker-side MP4 encoding for Wan VAE temporal chunks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from vllm_omni.diffusion.utils.media_utils import normalize_preencode_batch_frames, normalize_video_codec_options
+
+# Matches the fallback the video serving layer applies when a request omits fps,
+# so the bytes the worker encodes carry the rate the response advertises.
+WAN_DEFAULT_OUTPUT_FPS = 24
+
+# Keep worker-side encoding consistent with the one-shot serving encoder when
+# a request does not choose codec options explicitly.
+WAN_DEFAULT_VIDEO_CODEC_OPTIONS = {"preset": "ultrafast", "threads": "0"}
+
+# Wan publishes one latent frame group per callback, which is far finer than one
+# host transfer is worth. 17 frames matches MiniMax-H3's native clip size.
+WAN_DEFAULT_BATCH_FRAMES = 17
+
+
+def wan_preencoded_mp4_payload(video: Any) -> dict[str, Any] | None:
+    """Return a post-process payload when the worker already encoded the MP4.
+
+    Returns ``None`` for the ordinary frame-tensor output so callers fall
+    through to their existing post-processing.
+
+    No fps is reported here: :func:`resolve_wan_output_fps` mirrors the fallback
+    the serving layer applies, so the rate the response advertises already
+    matches the rate these bytes were encoded at.
+    """
+    if isinstance(video, (bytes, bytearray, memoryview)):
+        video = [video]
+    if not isinstance(video, list) or not all(isinstance(item, (bytes, bytearray, memoryview)) for item in video):
+        return None
+    return {"payload": {"video": [bytes(item) for item in video]}, "metadata": {}}
+
+
+def resolve_wan_preencode_mp4(sampling_params: Any, *, output_type: str) -> bool:
+    """Return whether this request wants the worker to pre-encode the MP4.
+
+    Reject rather than silently downgrade the combinations the pre-encoded path
+    cannot serve: it emits MP4 bytes, so nothing downstream can interpolate
+    frames or hand back an array.
+    """
+    extra_args = getattr(sampling_params, "extra_args", None) or {}
+    if not extra_args.get("preencode_mp4", False):
+        return False
+    if getattr(sampling_params, "enable_frame_interpolation", False):
+        raise ValueError(
+            "preencode_mp4 cannot be combined with enable_frame_interpolation: interpolation "
+            "needs the decoded frames that the pre-encoded path no longer materializes"
+        )
+    if output_type != "np":
+        raise ValueError(f"preencode_mp4 returns MP4 bytes and cannot serve output_type={output_type!r}")
+    return True
+
+
+def resolve_wan_preencode_batch_frames(sampling_params: Any, *, default: int = WAN_DEFAULT_BATCH_FRAMES) -> int:
+    """Read the MP4 batching threshold before starting expensive generation."""
+    extra_args = getattr(sampling_params, "extra_args", None) or {}
+    return normalize_preencode_batch_frames(extra_args.get("preencode_batch_frames", default))
+
+
+def resolve_wan_video_codec_options(sampling_params: Any) -> dict[str, str] | None:
+    """Read the request's encoder options, preserving serving defaults.
+
+    An absent key inherits the one-shot serving encoder's defaults. Explicit
+    ``None`` and an empty mapping remain distinct caller choices.
+    """
+    extra_args = getattr(sampling_params, "extra_args", None) or {}
+    return normalize_video_codec_options(extra_args.get("video_codec_options", WAN_DEFAULT_VIDEO_CODEC_OPTIONS))
+
+
+def resolve_wan_output_fps(sampling_params: Any) -> int:
+    """Resolve the fps the worker encodes with.
+
+    The serving layer resolves output fps from the request's ``fps`` field, not
+    from ``frame_rate``, so pre-encoding has to read the same field or the bytes
+    would carry a rate the response does not advertise.
+    """
+    fps = getattr(sampling_params, "fps", None)
+    if isinstance(fps, list):
+        fps = fps[0] if fps else None
+    return int(fps) if fps else WAN_DEFAULT_OUTPUT_FPS
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
index 915fb45f740..a971806b026 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2.py
@@ -40,12 +40,20 @@
 from vllm_omni.diffusion.models.interface import SupportsComponentDiscovery
 from vllm_omni.diffusion.models.progress_bar import ProgressBarMixin, _is_rank_zero
 from vllm_omni.diffusion.models.schedulers import FlowUniPCMultistepScheduler
+from vllm_omni.diffusion.models.wan2_2.chunked_mp4 import (
+    resolve_wan_output_fps,
+    resolve_wan_preencode_batch_frames,
+    resolve_wan_preencode_mp4,
+    resolve_wan_video_codec_options,
+    wan_preencoded_mp4_payload,
+)
 from vllm_omni.diffusion.models.wan2_2.scheduling_wan_euler import WanEulerScheduler
 from vllm_omni.diffusion.models.wan2_2.wan2_2_transformer import WanSelfAttention, WanTransformer3DModel
 from vllm_omni.diffusion.offloader import OffloadPlan
 from vllm_omni.diffusion.postprocess import interpolate_video_tensor
 from vllm_omni.diffusion.profiler.diffusion_pipeline_profiler import DiffusionPipelineProfilerMixin
 from vllm_omni.diffusion.request import OmniDiffusionRequest
+from vllm_omni.diffusion.utils.chunked_video import decode_to_mp4
 from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch, split_diffusion_output_by_request
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams, OmniTextPrompt
 from vllm_omni.platforms import current_omni_platform
@@ -269,6 +277,9 @@ def post_process_func(
             output_type = sampling_params.output_type
         if output_type == "latent":
             return video
+        encoded = wan_preencoded_mp4_payload(video)
+        if encoded is not None:
+            return encoded
         video_metadata = {}
         if sampling_params is not None and getattr(sampling_params, "enable_frame_interpolation", False):
             video, multiplier = interpolate_video_tensor(
@@ -711,6 +722,8 @@ def forward(self, req: DiffusionRequestBatch) -> list[DiffusionOutput]:
             num_steps = 40 if common.num_inference_steps is None else common.num_inference_steps
 
         output_type = common.output_type or "np"
+        preencode_mp4 = resolve_wan_preencode_mp4(common, output_type=output_type)
+        preencode_batch_frames = resolve_wan_preencode_batch_frames(common) if preencode_mp4 else 17
         num_outputs_per_prompt = common.num_outputs_per_prompt or 1
         attention_kwargs: dict | None = None
 
@@ -965,27 +978,36 @@ def forward(self, req: DiffusionRequestBatch) -> list[DiffusionOutput]:
                 latents.device, latents.dtype
             )
             latents = latents / latents_std + latents_mean
-            decoded = self.vae.decode(latents, return_dict=False)[0]
-            # Distributed VAE decode uses broadcast_result=False, so only the
-            # output-owning rank receives the full [B, C, T, H, W] video; other
-            # ranks get an empty placeholder. Emit typed media only from the
-            # owning rank and keep the placeholder on the legacy output field, so
-            # the media batch-dimension check in split_diffusion_output_by_request
-            # does not trip on every non-owner rank.
-            if decoded.dim() == 5:
-                output = None
-                media = DiffusionMediaOutput(
-                    video=VideoMediaOutput(
-                        tensor=decoded,
-                        spec=VideoTensorSpec(
-                            layout=VideoTensorLayout.BCTHW,
-                            encoding=VideoTensorEncoding.NORMALIZED_FLOAT,
-                            value_range=VideoValueRange.NEGATIVE_ONE_TO_ONE,
-                        ),
-                    )
+            if preencode_mp4:
+                output = decode_to_mp4(
+                    self.vae,
+                    latents,
+                    fps=resolve_wan_output_fps(common),
+                    batch_frames=preencode_batch_frames,
+                    video_codec_options=resolve_wan_video_codec_options(common),
                 )
             else:
-                output = decoded
+                decoded = self.vae.decode(latents, return_dict=False)[0]
+                # Distributed VAE decode uses broadcast_result=False, so only the
+                # output-owning rank receives the full [B, C, T, H, W] video; other
+                # ranks get an empty placeholder. Emit typed media only from the
+                # owning rank and keep the placeholder on the legacy output field, so
+                # the media batch-dimension check in split_diffusion_output_by_request
+                # does not trip on every non-owner rank.
+                if decoded.dim() == 5:
+                    output = None
+                    media = DiffusionMediaOutput(
+                        video=VideoMediaOutput(
+                            tensor=decoded,
+                            spec=VideoTensorSpec(
+                                layout=VideoTensorLayout.BCTHW,
+                                encoding=VideoTensorEncoding.NORMALIZED_FLOAT,
+                                value_range=VideoValueRange.NEGATIVE_ONE_TO_ONE,
+                            ),
+                        )
+                    )
+                else:
+                    output = decoded
 
         if DEBUG_PERF:
             current_omni_platform.synchronize()
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
index 1a75c40da83..9f03f5853a0 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_i2v.py
@@ -31,6 +31,13 @@
 from vllm_omni.diffusion.models.interface import SupportImageInput, SupportsComponentDiscovery
 from vllm_omni.diffusion.models.progress_bar import ProgressBarMixin, _is_rank_zero
 from vllm_omni.diffusion.models.utils import _load_json
+from vllm_omni.diffusion.models.wan2_2.chunked_mp4 import (
+    resolve_wan_output_fps,
+    resolve_wan_preencode_batch_frames,
+    resolve_wan_preencode_mp4,
+    resolve_wan_video_codec_options,
+    wan_preencoded_mp4_payload,
+)
 from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import (
     _WAN_TEXT_ENCODER_OFFLOAD_PLAN,
     build_wan_scheduler,
@@ -46,6 +53,7 @@
 from vllm_omni.diffusion.postprocess import interpolate_video_tensor
 from vllm_omni.diffusion.profiler.diffusion_pipeline_profiler import DiffusionPipelineProfilerMixin
 from vllm_omni.diffusion.request import OmniDiffusionRequest
+from vllm_omni.diffusion.utils.chunked_video import decode_to_mp4
 from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch, split_diffusion_output_by_request
 from vllm_omni.inputs.data import OmniTextPrompt
 from vllm_omni.platforms import current_omni_platform
@@ -70,6 +78,9 @@ def post_process_func(
             output_type = sampling_params.output_type
         if output_type == "latent":
             return video
+        encoded = wan_preencoded_mp4_payload(video)
+        if encoded is not None:
+            return encoded
         video_metadata = {}
         if sampling_params is not None and getattr(sampling_params, "enable_frame_interpolation", False):
             video, multiplier = interpolate_video_tensor(
@@ -507,6 +518,8 @@ def forward(self, req: DiffusionRequestBatch) -> list[DiffusionOutput]:
         num_steps = 40 if common.num_inference_steps is None else common.num_inference_steps
 
         output_type = common.output_type or "np"
+        preencode_mp4 = resolve_wan_preencode_mp4(common, output_type=output_type)
+        preencode_batch_frames = resolve_wan_preencode_batch_frames(common) if preencode_mp4 else 17
         num_outputs_per_prompt = common.num_outputs_per_prompt or 1
         attention_kwargs: dict | None = None
 
@@ -736,7 +749,16 @@ def forward(self, req: DiffusionRequestBatch) -> list[DiffusionOutput]:
                 latents.device, latents.dtype
             )
             latents = latents / latents_std + latents_mean
-            output = self.vae.decode(latents, return_dict=False)[0]
+            if preencode_mp4:
+                output = decode_to_mp4(
+                    self.vae,
+                    latents,
+                    fps=resolve_wan_output_fps(common),
+                    batch_frames=preencode_batch_frames,
+                    video_codec_options=resolve_wan_video_codec_options(common),
+                )
+            else:
+                output = self.vae.decode(latents, return_dict=False)[0]
 
         if DEBUG_PERF:
             current_omni_platform.synchronize()
diff --git a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.py b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.py
index 1d28b425dbb..3cbd727a7ca 100644
--- a/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.py
+++ b/vllm_omni/diffusion/models/wan2_2/pipeline_wan2_2_s2v.py
@@ -33,6 +33,11 @@
 from vllm_omni.diffusion.models.interface import SupportAudioInput, SupportImageInput
 from vllm_omni.diffusion.models.progress_bar import ProgressBarMixin
 from vllm_omni.diffusion.models.schedulers import FlowUniPCMultistepScheduler
+from vllm_omni.diffusion.models.wan2_2.chunked_mp4 import (
+    resolve_wan_preencode_batch_frames,
+    resolve_wan_preencode_mp4,
+    resolve_wan_video_codec_options,
+)
 from vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2 import (
     load_transformer_config,
     load_wan_weights_with_optional_gate,
@@ -44,6 +49,7 @@
 from vllm_omni.diffusion.offloader.config import DIT_COMPONENT, selected_offload_components
 from vllm_omni.diffusion.profiler.diffusion_pipeline_profiler import DiffusionPipelineProfilerMixin
 from vllm_omni.diffusion.request import OmniDiffusionRequest
+from vllm_omni.diffusion.utils.chunked_video import ChunkedVideoMP4Session
 from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch, split_diffusion_output_by_request
 from vllm_omni.inputs.data import OmniTextPrompt
 from vllm_omni.platforms import current_omni_platform
@@ -63,6 +69,10 @@
 
 _AUDIO_VIDEO_RATE = 30
 
+# S2V generates at a fixed rate; the worker-side encoder and the post-process
+# payload must report the same one.
+S2V_OUTPUT_FPS = 16
+
 
 def _s2v_audio_condition_key(audio: str | np.ndarray | None) -> tuple[Any, ...]:
     if isinstance(audio, str):
@@ -280,6 +290,10 @@ def post_process_func(
         if output_type == "latent":
             return video
 
+        if isinstance(video, list) and all(isinstance(item, (bytes, bytearray, memoryview)) for item in video):
+            # The worker already muxed the audio into these bytes.
+            return {"video": [bytes(item) for item in video], "audio": None, "fps": S2V_OUTPUT_FPS}
+
         processed_video = video_processor.postprocess_video(video, output_type=output_type)
 
         if audio_waveform is not None:
@@ -287,7 +301,7 @@ def post_process_func(
                 "video": processed_video,
                 "audio": audio_waveform,
                 "audio_sample_rate": audio_sr,
-                "fps": 16,
+                "fps": S2V_OUTPUT_FPS,
             }
         return processed_video
 
@@ -1177,6 +1191,13 @@ def forward(
         )
         num_steps = common.num_inference_steps or num_inference_steps
         num_outputs_per_prompt = common.num_outputs_per_prompt or 1
+        # The request's output_type is what serving honours downstream; the keyword
+        # argument only carries a default for direct callers. Reading it here is what
+        # lets pre-encoding reject pil, pt, and latent instead of returning MP4 bytes
+        # to a caller that asked for frames.
+        output_type = common.output_type or output_type or "np"
+        preencode_mp4 = resolve_wan_preencode_mp4(common, output_type=output_type)
+        preencode_batch_frames = resolve_wan_preencode_batch_frames(common, default=1) if preencode_mp4 else 1
 
         if common.guidance_scale_provided:
             guidance_scale = common.guidance_scale
@@ -1315,170 +1336,207 @@ def forward(
 
         # ---- 6. Multi-clip autoregressive denoising ----
         clips: list[torch.Tensor] = []
+        # Encode each finished clip while the next one denoises, instead of
+        # concatenating the whole video first.
+        mp4_session = (
+            ChunkedVideoMP4Session(
+                value_range=self.vae.chunk_value_range,
+                audio_waveforms=[raw_audio_waveforms[index // num_outputs_per_prompt] for index in range(batch_size)],
+                audio_sample_rate=raw_audio_sr,
+                fps=S2V_OUTPUT_FPS,
+                batch_frames=preencode_batch_frames,
+                video_codec_options=resolve_wan_video_codec_options(common),
+            )
+            if preencode_mp4
+            else None
+        )
         # Keep a pixel-space buffer of the trailing motion_frames for the
         # autoregressive connection between clips.
         videos_last_frames = torch.zeros([batch_size, 3, motion_frames, height, width], dtype=dtype, device=device)
 
-        for r in range(num_repeat):
-            clip_generators = _make_clip_generators(seeds, generators, r, device)
-            # -- Noise --
-            if r == 0 and request_latents is not None:
-                latents = request_latents.to(device=device, dtype=dtype)
-            else:
-                latents = torch.stack(
-                    [
-                        self.prepare_latents(
-                            infer_frames=infer_frames,
-                            height=height,
-                            width=width,
-                            motion_frames=motion_frames,
-                            lat_motion_frames=lat_motion_frames,
-                            dtype=dtype,
-                            device=device,
-                            generator=clip_generator,
-                        )
-                        for clip_generator in clip_generators
-                    ]
+        try:
+            for r in range(num_repeat):
+                clip_generators = _make_clip_generators(seeds, generators, r, device)
+                # -- Noise --
+                if r == 0 and request_latents is not None:
+                    latents = request_latents.to(device=device, dtype=dtype)
+                else:
+                    latents = torch.stack(
+                        [
+                            self.prepare_latents(
+                                infer_frames=infer_frames,
+                                height=height,
+                                width=width,
+                                motion_frames=motion_frames,
+                                lat_motion_frames=lat_motion_frames,
+                                dtype=dtype,
+                                device=device,
+                                generator=clip_generator,
+                            )
+                            for clip_generator in clip_generators
+                        ]
+                    )
+
+                # -- Scheduler --
+                self.scheduler.set_timesteps(num_steps, device=device, shift=self._flow_shift)
+                timesteps = self.scheduler.timesteps
+                self._num_timesteps = len(timesteps)
+
+                # -- Slice audio for this clip --
+                left_idx = r * infer_frames
+                right_idx = left_idx + infer_frames
+                audio_input = audio_emb[..., left_idx:right_idx]
+
+                # -- Pose condition for this clip --
+                # Default: zero condition (no pose driving)
+                # Shape: [B, C=16, T, H, W]
+                lat_h = height // self.vae_scale_factor_spatial
+                lat_w = width // self.vae_scale_factor_spatial
+                lat_target_frames = (infer_frames + 3 + motion_frames) // 4 - lat_motion_frames
+                cond_latents = torch.zeros(
+                    [batch_size, 16, lat_target_frames, lat_h, lat_w], dtype=dtype, device=device
                 )
 
-            # -- Scheduler --
-            self.scheduler.set_timesteps(num_steps, device=device, shift=self._flow_shift)
-            timesteps = self.scheduler.timesteps
-            self._num_timesteps = len(timesteps)
-
-            # -- Slice audio for this clip --
-            left_idx = r * infer_frames
-            right_idx = left_idx + infer_frames
-            audio_input = audio_emb[..., left_idx:right_idx]
-
-            # -- Pose condition for this clip --
-            # Default: zero condition (no pose driving)
-            # Shape: [B, C=16, T, H, W]
-            lat_h = height // self.vae_scale_factor_spatial
-            lat_w = width // self.vae_scale_factor_spatial
-            lat_target_frames = (infer_frames + 3 + motion_frames) // 4 - lat_motion_frames
-            cond_latents = torch.zeros([batch_size, 16, lat_target_frames, lat_h, lat_w], dtype=dtype, device=device)
-
-            # -- Clone motion latents for this clip --
-            input_motion_latents = motion_latents.clone()
-
-            # Max sequence length for the transformer
-            max_seq_len = int(np.prod([lat_target_frames, lat_h, lat_w]) // 4)
-
-            # -- Precompute audio embeddings once per clip --
-            mf = [motion_frames, lat_motion_frames]
-            # When CPU offload is active the transformer lives on CPU until
-            # its __call__ hook fires.  encode_audio() bypasses __call__,
-            # so move the audio sub-module to GPU explicitly.
-            _audio_enc = getattr(self.transformer, "casual_audio_encoder", None)
-            _audio_on_cpu = _audio_enc is not None and next(_audio_enc.parameters()).device.type == "cpu"
-            if _audio_on_cpu:
-                _audio_enc.to(device)
-            param_dtype = next(self.transformer.parameters()).dtype
-            with torch.amp.autocast(device.type, dtype=param_dtype):
-                positive_audio_emb = self.transformer.encode_audio(audio_input, mf)
-            do_true_cfg = self.do_classifier_free_guidance and negative_prompt_embeds is not None
-            if do_true_cfg:
+                # -- Clone motion latents for this clip --
+                input_motion_latents = motion_latents.clone()
+
+                # Max sequence length for the transformer
+                max_seq_len = int(np.prod([lat_target_frames, lat_h, lat_w]) // 4)
+
+                # -- Precompute audio embeddings once per clip --
+                mf = [motion_frames, lat_motion_frames]
+                # When CPU offload is active the transformer lives on CPU until
+                # its __call__ hook fires.  encode_audio() bypasses __call__,
+                # so move the audio sub-module to GPU explicitly.
+                _audio_enc = getattr(self.transformer, "casual_audio_encoder", None)
+                _audio_on_cpu = _audio_enc is not None and next(_audio_enc.parameters()).device.type == "cpu"
+                if _audio_on_cpu:
+                    _audio_enc.to(device)
+                param_dtype = next(self.transformer.parameters()).dtype
                 with torch.amp.autocast(device.type, dtype=param_dtype):
-                    negative_audio_emb = self.transformer.encode_audio(0.0 * audio_input, mf)
-            else:
-                negative_audio_emb = None
-            if _audio_on_cpu:
-                _audio_enc.to("cpu")
-
-            # -- Denoising loop --
-            latents = self.diffuse(
-                latents=latents,
-                timesteps=timesteps,
-                prompt_embeds=prompt_embeds,
-                negative_prompt_embeds=negative_prompt_embeds,
-                guidance_scale=guidance_scale,
-                clip_generator=clip_generators,
-                dtype=dtype,
-                device=device,
-                max_seq_len=max_seq_len,
-                cond_latents=cond_latents,
-                input_motion_latents=input_motion_latents,
-                ref_latents=ref_latents,
-                motion_frames=mf,
-                drop_first_motion=drop_first_motion and r == 0,
-                positive_audio_emb=positive_audio_emb,
-                negative_audio_emb=negative_audio_emb,
-            )
-
-            # ---- Decode this clip ----
-            if self._should_release_dit_before_decode():
-                self.transformer.to("cpu")
-                current_omni_platform.empty_cache()
-
-            if not (drop_first_motion and r == 0):
-                decode_latents = torch.cat([motion_latents, latents], dim=2)
-            else:
-                decode_latents = torch.cat([ref_latents, latents], dim=2)
-
-            decode_latents = self._denormalize_latents(decode_latents)
-            decode_latents = decode_latents.to(self.vae.dtype)
-            clip_video = self.vae.decode(decode_latents, return_dict=False)[0]  # [1, C, T, H, W]
-
-            # Handle VAE patch parallel: only rank 0 gets result, broadcast to all ranks
-            # This is needed for S2V's autoregressive loop where all ranks need the decoded frames
-            if clip_video.numel() == 0:
-                # Non-rank0 received empty tensor from patch parallel decode
-                # Use the same broadcast mechanism as the VAE patch parallel code
-                import torch.distributed as dist
-
-                total_frames = decode_latents.shape[2]
-
-                # Create buffer for broadcast
-                clip_video = torch.empty(
-                    (batch_size, 3, total_frames, height, width),
-                    device=decode_latents.device,
-                    dtype=decode_latents.dtype,
+                    positive_audio_emb = self.transformer.encode_audio(audio_input, mf)
+                do_true_cfg = self.do_classifier_free_guidance and negative_prompt_embeds is not None
+                if do_true_cfg:
+                    with torch.amp.autocast(device.type, dtype=param_dtype):
+                        negative_audio_emb = self.transformer.encode_audio(0.0 * audio_input, mf)
+                else:
+                    negative_audio_emb = None
+                if _audio_on_cpu:
+                    _audio_enc.to("cpu")
+
+                # -- Denoising loop --
+                latents = self.diffuse(
+                    latents=latents,
+                    timesteps=timesteps,
+                    prompt_embeds=prompt_embeds,
+                    negative_prompt_embeds=negative_prompt_embeds,
+                    guidance_scale=guidance_scale,
+                    clip_generator=clip_generators,
+                    dtype=dtype,
+                    device=device,
+                    max_seq_len=max_seq_len,
+                    cond_latents=cond_latents,
+                    input_motion_latents=input_motion_latents,
+                    ref_latents=ref_latents,
+                    motion_frames=mf,
+                    drop_first_motion=drop_first_motion and r == 0,
+                    positive_audio_emb=positive_audio_emb,
+                    negative_audio_emb=negative_audio_emb,
                 )
 
-                # Get the VAE's patch parallel group (same one used in decode)
-                vae_pp_group = getattr(self.vae, "_vae_pp_group", None)
-                if vae_pp_group is not None:
-                    # Broadcast using the same group as VAE patch parallel
-                    dist.broadcast(clip_video, src=0, group=vae_pp_group)
-
-            # Trim to the infer_frames of interest
-            clip_video = clip_video[:, :, -infer_frames:]
-            if drop_first_motion and r == 0:
-                # Drop the first 3 frames (artifact from ref_latents prepend)
-                clip_video = clip_video[:, :, 3:]
-
-            # ---- Update motion for next clip (autoregressive) ----
-            overlap_frames_num = min(motion_frames, clip_video.shape[2])
-            videos_last_frames = torch.cat(
-                [videos_last_frames[:, :, overlap_frames_num:], clip_video[:, :, -overlap_frames_num:]],
-                dim=2,
-            )
-            videos_last_frames = videos_last_frames.to(dtype=dtype, device=device)
-            # Only prepare motion latents if there's another clip coming
-            if r < num_repeat - 1:
-                motion_latents = self.prepare_motion_latents(videos_last_frames, device=device).to(dtype=dtype)
-
-            clips.append(clip_video.cpu())
+                # ---- Decode this clip ----
+                if self._should_release_dit_before_decode():
+                    self.transformer.to("cpu")
+                    current_omni_platform.empty_cache()
 
-            # Free VRAM between clips
-            if current_omni_platform.is_available():
-                current_omni_platform.empty_cache()
+                if not (drop_first_motion and r == 0):
+                    decode_latents = torch.cat([motion_latents, latents], dim=2)
+                else:
+                    decode_latents = torch.cat([ref_latents, latents], dim=2)
+
+                decode_latents = self._denormalize_latents(decode_latents)
+                decode_latents = decode_latents.to(self.vae.dtype)
+                clip_video = self.vae.decode(decode_latents, return_dict=False)[0]  # [1, C, T, H, W]
+                # Under VAE patch parallelism only the output-owning rank decodes a
+                # real clip; peers get an empty placeholder filled by the broadcast.
+                owns_output = clip_video.numel() > 0
+
+                # Handle VAE patch parallel: only rank 0 gets result, broadcast to all ranks
+                # This is needed for S2V's autoregressive loop where all ranks need the decoded frames
+                if clip_video.numel() == 0:
+                    # Non-rank0 received empty tensor from patch parallel decode
+                    # Use the same broadcast mechanism as the VAE patch parallel code
+                    import torch.distributed as dist
+
+                    total_frames = decode_latents.shape[2]
+
+                    # Create buffer for broadcast
+                    clip_video = torch.empty(
+                        (batch_size, 3, total_frames, height, width),
+                        device=decode_latents.device,
+                        dtype=decode_latents.dtype,
+                    )
+
+                    # Get the VAE's patch parallel group (same one used in decode)
+                    vae_pp_group = getattr(self.vae, "_vae_pp_group", None)
+                    if vae_pp_group is not None:
+                        # Broadcast using the same group as VAE patch parallel
+                        dist.broadcast(clip_video, src=0, group=vae_pp_group)
+
+                # Trim to the infer_frames of interest
+                clip_video = clip_video[:, :, -infer_frames:]
+                if drop_first_motion and r == 0:
+                    # Drop the first 3 frames (artifact from ref_latents prepend)
+                    clip_video = clip_video[:, :, 3:]
+
+                # ---- Update motion for next clip (autoregressive) ----
+                overlap_frames_num = min(motion_frames, clip_video.shape[2])
+                videos_last_frames = torch.cat(
+                    [videos_last_frames[:, :, overlap_frames_num:], clip_video[:, :, -overlap_frames_num:]],
+                    dim=2,
+                )
+                videos_last_frames = videos_last_frames.to(dtype=dtype, device=device)
+                # Only prepare motion latents if there's another clip coming
+                if r < num_repeat - 1:
+                    motion_latents = self.prepare_motion_latents(videos_last_frames, device=device).to(dtype=dtype)
+
+                if mp4_session is not None:
+                    # Every rank needs the frames for the motion loop above, but the
+                    # executor keeps only the owner's response, so a peer skips the
+                    # encode and finishes with no containers, like T2V's non-owners.
+                    if owns_output:
+                        mp4_session.push(clip_video)
+                else:
+                    clips.append(clip_video.cpu())
 
-        # ---- Concatenate all clips ----
-        output = torch.cat(clips, dim=2)  # [B, C, T_total, H, W]
+                # Free VRAM between clips
+                if current_omni_platform.is_available():
+                    current_omni_platform.empty_cache()
 
-        outputs = split_diffusion_output_by_request(
-            DiffusionOutput(
-                output=output,
-                stage_durations=self.stage_durations if hasattr(self, "stage_durations") else None,
-            ),
-            req,
-            num_outputs_per_prompt=num_outputs_per_prompt,
-        )
-        for request_output, raw_audio_waveform in zip(outputs, raw_audio_waveforms):
-            request_output.output = (request_output.output, raw_audio_waveform, raw_audio_sr)
-        return outputs
+            # ---- Assemble the output ----
+            if mp4_session is not None:
+                output = mp4_session.finish()  # one progressive MP4 per batch entry
+            else:
+                output = torch.cat(clips, dim=2)  # [B, C, T_total, H, W]
+
+            outputs = split_diffusion_output_by_request(
+                DiffusionOutput(
+                    output=output,
+                    stage_durations=self.stage_durations if hasattr(self, "stage_durations") else None,
+                ),
+                req,
+                num_outputs_per_prompt=num_outputs_per_prompt,
+            )
+            if mp4_session is not None:
+                # The waveform is already muxed into each container.
+                return outputs
+            for request_output, raw_audio_waveform in zip(outputs, raw_audio_waveforms):
+                request_output.output = (request_output.output, raw_audio_waveform, raw_audio_sr)
+            return outputs
+        except BaseException:
+            if mp4_session is not None:
+                mp4_session.abort()
+            raise
 
     def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
         return load_wan_weights_with_optional_gate(self, weights)
diff --git a/vllm_omni/diffusion/utils/chunked_video.py b/vllm_omni/diffusion/utils/chunked_video.py
new file mode 100644
index 00000000000..79ceeab8c86
--- /dev/null
+++ b/vllm_omni/diffusion/utils/chunked_video.py
@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Turn committed VAE chunks into MP4 bytes without materializing the video.
+
+The producer side is the model's business: a Wan VAE walks a causal
+frame-by-frame loop, a MiniMax-H3 VAE walks overlapping clips, and Wan S2V
+decodes one clip per autoregressive iteration. What happens to a chunk once it
+is final is not: every one of them quantizes to uint8, moves to the host once,
+and lands in a bounded encoder. That consumer lives here so a model only has to
+publish finished chunks -- :class:`SupportsChunkedVAEDecode` for producers that
+can be driven, :class:`ChunkedVideoMP4Session` for producers that drive
+themselves.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import torch
+
+from vllm_omni.diffusion.models.interface import supports_chunked_vae_decode
+from vllm_omni.diffusion.utils.media_utils import ChunkedMP4Encoder
+
+
+def chunk_to_uint8_frames(chunk: torch.Tensor, value_range: tuple[float, float]) -> np.ndarray:
+    """Quantize a ``BCTHW`` chunk to ``BTHWC`` uint8, transferring once.
+
+    ``value_range`` is the interval the producer publishes, which differs per
+    checkpoint (see ``SupportsChunkedVAEDecode.chunk_value_range``). Quantizing
+    on the accelerator means one transfer moves the final bytes rather than
+    float frames.
+
+    That transfer is synchronous: ``.cpu()`` blocks inside the producer's chunk
+    callback, so what overlaps the remaining decode today is the CPU H.264
+    encode of earlier chunks, not this copy. Splitting device preparation,
+    device-to-host copy, and encode into three independently scheduled stages --
+    a pool of reusable pinned host slots with non-blocking copies on a dedicated
+    stream, leases released by the encoder -- fits behind this same callback
+    contract, but is not implemented here.
+    """
+    low, high = float(value_range[0]), float(value_range[1])
+    if high <= low:
+        raise ValueError(f"value_range must be increasing, got {value_range!r}")
+    scale = 255.0 / (high - low)
+    frames = chunk.clamp(low, high).sub(low).mul(scale).round().to(torch.uint8)
+    return frames.permute(0, 2, 3, 4, 1).cpu().numpy()
+
+
+class ChunkedVideoMP4Session:
+    """Encode committed video chunks into one progressive MP4 per batch entry.
+
+    Push finished ``BCTHW`` chunks as the producer commits them; each batch
+    entry gets its own bounded encoder, so host transfer and H.264 encoding
+    overlap whatever the producer is still decoding.
+
+    ``audio_waveforms`` holds one waveform per batch entry (``None`` for a
+    silent entry), so a caller with several outputs per prompt repeats a
+    request's waveform across its entries. ``batch_frames`` coalesces transfers
+    for producers that publish finer than a transfer is worth; ``crop`` trims
+    the decoder's padding to the requested output size.
+    """
+
+    def __init__(
+        self,
+        *,
+        value_range: tuple[float, float],
+        fps: float,
+        audio_waveforms: list[np.ndarray | None] | None = None,
+        audio_sample_rate: int | None = None,
+        batch_frames: int = 1,
+        max_pending: int = 2,
+        video_codec_options: dict[str, str] | None = None,
+        crop: tuple[int, int] | None = None,
+    ) -> None:
+        if batch_frames <= 0:
+            raise ValueError("batch_frames must be positive")
+        self._value_range = value_range
+        self._fps = fps
+        self._audio_waveforms = audio_waveforms
+        self._audio_sample_rate = audio_sample_rate
+        self._batch_frames = batch_frames
+        self._max_pending = max_pending
+        self._video_codec_options = video_codec_options
+        self._crop = crop
+        self._encoders: list[ChunkedMP4Encoder] = []
+        self._pending: list[torch.Tensor] = []
+        self._pending_frames = 0
+
+    def push(self, chunk: torch.Tensor) -> None:
+        """Queue one committed ``BCTHW`` chunk."""
+        if self._crop is not None:
+            height, width = self._crop
+            chunk = chunk[..., :height, :width]
+        self._pending.append(chunk)
+        self._pending_frames += int(chunk.shape[2])
+        if self._pending_frames >= self._batch_frames:
+            self._flush()
+
+    def finish(self) -> list[bytes]:
+        """Flush what is pending and return one MP4 per batch entry."""
+        self._flush()
+        return [encoder.finish() for encoder in self._encoders]
+
+    def abort(self) -> None:
+        for encoder in self._encoders:
+            encoder.abort()
+
+    def _flush(self) -> None:
+        if not self._pending:
+            return
+        frames = chunk_to_uint8_frames(torch.cat(self._pending, dim=2), self._value_range)
+        if not self._encoders:
+            self._encoders = [
+                ChunkedMP4Encoder(
+                    width=frames.shape[3],
+                    height=frames.shape[2],
+                    fps=self._fps,
+                    audio_waveform=self._waveform_for(index, frames.shape[0]),
+                    audio_sample_rate=self._audio_sample_rate,
+                    max_pending=self._max_pending,
+                    video_codec_options=self._video_codec_options,
+                )
+                for index in range(frames.shape[0])
+            ]
+        for index, encoder in enumerate(self._encoders):
+            encoder.push(np.ascontiguousarray(frames[index]))
+        self._pending.clear()
+        self._pending_frames = 0
+
+    def _waveform_for(self, index: int, batch_size: int) -> np.ndarray | None:
+        if self._audio_waveforms is None:
+            return None
+        if len(self._audio_waveforms) != batch_size:
+            raise ValueError(
+                f"expected one audio waveform per batch entry, got "
+                f"{len(self._audio_waveforms)} for {batch_size} entries"
+            )
+        return self._audio_waveforms[index]
+
+
+def decode_to_mp4(vae: Any, z: torch.Tensor, **session_kwargs: Any) -> list[bytes]:
+    """Decode ``z`` straight into one progressive MP4 per batch entry.
+
+    Drives a VAE that declares :class:`SupportsChunkedVAEDecode`, so host
+    transfer and encoding overlap the remaining decode and the full video is
+    never materialized. Ranks that own no decode output receive no chunks and
+    get an empty list, matching the empty tensor the full-decode path returns
+    there.
+    """
+    if not supports_chunked_vae_decode(vae):
+        raise TypeError(f"{type(vae).__name__} does not expose the chunked VAE decode capability")
+
+    session = ChunkedVideoMP4Session(value_range=vae.chunk_value_range, **session_kwargs)
+    try:
+        vae.decode_with_chunks(z, on_chunk=session.push)
+        return session.finish()
+    except BaseException:
+        session.abort()
+        raise
diff --git a/vllm_omni/diffusion/utils/media_utils.py b/vllm_omni/diffusion/utils/media_utils.py
index 99d20a0af57..b2141400c79 100644
--- a/vllm_omni/diffusion/utils/media_utils.py
+++ b/vllm_omni/diffusion/utils/media_utils.py
@@ -51,8 +51,11 @@ def _validate_video_chunk(chunk: np.ndarray, *, width: int, height: int) -> None
 class ChunkedMP4Encoder:
     """Encode temporal video chunks while the producer is still decoding.
 
-    A bounded queue and one muxing worker provide ordered backpressure while
-    keeping host memory bounded by ``max_pending`` chunks. Chunks use the same
+    A bounded queue and one muxing worker provide ordered backpressure. What
+    that bounds is pending raw-frame memory: at most ``max_pending`` chunks wait
+    to be encoded, so the bound is in chunks rather than bytes and a taller
+    frame or a longer chunk raises it. The muxed container is not bounded -- it
+    accumulates in memory and grows with output duration. Chunks use the same
     ``(T, H, W, 3)`` uint8 contract as :func:`mux_video_audio_bytes`.
     """
 

From 97912de8d8b9b2ad8877cea5d356c4551686ab7f Mon Sep 17 00:00:00 2001
From: dongbo910220 <32610838+dongbo910220@users.noreply.github.com>
Date: Fri, 18 Sep 2026 02:27:57 +0800
Subject: [PATCH 072/105] [Kernel] Fuse LongCat paired Q/K RoPE (#7500)

Signed-off-by: dongbo910220 <1275604947@qq.com>
---
 tests/diffusion/layers/test_fused_qk_rope.py  | 125 +++++++++
 .../test_longcat_image_transformer.py         | 239 +++++++++++++++++
 vllm_omni/diffusion/layers/fused_qk_rope.py   | 251 ++++++++++++++++++
 .../longcat_image_transformer.py              | 199 ++++++++++++--
 4 files changed, 794 insertions(+), 20 deletions(-)
 create mode 100644 tests/diffusion/layers/test_fused_qk_rope.py
 create mode 100644 tests/diffusion/models/longcat_image/test_longcat_image_transformer.py
 create mode 100644 vllm_omni/diffusion/layers/fused_qk_rope.py

diff --git a/tests/diffusion/layers/test_fused_qk_rope.py b/tests/diffusion/layers/test_fused_qk_rope.py
new file mode 100644
index 00000000000..c37075ba665
--- /dev/null
+++ b/tests/diffusion/layers/test_fused_qk_rope.py
@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import pytest
+import torch
+from diffusers.models.embeddings import apply_rotary_emb
+from vllm.triton_utils import HAS_TRITON
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion]
+
+
+def test_fused_qk_rope_fake_and_cpu_eligibility():
+    from vllm_omni.diffusion.layers.fused_qk_rope import (
+        _fused_qk_rope_fake,
+        fused_qk_rope,
+        fused_qk_rope_supported,
+    )
+
+    q = torch.randn(2, 3, 4, 8, dtype=torch.bfloat16)
+    k = torch.randn_like(q)
+    cos = torch.randn(3, 8)
+    sin = torch.randn_like(cos)
+
+    fake_q, fake_k = _fused_qk_rope_fake(q, k, cos, sin)
+    assert fake_q.shape == q.shape and fake_q.dtype == q.dtype
+    assert fake_k.shape == k.shape and fake_k.dtype == k.dtype
+    assert not fused_qk_rope_supported(q, k, cos, sin)
+    with pytest.raises(ValueError, match="contiguous CUDA BF16"):
+        fused_qk_rope(q, k, cos, sin)
+
+
+def _cuda_inputs(batch: int, sequence: int, heads: int = 24, head_dim: int = 128):
+    q = torch.randn(batch, sequence, heads, head_dim, device="cuda", dtype=torch.bfloat16)
+    k = torch.randn_like(q)
+    # Deliberately do not repeat adjacent table columns.  Diffusers consumes
+    # full-width tables, so even and odd outputs may use different values.
+    cos = torch.randn(sequence, head_dim, device="cuda", dtype=torch.float32)
+    sin = torch.randn_like(cos)
+    return q, k, cos, sin
+
+
+def _reference(q, k, cos, sin):
+    rotary_emb = (cos, sin)
+    return (
+        apply_rotary_emb(q, rotary_emb, sequence_dim=1),
+        apply_rotary_emb(k, rotary_emb, sequence_dim=1),
+    )
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+@pytest.mark.parametrize("sequence", [512, 4096, 4608])
+def test_fused_qk_rope_is_bit_exact_at_longcat_production_shapes(sequence):
+    from vllm_omni.diffusion.layers.fused_qk_rope import _launch_fused_qk_rope, fused_qk_rope
+
+    torch.manual_seed(sequence)
+    with torch.inference_mode():
+        q, k, cos, sin = _cuda_inputs(1, sequence)
+        expected = _reference(q, k, cos, sin)
+        for actual in (
+            _launch_fused_qk_rope(q, k, cos, sin),
+            fused_qk_rope(q, k, cos, sin),
+        ):
+            assert torch.equal(actual[0], expected[0])
+            assert torch.equal(actual[1], expected[1])
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+def test_fused_qk_rope_is_bit_exact_for_batch_and_full_width_odd_even_tables():
+    from vllm_omni.diffusion.layers.fused_qk_rope import fused_qk_rope
+
+    torch.manual_seed(11)
+    with torch.inference_mode():
+        q, k, cos, sin = _cuda_inputs(2, 17, heads=3)
+        assert not torch.equal(cos[:, ::2], cos[:, 1::2])
+        assert not torch.equal(sin[:, ::2], sin[:, 1::2])
+        expected = _reference(q, k, cos, sin)
+        actual = fused_qk_rope(q, k, cos, sin)
+
+    assert torch.equal(actual[0], expected[0])
+    assert torch.equal(actual[1], expected[1])
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+def test_fused_qk_rope_rejects_noncontiguous_and_non_fp32_tables():
+    from vllm_omni.diffusion.layers.fused_qk_rope import fused_qk_rope_supported
+
+    q, k, cos, sin = _cuda_inputs(1, 8, heads=2)
+    q_noncontiguous = torch.randn(1, 8, 2, 256, device="cuda", dtype=torch.bfloat16)[..., ::2]
+    k_noncontiguous = torch.randn_like(q_noncontiguous)
+    cos_noncontiguous = torch.randn(8, 256, device="cuda")[:, ::2]
+    sin_noncontiguous = torch.randn(8, 256, device="cuda")[:, ::2]
+    with torch.inference_mode():
+        assert fused_qk_rope_supported(q, k, cos, sin)
+        assert not fused_qk_rope_supported(q_noncontiguous, k_noncontiguous, cos, sin)
+        assert not fused_qk_rope_supported(q, k, cos_noncontiguous, sin_noncontiguous)
+        assert not fused_qk_rope_supported(q, k, cos.to(torch.bfloat16), sin.to(torch.bfloat16))
+
+        q_wide = torch.randn(1, 8, 2, 256, device="cuda", dtype=torch.bfloat16)
+        k_wide = torch.randn_like(q_wide)
+        cos_wide = torch.randn(8, 256, device="cuda")
+        sin_wide = torch.randn_like(cos_wide)
+        assert not fused_qk_rope_supported(q_wide, k_wide, cos_wide, sin_wide)
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+def test_fused_qk_rope_custom_op_has_fullgraph_fake():
+    from vllm_omni.diffusion.layers.fused_qk_rope import fused_qk_rope
+
+    torch.manual_seed(29)
+    with torch.inference_mode():
+        q, k, cos, sin = _cuda_inputs(1, 19, heads=3)
+        expected = _reference(q, k, cos, sin)
+        compiled = torch.compile(fused_qk_rope, dynamic=True, fullgraph=True)
+        actual = compiled(q, k, cos, sin)
+
+    assert torch.equal(actual[0], expected[0])
+    assert torch.equal(actual[1], expected[1])
diff --git a/tests/diffusion/models/longcat_image/test_longcat_image_transformer.py b/tests/diffusion/models/longcat_image/test_longcat_image_transformer.py
new file mode 100644
index 00000000000..51cedbb8f00
--- /dev/null
+++ b/tests/diffusion/models/longcat_image/test_longcat_image_transformer.py
@@ -0,0 +1,239 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from contextlib import nullcontext
+from types import SimpleNamespace
+
+import pytest
+import torch
+from diffusers.models.embeddings import apply_rotary_emb
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
+
+
+@pytest.fixture(autouse=True)
+def _clear_qk_rope_signature_caches():
+    from vllm_omni.diffusion.models.longcat_image import longcat_image_transformer as longcat
+
+    longcat._FAILED_QK_ROPE_SIGNATURES.clear()
+    yield
+    longcat._FAILED_QK_ROPE_SIGNATURES.clear()
+
+
+def _inputs(sequence: int = 5, head_dim: int = 8):
+    q = torch.randn(2, sequence, 3, head_dim, dtype=torch.bfloat16)
+    k = torch.randn_like(q)
+    cos = torch.randn(sequence, head_dim)
+    sin = torch.randn_like(cos)
+    return q, k, (cos, sin)
+
+
+def _reference(q, k, rotary_emb):
+    return (
+        apply_rotary_emb(q, rotary_emb, sequence_dim=1),
+        apply_rotary_emb(k, rotary_emb, sequence_dim=1),
+    )
+
+
+def test_prepare_rotary_emb_resolves_threshold_once_only_when_enabled(monkeypatch):
+    from vllm_omni.diffusion.models.longcat_image import longcat_image_transformer as longcat
+
+    calls = 0
+
+    def resolve(default):
+        nonlocal calls
+        calls += 1
+        assert default == 512
+        return 37
+
+    monkeypatch.setattr(longcat, "fused_qk_norm_rope_min_tokens", resolve)
+    txt_cos, txt_sin = torch.randn(2, 8), torch.randn(2, 8)
+    img_cos, img_sin = torch.randn(3, 8), torch.randn(3, 8)
+    native = longcat._prepare_rotary_emb(txt_cos, txt_sin, img_cos, img_sin, enable_fusion=False)
+    fused = longcat._prepare_rotary_emb(txt_cos, txt_sin, img_cos, img_sin, enable_fusion=True)
+
+    assert calls == 1
+    assert len(native) == 2
+    assert len(fused) == 3 and fused[2] == 37
+    assert torch.equal(native[0], fused[0])
+    assert torch.equal(native[1], fused[1])
+
+
+@pytest.mark.parametrize(
+    ("mode", "sp_size"),
+    [
+        ("unsupported", 1),
+        ("compile", 1),
+        ("grad", 1),
+        ("capture", 1),
+        ("sequence_parallel", 2),
+        ("below_threshold", 1),
+    ],
+)
+def test_qk_rope_non_eager_modes_use_exact_original_path(monkeypatch, mode, sp_size):
+    from vllm_omni.diffusion.models.longcat_image import longcat_image_transformer as longcat
+
+    torch.manual_seed(1)
+    q, k, rotary_emb = _inputs()
+    expected = _reference(q, k, rotary_emb)
+    monkeypatch.setattr(torch.compiler, "is_compiling", lambda: mode == "compile")
+    monkeypatch.setattr(torch.cuda, "is_current_stream_capturing", lambda: mode == "capture")
+    monkeypatch.setattr(longcat, "fused_qk_rope_supported", lambda *args: mode != "unsupported")
+    monkeypatch.setattr(
+        longcat,
+        "fused_qk_rope",
+        lambda *args: (_ for _ in ()).throw(AssertionError("fallback called fused op")),
+    )
+
+    context = nullcontext() if mode == "grad" else torch.no_grad()
+    min_tokens = q.shape[0] * q.shape[1] + 1 if mode == "below_threshold" else 0
+    with context:
+        actual = longcat._apply_qk_rope(q, k, rotary_emb, sp_size, min_tokens)
+
+    assert torch.equal(actual[0], expected[0])
+    assert torch.equal(actual[1], expected[1])
+
+
+def test_qk_rope_eligible_path_skips_runtime_parity_check(monkeypatch):
+    from vllm_omni.diffusion.models.longcat_image import longcat_image_transformer as longcat
+
+    torch.manual_seed(2)
+    monkeypatch.setattr(torch.compiler, "is_compiling", lambda: False)
+    monkeypatch.setattr(torch.cuda, "is_current_stream_capturing", lambda: False)
+    monkeypatch.setattr(longcat, "fused_qk_rope_supported", lambda *args: True)
+    fused_calls = 0
+
+    def fused(query, key, cos, sin):
+        nonlocal fused_calls
+        fused_calls += 1
+        return query + 1, key + 2
+
+    monkeypatch.setattr(
+        longcat,
+        "_apply_qk_rope_reference",
+        lambda *args: (_ for _ in ()).throw(AssertionError("eligible path ran the native parity check")),
+    )
+    monkeypatch.setattr(longcat, "fused_qk_rope", fused)
+
+    with torch.no_grad():
+        q, k, rotary_emb = _inputs()
+        actual = longcat._apply_qk_rope(q, k, rotary_emb, 1, 0)
+
+    assert fused_calls == 1
+    assert torch.equal(actual[0], q + 1)
+    assert torch.equal(actual[1], k + 2)
+
+
+def test_qk_rope_launch_failure_permanently_falls_back(monkeypatch):
+    from vllm_omni.diffusion.models.longcat_image import longcat_image_transformer as longcat
+
+    torch.manual_seed(3)
+    monkeypatch.setattr(torch.compiler, "is_compiling", lambda: False)
+    monkeypatch.setattr(torch.cuda, "is_current_stream_capturing", lambda: False)
+    monkeypatch.setattr(longcat, "fused_qk_rope_supported", lambda *args: True)
+    fused_calls = 0
+
+    def broken_fused(query, key, cos, sin):
+        nonlocal fused_calls
+        fused_calls += 1
+        raise RuntimeError("kernel failed")
+
+    monkeypatch.setattr(longcat, "fused_qk_rope", broken_fused)
+    q, k, rotary_emb = _inputs()
+    expected = _reference(q, k, rotary_emb)
+    with torch.no_grad():
+        first = longcat._apply_qk_rope(q, k, rotary_emb, 1, 0)
+        second = longcat._apply_qk_rope(q, k, rotary_emb, 1, 0)
+
+    assert fused_calls == 1
+    assert len(longcat._FAILED_QK_ROPE_SIGNATURES) == 1
+    for actual in (first, second):
+        assert torch.equal(actual[0], expected[0])
+        assert torch.equal(actual[1], expected[1])
+
+
+def test_failed_qk_rope_signature_cache_is_bounded():
+    from vllm_omni.diffusion.models.longcat_image import longcat_image_transformer as longcat
+
+    for index in range(longcat._FAILED_QK_ROPE_SIGNATURES_MAX_SIZE + 1):
+        longcat._record_failed_qk_rope_signature((index,))
+
+    assert len(longcat._FAILED_QK_ROPE_SIGNATURES) == longcat._FAILED_QK_ROPE_SIGNATURES_MAX_SIZE
+    assert (0,) not in longcat._FAILED_QK_ROPE_SIGNATURES
+    assert (longcat._FAILED_QK_ROPE_SIGNATURES_MAX_SIZE,) in longcat._FAILED_QK_ROPE_SIGNATURES
+
+
+class _FakeQKV(torch.nn.Module):
+    def __init__(self, heads: int, head_dim: int) -> None:
+        super().__init__()
+        self.num_heads = heads
+        self.num_kv_heads = heads
+        self.width = heads * head_dim
+
+    def forward(self, x):
+        return torch.cat((x, x + 1, x + 2), dim=-1), None
+
+
+class _AddNorm(torch.nn.Module):
+    def __init__(self, value: float) -> None:
+        super().__init__()
+        self.value = value
+
+    def forward(self, x):
+        return x + self.value
+
+
+class _CaptureAttention(torch.nn.Module):
+    def forward(self, query, key, value, metadata=None):
+        del key, value, metadata
+        return query
+
+
+class _PassthroughLinear(torch.nn.Module):
+    def forward(self, x):
+        return x, None
+
+
+def test_dual_attention_keeps_native_norm_and_text_image_concat_order(monkeypatch):
+    from vllm_omni.diffusion.models.longcat_image import longcat_image_transformer as longcat
+
+    attention = longcat.LongCatImageAttention.__new__(longcat.LongCatImageAttention)
+    torch.nn.Module.__init__(attention)
+    attention.parallel_config = SimpleNamespace(sequence_parallel_size=1)
+    attention.head_dim = 4
+    attention.added_kv_proj_dim = 8
+    attention.to_qkv = _FakeQKV(2, 4)
+    attention.add_kv_proj = _FakeQKV(2, 4)
+    attention.norm_q = _AddNorm(10)
+    attention.norm_k = _AddNorm(20)
+    attention.norm_added_q = _AddNorm(100)
+    attention.norm_added_k = _AddNorm(200)
+    attention.attn = _CaptureAttention()
+    attention.to_out = _PassthroughLinear()
+    attention.to_add_out = _PassthroughLinear()
+
+    captured = []
+
+    def paired(query, key, rotary_emb, sp_size, min_tokens):
+        captured.append((query.clone(), key.clone(), rotary_emb, sp_size, min_tokens))
+        return query, key
+
+    monkeypatch.setattr(longcat, "_apply_qk_rope", paired)
+    image = torch.randn(1, 3, 8)
+    text = torch.randn(1, 2, 8)
+    rotary_pair = (torch.randn(5, 4), torch.randn(5, 4))
+    rotary_emb = (*rotary_pair, 0)
+    image_out, text_out = attention(image, text, rotary_emb)
+
+    image_q = image.unflatten(-1, (2, 4))
+    text_q = text.unflatten(-1, (2, 4))
+    expected_q = torch.cat((text_q + 100, image_q + 10), dim=1)
+    expected_k = torch.cat((text_q + 1 + 200, image_q + 1 + 20), dim=1)
+    assert len(captured) == 1
+    assert torch.equal(captured[0][0], expected_q)
+    assert torch.equal(captured[0][1], expected_k)
+    assert captured[0][2][0] is rotary_pair[0]
+    assert captured[0][2][1] is rotary_pair[1]
+    assert captured[0][3:] == (1, 0)
+    assert image_out.shape == image.shape
+    assert text_out.shape == text.shape
diff --git a/vllm_omni/diffusion/layers/fused_qk_rope.py b/vllm_omni/diffusion/layers/fused_qk_rope.py
new file mode 100644
index 00000000000..95b24451b12
--- /dev/null
+++ b/vllm_omni/diffusion/layers/fused_qk_rope.py
@@ -0,0 +1,251 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Bit-exact paired Q/K full-width interleaved RoPE for CUDA.
+
+The operator accepts already-normalized BF16 query and key tensors in BSND
+layout and full-width FP32 cosine/sine tables.  It deliberately performs two
+round-to-nearest FP32 multiplies followed by one round-to-nearest FP32 add,
+then rounds only once when storing BF16 output.  This matches Diffusers'
+``apply_rotary_emb`` arithmetic while combining its separate Q and K calls.
+"""
+
+from __future__ import annotations
+
+import torch
+from torch.library import Library
+from vllm.platforms import current_platform
+from vllm.triton_utils import HAS_TRITON, tl, triton
+from vllm.utils.torch_utils import direct_register_custom_op
+
+_HEAD_DIM = 128
+_HEADS_PER_PROGRAM = 4
+
+
+if HAS_TRITON:
+
+    @triton.jit
+    def _mul_rn_f32(x, y):
+        return tl.inline_asm_elementwise(
+            asm="mul.rn.f32 $0, $1, $2;",
+            constraints="=f,f,f",
+            args=[x, y],
+            dtype=tl.float32,
+            is_pure=True,
+            pack=1,
+        )
+
+    @triton.jit
+    def _add_rn_f32(x, y):
+        return tl.inline_asm_elementwise(
+            asm="add.rn.f32 $0, $1, $2;",
+            constraints="=f,f,f",
+            args=[x, y],
+            dtype=tl.float32,
+            is_pure=True,
+            pack=1,
+        )
+
+    @triton.jit
+    def _qk_rope_exact_kernel(
+        q_ptr,
+        k_ptr,
+        cos_ptr,
+        sin_ptr,
+        q_output_ptr,
+        k_output_ptr,
+        q_stride_token,
+        q_stride_head,
+        q_stride_dim,
+        k_stride_token,
+        k_stride_head,
+        k_stride_dim,
+        q_output_stride_token,
+        q_output_stride_head,
+        q_output_stride_dim,
+        k_output_stride_token,
+        k_output_stride_head,
+        k_output_stride_dim,
+        table_stride_sequence,
+        table_stride_dim,
+        sequence,
+        num_heads: tl.constexpr,
+        head_dim: tl.constexpr,
+        heads_per_program: tl.constexpr,
+    ):
+        token = tl.program_id(0)
+        group = tl.program_id(1)
+        is_key = tl.program_id(2) == 1
+        heads = group * heads_per_program + tl.arange(0, heads_per_program)
+        dims = tl.arange(0, head_dim)
+        valid = heads[:, None] < num_heads
+
+        q_offsets = token * q_stride_token + heads[:, None] * q_stride_head + dims[None, :] * q_stride_dim
+        k_offsets = token * k_stride_token + heads[:, None] * k_stride_head + dims[None, :] * k_stride_dim
+        input_ptrs = tl.where(is_key, k_ptr + k_offsets, q_ptr + q_offsets)
+
+        pair_dims = dims ^ 1
+        q_pair_offsets = token * q_stride_token + heads[:, None] * q_stride_head + pair_dims[None, :] * q_stride_dim
+        k_pair_offsets = token * k_stride_token + heads[:, None] * k_stride_head + pair_dims[None, :] * k_stride_dim
+        pair_ptrs = tl.where(is_key, k_ptr + k_pair_offsets, q_ptr + q_pair_offsets)
+        values = tl.load(input_ptrs, mask=valid, other=0.0).to(tl.float32)
+        pairs = tl.load(pair_ptrs, mask=valid, other=0.0).to(tl.float32)
+        signed_pairs = tl.where((dims[None, :] & 1) == 0, -pairs, pairs)
+
+        sequence_index = token % sequence
+        table_offsets = sequence_index * table_stride_sequence + dims * table_stride_dim
+        cos = tl.load(cos_ptr + table_offsets).to(tl.float32)[None, :]
+        sin = tl.load(sin_ptr + table_offsets).to(tl.float32)[None, :]
+
+        # Do not let the compiler contract this expression into an FMA.  The
+        # reference has two independently rounded FP32 multiplies and one
+        # independently rounded FP32 add, followed by the final BF16 store.
+        first = _mul_rn_f32(values, cos)
+        second = _mul_rn_f32(signed_pairs, sin)
+        output = _add_rn_f32(first, second)
+        q_output_offsets = (
+            token * q_output_stride_token + heads[:, None] * q_output_stride_head + dims[None, :] * q_output_stride_dim
+        )
+        k_output_offsets = (
+            token * k_output_stride_token + heads[:, None] * k_output_stride_head + dims[None, :] * k_output_stride_dim
+        )
+        output_ptrs = tl.where(
+            is_key,
+            k_output_ptr + k_output_offsets,
+            q_output_ptr + q_output_offsets,
+        )
+        tl.store(output_ptrs, output, mask=valid)
+
+
+def fused_qk_rope_supported(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    cos: torch.Tensor,
+    sin: torch.Tensor,
+) -> bool:
+    """Return whether the exact CUDA kernel can consume these tensors."""
+
+    if not (
+        HAS_TRITON
+        and torch.version.hip is None
+        and current_platform.is_cuda()
+        and not torch.is_grad_enabled()
+        and q.is_cuda
+        and k.is_cuda
+        and q.device == k.device
+        and q.dtype is torch.bfloat16
+        and k.dtype is q.dtype
+        and q.ndim == 4
+        and k.shape == q.shape
+        and q.numel() > 0
+        and q.is_contiguous()
+        and k.is_contiguous()
+    ):
+        return False
+
+    batch, sequence, _heads, head_dim = q.shape
+    del batch
+    if head_dim != _HEAD_DIM:
+        return False
+    if not (
+        cos.shape == (sequence, head_dim)
+        and sin.shape == cos.shape
+        and cos.device == q.device
+        and sin.device == q.device
+        and cos.dtype is torch.float32
+        and sin.dtype is torch.float32
+        and cos.is_contiguous()
+        and sin.is_contiguous()
+    ):
+        return False
+    return True
+
+
+def _launch_fused_qk_rope(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    cos: torch.Tensor,
+    sin: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    q_output = torch.empty_like(q)
+    k_output = torch.empty_like(k)
+    tokens = q.shape[0] * q.shape[1]
+    head_groups = triton.cdiv(q.shape[2], _HEADS_PER_PROGRAM)
+    grid = (tokens, head_groups, 2)
+    with torch.accelerator.device_index(q.device.index):
+        _qk_rope_exact_kernel[grid](
+            q,
+            k,
+            cos,
+            sin,
+            q_output,
+            k_output,
+            q.stride(1),
+            q.stride(2),
+            q.stride(3),
+            k.stride(1),
+            k.stride(2),
+            k.stride(3),
+            q_output.stride(1),
+            q_output.stride(2),
+            q_output.stride(3),
+            k_output.stride(1),
+            k_output.stride(2),
+            k_output.stride(3),
+            cos.stride(0),
+            cos.stride(1),
+            q.shape[1],
+            num_heads=q.shape[2],
+            head_dim=q.shape[-1],
+            heads_per_program=_HEADS_PER_PROGRAM,
+            num_warps=4,
+        )
+    return q_output, k_output
+
+
+def _fused_qk_rope_impl(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    cos: torch.Tensor,
+    sin: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    if not fused_qk_rope_supported(q, k, cos, sin):
+        raise ValueError("fused_qk_rope received unsupported inputs")
+    return _launch_fused_qk_rope(q, k, cos, sin)
+
+
+def _fused_qk_rope_fake(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    cos: torch.Tensor,
+    sin: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    del cos, sin
+    return torch.empty_like(q), torch.empty_like(k)
+
+
+_OMNI_OP_LIB = Library("vllm_omni", "FRAGMENT")
+if not hasattr(torch.ops.vllm_omni, "fused_qk_rope"):
+    direct_register_custom_op(
+        op_name="fused_qk_rope",
+        op_func=_fused_qk_rope_impl,
+        fake_impl=_fused_qk_rope_fake,
+        mutates_args=[],
+        target_lib=_OMNI_OP_LIB,
+    )
+
+
+def fused_qk_rope(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    cos: torch.Tensor,
+    sin: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Apply paired full-width adjacent/interleaved RoPE on CUDA."""
+
+    if not fused_qk_rope_supported(q, k, cos, sin):
+        raise ValueError("fused_qk_rope requires contiguous CUDA BF16 Q/K and contiguous full-width CUDA FP32 tables")
+    return torch.ops.vllm_omni.fused_qk_rope(q, k, cos, sin)
+
+
+__all__ = ["fused_qk_rope", "fused_qk_rope_supported"]
diff --git a/vllm_omni/diffusion/models/longcat_image/longcat_image_transformer.py b/vllm_omni/diffusion/models/longcat_image/longcat_image_transformer.py
index 3cde2a868a3..a93d147047a 100644
--- a/vllm_omni/diffusion/models/longcat_image/longcat_image_transformer.py
+++ b/vllm_omni/diffusion/models/longcat_image/longcat_image_transformer.py
@@ -1,6 +1,7 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
+from collections import OrderedDict
 from collections.abc import Iterable
 from typing import Any
 
@@ -16,6 +17,8 @@
 from vllm.model_executor.layers.layernorm import RMSNorm
 from vllm.model_executor.layers.linear import ColumnParallelLinear, QKVParallelLinear, RowParallelLinear
 from vllm.model_executor.model_loader.weight_utils import default_weight_loader
+from vllm.platforms import current_platform
+from vllm.triton_utils import HAS_TRITON
 
 from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
 from vllm_omni.diffusion.attention.layer import Attention
@@ -26,10 +29,150 @@
     SequenceParallelOutput,
 )
 from vllm_omni.diffusion.forward_context import get_forward_context
+from vllm_omni.diffusion.layers.fused_qk_norm_rope import fused_qk_norm_rope_min_tokens
+from vllm_omni.diffusion.layers.fused_qk_rope import fused_qk_rope, fused_qk_rope_supported
 from vllm_omni.platforms import current_omni_platform
 
 logger = init_logger(__name__)
 
+RotaryEmbedding = tuple[torch.Tensor, torch.Tensor] | tuple[torch.Tensor, torch.Tensor, int]
+
+# All LongCat production attention spans contain at least 512 tokens.  Reuse
+# the shared Q/K fusion threshold override so deployments can retain a
+# hardware-specific crossover without adding another environment variable.
+_FUSED_MIN_TOKENS = 512
+_FUSED_QK_ROPE = HAS_TRITON and current_platform.is_cuda()
+_FAILED_QK_ROPE_SIGNATURES_MAX_SIZE = 128
+_FAILED_QK_ROPE_SIGNATURES: OrderedDict[tuple[object, ...], None] = OrderedDict()
+
+
+def _fusion_enabled(sequence_parallel_size: int | None, *, enforce_eager: bool) -> bool:
+    return (
+        _FUSED_QK_ROPE
+        and enforce_eager
+        and not torch.compiler.is_compiling()
+        and not torch.is_grad_enabled()
+        and not (sequence_parallel_size is not None and sequence_parallel_size > 1)
+    )
+
+
+def _prepare_rotary_emb(
+    txt_cos: torch.Tensor,
+    txt_sin: torch.Tensor,
+    img_cos: torch.Tensor,
+    img_sin: torch.Tensor,
+    *,
+    enable_fusion: bool,
+) -> RotaryEmbedding:
+    """Join text/image tables and resolve the shared token gate once."""
+
+    joint = torch.cat((txt_cos, img_cos), dim=0), torch.cat((txt_sin, img_sin), dim=0)
+    if not enable_fusion:
+        return joint
+    return joint[0], joint[1], fused_qk_norm_rope_min_tokens(_FUSED_MIN_TOKENS)
+
+
+def _apply_qk_rope_reference(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    rotary_emb: tuple[torch.Tensor, torch.Tensor],
+) -> tuple[torch.Tensor, torch.Tensor]:
+    return (
+        apply_rotary_emb(query, rotary_emb, sequence_dim=1),
+        apply_rotary_emb(key, rotary_emb, sequence_dim=1),
+    )
+
+
+def _qk_rope_signature(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    cos: torch.Tensor,
+    sin: torch.Tensor,
+) -> tuple[object, ...]:
+    """Identify a runtime layout for failure-cache fallback."""
+
+    return (
+        query.device.type,
+        query.device.index,
+        query.dtype,
+        tuple(query.shape),
+        tuple(query.stride()),
+        tuple(key.shape),
+        tuple(key.stride()),
+        cos.dtype,
+        tuple(cos.shape),
+        tuple(cos.stride()),
+        tuple(sin.stride()),
+    )
+
+
+def _is_failed_qk_rope_signature(signature: tuple[object, ...]) -> bool:
+    if signature not in _FAILED_QK_ROPE_SIGNATURES:
+        return False
+    _FAILED_QK_ROPE_SIGNATURES.move_to_end(signature)
+    return True
+
+
+def _record_failed_qk_rope_signature(signature: tuple[object, ...]) -> None:
+    _FAILED_QK_ROPE_SIGNATURES[signature] = None
+    _FAILED_QK_ROPE_SIGNATURES.move_to_end(signature)
+    while len(_FAILED_QK_ROPE_SIGNATURES) > _FAILED_QK_ROPE_SIGNATURES_MAX_SIZE:
+        _FAILED_QK_ROPE_SIGNATURES.popitem(last=False)
+
+
+def _can_use_fused_qk_rope(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    cos: torch.Tensor,
+    sin: torch.Tensor,
+    sequence_parallel_size: int | None,
+    min_tokens: int | None,
+) -> bool:
+    """Keep compile, autograd, capture, SP, and unsupported inputs native."""
+
+    if (
+        torch.compiler.is_compiling()
+        or torch.is_grad_enabled()
+        or (sequence_parallel_size is not None and sequence_parallel_size > 1)
+        or min_tokens is None
+        or not fused_qk_rope_supported(query, key, cos, sin)
+        or torch.cuda.is_current_stream_capturing()
+    ):
+        return False
+    return query.shape[0] * query.shape[1] >= min_tokens
+
+
+def _apply_qk_rope(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    rotary_emb: RotaryEmbedding | None,
+    sequence_parallel_size: int | None,
+    min_tokens: int | None,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Apply one paired RoPE launch, falling back after launch failures."""
+
+    if rotary_emb is None:
+        return query, key
+    rotary_pair = rotary_emb[:2]
+    cos, sin = rotary_pair
+    if not _can_use_fused_qk_rope(query, key, cos, sin, sequence_parallel_size, min_tokens):
+        return _apply_qk_rope_reference(query, key, rotary_pair)
+
+    signature = _qk_rope_signature(query, key, cos, sin)
+    if _is_failed_qk_rope_signature(signature):
+        return _apply_qk_rope_reference(query, key, rotary_pair)
+
+    try:
+        return fused_qk_rope(query, key, cos, sin)
+    except Exception as exc:  # noqa: BLE001 - optimized-path failures must fall back
+        _record_failed_qk_rope_signature(signature)
+        logger.warning(
+            "Disabling LongCat paired Q/K RoPE fusion for signature %s after failure: %s",
+            signature,
+            exc,
+        )
+        return _apply_qk_rope_reference(query, key, rotary_pair)
+
 
 class FeedForward(nn.Module):
     def __init__(self, dim: int, dim_out: int | None = None, mult: int = 4, bias: bool = True):
@@ -121,7 +264,7 @@ def _sp_attention_with_rope(
         text_key: torch.Tensor,
         text_value: torch.Tensor,
         text_seq_len: int,
-        image_rotary_emb: tuple[torch.Tensor, torch.Tensor] | None,
+        image_rotary_emb: RotaryEmbedding | None,
     ) -> torch.Tensor:
         """
         Apply RoPE separately to text and image Q/K, then run SP attention with joint tensors.
@@ -139,7 +282,7 @@ def _sp_attention_with_rope(
             Attention output with shape (B, txt_len + img_len/SP, H, D)
         """
         if image_rotary_emb is not None:
-            freqs_cos, freqs_sin = image_rotary_emb
+            freqs_cos, freqs_sin = image_rotary_emb[:2]
             txt_rotary_emb = (freqs_cos[:text_seq_len], freqs_sin[:text_seq_len])
             img_rotary_emb_split = (freqs_cos[text_seq_len:], freqs_sin[text_seq_len:])
             # Apply RoPE to image Q/K
@@ -165,7 +308,7 @@ def forward(
         self,
         hidden_states: torch.Tensor,
         encoder_hidden_states: torch.Tensor | None = None,
-        image_rotary_emb: torch.Tensor | None = None,
+        image_rotary_emb: RotaryEmbedding | None = None,
         **kwargs,
     ) -> torch.Tensor:
         """
@@ -196,6 +339,8 @@ def forward(
 
         query = self.norm_q(query)
         key = self.norm_k(key)
+        rotary_pair = image_rotary_emb[:2] if image_rotary_emb is not None else None
+        min_tokens = image_rotary_emb[2] if image_rotary_emb is not None and len(image_rotary_emb) > 2 else None
 
         if self.added_kv_proj_dim is not None:
             encoder_qkv, _ = self.add_kv_proj(encoder_hidden_states)
@@ -222,7 +367,7 @@ def forward(
                     text_key=encoder_key,
                     text_value=encoder_value,
                     text_seq_len=encoder_query.shape[1],
-                    image_rotary_emb=image_rotary_emb,
+                    image_rotary_emb=rotary_pair,
                 )
             else:
                 # Non-SP Mode: Concat first, then apply RoPE to full sequence
@@ -230,10 +375,15 @@ def forward(
                 joint_key = torch.cat([encoder_key, key], dim=1)
                 joint_value = torch.cat([encoder_value, value], dim=1)
 
-                if image_rotary_emb is not None:
-                    # Apply RoPE to full (text + image) sequence
-                    joint_query = apply_rotary_emb(joint_query, image_rotary_emb, sequence_dim=1)
-                    joint_key = apply_rotary_emb(joint_key, image_rotary_emb, sequence_dim=1)
+                # Keep the native RMSNorm and text-then-image concatenation
+                # order, then combine only the two independent RoPE calls.
+                joint_query, joint_key = _apply_qk_rope(
+                    joint_query,
+                    joint_key,
+                    rotary_pair,
+                    sp_size,
+                    min_tokens,
+                )
 
                 hidden_states = self.attn(
                     joint_query,
@@ -272,13 +422,17 @@ def forward(
                     text_key=key[:, :text_seq_len],
                     text_value=value[:, :text_seq_len],
                     text_seq_len=text_seq_len,
-                    image_rotary_emb=image_rotary_emb,
+                    image_rotary_emb=rotary_pair,
                 )
             else:
                 # Non-SP Mode: standard path
-                if image_rotary_emb is not None:
-                    query = apply_rotary_emb(query, image_rotary_emb, sequence_dim=1)
-                    key = apply_rotary_emb(key, image_rotary_emb, sequence_dim=1)
+                query, key = _apply_qk_rope(
+                    query,
+                    key,
+                    rotary_pair,
+                    sp_size,
+                    min_tokens,
+                )
 
                 hidden_states = self.attn(
                     query,
@@ -345,7 +499,7 @@ def forward(
         hidden_states: torch.Tensor,
         encoder_hidden_states: torch.Tensor,
         temb: torch.Tensor,
-        image_rotary_emb: tuple[torch.Tensor, torch.Tensor] | None = None,
+        image_rotary_emb: RotaryEmbedding | None = None,
         joint_attention_kwargs: dict[str, Any] | None = None,
     ) -> tuple[torch.Tensor, torch.Tensor]:
         norm_hidden_states, gate_msa, shift_mlp, scale_mlp, gate_mlp = self.norm1(hidden_states, emb=temb)
@@ -536,7 +690,7 @@ def forward(
         hidden_states: torch.Tensor,
         encoder_hidden_states: torch.Tensor,
         temb: torch.Tensor,
-        image_rotary_emb: tuple[torch.Tensor, torch.Tensor] | None = None,
+        image_rotary_emb: RotaryEmbedding | None = None,
         joint_attention_kwargs: dict[str, Any] | None = None,
     ) -> tuple[torch.Tensor, torch.Tensor]:
         """
@@ -632,6 +786,7 @@ def __init__(
 
         # Store parallel config for SP support
         self.parallel_config = od_config.parallel_config
+        self.enforce_eager = bool(getattr(od_config, "enforce_eager", False))
 
         self.pos_embed = LongCatImagePosEmbed(theta=10000, axes_dim=axes_dims_rope)
         self.rope_preparer = RoPEPreparer(self.pos_embed)
@@ -701,11 +856,15 @@ def forward(
         # txt_cos/txt_sin (outputs 0, 1) remain replicated for dual-stream attention
         txt_cos, txt_sin, img_cos, img_sin = self.rope_preparer(txt_ids, img_ids)
 
-        # Reconstruct image_rotary_emb with chunked values
-        # Final shape: (txt_seq_len + img_seq_len // SP, head_dim)
-        image_rotary_emb = (
-            torch.cat([txt_cos, img_cos], dim=0),
-            torch.cat([txt_sin, img_sin], dim=0),
+        # Preserve the ordinary full-width tables.  A third scalar only marks
+        # the eligible eager SP=1 route and resolves the shared threshold once
+        # for all attention blocks in this transformer call.
+        image_rotary_emb = _prepare_rotary_emb(
+            txt_cos,
+            txt_sin,
+            img_cos,
+            img_sin,
+            enable_fusion=_fusion_enabled(sp_size, enforce_eager=self.enforce_eager),
         )
 
         for block in self.transformer_blocks:

From 9cdc57d2e7297d0621dcc5c02cf392ee9857e1ec Mon Sep 17 00:00:00 2001
From: BeatSeat <137616995+BeatSeat@users.noreply.github.com>
Date: Fri, 18 Sep 2026 03:02:08 +0800
Subject: [PATCH 073/105] [Bugfix][MAGI-2] Fix layerwise offload OOM by
 pointing offload block attrs to 'block' (#7523) (#7540)

Signed-off-by: BeatSeat <wendavid552@gmail.com>
---
 .../diffusion/models/magi2/test_native_preview.py | 15 +++++++++++++++
 .../diffusion/models/magi2/modeling_magi2.py      | 10 ++++------
 2 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/tests/diffusion/models/magi2/test_native_preview.py b/tests/diffusion/models/magi2/test_native_preview.py
index 9167d72ee54..10458c4939a 100644
--- a/tests/diffusion/models/magi2/test_native_preview.py
+++ b/tests/diffusion/models/magi2/test_native_preview.py
@@ -90,6 +90,21 @@ def test_hsdp_policy_shards_individual_preview_layers():
     assert not condition("pre_adapter", model.pre_adapter)
 
 
+def test_layerwise_offload_contract() -> None:
+    from vllm_omni.diffusion.offloader import get_blocks_from_dit
+
+    model = Magi2PreviewTransformer(_tiny_config(num_layers=2))
+
+    assert model._layerwise_offload_blocks_attrs == ["block"]
+    assert "block" in dict(model.named_children())
+    assert list(model.block) == list(model.block.layers)
+    assert model.layers is model.block.layers
+
+    attr_names, blocks = get_blocks_from_dit(model)
+    assert attr_names == ["block"]
+    assert blocks == list(model.block.layers)
+
+
 def test_data_proxy_keeps_output_layout_request_scoped() -> None:
     proxy = Magi2DataProxy(Magi2PreviewDataProxyConfig(time_channel_dim=0))
 
diff --git a/vllm_omni/diffusion/models/magi2/modeling_magi2.py b/vllm_omni/diffusion/models/magi2/modeling_magi2.py
index 44e282aa0ec..0009a2eccf1 100644
--- a/vllm_omni/diffusion/models/magi2/modeling_magi2.py
+++ b/vllm_omni/diffusion/models/magi2/modeling_magi2.py
@@ -670,11 +670,9 @@ def _is_magi2_transformer_layer(_name: str, module: nn.Module) -> bool:
 class Magi2PreviewTransformer(nn.Module):
     """Native preview DiT with the released checkpoint hierarchy."""
 
-    # ``block`` must remain the registered child name because it is part of the
-    # released checkpoint hierarchy.  The ``layers`` property below exposes its
-    # ModuleList through the standard layerwise-offload contract without
-    # changing the registered module names.
-    _layerwise_offload_blocks_attrs = ["layers"]
+    # ``block`` is the registered child module containing the repeated
+    # layers, exposed as the streamable blocks container for layerwise offload.
+    _layerwise_offload_blocks_attrs = ["block"]
     _hsdp_shard_conditions = [_is_magi2_transformer_layer]
     _hsdp_preserve_parameter_dtypes = True
     _EP_SHARDED_SUFFIXES = (
@@ -704,7 +702,7 @@ def __init__(self, config: Magi2PreviewConfig | None = None) -> None:
 
     @property
     def layers(self) -> nn.ModuleList:
-        """Expose Preview layers to the shared offload block discovery API."""
+        """Expose Preview layers for direct access and compatibility."""
 
         return self.block.layers
 

From a6570b68140cded3aa00e1fa6cddd78a869db6fe Mon Sep 17 00:00:00 2001
From: dongbo910220 <32610838+dongbo910220@users.noreply.github.com>
Date: Fri, 18 Sep 2026 03:06:45 +0800
Subject: [PATCH 074/105] [Diffusion] Fuse ERNIE-Image Q/K RoPE for eager
 execution (#7502)

Signed-off-by: dongbo910220 <1275604947@qq.com>
---
 .../test_ernie_image_fused_rope.py            | 169 ++++++++++++++
 .../ernie_image/test_ernie_image_rope.py      |  31 +++
 .../ernie_image/ernie_image_transformer.py    |  26 ++-
 .../models/ernie_image/fused_rope.py          | 211 ++++++++++++++++++
 4 files changed, 435 insertions(+), 2 deletions(-)
 create mode 100644 tests/diffusion/models/ernie_image/test_ernie_image_fused_rope.py
 create mode 100644 vllm_omni/diffusion/models/ernie_image/fused_rope.py

diff --git a/tests/diffusion/models/ernie_image/test_ernie_image_fused_rope.py b/tests/diffusion/models/ernie_image/test_ernie_image_fused_rope.py
new file mode 100644
index 00000000000..bf3dce4f326
--- /dev/null
+++ b/tests/diffusion/models/ernie_image/test_ernie_image_fused_rope.py
@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import pytest
+import torch
+from vllm.triton_utils import HAS_TRITON
+
+from vllm_omni.diffusion.models.ernie_image.ernie_image_transformer import _apply_rotary_emb
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cuda, pytest.mark.diffusion]
+
+
+@pytest.fixture(autouse=True)
+def reset_fused_rope_state():
+    from vllm_omni.diffusion.models.ernie_image import fused_rope
+
+    fused_rope._FAILED_KEYS.clear()
+    yield
+    fused_rope._FAILED_KEYS.clear()
+
+
+def _inputs(shape: tuple[int, int, int, int]):
+    batch, sequence, _, head_dim = shape
+    torch.manual_seed(17)
+    query = torch.randn(shape, device="cuda", dtype=torch.bfloat16)
+    key = torch.randn_like(query)
+    freqs_cos = torch.randn(
+        batch,
+        sequence,
+        head_dim // 2,
+        device="cuda",
+        dtype=torch.float32,
+    )
+    freqs_sin = torch.randn_like(freqs_cos)
+    return query, key, freqs_cos, freqs_sin
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+@pytest.mark.parametrize(
+    "shape",
+    [
+        (1, 1, 1, 128),
+        (2, 257, 7, 128),
+        (2, 4608, 32, 128),
+    ],
+)
+def test_fused_qk_rope_is_bit_exact(shape):
+    from vllm_omni.diffusion.models.ernie_image import fused_rope
+
+    query, key, freqs_cos, freqs_sin = _inputs(shape)
+    with torch.inference_mode():
+        expected_query = _apply_rotary_emb(query, freqs_cos, freqs_sin)
+        expected_key = _apply_rotary_emb(key, freqs_cos, freqs_sin)
+        actual = fused_rope.try_fused_qk_rotary_emb(query, key, freqs_cos, freqs_sin)
+
+    assert actual is not None
+    actual_query, actual_key = actual
+    assert torch.equal(actual_query, expected_query)
+    assert torch.equal(actual_key, expected_key)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+def test_launch_failure_disables_runtime_key(monkeypatch):
+    from vllm_omni.diffusion.models.ernie_image import fused_rope
+
+    query, key, freqs_cos, freqs_sin = _inputs((1, 17, 3, 128))
+    launch_count = 0
+
+    def failing_launch(*args):
+        nonlocal launch_count
+        launch_count += 1
+        raise RuntimeError("injected launch failure")
+
+    monkeypatch.setattr(
+        fused_rope,
+        "_launch_fused_qk_rotary_emb",
+        failing_launch,
+    )
+    with torch.inference_mode():
+        for _ in range(2):
+            assert fused_rope.try_fused_qk_rotary_emb(query, key, freqs_cos, freqs_sin) is None
+    assert launch_count == 1
+    assert len(fused_rope._FAILED_KEYS) == 1
+
+
+def test_failed_runtime_key_cache_is_bounded():
+    from vllm_omni.diffusion.models.ernie_image import fused_rope
+
+    for index in range(fused_rope._FAILED_KEYS_MAX_SIZE + 1):
+        fused_rope._record_failed_runtime_key((index,))
+
+    assert len(fused_rope._FAILED_KEYS) == fused_rope._FAILED_KEYS_MAX_SIZE
+    assert (0,) not in fused_rope._FAILED_KEYS
+    assert (fused_rope._FAILED_KEYS_MAX_SIZE,) in fused_rope._FAILED_KEYS
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+def test_compile_path_does_not_launch_fused_kernel(monkeypatch):
+    from vllm_omni.diffusion.models.ernie_image import fused_rope
+
+    query, key, freqs_cos, freqs_sin = _inputs((1, 17, 3, 128))
+    monkeypatch.setattr(torch.compiler, "is_compiling", lambda: True)
+
+    def unexpected_launch(*args):
+        raise AssertionError("compile path must remain native")
+
+    monkeypatch.setattr(
+        fused_rope,
+        "_launch_fused_qk_rotary_emb",
+        unexpected_launch,
+    )
+    with torch.inference_mode():
+        assert fused_rope.try_fused_qk_rotary_emb(query, key, freqs_cos, freqs_sin) is None
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+@pytest.mark.parametrize("requires_grad_input", ["query", "key", "cos", "sin"])
+def test_gradient_inputs_do_not_launch_fused_kernel(monkeypatch, requires_grad_input):
+    from vllm_omni.diffusion.models.ernie_image import fused_rope
+
+    values = list(_inputs((1, 17, 3, 128)))
+    input_index = {"query": 0, "key": 1, "cos": 2, "sin": 3}[requires_grad_input]
+    values[input_index].requires_grad_(True)
+
+    def unexpected_launch(*args):
+        raise AssertionError("autograd inputs must remain on the native path")
+
+    monkeypatch.setattr(
+        fused_rope,
+        "_launch_fused_qk_rotary_emb",
+        unexpected_launch,
+    )
+    assert (
+        fused_rope.try_fused_qk_rotary_emb(
+            *values,
+        )
+        is None
+    )
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+def test_mismatched_key_dtype_or_device_does_not_launch(monkeypatch):
+    from vllm_omni.diffusion.models.ernie_image import fused_rope
+
+    query, key, freqs_cos, freqs_sin = _inputs((1, 17, 3, 128))
+
+    def unexpected_launch(*args):
+        raise AssertionError("mismatched Q/K inputs must remain native")
+
+    monkeypatch.setattr(
+        fused_rope,
+        "_launch_fused_qk_rotary_emb",
+        unexpected_launch,
+    )
+    for unsupported_key in (key.float(), key.cpu()):
+        assert (
+            fused_rope.try_fused_qk_rotary_emb(
+                query,
+                unsupported_key,
+                freqs_cos,
+                freqs_sin,
+            )
+            is None
+        )
diff --git a/tests/diffusion/models/ernie_image/test_ernie_image_rope.py b/tests/diffusion/models/ernie_image/test_ernie_image_rope.py
index 22d8efaada4..34beb69f986 100644
--- a/tests/diffusion/models/ernie_image/test_ernie_image_rope.py
+++ b/tests/diffusion/models/ernie_image/test_ernie_image_rope.py
@@ -1,8 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 import pytest
 import torch
 
 from vllm_omni.diffusion.models.ernie_image.ernie_image_transformer import (
     ErnieImageEmbedND3,
+    _apply_qk_rotary_emb,
     _apply_rotary_emb,
     rope,
 )
@@ -185,3 +189,30 @@ def test_apply_rotary_emb_matches_diffusers_style(self):
         out_diffusers = x * cos_ + rotated * sin_
 
         assert torch.allclose(out_vllm, out_diffusers, atol=1e-6), "vllm-omni and diffusers outputs should match"
+
+    def test_apply_qk_rotary_emb_uses_native_fallback(self, monkeypatch):
+        """Unsupported routes preserve both existing eager calls exactly."""
+        from vllm_omni.diffusion.models.ernie_image import (
+            ernie_image_transformer,
+        )
+
+        B, S, H, D = 2, 17, 3, 128
+        query = torch.randn(B, S, H, D)
+        key = torch.randn(B, S, H, D)
+        freqs_cos = torch.randn(B, S, D // 2)
+        freqs_sin = torch.randn(B, S, D // 2)
+        monkeypatch.setattr(
+            ernie_image_transformer,
+            "try_fused_qk_rotary_emb",
+            lambda *args: None,
+        )
+
+        actual_query, actual_key = _apply_qk_rotary_emb(query, key, freqs_cos, freqs_sin)
+        assert torch.equal(
+            actual_query,
+            _apply_rotary_emb(query, freqs_cos, freqs_sin),
+        )
+        assert torch.equal(
+            actual_key,
+            _apply_rotary_emb(key, freqs_cos, freqs_sin),
+        )
diff --git a/vllm_omni/diffusion/models/ernie_image/ernie_image_transformer.py b/vllm_omni/diffusion/models/ernie_image/ernie_image_transformer.py
index bd96630e8d4..eb26e538901 100644
--- a/vllm_omni/diffusion/models/ernie_image/ernie_image_transformer.py
+++ b/vllm_omni/diffusion/models/ernie_image/ernie_image_transformer.py
@@ -28,6 +28,9 @@
     SequenceParallelInput,
     SequenceParallelOutput,
 )
+from vllm_omni.diffusion.models.ernie_image.fused_rope import (
+    try_fused_qk_rotary_emb,
+)
 
 logger = init_logger(__name__)
 
@@ -101,6 +104,26 @@ def _apply_rotary_emb(
     return torch.cat((x_rot * cos_ + x_rotated * sin_, x[..., rot_dim:]), dim=-1)
 
 
+def _apply_qk_rotary_emb(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    freqs_cos: torch.Tensor,
+    freqs_sin: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    fused = try_fused_qk_rotary_emb(
+        query,
+        key,
+        freqs_cos,
+        freqs_sin,
+    )
+    if fused is not None:
+        return fused
+    return (
+        _apply_rotary_emb(query, freqs_cos, freqs_sin),
+        _apply_rotary_emb(key, freqs_cos, freqs_sin),
+    )
+
+
 class ErnieImageEmbedND3(nn.Module):
     def __init__(self, dim: int, theta: int, axes_dim: tuple[int, int, int]):
         super().__init__()
@@ -340,8 +363,7 @@ def forward(
 
         if image_rotary_emb is not None:
             freqs_cos, freqs_sin = image_rotary_emb
-            query = _apply_rotary_emb(query, freqs_cos, freqs_sin)
-            key = _apply_rotary_emb(key, freqs_cos, freqs_sin)
+            query, key = _apply_qk_rotary_emb(query, key, freqs_cos, freqs_sin)
 
         attn_metadata = None
         if attention_mask is not None:
diff --git a/vllm_omni/diffusion/models/ernie_image/fused_rope.py b/vllm_omni/diffusion/models/ernie_image/fused_rope.py
new file mode 100644
index 00000000000..5bdb611656f
--- /dev/null
+++ b/vllm_omni/diffusion/models/ernie_image/fused_rope.py
@@ -0,0 +1,211 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Lossless eager Q/K RoPE fusion for ERNIE-Image."""
+
+from __future__ import annotations
+
+import logging
+from collections import OrderedDict
+
+import torch
+from vllm.triton_utils import HAS_TRITON, tl, triton
+
+from vllm_omni.platforms import current_omni_platform
+
+logger = logging.getLogger(__name__)
+
+_FAILED_KEYS_MAX_SIZE = 128
+_FAILED_KEYS: OrderedDict[tuple[object, ...], None] = OrderedDict()
+
+
+if HAS_TRITON:
+
+    @triton.jit
+    def _round_bf16_to_fp32(value):
+        """RNE-round FP32 to BF16 precision in an FP32 register."""
+
+        bits = value.to(tl.int32, bitcast=True)
+        rounding_bias = 0x7FFF + ((bits >> 16) & 1)
+        rounded_bits = (bits + rounding_bias) & -65536
+        return rounded_bits.to(tl.float32, bitcast=True)
+
+    @triton.jit
+    def _qk_rope_kernel(
+        out_q_ptr,
+        out_k_ptr,
+        q_ptr,
+        k_ptr,
+        cos_ptr,
+        sin_ptr,
+        heads,
+        head_dim: tl.constexpr,
+        rotary_dim: tl.constexpr,
+        rotary_half: tl.constexpr,
+        heads_block: tl.constexpr,
+        half_block: tl.constexpr,
+        tail_block: tl.constexpr,
+    ):
+        row = tl.program_id(0).to(tl.int64)
+        is_key = tl.program_id(1)
+        base = row * heads * head_dim
+        head_offsets = tl.arange(0, heads_block)[:, None]
+        head_mask = head_offsets < heads
+        columns = tl.arange(0, half_block)[None, :]
+        column_mask = columns < rotary_half
+        mask = head_mask & column_mask
+
+        if is_key == 0:
+            input_ptr = q_ptr
+            output_ptr = out_q_ptr
+        else:
+            input_ptr = k_ptr
+            output_ptr = out_k_ptr
+
+        first_offsets = base + head_offsets * head_dim + columns
+        second_offsets = first_offsets + rotary_half
+        first = tl.load(input_ptr + first_offsets, mask=mask, other=0.0).to(tl.float32)
+        second = tl.load(input_ptr + second_offsets, mask=mask, other=0.0).to(tl.float32)
+
+        # The eager path casts FP32 frequencies to BF16, duplicates adjacent
+        # values, rounds both BF16 multiplies, and finally rounds the add.
+        first_freq = columns // 2
+        second_freq = (rotary_half + columns) // 2
+        cos_first = _round_bf16_to_fp32(tl.load(cos_ptr + row * rotary_half + first_freq, mask=column_mask))
+        cos_second = _round_bf16_to_fp32(tl.load(cos_ptr + row * rotary_half + second_freq, mask=column_mask))
+        sin_first = _round_bf16_to_fp32(tl.load(sin_ptr + row * rotary_half + first_freq, mask=column_mask))
+        sin_second = _round_bf16_to_fp32(tl.load(sin_ptr + row * rotary_half + second_freq, mask=column_mask))
+
+        out_first = _round_bf16_to_fp32(first * cos_first) + _round_bf16_to_fp32(-second * sin_first)
+        out_second = _round_bf16_to_fp32(second * cos_second) + _round_bf16_to_fp32(first * sin_second)
+        tl.store(output_ptr + first_offsets, out_first, mask=mask)
+        tl.store(output_ptr + second_offsets, out_second, mask=mask)
+
+        if head_dim > rotary_dim:
+            tail_columns = rotary_dim + tl.arange(0, tail_block)[None, :]
+            tail_mask = head_mask & (tail_columns < head_dim)
+            tail_offsets = base + head_offsets * head_dim + tail_columns
+            tail = tl.load(input_ptr + tail_offsets, mask=tail_mask, other=0.0)
+            tl.store(output_ptr + tail_offsets, tail, mask=tail_mask)
+
+
+def _runtime_key(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    freqs_cos: torch.Tensor,
+) -> tuple[object, ...]:
+    return (
+        query.device.index,
+        tuple(query.shape),
+        tuple(key.shape),
+        tuple(freqs_cos.shape),
+        query.dtype,
+        freqs_cos.dtype,
+    )
+
+
+def _is_failed_runtime_key(runtime_key: tuple[object, ...]) -> bool:
+    if runtime_key not in _FAILED_KEYS:
+        return False
+    _FAILED_KEYS.move_to_end(runtime_key)
+    return True
+
+
+def _record_failed_runtime_key(runtime_key: tuple[object, ...]) -> None:
+    _FAILED_KEYS[runtime_key] = None
+    _FAILED_KEYS.move_to_end(runtime_key)
+    while len(_FAILED_KEYS) > _FAILED_KEYS_MAX_SIZE:
+        _FAILED_KEYS.popitem(last=False)
+
+
+def _supported_inputs(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    freqs_cos: torch.Tensor,
+    freqs_sin: torch.Tensor,
+) -> bool:
+    if torch.compiler.is_compiling():
+        return False
+    if any(tensor.requires_grad for tensor in (query, key, freqs_cos, freqs_sin)):
+        return False
+    if not HAS_TRITON or not current_omni_platform.is_cuda():
+        return False
+    if query.dtype is not torch.bfloat16 or not query.is_cuda:
+        return False
+    if query.ndim != 4 or key.shape != query.shape or key.dtype is not query.dtype or key.device != query.device:
+        return False
+    if not query.is_contiguous() or not key.is_contiguous():
+        return False
+    if freqs_cos.dtype is not torch.float32 or freqs_sin.dtype is not torch.float32:
+        return False
+    if not freqs_cos.is_cuda or freqs_cos.device != query.device:
+        return False
+    if freqs_sin.device != query.device or freqs_sin.shape != freqs_cos.shape:
+        return False
+    if not freqs_cos.is_contiguous() or not freqs_sin.is_contiguous():
+        return False
+    batch, sequence, _, head_dim = query.shape
+    rotary_half = freqs_cos.shape[-1] if freqs_cos.ndim == 3 else 0
+    return (
+        query.numel() > 0
+        and freqs_cos.shape == (batch, sequence, rotary_half)
+        and rotary_half > 0
+        and rotary_half * 2 <= head_dim
+    )
+
+
+def _launch_fused_qk_rotary_emb(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    freqs_cos: torch.Tensor,
+    freqs_sin: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    batch, sequence, heads, head_dim = query.shape
+    rotary_half = freqs_cos.shape[-1]
+    rotary_dim = rotary_half * 2
+    tail = head_dim - rotary_dim
+    output_query = torch.empty_like(query)
+    output_key = torch.empty_like(key)
+    with torch.accelerator.device_index(query.device.index):
+        _qk_rope_kernel[(batch * sequence, 2)](
+            output_query,
+            output_key,
+            query,
+            key,
+            freqs_cos,
+            freqs_sin,
+            heads,
+            head_dim=head_dim,
+            rotary_dim=rotary_dim,
+            rotary_half=rotary_half,
+            heads_block=triton.next_power_of_2(heads),
+            half_block=triton.next_power_of_2(rotary_half),
+            tail_block=triton.next_power_of_2(max(tail, 1)),
+        )
+    return output_query, output_key
+
+
+def try_fused_qk_rotary_emb(
+    query: torch.Tensor,
+    key: torch.Tensor,
+    freqs_cos: torch.Tensor,
+    freqs_sin: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor] | None:
+    """Return fused Q/K outputs, or ``None`` to request the eager fallback."""
+
+    if not _supported_inputs(query, key, freqs_cos, freqs_sin):
+        return None
+
+    runtime_key = _runtime_key(query, key, freqs_cos)
+    if _is_failed_runtime_key(runtime_key):
+        return None
+
+    try:
+        return _launch_fused_qk_rotary_emb(query, key, freqs_cos, freqs_sin)
+    except Exception:
+        _record_failed_runtime_key(runtime_key)
+        logger.exception("ERNIE-Image fused Q/K RoPE failed; using the eager fallback")
+        return None
+
+
+__all__ = ["try_fused_qk_rotary_emb"]

From b81f2c5d4be41d35664bd7b7ccea74396348ed8b Mon Sep 17 00:00:00 2001
From: Nick Cao <ncao@redhat.com>
Date: Thu, 17 Sep 2026 15:22:14 -0400
Subject: [PATCH 075/105] [Misc] treewide: remove shm_threshold_bytes from
 deploy config (#7522)

Signed-off-by: Nick Cao <ncao@redhat.com>
Co-authored-by: Codex <noreply@openai.com>
---
 vllm_omni/deploy/audex_s2s.yaml                         | 1 -
 vllm_omni/deploy/audex_s2s_30b.yaml                     | 1 -
 vllm_omni/deploy/audex_tta.yaml                         | 1 -
 vllm_omni/deploy/audex_tta_30b.yaml                     | 1 -
 vllm_omni/deploy/audex_tts.yaml                         | 1 -
 vllm_omni/deploy/audex_tts_30b.yaml                     | 1 -
 vllm_omni/deploy/minimax_music3.yaml                    | 1 -
 vllm_omni/deploy/minimax_music3_2gpu.yaml               | 1 -
 vllm_omni/deploy/nemotron_labs_voicechat.yaml           | 2 --
 vllm_omni/deploy/nemotron_labs_voicechat_duplex.yaml    | 1 -
 vllm_omni/deploy/nemotron_labs_voicechat_streaming.yaml | 1 -
 vllm_omni/deploy/personaplex.yaml                       | 1 -
 12 files changed, 13 deletions(-)

diff --git a/vllm_omni/deploy/audex_s2s.yaml b/vllm_omni/deploy/audex_s2s.yaml
index 86110631549..e6635ec6c38 100644
--- a/vllm_omni/deploy/audex_s2s.yaml
+++ b/vllm_omni/deploy/audex_s2s.yaml
@@ -14,7 +14,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       codec_streaming: true
       connector_get_sleep_s: 0.01
       connector_get_max_wait_first_chunk: 3000
diff --git a/vllm_omni/deploy/audex_s2s_30b.yaml b/vllm_omni/deploy/audex_s2s_30b.yaml
index 5921e830809..75b4c77ff76 100644
--- a/vllm_omni/deploy/audex_s2s_30b.yaml
+++ b/vllm_omni/deploy/audex_s2s_30b.yaml
@@ -9,7 +9,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       codec_streaming: true
       connector_get_sleep_s: 0.01
       connector_get_max_wait_first_chunk: 3000
diff --git a/vllm_omni/deploy/audex_tta.yaml b/vllm_omni/deploy/audex_tta.yaml
index d5419e00b20..8fe904f518a 100644
--- a/vllm_omni/deploy/audex_tta.yaml
+++ b/vllm_omni/deploy/audex_tta.yaml
@@ -21,7 +21,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       connector_get_sleep_s: 0.01
       connector_get_max_wait_first_chunk: 3000
       connector_get_max_wait: 300
diff --git a/vllm_omni/deploy/audex_tta_30b.yaml b/vllm_omni/deploy/audex_tta_30b.yaml
index 52c7fdc27c2..7547f09f9cb 100644
--- a/vllm_omni/deploy/audex_tta_30b.yaml
+++ b/vllm_omni/deploy/audex_tta_30b.yaml
@@ -9,7 +9,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       connector_get_sleep_s: 0.01
       connector_get_max_wait_first_chunk: 3000
       connector_get_max_wait: 300
diff --git a/vllm_omni/deploy/audex_tts.yaml b/vllm_omni/deploy/audex_tts.yaml
index f0509ec30ad..df04f3004c6 100644
--- a/vllm_omni/deploy/audex_tts.yaml
+++ b/vllm_omni/deploy/audex_tts.yaml
@@ -26,7 +26,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       codec_streaming: true
       connector_get_sleep_s: 0.01
       connector_get_max_wait_first_chunk: 3000
diff --git a/vllm_omni/deploy/audex_tts_30b.yaml b/vllm_omni/deploy/audex_tts_30b.yaml
index a4aa2d4cc01..aaa75fc15b8 100644
--- a/vllm_omni/deploy/audex_tts_30b.yaml
+++ b/vllm_omni/deploy/audex_tts_30b.yaml
@@ -26,7 +26,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       codec_streaming: true
       connector_get_sleep_s: 0.01
       connector_get_max_wait_first_chunk: 3000
diff --git a/vllm_omni/deploy/minimax_music3.yaml b/vllm_omni/deploy/minimax_music3.yaml
index 6e8a13d9d51..ba0101cde73 100644
--- a/vllm_omni/deploy/minimax_music3.yaml
+++ b/vllm_omni/deploy/minimax_music3.yaml
@@ -25,7 +25,6 @@ connectors:
       # Window geometry is fixed by the checkpoint (200-frame windows on a
       # 100-frame hop, models/minimax_music3/constants.py), so there are no
       # codec_chunk_frames knobs here: changing the window changes the audio.
-      shm_threshold_bytes: 65536
       connector_get_sleep_s: 0.01
       # One window is 200 AR frames = 8 s of music, so stage 1 waits far longer
       # for a chunk than a per-step codec stage would. First chunk additionally
diff --git a/vllm_omni/deploy/minimax_music3_2gpu.yaml b/vllm_omni/deploy/minimax_music3_2gpu.yaml
index 8c463e0e73d..fca04d04c4f 100644
--- a/vllm_omni/deploy/minimax_music3_2gpu.yaml
+++ b/vllm_omni/deploy/minimax_music3_2gpu.yaml
@@ -22,7 +22,6 @@ connectors:
       # Window geometry is fixed by the checkpoint (200-frame windows on a
       # 100-frame hop, models/minimax_music3/constants.py), so there are no
       # codec_chunk_frames knobs here: changing the window changes the audio.
-      shm_threshold_bytes: 65536
       connector_get_sleep_s: 0.01
       # One window is 200 AR frames = 8 s of music, so stage 1 waits far longer
       # for a chunk than a per-step codec stage would. First chunk additionally
diff --git a/vllm_omni/deploy/nemotron_labs_voicechat.yaml b/vllm_omni/deploy/nemotron_labs_voicechat.yaml
index 8c9ee864606..f03c07c8f3d 100644
--- a/vllm_omni/deploy/nemotron_labs_voicechat.yaml
+++ b/vllm_omni/deploy/nemotron_labs_voicechat.yaml
@@ -25,8 +25,6 @@ async_chunk: false
 connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
-    extra:
-      shm_threshold_bytes: 65536
 
 stages:
   - stage_id: 0  # thinker: speech -> frame-locked text (final text output)
diff --git a/vllm_omni/deploy/nemotron_labs_voicechat_duplex.yaml b/vllm_omni/deploy/nemotron_labs_voicechat_duplex.yaml
index 8927b122649..18ba3dca03c 100644
--- a/vllm_omni/deploy/nemotron_labs_voicechat_duplex.yaml
+++ b/vllm_omni/deploy/nemotron_labs_voicechat_duplex.yaml
@@ -58,7 +58,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       codec_chunk_frames: 1
       # PARITY: delete this line together with the stage-1 hf_overrides
       # below (the vendored talker drains chunks model-side and keeps the
diff --git a/vllm_omni/deploy/nemotron_labs_voicechat_streaming.yaml b/vllm_omni/deploy/nemotron_labs_voicechat_streaming.yaml
index 0a3ee158bb5..60e781d519c 100644
--- a/vllm_omni/deploy/nemotron_labs_voicechat_streaming.yaml
+++ b/vllm_omni/deploy/nemotron_labs_voicechat_streaming.yaml
@@ -22,7 +22,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       # Streaming cadence for talker -> code2wav: emit a chunk once this many
       # NEW frames (80 ms each) have accumulated (5 frames = 0.4 s of audio).
       # Small chunks are cheap because the incremental codec cache decodes
diff --git a/vllm_omni/deploy/personaplex.yaml b/vllm_omni/deploy/personaplex.yaml
index c4cc472d161..65cdec6d6f4 100644
--- a/vllm_omni/deploy/personaplex.yaml
+++ b/vllm_omni/deploy/personaplex.yaml
@@ -23,7 +23,6 @@ connectors:
   connector_of_shared_memory:
     name: SharedMemoryConnector
     extra:
-      shm_threshold_bytes: 65536
       codec_streaming: true
       # Mimi runs at 12.5 Hz (80 ms / frame). Stream a few frames per chunk.
       codec_chunk_frames: 5

From 77d8de70da6851a504d435df8bc8a0d6ff4913e3 Mon Sep 17 00:00:00 2001
From: Joshna-Medisetty <joshna.medisetty@intel.com>
Date: Thu, 17 Sep 2026 12:23:27 -0700
Subject: [PATCH 076/105] [XPU][HunyuanImage3] Fix HunyuanImage-3.0
 text-to-image on XPU (#7674)

Signed-off-by: Joshna Medisetty <joshna.medisetty@intel.com>
---
 vllm_omni/deploy/hunyuan_image_3_moe.yaml           | 13 ++++++++-----
 .../hunyuan_image3/hunyuan_image3_transformer.py    | 12 ++++++------
 .../hunyuan_image3/pipeline_hunyuan_image3.py       |  3 +++
 .../models/hunyuan_image3/hunyuan_image3.py         |  6 +++++-
 4 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/vllm_omni/deploy/hunyuan_image_3_moe.yaml b/vllm_omni/deploy/hunyuan_image_3_moe.yaml
index 4ae4520a7e0..657af048134 100644
--- a/vllm_omni/deploy/hunyuan_image_3_moe.yaml
+++ b/vllm_omni/deploy/hunyuan_image_3_moe.yaml
@@ -106,11 +106,14 @@ platforms:
 
   xpu:
     stages:
+      # Both stages stay resident, so they cannot share cards.
       - stage_id: 0
         gpu_memory_utilization: 0.95
-        devices: "0,1,2,3,4,5,6,7"
-        tensor_parallel_size: 8
-        max_num_batched_tokens: 32784
+        devices: "0,1,2,3"
+        tensor_parallel_size: 4
+        # fp8 AR weights leave under 1 GiB for KV; 22800 tokens will not fit.
+        max_num_batched_tokens: 8192
+        max_model_len: 8192
         quantization: fp8
         enable_expert_parallel: true
         worker_cls: vllm_omni.platforms.xpu.worker.xpu_ar_worker.XPUARWorker
@@ -120,12 +123,12 @@ platforms:
           repetition_penalty: 1.1
       - stage_id: 1
         gpu_memory_utilization: 0.9
-        devices: "0,1,2,3,4,5,6,7"
+        devices: "4,5,6,7"
         quantization: fp8
         parallel_config:
           pipeline_parallel_size: 1
           data_parallel_size: 1
-          tensor_parallel_size: 8
+          tensor_parallel_size: 4
           enable_expert_parallel: true
           sequence_parallel_size: 1
           ulysses_degree: 1
diff --git a/vllm_omni/diffusion/models/hunyuan_image3/hunyuan_image3_transformer.py b/vllm_omni/diffusion/models/hunyuan_image3/hunyuan_image3_transformer.py
index d58a4349818..1e91f87c12d 100644
--- a/vllm_omni/diffusion/models/hunyuan_image3/hunyuan_image3_transformer.py
+++ b/vllm_omni/diffusion/models/hunyuan_image3/hunyuan_image3_transformer.py
@@ -3040,7 +3040,7 @@ def _maybe_handle_ar_kv_reuse(
 
         # 3. negative cfg prefill
         # For CFG distilled models, skip negative CFG prefill (cfg_factor=1, no negative prompt)
-        if self.do_classifier_free_guidance and not self.model.config.cfg_distilled:
+        if self.do_classifier_free_guidance and not getattr(self.model.config, "cfg_distilled", False):
             self._maybe_run_negative_cfg_prefill(
                 input_ids=input_ids,
                 model_kwargs=model_kwargs,
@@ -3151,7 +3151,7 @@ def __call__(
         # For CFG distilled models, skip CFG parallel (cfg_factor=1, no negative branch)
         cfg_parallel_ready = (
             self.do_classifier_free_guidance
-            and not self.model.config.cfg_distilled
+            and not getattr(self.model.config, "cfg_distilled", False)
             and get_classifier_free_guidance_world_size() == 2
         )
 
@@ -3207,7 +3207,7 @@ def __call__(
             self._split_model_kwargs_for_cfg_parallel(model_kwargs, batch_size, cfg_rank)
         else:
             # For CFG distilled models, cfg_factor is always 1 (CFG embedded in model)
-            if self.model.config.cfg_distilled:
+            if getattr(self.model.config, "cfg_distilled", False):
                 cfg_factor = 1
             else:
                 cfg_factor = 1 + self.do_classifier_free_guidance
@@ -3252,7 +3252,7 @@ def __call__(
                     # Sequential CFG: double the batch
                     latent_model_input = torch.cat([latents] * cfg_factor)
 
-                if self.model.config.use_meanflow:
+                if getattr(self.model.config, "use_meanflow", False):
                     r = self.scheduler.get_timestep_r(t)
                     r_expand = r.repeat(latent_model_input.shape[0])
                 else:
@@ -3281,7 +3281,7 @@ def __call__(
 
                 if should_compute:
                     # Handle guidance for CFG distilled models
-                    if self.model.config.cfg_distilled:
+                    if getattr(self.model.config, "cfg_distilled", False):
                         model_kwargs["guidance"] = torch.tensor(
                             [1000.0 * self._guidance_scale],
                             device=self.device,
@@ -3308,7 +3308,7 @@ def __call__(
                 # Perform guidance
                 # For CFG distilled models, guidance is already embedded in the model,
                 # so we skip the explicit CFG computation
-                if self.model.config.cfg_distilled:
+                if getattr(self.model.config, "cfg_distilled", False):
                     # CFG distilled: guidance is handled internally via guidance_emb
                     pass
                 elif cfg_parallel_ready:
diff --git a/vllm_omni/diffusion/models/hunyuan_image3/pipeline_hunyuan_image3.py b/vllm_omni/diffusion/models/hunyuan_image3/pipeline_hunyuan_image3.py
index fcfd48b4f35..441a9636e7a 100644
--- a/vllm_omni/diffusion/models/hunyuan_image3/pipeline_hunyuan_image3.py
+++ b/vllm_omni/diffusion/models/hunyuan_image3/pipeline_hunyuan_image3.py
@@ -338,6 +338,9 @@ class HunyuanImage3Pipeline(
     supports_step_execution: ClassVar[bool] = True
     supports_request_batch = False
     support_image_input = True
+    # The warmup request's blank image routes this AR+diffusion model down its
+    # image-edit path, where the token block cannot match the latent patch grid.
+    dummy_run_num_frames: ClassVar[int] = 0
     _dit_modules: ClassVar[list[str]] = ["model"]
     _encoder_modules: ClassVar[list[str]] = ["vision_model"]
     _vae_modules: ClassVar[list[str]] = ["vae"]
diff --git a/vllm_omni/model_executor/models/hunyuan_image3/hunyuan_image3.py b/vllm_omni/model_executor/models/hunyuan_image3/hunyuan_image3.py
index b15a19982ae..31225d7ad8e 100755
--- a/vllm_omni/model_executor/models/hunyuan_image3/hunyuan_image3.py
+++ b/vllm_omni/model_executor/models/hunyuan_image3/hunyuan_image3.py
@@ -1557,7 +1557,11 @@ def __init__(self, *, vllm_config: VllmConfig, prefix: str = ""):
         self._end_ratio_id = tokenizer.convert_tokens_to_ids("<img_ratio_32>")
         ratio_33 = tokenizer.convert_tokens_to_ids("<img_ratio_33>")
         ratio_36 = tokenizer.convert_tokens_to_ids("<img_ratio_36>")
-        self._ratio_other_slices = [(ratio_33, ratio_36 + 1)]
+        # The base checkpoint stops at <img_ratio_32>; only Instruct has 33-36.
+        if ratio_33 is None or ratio_36 is None:
+            self._ratio_other_slices = []
+        else:
+            self._ratio_other_slices = [(ratio_33, ratio_36 + 1)]
         # Build the full set of ratio token IDs for use as stop tokens.
         self._all_ratio_ids = set(range(self._start_ratio_id, self._end_ratio_id + 1))
         for s, e in self._ratio_other_slices:

From 6bda549ac23a667efbe44a54cf3f6d57e6e24da2 Mon Sep 17 00:00:00 2001
From: Alex Brooks <albrooks@redhat.com>
Date: Thu, 17 Sep 2026 17:15:37 -0600
Subject: [PATCH 077/105] [Bugfix] Fix Parallel State Initialization For MoE +
 Diffusion (#7676)

Signed-off-by: Alex Brooks <albrooks@redhat.com>
---
 .../test_parallel_state_sp_groups.py          | 47 ++++++++++++++++++-
 .../diffusion/distributed/parallel_state.py   | 15 +++++-
 2 files changed, 58 insertions(+), 4 deletions(-)

diff --git a/tests/diffusion/distributed/test_parallel_state_sp_groups.py b/tests/diffusion/distributed/test_parallel_state_sp_groups.py
index c12882a221b..0febb192577 100644
--- a/tests/diffusion/distributed/test_parallel_state_sp_groups.py
+++ b/tests/diffusion/distributed/test_parallel_state_sp_groups.py
@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""Unit tests for SP subgroup construction in parallel_state.py."""
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Unit tests for SP subgroup construction for diffusion parallel state."""
 
 from __future__ import annotations
 
@@ -8,12 +8,55 @@
 
 import pytest
 import torch
+import vllm.distributed.parallel_state as vllm_parallel_state
 
+from tests.helpers.runtime import get_distributed_init_method
+from vllm_omni.diffusion.distributed import parallel_state as omni_parallel_state
 from vllm_omni.diffusion.distributed.parallel_state import RankGenerator, set_seq_parallel_pg
 
 pytestmark = [pytest.mark.diffusion, pytest.mark.parallel, pytest.mark.core_model, pytest.mark.cpu]
 
 
+def ensure_parallel_state_initialized():
+    """Ensure torch distributed is initialized and that all world / count vars are set."""
+    assert torch.distributed.is_initialized()
+    assert omni_parallel_state._WORLD is not None
+    assert vllm_parallel_state._WORLD is not None
+    assert vllm_parallel_state._NODE_COUNT is not None
+
+
+def ensure_parallel_state_not_initialized():
+    """Ensure torch distributed is not initialized and that all world / count vars are unset."""
+    assert not torch.distributed.is_initialized()
+    assert omni_parallel_state._WORLD is None
+    assert vllm_parallel_state._WORLD is None
+    assert vllm_parallel_state._NODE_COUNT is None
+
+
+def test_omni_manages_vllm_distributed_state(monkeypatch):
+    """Verify Omni initializes and tears down vLLM's distributed state properly.
+
+    This is a regression test for ensuring vLLM Omni also sets up vLLM's vars correctly
+    to avoid potential misalignment in cases where Omni uses vLLM's native coordinator,
+    e.g., MoE + diffusion.
+    """
+    ensure_parallel_state_not_initialized()
+    monkeypatch.setattr(omni_parallel_state.current_omni_platform, "get_device_count", lambda: 1)
+    monkeypatch.setattr(omni_parallel_state.current_omni_platform, "set_device", lambda _device: None)
+    omni_parallel_state.init_distributed_environment(
+        world_size=1,
+        rank=0,
+        local_rank=0,
+        distributed_init_method=get_distributed_init_method(),
+        backend="gloo",
+    )
+    try:
+        ensure_parallel_state_initialized()
+    finally:
+        omni_parallel_state.destroy_distributed_env()
+    ensure_parallel_state_not_initialized()
+
+
 def _fake_new_group_factory(created_groups: list[SimpleNamespace]):
     def _fake_new_group(ranks, *args, **kwargs):
         group = SimpleNamespace(ranks=list(ranks))
diff --git a/vllm_omni/diffusion/distributed/parallel_state.py b/vllm_omni/diffusion/distributed/parallel_state.py
index 335418254db..858a2e398c9 100644
--- a/vllm_omni/diffusion/distributed/parallel_state.py
+++ b/vllm_omni/diffusion/distributed/parallel_state.py
@@ -438,6 +438,17 @@ def init_distributed_environment(
             "world group already initialized with a different world size"
         )
 
+    # Now, initialize vLLM's distributed environment; we need to do this before initializing
+    # model parallel in Omni. Otherwise, if we use vLLM's native coordinator, we may run into
+    # issues with _NODE_COUNT / _WORLD (in vLLM, not the Omni _WORLD var above) being unset.
+    vllm_parallel_state.init_distributed_environment(
+        world_size=world_size,
+        rank=rank,
+        distributed_init_method=distributed_init_method,
+        local_rank=local_rank,
+        backend=backend,
+    )
+
 
 def model_parallel_is_initialized():
     """Check if tensor and pipeline parallel groups are initialized."""
@@ -1061,8 +1072,8 @@ def destroy_distributed_environment():
     if _WORLD:
         _WORLD.destroy()
     _WORLD = None
-    if torch.distributed.is_initialized():
-        torch.distributed.destroy_process_group()
+    # We only need to destroy / clear the Omni world; this takes care of the torch process groups
+    vllm_parallel_state.destroy_distributed_environment()
 
 
 def destroy_distributed_env():

From f8197e120f8361b3e951f60e95b3ea0ac938928e Mon Sep 17 00:00:00 2001
From: Anjie Hou <149605198+specture724@users.noreply.github.com>
Date: Fri, 18 Sep 2026 09:27:56 +0800
Subject: [PATCH 078/105] [5/N] Schedule chunk transfers as their own stage
 (#7406)

Signed-off-by: specture724 <specture724@gmail.com>
---
 .../minimax_h3/test_minimax_h3_contract.py    |   8 +-
 .../models/wan2_2/test_wan22_chunked_mp4.py   |   4 +-
 .../models/wan2_2/test_wan22_s2v_pipeline.py  |   7 +-
 .../diffusion/utils/test_chunked_transfer.py  | 261 ++++++++++++
 vllm_omni/diffusion/utils/chunked_video.py    | 394 ++++++++++++++++--
 vllm_omni/diffusion/utils/media_utils.py      |  83 +++-
 6 files changed, 702 insertions(+), 55 deletions(-)
 create mode 100644 tests/diffusion/utils/test_chunked_transfer.py

diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
index 7d2d8715f78..4e261b3e24d 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_contract.py
@@ -2859,8 +2859,10 @@ def __init__(self, **kwargs):
             self.kwargs = kwargs
             self.__class__.instances.append(self)
 
-        def push(self, frames):
+        def push(self, frames, *, on_consumed=None):
             self.pushes.append(np.array(frames, copy=True))
+            if on_consumed is not None:
+                on_consumed()
 
         def finish(self):
             return b"mp4"
@@ -2986,8 +2988,10 @@ def __init__(self, **kwargs):
             self.kwargs = kwargs
             self.__class__.instances.append(self)
 
-        def push(self, frames):
+        def push(self, frames, *, on_consumed=None):
             del frames
+            if on_consumed is not None:
+                on_consumed()
 
         def finish(self):
             return b"mp4"
diff --git a/tests/diffusion/models/wan2_2/test_wan22_chunked_mp4.py b/tests/diffusion/models/wan2_2/test_wan22_chunked_mp4.py
index a919d1727fb..2855bf6fb96 100644
--- a/tests/diffusion/models/wan2_2/test_wan22_chunked_mp4.py
+++ b/tests/diffusion/models/wan2_2/test_wan22_chunked_mp4.py
@@ -138,13 +138,13 @@ def test_request_batch_threshold_controls_transfers_without_losing_frames(monkey
     from vllm_omni.diffusion.utils import chunked_video
 
     transfers = []
-    quantize = chunked_video.chunk_to_uint8_frames
+    quantize = chunked_video.quantize_chunk
 
     def capture(chunk, value_range):
         transfers.append(chunk.shape[2])
         return quantize(chunk, value_range)
 
-    monkeypatch.setattr(chunked_video, "chunk_to_uint8_frames", capture)
+    monkeypatch.setattr(chunked_video, "quantize_chunk", capture)
     params = SimpleNamespace(extra_args={"preencode_mp4": True, "preencode_batch_frames": value})
     vae = _FakeWanVAE(batch=1, chunks=4, frames_per_chunk=3, height=16, width=32)
     videos = decode_to_mp4(vae, torch.zeros(1), fps=24, batch_frames=resolve_wan_preencode_batch_frames(params))
diff --git a/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py b/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
index ab8cd132c88..a36f3a6a592 100644
--- a/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
+++ b/tests/diffusion/models/wan2_2/test_wan22_s2v_pipeline.py
@@ -2,6 +2,7 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 from types import SimpleNamespace
+from typing import Any
 from unittest.mock import MagicMock, patch
 
 import numpy as np
@@ -43,7 +44,7 @@ def init_components(pipeline, *args):
 
 
 def _make_s2v_sampling(**overrides):
-    values: dict[str, object] = {
+    values: dict[str, Any] = {
         "height": 16,
         "width": 16,
         "num_frames": 8,
@@ -749,13 +750,13 @@ def test_s2v_preencode_returns_playable_mp4_bytes_per_request(monkeypatch, batch
     from vllm_omni.diffusion.utils import chunked_video
 
     transfers = []
-    quantize = chunked_video.chunk_to_uint8_frames
+    quantize = chunked_video.quantize_chunk
 
     def capture(chunk, value_range):
         transfers.append(chunk.shape[2])
         return quantize(chunk, value_range)
 
-    monkeypatch.setattr(chunked_video, "chunk_to_uint8_frames", capture)
+    monkeypatch.setattr(chunked_video, "quantize_chunk", capture)
 
     with patch("vllm_omni.diffusion.models.wan2_2.pipeline_wan2_2_s2v.current_omni_platform") as platform:
         platform.is_available.return_value = False
diff --git a/tests/diffusion/utils/test_chunked_transfer.py b/tests/diffusion/utils/test_chunked_transfer.py
new file mode 100644
index 00000000000..1a8c52eb5a9
--- /dev/null
+++ b/tests/diffusion/utils/test_chunked_transfer.py
@@ -0,0 +1,261 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Ownership and backpressure contract for chunk transfers to the host.
+
+The ring hands a chunk one reusable host slot for its whole trip. Getting the
+release point wrong is silent: a slot reused while its copy is still landing,
+or while an encoder still holds a view of it, corrupts frames rather than
+raising. These cover the release point, the backpressure it creates, and the
+escape path out of a wait.
+"""
+
+from __future__ import annotations
+
+import threading
+
+import numpy as np
+import pytest
+import torch
+
+from tests.helpers.mark import hardware_test
+from vllm_omni.diffusion.utils.chunked_video import (
+    ChunkedVideoMP4Session,
+    ChunkLease,
+    PinnedChunkRing,
+    quantize_chunk,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
+
+
+def _frames(value: int = 7, *, batch: int = 1) -> torch.Tensor:
+    """One quantized ``BTHWC`` chunk, the shape the ring transfers."""
+    return torch.full((batch, 2, 4, 6, 3), value, dtype=torch.uint8)
+
+
+def _cpu_ring(depth: int) -> PinnedChunkRing:
+    return PinnedChunkRing(depth=depth, device=torch.device("cpu"))
+
+
+def test_slot_returns_only_after_its_last_reader():
+    """Each batch entry reads the same buffer, so one release must not free it."""
+    ring = _cpu_ring(2)
+    lease = ring.transfer(_frames(batch=3), readers=3)
+
+    assert ring.slots_in_use == 1
+    view = lease.wait()
+    assert view.shape == (3, 2, 4, 6, 3)
+    # Waiting is not consuming: an encoder still holds a view of this buffer.
+    assert ring.slots_in_use == 1
+
+    lease.release()
+    lease.release()
+    assert ring.slots_in_use == 1
+
+    lease.release()
+    assert ring.slots_in_use == 0
+    # A late extra release must not free the slot a second time.
+    lease.release()
+    assert ring.slots_in_use == 0
+
+
+def test_transfer_waits_for_a_slot_instead_of_growing_the_pool():
+    """Depth is the bound on in-flight host buffers, so a full ring blocks."""
+    ring = _cpu_ring(1)
+    held = ring.transfer(_frames(1), readers=1)
+    second: list[object] = []
+
+    def take_a_slot() -> None:
+        second.append(ring.transfer(_frames(2), readers=1))
+
+    waiter = threading.Thread(target=take_a_slot)
+    waiter.start()
+    waiter.join(timeout=0.3)
+    assert waiter.is_alive(), "a full ring must not hand out a second slot"
+
+    held.wait()
+    held.release()
+    waiter.join(timeout=5)
+    assert not waiter.is_alive()
+    assert ring.slots_in_use == 1
+    assert ring.stats.slot_wait_seconds > 0
+
+
+def test_abort_wakes_a_transfer_waiting_for_a_slot():
+    """A dead consumer must surface as an error, not as a stuck producer."""
+    ring = _cpu_ring(1)
+    ring.transfer(_frames(), readers=1)
+    failures: list[BaseException] = []
+
+    def take_a_slot() -> None:
+        try:
+            ring.transfer(_frames(), readers=1)
+        except BaseException as exc:  # noqa: BLE001
+            failures.append(exc)
+
+    waiter = threading.Thread(target=take_a_slot)
+    waiter.start()
+    waiter.join(timeout=0.3)
+    assert waiter.is_alive()
+
+    ring.abort(RuntimeError("encoder died"))
+    waiter.join(timeout=5)
+    assert [str(exc) for exc in failures] == ["encoder died"]
+    # Later transfers stay failed rather than silently resuming.
+    with pytest.raises(RuntimeError, match="encoder died"):
+        ring.transfer(_frames(), readers=1)
+
+
+def test_encoder_releases_the_chunk_it_was_reading_when_muxing_fails(monkeypatch):
+    """A failed mux abandons the frame generator, which still owns a lent slot."""
+    from vllm_omni.diffusion.utils import media_utils
+
+    released: list[int] = []
+
+    def exploding_mux(frames, **kwargs):
+        # Read into the chunk, so the generator is suspended inside it.
+        next(iter(frames))
+        raise RuntimeError("mux failed")
+
+    monkeypatch.setattr(media_utils, "mux_av_video_audio_bytes", exploding_mux)
+    encoder = media_utils.ChunkedMP4Encoder(width=6, height=4, fps=24)
+    encoder.push(np.zeros((2, 4, 6, 3), dtype=np.uint8), on_consumed=lambda: released.append(1))
+
+    with pytest.raises(RuntimeError, match="mux failed"):
+        encoder.finish()
+
+    assert released == [1], "the abandoned generator must not keep holding its chunk"
+
+
+class _RecordingEncoder:
+    """Stands in for one batch entry's encoder, honouring the release contract."""
+
+    instances: list[_RecordingEncoder] = []
+
+    def __init__(self, **kwargs):
+        self.pushes: list[int] = []
+        self.released = 0
+        self.fail_on_push = False
+        self.__class__.instances.append(self)
+
+    def push(self, frames, *, on_consumed=None):
+        if self.fail_on_push:
+            if on_consumed is not None:
+                on_consumed()
+                self.released += 1
+            raise RuntimeError("encoder rejected the chunk")
+        self.pushes.append(int(frames[0, 0, 0, 0]))
+        if on_consumed is not None:
+            on_consumed()
+            self.released += 1
+
+    def finish(self) -> bytes:
+        return b"mp4"
+
+    def abort(self) -> None:
+        return None
+
+
+@pytest.fixture
+def recording_encoders(monkeypatch):
+    _RecordingEncoder.instances = []
+    monkeypatch.setattr(
+        "vllm_omni.diffusion.utils.chunked_video.ChunkedMP4Encoder",
+        _RecordingEncoder,
+    )
+    return _RecordingEncoder.instances
+
+
+def _push_ramp(session: ChunkedVideoMP4Session, values: list[int]) -> None:
+    for value in values:
+        session.push(torch.full((1, 3, 1, 4, 6), value / 255.0))
+
+
+def test_session_feeds_chunks_in_producer_order(recording_encoders):
+    """Copies complete in issue order, and the encoder must see that order."""
+    session = ChunkedVideoMP4Session(value_range=(0.0, 1.0), fps=24)
+    _push_ramp(session, [10, 20, 30, 40])
+
+    assert session.finish() == [b"mp4"]
+    assert recording_encoders[0].pushes == [10, 20, 30, 40]
+
+
+def test_session_returns_the_slot_when_an_encoder_rejects_a_chunk(recording_encoders):
+    """A rejected chunk must not strand the buffer it was lent."""
+    session = ChunkedVideoMP4Session(value_range=(0.0, 1.0), fps=24, transfer_slots=1)
+    session.push(torch.zeros(1, 3, 1, 4, 6))
+    recording_encoders[0].fail_on_push = True
+
+    with pytest.raises(RuntimeError, match="rejected"):
+        session.push(torch.zeros(1, 3, 1, 4, 6))
+
+    assert session.ring is not None
+    assert session.ring.slots_in_use == 0
+
+
+def test_session_abort_releases_every_slot_still_in_flight(recording_encoders):
+    """Teardown returns the pool even when nothing consumed the chunks."""
+    session = ChunkedVideoMP4Session(value_range=(0.0, 1.0), fps=24, transfer_slots=2)
+    session.push(torch.zeros(1, 3, 1, 4, 6))
+
+    session.abort()
+
+    assert session.ring is not None
+    assert session.ring.slots_in_use == 0
+
+
+def test_session_gets_its_slot_back_after_a_real_encoder_failure():
+    """A real libx264 error must not strand the producer on the slot it lent."""
+    session = ChunkedVideoMP4Session(
+        value_range=(0.0, 1.0),
+        fps=24,
+        transfer_slots=1,
+        video_codec_options={"preset": "invalid-preset"},
+    )
+    failures: list[BaseException] = []
+
+    def produce() -> None:
+        try:
+            for _ in range(4):
+                session.push(torch.zeros(1, 3, 1, 16, 16))
+            session.finish()
+        except BaseException as exc:  # noqa: BLE001
+            failures.append(exc)
+
+    producer = threading.Thread(target=produce, daemon=True)
+    producer.start()
+    producer.join(timeout=30)
+    # With one slot, a lease the failed encoder never released leaves the
+    # producer waiting on the ring forever instead of seeing the codec error.
+    assert not producer.is_alive(), "the producer stalled on a slot the failed encoder kept"
+    assert len(failures) == 1
+
+    session.abort()
+    assert session.ring is not None
+    assert session.ring.slots_in_use == 0
+
+
+@hardware_test(res={"cuda": ["H100", "B200"]})
+def test_device_chunks_land_intact_through_the_pinned_ring():
+    """On an accelerator the copy is deferred, so its event must order the read."""
+    if not torch.accelerator.is_available():
+        pytest.skip("no accelerator available")
+
+    device = torch.device(torch.accelerator.current_accelerator().type, 0)
+    ring = PinnedChunkRing(depth=2, device=device)
+    pending: list[tuple[int, ChunkLease]] = []
+    for step in range(6):
+        value = 10 * step + 1
+        # Quantize on the compute stream immediately before handing the chunk
+        # over: without the source-ready event the copy would race this work.
+        chunk = torch.full((1, 3, 2, 4, 6), value / 255.0, device=device)
+        pending.append((value, ring.transfer(quantize_chunk(chunk, (0.0, 1.0)), readers=1)))
+        if len(pending) == 2:
+            for expected, lease in pending:
+                assert int(lease.wait()[0, 0, 0, 0, 0]) == expected
+                lease.release()
+            pending.clear()
+
+    assert ring.stats.transfers == 6
+    assert ring.stats.peak_slots_in_use == 2
+    assert ring.stats.peak_pending_bytes == 2 * 2 * 4 * 6 * 3
diff --git a/vllm_omni/diffusion/utils/chunked_video.py b/vllm_omni/diffusion/utils/chunked_video.py
index 79ceeab8c86..57b6d2f82f3 100644
--- a/vllm_omni/diffusion/utils/chunked_video.py
+++ b/vllm_omni/diffusion/utils/chunked_video.py
@@ -10,41 +10,293 @@
 publish finished chunks -- :class:`SupportsChunkedVAEDecode` for producers that
 can be driven, :class:`ChunkedVideoMP4Session` for producers that drive
 themselves.
+
+The move to the host runs as its own scheduled stage. A chunk is quantized on
+the accelerator, copied without blocking into one of a fixed number of reusable
+pinned host slots on a dedicated stream, and only read once its copy-completion
+event has fired. The producer therefore returns to decoding while the copy is
+still in flight, and the slot count bounds how many chunks can be in flight at
+once.
 """
 
 from __future__ import annotations
 
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Any
 
 import numpy as np
 import torch
+from vllm.logger import init_logger
 
 from vllm_omni.diffusion.models.interface import supports_chunked_vae_decode
 from vllm_omni.diffusion.utils.media_utils import ChunkedMP4Encoder
 
+logger = init_logger(__name__)
+
+# Re-checked while waiting for a slot so an abort recorded without a notify
+# still wakes the producer.
+_SLOT_POLL_SECONDS = 0.05
+
+_COPY_STREAMS: dict[tuple[str, int], torch.Stream] = {}
+_COPY_STREAM_LOCK = threading.Lock()
+
+
+def _copy_stream(device: torch.device) -> torch.Stream:
+    """Return the process-wide chunk-copy stream for ``device``.
+
+    One stream per device rather than one per request: copies are issued in
+    order on it anyway, and a stream per request would churn accelerator
+    resources for no ordering benefit.
+    """
+    with _COPY_STREAM_LOCK:
+        key = (device.type, device.index or 0)
+        stream = _COPY_STREAMS.get(key)
+        if stream is None:
+            stream = torch.Stream(device=device)
+            _COPY_STREAMS[key] = stream
+        return stream
 
-def chunk_to_uint8_frames(chunk: torch.Tensor, value_range: tuple[float, float]) -> np.ndarray:
-    """Quantize a ``BCTHW`` chunk to ``BTHWC`` uint8, transferring once.
+
+def quantize_chunk(chunk: torch.Tensor, value_range: tuple[float, float]) -> torch.Tensor:
+    """Quantize a ``BCTHW`` chunk to contiguous ``BTHWC`` uint8 on its own device.
 
     ``value_range`` is the interval the producer publishes, which differs per
     checkpoint (see ``SupportsChunkedVAEDecode.chunk_value_range``). Quantizing
-    on the accelerator means one transfer moves the final bytes rather than
-    float frames.
-
-    That transfer is synchronous: ``.cpu()`` blocks inside the producer's chunk
-    callback, so what overlaps the remaining decode today is the CPU H.264
-    encode of earlier chunks, not this copy. Splitting device preparation,
-    device-to-host copy, and encode into three independently scheduled stages --
-    a pool of reusable pinned host slots with non-blocking copies on a dedicated
-    stream, leases released by the encoder -- fits behind this same callback
-    contract, but is not implemented here.
+    on the accelerator means the transfer that follows moves the final bytes
+    rather than float frames, and making the result contiguous there keeps the
+    copy a single flat move instead of a strided host-side gather.
     """
     low, high = float(value_range[0]), float(value_range[1])
     if high <= low:
         raise ValueError(f"value_range must be increasing, got {value_range!r}")
     scale = 255.0 / (high - low)
     frames = chunk.clamp(low, high).sub(low).mul(scale).round().to(torch.uint8)
-    return frames.permute(0, 2, 3, 4, 1).cpu().numpy()
+    return frames.permute(0, 2, 3, 4, 1).contiguous()
+
+
+def chunk_to_uint8_frames(chunk: torch.Tensor, value_range: tuple[float, float]) -> np.ndarray:
+    """Quantize a ``BCTHW`` chunk and block until it reaches the host.
+
+    The path a session takes when no pinned ring is available, and the one a
+    caller outside a session gets. A session on an accelerator uses
+    :class:`PinnedChunkRing` instead so the copy does not stall the producer.
+    """
+    return quantize_chunk(chunk, value_range).cpu().numpy()
+
+
+@dataclass
+class ChunkTransferStats:
+    """What the host transfer cost, for checking that it actually overlapped.
+
+    ``copy_wait_seconds`` staying near zero while ``transfers`` climbs is the
+    signal that copies completed behind the producer; it rising with them means
+    the producer is outrunning the copy stream. ``slot_wait_seconds`` rising
+    instead means the encoder is the bottleneck and backpressure has reached
+    the producer.
+    """
+
+    transfers: int = 0
+    slot_wait_seconds: float = 0.0
+    copy_wait_seconds: float = 0.0
+    peak_slots_in_use: int = 0
+    peak_pending_bytes: int = 0
+
+
+class _HostSlot:
+    """One reusable pinned host buffer.
+
+    The buffer is allocated on first use and never shrinks. ``batch_frames`` is
+    a flush threshold rather than a cap, so a later batch can be larger than
+    the first; the slot then keeps the larger buffer for the rest of the
+    request instead of reallocating per chunk.
+    """
+
+    def __init__(self, *, pinned: bool) -> None:
+        self._pinned = pinned
+        self._buffer: torch.Tensor | None = None
+        self.held_bytes = 0
+
+    def reserve(self, frames: torch.Tensor) -> torch.Tensor:
+        """Return a host view shaped like ``frames``, growing the buffer if needed."""
+        needed = frames.numel()
+        if self._buffer is None or self._buffer.numel() < needed:
+            try:
+                self._buffer = torch.empty(needed, dtype=frames.dtype, pin_memory=self._pinned)
+            except Exception:
+                # Pinning can be refused by the driver or unsupported on a
+                # platform. A pageable buffer still copies correctly, only
+                # synchronously, so degrade rather than fail the request.
+                logger.warning("Pinned host buffer unavailable; chunk copies fall back to pageable memory")
+                self._pinned = False
+                self._buffer = torch.empty(needed, dtype=frames.dtype)
+        self.held_bytes = needed * frames.element_size()
+        return self._buffer[:needed].view(frames.shape)
+
+
+class ChunkLease:
+    """One chunk in flight: a host slot, its copy event, and its readers.
+
+    The slot returns to the ring only after the last reader has finished with
+    it. Being handed to an encoder is not enough -- the encoder's queue holds a
+    view of this buffer until its muxing thread reads it -- so release is
+    driven by the encoder rather than by dequeuing.
+    """
+
+    def __init__(
+        self,
+        *,
+        ring: PinnedChunkRing,
+        slot: _HostSlot,
+        view: np.ndarray,
+        source: torch.Tensor,
+        landed: torch.Event | None,
+        readers: int,
+    ) -> None:
+        self._ring = ring
+        self._slot = slot
+        self._view = view
+        self._source: torch.Tensor | None = source
+        self._landed = landed
+        self._readers = readers
+        self._lock = threading.Lock()
+
+    def ready(self) -> bool:
+        """Whether the copy has landed, without blocking on it."""
+        return self._landed is None or self._landed.query()
+
+    def wait(self) -> np.ndarray:
+        """Block until the copy has landed, then hand over the host frames."""
+        if self._landed is not None:
+            started = time.perf_counter()
+            self._landed.synchronize()
+            self._ring.stats.copy_wait_seconds += time.perf_counter() - started
+            self._landed = None
+        # The source stays referenced until here so the allocator cannot hand
+        # its device memory to the next chunk while the copy is still reading.
+        self._source = None
+        return self._view
+
+    def release(self) -> None:
+        """Report one reader done; the last one returns the slot to the ring."""
+        with self._lock:
+            if self._readers <= 0:
+                return
+            self._readers -= 1
+            if self._readers > 0:
+                return
+        self._ring.reclaim(self._slot)
+
+    def discard(self) -> None:
+        """Drop an unread chunk during teardown, keeping the copy's memory alive.
+
+        The copy may still be writing into the slot and reading from the source
+        tensor, so this waits for it rather than letting either be reused
+        underneath an in-flight transfer.
+        """
+        if self._landed is not None:
+            self._landed.synchronize()
+            self._landed = None
+        self._source = None
+        with self._lock:
+            remaining, self._readers = self._readers, 0
+        if remaining > 0:
+            self._ring.reclaim(self._slot)
+
+
+class PinnedChunkRing:
+    """Fixed-depth pool of reusable host slots for chunk transfers.
+
+    A slot walks ``free -> copying -> ready -> encoding -> free`` and holds
+    exactly one chunk for that whole trip, so pending transfer bytes are
+    bounded by the depth times the largest chunk of the request. Waiting for a
+    free slot is where encoder backpressure reaches the producer.
+    """
+
+    def __init__(self, *, depth: int, device: torch.device) -> None:
+        if depth <= 0:
+            raise ValueError("transfer ring depth must be positive")
+        self.depth = depth
+        self.stats = ChunkTransferStats()
+        self._on_device = device.type != "cpu"
+        self._stream = _copy_stream(device) if self._on_device else None
+        self._lock = threading.Lock()
+        self._slot_freed = threading.Condition(self._lock)
+        self._free = [_HostSlot(pinned=self._on_device) for _ in range(depth)]
+        self._pending_bytes = 0
+        self._failure: BaseException | None = None
+
+    @property
+    def slots_in_use(self) -> int:
+        """Slots currently holding a chunk, whether copying, ready or encoding."""
+        with self._lock:
+            return self.depth - len(self._free)
+
+    def transfer(self, frames: torch.Tensor, *, readers: int) -> ChunkLease:
+        """Start one non-blocking copy of ``frames`` into a free slot."""
+        if readers <= 0:
+            raise ValueError("a transferred chunk needs at least one reader")
+        slot = self._acquire()
+        try:
+            host = slot.reserve(frames)
+            with self._lock:
+                self._pending_bytes += slot.held_bytes
+                self.stats.transfers += 1
+                self.stats.peak_pending_bytes = max(self.stats.peak_pending_bytes, self._pending_bytes)
+            landed = self._issue_copy(host, frames)
+        except BaseException:
+            self.reclaim(slot)
+            raise
+        return ChunkLease(ring=self, slot=slot, view=host.numpy(), source=frames, landed=landed, readers=readers)
+
+    def abort(self, error: BaseException | None = None) -> None:
+        """Fail every present and future wait for a slot."""
+        with self._slot_freed:
+            if self._failure is None:
+                self._failure = error or RuntimeError("chunk transfer ring aborted")
+            self._slot_freed.notify_all()
+
+    def reclaim(self, slot: _HostSlot) -> None:
+        """Return a slot whose last reader is done."""
+        with self._slot_freed:
+            self._pending_bytes -= slot.held_bytes
+            slot.held_bytes = 0
+            self._free.append(slot)
+            self._slot_freed.notify()
+
+    def _issue_copy(self, host: torch.Tensor, frames: torch.Tensor) -> torch.Event | None:
+        if self._stream is None:
+            host.copy_(frames)
+            return None
+        # The chunk was quantized on the compute stream, so the copy stream has
+        # to wait for that work before reading it.
+        source_ready = torch.Event()
+        source_ready.record()
+        self._stream.wait_event(source_ready)
+        with self._stream:
+            host.copy_(frames, non_blocking=True)
+            landed = torch.Event()
+            landed.record(self._stream)
+        return landed
+
+    def _acquire(self) -> _HostSlot:
+        started = time.perf_counter()
+        with self._slot_freed:
+            while not self._free and self._failure is None:
+                # ponytail: no request deadline yet, only an abort escape. A
+                # unified deadline across producer, slot, queue and encoder
+                # waits is RFC #6872 R4.
+                self._slot_freed.wait(timeout=_SLOT_POLL_SECONDS)
+            if self._failure is not None:
+                raise self._failure
+            slot = self._free.pop()
+            in_use = self.depth - len(self._free)
+            self.stats.peak_slots_in_use = max(self.stats.peak_slots_in_use, in_use)
+        self.stats.slot_wait_seconds += time.perf_counter() - started
+        return slot
 
 
 class ChunkedVideoMP4Session:
@@ -58,7 +310,8 @@ class ChunkedVideoMP4Session:
     silent entry), so a caller with several outputs per prompt repeats a
     request's waveform across its entries. ``batch_frames`` coalesces transfers
     for producers that publish finer than a transfer is worth; ``crop`` trims
-    the decoder's padding to the requested output size.
+    the decoder's padding to the requested output size. ``transfer_slots`` sets
+    how many chunks may be in flight to the host at once.
     """
 
     def __init__(
@@ -72,6 +325,7 @@ def __init__(
         max_pending: int = 2,
         video_codec_options: dict[str, str] | None = None,
         crop: tuple[int, int] | None = None,
+        transfer_slots: int = 2,
     ) -> None:
         if batch_frames <= 0:
             raise ValueError("batch_frames must be positive")
@@ -83,9 +337,13 @@ def __init__(
         self._max_pending = max_pending
         self._video_codec_options = video_codec_options
         self._crop = crop
+        self._transfer_slots = transfer_slots
         self._encoders: list[ChunkedMP4Encoder] = []
         self._pending: list[torch.Tensor] = []
         self._pending_frames = 0
+        self._ring: PinnedChunkRing | None = None
+        self._ring_resolved = False
+        self._inflight: deque[ChunkLease] = deque()
 
     def push(self, chunk: torch.Tensor) -> None:
         """Queue one committed ``BCTHW`` chunk."""
@@ -100,33 +358,96 @@ def push(self, chunk: torch.Tensor) -> None:
     def finish(self) -> list[bytes]:
         """Flush what is pending and return one MP4 per batch entry."""
         self._flush()
+        while self._inflight:
+            self._feed_lease(self._inflight.popleft())
         return [encoder.finish() for encoder in self._encoders]
 
     def abort(self) -> None:
+        if self._ring is not None:
+            self._ring.abort()
+        while self._inflight:
+            self._inflight.popleft().discard()
         for encoder in self._encoders:
             encoder.abort()
 
+    def transfer_stats(self) -> ChunkTransferStats | None:
+        """Per-request transfer accounting, or ``None`` if no ring was used."""
+        return None if self._ring is None else self._ring.stats
+
+    @property
+    def ring(self) -> PinnedChunkRing | None:
+        """The transfer ring this session settled on, once a chunk has flushed."""
+        return self._ring
+
     def _flush(self) -> None:
         if not self._pending:
             return
-        frames = chunk_to_uint8_frames(torch.cat(self._pending, dim=2), self._value_range)
-        if not self._encoders:
-            self._encoders = [
-                ChunkedMP4Encoder(
-                    width=frames.shape[3],
-                    height=frames.shape[2],
-                    fps=self._fps,
-                    audio_waveform=self._waveform_for(index, frames.shape[0]),
-                    audio_sample_rate=self._audio_sample_rate,
-                    max_pending=self._max_pending,
-                    video_codec_options=self._video_codec_options,
-                )
-                for index in range(frames.shape[0])
-            ]
-        for index, encoder in enumerate(self._encoders):
-            encoder.push(np.ascontiguousarray(frames[index]))
+        frames = quantize_chunk(torch.cat(self._pending, dim=2), self._value_range)
         self._pending.clear()
         self._pending_frames = 0
+        self._ensure_encoders(frames)
+        ring = self._resolve_ring(frames.device)
+        if ring is None:
+            self._feed(frames.cpu().numpy(), release=None)
+            return
+        # Free a slot before asking for one, so the ring's own wait is only
+        # ever for the encoder to catch up rather than for this loop.
+        while len(self._inflight) >= ring.depth:
+            self._feed_lease(self._inflight.popleft())
+        self._inflight.append(ring.transfer(frames, readers=len(self._encoders)))
+        while self._inflight and self._inflight[0].ready():
+            self._feed_lease(self._inflight.popleft())
+
+    def _feed_lease(self, lease: ChunkLease) -> None:
+        try:
+            self._feed(lease.wait(), release=lease.release)
+        except BaseException:
+            lease.discard()
+            raise
+
+    def _feed(self, frames: np.ndarray, *, release: Callable[[], None] | None) -> None:
+        for index, encoder in enumerate(self._encoders):
+            try:
+                encoder.push(frames[index], on_consumed=release)
+            except BaseException:
+                # push() owns the callback for the entry it was given, so only
+                # the encoders this chunk never reached still hold a reader.
+                for _ in range(len(self._encoders) - index - 1):
+                    if release is not None:
+                        release()
+                raise
+
+    def _ensure_encoders(self, frames: torch.Tensor) -> None:
+        if self._encoders:
+            return
+        self._encoders = [
+            ChunkedMP4Encoder(
+                width=int(frames.shape[3]),
+                height=int(frames.shape[2]),
+                fps=self._fps,
+                audio_waveform=self._waveform_for(index, int(frames.shape[0])),
+                audio_sample_rate=self._audio_sample_rate,
+                max_pending=self._max_pending,
+                video_codec_options=self._video_codec_options,
+            )
+            for index in range(int(frames.shape[0]))
+        ]
+
+    def _resolve_ring(self, device: torch.device) -> PinnedChunkRing | None:
+        if self._ring_resolved:
+            return self._ring
+        self._ring_resolved = True
+        if self._transfer_slots <= 0:
+            return None
+        try:
+            self._ring = PinnedChunkRing(depth=self._transfer_slots, device=device)
+        except Exception:
+            logger.warning(
+                "Pinned chunk transfers unavailable on %s; falling back to blocking copies",
+                device,
+                exc_info=True,
+            )
+        return self._ring
 
     def _waveform_for(self, index: int, batch_size: int) -> np.ndarray | None:
         if self._audio_waveforms is None:
@@ -154,7 +475,18 @@ def decode_to_mp4(vae: Any, z: torch.Tensor, **session_kwargs: Any) -> list[byte
     session = ChunkedVideoMP4Session(value_range=vae.chunk_value_range, **session_kwargs)
     try:
         vae.decode_with_chunks(z, on_chunk=session.push)
-        return session.finish()
+        videos = session.finish()
     except BaseException:
         session.abort()
         raise
+    stats = session.transfer_stats()
+    if stats is not None:
+        logger.debug(
+            "Chunked MP4 transfers=%d slot_wait=%.3fs copy_wait=%.3fs peak_slots=%d peak_bytes=%d",
+            stats.transfers,
+            stats.slot_wait_seconds,
+            stats.copy_wait_seconds,
+            stats.peak_slots_in_use,
+            stats.peak_pending_bytes,
+        )
+    return videos
diff --git a/vllm_omni/diffusion/utils/media_utils.py b/vllm_omni/diffusion/utils/media_utils.py
index b2141400c79..a53359cc82b 100644
--- a/vllm_omni/diffusion/utils/media_utils.py
+++ b/vllm_omni/diffusion/utils/media_utils.py
@@ -7,16 +7,36 @@
 import io
 import queue
 import threading
-from collections.abc import Iterable, Mapping
+from collections.abc import Callable, Iterable, Mapping
 from fractions import Fraction
-from typing import Any, cast
+from typing import Any, NamedTuple, cast
 
 import av
 import numpy as np
+from vllm.logger import init_logger
+
+logger = init_logger(__name__)
 
 _CHUNKED_MP4_DONE = object()
 
 
+class _QueuedChunk(NamedTuple):
+    """One queued chunk plus the callback that returns its buffer to its owner."""
+
+    frames: np.ndarray
+    on_consumed: Callable[[], None] | None
+
+
+def _release_chunk(on_consumed: Callable[[], None] | None) -> None:
+    """Hand a chunk's buffer back, never letting the callback wedge the worker."""
+    if on_consumed is None:
+        return
+    try:
+        on_consumed()
+    except BaseException:  # noqa: BLE001
+        logger.exception("Chunked MP4 encoder failed to release a consumed chunk")
+
+
 def normalize_preencode_batch_frames(value: Any) -> int:
     """Validate the request's MP4 transfer/encoding batch threshold."""
     if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
@@ -88,9 +108,10 @@ def __init__(
         self._state_lock = threading.Lock()
 
         def run() -> None:
+            frames = self._frames()
             try:
                 self._result = mux_av_video_audio_bytes(
-                    self._frames(),
+                    frames,
                     width=self.width,
                     height=self.height,
                     audio_waveform=audio_waveform,
@@ -103,6 +124,11 @@ def run() -> None:
                 )
             except BaseException as exc:
                 self._error = exc
+                # Closing is what runs the generator's cleanup and releases the
+                # chunk it was mid-way through. Waiting for collection would
+                # never get there: the traceback just stored on this encoder
+                # keeps the abandoned generator alive for the process's life.
+                frames.close()
                 self._drain_until_done()
 
         self._thread = threading.Thread(target=run, name="chunked-mp4", daemon=True)
@@ -110,19 +136,29 @@ def run() -> None:
 
     def _drain_until_done(self) -> None:
         # A flush/mux failure can occur after _frames consumed the sentinel.
-        if not self._input_done:
-            while self._queue.get() is not _CHUNKED_MP4_DONE:
-                pass
+        if self._input_done:
+            return
+        while True:
+            entry = self._queue.get()
+            if entry is _CHUNKED_MP4_DONE:
+                return
+            _release_chunk(cast(_QueuedChunk, entry).on_consumed)
 
     def _frames(self):
         while True:
-            chunk = self._queue.get()
-            if chunk is _CHUNKED_MP4_DONE:
+            entry = self._queue.get()
+            if entry is _CHUNKED_MP4_DONE:
                 self._input_done = True
                 return
-            assert isinstance(chunk, np.ndarray)
-            for frame_data in chunk:
-                yield av.VideoFrame.from_ndarray(frame_data, format="rgb24")
+            assert isinstance(entry, _QueuedChunk)
+            try:
+                for frame_data in entry.frames:
+                    yield av.VideoFrame.from_ndarray(frame_data, format="rgb24")
+            finally:
+                # Also runs when the muxer raises part-way through this chunk
+                # and abandons the generator, so a lent buffer is never
+                # stranded in the encoder.
+                _release_chunk(entry.on_consumed)
 
     def _validate_chunk(self, chunk: np.ndarray) -> None:
         _validate_video_chunk(chunk, width=self.width, height=self.height)
@@ -133,11 +169,22 @@ def _raise_if_failed(self) -> None:
         if self._closed:
             raise RuntimeError("ChunkedMP4Encoder is already closed")
 
-    def push(self, chunk: np.ndarray) -> None:
-        """Queue a chunk; asynchronous failures surface here or at finish()."""
-        self._validate_chunk(chunk)
-        self._raise_if_failed()
-        self._queue.put(chunk)
+    def push(self, chunk: np.ndarray, *, on_consumed: Callable[[], None] | None = None) -> None:
+        """Queue a chunk; asynchronous failures surface here or at finish().
+
+        ``on_consumed`` fires exactly once after this encoder has read
+        ``chunk``, including when the chunk is discarded by an abort or by a
+        failed encode. Ownership transfers on call: whether this returns or
+        raises, the callback is this encoder's responsibility, so a caller
+        lending a pooled host buffer never compensates on the error path.
+        """
+        try:
+            self._validate_chunk(chunk)
+            self._raise_if_failed()
+        except BaseException:
+            _release_chunk(on_consumed)
+            raise
+        self._queue.put(_QueuedChunk(chunk, on_consumed))
         self._raise_if_failed()
 
     def _send_done(self) -> None:
@@ -168,9 +215,11 @@ def abort(self) -> None:
                 self._aborted = True
                 while True:
                     try:
-                        self._queue.get_nowait()
+                        entry = self._queue.get_nowait()
                     except queue.Empty:
                         break
+                    if entry is not _CHUNKED_MP4_DONE:
+                        _release_chunk(cast(_QueuedChunk, entry).on_consumed)
                 self._send_done()
         self._thread.join()
 

From 242c3cddebc8ca925f571589f660fad230c468ea Mon Sep 17 00:00:00 2001
From: Zhenqiang Xu <56525831+De-cs@users.noreply.github.com>
Date: Fri, 18 Sep 2026 09:28:27 +0800
Subject: [PATCH 079/105] [Hardware][Ascend] Integrate MindIE dense and sparse
 quantized attention for Wan2.2 T2V (#7561)

Signed-off-by: zqxu <xuzhenqiang3@huawei.com>
Co-authored-by: zqxu <xuzhenqiang3@huawei.com>
---
 .../attention_backends/rainfusion.md          |  32 ++
 docs/user_guide/quantization/overview.md      |   2 +-
 .../quantization/quantized_kvcache.md         | 105 ++++--
 .../test_mindie_public_integration.py         | 160 +++++++++
 .../attention/test_mindie_runtime.py          | 319 ++++++++++++++++++
 .../attention/test_rainfusion_plan.py         |  29 +-
 .../wan2_2/test_wan22_mindie_metadata.py      |  40 +++
 .../platforms/npu/quant/test_kv_quant_npu.py  | 182 ++--------
 .../attention/backends/flash_attn.py          |  88 +++--
 .../attention/backends/rainfusion_attn.py     |  78 +++--
 vllm_omni/diffusion/attention/layer.py        |  31 +-
 vllm_omni/diffusion/data.py                   |   7 +-
 .../models/wan2_2/wan2_2_transformer.py       |  17 +-
 vllm_omni/entrypoints/cli/serve.py            |   3 +-
 vllm_omni/platforms/npu/quant/kv_quant_npu.py | 134 +-------
 15 files changed, 856 insertions(+), 371 deletions(-)
 create mode 100644 tests/diffusion/attention/test_mindie_public_integration.py
 create mode 100644 tests/diffusion/attention/test_mindie_runtime.py
 create mode 100644 tests/diffusion/models/wan2_2/test_wan22_mindie_metadata.py

diff --git a/docs/user_guide/diffusion/attention_backends/rainfusion.md b/docs/user_guide/diffusion/attention_backends/rainfusion.md
index 00f4e37a185..1d91cabfa3f 100644
--- a/docs/user_guide/diffusion/attention_backends/rainfusion.md
+++ b/docs/user_guide/diffusion/attention_backends/rainfusion.md
@@ -78,3 +78,35 @@ Protected video tails require a compatible MindIE-SD release.
 For common configuration and selector behavior, see the
 [attention backend overview](../attention_backends.md) and the
 [backend selection design](../../../design/feature/attention_backend_selection.md).
+
+## Wan2.2 T2V quantization on Ascend
+
+`RAINFUSION_ATTN` accepts `diffusion_kv_cache_dtype: fp8` or `mxfp4` for
+Wan2.2 T2V A14B.
+MindIE-SD must expose `sparse_attention` with `rf_v3` and an explicit `precision`
+argument. Omni passes the selected precision directly to this API; the installed
+native operators must support that precision. Unsupported inputs or an
+incompatible Python API raise an actionable error; Omni does not change BSA
+precision automatically. Update `diffusion_kv_cache_dtype` to a precision
+supported by the installed MindIE-SD, or unset it. Native execution errors also
+propagate without retry.
+BSA FP8 and MXFP4 retain MindIE-SD's default rotation policy.
+
+`diffusion_kv_cache_skip_layers`/`diffusion_kv_cache_skip_steps` explicitly
+select floating-point BSA and keep attention sparse. The existing `block_sparse`
+warmup/layer exclusions and short-sequence threshold instead select Dense
+attention, using the configured Dense precision. Leave `block_sparse.precision`
+at its default when using `diffusion_kv_cache_dtype` as the shared Dense/BSA
+precision setting.
+
+Configure BSA quantization in the model's existing deployment YAML with
+`backend: RAINFUSION_ATTN` and stage-level `diffusion_kv_cache_dtype: fp8` or
+`mxfp4`. The precision and skip selectors are siblings of
+`diffusion_attention_config`; they are not per-role `quant` fields.
+For 40 denoising steps, `diffusion_kv_cache_skip_steps: "0,1,38,39"` and
+`diffusion_kv_cache_skip_layers: "0,39"` are recommended starting points. These
+fixed step indices do not automatically follow a changed step count. Selected
+forwards remain floating-point BSA; unsupported BSA precision is an error rather
+than an automatic fallback. See
+[quantized attention](../../quantization/quantized_kvcache.md#wan22-t2v-quantized-attention-on-ascend)
+for the shared configuration structure and index semantics.
diff --git a/docs/user_guide/quantization/overview.md b/docs/user_guide/quantization/overview.md
index 8319077a23d..7e7452bec5a 100644
--- a/docs/user_guide/quantization/overview.md
+++ b/docs/user_guide/quantization/overview.md
@@ -13,7 +13,7 @@ For the internal architecture and backend extension points, see the
 | Mode | Guide | Description | Methods |
 | ------ | ------- | ------------- | --------- |
 | Online quantization | [Online Quantization](online.md) | vLLM-Omni computes quantized weights and scales while loading the model. | FP8 W8A8, Int8 W8A8, BitsAndBytes W4, MXFP8 W8A8, MXFP4 W4A4 |
-| Runtime attention quantization | [Quantized KV Cache](quantized_kvcache.md) | vLLM-Omni dynamically quantizes eligible diffusion Flash Attention tensors during inference. | FP8 FA |
+| Runtime attention quantization | [Quantized KV Cache](quantized_kvcache.md) | vLLM-Omni dynamically quantizes eligible diffusion attention tensors during inference. | FP8, MXFP8, MXFP4 |
 | Pre-quantized checkpoints | Method-specific guides | The checkpoint or an offline quantizer provides quantized weights and scales before serving. | ModelOpt, AutoRound, TorchAO, msModelSlim, serialized Int8, offline MXFP8, offline MXFP4 DualScale |
 
 ## Hardware Support
diff --git a/docs/user_guide/quantization/quantized_kvcache.md b/docs/user_guide/quantization/quantized_kvcache.md
index 99a90e08a38..30ba5359349 100644
--- a/docs/user_guide/quantization/quantized_kvcache.md
+++ b/docs/user_guide/quantization/quantized_kvcache.md
@@ -2,41 +2,36 @@
 
 ## Overview
 
-In DiT-based image and video generation, Flash Attention can take a large share
-of denoising time, especially for high-resolution or long-frame workloads.
-vLLM-Omni supports online FP8 quantization for eligible diffusion Flash
-Attention (FA) to reduce FA latency while keeping model weights in their
-original dtype.
-
-This feature is configured through `diffusion_kv_cache_dtype` on
-`OmniDiffusionConfig` (CLI: `--diffusion-kv-cache-dtype`). It is intentionally
-**not** the same as vLLM's `--kv-cache-dtype`, which controls autoregressive
-language-model KV cache storage and defaults to `"auto"`. Diffusion FA
-quantization uses the dedicated diffusion flags so omni serve does not inherit
-that default.
+In DiT-based image and video generation, attention can take a large share of
+denoising time, especially for high-resolution or long-frame workloads.
+vLLM-Omni supports online Q/K/V quantization for eligible diffusion attention
+paths while keeping model weights in their original dtype.
+
+Runtime attention precision is configured through `diffusion_kv_cache_dtype`
+on `OmniDiffusionConfig` (CLI: `--diffusion-kv-cache-dtype`). This setting is
+separate from vLLM's `--kv-cache-dtype`, which controls autoregressive
+language-model KV cache storage.
 
 In vLLM-Omni diffusion pipelines, this is a runtime FA path: Q/K/V tensors are
 dynamically quantized before the attention operator. It does not quantize model
 weights and is separate from [FP8 W8A8](fp8.md), [Int8 W8A8](int8.md), or
 pre-quantized checkpoint formats.
 
-If `diffusion_kv_cache_dtype` is not set, behavior is unchanged and attention
-runs in the native dtype.
+If `diffusion_kv_cache_dtype` is not set, attention runs in the native dtype.
 
 ## Hardware Support
 
-| Device | FP8 FA |
-|--------|--------|
-| Ascend NPU | ✅ |
-| NVIDIA GPU | ❌ |
-| AMD ROCm | ❌ |
-| Intel XPU | ❌ |
+| Device | Dense FP8 | Dense MXFP8/MXFP4 | BSA FP8/MXFP4 |
+|--------|------------|-------------------|----------------|
+| Ascend NPU | ✅ | ✅ | ✅ |
+| NVIDIA GPU | ❌ | ❌ | ❌ |
+| AMD ROCm | ❌ | ❌ | ❌ |
+| Intel XPU | ❌ | ❌ | ❌ |
 
 Legend: `✅` supported, `❌` unsupported.
 
-FP8 FA is currently implemented only for the NPU Flash Attention backend. Other
-backends do not support `diffusion_kv_cache_dtype="fp8"` for diffusion attention
-and fall back to native dtype execution.
+These runtime methods are implemented only by the NPU Flash Attention and BSA
+backends. Other backends reject an incompatible explicit configuration.
 
 ## Model Type Support
 
@@ -44,7 +39,7 @@ and fall back to native dtype execution.
 
 | Model | Scope | Status | Notes |
 |-------|-------|--------|-------|
-| Wan2.2 | Eligible DiT full-attention FA on Ascend NPU | Tested | Compare quality and latency against a BF16 baseline before production use |
+| Wan2.2 | Self-attention on Ascend NPU | NPU interface and T2V smoke tested | Compare quality and latency against a BF16 baseline before production use |
 | Other diffusion models | Eligible DiT full-attention FA on Ascend NPU | Not tested | You can try `diffusion_kv_cache_dtype="fp8"`; tune `diffusion_kv_cache_skip_steps` and `diffusion_kv_cache_skip_layers` when higher precision is needed |
 
 ### Multi-Stage Omni/TTS Model (Qwen3-Omni, Qwen3-TTS)
@@ -105,12 +100,13 @@ The legacy keyword aliases `kv_cache_dtype`, `kv_cache_skip_steps`, and
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `diffusion_kv_cache_dtype` | str \| None | `None` | Set to `"fp8"` to enable dynamic FP8 FA on supported attention backends |
+| `diffusion_kv_cache_dtype` | str \| None | `None` | Runtime attention method. Dense FA supports `fp8`, `mxfp8`, and `mxfp4`; BSA supports `fp8` and `mxfp4` |
 | `diffusion_kv_cache_skip_steps` | str \| None | `None` | Denoising step selector to keep in native dtype, for example `"0,1,4-6"` |
 | `diffusion_kv_cache_skip_layers` | str \| None | `None` | Transformer layer selector to keep in native dtype, for example `"0-2,10"` |
 
 Selectors use comma-separated integers and inclusive ranges. Listed steps or
-layers skip FP8 FA; all other eligible full-attention forwards use the FP8 path.
+layers run floating-point attention through the selected Dense or BSA backend;
+all other eligible forwards use `diffusion_kv_cache_dtype`.
 
 ## Validation and Notes
 
@@ -123,3 +119,60 @@ layers skip FP8 FA; all other eligible full-attention forwards use the FP8 path.
 4. Report both latency and quality results when enabling this option for a new
    model. For image or video models, include visual comparison and quantitative
    metrics when available, such as PSNR or SSIM.
+
+## Wan2.2 T2V quantized attention on Ascend
+
+Wan2.2 T2V A14B supports quantized self-attention through MindIE-SD. Model
+weights are unchanged, and model-level opt-out keeps cross-attention in its
+native dtype.
+
+| Attention path | self-attention `backend` | Supported `diffusion_kv_cache_dtype` |
+| --- | --- | --- |
+| Dense FA | `FLASH_ATTN` | `fp8`, `mxfp8`, `mxfp4` |
+| BSA | `RAINFUSION_ATTN` | `fp8`, `mxfp4` |
+
+Configure the method and fallback selectors once at the diffusion stage. The
+per-role attention config only selects the self-attention backend:
+
+```yaml
+stages:
+  - stage_id: 0
+    diffusion_kv_cache_dtype: "mxfp8"
+    diffusion_kv_cache_skip_layers: "0,39"
+    diffusion_kv_cache_skip_steps: "0,1,38,39"
+    diffusion_attention_config:
+      per_role:
+        self:
+          backend: FLASH_ATTN  # Use RAINFUSION_ATTN with fp8 or mxfp4 for BSA.
+```
+
+For 40 denoising steps, `diffusion_kv_cache_skip_steps: "0,1,38,39"` and
+`diffusion_kv_cache_skip_layers: "0,39"` are recommended starting points. Steps
+are zero-based across the complete request and do not reset when Wan switches
+transformers; layer indices are zero-based and local to each transformer.
+Selectors accept comma-separated indices and inclusive ranges such as
+`"0,3-5"`. A selected forward uses floating-point attention while preserving
+the Dense or BSA path.
+
+Unsupported precision/input combinations raise an error and must be corrected
+in the configuration; operator errors are not retried with another precision.
+
+For BSA, change the backend to `RAINFUSION_ATTN` and set
+`diffusion_kv_cache_dtype` to `fp8` or `mxfp4`.
+See [RainFusion attention](../diffusion/attention_backends/rainfusion.md) for
+sparse-path configuration and behavior.
+
+### Requirement and interface test
+
+Until these APIs are available in a MindIE-SD release, use revision
+[`8637b5333b0225381b215390fd09a8732e671cc4`](https://gitcode.com/zqxu/MindIE-SD/commit/8637b5333b0225381b215390fd09a8732e671cc4).
+Build the Python package, PyTorch plugin, and custom operators from that same
+checkout. With CANN sourced, run the NPU interface tests from the Omni checkout:
+
+```bash
+python -m pytest tests/platforms/npu/quant/test_kv_quant_npu.py \
+    -k real_npu -vv -s -o addopts=''
+```
+
+A skipped NPU test is not a pass. Validate generated video quality against a
+floating-point run with the same prompt, seed, resolution, and step count.
diff --git a/tests/diffusion/attention/test_mindie_public_integration.py b/tests/diffusion/attention/test_mindie_public_integration.py
new file mode 100644
index 00000000000..c3df5351b70
--- /dev/null
+++ b/tests/diffusion/attention/test_mindie_public_integration.py
@@ -0,0 +1,160 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Cross-repository CPU dispatch contracts, requiring the matching MindIE-SD source.
+
+Only native operators are replaced. Public adapters, rotations, layouts, padding,
+scale preparation, sequence metadata and output cropping execute their real code.
+Operator substitutes carry floating tensors; these are not numerical quantization tests.
+"""
+
+import importlib
+from types import SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+import torch
+
+from vllm_omni.diffusion.attention.backends import flash_attn, rainfusion_attn
+from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
+from vllm_omni.platforms.npu.quant.kv_quant_npu import get_quant_attention_rotation
+
+mindiesd = pytest.importorskip("mindiesd")
+torch_npu = importlib.import_module("torch_npu")
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+@pytest.mark.parametrize(
+    "precision,batch,q_len,kv_len,q_heads",
+    [
+        ("fp8", 1, 130, 130, 2),
+        ("mxfp8", 1, 130, 130, 2),
+        ("mxfp4", 1, 130, 130, 2),
+        ("mxfp8", 2, 17, 8, 4),
+        ("mxfp8", 2, 8, 17, 4),
+    ],
+)
+@pytest.mark.parametrize("layout", ["BSND", "BNSD"])
+def test_omni_calls_real_dense_public_api(monkeypatch, precision, layout, batch, q_len, kv_len, q_heads):
+    assert callable(getattr(mindiesd, "quant_attention", None)), "MindIE-SD must export quant_attention"
+    monkeypatch.setattr(flash_attn, "current_omni_platform", SimpleNamespace(is_npu=lambda: True, device_name="npu"))
+    monkeypatch.setattr(flash_attn, "get_current_diffusion_config_or_none", lambda: None)
+    quantized_inputs = []
+
+    def dynamic_quant(tensor, **kwargs):
+        quantized_inputs.append((tensor.clone(), kwargs))
+        shape = list(tensor.shape)
+        axis = kwargs.get("axis", -1)
+        shape[axis] = max(1, shape[axis] // 32)
+        return tensor, torch.ones(shape, dtype=torch.uint8)
+
+    monkeypatch.setattr(torch_npu, "npu_dynamic_block_quant", dynamic_quant, raising=False)
+    monkeypatch.setattr(torch_npu, "npu_dynamic_mx_quant", dynamic_quant, raising=False)
+    execute = Mock(side_effect=lambda query, *args, **kwargs: (query, None))
+    metadata = Mock(return_value=torch.zeros(1, dtype=torch.int32))
+    if precision == "fp8":
+        monkeypatch.setattr(torch.ops.mindiesd, "fused_infer_attention_score_v2", execute, raising=False)
+    elif precision == "mxfp8":
+        monkeypatch.setattr(torch_npu, "npu_fused_infer_attention_score_v2", execute, raising=False)
+    else:
+        monkeypatch.setattr(torch.ops.mindiesd, "quant_flash_attn", execute, raising=False)
+        monkeypatch.setattr(torch.ops.mindiesd, "quant_flash_attn_metadata", metadata, raising=False)
+
+    query = torch.randn(batch, q_len, q_heads, 64, dtype=torch.bfloat16)
+    key = torch.randn(batch, kv_len, 2, 64, dtype=torch.bfloat16)
+    value = torch.randn_like(key)
+    if layout == "BNSD":
+        query, key, value = (tensor.transpose(1, 2) for tensor in (query, key, value))
+    impl = flash_attn.FlashAttentionImpl(
+        num_heads=q_heads,
+        head_size=64,
+        softmax_scale=0.37,
+        qkv_layout=layout,
+    )
+    output = impl.forward_npu(query, key, value, AttentionMetadata(extra={"kv_cache_dtype": precision}))
+    rotation = get_quant_attention_rotation(query.device, query.dtype, 64)
+    expected = query @ rotation
+    torch.testing.assert_close(output, expected)
+    assert output.shape == query.shape and len(quantized_inputs) == 3
+    execute.assert_called_once()
+    kwargs = execute.call_args.kwargs
+    assert kwargs["softmax_scale"] == 0.37
+    if precision == "fp8":
+        assert kwargs["input_layout"] == "BNSD"
+        assert quantized_inputs[0][0].shape == (2, 130, 64)
+        assert quantized_inputs[0][1]["row_block_size"] == 128
+    elif precision == "mxfp8":
+        args = execute.call_args.args
+        assert args[0].shape == (batch * q_len, q_heads, 64)
+        assert args[1].shape == args[2].shape == (batch * kv_len, 2, 64)
+        assert kwargs["input_layout"] == "TND"
+        assert kwargs["num_query_heads"] == q_heads and kwargs["num_key_value_heads"] == 2
+        assert kwargs["actual_seq_qlen"] == [q_len * (i + 1) for i in range(batch)]
+        assert kwargs["actual_seq_kvlen"] == [kv_len * (i + 1) for i in range(batch)]
+        assert [entry[1]["axis"] for entry in quantized_inputs] == [-1, -1, 0]
+    else:
+        seq_axis = 1 if layout == "BSND" else 2
+        assert quantized_inputs[0][0].shape[seq_axis] == 512
+        assert kwargs["seqused_q"].tolist() == kwargs["seqused_kv"].tolist() == [512]
+        assert kwargs["layout_q"] == kwargs["layout_out"] == layout
+        assert kwargs["q_dtype"] == torch_npu.float4_e2m1fn_x2
+        assert kwargs["q_descale_dtype"] == torch_npu.float8_e8m0fnu
+        assert execute.call_args.args[3].shape[:2] == (1, 2)
+        assert [entry[1]["axis"] for entry in quantized_inputs] == [-1, -1, seq_axis]
+        assert kwargs["metadata"] is metadata.return_value
+        metadata.assert_called_once()
+
+
+@pytest.mark.parametrize("precision", ["fp8", "mxfp4"])
+@pytest.mark.parametrize("length", [65, 600])
+def test_omni_calls_real_sparse_public_api(monkeypatch, precision, length):
+    rf = importlib.import_module("mindiesd.layers.flash_attn.sparse_flash_attn_rf_v3")
+    monkeypatch.setattr(flash_attn, "current_omni_platform", SimpleNamespace(is_npu=lambda: True, device_name="npu"))
+    for module in (flash_attn, rainfusion_attn):
+        monkeypatch.setattr(module, "get_current_diffusion_config_or_none", lambda: None)
+    rainfusion_attn._mindiesd_supports_precision.cache_clear()
+    monkeypatch.setattr(rf, "do_tensor_rearrange_only", lambda q, k, v, *a, **kw: (q, k, v))
+    monkeypatch.setattr(rf, "avgpool", lambda *a, **kw: torch.ones(1))
+    monkeypatch.setattr(rf, "_generate_mask_direct", lambda *a, **kw: torch.ones(1, 2, 8, 8))
+    monkeypatch.setattr(rf, "_bsa_inv_rearrange", lambda out, *a: out)
+
+    def quantize(tensor, **kwargs):
+        shape = list(tensor.shape)
+        axis = kwargs.get("axis", -1)
+        shape[axis] = max(1, shape[axis] // 32)
+        return tensor, torch.ones(shape, dtype=torch.uint8)
+
+    monkeypatch.setattr(torch_npu, "npu_dynamic_mx_quant", quantize, raising=False)
+    monkeypatch.setattr(torch_npu, "npu_dynamic_block_quant", quantize, raising=False)
+    execute = Mock(side_effect=lambda **kw: (torch.ones_like(kw["query"]), None))
+    monkeypatch.setattr(torch.ops.mindiesd, "block_sparse_attention", execute, raising=False)
+    query = torch.randn(1, length, 2, 64, dtype=torch.bfloat16)
+    impl = rainfusion_attn.RainFusionAttentionImpl(
+        num_heads=2,
+        head_size=64,
+        softmax_scale=0.37,
+        qkv_layout="BSND",
+        backend_kwargs={"sparsity": 0.8},
+    )
+    plan = rainfusion_attn.RainFusionPlan(used_len=length, prefix_len=0, latent_shape=(1, 1, length))
+    try:
+        output = impl._forward_sparse_npu(
+            query,
+            query,
+            query,
+            plan,
+            AttentionMetadata(extra={"kv_cache_dtype": precision}),
+        )
+    finally:
+        rainfusion_attn._mindiesd_supports_precision.cache_clear()
+    torch.testing.assert_close(output, torch.ones_like(query))
+    execute.assert_called_once()
+    kwargs = execute.call_args.kwargs
+    assert kwargs["actual_seq_lengths"] == kwargs["actual_seq_lengths_kv"] == [length]
+    assert kwargs["q_input_layout"] == "BNSD"
+    assert kwargs["block_sparse_mask"] is not None
+    if precision == "mxfp4":
+        assert kwargs["query"].shape[2] == (length + 63) // 64 * 64
+        assert kwargs["quant_mode"] == 2
+        assert kwargs["q_dtype"] == torch_npu.float4_e2m1fn_x2
+        assert kwargs["v_scale_dtype"] == torch_npu.float8_e8m0fnu
diff --git a/tests/diffusion/attention/test_mindie_runtime.py b/tests/diffusion/attention/test_mindie_runtime.py
new file mode 100644
index 00000000000..bd9234a5f2d
--- /dev/null
+++ b/tests/diffusion/attention/test_mindie_runtime.py
@@ -0,0 +1,319 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""CPU contract tests for MindIE adapters; no NPU kernels are mocked in production."""
+
+import sys
+from types import ModuleType, SimpleNamespace
+from unittest.mock import Mock
+
+import pytest
+import torch
+
+from vllm_omni.diffusion.attention import layer as layer_mod
+from vllm_omni.diffusion.attention.backends import flash_attn, rainfusion_attn
+from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata, VideoTokenLayout
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+_DEFAULT_SKIP_STEPS = frozenset({0, 1, 38, 39})
+
+
+@pytest.fixture
+def runtime(monkeypatch):
+    mod = ModuleType("mindiesd")
+
+    def execute(q, k, v, *, precision, layout, scale, q_rot=None, k_rot=None):
+        return q
+
+    setattr(mod, "quant_attention", Mock(side_effect=execute))
+    monkeypatch.setitem(sys.modules, mod.__name__, mod)
+    for module in (flash_attn, layer_mod):
+        monkeypatch.setattr(module, "current_omni_platform", SimpleNamespace(is_npu=lambda: True, device_name="npu"))
+    monkeypatch.setattr(flash_attn, "get_current_diffusion_config_or_none", lambda: None)
+    monkeypatch.setattr(rainfusion_attn, "get_current_diffusion_config_or_none", lambda: None)
+    monkeypatch.setattr(rainfusion_attn, "is_forward_context_available", lambda: False)
+    supports_precision = rainfusion_attn._mindiesd_supports_precision
+    supports_precision.cache_clear()
+    yield mod
+    supports_precision.cache_clear()
+
+
+def flash(layout="BSND"):
+    return flash_attn.FlashAttentionImpl(
+        num_heads=2,
+        head_size=64,
+        softmax_scale=0.37,
+        qkv_layout=layout,
+    )
+
+
+def sparse(**kwargs):
+    return rainfusion_attn.RainFusionAttentionImpl(
+        num_heads=2,
+        head_size=64,
+        softmax_scale=0.37,
+        qkv_layout="BSND",
+        backend_kwargs={"sparsity": 0.8, **kwargs},
+    )
+
+
+def video_metadata(**extra):
+    return AttentionMetadata(
+        video_layout=VideoTokenLayout(prefix_len=0, latent_grid=(4, 32, 32), used_len=4096),
+        extra={"max_seqlen_q": 4096, **extra},
+    )
+
+
+@pytest.mark.parametrize("method", ["fp8", "mxfp8", "mxfp4"])
+@pytest.mark.parametrize("layout", [None, "BSND", "BNSD"])
+def test_exact_runtime_layout_scale_and_rotation(runtime, method, layout):
+    q = torch.randn(1, 128, 2, 64, dtype=torch.bfloat16)
+    if layout == "BNSD":
+        q = q.transpose(1, 2)
+    impl = flash(layout=layout)
+    metadata = AttentionMetadata(extra={"kv_cache_dtype": method})
+    assert impl.forward_npu(q, q, q, metadata) is q
+    args, kwargs = runtime.quant_attention.call_args
+    assert args[0] is q  # no unconditional transpose or extra quantization
+    assert kwargs["layout"] == (layout or "BSND") and kwargs["scale"] == 0.37 and kwargs["precision"] == method
+    assert "attn_mask" not in kwargs
+    from vllm_omni.platforms.npu.quant.kv_quant_npu import get_quant_attention_rotation
+
+    assert kwargs["q_rot"] is kwargs["k_rot"]
+    torch.testing.assert_close(kwargs["q_rot"], get_quant_attention_rotation(q.device, q.dtype, 64))
+
+
+def test_missing_runtime_requires_config_change(runtime):
+    q = torch.randn(1, 128, 2, 64, dtype=torch.bfloat16)
+    del runtime.quant_attention
+    with pytest.raises(ImportError, match="diffusion_kv_cache_dtype"):
+        flash().forward_npu(q, q, q, AttentionMetadata(extra={"kv_cache_dtype": "mxfp4"}))
+
+
+def test_operator_failure_never_falls_back(runtime):
+    q = torch.randn(1, 128, 2, 64, dtype=torch.bfloat16)
+    runtime.quant_attention.side_effect = RuntimeError("operator failure")
+    with pytest.raises(RuntimeError, match="operator failure"):
+        flash().forward_npu(q, q, q, AttentionMetadata(extra={"kv_cache_dtype": "mxfp4"}))
+    runtime.quant_attention.assert_called_once()
+
+
+@pytest.mark.parametrize("method", ["fp8", "mxfp8", "mxfp4"])
+def test_unsupported_shape_requires_config_change(runtime, method):
+    q = torch.randn(1, 128, 2, 96, dtype=torch.bfloat16)
+    with pytest.raises(ValueError, match="diffusion_kv_cache_dtype"):
+        flash().forward_npu(q, q, q, AttentionMetadata(extra={"kv_cache_dtype": method}))
+    runtime.quant_attention.assert_not_called()
+
+
+def test_packed_metadata_never_reaches_quant_runtime(runtime):
+    q = torch.randn(1, 128, 2, 64, dtype=torch.bfloat16)
+    metadata = AttentionMetadata(extra={"kv_cache_dtype": "mxfp8", "cu_seqlens_q": torch.tensor([0, 64, 128])})
+    with pytest.raises(ValueError, match="packed/varlen"):
+        flash().forward_npu(q, q, q, metadata)
+    runtime.quant_attention.assert_not_called()
+
+
+def make_layer(runtime, monkeypatch, method="mxfp8", skip_steps=_DEFAULT_SKIP_STEPS):
+    layer = object.__new__(layer_mod.Attention)
+    torch.nn.Module.__init__(layer)
+    layer.attention = flash()
+    layer.attn_backend = flash_attn.FlashAttentionBackend
+    layer._disable_kv_quant = False
+    layer.layer_idx = 3
+    cfg = SimpleNamespace(
+        diffusion_kv_cache_dtype=method,
+        diffusion_kv_cache_skip_step_indices=skip_steps,
+        diffusion_kv_cache_skip_layer_indices=None,
+        parallel_config=SimpleNamespace(ring_degree=1),
+    )
+    layer._init_kv_cache_quantization(cfg)
+    return layer
+
+
+@pytest.mark.parametrize("method", ["fp8", "mxfp8", "mxfp4"])
+def test_global_quant_method_is_published_per_forward(runtime, monkeypatch, method):
+    layer = make_layer(runtime, monkeypatch, method=method, skip_steps=None)
+    assert layer._with_kv_cache_dtype(None).extra["kv_cache_dtype"] == method
+
+
+@pytest.mark.parametrize("method", [None, "auto", "float"])
+def test_optout_without_quant_policy_keeps_metadata_unchanged(runtime, monkeypatch, method):
+    layer = make_layer(runtime, monkeypatch)
+    layer._disable_kv_quant = True
+    layer._init_kv_cache_quantization(
+        SimpleNamespace(
+            diffusion_kv_cache_dtype=method,
+            diffusion_kv_cache_skip_step_indices=None,
+            diffusion_kv_cache_skip_layer_indices=None,
+            parallel_config=SimpleNamespace(ring_degree=1),
+        )
+    )
+    source = video_metadata()
+    assert layer._with_kv_cache_dtype(source) is source
+
+
+def test_step_skip_is_request_local_and_cross_optout(runtime, monkeypatch):
+    layer = make_layer(runtime, monkeypatch)
+    ctx = SimpleNamespace(denoise_step_idx=0)
+    monkeypatch.setattr(layer_mod, "is_forward_context_available", lambda: True)
+    monkeypatch.setattr(layer_mod, "get_forward_context", lambda: ctx)
+    source = video_metadata()
+    for step in list(range(40)) * 2:
+        ctx.denoise_step_idx = step
+        resolved = layer._with_kv_cache_dtype(source)
+        assert resolved.extra["kv_cache_dtype"] == ("float" if step in (0, 1, 38, 39) else "mxfp8")
+        assert resolved.video_layout is source.video_layout
+    assert source.extra == {"max_seqlen_q": 4096}
+    layer._disable_kv_quant = True
+    assert layer._with_kv_cache_dtype(source).extra["kv_cache_dtype"] == "float"
+
+
+def test_ring_attention_is_rejected(runtime, monkeypatch):
+    layer = make_layer(runtime, monkeypatch)
+    cfg = SimpleNamespace(diffusion_kv_cache_dtype="mxfp8", parallel_config=SimpleNamespace(ring_degree=2))
+    with pytest.raises(ValueError, match="ring"):
+        layer._init_kv_cache_quantization(cfg)
+
+
+def test_sparse_tail_steps_and_dense_quant_dispatch(runtime, monkeypatch):
+    ctx = SimpleNamespace(denoise_step_idx=49, total_denoise_steps=50)
+    monkeypatch.setattr(rainfusion_attn, "is_forward_context_available", lambda: True)
+    monkeypatch.setattr(rainfusion_attn, "get_forward_context", lambda: ctx)
+    impl = sparse(start_step=2, end_step=2)
+    metadata = video_metadata(kv_cache_dtype="fp8")
+    assert impl._resolve_plan(metadata) is None
+    q = torch.randn(1, 4096, 2, 64, dtype=torch.bfloat16)
+    impl.forward_npu(q, q, q, metadata)
+    assert runtime.quant_attention.call_args.kwargs["precision"] == "fp8"
+
+
+@pytest.mark.parametrize("method", ["fp8", "mxfp4"])
+def test_sparse_quant_uses_public_runtime(runtime, monkeypatch, method):
+    runtime.sparse_attention = Mock(side_effect=lambda q, k, v, **kwargs: q)
+    monkeypatch.setattr(rainfusion_attn, "_mindiesd_supports_precision", lambda: True)
+    q = torch.randn(1, 4224, 2, 64, dtype=torch.bfloat16)
+    out = sparse().forward_npu(q, q, q, video_metadata(kv_cache_dtype=method))
+    assert out.shape == q.shape and not out[:, 4096:].any()
+    kwargs = runtime.sparse_attention.call_args.kwargs
+    assert (kwargs["precision"], kwargs["sparse_type"], kwargs["inner_precise"]) == (method, "rf_v3", 4)
+    runtime.quant_attention.assert_not_called()
+
+
+def test_sparse_custom_mask_stays_dense(runtime):
+    metadata = AttentionMetadata(
+        attn_mask=torch.ones(1, 4096, dtype=torch.bool),
+        video_layout=VideoTokenLayout(prefix_len=0, latent_grid=(4, 32, 32)),
+        extra={"max_seqlen_q": 4096},
+    )
+    assert sparse()._resolve_plan(metadata) is None
+
+
+def test_sparse_model_padding_mask_is_equivalent_to_trimming(runtime):
+    metadata = video_metadata()
+    metadata.attn_mask = torch.arange(4224)[None] < 4096
+    assert sparse()._resolve_plan(metadata).used_len == 4096
+
+
+def test_bsa_operator_failure_never_retries(runtime, monkeypatch):
+    runtime.sparse_attention = Mock(side_effect=RuntimeError("BSA operator failure"))
+    monkeypatch.setattr(rainfusion_attn, "_mindiesd_supports_precision", lambda: True)
+    q = torch.randn(1, 4096, 2, 64, dtype=torch.bfloat16)
+    with pytest.raises(RuntimeError, match="BSA operator failure"):
+        sparse().forward_npu(q, q, q, video_metadata(kv_cache_dtype="mxfp4"))
+    runtime.sparse_attention.assert_called_once()
+
+
+@pytest.mark.parametrize(
+    "method,shape,supports_precision,error",
+    [
+        ("mxfp8", (1, 4096, 2, 64), True, "sparse mxfp8 is not supported"),
+        ("mxfp4", (1, 4096, 2, 64), False, "explicitly support precision"),
+        ("fp8", (2, 4096, 2, 64), True, "batch size 1"),
+        ("fp8", (1, 4096, 2, 32), True, "power-of-two head dimension"),
+        ("mxfp4", (1, 4096, 2, 96), True, "power-of-two head dimension"),
+    ],
+)
+def test_invalid_sparse_quant_requires_config_change(runtime, monkeypatch, method, shape, supports_precision, error):
+    runtime.sparse_attention = Mock(side_effect=lambda q, k, v, **kwargs: q)
+    monkeypatch.setattr(rainfusion_attn, "_mindiesd_supports_precision", lambda: supports_precision)
+    q = torch.randn(shape, dtype=torch.bfloat16)
+    with pytest.raises(ValueError, match=error):
+        sparse().forward_npu(q, q, q, video_metadata(kv_cache_dtype=method))
+    runtime.sparse_attention.assert_not_called()
+
+
+def test_layer_selector_requires_index_except_cross_optout(runtime, monkeypatch):
+    layer = make_layer(runtime, monkeypatch)
+    layer.layer_idx = None
+    config = SimpleNamespace(
+        diffusion_kv_cache_dtype="mxfp8",
+        diffusion_kv_cache_skip_step_indices=None,
+        diffusion_kv_cache_skip_layer_indices={0, 3},
+        parallel_config=SimpleNamespace(ring_degree=1),
+    )
+    with pytest.raises(ValueError, match="parseable transformer block index"):
+        layer._init_kv_cache_quantization(config)
+    layer._disable_kv_quant = True
+    layer._init_kv_cache_quantization(config)
+    assert layer._with_kv_cache_dtype(None).extra["kv_cache_dtype"] == "float"
+
+
+@pytest.mark.parametrize("prefix", ["transformer.blocks.3.attn1", "transformer_2.blocks.3.attn1"])
+@pytest.mark.parametrize("method", ["fp8", "mxfp4"])
+def test_expert_layer_and_step_skip_remain_sparse(runtime, monkeypatch, prefix, method):
+    def execute(q, k, v, *, precision="bf16", **kwargs):
+        return q
+
+    runtime.sparse_attention = Mock(wraps=execute)
+    monkeypatch.setattr(rainfusion_attn, "_mindiesd_supports_precision", lambda: True)
+    layer = make_layer(runtime, monkeypatch)
+    layer.layer_idx = rainfusion_attn._try_extract_layer_index(prefix)
+    assert layer.layer_idx == 3
+    config = SimpleNamespace(
+        diffusion_kv_cache_dtype=method,
+        diffusion_kv_cache_skip_step_indices={0, 1, 38, 39},
+        diffusion_kv_cache_skip_layer_indices={3},
+        parallel_config=SimpleNamespace(ring_degree=1),
+    )
+    impl = sparse()
+    layer.attention = impl
+    layer.attn_backend = rainfusion_attn.RainFusionAttentionBackend
+    layer._init_kv_cache_quantization(config)
+    ctx = SimpleNamespace(denoise_step_idx=0)
+    monkeypatch.setattr(layer_mod, "is_forward_context_available", lambda: True)
+    monkeypatch.setattr(layer_mod, "get_forward_context", lambda: ctx)
+    source = video_metadata(kv_cache_dtype="mxfp8")
+    q = torch.randn(1, 4096, 2, 64, dtype=torch.bfloat16)
+    for layer_idx, step in ((3, 0), (3, 2), (4, 0), (4, 1), (4, 2), (4, 37), (4, 38), (4, 39), (4, 0)):
+        expected = "bf16" if layer_idx == 3 or step in (0, 1, 38, 39) else method
+        layer.layer_idx = layer_idx
+        ctx.denoise_step_idx = step
+        metadata = layer._with_kv_cache_dtype(source)
+        impl.forward_npu(q, q, q, metadata)
+        assert runtime.sparse_attention.call_args.kwargs["precision"] == expected
+    runtime.quant_attention.assert_not_called()
+    assert source.extra["kv_cache_dtype"] == "mxfp8"
+
+
+def test_custom_attention_initialization_keeps_upstream_optout(monkeypatch):
+    monkeypatch.setattr(layer_mod, "get_current_diffusion_config_or_none", lambda: None)
+    monkeypatch.setattr(layer_mod, "build_parallel_attention_strategy", lambda **kw: object())
+    monkeypatch.setattr(layer_mod, "NoParallelAttention", lambda: object())
+    custom = torch.nn.Identity()
+    layer = layer_mod.Attention(
+        num_heads=2,
+        head_size=64,
+        softmax_scale=0.125,
+        causal=False,
+        custom_attention=custom,
+        skip_sequence_parallel=True,
+    )
+    assert layer.attention is custom and layer._kv_cache_dtype is None
+
+
+def test_legacy_global_fp8_uses_implicit_bsnd(runtime):
+    q = torch.randn(1, 17, 2, 64, dtype=torch.bfloat16)
+    impl = flash(layout=None)
+    assert impl.forward_npu(q, q, q, AttentionMetadata(extra={"kv_cache_dtype": "fp8"})) is q
+    assert runtime.quant_attention.call_args.kwargs["layout"] == "BSND"
+    assert runtime.quant_attention.call_args.kwargs["precision"] == "fp8"
diff --git a/tests/diffusion/attention/test_rainfusion_plan.py b/tests/diffusion/attention/test_rainfusion_plan.py
index 5b5fcc4053f..6b364f1f141 100644
--- a/tests/diffusion/attention/test_rainfusion_plan.py
+++ b/tests/diffusion/attention/test_rainfusion_plan.py
@@ -133,18 +133,17 @@ def test_invalid_ref2va_video_spans_fall_back_to_dense():
     assert make_impl()._resolve_plan(AttentionMetadata(extra={"max_seqlen_q": 12000}, video_layout=layout)) is None
 
 
-def test_validate_available_rejects_legacy_mindiesd(monkeypatch):
+def test_validate_available_accepts_single_video_mindiesd(monkeypatch):
     mindiesd = types.ModuleType("mindiesd")
 
     def sparse_attention(query, key, value, **kwargs):
         return query
 
-    mindiesd.sparse_attention = sparse_attention
+    monkeypatch.setattr(mindiesd, "sparse_attention", sparse_attention, raising=False)
     monkeypatch.setitem(sys.modules, "mindiesd", mindiesd)
     monkeypatch.setattr("importlib.util.find_spec", lambda _: object())
 
-    with pytest.raises(ValueError, match="video_spans"):
-        RainFusionAttentionBackend.validate_available()
+    RainFusionAttentionBackend.validate_available()
 
 
 def test_validate_available_accepts_new_mindiesd(monkeypatch):
@@ -153,7 +152,7 @@ def test_validate_available_accepts_new_mindiesd(monkeypatch):
     def sparse_attention(query, key, value, *, video_spans=None, **kwargs):
         return query
 
-    mindiesd.sparse_attention = sparse_attention
+    monkeypatch.setattr(mindiesd, "sparse_attention", sparse_attention, raising=False)
     monkeypatch.setitem(sys.modules, "mindiesd", mindiesd)
     monkeypatch.setattr("importlib.util.find_spec", lambda _: object())
 
@@ -300,22 +299,21 @@ def _fake_mindiesd_module():
     import types
 
     fake = types.ModuleType("mindiesd")
-    fake.sparse_attention = lambda *args, **kwargs: None
+    setattr(fake, "sparse_attention", lambda *args, **kwargs: None)
     return fake
 
 
 def test_precision_non_bf16_requires_mindiesd_support():
-    """precision != bf16 against a mindiesd lacking the kwarg must raise RuntimeError."""
+    """Unsupported sparse precision must fail before any operator executes."""
     import sys
 
     impl = make_impl(precision="mix")
-    sys.modules["mindiesd"] = _fake_mindiesd_module()
-    try:
+    with mock.patch.dict(sys.modules, {"mindiesd": _fake_mindiesd_module()}):
         with mock.patch.object(rainfusion_attn, "_mindiesd_supports_precision", return_value=False):
-            with pytest.raises(RuntimeError, match="requires MindIE-SD"):
-                impl._forward_sparse_npu(None, None, None, None)
-    finally:
-        sys.modules.pop("mindiesd", None)
+            with pytest.raises(ValueError, match="explicitly support precision"):
+                impl._forward_sparse_npu(
+                    None, None, None, RainFusionPlan(prefix_len=0, used_len=8, latent_shape=[2, 2, 2])
+                )
 
 
 def test_precision_non_bf16_passes_gate_when_supported():
@@ -323,8 +321,7 @@ def test_precision_non_bf16_passes_gate_when_supported():
     import sys
 
     impl = make_impl(precision="mix")
-    sys.modules["mindiesd"] = _fake_mindiesd_module()
-    try:
+    with mock.patch.dict(sys.modules, {"mindiesd": _fake_mindiesd_module()}):
         with mock.patch.object(rainfusion_attn, "_mindiesd_supports_precision", return_value=True):
             # q/k/v shapes: [B, S, N, D]; plan geometry must match S.
             q = torch.randn(1, 8, 4, 128)
@@ -332,5 +329,3 @@ def test_precision_non_bf16_passes_gate_when_supported():
             # The gate must pass; the fake mindiesd returns None so no crash.
             out = impl._forward_sparse_npu(q, q, q, plan)
             assert out is None
-    finally:
-        sys.modules.pop("mindiesd", None)
diff --git a/tests/diffusion/models/wan2_2/test_wan22_mindie_metadata.py b/tests/diffusion/models/wan2_2/test_wan22_mindie_metadata.py
new file mode 100644
index 00000000000..c316a207d03
--- /dev/null
+++ b/tests/diffusion/models/wan2_2/test_wan22_mindie_metadata.py
@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Wan integration contracts required by quantized dense/sparse attention."""
+
+from unittest.mock import Mock
+
+import pytest
+import torch
+
+from vllm_omni.diffusion.models.wan2_2.wan2_2_transformer import WanTransformerBlock
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+
+def test_block_publishes_unpadded_grid_without_partial_packed_metadata():
+    block = object.__new__(WanTransformerBlock)
+    torch.nn.Module.__init__(block)
+    block.scale_shift_table = torch.zeros(1, 6, 4)
+    block.norm1 = lambda x, *a: x
+    block.norm2 = lambda x: x
+    block.norm3 = lambda x, *a: x
+    block.attn1 = Mock(side_effect=lambda x, *a: torch.zeros_like(x))
+    block.attn2 = Mock(side_effect=lambda x, *a: torch.zeros_like(x))
+    block.ffn = lambda x: torch.zeros_like(x)
+    # Local SP tokens include alignment padding; grid describes the full valid video.
+    x = torch.zeros(1, 1152, 4)
+    block(
+        x,
+        x,
+        torch.zeros(1, 6, 4),
+        None,
+        hidden_states_mask=torch.ones(1, 1152, dtype=torch.bool),
+        vsa_dit_seq_shape=(5, 16, 27),
+    )
+    metadata = block.attn1.call_args.args[2]
+    assert metadata.video_layout.latent_grid == (5, 16, 27)
+    assert metadata.video_layout.used_len == 2160
+    assert metadata.video_layout.prefix_len == 0
+    assert "max_seqlen_q" not in metadata.extra  # CUDA must not infer incomplete packed varlen.
+    assert block.attn2.call_args.args[2] is None
diff --git a/tests/platforms/npu/quant/test_kv_quant_npu.py b/tests/platforms/npu/quant/test_kv_quant_npu.py
index 0c828a6a3bd..611721809d8 100644
--- a/tests/platforms/npu/quant/test_kv_quant_npu.py
+++ b/tests/platforms/npu/quant/test_kv_quant_npu.py
@@ -1,6 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""Unit tests for NPU FP8 KV quantization helpers.
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Tests for seeded rotations and the quantized NPU attention backend.
 
 These tests load ``kv_quant_npu`` from its source file via ``importlib`` so
 the test module itself does not ``import vllm_omni`` (which would pull
@@ -10,10 +10,8 @@
 from __future__ import annotations
 
 import importlib.util
-import math
 from pathlib import Path
-from types import ModuleType, SimpleNamespace
-from typing import Any
+from types import ModuleType
 
 import pytest
 import torch
@@ -61,147 +59,39 @@ def _npu_smoke_available() -> bool:
 npu_smoke = pytest.mark.skipif(not _npu_smoke_available(), reason="NPU device or torch_npu not available.")
 
 
-def test_is_quantized_kv_cache() -> None:
-    assert kv_quant_npu.is_quantized_kv_cache("fp8")
-    assert not kv_quant_npu.is_quantized_kv_cache(None)
-    assert not kv_quant_npu.is_quantized_kv_cache("int8")
-
-
-class TestKVQuantNPUUnit:
-    @pytest.fixture(autouse=True)
-    def clear_rot_cache(self):
-        kv_quant_npu._ROT_MATRIXS.clear()
-
-    def test_get_rot_matrix_caches_by_device_dtype_and_head_dim(self) -> None:
-        calls = {"count": 0}
-
-        class FakeQuaRotMode:
-            HADAMARD = "hadamard"
-
-        def fake_create_rot(mode, head_dim, seed):
-            calls["count"] += 1
-            assert mode == FakeQuaRotMode.HADAMARD
-            assert seed == 425500
-            return torch.eye(head_dim, dtype=torch.float32)
-
-        device = torch.device("cpu")
-        rot_1 = kv_quant_npu._get_rot_matrix(device, torch.float16, 8, FakeQuaRotMode, fake_create_rot)
-        rot_2 = kv_quant_npu._get_rot_matrix(device, torch.float16, 8, FakeQuaRotMode, fake_create_rot)
-        rot_3 = kv_quant_npu._get_rot_matrix(device, torch.bfloat16, 8, FakeQuaRotMode, fake_create_rot)
-        rot_4 = kv_quant_npu._get_rot_matrix(device, torch.float16, 16, FakeQuaRotMode, fake_create_rot)
-
-        assert calls["count"] == 3
-        assert rot_1 is rot_2
-        assert rot_3.dtype == torch.bfloat16
-        assert rot_4.shape == (16, 16)
-
-    @pytest.fixture
-    def fake_quant_ops(self, monkeypatch: pytest.MonkeyPatch) -> dict[str, Any]:
-        captured: dict[str, Any] = {
-            "fa_calls": [],
-            "npu_kwargs": None,
-            "out_shape": None,
-        }
-
-        class FakeTorchNPU:
-            float8_e4m3fn = "fp8_marker"
-
-            @staticmethod
-            def npu_fused_infer_attention_score_v2(q, k, v, **kwargs):
-                del q, k, v
-                captured["npu_kwargs"] = kwargs
-                out_shape = captured["out_shape"]
-                return (torch.ones(out_shape, dtype=torch.float32),)
-
-        def fake_fa_block_quant_preprocess(x, block_size, dst_type, layout):
-            captured["fa_calls"].append(
-                {
-                    "block_size": block_size,
-                    "layout": layout,
-                    "dst_type": dst_type,
-                    "shape": tuple(x.shape),
-                }
-            )
-            scale = torch.full((1,), float(block_size), dtype=torch.float32)
-            return x, scale
-
-        fake_qua_rot_mode = SimpleNamespace(HADAMARD="hadamard")
-
-        def fake_create_rot(mode, head_dim, seed):
-            assert mode == "hadamard"
-            assert seed == 425500
-            return torch.eye(head_dim, dtype=torch.float32)
-
-        monkeypatch.setattr(
-            kv_quant_npu,
-            "_load_quant_ops",
-            lambda: (FakeTorchNPU, fake_fa_block_quant_preprocess, fake_qua_rot_mode, fake_create_rot),
-        )
-
-        return captured
-
-    @staticmethod
-    def _make_qkv(shape: tuple[int, int, int, int]) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
-        query = torch.randn(*shape, dtype=torch.float32)
-        key = torch.randn(*shape, dtype=torch.float32)
-        value = torch.randn(*shape, dtype=torch.float32)
-        return query, key, value
-
-    @pytest.mark.parametrize(
-        "layout,input_shape,out_shape,softmax_scale,expected_scale",
-        [
-            ("BNSD", (2, 3, 4, 8), (2, 3, 6, 8), None, 1.0 / math.sqrt(8)),
-            ("BSND", (2, 4, 3, 8), (2, 6, 3, 8), 0.125, 0.125),
-        ],
-    )
-    def test_fp8_rotate_quant_fa_layouts_scale_and_crop(
-        self,
-        fake_quant_ops: dict[str, Any],
-        layout: str,
-        input_shape: tuple[int, int, int, int],
-        out_shape: tuple[int, int, int, int],
-        softmax_scale: float | None,
-        expected_scale: float,
-    ) -> None:
-        query, key, value = self._make_qkv(input_shape)
-        fake_quant_ops["out_shape"] = out_shape
-
-        out = kv_quant_npu.fp8_rotate_quant_fa(query, key, value, layout=layout, softmax_scale=softmax_scale)
-
-        assert out.shape == query.shape
-        assert out.dtype == query.dtype
-        assert fake_quant_ops["npu_kwargs"]["input_layout"] == layout
-        # BNSD: shape[1]==heads, BSND: shape[2]==heads.
-        expected_heads = input_shape[1] if layout == "BNSD" else input_shape[2]
-        assert fake_quant_ops["npu_kwargs"]["num_query_heads"] == expected_heads
-        assert fake_quant_ops["npu_kwargs"]["softmax_scale"] == pytest.approx(expected_scale)
-        assert [call["block_size"] for call in fake_quant_ops["fa_calls"]] == [128, 256, 256]
-
-    def test_fp8_rotate_quant_fa_invalid_layout_raises(self, fake_quant_ops) -> None:
-        query = torch.randn(1, 2, 3, 4, dtype=torch.float32)
-        key = torch.randn(1, 2, 3, 4, dtype=torch.float32)
-        value = torch.randn(1, 2, 3, 4, dtype=torch.float32)
-        fake_quant_ops["out_shape"] = (1, 2, 3, 4)
-
-        with pytest.raises(ValueError, match="unsupported layout"):
-            kv_quant_npu.fp8_rotate_quant_fa(query, key, value, layout="INVALID")
+def test_rotation_is_fixed_orthogonal_cached_and_preserves_rng():
+    kv_quant_npu.get_quant_attention_rotation.cache_clear()
+    before = torch.random.get_rng_state()
+    rot = kv_quant_npu.get_quant_attention_rotation(torch.device("cpu"), torch.float32, 64)
+    assert rot is kv_quant_npu.get_quant_attention_rotation(torch.device("cpu"), torch.float32, 64)
+    torch.testing.assert_close(rot @ rot.T, torch.eye(64))
+    assert torch.equal(before, torch.random.get_rng_state())
 
 
 @npu_smoke
-class TestKVQuantNPUSmoke:
-    """Smoke tests using real torch_npu/mindiesd stack, only on NPU."""
-
-    def test_fp8_rotate_quant_fa_real_npu_shape_contract(self):
-        try:
-            kv_quant_npu._load_quant_ops.cache_clear()
-            kv_quant_npu._load_quant_ops()
-        except ImportError:
-            pytest.skip("NPU quant dependencies are not fully installed.")
-
-        query = torch.randn(1, 2, 4, 64, dtype=torch.float16, device="npu")
-        key = torch.randn(1, 2, 4, 64, dtype=torch.float16, device="npu")
-        value = torch.randn(1, 2, 4, 64, dtype=torch.float16, device="npu")
-
-        out = kv_quant_npu.fp8_rotate_quant_fa(query, key, value, layout="BNSD")
-        assert out.shape == query.shape
-        assert out.dtype == query.dtype
+@pytest.mark.npu
+@pytest.mark.parametrize("method", ["fp8", "mxfp8", "mxfp4"])
+@pytest.mark.parametrize("layout", ["BSND", "BNSD"])
+@pytest.mark.parametrize("seq_len", [256, 75600])
+def test_dense_runtime_backend_real_npu(method, layout, seq_len):
+    from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
+    from vllm_omni.diffusion.attention.backends.flash_attn import FlashAttentionImpl
+
+    # On NPU, missing Runtime symbols must fail this qualification test.
+    query = torch.randn(1, seq_len, 2, 128, dtype=torch.bfloat16, device="npu") * 0.1
+    # Distinct constant values per head detect head/layout mixing and tail writes.
+    value = torch.tensor([0.5, -0.5], dtype=query.dtype, device=query.device)
+    value = value.view(1, 1, 2, 1).expand_as(query).contiguous()
+    if layout == "BNSD":
+        query, value = query.transpose(1, 2), value.transpose(1, 2)
+    impl = FlashAttentionImpl(
+        num_heads=2,
+        head_size=128,
+        softmax_scale=128**-0.5,
+        qkv_layout=layout,
+    )
+    metadata = AttentionMetadata(extra={"kv_cache_dtype": method})
+    out = impl.forward_npu(query, query, value, metadata)
+    assert out.shape == query.shape and out.dtype == query.dtype
+    assert torch.isfinite(out).all()
+    torch.testing.assert_close(out.float().cpu(), value.float().cpu(), rtol=0.02, atol=0.02)
diff --git a/vllm_omni/diffusion/attention/backends/flash_attn.py b/vllm_omni/diffusion/attention/backends/flash_attn.py
index d1f09b51a6b..073fd3bd56f 100644
--- a/vllm_omni/diffusion/attention/backends/flash_attn.py
+++ b/vllm_omni/diffusion/attention/backends/flash_attn.py
@@ -2,6 +2,7 @@
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 import os
+from collections.abc import Callable
 from functools import cache, partial
 
 import torch
@@ -75,18 +76,18 @@ def get_impl_cls() -> type["FlashAttentionImpl"]:
 
 
 class FlashAttentionImpl(AttentionImpl[AttentionMetadata]):
-    # Per-platform FP8 KV quantization support.
-    # To enable FP8 on a new platform, add its OmniPlatformEnum value here
+    # Per-platform attention quantization support.
+    # To enable a method on a new platform, add its OmniPlatformEnum value here
     # and handle kv_cache_dtype in the corresponding forward_{platform}().
     #
-    # TODO(quant-backend): The FP8 quant path currently lives inside
+    # TODO(quant-backend): The quantized path currently lives inside
     # FlashAttentionImpl gated by ``attn_metadata.extra["kv_cache_dtype"]``.
     # Eventually extract it into a dedicated FlashAttentionQuantBackend so
-    # backend selection (not metadata) decides quant. Until then, model
-    # authors can opt a specific Attention layer out via
+    # backend selection decides quant.
+    # Until then, model authors can opt a specific Attention layer out via
     # ``Attention(disable_kv_quant=True)``.
     _supported_kv_cache_dtypes = {
-        "npu": {"fp8"},
+        "npu": {"fp8", "mxfp8", "mxfp4"},
     }
 
     def __init__(
@@ -526,11 +527,47 @@ def forward_npu(
     ) -> torch.Tensor:
         """NPU attention implementation using mindiesd."""
 
-        kv_cache_dtype = attn_metadata.extra.get("kv_cache_dtype") if attn_metadata else None
-        if kv_cache_dtype is not None:
+        extra = attn_metadata.extra if attn_metadata else {}
+        method = extra.get("kv_cache_dtype")
+        if method not in (None, "float", "auto"):
             return self.forward_fa_quant_npu(query, key, value, attn_metadata)
         return self.forward_fa_npu(query, key, value, attn_metadata)
 
+    @staticmethod
+    def _load_quant_runtime(method: str) -> Callable[..., torch.Tensor]:
+        if method not in ("fp8", "mxfp8", "mxfp4"):
+            raise ValueError(f"Unsupported NPU attention quantization method {method!r}.")
+        from mindiesd import quant_attention
+
+        return quant_attention
+
+    def _validate_quant_request(
+        self,
+        method: str,
+        query: torch.Tensor,
+        attn_metadata: AttentionMetadata | None,
+    ) -> None:
+        extra = attn_metadata.extra if attn_metadata else {}
+        reason = None
+        if self.causal:
+            reason = "causal quantized FA is not supported"
+        elif any(name in extra for name in ("cu_seqlens_q", "cu_seqlens_k")) or extra.get("npu_attn_varlen"):
+            reason = "packed/varlen metadata requires the float attention path"
+        elif attn_metadata is not None and attn_metadata.full_attn_spans is not None:
+            reason = "piecewise attention requires the float attention path"
+        elif attn_metadata is not None and attn_metadata.attn_mask is not None:
+            reason = "caller masks require the float attention path"
+        elif method in ("fp8", "mxfp8", "mxfp4") and (
+            query.ndim != 4 or query.shape[-1] <= 0 or query.shape[-1] & (query.shape[-1] - 1)
+        ):
+            reason = "generated Hadamard rotations require a four-dimensional input and power-of-two head size"
+        if reason is not None:
+            raise ValueError(
+                f"NPU attention precision {method!r} is unavailable: {reason}. "
+                "Set diffusion_kv_cache_dtype to a supported method, or set it to "
+                "'auto'. Automatic precision fallback is not performed."
+            )
+
     def forward_fa_quant_npu(
         self,
         query: torch.Tensor,
@@ -538,18 +575,29 @@ def forward_fa_quant_npu(
         value: torch.Tensor,
         attn_metadata: AttentionMetadata | None = None,
     ) -> torch.Tensor:
-        from vllm_omni.platforms.npu.quant.kv_quant_npu import fp8_rotate_quant_fa
-
-        layout = self.qkv_layout or "BNSD"
-        # Models pass (B, S, H, D); NPU fused op expects (B, N, S, D).
-        out = fp8_rotate_quant_fa(
-            query.transpose(1, 2),
-            key.transpose(1, 2),
-            value.transpose(1, 2),
-            layout=layout,
-            softmax_scale=self.softmax_scale,
-        )
-        return out.transpose(1, 2)
+        extra = attn_metadata.extra if attn_metadata else {}
+        method = extra.get("kv_cache_dtype", "fp8")
+        layout = self.qkv_layout or "BSND"
+        self._validate_quant_request(method, query, attn_metadata)
+        try:
+            runtime = self._load_quant_runtime(method)
+        except ImportError as exc:
+            raise ImportError(
+                f"NPU attention precision {method!r} requires a compatible MindIE-SD "
+                "quant Runtime. Install a compatible MindIE-SD build, select another "
+                "diffusion_kv_cache_dtype, or set it to 'auto'. Automatic precision "
+                "fallback is not performed."
+            ) from exc
+        kwargs = dict(precision=method, layout=layout, scale=self.softmax_scale)
+        # Apply Omni's deterministic Q/K rotation before every Dense quantized path.
+        if method in ("fp8", "mxfp8", "mxfp4"):
+            from vllm_omni.platforms.npu.quant.kv_quant_npu import get_quant_attention_rotation
+
+            rotation = get_quant_attention_rotation(query.device, query.dtype, query.shape[-1])
+            kwargs.update(q_rot=rotation, k_rot=rotation)
+        logger.info_once("NPU attention uses MindIE-SD %s Runtime, layout=%s.", method, layout)
+        # Execution errors propagate. Never retry with another precision.
+        return runtime(query, key, value, **kwargs)
 
     def forward_fa_npu(
         self,
diff --git a/vllm_omni/diffusion/attention/backends/rainfusion_attn.py b/vllm_omni/diffusion/attention/backends/rainfusion_attn.py
index 9bbde02facd..24a32bd31f8 100644
--- a/vllm_omni/diffusion/attention/backends/rainfusion_attn.py
+++ b/vllm_omni/diffusion/attention/backends/rainfusion_attn.py
@@ -146,8 +146,10 @@ def validate_available(cls) -> None:
             from mindiesd import sparse_attention
         except ImportError as exc:
             raise ValueError(_MISSING_MINDIESD) from exc
-        if not _supports_video_spans(sparse_attention):
-            raise ValueError(_INCOMPATIBLE_MINDIESD)
+        if not callable(sparse_attention):
+            raise ValueError(_MISSING_MINDIESD)
+        # Single-video Wan only needs the legacy geometry. Check video_spans
+        # when a forward actually carries multiple videos.
 
     @staticmethod
     def get_supported_head_sizes() -> list[int]:
@@ -174,6 +176,8 @@ class RainFusionAttentionImpl(AttentionImpl):
     irregular video tail internally, retaining it outside the sparse blocks.
     """
 
+    _supported_kv_cache_dtypes = {"npu": {"fp8", "mxfp4"}}
+
     def __init__(
         self,
         num_heads: int,
@@ -222,6 +226,8 @@ def __init__(
     def _validate_parallel_config(self) -> None:
         config = get_current_diffusion_config_or_none()
         parallel_config = getattr(config, "parallel_config", None)
+        if getattr(parallel_config, "allgather_degree", 1) > 1:
+            raise ValueError("RAINFUSION_ATTN requires full Q/K/V sequences; AllGather-KV SP is unsupported.")
         ring_degree = getattr(parallel_config, "ring_degree", 1)
         if ring_degree > 1:
             # Ring gives each rank a slice of the sequence, so block selection
@@ -262,7 +268,9 @@ def forward_npu(
         plan = self._resolve_plan(attn_metadata)
         if plan is None:
             return self.dense_fallback.forward_npu(query, key, value, attn_metadata)
-        return self._forward_sparse_npu(query, key, value, plan)
+        if query.ndim != 4 or key.shape != query.shape or value.shape != query.shape or plan.used_len > query.shape[1]:
+            raise ValueError("RainFusion video geometry must fit identical full-sequence BSND Q/K/V tensors.")
+        return self._forward_sparse_npu(query, key, value, plan, attn_metadata)
 
     def _resolve_plan(self, attn_metadata: AttentionMetadata | None) -> RainFusionPlan | None:
         """Return the rf_v2 geometry, or None when this forward must stay dense."""
@@ -271,18 +279,17 @@ def _resolve_plan(self, attn_metadata: AttentionMetadata | None) -> RainFusionPl
             return None
         if self.layer_idx is not None and self.layer_idx in rf.skip_layers:
             return None
+        step_idx = total_steps = None
         if is_forward_context_available():
             step_idx = get_forward_context().denoise_step_idx
             total_steps = get_forward_context().total_denoise_steps
-            if step_idx is not None and step_idx < rf.start_step:
+        if (rf.start_step and step_idx is None) or (rf.end_step and (step_idx is None or total_steps is None)):
+            return None
+        if step_idx is not None:
+            if step_idx < rf.start_step:
                 return None
             # Tail fallback: keep the last ``end_step`` denoise steps dense.
-            if (
-                rf.end_step > 0
-                and step_idx is not None
-                and total_steps is not None
-                and step_idx >= total_steps - rf.end_step
-            ):
+            if rf.end_step > 0 and total_steps is not None and step_idx >= total_steps - rf.end_step:
                 return None
         if self.qkv_layout is None:
             # The sparse path reads the sequence off dim 1, which the tensors alone
@@ -308,7 +315,16 @@ def _resolve_plan(self, attn_metadata: AttentionMetadata | None) -> RainFusionPl
                 "model must publish AttentionMetadata.video_layout for the sequence to be sparsified."
             )
             return None
-        max_seqlen_q = attn_metadata.extra.get("max_seqlen_q")
+
+        # The sparse Runtime constructs its own block mask. It cannot preserve
+        # an arbitrary caller-supplied mask or piecewise visibility constraints.
+        mask = attn_metadata.attn_mask
+        padding_only = layout.used_len is not None
+        if attn_metadata.full_attn_spans is not None or (
+            mask is not None and not (padding_only and mask.ndim == 2 and mask.dtype == torch.bool)
+        ):
+            return None
+        max_seqlen_q = attn_metadata.extra.get("max_seqlen_q", layout.used_len)
         if max_seqlen_q is None:
             logger.warning_once(
                 "RAINFUSION_ATTN staying dense: attention metadata is missing max_seqlen_q, so the "
@@ -459,19 +475,39 @@ def _forward_sparse_npu(
         key: torch.Tensor,
         value: torch.Tensor,
         plan: RainFusionPlan,
+        attn_metadata: AttentionMetadata | None = None,
     ) -> torch.Tensor:
         try:
             from mindiesd import sparse_attention
         except ImportError:
             raise ImportError(_MISSING_MINDIESD)
-        if self.rainfusion.precision != "bf16" and not _mindiesd_supports_precision():
-            raise RuntimeError(
-                f"block_sparse.precision={self.rainfusion.precision!r} requires MindIE-SD "
-                "with sparse_attention(precision=...) support; the installed mindiesd "
-                "silently ignores it and would run the BF16 path. Install a compatible "
-                "MindIE-SD release or use precision='bf16'."
+        if plan.video_spans is not None and not _supports_video_spans(sparse_attention):
+            raise ValueError(_INCOMPATIBLE_MINDIESD)
+        extra = attn_metadata.extra if attn_metadata else {}
+        requested = extra.get("kv_cache_dtype", self.rainfusion.precision)
+        reason = None
+        if requested in ("float", "bf16"):
+            precision = "bf16"
+        else:
+            precision = requested
+            if requested not in ("fp8", "mxfp4", "mix"):
+                reason = f"sparse {requested} is not supported"
+            elif not _mindiesd_supports_precision():
+                reason = "MindIE-SD sparse_attention must explicitly support precision"
+            elif plan.video_spans is not None:
+                reason = "quantized multi-video RainFusion is not supported"
+            elif requested in ("fp8", "mxfp4") and query.shape[0] != 1:
+                reason = "quantized Wan BSA requires batch size 1"
+            elif requested in ("fp8", "mxfp4") and (query.shape[-1] < 64 or query.shape[-1] & (query.shape[-1] - 1)):
+                reason = "BSA Hadamard rotations require a power-of-two head dimension of at least 64"
+        if reason is not None:
+            raise ValueError(
+                f"RainFusion precision {requested!r} is unavailable: {reason}. "
+                "Set diffusion_kv_cache_dtype or block_sparse.precision to a method supported by the installed "
+                "MindIE-SD, or disable attention quantization. Automatic precision fallback is not performed."
             )
 
+        logger.info_once("RainFusion uses MindIE-SD sparse attention, precision=%s.", precision)
         used = plan.used_len
         q, k, v = (tensor[:, :used] for tensor in (query, key, value))
         # Ulysses has already gathered the full sequence onto this rank and split
@@ -480,10 +516,10 @@ def _forward_sparse_npu(
             "scale": self.softmax_scale,
             "head_num": query.shape[-2],
             "input_layout": _INPUT_LAYOUT,
-            "inner_precise": _INNER_PRECISE,
+            "inner_precise": 4 if precision != "bf16" else _INNER_PRECISE,
             "block_size": _BLOCK_SIZE,
             "sparsity": self.rainfusion.sparsity,
-            "precision": self.rainfusion.precision,
+            "precision": precision,
         }
         if plan.video_spans is not None:
             out = sparse_attention(
@@ -497,7 +533,9 @@ def _forward_sparse_npu(
         else:
             assert plan.prefix_len is not None and plan.latent_shape is not None
             common_kwargs.update(
-                sparse_type="rf_v2",
+                # rf_v2 ignores precision on non-A5 devices. Select the explicit
+                # quantized high-level path so mask/rearrangement remain in MindIE.
+                sparse_type="rf_v3" if precision != "bf16" else "rf_v2",
                 txt_len=plan.prefix_len,
                 latent_shape_q=plan.latent_shape,
                 latent_shape_k=plan.latent_shape,
diff --git a/vllm_omni/diffusion/attention/layer.py b/vllm_omni/diffusion/attention/layer.py
index 2e0b2604d4e..0ad41e80f9a 100644
--- a/vllm_omni/diffusion/attention/layer.py
+++ b/vllm_omni/diffusion/attention/layer.py
@@ -321,7 +321,7 @@ def _init_kv_cache_quantization(self, config) -> None:
             dtype = None
         parallel_config = getattr(config, "parallel_config", None)
         ring_degree = getattr(parallel_config, "ring_degree", 1)
-        if dtype:
+        if dtype and dtype != "float":
             if ring_degree > 1:
                 raise ValueError(
                     "KV quantization is not compatible with ring attention "
@@ -338,13 +338,15 @@ def _init_kv_cache_quantization(self, config) -> None:
         self._kv_cache_dtype = dtype
         self._kv_cache_skip_steps = getattr(config, "diffusion_kv_cache_skip_step_indices", None)
         self._kv_cache_skip_layers = getattr(config, "diffusion_kv_cache_skip_layer_indices", None)
+        if self._kv_cache_skip_layers and self.layer_idx is None and not self._disable_kv_quant:
+            raise ValueError("Attention quantization skip_layers requires a parseable transformer block index.")
 
     def _should_apply_kv_cache_quant(self) -> bool:
         skip_steps = self._kv_cache_skip_steps
         skip_layers = self._kv_cache_skip_layers
         if skip_steps is not None:
             step_idx = get_forward_context().denoise_step_idx if is_forward_context_available() else None
-            if step_idx is not None and step_idx in skip_steps:
+            if skip_steps and (step_idx is None or step_idx in skip_steps):
                 return False
         if skip_layers is not None:
             if self.layer_idx is not None and self.layer_idx in skip_layers:
@@ -352,18 +354,21 @@ def _should_apply_kv_cache_quant(self) -> bool:
         return True
 
     def _with_kv_cache_dtype(self, attn_metadata: AttentionMetadata | None) -> AttentionMetadata | None:
-        kv_cache_dtype = self._kv_cache_dtype
-        if kv_cache_dtype is None or self._disable_kv_quant or not self._should_apply_kv_cache_quant():
-            if attn_metadata is None or "kv_cache_dtype" not in attn_metadata.extra:
-                return attn_metadata
-            extra = dict(attn_metadata.extra)
-            extra.pop("kv_cache_dtype", None)
-            return replace(attn_metadata, extra=extra)
-
+        disabled = self._disable_kv_quant or not self._should_apply_kv_cache_quant()
+        dtype = self._kv_cache_dtype
+        if dtype in (None, "float"):
+            dtype = None
+        elif disabled:
+            dtype = "float"
+        if dtype is None and (attn_metadata is None or "kv_cache_dtype" not in attn_metadata.extra):
+            return attn_metadata
+        extra = dict(attn_metadata.extra) if attn_metadata is not None else {}
+        # Recompute per forward so shared metadata cannot retain another step's policy.
+        extra.pop("kv_cache_dtype", None)
+        if dtype is not None:
+            extra["kv_cache_dtype"] = dtype
         if attn_metadata is None:
-            return AttentionMetadata(extra={"kv_cache_dtype": kv_cache_dtype})
-        extra = dict(attn_metadata.extra)
-        extra["kv_cache_dtype"] = kv_cache_dtype
+            return AttentionMetadata(extra=extra) if extra else None
         return replace(attn_metadata, extra=extra)
 
     def forward(
diff --git a/vllm_omni/diffusion/data.py b/vllm_omni/diffusion/data.py
index 6aa1a27d95f..53714893302 100644
--- a/vllm_omni/diffusion/data.py
+++ b/vllm_omni/diffusion/data.py
@@ -1028,11 +1028,8 @@ class OmniDiffusionConfig:
     # has already resolved to vLLM's ModelOpt FP8 linear method.
     force_cutlass_fp8: bool = False
 
-    # Diffusion attention KV cache dtype (not vLLM's --kv-cache-dtype for AR models).
-    # None = native dtype (no quantization).
-    # "fp8" = dynamic FP8 (float8_e4m3fn) quantization per forward pass.
-    # On Hopper+FA3: native FP8 attention (memory + compute savings).
-    # On other backends: no benefit, backends skip quantization.
+    # Runtime diffusion attention method (not vLLM's --kv-cache-dtype for AR models).
+    # None/"auto" keeps native dtype; other values are validated by the selected backend.
     diffusion_kv_cache_dtype: str | None = None
     # Optional skip selectors for KV-cache quantization. Format: "0-9,20,25-30".
     # Listed steps/layers skip quantization; others keep quantized execution.
diff --git a/vllm_omni/diffusion/models/wan2_2/wan2_2_transformer.py b/vllm_omni/diffusion/models/wan2_2/wan2_2_transformer.py
index 2808dcee7f1..91b482ebde3 100644
--- a/vllm_omni/diffusion/models/wan2_2/wan2_2_transformer.py
+++ b/vllm_omni/diffusion/models/wan2_2/wan2_2_transformer.py
@@ -29,7 +29,7 @@
 )
 from vllm.sequence import IntermediateTensors
 
-from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
+from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata, VideoTokenLayout
 from vllm_omni.diffusion.attention.layer import Attention
 from vllm_omni.diffusion.distributed.parallel_state import (
     get_pipeline_parallel_world_size,
@@ -417,6 +417,7 @@ def __init__(
             softmax_scale=1.0 / (head_dim**0.5),
             causal=False,
             role="self",
+            qkv_layout="BSND",
             prefix=prefix,
         )
 
@@ -609,8 +610,8 @@ def __init__(
             qkv_layout="BSND",
             prefix=prefix,
             skip_sequence_parallel=True,
-            # Wan2.2 cross-attn operates on short text-encoder sequences; per-block
-            # FP8 quant offers no perf win and degrades quality. Opt out until a
+            # Wan2.2 cross-attn operates on short text-encoder sequences; runtime
+            # Q/K/V quantization offers no perf win and degrades quality. Opt out until a
             # dedicated quant backend handles this case.
             disable_kv_quant=True,
         )
@@ -764,7 +765,15 @@ def forward(
             self_attn_extra["vsa_dit_seq_shape"] = vsa_dit_seq_shape
         if preserve_vsa_all_blocks:
             self_attn_extra["preserve_vsa_all_blocks"] = True
-        self_attn_metadata = AttentionMetadata(attn_mask=hidden_states_mask, extra=self_attn_extra)
+        video_layout = None
+        if vsa_dit_seq_shape is not None:
+            grid = tuple(int(dim) for dim in vsa_dit_seq_shape)
+            # Publish geometry independently of backend selection. Do not add
+            # partial cu_seqlens/max_seqlen metadata to dense CUDA attention.
+            video_layout = VideoTokenLayout(prefix_len=0, latent_grid=grid, used_len=math.prod(grid))
+        self_attn_metadata = AttentionMetadata(
+            attn_mask=hidden_states_mask, extra=self_attn_extra, video_layout=video_layout
+        )
         attn_output = self.attn1(norm_hidden_states, rotary_emb, self_attn_metadata)
         hidden_states = (hidden_states + attn_output * gate_msa).type_as(hidden_states)
 
diff --git a/vllm_omni/entrypoints/cli/serve.py b/vllm_omni/entrypoints/cli/serve.py
index 493f2533e7b..14e13cd4a13 100644
--- a/vllm_omni/entrypoints/cli/serve.py
+++ b/vllm_omni/entrypoints/cli/serve.py
@@ -941,7 +941,8 @@ def subparser_init(self, subparsers: argparse._SubParsersAction) -> TrackingArgu
             "--diffusion-kv-cache-dtype",
             type=str,
             default=None,
-            help="Diffusion attention KV cache dtype (e.g. fp8). Separate from vLLM --kv-cache-dtype.",
+            help="Diffusion Q/K/V precision: fp8, mxfp8, mxfp4, or float (NPU). "
+            "Separate from vLLM --kv-cache-dtype. Use --diffusion-attention-config for per-role fallback.",
         )
         omni_config_group.add_argument(
             "--diffusion-kv-cache-skip-steps",
diff --git a/vllm_omni/platforms/npu/quant/kv_quant_npu.py b/vllm_omni/platforms/npu/quant/kv_quant_npu.py
index cb76aab5144..76d090a7aac 100644
--- a/vllm_omni/platforms/npu/quant/kv_quant_npu.py
+++ b/vllm_omni/platforms/npu/quant/kv_quant_npu.py
@@ -1,127 +1,25 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""FP8 quantization utilities for diffusion attention tensors.
-
-Provides per-tensor dynamic quantization of Q/K/V tensors to
-float8_e4m3fn format. Designed for diffusion models where Q/K/V are
-computed fresh each forward pass (no persistent KV cache).
-"""
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Seeded rotation matrices for MindIE-SD quantized attention."""
 
 from __future__ import annotations
 
+import functools
 import math
-import threading
-from functools import lru_cache
 
 import torch
 
-# Hadamard rotation matrix for QuaRot-style preprocessing
-# keyed by (device, dtype, head_dim) to avoid matmul dtype mismatch.
-_ROT_MATRIXS: dict[tuple[torch.device, torch.dtype, int], torch.Tensor] = {}
-_ROT_MATRIX_LOCK = threading.Lock()
-
-_FP8_KV_LABELS = frozenset({"fp8"})
-
-
-def is_quantized_kv_cache(kv_cache_dtype: str | None) -> bool:
-    """True if config requests FP8-style KV / QKV quantization for the NPU FA path."""
-    return kv_cache_dtype in _FP8_KV_LABELS
-
-
-@lru_cache(maxsize=1)
-def _load_quant_ops():
-    try:
-        import torch_npu
-        from mindiesd.layers.quant.block_quant import fa_block_quant_preprocess
-        from msmodelslim.processor.quarot.common.quarot_utils import QuaRotMode, create_rot
-    except ImportError as e:
-        raise ImportError(
-            "fp8_rotate_quant_fa requires torch_npu, MindIE-SD (mindiesd), and MSModelSlim. "
-            "See https://gitcode.com/Ascend/MindIE-SD and https://gitcode.com/Ascend/msmodelslim"
-        ) from e
-    return torch_npu, fa_block_quant_preprocess, QuaRotMode, create_rot
-
-
-def _get_rot_matrix(
-    device: torch.device,
-    dtype: torch.dtype,
-    head_dim: int,
-    qua_rot_mode,
-    create_rot,
-) -> torch.Tensor:
-    key = (device, dtype, head_dim)
-    with _ROT_MATRIX_LOCK:
-        rot = _ROT_MATRIXS.get(key)
-        if rot is None:
-            rot = create_rot(qua_rot_mode.HADAMARD, head_dim, seed=425500).to(device=device, dtype=dtype)
-            _ROT_MATRIXS[key] = rot
-    return rot
-
-
-def fp8_rotate_quant_fa(
-    query: torch.Tensor,
-    key: torch.Tensor,
-    value: torch.Tensor,
-    *,
-    layout: str = "BNSD",
-    softmax_scale: float | None = None,
-) -> torch.Tensor:
-    """Run NPU fused attention with dynamic FP8 Q/K/V and optional QuaRot preprocess.
-
-    Args:
-        query: Query tensor in ``layout`` order (default BNSD: batch, heads, seq, dim).
-        key: Key tensor in ``layout`` order (default BNSD: batch, heads, seq, dim).
-        value: Value tensor in ``layout`` order (default BNSD: batch, heads, seq, dim).
-        layout: ``BNSD`` or ``BSND`` for ``npu_fused_infer_attention_score_v2``.
-        softmax_scale: If None, uses ``1 / sqrt(head_dim)``.
-
-    Returns:
-        Attention output in the same layout as inputs.
-    """
-    torch_npu, fa_block_quant_preprocess, qua_rot_mode, create_rot = _load_quant_ops()
-
-    out_dtype = query.dtype
-    device = query.device
-
-    if layout == "BNSD":
-        _, n, s, d = query.shape
-    elif layout == "BSND":
-        _, s, n, d = query.shape
-    else:
-        raise ValueError(f"fp8_rotate_quant_fa: unsupported layout {layout!r}, expected BNSD or BSND")
-
-    rot = _get_rot_matrix(device, query.dtype, d, qua_rot_mode, create_rot)
-    q_f = torch.matmul(query, rot)
-    k_f = torch.matmul(key, rot)
-
-    q, q_scale = fa_block_quant_preprocess(q_f, block_size=128, dst_type=torch_npu.float8_e4m3fn, layout=layout)
-    k, k_scale = fa_block_quant_preprocess(k_f, block_size=256, dst_type=torch_npu.float8_e4m3fn, layout=layout)
-    v, v_scale = fa_block_quant_preprocess(value, block_size=256, dst_type=torch_npu.float8_e4m3fn, layout=layout)
-
-    scale = softmax_scale if softmax_scale is not None else 1.0 / math.sqrt(d)
-
-    out = torch_npu.npu_fused_infer_attention_score_v2(
-        q,
-        k,
-        v,
-        input_layout=layout,
-        num_query_heads=n,
-        softmax_scale=scale,
-        pre_tokens=2147483647,  # INT32_MAX: no left-context truncation.
-        next_tokens=2147483647,  # INT32_MAX: no right-context truncation.
-        query_quant_mode=7,  # NPU mode id for block FP8 dequant path.
-        key_quant_mode=7,  # Same quant mode as query branch.
-        value_quant_mode=7,  # Same quant mode as key/query branches.
-        dequant_scale_query=q_scale,
-        dequant_scale_key=k_scale,
-        dequant_scale_value=v_scale,
-        out_dtype=out_dtype,
-    )[0]
-
-    if out.shape[2] != s:
-        if layout == "BNSD":
-            out = out[:, :, :s, :]
-        elif layout == "BSND":
-            out = out[:, :s, :, :]
 
-    return out
+@functools.lru_cache(maxsize=128)
+def get_quant_attention_rotation(device: torch.device, dtype: torch.dtype, head_dim: int) -> torch.Tensor:
+    """Preserve Omni's fixed Walsh-Hadamard rotation without changing global RNG."""
+    if head_dim <= 0 or head_dim & (head_dim - 1):
+        raise ValueError("Generated attention rotations require a power-of-two head dimension.")
+    generator = torch.Generator(device="cpu").manual_seed(425500)
+    signs = torch.randint(0, 2, (head_dim,), generator=generator, dtype=torch.int64)
+    signs = signs.to(dtype=torch.float32).mul_(2).sub_(1)
+    hadamard = torch.ones(1, 1)
+    while hadamard.shape[0] < head_dim:
+        hadamard = torch.cat((torch.cat((hadamard, hadamard), dim=1), torch.cat((hadamard, -hadamard), dim=1)), dim=0)
+    rotation = signs[:, None] * hadamard / math.sqrt(head_dim)
+    return rotation.to(device=device, dtype=dtype).contiguous()

From 1c7476ec19899f1e61838e23e9fad3505403b9b9 Mon Sep 17 00:00:00 2001
From: andyluo7 <43718156+andyluo7@users.noreply.github.com>
Date: Thu, 17 Sep 2026 20:13:07 -0700
Subject: [PATCH 080/105] [CI/Build][ROCm] Stabilize shared AMD test lanes
 (#7706)

Signed-off-by: andyluo7 <andy.luo@amd.com>
Signed-off-by: haic0 <haic0@users.noreply.github.com>
Co-authored-by: haic0 <haic0@users.noreply.github.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .buildkite/amd/test-amd-merge.yml             |  16 ++-
 .buildkite/amd/test-amd-ready.yml             |  48 ++++++-
 .buildkite/amd/test-template-amd-omni.j2      |  16 +++
 .buildkite/cuda/test-ready.yml                |   6 +
 tests/buildkite/test_amd_pipeline.py          |  24 ++++
 tests/diffusion/attention/test_flash_attn.py  |  33 ++++-
 .../models/magi2/test_native_compile_cuda.py  |   3 +-
 .../e2e/offline_inference/test_qwen3_omni.py  |   4 +-
 .../cosyvoice3/test_cosyvoice3_components.py  | 112 ---------------
 .../test_cosyvoice3_components_cuda.py        | 127 ++++++++++++++++++
 .../test_cosyvoice3_incremental_hift.py       |   5 +
 .../qwen3_omni/test_qwen3_omni_embed.py       |   7 +-
 12 files changed, 275 insertions(+), 126 deletions(-)
 create mode 100644 tests/model_executor/models/cosyvoice3/test_cosyvoice3_components_cuda.py

diff --git a/.buildkite/amd/test-amd-merge.yml b/.buildkite/amd/test-amd-merge.yml
index b1b9e7ecc98..6ee36de485d 100644
--- a/.buildkite/amd/test-amd-merge.yml
+++ b/.buildkite/amd/test-amd-merge.yml
@@ -9,15 +9,26 @@ steps:
   steps:
     - label: "Simple · Model Executor Test · Shard %N/%t"
       agent_pool: mi300_1
-      parallelism: 2
+      parallelism: 3
       depends_on: amd-build
       mirror_hardwares: [amdproduction]
       grade: Blocking
+      timeout_in_minutes: 90
       commands:
         - export VLLM_ROCM_USE_AITER=0
         # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
         # that is not supported on CPU
-        - "pytest -sv tests/model_executor -m 'core_model and cpu' --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB"
+        - "pytest -sv tests/model_executor -m 'core_model and cpu and not omni' --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB"
+
+    - label: "Simple · Omni Processor Test"
+      agent_pool: mi300_1
+      depends_on: amd-build
+      mirror_hardwares: [amdproduction]
+      grade: Blocking
+      timeout_in_minutes: 60
+      commands:
+        - export VLLM_ROCM_USE_AITER=0
+        - "pytest -sv tests/model_executor/models/test_omni_processing.py -m 'core_model and cpu and omni'"
 
     - label: "Simple · Diffusion Test · Shard %N/%t"
       agent_pool: mi300_1
@@ -25,6 +36,7 @@ steps:
       depends_on: amd-build
       mirror_hardwares: [amdproduction]
       grade: Blocking
+      timeout_in_minutes: 45
       commands:
         - export VLLM_ROCM_USE_AITER=0
         # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
diff --git a/.buildkite/amd/test-amd-ready.yml b/.buildkite/amd/test-amd-ready.yml
index 505ed1b8723..e46b559f318 100644
--- a/.buildkite/amd/test-amd-ready.yml
+++ b/.buildkite/amd/test-amd-ready.yml
@@ -9,26 +9,39 @@ steps:
   steps:
     - label: "Simple · Model Executor Test · Shard %N/%t"
       agent_pool: mi300_1
-      parallelism: 2
+      parallelism: 3
       depends_on: amd-build
       mirror_hardwares: [amdproduction]
       grade: Blocking
+      timeout_in_minutes: 90
       commands:
         - export VLLM_ROCM_USE_AITER=0
         # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
         # that is not supported on CPU
-        - "pytest -sv tests/model_executor -m 'core_model and cpu' --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB"
+        - "pytest -sv tests/model_executor -m 'core_model and cpu and not omni' --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB"
 
-    - label: "Simple · Diffusion Test"
+    - label: "Simple · Omni Processor Test"
       agent_pool: mi300_1
       depends_on: amd-build
       mirror_hardwares: [amdproduction]
       grade: Blocking
+      timeout_in_minutes: 60
+      commands:
+        - export VLLM_ROCM_USE_AITER=0
+        - "pytest -sv tests/model_executor/models/test_omni_processing.py -m 'core_model and cpu and omni'"
+
+    - label: "Simple · Diffusion Test · Shard %N/%t"
+      agent_pool: mi300_1
+      parallelism: 4
+      depends_on: amd-build
+      mirror_hardwares: [amdproduction]
+      grade: Blocking
+      timeout_in_minutes: 45
       commands:
         - export VLLM_ROCM_USE_AITER=0
         # ignore test_teacache_extractors.py because it use rocm gemm kernel from vLLM
         # that is not supported on CPU
-        - "pytest -sv tests/diffusion -m 'core_model and cpu'  --ignore=tests/diffusion/cache/test_teacache_extractors.py"
+        - "pytest -sv tests/diffusion -m 'core_model and cpu' --ignore=tests/diffusion/cache/test_teacache_extractors.py --num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT --shard-id=$$BUILDKITE_PARALLEL_JOB"
 
     - label: "Simple · Engine&Entrypoints Test"
       agent_pool: mi300_1
@@ -69,6 +82,27 @@ steps:
 
 - group: ":card_index_dividers: Diffusion Test"
   steps:
+    # Keep real FlashAttention execution out of the CPU-marked Simple lane.
+    # AITER may need to build several kernels on a cold worker, so run one
+    # pytest worker with job-local build directories and a bounded timeout.
+    - label: "ROCm · FlashAttention/AITER GPU Coverage"
+      agent_pool: mi300_1
+      depends_on: amd-build
+      mirror_hardwares: [amdproduction]
+      grade: NonBlocking
+      timeout_in_minutes: 60
+      commands:
+        - export VLLM_ROCM_USE_AITER=1
+        - export AITER_JIT_DIR="/tmp/vllm-omni-aiter-$$BUILDKITE_JOB_ID"
+        - export TORCH_EXTENSIONS_DIR="/tmp/vllm-omni-torch-extensions-$$BUILDKITE_JOB_ID"
+        - mkdir -p "$$AITER_JIT_DIR" "$$TORCH_EXTENSIONS_DIR"
+        - >-
+          timeout --signal=TERM --kill-after=2m 55m
+          pytest -s -v -n 1
+          tests/diffusion/attention/
+          -m 'core_model and rocm and MI325 and cards_1'
+          --run-level "core_model"
+
     - label: "Diffusion · Batch Test"
       agent_pool: mi300_1
       depends_on: amd-build
@@ -299,6 +333,12 @@ steps:
       depends_on: amd-build
       mirror_hardwares: [amdproduction]
       grade: Blocking
+      # A ROCm hardware hang aborts the interpreter with 134. Let Buildkite
+      # create one fresh pod instead of retrying on the poisoned GPU process.
+      retry:
+        automatic:
+          - exit_status: 134
+            limit: 1
       commands:
         - pytest -s -v tests/e2e/online_serving/test_cosyvoice3_tts_expansion.py -m "slow" --run-level "core_model"
 
diff --git a/.buildkite/amd/test-template-amd-omni.j2 b/.buildkite/amd/test-template-amd-omni.j2
index e2042b96ab3..11a4086b6a7 100644
--- a/.buildkite/amd/test-template-amd-omni.j2
+++ b/.buildkite/amd/test-template-amd-omni.j2
@@ -156,6 +156,14 @@ steps:
 {% for path in step.artifact_paths %}
           - "{{ path }}"
 {% endfor %}
+{% endif %}
+{% if step.retry %}
+        retry:
+          automatic:
+{% for retry_rule in step.retry.automatic %}
+            - exit_status: {{ retry_rule.exit_status }}
+              limit: {{ retry_rule.limit }}
+{% endfor %}
 {% endif %}
         {% if step.timeout_in_minutes %}
         timeout_in_minutes: {{ step.timeout_in_minutes }}
@@ -224,6 +232,14 @@ steps:
 {% for path in step.artifact_paths %}
       - "{{ path }}"
 {% endfor %}
+{% endif %}
+{% if step.retry %}
+    retry:
+      automatic:
+{% for retry_rule in step.retry.automatic %}
+        - exit_status: {{ retry_rule.exit_status }}
+          limit: {{ retry_rule.limit }}
+{% endfor %}
 {% endif %}
     {% if step.timeout_in_minutes %}
     timeout_in_minutes: {{ step.timeout_in_minutes }}
diff --git a/.buildkite/cuda/test-ready.yml b/.buildkite/cuda/test-ready.yml
index 67f03dbb680..53b9bc4d019 100644
--- a/.buildkite/cuda/test-ready.yml
+++ b/.buildkite/cuda/test-ready.yml
@@ -38,6 +38,12 @@ steps:
     depends_on: upload-ready-pipeline
     steps:
 
+      - label: "Diffusion · FlashAttention Test"
+        timeout_in_minutes: 20
+        commands:
+          - timeout 15m pytest -s -v tests/diffusion/attention/ -m 'core_model and cuda and L4 and cards_1' --run-level "core_model"
+        mirror_hardwares: l4_1
+
       - label: "Diffusion · Offloader Test"
         commands:
           - timeout 40m pytest -s -v tests/diffusion/offloader -m "core_model and cuda" --run-level "core_model"
diff --git a/tests/buildkite/test_amd_pipeline.py b/tests/buildkite/test_amd_pipeline.py
index c2c45f5ef7d..fac4f8c2943 100644
--- a/tests/buildkite/test_amd_pipeline.py
+++ b/tests/buildkite/test_amd_pipeline.py
@@ -11,6 +11,8 @@
 
 AMD_MERGE_PIPELINE = Path(".buildkite/amd/test-amd-merge.yml")
 AMD_NIGHTLY_PIPELINE = Path(".buildkite/amd/test-amd-nightly.yml")
+AMD_READY_PIPELINE = Path(".buildkite/amd/test-amd-ready.yml")
+AMD_TEMPLATE = Path(".buildkite/amd/test-template-amd-omni.j2")
 
 
 def _find_step(label: str, pipeline_path: Path = AMD_MERGE_PIPELINE) -> dict:
@@ -53,3 +55,25 @@ def test_qwen3_accuracy_defers_artifact_path_expansion() -> None:
     assert '"$${BUILDKITE_BUILD_CHECKOUT_PATH:?}"' in staging_command
     assert '"$$artifact_dir"' in staging_command
     assert step["artifact_paths"] == ["tests/e2e/accuracy/qwen3_omni/results/qwen_omni_acc/*.json"]
+
+
+def test_ready_diffusion_cpu_suite_is_sharded() -> None:
+    step = _find_step("Simple · Diffusion Test · Shard %N/%t", AMD_READY_PIPELINE)
+    pytest_command = next(command for command in step["commands"] if "pytest" in command)
+
+    assert step["parallelism"] == 4
+    assert step["timeout_in_minutes"] == 45
+    assert "--num-shards=$$BUILDKITE_PARALLEL_JOB_COUNT" in pytest_command
+    assert "--shard-id=$$BUILDKITE_PARALLEL_JOB" in pytest_command
+
+
+def test_cosyvoice_gpu_abort_gets_one_fresh_job_retry() -> None:
+    step = _find_step("CosyVoice3-TTS E2E Test", AMD_READY_PIPELINE)
+
+    assert step["retry"] == {"automatic": [{"exit_status": 134, "limit": 1}]}
+
+    template = AMD_TEMPLATE.read_text(encoding="utf-8")
+    # Both grouped and top-level AMD steps must preserve an explicit retry
+    # policy when the source suite is rendered into the uploaded pipeline.
+    assert template.count("{% if step.retry %}") == 2
+    assert template.count("{% for retry_rule in step.retry.automatic %}") == 2
diff --git a/tests/diffusion/attention/test_flash_attn.py b/tests/diffusion/attention/test_flash_attn.py
index 183bbd94c63..5dbd8d794a3 100644
--- a/tests/diffusion/attention/test_flash_attn.py
+++ b/tests/diffusion/attention/test_flash_attn.py
@@ -16,13 +16,14 @@
 import pytest
 import torch
 
+from tests.helpers.mark import hardware_test
 from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
 from vllm_omni.diffusion.attention.backends.flash_attn import FlashAttentionImpl
 from vllm_omni.diffusion.attention.backends.sdpa import SDPAImpl
 from vllm_omni.diffusion.attention.backends.utils import fa  # noqa: E402
 from vllm_omni.platforms import current_omni_platform
 
-pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion]
 
 is_gpu = current_omni_platform.is_cuda_alike() or current_omni_platform.is_xpu()
 HAS_FLASH_ATTN = fa.HAS_FLASH_ATTN
@@ -42,10 +43,12 @@
         (9, "4", frozenset((2, 3, 4)), 4),
     ],
 )
+@pytest.mark.cpu
 def test_versioned_flash_attention_selection(device_major, requested, supported, expected):
     assert fa._choose_vllm_flash_attn_version(device_major, requested, supported) == expected
 
 
+@pytest.mark.cpu
 def test_versioned_flash_attention_selection_rejects_invalid_or_unavailable_version():
     with pytest.raises(ValueError, match="must be 2, 3, or 4"):
         fa._choose_vllm_flash_attn_version(9, "5", frozenset((2, 3, 4)))
@@ -92,7 +95,8 @@ def pad_tensor(tensor: torch.Tensor, target_seq_len: int, pad_value: float = 0.0
     return torch.cat([tensor, padding], dim=1)
 
 
-@pytest.mark.skipif(not is_gpu, reason="FlashAttention requires CUDA or XPU")
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
+@pytest.mark.skipif(not is_gpu, reason="FlashAttention requires an accelerator")
 def test_padding_equivalence():
     """
     Case 1: Test that padded and unpadded inputs produce similar outputs.
@@ -185,7 +189,8 @@ def test_padding_equivalence():
     print("✓ Case 1 PASSED: Padded and unpadded outputs are very close!")
 
 
-@pytest.mark.skipif(not is_gpu, reason="FlashAttention requires CUDA or XPU")
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
+@pytest.mark.skipif(not is_gpu, reason="FlashAttention requires an accelerator")
 def test_fa_vs_sdpa():
     """
     Case 2: Compare FlashAttention and SDPA backends with padding.
@@ -302,7 +307,8 @@ def test_fa_vs_sdpa():
     print("✓ Case 2 PASSED: FA and SDPA outputs are very close!")
 
 
-@pytest.mark.skipif(not is_gpu, reason="FlashAttention requires CUDA or XPU")
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
+@pytest.mark.skipif(not is_gpu, reason="FlashAttention requires an accelerator")
 def test_flash_attn_func_preferred_over_varlen():
     """Test flash_attn_func availability and basic forward call."""
     if not HAS_FLASH_ATTN:
@@ -332,7 +338,8 @@ def test_flash_attn_func_preferred_over_varlen():
     print("✓ flash_attn_func forward works correctly!")
 
 
-@pytest.mark.skipif(not is_gpu, reason="FlashAttention requires CUDA or XPU")
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
+@pytest.mark.skipif(not is_gpu, reason="FlashAttention requires an accelerator")
 @pytest.mark.parametrize("k_len", [40, 256])
 def test_cross_attn_key_padding_vs_sdpa(k_len):
     """
@@ -390,6 +397,7 @@ def test_cross_attn_key_padding_vs_sdpa(k_len):
     print("✓ Case 3 PASSED: FA and SDPA cross-attention outputs are very close!")
 
 
+@pytest.mark.cpu
 def test_varlen_masked_routing_by_role(monkeypatch):
     """The unpad route is picked by role, not Q/K length equality; runs without a GPU."""
     calls = []
@@ -424,6 +432,7 @@ def fake_varlen_func(q, k, v, **kwargs):
     assert cu_seqlens_k.tolist() == [0, 2, 5]
 
 
+@pytest.mark.cpu
 def test_piecewise_flash_attn_uses_varlen_fallback(monkeypatch):
     calls = []
 
@@ -454,6 +463,7 @@ def fake_varlen_func(q, k, v, **kwargs):
     assert calls[0]["softmax_scale"] == 0.5
 
 
+@pytest.mark.cpu
 def test_packed_varlen_metadata_bypasses_mask_unpadding(monkeypatch):
     calls = []
 
@@ -486,6 +496,7 @@ def fake_varlen_func(q, k, v, **kwargs):
     assert calls[0][3]["max_seqlen_q"] == 6
 
 
+@pytest.mark.cpu
 def test_packed_varlen_metadata_must_be_complete(monkeypatch):
     monkeypatch.setattr(fa, "HAS_FLASH_ATTN", True)
     impl = FlashAttentionImpl(num_heads=2, head_size=4, softmax_scale=0.5, causal=False)
@@ -542,6 +553,7 @@ def _fake_torch_npu(monkeypatch, *, npu_fusion_attention=None):
 # --- Test group A: boundary resolution (_resolve_packed_seq_npu) -------------
 
 
+@pytest.mark.cpu
 def test_resolve_packed_seq_accepts_real_plus_pad_contract():
     impl = _npu_impl()
     q = torch.randn(1, 8, 2, 4)
@@ -551,6 +563,7 @@ def test_resolve_packed_seq_accepts_real_plus_pad_contract():
     assert impl._resolve_packed_seq_npu(q, q, extra) == ([5, 8], [5, 8])
 
 
+@pytest.mark.cpu
 def test_resolve_packed_seq_single_document_no_padding():
     impl = _npu_impl()
     q = torch.randn(1, 8, 2, 4)
@@ -574,6 +587,7 @@ def test_resolve_packed_seq_single_document_no_padding():
         "pad_longer_than_real",
     ],
 )
+@pytest.mark.cpu
 def test_resolve_packed_seq_rejects_malformed_metadata(case):
     """Any metadata outside the exact [real, pad] contract returns None so the
     caller falls back to the masked path."""
@@ -630,6 +644,7 @@ def _npu_impl_with_mocked_paths() -> tuple[FlashAttentionImpl, torch.Tensor]:
     return impl, sentinel
 
 
+@pytest.mark.cpu
 def test_npu_env_unset_uses_varlen(monkeypatch):
     monkeypatch.delenv("MINDIE_SD_FA_TYPE", raising=False)
     _fake_mindiesd(monkeypatch)
@@ -642,6 +657,7 @@ def test_npu_env_unset_uses_varlen(monkeypatch):
     impl._forward_prefix_kv_slice_npu.assert_not_called()
 
 
+@pytest.mark.cpu
 def test_npu_env_laser_uses_slice(monkeypatch):
     monkeypatch.setenv("MINDIE_SD_FA_TYPE", "ascend_laser_attention")
     _fake_mindiesd(monkeypatch)
@@ -655,6 +671,7 @@ def test_npu_env_laser_uses_slice(monkeypatch):
 
 
 @pytest.mark.parametrize("fa_type", ["prompt_flash_attn", "fused_attn_score", "ascend_laser_attenton", "garbage"])
+@pytest.mark.cpu
 def test_npu_env_non_laser_value_falls_back_to_varlen(monkeypatch, fa_type):
     """Locks in the CURRENT dispatch behavior (PR #5891).
 
@@ -675,6 +692,7 @@ def test_npu_env_non_laser_value_falls_back_to_varlen(monkeypatch, fa_type):
     impl._forward_prefix_kv_slice_npu.assert_not_called()
 
 
+@pytest.mark.cpu
 def test_npu_varlen_opt_in_unset_takes_mask_path(monkeypatch):
     """Models that do not set ``npu_attn_varlen`` (e.g. Wan/Cosmos) keep using
     the existing masked attention_forward path; the new branches are skipped."""
@@ -702,6 +720,7 @@ def test_npu_varlen_opt_in_unset_takes_mask_path(monkeypatch):
     ("query_length", "key_length", "expected_inner_precise"),
     [(4, 4, 0), (2, 4, 0), (4, 2, 2)],
 )
+@pytest.mark.cpu
 def test_npu_causal_uses_native_right_down_mode(
     monkeypatch,
     query_length,
@@ -746,6 +765,7 @@ def test_npu_causal_uses_native_right_down_mode(
     assert out is expected_out
 
 
+@pytest.mark.cpu
 def test_npu_causal_composes_explicit_keep_mask(monkeypatch):
     expected_out = torch.randn(1, 4, 2, 4)
     fusion_attention = Mock(return_value=(expected_out, None, None, None, 0, 0, 0))
@@ -782,6 +802,7 @@ def test_npu_causal_composes_explicit_keep_mask(monkeypatch):
     assert out is expected_out
 
 
+@pytest.mark.cpu
 def test_npu_noncausal_without_explicit_mask_stays_unmasked(monkeypatch):
     captured: dict = {}
 
@@ -800,6 +821,7 @@ def fake_attention_forward(query, key, value, **kwargs):
 # --- Test group D: laser input pre-scaling in _forward_prefix_kv_slice_npu --
 
 
+@pytest.mark.cpu
 def test_prefix_kv_slice_applies_laser_input_scaling(monkeypatch):
     monkeypatch.setenv("MINDIE_SD_FA_TYPE", "ascend_laser_attention")
     captured: dict = {}
@@ -838,6 +860,7 @@ def fake_attention_forward(query, key, value, **kwargs):
     torch.testing.assert_close(out, torch.ones(1, 8, 2, 4) * 256.0)
 
 
+@pytest.mark.cpu
 def test_prefix_kv_slice_no_scaling_without_factor(monkeypatch):
     monkeypatch.setenv("MINDIE_SD_FA_TYPE", "ascend_laser_attention")
     captured: dict = {}
diff --git a/tests/diffusion/models/magi2/test_native_compile_cuda.py b/tests/diffusion/models/magi2/test_native_compile_cuda.py
index 1db394750bb..f6f87f0d119 100644
--- a/tests/diffusion/models/magi2/test_native_compile_cuda.py
+++ b/tests/diffusion/models/magi2/test_native_compile_cuda.py
@@ -14,12 +14,13 @@
 )
 from tests.helpers.mark import hardware_marks
 from vllm_omni.diffusion.models.magi2.sampler_magi2 import CFGConfig
+from vllm_omni.platforms import current_omni_platform
 
 pytestmark = [
     pytest.mark.diffusion,
     pytest.mark.core_model,
     *hardware_marks(res={"cuda": "L4"}, num_cards=1),
-    pytest.mark.skipif(not torch.cuda.is_available(), reason="requires CUDA"),
+    pytest.mark.skipif(not current_omni_platform.is_cuda(), reason="requires CUDA"),
 ]
 
 
diff --git a/tests/e2e/offline_inference/test_qwen3_omni.py b/tests/e2e/offline_inference/test_qwen3_omni.py
index f5937265c37..b33d693efec 100644
--- a/tests/e2e/offline_inference/test_qwen3_omni.py
+++ b/tests/e2e/offline_inference/test_qwen3_omni.py
@@ -118,7 +118,9 @@ def test_structured_multistage_config_reaches_runtime(omni_runner, offline_clien
         {
             "temperature": 0.0,
             "top_p": 1.0,
-            "top_k": -1,
+            # SamplingParams normalizes the disabled greedy-sampling sentinel
+            # from the deploy YAML (top_k=-1) to its runtime value (top_k=0).
+            "top_k": 0,
             "max_tokens": 65536,
             "repetition_penalty": 1.1,
         },
diff --git a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
index 74fc5059bcd..46255110c99 100644
--- a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
+++ b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components.py
@@ -10,7 +10,6 @@
 import torch
 import torch.nn as nn
 
-from tests.helpers.mark import hardware_test
 from vllm_omni.diffusion.config import set_current_diffusion_config
 from vllm_omni.diffusion.data import AttentionConfig
 from vllm_omni.model_executor.models.cosyvoice3.code2wav_core.hifigan import (
@@ -732,114 +731,3 @@ def fake_stream_hift(self, feat, *, cache_state=None, finalize=False):
     assert torch.equal(call["token_lens"], torch.tensor([3, 5], dtype=torch.int32))
     assert results[0][0].shape[-1] == 4
     assert results[1][0].shape[-1] == 8
-
-
-@pytest.mark.core_model
-@hardware_test(res={"cuda": "L4"}, num_cards=1)
-def test_code2wav_streaming_batch_matches_ragged_flow_numerics(monkeypatch):
-    """A padded flow batch must match individual flow calls on valid mels."""
-    from omegaconf import DictConfig
-
-    from vllm_omni.diffusion.models.cosyvoice3_audio.cosyvoice3_dit import DiT
-    from vllm_omni.model_executor.models.cosyvoice3.code2wav_core.cfm import (
-        CausalConditionalCFM,
-        CausalMaskedDiffWithDiT,
-    )
-    from vllm_omni.model_executor.models.cosyvoice3.code2wav_core.layers import PreLookaheadLayer
-    from vllm_omni.model_executor.models.cosyvoice3.cosyvoice3_code2wav import CosyVoice3Code2Wav
-
-    torch.manual_seed(0)
-    estimator = DiT(
-        dim=32,
-        depth=1,
-        heads=4,
-        dim_head=8,
-        dropout=0.0,
-        ff_mult=2,
-        mel_dim=80,
-        mu_dim=80,
-        spk_dim=80,
-        out_channels=80,
-    )
-    decoder = CausalConditionalCFM(
-        in_channels=80,
-        cfm_params=DictConfig(
-            {
-                "sigma_min": 1e-6,
-                "solver": "euler",
-                "t_scheduler": "cosine",
-                "training_cfg_rate": 0.2,
-                "inference_cfg_rate": 0.7,
-            }
-        ),
-        n_spks=1,
-        spk_emb_dim=80,
-        estimator=estimator,
-    )
-    flow_model = (
-        CausalMaskedDiffWithDiT(
-            input_size=80,
-            output_size=80,
-            spk_embed_dim=192,
-            vocab_size=64,
-            input_frame_rate=25,
-            only_mask_loss=True,
-            token_mel_ratio=2,
-            pre_lookahead_len=1,
-            pre_lookahead_layer=PreLookaheadLayer(in_channels=80, channels=80, pre_lookahead_len=1),
-            decoder=decoder,
-        )
-        .to(device="cuda", dtype=torch.bfloat16)
-        .eval()
-    )
-
-    model = object.__new__(CosyVoice3Code2Wav)
-    nn.Module.__init__(model)
-    model.flow_model = flow_model
-
-    def return_mel(self, feat, *, cache_state=None, finalize=False):
-        return feat, None
-
-    model._stream_hift_from_feat = types.MethodType(return_mel, model)
-
-    original_randn = torch.randn
-
-    def length_consistent_randn(*size, **kwargs):
-        shape = tuple(size[0]) if len(size) == 1 and isinstance(size[0], (tuple, list)) else tuple(size)
-        if len(shape) == 3 and shape[1] == 80:
-            device = kwargs.get("device")
-            dtype = kwargs.get("dtype", torch.float32)
-            channels = torch.arange(shape[1], device=device, dtype=torch.float32).view(1, -1, 1)
-            positions = torch.arange(shape[2], device=device, dtype=torch.float32).view(1, 1, -1)
-            noise = torch.sin(channels * 0.17 + positions * 0.31)
-            return noise.expand(shape[0], -1, -1).to(dtype=dtype).clone()
-        return original_randn(*size, **kwargs)
-
-    monkeypatch.setattr(torch, "randn", length_consistent_randn)
-    common = {
-        "prompt_token": torch.tensor([[7, 8]], dtype=torch.int32),
-        "prompt_feat": torch.linspace(-0.5, 0.5, 4 * 80).reshape(1, 4, 80),
-        "embedding": torch.linspace(-1.0, 1.0, 192).reshape(1, 192),
-        "finalize": False,
-    }
-    items = [
-        {**common, "token": torch.tensor([[1, 2, 3]], dtype=torch.int32)},
-        {**common, "token": torch.tensor([[1, 2, 3, 4, 5]], dtype=torch.int32)},
-    ]
-
-    batched = model.forward_streaming_batch(items, n_timesteps=2)
-    individual = [
-        model.forward_streaming(
-            token=item["token"],
-            prompt_token=item["prompt_token"],
-            prompt_feat=item["prompt_feat"],
-            embedding=item["embedding"],
-            n_timesteps=2,
-        )
-        for item in items
-    ]
-
-    for (batched_mel, _), (individual_mel, _) in zip(batched, individual):
-        assert batched_mel.shape == individual_mel.shape
-        rel_mean = (batched_mel - individual_mel).abs().mean() / individual_mel.abs().mean().clamp_min(1e-6)
-        assert rel_mean.item() < 0.05
diff --git a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components_cuda.py b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components_cuda.py
new file mode 100644
index 00000000000..aff89f852cc
--- /dev/null
+++ b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_components_cuda.py
@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""CUDA-only CosyVoice3 component tests."""
+
+import types
+
+import pytest
+import torch
+import torch.nn as nn
+
+from tests.helpers.mark import hardware_test
+from vllm_omni.platforms import current_omni_platform
+
+pytestmark = [
+    pytest.mark.core_model,
+    pytest.mark.skipif(not current_omni_platform.is_cuda(), reason="requires CUDA"),
+]
+
+
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+def test_code2wav_streaming_batch_matches_ragged_flow_numerics(monkeypatch):
+    """A padded flow batch must match individual flow calls on valid mels."""
+    from omegaconf import DictConfig
+
+    from vllm_omni.diffusion.models.cosyvoice3_audio.cosyvoice3_dit import DiT
+    from vllm_omni.model_executor.models.cosyvoice3.code2wav_core.cfm import (
+        CausalConditionalCFM,
+        CausalMaskedDiffWithDiT,
+    )
+    from vllm_omni.model_executor.models.cosyvoice3.code2wav_core.layers import PreLookaheadLayer
+    from vllm_omni.model_executor.models.cosyvoice3.cosyvoice3_code2wav import CosyVoice3Code2Wav
+
+    torch.manual_seed(0)
+    estimator = DiT(
+        dim=32,
+        depth=1,
+        heads=4,
+        dim_head=8,
+        dropout=0.0,
+        ff_mult=2,
+        mel_dim=80,
+        mu_dim=80,
+        spk_dim=80,
+        out_channels=80,
+    )
+    decoder = CausalConditionalCFM(
+        in_channels=80,
+        cfm_params=DictConfig(
+            {
+                "sigma_min": 1e-6,
+                "solver": "euler",
+                "t_scheduler": "cosine",
+                "training_cfg_rate": 0.2,
+                "inference_cfg_rate": 0.7,
+            }
+        ),
+        n_spks=1,
+        spk_emb_dim=80,
+        estimator=estimator,
+    )
+    flow_model = (
+        CausalMaskedDiffWithDiT(
+            input_size=80,
+            output_size=80,
+            spk_embed_dim=192,
+            vocab_size=64,
+            input_frame_rate=25,
+            only_mask_loss=True,
+            token_mel_ratio=2,
+            pre_lookahead_len=1,
+            pre_lookahead_layer=PreLookaheadLayer(in_channels=80, channels=80, pre_lookahead_len=1),
+            decoder=decoder,
+        )
+        .to(device="cuda", dtype=torch.bfloat16)
+        .eval()
+    )
+
+    model = object.__new__(CosyVoice3Code2Wav)
+    nn.Module.__init__(model)
+    model.flow_model = flow_model
+
+    def return_mel(self, feat, *, cache_state=None, finalize=False):
+        return feat, None
+
+    model._stream_hift_from_feat = types.MethodType(return_mel, model)
+
+    original_randn = torch.randn
+
+    def length_consistent_randn(*size, **kwargs):
+        shape = tuple(size[0]) if len(size) == 1 and isinstance(size[0], (tuple, list)) else tuple(size)
+        if len(shape) == 3 and shape[1] == 80:
+            device = kwargs.get("device")
+            dtype = kwargs.get("dtype", torch.float32)
+            channels = torch.arange(shape[1], device=device, dtype=torch.float32).view(1, -1, 1)
+            positions = torch.arange(shape[2], device=device, dtype=torch.float32).view(1, 1, -1)
+            noise = torch.sin(channels * 0.17 + positions * 0.31)
+            return noise.expand(shape[0], -1, -1).to(dtype=dtype).clone()
+        return original_randn(*size, **kwargs)
+
+    monkeypatch.setattr(torch, "randn", length_consistent_randn)
+    common = {
+        "prompt_token": torch.tensor([[7, 8]], dtype=torch.int32),
+        "prompt_feat": torch.linspace(-0.5, 0.5, 4 * 80).reshape(1, 4, 80),
+        "embedding": torch.linspace(-1.0, 1.0, 192).reshape(1, 192),
+        "finalize": False,
+    }
+    items = [
+        {**common, "token": torch.tensor([[1, 2, 3]], dtype=torch.int32)},
+        {**common, "token": torch.tensor([[1, 2, 3, 4, 5]], dtype=torch.int32)},
+    ]
+
+    batched = model.forward_streaming_batch(items, n_timesteps=2)
+    individual = [
+        model.forward_streaming(
+            token=item["token"],
+            prompt_token=item["prompt_token"],
+            prompt_feat=item["prompt_feat"],
+            embedding=item["embedding"],
+            n_timesteps=2,
+        )
+        for item in items
+    ]
+
+    for (batched_mel, _), (individual_mel, _) in zip(batched, individual):
+        assert batched_mel.shape == individual_mel.shape
+        rel_mean = (batched_mel - individual_mel).abs().mean() / individual_mel.abs().mean().clamp_min(1e-6)
+        assert rel_mean.item() < 0.05
diff --git a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_incremental_hift.py b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_incremental_hift.py
index 1e8eff599a8..91b3228642a 100644
--- a/tests/model_executor/models/cosyvoice3/test_cosyvoice3_incremental_hift.py
+++ b/tests/model_executor/models/cosyvoice3/test_cosyvoice3_incremental_hift.py
@@ -31,6 +31,7 @@
     _wrapped_slice,
 )
 from vllm_omni.model_executor.models.cosyvoice3.cosyvoice3_code2wav import CosyVoice3Code2Wav
+from vllm_omni.platforms import current_omni_platform
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
@@ -334,6 +335,10 @@ def test_incremental_hift_matches_reference_for_voiced_f0(config):
 
 @pytest.mark.parametrize("config", CONFIGS)
 @pytest.mark.parametrize("first_len,step_len", [(10, 6), (10, 3), (20, 3), (10, 1)])
+@pytest.mark.skipif(
+    current_omni_platform.is_rocm(),
+    reason="exhaustive CPU reference matrix exceeds the AMD CI time budget",
+)
 def test_incremental_hift_matches_reference_for_voiced_f0_small_chunks(config, first_len, step_len):
     """Same as test_incremental_hift_matches_reference_for_voiced_f0, but with small,
     sub-receptive-field chunk sizes (down to 1 mel frame) instead of the uniform
diff --git a/tests/model_executor/models/qwen3_omni/test_qwen3_omni_embed.py b/tests/model_executor/models/qwen3_omni/test_qwen3_omni_embed.py
index d041eace013..ec6e653c525 100644
--- a/tests/model_executor/models/qwen3_omni/test_qwen3_omni_embed.py
+++ b/tests/model_executor/models/qwen3_omni/test_qwen3_omni_embed.py
@@ -21,8 +21,13 @@
     expected_outputs,
     make_thinker,
 )
+from vllm_omni.platforms import current_omni_platform
 
-pytestmark = [pytest.mark.core_model, pytest.mark.cuda]
+pytestmark = [
+    pytest.mark.core_model,
+    pytest.mark.cuda,
+    pytest.mark.skipif(not current_omni_platform.is_cuda(), reason="requires NVIDIA CUDA"),
+]
 
 _SHAPE = ModelShape(
     vocab_size=64,

From 9fbc36ab2d672b9c7c6873b094500bc5e2d54665 Mon Sep 17 00:00:00 2001
From: wtz2333 <2955110911@qq.com>
Date: Fri, 18 Sep 2026 12:06:02 +0800
Subject: [PATCH 081/105] [AR-Diffusion] Bound KV metadata for long rollouts
 (#7498)

Signed-off-by: wtz2333 <2955110911@qq.com>
---
 .../ar_diffusion/test_capability_runner.py    |  14 ++-
 .../ar_diffusion/test_kv_orchestration.py     | 102 ++++++++++++++++++
 .../experimental/ar_diffusion/capability.py   |   1 +
 .../ar_diffusion/kv_cache/manager.py          |  37 ++++---
 .../ar_diffusion/kv_cache/paged.py            |  22 ++++
 5 files changed, 159 insertions(+), 17 deletions(-)

diff --git a/tests/diffusion/ar_diffusion/test_capability_runner.py b/tests/diffusion/ar_diffusion/test_capability_runner.py
index 70166189b82..d753efbf655 100644
--- a/tests/diffusion/ar_diffusion/test_capability_runner.py
+++ b/tests/diffusion/ar_diffusion/test_capability_runner.py
@@ -323,12 +323,18 @@ def test_lingbot_like_sink_survives_sliding_window_eviction():
     kv = runner.kv_cache
     assert kv is not None
 
-    for _ in range(8):
+    state = commit_one_frame(runner, "s1", "main")
+    sink_block = kv.block_table(state.adapter("main"))[0]
+    for _ in range(7):
         state = commit_one_frame(runner, "s1", "main")
 
-    table = kv.block_table(state.adapter("main"))
-    assert table[0] != kv.null_block_id
-    assert table[1] == kv.null_block_id
+    adapter = state.adapter("main")
+    table = kv.block_table(adapter)
+    assert len(table) == 6  # one sink + five recent frames
+    assert table[0] == sink_block
+    assert kv.null_block_id not in table
+    assert adapter.absolute_num_computed_tokens == 8 * BLOCK
+    assert adapter.num_computed_tokens == 6 * BLOCK
 
     ctx = state.get_kv_caches("main", seq_len=BLOCK, commit_current=False)[0].forward_ctx
     visible, _ = ctx.video_block_table(torch.device("cpu"))
diff --git a/tests/diffusion/ar_diffusion/test_kv_orchestration.py b/tests/diffusion/ar_diffusion/test_kv_orchestration.py
index 4482fa6fbf0..0c1c870bf76 100644
--- a/tests/diffusion/ar_diffusion/test_kv_orchestration.py
+++ b/tests/diffusion/ar_diffusion/test_kv_orchestration.py
@@ -6,6 +6,7 @@
 
 from vllm_omni.experimental.ar_diffusion.capability import ARDiffusionKVBranchSpec
 from vllm_omni.experimental.ar_diffusion.kv_cache import ARDiffusionKVCache, ARDiffusionKVConfig
+from vllm_omni.experimental.ar_diffusion.kv_cache.state import ARDiffusionKVState
 
 pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
 DIMS = dict(
@@ -108,3 +109,104 @@ def test_state_close_frees_both_branch_blocks():
     state.close()
     # All blocks returned — no leak across an evicted session.
     assert kv.manager.block_pool.get_num_free_blocks() == free_total
+
+
+@pytest.mark.parametrize(
+    "frames_per_call,block_size,max_model_len,num_calls",
+    [(1, 16, 113, 1000), (3, 16, 113, 1000), (3, 1560, 1 << 20, 241)],
+    ids=["single-frame", "three-frame", "lingbot-two-minutes"],
+)
+@pytest.mark.parametrize("sink_chunks,reset_at_boundary", [(0, False), (2, False), (0, True), (2, True)])
+def test_rollout_keeps_metadata_bounded(
+    frames_per_call, block_size, max_model_len, num_calls, sink_chunks, reset_at_boundary
+):
+    """Long rollouts retain exact global-position K/V with bounded storage indices."""
+    kv = ARDiffusionKVCache(
+        ARDiffusionKVConfig(
+            enable=True,
+            chunk_size=block_size,
+            window_chunks=3,
+            sink_chunks=sink_chunks,
+            reset_at_boundary=reset_at_boundary,
+        ),
+        num_layers=1,
+        num_kv_heads=1,
+        head_size=4,
+        dtype=torch.float32,
+        block_size=block_size,
+        max_model_len=max_model_len,
+        available_bytes=1 << 24,
+        kv_branches=(ARDiffusionKVBranchSpec("main", 0),),
+        session_capacity=1,
+        frames_per_block=frames_per_call,
+        device=torch.device("cpu"),
+    )
+    adapter = kv.begin_request("long-rollout")
+    state = ARDiffusionKVState(kv, "long-rollout", {"main": adapter}, num_layers=1)
+    free_total = kv.manager.block_pool.get_num_free_blocks()
+    pool_shape = kv.key_cache(0).shape
+    retained_frames = sink_chunks + (0 if reset_at_boundary else 3)
+    for call_index in range(num_calls):
+        start = call_index * frames_per_call * block_size
+        stop = start + frames_per_call * block_size
+        if frames_per_call == 1:
+            kv.allocate_chunk(adapter)
+            slots = kv.chunk_write_slots(adapter)
+        else:
+            context = state.get_kv_caches("main", seq_len=stop - start, commit_current=True)[0].forward_ctx
+            context.ensure_video_slots(torch.device("cpu"))
+            slots = context.current_video_slot_mapping
+        assert len(kv.block_table(adapter)) <= retained_frames + frames_per_call
+        values = torch.arange(start, stop, dtype=torch.float32).view(-1, 1, 1).expand(-1, 1, 4)
+        kv.key_cache(0).flatten(0, 1)[slots] = values
+        kv.value_cache(0).flatten(0, 1)[slots] = -values
+        if frames_per_call == 1:
+            kv.commit_chunk(adapter)
+        else:
+            state.commit_paged_context("main")
+            assert state._committed["main"] == stop
+        sink_end = min(stop, sink_chunks * block_size)
+        tail_start = stop if reset_at_boundary else max(sink_end, stop - 3 * block_size)
+        expected = torch.cat((torch.arange(sink_end), torch.arange(tail_start, stop))).float()
+        expected = expected.view(-1, 1, 1).expand(-1, 1, 4)
+        resident = kv.window_block_ids(adapter)
+        torch.testing.assert_close(kv.key_cache(0)[resident].flatten(0, 1), expected)
+        torch.testing.assert_close(kv.value_cache(0)[resident].flatten(0, 1), -expected)
+        assert adapter.completed_chunks * block_size == stop
+        assert adapter.absolute_num_computed_tokens == stop
+        assert len(kv.block_table(adapter)) <= retained_frames
+        assert adapter.num_computed_tokens <= retained_frames * block_size
+        assert kv.key_cache(0).shape == pool_shape
+        assert free_total - kv.manager.block_pool.get_num_free_blocks() == min(stop // block_size, retained_frames)
+    state.reset()
+    fresh = state.adapter("main")
+    assert fresh.compacted_tokens == fresh.absolute_num_computed_tokens == fresh.num_computed_tokens == 0
+    assert kv.block_table(fresh) == []
+    assert kv.manager.block_pool.get_num_free_blocks() == free_total
+    kv.allocate_chunk(fresh)
+    assert len(kv.chunk_write_slots(fresh)) == block_size
+    state.close()
+    assert kv.manager.block_pool.get_num_free_blocks() == free_total
+
+
+def test_compaction_offsets_are_request_local():
+    kv = make_cache()
+    free_total = kv.manager.block_pool.get_num_free_blocks()
+    first, second = kv.begin_request("first"), kv.begin_request("second")
+    for index in range(8):
+        kv.allocate_chunk(first)
+        kv.commit_chunk(first)
+        if index in (0, 4):
+            kv.allocate_chunk(second)
+            kv.commit_chunk(second)
+    assert first.absolute_num_computed_tokens == 8 * 16
+    assert first.compacted_tokens == 6 * 16
+    assert second.absolute_num_computed_tokens == 2 * 16
+    assert second.compacted_tokens == 0
+    assert first.num_computed_tokens == second.num_computed_tokens == 2 * 16
+    assert set(kv.block_table(first)).isdisjoint(kv.block_table(second))
+    kv.end_request(first)
+    kv.end_request(second)
+    group = kv.manager.coordinator.single_type_managers[0]
+    assert not group.req_to_blocks and not group.num_cached_block
+    assert kv.manager.block_pool.get_num_free_blocks() == free_total
diff --git a/vllm_omni/experimental/ar_diffusion/capability.py b/vllm_omni/experimental/ar_diffusion/capability.py
index 14526151357..48456222798 100644
--- a/vllm_omni/experimental/ar_diffusion/capability.py
+++ b/vllm_omni/experimental/ar_diffusion/capability.py
@@ -81,6 +81,7 @@ class ARDiffusionKVCacheSpec:
     sink_frames: int = 0
     reset_at_boundary: bool = False
     cross_attention: tuple[ARDiffusionCrossAttentionKVSpec, ...] = ()
+    # Initial vLLM storage horizon; extended to fit an in-flight span.
     max_model_len: int = 1 << 20
     max_scratch_tokens_per_branch: int = 0
     model_owned_state_bytes_per_session: int = 0
diff --git a/vllm_omni/experimental/ar_diffusion/kv_cache/manager.py b/vllm_omni/experimental/ar_diffusion/kv_cache/manager.py
index f4cb416f64e..48ede64731f 100644
--- a/vllm_omni/experimental/ar_diffusion/kv_cache/manager.py
+++ b/vllm_omni/experimental/ar_diffusion/kv_cache/manager.py
@@ -15,6 +15,7 @@
 import inspect
 import os
 from collections.abc import Collection, Iterable, Sequence
+from typing import cast
 
 import torch
 from vllm.logger import init_logger
@@ -30,6 +31,7 @@
 from vllm_omni.experimental.ar_diffusion.capability import ARDiffusionKVBranchSpec
 from vllm_omni.experimental.ar_diffusion.kv_cache.config import ARDiffusionKVConfig
 from vllm_omni.experimental.ar_diffusion.kv_cache.paged import (
+    ChunkWindowManager,
     ChunkWindowSpec,
     allocate_kv_pool_with_views,
     chunk_slot_mapping,
@@ -49,10 +51,10 @@ class ARDiffusionRequestAdapter:
     real ``KVCacheManager`` against this adapter so the surface cannot silently
     drift across vLLM versions.
 
-    An AR-Diffusion request advances one *chunk* at a time: ``allocate_slots`` is called
-    once per chunk and ``num_computed_tokens`` advances only when a chunk is
-    committed (:meth:`on_chunk_committed`), so the ``T`` denoise steps of a chunk
-    reuse the same slots.
+    ``completed_chunks`` and ``absolute_num_computed_tokens`` track the model
+    timeline. vLLM sees compacted storage positions through ``num_computed_tokens``
+    and ``num_tokens``. A chunk's denoise steps reuse the same slots; only a
+    successful commit advances the timeline and compacts evicted metadata.
     """
 
     def __init__(
@@ -66,6 +68,7 @@ def __init__(
         self._chunk_size = chunk_size
         self._prefill = prefill_prefix_tokens
         self._completed_chunks = 0
+        self.compacted_tokens = 0
         # Filled only when cross-request prefix reuse is enabled (Phase 3).
         self.block_hashes: list = []
         self.skip_reading_prefix_cache = True
@@ -79,14 +82,19 @@ def __init__(
         self.num_in_flight_tokens = 0
 
     @property
-    def num_computed_tokens(self) -> int:
-        """Persistent KV already materialized (committed chunks + prefill)."""
+    def absolute_num_computed_tokens(self) -> int:
+        """Cumulative model position, unaffected by storage compaction."""
         return self._prefill + self._completed_chunks * self._chunk_size
 
+    @property
+    def num_computed_tokens(self) -> int:
+        """Committed position in the compact vLLM block table."""
+        return self.absolute_num_computed_tokens - self.compacted_tokens
+
     @property
     def num_tokens(self) -> int:
-        """Total tokens once the in-flight chunk is committed."""
-        return self._prefill + (self._completed_chunks + 1) * self._chunk_size
+        """Storage position once the in-flight chunk is committed."""
+        return self.num_computed_tokens + self._chunk_size
 
     @property
     def num_prompt_tokens(self) -> int:
@@ -540,12 +548,9 @@ def end_request(self, adapter: ARDiffusionRequestAdapter) -> None:
     def allocate_chunk(self, adapter: ARDiffusionRequestAdapter) -> list[int]:
         """Allocate a chunk's blocks (evicting out-of-window blocks first).
 
-        Returns the request's full block table (incl. null_block placeholders).
+        Returns the request's compact storage block table.
         """
-        blocks = self.manager.allocate_slots(adapter, num_new_tokens=self.spec.chunk_size)
-        if blocks is None:
-            raise RuntimeError("AR-Diffusion KV pool exhausted while allocating a chunk")
-        table = self.block_table(adapter)
+        table = self.allocate_token_slots(adapter, self.spec.chunk_size)
         resident = resident_block_ids(table, self.null_block_id)
         _log.debug(
             "AR-Diffusion allocate_chunk: req=%s chunk=%d table_len=%d resident=%d free=%d",
@@ -561,6 +566,10 @@ def allocate_token_slots(self, adapter: ARDiffusionRequestAdapter, num_tokens: i
         """Allocate managed blocks for an in-flight video span without committing it."""
         if num_tokens <= 0:
             raise ValueError(f"num_tokens must be positive, got {num_tokens}")
+        # vLLM clips slot allocation at max_model_len. Admit the entire
+        # in-flight span in compact storage coordinates, independent of the
+        # model's absolute frame positions.
+        self.manager.max_model_len = max(self.manager.max_model_len, adapter.num_computed_tokens + num_tokens)
         blocks = self.manager.allocate_slots(adapter, num_new_tokens=num_tokens)
         if blocks is None:
             raise RuntimeError("AR-Diffusion KV pool exhausted while allocating paged attention slots")
@@ -618,6 +627,8 @@ def commit_chunk(self, adapter: ARDiffusionRequestAdapter) -> None:
             adapter.num_computed_tokens,
             num_prompt_tokens=adapter.num_prompt_tokens,
         )
+        window_manager = cast(ChunkWindowManager, self.manager.coordinator.single_type_managers[0])
+        adapter.compacted_tokens += window_manager.compact_block_table(adapter.request_id)
         _log.debug("AR-Diffusion commit: req=%s after=%d", adapter.request_id, adapter.completed_chunks)
 
     # -- pool-backed K/V access --------------------------------------------
diff --git a/vllm_omni/experimental/ar_diffusion/kv_cache/paged.py b/vllm_omni/experimental/ar_diffusion/kv_cache/paged.py
index ddc1937a2b4..325bbaf166f 100644
--- a/vllm_omni/experimental/ar_diffusion/kv_cache/paged.py
+++ b/vllm_omni/experimental/ar_diffusion/kv_cache/paged.py
@@ -197,6 +197,28 @@ def get_num_skipped_tokens(self, num_computed_tokens: int) -> int:
             reset_at_boundary=spec.reset_at_boundary,
         )
 
+    def compact_block_table(self, request_id: str) -> int:
+        """Remove the evicted gap after the sink; return its size in tokens.
+
+        Call only after commit/eviction, then shift the request's storage
+        position by the returned amount. Physical pages and model positions
+        are unchanged, including any allocated but not yet committed tail.
+        """
+        if self.enable_caching:
+            raise RuntimeError("AR block-table compaction requires prefix caching to be disabled")
+        blocks = self.req_to_blocks.get(request_id, [])
+        start = self.kv_cache_spec.sink_chunks
+        end = start
+        while end < len(blocks) and blocks[end] == self._null_block:
+            end += 1
+        if end == start:
+            return 0
+        del blocks[start:end]
+        if request_id in self.num_cached_block:
+            cached = self.num_cached_block[request_id]
+            self.num_cached_block[request_id] = min(cached, start) + max(0, cached - end)
+        return (end - start) * self.block_size
+
     def remove_skipped_blocks(
         self,
         request_id: str,

From 5d3e6dc1b4c172202b080a8659f522deae76852b Mon Sep 17 00:00:00 2001
From: WeiQing Chen <40507679+david6666666@users.noreply.github.com>
Date: Fri, 18 Sep 2026 15:16:45 +0800
Subject: [PATCH 082/105] [Bugfix][MiniMax-H3] Use Hopper-safe modulation
 precision (#7693)

Signed-off-by: david6666666 <530634352@qq.com>
---
 .../common/ci_source_file_dependencies.yml    |  1 +
 .../minimax_h3/test_minimax_h3_modulation.py  | 53 +++++++++++++++++++
 .../diffusion/layers/indexed_modulation.py    | 49 +++++++++++++----
 3 files changed, 94 insertions(+), 9 deletions(-)

diff --git a/.buildkite/common/ci_source_file_dependencies.yml b/.buildkite/common/ci_source_file_dependencies.yml
index c101db48d25..067af9fa689 100644
--- a/.buildkite/common/ci_source_file_dependencies.yml
+++ b/.buildkite/common/ci_source_file_dependencies.yml
@@ -100,6 +100,7 @@ x-hunyuan-image3: &hunyuan_image3
 
 x-minimax-h3: &minimax_h3
   - vllm_omni/diffusion/models/minimax_h3/
+  - vllm_omni/diffusion/layers/indexed_modulation.py
 
 x-hunyuan-video: &hunyuan_video
   - vllm_omni/diffusion/models/hunyuan_video/
diff --git a/tests/diffusion/models/minimax_h3/test_minimax_h3_modulation.py b/tests/diffusion/models/minimax_h3/test_minimax_h3_modulation.py
index 7fde01354be..fcca6f7adc3 100644
--- a/tests/diffusion/models/minimax_h3/test_minimax_h3_modulation.py
+++ b/tests/diffusion/models/minimax_h3/test_minimax_h3_modulation.py
@@ -10,6 +10,7 @@
     _MAX_1D_GRID_SIZE,
     _iter_row_chunks,
     _launch_row_chunks,
+    _use_hopper_bf16_affine_semantics,
     indexed_gate,
     indexed_gate_rms_norm_scale_shift,
     indexed_scale_shift_,
@@ -190,3 +191,55 @@ def test_fused_modulation_preserves_bf16_residual_boundary() -> None:
     )
 
     assert torch.equal(modulated_out, expected)
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@pytest.mark.skipif(
+    torch.cuda.is_available() and torch.cuda.get_device_capability()[0] != 9,
+    reason="SM90-specific precision path",
+)
+@pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
+def test_hopper_fused_modulation_matches_pytorch_reference() -> None:
+    torch.manual_seed(42)
+    rows, hidden_size, conditions = 128, 3072, 4
+    residual = torch.randn(rows, hidden_size, device="cuda", dtype=torch.bfloat16)
+    gate = torch.randn(conditions, hidden_size, device="cuda", dtype=torch.bfloat16)
+    branch = torch.randn(rows, hidden_size, device="cuda", dtype=torch.bfloat16)
+    weight = torch.randn(hidden_size, device="cuda", dtype=torch.bfloat16)
+    shift = torch.randn(conditions, hidden_size, device="cuda", dtype=torch.bfloat16)
+    scale = torch.randn(conditions, hidden_size, device="cuda", dtype=torch.bfloat16)
+    indices = torch.arange(rows, device="cuda") % conditions
+    eps = 1e-6
+
+    reference_residual = (residual + gate.index_select(0, indices) * branch).to(torch.bfloat16)
+    normalized = reference_residual.float()
+    variance = normalized.pow(2).mean(-1, keepdim=True)
+    normalized = (weight.float() * (normalized * torch.rsqrt(variance + eps))).to(torch.bfloat16)
+    reference_modulated = (normalized * (1.0 + scale.index_select(0, indices)) + shift.index_select(0, indices)).to(
+        torch.bfloat16
+    )
+
+    actual_residual, actual_modulated = indexed_gate_rms_norm_scale_shift(
+        residual,
+        gate,
+        branch,
+        weight,
+        shift,
+        scale,
+        indices,
+        eps,
+    )
+
+    torch.testing.assert_close(actual_residual, reference_residual, atol=5e-2, rtol=5e-2)
+    torch.testing.assert_close(actual_modulated, reference_modulated, atol=5e-2, rtol=5e-2)
+
+
+@pytest.mark.cuda
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+def test_hopper_precision_dispatch_is_architecture_scoped(monkeypatch) -> None:
+    tensor = torch.empty(0, device="cuda")
+    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda _device: (9, 0))
+    assert _use_hopper_bf16_affine_semantics(tensor)
+    monkeypatch.setattr(torch.cuda, "get_device_capability", lambda _device: (10, 3))
+    assert not _use_hopper_bf16_affine_semantics(tensor)
diff --git a/vllm_omni/diffusion/layers/indexed_modulation.py b/vllm_omni/diffusion/layers/indexed_modulation.py
index 385ce1a1be0..0f4f2e59e9e 100644
--- a/vllm_omni/diffusion/layers/indexed_modulation.py
+++ b/vllm_omni/diffusion/layers/indexed_modulation.py
@@ -24,6 +24,18 @@ def _launch_row_chunks(kernel, rows: int, device_type: str, *args, **kwargs) ->
         kernel[(chunk_rows,)](*args, row_offset, **kwargs)
 
 
+def _use_hopper_bf16_affine_semantics(x: torch.Tensor) -> bool:
+    """Use the unfused AdaLN dtype boundaries on Hopper.
+
+    The fused FP32 modulation path is stable on Blackwell, but the SM90
+    kernel can accumulate enough extra precision in the repeated RMSNorm and
+    AdaLN operations to move the 50-step I2VA result below its CI threshold.
+    Keep the existing path on other architectures until their numerical
+    baselines are independently validated.
+    """
+    return x.device.type == "cuda" and torch.cuda.get_device_capability(x.device)[0] == 9
+
+
 @triton.jit
 def _indexed_scale_shift_kernel(
     output_ptr,
@@ -102,6 +114,7 @@ def _rms_norm_indexed_scale_shift_kernel(
     stride_scale_row,
     stride_indices,
     row_offset,
+    use_bf16_affine: tl.constexpr,
     block_n: tl.constexpr,
 ):
     row = tl.program_id(0) + row_offset
@@ -112,13 +125,20 @@ def _rms_norm_indexed_scale_shift_kernel(
     x = tl.load(x_ptr + row * stride_x_row + columns, mask=mask, other=0.0).to(tl.float32)
     weight = tl.load(weight_ptr + columns, mask=mask, other=0.0).to(tl.float32)
     variance = tl.sum(x * x, axis=0) / hidden_size
-    normalized = x * tl.rsqrt(variance + eps) * weight
-
-    shift = tl.load(shift_ptr + index * stride_shift_row + columns, mask=mask, other=0.0).to(tl.float32)
-    scale = tl.load(scale_ptr + index * stride_scale_row + columns, mask=mask, other=0.0).to(tl.float32)
+    if use_bf16_affine:
+        # Match the unfused RMSNorm output consumed by AdaLN on Hopper.
+        normalized = (x * tl.rsqrt(variance + eps) * weight).to(tl.bfloat16)
+        shift = tl.load(shift_ptr + index * stride_shift_row + columns, mask=mask, other=0.0)
+        scale = tl.load(scale_ptr + index * stride_scale_row + columns, mask=mask, other=0.0)
+        output = normalized * (scale + 1.0) + shift
+    else:
+        normalized = x * tl.rsqrt(variance + eps) * weight
+        shift = tl.load(shift_ptr + index * stride_shift_row + columns, mask=mask, other=0.0).to(tl.float32)
+        scale = tl.load(scale_ptr + index * stride_scale_row + columns, mask=mask, other=0.0).to(tl.float32)
+        output = normalized * (1.0 + scale) + shift
     tl.store(
         output_ptr + row * hidden_size + columns,
-        normalized * (1.0 + scale) + shift,
+        output,
         mask=mask,
     )
 
@@ -143,6 +163,7 @@ def _indexed_gate_rms_norm_scale_shift_kernel(
     stride_scale_row,
     stride_indices,
     row_offset,
+    use_bf16_affine: tl.constexpr,
     block_n: tl.constexpr,
 ):
     row = tl.program_id(0) + row_offset
@@ -159,12 +180,20 @@ def _indexed_gate_rms_norm_scale_shift_kernel(
 
     weight = tl.load(weight_ptr + columns, mask=mask, other=0.0).to(tl.float32)
     variance = tl.sum(updated * updated, axis=0) / hidden_size
-    normalized = updated * tl.rsqrt(variance + eps) * weight
-    shift = tl.load(shift_ptr + index * stride_shift_row + columns, mask=mask, other=0.0).to(tl.float32)
-    scale = tl.load(scale_ptr + index * stride_scale_row + columns, mask=mask, other=0.0).to(tl.float32)
+    if use_bf16_affine:
+        # Match the unfused RMSNorm output consumed by AdaLN on Hopper.
+        normalized = (updated * tl.rsqrt(variance + eps) * weight).to(tl.bfloat16)
+        shift = tl.load(shift_ptr + index * stride_shift_row + columns, mask=mask, other=0.0)
+        scale = tl.load(scale_ptr + index * stride_scale_row + columns, mask=mask, other=0.0)
+        output = normalized * (scale + 1.0) + shift
+    else:
+        normalized = updated * tl.rsqrt(variance + eps) * weight
+        shift = tl.load(shift_ptr + index * stride_shift_row + columns, mask=mask, other=0.0).to(tl.float32)
+        scale = tl.load(scale_ptr + index * stride_scale_row + columns, mask=mask, other=0.0).to(tl.float32)
+        output = normalized * (1.0 + scale) + shift
     tl.store(
         modulated_out_ptr + row * hidden_size + columns,
-        normalized * (1.0 + scale) + shift,
+        output,
         mask=mask,
     )
 
@@ -271,6 +300,7 @@ def rms_norm_indexed_scale_shift(
             shift.stride(0),
             scale.stride(0),
             indices.stride(0),
+            use_bf16_affine=_use_hopper_bf16_affine_semantics(x),
             block_n=triton.next_power_of_2(hidden_size),
             num_warps=8,
         )
@@ -324,6 +354,7 @@ def indexed_gate_rms_norm_scale_shift(
             shift.stride(0),
             scale.stride(0),
             indices.stride(0),
+            use_bf16_affine=_use_hopper_bf16_affine_semantics(residual),
             block_n=triton.next_power_of_2(hidden_size),
             num_warps=8,
         )

From 823af92347952708b2496e4b07d2a4a26ed436ac Mon Sep 17 00:00:00 2001
From: ooooooye <53851298+brandneway@users.noreply.github.com>
Date: Fri, 18 Sep 2026 15:36:48 +0800
Subject: [PATCH 083/105] [Bugfix][Ascend NPU][Diffusion] Load over-wide
 unquantized fallback weights straight into host memory under DLOFix/mxfp
 online offload after quant (#7009)

Signed-off-by: brandneway <gyuan4892@gmail.com>
---
 .../distributed_layerwise_offload.md          |  11 +-
 .../model_loader/test_diffusers_loader.py     | 163 ++++++++++++++++++
 .../quantization/test_int8_config.py          | 122 ++++++++++++-
 .../quantization/test_mxfp8_config.py         | 100 ++++++++++-
 .../model_loader/diffusers_loader.py          | 102 +++++++----
 vllm_omni/quantization/int8_config.py         |  86 ++++++++-
 vllm_omni/quantization/mxfp8_config.py        |  24 ++-
 7 files changed, 563 insertions(+), 45 deletions(-)

diff --git a/docs/user_guide/diffusion/offloader/distributed_layerwise_offload.md b/docs/user_guide/diffusion/offloader/distributed_layerwise_offload.md
index b6e67c5cab1..d36afb79ee1 100644
--- a/docs/user_guide/diffusion/offloader/distributed_layerwise_offload.md
+++ b/docs/user_guide/diffusion/offloader/distributed_layerwise_offload.md
@@ -353,9 +353,14 @@ modes can resolve the same `None` value to different schedules.
   Cache-DiT on any selected component. Prompt-embedding cache is also
   incompatible when the text encoder uses `allgather`. Rank-local cache hits
   could otherwise make ranks enter different weight collectives.
-- Per-tensor online FP8 linears use the ordinary loader and can run with either
-  DiT transfer path. With DiT `allgather`, every rank temporarily materializes
-  the complete FP8 model in host memory before DLO retains only its shard.
+- Per-tensor online FP8, INT8, and MXFP8 linears use the ordinary loader and
+  can run with either DiT transfer path. With DiT `allgather`, every rank
+  temporarily materializes the complete quantized model in host memory before
+  DLO retains only its shard. Layers too wide for the NPU quantization kernel
+  (`npu_quant_matmul` rejects an output dimension past 65535) stay
+  unquantized and load straight into host memory under offload-after-quant —
+  their runtime layout is a plain contiguous bf16 weight, the same layout DLO
+  shards on the ordinary path, so they are allowed under `allgather` too.
   Other online quantization methods require rank-local transfer for the
   affected component until their runtime layouts are validated.
 - Resident leading layers require DiT `rank-local` transfer and a model
diff --git a/tests/diffusion/model_loader/test_diffusers_loader.py b/tests/diffusion/model_loader/test_diffusers_loader.py
index c7a87ac343a..8a2ee0900d1 100644
--- a/tests/diffusion/model_loader/test_diffusers_loader.py
+++ b/tests/diffusion/model_loader/test_diffusers_loader.py
@@ -1241,6 +1241,169 @@ class UnsupportedOnlineMethod:
         loader.load_model(load_device="cpu")
 
 
+def test_dlo_allgather_allows_unquantized_host_fallback():
+    """Host-loaded unquantized fallback layers are plain contiguous bf16 —
+    the same runtime layout DLO already shards on the ordinary path — so the
+    allowlist must not reject them."""
+    from vllm_omni.quantization.int8_config import UnquantizedHostLinearMethod
+
+    model = nn.Module()
+    model.transformer = nn.Linear(2, 2, bias=False)
+    model.transformer.quant_method = object.__new__(UnquantizedHostLinearMethod)
+
+    assert DiffusersPipelineLoader._unsupported_dlo_allgather_online_quant_methods(model) == ()
+
+
+def test_dlo_load_model_keeps_host_fallback_on_cpu_through_post_load_sweep(monkeypatch, mocker):
+    """Through load_model(): DLO + online quant must build the model inside
+    load_unquantizable_fallback_on_cpu(), and the over-wide fallback weight
+    must survive the post-load sweep (the _process_weights_after_loading pass
+    plus model.to("cpu")) as the same host tensor it was loaded into — never
+    bounced to the accelerator."""
+    import vllm_omni.diffusion.model_loader.diffusers_loader as loader_mod
+    from vllm_omni.quantization import int8_config
+    from vllm_omni.quantization.int8_config import (
+        NPU_QUANT_MATMUL_MAX_OUT_FEATURES,
+        DiffusionInt8Config,
+        NPUInt8OnlineLinearMethod,
+        UnquantizedHostLinearMethod,
+    )
+
+    # Same stand-in as TestHostFallbackLoading: the eager fallback delegates to
+    # UnquantizedLinearMethod, which reads the TP group.
+    mock_group = mocker.Mock()
+    mock_group.rank_in_group = 0
+    mocker.patch("vllm.model_executor.layers.linear.get_tensor_model_parallel_world_size", return_value=1)
+    mocker.patch("vllm.model_executor.layers.linear.get_tensor_model_parallel_rank", return_value=0)
+    mocker.patch("vllm.distributed.parallel_state.get_tp_group", return_value=mock_group)
+
+    od_config = _make_dlo_online_quant_config()
+    loader = DiffusersPipelineLoader(LoadConfig(), od_config)
+
+    out_features = NPU_QUANT_MATMUL_MAX_OUT_FEATURES + 1
+    built_with_ctx: list[bool] = []
+
+    def copy_loader(param, loaded_weight, *args, **kwargs):
+        param.data.copy_(loaded_weight)
+
+    def build_model(*_args, **_kwargs):
+        built_with_ctx.append(int8_config._LOAD_UNQUANTIZABLE_FALLBACK_ON_CPU.get())
+        quant_config = DiffusionInt8Config(is_checkpoint_int8_serialized=False, activation_scheme="dynamic")
+        method = NPUInt8OnlineLinearMethod(quant_config)
+        layer = nn.Module()
+        layer.quant_method = method
+        method.create_weights(
+            layer,
+            input_size_per_partition=8,
+            output_partition_sizes=[out_features],
+            input_size=8,
+            output_size=out_features,
+            params_dtype=torch.bfloat16,
+            weight_loader=copy_loader,
+        )
+        model = nn.Module()
+        model.transformer = layer
+        return model
+
+    def load_weights(_model, **_kwargs):
+        layer = _model.transformer
+        loaded = torch.arange(out_features * 8, dtype=torch.float32).reshape(out_features, 8).to(torch.bfloat16)
+        layer.weight.weight_loader(layer.weight, loaded)
+
+    loader._init_from_load_format = build_model  # type: ignore[method-assign]
+    loader.load_weights = load_weights  # type: ignore[method-assign]
+    loader._apply_skip_softmax_calibration = lambda _model: None  # type: ignore[method-assign]
+    monkeypatch.setattr(
+        loader_mod,
+        "build_checkpoint_mmap_plan",
+        lambda *_args, **_kwargs: HostWeightPlanResult(
+            None,
+            "online quantization requires the ordinary loader",
+        ),
+    )
+    # Diffusion DiT models have no vLLM Attention layers, so the upstream
+    # layerwise finalize is a no-op here; stub it to keep the real
+    # _process_weights_after_loading sweep CPU-only.
+    monkeypatch.setattr(
+        "vllm.model_executor.model_loader.reload.layerwise.finalize_layerwise_processing",
+        lambda *_args, **_kwargs: None,
+    )
+
+    model = loader.load_model(load_device="cpu", device=torch.device("cpu"))
+
+    # Construction ran inside load_unquantizable_fallback_on_cpu(), so the
+    # over-wide layer took the host-loading fallback...
+    assert built_with_ctx == [True]
+    assert type(model.transformer.quant_method) is UnquantizedHostLinearMethod
+    # ...and the real post-load sweep skipped it via the fully-loaded flag and
+    # model.to("cpu") left the loaded host tensor untouched.
+    assert model.transformer._already_called_process_weights_after_loading
+    assert model.transformer.weight.device.type == "cpu"
+    expected = torch.arange(out_features * 8, dtype=torch.float32).reshape(out_features, 8).to(torch.bfloat16)
+    assert torch.equal(model.transformer.weight, expected)
+
+
+@pytest.mark.parametrize(("offload_after_quant", "ctx_expected"), [(True, True), (False, False)])
+def test_hsdp_enters_host_fallback_context_only_when_offloading_after_quant(mocker, offload_after_quant, ctx_expected):
+    """The HSDP path must apply the same host-fallback bound as the ordinary
+    path: with a quant config it initializes on the accelerator, so the
+    load_unquantizable_fallback_on_cpu() context is what keeps over-wide
+    fallback weights off the device before sharding."""
+    import vllm_omni.diffusion.model_loader.diffusers_loader as loader_mod
+    from vllm_omni.diffusion.offloader.module_collector import PipelineModules
+    from vllm_omni.quantization import int8_config
+
+    od_config = SimpleNamespace(
+        dtype=torch.float32,
+        parallel_config=SimpleNamespace(
+            use_hsdp=True,
+            hsdp_replicate_size=1,
+            hsdp_shard_size=2,
+        ),
+        quantization_config=None,
+    )
+    loader = DiffusersPipelineLoader(LoadConfig(), od_config)
+    loader.quant_config = object()
+
+    model = nn.Module()
+    model.transformer = nn.Linear(2, 2, bias=False)
+    ctx_seen: list[bool] = []
+
+    def build_model(*_args, **_kwargs):
+        ctx_seen.append(int8_config._LOAD_UNQUANTIZABLE_FALLBACK_ON_CPU.get())
+        return model
+
+    loader._init_from_load_format = build_model  # type: ignore[method-assign]
+    loader.load_weights = lambda _model: None  # type: ignore[method-assign]
+    loader._process_weights_after_loading = lambda *_args: None  # type: ignore[method-assign]
+    mocker.patch.object(
+        loader_mod.ModuleDiscovery,
+        "discover",
+        return_value=PipelineModules(
+            dits=[model.transformer],
+            dit_names=["transformer"],
+            vaes=[],
+            encoders=[],
+            encoder_names=[],
+            resident_modules=[],
+            resident_names=[],
+        ),
+    )
+    mocker.patch(
+        "vllm_omni.diffusion.quantization.hsdp_fp8.prepare_fp8_layers_for_fsdp",
+        side_effect=lambda _model: None,
+    )
+    mocker.patch.object(
+        loader_mod,
+        "apply_hsdp_to_model",
+        side_effect=lambda *_args, **_kwargs: None,
+    )
+
+    loader._load_model_with_hsdp(torch.device("cpu"), offload_after_quant=offload_after_quant)
+
+    assert ctx_seen == [ctx_expected]
+
+
 def test_dlo_allgather_online_mxfp8_uses_ordinary_loader(monkeypatch):
     mxfp8_config = pytest.importorskip("vllm_omni.quantization.mxfp8_config")
     NPUMxfp8OnlineLinearMethod = mxfp8_config.NPUMxfp8OnlineLinearMethod
diff --git a/tests/diffusion/quantization/test_int8_config.py b/tests/diffusion/quantization/test_int8_config.py
index f706cc68b00..6eba09c214f 100644
--- a/tests/diffusion/quantization/test_int8_config.py
+++ b/tests/diffusion/quantization/test_int8_config.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Unit tests for Int8 quantization config."""
 
 import pytest
@@ -12,7 +12,7 @@
 from vllm_omni.quantization import build_quant_config
 from vllm_omni.quantization.factory import SUPPORTED_QUANTIZATION_METHODS
 
-pytestmark = [pytest.mark.core_model, pytest.mark.diffusion]
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
 
 npu_available = pytest.mark.skipif(not current_omni_platform.is_npu(), reason="NPU platform not available.")
 
@@ -248,6 +248,124 @@ def test_tensor_parallel_sharding_brings_a_wide_layer_back(self, quant_config):
         assert layer.quant_method is method
 
 
+class TestHostFallbackLoading:
+    """Over-wide fallback layers load straight into host memory when the loader
+    will offload the model back to CPU after online quantization (DLO).
+
+    Without the context the eager path is preserved: the fallback weight is a
+    real tensor created at construction time.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _mock_tp(self, mocker):
+        # Same stand-in as TestNPUQuantMatmulShapeFallback: the eager fallback
+        # delegates to UnquantizedLinearMethod, which reads the TP group.
+        mock_group = mocker.Mock()
+        mock_group.rank_in_group = 0
+        mocker.patch("vllm.model_executor.layers.linear.get_tensor_model_parallel_world_size", return_value=1)
+        mocker.patch("vllm.model_executor.layers.linear.get_tensor_model_parallel_rank", return_value=0)
+        mocker.patch("vllm.distributed.parallel_state.get_tp_group", return_value=mock_group)
+
+    @pytest.fixture
+    def quant_config(self):
+        from vllm_omni.quantization.int8_config import DiffusionInt8Config
+
+        return DiffusionInt8Config(is_checkpoint_int8_serialized=False, activation_scheme="dynamic")
+
+    def _make_over_wide_layer(self, quant_config, weight_loader):
+        from vllm_omni.quantization.int8_config import (
+            NPU_QUANT_MATMUL_MAX_OUT_FEATURES,
+            NPUInt8OnlineLinearMethod,
+        )
+
+        out_features = NPU_QUANT_MATMUL_MAX_OUT_FEATURES + 1
+        method = NPUInt8OnlineLinearMethod(quant_config)
+        layer = Module()
+        layer.quant_method = method
+        method.create_weights(
+            layer,
+            input_size_per_partition=8,
+            output_partition_sizes=[out_features],
+            input_size=8,
+            output_size=out_features,
+            params_dtype=torch.bfloat16,
+            weight_loader=weight_loader,
+        )
+        return layer, out_features
+
+    @staticmethod
+    def _loaded_values(out_features):
+        return torch.arange(out_features * 8, dtype=torch.float32).reshape(out_features, 8).to(torch.bfloat16)
+
+    def test_fallback_without_context_keeps_eager_weights(self, quant_config):
+        layer, _ = self._make_over_wide_layer(quant_config, lambda param, loaded_weight, *a, **k: None)
+
+        assert type(layer.quant_method) is UnquantizedLinearMethod
+        assert layer.weight.device.type != "meta"
+
+    def test_fallback_under_context_defers_weight_to_meta(self, quant_config):
+        from vllm_omni.quantization.int8_config import (
+            UnquantizedHostLinearMethod,
+            load_unquantizable_fallback_on_cpu,
+        )
+
+        with load_unquantizable_fallback_on_cpu():
+            layer, _ = self._make_over_wide_layer(quant_config, lambda param, loaded_weight, *a, **k: None)
+
+        assert isinstance(layer.quant_method, UnquantizedHostLinearMethod)
+        assert layer.quant_method.uses_meta_device
+        assert layer.weight.device.type == "meta"
+
+    def test_fallback_weight_loads_straight_to_cpu(self, quant_config):
+        from vllm_omni.quantization.int8_config import load_unquantizable_fallback_on_cpu
+
+        def copy_loader(param, loaded_weight, *args, **kwargs):
+            param.data.copy_(loaded_weight)
+
+        with load_unquantizable_fallback_on_cpu():
+            layer, out_features = self._make_over_wide_layer(quant_config, copy_loader)
+
+        loaded = self._loaded_values(out_features)
+        layer.weight.weight_loader(layer.weight, loaded)
+
+        assert layer.weight.device.type == "cpu"
+        assert torch.equal(layer.weight, loaded)
+        # Marks the post-load sweep to skip the layer instead of bouncing the
+        # host tensor to the accelerator and back for a no-op process call.
+        assert layer._already_called_process_weights_after_loading
+
+    def test_chunked_load_marks_completion_only_when_full(self, quant_config):
+        from vllm_omni.quantization.int8_config import load_unquantizable_fallback_on_cpu
+
+        state = {"offset": 0}
+
+        def half_loader(param, loaded_weight, *args, **kwargs):
+            start = state["offset"]
+            param.data[start : start + loaded_weight.shape[0]].copy_(loaded_weight)
+            state["offset"] += loaded_weight.shape[0]
+
+        with load_unquantizable_fallback_on_cpu():
+            layer, out_features = self._make_over_wide_layer(quant_config, half_loader)
+
+        loaded = self._loaded_values(out_features)
+        halves = loaded.chunk(2, dim=0)
+        layer.weight.weight_loader(layer.weight, halves[0])
+        assert not getattr(layer, "_already_called_process_weights_after_loading", False)
+
+        layer.weight.weight_loader(layer.weight, halves[1])
+        assert layer._already_called_process_weights_after_loading
+        assert torch.equal(layer.weight, loaded)
+
+    def test_context_does_not_leak(self, quant_config):
+        from vllm_omni.quantization.int8_config import load_unquantizable_fallback_on_cpu
+
+        with load_unquantizable_fallback_on_cpu():
+            pass
+        layer, _ = self._make_over_wide_layer(quant_config, lambda param, loaded_weight, *a, **k: None)
+
+        assert type(layer.quant_method) is UnquantizedLinearMethod
+
+
 class TestOffloadAfterQuant:
     def test_only_methods_advertising_the_capability_are_asked(self):
         from vllm_omni.diffusion.model_loader.diffusers_loader import DiffusersPipelineLoader
diff --git a/tests/diffusion/quantization/test_mxfp8_config.py b/tests/diffusion/quantization/test_mxfp8_config.py
index cc34fb23225..7c3745d4b2a 100644
--- a/tests/diffusion/quantization/test_mxfp8_config.py
+++ b/tests/diffusion/quantization/test_mxfp8_config.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Tests for MXFP8 quantization config and linear method dispatch.
 
 Coverage:
@@ -9,11 +9,13 @@
 - Weight / scale shape-transform arithmetic from process_weights_after_loading (CPU)
 - build_quant_config integration
 - MXFP8_QUANT_CONFIG structure as the auto-detection contract
+- Offload-after-quant capability of the shared online-method mixin (CPU)
 """
 
 import pytest
 import torch
 from pytest_mock import MockerFixture
+from torch.nn import Module
 from vllm.model_executor.layers.linear import LinearBase, UnquantizedLinearMethod
 
 from vllm_omni.platforms import current_omni_platform
@@ -335,3 +337,99 @@ def test_supported_methods_include_mxfp8():
     from vllm_omni.quantization import SUPPORTED_QUANTIZATION_METHODS
 
     assert "mxfp8" in SUPPORTED_QUANTIZATION_METHODS
+
+
+# ---------------------------------------------------------------------------
+# Offload-after-quant capability (CPU, no NPU ops)
+# ---------------------------------------------------------------------------
+
+
+class TestOffloadAfterQuant:
+    """Online MXFP methods advertise ``supports_offload_after_quant`` so the
+    diffusion loader can stream each layer back to host memory right after it
+    is quantized, instead of accumulating the whole model on the accelerator
+    until the final ``model.to("cpu")``.
+
+    The capability lives on ``_LazyWeightMixin``, which is shared by all
+    online MXFP8/MXFP4 methods, so pinning it here covers mxfp4 too.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _mock_tp(self, mocker: MockerFixture):
+        # create_weights resolves the TP group while computing per-partition
+        # shapes; these tests never initialize torch.distributed.
+        mock_group = mocker.Mock()
+        mock_group.rank_in_group = 0
+        mocker.patch("vllm.model_executor.layers.linear.get_tensor_model_parallel_world_size", return_value=1)
+        mocker.patch("vllm.model_executor.layers.linear.get_tensor_model_parallel_rank", return_value=0)
+        mocker.patch("vllm.distributed.parallel_state.get_tp_group", return_value=mock_group)
+
+    def _make_method(self):
+        from vllm_omni.quantization.mxfp8_config import (
+            DiffusionMXFP8Config,
+            NPUMxfp8OnlineLinearMethod,
+        )
+
+        return NPUMxfp8OnlineLinearMethod(DiffusionMXFP8Config(is_checkpoint_mxfp8_serialized=False))
+
+    def test_only_methods_advertising_the_capability_are_asked(self):
+        from vllm_omni.diffusion.model_loader.diffusers_loader import (
+            DiffusersPipelineLoader,
+        )
+
+        class MetaDeviceOnlyMethod:
+            """Stands in for upstream online FP8: lazy, but no offload hook."""
+
+            uses_meta_device = True
+
+        model = torch.nn.Sequential(Module(), Module())
+        lazy_mxfp8 = self._make_method()
+        model[0].quant_method = lazy_mxfp8
+        model[1].quant_method = MetaDeviceOnlyMethod()
+
+        marked = DiffusersPipelineLoader._request_offload_after_quant(model)
+
+        assert marked == 1
+        assert lazy_mxfp8._offload_after_quant
+
+    def _load_layer_in_one_chunk(self, method, layer):
+        method.create_weights(
+            layer,
+            input_size_per_partition=8,
+            output_partition_sizes=[4],
+            input_size=8,
+            output_size=4,
+            params_dtype=torch.bfloat16,
+            weight_loader=lambda param, loaded_weight, *args, **kwargs: param.copy_(loaded_weight),
+        )
+        full_weight = torch.randn(4, 8, dtype=torch.bfloat16)
+        layer.weight.weight_loader(layer.weight, full_weight)
+
+    def test_finished_layer_returns_to_cpu_when_enabled(self, mocker: MockerFixture):
+        method = self._make_method()
+        method.enable_offload_after_quant()
+        mocker.patch.object(method, "process_weights_after_loading")
+
+        layer = Module()
+        moved_to = []
+        layer.to = lambda device, *args, **kwargs: moved_to.append(device)  # type: ignore[method-assign]
+
+        self._load_layer_in_one_chunk(method, layer)
+
+        method.process_weights_after_loading.assert_called_once_with(layer)
+        assert layer._already_called_process_weights_after_loading
+        assert moved_to == ["cpu"]
+
+    def test_finished_layer_stays_put_by_default(self, mocker: MockerFixture):
+        method = self._make_method()
+        mocker.patch.object(method, "process_weights_after_loading")
+
+        layer = Module()
+        moved_to = []
+        layer.to = lambda device, *args, **kwargs: moved_to.append(device)  # type: ignore[method-assign]
+
+        self._load_layer_in_one_chunk(method, layer)
+
+        method.process_weights_after_loading.assert_called_once_with(layer)
+        assert layer._already_called_process_weights_after_loading
+        assert moved_to == []
diff --git a/vllm_omni/diffusion/model_loader/diffusers_loader.py b/vllm_omni/diffusion/model_loader/diffusers_loader.py
index 834887f4150..c47eab7f7e9 100644
--- a/vllm_omni/diffusion/model_loader/diffusers_loader.py
+++ b/vllm_omni/diffusion/model_loader/diffusers_loader.py
@@ -679,10 +679,21 @@ def load_model(
         with set_default_torch_dtype(self.od_config.dtype):
             if self.parallel_config.use_hsdp:
                 model = self._load_model_with_hsdp(
-                    target_device=device, load_format=load_format, custom_pipeline_name=custom_pipeline_name
+                    target_device=device,
+                    load_format=load_format,
+                    custom_pipeline_name=custom_pipeline_name,
+                    offload_after_quant=offload_after_quant,
                 )
             else:
-                model = self._init_from_load_format(load_format, target_device, custom_pipeline_name, is_hsdp=False)
+                # The model is headed back to host memory right after online
+                # quantization, so over-wide NPU-unquantizable fallback weights
+                # load straight into host memory instead of round-tripping
+                # through the accelerator (~24 GiB startup peak on MiniMax H3).
+                from vllm_omni.quantization.int8_config import load_unquantizable_fallback_on_cpu
+
+                fallback_ctx = load_unquantizable_fallback_on_cpu() if offload_after_quant else contextlib.nullcontext()
+                with fallback_ctx:
+                    model = self._init_from_load_format(load_format, target_device, custom_pipeline_name, is_hsdp=False)
 
                 resolved_offload = resolve_offload(self.od_config)
                 distributed_offload = resolved_offload.strategy is OffloadStrategy.DISTRIBUTED_LAYER_WISE
@@ -721,8 +732,9 @@ def load_model(
                     if unsupported_methods:
                         raise ValueError(
                             "DLO+AllGather supports online quantization only for "
-                            "per-tensor FP8, INT8, and MXFP8 linears; unsupported "
-                            f"online methods: {', '.join(sorted(unsupported_methods))}. "
+                            "per-tensor FP8, INT8, and MXFP8 linears "
+                            "(host-loaded unquantized fallback layers are also allowed); "
+                            f"unsupported online methods: {', '.join(sorted(unsupported_methods))}. "
                             "Use rank-local transfer for the affected component or "
                             "disable online quantization."
                         )
@@ -930,6 +942,11 @@ def _unsupported_dlo_allgather_online_quant_methods(model: nn.Module) -> tuple[s
         scale, packing, or aliasing layouts (e.g. dual-scale fp4 pairs,
         swizzled or NZ hardware formats) and remain fail-closed until
         validated.
+
+        ``UnquantizedHostLinearMethod`` is also allowed: it backs layers too
+        wide for npu_quant_matmul, loads their weights straight into host
+        memory, and its runtime layout is a plain contiguous bf16 weight —
+        identical to the ordinary unquantized path DLO already shards.
         """
         from vllm.model_executor.layers.quantization.online.fp8 import (
             Fp8PerTensorOnlineLinearMethod,
@@ -938,6 +955,7 @@ def _unsupported_dlo_allgather_online_quant_methods(model: nn.Module) -> tuple[s
         from vllm_omni.quantization.int8_config import (
             Int8OnlineLinearMethod,
             NPUInt8OnlineLinearMethod,
+            UnquantizedHostLinearMethod,
         )
 
         try:
@@ -959,6 +977,7 @@ def _unsupported_dlo_allgather_online_quant_methods(model: nn.Module) -> tuple[s
             Fp8PerTensorOnlineLinearMethod,
             Int8OnlineLinearMethod,
             NPUInt8OnlineLinearMethod,
+            UnquantizedHostLinearMethod,
             *mxfp8_online_methods,
         )
 
@@ -1208,6 +1227,7 @@ def _load_model_with_hsdp(
         target_device: torch.device,
         load_format: str = "default",
         custom_pipeline_name: str | type[nn.Module] | None = None,
+        offload_after_quant: bool = False,
     ) -> nn.Module:
         """Load model with HSDP sharding for inference.
 
@@ -1231,40 +1251,54 @@ def _load_model_with_hsdp(
         # mapping (QKV fusion, etc.).
         if load_format == "diffusers":
             raise ValueError("HSDP is not supported with the diffusers adapter load format")
-        model = self._init_from_load_format(load_format, target_device, custom_pipeline_name, is_hsdp=True)
-        world_size = 1
-        rank = 0
-        if torch.distributed.is_initialized():
-            world_size = torch.distributed.get_world_size()
-            rank = torch.distributed.get_rank()
-
-        has_online_quant = self._has_online_quant(model) or (
-            self.quant_config is not None and not getattr(self.quant_config, "is_checkpoint_quantized", False)
-        )
-        enable_broadcast = bool(getattr(self.od_config, "enable_broadcast_weight_load", False)) and world_size > 1
-
-        if enable_broadcast and has_online_quant:
-            logger.info(
-                "Worker %d: Online quantization detected; falling back to ordinary per-rank weight loading for HSDP",
-                rank,
+        # Same host-fallback bound as the ordinary path: with a quant config the
+        # HSDP path initializes on the accelerator (hsdp_defer_to_cpu=False), so
+        # over-wide NPU-unquantizable fallback weights would otherwise round-trip
+        # through the device before apply_hsdp_to_model shards them. Loading them
+        # straight into host memory keeps the load-time device peak at the
+        # quantizable layers alone; sharding then distributes the fallback like
+        # any other parameter. Broadcast loading excludes online quantization
+        # already, so the context below only ever matters on the ordinary
+        # per-rank branch -- but spanning both is harmless.
+        from vllm_omni.quantization.int8_config import load_unquantizable_fallback_on_cpu
+
+        fallback_ctx = load_unquantizable_fallback_on_cpu() if offload_after_quant else contextlib.nullcontext()
+        with fallback_ctx:
+            model = self._init_from_load_format(load_format, target_device, custom_pipeline_name, is_hsdp=True)
+            world_size = 1
+            rank = 0
+            if torch.distributed.is_initialized():
+                world_size = torch.distributed.get_world_size()
+                rank = torch.distributed.get_rank()
+
+            has_online_quant = self._has_online_quant(model) or (
+                self.quant_config is not None and not getattr(self.quant_config, "is_checkpoint_quantized", False)
             )
-            enable_broadcast = False
+            enable_broadcast = bool(getattr(self.od_config, "enable_broadcast_weight_load", False)) and world_size > 1
+
+            if enable_broadcast and has_online_quant:
+                logger.info(
+                    "Worker %d: Online quantization detected; falling back to ordinary "
+                    "per-rank weight loading for HSDP",
+                    rank,
+                )
+                enable_broadcast = False
 
-        if enable_broadcast:
-            if rank == 0:
+            if enable_broadcast:
+                if rank == 0:
+                    self.load_weights(model)
+                    self._maybe_fuse_distilled_lora(model)
+                self._broadcast_model_weights(model, target_device=target_device, src_rank=0)
+                if (
+                    rank != 0
+                    and getattr(self.od_config, "lora_backend", None) in (LoRABackend.DISTILL, "distill")
+                    and getattr(self.od_config, "lora_path", None)
+                    and hasattr(model, "load_lora_weights")
+                ):
+                    setattr(model, "lora_is_fused", True)
+            else:
                 self.load_weights(model)
                 self._maybe_fuse_distilled_lora(model)
-            self._broadcast_model_weights(model, target_device=target_device, src_rank=0)
-            if (
-                rank != 0
-                and getattr(self.od_config, "lora_backend", None) in (LoRABackend.DISTILL, "distill")
-                and getattr(self.od_config, "lora_path", None)
-                and hasattr(model, "load_lora_weights")
-            ):
-                setattr(model, "lora_is_fused", True)
-        else:
-            self.load_weights(model)
-            self._maybe_fuse_distilled_lora(model)
 
         # Quantization methods must finish while parameters are ordinary local
         # tensors. Some post-load transforms use operations (for example,
diff --git a/vllm_omni/quantization/int8_config.py b/vllm_omni/quantization/int8_config.py
index de31fbc3ab6..c7abe209f5a 100644
--- a/vllm_omni/quantization/int8_config.py
+++ b/vllm_omni/quantization/int8_config.py
@@ -7,6 +7,8 @@
 """
 
 from collections.abc import Callable
+from contextlib import contextmanager
+from contextvars import ContextVar
 from typing import TYPE_CHECKING, Any, Optional
 
 import torch
@@ -62,6 +64,32 @@
 
 logger = init_logger(__name__)
 
+# Set by the diffusion loader while it constructs a model whose weights will be
+# offloaded back to host memory after online quantization (DLO). Over-wide
+# layers that npu_quant_matmul cannot run then load straight into host memory
+# instead of being built on the accelerator and moved off at the end of
+# loading — on MiniMax H3 the 50 fallback adaln layers are ~24 GiB of bf16,
+# which is the dominant startup memory peak.
+_LOAD_UNQUANTIZABLE_FALLBACK_ON_CPU: ContextVar[bool] = ContextVar(
+    "int8_load_unquantizable_fallback_on_cpu", default=False
+)
+
+
+@contextmanager
+def load_unquantizable_fallback_on_cpu():
+    """Create npu_quant_matmul-incompatible fallback weights on meta and load
+    them straight into host memory.
+
+    Only valid when the whole model returns to the host after loading (the
+    loader's offload-after-quant path); otherwise the fallback weights would
+    stay on CPU while the rest of the model runs on the accelerator.
+    """
+    token = _LOAD_UNQUANTIZABLE_FALLBACK_ON_CPU.set(True)
+    try:
+        yield
+    finally:
+        _LOAD_UNQUANTIZABLE_FALLBACK_ON_CPU.reset(token)
+
 
 def _fell_back_to_unquantized_npu(
     layer: torch.nn.Module,
@@ -90,7 +118,15 @@ def _fell_back_to_unquantized_npu(
         output_size_per_partition,
         NPU_QUANT_MATMUL_MAX_OUT_FEATURES,
     )
-    fallback = UnquantizedLinearMethod()
+    if _LOAD_UNQUANTIZABLE_FALLBACK_ON_CPU.get():
+        logger.info_once(
+            "Loading over-wide unquantized fallback weights straight into host memory "
+            "(offload-after-quant is active); they only reach the accelerator via "
+            "the offload backend's runtime prefetch."
+        )
+        fallback: LinearMethodBase = UnquantizedHostLinearMethod()
+    else:
+        fallback = UnquantizedLinearMethod()
     layer.quant_method = fallback
     fallback.create_weights(
         layer,
@@ -297,6 +333,14 @@ def enable_offload_after_quant(self) -> None:
         """
         self._offload_after_quant = True
 
+    def _lazy_load_device(self) -> torch.device:
+        """Device the meta weight materializes on at first load.
+
+        Subclasses that never want the accelerator involved (e.g. the
+        over-wide host fallback) override this to return host memory.
+        """
+        return torch.get_default_device()
+
     def create_weights(
         self,
         layer: torch.nn.Module,
@@ -347,7 +391,7 @@ def patched_weight_loader(param, loaded_weight, *args, **kwargs):
             # process_weights_after_loading
             target_loaded_numel = layer.weight.numel()
             if layer._loaded_numel == target_loaded_numel:
-                self.process_weights_after_loading(layer)
+                self.process_weights_after_loading(layer)  # type: ignore[attr-defined]
 
                 # Prevent the usual `process_weights_after_loading` call from doing
                 # anything
@@ -378,10 +422,46 @@ def patched_weight_loader(param, loaded_weight, *args, **kwargs):
             weight_loader=patched_weight_loader,
         )
         # stash the correct device for `patched_weight_loader`
-        layer._load_device = torch.get_default_device()
+        layer._load_device = self._lazy_load_device()
         layer.register_parameter("weight", weight)
 
 
+class UnquantizedHostLinearMethod(LazyWeightMixin, UnquantizedLinearMethod):
+    """Unquantized linear method whose weight loads straight into host memory.
+
+    Layers wider than ``NPU_QUANT_MATMUL_MAX_OUT_FEATURES`` cannot be quantized,
+    so under the ordinary path their bf16 weights materialize on the accelerator
+    at construction time and stay there until the whole model is moved off after
+    loading. When the loader has entered ``load_unquantizable_fallback_on_cpu()``
+    (offload-after-quant, i.e. DLO), that round trip is pure startup peak — the
+    weights end up pinned on the host either way and only visit the accelerator
+    through the offload backend's runtime prefetch.
+
+    This method reuses ``LazyWeightMixin``'s meta + just-in-time materialization
+    wholesale (the weight really is deferred on meta until loading, like the
+    online quant methods, so the loader's meta-aware bookkeeping treats the
+    layer correctly) and only overrides the materialization target to host
+    memory: checkpoint chunks are CPU tensors, so loading stays CPU->CPU with
+    no accelerator round trip.
+    """
+
+    # Offload-after-quant marking is deliberately not advertised even though
+    # the mixin provides the hook: the weight never visits the accelerator,
+    # so there is nothing to return to host.
+    supports_offload_after_quant: bool = False
+
+    def _lazy_load_device(self) -> torch.device:
+        return torch.device("cpu")
+
+    def process_weights_after_loading(self, layer: torch.nn.Module) -> None:
+        """Unquantized weights need no post-load transform.
+
+        The mixin calls this when the weight is fully loaded, right before it
+        flags the layer — and the flag is what keeps the loader's post-load
+        sweep from bouncing the host tensor to the accelerator and back.
+        """
+
+
 class Int8LinearMethod(BaseInt8LinearMethod):
     """
     Linear method for Int8
diff --git a/vllm_omni/quantization/mxfp8_config.py b/vllm_omni/quantization/mxfp8_config.py
index 69e51dc6bcb..28a91574b79 100644
--- a/vllm_omni/quantization/mxfp8_config.py
+++ b/vllm_omni/quantization/mxfp8_config.py
@@ -167,6 +167,21 @@ class _LazyWeightMixin:
 
     uses_meta_device: bool = True
 
+    # This mixin knows when a layer's weight is final, so it can hand the layer
+    # back to the host right there. Loaders that intend to offload the whole
+    # model after loading opt in per layer via ``enable_offload_after_quant``.
+    supports_offload_after_quant: bool = True
+    _offload_after_quant: bool = False
+
+    def enable_offload_after_quant(self) -> None:
+        """Return each layer to host memory as soon as it has been quantized.
+
+        Caps the load-time device footprint at one layer instead of the whole
+        model. A quant method instance belongs to a single layer, so this is not
+        a global switch.
+        """
+        self._offload_after_quant = True
+
     def create_weights(
         self,
         layer: torch.nn.Module,
@@ -202,12 +217,17 @@ def patched_weight_loader(param, loaded_weight, *args, **kwargs):
             param = layer.weight
             counter = CopyNumelCounter()
             with counter:
-                res = weight_loader(param, loaded_weight, *args, **kwargs)
+                res = weight_loader(param, loaded_weight, *args, **kwargs)  # type: ignore[misc]
             layer._loaded_numel += counter.copied_numel
 
             if layer._loaded_numel == layer.weight.numel():
-                self.process_weights_after_loading(layer)
+                self.process_weights_after_loading(layer)  # type: ignore[attr-defined]
                 layer._already_called_process_weights_after_loading = True
+
+                # This layer's weight is final, so nothing needs it on the
+                # accelerator until inference.
+                if self._offload_after_quant:
+                    layer.to("cpu")
             return res
 
         weight = ModelWeightParameter(

From eb2075981d3a2351978bf890bcc8c266c2917887 Mon Sep 17 00:00:00 2001
From: Zeng Chuang <zengchuang3@huawei.com>
Date: Fri, 18 Sep 2026 16:49:08 +0800
Subject: [PATCH 084/105] [Test][Ascend] Share HunyuanVideo-1.5 E2E across GPU
 and NPU (#7547)

Signed-off-by: zengchuang <zengchuang3@huawei.com>
---
 .buildkite/npu/test-npu-nightly.yml           | 31 ++++++++
 .../test_hunyuanvideo15_t2v_vllm_omni.json    |  3 +-
 .../test_hunyuan_video_15_expansion.py        | 76 +++++++++++++------
 3 files changed, 85 insertions(+), 25 deletions(-)

diff --git a/.buildkite/npu/test-npu-nightly.yml b/.buildkite/npu/test-npu-nightly.yml
index f64fa711f64..0c39a3f93a1 100644
--- a/.buildkite/npu/test-npu-nightly.yml
+++ b/.buildkite/npu/test-npu-nightly.yml
@@ -235,6 +235,37 @@ steps:
       build.env("NIGHTLY") == "1" ||
       build.pull_request.labels includes "nightly-test"
     steps:
+      - label: ":full_moon: Diffusion X2V · HunyuanVideo-1.5 Function Test"
+        source_file_dependencies: diffusion_hunyuan_video_function
+        timeout_in_minutes: 180
+        mirror_hardwares: a2b3_npu_4
+        env:
+          VLLM_WORKER_MULTIPROC_METHOD: spawn
+          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
+          HF_TOKEN: "${HF_TOKEN}"
+          HF_HUB_OFFLINE: "1"
+        commands:
+          - pytest -s -v tests/e2e/online_serving/test_hunyuan_video_15_expansion.py -m "npu and A2" --run-level "full_model"
+      - label: ":full_moon: Diffusion X2V · HunyuanVideo-1.5 Perf Test"
+        source_file_dependencies: diffusion_hunyuan_video_perf
+        key: nightly-diffusion-x2v-performance-hunyuanvideo15
+        timeout_in_minutes: 180
+        mirror_hardwares: a3_npu_2
+        env:
+          VLLM_WORKER_MULTIPROC_METHOD: spawn
+          VLLM_ALLOW_LONG_MAX_MODEL_LEN: "1"
+          HF_TOKEN: "${HF_TOKEN}"
+          HF_HUB_OFFLINE: "1"
+          DIFFUSION_ATTENTION_BACKEND: TORCH_SDPA
+        commands:
+          - export DIFFUSION_BENCHMARK_DIR=tests/dfx/perf/results
+          - |
+            set +e
+            pytest -s -v tests/dfx/perf/scripts/run_diffusion_benchmark.py -m "npu and A3" --test-config-file tests/dfx/perf/tests/test_hunyuanvideo15_t2v_vllm_omni.json
+            EXIT=$$?
+            buildkite-agent artifact upload "tests/dfx/perf/results/diffusion_result_*.json"
+            buildkite-agent artifact upload "tests/dfx/perf/results/logs/*.log"
+            exit $$EXIT
       - label: ":full_moon: Diffusion X2V · Wan 2.2 Function Test"
         source_file_dependencies: diffusion_wan22_function
         mirror_hardwares: a2b3_npu_4
diff --git a/tests/dfx/perf/tests/test_hunyuanvideo15_t2v_vllm_omni.json b/tests/dfx/perf/tests/test_hunyuanvideo15_t2v_vllm_omni.json
index ffaaba43614..6a3433dbe2c 100644
--- a/tests/dfx/perf/tests/test_hunyuanvideo15_t2v_vllm_omni.json
+++ b/tests/dfx/perf/tests/test_hunyuanvideo15_t2v_vllm_omni.json
@@ -54,7 +54,8 @@
       {
         "hardware_marks": {
           "res": {
-            "cuda": ["H100", "B200"]
+            "cuda": ["H100", "B200"],
+            "npu": "A3"
           },
           "num_cards": 2
         }
diff --git a/tests/e2e/online_serving/test_hunyuan_video_15_expansion.py b/tests/e2e/online_serving/test_hunyuan_video_15_expansion.py
index 1d6df33176c..3d54303f77f 100644
--- a/tests/e2e/online_serving/test_hunyuan_video_15_expansion.py
+++ b/tests/e2e/online_serving/test_hunyuan_video_15_expansion.py
@@ -4,14 +4,15 @@
 Tests of common diffusion feature combinations in online serving mode
 for HunyuanVideo-1.5-T2V (480p).
 
-Coverage (H100, since model cannot fit L4):
-- CPU offloading (1 GPU) — ``core_model`` + ``advanced_model``
-- CacheDiT + Layerwise CPU offloading (1 GPU) — ``full_model``
-- CacheDiT + TP=2 + VAE patch parallel=2 (2 GPUs) — ``full_model``
-
-HunyuanVideo-1.5 is a high-priority model, so only the most basic single-card deployment
-row runs on every PR (L2) and on merge (L3). The heavyweight feature combinations stay
-nightly-only (L4), together with the video similarity suites in
+Coverage:
+- Default single-card deployment (H100, B200, or Ascend A2) — ``full_model``
+- CPU offloading (1 H100 or Ascend A2) — ``core_model`` + ``advanced_model``
+- CacheDiT + Layerwise CPU offloading (1 H100, B200, or Ascend A2) — ``full_model``
+- CacheDiT + TP=2 + VAE patch parallel=2 (2 H100s, B200s, or Ascend A2s) — ``full_model``
+
+HunyuanVideo-1.5 is a high-priority model. The CPU-offload row runs in the existing
+CUDA PR (L2) and merge (L3) lanes. The shared default and CacheDiT / parallel rows
+carry ``full_model`` (L4) marks, together with the video similarity suites in
 ``tests/e2e/accuracy/hunyuanvideo15_{t2v,i2v}/``.
 
 From ``tests/``::
@@ -23,8 +24,9 @@
 
 import pytest
 
-from tests.helpers.mark import hardware_marks
+from tests.helpers.mark import hardware_marks, hardware_test
 from tests.helpers.runtime import OmniServer, OmniServerParams, OnlineOmniClient
+from tests.helpers.stage_config import get_deploy_config_path
 
 pytestmark = [pytest.mark.diffusion]
 
@@ -32,17 +34,25 @@
 NEGATIVE_PROMPT = "low quality, blurry, distorted"
 
 MODEL = "hunyuanvideo-community/HunyuanVideo-1.5-Diffusers-480p_t2v"
+DEPLOY_CONFIG = get_deploy_config_path("hunyuan_video_15.yaml")
+
+DEFAULT_TEST_PARAMS = [
+    pytest.param(
+        OmniServerParams(model=MODEL, stage_config_path=DEPLOY_CONFIG),
+        id="default",
+    )
+]
 
 
 def _get_diffusion_feature_cases(model: str):
     """Return diffusion feature cases for HunyuanVideo-1.5.
 
-    Designed for 2x H100 environment per issue #1832.
+    Designed for up to two accelerators per issue #1832.
     Only the CPU-offload row is cheap enough for PR (L2) / merge (L3);
     CacheDiT / parallel combinations run nightly (L4).
     """
     return [
-        # (1 GPU) CPU offload
+        # (1 accelerator) CPU offload
         pytest.param(
             OmniServerParams(
                 model=model,
@@ -52,12 +62,12 @@ def _get_diffusion_feature_cases(model: str):
             ),
             id="single_card_cpu_offload",
             marks=[
-                *hardware_marks(res={"cuda": "H100"}),
+                *hardware_marks(res={"cuda": "H100", "npu": "A2"}),
                 pytest.mark.core_model,
                 pytest.mark.advanced_model,
             ],
         ),
-        # (1 GPU) CacheDiT + Layerwise CPU offloading
+        # (1 accelerator) CacheDiT + Layerwise CPU offloading
         pytest.param(
             OmniServerParams(
                 model=model,
@@ -69,11 +79,11 @@ def _get_diffusion_feature_cases(model: str):
             ),
             id="single_card_cachedit_layerwise",
             marks=[
-                *hardware_marks(res={"cuda": ["H100", "B200"]}),
+                *hardware_marks(res={"cuda": ["H100", "B200"], "npu": "A2"}),
                 pytest.mark.full_model,
             ],
         ),
-        # (2 GPUs) CacheDiT + TP=2 + VAE patch parallel=2
+        # (2 accelerators) CacheDiT + TP=2 + VAE patch parallel=2
         pytest.param(
             OmniServerParams(
                 model=model,
@@ -89,23 +99,17 @@ def _get_diffusion_feature_cases(model: str):
             ),
             id="parallel_cachedit_tp2_vae2",
             marks=[
-                *hardware_marks(res={"cuda": ["H100", "B200"]}, num_cards=2),
+                *hardware_marks(res={"cuda": ["H100", "B200"], "npu": "A2"}, num_cards=2),
                 pytest.mark.full_model,
             ],
         ),
     ]
 
 
-@pytest.mark.parametrize(
-    "omni_server",
-    _get_diffusion_feature_cases(MODEL),
-    indirect=True,
-)
-def test_hunyuan_video_15_t2v(
+def _run_hunyuan_video_15_t2v(
     omni_server: OmniServer,
     online_client: OnlineOmniClient,
-):
-    """Diffusion feature coverage for HunyuanVideo-1.5-T2V on H100."""
+) -> None:
     form_data = {
         "prompt": PROMPT,
         "negative_prompt": NEGATIVE_PROMPT,
@@ -123,3 +127,27 @@ def test_hunyuan_video_15_t2v(
     }
 
     online_client.send_video_diffusion_request(request_config)
+
+
+@hardware_test(res={"cuda": ["H100", "B200"], "npu": "A2"}, num_cards=1)
+@pytest.mark.full_model
+@pytest.mark.parametrize("omni_server", DEFAULT_TEST_PARAMS, indirect=True)
+def test_hunyuan_video_15_t2v_default(
+    omni_server: OmniServer,
+    online_client: OnlineOmniClient,
+) -> None:
+    """Generate a short video with the shared default GPU/NPU configuration."""
+    _run_hunyuan_video_15_t2v(omni_server, online_client)
+
+
+@pytest.mark.parametrize(
+    "omni_server",
+    _get_diffusion_feature_cases(MODEL),
+    indirect=True,
+)
+def test_hunyuan_video_15_t2v_features(
+    omni_server: OmniServer,
+    online_client: OnlineOmniClient,
+) -> None:
+    """Exercise shared diffusion features for HunyuanVideo-1.5-T2V."""
+    _run_hunyuan_video_15_t2v(omni_server, online_client)

From aa2fadac42a9370d33958351ed8bc8869d4c8354 Mon Sep 17 00:00:00 2001
From: holykie <116775684+holykie@users.noreply.github.com>
Date: Fri, 18 Sep 2026 16:51:23 +0800
Subject: [PATCH 085/105] [Perf][Diffusion] Activate NPU/GPU matmul for LoRA
 delta computation when weights are on CPU (#7590)

Signed-off-by: holykie <116775684+holykie@users.noreply.github.com>
---
 tests/diffusion/lora/test_loader.py | 79 +++++++++++++++++++++++++++++
 vllm_omni/diffusion/lora/loader.py  | 27 +++++++++-
 2 files changed, 104 insertions(+), 2 deletions(-)

diff --git a/tests/diffusion/lora/test_loader.py b/tests/diffusion/lora/test_loader.py
index 4fd8769372c..a10d609d825 100644
--- a/tests/diffusion/lora/test_loader.py
+++ b/tests/diffusion/lora/test_loader.py
@@ -18,6 +18,7 @@
     WanLoraLoaderMixin,
     _prepare_lora_delta,
     _remap_state_dict_keys,
+    _resolve_lora_compute_device,
 )
 
 HEAD_DIM = 24
@@ -521,3 +522,81 @@ def test_prepare_lora_delta_with_compute_device():
     assert delta is not None
     assert delta.shape == (HEAD_DIM, HEAD_DIM)
     assert len(used_keys) == 2
+
+
+def test_resolve_lora_compute_device_probes_unusable_accelerator(mocker: MockerFixture):
+    """cuda:N/npu:N may be reported without a physical device; the probe must reject it."""
+    mocker.patch(
+        "vllm_omni.diffusion.lora.loader.get_local_device",
+        return_value=torch.device("cuda:999"),
+    )
+    assert _resolve_lora_compute_device() is None
+
+
+def test_load_lora_into_module_cpu_weights_match_cpu_reference(mocker: MockerFixture):
+    """Regression test: params on CPU used to force compute_device=None and skip the
+    #7005 accelerator path. With an unusable accelerator, fusion must fall back to
+    CPU and still produce base + lora_B @ lora_A."""
+    pipeline = DummyPipeline(NUM_LAYERS, HEAD_DIM)
+    original_params = {name: param.clone() for name, param in pipeline.transformer.named_parameters()}
+
+    lora_state_dict = make_lora_state_dict_for_module(pipeline.transformer)
+    lora_state_dict = _remap_state_dict_keys(lora_state_dict, [(".to_out.0.", ".to_out.")])
+
+    mocker.patch(
+        "vllm_omni.diffusion.lora.loader.get_local_device",
+        return_value=torch.device("cuda:999"),
+    )
+
+    used_keys = pipeline.load_lora_into_module(lora_state_dict, pipeline.transformer)
+    assert len(used_keys) > 0
+    assert not (set(lora_state_dict.keys()) - used_keys)
+
+    for name, param in pipeline.transformer.named_parameters():
+        if not name.endswith(".weight"):
+            continue
+        base_key = name[: -len(".weight")]
+        key_a = f"{base_key}.lora_A.weight"
+        key_b = f"{base_key}.lora_B.weight"
+        if key_a in lora_state_dict and key_b in lora_state_dict:
+            expected = original_params[name] + (
+                lora_state_dict[key_b].to(param.dtype) @ lora_state_dict[key_a].to(param.dtype)
+            )
+            assert_close(param, expected)
+
+
+def test_load_lora_into_module_forwards_usable_accel_device(mocker: MockerFixture):
+    """A usable accelerator must be forwarded as compute_device for CPU params.
+    A spy forces the actual math back onto CPU so the test runs without a device."""
+    fake_dev = torch.device("cuda:0")
+    mocker.patch(
+        "vllm_omni.diffusion.lora.loader._resolve_lora_compute_device",
+        return_value=fake_dev,
+    )
+
+    seen_devices = []
+    original = _prepare_lora_delta
+
+    def spy(state_dict, base_key, *args, **kwargs):
+        seen_devices.append(kwargs.get("compute_device"))
+        kwargs["compute_device"] = None
+        return original(state_dict, base_key, *args, **kwargs)
+
+    mocker.patch(
+        "vllm_omni.diffusion.lora.loader._prepare_lora_delta",
+        side_effect=spy,
+    )
+
+    pipeline = DummyPipeline(NUM_LAYERS, HEAD_DIM)
+    original_params = {name: param.clone() for name, param in pipeline.transformer.named_parameters()}
+
+    lora_state_dict = make_lora_state_dict_for_module(pipeline.transformer)
+    lora_state_dict = _remap_state_dict_keys(lora_state_dict, [(".to_out.0.", ".to_out.")])
+
+    used_keys = pipeline.load_lora_into_module(lora_state_dict, pipeline.transformer)
+
+    # Every CPU param with a LoRA delta must have received the accelerator device.
+    assert seen_devices
+    assert all(d == fake_dev for d in seen_devices)
+    assert not (set(lora_state_dict.keys()) - used_keys)
+    assert_params_not_equal(pipeline.transformer, original_params)
diff --git a/vllm_omni/diffusion/lora/loader.py b/vllm_omni/diffusion/lora/loader.py
index eb3f35188ea..8ed60ea066a 100644
--- a/vllm_omni/diffusion/lora/loader.py
+++ b/vllm_omni/diffusion/lora/loader.py
@@ -13,6 +13,7 @@
 from safetensors.torch import load_file
 from vllm.logger import init_logger
 
+from vllm_omni.diffusion.distributed.utils import get_local_device
 from vllm_omni.diffusion.utils.tf_utils import get_transformer_from_pipeline
 from vllm_omni.transformers_utils.repo_utils import hf_api
 
@@ -120,6 +121,22 @@ def _prepare_lora_delta(
     return delta, used_keys
 
 
+def _resolve_lora_compute_device() -> torch.device | None:
+    """Return the local accelerator device if actually usable, else None.
+
+    get_local_device() may return cuda:N/npu:N even when no physical device is
+    present, so probe with a tiny allocation before trusting the lookup.
+    """
+    try:
+        dev = get_local_device()
+        if dev.type != "cpu":
+            torch.empty(1, device=dev)
+            return dev
+    except Exception:
+        pass
+    return None
+
+
 def _load_lora_state_dict(
     pretrained_model_name_or_path: str,
     weights_name: str | None = None,
@@ -270,6 +287,9 @@ def load_lora_into_module(
             for param_name, weight_name, _ in module.stacked_params_mapping:
                 param_to_weight_names[param_name].append(weight_name)
 
+        # Resolve the accelerator fallback once, outside the parameter loop.
+        accel_dev = _resolve_lora_compute_device()
+
         for name, params in module.named_parameters(prefix):
             is_bias = False
             if name.endswith(".bias"):
@@ -280,7 +300,7 @@ def load_lora_into_module(
             else:
                 continue
 
-            compute_dev = params.device if params.device.type != "cpu" else None
+            compute_dev = params.device if params.device.type != "cpu" else accel_dev
             delta, used_keys = _prepare_lora_delta(
                 state_dict,
                 base_key,
@@ -324,6 +344,9 @@ def unload_module_lora(
             for param_name, weight_name, _ in module.stacked_params_mapping:
                 param_to_weight_names[param_name].append(weight_name)
 
+        # Resolve the accelerator fallback once, outside the parameter loop.
+        accel_dev = _resolve_lora_compute_device()
+
         for name, param in module.named_parameters(prefix):
             is_bias = False
             if name.endswith(".bias"):
@@ -334,7 +357,7 @@ def unload_module_lora(
             else:
                 continue
 
-            compute_dev = param.device if param.device.type != "cpu" else None
+            compute_dev = param.device if param.device.type != "cpu" else accel_dev
             delta, used_keys = _prepare_lora_delta(
                 state_dict,
                 base_key,

From 6df62d51573ca5be7826321ba2de1cd071d997f8 Mon Sep 17 00:00:00 2001
From: chickeyton <ngton2014@gmail.com>
Date: Fri, 18 Sep 2026 16:58:33 +0800
Subject: [PATCH 086/105] [CI/Build][MiniCPM-o] Fix the Nightly tests (#7758)

Signed-off-by: chickeyton <ngton2014@gmail.com>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
---
 tests/dfx/perf/tests/test_minicpmo_4_5.json   | 86 +++++++++++++++++--
 .../perf/tests/test_minicpmo_4_5_ready.json   | 40 ++++++++-
 .../test_nemotron_voicechat_duplex.py         | 11 ++-
 .../minicpmo_4_5/test_talker_batching.py      | 46 +++++++++-
 .../distributed/omni_connectors/adapter.py    |  9 +-
 .../models/minicpmo_4_5/__init__.py           |  6 ++
 .../minicpmo_4_5/minicpmo_4_5_omni_tts.py     | 42 +++++++--
 .../minicpmo_4_5_omni.py                      | 11 ++-
 8 files changed, 233 insertions(+), 18 deletions(-)

diff --git a/tests/dfx/perf/tests/test_minicpmo_4_5.json b/tests/dfx/perf/tests/test_minicpmo_4_5.json
index b384d61a0e6..7d7ca08adcd 100644
--- a/tests/dfx/perf/tests/test_minicpmo_4_5.json
+++ b/tests/dfx/perf/tests/test_minicpmo_4_5.json
@@ -26,8 +26,8 @@
       {
         "dataset_name": "seed-tts",
         "dataset_path": "zhaochenyang20/seed-tts-eval",
-        "backend": "openai-realtime-tts",
-        "endpoint": "/v1/realtime",
+        "backend": "openai-chat-omni",
+        "endpoint": "/v1/chat/completions",
         "num_prompts": [
           32,
           64,
@@ -42,7 +42,73 @@
         "disable_shuffle": true,
         "trust_remote_code": true,
         "seed_tts_locale": "en",
-        "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration"
+        "extra_body": {
+          "modalities": [
+            "text",
+            "audio"
+          ],
+          "chat_template_kwargs": {
+            "enable_thinking": false,
+            "use_tts_template": true
+          }
+        },
+        "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration",
+        "baseline": {
+          "H100": {
+            "request_throughput": [
+              0.9731,
+              1.1986,
+              1.686
+            ],
+            "mean_ttft_ms": [
+              152.5665,
+              270.2559,
+              301.455
+            ],
+            "mean_e2el_ms": [
+              1027.2953,
+              3306.3735,
+              4686.5366
+            ],
+            "mean_audio_ttfp_ms": [
+              458.1553,
+              2030.2335,
+              2068.6233
+            ],
+            "mean_audio_rtf": [
+              0.2357,
+              0.791,
+              1.0324
+            ]
+          },
+          "A3": {
+            "request_throughput": [
+              0.5383,
+              0.6042,
+              0.7547
+            ],
+            "mean_ttft_ms": [
+              333.2633,
+              533.8656,
+              547.3388
+            ],
+            "mean_e2el_ms": [
+              1857.2154,
+              6600.5101,
+              10450.6811
+            ],
+            "mean_audio_ttfp_ms": [
+              986.4666,
+              3411.0754,
+              3352.7515
+            ],
+            "mean_audio_rtf": [
+              0.4423,
+              1.5734,
+              2.3024
+            ]
+          }
+        }
       }
     ]
   },
@@ -72,8 +138,8 @@
       {
         "dataset_name": "seed-tts",
         "dataset_path": "zhaochenyang20/seed-tts-eval",
-        "backend": "openai-realtime-tts",
-        "endpoint": "/v1/realtime",
+        "backend": "openai-chat-omni",
+        "endpoint": "/v1/chat/completions",
         "num_prompts": [
           32,
           64,
@@ -88,6 +154,16 @@
         "disable_shuffle": true,
         "trust_remote_code": true,
         "seed_tts_locale": "en",
+        "extra_body": {
+          "modalities": [
+            "text",
+            "audio"
+          ],
+          "chat_template_kwargs": {
+            "enable_thinking": false,
+            "use_tts_template": true
+          }
+        },
         "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration"
       }
     ]
diff --git a/tests/dfx/perf/tests/test_minicpmo_4_5_ready.json b/tests/dfx/perf/tests/test_minicpmo_4_5_ready.json
index 4fd78d68139..26dc54aab08 100644
--- a/tests/dfx/perf/tests/test_minicpmo_4_5_ready.json
+++ b/tests/dfx/perf/tests/test_minicpmo_4_5_ready.json
@@ -26,8 +26,8 @@
       {
         "dataset_name": "seed-tts",
         "dataset_path": "zhaochenyang20/seed-tts-eval",
-        "backend": "openai-realtime-tts",
-        "endpoint": "/v1/realtime",
+        "backend": "openai-chat-omni",
+        "endpoint": "/v1/chat/completions",
         "num_prompts": [
           10,
           40
@@ -40,7 +40,41 @@
         "disable_shuffle": true,
         "trust_remote_code": true,
         "seed_tts_locale": "en",
-        "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration"
+        "extra_body": {
+          "modalities": [
+            "text",
+            "audio"
+          ],
+          "chat_template_kwargs": {
+            "enable_thinking": false,
+            "use_tts_template": true
+          }
+        },
+        "percentile-metrics": "ttft,e2el,audio_ttfp,audio_rtf,audio_duration",
+        "baseline": {
+          "H100": {
+            "request_throughput": [
+              0.9731,
+              1.1986
+            ],
+            "mean_ttft_ms": [
+              152.5665,
+              270.2559
+            ],
+            "mean_e2el_ms": [
+              1027.2953,
+              3306.3735
+            ],
+            "mean_audio_ttfp_ms": [
+              458.1553,
+              2030.2335
+            ],
+            "mean_audio_rtf": [
+              0.2357,
+              0.791
+            ]
+          }
+        }
       }
     ]
   }
diff --git a/tests/e2e/online_serving/test_nemotron_voicechat_duplex.py b/tests/e2e/online_serving/test_nemotron_voicechat_duplex.py
index 6f97eaee275..dfb3044e864 100644
--- a/tests/e2e/online_serving/test_nemotron_voicechat_duplex.py
+++ b/tests/e2e/online_serving/test_nemotron_voicechat_duplex.py
@@ -29,7 +29,16 @@
 if TOKENIZER:
     _SERVER_ENV["NEMOTRON_VOICECHAT_LLM_PATH"] = TOKENIZER
 
-pytestmark = [pytest.mark.full_model, pytest.mark.omni]
+pytestmark = [
+    pytest.mark.full_model,
+    pytest.mark.omni,
+    # Since #7413 a duplex-capable model is served by the duplex engine only when
+    # its pipeline declares a duplex_plugin. The Nemotron VoiceChat pipeline does
+    # not, so the server starts the turn engine and the /v1/realtime websocket
+    # falls through to vllm's speech-to-text realtime handler, which rejects the
+    # native duplex client's session.update ("Missing required field: model").
+    pytest.mark.skip(reason="Nemotron VoiceChat is not served by the duplex engine yet (no duplex_plugin)"),
+]
 
 
 @hardware_test(res={"cuda": ["H100", "B200"]}, num_cards=1)
diff --git a/tests/model_executor/models/minicpmo_4_5/test_talker_batching.py b/tests/model_executor/models/minicpmo_4_5/test_talker_batching.py
index 0c5b97ae2b9..4335bb88e1d 100644
--- a/tests/model_executor/models/minicpmo_4_5/test_talker_batching.py
+++ b/tests/model_executor/models/minicpmo_4_5/test_talker_batching.py
@@ -20,12 +20,14 @@
 from vllm_omni.model_executor.models.minicpmo_4_5.minicpmo_4_5_omni_tts import (
     _CODEC_PENALTY_WINDOW,
     _DUPLEX_CODEC_TOKENS_PER_CHUNK,
+    _DUPLEX_TURN_END_CODEC_TOKENS,
     _OFFLINE_CODEC_MAX_NEW_TOKENS,
     _REPETITION_PENALTY_CHUNK_SIZE,
     MiniCPMO45OmniTTSForConditionalGeneration,
     _apply_batched_repetition_penalty,
     _native_duplex_chunk_budget,
     _restore_weight_norm_weight,
+    _turn_end_boundary_eos_masked,
     blank_scheduler_prompt_for_penalties,
 )
 from vllm_omni.utils.mm_outputs import to_payload_element
@@ -453,7 +455,9 @@ def test_sample_leaves_unforced_rows_to_the_sampler(mocker) -> None:
 def test_native_duplex_chunk_budget_masks_eos_until_generate_chunk_is_full() -> None:
     assert _native_duplex_chunk_budget({}) == (_DUPLEX_CODEC_TOKENS_PER_CHUNK, _DUPLEX_CODEC_TOKENS_PER_CHUNK)
     assert _native_duplex_chunk_budget({"turn_start": True}) == (_DUPLEX_CODEC_TOKENS_PER_CHUNK, 0)
-    assert _native_duplex_chunk_budget({"turn_end": True}) == (_DUPLEX_CODEC_TOKENS_PER_CHUNK, 0)
+    # The turn-end chunk drains the owed text: no floor, multi-unit ceiling.
+    assert _native_duplex_chunk_budget({"turn_end": True}) == (_DUPLEX_TURN_END_CODEC_TOKENS, 0)
+    assert _DUPLEX_TURN_END_CODEC_TOKENS > _DUPLEX_CODEC_TOKENS_PER_CHUNK
 
     talker = _make_talker()
     talker._request_audio_states["req-chunk"] = {
@@ -1097,3 +1101,43 @@ def test_request_cleanup_evicts_decode_state() -> None:
 
     assert "req-done" not in talker._request_audio_states
     assert "req-done" not in talker._request_condition_states
+
+
+def test_turn_end_drain_masks_only_the_cadence_eos() -> None:
+    # Early EOS (text spoken before the first boundary) is allowed.
+    assert not _turn_end_boundary_eos_masked(0)
+    assert not _turn_end_boundary_eos_masked(18)
+    assert not _turn_end_boundary_eos_masked(24)
+    # The cadence EOS right after each 25-frame boundary is masked for a short window.
+    assert _turn_end_boundary_eos_masked(25)
+    assert _turn_end_boundary_eos_masked(29)
+    assert not _turn_end_boundary_eos_masked(30)
+    assert not _turn_end_boundary_eos_masked(49)
+    assert _turn_end_boundary_eos_masked(50)
+    assert not _turn_end_boundary_eos_masked(60)
+
+    talker = _make_talker()
+    talker._request_audio_states["req-drain"] = {
+        "finished": False,
+        "step": 25,
+        "max_tokens": _DUPLEX_TURN_END_CODEC_TOKENS,
+        "min_tokens": 0,
+        "turn_end_drain": True,
+    }
+    output = talker.make_omni_output(
+        torch.ones(1, 2),
+        model_intermediate_buffer=[{"request_id": "req-drain", "codes": {"audio": torch.empty(0)}}],
+        request_token_spans=[(0, 1)],
+    )
+    logits = talker.compute_logits(output.text_hidden_states)
+    assert logits[0, 7].item() == float("-inf")
+    assert output.multimodal_outputs["meta"]["finished"][0].item() is False
+
+    talker._request_audio_states["req-drain"]["step"] = 30
+    output = talker.make_omni_output(
+        torch.ones(1, 2),
+        model_intermediate_buffer=[{"request_id": "req-drain", "codes": {"audio": torch.empty(0)}}],
+        request_token_spans=[(0, 1)],
+    )
+    logits = talker.compute_logits(output.text_hidden_states)
+    assert torch.isfinite(logits[0, 7])
diff --git a/vllm_omni/distributed/omni_connectors/adapter.py b/vllm_omni/distributed/omni_connectors/adapter.py
index 79a1d788785..dc3be166fc9 100644
--- a/vllm_omni/distributed/omni_connectors/adapter.py
+++ b/vllm_omni/distributed/omni_connectors/adapter.py
@@ -10,6 +10,11 @@
 
 from .utils.logging import get_connector_logger
 
+# Upper bound on a previous streaming chunk's generation reserve: a duplex
+# turn-end chunk may retain more codec ids than the steady-state per-unit
+# reserve (see MINICPMO45_DUPLEX_TURN_END_CODEC_TOKENS).
+_MAX_PREVIOUS_CHUNK_GENERATION_RESERVE = 26 * 4
+
 logger = get_connector_logger(__name__)
 
 
@@ -345,7 +350,9 @@ def construct_next_stage_streaming_input_prompt(
                 f"confirmed={confirmed_num_computed_tokens}, prompt={request.num_prompt_tokens}"
             )
         previous_codec_ids = list(request._all_token_ids[request.num_prompt_tokens : confirmed_num_computed_tokens])
-        max_confirmed_codec_tokens = generation_reserve - 1
+        # The previous chunk may have been a turn-end unit that ran to the
+        # Talker's EOS with a larger reserve than this chunk's.
+        max_confirmed_codec_tokens = max(generation_reserve, _MAX_PREVIOUS_CHUNK_GENERATION_RESERVE) - 1
         if len(previous_codec_ids) > max_confirmed_codec_tokens:
             raise ValueError(
                 "streaming prompt recompute retained too many codec tokens: "
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/__init__.py b/vllm_omni/model_executor/models/minicpmo_4_5/__init__.py
index 6e8677cf2e8..77ee3b9a060 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/__init__.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/__init__.py
@@ -9,3 +9,9 @@
 
 # One MiniCPMTTS.generate_chunk emits 25 codec frames plus its terminator.
 MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK = 26
+# Codec budget for the Talker chunk that carries the Thinker's turn end. The
+# Talker paces ~1 s of speech per unit and emits its chunk EOS at the 25-frame
+# cadence, while the text it still owes at turn end can exceed one unit. The
+# turn-end chunk may run for several units so the tail of the turn is spoken
+# (see ``_native_duplex_chunk_budget`` and the boundary EOS mask in the Talker).
+MINICPMO45_DUPLEX_TURN_END_CODEC_TOKENS = MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK * 4
diff --git a/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_omni_tts.py b/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_omni_tts.py
index bdc418f051f..67843833dda 100644
--- a/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_omni_tts.py
+++ b/vllm_omni/model_executor/models/minicpmo_4_5/minicpmo_4_5_omni_tts.py
@@ -28,7 +28,10 @@
 from vllm.v1.sample.sampler import Sampler
 
 from vllm_omni.engine.duplex.intermediate import get_tts_handoff
-from vllm_omni.model_executor.models.minicpmo_4_5 import MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK
+from vllm_omni.model_executor.models.minicpmo_4_5 import (
+    MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK,
+    MINICPMO45_DUPLEX_TURN_END_CODEC_TOKENS,
+)
 from vllm_omni.model_executor.models.output_templates import OmniOutput
 from vllm_omni.platforms import current_omni_platform
 
@@ -48,13 +51,38 @@
 # Without this, the single-vocab Sampler keeps the stage-1 request alive
 # until codec EOS / 4096 and Thinker never starts the next model turn.
 _DUPLEX_CODEC_TOKENS_PER_CHUNK = MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK
+_DUPLEX_TURN_END_CODEC_TOKENS = MINICPMO45_DUPLEX_TURN_END_CODEC_TOKENS
+#: Frames the Talker forwards per generate_chunk before its cadence EOS.
+_DUPLEX_CODEC_FRAMES_PER_CHUNK = MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK - 1
+#: On a turn-end chunk the Talker's EOS is masked for this many steps after
+#: each 25-frame boundary: the model emits a cadence EOS there whether or not
+#: its text is spoken, while a genuine end of text shows up as an EOS anywhere
+#: else in the window.
+_DUPLEX_TURN_END_BOUNDARY_MASK_STEPS = 5
 
 
 def _native_duplex_chunk_budget(meta: Mapping[str, Any] | None) -> tuple[int, int]:
     """Return ``(max_tokens, min_tokens)`` for one native-duplex Talker request."""
-    boundary = isinstance(meta, Mapping) and (bool(meta.get("turn_start")) or bool(meta.get("turn_end")))
+    turn_start = isinstance(meta, Mapping) and bool(meta.get("turn_start"))
+    turn_end = isinstance(meta, Mapping) and bool(meta.get("turn_end"))
+    if turn_end:
+        # The turn-end chunk drains the text the Talker still owes: no floor
+        # (an early EOS means the text is spoken) and a multi-unit ceiling.
+        return _DUPLEX_TURN_END_CODEC_TOKENS, 0
     ceiling = _DUPLEX_CODEC_TOKENS_PER_CHUNK
-    return ceiling, 0 if boundary else ceiling
+    return ceiling, 0 if turn_start else ceiling
+
+
+def _turn_end_boundary_eos_masked(step: int) -> bool:
+    """Whether a turn-end chunk masks codec EOS at ``step`` forwarded frames.
+
+    The Talker emits a cadence EOS after every 25 frames regardless of the text
+    left, so a turn-end chunk ignores EOS in a short window after each boundary
+    and lets the model continue; EOS elsewhere ends the chunk as usual.
+    """
+    if step < _DUPLEX_CODEC_FRAMES_PER_CHUNK:
+        return False
+    return step % _DUPLEX_CODEC_FRAMES_PER_CHUNK < _DUPLEX_TURN_END_BOUNDARY_MASK_STEPS
 
 
 def blank_scheduler_prompt_for_penalties(
@@ -367,7 +395,7 @@ def _build_streaming_recompute_embeddings(
             code_ids = torch.as_tensor(previous_codes, device=self.emb_code[0].weight.device, dtype=torch.long)
         else:
             raise ValueError("streaming prompt recompute is missing confirmed codec ids")
-        if code_ids.numel() > _DUPLEX_CODEC_TOKENS_PER_CHUNK - 1:
+        if code_ids.numel() > _DUPLEX_TURN_END_CODEC_TOKENS - 1:
             raise ValueError(f"streaming prompt recompute has too many codec ids: {code_ids.numel()}")
         if code_ids.numel() and bool(((code_ids < 0) | (code_ids >= self._codec_eos_id)).any()):
             raise ValueError("streaming prompt recompute codec ids include an invalid or terminal token")
@@ -500,6 +528,7 @@ def preprocess(
                 "step": 0,
                 "max_tokens": max_tokens,
                 "min_tokens": min_tokens,
+                "turn_end_drain": bool(native_duplex and isinstance(meta, Mapping) and bool(meta.get("turn_end"))),
             }
             if retained_codes:
                 state["recent_codes"] = retained_codes
@@ -653,7 +682,10 @@ def make_omni_output(
                 # plane does not wait for a follow-up empty decode.
                 state["finished"] = True
             force_eos_rows[index] = chunk_done
-            mask_eos_rows[index] = not force_eos_rows[index] and min_tokens is not None and step < int(min_tokens)
+            mask_eos_rows[index] = not force_eos_rows[index] and (
+                (min_tokens is not None and step < int(min_tokens))
+                or (bool(state.get("turn_end_drain")) and _turn_end_boundary_eos_masked(step))
+            )
             terminal_flags[index] = torch.tensor(chunk_done, dtype=torch.bool)
 
         # Empty-speech rows, finished duplex chunks, and offline requests that
diff --git a/vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py b/vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py
index 1c374be8552..4d818b79f84 100644
--- a/vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py
+++ b/vllm_omni/model_executor/stage_input_processors/minicpmo_4_5_omni.py
@@ -16,7 +16,10 @@
     set_tts_handoff,
 )
 from vllm_omni.inputs.data import OmniTokensPrompt
-from vllm_omni.model_executor.models.minicpmo_4_5 import MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK
+from vllm_omni.model_executor.models.minicpmo_4_5 import (
+    MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK,
+    MINICPMO45_DUPLEX_TURN_END_CODEC_TOKENS,
+)
 from vllm_omni.model_executor.models.minicpmo_4_5.pipeline import MINICPMO45_REFERENCE_AUDIO_KEY
 
 logger = logging.getLogger(__name__)
@@ -1010,7 +1013,11 @@ def llm2tts(
             handoff_meta = model_intermediate_buffer.setdefault("meta", {})
             handoff_meta["next_stage_prompt_len"] = condition_length
             if is_native_duplex_handoff:
-                handoff_meta["next_stage_generation_tokens"] = MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK
+                handoff_meta["next_stage_generation_tokens"] = (
+                    MINICPMO45_DUPLEX_TURN_END_CODEC_TOKENS
+                    if native_turn_end_handoff
+                    else MINICPMO45_DUPLEX_CODEC_TOKENS_PER_CHUNK
+                )
                 bridge_states = getattr(_streaming_context, "bridge_states", None)
                 handoff_state = bridge_states.get("minicpmo45_tts_handoff") if isinstance(bridge_states, dict) else None
                 if not isinstance(handoff_state, dict) or handoff_state.get("request_id") != str(llm_output.request_id):

From 3084b5d1073522b970002a2b8127ab0b2354c8a3 Mon Sep 17 00:00:00 2001
From: akshatvishu <akshatnayak197@gmail.com>
Date: Fri, 18 Sep 2026 17:36:57 +0530
Subject: [PATCH 087/105] [BugFix][TTS] Restore MOSS v1 codec streaming (#6420)

Signed-off-by: akshatvishu <akshatnayak197@gmail.com>
---
 tests/config/test_config_factory.py           |   9 +
 .../test_moss_tts_v1_5_expansion.py           |  36 +--
 .../test_audio_tokenizer_v1_streaming.py      | 199 ++++++++++++
 vllm_omni/deploy/moss_tts.yaml                |   8 +
 .../models/moss_tts/audio_tokenizer.py        | 283 +++++++++++++++++-
 .../cuda_graph_streaming_decoder_wrapper.py   |  10 +-
 .../moss_tts/modeling_moss_tts_codec.py       |   3 +-
 7 files changed, 511 insertions(+), 37 deletions(-)
 create mode 100644 tests/model_executor/models/moss_tts/test_audio_tokenizer_v1_streaming.py

diff --git a/tests/config/test_config_factory.py b/tests/config/test_config_factory.py
index 7940e217681..2ea871890ec 100644
--- a/tests/config/test_config_factory.py
+++ b/tests/config/test_config_factory.py
@@ -2625,6 +2625,15 @@ def test_qwen3_tts_propagates_explicit_code2wav_dtype(self, deploy_name, platfor
 
         assert stages[1].yaml_engine_args["dtype"] == dtype
 
+    def test_moss_tts_rocm_disables_codec_cudagraph(self):
+        deploy_path = Path(get_deploy_config_path("moss_tts.yaml"))
+
+        base = load_deploy_config(deploy_path)
+        assert base.stages[1].enforce_eager is False
+
+        rocm = _apply_platform_overrides(base, platform="rocm")
+        assert rocm.stages[1].enforce_eager is True
+
     def test_higgs_audio_v3_rocm_uses_triton_attention(self):
         deploy_path = Path(get_deploy_config_path("higgs_multimodal_qwen3.yaml"))
 
diff --git a/tests/e2e/offline_inference/test_moss_tts_v1_5_expansion.py b/tests/e2e/offline_inference/test_moss_tts_v1_5_expansion.py
index 487a6bfa6e8..b86db369e83 100644
--- a/tests/e2e/offline_inference/test_moss_tts_v1_5_expansion.py
+++ b/tests/e2e/offline_inference/test_moss_tts_v1_5_expansion.py
@@ -1,19 +1,21 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """E2E offline inference test for MOSS-TTS-v1.5 (MossTTSDelay-8B).
 
 MOSS-TTS-v1.5 is a continued-training upgrade of MOSS-TTS 1.0 with the SAME
-``MossTTSDelay`` architecture and API. The 8B checkpoint is H100-gated; small-GPU
-MossTTSDelay coverage stays in ``test_moss_tts_expansion.py``.
+``MossTTSDelay`` architecture and API. The 8B checkpoint runs on H100 or MI325;
+small-GPU MossTTSDelay coverage stays in ``test_moss_tts_expansion.py``.
 """
 
 from __future__ import annotations
 
+import gc
 import os
 import urllib.request
 
 import pytest
 import torch
+from transformers import AutoProcessor
 from vllm import SamplingParams
 
 from tests.helpers.mark import hardware_test
@@ -28,14 +30,10 @@
     {"stage_init_timeout": 600, "trust_remote_code": True},
 )
 
-_SKIP_ISSUE_6417 = pytest.mark.skip(
-    reason="https://github.com/vllm-project/vllm-omni/issues/6417",
-)
-
 pytestmark = [
+    pytest.mark.full_model,
     pytest.mark.slow,
     pytest.mark.tts,
-    _SKIP_ISSUE_6417,
     pytest.mark.parametrize("omni_runner", [_OMNI_RUNNER_PARAM], indirect=True),
 ]
 
@@ -69,15 +67,19 @@ def ref_audio_path(tmp_path_factory) -> str:
 
 
 def _build_request(text: str, ref_audio_path: str) -> dict:
+    processor = AutoProcessor.from_pretrained(MODEL, trust_remote_code=True)
+    message = processor.build_user_message(
+        text=text,
+        reference=[ref_audio_path],
+        language="English",
+    )
+    unified = processor(conversations=[[message]], mode="generation")["input_ids"][0]
+    del processor
+    gc.collect()
+
     return {
-        "prompt": "<|im_start|>assistant\n",
-        "additional_information": {
-            "task_type": ["voice_clone"],
-            "text": [text],
-            "mode": ["voice_clone"],
-            "prompt_audio_path": [ref_audio_path],
-            "seed": [42],
-        },
+        "prompt_token_ids": unified[:, 0].tolist(),
+        "additional_information": {"codes": {"ref": unified[:, 1:].contiguous().to(torch.int64)}},
     }
 
 
@@ -112,7 +114,7 @@ def _collect_audio(omni_runner: OmniRunner, request: dict) -> tuple[torch.Tensor
     raise AssertionError("No stage outputs received")
 
 
-@hardware_test(res={"cuda": "H100"})
+@hardware_test(res={"cuda": "H100", "rocm": "MI325"})
 def test_moss_tts_v15_voice_clone(omni_runner: OmniRunner, ref_audio_path) -> None:
     """MOSS-TTS-v1.5 (8B): voice_clone produces non-empty 24 kHz audio."""
     req = _build_request("Hello, this is a MOSS-TTS v1.5 voice cloning test.", ref_audio_path)
diff --git a/tests/model_executor/models/moss_tts/test_audio_tokenizer_v1_streaming.py b/tests/model_executor/models/moss_tts/test_audio_tokenizer_v1_streaming.py
new file mode 100644
index 00000000000..c0352630738
--- /dev/null
+++ b/tests/model_executor/models/moss_tts/test_audio_tokenizer_v1_streaming.py
@@ -0,0 +1,199 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import pytest
+import torch
+
+from vllm_omni.model_executor.models.moss_tts.audio_tokenizer import (
+    MossAudioTokenizerConfig,
+    MossAudioTokenizerModel,
+    _Attention,
+    _StreamingExecutionContext,
+)
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def _make_codec() -> MossAudioTokenizerModel:
+    torch.manual_seed(0)
+    config = MossAudioTokenizerConfig(
+        sampling_rate=100,
+        downsample_rate=1,
+        causal_transformer_context_duration=0.08,
+        encoder_kwargs=[{"module_type": "PatchedPretransform", "patch_size": 1}],
+        decoder_kwargs=[
+            {
+                "module_type": "Transformer",
+                "input_dimension": 4,
+                "output_dimension": 1,
+                "d_model": 4,
+                "num_heads": 2,
+                "num_layers": 2,
+                "dim_feedforward": 8,
+                "causal": True,
+                "norm": "layer_norm",
+                "positional_embedding": "rope",
+                "max_period": 10_000,
+                "gating": "none",
+                "layer_scale": 0.01,
+                "conv_layout": True,
+            }
+        ],
+        quantizer_kwargs={
+            "input_dim": 4,
+            "rvq_dim": 4,
+            "output_dim": 4,
+            "num_quantizers": 2,
+            "codebook_size": 8,
+            "codebook_dim": 2,
+            "quantizer_type": "rlfq",
+        },
+    )
+    return MossAudioTokenizerModel(config).eval()
+
+
+def _codes(values: list[list[int]]) -> torch.Tensor:
+    return torch.tensor(values, dtype=torch.long)
+
+
+def _reference_audio(codec: MossAudioTokenizerModel, codes: torch.Tensor) -> torch.Tensor:
+    output = codec.batch_decode([codes], num_quantizers=int(codes.shape[0]))
+    assert output.audio is not None
+    return output.audio[0]
+
+
+def _stream(
+    codec: MossAudioTokenizerModel,
+    codes: torch.Tensor,
+    *,
+    slot: int,
+) -> torch.Tensor:
+    output = codec.decode_streaming_batch(
+        codes.unsqueeze(1),
+        torch.tensor([codes.shape[1]], dtype=torch.long),
+        torch.tensor([slot], dtype=torch.long),
+        torch.tensor([True]),
+    )
+    assert output.audio is not None
+    return output.audio[0]
+
+
+def test_streaming_chunks_match_full_decode() -> None:
+    codec = _make_codec()
+    codes = _codes([[1, 2, 3, 4], [4, 3, 2, 1]])
+    expected = _reference_audio(codec, codes)
+
+    codec.initialize_decoder_state_pool(state_capacity=2)
+    first = _stream(codec, codes[:, :2], slot=1)
+    second = _stream(codec, codes[:, 2:], slot=1)
+
+    torch.testing.assert_close(torch.cat([first, second], dim=-1), expected, atol=1e-5, rtol=1e-5)
+
+
+def test_streaming_attention_ring_wrap_matches_full_attention() -> None:
+    torch.manual_seed(0)
+    attention = _Attention(
+        embed_dim=8,
+        num_heads=2,
+        causal=True,
+        max_period=10_000,
+        context=8,
+    ).eval()
+    hidden_states = torch.randn(1, 12, 8)
+    expected = attention(hidden_states)
+
+    attention.initialize_streaming_state(torch.zeros(1, dtype=torch.long))
+    execution_context = _StreamingExecutionContext(
+        state_slot_ids=torch.tensor([0]),
+        valid_rows=torch.tensor([True]),
+    )
+    chunks = [
+        attention(hidden_states[:, start : start + 3], execution_context)
+        for start in range(0, hidden_states.shape[1], 3)
+    ]
+
+    torch.testing.assert_close(torch.cat(chunks, dim=1), expected, atol=1e-6, rtol=1e-6)
+
+
+def test_streaming_slots_keep_independent_state() -> None:
+    codec = _make_codec()
+    first_codes = _codes([[1, 2, 3, 4], [4, 3, 2, 1]])
+    second_codes = _codes([[5, 6, 7, 1], [1, 7, 6, 5]])
+    first_expected = _reference_audio(codec, first_codes)
+    second_expected = _reference_audio(codec, second_codes)
+
+    codec.initialize_decoder_state_pool(state_capacity=3)
+    chunks: list[tuple[torch.Tensor, torch.Tensor]] = []
+    for start in (0, 2):
+        batch = torch.stack([first_codes[:, start : start + 2], second_codes[:, start : start + 2]], dim=1)
+        output = codec.decode_streaming_batch(
+            batch,
+            torch.tensor([2, 2], dtype=torch.long),
+            torch.tensor([2, 0], dtype=torch.long),
+            torch.tensor([True, True]),
+        )
+        assert output.audio is not None
+        chunks.append((output.audio[0], output.audio[1]))
+
+    torch.testing.assert_close(
+        torch.cat([chunk[0] for chunk in chunks], dim=-1),
+        first_expected,
+        atol=1e-5,
+        rtol=1e-5,
+    )
+    torch.testing.assert_close(
+        torch.cat([chunk[1] for chunk in chunks], dim=-1),
+        second_expected,
+        atol=1e-5,
+        rtol=1e-5,
+    )
+
+
+def test_reset_slot_removes_previous_request_state() -> None:
+    codec = _make_codec()
+    old_codes = _codes([[1, 2], [4, 3]])
+    new_codes = _codes([[7, 6], [2, 5]])
+    expected = _reference_audio(codec, new_codes)
+
+    codec.initialize_decoder_state_pool(state_capacity=1)
+    _stream(codec, old_codes, slot=0)
+    codec.reset_decoder_state_slots(torch.tensor([0], dtype=torch.long))
+
+    torch.testing.assert_close(_stream(codec, new_codes, slot=0), expected, atol=1e-5, rtol=1e-5)
+
+
+def test_invalid_padding_row_does_not_advance_state() -> None:
+    codec = _make_codec()
+    codes = _codes([[1, 2], [4, 3]])
+    expected = _reference_audio(codec, codes)
+
+    codec.initialize_decoder_state_pool(state_capacity=1, scratch_capacity=1)
+    padding_output = codec.decode_streaming_batch(
+        codes.unsqueeze(1),
+        torch.tensor([0], dtype=torch.long),
+        torch.tensor([1], dtype=torch.long),
+        torch.tensor([False]),
+    )
+    assert padding_output.audio_lengths is not None
+    assert int(padding_output.audio_lengths[0]) == 0
+
+    torch.testing.assert_close(_stream(codec, codes, slot=1), expected, atol=1e-5, rtol=1e-5)
+
+
+def test_streaming_requires_initialized_state_pool() -> None:
+    codec = _make_codec()
+    codes = _codes([[1], [2]])
+
+    with pytest.raises(RuntimeError, match="state pool is not initialized"):
+        _stream(codec, codes, slot=0)
+
+
+def test_closed_state_pool_can_be_reinitialized() -> None:
+    codec = _make_codec()
+    codes = _codes([[1], [2]])
+
+    codec.initialize_decoder_state_pool(state_capacity=1)
+    codec.close_decoder_state_pool()
+    codec.initialize_decoder_state_pool(state_capacity=1)
+
+    assert _stream(codec, codes, slot=0).numel() > 0
diff --git a/vllm_omni/deploy/moss_tts.yaml b/vllm_omni/deploy/moss_tts.yaml
index 92bd2f3ba84..229377431b0 100644
--- a/vllm_omni/deploy/moss_tts.yaml
+++ b/vllm_omni/deploy/moss_tts.yaml
@@ -57,3 +57,11 @@ stages:
       max_tokens: 65536
       seed: 42
       repetition_penalty: 1.0
+
+platforms:
+  rocm:
+    stages:
+      - stage_id: 1
+        # MIOPEN_FIND_MODE=FAST changes solver selection, not HIP graph safety.
+        # Keep the Conv1d codec outside the outer vLLM graph on ROCm.
+        enforce_eager: true
diff --git a/vllm_omni/model_executor/models/moss_tts/audio_tokenizer.py b/vllm_omni/model_executor/models/moss_tts/audio_tokenizer.py
index 99dcb33e480..a8fd5b25df3 100644
--- a/vllm_omni/model_executor/models/moss_tts/audio_tokenizer.py
+++ b/vllm_omni/model_executor/models/moss_tts/audio_tokenizer.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 # Copyright 2026 OpenMOSS and the HuggingFace Inc. team. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -8,7 +11,6 @@
 #
 # Vendored from OpenMOSS-Team/MOSS-Audio-Tokenizer (configuration_moss_audio_tokenizer.py
 # and modeling_moss_audio_tokenizer.py).  Simplified for inference-only use:
-#   - Streaming KV-cache infrastructure removed (single-pass batch decode only).
 #   - Training-only methods (forward, encode, decode) removed.
 #   - Dead branches removed: gating="none" always, weights_per_step=0 always,
 #     positional_embedding="rope" always, norm="layer_norm" always in default config.
@@ -155,6 +157,29 @@ class MossAudioTokenizerDecoderOutput(ModelOutput):
     audio_lengths: torch.Tensor | None = None
 
 
+@dataclass(frozen=True)
+class _StreamingExecutionContext:
+    state_slot_ids: torch.Tensor
+    valid_rows: torch.Tensor
+
+    def validate(self, *, batch_size: int, state_capacity: int, device: torch.device) -> None:
+        if self.state_slot_ids.shape != (batch_size,):
+            raise ValueError(f"Expected state_slot_ids shape ({batch_size},), got {tuple(self.state_slot_ids.shape)}")
+        if self.valid_rows.shape != (batch_size,):
+            raise ValueError(f"Expected valid_rows shape ({batch_size},), got {tuple(self.valid_rows.shape)}")
+        if self.state_slot_ids.device != device or self.valid_rows.device != device:
+            raise ValueError("Streaming execution metadata must be on the same device as decoder inputs.")
+        if self.state_slot_ids.dtype != torch.long or self.valid_rows.dtype != torch.bool:
+            raise TypeError("state_slot_ids must be int64 and valid_rows must be bool.")
+        if device.type == "cpu" and self.state_slot_ids.numel() > 0:
+            min_slot = int(self.state_slot_ids.min())
+            max_slot = int(self.state_slot_ids.max())
+            if min_slot < 0 or max_slot >= state_capacity:
+                raise ValueError(
+                    f"Decoder state slots must be in [0, {state_capacity}), got {self.state_slot_ids.tolist()}"
+                )
+
+
 # ---------------------------------------------------------------------------
 # Building blocks
 # ---------------------------------------------------------------------------
@@ -169,7 +194,12 @@ def forward(self, x: torch.Tensor) -> torch.Tensor:
         return self.scale * x
 
 
-def _apply_rope(q: torch.Tensor, k: torch.Tensor, max_period: float = 10_000) -> tuple[torch.Tensor, torch.Tensor]:
+def _apply_rope(
+    q: torch.Tensor,
+    k: torch.Tensor,
+    offsets: torch.Tensor | None = None,
+    max_period: float = 10_000,
+) -> tuple[torch.Tensor, torch.Tensor]:
     """Rotary position embedding over sequence dimension (B, H, T, D).
 
     Matches upstream MossAudioTokenizer's ``apply_rope``: pair the last dim
@@ -181,7 +211,10 @@ def _apply_rope(q: torch.Tensor, k: torch.Tensor, max_period: float = 10_000) ->
     half = D // 2
     ds = torch.arange(half, device=q.device, dtype=torch.float32)
     freqs = torch.exp(ds * (-math.log(max_period) * 2 / D))
-    ts = torch.arange(T, device=q.device, dtype=torch.float32).view(1, 1, -1, 1)  # (1, 1, T, 1)
+    if offsets is None:
+        offsets = torch.zeros(B, device=q.device, dtype=torch.long)
+    ts = offsets.float().view(B, 1) + torch.arange(T, device=q.device, dtype=torch.float32)
+    ts = ts.view(B, 1, T, 1)
     rotr = torch.cos(freqs * ts)  # (1, 1, T, D/2)
     roti = torch.sin(freqs * ts)
 
@@ -201,8 +234,80 @@ def _apply_rope(q: torch.Tensor, k: torch.Tensor, max_period: float = 10_000) ->
     return qo, ko
 
 
+class _RingKVCache:
+    def __init__(
+        self,
+        state_capacity: int,
+        num_heads: int,
+        context: int,
+        head_dim: int,
+        *,
+        device: torch.device,
+        dtype: torch.dtype,
+    ) -> None:
+        self.context = context
+        self.cache = torch.zeros(
+            (2, state_capacity, num_heads, context, head_dim),
+            device=device,
+            dtype=dtype,
+        )
+
+    def complete(
+        self,
+        k: torch.Tensor,
+        v: torch.Tensor,
+        offsets: torch.Tensor,
+        execution_context: _StreamingExecutionContext,
+    ) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
+        batch_size, num_heads, num_frames, head_dim = k.shape
+        slots = execution_context.state_slot_ids
+        row_cache = self.cache.index_select(1, slots)
+        cache_indexes = torch.arange(self.context, device=offsets.device, dtype=torch.long)
+        last_offset = offsets.view(-1, 1) - 1
+        end_index = last_offset % self.context
+        delta = cache_indexes - end_index
+        cached_positions = torch.where(
+            delta <= 0,
+            last_offset + delta,
+            last_offset + delta - self.context,
+        )
+        cached_positions = torch.where(
+            (cache_indexes < offsets.view(-1, 1)) & execution_context.valid_rows.view(-1, 1),
+            cached_positions,
+            torch.full_like(cached_positions, -1),
+        )
+        current_positions = offsets.view(-1, 1) + torch.arange(num_frames, device=offsets.device, dtype=offsets.dtype)
+        current_positions = torch.where(
+            execution_context.valid_rows.view(-1, 1),
+            current_positions,
+            torch.full_like(current_positions, -1),
+        )
+
+        # Keep this chunk separate from the pre-write cache so a ring wrap does
+        # not overwrite keys that early queries in the chunk still need.
+        keys = torch.cat((row_cache[0], k), dim=2)
+        values = torch.cat((row_cache[1], v), dim=2)
+        positions = torch.cat((cached_positions, current_positions), dim=1)
+
+        cache_frames = min(num_frames, self.context)
+        cache_start = offsets.view(-1, 1) + num_frames - cache_frames
+        indexes = torch.arange(cache_frames, device=offsets.device, dtype=offsets.dtype)
+        indexes = (indexes + cache_start) % self.context
+        scatter_indexes = indexes.view(batch_size, 1, cache_frames, 1).expand(-1, num_heads, -1, head_dim)
+        row_cache[0].scatter_(2, scatter_indexes, k[:, :, -cache_frames:])
+        row_cache[1].scatter_(2, scatter_indexes, v[:, :, -cache_frames:])
+        self.cache.index_copy_(1, slots, row_cache)
+        return keys, values, positions
+
+
+@dataclass
+class _AttentionStreamingState:
+    offsets: torch.Tensor
+    kv_cache: _RingKVCache
+
+
 class _Attention(nn.Module):
-    """Causal multi-head self-attention with RoPE, no streaming KV cache."""
+    """Causal multi-head self-attention with request-addressed streaming state."""
 
     def __init__(
         self,
@@ -220,6 +325,7 @@ def __init__(
         self.causal = causal
         self.max_period = max_period
         self.context = context
+        self._streaming_state: _AttentionStreamingState | None = None
         kw = {"device": device, "dtype": dtype}
         self.in_proj = nn.Linear(embed_dim, 3 * embed_dim, bias=False, **kw)
         self.out_proj = nn.Linear(embed_dim, embed_dim, bias=False, **kw)
@@ -240,12 +346,58 @@ def _remap_weights(module, state_dict, prefix, *_):
                     dst = src.replace("in_projs.0.", "in_proj.").replace("out_projs.0.", "out_proj.")
                     state_dict[dst] = state_dict.pop(src)
 
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
+    def initialize_streaming_state(self, offsets: torch.Tensor) -> None:
+        if self._streaming_state is not None:
+            raise RuntimeError("MOSS Audio Tokenizer attention is already streaming.")
+        weight = self.in_proj.weight
+        head_dim = self.embed_dim // self.num_heads
+        self._streaming_state = _AttentionStreamingState(
+            offsets=offsets,
+            kv_cache=_RingKVCache(
+                offsets.shape[0],
+                self.num_heads,
+                self.context or 1024,
+                head_dim,
+                device=weight.device,
+                dtype=weight.dtype,
+            ),
+        )
+
+    def close_streaming_state(self) -> None:
+        self._streaming_state = None
+
+    def forward(
+        self,
+        x: torch.Tensor,
+        execution_context: _StreamingExecutionContext | None = None,
+    ) -> torch.Tensor:
         B, T, _ = x.shape
         H, D = self.num_heads, self.embed_dim // self.num_heads
         qkv = self.in_proj(x).reshape(B, T, 3, H, D).permute(2, 0, 3, 1, 4)
         q, k, v = qkv[0], qkv[1], qkv[2]  # each (B, H, T, D)
-        q, k = _apply_rope(q, k, self.max_period)
+        state = self._streaming_state
+        if execution_context is None:
+            offsets = torch.zeros(B, device=x.device, dtype=torch.long)
+        else:
+            if state is None:
+                raise RuntimeError("MOSS Audio Tokenizer decoder state pool is not initialized.")
+            offsets = state.offsets.index_select(0, execution_context.state_slot_ids)
+        q, k = _apply_rope(q, k, offsets, self.max_period)
+
+        if execution_context is not None:
+            assert state is not None
+            k, v, key_positions = state.kv_cache.complete(k, v, offsets, execution_context)
+            query_positions = offsets.view(-1, 1, 1) + torch.arange(T, device=x.device).view(1, -1, 1)
+            delta = query_positions - key_positions.view(B, 1, -1)
+            mask = (key_positions.view(B, 1, -1) >= 0) & (delta >= 0)
+            if self.context is not None:
+                mask &= delta < self.context
+            out = F.scaled_dot_product_attention(q, k, v, attn_mask=mask.unsqueeze(1))
+            next_offsets = torch.where(execution_context.valid_rows, offsets + T, offsets)
+            state.offsets.index_copy_(0, execution_context.state_slot_ids, next_offsets)
+            out = out.transpose(1, 2).reshape(B, T, self.embed_dim)
+            return self.out_proj(out)
+
         if self.context is not None and self.context < T:
             # Local-windowed causal attention: query i may only see keys in
             # [i - context + 1, i]. Matches upstream's per-stage receptive
@@ -310,8 +462,12 @@ def __init__(
             self.ls1 = nn.Identity()
             self.ls2 = nn.Identity()
 
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
-        x = x + self.ls1(self.attn(self.norm1(x)))
+    def forward(
+        self,
+        x: torch.Tensor,
+        execution_context: _StreamingExecutionContext | None = None,
+    ) -> torch.Tensor:
+        x = x + self.ls1(self.attn(self.norm1(x), execution_context))
         x = x + self.ls2(self.ff2(F.gelu(self.ff1(self.norm2(x)))))
         return x
 
@@ -340,9 +496,13 @@ def __init__(
             ]
         )
 
-    def forward(self, x: torch.Tensor) -> torch.Tensor:
+    def forward(
+        self,
+        x: torch.Tensor,
+        execution_context: _StreamingExecutionContext | None = None,
+    ) -> torch.Tensor:
         for layer in self.layers:
-            x = layer(x)
+            x = layer(x, execution_context)
         return x
 
 
@@ -360,9 +520,14 @@ def __init__(
             nn.Linear(d_model, output_dimension, bias=False) if output_dimension != d_model else nn.Identity()
         )
 
-    def forward(self, x: torch.Tensor, lengths: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+    def forward(
+        self,
+        x: torch.Tensor,
+        lengths: torch.Tensor,
+        execution_context: _StreamingExecutionContext | None = None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
         x = self.in_proj(x.transpose(1, 2))  # (B, D, T) → (B, T, d_model)
-        x = self.transformer(x)
+        x = self.transformer(x, execution_context)
         x = self.out_proj(x).transpose(1, 2)  # (B, T, D) → (B, D, T)
         return x, lengths
 
@@ -544,7 +709,7 @@ def _build_modules(
 
 
 class MossAudioTokenizerModel(PreTrainedModel):
-    """MOSS Audio Tokenizer — inference-only (batch_encode / batch_decode)."""
+    """MOSS Audio Tokenizer inference model with stateful decoder streaming."""
 
     config_class = MossAudioTokenizerConfig
     base_model_prefix = ""
@@ -579,8 +744,83 @@ def __init__(self, config: MossAudioTokenizerConfig) -> None:
 
         kw = dict(config.quantizer_kwargs)
         self.quantizer = _ResidualQ(**kw)
+        self._decoder_streaming_attentions: list[_Attention] = []
+        self._decoder_slot_offsets: torch.Tensor | None = None
+        self._decoder_state_capacity = 0
         self.post_init()
 
+    def initialize_decoder_state_pool(self, state_capacity: int, scratch_capacity: int = 0) -> None:
+        if state_capacity <= 0 or scratch_capacity < 0:
+            raise ValueError(f"Invalid decoder state capacities: state={state_capacity}, scratch={scratch_capacity}.")
+        if self._decoder_streaming_attentions:
+            raise RuntimeError("MOSS Audio Tokenizer decoder state pool is already initialized.")
+        attentions = [module for module in self.decoder.modules() if isinstance(module, _Attention)]
+        if not attentions:
+            raise RuntimeError("MOSS Audio Tokenizer decoder has no streaming attention layers.")
+        total_capacity = state_capacity + scratch_capacity
+        offsets = torch.zeros(
+            (len(attentions), total_capacity),
+            device=next(self.parameters()).device,
+            dtype=torch.long,
+        )
+        for index, attention in enumerate(attentions):
+            attention.initialize_streaming_state(offsets[index])
+        self._decoder_streaming_attentions = attentions
+        self._decoder_slot_offsets = offsets
+        self._decoder_state_capacity = total_capacity
+
+    def close_decoder_state_pool(self) -> None:
+        for attention in self._decoder_streaming_attentions:
+            attention.close_streaming_state()
+        self._decoder_streaming_attentions = []
+        self._decoder_slot_offsets = None
+        self._decoder_state_capacity = 0
+
+    def reset_decoder_state_slots(self, state_slot_ids: torch.Tensor) -> None:
+        if not self._decoder_streaming_attentions or self._decoder_slot_offsets is None:
+            raise RuntimeError("MOSS Audio Tokenizer decoder state pool is not initialized.")
+        if state_slot_ids.numel() == 0:
+            return
+        if state_slot_ids.device.type == "cpu":
+            min_slot = int(state_slot_ids.min())
+            max_slot = int(state_slot_ids.max())
+            if min_slot < 0 or max_slot >= self._decoder_state_capacity:
+                raise ValueError(
+                    f"Decoder state slots must be in [0, {self._decoder_state_capacity}), got {state_slot_ids.tolist()}"
+                )
+        slots = state_slot_ids.to(device=self._decoder_slot_offsets.device, dtype=torch.long)
+        # A zero offset marks every old ring-cache entry invalid, so the large
+        # KV buffers do not need to be cleared when a slot is reused.
+        self._decoder_slot_offsets.index_fill_(1, slots, 0)
+
+    def decode_streaming_batch(
+        self,
+        codes: torch.Tensor,
+        codes_lengths: torch.Tensor,
+        state_slot_ids: torch.Tensor,
+        valid_rows: torch.Tensor,
+    ) -> MossAudioTokenizerDecoderOutput:
+        if not self._decoder_streaming_attentions:
+            raise RuntimeError("MOSS Audio Tokenizer decoder state pool is not initialized.")
+        execution_context = _StreamingExecutionContext(state_slot_ids, valid_rows)
+        execution_context.validate(
+            batch_size=int(codes.shape[1]),
+            state_capacity=self._decoder_state_capacity,
+            device=codes.device,
+        )
+        audio, audio_lengths = self._decode_tensors(codes, codes_lengths, execution_context)
+        return MossAudioTokenizerDecoderOutput(audio=audio, audio_lengths=audio_lengths)
+
+    def decode_streaming_tensors(
+        self,
+        codes: torch.Tensor,
+        codes_lengths: torch.Tensor,
+        state_slot_ids: torch.Tensor,
+        valid_rows: torch.Tensor,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        execution_context = _StreamingExecutionContext(state_slot_ids, valid_rows)
+        return self._decode_tensors(codes, codes_lengths, execution_context)
+
     @torch.no_grad()
     def batch_encode(
         self,
@@ -688,13 +928,26 @@ def _decode(
         self,
         codes: torch.Tensor,
         lengths: torch.Tensor,
+        execution_context: _StreamingExecutionContext | None = None,
     ) -> MossAudioTokenizerDecoderOutput:
+        audio, audio_lengths = self._decode_tensors(codes, lengths, execution_context)
+        return MossAudioTokenizerDecoderOutput(audio=audio, audio_lengths=audio_lengths)
+
+    def _decode_tensors(
+        self,
+        codes: torch.Tensor,
+        lengths: torch.Tensor,
+        execution_context: _StreamingExecutionContext | None = None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
         z = self.quantizer.decode_codes(codes)
         d, d_len = z, lengths
         for m in self.decoder:
-            d, d_len = m(d, d_len)
+            if isinstance(m, _ProjectedTransformer):
+                d, d_len = m(d, d_len, execution_context)
+            else:
+                d, d_len = m(d, d_len)
         d, d_len = self._restore_channels_from_codec(d, d_len)
-        return MossAudioTokenizerDecoderOutput(audio=d, audio_lengths=d_len)
+        return d, d_len
 
 
 __all__ = [
diff --git a/vllm_omni/model_executor/models/moss_tts/cuda_graph_streaming_decoder_wrapper.py b/vllm_omni/model_executor/models/moss_tts/cuda_graph_streaming_decoder_wrapper.py
index 52815dd3b89..4d277f44e3a 100644
--- a/vllm_omni/model_executor/models/moss_tts/cuda_graph_streaming_decoder_wrapper.py
+++ b/vllm_omni/model_executor/models/moss_tts/cuda_graph_streaming_decoder_wrapper.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 # Copyright 2026 OpenMOSS and the vLLM-Omni team. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License").
@@ -30,11 +33,10 @@
     }
 )
 class _MossStreamingDecodeCompileAdapter(nn.Module):
-    """Expose the BF16 codec streaming hot path to vLLM compile.
+    """Expose the codec streaming hot path to vLLM compile.
 
-    The dtype is part of the class identity intentionally: vLLM's AOT cache
-    drops runtime guards, so an artifact traced with the old FP32 decoder
-    weights must never be reused after the decoder is materialized as BF16.
+    The wrapper preserves the codec dtype: v1 decodes in FP32 to match its
+    quantizer output, while v2 uses BF16.
     """
 
     def __init__(self, codec: nn.Module, *, vllm_config: VllmConfig) -> None:
diff --git a/vllm_omni/model_executor/models/moss_tts/modeling_moss_tts_codec.py b/vllm_omni/model_executor/models/moss_tts/modeling_moss_tts_codec.py
index c279493102c..fbefe3a6aaa 100644
--- a/vllm_omni/model_executor/models/moss_tts/modeling_moss_tts_codec.py
+++ b/vllm_omni/model_executor/models/moss_tts/modeling_moss_tts_codec.py
@@ -767,7 +767,8 @@ def _remap(name: str) -> str:
         )
 
         codec.eval()
-        if device.type != "cpu":
+        # The v1 quantizer emits FP32 tensors, so its decoder must remain FP32.
+        if device.type != "cpu" and isinstance(codec, MossAudioTokenizerV2Model):
             codec.decoder.to(dtype=torch.bfloat16)
         attention_backend = getattr(self.vllm_config.model_config.hf_config, "codec_attention_backend", "sdpa")
         if attention_backend != "sdpa":

From 4b0c187a1e1658c14b93121cae2a6bfda7c563d2 Mon Sep 17 00:00:00 2001
From: Yukim1 <121286183+zwhzzz0821@users.noreply.github.com>
Date: Fri, 18 Sep 2026 21:09:18 +0800
Subject: [PATCH 088/105] [Bugfix][Core] Fix CLI parallel flags losing to
 nested deploy parallel_config (#7786)

Signed-off-by: zwhzzz0821 <2831474076@qq.com>
---
 tests/config/test_omni_config.py | 24 ++++++++++++++++++++++++
 vllm_omni/config/omni_config.py  |  6 ++++++
 2 files changed, 30 insertions(+)

diff --git a/tests/config/test_omni_config.py b/tests/config/test_omni_config.py
index 97f9a53704f..c0ac38924db 100644
--- a/tests/config/test_omni_config.py
+++ b/tests/config/test_omni_config.py
@@ -255,6 +255,30 @@ def test_from_pipeline_config_applies_cli_overrides_without_stage_config_runtime
     assert stage1.runtime_config.num_gpus == stage1.parallel_config.world_size
 
 
+def test_diffusion_cli_parallel_overrides_beat_nested_deploy_parallel_config():
+    """Flat CLI parallel flags override the deploy YAML's nested parallel_config.
+
+    Regression for the NPU nightly failure (#7778): hunyuan_image3_dit.yaml's
+    platform section sets nested parallel_config.tensor_parallel_size=4 while
+    the perf tests pass --tensor-parallel-size 2. The flat CLI value must win,
+    mirroring StageConfig.to_omegaconf, or the stage demands more devices than
+    the machine has (tp=4 x usp=2 = 8 on a 4-card box).
+    """
+    omni_config = VllmOmniConfig.from_pipeline_config(
+        _resolve_pipeline_or_skip("hunyuan_image3_dit"),
+        user_deploy_config=DeployConfig(
+            stages=[StageDeployConfig(stage_id=0, engine_extras={"parallel_config": {"tensor_parallel_size": 4}})]
+        ),
+        cli_overrides={"tensor_parallel_size": 2, "ulysses_degree": 2},
+    )
+
+    stage = omni_config.stage_by_id(0)
+
+    assert stage.parallel_config.tensor_parallel_size == 2
+    assert stage.parallel_config.ulysses_degree == 2
+    assert stage.parallel_config.world_size == 4
+
+
 @pytest.mark.parametrize(
     "cli_overrides",
     [
diff --git a/vllm_omni/config/omni_config.py b/vllm_omni/config/omni_config.py
index 1407615ab21..f1e5de26a6e 100644
--- a/vllm_omni/config/omni_config.py
+++ b/vllm_omni/config/omni_config.py
@@ -43,6 +43,7 @@
     StageExecutionType,
     StagePipelineConfig,
     StageType,
+    _apply_diffusion_parallel_runtime_overrides,
     _apply_platform_overrides,
     _get_recursively_merged_dict,
     _resolve_scheduler,
@@ -1328,8 +1329,13 @@ def _stage_engine_values(
     if topology.omni_kv_config:
         engine["omni_kv_config"] = _copy_value(topology.omni_kv_config)
     if stage_cli_overrides:
+        stage_cli_overrides = dict(stage_cli_overrides)
         if topology.execution_type == StageExecutionType.DIFFUSION:
             # Mirror StageConfig.to_omegaconf so both projections resolve alike.
+            # CLI parallel fields move into the nested ``parallel_config`` dict,
+            # otherwise the deploy YAML's nested values would win over flat CLI
+            # flags when ``_build_parallel_config`` merges nested over flat.
+            _apply_diffusion_parallel_runtime_overrides(engine, stage_cli_overrides)
             reconcile_diffusion_attention_overrides(engine, stage_cli_overrides)
         for key, value in stage_cli_overrides.items():
             existing = engine.get(key)

From 0a5ece4ae5559fc40e1b6fe38f695b7e0dbe4466 Mon Sep 17 00:00:00 2001
From: wangyu <53896905+yenuo26@users.noreply.github.com>
Date: Fri, 18 Sep 2026 21:24:00 +0800
Subject: [PATCH 089/105] [CI/Build] Retarget skipped HiDream and MammothModa2
 E2E tests to current issues (#7755)

Signed-off-by: wangyu <410167048@qq.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 tests/e2e/offline_inference/test_mammoth_moda2_expansion.py | 2 +-
 tests/e2e/online_serving/test_hidream_i1_full_expansion.py  | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/e2e/offline_inference/test_mammoth_moda2_expansion.py b/tests/e2e/offline_inference/test_mammoth_moda2_expansion.py
index 4f21dd1c485..faedd0e0937 100644
--- a/tests/e2e/offline_inference/test_mammoth_moda2_expansion.py
+++ b/tests/e2e/offline_inference/test_mammoth_moda2_expansion.py
@@ -108,7 +108,7 @@ def _sample_pixels(img_tensor: torch.Tensor) -> list[float]:
 ]
 
 
-@pytest.mark.skip(reason="https://github.com/vllm-project/vllm-omni/issues/3201")
+@pytest.mark.skip(reason="https://github.com/vllm-project/vllm-omni/issues/7718")
 @hardware_test(res={"cuda": "H100"})
 def test_mammothmoda2_t2i_e2e(omni_runner: OmniRunner):
     """
diff --git a/tests/e2e/online_serving/test_hidream_i1_full_expansion.py b/tests/e2e/online_serving/test_hidream_i1_full_expansion.py
index dea3b3c9a34..f9b9ab131ec 100644
--- a/tests/e2e/online_serving/test_hidream_i1_full_expansion.py
+++ b/tests/e2e/online_serving/test_hidream_i1_full_expansion.py
@@ -49,7 +49,7 @@ def _get_hidream_i1_image_feature_cases(model: str):
     _get_hidream_i1_image_feature_cases(MODEL),
     indirect=True,
 )
-@pytest.mark.skip(reason="https://github.com/vllm-project/vllm-omni/issues/4662")
+@pytest.mark.skip(reason="https://github.com/vllm-project/vllm-omni/issues/7753")
 def test_hidream_i1_image(
     omni_server: OmniServer,
     online_client: OnlineOmniClient,

From d4ffde1a6ef1559426616b9aed4d0c53530d81fa Mon Sep 17 00:00:00 2001
From: Yueqian Lin <70319226+linyueqian@users.noreply.github.com>
Date: Fri, 18 Sep 2026 07:55:58 -0700
Subject: [PATCH 090/105] [CI][Qwen3-Omni] Compare structured-config sampling
 defaults against vLLM normalization (#7742)

Signed-off-by: Yueqian Lin <linyueqian@outlook.com>
---
 .../e2e/offline_inference/test_qwen3_omni.py  | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/tests/e2e/offline_inference/test_qwen3_omni.py b/tests/e2e/offline_inference/test_qwen3_omni.py
index b33d693efec..de64c9045b5 100644
--- a/tests/e2e/offline_inference/test_qwen3_omni.py
+++ b/tests/e2e/offline_inference/test_qwen3_omni.py
@@ -13,6 +13,7 @@
 os.environ["VLLM_WORKER_MULTIPROC_METHOD"] = "spawn"
 
 import pytest
+from vllm import SamplingParams
 
 from tests.helpers.mark import hardware_test
 from tests.helpers.media import generate_synthetic_video
@@ -126,11 +127,19 @@ def test_structured_multistage_config_reaches_runtime(omni_runner, offline_clien
         },
     )
     assert len(engine.default_sampling_params_list) == len(expected_sampling)
-    for runtime_params, expected in zip(engine.default_sampling_params_list, expected_sampling, strict=True):
-        # SamplingParams normalization may add backend defaults (for example
-        # ``detokenize=True``). Verify deploy-owned values without rejecting
-        # those non-lossy normalized fields.
-        assert all(getattr(runtime_params, name) == value for name, value in expected.items())
+    for stage, runtime_params, expected in zip(
+        resolved_stages, engine.default_sampling_params_list, expected_sampling, strict=True
+    ):
+        # The resolver keeps the deploy values verbatim; the pipeline only adds
+        # its own ``detokenize`` / ``stop_token_ids`` constraints on top.
+        assert expected.items() <= (stage.model_config.default_sampling_params or {}).items()
+        # The runtime object is a SamplingParams built from those values, so it
+        # carries vLLM's normalization: greedy sampling (temperature 0) stores
+        # top_k=0, top_p=1.0 and min_p=0.0 even when the YAML spells the
+        # disabled top_k as -1, and backend defaults such as ``detokenize=True``
+        # appear. Compare against the same normalization, not the raw literals.
+        normalized = SamplingParams(**expected)
+        assert all(getattr(runtime_params, name) == getattr(normalized, name) for name in expected)
 
     if current_omni_platform.is_cuda():
         assert thinker_vllm.model_config.enforce_eager is False

From 0570f7a06ebcac9d880f18d106e8ceb7c1e94567 Mon Sep 17 00:00:00 2001
From: Yueqian Lin <70319226+linyueqian@users.noreply.github.com>
Date: Fri, 18 Sep 2026 11:25:01 -0700
Subject: [PATCH 091/105] [CI][Qwen3-Omni] Keep the deploy-YAML literal in the
 structured-config sampling check (#7803)

Signed-off-by: Yueqian Lin <linyueqian@outlook.com>
---
 tests/e2e/offline_inference/test_qwen3_omni.py | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/tests/e2e/offline_inference/test_qwen3_omni.py b/tests/e2e/offline_inference/test_qwen3_omni.py
index de64c9045b5..4b744df154a 100644
--- a/tests/e2e/offline_inference/test_qwen3_omni.py
+++ b/tests/e2e/offline_inference/test_qwen3_omni.py
@@ -112,16 +112,18 @@ def test_structured_multistage_config_reaches_runtime(omni_runner, offline_clien
     assert code2wav_vllm.scheduler_config.async_scheduling is False
 
     # Sampling defaults are consumed from StageClient metadata, rather than
-    # from either the resolver output or VllmConfig.
+    # from either the resolver output or VllmConfig. These literals mirror
+    # vllm_omni/deploy/qwen3_omni_moe.yaml exactly.
     expected_sampling = (
         {"temperature": 0.0, "max_tokens": 2048},
         {"temperature": 0.9, "top_k": 50, "max_tokens": 4096, "repetition_penalty": 1.05},
         {
             "temperature": 0.0,
             "top_p": 1.0,
-            # SamplingParams normalizes the disabled greedy-sampling sentinel
-            # from the deploy YAML (top_k=-1) to its runtime value (top_k=0).
-            "top_k": 0,
+            # Deploy YAML literal. The resolver check below compares it verbatim;
+            # the runtime check normalizes it through SamplingParams, which turns
+            # the greedy-sampling sentinel -1 into 0.
+            "top_k": -1,
             "max_tokens": 65536,
             "repetition_penalty": 1.1,
         },

From fbb4e63f0abc7076b0c3d92110d2b376adbb313c Mon Sep 17 00:00:00 2001
From: bcsdhjew <nliang@nvidia.com>
Date: Sat, 19 Sep 2026 02:59:09 +0800
Subject: [PATCH 092/105] [Bugfix][Core] Apply Realtime item truncation once
 per command (#7800)

Signed-off-by: Nolen Liang <nliang@nvidia.com>
---
 docs/serving/realtime_duplex_api.md        |  4 ++++
 tests/engine/duplex/test_duplex_events.py  | 27 ++++++++++++++++++++++
 vllm_omni/engine/duplex/realtime_events.py |  1 -
 3 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/serving/realtime_duplex_api.md b/docs/serving/realtime_duplex_api.md
index a20750090cb..029f35f5836 100644
--- a/docs/serving/realtime_duplex_api.md
+++ b/docs/serving/realtime_duplex_api.md
@@ -948,6 +948,10 @@ deferred commit during an active response (`event.response_create_deferred`)
 {"type": "conversation.item.truncated", "item_id": "item_resp_01", "content_index": 0, "audio_end_ms": 1850, "event": {"…": "…"}}
 ```
 
+After this acknowledgement, `conversation.item.retrieve` returns the truncated
+transcript. Without text/audio alignment marks, its prefix is estimated from
+the requested position and audio duration; this is not exact word alignment.
+
 #### Response lifecycle
 
 `C→S response.create`
diff --git a/tests/engine/duplex/test_duplex_events.py b/tests/engine/duplex/test_duplex_events.py
index a4ebfbf5a3d..11c82286983 100644
--- a/tests/engine/duplex/test_duplex_events.py
+++ b/tests/engine/duplex/test_duplex_events.py
@@ -11,6 +11,7 @@
 import pytest
 
 from vllm_omni.engine.duplex import events as events_module
+from vllm_omni.engine.duplex.commands import TruncateItem
 from vllm_omni.engine.duplex.events import (
     REALTIME_ERROR_TYPES_BY_CODE,
     AudioDelta,
@@ -40,6 +41,8 @@
 from vllm_omni.engine.duplex.realtime_events import (
     RealtimeProjectionState,
     project_internal_event,
+    resolve_truncate_item,
+    retrieve_item_events,
 )
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
@@ -373,6 +376,30 @@ def test_projection_of_output_audio_buffer_clear_emits_cleared_before_terminals(
     assert state.item_truncation_cursors["item_resp_1"] == (0, 250)
 
 
+def test_one_truncate_command_truncates_retrieved_transcript_once():
+    state = RealtimeProjectionState(session_id="duplex-truncate")
+    state.conversation_items["item_resp_1"] = {
+        "id": "item_resp_1",
+        "type": "message",
+        "role": "assistant",
+        "status": "completed",
+        "content": [{"type": "output_audio", "transcript": "abcdefghij", "audio_duration_ms": 10_000}],
+    }
+
+    control = resolve_truncate_item(state, TruncateItem(item_id="item_resp_1", audio_end_ms=4_000))
+    # The runner executes this signal and projects its acknowledgement.
+    signal = control.payloads[0]
+    payload = signal["payload"]
+    assert isinstance(payload, dict)
+    assert signal["event"] == "conversation.item.truncate"
+    project_internal_event(state, {"type": "conversation.item.truncated", **payload})
+
+    retrieved = retrieve_item_events(state, {"item_id": "item_resp_1"})[0].to_realtime()
+    assert retrieved["item"]["content"][0]["transcript"] == "abcd"
+    # Keep the cursor: later output must not restore the untruncated item.
+    assert state.item_truncation_cursors["item_resp_1"] == (0, 4_000)
+
+
 def test_projection_leaves_error_to_typed_emit_sites():
     # Errors are constructed typed (``error_event``) at the emit site; the projector
     # has no ``error`` branch and falls back to the raw wrapper for such a dict.
diff --git a/vllm_omni/engine/duplex/realtime_events.py b/vllm_omni/engine/duplex/realtime_events.py
index a6a619ac807..503b557ac80 100644
--- a/vllm_omni/engine/duplex/realtime_events.py
+++ b/vllm_omni/engine/duplex/realtime_events.py
@@ -1362,7 +1362,6 @@ def resolve_truncate_item(state: RealtimeProjectionState, command: TruncateItem)
             payloads=[], events=[error_event("bad_event", truncate_error, event_id=command.event_id)]
         )
     state.item_truncation_cursors[command.item_id] = (command.content_index, command.audio_end_ms)
-    truncate_realtime_item_content(item, content_index=command.content_index, audio_end_ms=command.audio_end_ms)
     ack_payload: dict[str, object] = {
         "type": "playback.ack",
         "item_id": command.item_id,

From ca3ccfc9a3054e65e4267bb3e3cc95db48a98f09 Mon Sep 17 00:00:00 2001
From: Joshna-Medisetty <joshna.medisetty@intel.com>
Date: Fri, 18 Sep 2026 12:41:41 -0700
Subject: [PATCH 093/105] [XPU][Bugfix] Make AR-Diffusion KV preallocation
 device-agnostic (#7777)

Signed-off-by: Joshna Medisetty <joshna.medisetty@intel.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../diffusion/models/dreamzero/pipeline_dreamzero.py      | 8 ++++----
 vllm_omni/experimental/ar_diffusion/runner.py             | 6 +++---
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/vllm_omni/diffusion/models/dreamzero/pipeline_dreamzero.py b/vllm_omni/diffusion/models/dreamzero/pipeline_dreamzero.py
index 939544a9f01..3ebda6b6eb7 100644
--- a/vllm_omni/diffusion/models/dreamzero/pipeline_dreamzero.py
+++ b/vllm_omni/diffusion/models/dreamzero/pipeline_dreamzero.py
@@ -720,7 +720,7 @@ def setup_compile(self) -> None:
 
     def warmup_compile(self) -> None:
         """Warm up compiled text/image/VAE paths before timed inference."""
-        if not torch.cuda.is_available():
+        if not torch.accelerator.is_available():
             return
 
         state = self.state
@@ -801,12 +801,12 @@ def _synchronize_cfg_parallel_step_output(
         latents: tuple[torch.Tensor, torch.Tensor],
         do_true_cfg: bool,
     ) -> tuple[torch.Tensor, torch.Tensor]:
-        """Post-step sync: .contiguous() + cuda.synchronize()"""
+        """Post-step sync: .contiguous() + accelerator stream synchronize"""
         latents = tuple(t.contiguous() for t in latents)
         if do_true_cfg and get_classifier_free_guidance_world_size() > 1:
-            device = next((t.device for t in latents if t.is_cuda), None)
+            device = next((t.device for t in latents if t.device.type != "cpu"), None)
             if device is not None:
-                torch.cuda.current_stream(device).synchronize()
+                torch.accelerator.current_stream(device).synchronize()
         return latents
 
     # -----------------------------------------------------------------------
diff --git a/vllm_omni/experimental/ar_diffusion/runner.py b/vllm_omni/experimental/ar_diffusion/runner.py
index 23da43054c0..740587f3830 100644
--- a/vllm_omni/experimental/ar_diffusion/runner.py
+++ b/vllm_omni/experimental/ar_diffusion/runner.py
@@ -93,9 +93,9 @@ def load_model(self, *args: object, **kwargs: object) -> None:
             self._warmup_ar_rollout()
 
     def _available_memory_bytes(self) -> int:
-        if self.device is None or torch.device(self.device).type != "cuda":
-            raise RuntimeError("AR-Diffusion KV preallocation currently requires a CUDA device")
-        return int(torch.cuda.mem_get_info(self.device)[0])
+        if self.device is None:
+            raise RuntimeError("AR-Diffusion KV preallocation requires an initialized device")
+        return current_omni_platform.get_free_memory(torch.device(self.device))
 
     def _preallocate_kv_cache(self, *, available_bytes: int | None = None) -> None:
         """Build pools solely from the pipeline capability and runner config."""

From 7b4fc7ce2e533b29193b3d10a7348b6ac5380fae Mon Sep 17 00:00:00 2001
From: Sun <2114377220@qq.com>
Date: Sat, 19 Sep 2026 04:29:18 +0800
Subject: [PATCH 094/105] [Model] Migrate MammothModa2 DiT to the shared
 diffusion runtime (#7134)

Signed-off-by: levius <2114377220@qq.com>
Signed-off-by: Yueqian Lin <linyueqian@outlook.com>
Co-authored-by: amy-why-3459 <wuhaiyan17@huawei.com>
Co-authored-by: Yueqian Lin <linyueqian@outlook.com>
---
 recipes/MammothModa2/MammothModa2.md          | 107 +++--
 tests/config/test_endpoint_policy.py          |  28 +-
 .../test_mammoth_moda2_shared_runtime.py      |  60 +++
 tests/config/test_omni_config.py              |  14 +
 .../test_pipeline_mammothmoda2_dit.py         | 392 ++++++++++++++++++
 .../test_mammoth_moda2_expansion.py           | 113 ++---
 .../test_mammoth_moda2.py                     | 212 +++++-----
 tests/model_tests/diffusion/test_alignment.py |   3 +
 tests/worker/test_omni_connector_mixin.py     |   2 +-
 vllm_omni/config/endpoint_policy.py           |   1 +
 vllm_omni/deploy/mammoth_moda2.yaml           |   5 -
 .../pipeline_mammothmoda2_dit.py              | 365 +++++++++-------
 vllm_omni/diffusion/registry.py               |   6 +
 .../models/mammoth_moda2/pipeline.py          |  17 +-
 vllm_omni/model_executor/models/registry.py   |   5 -
 .../stage_input_processors/mammoth_moda2.py   | 147 +++----
 16 files changed, 1048 insertions(+), 429 deletions(-)
 create mode 100644 tests/config/test_mammoth_moda2_shared_runtime.py
 create mode 100644 tests/diffusion/models/mammoth_moda2/test_pipeline_mammothmoda2_dit.py

diff --git a/recipes/MammothModa2/MammothModa2.md b/recipes/MammothModa2/MammothModa2.md
index 02f8e30bfd2..26ec9ed1fd1 100644
--- a/recipes/MammothModa2/MammothModa2.md
+++ b/recipes/MammothModa2/MammothModa2.md
@@ -18,11 +18,18 @@ The generic example formats the AR prompt, drives the AR → DiT stage pipeline,
 and forwards MammothModa2-specific generation parameters through the
 pipeline-declared `extra_body` contract.
 
-MammothModa2's DiT stage consumes its inputs through the multi-stage kwargs
-interface (not `OmniDiffusionRequest`), so its generation knobs
-(`text_guidance_scale`, `cfg_range`, `num_inference_steps`) are passed via
-`--extra-body` rather than the standard `--num-inference-steps` / `--cfg-scale`
-flags. Image size uses the standard `--height` / `--width` flags.
+MammothModa2's DiT stage runs in the shared diffusion runtime in request mode.
+The first integration intentionally supports one request and one image per
+forward only (`max_num_seqs: 1`, `num_outputs_per_prompt: 1`). Request-level
+batching, step execution, continuous batching, cache acceleration,
+compilation, quantization, parallelism, and offload are not enabled by this
+recipe.
+
+Image size, seed, guidance, and denoising steps use the standard diffusion
+request fields. `cfg_range` remains a MammothModa2-specific `extra_body`
+parameter. For compatibility, the runtime also accepts the former
+`text_guidance_scale` and `num_inference_steps` keys in `extra_body`; when
+present and non-null, those keys take precedence over the standard fields.
 
 ## References
 
@@ -41,11 +48,11 @@ flags. Image size uses the standard `--height` / `--width` flags.
 
 ## Hardware Support
 
-The default deploy config runs both the AR and DiT stages on a single GPU
-(`devices: "0"`). The committed `gpu_memory_utilization` split (stage-0 AR `0.5`,
-stage-1 DiT `0.3`) is sized for an ~80 GB GPU. The model also fits on a 48 GB GPU
-after rebalancing the split so the AR weights (~23 GB) leave room for the KV
-cache — see the note under *1x L40S 48GB*.
+The default deploy config places both the AR and DiT stages on one GPU
+(`devices: "0"`). Its committed `gpu_memory_utilization` split is 0.5 for
+stage 0 and 0.3 for stage 1. The A800 validation section below also shows a
+two-GPU placement with one stage per GPU for attributable timing and memory;
+the measured results are summarized below.
 
 ## GPU
 
@@ -102,12 +109,13 @@ not implied.
 > set the stage-0 (AR) value to `0.8` and the stage-1 (DiT) value to `0.16`
 > before running. (On an ~80 GB GPU, leave the defaults unchanged.)
 
+### 1x NVIDIA A800 80GB
+
 #### Environment
 
 - OS: Linux
 - Python: Match the repository requirements for your checkout
-- Driver / runtime: NVIDIA CUDA environment with one L40S 48 GB (verified) or an
-  ~80 GB GPU for the default config
+- Driver / runtime: NVIDIA CUDA environment with one A800 80 GB
 - vLLM version: Match the repository requirements for your checkout
 - vLLM-Omni version or commit: Use the commit you are deploying from
 
@@ -120,8 +128,7 @@ hf download bytedance-research/MammothModa2-Preview --local-dir ./MammothModa2-P
 ```
 
 Run text-to-image with the shared offline example from the repository root. The
-deploy config sets `trust_remote_code`, so no extra flag is needed. Forward the
-MammothModa2 generation parameters as a JSON object through `--extra-body`:
+deploy config sets `trust_remote_code`, so no extra flag is needed:
 
 ```bash
 python examples/offline_inference/text_to_image/text_to_image.py \
@@ -130,23 +137,25 @@ python examples/offline_inference/text_to_image/text_to_image.py \
   --prompt "A stylish woman riding a motorcycle in NYC, movie poster style" \
   --height 1024 \
   --width 1024 \
-  --extra-body '{"text_guidance_scale": 4.0, "cfg_range": [0.0, 1.0], "num_inference_steps": 50}' \
+  --seed 42 \
+  --guidance-scale 4.0 \
+  --num-inference-steps 50 \
+  --extra-body '{"cfg_range": [0.0, 1.0]}' \
   --output mammoth_t2i.png
 ```
 
-The `--extra-body` JSON forwards MammothModa2-specific parameters into
-`OmniDiffusionSamplingParams.extra_args`. Keys are filtered against the model's
-declared `extra_body_params` (see
-[`vllm_omni/model_extras/mammothmodal2_preview.py`](../../vllm_omni/model_extras/mammothmodal2_preview.py)),
-so unknown keys for MammothModa2 are silently dropped:
-
-- `text_guidance_scale` — classifier-free guidance scale for the DiT stage
-  (default `9.0`; CFG is active only when `> 1.0`).
-- `cfg_range` — relative step range `[start, end]` over which CFG is applied
-  (default `[0.0, 1.0]`).
-- `num_inference_steps` — number of DiT denoising steps (default `50`).
+The standard diffusion request fields are `height`, `width`, `seed`,
+`guidance_scale`, and `num_inference_steps`; use their corresponding CLI flags
+shown above. `--height` and `--width` must be multiples of 16.
 
-`--height` and `--width` must be multiples of 16.
+`cfg_range` is the only recommended MammothModa2 field in `--extra-body`; it
+sets the relative step range `[start, end]` over which CFG is applied (default
+`[0.0, 1.0]`). For compatibility, `text_guidance_scale` and
+`num_inference_steps` remain accepted `extra_body` aliases and, when non-null,
+take precedence over the standard request fields. Model extras are filtered
+against the declared `extra_body_params` (see
+[`vllm_omni/model_extras/mammothmodal2_preview.py`](../../vllm_omni/model_extras/mammothmodal2_preview.py)),
+so unknown MammothModa2 extras may be dropped.
 
 Run text-to-text through the shared understanding example. It recognizes the
 MammothModa2 checkpoint and automatically selects `mammoth_moda2_ar.yaml`:
@@ -177,7 +186,49 @@ ls -lh mammoth_t2i.png
 python -c "from PIL import Image; print(Image.open('mammoth_t2i.png').size)"
 ```
 
-### 1x AMD MI300X, MammothModa2 Preview
+### 2x NVIDIA A800 80GB validation
+
+Use one A800 per stage so AR and DiT memory and timing are attributable. The
+per-stage override changes placement only; both stages remain single-rank.
+
+```bash
+VLLM_LOGGING_LEVEL=DEBUG vllm serve ./MammothModa2-Preview --omni \
+  --deploy-config vllm_omni/deploy/mammoth_moda2.yaml \
+  --stage-overrides '{"0":{"devices":"0"},"1":{"devices":"1"}}' \
+  --port 8099 \
+  --log-stats
+```
+
+Startup logs should identify stage 1 as `StageDiffusionClient` and resolve it
+to `MammothModa2DiTPipeline`. `DiffusionEngine` step timing is a DEBUG-level,
+per-request message, so it appears only after sending a text-to-image request
+with `VLLM_LOGGING_LEVEL=DEBUG`; it is not a startup marker. Seeing the legacy
+generation model runner for stage 1 is a failed migration.
+
+#### Migration benchmark
+
+The request-mode migration was checked on 2x NVIDIA A800 80GB PCIe with AR on
+GPU 0 and DiT on GPU 1. Each revision ran one warmup followed by 10 serial
+measured requests in the same initialized process. Both used BF16 eager mode,
+1024x1024 output, 50 denoising steps, guidance scale 4.0, seed 42, and no
+diffusion cache. The baseline was the pre-migration revision `caed3061`; the
+candidate was `19de562a`. Lower latency is better.
+
+| Metric | Baseline p50 | Baseline p95 | Candidate p50 | Candidate p95 |
+| --- | ---: | ---: | ---: | ---: |
+| End-to-end latency | 105.36 s | 106.01 s | 104.94 s | 105.79 s |
+| AR stage latency | 86.97 s | 87.61 s | 86.26 s | 87.11 s |
+| DiT stage latency | 18.27 s | 18.41 s | 18.60 s | 18.62 s |
+
+Peak sampled device memory was 39,209 MiB on the AR GPU for both revisions.
+The DiT GPU used 11,089 MiB for the baseline and 10,967 MiB for the candidate.
+The candidate's shared runtime reported 372.02 ms p50 per denoising step and a
+5.89 ms p50 AR-to-diffusion adapter time. All measured requests completed and
+both revisions produced valid, prompt-aligned 1024x1024 RGB images. The small
+latency differences are regression evidence, not a statistically significant
+speedup claim.
+
+### 1x AMD MI300X, MammothModa2 Preview (pre-migration baseline)
 
 #### Environment
 
diff --git a/tests/config/test_endpoint_policy.py b/tests/config/test_endpoint_policy.py
index aeb1ffa5133..fa42b80c74d 100644
--- a/tests/config/test_endpoint_policy.py
+++ b/tests/config/test_endpoint_policy.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Tests for endpoint restrictions logic."""
 
 import pytest
@@ -44,6 +44,32 @@ def test_restricted_completions_returns_400():
     assert body["error"]["type"] == "BadRequestError"
 
 
+def test_restricted_image_edits_returns_400():
+    """Ensure pipelines can reject image edits independently of generation."""
+    app = FastAPI()
+
+    @app.post("/v1/images/edits")
+    async def existing_handler():
+        return {"ok": True}
+
+    @app.post("/v1/images/generations")
+    async def generations_handler():
+        return {"ok": True}
+
+    restrictions = (EndpointRestriction(OmniServingCapability.IMAGE_EDITS, REJECTION_REASON),)
+    shutdown_unsupported_routes(app, restrictions)
+
+    client = TestClient(app)
+    resp = client.post("/v1/images/edits")
+    assert resp.status_code == 400
+    assert resp.json()["error"]["message"] == REJECTION_REASON
+
+    # The restriction is endpoint-specific and must not remove generations.
+    resp = client.post("/v1/images/generations")
+    assert resp.status_code == 200
+    assert resp.json() == {"ok": True}
+
+
 def test_unrestricted_completions_not_blocked():
     """Ensure that if we don't shutdown any routes, the route stays."""
     app = _make_app_with_server_route()
diff --git a/tests/config/test_mammoth_moda2_shared_runtime.py b/tests/config/test_mammoth_moda2_shared_runtime.py
new file mode 100644
index 00000000000..f5c11b2a5e2
--- /dev/null
+++ b/tests/config/test_mammoth_moda2_shared_runtime.py
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import pytest
+
+from tests.helpers.stage_config import get_deploy_config_path
+from vllm_omni.config.endpoint_policy import OmniServingCapability
+from vllm_omni.config.stage_config import StageExecutionType, load_deploy_config
+from vllm_omni.diffusion.registry import _DIFFUSION_MODELS
+from vllm_omni.model_executor.models.mammoth_moda2.pipeline import (
+    MAMMOTH_MODA2_AR_PIPELINE,
+    MAMMOTH_MODA2_PIPELINE,
+)
+from vllm_omni.model_executor.models.registry import _OMNI_MODELS
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def test_mammothmoda2_generation_stage_uses_shared_diffusion_runtime() -> None:
+    ar_stage, dit_stage = MAMMOTH_MODA2_PIPELINE.stages
+    assert ar_stage.execution_type is StageExecutionType.LLM_AR
+    assert dit_stage.execution_type is StageExecutionType.DIFFUSION
+    assert dit_stage.model_arch == "MammothModa2DiTPipeline"
+    assert dit_stage.custom_process_input_func.endswith(".ar2diffusion")
+    assert dit_stage.omni_kv_config == {"need_recv_cache": False}
+    assert dit_stage.input_sources == (0,)
+    assert dit_stage.final_output is True
+    assert dit_stage.final_output_type == "image"
+
+
+def test_mammothmoda2_dit_is_registered_only_with_diffusion_runtime() -> None:
+    assert _DIFFUSION_MODELS["MammothModa2DiTPipeline"] == (
+        "mammoth_moda2",
+        "pipeline_mammothmoda2_dit",
+        "MammothModa2DiTPipeline",
+    )
+    assert "MammothModa2DiTPipeline" not in _OMNI_MODELS
+
+
+def test_mammothmoda2_deploy_does_not_shadow_request_sampling_fields() -> None:
+    deploy = load_deploy_config(get_deploy_config_path("mammoth_moda2.yaml"))
+
+    assert deploy.stages[1].default_sampling_params is None
+
+
+def test_mammothmoda2_rejects_unsupported_image_edits() -> None:
+    restrictions = {
+        restriction.capability: restriction.reason for restriction in MAMMOTH_MODA2_PIPELINE.endpoint_restrictions
+    }
+
+    assert set(restrictions) == {OmniServingCapability.IMAGE_EDITS}
+    assert "img2img" in restrictions[OmniServingCapability.IMAGE_EDITS]
+    assert MAMMOTH_MODA2_AR_PIPELINE.endpoint_restrictions == ()
+
+
+def test_mammothmoda2_ar_only_topology_is_unchanged() -> None:
+    assert len(MAMMOTH_MODA2_AR_PIPELINE.stages) == 1
+    stage = MAMMOTH_MODA2_AR_PIPELINE.stages[0]
+    assert stage.execution_type is StageExecutionType.LLM_AR
+    assert stage.final_output_type == "text"
diff --git a/tests/config/test_omni_config.py b/tests/config/test_omni_config.py
index c0ac38924db..3d356ad9111 100644
--- a/tests/config/test_omni_config.py
+++ b/tests/config/test_omni_config.py
@@ -95,6 +95,20 @@ def _from_pipeline_key(
     )
 
 
+def test_mammothmoda2_diffusion_stage_projects_native_backend_config() -> None:
+    config = _from_pipeline_key(
+        "mammoth_moda2",
+        cli_overrides={"model": "/models/MammothModa2-Preview"},
+    )
+    stage = config.stage_by_id(1)
+    assert isinstance(stage, VllmOmniDiffusionStageConfig)
+    assert stage.diffusion_config.model_class_name == "MammothModa2DiTPipeline"
+    assert stage.diffusion_config.model == "/models/MammothModa2-Preview"
+    assert stage.diffusion_config.step_execution is False
+    assert stage.scheduler_config.max_num_seqs == 1
+    assert stage.connector_config.omni_kv_config == {"need_recv_cache": False}
+
+
 def test_minimax_h3_text_encoder_tp_targets_only_structured_stage_zero() -> None:
     config = _from_pipeline_key(
         "minimax_h3_disaggregated",
diff --git a/tests/diffusion/models/mammoth_moda2/test_pipeline_mammothmoda2_dit.py b/tests/diffusion/models/mammoth_moda2/test_pipeline_mammothmoda2_dit.py
new file mode 100644
index 00000000000..776ca5bc6de
--- /dev/null
+++ b/tests/diffusion/models/mammoth_moda2/test_pipeline_mammothmoda2_dit.py
@@ -0,0 +1,392 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from dataclasses import dataclass
+
+import pytest
+import torch
+from torch import nn
+
+from vllm_omni.diffusion.data import DiffusionOutput, OmniDiffusionConfig, TransformerConfig
+from vllm_omni.diffusion.models.mammoth_moda2 import pipeline_mammothmoda2_dit
+from vllm_omni.diffusion.models.mammoth_moda2.pipeline_mammothmoda2_dit import (
+    MammothModa2DiTPipeline,
+    _build_mammoth_config,
+    _root_weight_source,
+)
+from vllm_omni.diffusion.request import OmniDiffusionRequest
+from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch
+from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+def _raw_config() -> dict:
+    return {
+        "model_type": "mammothmoda2",
+        "llm_config": {
+            "model_type": "mammothmoda2_qwen2_5_vl",
+            "text_config": {
+                "model_type": "mammothmoda2_qwen2_5_vl_text",
+                "hidden_size": 8,
+                "gen_vocab_start_index": 100,
+            },
+        },
+        "gen_vae_config": {"block_out_channels": [8, 8]},
+        "gen_dit_config": {"hidden_size": 8, "in_channels": 4},
+    }
+
+
+def _od_config() -> OmniDiffusionConfig:
+    return OmniDiffusionConfig(
+        model="/models/MammothModa2-Preview",
+        model_class_name="MammothModa2DiTPipeline",
+        tf_model_config=TransformerConfig.from_dict(_raw_config()),
+    )
+
+
+def test_build_mammoth_config_uses_shared_transformer_projection() -> None:
+    config = _build_mammoth_config(_od_config())
+    assert config.model_type == "mammothmoda2"
+    assert config.get_text_config().hidden_size == 8
+    assert config.gen_dit_config == {"hidden_size": 8, "in_channels": 4}
+
+
+def test_build_mammoth_config_rejects_empty_shared_projection() -> None:
+    config = _od_config()
+    config.tf_model_config = TransformerConfig()
+    with pytest.raises(ValueError, match="root checkpoint config"):
+        _build_mammoth_config(config)
+
+
+def test_root_weight_source_loads_combined_checkpoint_once() -> None:
+    source = _root_weight_source(_od_config())
+    assert source.model_or_path == "/models/MammothModa2-Preview"
+    assert source.subfolder is None
+    assert source.prefix == ""
+    assert source.fall_back_to_pt is True
+
+
+def test_root_weight_source_forwards_revision() -> None:
+    config = _od_config()
+    config.revision = "rev-7"
+    assert _root_weight_source(config).revision == "rev-7"
+
+
+def test_pipeline_declares_native_components_and_single_request_mode_only() -> None:
+    assert MammothModa2DiTPipeline._dit_modules == ["gen_transformer"]
+    assert MammothModa2DiTPipeline._encoder_modules == ["gen_image_condition_refiner"]
+    assert MammothModa2DiTPipeline._vae_modules == ["gen_vae"]
+    assert MammothModa2DiTPipeline.supports_request_batch is False
+    assert MammothModa2DiTPipeline.supports_step_execution is False
+
+
+def test_mammoth_postprocess_denormalizes_nonnegative_raw_vae_output() -> None:
+    factory = getattr(pipeline_mammothmoda2_dit, "get_mammoth_moda2_post_process_func", None)
+    assert factory is not None
+
+    images = factory(_od_config())(torch.zeros(1, 3, 2, 2))
+
+    assert len(images) == 1
+    assert images[0].getpixel((0, 0)) == (128, 128, 128)
+
+
+def test_mammoth_postprocess_is_registered() -> None:
+    from vllm_omni.diffusion.registry import _DIFFUSION_POST_PROCESS_FUNCS
+
+    assert _DIFFUSION_POST_PROCESS_FUNCS["MammothModa2DiTPipeline"] == "get_mammoth_moda2_post_process_func"
+
+
+def test_root_weight_source_rejects_missing_model_path() -> None:
+    config = _od_config()
+    config.model = None
+    with pytest.raises(ValueError, match="model path"):
+        _root_weight_source(config)
+
+
+def _pipeline_shell() -> MammothModa2DiTPipeline:
+    pipeline = object.__new__(MammothModa2DiTPipeline)
+    nn.Module.__init__(pipeline)
+    pipeline.device = torch.device("cpu")
+    pipeline.config = _build_mammoth_config(_od_config())
+    pipeline._llm_hidden_size = 8
+    return pipeline
+
+
+def _batch(
+    *,
+    request_id: str = "req-7",
+    prompt: object | None = None,
+    sampling: OmniDiffusionSamplingParams | None = None,
+) -> DiffusionRequestBatch:
+    if prompt is None:
+        prompt = {
+            "prompt": "",
+            "height": 32,
+            "width": 48,
+            "additional_information": {
+                "full_hidden_states": torch.arange(32, dtype=torch.float32).reshape(4, 8),
+                "full_token_ids": [10, 11, 100, 101],
+                "answer_start_index": 2,
+            },
+        }
+    if sampling is None:
+        sampling = OmniDiffusionSamplingParams(
+            height=32,
+            width=48,
+            seed=42,
+            guidance_scale=4.0,
+            num_inference_steps=7,
+            extra_args={"cfg_range": [0.2, 0.8]},
+        )
+    return DiffusionRequestBatch([OmniDiffusionRequest(prompt=prompt, sampling_params=sampling, request_id=request_id)])
+
+
+def test_parse_request_uses_standard_sampling_fields() -> None:
+    parsed = _pipeline_shell()._parse_request(_batch())
+    assert parsed.request_id == "req-7"
+    assert (parsed.height, parsed.width) == (32, 48)
+    assert parsed.num_inference_steps == 7
+    assert parsed.text_guidance_scale == 4.0
+    assert parsed.cfg_range == (0.2, 0.8)
+    assert parsed.seed == 42
+    assert parsed.answer_start_index == 2
+
+
+def test_parse_request_prefers_legacy_sampling_overrides() -> None:
+    sampling = OmniDiffusionSamplingParams(
+        guidance_scale=3.0,
+        num_inference_steps=5,
+        seed=9,
+        extra_args={"text_guidance_scale": 6.0, "num_inference_steps": 11, "cfg_range": [0.0, 0.5]},
+    )
+    parsed = _pipeline_shell()._parse_request(_batch(sampling=sampling))
+    assert parsed.text_guidance_scale == 6.0
+    assert parsed.num_inference_steps == 11
+    assert parsed.cfg_range == (0.0, 0.5)
+
+
+def test_parse_request_falls_back_to_request_level_sampling_values() -> None:
+    prompt = _batch().prompts[0]
+    prompt["additional_information"].update(
+        text_guidance_scale=[1.5],
+        num_inference_steps=[3],
+        cfg_range=[0.25, 0.75],
+    )
+
+    parsed = _pipeline_shell()._parse_request(_batch(prompt=prompt, sampling=OmniDiffusionSamplingParams()))
+
+    assert parsed.text_guidance_scale == 1.5
+    assert parsed.num_inference_steps == 3
+    assert parsed.cfg_range == (0.25, 0.75)
+
+
+def test_parse_request_standard_fields_precede_request_level_fallbacks() -> None:
+    prompt = _batch().prompts[0]
+    prompt["additional_information"].update(
+        text_guidance_scale=[1.5],
+        num_inference_steps=[3],
+    )
+    sampling = OmniDiffusionSamplingParams(guidance_scale=4.0, num_inference_steps=7)
+
+    parsed = _pipeline_shell()._parse_request(_batch(prompt=prompt, sampling=sampling))
+
+    assert parsed.text_guidance_scale == 4.0
+    assert parsed.num_inference_steps == 7
+
+
+def test_parse_request_rejects_multiple_requests_and_outputs() -> None:
+    pipeline = _pipeline_shell()
+    batch = _batch()
+    batch.requests.append(_batch(request_id="req-8").requests[0])
+    with pytest.raises(ValueError, match="exactly one request"):
+        pipeline._parse_request(batch)
+    with pytest.raises(ValueError, match="num_outputs_per_prompt=1"):
+        pipeline._parse_request(_batch(sampling=OmniDiffusionSamplingParams(num_outputs_per_prompt=2)))
+
+
+@pytest.mark.parametrize(
+    ("cfg_range", "message"),
+    [
+        ([0.5], "two values"),
+        ([-0.1, 0.5], "0 <= start <= end <= 1"),
+        ([0.7, 0.2], "0 <= start <= end <= 1"),
+        ([0.2, 1.1], "0 <= start <= end <= 1"),
+    ],
+)
+def test_parse_request_rejects_invalid_cfg_range(cfg_range, message) -> None:
+    batch = _batch(sampling=OmniDiffusionSamplingParams(extra_args={"cfg_range": cfg_range}))
+    with pytest.raises(ValueError, match=message):
+        _pipeline_shell()._parse_request(batch)
+
+
+def test_parse_request_requires_real_ar_conditions() -> None:
+    with pytest.raises(ValueError, match="req-missing"):
+        _pipeline_shell()._parse_request(_batch(request_id="req-missing", prompt={"prompt": "draw a cat"}))
+
+
+def test_parse_request_rejects_hidden_state_token_count_mismatch() -> None:
+    batch = _batch()
+    batch.prompts[0]["additional_information"]["full_hidden_states"] = torch.zeros(3, 8)
+    with pytest.raises(ValueError, match="hidden-state/token-count mismatch"):
+        _pipeline_shell()._parse_request(batch)
+
+
+@pytest.mark.parametrize(
+    ("height", "width", "message"),
+    [
+        (0, 32, "Invalid image size"),
+        (32, -1, "Invalid image size"),
+        (30, 32, "multiples of 16"),
+        (32, 31, "multiples of 16"),
+    ],
+)
+def test_parse_request_rejects_invalid_dimensions(height, width, message) -> None:
+    batch = _batch()
+    batch.prompts[0].update(height=height, width=width)
+    with pytest.raises(ValueError, match=message):
+        _pipeline_shell()._parse_request(batch)
+
+
+def test_parse_request_rejects_explicit_zero_steps() -> None:
+    with pytest.raises(ValueError, match="num_inference_steps must be positive"):
+        _pipeline_shell()._parse_request(_batch(sampling=OmniDiffusionSamplingParams(num_inference_steps=0)))
+
+
+@pytest.mark.parametrize(("standard_steps", "expected_steps"), [(7, 7), (None, 50)])
+def test_parse_request_falls_through_null_legacy_step_count(standard_steps, expected_steps) -> None:
+    sampling = OmniDiffusionSamplingParams(num_inference_steps=standard_steps, extra_args={"num_inference_steps": None})
+    parsed = _pipeline_shell()._parse_request(_batch(sampling=sampling))
+    assert parsed.num_inference_steps == expected_steps
+
+
+@pytest.mark.parametrize(("standard_guidance", "expected_guidance"), [(4.0, 4.0), (None, 9.0)])
+def test_parse_request_falls_through_null_legacy_guidance(standard_guidance, expected_guidance) -> None:
+    sampling = OmniDiffusionSamplingParams(guidance_scale=standard_guidance, extra_args={"text_guidance_scale": None})
+    parsed = _pipeline_shell()._parse_request(_batch(sampling=sampling))
+    assert parsed.text_guidance_scale == expected_guidance
+
+
+def test_parse_request_defaults_null_cfg_range() -> None:
+    sampling = OmniDiffusionSamplingParams(extra_args={"cfg_range": None})
+    parsed = _pipeline_shell()._parse_request(_batch(sampling=sampling))
+    assert parsed.cfg_range == (0.0, 1.0)
+
+
+@pytest.mark.parametrize("generators", [[], [torch.Generator(), torch.Generator()]])
+def test_parse_request_rejects_invalid_generator_list_cardinality(generators) -> None:
+    sampling = OmniDiffusionSamplingParams(generator=generators)
+    with pytest.raises(ValueError, match="exactly one generator.*req-generators"):
+        _pipeline_shell()._parse_request(_batch(request_id="req-generators", sampling=sampling))
+
+
+def test_parse_request_synthesizes_dummy_ar_conditions() -> None:
+    batch = _batch(
+        request_id="dummy_req_id",
+        prompt={"prompt": "dummy run"},
+        sampling=OmniDiffusionSamplingParams(height=512, width=512, seed=1, guidance_scale=0.0, num_inference_steps=2),
+    )
+    parsed = _pipeline_shell()._parse_request(batch)
+    assert parsed.full_hidden_states.shape == (2, 8)
+    assert parsed.full_token_ids == [0, 100]
+    assert parsed.answer_start_index == 1
+
+
+@dataclass
+class _FakeTransformerConfig:
+    in_channels: int = 4
+
+
+@dataclass
+class _FakeTimeCaptionEmbed:
+    image_embedder: nn.Module | None = None
+
+
+class _FakeTransformer(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+        self.anchor = nn.Parameter(torch.zeros(1))
+        self.config = _FakeTransformerConfig()
+        self.time_caption_embed = _FakeTimeCaptionEmbed()
+        self.calls = 0
+
+    def forward(self, *, hidden_states, **kwargs):
+        self.calls += 1
+        return torch.zeros_like(hidden_states)
+
+
+@dataclass
+class _FakeVaeConfig:
+    scaling_factor: float | None = None
+    shift_factor: float | None = None
+
+
+class _FakeVae(nn.Module):
+    def __init__(self) -> None:
+        super().__init__()
+        self.anchor = nn.Parameter(torch.zeros(1))
+        self.config = _FakeVaeConfig()
+
+    def decode(self, latents, return_dict=False):
+        assert return_dict is False
+        return (torch.zeros(1, 3, 32, 48, dtype=latents.dtype),)
+
+
+class _FakeScheduler:
+    def __init__(self) -> None:
+        self.timesteps = torch.tensor([])
+        self.requested_steps = None
+
+    def set_timesteps(self, *, num_inference_steps, device, num_tokens):
+        self.requested_steps = num_inference_steps
+        self.timesteps = torch.arange(num_inference_steps, device=device, dtype=torch.float32)
+
+    def step(self, model_pred, timestep, latents, return_dict=False):
+        assert return_dict is False
+        return (latents - model_pred,)
+
+
+def test_forward_returns_diffusion_output_with_request_sampling(mocker) -> None:
+    pipeline = _pipeline_shell()
+    pipeline.gen_transformer = _FakeTransformer()
+    pipeline.gen_image_condition_refiner = None
+    pipeline.gen_vae = _FakeVae()
+    pipeline.gen_freqs_cis = torch.zeros(1)
+    scheduler = _FakeScheduler()
+    captured = {}
+
+    def fake_randn_tensor(shape, *, generator, device, dtype):
+        captured["shape"] = shape
+        captured["seed"] = generator.initial_seed()
+        return torch.zeros(shape, device=device, dtype=dtype)
+
+    module = "vllm_omni.diffusion.models.mammoth_moda2.pipeline_mammothmoda2_dit"
+    mocker.patch(f"{module}.FlowMatchEulerDiscreteScheduler", return_value=scheduler)
+    mocker.patch(f"{module}.randn_tensor", side_effect=fake_randn_tensor)
+    result = pipeline.forward(
+        _batch(
+            sampling=OmniDiffusionSamplingParams(
+                height=32, width=48, seed=42, guidance_scale=1.0, num_inference_steps=2
+            )
+        )
+    )
+
+    assert isinstance(result, DiffusionOutput)
+    assert result.output.shape == (1, 3, 32, 48)
+    assert captured["shape"] == (1, 4, 4, 6)
+    assert captured["seed"] == 42
+    assert scheduler.requested_steps == 2
+    assert pipeline.gen_transformer.calls == 2
+
+
+def test_forward_rejects_missing_visual_tokens_before_model_access() -> None:
+    prompt = {
+        "prompt": "",
+        "additional_information": {
+            "full_hidden_states": torch.zeros(3, 8),
+            "full_token_ids": [10, 11, 12],
+            "answer_start_index": 2,
+        },
+    }
+    with pytest.raises(ValueError, match="no visual-token hidden states.*req-empty"):
+        _pipeline_shell().forward(_batch(request_id="req-empty", prompt=prompt))
diff --git a/tests/e2e/offline_inference/test_mammoth_moda2_expansion.py b/tests/e2e/offline_inference/test_mammoth_moda2_expansion.py
index faedd0e0937..a5f7aac1dcb 100644
--- a/tests/e2e/offline_inference/test_mammoth_moda2_expansion.py
+++ b/tests/e2e/offline_inference/test_mammoth_moda2_expansion.py
@@ -4,8 +4,9 @@
 """
 End-to-end test for MammothModa2 text-to-image generation.
 
-Verifies that the AR->DiT pipeline produces an image tensor whose pixel values
-match a golden reference.
+Verifies that the AR->DiT pipeline produces a valid PIL image. When an
+optional golden fixture is present, the test also compares fixed pixel samples;
+the portable golden/stability oracle remains tracked in #7090.
 
 Model Hub repo id: ``bytedance-research/MammothModa2-Preview``.
 Deploy config: ``get_deploy_config_path("mammoth_moda2.yaml")`` -> ``vllm_omni/deploy/mammoth_moda2.yaml``
@@ -20,13 +21,17 @@
 import os
 from pathlib import Path
 
+import numpy as np
 import pytest
 import torch
+from PIL import Image
 from vllm.sampling_params import SamplingParams
 
 from tests.helpers.mark import hardware_test
 from tests.helpers.runtime import OmniRunner
 from tests.helpers.stage_config import get_deploy_config_path
+from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+from vllm_omni.outputs import OmniRequestOutput
 from vllm_omni.transformers_utils.repo_utils import hf_api
 
 # ---------------------------------------------------------------------------
@@ -43,7 +48,7 @@
 
 _OMNI_RUNNER_PARAM = (MODEL_PATH, T2I_DEPLOY_CONFIG)
 
-# Golden pixel reference file.  Set UPDATE_GOLDEN=1 to regenerate.
+# Optional golden pixel reference file. Set UPDATE_GOLDEN=1 to regenerate.
 _GOLDEN_T2I_PATH = Path(__file__).parent / "fixtures" / "mammoth_moda2_t2i_golden.json"
 # Fixed sampling coordinates: (channel, row_fraction, col_fraction)
 # Covers corners, centre, and mid-edges across all 3 channels.
@@ -98,17 +103,33 @@ def _sample_pixels(img_tensor: torch.Tensor) -> list[float]:
     return values
 
 
-# ---------------------------------------------------------------------------
-# End-to-end test
-# ---------------------------------------------------------------------------
-pytestmark = [
-    pytest.mark.slow,
-    pytest.mark.diffusion,
-    pytest.mark.parametrize("omni_runner", [_OMNI_RUNNER_PARAM], indirect=True),
-]
+def _iter_images(outputs: list[object]):
+    """Yield images from shared diffusion ``OmniRequestOutput`` objects."""
+    for out in outputs:
+        ro_list = out if isinstance(out, list) else [out]
+        for ro in ro_list:
+            images = getattr(ro, "images", None)
+            if isinstance(images, list):
+                yield from images
+
+
+def _pil_to_tensor(image: Image.Image) -> torch.Tensor:
+    array = np.asarray(image, dtype=np.float32) / 255.0
+    return torch.from_numpy(array).permute(2, 0, 1)
+
 
+@pytest.mark.cpu
+def test_diffusion_output_exposes_images_at_top_level():
+    image = Image.new("RGB", (16, 16), "black")
+    output = OmniRequestOutput.from_diffusion(request_id="diffusion-test", images=[image])
 
-@pytest.mark.skip(reason="https://github.com/vllm-project/vllm-omni/issues/7718")
+    assert output.outputs == []
+    assert list(_iter_images([output])) == [image]
+
+
+@pytest.mark.slow
+@pytest.mark.diffusion
+@pytest.mark.parametrize("omni_runner", [_OMNI_RUNNER_PARAM], indirect=True)
 @hardware_test(res={"cuda": "H100"})
 def test_mammothmoda2_t2i_e2e(omni_runner: OmniRunner):
     """
@@ -116,9 +137,9 @@ def test_mammothmoda2_t2i_e2e(omni_runner: OmniRunner):
 
     Verifies:
       - Omni pipeline initialises with the two-stage YAML config.
-      - DiT stage outputs an image tensor with the correct shape.
-      - A fixed set of pixel values matches a golden reference
-        (regenerate with ``UPDATE_GOLDEN=1``).
+      - DiT stage outputs one RGB PIL image at the requested size.
+      - When the optional fixture exists, fixed pixel samples match its golden
+        reference (regenerate with ``UPDATE_GOLDEN=1``).
     """
     gen_cfg = _load_t2i_gen_config(MODEL_PATH)
     eol_token_id = int(gen_cfg["eol_token_id"])
@@ -139,7 +160,14 @@ def test_mammothmoda2_t2i_e2e(omni_runner: OmniRunner):
         max_tokens=max(1, expected_grid_tokens + 1),
         detokenize=False,
     )
-    dit_sampling = SamplingParams(temperature=0.0, max_tokens=1, detokenize=False)
+    dit_sampling = OmniDiffusionSamplingParams(
+        height=height,
+        width=width,
+        seed=42,
+        guidance_scale=1.0,
+        num_inference_steps=2,
+        extra_args={"cfg_range": [0.0, 1.0]},
+    )
 
     outputs = list(
         omni.generate(
@@ -155,9 +183,6 @@ def test_mammothmoda2_t2i_e2e(omni_runner: OmniRunner):
                         "visual_token_end_id": [visual_end],
                         "image_height": [height],
                         "image_width": [width],
-                        "num_inference_steps": [2],
-                        "text_guidance_scale": [1.0],
-                        "cfg_range": [0.0, 1.0],
                         "visual_ids": [
                             _IMAGE_TOKEN_ID,
                             _VIDEO_TOKEN_ID,
@@ -173,35 +198,21 @@ def test_mammothmoda2_t2i_e2e(omni_runner: OmniRunner):
 
     assert len(outputs) > 0, "Pipeline produced no outputs"
 
-    found_image = False
-    for out in outputs:
-        ro_list = out
-        if not isinstance(ro_list, list):
-            ro_list = [ro_list]
-        for ro in ro_list:
-            completion_outputs = getattr(ro, "outputs", None)
-            if not isinstance(completion_outputs, list):
-                continue
-            for completion in completion_outputs:
-                mm = getattr(completion, "multimodal_output", None)
-                if not (isinstance(mm, dict) and "image" in mm):
-                    continue
-                img_list = mm["image"] if isinstance(mm["image"], list) else [mm["image"]]
-                for img_tensor in img_list:
-                    assert isinstance(img_tensor, torch.Tensor), f"Expected image tensor, got {type(img_tensor)}"
-                    assert img_tensor.ndim in (3, 4), f"Expected 3D or 4D image tensor, got {img_tensor.ndim}D"
-
-                    sampled = _sample_pixels(img_tensor)
-
-                    if os.environ.get("UPDATE_GOLDEN"):
-                        _GOLDEN_T2I_PATH.parent.mkdir(parents=True, exist_ok=True)
-                        _GOLDEN_T2I_PATH.write_text(json.dumps({"pixels": sampled}, indent=2))
-                        print(f"\nGolden file written to {_GOLDEN_T2I_PATH}")
-                    elif _GOLDEN_T2I_PATH.exists():
-                        golden = json.loads(_GOLDEN_T2I_PATH.read_text())["pixels"]
-                        for i, (got, exp) in enumerate(zip(sampled, golden)):
-                            assert abs(got - exp) < 1e-4, f"Pixel {i} mismatch: got {got}, expected {exp}"
-
-                    found_image = True
-
-    assert found_image, "No image tensor found in pipeline output"
+    images = list(_iter_images(outputs))
+    assert len(images) == 1, f"Expected exactly one image, got {len(images)}"
+
+    image = images[0]
+    assert isinstance(image, Image.Image), f"Expected PIL image, got {type(image)}"
+    assert image.mode == "RGB"
+    assert image.size == (width, height)
+
+    sampled = _sample_pixels(_pil_to_tensor(image))
+
+    if os.environ.get("UPDATE_GOLDEN"):
+        _GOLDEN_T2I_PATH.parent.mkdir(parents=True, exist_ok=True)
+        _GOLDEN_T2I_PATH.write_text(json.dumps({"pixels": sampled}, indent=2))
+        print(f"\nGolden file written to {_GOLDEN_T2I_PATH}")
+    elif _GOLDEN_T2I_PATH.exists():
+        golden = json.loads(_GOLDEN_T2I_PATH.read_text())["pixels"]
+        for i, (got, exp) in enumerate(zip(sampled, golden)):
+            assert abs(got - exp) < 1e-4, f"Pixel {i} mismatch: got {got}, expected {exp}"
diff --git a/tests/model_executor/stage_input_processors/test_mammoth_moda2.py b/tests/model_executor/stage_input_processors/test_mammoth_moda2.py
index 992908c3665..c404b6d5855 100644
--- a/tests/model_executor/stage_input_processors/test_mammoth_moda2.py
+++ b/tests/model_executor/stage_input_processors/test_mammoth_moda2.py
@@ -1,8 +1,8 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-"""CPU regression tests for MammothModa2's completed-AR to DiT bridge."""
+"""CPU regressions for MammothModa2's completed-AR to diffusion bridge."""
 
-from types import SimpleNamespace
+from dataclasses import dataclass
 
 import pytest
 import torch
@@ -16,90 +16,129 @@
 )
 from vllm_omni.engine.stage_engine_core_client import StageEngineCoreClient
 from vllm_omni.model_executor.models.mammoth_moda2.pipeline import MAMMOTH_MODA2_PIPELINE
-from vllm_omni.model_executor.stage_input_processors.mammoth_moda2 import ar2dit
+from vllm_omni.model_executor.stage_input_processors.mammoth_moda2 import ar2diffusion
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
 
-_PROMPT_TOKEN_IDS = [7, 8, 9]
-_GENERATED_TOKEN_IDS = [101, 102, 103]
+@dataclass
+class _CompletionOutputStub:
+    cumulative_token_ids: list[int]
+    multimodal_output: dict[str, torch.Tensor]
 
 
-def _hidden_states(rows: int = 5, dtype: torch.dtype = torch.bfloat16) -> torch.Tensor:
-    return torch.arange(rows * 4, dtype=dtype).reshape(rows, 4)
+@dataclass
+class _AROutputStub:
+    request_id: str
+    prompt_token_ids: list[int]
+    outputs: list[_CompletionOutputStub]
 
 
-def _ar_output(hidden_states: torch.Tensor | None = None) -> SimpleNamespace:
-    multimodal_output = {} if hidden_states is None else {"latent": hidden_states}
-    return SimpleNamespace(
-        request_id="mammoth-request",
-        prompt_token_ids=list(_PROMPT_TOKEN_IDS),
-        outputs=[
-            SimpleNamespace(
-                cumulative_token_ids=list(_GENERATED_TOKEN_IDS),
-                multimodal_output=multimodal_output,
-            )
-        ],
+@dataclass
+class _TextConfigStub:
+    gen_vocab_start_index: int
+
+
+@dataclass
+class _MammothConfigStub:
+    llm_config: _TextConfigStub
+    image_token_id: int
+    video_token_id: int
+    vision_start_token_id: int
+    vision_end_token_id: int
+
+
+def _source_output(*, include_latent: bool = True) -> _AROutputStub:
+    multimodal_output = {"latent": torch.arange(32, dtype=torch.float32).reshape(4, 8)} if include_latent else {}
+    completion = _CompletionOutputStub(
+        cumulative_token_ids=[100, 101, 102],
+        multimodal_output=multimodal_output,
+    )
+    return _AROutputStub(
+        request_id="req-7",
+        prompt_token_ids=[10, 11],
+        outputs=[completion],
     )
 
 
-def _prompt(
-    *,
-    target_h: int | None = None,
-    target_w: int | None = None,
-) -> dict[str, object]:
-    mm_processor_kwargs: dict[str, int] = {}
-    if target_h is not None:
-        mm_processor_kwargs["target_h"] = target_h
-    if target_w is not None:
-        mm_processor_kwargs["target_w"] = target_w
-    return {
-        "additional_information": {
-            "image_height": [384],
-            "image_width": [640],
-            "text_guidance_scale": [4.5],
-            "cfg_range": [0.1, 0.9],
-            "num_inference_steps": [20],
+def test_ar2diffusion_builds_one_prompt_with_raw_ar_conditions() -> None:
+    result = ar2diffusion(
+        [_source_output()],
+        {"prompt": "a cat", "mm_processor_kwargs": {"target_h": 512, "target_w": 768}},
+    )
+    assert not isinstance(result, list)
+    assert result["prompt"] == ""
+    assert result["height"] == 512
+    assert result["width"] == 768
+    info = result["additional_information"]
+    assert info["full_token_ids"] == [10, 11, 100, 101]
+    assert info["answer_start_index"] == 2
+    torch.testing.assert_close(
+        info["full_hidden_states"],
+        torch.arange(32, dtype=torch.float32).reshape(4, 8),
+    )
+    assert info["full_hidden_states"].is_contiguous()
+
+
+def test_ar2diffusion_uses_prompt_dimension_fallbacks() -> None:
+    result = ar2diffusion(
+        [_source_output()],
+        {"additional_information": {"image_height": [256], "image_width": [384]}},
+    )
+    assert (result["height"], result["width"]) == (256, 384)
+
+
+def test_ar2diffusion_preserves_request_level_sampling_fallbacks() -> None:
+    result = ar2diffusion(
+        [_source_output()],
+        {
+            "additional_information": {
+                "text_guidance_scale": [1.5],
+                "num_inference_steps": [3],
+                "cfg_range": [0.25, 0.75],
+            }
         },
-        "mm_processor_kwargs": mm_processor_kwargs,
-    }
+    )
 
+    info = result["additional_information"]
+    assert info["text_guidance_scale"] == [1.5]
+    assert info["num_inference_steps"] == [3]
+    assert info["cfg_range"] == [0.25, 0.75]
 
-def _assert_complete_dit_input(dit_inputs: list[dict[str, object]], hidden_states: torch.Tensor) -> None:
-    assert len(dit_inputs) == 1
-    dit_input = dit_inputs[0]
-    assert dit_input["prompt_token_ids"] == [0]
 
-    additional_information = dit_input["additional_information"]
-    assert isinstance(additional_information, dict)
-    full_hidden_states = additional_information["full_hidden_states"]
-    assert isinstance(full_hidden_states, torch.Tensor)
-    assert full_hidden_states.dtype == torch.bfloat16
-    assert full_hidden_states.is_contiguous()
-    assert torch.equal(full_hidden_states, hidden_states)
-    assert additional_information["full_token_ids"] == [7, 8, 9, 101, 102]
-    assert additional_information["answer_start_index"] == [3]
-    assert additional_information["image_height"] == [384]
-    assert additional_information["image_width"] == [640]
-    assert additional_information["text_guidance_scale"] == [4.5]
-    assert additional_information["cfg_range"] == [0.1, 0.9]
-    assert additional_information["num_inference_steps"] == [20]
+def test_ar2diffusion_unwraps_the_orchestrator_prompt_list() -> None:
+    result = ar2diffusion(
+        [_source_output()],
+        [{"mm_processor_kwargs": {"target_h": 640, "target_w": 960}}],
+    )
+    assert (result["height"], result["width"]) == (640, 960)
+
+
+def test_ar2diffusion_rejects_multiple_source_requests() -> None:
+    with pytest.raises(ValueError, match="exactly one AR output"):
+        ar2diffusion([_source_output(), _source_output()], {})
 
 
-def test_ar2dit_builds_one_complete_dit_input() -> None:
-    hidden_states = _hidden_states()
+def test_ar2diffusion_reports_missing_latent_with_request_id() -> None:
+    with pytest.raises(ValueError, match="req-7"):
+        ar2diffusion([_source_output(include_latent=False)], {})
 
-    dit_inputs = ar2dit([_ar_output(hidden_states)], _prompt())
 
-    _assert_complete_dit_input(dit_inputs, hidden_states)
+def test_ar2diffusion_rejects_hidden_state_length_mismatch() -> None:
+    source = _source_output()
+    source.outputs[0].multimodal_output["latent"] = torch.zeros(3, 8)
+    with pytest.raises(ValueError, match="Hidden states length mismatch"):
+        ar2diffusion([source], {})
 
 
 @pytest.mark.parametrize("dtype", (torch.float16, torch.bfloat16))
-def test_ar2dit_preserves_low_precision_through_engine_core_payload(dtype: torch.dtype) -> None:
-    hidden_states = _hidden_states(dtype=dtype)
-    dit_input = ar2dit([_ar_output(hidden_states)], _prompt())[0]
+def test_ar2diffusion_preserves_low_precision_through_engine_core_payload(dtype: torch.dtype) -> None:
+    source = _source_output()
+    hidden_states = torch.arange(32, dtype=dtype).reshape(4, 8)
+    source.outputs[0].multimodal_output["latent"] = hidden_states
+    diffusion_input = ar2diffusion([source], {})
 
-    wire_payload = serialize_additional_information(dit_input["additional_information"])
+    wire_payload = serialize_additional_information(diffusion_input["additional_information"])
     assert wire_payload is not None
     restored = deserialize_additional_information(wire_payload)
     restored_hidden_states = restored["full_hidden_states"]
@@ -112,21 +151,19 @@ def test_ar2dit_preserves_low_precision_through_engine_core_payload(dtype: torch
 
 @pytest.mark.parametrize("dtype", (torch.float16, torch.bfloat16))
 def test_dit_condition_split_preserves_compact_transfer_dtype(dtype: torch.dtype) -> None:
-    # Construct only the config read by _split_ar_conditions.  This keeps the
-    # test CPU-only and avoids loading the DiT/VAE weights.
     pipeline = object.__new__(MammothModa2DiTPipeline)
     object.__setattr__(
         pipeline,
         "config",
-        SimpleNamespace(
-            llm_config=SimpleNamespace(gen_vocab_start_index=100),
+        _MammothConfigStub(
+            llm_config=_TextConfigStub(gen_vocab_start_index=100),
             image_token_id=20,
             video_token_id=21,
             vision_start_token_id=22,
             vision_end_token_id=23,
         ),
     )
-    hidden_states = _hidden_states(dtype=dtype)
+    hidden_states = torch.arange(20, dtype=dtype).reshape(5, 4)
 
     text_cond, image_cond = pipeline._split_ar_conditions(
         full_hidden_states=hidden_states,
@@ -142,44 +179,29 @@ def test_dit_condition_split_preserves_compact_transfer_dtype(dtype: torch.dtype
     assert torch.equal(image_cond, hidden_states[[3, 4]])
 
 
-def test_ar2dit_prefers_processor_image_dimensions() -> None:
-    hidden_states = _hidden_states()
-
-    dit_inputs = ar2dit([_ar_output(hidden_states)], _prompt(target_h=512, target_w=768))
-
-    additional_information = dit_inputs[0]["additional_information"]
-    assert additional_information["image_height"] == [512]
-    assert additional_information["image_width"] == [768]
-
-
-def test_ar2dit_rejects_missing_latent_output() -> None:
-    with pytest.raises(ValueError, match="missing latent multimodal output"):
-        ar2dit([_ar_output()], _prompt())
-
-
-def test_ar2dit_rejects_hidden_token_row_mismatch() -> None:
-    with pytest.raises(AssertionError, match="Hidden states length mismatch"):
-        ar2dit([_ar_output(_hidden_states(rows=4))], _prompt())
-
-
 def test_mammoth_pipeline_uses_standard_completed_ar_forwarding() -> None:
     stage0, stage1 = MAMMOTH_MODA2_PIPELINE.stages
 
     assert stage0.custom_process_next_stage_input_func is None
-    assert stage1.custom_process_input_func.endswith(".ar2dit")
+    assert stage1.custom_process_input_func.endswith(".ar2diffusion")
     assert stage1.sync_process_input_func is None
     assert stage1.requires_full_payload_input is False
 
 
 def test_stage_client_forwards_completed_ar_output_to_mammoth_adapter() -> None:
-    hidden_states = _hidden_states()
+    source = _source_output()
     client = object.__new__(StageEngineCoreClient)
-    client.custom_process_input_func = ar2dit
+    client.custom_process_input_func = ar2diffusion
     client.requires_multimodal_data = False
 
-    dit_inputs = client.process_engine_inputs(
-        [_ar_output(hidden_states)],
-        _prompt(),
+    diffusion_input = client.process_engine_inputs(
+        [source],
+        {"mm_processor_kwargs": {"target_h": 512, "target_w": 768}},
     )
 
-    _assert_complete_dit_input(dit_inputs, hidden_states)
+    assert diffusion_input["height"] == 512
+    assert diffusion_input["width"] == 768
+    info = diffusion_input["additional_information"]
+    assert info["full_token_ids"] == [10, 11, 100, 101]
+    assert info["answer_start_index"] == 2
+    assert torch.equal(info["full_hidden_states"], source.outputs[0].multimodal_output["latent"])
diff --git a/tests/model_tests/diffusion/test_alignment.py b/tests/model_tests/diffusion/test_alignment.py
index ed266d73434..f7f1855cc3c 100644
--- a/tests/model_tests/diffusion/test_alignment.py
+++ b/tests/model_tests/diffusion/test_alignment.py
@@ -28,6 +28,9 @@
     "GlmImagePipeline",
     "ZImagePipeline",
     "OvisImagePipeline",
+    # Requires upstream AR hidden states and token boundaries; covered by
+    # dedicated MammothModa2 bridge/pipeline tests and real-checkpoint E2E.
+    "MammothModa2DiTPipeline",
     "WanPipeline",
     "WanDMDPipeline",
     "WanVACEPipeline",
diff --git a/tests/worker/test_omni_connector_mixin.py b/tests/worker/test_omni_connector_mixin.py
index 603ca65ffe8..ec2d4a70432 100644
--- a/tests/worker/test_omni_connector_mixin.py
+++ b/tests/worker/test_omni_connector_mixin.py
@@ -397,7 +397,7 @@ def test_uses_validator_override_from_public_mixin(self):
     def test_skips_non_payload_stage_input_processors_for_full_payload_mode(self):
         incompatible_paths = [
             "vllm_omni.model_executor.stage_input_processors.mimo_audio.llm2code2wav",
-            "vllm_omni.model_executor.stage_input_processors.mammoth_moda2.ar2dit",
+            "vllm_omni.model_executor.stage_input_processors.mammoth_moda2.ar2diffusion",
             "vllm_omni.model_executor.stage_input_processors.cosyvoice3.text2flow",
             "vllm_omni.model_executor.stage_input_processors.glm_image.ar2diffusion",
         ]
diff --git a/vllm_omni/config/endpoint_policy.py b/vllm_omni/config/endpoint_policy.py
index f0aca95eb9e..24dea97e2fe 100644
--- a/vllm_omni/config/endpoint_policy.py
+++ b/vllm_omni/config/endpoint_policy.py
@@ -24,6 +24,7 @@ class OmniServingCapability(Enum):
     """Serving capabilities that pipelines can shut down."""
 
     COMPLETIONS = RouteTarget("/v1/completions", frozenset({"POST"}))
+    IMAGE_EDITS = RouteTarget("/v1/images/edits", frozenset({"POST"}))
 
     @property
     def path(self) -> str:
diff --git a/vllm_omni/deploy/mammoth_moda2.yaml b/vllm_omni/deploy/mammoth_moda2.yaml
index afae38ee0e1..76027424c40 100644
--- a/vllm_omni/deploy/mammoth_moda2.yaml
+++ b/vllm_omni/deploy/mammoth_moda2.yaml
@@ -20,8 +20,3 @@ stages:
     enforce_eager: true
     trust_remote_code: true
     enable_prefix_caching: false
-    default_sampling_params:
-      extra_args:
-        text_guidance_scale: 9.0
-        cfg_range: [0.0, 1.0]
-        num_inference_steps: 50
diff --git a/vllm_omni/diffusion/models/mammoth_moda2/pipeline_mammothmoda2_dit.py b/vllm_omni/diffusion/models/mammoth_moda2/pipeline_mammothmoda2_dit.py
index c96e5548cc8..21977f488d7 100644
--- a/vllm_omni/diffusion/models/mammoth_moda2/pipeline_mammothmoda2_dit.py
+++ b/vllm_omni/diffusion/models/mammoth_moda2/pipeline_mammothmoda2_dit.py
@@ -3,19 +3,23 @@
 from __future__ import annotations
 
 from collections.abc import Iterable
-from typing import Any, ClassVar
+from dataclasses import dataclass
+from typing import ClassVar
 
 import torch
+from diffusers.image_processor import VaeImageProcessor
 from diffusers.models.autoencoders.autoencoder_kl import AutoencoderKL
 from diffusers.utils.torch_utils import randn_tensor
 from torch import nn
 from transformers.models.qwen2.modeling_qwen2 import Qwen2RMSNorm
-from vllm.config import VllmConfig
 from vllm.logger import init_logger
 from vllm.model_executor.models.utils import AutoWeightsLoader, WeightsMapper
 
+from vllm_omni.diffusion.data import DiffusionOutput, OmniDiffusionConfig
+from vllm_omni.diffusion.distributed.utils import get_local_device
+from vllm_omni.diffusion.model_loader.diffusers_loader import DiffusersPipelineLoader
 from vllm_omni.diffusion.models.interface import SupportsComponentDiscovery
-from vllm_omni.model_executor.models.output_templates import OmniOutput
+from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch
 from vllm_omni.transformers_utils.configs.mammoth_moda2 import Mammothmoda2Config
 
 from .mammothmoda2_dit_model import SimpleQFormerImageRefiner, Transformer2DModel
@@ -25,6 +29,59 @@
 logger = init_logger(__name__)
 
 
+def _first_request_value(value: object) -> object:
+    if isinstance(value, (list, tuple)):
+        return value[0] if value else None
+    return value
+
+
+def get_mammoth_moda2_post_process_func(
+    _od_config: OmniDiffusionConfig,
+):
+    image_processor = VaeImageProcessor()
+
+    def post_process_func(images: torch.Tensor):
+        return image_processor.postprocess(images)
+
+    return post_process_func
+
+
+def _build_mammoth_config(od_config: OmniDiffusionConfig) -> Mammothmoda2Config:
+    raw_config = od_config.tf_model_config.to_dict()
+    if not raw_config:
+        raise ValueError("MammothModa2 diffusion stage requires the root checkpoint config")
+    return Mammothmoda2Config(**raw_config)
+
+
+def _root_weight_source(
+    od_config: OmniDiffusionConfig,
+) -> DiffusersPipelineLoader.ComponentSource:
+    if not od_config.model:
+        raise ValueError("MammothModa2 diffusion stage requires a model path")
+    return DiffusersPipelineLoader.ComponentSource(
+        model_or_path=od_config.model,
+        subfolder=None,
+        revision=od_config.revision,
+        prefix="",
+        fall_back_to_pt=True,
+    )
+
+
+@dataclass(frozen=True)
+class _MammothRequest:
+    request_id: str
+    full_hidden_states: torch.Tensor
+    full_token_ids: list[int]
+    answer_start_index: int
+    height: int
+    width: int
+    text_guidance_scale: float
+    cfg_range: tuple[float, float]
+    num_inference_steps: int
+    seed: int | None
+    generator: torch.Generator | list[torch.Generator] | None
+
+
 class MammothModa2DiTPipeline(nn.Module, SupportsComponentDiscovery):
     """
     MammothModa2 DiT + VAE generation stage (non-autoregressive).
@@ -38,7 +95,8 @@ class MammothModa2DiTPipeline(nn.Module, SupportsComponentDiscovery):
     _encoder_modules: ClassVar[list[str]] = ["gen_image_condition_refiner"]
     _vae_modules: ClassVar[list[str]] = ["gen_vae"]
 
-    have_multimodal_outputs = True
+    supports_request_batch = False
+    supports_step_execution = False
 
     # Load only gen_* weights; ignore llm_model.* to prevent loading the entire LLM backbone in the DiT stage.
     hf_to_vllm_mapper = WeightsMapper(
@@ -48,15 +106,13 @@ class MammothModa2DiTPipeline(nn.Module, SupportsComponentDiscovery):
         }
     )
 
-    def __init__(self, *, vllm_config: VllmConfig, prefix: str = ""):
+    def __init__(self, *, od_config: OmniDiffusionConfig, prefix: str = ""):
         super().__init__()
         del prefix
-
-        hf_config = vllm_config.model_config.hf_config
-        if not isinstance(hf_config, Mammothmoda2Config):
-            raise TypeError(f"Expected Mammothmoda2Config, got {type(hf_config)}")
-
-        self.config = hf_config
+        self.od_config = od_config
+        self.device = get_local_device()
+        self.config = _build_mammoth_config(od_config)
+        self.weights_sources = [_root_weight_source(od_config)]
 
         # --- Build DiT / VAE modules (names must match checkpoint keys) ---
         if self.config.gen_vae_config is None or self.config.gen_dit_config is None:
@@ -111,9 +167,6 @@ def __init__(self, *, vllm_config: VllmConfig, prefix: str = ""):
             theta=10000,
         )
 
-        # vLLM PP interface compatibility
-        self.make_empty_intermediate_tensors = lambda: None
-
         self._llm_hidden_size = llm_hidden_size
 
     def _reinit_caption_embedder(self, in_features: int) -> None:
@@ -125,39 +178,118 @@ def _reinit_caption_embedder(self, in_features: int) -> None:
             nn.Linear(in_features, out_features, bias=True),
         )
 
-    def get_dummy_runtime_additional_information(self, num_reqs: int) -> list[dict[str, object]]:
-        if num_reqs <= 0:
-            raise ValueError(f"num_reqs must be positive, got {num_reqs}")
-        if num_reqs > 1:
-            raise NotImplementedError(
-                f"get_dummy_runtime_additional_information does not support num_reqs > 1, got {num_reqs}"
+    def _parse_request(self, req: DiffusionRequestBatch) -> _MammothRequest:
+        if req.num_reqs != 1:
+            raise ValueError("MammothModa2 diffusion requires exactly one request")
+        request_id = req.request_id
+        sampling = req.sampling_params
+        if sampling.num_outputs_per_prompt != 1:
+            raise ValueError(f"MammothModa2 requires num_outputs_per_prompt=1 for request {request_id}")
+
+        prompt = req.prompts[0]
+        prompt = prompt if isinstance(prompt, dict) else {}
+        info = prompt.get("additional_information")
+        if req.is_dummy_run():
+            full_hidden_states = torch.zeros((2, self._llm_hidden_size), dtype=torch.float32, device="cpu")
+            full_token_ids = [0, int(self.config.llm_config.gen_vocab_start_index)]
+            answer_start_index = 1
+        else:
+            if not isinstance(info, dict):
+                raise ValueError(f"Missing additional_information AR conditions for request {request_id}")
+            full_hidden_states = info.get("full_hidden_states")
+            full_token_ids = info.get("full_token_ids")
+            if not isinstance(full_hidden_states, torch.Tensor) or not isinstance(full_token_ids, list):
+                raise ValueError(f"Expected full_hidden_states tensor and full_token_ids list for request {request_id}")
+            try:
+                answer_start_index = int(info.get("answer_start_index"))
+            except (TypeError, ValueError, OverflowError) as exc:
+                raise ValueError(f"Invalid answer_start_index for request {request_id}") from exc
+            if full_hidden_states.ndim != 2:
+                raise ValueError(f"Expected 2D full_hidden_states for request {request_id}")
+            if full_hidden_states.shape[0] != len(full_token_ids):
+                raise ValueError(f"AR hidden-state/token-count mismatch for request {request_id}")
+            if not 0 <= answer_start_index <= len(full_token_ids):
+                raise ValueError(f"answer_start_index outside token range for request {request_id}")
+            try:
+                full_token_ids = [int(token_id) for token_id in full_token_ids]
+            except (TypeError, ValueError, OverflowError) as exc:
+                raise ValueError(f"Invalid full_token_ids for request {request_id}") from exc
+
+        dimensions = []
+        for name in ("height", "width"):
+            value = DiffusionRequestBatch.get_prompt_field(prompt, name)
+            if value is None:
+                value = getattr(sampling, name)
+            if value is None:
+                value = 1024
+            try:
+                dimensions.append(int(value))
+            except (TypeError, ValueError, OverflowError) as exc:
+                raise ValueError(f"Invalid image size {name}={value!r} for request {request_id}") from exc
+        height, width = dimensions
+        if height <= 0 or width <= 0:
+            raise ValueError(f"Invalid image size: {height}x{width} for request {request_id}")
+        if height % 16 != 0 or width % 16 != 0:
+            raise ValueError(f"Image size must be multiples of 16, got {height}x{width} for request {request_id}")
+
+        request_info = info if isinstance(info, dict) else {}
+        extra_args = sampling.extra_args or {}
+        guidance = extra_args.get("text_guidance_scale")
+        if guidance is None:
+            guidance = sampling.guidance_scale if sampling.guidance_scale_provided else None
+        if guidance is None:
+            guidance = _first_request_value(request_info.get("text_guidance_scale"))
+        if guidance is None:
+            guidance = 9.0
+        try:
+            text_guidance_scale = float(guidance)
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise ValueError(f"Invalid text_guidance_scale for request {request_id}") from exc
+        raw_num_inference_steps = extra_args.get("num_inference_steps")
+        if raw_num_inference_steps is None:
+            raw_num_inference_steps = sampling.num_inference_steps
+        if raw_num_inference_steps is None:
+            raw_num_inference_steps = _first_request_value(request_info.get("num_inference_steps"))
+        if raw_num_inference_steps is None:
+            raw_num_inference_steps = 50
+        try:
+            num_inference_steps = int(raw_num_inference_steps)
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise ValueError(f"Invalid num_inference_steps for request {request_id}") from exc
+        if num_inference_steps <= 0:
+            raise ValueError(f"num_inference_steps must be positive for request {request_id}")
+        cfg_range = extra_args.get("cfg_range")
+        if cfg_range is None:
+            cfg_range = request_info.get("cfg_range")
+        if cfg_range is None:
+            cfg_range = [0.0, 1.0]
+        if not isinstance(cfg_range, (list, tuple)) or len(cfg_range) != 2:
+            raise ValueError(f"cfg_range requires two values for request {request_id}")
+        try:
+            cfg_start, cfg_end = float(cfg_range[0]), float(cfg_range[1])
+        except (TypeError, ValueError, OverflowError) as exc:
+            raise ValueError(f"cfg_range requires two values convertible to floats for request {request_id}") from exc
+        if not 0 <= cfg_start <= cfg_end <= 1:
+            raise ValueError(f"cfg_range must satisfy 0 <= start <= end <= 1 for request {request_id}")
+
+        generator = sampling.generator
+        if isinstance(generator, list) and len(generator) != 1:
+            raise ValueError(
+                f"MammothModa2 single-output request mode requires exactly one generator for request {request_id}"
             )
-        text_prompt_embeds = torch.zeros((1, self._llm_hidden_size), dtype=torch.float32)
-        image_prompt_embeds = torch.zeros((1, self._llm_hidden_size), dtype=torch.float32)
-        negative_prompt_embeds = torch.zeros((0, self._llm_hidden_size), dtype=torch.float32)
-        info = {
-            "text_prompt_embeds": text_prompt_embeds,
-            "image_prompt_embeds": image_prompt_embeds,
-            "negative_prompt_embeds": negative_prompt_embeds,
-            "negative_prompt_attention_mask": [],
-            "image_height": [512],
-            "image_width": [512],
-            "text_guidance_scale": [1.0],
-            "cfg_range": [0.0, 1.0],
-            "num_inference_steps": [1],
-        }
-        return [info for _ in range(num_reqs)]
 
-    def embed_input_ids(self, input_ids: torch.Tensor) -> torch.Tensor:
-        # DiT stage does not consume token embeddings; return a dummy tensor.
-        try:
-            dtype = next(self.parameters()).dtype
-        except StopIteration:
-            dtype = torch.float32
-        return torch.zeros(
-            (input_ids.numel(), self._llm_hidden_size),
-            device=input_ids.device,
-            dtype=dtype,
+        return _MammothRequest(
+            request_id=request_id,
+            full_hidden_states=full_hidden_states,
+            full_token_ids=full_token_ids,
+            answer_start_index=answer_start_index,
+            height=height,
+            width=width,
+            text_guidance_scale=text_guidance_scale,
+            cfg_range=(cfg_start, cfg_end),
+            num_inference_steps=num_inference_steps,
+            seed=sampling.seed,
+            generator=generator,
         )
 
     def _split_ar_conditions(
@@ -202,42 +334,19 @@ def _split_ar_conditions(
         return text_cond, image_cond
 
     @torch.inference_mode()
-    def forward(
-        self,
-        *,
-        inputs_embeds: torch.Tensor | None = None,
-        **kwargs: Any,  # noqa: ARG002
-    ) -> OmniOutput:
-        runtime_addi = kwargs.get("runtime_additional_information", None)
-        info = runtime_addi[0]
-
-        # Sampling knobs are declared in vllm_omni/model_extras/mammothmodal2_preview.py
-        # and routed via extra_body -> sampling_params.extra_args (surfaced here as
-        # ``sampling_extra_args``). Fall back to runtime_additional_information for the
-        # legacy bespoke-example path during the transition.
-        extra_args_list = kwargs.get("sampling_extra_args") or []
-        extra_args = extra_args_list[0] if extra_args_list else {}
-        text_guidance_scale = float(extra_args.get("text_guidance_scale", info["text_guidance_scale"][0]))
-        cfg_range_val = extra_args.get("cfg_range", info["cfg_range"])
-        cfg_range = float(cfg_range_val[0]), float(cfg_range_val[1])
-        num_inference_steps = int(extra_args.get("num_inference_steps", info["num_inference_steps"][0]))
-
-        negative_cond = info.get("negative_prompt_embeds")
-        negative_attention_mask = info.get("negative_prompt_attention_mask")
-        image_hw = info["image_height"][0], info["image_width"][0]
-
-        # Split the AR hidden states into text / image conditions. The token ids that
-        # drive the split are sourced from the model config (see _split_ar_conditions),
-        # formerly supplied by the bespoke example via additional_information. Legacy
-        # fallback: ar2dit may have already produced the split conditions.
-        if "text_prompt_embeds" in info:
-            text_cond = info["text_prompt_embeds"]
-            image_cond = info["image_prompt_embeds"]
-        else:
-            text_cond, image_cond = self._split_ar_conditions(
-                full_hidden_states=info["full_hidden_states"],
-                full_token_ids=info["full_token_ids"],
-                answer_start_index=int(info["answer_start_index"][0]),
+    def forward(self, req: DiffusionRequestBatch) -> DiffusionOutput:
+        request = self._parse_request(req)
+        text_cond, image_cond = self._split_ar_conditions(
+            full_hidden_states=request.full_hidden_states,
+            full_token_ids=request.full_token_ids,
+            answer_start_index=request.answer_start_index,
+        )
+        if image_cond.shape[0] == 0:
+            answer_token_ids = request.full_token_ids[request.answer_start_index :]
+            raise ValueError(
+                "MammothModa2 AR stage produced no visual-token hidden states for "
+                f"request {request.request_id}; the DiT stage requires at least one generated visual token. "
+                f"Generated token ids: {answer_token_ids[:32]}"
             )
 
         # Move to model device/dtype.
@@ -247,22 +356,6 @@ def forward(
         else:
             target_dtype = next(self.gen_transformer.parameters()).dtype
 
-        def _ensure_2d(x: torch.Tensor, name: str) -> torch.Tensor:
-            if x.ndim == 3 and x.shape[0] == 1:
-                x = x[0]
-            if x.ndim != 2:
-                raise ValueError(f"Expected {name} to be 2D [T,H], got shape={tuple(x.shape)}")
-            return x
-
-        text_cond = _ensure_2d(text_cond, "text_prompt_embeds")
-        image_cond = _ensure_2d(image_cond, "image_prompt_embeds")
-        if image_cond.shape[0] == 0:
-            answer_token_ids = info.get("full_token_ids", [])[int(info.get("answer_start_index", [0])[0]) :]
-            raise ValueError(
-                "MammothModa2 AR stage produced no visual-token hidden states; "
-                "the DiT stage requires at least one generated visual token. "
-                f"Generated token ids: {answer_token_ids[:32]}"
-            )
         text_cond = text_cond.to(device=model_device, dtype=target_dtype, non_blocking=True).contiguous()
         image_cond = image_cond.to(device=model_device, dtype=target_dtype, non_blocking=True).contiguous()
 
@@ -301,63 +394,38 @@ def _ensure_2d(x: torch.Tensor, name: str) -> torch.Tensor:
             ar_image_embeds = image_embeds
             ar_image_attention_mask = image_attention_mask
 
-        # Prepare negative prompt (for CFG). If none provided, fall back to unconditional.
+        # Empty unconditional prompt for classifier-free guidance.
         negative_prompt_embeds = None
         negative_prompt_attention_mask = None
-        if text_guidance_scale > 1.0:
-            if negative_cond is not None:
-                negative_cond = _ensure_2d(negative_cond, "negative_prompt_embeds")
-                negative_prompt_embeds = (
-                    negative_cond.to(device=model_device, dtype=target_dtype, non_blocking=True)
-                    .contiguous()
-                    .unsqueeze(0)
-                )
-                if isinstance(negative_attention_mask, torch.Tensor):
-                    neg_mask = negative_attention_mask
-                elif isinstance(negative_attention_mask, list):
-                    neg_mask = torch.tensor(negative_attention_mask, dtype=torch.bool)
-                else:
-                    neg_mask = None
-                if neg_mask is None:
-                    negative_prompt_attention_mask = torch.ones(
-                        (1, negative_prompt_embeds.shape[1]),
-                        dtype=torch.bool,
-                        device=negative_prompt_embeds.device,
-                    )
-                else:
-                    neg_mask = neg_mask.to(device=negative_prompt_embeds.device, dtype=torch.bool)
-                    if neg_mask.ndim == 1:
-                        neg_mask = neg_mask.unsqueeze(0)
-                    negative_prompt_attention_mask = neg_mask
-            else:
-                hidden_size = int(prompt_embeds.shape[-1])
-                negative_prompt_embeds = torch.zeros(
-                    (1, 0, hidden_size),
-                    dtype=target_dtype,
-                    device=prompt_embeds.device,
-                )
-                negative_prompt_attention_mask = torch.zeros(
-                    (1, 0),
-                    dtype=torch.bool,
-                    device=prompt_embeds.device,
-                )
+        if request.text_guidance_scale > 1.0:
+            hidden_size = int(prompt_embeds.shape[-1])
+            negative_prompt_embeds = torch.zeros(
+                (1, 0, hidden_size),
+                dtype=target_dtype,
+                device=prompt_embeds.device,
+            )
+            negative_prompt_attention_mask = torch.zeros(
+                (1, 0),
+                dtype=torch.bool,
+                device=prompt_embeds.device,
+            )
+
+        generator = request.generator
+        if generator is None and request.seed is not None:
+            generator = torch.Generator(device=model_device).manual_seed(request.seed)
 
         # Output image size (px), passed from stage input processor.
-        height, width = image_hw
-        if height <= 0 or width <= 0:
-            raise ValueError(f"Invalid image size: {height}x{width}")
-        if height % 16 != 0 or width % 16 != 0:
-            raise ValueError(f"Image size must be multiples of 16, got {height}x{width}")
+        height, width = request.height, request.width
         vae_scale_factor = 16
 
         latent_channels = int(self.gen_transformer.config.in_channels)
         shape = (1, latent_channels, 2 * height // vae_scale_factor, 2 * width // vae_scale_factor)
-        latents = randn_tensor(shape, device=prompt_embeds.device, dtype=prompt_embeds.dtype)
+        latents = randn_tensor(shape, generator=generator, device=prompt_embeds.device, dtype=prompt_embeds.dtype)
 
         scheduler = FlowMatchEulerDiscreteScheduler()
 
         scheduler.set_timesteps(
-            num_inference_steps=num_inference_steps,
+            num_inference_steps=request.num_inference_steps,
             device=prompt_embeds.device,
             num_tokens=latents.shape[-2] * latents.shape[-1],
         )
@@ -376,7 +444,9 @@ def _ensure_2d(x: torch.Tensor, name: str) -> torch.Tensor:
                 ar_image_attention_mask=ar_image_attention_mask,
                 freqs_cis=self.gen_freqs_cis,
             )
-            guidance_scale = text_guidance_scale if cfg_range[0] <= i / total_steps <= cfg_range[1] else 1.0
+            guidance_scale = (
+                request.text_guidance_scale if request.cfg_range[0] <= i / total_steps <= request.cfg_range[1] else 1.0
+            )
             if guidance_scale > 1.0 and negative_prompt_embeds is not None:
                 model_pred_uncond = self.gen_transformer(
                     hidden_states=latents,
@@ -397,14 +467,7 @@ def _ensure_2d(x: torch.Tensor, name: str) -> torch.Tensor:
             latents = latents + self.gen_vae.config.shift_factor
         image = self.gen_vae.decode(latents, return_dict=False)[0]
 
-        return OmniOutput(
-            text_hidden_states=inputs_embeds,  # placeholder, not used by runner
-            multimodal_outputs=image,
-            intermediate_tensors=None,
-        )
-
-    def compute_logits(self, hidden_states: torch.Tensor) -> torch.Tensor | None:  # noqa: ARG002
-        return None
+        return DiffusionOutput(output=image)
 
     def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
         loader = AutoWeightsLoader(self)
diff --git a/vllm_omni/diffusion/registry.py b/vllm_omni/diffusion/registry.py
index f94952b1dcf..fadb712df00 100644
--- a/vllm_omni/diffusion/registry.py
+++ b/vllm_omni/diffusion/registry.py
@@ -56,6 +56,11 @@
         "pipeline_ovis_image",
         "OvisImagePipeline",
     ),
+    "MammothModa2DiTPipeline": (
+        "mammoth_moda2",
+        "pipeline_mammothmoda2_dit",
+        "MammothModa2DiTPipeline",
+    ),
     "WanPipeline": (
         "wan2_2",
         "pipeline_wan2_2",
@@ -564,6 +569,7 @@ def _apply_sequence_parallel_if_enabled(model, od_config: OmniDiffusionConfig) -
     "GlmImagePipeline": "get_glm_image_post_process_func",
     "ZImagePipeline": "get_post_process_func",
     "OvisImagePipeline": "get_ovis_image_post_process_func",
+    "MammothModa2DiTPipeline": "get_mammoth_moda2_post_process_func",
     "BooguImagePipeline": "get_boogu_image_post_process_func",
     "BooguImageTurboPipeline": "get_boogu_image_post_process_func",
     "WanPipeline": "get_wan22_post_process_func",
diff --git a/vllm_omni/model_executor/models/mammoth_moda2/pipeline.py b/vllm_omni/model_executor/models/mammoth_moda2/pipeline.py
index 830c63aff32..be2e256fbf6 100644
--- a/vllm_omni/model_executor/models/mammoth_moda2/pipeline.py
+++ b/vllm_omni/model_executor/models/mammoth_moda2/pipeline.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """MammothModa2 pipeline topology (frozen).
 
 Stage 0: AR  — multimodal understanding + latent generation
@@ -8,6 +8,7 @@
 For text/image understanding tasks (text output only), use MAMMOTH_MODA2_AR_PIPELINE.
 """
 
+from vllm_omni.config.endpoint_policy import EndpointRestriction, OmniServingCapability
 from vllm_omni.config.stage_config import (
     PipelineConfig,
     StageExecutionType,
@@ -21,6 +22,13 @@
     default_deploy_config_name="mammoth_moda2.yaml",
     model_arch="MammothModa2ForConditionalGeneration",
     hf_architectures=("Mammothmoda2Model", "MammothModa2ForConditionalGeneration"),
+    endpoint_restrictions=(
+        EndpointRestriction(
+            OmniServingCapability.IMAGE_EDITS,
+            "MammothModa2 image editing (img2img) is not supported. "
+            "Use /v1/images/generations for text-to-image requests.",
+        ),
+    ),
     stages=(
         StagePipelineConfig(
             stage_id=0,
@@ -35,14 +43,15 @@
         StagePipelineConfig(
             stage_id=1,
             model_stage="dit",
-            execution_type=StageExecutionType.LLM_GENERATION,
+            execution_type=StageExecutionType.DIFFUSION,
             input_sources=(0,),
             final_output=True,
             final_output_type="image",
             owns_tokenizer=False,
             requires_multimodal_data=False,
-            engine_output_type="image",
-            custom_process_input_func=f"{_PROC}.ar2dit",
+            model_arch="MammothModa2DiTPipeline",
+            custom_process_input_func=f"{_PROC}.ar2diffusion",
+            omni_kv_config={"need_recv_cache": False},
         ),
     ),
 )
diff --git a/vllm_omni/model_executor/models/registry.py b/vllm_omni/model_executor/models/registry.py
index 1a519917ce9..d1638ae9db7 100644
--- a/vllm_omni/model_executor/models/registry.py
+++ b/vllm_omni/model_executor/models/registry.py
@@ -142,11 +142,6 @@
         "mammoth_moda2",
         "MammothModa2Qwen3ForCausalLM",
     ),
-    "MammothModa2DiTPipeline": (
-        "mammoth_moda2",
-        "pipeline_mammothmoda2_dit",
-        "MammothModa2DiTPipeline",
-    ),
     "MammothModa2ForConditionalGeneration": (
         "mammoth_moda2",
         "mammoth_moda2",
diff --git a/vllm_omni/model_executor/stage_input_processors/mammoth_moda2.py b/vllm_omni/model_executor/stage_input_processors/mammoth_moda2.py
index fab22b739a1..5972dfa025f 100644
--- a/vllm_omni/model_executor/stage_input_processors/mammoth_moda2.py
+++ b/vllm_omni/model_executor/stage_input_processors/mammoth_moda2.py
@@ -1,21 +1,12 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
-"""Stage input processor for MammothModa2 (AR -> DiT)."""
+"""Stage input processor for MammothModa2 (AR -> diffusion)."""
 
 from collections.abc import Mapping
 from typing import Any
 
-from vllm.inputs import TextPrompt
-
-from vllm_omni.inputs.data import OmniTokensPrompt
-
 
 def _as_dict(prompt: Any) -> dict[str, Any]:
-    """Coerce an original-stage prompt to a dict.
-
-    It may arrive as a dict, a NamedTuple/object, or a bare string depending on
-    the calling flow (the shared text_to_image example vs the bespoke script).
-    """
     if isinstance(prompt, dict):
         return prompt
     if hasattr(prompt, "_asdict"):
@@ -27,93 +18,73 @@ def _as_dict(prompt: Any) -> dict[str, Any]:
 
 def _coerce_dim(value: Any, default: int) -> int:
     try:
-        iv = int(value)
+        resolved = int(value)
     except (TypeError, ValueError):
         return default
-    return iv if iv > 0 else default
+    return resolved if resolved > 0 else default
 
 
-def ar2dit(
+def ar2diffusion(
     source_outputs: list[Any],
-    prompts: OmniTokensPrompt | TextPrompt | list[OmniTokensPrompt | TextPrompt] | None = None,
-    _requires_multimodal_data: bool = False,
-) -> list[OmniTokensPrompt]:
-    """Convert AR stage outputs to DiT stage inputs."""
-    ar_outputs = source_outputs
-
-    # The shared text_to_image example forwards a single prompt (not a list); normalize
-    # so a lone dict isn't iterated as its keys. Mirrors glm_image.ar2diffusion.
-    if not isinstance(prompts, list):
-        prompts = [prompts] if prompts is not None else [{}]
-
-    dit_inputs: list[OmniTokensPrompt] = []
-    for i, ar_output in enumerate(ar_outputs):
-        prompt_dict = _as_dict(prompts[i] if i < len(prompts) else {})
-        addi_info = prompt_dict.get("additional_information") or {}
-        mm_kwargs = prompt_dict.get("mm_processor_kwargs") or {}
-
-        # Image size: prefer mm_processor_kwargs target_h/target_w (set by the serving
-        # layer), fall back to additional_information, then a 1024 default.
-        image_height = _coerce_dim(
-            mm_kwargs.get("target_h"),
-            _coerce_dim((addi_info.get("image_height") or [None])[0], 1024),
+    prompt: Any | None = None,
+    requires_multimodal_data: bool = False,
+) -> dict[str, Any]:
+    del requires_multimodal_data
+    if len(source_outputs) != 1:
+        raise ValueError(
+            f"MammothModa2 request-mode diffusion expects exactly one AR output, got {len(source_outputs)}"
         )
-        image_width = _coerce_dim(
-            mm_kwargs.get("target_w"),
-            _coerce_dim((addi_info.get("image_width") or [None])[0], 1024),
-        )
-
-        # Sampling knobs arrive on the DiT stage via extra_body -> extra_args; these are
-        # defensive fallbacks (defaults mirror the former bespoke script's argparse).
-        text_guidance_scale = (addi_info.get("text_guidance_scale") or [9.0])[0]
-        cfg_range = addi_info.get("cfg_range") or [0.0, 1.0]
-        num_inference_steps = (addi_info.get("num_inference_steps") or [50])[0]
 
-        prompt_token_ids = ar_output.prompt_token_ids
-        # exclude the last token because it has no corresponding hidden state
-        completion_output = ar_output.outputs[0]
-        gen_token_ids = completion_output.cumulative_token_ids[:-1]
-        full_token_ids = prompt_token_ids + gen_token_ids
+    ar_output = source_outputs[0]
+    if isinstance(prompt, list):
+        prompt = prompt[0] if prompt else {}
+    prompt_dict = _as_dict(prompt)
+    additional = prompt_dict.get("additional_information") or {}
+    mm_kwargs = prompt_dict.get("mm_processor_kwargs") or {}
+    height = _coerce_dim(
+        mm_kwargs.get("target_h"),
+        _coerce_dim((additional.get("image_height") or [None])[0], 1024),
+    )
+    width = _coerce_dim(
+        mm_kwargs.get("target_w"),
+        _coerce_dim((additional.get("image_width") or [None])[0], 1024),
+    )
+
+    completion = ar_output.outputs[0]
+    generated_token_ids = list(completion.cumulative_token_ids[:-1])
+    prompt_token_ids = list(ar_output.prompt_token_ids)
+    full_token_ids = prompt_token_ids + generated_token_ids
+    multimodal_output = getattr(completion, "multimodal_output", None)
+    if not isinstance(multimodal_output, Mapping) or "latent" not in multimodal_output:
+        raise ValueError(
+            "MammothModa2 AR stage output is missing latent multimodal output; "
+            f"request_id={getattr(ar_output, 'request_id', None)}"
+        )
 
-        mm_output = getattr(completion_output, "multimodal_output", None)
-        if not isinstance(mm_output, Mapping) or "latent" not in mm_output:
-            raise ValueError(
-                "AR stage output missing latent multimodal output. "
-                f"request_id={getattr(ar_output, 'request_id', None)}, "
-                f"completion_has_mm={hasattr(completion_output, 'multimodal_output')}"
-            )
-        full_hidden_states = mm_output["latent"]
-        hidden_total = int(full_hidden_states.shape[0])
-        assert hidden_total == len(prompt_token_ids) + len(gen_token_ids), (
-            f"Hidden states length mismatch: expected {len(prompt_token_ids) + len(gen_token_ids)}, got {hidden_total}"
+    full_hidden_states = multimodal_output["latent"]
+    hidden_total = int(full_hidden_states.shape[0])
+    if hidden_total != len(full_token_ids):
+        raise ValueError(
+            "Hidden states length mismatch: "
+            f"expected {len(full_token_ids)}, got {hidden_total}; "
+            f"request_id={getattr(ar_output, 'request_id', None)}"
         )
 
-        # The text/image condition split is performed in the DiT pipeline, which sources
-        # the distinguishing token ids (gen_vocab_start_index, vision placeholder ids)
-        # from the model config. Pass through the raw AR hidden states + token ids and
-        # the question/answer boundary so the pipeline can reconstruct the masks.
-        additional_information = {
-            # The EngineCore payload serializer preserves bfloat16 as raw bytes.
-            # Keep the AR representation compact across the CPU/IPC boundary;
-            # the DiT selects its conditioning rows and casts them only when it
-            # consumes them.
+    return {
+        "prompt": "",
+        "height": height,
+        "width": width,
+        "additional_information": {
+            # Keep #7102's compact BF16/FP16 payload across the EngineCore
+            # boundary. The diffusion pipeline casts only after selecting the
+            # text/image condition rows.
             "full_hidden_states": full_hidden_states.contiguous(),
             "full_token_ids": full_token_ids,
-            "answer_start_index": [len(prompt_token_ids)],
-            "image_height": [int(image_height)],
-            "image_width": [int(image_width)],
-            "text_guidance_scale": [float(text_guidance_scale)],
-            "cfg_range": [float(cfg_range[0]), float(cfg_range[1])],
-            "num_inference_steps": [int(num_inference_steps)],
-        }
-
-        dit_inputs.append(
-            OmniTokensPrompt(
-                prompt_token_ids=[0],
-                additional_information=additional_information,
-                multi_modal_data=None,
-                mm_processor_kwargs=None,
-            )
-        )
-
-    return dit_inputs
+            "answer_start_index": len(prompt_token_ids),
+            **{
+                key: additional[key]
+                for key in ("text_guidance_scale", "num_inference_steps", "cfg_range")
+                if key in additional
+            },
+        },
+    }

From 4c7a98c26f6167a219b008263773c959a65ac0f2 Mon Sep 17 00:00:00 2001
From: Joshna-Medisetty <joshna.medisetty@intel.com>
Date: Fri, 18 Sep 2026 15:32:33 -0700
Subject: [PATCH 095/105] [XPU][CI] Drop the USTC PyPI mirror from the XPU
 image build (#7808)

Signed-off-by: Joshna Medisetty <joshna.medisetty@intel.com>
---
 docker/Dockerfile.xpu | 1 -
 1 file changed, 1 deletion(-)

diff --git a/docker/Dockerfile.xpu b/docker/Dockerfile.xpu
index 018bc4316ca..da7930ae2d5 100644
--- a/docker/Dockerfile.xpu
+++ b/docker/Dockerfile.xpu
@@ -40,7 +40,6 @@ ENV VLLM_OMNI_TARGET_DEVICE=xpu
 # Keep the upstream oneCCL packages paired with the XPU torch runtime.
 RUN --mount=type=cache,target=/root/.cache/uv \
     uv pip install --no-build-isolation \
-    --extra-index-url https://mirrors.ustc.edu.cn/pypi/simple/ \
     ".[dev]" && \
     uv pip uninstall triton && \
     uv pip install triton-xpu==3.7.2 --reinstall

From 232dbc82f8fcb6cb698860b0210b47d60a13ebdc Mon Sep 17 00:00:00 2001
From: andyluo7 <43718156+andyluo7@users.noreply.github.com>
Date: Fri, 18 Sep 2026 22:23:50 -0700
Subject: [PATCH 096/105] [CI/Build] Restrict ERNIE fused RoPE tests to NVIDIA
 CUDA (#7771)

Signed-off-by: andyluo7 <andy.luo@amd.com>
---
 .../test_ernie_image_fused_rope.py            | 20 +++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/tests/diffusion/models/ernie_image/test_ernie_image_fused_rope.py b/tests/diffusion/models/ernie_image/test_ernie_image_fused_rope.py
index bf3dce4f326..b73804433d1 100644
--- a/tests/diffusion/models/ernie_image/test_ernie_image_fused_rope.py
+++ b/tests/diffusion/models/ernie_image/test_ernie_image_fused_rope.py
@@ -5,9 +5,11 @@
 import torch
 from vllm.triton_utils import HAS_TRITON
 
+from tests.helpers.mark import hardware_test
 from vllm_omni.diffusion.models.ernie_image.ernie_image_transformer import _apply_rotary_emb
+from vllm_omni.platforms import current_omni_platform
 
-pytestmark = [pytest.mark.core_model, pytest.mark.cuda, pytest.mark.diffusion]
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion]
 
 
 @pytest.fixture(autouse=True)
@@ -35,7 +37,8 @@ def _inputs(shape: tuple[int, int, int, int]):
     return query, key, freqs_cos, freqs_sin
 
 
-@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.skipif(not current_omni_platform.is_cuda(), reason="NVIDIA CUDA required")
 @pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
 @pytest.mark.parametrize(
     "shape",
@@ -60,7 +63,8 @@ def test_fused_qk_rope_is_bit_exact(shape):
     assert torch.equal(actual_key, expected_key)
 
 
-@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.skipif(not current_omni_platform.is_cuda(), reason="NVIDIA CUDA required")
 @pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
 def test_launch_failure_disables_runtime_key(monkeypatch):
     from vllm_omni.diffusion.models.ernie_image import fused_rope
@@ -85,6 +89,7 @@ def failing_launch(*args):
     assert len(fused_rope._FAILED_KEYS) == 1
 
 
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
 def test_failed_runtime_key_cache_is_bounded():
     from vllm_omni.diffusion.models.ernie_image import fused_rope
 
@@ -96,7 +101,8 @@ def test_failed_runtime_key_cache_is_bounded():
     assert (fused_rope._FAILED_KEYS_MAX_SIZE,) in fused_rope._FAILED_KEYS
 
 
-@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.skipif(not current_omni_platform.is_cuda(), reason="NVIDIA CUDA required")
 @pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
 def test_compile_path_does_not_launch_fused_kernel(monkeypatch):
     from vllm_omni.diffusion.models.ernie_image import fused_rope
@@ -116,7 +122,8 @@ def unexpected_launch(*args):
         assert fused_rope.try_fused_qk_rotary_emb(query, key, freqs_cos, freqs_sin) is None
 
 
-@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.skipif(not current_omni_platform.is_cuda(), reason="NVIDIA CUDA required")
 @pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
 @pytest.mark.parametrize("requires_grad_input", ["query", "key", "cos", "sin"])
 def test_gradient_inputs_do_not_launch_fused_kernel(monkeypatch, requires_grad_input):
@@ -142,7 +149,8 @@ def unexpected_launch(*args):
     )
 
 
-@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA required")
+@hardware_test(res={"cuda": "L4"}, num_cards=1)
+@pytest.mark.skipif(not current_omni_platform.is_cuda(), reason="NVIDIA CUDA required")
 @pytest.mark.skipif(not HAS_TRITON, reason="Triton required")
 def test_mismatched_key_dtype_or_device_does_not_launch(monkeypatch):
     from vllm_omni.diffusion.models.ernie_image import fused_rope

From ea84055507971c4a7f31d4efdba1488f50c264ae Mon Sep 17 00:00:00 2001
From: Anjie Hou <149605198+specture724@users.noreply.github.com>
Date: Sat, 19 Sep 2026 19:05:18 +0800
Subject: [PATCH 097/105] [Refactor][Diffusion] Resolve distributed layerwise
 topology in the plan (#7326)

Signed-off-by: specture724 <specture724@gmail.com>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Hongsheng Liu <liuhongsheng4@huawei.com>
---
 docs/design/feature/offloader/README.md       |  20 +-
 .../models/magi2/test_native_dlo_allgather.py |   9 +-
 .../test_distributed_layerwise_backend.py     | 208 +++++++++++++++++-
 .../distributed_layerwise_backend.py          | 132 +++--------
 .../diffusion/offloader/plan_resolver.py      | 121 +++++++++-
 5 files changed, 361 insertions(+), 129 deletions(-)

diff --git a/docs/design/feature/offloader/README.md b/docs/design/feature/offloader/README.md
index 0ec81f3b5f7..52797b68c19 100644
--- a/docs/design/feature/offloader/README.md
+++ b/docs/design/feature/offloader/README.md
@@ -84,10 +84,22 @@ Block topology comes from the pipeline `OffloadPlan` first: `block_attrs` maps
 each DiT path to its ordered block containers, `encoder_block_attrs` declares
 streamable encoder stacks, `on_demand_component_paths` marks pipeline-managed
 residency, `resident_dit_paths` marks the DiTs that may hold resident layers,
-and `encoder_dlo_weight_replication` marks the encoders whose loader-produced
-weights are safe for AllGather. DiTs absent from the plan fall back to
-`_layerwise_offload_blocks_attrs` (including the deprecated singular-name
-compatibility path).
+`encoder_dlo_weight_replication` marks the encoders whose loader-produced
+weights are safe for AllGather, and `offload_submodules` maps a DiT submodule
+that owns its residency to its own block container. DiTs absent from the plan
+fall back to `_layerwise_offload_blocks_attrs` (including the deprecated
+singular-name compatibility path).
+
+An undeclared DiT submodule joins the plan only when it is large enough that
+keeping it resident would defeat streaming; its block container is then found
+by scanning well-known attribute names, which warns once per submodule class.
+Size is computed from parameter shapes and dtypes, including meta parameters,
+so resolving before mmap loading preserves the same residency decision.
+Block ownership validation includes nested components: a block shared with a
+parent, sibling, or encoder is rejected before any hooks or storage are changed.
+A submodule with no block container must implement the `load_to_device` /
+`offload_to_cpu` lifecycle, and the resolver rejects it before any component of
+the pipeline is placed or hooked.
 
 The resolver is pure: it moves no tensor, installs no hook, writes no module
 attribute, and reads no process group — multi-rank facts come from
diff --git a/tests/diffusion/models/magi2/test_native_dlo_allgather.py b/tests/diffusion/models/magi2/test_native_dlo_allgather.py
index 9bea5dc30e2..5cfaabf3fda 100644
--- a/tests/diffusion/models/magi2/test_native_dlo_allgather.py
+++ b/tests/diffusion/models/magi2/test_native_dlo_allgather.py
@@ -36,6 +36,7 @@
     DistributedLayerwiseOffloadBackend,
     DistributedLayerwiseOffloadHook,
 )
+from vllm_omni.diffusion.offloader.plan_resolver import ResolvedComponent
 
 
 @dataclass(frozen=True)
@@ -46,12 +47,6 @@ class _WeightSourceStub:
     prefix: str
 
 
-@dataclass(frozen=True)
-class _PipelineModulesStub:
-    dits: list[nn.Module]
-    dit_names: list[str]
-
-
 _WORLD_SIZE = 4
 pytestmark = [pytest.mark.diffusion, pytest.mark.cpu, pytest.mark.core_model]
 
@@ -189,7 +184,7 @@ def _load_mmap_transform_and_reconstruct(
         backend._mmap_transforms_by_tensor_id = {}
         backend._load_weights_via_mmap(
             pipeline,
-            _PipelineModulesStub(dits=[target], dit_names=["transformer"]),
+            (ResolvedComponent(path="transformer", module=target, selected=True),),
             plan_result.plan,
         )
 
diff --git a/tests/diffusion/offloader/test_distributed_layerwise_backend.py b/tests/diffusion/offloader/test_distributed_layerwise_backend.py
index c246394342e..fed60be1f5c 100644
--- a/tests/diffusion/offloader/test_distributed_layerwise_backend.py
+++ b/tests/diffusion/offloader/test_distributed_layerwise_backend.py
@@ -32,6 +32,7 @@
     TensorBinding,
     build_checkpoint_mmap_plan,
 )
+from vllm_omni.diffusion.offloader import plan_resolver
 from vllm_omni.diffusion.offloader.base import OffloadConfig, OffloadStrategy
 from vllm_omni.diffusion.offloader.block_discovery import (
     get_blocks_attr_names,
@@ -52,7 +53,7 @@
     OffloadPlan,
     get_offload_plan,
 )
-from vllm_omni.diffusion.offloader.plan_resolver import resolve_offload_plan
+from vllm_omni.diffusion.offloader.plan_resolver import ResolvedComponent, resolve_offload_plan
 from vllm_omni.diffusion.offloader.startup import OffloadStartupState, attach_offload_startup_state
 from vllm_omni.host_weight_runtime import MappedHostRegion
 from vllm_omni.platforms import current_omni_platform
@@ -1235,6 +1236,78 @@ def _remap_ckpt_key(key: str) -> str:
 
 
 class TestMmapWeightLoading:
+    @pytest.mark.parametrize("initial_device", ["cpu", "meta"])
+    @pytest.mark.parametrize("use_allgather", [False, True])
+    def test_mmap_keeps_undeclared_nested_blocks_streamed(
+        self, tmp_path, patched_offload_runtime, monkeypatch, initial_device, use_allgather
+    ):
+        class Refiner(nn.Module):
+            def __init__(self):
+                super().__init__()
+                self.layers = nn.ModuleList([nn.Linear(2, 2), nn.Linear(2, 2)])
+
+            def forward(self, x):
+                for block in self.layers:
+                    x = block(x)
+                return x
+
+        class Transformer(nn.Module):
+            _layerwise_offload_blocks_attrs = ["blocks"]
+
+            def __init__(self):
+                super().__init__()
+                self.blocks = nn.ModuleList([nn.Linear(2, 2), nn.Linear(2, 2)])
+                self.refiner = Refiner()
+
+            def forward(self, x):
+                x = self.refiner(x)
+                for block in self.blocks:
+                    x = block(x)
+                return x
+
+        pipeline = nn.Module()
+        pipeline.transformer = Transformer()
+        weights = {name: param.detach().clone() for name, param in pipeline.named_parameters()}
+        x = torch.randn(1, 2)
+        with torch.no_grad():
+            expected = pipeline.transformer(x)
+        checkpoint_file = tmp_path / "model.safetensors"
+        save_file(weights, str(checkpoint_file))
+        # Exercise the real mmap path with a small model instead of allocating
+        # the 1 GiB needed to trigger the production compatibility threshold.
+        monkeypatch.setattr(plan_resolver, "_NESTED_OFFLOAD_THRESHOLD_MB", 0)
+        if initial_device == "meta":
+            pipeline.transformer.to_empty(device="meta")
+        plan = HostWeightPlan(
+            backing_kind="checkpoint_mmap",
+            bindings={name: TensorBinding(checkpoint_key=name, file_path=str(checkpoint_file)) for name in weights},
+        )
+        backend = DistributedLayerwiseOffloadBackend(
+            OffloadConfig(
+                strategy=OffloadStrategy.DISTRIBUTED_LAYER_WISE,
+                pin_cpu_memory=False,
+                dlo_use_allgather=use_allgather,
+            ),
+            torch.device("cpu"),
+            host_weight_plan=plan,
+        )
+
+        for _ in range(2):
+            try:
+                backend.enable(pipeline)
+                assert len(backend._all_hook_groups) == 2
+                with torch.no_grad():
+                    torch.testing.assert_close(pipeline.transformer(x), expected)
+            finally:
+                backend.disable()
+            for name, parameter in pipeline.named_parameters():
+                assert not parameter.is_meta
+                torch.testing.assert_close(parameter, weights[name])
+            for module in pipeline.modules():
+                registry = getattr(module, "_hook_registry", None)
+                if registry is not None:
+                    assert registry.get_hook("distributed_layerwise_offload") is None
+
     def test_runs_model_post_load_hook(self, tmp_path, patched_offload_runtime):
         pipeline = _MmapPostLoadPipeline()
         weights = {name: torch.ones(param.shape, dtype=torch.bfloat16) for name, param in pipeline.named_parameters()}
@@ -1250,10 +1323,7 @@ def test_runs_model_post_load_hook(self, tmp_path, patched_offload_runtime):
             ),
             torch.device("cpu"),
         )
-        modules = SimpleNamespace(
-            dits=[pipeline.transformer],
-            dit_names=["transformer"],
-        )
+        dits = (ResolvedComponent(path="transformer", module=pipeline.transformer, selected=True),)
         plan = HostWeightPlan(
             backing_kind="checkpoint_mmap",
             bindings={
@@ -1265,7 +1335,7 @@ def test_runs_model_post_load_hook(self, tmp_path, patched_offload_runtime):
             },
         )
 
-        backend._load_weights_via_mmap(pipeline, modules, plan)
+        backend._load_weights_via_mmap(pipeline, dits, plan)
 
         assert pipeline.transformer.post_load_calls == 1
         assert pipeline.transformer.time_embedder.weight.dtype == torch.float32
@@ -1717,6 +1787,128 @@ def __init__(self):
         for name, parameter in pipeline.named_parameters():
             torch.testing.assert_close(parameter, expected_parameters[name])
 
+    @pytest.mark.parametrize("shared_owner", ["parent", "encoder", "sibling"])
+    def test_nested_duplicate_ownership_is_rejected_before_any_hook(self, patched_offload_runtime, shared_owner):
+        class Pipeline(nn.Module):
+            _offload_plan = OffloadPlan(
+                offload_submodules={"refiner": "blocks", "other_refiner": "blocks"},
+                encoder_block_attrs={"text_encoder": ("encoder.block",)},
+            )
+
+            def __init__(self):
+                super().__init__()
+                self.transformer = _SingleBlockModel(num_blocks=2)
+                self.transformer.refiner = _SingleBlockModel(num_blocks=2)
+                self.transformer.other_refiner = _SingleBlockModel(num_blocks=2)
+                self.text_encoder = _PlainEncoder()
+                owners = {
+                    "parent": self.transformer.blocks,
+                    "encoder": self.text_encoder.encoder.block,
+                    "sibling": self.transformer.other_refiner.blocks,
+                }
+                self.transformer.refiner.blocks = owners[shared_owner]
+
+        pipeline = Pipeline()
+        backend = DistributedLayerwiseOffloadBackend(
+            OffloadConfig(strategy=OffloadStrategy.DISTRIBUTED_LAYER_WISE, pin_cpu_memory=False),
+            torch.device("cpu"),
+        )
+        storage = {name: parameter.data_ptr() for name, parameter in pipeline.named_parameters()}
+        try:
+            with pytest.raises(ValueError, match="claimed by both"):
+                backend.enable(pipeline)
+            assert not backend.enabled
+            assert not backend._all_hook_groups
+            assert {name: parameter.data_ptr() for name, parameter in pipeline.named_parameters()} == storage
+            assert not getattr(pipeline.text_encoder, "_omni_layerwise_enabled", False)
+            for module in pipeline.modules():
+                assert getattr(module, "_hook_registry", None) is None
+        finally:
+            backend.disable()
+
+    def test_unstageable_submodule_is_rejected_before_any_hook(self, patched_offload_runtime):
+        """Plan-dependent rejection happens before earlier components are hooked."""
+
+        class Pipeline(nn.Module):
+            _offload_plan = OffloadPlan(
+                offload_submodules={"refiner": "missing"},
+                encoder_component_types={"text_encoder": "text_encoder"},
+                encoder_block_attrs={"text_encoder": ("encoder.block",)},
+            )
+
+            def __init__(self):
+                super().__init__()
+                self.transformer = _SingleBlockModel(num_blocks=2)
+                # Declared for submodule offload but without a block list or the
+                # load_to_device/offload_to_cpu lifecycle.
+                self.transformer.refiner = nn.Linear(2, 2)
+                self.text_encoder = _PlainEncoder()
+
+        pipeline = Pipeline()
+        backend = DistributedLayerwiseOffloadBackend(
+            OffloadConfig(strategy=OffloadStrategy.DISTRIBUTED_LAYER_WISE, pin_cpu_memory=False),
+            torch.device("cpu"),
+        )
+
+        # Storage identity proves the encoder was never staged and rolled back.
+        encoder_storage = [block.weight.data_ptr() for block in pipeline.text_encoder.encoder.block]
+
+        with pytest.raises(ValueError, match="must implement load_to_device"):
+            backend.enable(pipeline)
+
+        assert not backend.enabled
+        assert [block.weight.data_ptr() for block in pipeline.text_encoder.encoder.block] == encoder_storage
+        assert not getattr(pipeline.text_encoder, "_omni_layerwise_enabled", False)
+        for block in pipeline.transformer.blocks:
+            assert getattr(block, "_hook_registry", None) is None
+
+    def test_undeclared_submodule_block_scan_warns(self, patched_offload_runtime, monkeypatch):
+        """The size-triggered attribute scan still works and is deprecated."""
+
+        class Refiner(nn.Module):
+            def __init__(self):
+                super().__init__()
+                self.layers = nn.ModuleList([nn.Linear(2, 2), nn.Linear(2, 2)])
+
+        class Transformer(nn.Module):
+            _layerwise_offload_blocks_attrs = ["blocks"]
+
+            def __init__(self):
+                super().__init__()
+                self.blocks = nn.ModuleList([nn.Linear(2, 2), nn.Linear(2, 2)])
+                self.refiner = Refiner()
+
+        class Pipeline(nn.Module):
+            def __init__(self):
+                super().__init__()
+                self.transformer = Transformer()
+
+        warnings: list[str] = []
+
+        class _Recorder:
+            def warning(self, message, *args):
+                warnings.append(message % args if args else message)
+
+            def __getattr__(self, _name):
+                return lambda *args, **kwargs: None
+
+        monkeypatch.setattr(plan_resolver, "logger", _Recorder())
+        monkeypatch.setattr(plan_resolver, "_NESTED_OFFLOAD_THRESHOLD_MB", 0)
+        plan_resolver._warn_nested_block_scan.cache_clear()
+        plan_resolver._warn_legacy_discovery.cache_clear()
+        pipeline = Pipeline()
+        backend = DistributedLayerwiseOffloadBackend(
+            OffloadConfig(strategy=OffloadStrategy.DISTRIBUTED_LAYER_WISE, pin_cpu_memory=False),
+            torch.device("cpu"),
+        )
+
+        backend.enable(pipeline)
+
+        assert len(backend._all_hook_groups) == 2
+        assert sum("OffloadPlan.offload_submodules" in message for message in warnings) == 1
+
+        backend.disable()
+
 
 class TestMmapValidation:
     """Tests for loader preflight and backend plan realization."""
@@ -2101,7 +2293,7 @@ def _remap_ckpt_key(key):
             ),
             torch.device("cpu"),
         )
-        modules = SimpleNamespace(dits=[pipeline.transformer], dit_names=["transformer"])
+        dits = (ResolvedComponent(path="transformer", module=pipeline.transformer, selected=True),)
         result = build_checkpoint_mmap_plan(
             pipeline,
             dit_modules=(("transformer", pipeline.transformer),),
@@ -2113,7 +2305,7 @@ def _remap_ckpt_key(key):
         )
 
         assert result.plan is not None
-        backend._load_weights_via_mmap(pipeline, modules, result.plan)
+        backend._load_weights_via_mmap(pipeline, dits, result.plan)
         assert pipeline.transformer.validate_called, "validate_loaded_weights should be called"
 
 
diff --git a/vllm_omni/diffusion/offloader/distributed_layerwise_backend.py b/vllm_omni/diffusion/offloader/distributed_layerwise_backend.py
index 299ec3d3a9f..e79d1f197a6 100644
--- a/vllm_omni/diffusion/offloader/distributed_layerwise_backend.py
+++ b/vllm_omni/diffusion/offloader/distributed_layerwise_backend.py
@@ -53,8 +53,7 @@
     HostRegistrationError,
     register_host_mappings,
 )
-from .offload_plan import OffloadPlan
-from .plan_resolver import ResolvedComponent, resolve_offload_plan
+from .plan_resolver import BlockStack, ResolvedComponent, resolve_offload_plan
 from .tensor_utils import (
     clear_block_storage,
     clear_tensor_storage,
@@ -111,7 +110,6 @@ def _forget_active_hwr_registration(
 # use layerwise offload (streaming hooks) or be moved to GPU as a resident
 # module.  Submodules larger than this are offloaded to save HBM; smaller
 # ones stay resident for lower latency.
-_ON_DEMAND_THRESHOLD_MB = 1024
 
 
 class DistributedLayerwiseOffloadHook(ModelHook):
@@ -1182,7 +1180,7 @@ def _release_registered_mmap(self) -> None:
     def _load_weights_via_mmap(
         self,
         pipeline: nn.Module,
-        modules,
+        dits: tuple[ResolvedComponent, ...],
         plan: HostWeightPlan,
     ) -> None:
         """Load DiT checkpoint tensors as file-backed safetensors views.
@@ -1226,7 +1224,7 @@ def _load_weights_via_mmap(
         # converts the child's buffers too.  So we must save ALL buffers
         # from ALL DiT modules BEFORE any to_empty call.
         saved_buffers: dict[int, dict[str, torch.Tensor]] = {}
-        for dit_module in modules.dits:
+        for dit_module in (component.module for component in dits):
             bufs: dict[str, torch.Tensor] = {}
             for name, buf in dit_module.named_buffers():
                 # Check if this buffer is non-persistent on its OWNING module
@@ -1246,7 +1244,7 @@ def _load_weights_via_mmap(
         # Skip modules that are already meta (happens when a parent DiT
         # module contains a child DiT module — to_empty on the parent
         # already converted the child).
-        for dit_module in modules.dits:
+        for dit_module in (component.module for component in dits):
             if any(p.is_meta for p in dit_module.parameters()):
                 logger.info(
                     "%s already on meta device (skipping to_empty, %d buffers saved)",
@@ -1307,7 +1305,7 @@ def _load_weights_via_mmap(
         # assigning checkpoint tensors. The mmap path bypasses that loader, so
         # preserve the same lifecycle for transforms such as Cosmos3's fp32
         # timestep embedder.
-        for dit_name, dit_module in zip(modules.dit_names, modules.dits):
+        for dit_name, dit_module in ((component.path, component.module) for component in dits):
             # Restore non-persistent buffers before post-load hooks and strict
             # validation. They are constructor-derived and intentionally have
             # no checkpoint binding.
@@ -1352,7 +1350,7 @@ def _load_weights_via_mmap(
             self._mmap_transforms_by_tensor_id[id(target)] = binding.transform
 
         remaining_meta: list[str] = []
-        for dit_name, dit_module in zip(modules.dit_names, modules.dits):
+        for dit_name, dit_module in ((component.path, component.module) for component in dits):
             remaining_meta.extend(
                 f"{dit_name}.{name}" for name, tensor in dit_module.named_parameters() if tensor.is_meta
             )
@@ -1517,73 +1515,26 @@ def _try_layerwise_offload_encoder(self, component: ResolvedComponent) -> bool:
         )
         return True
 
-    def _try_layerwise_offload_submodule(self, module: nn.Module, name: str, plan: OffloadPlan | None = None) -> bool:
-        """Try to apply layerwise offload to a large submodule's blocks.
-        Resolution order:
-        1. OffloadPlan.offload_submodules (declarative, if plan is provided)
-        2. Heuristic search for common block-list attributes
-
-        Returns True if layerwise offload was applied, False otherwise.
-        """
-        from operator import attrgetter
-
-        blocks = None
-        blocks_attr = None
-
-        # 1. Check OffloadPlan first (declarative — no guessing)
-        if plan is not None and name in plan.offload_submodules:
-            attr_name = plan.offload_submodules[name]
-            try:
-                candidate = attrgetter(attr_name)(module)
-                if isinstance(candidate, nn.ModuleList) and len(candidate) > 1:
-                    blocks = candidate
-                    blocks_attr = attr_name
-            except AttributeError:
-                logger.warning(
-                    "OffloadPlan declared block attr '%s' for submodule '%s' "
-                    "but attribute not found — falling back to heuristic",
-                    attr_name,
-                    name,
-                )
-
-        # 2. Fallback: heuristic search
-        if blocks is None:
-            for attr_name in ("layers", "blocks", "h", "model.layers"):
-                try:
-                    candidate = attrgetter(attr_name)(module)
-                except AttributeError:
-                    continue
-                if isinstance(candidate, nn.ModuleList) and len(candidate) > 1:
-                    blocks = candidate
-                    blocks_attr = attr_name
-                    break
-
-        if blocks is None:
-            return False
-
+    def _offload_nested_submodule(self, component: ResolvedComponent) -> None:
+        """Stream one resolved DiT submodule through its own hook ring."""
+        stack = component.stacks[0]
         logger.info(
             "Distributed layerwise offload for submodule '%s.%s' (%d blocks, %.0f MB total, group_size=%d)",
-            name,
-            blocks_attr,
-            len(blocks),
-            sum(p.nelement() * p.element_size() for p in module.parameters()) / 1048576,
+            component.path,
+            stack.attrs[0],
+            len(stack.blocks),
+            sum(p.nelement() * p.element_size() for p in component.module.parameters()) / 1048576,
             self._component_transport(DIT_COMPONENT)[1],
         )
-
-        # Move non-block parts of the submodule to GPU (small: embeddings, norms)
-        for child_name, child in module.named_children():
-            if child_name != blocks_attr:
-                child.to(self.device)
-
-        self._install_hook_group(blocks, DIT_COMPONENT, use_dit_mmap=True)
-        return True
+        # Keep the submodule's own non-block state resident by block identity,
+        # so an attribute aliasing a streamed block is not placed with it.
+        move_non_block_state_to_device(component.module, (stack.blocks,), self.device)
+        self._install_hook_group(stack.blocks, DIT_COMPONENT, use_dit_mmap=True)
 
     def _prepare_dit_non_block_modules(
         self,
-        dit_module: nn.Module,
-        blocks_attr_names: list[str],
-        all_dit_modules: set[int],
-        plan: OffloadPlan | None,
+        component: ResolvedComponent,
+        stack: BlockStack,
     ) -> None:
         """Place or hook the DiT parts that are outside its repeated blocks.
 
@@ -1591,28 +1542,23 @@ def _prepare_dit_non_block_modules(
         an all-resident stage skips placement for modules such as H3's token
         refiner and enters the forward pass with CPU or meta tensors.
         """
+        dit_module = component.module
+        nested = {child.path.rsplit(".", 1)[-1]: child for child in component.children}
         for name, module in dit_module.named_children():
-            if name in blocks_attr_names:
+            if name in stack.attrs:
                 logger.debug("Skipped blocks module %s", name)
                 continue
 
-            module_mb = (
-                sum(
-                    param.nelement() * param.element_size() if not getattr(param, "is_meta", False) else 0
-                    for param in module.parameters()
-                )
-                / 1048576
-            )
-            explicitly_planned = plan is not None and name in plan.offload_submodules
-            if explicitly_planned or module_mb > _ON_DEMAND_THRESHOLD_MB:
-                if id(module) in all_dit_modules:
+            child = nested.get(name)
+            if child is not None:
+                if not child.selected:
                     logger.info("Submodule '%s' is already a DiT module, skipping layerwise offload", name)
-                elif self._try_layerwise_offload_submodule(module, name, plan):
-                    pass
+                elif child.stacks:
+                    self._offload_nested_submodule(child)
                 else:
                     prepare_component(
-                        module,
-                        name,
+                        child.module,
+                        child.path,
                         device=self.device,
                         stage_on_demand=True,
                         blockwise=False,
@@ -1715,7 +1661,7 @@ def _enable(self, pipeline: nn.Module) -> None:
             elif host_weight_plan.backing_kind == "checkpoint_mmap":
                 self._load_weights_via_mmap(
                     pipeline,
-                    resolved.modules,
+                    resolved.dits,
                     host_weight_plan,
                 )
             else:
@@ -1750,16 +1696,12 @@ def _enable(self, pipeline: nn.Module) -> None:
             enable_encoder_blocks=self._try_layerwise_offload_encoder,
         )
 
-        if self.config.offloads(DIT_COMPONENT):
+        if any(component.selected for component in resolved.dits):
             logger.info(
                 "Applying distributed layer-wise offloading on %s",
                 [component.path for component in resolved.dits],
             )
 
-        # Collect all DiT module objects to detect submodules that are
-        # already handled as a separate DiT module (avoids duplicate hooks).
-        all_dit_modules = set(id(component.module) for component in resolved.dits)
-
         # Apply hooks for each DiT module
         for component, stack in iter_streamable_dits(resolved, self.device):
             streaming = list(stack.streaming)
@@ -1772,12 +1714,7 @@ def _enable(self, pipeline: nn.Module) -> None:
                     len(streaming),
                 )
 
-            self._prepare_dit_non_block_modules(
-                component.module,
-                list(stack.attrs),
-                all_dit_modules,
-                resolved.declaration,
-            )
+            self._prepare_dit_non_block_modules(component, stack)
 
             if not streaming:
                 logger.info("All blocks for %s are resident; no streaming hooks required", component.path)
@@ -1804,11 +1741,6 @@ def _enable(self, pipeline: nn.Module) -> None:
             self.enabled = bool(self._resident_blocks or self._encoder_modules or self._staged_components)
             if self._using_mmap and not self.enabled:
                 self._release_mmap_handles()
-            if not self.enabled and not self.config.offloads(DIT_COMPONENT):
-                raise ValueError(
-                    "None of the selected distributed layerwise offload components have "
-                    "a model-declared streamable or on-demand plan"
-                )
             return
 
         # Unified allocation: 2 shared output buffers + 2 shared shard buffers
diff --git a/vllm_omni/diffusion/offloader/plan_resolver.py b/vllm_omni/diffusion/offloader/plan_resolver.py
index 08527318f76..ca32f6d3f4a 100644
--- a/vllm_omni/diffusion/offloader/plan_resolver.py
+++ b/vllm_omni/diffusion/offloader/plan_resolver.py
@@ -17,6 +17,7 @@
 
 from dataclasses import dataclass
 from functools import cache
+from operator import attrgetter
 from typing import TYPE_CHECKING
 
 from torch import nn
@@ -27,7 +28,7 @@
 from .block_discovery import get_blocks_from_dit
 from .component_utils import get_encoder_block_groups, validate_on_demand_component
 from .config import DIT_COMPONENT, TEXT_ENCODER_COMPONENT, OffloadStrategy
-from .module_collector import ModuleDiscovery, PipelineModules
+from .module_collector import ModuleDiscovery
 from .offload_plan import OffloadPlan, get_offload_plan
 
 if TYPE_CHECKING:
@@ -76,6 +77,9 @@ class ResolvedComponent:
     selected: bool
     stacks: tuple[BlockStack, ...] = ()
     on_demand: bool = False
+    # Submodules of a DiT that are large enough to own their residency instead
+    # of staying resident with the rest of its non-block state.
+    children: tuple[ResolvedComponent, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -86,11 +90,6 @@ class ResolvedOffloadPlan:
     encoders: tuple[ResolvedComponent, ...]
     vaes: tuple[ResolvedComponent, ...]
     residents: tuple[ResolvedComponent, ...]
-    # Raw discovery output and the model declaration remain reachable for the
-    # loader-owned mmap path and for DLO's nested-submodule staging, which
-    # still interpret topology themselves.
-    modules: PipelineModules
-    declaration: OffloadPlan | None = None
     # Ordinary layerwise offload turns a legacy selection it cannot serve into
     # a complete no-op, placement included. Distributed layerwise offload warns
     # and keeps preparing its other components instead, so this stays scoped to
@@ -102,6 +101,22 @@ def components(self) -> tuple[ResolvedComponent, ...]:
         return self.dits + self.encoders + self.vaes + self.residents
 
 
+# A DiT submodule this large owns its residency even when no plan declares it.
+_NESTED_OFFLOAD_THRESHOLD_MB = 1024
+_NESTED_BLOCK_ATTRS = ("layers", "blocks", "h", "model.layers")
+
+
+@cache
+def _warn_nested_block_scan(module_class: str, attr: str) -> None:
+    """Warn once per class that a nested block list was found by guessing."""
+    logger.warning(
+        "%s block list was discovered as %r by scanning well-known attribute names. "
+        "Declare it in OffloadPlan.offload_submodules; the attribute scan is deprecated.",
+        module_class,
+        attr,
+    )
+
+
 @cache
 def _warn_legacy_discovery(pipeline_class: str) -> None:
     """Warn once per pipeline class that component discovery guessed.
@@ -117,6 +132,77 @@ def _warn_legacy_discovery(pipeline_class: str) -> None:
     )
 
 
+def _nested_block_stack(module: nn.Module, declared_attr: str | None) -> BlockStack | None:
+    """Resolve one DiT submodule's own block ring, if it has one."""
+    candidates = (declared_attr,) if declared_attr is not None else _NESTED_BLOCK_ATTRS
+    for attr in candidates:
+        try:
+            blocks = attrgetter(attr)(module)
+        except AttributeError:
+            continue
+        if isinstance(blocks, nn.ModuleList) and len(blocks) > 1:
+            if declared_attr is None:
+                _warn_nested_block_scan(type(module).__name__, attr)
+            return BlockStack(attrs=(attr,), blocks=tuple(blocks))
+    if declared_attr is not None:
+        logger.warning(
+            "OffloadPlan declared block attr %r for submodule %s but it is not a streamable block list",
+            declared_attr,
+            type(module).__name__,
+        )
+    return None
+
+
+def _resolve_dit_children(
+    dit_module: nn.Module,
+    dit_path: str,
+    stack: BlockStack,
+    declaration: OffloadPlan | None,
+    dit_module_ids: set[int],
+) -> tuple[ResolvedComponent, ...]:
+    """Resolve the DiT submodules that own their residency.
+
+    A submodule qualifies when the model declares it or when it is large enough
+    that keeping it resident would defeat streaming. Submodules that are
+    themselves discovered DiTs are left to their own component.
+    """
+    children: list[ResolvedComponent] = []
+    for name, module in dit_module.named_children():
+        if name in stack.attrs:
+            continue
+        declared_attr = None if declaration is None else declaration.offload_submodules.get(name)
+        if declared_attr is None and _module_size_mb(module) <= _NESTED_OFFLOAD_THRESHOLD_MB:
+            continue
+        path = f"{dit_path}.{name}"
+        if id(module) in dit_module_ids:
+            # Its own component owns this submodule; the parent must not place it.
+            children.append(ResolvedComponent(path=path, module=module, selected=False))
+            continue
+        nested_stack = _nested_block_stack(module, declared_attr)
+        if nested_stack is None:
+            # Without its own ring the submodule needs the pipeline lifecycle.
+            validate_on_demand_component(module, path)
+        children.append(
+            ResolvedComponent(
+                path=path,
+                module=module,
+                selected=True,
+                stacks=() if nested_stack is None else (nested_stack,),
+                on_demand=nested_stack is None,
+            )
+        )
+    return tuple(children)
+
+
+def _module_size_mb(module: nn.Module) -> float:
+    """Expected parameter bytes in MiB, including not-yet-loaded meta tensors.
+
+    Resolution precedes mmap materialization, so residency must depend on the
+    tensor metadata rather than whether the loader has allocated storage yet.
+    """
+    return sum(parameter.nelement() * parameter.element_size() for parameter in module.parameters()) / 1048576
+
+
 def _resolve_dit_stacks(
     module: nn.Module,
     path: str,
@@ -253,11 +339,25 @@ def resolve_offload_plan(pipeline: nn.Module, config: OffloadConfig) -> Resolved
     vaes: list[ResolvedComponent] = []
     residents: list[ResolvedComponent] = []
 
+    dit_module_ids = {id(module) for module in modules.dits}
     for path, module in zip(modules.dit_names, modules.dits):
         stacks: tuple[BlockStack, ...] = ()
+        children: tuple[ResolvedComponent, ...] = ()
         if dit_selected and layerwise:
             stacks = _resolve_dit_stacks(module, path, declaration, config, explicit=explicit)
-        dits.append(ResolvedComponent(path=path, module=module, selected=dit_selected, stacks=stacks))
+            # Only distributed layerwise offload streams or stages submodules;
+            # the ordinary backend keeps all non-block state resident.
+            if stacks and config.strategy is OffloadStrategy.DISTRIBUTED_LAYER_WISE:
+                children = _resolve_dit_children(module, path, stacks[0], declaration, dit_module_ids)
+        dits.append(
+            ResolvedComponent(
+                path=path,
+                module=module,
+                selected=dit_selected,
+                stacks=stacks,
+                children=children,
+            )
+        )
 
     for path, module in zip(modules.encoder_names, modules.encoders):
         selected = config.should_offload_encoder(path, declaration)
@@ -307,8 +407,6 @@ def resolve_offload_plan(pipeline: nn.Module, config: OffloadConfig) -> Resolved
         encoders=tuple(encoders),
         vaes=tuple(vaes),
         residents=tuple(residents),
-        modules=modules,
-        declaration=declaration,
         skip_reason=(
             "No DiT/transformer modules found for selected DiT layerwise offload"
             if config.strategy is OffloadStrategy.LAYER_WISE and dit_selected and not dits
@@ -322,7 +420,10 @@ def resolve_offload_plan(pipeline: nn.Module, config: OffloadConfig) -> Resolved
 def _validate_unique_ownership(resolved: ResolvedOffloadPlan) -> None:
     """Reject topologies where two components would hook the same blocks."""
     owner_by_block: dict[int, str] = {}
-    for component in resolved.components:
+    pending = list(reversed(resolved.components))
+    while pending:
+        component = pending.pop()
+        pending.extend(reversed(component.children))
         for block in (block for stack in component.stacks for block in stack.blocks):
             owner = owner_by_block.setdefault(id(block), component.path)
             if owner != component.path:

From 470ec60848fa98e030298706cceff88ae8f691a8 Mon Sep 17 00:00:00 2001
From: Zheng Wengang <zwg0606@gmail.com>
Date: Sat, 19 Sep 2026 14:23:59 +0100
Subject: [PATCH 098/105] [Core] Refactor omni prefix cache into
 Manager/Controller (#6654)

Signed-off-by: ZhengWG <zwg0606@gmail.com>
Co-authored-by: amy-why-3459 <wuhaiyan17@huawei.com>
Co-authored-by: Hongsheng Liu <liuhongsheng4@huawei.com>
---
 .../omni_async_output_materialization.md      |   25 +-
 docs/design/feature/prefix_caching.md         |  193 +-
 tests/core/test_prefix_cache.py               | 2636 +++++++++++------
 tests/core/test_prefix_cache_async_write.py   |  119 -
 tests/core/test_prefix_cache_runner_mixin.py  |  182 ++
 tests/e2e/online_serving/test_qwen3_omni.py   |  112 +-
 ...st_runner_assisted_unified_graph_static.py |    4 +-
 .../npu/test_npu_prefix_cache_wiring.py       |  158 +
 .../test_fa3_scheduler_metadata_size.py       |   12 +-
 tests/worker/test_gpu_ar_model_runner.py      |   41 +-
 vllm_omni/core/prefix_cache.py                |  737 -----
 vllm_omni/core/prefix_cache/__init__.py       |   58 +
 vllm_omni/core/prefix_cache/block_pool.py     |   84 +
 vllm_omni/core/prefix_cache/controller.py     |  976 ++++++
 vllm_omni/core/prefix_cache/group_view.py     |  208 ++
 vllm_omni/core/prefix_cache/interface.py      |  171 ++
 vllm_omni/core/prefix_cache/manager.py        | 1475 +++++++++
 vllm_omni/core/prefix_cache/runner_mixin.py   |  148 +
 vllm_omni/deploy/qwen3_tts.yaml               |   11 +-
 .../npu/worker/npu_ar_model_runner.py         |  124 +-
 .../npu/worker/npu_generation_model_runner.py |    1 +
 .../platforms/npu/worker/npu_model_runner.py  |   55 +-
 vllm_omni/worker/gpu_ar_model_runner.py       |  240 +-
 .../worker/gpu_generation_model_runner.py     |    1 +
 vllm_omni/worker/gpu_model_runner.py          |   52 +-
 25 files changed, 5692 insertions(+), 2131 deletions(-)
 delete mode 100644 tests/core/test_prefix_cache_async_write.py
 create mode 100644 tests/core/test_prefix_cache_runner_mixin.py
 create mode 100644 tests/platforms/npu/test_npu_prefix_cache_wiring.py
 delete mode 100644 vllm_omni/core/prefix_cache.py
 create mode 100644 vllm_omni/core/prefix_cache/__init__.py
 create mode 100644 vllm_omni/core/prefix_cache/block_pool.py
 create mode 100644 vllm_omni/core/prefix_cache/controller.py
 create mode 100644 vllm_omni/core/prefix_cache/group_view.py
 create mode 100644 vllm_omni/core/prefix_cache/interface.py
 create mode 100644 vllm_omni/core/prefix_cache/manager.py
 create mode 100644 vllm_omni/core/prefix_cache/runner_mixin.py

diff --git a/docs/design/feature/omni_async_output_materialization.md b/docs/design/feature/omni_async_output_materialization.md
index 50a2e7c5214..eff3024d8e2 100644
--- a/docs/design/feature/omni_async_output_materialization.md
+++ b/docs/design/feature/omni_async_output_materialization.md
@@ -318,18 +318,18 @@ The same behavior applies to the Base and VoiceDesign Qwen3-TTS checkpoints
 because they use the same Talker implementation.
 
 !!! warning
-    Do not pass `--no-async-chunk` or enable prefix caching when you want this
-    optimization. Either change causes the runner to fall back to synchronous
-    output construction. Enabling async chunk alone cannot activate the feature
-    for a model that has not opted into async Omni output.
+    Do not pass `--no-async-chunk` when you want this optimization. Disabling
+    async chunk causes the runner to fall back to synchronous output
+    construction. Enabling async chunk alone cannot activate the feature for a
+    model that has not opted into async Omni output.
 
 !!! note "Prefix cache compatibility"
-    Async Omni output materialization and Omni prefix caching cannot currently
-    run together. `_should_use_async_omni_output()` returns `False` whenever
-    `self.omni_prefix_cache` is present, so prefix caching selects synchronous
-    output materialization. Supporting both features requires snapshotting or
-    otherwise synchronizing prefix-cache merge and update state before the
-    background output path can consume it safely.
+    Prefix cache and async Omni output can run together. `save_outputs` returns
+    a `step_id`; the output builder later calls `materialize(sid, req_ids)` with
+    the save-time request list, which may be a step late relative to the live
+    `input_batch`. `_should_use_async_omni_output()` does not disable itself
+    when the cache is present. See
+    [Automatic Prefix Caching](prefix_caching.md#implementation).
 
 ## Compatibility and Fallbacks
 
@@ -341,10 +341,9 @@ runtime conditions hold:
 | AR async scheduling is enabled | The optimization relies on the scheduler advancing while the prior output is materialized |
 | `async_chunk` is enabled | The feature targets incremental downstream Omni payloads |
 | The model stage opts in with `use_async_omni_output` | Models must declare that their output lifecycle is safe to defer |
-| Omni prefix cache is disabled | Prefix-cache merge and update ordering currently requires synchronous materialization |
 | Speculative decoding is disabled | Speculative output state is not included in this deferred path |
 | Routed-expert output is disabled | Routed-expert extraction currently requires the synchronous path |
-| Postprocess is absent or explicitly runs eagerly | State needed by the next decode step must be updated before the runner returns |
+| Postprocess is absent or explicitly runs eagerly | State needed by the next decode step must be updated before the runner returns. Eager postprocess sees the scheduled slice (`None, None` combined tensors), not the prefix-cache-merged full prompt; it must only consume the tail |
 
 These checks are evaluated per stage on runners based on `GPUARModelRunner`.
 An unsupported combination does not prevent serving; it only falls back to
@@ -380,6 +379,8 @@ so Omni payload materialization remains synchronous.
 - `tests/worker/test_gpu_ar_model_runner.py`: Snapshot, guard, connector
   ordering, and background error-propagation tests.
 - [Async Chunk](async_chunk.md): Inter-stage chunking and scheduling design.
+- [Automatic Prefix Caching](prefix_caching.md#implementation): Prefix-cache
+  `step_id` / `materialize` contract used by the deferred output builder.
 - [Qwen3-Omni optimization blog](https://vllm.ai/blog/2026-07-01-qwen3-omni-optimization):
   Optimization context and controlled performance results.
 - [PR #4476](https://github.com/vllm-project/vllm-omni/pull/4476): Feature
diff --git a/docs/design/feature/prefix_caching.md b/docs/design/feature/prefix_caching.md
index a8fe4fc50a3..5aeef0f779d 100644
--- a/docs/design/feature/prefix_caching.md
+++ b/docs/design/feature/prefix_caching.md
@@ -1,6 +1,5 @@
 # Automatic Prefix Caching in Omni Models
 
-
 ---
 
 ## Table of Contents
@@ -9,6 +8,8 @@
 - [High-Level Approach](#high-level-approach)
 - [Example](#example)
 - [What About Multimodal Inputs?](#what-about-multimodal-inputs)
+- [Implementation](#implementation)
+- [Related Files](#related-files)
 
 ---
 
@@ -27,6 +28,7 @@ vLLM implements automatic prefix caching for managing its kv-cache, which is bes
     This document describes vLLM-Omni's mechanism for caching tensor outputs that are meant to be passed between stages, when requests have common prefixes, similar to the way in which vLLM has prefix caching for the kv-cache. This works in conjunction with vLLM's multimodal encoder caching, but is distinct. See the final section for a concrete example for how they tie together in practice.
 
 ### High-Level Approach
+
 !!! note "Note 2"
     Prior to reading this section, it's recommended to take a look at the design documents in vLLM for [Automatic Prefix Caching](https://docs.vllm.ai/en/latest/features/automatic_prefix_caching/), which will make some of the concepts more clear.
 
@@ -38,8 +40,10 @@ The main focus of vLLM-Omni's approach to prefix caching stage outputs is to bui
 
 With this in mind, consider the set of blocks in a 2D layout, where the row represents the index of blocks being considered, and the columns represent the slots corresponding to tokens within each block. Since we know the `num_blocks` and `block_size` from our kv cache config, if we want to cache a tensor with feature size `D`, we can preallocate a CPU tensor of size `(num_blocks, block_size, D)`, and use the same block index and slot mapping to retrieve the corresponding feature vector.
 
+Host footprint: each cached key costs `num_blocks × block_size × D × dtype_bytes` of **pinned** CPU memory (pinned so device→host can overlap compute), allocated on the first `save_outputs` that sees the key — the first real request pays the `cudaHostAlloc`. Measured on a Qwen3-Omni deployment: thinker `__hidden_states__` `[15092, 16, 2048]` bf16 ≈ 0.92 GiB (plus the same again for each `hidden_states.layer_*` key a model exposes), Qwen3-TTS talker `codes.audio` `[16180, 16, 16]` ≈ 33 MiB. Budget host RAM for the stage accordingly.
 
 ### Example
+
 !!! note "Note 3"
     Prefix caching in vLLM-Omni currently is only supported on AutoRegressive stages with one kv-cache group. Configure it with the pipeline-wide `enable_prefix_caching` field in the deploy config.
 
@@ -56,7 +60,7 @@ The prefix cache flow is then outlined below.
 
 2. Say we process the request `The quick brown fox was tired and slept beneath the shady tree`, which is 12 tokens and evenly divides into 3 blocks as shown below.
 
-```
+```text
          [  The quick brown fox  ] [  was tired and slept ] [beneath the shady tree ]
 Block 1: |<--- block tokens ---->|
 Block 2: |<------- prefix ------>| |<--- block tokens --->|
@@ -65,10 +69,9 @@ Block 3: |<------------------ prefix -------------------->| |<--- block tokens -
 
 When the request processes, we inspect the multimodal outputs and identify the `mm_feature` tensor, which will be of shape `(seq_len, feature_dim)`, i.e., `(12, 16)` in this example. We note that the first axis is dependent on the `seq_len` and add a new cache_tensor of shape `(num_blocks, block_size, feature_dim)` to our multimodal cache for tensors.
 
+1. If we lay out the cache as a 2D tensor of shape (`num_blocks`, `block_size`), we'll have something like the following:
 
-3. If we lay out the cache as a 2D tensor of shape (`num_blocks`, `block_size`), we'll have something like the following:
-
-```
+```text
 0: [  The quick brown fox  ]
 1: [  was tired and slept  ]
 2: [beneath the shady tree ]
@@ -78,7 +81,8 @@ When the request processes, we inspect the multimodal outputs and identify the `
 ```
 
 Or, if we flatten it down to 1D,
-```
+
+```text
 0: The
 1: quick
 2: brown
@@ -90,7 +94,8 @@ Or, if we flatten it down to 1D,
 ```
 
 which we can think of as row indices into the hidden states tensor if we view it as the 2D shape `(num_blocks x block_size, feature_dim)`. That is, the analogous flattened (from 3D -> 2D) mapping of the cache for hidden states becomes the following.
-```
+
+```text
 0: <hidden states vector of len 2 corresponding to 'The'>
 1: <hidden states vector of len 2 corresponding to 'quick'>
 2: <hidden states vector of len 2 corresponding to 'brown'>
@@ -103,10 +108,9 @@ which we can think of as row indices into the hidden states tensor if we view it
 
 Similarly, for the multimodal outputs cache, the flattened coordinates are the same, but the `mm_feature` maps to vectors of length `16` instead of the hidden size of `2`. Note that in practice, we may have multiple  multimodal output tensors per forward pass, which may have different names and different feature dimensions.
 
+1. Now, say that we receive a new request `The quick brown fox jumped over the dog`.
 
-4. Now, say that we receive a new request `The quick brown fox jumped over the dog`.
-
-```
+```text
          [  The quick brown fox  ] [  jumped over the dog ]
 Block 1: |<--- block tokens ---->|
 Block 2: |<------- prefix ------>| |<--- block tokens --->|
@@ -116,7 +120,7 @@ Here, we will have a cache hit for `Block 1` which will be detected by vLLM base
 
 Since we have the block indices / slot mappings from the kv cache manager, we can simply mirror the mappings and leverage the same indices for the cached hidden states and multimodal outputs. This allows us to look up the correct tensors from our externally maintained 3D caches.
 
-```
+```text
 0: [  The quick brown fox  ] < already in the cache
 1: [  was tired and slept  ]
 2: [beneath the shady tree ]
@@ -129,11 +133,11 @@ Since we have the block indices / slot mappings from the kv cache manager, we ca
 
 Finally, to pass the full hidden states and multimodal outputs to the next stage, we simply concatenate the cached contents with the corresponding new tensors computed from the current forward call.
 
-
 ### What About Multimodal Inputs?
+
 It's also useful to consider the case about how Omni prefix caching is handled when we have multimodal inputs that don't cleanly end on block boundaries, as well as how this works with multimodal encoder caching in vLLM. For example:
 
-```
+```text
          [   Im0  Im1  Im2  Im3  ] [ Im4  Im5 foo <empty> ]
 Block 1: |<--- block tokens ---->|
 Block 2: |<------- prefix ------>| |<--- block tokens --->|
@@ -147,9 +151,9 @@ In reality, this isn't a big problem for correctness, because vLLM also maintain
 - The hash describing the image data starting at position 0 and with length 6
 - In vLLM's encoder cache, a mapping from the image hash above to the encoder output
 
-
 To understand what happens, say we get the following input as a second request:
-```
+
+```text
          [   Im0  Im1  Im2  Im3  ] [  Im4  Im5 bar  baz  ]
 Block 1: |<--- block tokens ---->|
 Block 2: |<------- prefix ------>| |<--- block tokens --->|
@@ -162,3 +166,162 @@ Because we have multimodal data in a scheduled span that isn't fully precomputed
 When we pass our multimodal tensors to the language model component in the same stage, we'll then expect the same outputs, because the prefix caching behaviors in vLLM-Omni / vLLM match, so the LLM will use vLLM's KV cache manager's prefix caching to correctly handle the attention information for `Block 1` while calculating the outputs for `Block 2`, giving us the correct results for processing `Block 2` with the context of `Block 1`.
 
 Finally, we look up the output hidden states/multimodal tensors corresponding to the prefix cache hit `Block 1` and concatenate it with the forward pass result to get the final result, which is expected to be identical to the full hidden states when prefix caching is disabled.
+
+### Implementation
+
+The block/slot model is `vllm_omni/core/prefix_cache/`.
+`OmniPrefixCacheManager` owns slot occupancy, the request-task table,
+hit spans, and merge.
+`OmniPrefixCacheController` moves data: a reusable `StagingBufferPool` for
+this step's device→host copy, and writes into the durable `PrefixBlockPool`.
+The state lock covers those tables only.
+
+Miss is not an error (this step's forward slice only). A hit span whose
+hidden rows are absent is fatal. For mm keys the rule is looser: a model may
+emit a key only for some requests, so a hit span with no rows behind an mm key
+reads zeros from the pool for those positions rather than raising. Abort still
+writes: once a hash entered this step's batch it must land in the cache.
+
+`enable_prefix_caching` is refused on KV-consumer stages (`kv_role` of
+`kv_consumer` or `kv_both`). KV received from a producer is reported as
+`num_computed_tokens` too, and the manager cannot tell it from a local hit.
+Producer-only stages are unaffected. Pooling stages never save, so they get
+no cache. This gate is one function, `stage_prefix_cache_config`, called by
+both the GPU and the NPU model runner at kv-cache init.
+
+Which stages may set `enable_prefix_caching: true`:
+
+| Stage | `enable_prefix_caching` | Why |
+| --- | --- | --- |
+| AR stage with one full-attention kv group whose hidden states / per-token mm feed the next stage (Qwen3-Omni thinker and talker) | supported | The case the cache is built for: full-prompt hidden states are merged from the pool on a hit. |
+| AR stage that sets `requires_full_prefix_cached_hidden_states = False`, optionally with `deferred_prefix_cache_mm_keys` (Qwen3-TTS talker, Higgs v3 talker) | supported | Hidden is not cached; deferred codec rows are written once on finish. |
+| Pooling stage | ignored | Never saves; the gate returns no config. |
+| `kv_role: kv_consumer` / `kv_both` | refused at kv-cache init (`OmniPrefixCacheUnmatchError`) | Producer KV shows up as `num_computed_tokens` and is indistinguishable from a local hit. |
+| Speculative decoding on the stage | refused at kv-cache init | Under async scheduling vLLM keeps `num_computed_tokens_cpu` optimistic (all drafts accepted) during the forward and corrects it afterwards; `step_slots_cpu` would mirror rows at the wrong slots. Not verified; refused as a whole. |
+| `prefix_match_unit` smaller than `block_size` | refused at kv-cache init | Sub-block hits make `num_computed_tokens` unaligned; the hit registry only mirrors whole blocks. |
+| Hybrid / sliding-window / multi-group kv cache (e.g. a talker with `attention_type: sliding_recompute`) | refused at kv-cache init | The cache mirrors exactly one full-attention block table. |
+| Attention backend whose kernel block size differs from `--block-size` (FlashInfer / FlashMLA / CutlassMLA with a block size they do not list natively), or decode context parallel | refused at first step (`FullAttentionGroupView`) | `step_slots_cpu` computes `table[req, pos // block_size] * block_size + pos % block_size` over allocator block ids; hybrid kernel blocks and DCP token striping change that row layout. FlashAttention / Triton accept any multiple of 16 and never split blocks. |
+| Codec decoder / Code2Wav stages (Qwen3-Omni stage 2, Qwen3-TTS stage 1) | keep `false` | Nothing downstream consumes their hidden states; the cache would only add device→host copies. Not validated. |
+| Diffusion stages | n/a | No vLLM KV cache to mirror. |
+
+Hit spans come from `scheduled_new_reqs` only, as in the pre-refactor cache:
+
+- A new request with a (partial) prefix hit is the normal path: the hit
+  blocks are read from the pool, the rest is this step's rows, and the
+  divergent tail is written under its own blocks. The gather starts on the
+  prefetch thread at `new_step_starts`; a same-step hit (vLLM hashes blocks
+  at schedule time, so `b` can hit blocks `a` computes in the same forward)
+  cannot plan until `a`'s write is registered and starts at `save_outputs`
+  instead. Either way it runs before the next step can hand those blocks
+  to a new tenant. vLLM frees blocks one step before `finished_req_ids`
+  arrives, so a finished request whose last step materializes late may
+  still find a hit slot reassigned. Each `(slot, key)` carries a write
+  version, bumped whenever a new write claims it. A planned read captures
+  that version and is registered in `_pending_reads`; a later write that
+  reclaims those slots copy-on-writes the still-`COMMITTED` rows into the
+  ref before it overwrites the pool, so a delayed fetch serves the original
+  tenant. A version mismatch with no preserved copy raises for live and
+  finished alike (the pool rows are a newer tenant's). Production defaults
+  stay opt-in until preempt/resume hit spans are reconstructed.
+- `async_chunk` continuation: when the next upstream chunk arrives, the same
+  request id re-enters `scheduled_new_reqs` with `num_computed_tokens` equal
+  to what it already computed itself. Ids already in `live_reqs` are skipped
+  for hit marking: those rows were delivered in earlier steps and re-emitting
+  them would duplicate output. A `delivered_upto` span for this case is
+  Phase 2.
+- Preemption + reschedule: vLLM resets `num_computed_tokens` to 0 on
+  preemption and re-runs prefix matching on resume, so the resumed request
+  can come back with a fresh hit. With the V1 model runner it arrives
+  through `scheduled_cached_reqs` (id in `resumed_req_ids`, `new_block_ids`
+  replaces the table); with the V2 runner it re-enters `scheduled_new_reqs`
+  while still in `live_reqs`. Neither path marks an omni hit span: the
+  resumed request gets only the rows it recomputes, and its still-open
+  deferred write keeps appending (a slot written twice keeps the later
+  chunk). Cache integrity holds either way — the hit blocks already have
+  rows, from this request or the one it hit. Stages that need full prompt
+  hidden states should be sized so preemption does not occur while prefix
+  caching is on. Same as before this refactor; tracked for Phase 2.
+
+Two write paths, split by `ModelCachePolicy.deferred_keys`:
+
+- Immediate (`JOIN_NEXT_STEP`): save launches a whole-step device→host into
+  a staging slot; the committer waits that event and writes the CPU pool.
+  The next save waits `done` (the pool write): a reused slot must never
+  leave a pending pool write behind, or a delayed hit read of the old rows
+  would find nothing recoverable.
+- Deferred (`JOIN_ON_FINISH`): mm whose first dim is this step's token count
+  stays on a per-request GPU clone; `_WriteChunk`s append across steps;
+  finish/abort (or GPU-byte-budget pressure) forces the copy. One open
+  WriteTask per request; a budget flush may close it mid-request, in which
+  case the next save opens a new one (`write_n` + 1) and a hit reads both,
+  so one long request cannot pin the whole budget.
+
+A `WriteTask` moves through `TaskState` only via `transition()`, one step at
+a time along a strict chain:
+`PENDING` (registered, not queued) → `QUEUED` (on a copy queue) →
+`COPYING` (one thread owns the copy stage) → `HOST_READY` (host rows ready) →
+`WRITTEN` (in the CPU pool); `FAILED` is reachable from any non-terminal
+state. Skipping a step raises. The worker claims `COPYING` in the same `_wake`
+critical section as the queue pop, so `escalate` never re-queues a task it can
+see is already claimed. `host_ready` / `done` are wait primitives set by the
+transitions into `HOST_READY` / `WRITTEN` / `FAILED`. GPU-clone bytes are
+charged once per clone on a `_BudgetTicket` pinned by every task that views
+it, and uncharged when the last holder releases (idempotent per tid).
+
+Mm whose first dim equals the unpadded scheduled length *or* the CUDA-graph
+padded length is registered on first sighting. Talker `codes.audio` is a
+cat of scheduled rows and stays unpadded while hidden is padded; both must
+open a pool key, whether immediate or deferred.
+Leftover mm (lists, `codes.ref`, any tensor whose first dim is not this
+step's token count) is copied to CPU at save without truncating that first
+dim. That leftover copy is the async-builder read replica for this step; it
+does not write the pool or carry abort/preempt occupancy.
+
+```python
+cache.register_policy(ModelCachePolicy.from_model(model))   # load_model
+cache.new_step_starts(scheduler_output)   # before _update_states
+sid = cache.save_outputs(hidden, mm_outputs, num_tokens_unpadded=n,
+                         num_tokens_padded=n_pad)
+outs = cache.materialize(sid, req_ids)    # or discard_step(sid)
+```
+
+Each step id is consumed exactly once. `req_ids` must be a subset of the save
+snapshot. At most `staging_depth` unused step ids may exist at once: every
+`save_outputs` claims one staging slot, including saves with only leftover
+mm that copy no device→host page. A slot is also held by each immediate
+write that views it, until the committer's pool write. A later save waits
+for `materialize`/`discard_step` or that pool write to free a slot;
+`staging_claim_timeout_s` then errors with the unused ids and the task count.
+`join`/`join_host_ready` use the same bound and raise with the stuck task's
+id and state instead of hanging the caller.
+`materialize` may run on the async output builder after the engine has
+entered the next step; leftover mm (not written to the pool) is copied
+to CPU at `save_outputs` so the builder never reads live CUDA-graph
+buffers. See
+[Async Omni Output Materialization](omni_async_output_materialization.md).
+
+The cache is constructed only on the last pipeline-parallel rank
+(`_ensure_omni_prefix_cache`). Other ranks skip it: they never call
+`save_outputs`, so a hit table there would resolve to absent slots.
+
+Threads, locks, and what each may block on:
+
+| Thread | Role | May block on | Must not hold while blocked |
+| --- | --- | --- | --- |
+| Engine | `new_step_starts`, `save_outputs` | previous-step `join` (`done`) / finished-write `join_host_ready`; `reserve()` GPU-byte flush; staging-slot claim; `dispatch()` / finish-abort `escalate()` (eager mode: the copy + pool write run inline) | `_state_lock` |
+| Async output builder | `materialize` (may overlap the next engine step) | this step's `step_d2h_event`; `join` (`done`); deferred `fetch_host` | `_state_lock` |
+| Committer | `_worker_loop`: wait device→host / deferred copy / pool write | `_wake.wait`; `step_d2h_event` or copy-stream sync | never takes `_state_lock` |
+| Prefetch pool | hit-span gather during forward | `join` (`done`); deferred `fetch_host` | `_state_lock` |
+
+| Lock | Covers | Does not cover |
+| --- | --- | --- |
+| manager `_state_lock` | occupancy tables, step contexts, hit spans, task registration, pool-key publish (`install_key`) | join, GPU-byte flush, copy, `step_d2h_event` wait, pool-key allocation, eager `dispatch()` / `escalate()` |
+| controller `_lock` / `_wake` | task registry, queues, GPU-clone byte budget | device→host / pool-write body (released before `synchronize`) |
+| `WriteTask.lock` | `state`, `reassigned`, `append_chunk` | waiting on `host_ready` / `done` (those are events) |
+
+### Related Files
+
+- `vllm_omni/core/prefix_cache/`
+- `vllm_omni/worker/gpu_model_runner.py` (`_ensure_omni_prefix_cache`)
+- `tests/core/test_prefix_cache.py`
+- [Async Omni Output Materialization](omni_async_output_materialization.md)
diff --git a/tests/core/test_prefix_cache.py b/tests/core/test_prefix_cache.py
index 4f91a95b7af..171f36f7182 100644
--- a/tests/core/test_prefix_cache.py
+++ b/tests/core/test_prefix_cache.py
@@ -1,917 +1,1801 @@
-import math
-from typing import NamedTuple
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Unit tests for vllm_omni/core/prefix_cache (manager + controller + pool).
+
+CPU-only: the controller runs in eager mode. Uses a fake group view, so no
+vLLM runtime is required (runnable without a vllm install via
+``pytest --confcutdir=tests/core``).
+"""
+
+import ast
+import logging
+import sys
+import threading
+import time
+from pathlib import Path
+from types import SimpleNamespace
 
 import pytest
 import torch
 
-from vllm_omni.core.prefix_cache import OmniTensorPrefixCache
+try:  # pragma: no cover - shim only matters on vllm-less dev machines
+    import vllm  # noqa: F401
+except ModuleNotFoundError:
+    # Bypass vllm_omni/__init__ (which imports vllm): register namespace
+    # parents so the pure-torch prefix_cache subpackage imports directly.
+    _root = Path(__file__).resolve().parents[2]
+    for _pkg in ("vllm_omni", "vllm_omni.core", "vllm_omni.utils"):
+        if _pkg not in sys.modules:
+            _m = __import__("types").ModuleType(_pkg)
+            _m.__path__ = [str(_root / _pkg.replace(".", "/"))]
+            sys.modules[_pkg] = _m
+    _vllm = __import__("types").ModuleType("vllm")
+    _vllm_logger = __import__("types").ModuleType("vllm.logger")
+    _vllm_logger.init_logger = logging.getLogger
+    _vllm.logger = _vllm_logger
+    sys.modules["vllm"] = _vllm
+    sys.modules["vllm.logger"] = _vllm_logger
+
+from vllm_omni.core.prefix_cache.controller import StagingBufferHolder
+from vllm_omni.core.prefix_cache.group_view import (
+    FullAttentionGroupView,
+    check_prefix_cache_kv_groups,
+    stage_prefix_cache_config,
+)
+from vllm_omni.core.prefix_cache.interface import (
+    HIDDEN_KEY,
+    ModelCachePolicy,
+    OmniPrefixCacheStagingTimeoutError,
+    OmniPrefixCacheUnmatchError,
+    PrefixCacheConfig,
+    WriteSchedule,
+)
+from vllm_omni.core.prefix_cache.manager import (
+    OmniPrefixCacheManager,
+    _is_step_token_tensor,
+    _snapshot_leftover_mm_cpu,
+)
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
-
-DEFAULT_SEQ_LEN = 15
-NUM_BLOCKS = 10
+NUM_BLOCKS = 16
 BLOCK_SIZE = 4
-HIDDEN_SIZE = 2
+HIDDEN = 8
 DTYPE = torch.float32
-OTHER_DTYPE = torch.float16
-DEFAULT_SHAPE = torch.Size([NUM_BLOCKS, BLOCK_SIZE, HIDDEN_SIZE])
-
 
-class MockInputBatch:
-    def __init__(self, num_computed_tokens_cpu, block_table=None):
-        self.req_ids = ["req1", "req2"]
-        self.req_id_to_index = {req_id: i for i, req_id in enumerate(self.req_ids)}
-        self.num_computed_tokens_cpu = num_computed_tokens_cpu
 
-        # Block table is only mocked for validation of length;
-        # we don't actually need to add valid values here since
-        # we patch the table when testing.
-        if block_table is None:
-
-            class _DummyBlockTable:
-                pass
-
-            self.block_table = _DummyBlockTable()
-            self.block_table.block_tables = [None]
+class FakeView:
+    """Duck-typed group view backed by plain dicts."""
+
+    def __init__(self):
+        self.block_size = BLOCK_SIZE
+        self.req_blocks: dict[str, list[int]] = {}
+        self.order: list[str] = []
+        self.computed: dict[str, int] = {}
+        self.step_slot_mapping: torch.Tensor | None = None
+
+    def slots_for(self, req_id, token_start, token_end):
+        blocks = self.req_blocks[req_id]
+        slots = []
+        for pos in range(token_start, token_end):
+            slots.append(blocks[pos // BLOCK_SIZE] * BLOCK_SIZE + pos % BLOCK_SIZE)
+        return torch.tensor(slots, dtype=torch.long)
+
+    def batch_req_ids(self) -> list[str]:
+        return list(self.order)
+
+    def step_slots_cpu(self, req_ids, num_scheduled) -> torch.Tensor:
+        parts = []
+        for r in req_ids:
+            n = int(num_scheduled.get(r, 0))
+            if n <= 0:
+                continue
+            start = self.computed.get(r, 0)
+            parts.append(self.slots_for(r, start, start + n))
+        return torch.cat(parts) if parts else torch.empty((0,), dtype=torch.long)
+
+
+class FakeNewReq:
+    def __init__(self, req_id, num_computed_tokens=0, block_ids=None):
+        self.req_id = req_id
+        self.num_computed_tokens = num_computed_tokens
+        self.block_ids = block_ids
+
+
+class FakeSchedOut:
+    def __init__(self, new_reqs=(), finished=(), num_scheduled=None):
+        self.scheduled_new_reqs = list(new_reqs)
+        self.finished_req_ids = set(finished)
+        self.num_scheduled_tokens = dict(num_scheduled or {})
+
+
+def make_manager(view=None, policy=None, **cfg_kwargs) -> tuple[OmniPrefixCacheManager, FakeView]:
+    view = view or FakeView()
+    config = PrefixCacheConfig(num_blocks=NUM_BLOCKS, block_size=BLOCK_SIZE, **cfg_kwargs)
+    mgr = OmniPrefixCacheManager(config, view, eager=True)
+    if policy is not None:
+        mgr.register_policy(policy)
+    return mgr, view
+
+
+def run_step(
+    mgr,
+    view,
+    reqs: dict[str, tuple[list[int], int, int]],
+    new_hits=None,
+    finished=(),
+    mm=None,
+    num_tokens_padded=None,
+) -> int:
+    """One step: reqs = req_id -> (blocks, sched_start_pos, sched_tokens)."""
+    view.order = list(reqs.keys())
+    new_reqs = []
+    num_sched = {}
+    slot_parts = []
+    hidden_parts = []
+    for req_id, (blocks, start_pos, sched) in reqs.items():
+        view.req_blocks[req_id] = blocks
+        view.computed[req_id] = start_pos
+        num_sched[req_id] = sched
+        slots = view.slots_for(req_id, start_pos, start_pos + sched)
+        slot_parts.append(slots)
+        hidden_parts.append(slots.to(DTYPE).unsqueeze(1).expand(sched, HIDDEN).clone())
+        hit = (new_hits or {}).get(req_id, 0)
+        new_reqs.append(FakeNewReq(req_id, num_computed_tokens=hit, block_ids=[list(blocks)]))
+    view.step_slot_mapping = torch.cat(slot_parts)
+    hidden = torch.cat(hidden_parts)
+    sched_out = FakeSchedOut(new_reqs=new_reqs, finished=finished, num_scheduled=num_sched)
+    mgr.new_step_starts(sched_out)
+    n = int(view.step_slot_mapping.numel())
+    padded = n if num_tokens_padded is None else int(num_tokens_padded)
+    return mgr.save_outputs(hidden, mm or {}, num_tokens_unpadded=n, num_tokens_padded=padded)
+
+
+def expected_rows(slots: torch.Tensor) -> torch.Tensor:
+    return slots.to(DTYPE).unsqueeze(1).expand(slots.numel(), HIDDEN)
+
+
+def plan_fetch(mgr, slots, key, *, req_id):
+    with mgr._state_lock:
+        src = mgr._slot_ref(slots, key, req_id)
+    with torch.inference_mode():
+        return mgr._fetch_source(src)
+
+
+def _assert_leftover_shapes(inp, got, n: int) -> None:
+    """Every leftover tensor keeps its shape unless dim0 is this step's token count."""
+    if isinstance(inp, torch.Tensor):
+        if inp.ndim >= 1 and n > 0 and inp.shape[0] == n:
+            assert got.shape == (n, *inp.shape[1:])
         else:
-
-            class _TensorWrapper:
-                def __init__(self, tensor):
-                    self.cpu = tensor
-
-            class _BlockGroup:
-                def __init__(self, tensor):
-                    self.block_table = _TensorWrapper(tensor)
-
-            class _BlockTable:
-                def __init__(self, tensor):
-                    self._group = _BlockGroup(tensor)
-                    self.block_tables = [self._group.block_table]
-
-                def __getitem__(self, idx):
-                    assert idx == 0
-                    return self._group
-
-            self.block_table = _BlockTable(block_table)
-
-
-def get_omni_pcache_with_mm_tensors(feat_dims, seq_len) -> OmniTensorPrefixCache:
-    """Build an OmniTensorPrefixCache and init mm tensors."""
-    cache = get_omni_pcache()
-    mm_outputs = get_multimodal_outputs(feat_dims, seq_len)
-    cache.maybe_init_missing_mm_cache_keys(mm_outputs, seq_len)
-    return cache
-
-
-def get_omni_pcache() -> OmniTensorPrefixCache:
-    """Build an OmniTensorPrefixCache, but don't init mm tensors."""
-    cache = OmniTensorPrefixCache(
-        num_blocks=NUM_BLOCKS,
-        block_size=BLOCK_SIZE,
-        hidden_size=HIDDEN_SIZE,
-        hs_dtype=DTYPE,
-    )
-    return cache
-
-
-def get_multimodal_outputs(feat_dims: dict[str, int], seq_len: int) -> dict[str, torch.Tensor]:
-    fake_mm_inputs = {}
-    for mm_key, feat_dim in feat_dims.items():
-        fake_mm_inputs[mm_key] = torch.rand((seq_len, feat_dim), dtype=DTYPE)
-    return fake_mm_inputs
-
-
-### Tests for initialization
-def test_initialization_simple():
-    """Check default initialization only creates the hidden states."""
-    cache = get_omni_pcache()
-    assert isinstance(cache.hidden_states_cache, torch.Tensor)
-    assert cache.hidden_states_cache.shape == DEFAULT_SHAPE
-    assert len(cache.mm_outputs_cache) == 0
-    assert len(cache.mm_cache_keys) == 0
-
-
-def test_initialization_with_multimodal():
-    """Check initialization + registration of multimodal outputs."""
-    cache = get_omni_pcache()
-    feat_dims = {"foo": 100, "bar": 50, "baz": 10}
-    mm_outputs = get_multimodal_outputs(
-        feat_dims,
-        seq_len=DEFAULT_SEQ_LEN,
-    )
-    # Cast one of the keys to a different dtype; the dtype of the tensor
-    # that is used to initialize the cache dictates the cache dtype.
-    mm_outputs["foo"] = mm_outputs["foo"].to(OTHER_DTYPE)
-
-    cache.maybe_init_missing_mm_cache_keys(mm_outputs, DEFAULT_SEQ_LEN)
-    assert len(cache.mm_cache_keys) == 3
-    assert set(cache.mm_cache_keys) == set(feat_dims.keys())
-    for mm_key in cache.mm_cache_keys:
-        cache_tensor = cache.mm_outputs_cache[mm_key]
-        assert isinstance(cache_tensor, torch.Tensor)
-        assert cache_tensor.shape[-1] == feat_dims[mm_key]
-        assert mm_outputs[mm_key].dtype == cache_tensor.dtype
-
-
-def test_init_missing_mm_cache_keys_is_idempotent():
-    """Ensure that the cache doesn't reinitialize old keys."""
-    cache = get_omni_pcache()
-    mm_key = "foo"
-    feat_dims = {mm_key: 100}
-    mm_outputs = get_multimodal_outputs(
-        feat_dims,
-        seq_len=DEFAULT_SEQ_LEN,
-    )
-    cache.maybe_init_missing_mm_cache_keys(mm_outputs, DEFAULT_SEQ_LEN)
-    assert len(cache.mm_cache_keys) == 1
-    assert mm_key in cache.mm_cache_keys
-
-    # Cache is initialized to 0 - fill it with 1s
-    cache.mm_outputs_cache[mm_key].fill_(1)
-
-    # Ensure that running another initialization
-    # doesn't zero out our cache values
-    cache.maybe_init_missing_mm_cache_keys(mm_outputs, DEFAULT_SEQ_LEN)
-    assert len(cache.mm_cache_keys) == 1
-    assert mm_key in cache.mm_cache_keys
-    assert torch.all(cache.mm_outputs_cache[mm_key] == 1)
-
-
-### Tests for Update
-def test_update_no_multimodal():
-    """Test that slot mappings act as row indices hidden states."""
-    cache = get_omni_pcache()
-
-    num_tokens_unpadded = 8
-    slot_offset = 8
-    slot_mapping = torch.arange(slot_offset, slot_offset + num_tokens_unpadded)
-    new_hidden_states = torch.rand((num_tokens_unpadded, HIDDEN_SIZE), dtype=DTYPE)
-
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=new_hidden_states,
-        multimodal_outputs=None,
-        num_tokens_unpadded=num_tokens_unpadded,
-        slot_mapping=slot_mapping,
-    )
-
-    # Ensure that if we reshape our 3D cache back to 2D, we can use the
-    # indices in our slot mappings to access the hidden states as expected
-    hs_rows = cache.hidden_states_cache.view(NUM_BLOCKS * BLOCK_SIZE, HIDDEN_SIZE)
-    for slot_idx, new_states in zip(slot_mapping, new_hidden_states):
-        slot_states = hs_rows[slot_idx]
-        assert torch.all(slot_states == new_states)
-
-
-def test_update_uses_precomputed_hidden_states_cpu():
-    """Precomputed CPU staging should be the only hidden-state cache source."""
-    cache = get_omni_pcache()
-
-    num_tokens_unpadded = 8
-    slot_offset = 8
-    slot_mapping = torch.arange(slot_offset, slot_offset + num_tokens_unpadded)
-    hidden_states = torch.zeros((num_tokens_unpadded, HIDDEN_SIZE), dtype=DTYPE)
-    hidden_states_cpu = torch.rand((num_tokens_unpadded, HIDDEN_SIZE), dtype=DTYPE)
-
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=hidden_states,
-        hidden_states_cpu=hidden_states_cpu,
-        multimodal_outputs=None,
-        num_tokens_unpadded=num_tokens_unpadded,
-        slot_mapping=slot_mapping,
-    )
-
-    hs_rows = cache.hidden_states_cache.view(NUM_BLOCKS * BLOCK_SIZE, HIDDEN_SIZE)
-    for slot_idx, new_states in zip(slot_mapping, hidden_states_cpu):
-        slot_states = hs_rows[slot_idx]
-        assert torch.all(slot_states == new_states)
-
-
-@pytest.mark.parametrize(
-    "hidden_states_cpu",
-    [
-        torch.rand((4, HIDDEN_SIZE), dtype=DTYPE),
-        torch.rand((8, HIDDEN_SIZE), dtype=OTHER_DTYPE),
-        torch.rand((8, HIDDEN_SIZE + 1), dtype=DTYPE),
-        torch.rand((HIDDEN_SIZE, 8), dtype=DTYPE).t(),
-    ],
-)
-def test_update_rejects_invalid_hidden_states_cpu(hidden_states_cpu):
-    cache = get_omni_pcache()
-
-    num_tokens_unpadded = 8
-    slot_mapping = torch.arange(num_tokens_unpadded)
-    hidden_states = torch.rand((num_tokens_unpadded, HIDDEN_SIZE), dtype=DTYPE)
-
-    with pytest.raises(RuntimeError):
-        cache.update_omni_tensor_prefix_cache(
-            hidden_states=hidden_states,
-            hidden_states_cpu=hidden_states_cpu,
-            multimodal_outputs=None,
-            num_tokens_unpadded=num_tokens_unpadded,
-            slot_mapping=slot_mapping,
-        )
-
-
-@pytest.mark.skipif(not torch.cuda.is_available(), reason="requires CUDA")
-def test_update_rejects_gpu_hidden_states_cpu():
-    cache = get_omni_pcache()
-
-    num_tokens_unpadded = 8
-    slot_mapping = torch.arange(num_tokens_unpadded)
-    hidden_states = torch.rand((num_tokens_unpadded, HIDDEN_SIZE), dtype=DTYPE)
-    hidden_states_cpu = torch.rand((num_tokens_unpadded, HIDDEN_SIZE), dtype=DTYPE, device="cuda")
-
-    with pytest.raises(RuntimeError):
-        cache.update_omni_tensor_prefix_cache(
-            hidden_states=hidden_states,
-            hidden_states_cpu=hidden_states_cpu,
-            multimodal_outputs=None,
-            num_tokens_unpadded=num_tokens_unpadded,
-            slot_mapping=slot_mapping,
-        )
-
-
-@pytest.mark.parametrize(
-    "feat_dims",
-    [
-        {"foo": 100, "bar": 100},
-        {"foo": 100, "bar": 50, "baz": 10},
-    ],
-)
-def test_update_with_multimodal_outputs(feat_dims):
-    """Test that slot mappings are correct for multimodal tensors."""
-    cache = get_omni_pcache_with_mm_tensors(feat_dims, seq_len=DEFAULT_SEQ_LEN)
-
-    num_tokens_unpadded = 8
-    slot_offset = 8
-    slot_mapping = torch.arange(slot_offset, slot_offset + num_tokens_unpadded)
-    feature_dims = {key: val.shape[-1] for key, val in cache.mm_outputs_cache.items()}
-    mm_outputs = {key: torch.rand((num_tokens_unpadded, feature_dims[key]), dtype=DTYPE) for key in cache.mm_cache_keys}
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=None,
-        multimodal_outputs=mm_outputs,
-        num_tokens_unpadded=num_tokens_unpadded,
-        slot_mapping=slot_mapping,
-    )
-
-    for mm_key in feat_dims.keys():
-        assert mm_key in cache.mm_outputs_cache
-        key_feat_dim = feature_dims[mm_key]
-        mm_state_rows = cache.mm_outputs_cache[mm_key].view(NUM_BLOCKS * BLOCK_SIZE, key_feat_dim)
-
-        # Similar to hidden states, but for each key in the dict;
-        # Different tensors may have different feature dims
-        new_mm_outputs = mm_outputs[mm_key]
-        for slot_idx, new_output in zip(slot_mapping, new_mm_outputs):
-            slot_states = mm_state_rows[slot_idx]
-            assert torch.all(slot_states == new_output)
-
-
-def test_deferred_multimodal_cache_write_commits_on_completion():
-    cache = get_omni_pcache()
-    mm_key = "codes.audio"
-    block_table = torch.tensor(
-        [
-            [2, 3, 4, 5],
-            [6, 7, 8, 9],
-        ],
-        dtype=torch.long,
-    )
-    input_batch = MockInputBatch(
-        num_computed_tokens_cpu=torch.tensor([4, 0], dtype=torch.long),
-        block_table=block_table,
-    )
-
-    first_chunk = torch.arange(8, dtype=torch.long).reshape(4, 2)
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=None,
-        multimodal_outputs={mm_key: first_chunk},
-        num_tokens_unpadded=4,
-        slot_mapping=torch.arange(8, 12),
-        skip_mm_cache_keys={mm_key},
-    )
-
-    rows = cache.mm_outputs_cache[mm_key].view(-1, 2)
-    assert torch.all(rows[8:12] == 0)
-
-    cache.stage_deferred_mm_outputs(
-        query_start_loc=torch.tensor([0, 4], dtype=torch.long),
-        input_batch=input_batch,
-        multimodal_outputs={mm_key: first_chunk},
-        num_scheduled_tokens={"req1": 4, "req2": 0},
-        deferred_mm_cache_keys={mm_key},
-    )
-
-    second_chunk = torch.arange(8, 16, dtype=torch.long).reshape(4, 2)
-    input_batch.num_computed_tokens_cpu = torch.tensor([8, 0], dtype=torch.long)
-    cache.stage_deferred_mm_outputs(
-        query_start_loc=torch.tensor([0, 4], dtype=torch.long),
-        input_batch=input_batch,
-        multimodal_outputs={mm_key: second_chunk},
-        num_scheduled_tokens={"req1": 4, "req2": 0},
-        deferred_mm_cache_keys={mm_key},
-    )
-
-    cache.commit_deferred_mm_outputs({"req1"}, input_batch)
-
-    expected = torch.cat([first_chunk, second_chunk], dim=0)
-    rows = cache.mm_outputs_cache[mm_key].view(-1, 2)
-    assert torch.equal(rows[8:16], expected)
-
-
-def test_discard_deferred_mm_outputs_drops_pending_chunks():
-    """discard_deferred_mm_outputs is the abort path: a request that
-    leaves without a cache commit must not leak its staged chunks into
-    the cache if commit_deferred_mm_outputs is later called for it."""
-    cache = get_omni_pcache()
-    mm_key = "codes.audio"
-    block_table = torch.tensor(
-        [
-            [2, 3, 4, 5],
-            [6, 7, 8, 9],
-        ],
-        dtype=torch.long,
-    )
-    input_batch = MockInputBatch(
-        num_computed_tokens_cpu=torch.tensor([4, 0], dtype=torch.long),
-        block_table=block_table,
-    )
-
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=None,
-        multimodal_outputs={mm_key: torch.arange(8, dtype=torch.long).reshape(4, 2)},
-        num_tokens_unpadded=4,
-        slot_mapping=torch.arange(8, 12),
-        skip_mm_cache_keys={mm_key},
-    )
-
-    chunk = torch.arange(8, dtype=torch.long).reshape(4, 2)
-    cache.stage_deferred_mm_outputs(
-        query_start_loc=torch.tensor([0, 4], dtype=torch.long),
-        input_batch=input_batch,
-        multimodal_outputs={mm_key: chunk},
-        num_scheduled_tokens={"req1": 4, "req2": 0},
-        deferred_mm_cache_keys={mm_key},
-    )
-    assert "req1" in cache._deferred_mm_outputs
-
-    cache.discard_deferred_mm_outputs("req1")
-    assert "req1" not in cache._deferred_mm_outputs
-
-    # A later commit call for the now-discarded req_id must be a no-op,
-    # not a resurrection of the dropped chunk.
-    cache.commit_deferred_mm_outputs({"req1"}, input_batch)
-    rows = cache.mm_outputs_cache[mm_key].view(-1, 2)
-    assert torch.all(rows[8:12] == 0)
-
-
-def test_deferred_mm_outputs_request_id_reused_after_discard():
-    """A request ID reused after discard_deferred_mm_outputs must start
-    clean: the new occupant's committed data must not be mixed with the
-    previous (discarded) occupant's staged chunks."""
-    cache = get_omni_pcache()
-    mm_key = "codes.audio"
-    block_table = torch.tensor(
-        [
-            [2, 3, 4, 5],
-            [6, 7, 8, 9],
-        ],
-        dtype=torch.long,
-    )
-    input_batch = MockInputBatch(
-        num_computed_tokens_cpu=torch.tensor([4, 0], dtype=torch.long),
-        block_table=block_table,
-    )
-
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=None,
-        multimodal_outputs={mm_key: torch.arange(8, dtype=torch.long).reshape(4, 2)},
-        num_tokens_unpadded=4,
-        slot_mapping=torch.arange(8, 12),
-        skip_mm_cache_keys={mm_key},
-    )
-
-    stale_chunk = torch.full((4, 2), -1, dtype=torch.long)
-    cache.stage_deferred_mm_outputs(
-        query_start_loc=torch.tensor([0, 4], dtype=torch.long),
-        input_batch=input_batch,
-        multimodal_outputs={mm_key: stale_chunk},
-        num_scheduled_tokens={"req1": 4, "req2": 0},
-        deferred_mm_cache_keys={mm_key},
-    )
-    cache.discard_deferred_mm_outputs("req1")
-
-    # "req1" is reused by a brand-new request with different data.
-    fresh_chunk = torch.arange(8, dtype=torch.long).reshape(4, 2)
-    cache.stage_deferred_mm_outputs(
-        query_start_loc=torch.tensor([0, 4], dtype=torch.long),
-        input_batch=input_batch,
-        multimodal_outputs={mm_key: fresh_chunk},
-        num_scheduled_tokens={"req1": 4, "req2": 0},
-        deferred_mm_cache_keys={mm_key},
-    )
-    cache.commit_deferred_mm_outputs({"req1"}, input_batch)
-
-    rows = cache.mm_outputs_cache[mm_key].view(-1, 2)
-    assert torch.equal(rows[8:12], fresh_chunk)
-
-
-def test_deferred_multimodal_cache_can_be_merged_on_full_block_hit():
-    cache = get_omni_pcache()
-    mm_key = "codes.audio"
-    block_table = torch.tensor(
-        [
-            [2, 3, 4, 5],
-            [6, 7, 8, 9],
-        ],
-        dtype=torch.long,
-    )
-    input_batch = MockInputBatch(
-        num_computed_tokens_cpu=torch.tensor([8, 0], dtype=torch.long),
-        block_table=block_table,
-    )
-    cached_codes = torch.arange(16, dtype=torch.long).reshape(8, 2)
-    cache.stage_deferred_mm_outputs(
-        query_start_loc=torch.tensor([0, 8], dtype=torch.long),
-        input_batch=input_batch,
-        multimodal_outputs={mm_key: cached_codes},
-        num_scheduled_tokens={"req1": 8, "req2": 0},
-        deferred_mm_cache_keys={mm_key},
+            assert got.shape == inp.shape
+        return
+    if isinstance(inp, dict):
+        assert set(got) == set(inp)
+        for k in inp:
+            _assert_leftover_shapes(inp[k], got[k], n)
+        return
+    if isinstance(inp, (list, tuple)):
+        assert len(got) == len(inp)
+        for a, b in zip(inp, got):
+            _assert_leftover_shapes(a, b, n)
+
+
+def _module_scope_imported_modules(path: Path) -> list[str]:
+    """Top-level import module names, skipping ``if TYPE_CHECKING`` blocks."""
+    tree = ast.parse(path.read_text())
+    names: list[str] = []
+
+    def _from_stmt(node: ast.AST) -> None:
+        if isinstance(node, ast.Import):
+            names.extend(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module:
+            names.append(node.module)
+
+    for node in tree.body:
+        if isinstance(node, ast.If) and isinstance(node.test, ast.Name) and node.test.id == "TYPE_CHECKING":
+            continue
+        _from_stmt(node)
+    return names
+
+
+def test_prefix_cache_package_has_no_module_scope_vllm_import():
+    """This package must import without vllm. See the package docstring."""
+    pkg = Path(__file__).resolve().parents[2] / "vllm_omni" / "core" / "prefix_cache"
+    leaked: list[str] = []
+    for path in sorted(pkg.glob("*.py")):
+        for mod in _module_scope_imported_modules(path):
+            if mod == "vllm" or mod.startswith("vllm."):
+                leaked.append(f"{path.name}: {mod}")
+    assert not leaked, leaked
+
+
+def test_no_hit_passthrough():
+    mgr, view = make_manager()
+    sid = run_step(mgr, view, {"a": ([0, 1], 0, 8)})
+    outs = mgr.materialize(sid, ["a"])
+    assert torch.equal(outs.hidden_states["a"], expected_rows(view.slots_for("a", 0, 8)))
+
+
+def test_hit_merge_from_mirror():
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"b": ([0, 1, 2], 8, 4)}, new_hits={"b": 8}, finished=["a"])
+    outs = mgr.materialize(s2, ["b"])
+    merged = outs.hidden_states["b"]
+    assert merged.shape == (12, HIDDEN)
+    assert torch.equal(merged[:8], expected_rows(view.slots_for("b", 0, 8)))
+    assert torch.equal(merged[8:], expected_rows(view.slots_for("b", 8, 12)))
+
+
+@pytest.mark.parametrize("a_finished_before_b", [False, True])
+def test_partial_match_hits_shared_prefix_and_writes_divergent_block(a_finished_before_b):
+    """`a` occupies [0, 1, 2]; `b` shares the first two blocks and diverges on
+    the third ([0, 1, 3]). `b` must merge 8 hit rows from the shared blocks
+    plus its own 4 rows, land block 3 in the pool, and leave `a`'s block 2
+    untouched — whether `a` already finished or is still running."""
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0, 1, 2], 0, 12)})
+    mgr.materialize(s1, ["a"])
+    a_tail = view.slots_for("a", 8, 12)
+    assert torch.equal(plan_fetch(mgr, a_tail, HIDDEN_KEY, req_id="a"), expected_rows(a_tail))
+
+    finished = ["a"] if a_finished_before_b else ()
+    s2 = run_step(mgr, view, {"b": ([0, 1, 3], 8, 4)}, new_hits={"b": 8}, finished=finished)
+    outs = mgr.materialize(s2, ["b"])
+    merged = outs.hidden_states["b"]
+    assert merged.shape == (12, HIDDEN)
+    assert torch.equal(merged[:8], expected_rows(view.slots_for("b", 0, 8)))
+    assert torch.equal(merged[8:], expected_rows(view.slots_for("b", 8, 12)))
+    # Divergent third block landed; the shared prefix and a's own tail did not move.
+    b_tail = view.slots_for("b", 8, 12)
+    assert torch.equal(plan_fetch(mgr, b_tail, HIDDEN_KEY, req_id="b"), expected_rows(b_tail))
+    assert torch.equal(plan_fetch(mgr, a_tail, HIDDEN_KEY, req_id="a"), expected_rows(a_tail))
+    shared = view.slots_for("a", 0, 8)
+    assert torch.equal(plan_fetch(mgr, shared, HIDDEN_KEY, req_id="a"), expected_rows(shared))
+
+    if not a_finished_before_b:
+        # `a` finishes later; releasing its task must not disturb b's rows.
+        s3 = run_step(mgr, view, {"b": ([0, 1, 3, 4], 12, 1)}, finished=["a"])
+        mgr.materialize(s3, ["b"])
+        assert torch.equal(plan_fetch(mgr, b_tail, HIDDEN_KEY, req_id="b"), expected_rows(b_tail))
+
+
+def test_live_req_reentering_new_reqs_is_not_a_hit():
+    """async_chunk continuation: the same id re-enters scheduled_new_reqs with
+    num_computed_tokens equal to what it computed itself. No hit span is
+    opened and materialize returns only this step's rows (parity with the
+    pre-refactor cache; a delivered_upto span is Phase 2). Once the id has
+    finished, the same id is a new request again and its hit is merged."""
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)})
+    mgr.materialize(s1, ["a"])
+
+    # Next chunk arrives: `a` is scheduled again as a "new" request at 8.
+    s2 = run_step(mgr, view, {"a": ([0, 1, 2], 8, 4)}, new_hits={"a": 8})
+    assert not mgr._step_ctxs[s2].hits
+    outs = mgr.materialize(s2, ["a"])
+    assert torch.equal(outs.hidden_states["a"], expected_rows(view.slots_for("a", 8, 12)))
+
+    # `a` finishes; a later request reusing the id is new and does hit.
+    s3 = run_step(mgr, view, {"b": ([3], 0, 2)}, finished=["a"])
+    mgr.materialize(s3, ["b"])
+    s4 = run_step(mgr, view, {"a": ([0, 1, 4], 8, 4)}, new_hits={"a": 8}, finished=["b"])
+    assert mgr._step_ctxs[s4].hits == {"a": (8, [0, 1])}
+    outs = mgr.materialize(s4, ["a"])
+    assert outs.hidden_states["a"].shape == (12, HIDDEN)
+    assert torch.equal(outs.hidden_states["a"][:8], expected_rows(view.slots_for("a", 0, 8)))
+
+
+def test_join_next_step_hit_waits_done_then_reads_pool():
+    """CPU stand-in for the non-eager path: dispatch holds the task instead of
+    writing the pool. A same-step hit must join(done), drain, then read the pool."""
+    mgr, view = make_manager()
+    real_run = mgr._controller._run_eager
+    real_join = mgr._controller.join
+
+    def join_then_scatter(tids):
+        # Stand-in committer: the write lands only when someone joins it.
+        for tid in tids:
+            task = mgr._controller.get_task(tid)
+            if task is not None and not task.done.is_set():
+                real_run(task)
+        real_join(tids)
+
+    mgr._controller.dispatch = lambda tasks: None
+    mgr._controller.join = join_then_scatter
+
+    view.req_blocks["a"] = [0, 1]
+    sid = run_step(
+        mgr,
+        view,
+        {"a": ([0, 1], 0, 8), "b": ([0, 1, 2], 8, 4)},
+        new_hits={"b": 8},
     )
-    cache.commit_deferred_mm_outputs({"req1"}, input_batch)
-
-    new_codes = torch.tensor([[99, 100]], dtype=torch.long)
-    cache.add_prefix_cached_new_req_id("req1")
-    merged = cache.get_merged_multimodal_states(
-        query_start_loc=torch.tensor([0, 1], dtype=torch.long),
-        input_batch=input_batch,
-        multimodal_outputs={mm_key: new_codes},
-        num_scheduled_tokens={"req1": 1, "req2": 0},
+    outs = mgr.materialize(sid, ["a", "b"])
+    assert torch.equal(outs.hidden_states["b"][:8], expected_rows(view.slots_for("b", 0, 8)))
+    slots = view.slots_for("a", 0, 8)
+    assert torch.equal(mgr._pool.rows(HIDDEN_KEY, slots), expected_rows(slots))
+
+
+def test_same_step_hit_reads_in_transit():
+    mgr, view = make_manager()
+    view.req_blocks["a"] = [0, 1]
+    sid = run_step(
+        mgr,
+        view,
+        {"a": ([0, 1], 0, 8), "b": ([0, 1, 2], 8, 4)},
+        new_hits={"b": 8},
     )
-
-    assert torch.equal(merged[mm_key]["req1"], torch.cat([cached_codes, new_codes], dim=0))
-
-
-### Tests for Merging
-def fake_get_cached_block_ids(self, req_idx, *args, **kwargs):
-    """Fake block table lookup.
-
-    Assumption:
-        req_idx 0 is a cache hit with slots 8, 9, ..., 15
-        req_idx 1 is a cache miss
+    outs = mgr.materialize(sid, ["a", "b"])
+    assert torch.equal(outs.hidden_states["b"][:8], expected_rows(view.slots_for("b", 0, 8)))
+
+
+def test_absent_hit_fails_fast():
+    mgr, view = make_manager()
+    view.req_blocks["c"] = [5, 6]
+    sid = run_step(mgr, view, {"c": ([5, 6, 7], 8, 4)}, new_hits={"c": 8})
+    d2h = mgr._step_ctxs[sid].d2h
+    with pytest.raises(OmniPrefixCacheUnmatchError):
+        mgr.materialize(sid, ["c"])
+    if d2h is not None:
+        assert not mgr._controller._staging_pool._busy[d2h.staging_slot]
+
+
+def test_hit_not_block_aligned_fails_at_register():
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)})
+    mgr.materialize(s1, ["a"])
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="prefix hit not block aligned"):
+        run_step(mgr, view, {"b": ([0, 1, 2], 8, 4)}, new_hits={"b": 6})
+
+
+def test_mm_cached_key_merge():
+    mgr, view = make_manager()
+    feat = 3
+    mm1 = {"talker.h": torch.arange(8 * feat, dtype=DTYPE).reshape(8, feat)}
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)}, mm=mm1)
+    mgr.materialize(s1, ["a"])
+    mm2 = {"talker.h": torch.full((4, feat), 7.0)}
+    s2 = run_step(mgr, view, {"b": ([0, 1, 2], 8, 4)}, new_hits={"b": 8}, finished=["a"], mm=mm2)
+    outs = mgr.materialize(s2, ["b"])
+    merged = outs.mm_outputs["talker.h"]["b"]
+    assert merged.shape == (12, feat)
+    assert torch.equal(merged[:8], mm1["talker.h"])
+    assert torch.equal(merged[8:], mm2["talker.h"])
+
+
+def test_codes_audio_matches_ordinary_mm_key():
+    """Without a deferred policy, codes.audio is an ordinary mm key (dim0 = tokens)."""
+    mgr, view = make_manager()
+    step1 = torch.arange(8 * 2, dtype=DTYPE).reshape(8, 2)
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)}, mm={"codes.audio": step1})
+    assert torch.equal(mgr.materialize(s1, ["a"]).mm_outputs["codes.audio"]["a"], step1)
+    step2 = torch.full((4, 2), 7.0)
+    s2 = run_step(mgr, view, {"b": ([0, 1, 2], 8, 4)}, new_hits={"b": 8}, finished=["a"], mm={"codes.audio": step2})
+    merged = mgr.materialize(s2, ["b"]).mm_outputs["codes.audio"]["b"]
+    assert torch.equal(merged, torch.cat([step1, step2], dim=0))
+
+
+def test_unpadded_mm_registers_on_padded_step():
+    """Qwen3-TTS codes.audio is scheduled-length; cudagraph makes padded > n.
+
+    Immediate-only `shape[0] == padded` would skip ensure_key, drop the
+    rows into leftover, and silently serve hits without a cached prefix.
     """
-    assert req_idx < 2
-    if req_idx == 0:
-        # With the slot offset we provided (8), the corresponding
-        # blocks IDs are 2 & 3 because the block size is 4.
-        return torch.tensor([2, 3], dtype=torch.long)
-    return torch.tensor([], dtype=torch.long)
-
-
-@pytest.mark.parametrize("num_tokens_padded", [None, 16])
-def test_get_merged_hidden_states(num_tokens_padded, mocker):
-    """Ensure that hidden states are merged correctly."""
-    cache = get_omni_pcache()
-
-    orig_num_tokens_unpadded = 8
-    slot_offset = 8  # We'll put our states in slots 8, 9, 10, ..., 15
-    orig_slot_mapping = torch.arange(slot_offset, slot_offset + orig_num_tokens_unpadded)
-    orig_hidden_states = torch.rand((orig_num_tokens_unpadded, HIDDEN_SIZE), dtype=DTYPE)
-
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=orig_hidden_states,
-        multimodal_outputs=None,
-        num_tokens_unpadded=orig_num_tokens_unpadded,
-        slot_mapping=orig_slot_mapping,
-        num_tokens_padded=num_tokens_padded,
+    mgr, view = make_manager()
+    audio = torch.arange(8 * 2, dtype=DTYPE).reshape(8, 2)
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)}, mm={"codes.audio": audio}, num_tokens_padded=16)
+    assert mgr._pool.has_key("codes.audio")
+    assert "codes.audio" not in mgr._step_ctxs[s1].mm_cpu_snapshot
+    assert torch.equal(mgr.materialize(s1, ["a"]).mm_outputs["codes.audio"]["a"], audio)
+    s2 = run_step(
+        mgr,
+        view,
+        {"b": ([0, 1, 2], 8, 4)},
+        new_hits={"b": 8},
+        finished=["a"],
+        mm={"codes.audio": torch.full((4, 2), 3.0)},
+        num_tokens_padded=16,
     )
-
-    # Say that we have two requests, but only one of them is a cache hit
-    num_new_toks_req1 = 3
-    num_new_toks_req2 = 2
-    cache.add_prefix_cached_new_req_id("req1")
-
-    num_scheduled_tokens = {
-        "req1": num_new_toks_req1,
-        "req2": num_new_toks_req2,
+    merged = mgr.materialize(s2, ["b"]).mm_outputs["codes.audio"]["b"]
+    assert torch.equal(merged[:8], audio)
+    assert torch.equal(merged[8:], torch.full((4, 2), 3.0))
+
+
+def test_split_step_outputs_routes_immediate_deferred_leftover():
+    """One split: immediate device→host, deferred write + leftover read, leftover only."""
+    policy = ModelCachePolicy(needs_full_hidden_states=True, deferred_keys=frozenset({"codes.audio"}))
+    mgr, view = make_manager(policy=policy)
+    view.order = ["a"]
+    view.req_blocks["a"] = [0]
+    view.computed["a"] = 0
+    n = 4
+    mgr.new_step_starts(FakeSchedOut(new_reqs=[FakeNewReq("a")], num_scheduled={"a": n}))
+    hidden = torch.ones(n, HIDDEN)
+    mm = {
+        "codes.audio": torch.full((n, 2), 5.0),
+        "codes.ref": torch.zeros(15, 2),
+        "tok": torch.full((n, 2), 7.0),
     }
-    new_hidden_states = torch.rand(
-        (num_new_toks_req1 + num_new_toks_req2, HIDDEN_SIZE),
-        dtype=DTYPE,
-    )
-    req1_new_states = new_hidden_states[:num_new_toks_req1]
-    req2_new_states = new_hidden_states[-num_new_toks_req2:]
-
-    input_batch = MockInputBatch(num_computed_tokens_cpu=torch.Tensor([orig_num_tokens_unpadded, 0]))
-
-    mocker.patch(
-        "vllm_omni.core.prefix_cache.OmniTensorPrefixCache._get_cached_block_ids",
-        new=fake_get_cached_block_ids,
-    )
-    merged_states = cache.get_merged_hidden_states(
-        query_start_loc=[0, num_new_toks_req1],
-        input_batch=input_batch,
-        hidden_states=new_hidden_states,
-        num_scheduled_tokens=num_scheduled_tokens,
+    step_outputs = mgr._split_step_outputs(
+        hidden,
+        mm,
+        n,
+        n,
+        slots_cpu=view.step_slots_cpu(["a"], {"a": n}),
+        req_order=["a"],
+        num_sched={"a": n},
+        query_start={"a": 0},
     )
+    assert HIDDEN_KEY in step_outputs.immediate and "tok" in step_outputs.immediate
+    assert "codes.audio" not in step_outputs.immediate and "codes.ref" not in step_outputs.immediate
+    assert "codes.audio" in step_outputs.leftover and "codes.ref" in step_outputs.leftover
+    assert "tok" not in step_outputs.leftover
+    assert len(step_outputs.deferred_chunks) == 1
+    assert step_outputs.deferred_chunks[0][0] == "a"
+    assert "codes.audio" in step_outputs.deferred_chunks[0][1].tensors
 
-    assert "req1" in merged_states and "req2" in merged_states
-    req1_merged_states = merged_states["req1"]
-    req2_merged_states = merged_states["req2"]
-
-    # First, check the cache hit case
-    assert req1_merged_states.shape == torch.Size([orig_num_tokens_unpadded + num_new_toks_req1, HIDDEN_SIZE])
-    # Ensure that the req1 merged states are the cached states + the new req1 states
-    assert torch.all(req1_merged_states[:orig_num_tokens_unpadded] == orig_hidden_states)
-    assert torch.all(req1_merged_states[-num_new_toks_req1:] == req1_new_states)
-
-    # Next, ensure that the cache miss case only has the new states
-    assert req2_merged_states.shape == torch.Size([num_new_toks_req2, HIDDEN_SIZE])
-    assert torch.all(req2_merged_states == req2_new_states)
-
-
-def test_get_merged_hidden_states_uses_precomputed_hidden_states_cpu(mocker):
-    cache = get_omni_pcache()
 
-    orig_num_tokens_unpadded = 8
-    slot_offset = 8
-    orig_slot_mapping = torch.arange(slot_offset, slot_offset + orig_num_tokens_unpadded)
-    orig_hidden_states = torch.rand((orig_num_tokens_unpadded, HIDDEN_SIZE), dtype=DTYPE)
+def test_leftover_snapshot_preserves_non_token_major_shapes():
+    """P1: leftover copy must not use `shape[0] >= n` as a slice predicate.
 
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=orig_hidden_states,
-        multimodal_outputs=None,
-        num_tokens_unpadded=orig_num_tokens_unpadded,
-        slot_mapping=orig_slot_mapping,
-    )
-
-    num_new_toks_req1 = 3
-    num_new_toks_req2 = 2
-    cache.add_prefix_cached_new_req_id("req1")
-    num_scheduled_tokens = {
-        "req1": num_new_toks_req1,
-        "req2": num_new_toks_req2,
+    Tensors whose first dim is this step's token count (`shape[0] == n`)
+    may be sliced; every other tensor — including `codes.ref` with
+    ref_len >> n, and list-held tensors — must keep the input shape.
+    """
+    n = 4
+    mm = {
+        "codes.ref": torch.arange(30, dtype=DTYPE).reshape(15, 2),
+        "tags": [torch.ones(3, 5), torch.zeros(7)],
+        "tokenish": torch.arange(n * 2, dtype=DTYPE).reshape(n, 2),
+        "scalar": torch.tensor(3.0),
     }
-    new_hidden_states = torch.zeros(
-        (num_new_toks_req1 + num_new_toks_req2, HIDDEN_SIZE),
-        dtype=DTYPE,
-    )
-    hidden_states_cpu = torch.rand_like(new_hidden_states)
-    req1_new_states = hidden_states_cpu[:num_new_toks_req1]
-    req2_new_states = hidden_states_cpu[-num_new_toks_req2:]
-    input_batch = MockInputBatch(num_computed_tokens_cpu=torch.Tensor([orig_num_tokens_unpadded, 0]))
-
-    mocker.patch(
-        "vllm_omni.core.prefix_cache.OmniTensorPrefixCache._get_cached_block_ids",
-        new=fake_get_cached_block_ids,
-    )
-    merged_states = cache.get_merged_hidden_states(
-        query_start_loc=[0, num_new_toks_req1],
-        input_batch=input_batch,
-        hidden_states=new_hidden_states,
-        hidden_states_cpu=hidden_states_cpu,
-        num_scheduled_tokens=num_scheduled_tokens,
-    )
-
-    assert torch.all(merged_states["req1"][:orig_num_tokens_unpadded] == orig_hidden_states)
-    assert torch.all(merged_states["req1"][-num_new_toks_req1:] == req1_new_states)
-    assert torch.all(merged_states["req2"] == req2_new_states)
-
-
-def test_get_merged_hidden_states_rejects_short_hidden_states_cpu(mocker):
-    cache = get_omni_pcache()
-    num_scheduled_tokens = {
-        "req1": 3,
-        "req2": 2,
+    out, event = _snapshot_leftover_mm_cpu(mm, set(), n)
+    assert event is None
+    _assert_leftover_shapes(mm, out, n)
+    assert torch.equal(out["codes.ref"], mm["codes.ref"])
+    assert out["codes.ref"].shape == (15, 2)
+
+
+@pytest.mark.skipif(not torch.cuda.is_available(), reason="CUDA leftover copy")
+def test_leftover_snapshot_cuda_is_pinned_and_event_ordered():
+    """CUDA leftover lands pinned via a non-blocking copy; values are exact once the event is waited."""
+    n = 4
+    mm = {
+        "codes.audio": torch.arange(n * 2, dtype=DTYPE, device="cuda").reshape(n, 2),
+        "codes.ref": torch.arange(30, dtype=DTYPE, device="cuda").reshape(15, 2),
+        "tags": [torch.ones(3, 5, device="cuda")],
     }
-    input_batch = MockInputBatch(num_computed_tokens_cpu=torch.Tensor([0, 0]))
-
-    mocker.patch(
-        "vllm_omni.core.prefix_cache.OmniTensorPrefixCache._get_cached_block_ids",
-        new=fake_get_cached_block_ids,
-    )
-    with pytest.raises(RuntimeError):
-        cache.get_merged_hidden_states(
-            query_start_loc=[0, 3],
-            input_batch=input_batch,
-            hidden_states=torch.rand((5, HIDDEN_SIZE), dtype=DTYPE),
-            hidden_states_cpu=torch.rand((4, HIDDEN_SIZE), dtype=DTYPE),
-            num_scheduled_tokens=num_scheduled_tokens,
+    out, event = _snapshot_leftover_mm_cpu(mm, set(), n)
+    assert event is not None
+    event.synchronize()
+    _assert_leftover_shapes(mm, out, n)
+    for t in (out["codes.audio"], out["codes.ref"], out["tags"][0]):
+        assert t.device.type == "cpu" and t.is_pinned()
+    assert torch.equal(out["codes.audio"], mm["codes.audio"].cpu())
+    assert torch.equal(out["codes.ref"], mm["codes.ref"].cpu())
+
+
+def test_codes_ref_matches_old_build_mm_cpu_path():
+    """Leftover `codes.ref` equals the old runner path: build_mm_cpu + to_payload_element."""
+    pytest.importorskip("vllm")
+    from vllm_omni.utils.mm_outputs import build_mm_cpu, to_payload_element
+
+    refs = [torch.arange(8, dtype=torch.long), torch.arange(12, dtype=torch.long)]
+    mgr, view = make_manager()
+    sid = run_step(mgr, view, {"a": ([0], 0, 2), "b": ([1], 0, 2)}, mm={"codes.ref": refs})
+    ctx = mgr._step_ctxs[sid]
+    assert "codes.ref" in ctx.mm_cpu_snapshot
+    assert [t.shape for t in ctx.mm_cpu_snapshot["codes.ref"]] == [t.shape for t in refs]
+    outs = mgr.materialize(sid, ["a", "b"])
+    old = build_mm_cpu({"codes.ref": refs})
+    total = 4
+    for req_id, idx, start, end in (("a", 0, 0, 2), ("b", 1, 2, 4)):
+        want = to_payload_element(old["codes.ref"], idx, start=start, end=end, pass_lists_through=True, seq_len=total)
+        got = outs.mm_outputs["codes.ref"][req_id]
+        assert len(got) == len(want)
+        for g, w in zip(got, want):
+            assert torch.equal(g, w)
+
+
+def test_is_step_token_tensor():
+    n, padded = 4, 8
+    assert _is_step_token_tensor(torch.zeros(n, 2), n, padded)
+    assert _is_step_token_tensor(torch.zeros(padded, 2), n, padded)
+    assert not _is_step_token_tensor([torch.zeros(1, 8)], n, padded)
+    assert not _is_step_token_tensor(torch.zeros(15, 2), n, padded)
+    assert not _is_step_token_tensor(torch.tensor([1, 2, 3]), n, padded)
+
+
+def test_policy_from_model_shim():
+    class M:
+        requires_full_prefix_cached_hidden_states = False
+        deferred_prefix_cache_mm_keys = {"codes.audio"}
+
+    p = ModelCachePolicy.from_model(M())
+    assert p.needs_full_hidden_states is False
+    assert p.hidden_key is None
+    assert p.deferred_keys == frozenset({"codes.audio"})
+    assert p.get_hit_keys([HIDDEN_KEY, "codes.audio"]) == ["codes.audio"]
+    assert p.skip_immediate_mm("codes.audio")
+    d = ModelCachePolicy.from_model(object())
+    assert d.needs_full_hidden_states is True and not d.deferred_keys
+    assert d.hidden_key == HIDDEN_KEY
+    assert d.get_hit_keys(["talker.h", HIDDEN_KEY]) == [HIDDEN_KEY, "talker.h"]
+
+
+def test_deferred_key_accumulates_and_flushes_on_finish():
+    policy = ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"codes.audio"}))
+    mgr, view = make_manager(policy=policy)
+    feat = 2
+    for pos in range(2):
+        sid = run_step(
+            mgr,
+            view,
+            {"a": ([3], pos, 1)},
+            mm={"codes.audio": torch.full((1, feat), float(pos + 1))},
         )
-
-
-@pytest.mark.parametrize("num_tokens_padded", [None, 16])
-@pytest.mark.parametrize(
-    "feat_dims",
-    [
-        {"foo": 100, "bar": 100},
-        {"foo": 100, "bar": 50, "baz": 10},
-    ],
-)
-def test_get_merged_multimodal_outputs(feat_dims, num_tokens_padded, mocker):
-    cache = get_omni_pcache_with_mm_tensors(feat_dims, seq_len=DEFAULT_SEQ_LEN)
-
-    orig_num_tokens_unpadded = 8
-    slot_offset = 8  # We'll put our states in slots 8, 9, 10, ..., 15
-    orig_slot_mapping = torch.arange(slot_offset, slot_offset + orig_num_tokens_unpadded)
-    feature_dims = {key: val.shape[-1] for key, val in cache.mm_outputs_cache.items()}
-    orig_mm_outputs = {
-        key: torch.rand((orig_num_tokens_unpadded, feature_dims[key]), dtype=DTYPE) for key in cache.mm_cache_keys
-    }
-
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=None,
-        multimodal_outputs=orig_mm_outputs,
-        num_tokens_unpadded=orig_num_tokens_unpadded,
-        slot_mapping=orig_slot_mapping,
-        num_tokens_padded=num_tokens_padded,
+        mgr.materialize(sid, ["a"])
+    slots = view.slots_for("a", 0, 2)
+    rows = plan_fetch(mgr, slots, "codes.audio", req_id="a")
+    assert torch.equal(rows[:, 0], torch.tensor([1.0, 2.0]))
+    sid = run_step(mgr, view, {"z": ([9], 0, 1)}, finished=["a"])
+    mgr.materialize(sid, ["z"])
+    mirror = mgr._pool.rows("codes.audio", slots)
+    assert torch.equal(mirror[:, 0], torch.tensor([1.0, 2.0]))
+
+
+def test_deferred_gpu_bytes_held_until_last_view_drops():
+    """Shared deferred clone is one allocation; finishing the first
+    co-scheduled request must not drop ``_staged_bytes`` while the other
+    still pins it."""
+    policy = ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    feat = 2
+    n = 4
+    s1 = run_step(
+        mgr,
+        view,
+        {"a": ([0], 0, 2), "b": ([1], 0, 2)},
+        mm={"k": torch.zeros(n, feat)},
     )
-
-    # Similar to hs test- say that we have two requests, but only one of them is a cache hit
-    num_new_toks_req1 = 3
-    num_new_toks_req2 = 2
-    cache.add_prefix_cached_new_req_id("req1")
-
-    num_scheduled_tokens = {
-        "req1": num_new_toks_req1,
-        "req2": num_new_toks_req2,
-    }
-
-    new_mm_outputs = {}
-    for mm_key in cache.mm_cache_keys:
-        new_mm_outputs[mm_key] = torch.rand(
-            (num_new_toks_req1 + num_new_toks_req2, feature_dims[mm_key]),
-            dtype=DTYPE,
-        )
-    # We also want to make sure passthrough data (outside of our keys) isn't dropped
-    new_mm_outputs["passthrough_data"] = "Something else"
-    # Lists are a special case because we can't split them yet if we want to match
-    # the nonprefix cache behavior, because this runs before post process.
-    new_mm_outputs["passthrough_list"] = ["should", "not", "split"]
-
-    input_batch = MockInputBatch(num_computed_tokens_cpu=torch.Tensor([orig_num_tokens_unpadded, 0]))
-
-    mocker.patch(
-        "vllm_omni.core.prefix_cache.OmniTensorPrefixCache._get_cached_block_ids",
-        new=fake_get_cached_block_ids,
-    )
-    merged_mm_outputs = cache.get_merged_multimodal_states(
-        query_start_loc=[0, num_new_toks_req1],
-        input_batch=input_batch,
-        multimodal_outputs=new_mm_outputs,
-        num_scheduled_tokens=num_scheduled_tokens,
+    mgr.materialize(s1, ["a", "b"])
+    clone_bytes = n * feat * 4  # float32
+    assert mgr._controller._staged_bytes == clone_bytes
+    s2 = run_step(mgr, view, {"z": ([9], 0, 1)}, finished=["a"])
+    mgr.materialize(s2, ["z"])
+    assert mgr._controller._staged_bytes == clone_bytes
+    s3 = run_step(mgr, view, {"z2": ([9], 1, 1)}, finished=["b"])
+    mgr.materialize(s3, ["z2"])
+    assert mgr._controller._staged_bytes == 0
+
+
+def test_cap_forces_flush_of_deferred():
+    """One long request's deferred clone must not pin the whole budget:
+    the flush closes its open task and the next step opens a new one."""
+    policy = ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy, gpu_staging_bytes=48)  # three (1, 4) fp32 chunks
+    for pos in range(4):
+        sid = run_step(mgr, view, {"a": ([2, 3], pos, 1)}, mm={"k": torch.full((1, 4), float(pos + 1))})
+        mgr.materialize(sid, ["a"])
+    # Fourth chunk flushed the first three; only it is still charged.
+    assert mgr._controller._staged_bytes == 16
+    rows = mgr._pool.rows("k", view.slots_for("a", 0, 4))[:, 0].tolist()
+    assert rows == [1.0, 2.0, 3.0, 0.0]
+    assert mgr._request_tasks.deferred["a"].write_n == 2
+    assert len(mgr._request_tasks.tasks["a"]) == 1  # the flushed write was drained
+
+
+def test_deferred_tenant_succession_no_stale_wins():
+    policy = ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    s1 = run_step(mgr, view, {"a": ([2], 0, 2)}, mm={"k": torch.full((2, 2), 1.0)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"b": ([2], 0, 2)}, mm={"k": torch.full((2, 2), 2.0)})
+    mgr.materialize(s2, ["b"])
+    slots = view.slots_for("b", 0, 2)
+    s3 = run_step(mgr, view, {"z1": ([9], 0, 1)}, finished=["b"])
+    mgr.materialize(s3, ["z1"])
+    s4 = run_step(mgr, view, {"z2": ([9], 1, 1)}, finished=["a"])
+    mgr.materialize(s4, ["z2"])
+    assert torch.equal(mgr._pool.rows("k", slots), torch.full((2, 2), 2.0))
+
+
+def test_reacquired_slot_deferred_rewrite_wins_over_interim_tenant():
+    """Preempt + resume onto the same block: the rewrite must open a new
+    write, or the old task's reassigned tombstone drops the fresh rows and
+    the interim tenant's stale value is served as a's."""
+    policy = ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    s1 = run_step(mgr, view, {"a": ([2], 0, 1)}, mm={"k": torch.full((1, 2), 11.0)})
+    mgr.materialize(s1, ["a"])
+    slots = view.slots_for("a", 0, 1)
+    s2 = run_step(mgr, view, {"b": ([2], 0, 1)}, mm={"k": torch.full((1, 2), 22.0)})
+    mgr.materialize(s2, ["b"])
+    s3 = run_step(mgr, view, {"z": ([9], 0, 1)}, finished=["b"])  # 22 committed
+    mgr.materialize(s3, ["z"])
+    s4 = run_step(mgr, view, {"a": ([2], 0, 1)}, mm={"k": torch.full((1, 2), 33.0)})  # a re-claims
+    mgr.materialize(s4, ["a"])
+    s5 = run_step(mgr, view, {"z2": ([9], 1, 1)}, finished=["a"])  # flush a's write
+    mgr.materialize(s5, ["z2"])
+    assert torch.equal(mgr._pool.rows("k", slots), torch.full((1, 2), 33.0))
+
+
+def test_deferred_key_hit_reads_staged_rows_not_mirror():
+    policy = ModelCachePolicy(needs_full_hidden_states=True, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    s1 = run_step(mgr, view, {"a": ([0], 0, 4)}, mm={"k": torch.full((4, 2), 1.0)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"b": ([0, 1], 4, 2)}, new_hits={"b": 4}, mm={"k": torch.full((2, 2), 9.0)})
+    rows = mgr.materialize(s2, ["b"]).mm_outputs["k"]["b"]
+    assert torch.equal(rows[:4], torch.full((4, 2), 1.0)), rows
+    assert torch.equal(rows[4:], torch.full((2, 2), 9.0))
+
+
+def test_append_to_closed_deferred_entry_opens_new_one():
+    """A deferred task closed by the budget flush (or an early escalate)
+    cannot take more chunks; the next save opens a new write and a hit
+    reads both."""
+    policy = ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    s1 = run_step(mgr, view, {"a": ([2], 0, 1)}, mm={"k": torch.full((1, 2), 1.0)})
+    mgr.materialize(s1, ["a"])
+    first = mgr._request_tasks.deferred["a"]
+    mgr._controller.escalate([first.tid])
+    s2 = run_step(mgr, view, {"a": ([2], 1, 1)}, mm={"k": torch.full((1, 2), 2.0)})
+    mgr.materialize(s2, ["a"])
+    assert mgr._request_tasks.deferred["a"].tid != first.tid
+    slots = view.slots_for("a", 0, 2)
+    rows = plan_fetch(mgr, slots, "k", req_id="a")
+    assert torch.equal(rows[:, 0], torch.tensor([1.0, 2.0]))
+
+
+def test_deferred_unpadded_registers_on_padded_step():
+    """Qwen3-TTS: deferred codes.audio is unpadded; cudagraph pads hidden."""
+    policy = ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"codes.audio"}))
+    mgr, view = make_manager(policy=policy)
+    audio = torch.arange(8 * 2, dtype=DTYPE).reshape(8, 2)
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)}, mm={"codes.audio": audio}, num_tokens_padded=16)
+    assert mgr._pool.has_key("codes.audio")
+    assert "codes.audio" in mgr._step_ctxs[s1].mm_cpu_snapshot
+    rows = plan_fetch(mgr, view.slots_for("a", 0, 8), "codes.audio", req_id="a")
+    assert torch.equal(rows, audio)
+    outs = mgr.materialize(s1, ["a"])
+    assert torch.equal(outs.mm_outputs["codes.audio"]["a"], audio)
+
+
+def test_check_kv_groups_rejects_empty_or_multi():
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="single full-attention"):
+        check_prefix_cache_kv_groups([])
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="single full-attention"):
+        check_prefix_cache_kv_groups([object(), object()])
+
+
+def _stage_cfg(*, enable=True, pooling=False, kv_transfer=None, groups=(object(),), spec=None, match_unit=None):
+    return stage_prefix_cache_config(
+        kv_cache_config=SimpleNamespace(num_blocks=NUM_BLOCKS, kv_cache_groups=list(groups)),
+        cache_config=SimpleNamespace(enable_prefix_caching=enable, block_size=BLOCK_SIZE, prefix_match_unit=match_unit),
+        kv_transfer_config=kv_transfer,
+        scheduler_config=SimpleNamespace(max_num_batched_tokens=64, max_model_len=128),
+        model_config=None,
+        is_pooling_model=pooling,
+        speculative_config=spec,
     )
 
-    # Ensure the passthrough data wasn't dropped
-    assert "passthrough_data" in merged_mm_outputs
-    assert "passthrough_list" in merged_mm_outputs
-
-    for mm_key, mm_output in merged_mm_outputs.items():
-        # Ensure passthrough data is just forwarded normally and not duplicated
-        assert isinstance(mm_output, dict)
-        assert "req1" in mm_output and "req2" in mm_output
-        if mm_key == "passthrough_data":
-            assert mm_key not in cache.mm_cache_keys
-            assert new_mm_outputs[mm_key] == mm_output["req1"]
-            assert new_mm_outputs[mm_key] == mm_output["req2"]
-        elif mm_key == "passthrough_list":
-            assert mm_key not in cache.mm_cache_keys
-            assert new_mm_outputs[mm_key] == mm_output["req1"]
-            assert new_mm_outputs[mm_key] == mm_output["req2"]
-        else:
-            assert mm_key in cache.mm_cache_keys
-            curr_feat_dim = feature_dims[mm_key]
-            # Ensure that req1 (cache hit) merged the mm data
-            req1_merged_mm_outputs = mm_output["req1"]
-            req1_new_mm_outputs = new_mm_outputs[mm_key][:num_new_toks_req1]
-
-            assert req1_merged_mm_outputs.shape == torch.Size(
-                [orig_num_tokens_unpadded + num_new_toks_req1, curr_feat_dim]
-            )
-            # Ensure that the req1 merged mm data are the cached data + the new data
-            assert torch.all(req1_merged_mm_outputs[:orig_num_tokens_unpadded] == orig_mm_outputs[mm_key])
-            assert torch.all(req1_merged_mm_outputs[-num_new_toks_req1:] == req1_new_mm_outputs)
-
-            # Ensure that req2 (cache miss) only has the new mm data
-            req2_merged_mm_outputs = mm_output["req2"]
-            req2_new_mm_outputs = new_mm_outputs[mm_key][-num_new_toks_req2:]
-
-            assert req2_merged_mm_outputs.shape == torch.Size([num_new_toks_req2, curr_feat_dim])
-            assert torch.all(req2_merged_mm_outputs == req2_new_mm_outputs)
-
-
-@pytest.mark.parametrize(
-    "passthrough_shape",
-    [(5,), (5, 3)],
-    ids=["1d_token_metadata", "2d_feature_tensor"],
-)
-def test_get_merged_multimodal_outputs_slices_passthrough_tensor_per_request(passthrough_shape, mocker):
-    """A passthrough key that is itself a real tensor (not the string/list
-    passthrough already covered above) must be sliced per request through
-    to_payload_element's tensor branch, under the same mixed cache
-    hit/miss + uneven scheduled-length batch as test_get_merged_multimodal_outputs.
-
-    Covers both a 1D token-aligned metadata tensor (e.g. ref_code_len,
-    codec_streaming -- shape (total_tokens,)) and a 2D per-token feature
-    tensor (shape (total_tokens, feat_dim)), since W2's batching could
-    easily special-case one and silently mishandle the other.
-    """
-    feat_dims = {"foo": 100, "bar": 100}
-    cache = get_omni_pcache_with_mm_tensors(feat_dims, seq_len=DEFAULT_SEQ_LEN)
-
-    orig_num_tokens_unpadded = 8
-    slot_offset = 8
-    orig_slot_mapping = torch.arange(slot_offset, slot_offset + orig_num_tokens_unpadded)
-    feature_dims = {key: val.shape[-1] for key, val in cache.mm_outputs_cache.items()}
-    orig_mm_outputs = {
-        key: torch.rand((orig_num_tokens_unpadded, feature_dims[key]), dtype=DTYPE) for key in cache.mm_cache_keys
-    }
 
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=None,
-        multimodal_outputs=orig_mm_outputs,
-        num_tokens_unpadded=orig_num_tokens_unpadded,
-        slot_mapping=orig_slot_mapping,
-        num_tokens_padded=None,
+def test_stage_prefix_cache_config_gate():
+    """The runner-side gate the GPU and NPU runners share: off / pooling
+    stages get no cache; kv_consumer, spec decode, sub-block matching and
+    hybrid groups refuse loudly."""
+    assert _stage_cfg(enable=False) is None
+    assert _stage_cfg(pooling=True) is None
+    # kv_consumer / kv_both refuse before the group check, on both platforms.
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="KV connector"):
+        _stage_cfg(kv_transfer=SimpleNamespace(is_kv_consumer=True), groups=())
+    assert _stage_cfg(kv_transfer=SimpleNamespace(is_kv_consumer=True), enable=False) is None
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="speculative decoding"):
+        _stage_cfg(spec=SimpleNamespace(method="ngram"), groups=())
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="block-aligned"):
+        _stage_cfg(match_unit=BLOCK_SIZE // 2, groups=())
+    # A unit equal to the block is a whole-block match; only the group check is left.
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="single full-attention"):
+        _stage_cfg(match_unit=BLOCK_SIZE, groups=())
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="single full-attention"):
+        _stage_cfg(groups=(object(), object()))
+
+
+def test_npu_runner_uses_shared_prefix_cache_gate():
+    """npu_model_runner cannot be imported without vllm_ascend; pin at the
+    source level that it stages through the shared gate instead of a
+    hand-rolled subset of the GPU checks."""
+    path = Path(__file__).resolve().parents[2] / "vllm_omni/platforms/npu/worker/npu_model_runner.py"
+    tree = ast.parse(path.read_text())
+    calls = {n.func.id for n in ast.walk(tree) if isinstance(n, ast.Call) and isinstance(n.func, ast.Name)}
+    assert "stage_prefix_cache_config" in calls
+    assert "check_prefix_cache_kv_groups" not in calls
+
+
+def _table_slots(table, req_idx, token_start, token_end, block_size=BLOCK_SIZE):
+    if token_end <= token_start:
+        return torch.empty((0,), dtype=torch.long)
+    token_positions = torch.arange(token_start, token_end, dtype=torch.long)
+    block_offsets = token_positions // block_size
+    max_blocks = int(table.shape[1])
+    valid = block_offsets < max_blocks
+    if not bool(valid.all()):
+        token_positions = token_positions[valid]
+        block_offsets = block_offsets[valid]
+    if token_positions.numel() == 0:
+        return torch.empty((0,), dtype=torch.long)
+    block_ids = table[req_idx, block_offsets].to(torch.long)
+    return block_ids * block_size + (token_positions % block_size)
+
+
+def test_group_view_step_slots_cpu():
+    class TensorWrap:
+        def __init__(self, t):
+            self.cpu = t
+
+    class Group:
+        def __init__(self, t):
+            self.block_table = TensorWrap(t)
+
+    class BT:
+        def __init__(self, t):
+            self._g = Group(t)
+            self.block_tables = [self._g.block_table]
+
+        def __getitem__(self, idx):
+            assert idx == 0
+            return self._g
+
+    class IB:
+        def __init__(self, table):
+            self.req_ids = ["r1", "r2"]
+            self.req_id_to_index = {"r1": 0, "r2": 1}
+            self.num_computed_tokens_cpu = torch.tensor([8, 0])
+            self.block_table = BT(table)
+
+    table = torch.tensor([[2, 5, 7], [1, 0, 0]])
+    view = FullAttentionGroupView(IB(table), block_size=BLOCK_SIZE)
+    assert view.step_slots_cpu(["r1"], {"r1": 2}).tolist() == [7 * 4 + 0, 7 * 4 + 1]
+    assert view.step_slots_cpu(["r1"], {"r1": 8}).tolist() == [7 * 4 + i for i in range(4)]
+    assert view.step_slots_cpu(["r1"], {"r1": 0}).numel() == 0
+
+
+def test_join_next_step_previous_save():
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0], 0, 2)})
+    assert len(mgr._join_next_step_tids) == 1
+    task_id = mgr._join_next_step_tids[0]
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"a": ([0], 2, 1)})
+    assert mgr._controller.get_task(task_id) is None
+    assert int(mgr._slot_status.state[HIDDEN_KEY][view.slots_for("a", 0, 2)].min()) == 2
+    mgr.materialize(s2, ["a"])
+
+
+def test_tenant_succession_hit_reads_newest():
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0], 0, 4)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"b": ([0], 0, 4)}, finished=["a"])
+    mgr.materialize(s2, ["b"])
+    b_hidden = expected_rows(view.slots_for("b", 0, 4))
+    s3 = run_step(mgr, view, {"c": ([0, 1], 4, 2)}, new_hits={"c": 4}, finished=["b"])
+    outs = mgr.materialize(s3, ["c"])
+    assert torch.equal(outs.hidden_states["c"][:4], b_hidden)
+
+
+def test_tenant_succession_mm_key():
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([2], 0, 4)}, mm={"k": torch.full((4, 2), 1.0)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"b": ([2], 0, 4)}, finished=["a"], mm={"k": torch.full((4, 2), 2.0)})
+    mgr.materialize(s2, ["b"])
+    s3 = run_step(
+        mgr, view, {"c": ([2, 3], 4, 2)}, new_hits={"c": 4}, finished=["b"], mm={"k": torch.full((2, 2), 3.0)}
     )
+    rows = mgr.materialize(s3, ["c"]).mm_outputs["k"]["c"]
+    assert torch.equal(rows[:4], torch.full((4, 2), 2.0))
+    assert torch.equal(rows[4:], torch.full((2, 2), 3.0))
 
-    num_new_toks_req1 = 3
-    num_new_toks_req2 = 2
-    cache.add_prefix_cached_new_req_id("req1")
 
-    num_scheduled_tokens = {
-        "req1": num_new_toks_req1,
-        "req2": num_new_toks_req2,
-    }
+def test_scatter_rows_coalesces_per_key_last_chunk_wins_and_skips_reassigned():
+    from vllm_omni.core.prefix_cache.controller import WriteSchedule, WriteTask, _BudgetTicket, _WriteChunk
 
-    new_mm_outputs = {}
-    for mm_key in cache.mm_cache_keys:
-        new_mm_outputs[mm_key] = torch.rand(
-            (num_new_toks_req1 + num_new_toks_req2, feature_dims[mm_key]),
-            dtype=DTYPE,
-        )
-    total_scheduled_tokens = num_new_toks_req1 + num_new_toks_req2
-    assert passthrough_shape[0] == total_scheduled_tokens
-    passthrough_tensor = torch.arange(int(torch.prod(torch.tensor(passthrough_shape))), dtype=DTYPE).reshape(
-        passthrough_shape
-    )
-    new_mm_outputs["passthrough_tensor"] = passthrough_tensor
+    t1, t2 = _BudgetTicket(nbytes=8), _BudgetTicket(nbytes=8)
 
-    input_batch = MockInputBatch(num_computed_tokens_cpu=torch.Tensor([orig_num_tokens_unpadded, 0]))
+    def chunk(slots, base, ticket):
+        s = torch.tensor(slots, dtype=torch.int64)
+        host = {"k": torch.full((len(slots), 2), float(base)) + s[:, None]}
+        return _WriteChunk(slots_cpu=s, tensors={}, host=host, budget=ticket)
 
-    mocker.patch(
-        "vllm_omni.core.prefix_cache.OmniTensorPrefixCache._get_cached_block_ids",
-        new=fake_get_cached_block_ids,
+    task = WriteTask(
+        tid=1,
+        req_id="a",
+        write_n=1,
+        schedule=WriteSchedule.JOIN_ON_FINISH,
+        chunks=[chunk([0, 1], 10, t1), chunk([2, 3], 20, t1), chunk([1, 4], 30, t2)],
     )
-    merged_mm_outputs = cache.get_merged_multimodal_states(
-        query_start_loc=[0, num_new_toks_req1],
-        input_batch=input_batch,
-        multimodal_outputs=new_mm_outputs,
-        num_scheduled_tokens=num_scheduled_tokens,
+    assert task.budget_tickets() == [t1, t2]
+    task.add_reassigned("k", torch.tensor([3], dtype=torch.int64))
+    rows = task.scatter_rows()
+    assert len(rows) == 1
+    key, slots, host = rows[0]
+    assert key == "k" and slots.tolist() == [0, 2, 1, 4]
+    # slot 1: the third chunk's row (base 30) replaces the first chunk's; slot 3 is reassigned.
+    assert host[:, 0].tolist() == [10.0, 22.0, 31.0, 34.0]
+
+
+def test_slot_reuse_pushes_skip_to_old_task():
+    """Reassignment = task swap. Keep the old write in progress so the
+    new write records those rows as no longer owned by it."""
+    mgr, view = make_manager()
+
+    def hold(tasks):
+        for task in tasks:
+            task.host_ready.set()
+            task.done.set()  # satisfy the next save's done barrier; state stays QUEUED
+
+    mgr._controller.dispatch = hold
+    policy = ModelCachePolicy(needs_full_hidden_states=False)
+    mgr.register_policy(policy)
+    s1 = run_step(mgr, view, {"a": ([2], 0, 1)}, mm={"k": torch.ones(1, 2)})
+    mgr.materialize(s1, ["a"])
+    old_tid = next(iter(mgr._request_tasks.tasks["a"]))
+    old_task = mgr._controller.get_task(old_tid)
+    s2 = run_step(mgr, view, {"b": ([2], 0, 2)}, mm={"k": torch.full((2, 2), 2.0)})
+    assert old_task is not None and "k" in old_task.reassigned
+    reused = view.slots_for("b", 0, 1)
+    assert bool(torch.isin(reused, old_task.reassigned["k"]).all())
+    mgr.materialize(s2, ["b"])
+
+
+def test_step_slots_cpu_matches_block_table_math():
+    class TensorWrap:
+        def __init__(self, t):
+            self.cpu = t
+
+    class Group:
+        def __init__(self, t):
+            self.block_table = TensorWrap(t)
+
+    class BT:
+        def __init__(self, t):
+            self._g = Group(t)
+            self.block_tables = [self._g.block_table]
+
+        def __getitem__(self, idx):
+            return self._g
+
+    class IB:
+        def __init__(self, table, computed):
+            self.req_ids = ["r1", "r2"]
+            self.req_id_to_index = {"r1": 0, "r2": 1}
+            self.num_computed_tokens_cpu = torch.tensor(computed)
+            self.block_table = BT(table)
+
+    table = torch.tensor([[2, 5, 7], [1, 3, 4]])
+    view = FullAttentionGroupView(IB(table, [4, 0]), block_size=BLOCK_SIZE)
+    num_sched = {"r1": 3, "r2": 5}
+    got = view.step_slots_cpu(["r1", "r2"], num_sched)
+    want = torch.cat([_table_slots(table, 0, 4, 7), _table_slots(table, 1, 0, 5)])
+    assert torch.equal(got, want), (got, want)
+    assert torch.equal(view.step_slots_cpu(["r1", "r2"], {"r1": 3, "r2": 0}), _table_slots(table, 0, 4, 7))
+
+
+def _ib_with_layout(**layout):
+    """InputBatch fake whose group-0 block table carries vLLM's layout attrs."""
+    attrs = dict(kv_cache_block_size=BLOCK_SIZE, blocks_per_kv_block=1, use_hybrid_blocks=False, dcp_world_size=1)
+    attrs.update(layout)
+    group = SimpleNamespace(block_table=SimpleNamespace(cpu=torch.zeros((1, 2), dtype=torch.int32)), **attrs)
+
+    class BT:
+        block_tables = [group.block_table]
+
+        def __getitem__(self, idx):
+            return group
+
+    return SimpleNamespace(req_ids=[], req_id_to_index={}, num_computed_tokens_cpu=torch.zeros(1), block_table=BT())
+
+
+def test_group_view_refuses_hybrid_kernel_blocks_and_dcp():
+    """step_slots_cpu assumes one allocator block per table column and no
+    token striping; both are silent wrong-slot writes if not refused."""
+    FullAttentionGroupView(_ib_with_layout(), block_size=BLOCK_SIZE)
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="kernel_block_size"):
+        FullAttentionGroupView(_ib_with_layout(use_hybrid_blocks=True, blocks_per_kv_block=2), block_size=BLOCK_SIZE)
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="decode context parallel"):
+        FullAttentionGroupView(_ib_with_layout(dcp_world_size=2), block_size=BLOCK_SIZE)
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="does not match"):
+        FullAttentionGroupView(_ib_with_layout(kv_cache_block_size=BLOCK_SIZE * 2), block_size=BLOCK_SIZE)
+
+
+def test_step_context_consumed_by_id_not_order():
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0], 0, 4)})
+    s2 = run_step(mgr, view, {"b": ([1], 0, 4)})
+    mgr.discard_step(s2)
+    outs = mgr.materialize(s1, ["a"])
+    assert torch.equal(outs.hidden_states["a"], expected_rows(view.slots_for("a", 0, 4)))
+    assert len(mgr._step_ctxs) == 0
+
+
+def test_step_context_exactly_once():
+    mgr, view = make_manager()
+    sid = run_step(mgr, view, {"a": ([0], 0, 4)})
+    mgr.materialize(sid, ["a"])
+    with pytest.raises(OmniPrefixCacheUnmatchError):
+        mgr.materialize(sid, ["a"])
+    with pytest.raises(OmniPrefixCacheUnmatchError):
+        mgr.discard_step(sid)
+
+
+def test_unconsumed_contexts_timeout():
+    mgr, view = make_manager(staging_claim_timeout_s=0.0)
+    with pytest.raises(OmniPrefixCacheStagingTimeoutError, match="unconsumed step contexts"):
+        for pos in range(8):
+            run_step(mgr, view, {"a": ([0, 1, 2, 3], pos, 1)})
+
+
+def test_save_waits_until_a_slot_is_consumed():
+    mgr, view = make_manager(staging_depth=2, staging_claim_timeout_s=2.0)
+    s0 = run_step(mgr, view, {"a": ([0], 0, 1)})
+    s1 = run_step(mgr, view, {"a": ([0], 1, 1)})
+    err: list[BaseException] = []
+    sid_holder: list[int] = []
+
+    def _blocked_save() -> None:
+        try:
+            sid_holder.append(run_step(mgr, view, {"a": ([0], 2, 1)}))
+        except BaseException as e:
+            err.append(e)
+
+    t = threading.Thread(target=_blocked_save, daemon=True)
+    t.start()
+    time.sleep(0.1)
+    assert t.is_alive()
+    mgr.discard_step(s0)
+    t.join(timeout=1.0)
+    assert not t.is_alive()
+    assert not err
+    mgr.discard_step(s1)
+    mgr.discard_step(sid_holder[0])
+
+
+def test_leftover_only_save_claims_staging_slot():
+    policy = ModelCachePolicy(needs_full_hidden_states=False)
+    mgr, view = make_manager(policy=policy, staging_depth=2, staging_claim_timeout_s=0.0)
+    leftover = {"codes.ref": torch.zeros(3, 2)}
+    s0 = run_step(mgr, view, {"a": ([0], 0, 1)}, mm=leftover)
+    s1 = run_step(mgr, view, {"a": ([0], 1, 1)}, mm=leftover)
+    assert mgr._step_ctxs[s0].d2h is not None and mgr._step_ctxs[s0].d2h.views == {}
+    assert mgr._step_ctxs[s1].d2h is not None and mgr._step_ctxs[s1].d2h.views == {}
+    with pytest.raises(OmniPrefixCacheStagingTimeoutError, match="unconsumed step contexts"):
+        run_step(mgr, view, {"a": ([0], 2, 1)}, mm=leftover)
+
+
+def test_save_slot_mismatch_fails_fast():
+    mgr, view = make_manager()
+    view.order = ["a"]
+    view.req_blocks["a"] = [0]
+    view.computed["a"] = 0
+    mgr.new_step_starts(FakeSchedOut(new_reqs=[FakeNewReq("a")], num_scheduled={"a": 2}))
+    hidden = torch.zeros(4, HIDDEN, dtype=DTYPE)
+    with pytest.raises(OmniPrefixCacheUnmatchError):
+        mgr.save_outputs(hidden, {}, num_tokens_unpadded=4, num_tokens_padded=4)
+
+
+def test_materialize_rejects_out_of_snapshot_ids():
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"b": ([0, 1, 2], 8, 4)}, new_hits={"b": 8}, finished=["a"])
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="outside the save snapshot"):
+        mgr.materialize(s2, ["b", "late_joiner"])
+
+
+def test_materialize_unknown_step_id_fails_fast():
+    mgr, view = make_manager()
+    sid = run_step(mgr, view, {"a": ([0], 0, 4)})
+    with pytest.raises(OmniPrefixCacheUnmatchError):
+        mgr.materialize(sid + 999, ["ghost"])
+    mgr.discard_step(sid)
+
+
+def test_mm_hit_span_never_registered_serves_mirror_baseline():
+    """A hit span slot on which a sparse mm key was never registered is
+    legitimate absence — served from the mirror baseline, not a crash."""
+    policy = ModelCachePolicy(needs_full_hidden_states=True, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    s1 = run_step(mgr, view, {"a": ([0], 0, 4)}, mm={"k": torch.full((4, 2), 5.0)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"c": ([1], 0, 4)})
+    mgr.materialize(s2, ["c"])
+    s3 = run_step(mgr, view, {"b": ([0, 1, 2], 8, 2)}, new_hits={"b": 8}, mm={"k": torch.full((2, 2), 9.0)})
+    rows = mgr.materialize(s3, ["b"]).mm_outputs["k"]["b"]
+    assert torch.equal(rows[:4], torch.full((4, 2), 5.0))
+    assert torch.equal(rows[4:8], torch.zeros(4, 2))
+    assert torch.equal(rows[8:], torch.full((2, 2), 9.0))
+
+
+def test_mm_in_transit_unresolvable_fails_fast():
+    """Rows registered in-transit whose entry cannot serve them must raise."""
+    policy = ModelCachePolicy(needs_full_hidden_states=True, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    s1 = run_step(mgr, view, {"a": ([0], 0, 4)}, mm={"k": torch.full((4, 2), 1.0)})
+    mgr.materialize(s1, ["a"])
+    tid = mgr._request_tasks.deferred["a"].tid
+    mgr._controller._tasks.pop(tid)
+    s2 = run_step(mgr, view, {"b": ([0, 1], 4, 2)}, new_hits={"b": 4}, mm={"k": torch.full((2, 2), 9.0)})
+    with pytest.raises(OmniPrefixCacheUnmatchError):
+        mgr.materialize(s2, ["b"])
+
+
+def test_lock_never_covers_fetch_or_join():
+    """State lock must not be held across join / join_host_ready / fetch_host."""
+    policy = ModelCachePolicy(needs_full_hidden_states=True, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    calls = []
+
+    def probe(kind):
+        on_facade = not threading.current_thread().name.startswith("omni-prefix-cache-prefetch")
+        calls.append((kind, on_facade and mgr._state_lock.locked()))
+
+    real_fetch = mgr._controller.fetch_host
+    real_join_hr = mgr._controller.join_host_ready
+    real_join = mgr._controller.join
+    mgr._controller.fetch_host = lambda *a, **kw: (probe("fetch"), real_fetch(*a, **kw))[1]
+    mgr._controller.join_host_ready = lambda ids: (probe("join"), real_join_hr(ids))[1]
+    mgr._controller.join = lambda ids: (probe("join"), real_join(ids))[1]
+
+    s1 = run_step(mgr, view, {"a": ([0], 0, 4)}, mm={"k": torch.full((4, 2), 1.0)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"b": ([0, 1], 4, 2)}, new_hits={"b": 4}, mm={"k": torch.full((2, 2), 9.0)})
+    mgr.materialize(s2, ["b"])
+    assert any(kind == "fetch" for kind, _ in calls)
+    assert any(kind == "join" for kind, _ in calls)
+    assert all(not locked for _, locked in calls), calls
+
+
+def test_failed_write_fails_fast_at_next_facade_entry():
+    mgr, view = make_manager()
+    sid = run_step(mgr, view, {"a": ([0], 0, 4)})
+    mgr.materialize(sid, ["a"])
+    from vllm_omni.core.prefix_cache.controller import WriteTask, _WriteChunk
+
+    task = WriteTask(
+        tid=999,
+        req_id="x",
+        write_n=1,
+        schedule=WriteSchedule.JOIN_NEXT_STEP,
+        chunks=[_WriteChunk(slots_cpu=torch.tensor([0]), tensors={})],
     )
-
-    assert "passthrough_tensor" not in cache.mm_cache_keys
-
-    passthrough_out = merged_mm_outputs["passthrough_tensor"]
-    # req1 (cache hit) gets tokens [0:3), req2 (cache miss) gets tokens [3:5) --
-    # a passthrough tensor is sliced by scheduled position, not merged with
-    # any cached history (unlike the mm_cache_keys tensors above).
-    assert torch.equal(passthrough_out["req1"], passthrough_tensor[0:num_new_toks_req1])
-    assert torch.equal(passthrough_out["req2"], passthrough_tensor[num_new_toks_req1:total_scheduled_tokens])
-
-
-class MergeHarness(NamedTuple):
-    """A primed cache plus the arguments get_merged_multimodal_states needs."""
-
-    cache: OmniTensorPrefixCache
-    input_batch: MockInputBatch
-    num_scheduled_tokens: dict[str, int]
-    query_start_loc: list[int]
-    total_scheduled_tokens: int
-    new_mm_outputs: dict[str, object]
-
-
-def build_mixed_hit_miss_harness(mocker, num_new_toks_req1: int = 3, num_new_toks_req2: int = 2) -> MergeHarness:
-    """Two requests over one cache key: req1 hits 8 cached tokens, req2 misses,
-    and their scheduled lengths differ -- the same batch shape as
-    test_get_merged_multimodal_outputs, which is what makes a per-request
-    boundary error observable. Callers add their passthrough keys to
-    ``new_mm_outputs`` before calling get_merged_multimodal_states.
-    """
-    cache = get_omni_pcache_with_mm_tensors({"foo": 100}, seq_len=DEFAULT_SEQ_LEN)
-
-    orig_num_tokens_unpadded = 8
-    feature_dims = {key: val.shape[-1] for key, val in cache.mm_outputs_cache.items()}
-    cache.update_omni_tensor_prefix_cache(
-        hidden_states=None,
-        multimodal_outputs={
-            key: torch.rand((orig_num_tokens_unpadded, feature_dims[key]), dtype=DTYPE) for key in cache.mm_cache_keys
-        },
-        num_tokens_unpadded=orig_num_tokens_unpadded,
-        slot_mapping=torch.arange(8, 8 + orig_num_tokens_unpadded),
-        num_tokens_padded=None,
+    mgr._controller._tasks[999] = task
+    mgr._controller._fail_task(999)
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="write failed"):
+        run_step(mgr, view, {"a": ([0, 1], 4, 1)})
+    # Sticky: the record is one-shot and the first raise may land in a
+    # swallowed path (prefetch Future dropped by discard_step); a later
+    # entry must keep raising, never serve zeros for the lost rows.
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="write failed"):
+        run_step(mgr, view, {"c": ([0, 1], 0, 4)})
+
+
+def test_join_raises_on_failed_task():
+    """A joiner woken by FAILED must not treat the wake as a completed
+    write; the one-shot failure record may already be drained elsewhere."""
+    mgr, view = make_manager()
+    _hold_writes(mgr)
+    run_step(mgr, view, {"a": ([0], 0, 4)})
+    tid = next(iter(mgr._request_tasks.tasks["a"]))
+    mgr._controller._fail_task(tid)
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="failed before done"):
+        mgr._controller.join([tid])
+
+
+@pytest.mark.parametrize("fail_at", ["copy", "scatter"])
+def test_eager_dispatch_failure_releases_step_and_all_task_owners(monkeypatch, fail_at):
+    from vllm_omni.core.prefix_cache.controller import TaskState, WriteTask
+
+    mgr, view = make_manager(staging_claim_timeout_s=0)
+    ctrl = mgr._controller
+    preserved_sid = run_step(mgr, view, {"previous": ([3], 0, 4)})
+    if fail_at == "copy":
+        original = WriteTask.mark_host_ready
+
+        def fail_copy(task):
+            if task.req_id == "b":
+                raise RuntimeError("injected copy failure")
+            return original(task)
+
+        monkeypatch.setattr(WriteTask, "mark_host_ready", fail_copy)
+    else:
+        original = ctrl._scatter
+
+        def fail_scatter(task):
+            if task.req_id == "b":
+                raise RuntimeError("injected scatter failure")
+            return original(task)
+
+        monkeypatch.setattr(ctrl, "_scatter", fail_scatter)
+
+    try:
+        with pytest.raises(RuntimeError, match=f"injected {fail_at} failure"):
+            run_step(mgr, view, {"a": ([0], 0, 4), "b": ([1], 0, 4), "c": ([2], 0, 4)})
+        assert set(mgr._step_ctxs) == {preserved_sid}
+        assert ctrl._staged_bytes == 0
+        tasks = [task for task in ctrl._tasks.values() if task.req_id in {"a", "b", "c"}]
+        assert len(tasks) == 3
+        for task in tasks:
+            expected = TaskState.WRITTEN if task.req_id == "a" else TaskState.FAILED
+            assert task.state is expected
+            assert task.done.is_set() and task.host_ready.is_set()
+        assert all(
+            holder == StagingBufferHolder.for_step(preserved_sid)
+            for holders in ctrl._staging_pool._busy
+            for holder in holders
+        )
+        mgr.discard_step(preserved_sid)
+        assert all(not holders for holders in ctrl._staging_pool._busy)
+        with pytest.raises(OmniPrefixCacheUnmatchError, match="write failed"):
+            mgr.new_step_starts(FakeSchedOut())
+    finally:
+        mgr.shutdown()
+
+
+def test_eager_escalation_failure_releases_deferred_tasks(monkeypatch):
+    from vllm_omni.core.prefix_cache.controller import TaskState
+
+    mgr, view = make_manager(policy=ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"k"})))
+    ctrl = mgr._controller
+    sid = run_step(mgr, view, {"a": ([0], 0, 4), "b": ([1], 0, 4)}, mm={"k": torch.ones(8, 2)})
+    mgr.discard_step(sid)
+    assert ctrl._staged_bytes > 0
+    tasks = list(ctrl._tasks.values())
+
+    def fail_scatter(task):
+        raise RuntimeError("injected deferred scatter failure")
+
+    monkeypatch.setattr(ctrl, "_scatter", fail_scatter)
+    try:
+        with pytest.raises(RuntimeError, match="injected deferred scatter failure"):
+            ctrl.escalate([task.tid for task in tasks])
+        assert ctrl._staged_bytes == 0
+        assert all(task.state is TaskState.FAILED for task in tasks)
+        assert all(task.done.is_set() and task.host_ready.is_set() for task in tasks)
+        assert all(not holders for holders in ctrl._staging_pool._busy)
+        with pytest.raises(OmniPrefixCacheUnmatchError, match="write failed"):
+            mgr.new_step_starts(FakeSchedOut())
+    finally:
+        mgr.shutdown()
+
+
+def test_per_request_staging_writes():
+    mgr, view = make_manager()
+    sid = run_step(mgr, view, {"p": ([0, 1], 0, 8), "d": ([2], 0, 1)})
+    tp = mgr._controller.get_task(next(iter(mgr._request_tasks.tasks["p"])))
+    td = mgr._controller.get_task(next(iter(mgr._request_tasks.tasks["d"])))
+    assert tp is not None and td is not None
+    assert (tp.req_id, td.req_id) == ("p", "d")
+    assert mgr._join_next_step_tids == [tp.tid, td.tid]
+    outs = mgr.materialize(sid, ["p", "d"])
+    assert torch.equal(outs.hidden_states["p"], expected_rows(view.slots_for("p", 0, 8)))
+    assert torch.equal(outs.hidden_states["d"], expected_rows(view.slots_for("d", 0, 1)))
+
+
+def test_staging_step_prefills_task_host_and_recycles():
+    mgr, view = make_manager()
+    for i in range(6):
+        sid = run_step(mgr, view, {"a": ([i % 8, (i % 8) + 8], i, 1)})
+        ctx = mgr._step_ctxs[sid]
+        assert ctx.d2h is not None
+        expect = expected_rows(view.slots_for("a", i, i + 1))
+        outs = mgr.materialize(sid, ["a"])
+        assert torch.equal(outs.hidden_states["a"], expect), i
+
+
+def test_oversized_step_fails_fast():
+    mgr, view = make_manager(staging_capacity_tokens=4)
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="staging capacity is 4"):
+        run_step(mgr, view, {"a": ([0, 1], 0, 8)})
+
+
+def test_staging_slot_eager_save_leaves_only_step_holder():
+    """Eager submit writes the pool inline, so the task holder is bound and
+    released inside save; materialize then empties the slot."""
+    mgr, view = make_manager()
+    sid = run_step(mgr, view, {"p": ([0, 1], 0, 8)})
+    ctx = mgr._step_ctxs[sid]
+    assert ctx.d2h is not None
+    busy = mgr._controller._staging_pool._busy[ctx.d2h.staging_slot]
+    assert busy == {StagingBufferHolder.for_step(sid)}
+    mgr.materialize(sid, ["p"])
+    assert not busy
+
+
+def _hold_writes(mgr) -> None:
+    """Non-eager stand-in: dispatch takes the task to device→host done, but
+    leaves the pool write to the caller (`mgr._controller._scatter`)."""
+
+    def dispatch(tasks):
+        for task in tasks:
+            assert task.claim_copy()
+            task.mark_host_ready()
+
+    mgr._controller.dispatch = dispatch
+
+
+def test_eager_copy_runs_outside_state_lock_and_key_install_inside():
+    """Eager mode (NPU/CPU): the copy + pool write must not run under
+    _state_lock, or materialize on the builder thread waits a whole D2H;
+    publishing a new pool key must happen under it."""
+    policy = ModelCachePolicy(needs_full_hidden_states=True, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    seen: dict[str, bool] = {}
+
+    def probe(name):
+        free = mgr._state_lock.acquire(blocking=False)
+        if free:
+            mgr._state_lock.release()
+        seen[name] = free
+
+    real_run, real_install = mgr._controller._run_eager, mgr._pool.install_key
+
+    def run_eager(task):
+        probe("run_eager")
+        real_run(task)
+
+    def install_key(key, storage):
+        probe("install_key")
+        real_install(key, storage)
+
+    mgr._controller._run_eager = run_eager
+    mgr._pool.install_key = install_key
+    sid = run_step(mgr, view, {"a": ([0], 0, 2)}, mm={"k": torch.ones(2, 2)})
+    assert seen == {"run_eager": True, "install_key": False}
+    mgr.materialize(sid, ["a"])
+    assert mgr._pool.has_key("k") and "k" in mgr._slot_status.state
+
+
+def test_eager_finish_escalate_runs_outside_state_lock():
+    """Finish/abort escalate must not _run_eager under _state_lock."""
+    policy = ModelCachePolicy(needs_full_hidden_states=False, deferred_keys=frozenset({"k"}))
+    mgr, view = make_manager(policy=policy)
+    s1 = run_step(mgr, view, {"a": ([2], 0, 1)}, mm={"k": torch.ones(1, 2)})
+    mgr.materialize(s1, ["a"])
+    seen: list[bool] = []
+    real_run = mgr._controller._run_eager
+
+    def run_eager(task):
+        free = mgr._state_lock.acquire(blocking=False)
+        if free:
+            mgr._state_lock.release()
+        seen.append(free)
+        real_run(task)
+
+    mgr._controller._run_eager = run_eager
+    s2 = run_step(mgr, view, {"z": ([9], 0, 1)}, finished=["a"])
+    assert seen == [True]
+    mgr.materialize(s2, ["z"])
+
+
+def test_staging_task_slot_released_at_pool_write_not_drain():
+    mgr, view = make_manager()
+    _hold_writes(mgr)
+    sid = run_step(mgr, view, {"p": ([0, 1], 0, 8)})
+    ctx = mgr._step_ctxs[sid]
+    tid = next(iter(mgr._request_tasks.tasks["p"]))
+    busy = mgr._controller._staging_pool._busy[ctx.d2h.staging_slot]
+    assert StagingBufferHolder.for_task(tid) in busy and StagingBufferHolder.for_step(sid) in busy
+    task = mgr._controller.get_task(tid)
+    mgr._controller._scatter(task)
+    # Released by the committer's pool write; the manager has not drained yet.
+    assert busy == {StagingBufferHolder.for_step(sid)}
+    assert mgr._controller.get_task(tid) is not None
+    mgr.materialize(sid, ["p"])
+    assert not busy
+    assert mgr._controller.get_task(tid) is None
+
+
+def test_blocked_save_is_released_by_pool_write_alone():
+    """All step contexts consumed, the only slot held by a pending write:
+    the committer finishing that write must unblock the waiting save."""
+    mgr, view = make_manager(staging_depth=1, staging_claim_timeout_s=2.0)
+    _hold_writes(mgr)
+    s0 = run_step(mgr, view, {"a": ([0], 0, 1)})
+    tid = next(iter(mgr._request_tasks.tasks["a"]))
+    mgr.materialize(s0, ["a"])
+    slot = mgr._step_ctxs.get(s0)  # consumed
+    assert slot is None
+    assert mgr._controller._staging_pool._busy[0] == {StagingBufferHolder.for_task(tid)}
+    err: list[BaseException] = []
+    sid_holder: list[int] = []
+
+    def _blocked_save() -> None:
+        try:
+            sid_holder.append(run_step(mgr, view, {"a": ([0], 1, 1)}))
+        except BaseException as e:
+            err.append(e)
+
+    t = threading.Thread(target=_blocked_save, daemon=True)
+    t.start()
+    time.sleep(0.1)
+    assert t.is_alive()
+    mgr._controller._scatter(mgr._controller.get_task(tid))
+    t.join(timeout=1.0)
+    assert not t.is_alive()
+    assert not err
+    mgr.discard_step(sid_holder[0])
+
+
+def test_hit_prefetch_prebuilds_merged_buffer():
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)})
+    mgr.materialize(s1, ["a"])
+    s2 = run_step(mgr, view, {"b": ([0, 1, 2], 8, 4)}, new_hits={"b": 8}, finished=["a"])
+    ctx = mgr._step_ctxs[s2]
+    fut = ctx.hit_prefetch["b"][HIDDEN_KEY]
+    buf = fut.result()
+    assert buf.shape == (12, HIDDEN)
+    assert torch.equal(buf[:8], expected_rows(view.slots_for("b", 0, 8)))
+    merged = mgr.materialize(s2, ["b"]).hidden_states["b"]
+    assert merged.data_ptr() == buf.data_ptr()
+    assert torch.equal(merged[8:], expected_rows(view.slots_for("b", 8, 12)))
+
+
+def test_same_step_hit_prefetch_starts_at_save(caplog):
+    """b hits blocks a computes in the same step: nothing to plan at
+    new_step_starts (rows ABSENT), planned at publish once a's write is
+    registered, so the gather runs before the next step can reuse them."""
+    mgr, view = make_manager()
+    view.req_blocks["a"] = [0, 1]
+    with caplog.at_level(logging.CRITICAL, logger="vllm_omni.core.prefix_cache.manager"):
+        sid = run_step(mgr, view, {"a": ([0, 1], 0, 8), "b": ([0, 1, 2], 8, 4)}, new_hits={"b": 8})
+    assert not any("omni prefix cache unmatch" in r.message for r in caplog.records)
+    ctx = mgr._step_ctxs[sid]
+    fut = ctx.hit_prefetch["b"][HIDDEN_KEY]
+    assert torch.equal(fut.result()[:8], expected_rows(view.slots_for("b", 0, 8)))
+    outs = mgr.materialize(sid, ["a", "b"])
+    assert torch.equal(outs.hidden_states["b"][:8], expected_rows(view.slots_for("b", 0, 8)))
+
+
+def test_delayed_read_of_reassigned_hit_raises():
+    """A version check with no COW copy still raises for live and finished.
+    The production path registers the ref first so remap preserves the rows
+    (see test_delayed_read_after_committed_reuse_serves_preserved)."""
+    mgr, view = make_manager()
+    s1 = run_step(mgr, view, {"a": ([0, 1], 0, 8)})
+    mgr.materialize(s1, ["a"])
+    slots = view.slots_for("a", 0, 8)
+    with mgr._state_lock:
+        planned = mgr._slot_status.get_slot_status(HIDDEN_KEY).slot_version[slots].clone()
+    mgr._controller.dispatch = lambda tasks: None  # new tenant's write stays IN_TRANSIT
+    s2 = run_step(mgr, view, {"c": ([0, 1], 0, 8)}, finished=["a"])
+    for req in ("c", "a"):  # live then finished — both fatal without a preserved copy
+        with pytest.raises(OmniPrefixCacheUnmatchError, match="reassigned"):
+            mgr._ensure_not_reassigned(slots, HIDDEN_KEY, req_id=req, planned_version=planned)
+    mgr.discard_step(s2)
+
+
+def test_delayed_read_after_committed_reuse_serves_preserved():
+    """Amy's block-0 reuse: plan A's read, then B commits over the same
+    slots. The reusing write copy-on-writes A's committed rows into the
+    planned ref; the delayed fetch must return those, not B's."""
+    mgr, view = make_manager()
+    sa = run_step(mgr, view, {"a": ([0], 0, 4)})
+    mgr.materialize(sa, ["a"])  # A committed into block 0
+    slots = view.slots_for("a", 0, 4)
+    with mgr._state_lock:
+        src = mgr._slot_ref(slots, HIDDEN_KEY, "a")  # plan A's read
+    assert src.already_staged and not src.staged_list and not src.join_tids
+    sb = run_step(mgr, view, {"b": ([0], 0, 4)}, finished=["a"])
+    mgr.materialize(sb, ["b"])  # A freed, block 0 reused by B and COMMITTED
+    # run_step derives rows from slot ids, so A's and B's values coincide.
+    # Scribble the pool so only the preserved copy can produce A's rows.
+    assert set(src.preserved) == {int(s) for s in slots.tolist()}
+    with torch.inference_mode():
+        mgr._pool.write(HIDDEN_KEY, slots, torch.full((4, HIDDEN), 99.0, dtype=DTYPE))
+        got = mgr._fetch_source(src)
+    assert torch.equal(got, expected_rows(slots))
+    assert all(ref is not src for ref in mgr._pending_reads)
+
+
+def test_done_fires_only_after_completion_record_published():
+    """A join(done) waiter (the save barrier) must find the completion record
+    on its next drain — done-before-append leaves occupancy IN_TRANSIT and the
+    COW preserve skips the reused rows."""
+    mgr, view = make_manager()
+    checks = []
+    orig_scatter = mgr._controller._scatter
+
+    def scatter(task):
+        orig_set = task.done.set
+
+        def checked_set():
+            checks.append(task.tid in mgr._controller._completed)
+            orig_set()
+
+        task.done.set = checked_set
+        orig_scatter(task)
+
+    mgr._controller._scatter = scatter
+    sid = run_step(mgr, view, {"a": ([0], 0, 4)})
+    mgr.materialize(sid, ["a"])
+    assert checks and all(checks)
+
+
+def test_failed_wakes_only_after_failure_record_published():
+    """Same window as the done/_completed one, failure side: a joiner woken
+    by FAILED must find the record on drain, not read never-written rows."""
+    mgr, view = make_manager()
+    _hold_writes(mgr)  # keep the write non-terminal
+    run_step(mgr, view, {"a": ([0], 0, 4)})
+    tid = next(iter(mgr._request_tasks.tasks["a"]))
+    task = mgr._controller.get_task(tid)
+    checks = []
+    orig_set = task.done.set
+
+    def checked_set():
+        checks.append(tid in mgr._controller._failed)
+        orig_set()
+
+    task.done.set = checked_set
+    mgr._controller._fail_task(tid)
+    assert checks and all(checks)
+
+
+def test_save_waits_pool_write_of_previous_step():
+    """A save must not reuse slots whose JOIN_NEXT_STEP write has not reached
+    the pool — no delayed read could recover such a row."""
+    mgr, view = make_manager(staging_claim_timeout_s=0.2)
+    _hold_writes(mgr)  # host_ready only; the pool write never happens
+    run_step(mgr, view, {"a": ([0], 0, 4)})
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="did not reach done"):
+        run_step(mgr, view, {"b": ([1], 0, 4)})
+
+
+def test_join_next_step_hit_survives_task_already_drained():
+    mgr, view = make_manager()
+    mgr._controller.dispatch = lambda tasks: None  # registered, never run
+    view.req_blocks["a"] = [0, 1]
+    sid = run_step(mgr, view, {"a": ([0, 1], 0, 8), "b": ([0, 1, 2], 8, 4)}, new_hits={"b": 8})
+    with mgr._state_lock:
+        src = mgr._slot_ref(view.slots_for("b", 0, 8), HIDDEN_KEY, "b")
+    for tid in src.join_tids:
+        mgr._controller._run_eager(mgr._controller.get_task(tid))
+    with torch.inference_mode():
+        with mgr._state_lock:
+            mgr._commit_drained_writes()
+        assert mgr._controller.get_task(src.join_tids[0]) is None
+        assert torch.equal(mgr._fetch_source(src), expected_rows(view.slots_for("b", 0, 8)))
+    mgr.materialize(sid, ["a", "b"])
+
+
+def test_leftover_mm_snapshot_survives_live_overwrite():
+    """Leftover mm is copied at save; mutating the live buffer
+    afterwards must not change the snapshot."""
+    mgr, view = make_manager()
+    live = [torch.arange(10, dtype=DTYPE)]
+    sid = run_step(mgr, view, {"a": ([0], 0, 2)}, mm={"codes.ref": live})
+    assert "codes.ref" in mgr._step_ctxs[sid].mm_cpu_snapshot
+    snap = mgr._step_ctxs[sid].mm_cpu_snapshot["codes.ref"]
+    live[0].fill_(99.0)
+    assert torch.equal(snap[0], torch.arange(10, dtype=DTYPE))
+    mgr.discard_step(sid)
+
+
+@pytest.mark.parametrize("needs_full_hidden_states", [True, False])
+def test_deferred_leftover_snapshot_survives_live_overwrite(needs_full_hidden_states):
+    """Deferred tails are leftover-copied at save for materialize; the GPU
+    freeze is a different product (pool write on finish). ``False`` is the
+    hidden opt-out + miss path (Qwen3-TTS / Higgs talker)."""
+    policy = ModelCachePolicy(
+        needs_full_hidden_states=needs_full_hidden_states, deferred_keys=frozenset({"codes.audio"})
     )
-    cache.add_prefix_cached_new_req_id("req1")
-
-    total_scheduled_tokens = num_new_toks_req1 + num_new_toks_req2
-    mocker.patch(
-        "vllm_omni.core.prefix_cache.OmniTensorPrefixCache._get_cached_block_ids",
-        new=fake_get_cached_block_ids,
+    mgr, view = make_manager(policy=policy)
+    live = torch.full((2, 2), 1.0)
+    ref = [torch.arange(4, dtype=DTYPE)]
+    sid = run_step(mgr, view, {"a": ([0], 0, 2)}, mm={"codes.audio": live, "codes.ref": ref})
+    assert "codes.audio" in mgr._step_ctxs[sid].mm_cpu_snapshot
+    live.fill_(99.0)
+    ref[0].fill_(99.0)
+    outs = mgr.materialize(sid, ["a"])
+    assert torch.equal(outs.mm_outputs["codes.audio"]["a"], torch.full((2, 2), 1.0))
+    assert torch.equal(outs.mm_outputs["codes.ref"]["a"][0], torch.arange(4, dtype=DTYPE))
+    assert (outs.hidden_states is None) == (not needs_full_hidden_states)
+
+
+def test_frozen_mm_clone_survives_live_overwrite():
+    mgr, view = make_manager()
+    live = torch.full((2, 2), 1.0)
+    sid = run_step(mgr, view, {"a": ([0], 0, 2)}, mm={"codes.audio": live})
+    assert "codes.audio" not in mgr._step_ctxs[sid].mm_cpu_snapshot
+    live.fill_(99.0)
+    outs = mgr.materialize(sid, ["a"])
+    assert torch.equal(outs.mm_outputs["codes.audio"]["a"], torch.full((2, 2), 1.0))
+
+
+def test_hidden_opt_out_miss_returns_mm_and_releases_slot():
+    policy = ModelCachePolicy(needs_full_hidden_states=False)
+    mgr, view = make_manager(policy=policy)
+    for i in range(6):
+        sid = run_step(mgr, view, {"a": ([i % 8, (i % 8) + 8], i, 1)}, mm={"k": torch.full((1, 2), float(i))})
+        ctx = mgr._step_ctxs[sid]
+        assert ctx.d2h is not None, i
+        outs = mgr.materialize(sid, ["a"])
+        assert outs.hidden_states is None
+        assert torch.equal(outs.mm_outputs["k"]["a"], torch.full((1, 2), float(i)))
+        assert not mgr._controller._staging_pool._busy[ctx.d2h.staging_slot], i
+
+
+def test_save_releases_staging_if_commit_drained_writes_fails():
+    mgr, view = make_manager(staging_depth=2)
+    calls = {"n": 0}
+    real = mgr._commit_drained_writes
+
+    def wrapped():
+        calls["n"] += 1
+        if calls["n"] == 2:
+            raise OmniPrefixCacheUnmatchError("injected fail")
+        return real()
+
+    mgr._commit_drained_writes = wrapped
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="injected fail"):
+        run_step(mgr, view, {"a": ([0], 0, 4)})
+    assert all(not busy for busy in mgr._controller._staging_pool._busy)
+    mgr._commit_drained_writes = real
+    sid = run_step(mgr, view, {"a": ([0], 0, 4)})
+    assert mgr._step_ctxs[sid].d2h is not None
+    mgr.materialize(sid, ["a"])
+
+
+def test_fetch_host_maps_slots_across_layouts():
+    """Identity, prefix, gapped, and a two-`_WriteChunk` gather."""
+    from vllm_omni.core.prefix_cache.block_pool import PrefixBlockPool
+    from vllm_omni.core.prefix_cache.controller import OmniPrefixCacheController, WriteTask, _WriteChunk
+
+    cfg = PrefixCacheConfig(num_blocks=NUM_BLOCKS, block_size=BLOCK_SIZE)
+    pool = PrefixBlockPool(cfg)
+    pool.ensure_key(HIDDEN_KEY, DTYPE, HIDDEN)
+    ctrl = OmniPrefixCacheController(pool, cfg, eager=True)
+
+    slots = torch.tensor([40, 41, 42, 43, 44], dtype=torch.int64)
+    rows = torch.arange(slots.numel() * HIDDEN, dtype=DTYPE).reshape(slots.numel(), HIDDEN)
+
+    def _expect(want):
+        return torch.stack([rows[(slots == s).nonzero()[0, 0]] for s in want.tolist()])
+
+    one = WriteTask(
+        tid=1,
+        req_id="r",
+        write_n=1,
+        schedule=WriteSchedule.JOIN_ON_FINISH,
+        chunks=[_WriteChunk(slots_cpu=slots, tensors={HIDDEN_KEY: rows})],
     )
-    return MergeHarness(
-        cache=cache,
-        input_batch=MockInputBatch(num_computed_tokens_cpu=torch.Tensor([orig_num_tokens_unpadded, 0])),
-        num_scheduled_tokens={"req1": num_new_toks_req1, "req2": num_new_toks_req2},
-        query_start_loc=[0, num_new_toks_req1],
-        total_scheduled_tokens=total_scheduled_tokens,
-        new_mm_outputs={
-            key: torch.rand((total_scheduled_tokens, feature_dims[key]), dtype=DTYPE) for key in cache.mm_cache_keys
-        },
+    for want in (slots, slots[:3], slots[[0, 1, 3, 4]]):
+        assert torch.equal(ctrl.fetch_host(one, want, HIDDEN_KEY), _expect(want))
+
+    two = WriteTask(
+        tid=2,
+        req_id="r",
+        write_n=2,
+        schedule=WriteSchedule.JOIN_ON_FINISH,
+        chunks=[
+            _WriteChunk(slots_cpu=slots[:3], tensors={HIDDEN_KEY: rows[:3]}),
+            _WriteChunk(slots_cpu=slots[3:], tensors={HIDDEN_KEY: rows[3:]}),
+        ],
     )
-
-
-def test_get_merged_multimodal_outputs_passes_per_request_tensor_list_through(mocker):
-    """The passthrough shape qwen3-tts actually emits: a nested ``codes``/``meta``
-    dict whose ``codes.ref`` holds one tensor per request
-    (qwen3_tts_talker.make_omni_output), carried through to_payload_element's
-    pass_lists_through branch beside 1D int metadata that IS sliced per request.
-
-    Each request must receive the list *whole*. Per-request indexing happens
-    later, in the runner's _unwrap_lists; a W2 that split the list here would
-    make that second index select a different request's reference codes. The
-    existing list coverage passes a list of strings, which cannot catch a
-    tensor-specific regression, and no other test covers an int dtype.
-    """
-    harness = build_mixed_hit_miss_harness(mocker)
-
-    ref_codes = [torch.tensor([11, 12], dtype=torch.long), torch.tensor([21], dtype=torch.long)]
-    ref_code_len = torch.arange(harness.total_scheduled_tokens, dtype=torch.int32)
-    harness.new_mm_outputs["codes"] = {"ref": ref_codes}
-    harness.new_mm_outputs["meta"] = {"ref_code_len": ref_code_len}
-
-    merged = harness.cache.get_merged_multimodal_states(
-        query_start_loc=harness.query_start_loc,
-        input_batch=harness.input_batch,
-        multimodal_outputs=harness.new_mm_outputs,
-        num_scheduled_tokens=harness.num_scheduled_tokens,
+    want = slots[[0, 3, 1, 4]]
+    assert torch.equal(ctrl.fetch_host(two, want, HIDDEN_KEY), _expect(want))
+
+
+def test_fetch_host_waits_staging_step_d2h_event():
+    """JOIN_NEXT_STEP stores chunk.host as a staging view; fetch_host waits
+    step_d2h_event before slicing. Production JOIN_NEXT_STEP hits wait for
+    the pool write instead; this is the unit-level wait contract for that branch."""
+    from vllm_omni.core.prefix_cache.block_pool import PrefixBlockPool
+    from vllm_omni.core.prefix_cache.controller import OmniPrefixCacheController, WriteTask, _WriteChunk
+
+    cfg = PrefixCacheConfig(num_blocks=NUM_BLOCKS, block_size=BLOCK_SIZE)
+    pool = PrefixBlockPool(cfg)
+    ctrl = OmniPrefixCacheController(pool, cfg, eager=True)
+
+    slots = torch.tensor([0, 1, 2], dtype=torch.int64)
+    src = torch.arange(3 * HIDDEN, dtype=DTYPE).reshape(3, HIDDEN)
+    landing = torch.zeros_like(src)
+
+    class _HostEvent:
+        n = 0
+
+        def synchronize(self):
+            self.n += 1
+            landing.copy_(src)
+
+    event = _HostEvent()
+    chunk = _WriteChunk(slots_cpu=slots, tensors={HIDDEN_KEY: src})
+    chunk.host = {HIDDEN_KEY: landing}
+    task = WriteTask(
+        tid=1,
+        req_id="r",
+        write_n=1,
+        schedule=WriteSchedule.JOIN_NEXT_STEP,
+        chunks=[chunk],
+        staging_slot=0,
+        step_d2h_event=event,
     )
-
-    assert "codes" not in harness.cache.mm_cache_keys
-    for req_id in ("req1", "req2"):
-        req_refs = merged["codes"][req_id]["ref"]
-        assert len(req_refs) == len(ref_codes)
-        for got, want in zip(req_refs, ref_codes):
-            assert torch.equal(got, want)
-            assert got.dtype == torch.long
-
-    # Per-request clones: the branch exists so one request's downstream mutation
-    # cannot reach another request's payload or the source list.
-    merged["codes"]["req1"]["ref"][0] += 100
-    assert torch.equal(merged["codes"]["req2"]["ref"][0], torch.tensor([11, 12], dtype=torch.long))
-    assert torch.equal(ref_codes[0], torch.tensor([11, 12], dtype=torch.long))
-
-    # Token-aligned 1D metadata is still split per request, unlike the list.
-    req1_len = harness.num_scheduled_tokens["req1"]
-    assert torch.equal(merged["meta"]["req1"]["ref_code_len"], ref_code_len[:req1_len])
-    assert torch.equal(merged["meta"]["req2"]["ref_code_len"], ref_code_len[req1_len:])
-    assert merged["meta"]["req1"]["ref_code_len"].dtype == torch.int32
-
-
-@pytest.mark.parametrize(
-    "passthrough_shape",
-    [(3, 4), (1, 4), (7,)],
-    ids=["shorter_2d", "single_row_2d", "longer_1d"],
-)
-def test_get_merged_multimodal_outputs_broadcasts_non_token_aligned_passthrough(passthrough_shape, mocker):
-    """A passthrough tensor whose first dimension is not the scheduled-token
-    count is request-invariant: to_payload_element hands every request the whole
-    tensor, cloned, rather than slicing it.
-
-    W2 batching most plausibly breaks by assuming every passthrough tensor is
-    token-aligned; that assumption would slice these and give each request a
-    truncated view, or an empty one once start exceeds the first dimension.
-    """
-    harness = build_mixed_hit_miss_harness(mocker)
-    assert passthrough_shape[0] != harness.total_scheduled_tokens
-
-    passthrough = torch.arange(math.prod(passthrough_shape), dtype=DTYPE).reshape(passthrough_shape)
-    expected = passthrough.clone()
-    harness.new_mm_outputs["speaker_embedding"] = passthrough
-
-    merged = harness.cache.get_merged_multimodal_states(
-        query_start_loc=harness.query_start_loc,
-        input_batch=harness.input_batch,
-        multimodal_outputs=harness.new_mm_outputs,
-        num_scheduled_tokens=harness.num_scheduled_tokens,
+    rows = ctrl.fetch_host(task, slots, HIDDEN_KEY)
+    assert event.n == 1
+    assert torch.equal(rows, src)
+
+
+def _bare_controller(eager=True):
+    from vllm_omni.core.prefix_cache.block_pool import PrefixBlockPool
+    from vllm_omni.core.prefix_cache.controller import OmniPrefixCacheController
+
+    cfg = PrefixCacheConfig(num_blocks=NUM_BLOCKS, block_size=BLOCK_SIZE)
+    pool = PrefixBlockPool(cfg)
+    pool.ensure_key(HIDDEN_KEY, DTYPE, HIDDEN)
+    ctrl = OmniPrefixCacheController(pool, cfg, eager=eager)
+    return ctrl, pool
+
+
+def _bare_task(tid=7, schedule=WriteSchedule.JOIN_NEXT_STEP, host=None, tensors=None, budget=None, queued=False):
+    from vllm_omni.core.prefix_cache.controller import TaskState, WriteTask, _WriteChunk
+
+    slots = torch.tensor([0, 1], dtype=torch.int64)
+    chunk = _WriteChunk(slots_cpu=slots, tensors=tensors or {}, budget=budget)
+    if host is not None:
+        chunk.host = {HIDDEN_KEY: host}
+    task = WriteTask(tid=tid, req_id="r", write_n=1, schedule=schedule, chunks=[chunk])
+    if queued:
+        task.transition(TaskState.QUEUED)
+    return task, slots
+
+
+def test_task_state_is_a_strict_chain():
+    """PENDING -> QUEUED -> COPYING -> HOST_READY -> WRITTEN, one step at a time."""
+    from vllm_omni.core.prefix_cache.controller import TaskState
+
+    task, _ = _bare_task()
+    assert task.state is TaskState.PENDING
+    assert not task.claim_copy()  # PENDING may not skip QUEUED
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="illegal transition PENDING -> HOST_READY"):
+        task.transition(TaskState.HOST_READY)
+    task.transition(TaskState.QUEUED)
+    assert task.claim_copy()
+    assert task.state is TaskState.COPYING and not task.host_ready.is_set()
+    assert not task.claim_copy()  # second claimant loses
+    task.mark_host_ready()
+    assert task.state is TaskState.HOST_READY and task.host_ready.is_set() and not task.done.is_set()
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="illegal transition HOST_READY -> COPYING"):
+        task.transition(TaskState.COPYING)  # no going back
+    task.mark_done()
+    assert task.state is TaskState.WRITTEN and task.done.is_set()
+    assert not task.mark_failed()  # terminal stays terminal
+    assert task.state is TaskState.WRITTEN
+
+
+def test_task_failed_sets_both_events_and_closes_append():
+    from vllm_omni.core.prefix_cache.controller import TaskState, _WriteChunk
+
+    task, slots = _bare_task()
+    assert task.mark_failed()
+    assert task.state is TaskState.FAILED and task.host_ready.is_set() and task.done.is_set()
+    assert task.append_chunk(_WriteChunk(slots_cpu=slots, tensors={})) is TaskState.FAILED
+
+
+def test_escalate_leaves_claimed_task_alone():
+    """Once the worker owns the copy stage (COPYING), escalate must not
+    re-queue the tid — that re-queue was the double-write race."""
+    from vllm_omni.core.prefix_cache.controller import TaskState
+
+    ctrl, _ = _bare_controller(eager=True)
+    ctrl._eager = False  # exercise the queue path without a worker thread
+    later, _ = _bare_task(tid=1, schedule=WriteSchedule.JOIN_ON_FINISH)
+    ctrl.submit(later, queued=False)
+    assert later.state is TaskState.PENDING
+    ctrl.escalate([1])
+    assert later.state is TaskState.QUEUED and list(ctrl._queue_hi) == [1]
+    ctrl.escalate([1])  # already high-priority: no duplicate
+    assert list(ctrl._queue_hi) == [1]
+
+    ctrl._queue_hi.clear()
+    later.transition(TaskState.COPYING)
+    ctrl.escalate([1])
+    assert list(ctrl._queue_hi) == [] and list(ctrl._queue_lo) == []
+
+
+def test_join_on_stuck_committer_raises_instead_of_hanging():
+    from vllm_omni.core.prefix_cache.block_pool import PrefixBlockPool
+    from vllm_omni.core.prefix_cache.controller import OmniPrefixCacheController, TaskState
+
+    cfg = PrefixCacheConfig(num_blocks=NUM_BLOCKS, block_size=BLOCK_SIZE, staging_claim_timeout_s=0.05)
+    ctrl = OmniPrefixCacheController(PrefixBlockPool(cfg), cfg, eager=True)
+    ctrl._eager = False  # queue path without a worker thread: nothing will finish the task
+    task, _ = _bare_task(tid=1, schedule=WriteSchedule.JOIN_ON_FINISH)
+    ctrl.submit(task, queued=True)
+    task.transition(TaskState.COPYING)
+
+    with pytest.raises(
+        OmniPrefixCacheUnmatchError, match=r"task 1 \(join_on_finish\) did not reach host_ready .*state=COPYING"
+    ):
+        ctrl.join_host_ready([1])
+    with pytest.raises(OmniPrefixCacheUnmatchError, match="did not reach done"):
+        ctrl.join([1])
+
+
+def test_scatter_host_ready_writes_only_staged_tasks():
+    from vllm_omni.core.prefix_cache.controller import TaskState
+
+    ctrl, pool = _bare_controller()
+    task, slots = _bare_task(host=torch.ones(2, HIDDEN), queued=True)
+    ctrl._tasks[task.tid] = task
+    assert task.claim_copy()
+    ctrl._blocked.append(task.tid)
+    ctrl._scatter_host_ready()  # COPYING: not ready, stays blocked
+    assert ctrl._blocked == [task.tid] and list(ctrl._completed) == []
+    task.mark_host_ready()
+    ctrl._scatter_host_ready()
+    assert ctrl._blocked == [] and list(ctrl._completed) == [task.tid]
+    assert task.state is TaskState.WRITTEN
+    assert torch.equal(pool.rows(HIDDEN_KEY, slots), torch.ones(2, HIDDEN))
+
+
+def test_budget_ticket_uncharges_once_per_clone():
+    from vllm_omni.core.prefix_cache.controller import _BudgetTicket
+
+    ctrl, _ = _bare_controller()
+    ticket = _BudgetTicket(nbytes=100)
+    ctrl.reserve(100)
+    a, _ = _bare_task(tid=1, budget=ticket)
+    b, _ = _bare_task(tid=2, budget=ticket)
+    ctrl.pin_budget(ticket, 1)
+    ctrl.pin_budget(ticket, 2)
+    ctrl._release_staged_bytes(a)
+    assert ctrl._staged_bytes == 100  # b still holds the clone
+    ctrl._release_staged_bytes(a)  # idempotent per tid
+    assert ctrl._staged_bytes == 100
+    ctrl._release_staged_bytes(b)
+    assert ctrl._staged_bytes == 0
+    ctrl._release_staged_bytes(b)  # freed once, never twice
+    assert ctrl._staged_bytes == 0
+
+
+def test_fail_task_after_copy_does_not_uncharge_twice():
+    from vllm_omni.core.prefix_cache.controller import TaskState, _BudgetTicket
+
+    ctrl, _ = _bare_controller()
+    ticket = _BudgetTicket(nbytes=64)
+    ctrl.reserve(64)
+    task, _ = _bare_task(tid=3, budget=ticket, queued=True)
+    ctrl._tasks[task.tid] = task
+    ctrl.pin_budget(ticket, 3)
+    assert task.claim_copy()
+    task.mark_host_ready()
+    ctrl._release_staged_bytes(task)  # what _copy_task does on HOST_READY
+    assert ctrl._staged_bytes == 0
+    ctrl._fail_task(3)
+    assert task.state is TaskState.FAILED and ctrl._staged_bytes == 0
+    assert list(ctrl._failed) == [3]
+    ctrl._fail_task(3)  # terminal: no second publish
+    assert list(ctrl._failed) == [3]
+
+
+def test_from_vllm_config_uses_batched_tokens():
+    cfg = PrefixCacheConfig.from_vllm_config(
+        num_blocks=NUM_BLOCKS,
+        block_size=BLOCK_SIZE,
+        scheduler_config=SimpleNamespace(max_num_batched_tokens=8192, max_model_len=32768, max_num_seqs=64),
     )
-
-    assert "speaker_embedding" not in harness.cache.mm_cache_keys
-    out = merged["speaker_embedding"]
-    for req_id in ("req1", "req2"):
-        assert out[req_id].shape == passthrough_shape
-        assert torch.equal(out[req_id], expected)
-
-    out["req1"] += 100
-    assert torch.equal(out["req2"], expected)
-    assert torch.equal(passthrough, expected)
+    assert cfg.staging_capacity_tokens == 8192
+    assert cfg.staging_depth == 4
+    cfg_fallback = PrefixCacheConfig.from_vllm_config(
+        num_blocks=NUM_BLOCKS,
+        block_size=BLOCK_SIZE,
+        scheduler_config=SimpleNamespace(max_num_batched_tokens=None, max_model_len=4096),
+    )
+    assert cfg_fallback.staging_capacity_tokens == 4096
diff --git a/tests/core/test_prefix_cache_async_write.py b/tests/core/test_prefix_cache_async_write.py
deleted file mode 100644
index fa198022745..00000000000
--- a/tests/core/test_prefix_cache_async_write.py
+++ /dev/null
@@ -1,119 +0,0 @@
-import pytest
-import torch
-
-from vllm_omni.core.prefix_cache import OmniTensorPrefixCache
-
-# `cpu` is the lane selector, not a hardware claim: the only Buildkite steps that
-# reach tests/ select `core_model and cpu`, and they run on GPU hardware (l4_1).
-# Marking this `cuda` collects it nowhere. Real hardware need is the skipif below.
-pytestmark = [
-    pytest.mark.core_model,
-    pytest.mark.cpu,
-    pytest.mark.skipif(not torch.cuda.is_available(), reason="requires a CUDA device"),
-]
-
-NUM_BLOCKS = 10
-BLOCK_SIZE = 4
-HIDDEN_SIZE = 2
-DTYPE = torch.float32
-
-
-def get_omni_pcache() -> OmniTensorPrefixCache:
-    """Build an OmniTensorPrefixCache, but don't init mm tensors."""
-    return OmniTensorPrefixCache(
-        num_blocks=NUM_BLOCKS,
-        block_size=BLOCK_SIZE,
-        hidden_size=HIDDEN_SIZE,
-        hs_dtype=DTYPE,
-    )
-
-
-def test_drain_ready_async_writes_is_a_noop_before_the_event_is_ready(monkeypatch):
-    """drain_ready_async_writes() must not touch the cache while the
-    scheduled D2H's event has not completed, and must consume it exactly
-    once after it has.
-
-    Real GPU timing (e.g. via torch.cuda._sleep to stall the copy stream)
-    was tried and found unreliable on this box: cross-stream wait_stream/
-    wait_event did not reliably delay event.query() from reporting ready
-    immediately, likely a virtualization/driver quirk of this cloud GPU.
-    Forcing the event's query() result directly tests the branching logic
-    in drain_ready_async_writes/_consume_pending_write deterministically,
-    independent of real CUDA scheduling behavior.
-    """
-    cache = get_omni_pcache()
-    mm_key = "codes.audio"
-    cache.maybe_init_missing_mm_cache_keys({mm_key: torch.zeros(4, HIDDEN_SIZE)}, seq_len=4)
-
-    num_tokens = 4
-    slot_mapping_gpu = torch.arange(8, 8 + num_tokens, dtype=torch.int64, device="cuda")
-    mm_gpu = {
-        mm_key: torch.arange(num_tokens * HIDDEN_SIZE, dtype=torch.float32, device="cuda").reshape(
-            num_tokens, HIDDEN_SIZE
-        )
-    }
-
-    cache.schedule_async_write(
-        hidden_states_gpu=None,
-        multimodal_outputs_gpu=mm_gpu,
-        slot_mapping_gpu=slot_mapping_gpu,
-        num_tokens_unpadded=num_tokens,
-        num_tokens_padded=num_tokens,
-    )
-
-    pending_event = cache._pending_write.event
-    rows = cache.mm_outputs_cache[mm_key].view(-1, HIDDEN_SIZE)
-
-    monkeypatch.setattr(pending_event, "query", lambda: False)
-    assert cache.drain_ready_async_writes() == 0
-    assert torch.all(rows[8 : 8 + num_tokens] == 0)
-    assert cache._pending_write is not None
-
-    monkeypatch.setattr(pending_event, "query", lambda: True)
-    assert cache.drain_ready_async_writes() == 1
-    assert torch.equal(rows[8 : 8 + num_tokens], mm_gpu[mm_key].cpu())
-    assert cache._pending_write is None
-
-    # Nothing pending anymore: a second drain is a no-op, not a re-scatter.
-    assert cache.drain_ready_async_writes() == 0
-
-
-def test_schedule_async_write_consumes_previous_pending_write_first():
-    """Scheduling step N+1's write must first consume (scatter) step N's
-    pending write, even if the caller never explicitly called
-    drain_ready_async_writes() in between -- otherwise step N's data would
-    be silently dropped when overwritten by step N+1's pending write."""
-    cache = get_omni_pcache()
-    mm_key = "codes.audio"
-    cache.maybe_init_missing_mm_cache_keys({mm_key: torch.zeros(4, HIDDEN_SIZE)}, seq_len=4)
-
-    num_tokens = 4
-    first_slots = torch.arange(8, 8 + num_tokens, dtype=torch.int64, device="cuda")
-    first_gpu = {mm_key: torch.full((num_tokens, HIDDEN_SIZE), 1.0, device="cuda")}
-    second_slots = torch.arange(12, 12 + num_tokens, dtype=torch.int64, device="cuda")
-    second_gpu = {mm_key: torch.full((num_tokens, HIDDEN_SIZE), 2.0, device="cuda")}
-
-    cache.schedule_async_write(
-        hidden_states_gpu=None,
-        multimodal_outputs_gpu=first_gpu,
-        slot_mapping_gpu=first_slots,
-        num_tokens_unpadded=num_tokens,
-        num_tokens_padded=num_tokens,
-    )
-    torch.accelerator.synchronize()
-
-    # This call's internal _consume_pending_write() must flush the FIRST
-    # write before the second one is scheduled; the caller never drained.
-    cache.schedule_async_write(
-        hidden_states_gpu=None,
-        multimodal_outputs_gpu=second_gpu,
-        slot_mapping_gpu=second_slots,
-        num_tokens_unpadded=num_tokens,
-        num_tokens_padded=num_tokens,
-    )
-    torch.accelerator.synchronize()
-    cache.drain_ready_async_writes()
-
-    rows = cache.mm_outputs_cache[mm_key].view(-1, HIDDEN_SIZE)
-    assert torch.all(rows[8:12] == 1.0)
-    assert torch.all(rows[12:16] == 2.0)
diff --git a/tests/core/test_prefix_cache_runner_mixin.py b/tests/core/test_prefix_cache_runner_mixin.py
new file mode 100644
index 00000000000..3809c20b8b6
--- /dev/null
+++ b/tests/core/test_prefix_cache_runner_mixin.py
@@ -0,0 +1,182 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""CPU tests for PrefixCacheRunnerMixin: one-shot construction, policy
+snapshot identity/isolation, and the shared save/materialize gates.
+No vLLM and no GPU required (same shim as test_prefix_cache.py)."""
+
+import sys
+from pathlib import Path
+from types import ModuleType, SimpleNamespace
+from typing import Any
+
+import pytest
+import torch
+
+try:  # pragma: no cover - shim only matters on vllm-less dev machines
+    import vllm  # noqa: F401
+except ModuleNotFoundError:
+    _root = Path(__file__).resolve().parents[2]
+    for _pkg in ("vllm_omni", "vllm_omni.core"):
+        if _pkg not in sys.modules:
+            _m = ModuleType(_pkg)
+            _m.__path__ = [str(_root / _pkg.replace(".", "/"))]
+            sys.modules[_pkg] = _m
+    import logging
+
+    _vllm = ModuleType("vllm")
+    _vllm_logger = ModuleType("vllm.logger")
+    setattr(_vllm_logger, "init_logger", logging.getLogger)
+    setattr(_vllm, "logger", _vllm_logger)
+    sys.modules["vllm"] = _vllm
+    sys.modules["vllm.logger"] = _vllm_logger
+
+from vllm_omni.core.prefix_cache.interface import PrefixCacheConfig, StageCacheOutputs
+from vllm_omni.core.prefix_cache.runner_mixin import PrefixCacheRunnerMixin
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+BLOCK_SIZE = 4
+
+
+def _patch_pp(monkeypatch, is_last: bool) -> None:
+    """Route the mixin's call-time get_pp_group import to a fake rank."""
+    mod = ModuleType("vllm.distributed.parallel_state")
+    setattr(mod, "get_pp_group", lambda: SimpleNamespace(is_last_rank=is_last))
+    if "vllm.distributed" not in sys.modules:
+        monkeypatch.setitem(sys.modules, "vllm.distributed", ModuleType("vllm.distributed"))
+    monkeypatch.setitem(sys.modules, "vllm.distributed.parallel_state", mod)
+
+
+def _full_attention_groups():
+    """A single-group config that passes check_prefix_cache_kv_groups.
+
+    Real FullAttentionSpec when vllm is installed; otherwise a stand-in
+    registered under the import path the check resolves at call time.
+    """
+    try:
+        from vllm.v1.kv_cache_interface import FullAttentionSpec
+    except ModuleNotFoundError:
+        iface = sys.modules.get("vllm.v1.kv_cache_interface")
+        if iface is None:
+            iface = ModuleType("vllm.v1.kv_cache_interface")
+
+            class _FullAttentionSpecStub:
+                pass
+
+            setattr(iface, "FullAttentionSpec", _FullAttentionSpecStub)
+            sys.modules["vllm.v1"] = ModuleType("vllm.v1")
+            sys.modules["vllm.v1.kv_cache_interface"] = iface
+        FullAttentionSpec = getattr(iface, "FullAttentionSpec")
+    return [SimpleNamespace(kv_cache_spec=FullAttentionSpec.__new__(FullAttentionSpec))]
+
+
+class _FakeBlockTables:
+    """Group-0 table whose layout attrs pass check_prefix_cache_block_layout."""
+
+    def __init__(self):
+        self.block_tables = [object()]
+
+    def __getitem__(self, idx):
+        return SimpleNamespace()
+
+
+class _Runner(PrefixCacheRunnerMixin):
+    def __init__(self, cfg: PrefixCacheConfig | None = None):
+        # Any: tests swap in _CacheStub for the manager.
+        self.omni_prefix_cache: Any = None
+        self._omni_prefix_cache_cfg = cfg
+        self.input_batch = SimpleNamespace(block_table=_FakeBlockTables(), req_ids=[])
+        self.kv_cache_config = SimpleNamespace(kv_cache_groups=_full_attention_groups())
+        self.is_pooling_model = False
+
+
+def _cfg() -> PrefixCacheConfig:
+    return PrefixCacheConfig(num_blocks=8, block_size=BLOCK_SIZE)
+
+
+def _sched():
+    return SimpleNamespace(scheduled_new_reqs=(), finished_req_ids=set(), num_scheduled_tokens={})
+
+
+class _CacheStub:
+    def __init__(self):
+        self.save_calls = []
+        self.materialize_calls = []
+        self.outs = StageCacheOutputs(hidden_states=None, mm_outputs={})
+
+    def save_outputs(self, hidden, mm, *, num_tokens_unpadded, num_tokens_padded):
+        self.save_calls.append((hidden, mm, num_tokens_unpadded, num_tokens_padded))
+        return 7
+
+    def materialize(self, step_id, req_ids):
+        self.materialize_calls.append((step_id, req_ids))
+        return self.outs
+
+
+def test_step_begin_builds_once_and_registers_snapshot_policy(monkeypatch):
+    _patch_pp(monkeypatch, is_last=True)
+    r = _Runner(_cfg())
+    r._snapshot_prefix_cache_model_policy(
+        SimpleNamespace(requires_full_prefix_cached_hidden_states=True, deferred_prefix_cache_mm_keys=("k",))
+    )
+    r._prefix_cache_step_begin(_sched())
+    mgr = r.omni_prefix_cache
+    assert mgr is not None and r._omni_prefix_cache_cfg is None
+    assert mgr._policy is r._omni_cache_policy  # the load-time snapshot, same object
+    r._prefix_cache_step_begin(_sched())
+    assert r.omni_prefix_cache is mgr  # one-shot
+
+
+def test_default_policy_isolated_per_instance():
+    a, b = _Runner(), _Runner()
+    a._snapshot_prefix_cache_model_policy(SimpleNamespace(requires_full_prefix_cached_hidden_states=False))
+    assert a._omni_cache_policy.needs_full_hidden_states is False
+    assert a._model_needs_full_prefix_hidden_states() is False
+    assert b._omni_cache_policy.needs_full_hidden_states is True  # class default untouched
+    assert PrefixCacheRunnerMixin._omni_cache_policy.needs_full_hidden_states is True
+
+
+def test_non_last_rank_consumes_cfg_without_building(monkeypatch):
+    _patch_pp(monkeypatch, is_last=False)
+    r = _Runner(_cfg())
+    r._prefix_cache_step_begin(_sched())
+    assert r.omni_prefix_cache is None and r._omni_prefix_cache_cfg is None
+
+
+def test_disabled_cache_step_begin_is_a_noop():
+    r = _Runner(cfg=None)  # enable_prefix_caching off: nothing staged
+    r._prefix_cache_step_begin(_sched())
+    assert r.omni_prefix_cache is None
+
+
+def test_save_step_gates_and_passthrough(monkeypatch):
+    r = _Runner()
+    stub = _CacheStub()
+    hidden = torch.zeros(2, 2)
+
+    def save():
+        return r._prefix_cache_save_step(hidden, None, num_tokens_unpadded=2, num_tokens_padded=2)
+
+    _patch_pp(monkeypatch, is_last=True)
+    assert save() is None  # cache off
+    r.omni_prefix_cache = stub
+    r.is_pooling_model = True
+    assert save() is None  # pooling stage never writes
+    r.is_pooling_model = False
+    _patch_pp(monkeypatch, is_last=False)
+    assert save() is None  # not the last PP rank
+    _patch_pp(monkeypatch, is_last=True)
+    assert save() == 7
+    assert stub.save_calls == [(hidden, {}, 2, 2)]  # empty mm stays {}
+
+
+def test_materialize_requires_explicit_step_and_snapshot_req_ids():
+    r = _Runner()
+    stub = _CacheStub()
+    r.omni_prefix_cache = stub
+    assert r._prefix_cache_materialize(None, ["a"]) == (None, None)
+    assert stub.materialize_calls == []  # step_id None: nothing to consume
+    hidden = {"a": torch.zeros(1, 2)}
+    stub.outs = StageCacheOutputs(hidden_states=hidden, mm_outputs={})
+    assert r._prefix_cache_materialize(7, ["a"]) == (hidden, None)  # empty mm -> None
+    assert stub.materialize_calls == [(7, ["a"])]
diff --git a/tests/e2e/online_serving/test_qwen3_omni.py b/tests/e2e/online_serving/test_qwen3_omni.py
index f6ede894480..5b4bbc51e54 100644
--- a/tests/e2e/online_serving/test_qwen3_omni.py
+++ b/tests/e2e/online_serving/test_qwen3_omni.py
@@ -24,29 +24,40 @@
 _CI_DEPLOY = get_deploy_config_path("ci/qwen3_omni_moe.yaml")
 
 
-# For prefix caching checks against we enable it on the thinker and talker via CLI override
-# and enable prompt token details so that we can determine if any tokens were cached.
-# We also explicitly set block size so that we can make sure the cached token counts are a
-# multiple of the block size.
+# Prefix cache is opt-in on the deploy YAML. CI overlay also pins
+# ``async_chunk: False``; the existing server keeps ``--no-async-chunk``.
+# Production Qwen YAML is ``async_chunk: true``, so a sibling server boots
+# with ``--async-chunk`` and the same cache overrides (async output builder).
 BLOCK_SIZE = 16
+_PREFIX_CACHE_SERVER_ARGS = [
+    "--block-size",
+    str(BLOCK_SIZE),
+    "--stage-overrides",
+    '{"0": {"enable_prefix_caching": true}, "1": {"enable_prefix_caching": true}}',
+    "--enable-prompt-tokens-details",
+]
 test_params = [
     pytest.param(
         OmniServerParams(
             model=_MODEL,
             stage_config_path=_CI_DEPLOY,
             use_stage_cli=True,
-            server_args=[
-                "--no-async-chunk",
-                "--block-size",
-                str(BLOCK_SIZE),
-                "--stage-overrides",
-                '{"0": {"enable_prefix_caching": true}, "1": {"enable_prefix_caching": true}}',
-                "--enable-prompt-tokens-details",
-            ],
+            server_args=["--no-async-chunk", *_PREFIX_CACHE_SERVER_ARGS],
         ),
         id="default",
     )
 ]
+prefix_cache_async_chunk_params = [
+    pytest.param(
+        OmniServerParams(
+            model=_MODEL,
+            stage_config_path=_CI_DEPLOY,
+            use_stage_cli=True,
+            server_args=["--async-chunk", *_PREFIX_CACHE_SERVER_ARGS],
+        ),
+        id="prefix_cache_async_chunk",
+    )
+]
 
 
 def get_system_prompt():
@@ -245,6 +256,83 @@ def test_thinker_prefix_caching_audio_output(omni_server, online_client) -> None
     _run_prefix_cache_check(online_client, request_config)
 
 
+def _assert_omni_payload_complete(resp) -> None:
+    """Async-chunk + prefix-cache must still deliver a full downstream payload."""
+    assert resp.success
+    assert resp.text_content
+    has_audio = bool(resp.audio_bytes) or bool(resp.audio_data)
+    assert has_audio
+
+
+@pytest.mark.advanced_model
+@pytest.mark.core_model
+@pytest.mark.omni
+@hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards=2)
+@pytest.mark.parametrize("omni_server", prefix_cache_async_chunk_params, indirect=True)
+def test_thinker_prefix_caching_async_chunk_identical(omni_server, online_client) -> None:
+    """Production path: ``async_chunk: true`` plus thinker/talker prefix cache.
+
+    Two identical streaming requests. The second must report a block-aligned
+    cache hit and still produce text + audio (async output builder).
+    """
+    messages = dummy_messages_from_mix_data(
+        system_prompt=get_system_prompt(),
+        content_text=get_prompt(),
+    )
+    request_config = {
+        "model": omni_server.model,
+        "messages": messages,
+        "stream": True,
+        "stream_options": {"include_usage": True},
+    }
+    first_response, cached_response = _run_prefix_cache_check(online_client, request_config)
+    _assert_omni_payload_complete(first_response)
+    _assert_omni_payload_complete(cached_response)
+
+
+@pytest.mark.advanced_model
+@pytest.mark.core_model
+@pytest.mark.omni
+@hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards=2)
+@pytest.mark.parametrize("omni_server", prefix_cache_async_chunk_params, indirect=True)
+def test_thinker_prefix_caching_async_chunk_shared_image_prefix(omni_server, online_client) -> None:
+    """Shared image / system prefix, different user text — not a full-prompt replay.
+
+    The second request must still hit cached tokens (block-aligned, less than
+    its prompt). A merge that only works when ``hit_upto == prompt_len`` would
+    fail this.
+    """
+    image_data_url = f"data:image/jpeg;base64,{generate_synthetic_image(224, 224)['base64']}"
+    first_messages = dummy_messages_from_mix_data(
+        system_prompt=get_system_prompt(),
+        image_data_url=image_data_url,
+        content_text=get_prompt("text_image"),
+    )
+    second_messages = dummy_messages_from_mix_data(
+        system_prompt=get_system_prompt(),
+        image_data_url=image_data_url,
+        content_text="How many squares are in this image? Answer in 20 words.",
+    )
+    first_cfg = {
+        "model": omni_server.model,
+        "messages": first_messages,
+        "stream": True,
+        "stream_options": {"include_usage": True},
+        "modalities": ["text"],
+    }
+    second_cfg = {**first_cfg, "messages": second_messages}
+    first_response = online_client.send_omni_request(first_cfg, request_num=1)[0]
+    cached_response = online_client.send_omni_request(second_cfg, request_num=1)[0]
+    assert first_response.success and cached_response.success
+    assert first_response.text_content and cached_response.text_content
+    num_cached = cached_response.cached_tokens
+    num_prompt = cached_response.prompt_tokens
+    assert num_cached is not None and num_prompt is not None
+    assert num_cached > 0
+    assert num_cached % BLOCK_SIZE == 0
+    assert num_cached < num_prompt
+
+
 @pytest.mark.advanced_model
 @pytest.mark.core_model
 @pytest.mark.omni
diff --git a/tests/model_executor/models/voxcpm2/test_runner_assisted_unified_graph_static.py b/tests/model_executor/models/voxcpm2/test_runner_assisted_unified_graph_static.py
index 0007f021aa5..0c2d9ee67bf 100644
--- a/tests/model_executor/models/voxcpm2/test_runner_assisted_unified_graph_static.py
+++ b/tests/model_executor/models/voxcpm2/test_runner_assisted_unified_graph_static.py
@@ -74,7 +74,9 @@ def test_ar_runner_without_model_hook_stays_on_normal_path():
     assert "exceptException" not in compact_request_source
 
     set_context_source = source[source.index("def _set_runner_assisted_full_attention_metadata_context") :]
-    set_context_source = set_context_source[: set_context_source.index("def _deferred_prefix_cache_mm_keys")]
+    set_context_source = set_context_source[
+        : set_context_source.index("def _prepare_prefix_cache_pooler_payload_sources")
+    ]
     assert "except Exception" not in set_context_source
 
 
diff --git a/tests/platforms/npu/test_npu_prefix_cache_wiring.py b/tests/platforms/npu/test_npu_prefix_cache_wiring.py
new file mode 100644
index 00000000000..12cded5bab0
--- /dev/null
+++ b/tests/platforms/npu/test_npu_prefix_cache_wiring.py
@@ -0,0 +1,158 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""NPU prefix-cache wiring: save_outputs -> sid -> materialize on CPU.
+
+The NPU runner consumes the prefix cache in eager mode (no CUDA streams) and
+hands the step id across execute_model()/sample_tokens() as the LAST field of
+its positionally-packed ``ExecuteModelState``. Neither path runs in CUDA CI,
+so a hit-read change can silently break them (`vllm_ascend` imports keep the
+runner modules out of reach of a plain unit test).
+
+Two layers of protection, both pure CPU:
+
+1. AST characterization of the ``ExecuteModelState`` field order in the NPU
+   and GPU runners — the pack/unpack sites pass fields positionally, so a
+   reorder or drop of ``prefix_cache_step_id`` corrupts the sid without any
+   import-time error.
+2. The eager-mode facade contract the NPU runner relies on: controller
+   auto-selects eager when CUDA is unavailable, and save -> materialize
+   returns byte-identical rows for both the miss and the hit-merge paths.
+"""
+
+import ast
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+import torch
+
+from vllm_omni.core.prefix_cache.interface import PrefixCacheConfig
+from vllm_omni.core.prefix_cache.manager import OmniPrefixCacheManager
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+_REPO_ROOT = Path(__file__).resolve().parents[3]
+_NPU_RUNNER = _REPO_ROOT / "vllm_omni/platforms/npu/worker/npu_ar_model_runner.py"
+_GPU_RUNNER = _REPO_ROOT / "vllm_omni/worker/gpu_ar_model_runner.py"
+
+NUM_BLOCKS = 16
+BLOCK_SIZE = 4
+HIDDEN = 8
+DTYPE = torch.float32
+
+
+def _named_tuple_fields(path: Path, class_name: str) -> list[str]:
+    tree = ast.parse(path.read_text())
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ClassDef) and node.name == class_name:
+            return [stmt.target.id for stmt in node.body if isinstance(stmt, ast.AnnAssign)]
+    raise AssertionError(f"{class_name} not found in {path}")
+
+
+def test_execute_model_state_keeps_prefix_cache_sid_last():
+    """Both runners pack ExecuteModelState positionally: the sid must stay
+    the LAST field, and the NPU field order is pinned exactly — a reorder
+    passes import and every CUDA test, then ships the wrong value as the
+    sid on hardware."""
+    npu_fields = _named_tuple_fields(_NPU_RUNNER, "ExecuteModelState")
+    assert npu_fields == [
+        "scheduler_output",
+        "logits",
+        "spec_decode_metadata",
+        "spec_decode_common_attn_metadata",
+        "hidden_states",
+        "sample_hidden_states",
+        "aux_hidden_states",
+        "attn_metadata",
+        "positions",
+        "ec_connector_output",
+        "cudagraph_stats",
+        "batch_desc",
+        "multimodal_outputs",
+        "prefix_cache_step_id",
+    ]
+    gpu_fields = _named_tuple_fields(_GPU_RUNNER, "ExecuteModelState")
+    assert gpu_fields[-1] == "prefix_cache_step_id"
+
+
+class _FakeView:
+    """Minimal group-view double (mirrors tests/core/test_prefix_cache)."""
+
+    def __init__(self):
+        self.block_size = BLOCK_SIZE
+        self.num_blocks = NUM_BLOCKS
+        self.req_blocks: dict[str, list[int]] = {}
+        self.order: list[str] = []
+        self.computed: dict[str, int] = {}
+
+    def slots_for(self, req_id, token_start, token_end):
+        blocks = self.req_blocks[req_id]
+        return torch.tensor(
+            [blocks[p // BLOCK_SIZE] * BLOCK_SIZE + p % BLOCK_SIZE for p in range(token_start, token_end)],
+            dtype=torch.long,
+        )
+
+    def batch_req_ids(self) -> list[str]:
+        return list(self.order)
+
+    def step_slots_cpu(self, req_ids, num_scheduled) -> torch.Tensor:
+        parts = []
+        for r in req_ids:
+            n = int(num_scheduled.get(r, 0))
+            if n > 0:
+                start = self.computed.get(r, 0)
+                parts.append(self.slots_for(r, start, start + n))
+        return torch.cat(parts) if parts else torch.empty((0,), dtype=torch.long)
+
+
+def _run_step(mgr, view, req_id, blocks, start_pos, sched, *, hit=0, finished=()):
+    """One NPU-shaped step: new_step_starts -> save_outputs -> sid."""
+    view.order = [req_id]
+    view.req_blocks[req_id] = blocks
+    view.computed[req_id] = start_pos
+    slots = view.slots_for(req_id, start_pos, start_pos + sched)
+    hidden = slots.to(DTYPE).unsqueeze(1).expand(sched, HIDDEN).clone()
+    sched_out = SimpleNamespace(
+        scheduled_new_reqs=[
+            SimpleNamespace(req_id=req_id, num_computed_tokens=hit, block_ids=[list(blocks)]),
+        ],
+        finished_req_ids=set(finished),
+        num_scheduled_tokens={req_id: sched},
+    )
+    mgr.new_step_starts(sched_out)
+    return mgr.save_outputs(hidden, {}, num_tokens_unpadded=sched, num_tokens_padded=sched)
+
+
+def _expected_rows(slots: torch.Tensor) -> torch.Tensor:
+    return slots.to(DTYPE).unsqueeze(1).expand(slots.numel(), HIDDEN)
+
+
+def _make_npu_mode_manager(monkeypatch) -> tuple[OmniPrefixCacheManager, _FakeView]:
+    # The NPU condition: no CUDA -> the controller must auto-select eager
+    # (submit() completes copy+scatter synchronously), exactly how
+    # npu_model_runner builds the manager with the default eager=None.
+    monkeypatch.setattr(torch.cuda, "is_available", lambda: False)
+    view = _FakeView()
+    config = PrefixCacheConfig(num_blocks=NUM_BLOCKS, block_size=BLOCK_SIZE)
+    return OmniPrefixCacheManager(config, view), view
+
+
+def test_npu_mode_auto_selects_eager_and_roundtrips(monkeypatch):
+    mgr, view = _make_npu_mode_manager(monkeypatch)
+    assert mgr._controller._eager is True
+    sid = _run_step(mgr, view, "a", [0, 1], 0, 8)
+    outs = mgr.materialize(sid, ["a"])
+    assert torch.equal(outs.hidden_states["a"], _expected_rows(view.slots_for("a", 0, 8)))
+
+
+def test_npu_mode_hit_merges_cached_prefix(monkeypatch):
+    """The hit-read path in eager mode: consumer's merged output must be
+    [cached prefix rows + this step's rows], byte-identical."""
+    mgr, view = _make_npu_mode_manager(monkeypatch)
+    s1 = _run_step(mgr, view, "a", [0, 1], 0, 8)
+    mgr.materialize(s1, ["a"])
+    s2 = _run_step(mgr, view, "b", [0, 1, 2], 8, 4, hit=8, finished=["a"])
+    merged = mgr.materialize(s2, ["b"]).hidden_states["b"]
+    assert merged.shape == (12, HIDDEN)
+    assert torch.equal(merged[:8], _expected_rows(view.slots_for("b", 0, 8)))
+    assert torch.equal(merged[8:], _expected_rows(view.slots_for("b", 8, 12)))
diff --git a/tests/worker/test_fa3_scheduler_metadata_size.py b/tests/worker/test_fa3_scheduler_metadata_size.py
index 5e308bed775..ac7d1a75281 100644
--- a/tests/worker/test_fa3_scheduler_metadata_size.py
+++ b/tests/worker/test_fa3_scheduler_metadata_size.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Characterization of ``OmniGPUModelRunner.initialize_metadata_builders``.
 
 Upstream ``FlashAttentionMetadataBuilder`` pre-allocates ``scheduler_metadata``
@@ -19,14 +19,12 @@
 
 import pytest
 import torch
+from vllm.v1.worker.gpu_model_runner import GPUModelRunner
 
 from vllm_omni.worker.gpu_model_runner import OmniGPUModelRunner
 
 pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
 
-# The class ``super().initialize_metadata_builders`` dispatches to.
-_UPSTREAM_RUNNER = OmniGPUModelRunner.__mro__[1]
-
 
 def _builder(*, prealloc: int | None, max_num_splits: int) -> SimpleNamespace:
     sm = None if prealloc is None else torch.zeros(prealloc, dtype=torch.int32)
@@ -36,10 +34,14 @@ def _builder(*, prealloc: int | None, max_num_splits: int) -> SimpleNamespace:
 def _make_runner(monkeypatch, *, max_num_seqs: int, builders: list) -> OmniGPUModelRunner:
     # Stub the upstream initialize_metadata_builders; our fake runner already
     # carries the attn_groups the Omni override iterates over.
-    monkeypatch.setattr(_UPSTREAM_RUNNER, "initialize_metadata_builders", lambda self, *a, **k: None)
+    monkeypatch.setattr(GPUModelRunner, "initialize_metadata_builders", lambda self, *a, **k: None)
     runner = object.__new__(OmniGPUModelRunner)
     runner.scheduler_config = SimpleNamespace(max_num_seqs=max_num_seqs)
     runner.cache_config = SimpleNamespace(enable_prefix_caching=False)  # skip omni_prefix_cache branch
+    runner.vllm_config = SimpleNamespace(kv_transfer_config=None)
+    runner.model_config = SimpleNamespace()
+    runner.is_pooling_model = False
+    runner.speculative_config = None
     runner.attn_groups = [[SimpleNamespace(metadata_builders=builders)]]
     return runner
 
diff --git a/tests/worker/test_gpu_ar_model_runner.py b/tests/worker/test_gpu_ar_model_runner.py
index 33abbb618fd..d09282035ed 100644
--- a/tests/worker/test_gpu_ar_model_runner.py
+++ b/tests/worker/test_gpu_ar_model_runner.py
@@ -18,6 +18,7 @@
 from vllm.v1.worker import gpu_input_batch
 from vllm.v1.worker.gpu_input_batch import CachedRequestState, InputBatch
 
+from vllm_omni.core.prefix_cache import ModelCachePolicy
 from vllm_omni.entrypoints.openai.protocol.audio import OpenAICreateSpeechRequest
 from vllm_omni.entrypoints.openai.serving_speech import OmniOpenAIServingSpeech
 from vllm_omni.entrypoints.openai.tts_adapters.base import PreparedRequest
@@ -37,6 +38,8 @@
 
 def _make_runner(engine_output_type: str | None, downstream_req_ids: set[str]) -> GPUARModelRunner:
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     runner.vllm_config = SimpleNamespace(
         model_config=SimpleNamespace(engine_output_type=engine_output_type),
     )
@@ -57,6 +60,8 @@ def post_sample_talker_mtp(*, input_ids, hidden_states, req_ids, req_infos):
         return torch.tensor([[11, 12, 13]], dtype=torch.long)
 
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     runner.use_async_scheduling = async_scheduling
     runner.model = SimpleNamespace(post_sample_talker_mtp=post_sample_talker_mtp)
     runner.requests = {req_id: SimpleNamespace() for req_id in buffers}
@@ -143,6 +148,8 @@ def test_post_sample_talker_mtp_uses_gpu_token_with_async_scheduling() -> None:
 
 def test_post_sample_talker_mtp_skips_shape_validation_without_duplex_rows() -> None:
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     runner.use_async_scheduling = False
     runner.model = SimpleNamespace(
         post_sample_talker_mtp=lambda **_: pytest.fail("hook must not run"),
@@ -178,6 +185,8 @@ def test_post_sample_talker_mtp_rejects_invalid_selected_token_shape(
     error_match: str,
 ) -> None:
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     runner.use_async_scheduling = False
     runner.model = SimpleNamespace(
         post_sample_talker_mtp=lambda **_: pytest.fail("hook must not run"),
@@ -265,6 +274,8 @@ def apply_sampling_overrides(
 
     received = []
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     runner.input_batch = input_batch
     runner.model = SimpleNamespace(
         prefer_model_sampler=True,
@@ -323,6 +334,8 @@ def test_sparse_mm_req_ids_requires_sparse_audio_marker():
 
 def test_runner_assisted_full_attention_metadata_request_is_opt_in():
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     runner.model = object()
     runner.scheduler_config = SimpleNamespace(max_num_seqs=16)
 
@@ -377,6 +390,8 @@ def set_runner_assisted_full_attention_metadata_context(
             calls.append(("context", {"enabled": enabled, "num_reqs": num_reqs}))
 
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     runner.model = Model()
     runner.scheduler_config = SimpleNamespace(max_num_seqs=8)
 
@@ -466,6 +481,8 @@ def join(self):
 
 def _make_async_output_runner(engine_output_type: str = "audio"):
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     model_config = SimpleNamespace(
         engine_output_type=engine_output_type,
         async_chunk=True,
@@ -642,10 +659,11 @@ def test_async_omni_output_guard_requires_safe_conditions():
 
     assert GPUARModelRunner._should_use_async_omni_output(runner)
 
+    # Prefix cache no longer forces the sync output path; leftover mm is
+    # snapshotted at save so the builder can materialize a step late.
     runner.omni_prefix_cache = object()
-    assert not GPUARModelRunner._should_use_async_omni_output(runner)
+    assert GPUARModelRunner._should_use_async_omni_output(runner)
 
-    runner.omni_prefix_cache = None
     runner.model.has_postprocess = True
     assert not GPUARModelRunner._should_use_async_omni_output(runner)
 
@@ -656,6 +674,7 @@ def test_async_omni_output_guard_requires_safe_conditions():
 def test_build_omni_output_skips_hidden_when_model_opts_out(monkeypatch):
     runner = _make_async_output_runner(engine_output_type="latent")
     runner.model.omni_pooler_payload_include_hidden = False
+    runner._pooler_payload_include_hidden_flag = False
 
     monkeypatch.setattr(
         GPUARModelRunner,
@@ -699,6 +718,7 @@ def test_build_omni_output_skips_hidden_when_model_opts_out(monkeypatch):
 def test_build_omni_output_splits_mm_by_scheduled_tokens_when_hidden_is_tail_only(monkeypatch):
     runner = _make_async_output_runner(engine_output_type="latent")
     runner.model.omni_pooler_payload_include_hidden = False
+    runner._pooler_payload_include_hidden_flag = False
     runner._async_chunk = False
     runner.requests = {"r1": object(), "r2": object(), "r3": object()}
 
@@ -745,6 +765,7 @@ def test_build_omni_output_splits_mm_by_hidden_len_when_scheduled_is_padded(monk
     """Thinker mm rows align to hidden_states.shape[0], not padded scheduled count."""
     runner = _make_async_output_runner(engine_output_type="latent")
     runner.model.omni_pooler_payload_include_hidden = False
+    runner._pooler_payload_include_hidden_flag = False
     runner._async_chunk = False
     runner.requests = {"r1": object(), "r2": object(), "r3": object()}
 
@@ -790,6 +811,7 @@ def test_build_omni_output_splits_mm_by_hidden_len_when_scheduled_is_padded(monk
 def test_async_snapshot_payload_omits_hidden_when_model_opts_out():
     runner = _make_async_output_runner()
     runner.model.omni_pooler_payload_include_hidden = False
+    runner._pooler_payload_include_hidden_flag = False
 
     payload = GPUARModelRunner._build_omni_async_snapshot_payload(
         runner,
@@ -819,6 +841,8 @@ def commit_block_table(self, num_reqs_padded):
             self.commits.append(num_reqs_padded)
 
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     block_table = BlockTable()
     runner.input_batch = SimpleNamespace(
         num_computed_tokens_cpu=torch.tensor([10, 20, 99, 99], dtype=torch.int32),
@@ -846,6 +870,8 @@ def commit_block_table(self, num_reqs_padded):
 @pytest.mark.parametrize("query_start_loc_attr", ["method", "tensor_attr"])
 def test_sample_tokens_tail_only_prefix_cache_uses_staged_cpu_hidden_states(monkeypatch, query_start_loc_attr):
     runner = object.__new__(GPUARModelRunner)
+    runner._omni_cache_policy = ModelCachePolicy(needs_full_hidden_states=True)
+    runner._pooler_payload_include_hidden_flag = True
     runner.execute_model_state = ExecuteModelState(
         SimpleNamespace(
             total_num_scheduled_tokens=3,
@@ -908,12 +934,11 @@ def test_sample_tokens_tail_only_prefix_cache_uses_staged_cpu_hidden_states(monk
     )
     monkeypatch.setattr(GPUARModelRunner, "eplb_step", lambda self: None)
     monkeypatch.setattr(GPUARModelRunner, "_resolve_pooler_payload_req_ids", lambda self, req_ids: ("audio", req_ids))
-    monkeypatch.setattr(GPUARModelRunner, "_deferred_prefix_cache_mm_keys", lambda self: set())
     monkeypatch.setattr(GPUARModelRunner, "_model_needs_full_prefix_hidden_states", lambda self: False)
     monkeypatch.setattr(
         GPUARModelRunner,
-        "_maybe_get_combined_prefix_cache_tensors",
-        lambda *args, **kwargs: (None, None),
+        "_prepare_prefix_cache_pooler_payload_sources",
+        lambda self, **kwargs: (kwargs["staged_hidden_states_cpu"], None, None),
     )
     monkeypatch.setattr(GPUARModelRunner, "_process_additional_information_updates", lambda *args, **kwargs: None)
     monkeypatch.setattr(GPUARModelRunner, "_should_accumulate_full_payload_output", lambda self: False)
@@ -946,8 +971,6 @@ def test_build_omni_output_falls_back_to_mm_cpu_without_prefix_merge(monkeypatch
         lambda self, req_ids: ("latent", req_ids),
     )
     monkeypatch.setattr(GPUARModelRunner, "_model_needs_full_prefix_hidden_states", lambda self: False)
-    monkeypatch.setattr(GPUARModelRunner, "_deferred_prefix_cache_mm_keys", lambda self: {"codes.audio"})
-    monkeypatch.setattr(GPUARModelRunner, "_stage_deferred_prefix_cache_mm_outputs", lambda *args, **kwargs: None)
     monkeypatch.setattr(
         GPUARModelRunner,
         "_prepare_prefix_cache_pooler_payload_sources",
@@ -1095,8 +1118,6 @@ def test_build_omni_output_filters_multimodal_by_partial_downstream_batch(monkey
         lambda self, req_ids: ("latent", ["r1", "r3"]),
     )
     monkeypatch.setattr(GPUARModelRunner, "_model_needs_full_prefix_hidden_states", lambda self: False)
-    monkeypatch.setattr(GPUARModelRunner, "_deferred_prefix_cache_mm_keys", lambda self: {"codes.audio"})
-    monkeypatch.setattr(GPUARModelRunner, "_stage_deferred_prefix_cache_mm_outputs", lambda *args, **kwargs: None)
     monkeypatch.setattr(
         GPUARModelRunner,
         "_prepare_prefix_cache_pooler_payload_sources",
@@ -1172,8 +1193,6 @@ def test_build_omni_output_uses_combined_prefix_cache_mm_payload_for_partial_dow
         lambda self, req_ids: ("latent", ["r1", "r3"]),
     )
     monkeypatch.setattr(GPUARModelRunner, "_model_needs_full_prefix_hidden_states", lambda self: False)
-    monkeypatch.setattr(GPUARModelRunner, "_deferred_prefix_cache_mm_keys", lambda self: {"codes.audio"})
-    monkeypatch.setattr(GPUARModelRunner, "_stage_deferred_prefix_cache_mm_outputs", lambda *args, **kwargs: None)
     monkeypatch.setattr(
         GPUARModelRunner,
         "_prepare_prefix_cache_pooler_payload_sources",
diff --git a/vllm_omni/core/prefix_cache.py b/vllm_omni/core/prefix_cache.py
deleted file mode 100644
index 17a9811402f..00000000000
--- a/vllm_omni/core/prefix_cache.py
+++ /dev/null
@@ -1,737 +0,0 @@
-"""
-Utilities for Prefix Caching in Omni models.
-"""
-
-from dataclasses import dataclass, field
-
-import torch
-from vllm.logger import init_logger
-from vllm.v1.worker.gpu_input_batch import InputBatch
-
-from vllm_omni.utils.mm_outputs import build_mm_cpu, to_payload_element
-
-logger = init_logger(__name__)
-
-
-@dataclass
-class _PendingAsyncWrite:
-    """One in-flight async write into the prefix cache.
-
-    Holds the CPU tensors that PyTorch implicitly allocated via
-    ``.to("cpu", non_blocking=True)`` together with a CUDA event recorded
-    on the copy stream. The consumer calls ``event.synchronize()`` once
-    (blocking) to guarantee the D2H has completed before reading.
-    """
-
-    event: "torch.cuda.Event"
-    num_tokens: int
-    slots_cpu: torch.Tensor
-    hidden_cpu: torch.Tensor | None
-    mm_cpu: dict[str, torch.Tensor] = field(default_factory=dict)
-
-
-class OmniTensorPrefixCache:
-    """Prefix cache for hidden states (model outputs) and model specific
-    multimodal outputs.
-
-    This class implements prefix caching in a non-invasive way on top of
-    vLLM by leveraging the same slot mappings that the vLLM scheduler uses
-    for the KV Cache.
-
-    Conceptually, this means we are mapping vLLM's cache mapping:
-                        (num_blocks, block_size)
-
-    to 3D tensors of shape:
-                   (num_blocks, block_size, feature_size)
-
-    Note that feature_size may vary across multimodal_outputs.
-    """
-
-    def __init__(
-        self,
-        num_blocks: int,
-        block_size: int,
-        hidden_size: int,
-        hs_dtype: torch.dtype,
-    ):
-        self.num_blocks = num_blocks
-        self.block_size = block_size
-        self.default_hidden_size = hidden_size
-
-        # Initialize the hidden states cache immediately
-        self.hidden_states_cache = self._get_cache_tensor(dtype=hs_dtype)
-
-        # Defer initialization of the mm_outputs_cache until we
-        # actually see mm output tensors dependent on num tokens.
-        self.mm_outputs_cache = {}
-        self.mm_cache_keys = set()
-        self._new_req_cache_hit_ids: set[str] = set()
-        self._deferred_mm_outputs: dict[str, dict[str, list[tuple[int, torch.Tensor]]]] = {}
-
-        # Async write pipeline state:
-        #   - one dedicated copy stream
-        #   - one in-flight pending write at a time (the producer is exactly
-        #     one forward step ahead of the consumer)
-        #   - schedule_async_write() consumes the *previous* pending write
-        #     (via event.synchronize() + scatter) before kicking off the new
-        #     D2H. By the time we hit synchronize, the previous step's GPU
-        #     work has been done for ~one forward step, so the sync is
-        #     near-zero wall-clock.
-        self._async_initialized: bool = False
-        self._async_copy_stream: torch.cuda.Stream | None = None
-        self._pending_write: _PendingAsyncWrite | None = None
-
-    def maybe_init_missing_mm_cache_keys(self, multimodal_outputs: dict, seq_len: int):
-        """Given multimodal outputs from executing the model, dynamically
-        determine which multimodal outputs are tensors depending on sequence
-        length and should be cached, and initialize the cache tensors
-        accordingly.
-
-        NOTE: This is done to avoid the need for explicit specification of
-        cache keys for every model/stage and aligns with the current way
-        that we slice the multimodal outputs based on the first dimension.
-
-        This will usually be called by the first forward pass, i.e.,
-        determined by the warmup.
-        """
-        for key, val in multimodal_outputs.items():
-            # Only cache per-token feature tensors: 2D+ with first dim == seq_len.
-            # A 1D tensor of shape (seq_len,) is a broadcast scalar (per-request
-            # metadata such as ref_code_len / codec_streaming), not per-token data;
-            # caching it by slot causes a shape mismatch when a later request has a
-            # different scheduled seq length.
-            if (
-                isinstance(val, torch.Tensor)
-                and val.ndim >= 2
-                and val.shape[0] == seq_len
-                and key not in self.mm_cache_keys
-            ):
-                feat_dim = val.shape[-1]
-                self.mm_outputs_cache[key] = self._get_cache_tensor(
-                    dtype=val.dtype,
-                    hidden_size=feat_dim,
-                )
-                self.mm_cache_keys.add(key)
-                new_tensor_shape = self.mm_outputs_cache[key].shape
-                logger.info("Initializing multimodal output cache of size %s for key: %s", list(new_tensor_shape), key)
-
-    def _get_cache_tensor(self, dtype: torch.dtype, hidden_size: int | None = None) -> torch.Tensor:
-        """Allocate a CPU cache tensor for a specific key.
-
-        When CUDA is available the tensor is pinned: this is what lets the
-        async-write pipeline ride the GPU->CPU copy on the dedicated copy
-        stream as a true async ``cudaMemcpyAsync`` and lets the post-copy CPU
-        scatter avoid page-resolution stalls. On CPU-only builds pinning is
-        unsupported (``torch.zeros(pin_memory=True)`` raises), and the async
-        pipeline is disabled anyway (``schedule_async_write`` early-returns
-        when ``torch.cuda.is_available()`` is False), so we fall back to a
-        plain pageable allocation with no behavioral change.
-        """
-        actual_hidden_size = hidden_size if hidden_size is not None else self.default_hidden_size
-        return torch.zeros(
-            (self.num_blocks, self.block_size, actual_hidden_size),
-            dtype=dtype,
-            device="cpu",
-            pin_memory=torch.cuda.is_available(),
-        )
-
-    # =====================================================================
-    # Async write pipeline:
-    #   schedule_async_write : called per forward step, enqueues a
-    #                          non-blocking D2H + records a CUDA event
-    #   drain_ready_async_writes : non-blocking poll, applies any writes
-    #                              whose D2H has completed
-    # =====================================================================
-
-    def _ensure_async_resources(self) -> None:
-        """Lazily allocate the dedicated copy stream.
-
-        The per-step CPU staging tensors are allocated by PyTorch on demand
-        inside ``.to("cpu", non_blocking=True)``, which gives them
-        implicitly-pinned memory and lets PyTorch's allocator amortize /
-        reuse them.
-        """
-        if self._async_initialized:
-            return
-        if not torch.cuda.is_available():
-            return
-        self._async_copy_stream = torch.cuda.Stream()
-        self._async_initialized = True
-        logger.info("Omni prefix cache async-write copy stream initialized.")
-
-    def schedule_async_write(
-        self,
-        hidden_states_gpu: torch.Tensor | None,
-        multimodal_outputs_gpu: dict[str, torch.Tensor] | None,
-        slot_mapping_gpu: torch.Tensor,
-        num_tokens_unpadded: int,
-        num_tokens_padded: int,
-        skip_mm_cache_keys: set[str] | None = None,
-    ) -> None:
-        """Kick off a non-blocking GPU->CPU copy for this step's writes.
-
-        1. **Consume the previous step's write** (if any): block on its
-           event and scatter the CPU tensors into the cache. By the time we
-           reach this point, the previous step's GPU work has been done for
-           ~one forward step, so the synchronize is near-zero wall-clock.
-        2. **Schedule THIS step's D2H** on a dedicated copy stream using
-           ``.to("cpu", non_blocking=True)``. PyTorch allocates the pinned
-           destination implicitly.
-        3. **Record an event** and stash everything for the next step's
-           consume.
-
-        Holding exactly one in-flight write at a time keeps the design
-        simple: no ring, no event-polling, no driver-mutex pressure from
-        repeated event.query() calls.
-        """
-        if not torch.cuda.is_available():
-            return
-
-        self._ensure_async_resources()
-        if not self._async_initialized:
-            return
-
-        # Decide which mm keys we'll cache. Init the dest cache tensors
-        # before scheduling the copies so the apply step has somewhere
-        # to scatter into.
-        skip = skip_mm_cache_keys or set()
-        cacheable_mm_keys: list[str] = []
-        if multimodal_outputs_gpu:
-            self.maybe_init_missing_mm_cache_keys(multimodal_outputs_gpu, seq_len=num_tokens_padded)
-            for k in self.mm_cache_keys:
-                if k in skip:
-                    continue
-                v = multimodal_outputs_gpu.get(k)
-                if not isinstance(v, torch.Tensor) or v.ndim < 2:
-                    continue
-                if v.shape[0] < num_tokens_unpadded:
-                    continue
-                cacheable_mm_keys.append(k)
-
-        # Step 1: consume the previous step's write FIRST. The previous
-        # step's event was recorded ~one forward step ago, so
-        # synchronize() is effectively a no-op cost-wise; the scatter
-        # into pinned CPU caches is also fast.
-        self._consume_pending_write()
-
-        if hidden_states_gpu is None and not cacheable_mm_keys:
-            return  # nothing to schedule this step
-
-        # Step 2: schedule the D2H on the copy stream. PyTorch implicitly
-        # allocates pinned host destinations for the ``.to("cpu",
-        # non_blocking=True)`` results.
-        copy_stream = self._async_copy_stream
-        default_stream = torch.cuda.current_stream()
-        with torch.cuda.stream(copy_stream):
-            copy_stream.wait_stream(default_stream)
-
-            # slot_mapping: copy as-is; the int64 cast required by
-            # ``index_copy_`` is deferred to ``_consume_pending_write``
-            # so we avoid launching an extra GPU kernel here that would
-            # contend the driver mutex with the compute stream.
-            slots_cpu = slot_mapping_gpu[:num_tokens_unpadded].to("cpu", non_blocking=True)
-            hidden_cpu: torch.Tensor | None = None
-            if hidden_states_gpu is not None:
-                hidden_cpu = hidden_states_gpu[:num_tokens_unpadded].to("cpu", non_blocking=True)
-            mm_cpu: dict[str, torch.Tensor] = {}
-            for k in cacheable_mm_keys:
-                mm_cpu[k] = multimodal_outputs_gpu[k][:num_tokens_unpadded].to("cpu", non_blocking=True)
-
-            event = torch.cuda.Event()
-            event.record()
-
-        # Step 3: stash for next step's consume.
-        self._pending_write = _PendingAsyncWrite(
-            event=event,
-            num_tokens=num_tokens_unpadded,
-            slots_cpu=slots_cpu,
-            hidden_cpu=hidden_cpu,
-            mm_cpu=mm_cpu,
-        )
-
-    def drain_ready_async_writes(self) -> int:
-        """Consume one in-flight write if it has finished (non-blocking).
-
-        Exposed so the model runner can drain at the top of
-        ``execute_model`` regardless of whether a new write will be
-        scheduled this step.
-        """
-        if self._pending_write is None:
-            return 0
-        if not self._pending_write.event.query():
-            return 0
-        self._consume_pending_write()
-        return 1
-
-    def _consume_pending_write(self) -> None:
-        """Synchronize on the pending event and scatter the CPU tensors
-        into the destination caches. Drops state on completion.
-        """
-        entry = self._pending_write
-        if entry is None:
-            return
-        self._pending_write = None
-        entry.event.synchronize()
-        n = entry.num_tokens
-        if n <= 0:
-            return
-
-        slots = entry.slots_cpu
-        if slots.dtype != torch.int64:
-            slots = slots.to(torch.int64)
-
-        # NOTE: ``index_copy_(0, idx, src)`` is the row-scatter primitive in
-        # PyTorch. It's semantically identical to ``flat[idx] = src`` but
-        # dispatches to a much simpler CPU implementation (single dim,
-        # no broadcasting, no accumulate), which on pinned memory at large
-        # row sizes is observed to be much faster than the generic
-        # ``aten::index_put_`` path used by advanced-indexing assignment.
-        if entry.hidden_cpu is not None:
-            flat = self.hidden_states_cache.view(-1, self.hidden_states_cache.shape[-1])
-            flat.index_copy_(0, slots, entry.hidden_cpu)
-        for k, src_cpu in entry.mm_cpu.items():
-            mm_cache = self.mm_outputs_cache.get(k)
-            if mm_cache is None:
-                continue
-            flat = mm_cache.view(-1, mm_cache.shape[-1])
-            flat.index_copy_(0, slots, src_cpu)
-
-    def add_prefix_cached_new_req_id(self, req_id: str):
-        """Adds a new request ID to the set of prefix cache hits on the batch."""
-        self._new_req_cache_hit_ids.add(req_id)
-
-    def reset_prefix_cached_new_req_ids(self):
-        """Clears the cache hit IDs to prepare for a new engine step."""
-        self._new_req_cache_hit_ids.clear()
-
-    def has_prefix_cached_new_req_ids(self) -> bool:
-        """Return True when this step contains a newly scheduled prefix hit."""
-        return bool(self._new_req_cache_hit_ids)
-
-    @staticmethod
-    def _coerce_to_cpu_tensor(maybe_gpu_tensor: torch.Tensor) -> torch.Tensor:
-        """Convert GPU tensors -> contiguous CPU tensors if needed."""
-        return maybe_gpu_tensor.detach().cpu().contiguous()
-
-    @staticmethod
-    def _resolve_hidden_states_cpu(
-        hidden_states: torch.Tensor,
-        num_tokens: int,
-        hidden_states_cpu: torch.Tensor | None,
-    ) -> torch.Tensor:
-        if hidden_states_cpu is None:
-            return OmniTensorPrefixCache._coerce_to_cpu_tensor(hidden_states[:num_tokens])
-        if hidden_states_cpu.device.type != "cpu":
-            raise RuntimeError("hidden_states_cpu must be a CPU tensor.")
-        if not hidden_states_cpu.is_contiguous():
-            raise RuntimeError("hidden_states_cpu must be contiguous.")
-        if hidden_states_cpu.dtype != hidden_states.dtype:
-            raise RuntimeError(
-                "hidden_states_cpu has an incompatible dtype: "
-                f"got {hidden_states_cpu.dtype}, expected {hidden_states.dtype}."
-            )
-        if hidden_states_cpu.shape[1:] != hidden_states.shape[1:]:
-            raise RuntimeError(
-                "hidden_states_cpu has an incompatible feature shape: "
-                f"got {tuple(hidden_states_cpu.shape[1:])}, expected {tuple(hidden_states.shape[1:])}."
-            )
-        if hidden_states_cpu.shape[0] < num_tokens:
-            raise RuntimeError(
-                "hidden_states_cpu does not cover the requested hidden states "
-                f"slice: got {hidden_states_cpu.shape[0]} tokens, need {num_tokens}."
-            )
-        return hidden_states_cpu[:num_tokens]
-
-    def update_omni_tensor_prefix_cache(
-        self,
-        hidden_states: torch.Tensor | None,
-        multimodal_outputs: dict[str, torch.Tensor] | None,
-        num_tokens_unpadded: int,
-        slot_mapping: torch.Tensor,
-        num_tokens_padded: int | None = None,
-        skip_mm_cache_keys: set[str] | None = None,
-        hidden_states_cpu: torch.Tensor | None = None,
-    ):
-        """Updates the hidden cache state for the provided hidden states and multimodal outputs.
-
-        Args:
-            hidden_states: Hidden states tensor to cache (if any)
-            multimodal_outputs: Multimodal dict whose tensors may be cached
-            num_tokens_unpadded: Number of tokens without padding
-            slot_mapping: Slot mapping for the input sequence
-            num_tokens_padded: Total number of tokens including padding
-            skip_mm_cache_keys: Multimodal keys whose CPU cache writes are deferred
-            hidden_states_cpu: Optional pre-staged CPU view of hidden_states.
-                When provided, it must be contiguous, live on CPU, match the
-                feature shape of hidden_states, and cover num_tokens_unpadded.
-        """
-        unpadded_slot_mapping = slot_mapping[:num_tokens_unpadded]
-        if num_tokens_padded is None:
-            num_tokens_padded = num_tokens_unpadded
-        skip_mm_cache_keys = skip_mm_cache_keys or set()
-
-        if hidden_states is not None:
-            # Slice to unpadded portion before caching
-            hidden_states = OmniTensorPrefixCache._resolve_hidden_states_cpu(
-                hidden_states,
-                num_tokens_unpadded,
-                hidden_states_cpu,
-            )
-            # View the cache as 2D so that we can treat our slots as row indices.
-            # ``index_copy_`` is the row-scatter primitive — it's semantically
-            # ``cache[idx] = src`` but dispatches to a faster CPU path than the
-            # generic advanced-indexing assignment (which goes through
-            # ``aten::index_put_`` and is dominated by per-row dispatch
-            # overhead on large feature widths).
-            flat_cache = self.hidden_states_cache.view(-1, self.hidden_states_cache.shape[-1])
-            slot_idx = unpadded_slot_mapping
-            if slot_idx.dtype != torch.int64:
-                slot_idx = slot_idx.to(torch.int64)
-            flat_cache.index_copy_(0, slot_idx, hidden_states)
-            logger.debug("Writing to hidden states for %s tokens", num_tokens_unpadded)
-
-        # Do the same for the stage's cached multimodal outputs
-        if multimodal_outputs is not None:
-            # If we haven't initialized the keys already, do it now
-            # We check against the padded token count since we haven't sliced yet
-            self.maybe_init_missing_mm_cache_keys(
-                multimodal_outputs,
-                seq_len=num_tokens_padded,
-            )
-
-            for mm_out_key, mm_cache in self.mm_outputs_cache.items():
-                if mm_out_key in multimodal_outputs:
-                    if mm_out_key in skip_mm_cache_keys:
-                        continue
-                    # Slice to unpadded portion before caching
-                    mm_state = multimodal_outputs[mm_out_key][:num_tokens_unpadded]
-                    mm_state = OmniTensorPrefixCache._coerce_to_cpu_tensor(mm_state)
-                    flat_cache = mm_cache.view(-1, mm_cache.shape[-1])
-                    slot_idx = unpadded_slot_mapping
-                    if slot_idx.dtype != torch.int64:
-                        slot_idx = slot_idx.to(torch.int64)
-                    flat_cache.index_copy_(0, slot_idx, mm_state)
-            logger.debug("Writing to mm output cache for %s tokens", num_tokens_unpadded)
-
-    def stage_deferred_mm_outputs(
-        self,
-        query_start_loc: torch.Tensor,
-        input_batch: InputBatch,
-        multimodal_outputs: dict[str, torch.Tensor] | None,
-        num_scheduled_tokens: dict[str, int],
-        deferred_mm_cache_keys: set[str],
-    ) -> None:
-        """Keep GPU multimodal chunks until a request finishes.
-
-        The normal prefix-cache write path copies every cached multimodal tensor
-        to CPU on every step.  For model outputs that are only needed by future
-        full-block prefix hits, we can keep detached GPU chunks and materialize
-        the CPU cache once when the request completes.
-        """
-        if not multimodal_outputs or not deferred_mm_cache_keys:
-            return
-
-        for mm_key in deferred_mm_cache_keys:
-            mm_state = multimodal_outputs.get(mm_key)
-            if not isinstance(mm_state, torch.Tensor) or mm_state.ndim < 2:
-                continue
-            for req_id in input_batch.req_ids:
-                req_idx = input_batch.req_id_to_index[req_id]
-                sched = int(num_scheduled_tokens.get(req_id, 0))
-                if sched <= 0:
-                    continue
-                start = int(query_start_loc[req_idx])
-                end = start + sched
-                if start >= int(mm_state.shape[0]):
-                    continue
-                end = min(end, int(mm_state.shape[0]))
-                if end <= start:
-                    continue
-
-                computed_end = int(input_batch.num_computed_tokens_cpu[req_idx])
-                token_start = max(0, computed_end - sched)
-                chunk = mm_state[start:end].detach()
-                self._deferred_mm_outputs.setdefault(req_id, {}).setdefault(mm_key, []).append((token_start, chunk))
-
-    def commit_deferred_mm_outputs(
-        self,
-        finished_req_ids: set[str] | list[str],
-        input_batch: InputBatch,
-    ) -> None:
-        """Write deferred multimodal chunks into the CPU prefix cache.
-
-        This must run before finished requests are removed from ``input_batch``,
-        because the block table is needed to map logical token positions to KV
-        cache slots.
-        """
-        if not finished_req_ids or not self._deferred_mm_outputs:
-            return
-
-        for req_id in tuple(finished_req_ids):
-            per_key = self._deferred_mm_outputs.pop(req_id, None)
-            if not per_key:
-                continue
-            req_idx = input_batch.req_id_to_index.get(req_id)
-            if req_idx is None:
-                continue
-            for mm_key, chunks in per_key.items():
-                self._commit_deferred_mm_key(req_idx, input_batch, mm_key, chunks)
-
-    def discard_deferred_mm_outputs(self, req_id: str) -> None:
-        """Drop deferred chunks for requests that leave without a cache commit."""
-        self._deferred_mm_outputs.pop(req_id, None)
-
-    def _commit_deferred_mm_key(
-        self,
-        req_idx: int,
-        input_batch: InputBatch,
-        mm_key: str,
-        chunks: list[tuple[int, torch.Tensor]],
-    ) -> None:
-        if not chunks:
-            return
-
-        chunks = sorted(chunks, key=lambda item: item[0])
-        first_start = chunks[0][0]
-        expected_start = first_start
-        tensors: list[torch.Tensor] = []
-        for token_start, tensor in chunks:
-            if tensor.numel() == 0:
-                continue
-            if token_start != expected_start:
-                if tensors:
-                    self._write_deferred_mm_tensor(req_idx, input_batch, mm_key, tensors, first_start)
-                first_start = token_start
-                expected_start = token_start
-                tensors = []
-            tensors.append(tensor)
-            expected_start += int(tensor.shape[0])
-
-        if tensors:
-            self._write_deferred_mm_tensor(req_idx, input_batch, mm_key, tensors, first_start)
-
-    def _write_deferred_mm_tensor(
-        self,
-        req_idx: int,
-        input_batch: InputBatch,
-        mm_key: str,
-        tensors: list[torch.Tensor],
-        token_start: int,
-    ) -> None:
-        mm_state = tensors[0] if len(tensors) == 1 else torch.cat(tensors, dim=0)
-        if mm_state.ndim < 2 or mm_state.shape[0] == 0:
-            return
-
-        if mm_key not in self.mm_cache_keys:
-            self.mm_outputs_cache[mm_key] = self._get_cache_tensor(
-                dtype=mm_state.dtype,
-                hidden_size=int(mm_state.shape[-1]),
-            )
-            self.mm_cache_keys.add(mm_key)
-            logger.info(
-                "Initializing deferred multimodal output cache of size %s for key: %s",
-                list(self.mm_outputs_cache[mm_key].shape),
-                mm_key,
-            )
-
-        slots = self._get_slot_ids_for_token_range(
-            req_idx=req_idx,
-            input_batch=input_batch,
-            token_start=token_start,
-            num_tokens=int(mm_state.shape[0]),
-        )
-        if slots.numel() == 0:
-            return
-
-        mm_state_cpu = OmniTensorPrefixCache._coerce_to_cpu_tensor(mm_state[: slots.numel()])
-        mm_cache = self.mm_outputs_cache[mm_key]
-        flat_cache = mm_cache.view(-1, mm_cache.shape[-1])
-        if slots.dtype != torch.int64:
-            slots = slots.to(torch.int64)
-        flat_cache.index_copy_(0, slots, mm_state_cpu)
-
-    def _get_slot_ids_for_token_range(
-        self,
-        req_idx: int,
-        input_batch: InputBatch,
-        token_start: int,
-        num_tokens: int,
-    ) -> torch.Tensor:
-        if num_tokens <= 0:
-            return torch.empty((0,), dtype=torch.long)
-
-        block_table = input_batch.block_table[0].block_table.cpu
-        token_positions = torch.arange(token_start, token_start + num_tokens, dtype=torch.long)
-        block_offsets = token_positions // self.block_size
-        max_blocks = int(block_table.shape[1])
-        valid = block_offsets < max_blocks
-        if not bool(valid.all()):
-            token_positions = token_positions[valid]
-            block_offsets = block_offsets[valid]
-        if token_positions.numel() == 0:
-            return torch.empty((0,), dtype=torch.long)
-
-        block_ids = block_table[req_idx, block_offsets].to(torch.long)
-        return block_ids * self.block_size + (token_positions % self.block_size)
-
-    def _coerce_to_payload_dict(
-        self,
-        element: object,
-        query_start_loc: torch.Tensor,
-        input_batch: InputBatch,
-        num_scheduled_tokens: dict[str, int],
-    ) -> dict[str, object]:
-        """Build the multimodal passthrough data per request for
-        the object under consideration. This mirrors the no-prefix-cache
-        path: a tensor whose first dimension matches the total scheduled
-        token count is sliced per request, so 1D (seq_len,) metadata that
-        is intentionally not cached (e.g. ref_code_len, codec_streaming)
-        is still split per request instead of leaking the whole batch.
-        """
-        total_scheduled_tokens = sum(int(num_scheduled_tokens[r]) for r in input_batch.req_ids)
-        elem_dict = {}
-        for req_id in input_batch.req_ids:
-            req_idx = input_batch.req_id_to_index[req_id]
-            start = query_start_loc[req_idx]
-            end = start + num_scheduled_tokens[req_id]
-            elem_dict[req_id] = to_payload_element(
-                element,
-                req_idx,
-                start=start,
-                end=end,
-                pass_lists_through=True,
-                seq_len=total_scheduled_tokens,
-            )
-        return elem_dict
-
-    def get_merged_multimodal_states(
-        self,
-        query_start_loc: torch.Tensor,
-        input_batch: InputBatch,
-        multimodal_outputs: dict | None,
-        num_scheduled_tokens: dict[str, int],
-    ):
-        """Get the merged multimodal states if hidden state prefix caching is enabled."""
-        combined_multimodal_outputs = {}
-        # Talkers that produce multimodal outputs only at decode (e.g. Higgs
-        # Audio v3's audio codes) have ``multimodal_outputs is None`` at the
-        # initial prefill step. Treat it as an empty mapping so the merger
-        # short-circuits cleanly and the cache merge still runs once codes
-        # start arriving.
-        mm_outputs = multimodal_outputs if multimodal_outputs is not None else {}
-        # First get the prefix cached tensors that are present in the mm data
-        for mm_key in self.mm_cache_keys:
-            if mm_key in mm_outputs:
-                combined_multimodal_outputs[mm_key] = self._get_merged_tensors(
-                    query_start_loc=query_start_loc,
-                    input_batch=input_batch,
-                    cache=self.mm_outputs_cache[mm_key],
-                    hidden_states=mm_outputs[mm_key],
-                    num_scheduled_tokens=num_scheduled_tokens,
-                )
-
-        # Then, get everything else (passthrough data); first, convert to CPU
-        # tensors similarly to the non prefix cached path, and then populate
-        # the subdicts mapping request IDs -> payload objects
-        passthrough_keys = set(mm_outputs.keys()) - self.mm_cache_keys
-        passthrough_mm_data = {k: v for k, v in mm_outputs.items() if k in passthrough_keys}
-        mm_cpu = build_mm_cpu(multimodal_outputs=passthrough_mm_data)
-
-        for mm_key, mm_val in mm_cpu.items():
-            combined_multimodal_outputs[mm_key] = self._coerce_to_payload_dict(
-                element=mm_val,
-                query_start_loc=query_start_loc,
-                input_batch=input_batch,
-                num_scheduled_tokens=num_scheduled_tokens,
-            )
-        return combined_multimodal_outputs
-
-    def get_merged_hidden_states(
-        self,
-        query_start_loc: torch.Tensor,
-        input_batch: InputBatch,
-        hidden_states: torch.Tensor,
-        num_scheduled_tokens: dict[str, int],
-        hidden_states_cpu: torch.Tensor | None = None,
-    ) -> dict[str, torch.Tensor]:
-        """Get merged hidden states, optionally reusing pre-staged CPU states.
-
-        When provided, hidden_states_cpu follows the same contract as
-        update_omni_tensor_prefix_cache: CPU, contiguous, same dtype and feature
-        shape as hidden_states, and covering every scheduled-token span derived
-        from query_start_loc and num_scheduled_tokens.
-        """
-        return self._get_merged_tensors(
-            query_start_loc=query_start_loc,
-            input_batch=input_batch,
-            hidden_states=hidden_states,
-            num_scheduled_tokens=num_scheduled_tokens,
-            staged_cpu_tensor=hidden_states_cpu,
-            cache=self.hidden_states_cache,
-        )
-
-    def _get_merged_tensors(
-        self,
-        query_start_loc: torch.Tensor,
-        input_batch: InputBatch,
-        cache: torch.Tensor,
-        hidden_states: torch.Tensor,
-        num_scheduled_tokens: dict[str, int],
-        staged_cpu_tensor: torch.Tensor | None = None,
-    ) -> dict[str, torch.Tensor]:
-        """When hidden state caching is enabled, takes the input hidden_states,
-        which only correspond to the scheduled tokens, and returns a mapping
-        from request IDs to their full hidden states. This is accomplished by
-        looking up the block IDs & scheduled token counts to split the
-        hidden_states. staged_cpu_tensor can supply the already materialized CPU
-        scheduled-token view; None preserves the legacy per-call CPU conversion.
-        """
-        # We do not support hybrid caches at the moment.
-        if len(input_batch.block_table.block_tables) > 1:
-            logger.warning_once(
-                "Omni prefix caching is enabled, but the batch block table appears to"
-                " have multiple kv groups; only the first group will be used!"
-            )
-
-        combined_hidden_states = {}
-        required_tokens = 0
-        for req_id in input_batch.req_ids:
-            req_idx = input_batch.req_id_to_index[req_id]
-            start = query_start_loc[req_idx]
-            end = start + num_scheduled_tokens[req_id]
-            required_tokens = max(required_tokens, int(end))
-        hidden_states = OmniTensorPrefixCache._resolve_hidden_states_cpu(
-            hidden_states,
-            required_tokens,
-            staged_cpu_tensor,
-        )
-        for req_id in input_batch.req_ids:
-            req_idx = input_batch.req_id_to_index[req_id]
-
-            if req_id in self._new_req_cache_hit_ids:
-                block_ids = self._get_cached_block_ids(req_idx, input_batch)
-                cached_hs = cache[block_ids].reshape(-1, cache.shape[-1])
-
-                # Slice the hidden states corresponding to this request;
-                # we do this by using the query start
-                start = query_start_loc[req_idx]
-                new_hs = hidden_states[start : start + num_scheduled_tokens[req_id]]
-                combined_hidden_states[req_id] = torch.cat([cached_hs, new_hs], dim=0)
-            else:
-                # cache miss for this request, pass through normally
-                start = query_start_loc[req_idx]
-                new_hs = hidden_states[start : start + num_scheduled_tokens[req_id]]
-                combined_hidden_states[req_id] = new_hs
-
-        return combined_hidden_states
-
-    def _get_cached_block_ids(self, req_idx: int, input_batch: InputBatch) -> torch.Tensor:
-        """Given an input batch and request index in the batch (not ID), get the
-        block IDs corresponding to the cache hit.
-        """
-        num_computed = input_batch.num_computed_tokens_cpu[req_idx]
-        # NOTE: vLLM only caches full blocks
-        num_cached_blocks = num_computed // self.block_size
-        # Get the block IDs attached to this cache hit and reindex into
-        # the flattened cached hidden states (i.e., 1 row per token).
-        return input_batch.block_table[0].block_table.cpu[req_idx, :num_cached_blocks]
diff --git a/vllm_omni/core/prefix_cache/__init__.py b/vllm_omni/core/prefix_cache/__init__.py
new file mode 100644
index 00000000000..4d14da6fae6
--- /dev/null
+++ b/vllm_omni/core/prefix_cache/__init__.py
@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Omni prefix cache.
+
+Structure mirrors vllm/v1/core.
+
+Import invariant: this package must not import ``vllm`` at module
+scope (``TYPE_CHECKING`` and function-body imports are fine).
+``tests/core/test_prefix_cache.py`` loads these modules without a
+vllm install; a top-level ``from vllm...`` turns that suite red.
+
+That is also why these files use ``logging.getLogger`` instead of
+the repo-wide ``init_logger`` — ``init_logger`` comes from
+``vllm.logger``. The deviation is required, not an oversight.
+
+``_merge_uncached_mm`` is the exception at *call* time: it lazily
+imports ``vllm_omni.utils.mm_outputs``, which pulls in vllm. Import
+of this package still succeeds without vllm; materialize of leftover
+mm does not.
+"""
+
+from vllm_omni.core.prefix_cache.block_pool import PrefixBlockPool
+from vllm_omni.core.prefix_cache.controller import OmniPrefixCacheController
+from vllm_omni.core.prefix_cache.group_view import (
+    FullAttentionGroupView,
+    check_prefix_cache_kv_groups,
+    check_prefix_cache_kv_transfer,
+    get_prefix_cache_group_view,
+    stage_prefix_cache_config,
+)
+from vllm_omni.core.prefix_cache.interface import (
+    HIDDEN_KEY,
+    ModelCachePolicy,
+    OmniPrefixCacheStagingTimeoutError,
+    OmniPrefixCacheUnmatchError,
+    PrefixCacheConfig,
+    StageCacheOutputs,
+    WriteSchedule,
+)
+from vllm_omni.core.prefix_cache.manager import OmniPrefixCacheManager
+
+__all__ = [
+    "HIDDEN_KEY",
+    "FullAttentionGroupView",
+    "ModelCachePolicy",
+    "OmniPrefixCacheController",
+    "OmniPrefixCacheManager",
+    "OmniPrefixCacheStagingTimeoutError",
+    "OmniPrefixCacheUnmatchError",
+    "StageCacheOutputs",
+    "PrefixBlockPool",
+    "PrefixCacheConfig",
+    "WriteSchedule",
+    "check_prefix_cache_kv_groups",
+    "check_prefix_cache_kv_transfer",
+    "get_prefix_cache_group_view",
+    "stage_prefix_cache_config",
+]
diff --git a/vllm_omni/core/prefix_cache/block_pool.py b/vllm_omni/core/prefix_cache/block_pool.py
new file mode 100644
index 00000000000..9cf34cb2d2f
--- /dev/null
+++ b/vllm_omni/core/prefix_cache/block_pool.py
@@ -0,0 +1,84 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Pinned CPU block mirror (mirrors vLLM BlockPool)."""
+
+import logging
+
+import torch
+
+from vllm_omni.core.prefix_cache.interface import PrefixCacheConfig, TensorName
+
+logger = logging.getLogger(__name__)
+
+
+class PrefixBlockPool:
+    """Durable CPU mirror of vLLM KV slots, one tensor per name.
+
+    Storage is ``(num_blocks, block_size, feat)`` per key, viewed flat as
+    ``(num_slots, feat)`` so vLLM slot ids index rows directly. Write
+    access is single-writer (the controller committer thread); readers
+    take row views.
+
+    ``_caches`` is not an unbounded store and has no LRU. Dict keys are
+    tensor names (``__hidden_states__`` plus mm whose first dim is tokens),
+    opened once by ``ensure_key`` and never dropped — a model emits a
+    handful of those names, not a per-request set. Each value is a
+    fixed tensor sized to the same ``num_blocks`` as the upstream KV
+    pool. Rows *are* those kv slots: when vLLM recycles a block, the
+    next pool write overwrites that row. Slot reuse is the eviction.
+    """
+
+    def __init__(self, config: PrefixCacheConfig):
+        self._config = config
+        self._caches: dict[TensorName, torch.Tensor] = {}
+
+    def _alloc(self, dtype: torch.dtype, feat: int) -> torch.Tensor:
+        return torch.zeros(
+            (self._config.num_blocks, self._config.block_size, feat),
+            dtype=dtype,
+            device="cpu",
+            # Pinning lets device→host overlap compute; unsupported on
+            # CPU-only builds where that overlap is off anyway.
+            pin_memory=torch.cuda.is_available(),
+        )
+
+    def alloc_key(self, key: str, dtype: torch.dtype, feat: int) -> torch.Tensor | None:
+        """Allocate storage for a new ``key`` without publishing it (None if
+        already open). Pinned allocation is slow; run this unlocked and
+        hand the tensor to ``install_key`` under the manager's state lock."""
+        if key in self._caches:
+            return None
+        return self._alloc(dtype, feat)
+
+    def install_key(self, key: str, storage: torch.Tensor) -> None:
+        if key in self._caches:
+            return
+        self._caches[key] = storage
+        logger.info("prefix_cache: initialized mirror %s for key %s", list(storage.shape), key)
+
+    def ensure_key(self, key: str, dtype: torch.dtype, feat: int) -> None:
+        storage = self.alloc_key(key, dtype, feat)
+        if storage is not None:
+            self.install_key(key, storage)
+
+    def has_key(self, key: str) -> bool:
+        return key in self._caches
+
+    def keys(self) -> set[TensorName]:
+        return set(self._caches.keys())
+
+    def _flat(self, key: str) -> torch.Tensor:
+        cache = self._caches[key]
+        return cache.view(-1, cache.shape[-1])
+
+    def rows(self, key: str, slots: torch.Tensor) -> torch.Tensor:
+        """Gather rows for non-contiguous slots (returns a copy)."""
+        return self._flat(key).index_select(0, slots)
+
+    def write(self, key: str, slots: torch.Tensor, src_cpu: torch.Tensor) -> None:
+        """Write rows into the pool; caller (committer thread) is the single writer."""
+        if slots.dtype != torch.int64:
+            slots = slots.to(torch.int64)
+        # index_copy_ dispatches to a faster single-dim CPU path than
+        # advanced-indexing assignment (aten::index_put_).
+        self._flat(key).index_copy_(0, slots, src_cpu)
diff --git a/vllm_omni/core/prefix_cache/controller.py b/vllm_omni/core/prefix_cache/controller.py
new file mode 100644
index 00000000000..4c26ac055ec
--- /dev/null
+++ b/vllm_omni/core/prefix_cache/controller.py
@@ -0,0 +1,976 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Runs WriteTasks and the step device→host staging pool.
+
+The manager owns request/slot identity and when to submit. This class
+owns the staging pool, the GPU-byte budget, the copy queues, and the
+single committer that writes into the CPU block pool.
+
+Two device→host paths — the step path does not write `chunk.host` in
+the committer:
+
+    JOIN_NEXT_STEP   save already launched a whole-step device→host into
+                     a staging slot and set `chunk.host` as views.
+                     Committer waits that `step_d2h_event`, then writes
+                     the pool.
+    JOIN_ON_FINISH   committer copies the device clone → owned host
+                     tensors, then writes the pool.
+
+Async: high-priority then low-priority queues, then pool write.
+Eager: submit() does wait+write inline (CPU tests / no CUDA).
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum, auto
+from typing import Literal, NamedTuple
+
+import torch
+
+from vllm_omni.core.prefix_cache.block_pool import PrefixBlockPool
+from vllm_omni.core.prefix_cache.interface import (
+    OmniPrefixCacheStagingTimeoutError,
+    OmniPrefixCacheUnmatchError,
+    PrefixCacheConfig,
+    ReqId,
+    TensorName,
+    Tid,
+    WriteSchedule,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class StagingBufferHolder(NamedTuple):
+    """One owner of a staging-buffer slot. The slot is free when none remain.
+
+    Not a buffer state — concurrent owners share the same slot:
+    - for_step: claimed at save, released when materialize/discard consumes the ctx
+    - for_task: bound before WriteTask submit, released when that task completes
+    """
+
+    kind: Literal["step", "task"]
+    owner_id: int
+
+    @classmethod
+    def for_step(cls, step_id: int) -> StagingBufferHolder:
+        return cls("step", step_id)
+
+    @classmethod
+    def for_task(cls, tid: int) -> StagingBufferHolder:
+        return cls("task", tid)
+
+
+@dataclass
+class _BudgetTicket:
+    """GPU-byte-budget charge for one device clone shared by several writes.
+
+    Charged once at ``reserve()``; freed when the last pinned tid releases.
+    Immediate: the whole-step clone, pinned by that step's JOIN_NEXT_STEP
+    tasks. Deferred: the shared deferred clone, pinned by every task a
+    chunk of it was appended to. Does not store tensors.
+    """
+
+    nbytes: int
+    tids: set[Tid] = field(default_factory=set)
+    _freed: bool = False
+
+    def release(self, tid: Tid) -> int:
+        """Drop `tid`; return the bytes to uncharge (nbytes once, when the
+        last holder leaves; 0 otherwise). Idempotent per tid."""
+        self.tids.discard(tid)
+        if self.tids or self._freed:
+            return 0
+        self._freed = True
+        return self.nbytes
+
+
+@dataclass
+class _WriteChunk:
+    """One save's slots + tensors appended onto a WriteTask.
+
+    Controller identity is the parent ``tid``, not a request. Deferred
+    writes grow by appending one chunk per save.
+    """
+
+    slots_cpu: torch.Tensor  # int64 flat row ids, in token order
+    tensors: dict[TensorName, torch.Tensor]  # freeze (device or eager CPU)
+    host: dict[TensorName, torch.Tensor] = field(default_factory=dict)  # host view of rows [0:n)
+    # GPU-byte charge of the clone these tensors view; shared across the
+    # chunks cut from one save. None for chunks with no device clone.
+    budget: _BudgetTicket | None = None
+
+
+class TaskState(Enum):
+    """WriteTask lifecycle: a strict chain, plus FAILED from any non-terminal.
+
+        PENDING -> QUEUED -> COPYING -> HOST_READY -> WRITTEN
+
+    PENDING     registered, not on a copy queue (deferred: waiting for
+                finish / budget pressure)
+    QUEUED      on a copy queue
+    COPYING     one thread owns the copy stage (staging: waits the step
+                device→host; deferred: copies the device clone)
+    HOST_READY  host rows ready (`host_ready` set); device clone dropped
+    WRITTEN     in the CPU pool (`done` set)
+    FAILED      committer could not finish (`host_ready` + `done` set;
+                manager raises from every later entry)
+
+    Moves only through `WriteTask.transition`; skipping a step is illegal.
+    """
+
+    PENDING = auto()
+    QUEUED = auto()
+    COPYING = auto()
+    HOST_READY = auto()
+    WRITTEN = auto()
+    FAILED = auto()
+
+    @property
+    def is_terminal(self) -> bool:
+        return self in (TaskState.WRITTEN, TaskState.FAILED)
+
+
+# The one legal forward move from each non-terminal state.
+_CHAIN: dict[TaskState, TaskState] = {
+    TaskState.PENDING: TaskState.QUEUED,
+    TaskState.QUEUED: TaskState.COPYING,
+    TaskState.COPYING: TaskState.HOST_READY,
+    TaskState.HOST_READY: TaskState.WRITTEN,
+}
+_NOT_YET_COPYING = frozenset({TaskState.PENDING, TaskState.QUEUED})
+
+
+def _is_legal_move(frm: TaskState, to: TaskState) -> bool:
+    return (to is TaskState.FAILED and not frm.is_terminal) or _CHAIN.get(frm) is to
+
+
+@dataclass
+class WriteTask:
+    """One write of (slot, key) rows for a single request.
+
+    Identity: `tid` is the handle in the manager's (slot, key) tables.
+    `req_id` + `write_n` mark whose write this is and the nth time that
+    request opened a write. One write may cover several keys.
+
+    `state` is the single source of truth for where the write is (see
+    `TaskState`). `host_ready` / `done` are wait primitives set by the
+    transitions into HOST_READY / WRITTEN / FAILED, never directly.
+
+    How HOST_READY is reached:
+    - JOIN_NEXT_STEP: `chunk.host` is a staging view set at save; the
+      copy stage only waits `step_d2h_event`.
+    - JOIN_ON_FINISH: the copy stage copies device→host into `chunk.host`.
+
+    `JOIN_NEXT_STEP` is queued at submit. `JOIN_ON_FINISH` stays
+    PENDING until finish or GPU-byte-budget pressure escalates it;
+    budget flush takes the unfinished task with the oldest `enqueued_time`.
+
+    Concurrent readers/writers:
+    - Staging readers (materialize clone, committer pool write) all wait
+      the same `step_d2h_event` before touching the view.
+    - A later task taking the same (slot, key) records those rows in
+      `reassigned`; the old pool write skips them.
+    - `append_chunk` is refused once the copy stage is claimed; the caller
+      opens a fresh task rather than mutating a closed one.
+    - `lock` covers `state` / `reassigned` / `append_chunk` / host↔freeze /
+      `slot_to_row`. `scatter_rows` snapshots `reassigned`.
+    """
+
+    tid: Tid
+    req_id: ReqId
+    write_n: int  # 1-based: nth write opened by this request
+    schedule: WriteSchedule
+    chunks: list[_WriteChunk]
+    # On-device clone finished on the compute stream. Copy/read streams
+    # must wait this before touching `chunks[].tensors`, or they can read
+    # the next CUDA-graph static-buffer overwrite.
+    freeze_event: torch.cuda.Event | None = None
+    state: TaskState = TaskState.PENDING
+    # Slots this write no longer owns (a newer write took them over).
+    reassigned: dict[TensorName, torch.Tensor] = field(default_factory=dict)
+    # Set on entering HOST_READY (or FAILED): this write's host rows are ready.
+    host_ready: threading.Event = field(default_factory=threading.Event)
+    # Set on entering WRITTEN (or FAILED): the CPU-pool write is over.
+    done: threading.Event = field(default_factory=threading.Event)
+    # Guards state / reassigned / append / host↔freeze.
+    lock: threading.Lock = field(default_factory=threading.Lock)
+    # time.monotonic() at submit; GPU-byte flush picks the oldest of these.
+    enqueued_time: float = field(default_factory=time.monotonic)
+    # Immediate path: this write's view into the shared step staging page.
+    staging_slot: int | None = None
+    # Immediate path: this step's CUDA device→host event (shared). None if deferred.
+    step_d2h_event: torch.cuda.Event | None = None
+    # slot -> (which chunk, row in that tensor). Built on demand
+    # when a write has more than one `_WriteChunk`; pool write uses slot, the tensor uses row.
+    _slot_to_row: dict[int, tuple[int, int]] | None = None
+
+    def add_reassigned(self, key: str, slots: torch.Tensor) -> None:
+        with self.lock:
+            prev = self.reassigned.get(key)
+            self.reassigned[key] = slots.clone() if prev is None else torch.cat([prev, slots])
+
+    def reassigned_intersects(self, chunk: _WriteChunk) -> bool:
+        """True if this write already lost ownership of any (key, slot) the
+        chunk would add; the caller opens a fresh WriteTask instead."""
+        with self.lock:
+            if not self.reassigned:
+                return False
+            for key in chunk.tensors:
+                taken = self.reassigned.get(key)
+                if taken is not None and taken.numel() and bool(torch.isin(chunk.slots_cpu, taken).any()):
+                    return True
+            return False
+
+    # ------------------------------------------------------------ lifecycle
+
+    def transition(self, to: TaskState) -> None:
+        """Move to `to`; raises unless it is the next chain step or FAILED."""
+        with self.lock:
+            self._transition_locked(to)
+
+    def try_transition(self, to: TaskState) -> bool:
+        """Move to `to` if legal from the current state. True if moved."""
+        with self.lock:
+            if not _is_legal_move(self.state, to):
+                return False
+            self._transition_locked(to)
+            return True
+
+    def _transition_locked(self, to: TaskState, wake: bool = True) -> None:
+        if not _is_legal_move(self.state, to):
+            raise OmniPrefixCacheUnmatchError(f"task {self.tid}: illegal transition {self.state.name} -> {to.name}")
+        self.state = to
+        if not wake:
+            return
+        if to is TaskState.HOST_READY:
+            self.host_ready.set()
+        elif to is TaskState.WRITTEN:
+            self.done.set()
+        elif to is TaskState.FAILED:
+            self.host_ready.set()
+            self.done.set()
+
+    def claim_copy(self) -> bool:
+        """QUEUED -> COPYING. Only one thread may run the copy stage; True if this caller won."""
+        return self.try_transition(TaskState.COPYING)
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.state.is_terminal
+
+    def append_chunk(self, chunk: _WriteChunk, freeze_event: torch.cuda.Event | None = None) -> TaskState | None:
+        """Grow this write with one save's rows. Returns None when appended,
+        else the state that closed the task (COPYING or later).
+
+        `freeze_event` is stored in the same snapshot: events on one compute
+        stream are ordered, so the newest also covers every earlier clone.
+        """
+        with self.lock:
+            if self.state not in _NOT_YET_COPYING:
+                return self.state
+            self.chunks.append(chunk)
+            self._slot_to_row = None
+            if freeze_event is not None:
+                self.freeze_event = freeze_event
+            return None
+
+    def get_host_tensor(self, si: int, key: str) -> torch.Tensor | None:
+        """`chunks[si]` host if written, else device freeze. One snapshot."""
+        with self.lock:
+            chunk = self.chunks[si]
+            src = chunk.host.get(key)
+            if src is None:
+                src = chunk.tensors.get(key)
+            return src
+
+    def set_host_tensor(self, rows: list[tuple[_WriteChunk, str, torch.Tensor]]) -> None:
+        """COPYING -> HOST_READY: write these host tensors, drop the device freeze."""
+        with self.lock:
+            for chunk, key, tensor in rows:
+                chunk.host[key] = tensor
+            self._clear_tensors()
+            self._transition_locked(TaskState.HOST_READY)
+
+    def mark_host_ready(self) -> None:
+        """COPYING -> HOST_READY for staging views: wait the step device→host, drop freeze."""
+        if self.step_d2h_event is not None:
+            self.step_d2h_event.synchronize()
+        with self.lock:
+            self._clear_tensors()
+            self._transition_locked(TaskState.HOST_READY)
+
+    def mark_failed(self, *, defer_wake: bool = False) -> bool:
+        """-> FAILED from any non-terminal state; unblocks joiners. False if
+        already terminal. ``defer_wake``: the caller publishes the failure
+        record first, then calls ``wake_failed_waiters``."""
+        with self.lock:
+            if self.state.is_terminal:
+                return False
+            self._clear_tensors()
+            self._transition_locked(TaskState.FAILED, wake=not defer_wake)
+            return True
+
+    def wake_failed_waiters(self) -> None:
+        """Set the events after the failure record is published (see
+        ``mark_failed(defer_wake=True)``): a woken joiner must find it."""
+        self.host_ready.set()
+        self.done.set()
+
+    def mark_done(self) -> None:
+        """HOST_READY -> WRITTEN."""
+        self.transition(TaskState.WRITTEN)
+
+    def scatter_rows(self) -> list[tuple[TensorName, torch.Tensor, torch.Tensor]]:
+        """`(key, slots, host)` to write, one entry per key. Omits slots in
+        `reassigned`. A slot written twice by this task (preempt + resume
+        onto the same block) keeps the later chunk's row.
+        """
+        with self.lock:
+            reassigned = {k: s.clone() for k, s in self.reassigned.items()}
+        by_key: dict[TensorName, tuple[list[torch.Tensor], list[torch.Tensor]]] = {}
+        for chunk in self.chunks:
+            for k, host in chunk.host.items():
+                s, h = by_key.setdefault(k, ([], []))
+                s.append(chunk.slots_cpu)
+                h.append(host)
+        out: list[tuple[TensorName, torch.Tensor, torch.Tensor]] = []
+        for k, (s, h) in by_key.items():
+            slots = s[0] if len(s) == 1 else torch.cat(s)
+            host = h[0] if len(h) == 1 else torch.cat(h, dim=0)
+            if len(s) > 1 and torch.unique(slots).numel() != slots.numel():
+                last_pos = {int(slot): i for i, slot in enumerate(slots.tolist())}
+                keep_idx = torch.tensor(sorted(last_pos.values()), dtype=torch.int64)
+                slots, host = slots[keep_idx], host[keep_idx]
+            taken = reassigned.get(k)
+            if taken is not None and taken.numel():
+                keep = ~torch.isin(slots, taken)
+                if not bool(keep.any()):
+                    continue
+                slots, host = slots[keep], host[keep]
+            out.append((k, slots, host))
+        return out
+
+    def clear_tensors(self) -> None:
+        """Drop the device freeze. Host is unchanged (staging wait / fail)."""
+        with self.lock:
+            self._clear_tensors()
+
+    def _clear_tensors(self) -> None:
+        for chunk in self.chunks:
+            chunk.tensors = {}
+
+    def budget_tickets(self) -> list[_BudgetTicket]:
+        """Distinct tickets across this task's chunks (by identity; one per save)."""
+        out: dict[int, _BudgetTicket] = {}
+        for chunk in self.chunks:
+            if chunk.budget is not None:
+                out.setdefault(id(chunk.budget), chunk.budget)
+        return list(out.values())
+
+    def slot_to_row(self) -> dict[int, tuple[int, int]]:
+        with self.lock:
+            if self._slot_to_row is None:
+                m: dict[int, tuple[int, int]] = {}
+                for si, chunk in enumerate(self.chunks):
+                    for ri, slot in enumerate(chunk.slots_cpu.tolist()):
+                        m[slot] = (si, ri)
+                self._slot_to_row = m
+            return self._slot_to_row
+
+
+class StagingBufferPool:
+    """Reusable pinned landing zone for ONE whole-step device→host at save.
+
+    Per-task `chunk.host` is a row-range view into a slot, so the committer
+    skips a per-task device→host. Slots recycle; this is not the CPU block pool.
+
+    A slot stays busy while anyone still holds it: the step (until
+    materialize/discard) and each immediate write that views the page
+    (until its pool write). Prefix hits do not hold a slot —
+    they wait for the pool write and read the durable pool.
+
+    Saves with only leftover mm still claim a slot (empty views) so
+    every step id shares this bound. A full pool waits; timeout then errors.
+    """
+
+    def __init__(self, depth: int, capacity: int):
+        self.depth = depth
+        self.capacity = capacity  # rows per slot; a larger step raises
+        self._bufs: dict[TensorName, torch.Tensor] = {}  # [depth*capacity, width]
+        self._busy: list[set[StagingBufferHolder]] = [set() for _ in range(depth)]
+        self._slot_free_condition = threading.Condition()
+        self._closed = False
+
+    def _buf(self, key: str, width: int, dtype: torch.dtype, pin: bool) -> torch.Tensor:
+        buf = self._bufs.get(key)
+        if buf is None or buf.shape[-1] != width or buf.dtype != dtype:
+            buf = torch.empty((self.depth * self.capacity, width), dtype=dtype, pin_memory=pin)
+            self._bufs[key] = buf
+        return buf
+
+    def claim(self, holder: StagingBufferHolder, timeout: float) -> int:
+        """Grab a free slot for `holder`. Waits until one is free, then
+        times out. ``timeout<=0`` fails immediately if none are free.
+        """
+        deadline = time.monotonic() + max(0.0, timeout)
+        with self._slot_free_condition:
+            while True:
+                if self._closed:
+                    raise OmniPrefixCacheUnmatchError("staging pool shut down while waiting for a slot")
+                for slot in range(self.depth):
+                    if not self._busy[slot]:
+                        self._busy[slot].add(holder)
+                        return slot
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise OmniPrefixCacheStagingTimeoutError(f"timed out waiting for a staging slot after {timeout}s")
+                self._slot_free_condition.wait(timeout=remaining)
+
+    def bind(self, slot: int, holder: StagingBufferHolder) -> None:
+        with self._slot_free_condition:
+            self._busy[slot].add(holder)
+
+    def release(self, slot: int, holder: StagingBufferHolder) -> None:
+        with self._slot_free_condition:
+            self._busy[slot].discard(holder)
+            if not self._busy[slot]:
+                self._slot_free_condition.notify()
+
+    def close(self) -> None:
+        with self._slot_free_condition:
+            self._closed = True
+            self._slot_free_condition.notify_all()
+
+    def views(self, slot: int, key: str, n: int, width: int, dtype: torch.dtype, pin: bool) -> torch.Tensor:
+        base = slot * self.capacity
+        return self._buf(key, width, dtype, pin)[base : base + n]
+
+
+@dataclass
+class StepD2HClaim:
+    """One whole-step landing in StagingBufferPool.
+
+    Return of ``stage_step_host``. The manager stores this on
+    ``_StepContext`` until materialize/discard releases the step holder.
+    """
+
+    staging_slot: int  # StagingBufferPool index
+    views: dict[TensorName, torch.Tensor]  # host rows [0:n)
+    event: torch.cuda.Event | None = None  # torch.cuda.Event; None on eager/CPU
+
+
+class OmniPrefixCacheController:
+    """Staging pool + committer. Step device→host is launched at save;
+    this thread waits that event (JOIN_NEXT_STEP) or copies deferred
+    rows (JOIN_ON_FINISH), then writes into the CPU pool.
+    """
+
+    def __init__(self, pool: PrefixBlockPool, config: PrefixCacheConfig, eager: bool | None = None):
+        self._pool = pool
+        self._config = config
+        self._eager = (not torch.cuda.is_available()) if eager is None else eager
+        self._tasks: dict[Tid, WriteTask] = {}
+        self._completed: deque[Tid] = deque()  # pool write done, awaiting manager drain
+        self._failed: deque[Tid] = deque()  # write failed; manager raises from every later entry (sticky)
+        self._staged_bytes = 0
+        self._lock = threading.Lock()
+        self._wake = threading.Condition(self._lock)
+        self._queue_hi: deque[Tid] = deque()  # JOIN_NEXT_STEP + forced JOIN_ON_FINISH
+        self._queue_lo: deque[Tid] = deque()  # JOIN_ON_FINISH waiting for finish/budget
+        self._blocked: list[Tid] = []  # host copy done, awaiting pool write
+        self._shutdown = False
+        self._copy_stream: torch.cuda.Stream | None = None
+        self._read_stream: torch.cuda.Stream | None = None
+        self._worker: threading.Thread | None = None
+        self._staging_pool = StagingBufferPool(config.staging_depth, config.staging_capacity_tokens)
+        if not self._eager:
+            self._copy_stream = torch.cuda.Stream()
+            self._read_stream = torch.cuda.Stream()
+            self._worker = threading.Thread(target=self._worker_loop, name="omni-prefix-cache-committer", daemon=True)
+            self._worker.start()
+
+    # --------------------------------------------------------- step device→host staging
+
+    def _d2h_on_stream(
+        self,
+        stream: torch.cuda.Stream,
+        freeze_event: torch.cuda.Event | None,
+        copy: Callable[[], None],
+    ) -> torch.cuda.Event:
+        """Issue device→host on `stream` after freeze; return the done event."""
+        with torch.cuda.stream(stream):
+            if freeze_event is not None:
+                stream.wait_event(freeze_event)
+            copy()
+            ev = torch.cuda.Event()
+            ev.record()
+        return ev
+
+    def stage_step_host(
+        self,
+        tensors: dict[str, torch.Tensor],
+        n: int,
+        freeze_event: torch.cuda.Event | None,
+        step_holder: StagingBufferHolder,
+    ) -> StepD2HClaim:
+        """Claim a staging slot and, when `tensors` is non-empty, launch
+        ONE whole-step device→host into it.
+
+        Leftover-only saves pass empty `tensors` and still take a slot
+        (empty views) so every step id shares this bound. A full pool
+        waits for materialize/discard; timeout then errors. A step
+        larger than the page overflows the next slot — that is a config
+        break. The caller binds tasks after submit; `step_holder` is
+        released by materialize/discard via staging_release.
+        """
+        if tensors and n > self._staging_pool.capacity:
+            raise OmniPrefixCacheUnmatchError(
+                f"step has {n} tokens; staging capacity is {self._staging_pool.capacity} "
+                "(size staging_capacity_tokens to max_num_batched_tokens)"
+            )
+        slot = self._staging_pool.claim(step_holder, self._config.staging_claim_timeout_s)
+        try:
+            pin = not self._eager
+            views: dict[str, torch.Tensor] = {}
+            event: torch.cuda.Event | None = None
+            if self._eager or all(t.device.type == "cpu" for t in tensors.values()):
+                for key, src in tensors.items():
+                    v = self._staging_pool.views(slot, key, n, int(src.shape[-1]), src.dtype, pin)
+                    v.copy_(src)
+                    views[key] = v
+            else:
+
+                def _copy_to_staging() -> None:
+                    for key, src in tensors.items():
+                        v = self._staging_pool.views(slot, key, n, int(src.shape[-1]), src.dtype, pin)
+                        v.copy_(src, non_blocking=True)
+                        views[key] = v
+
+                event = self._d2h_on_stream(self._copy_stream, freeze_event, _copy_to_staging)
+            return StepD2HClaim(staging_slot=slot, views=views, event=event)
+        except Exception:
+            self._staging_pool.release(slot, step_holder)
+            raise
+
+    def staging_bind(self, slot: int, holder: StagingBufferHolder) -> None:
+        self._staging_pool.bind(slot, holder)
+
+    def staging_release(self, slot: int, holder: StagingBufferHolder) -> None:
+        self._staging_pool.release(slot, holder)
+
+    def _release_task_slot(self, task: WriteTask) -> None:
+        """Drop the task's staging hold at a terminal state (pool write or failure)."""
+        if task.staging_slot is not None:
+            self._staging_pool.release(task.staging_slot, StagingBufferHolder.for_task(task.tid))
+
+    def in_flight_tasks(self) -> int:
+        """Registered tasks not yet drained (diagnostics only)."""
+        return len(self._tasks)
+
+    # ------------------------------------------------------------------ submit
+
+    def register(self, task: WriteTask, queued: bool = True) -> None:
+        """Make a task visible (registry + QUEUED) without running anything;
+        safe under the manager's state lock. queued=False (deferred tasks)
+        stays PENDING on the GPU clone until finish/abort or the GPU-byte
+        budget forces a copy. Queued tasks must then go through
+        ``dispatch``.
+
+        Caller must reserve() the task bytes first (budget flush can
+        block; the manager does that outside the state lock) and pin the
+        task on its budget ticket(s) before register.
+        """
+        task.enqueued_time = time.monotonic()
+        with self._lock:
+            self._tasks[task.tid] = task
+            if queued:
+                task.transition(TaskState.QUEUED)
+
+    def dispatch(self, tasks: list[WriteTask]) -> None:
+        """Hand registered, queued tasks to the copy path. Threaded: enqueue.
+        Eager: the copy + pool write run here, inline — never call this
+        under the manager's state lock."""
+        if not tasks:
+            return
+        if self._eager:
+            try:
+                for task in tasks:
+                    self._run_eager(task)
+            except Exception:
+                # Later tasks were registered but will never be dispatched.
+                # Fail them too so shared budget owners and waiters release.
+                for task in tasks:
+                    self._fail_task(task.tid)
+                raise
+            return
+        with self._wake:
+            for task in tasks:
+                (self._queue_hi if task.schedule is WriteSchedule.JOIN_NEXT_STEP else self._queue_lo).append(task.tid)
+            self._wake.notify_all()
+
+    def submit(self, task: WriteTask, queued: bool = True) -> None:
+        """register + dispatch in one call (callers not holding the state lock)."""
+        self.register(task, queued)
+        if queued:
+            self.dispatch([task])
+
+    def append_chunk(
+        self, task: WriteTask, chunk: _WriteChunk, freeze_event: torch.cuda.Event | None = None
+    ) -> TaskState | None:
+        """Append to a pending task. None when appended, else the closing state."""
+        return task.append_chunk(chunk, freeze_event)
+
+    def pin_budget(self, ticket: _BudgetTicket, tid: int) -> None:
+        """Record that ``tid`` holds a view of the clone ``ticket`` charges."""
+        with self._lock:
+            ticket.tids.add(tid)
+
+    def reserve(self, nbytes: int) -> None:
+        """Reserve GPU-clone bytes; blocking flush happens here, so callers
+        must not hold the manager's state lock."""
+        self._reserve_bytes(nbytes)
+
+    def _release_staged_bytes(self, task: WriteTask) -> None:
+        """Drop this task's hold on its budget ticket(s). Idempotent; a
+        ticket uncharges once, when its last holder leaves."""
+        tickets = task.budget_tickets()
+        with self._wake:
+            for ticket in tickets:
+                self._staged_bytes -= ticket.release(task.tid)
+
+    def _reserve_bytes(self, nbytes: int) -> None:
+        # GPU-byte budget: force-copy oldest pending tasks until under
+        # budget. Bounded wait: their device→host has usually long completed.
+        while True:
+            with self._lock:
+                pending = [tid for tid, t in self._tasks.items() if not t.is_terminal]
+                if self._staged_bytes + nbytes <= self._config.gpu_staging_bytes or not pending:
+                    # Under budget or no pending tasks; admit reservation.
+                    self._staged_bytes += nbytes
+                    return
+                oldest = min(pending, key=lambda tid: self._tasks[tid].enqueued_time)
+            logger.warning("omni prefix cache: staging cap hit, force-flushing task %d", oldest)
+            self.escalate([oldest])
+            self.join([oldest])
+
+    # ------------------------------------------------------------- lifecycle
+
+    def escalate(self, tids: list[int]) -> None:
+        """Move pending tasks to the front of the high-priority queue.
+
+        PENDING -> QUEUED at the head; QUEUED on the low-priority queue
+        moves up; QUEUED already high-priority is a no-op. COPYING and later
+        belong to the worker and are untouched: the worker claims under
+        `_wake` too, so a task cannot be popped and re-queued behind its back.
+        """
+        if self._eager:
+            self.dispatch([task for tid in tids if (task := self._tasks.get(tid)) is not None and not task.is_terminal])
+            return
+        with self._wake:
+            for tid in tids:
+                task = self._tasks.get(tid)
+                if task is None:
+                    continue
+                if task.try_transition(TaskState.QUEUED):
+                    self._queue_hi.appendleft(tid)
+                elif task.state is TaskState.QUEUED and tid in self._queue_lo:
+                    self._queue_lo.remove(tid)
+                    self._queue_hi.appendleft(tid)
+            self._wake.notify_all()
+
+    def join(self, tids: list[int]) -> None:
+        """Block until each task has finished the CPU-pool write (or failed)."""
+        self._wait_tasks(tids, "done")
+
+    def join_host_ready(self, tids: list[int]) -> None:
+        """Block until each task's device→host is complete (`host_ready`).
+
+        Staging: committer has waited `step_d2h_event`. Deferred: committer
+        has written `chunk.host`. Does not wait for the CPU-pool write.
+        """
+        self._wait_tasks(tids, "host_ready")
+
+    def _wait_tasks(self, tids: list[int], event: Literal["done", "host_ready"]) -> None:
+        timeout = self._config.staging_claim_timeout_s
+        deadline = time.monotonic() + timeout
+        for tid in tids:
+            task = self._tasks.get(tid)
+            if task is None:
+                continue
+            if not getattr(task, event).wait(max(0.0, deadline - time.monotonic())):
+                raise OmniPrefixCacheUnmatchError(
+                    f"task {tid} ({task.schedule.value}) did not reach {event} within {timeout:g}s "
+                    f"(state={task.state.name}, in_flight_tasks={len(self._tasks)})"
+                )
+            if task.state is TaskState.FAILED:
+                # FAILED sets both events; success here would read rows the
+                # write never produced. The one-shot failure record may have
+                # been drained by another thread — do not rely on it.
+                raise OmniPrefixCacheUnmatchError(f"task {tid} ({task.schedule.value}) write failed before {event}")
+
+    def drain_completed(self) -> list[int]:
+        """Pop pool-written tasks from `_completed` and drop them from `_tasks`.
+        Staging holders were already released at the pool write."""
+        out: list[int] = []
+        with self._lock:
+            while self._completed:
+                out.append(self._completed.popleft())
+            for tid in out:
+                self._tasks.pop(tid, None)
+        return out
+
+    def drain_failed(self) -> list[int]:
+        """Pop failed task ids from `_failed`. Does not drop `_tasks`."""
+        out: list[int] = []
+        with self._lock:
+            while self._failed:
+                out.append(self._failed.popleft())
+        return out
+
+    def get_task(self, tid: int) -> WriteTask | None:
+        return self._tasks.get(tid)
+
+    def shutdown(self) -> None:
+        self._staging_pool.close()
+        with self._wake:
+            self._shutdown = True
+            self._wake.notify_all()
+        if self._worker is not None:
+            self._worker.join(timeout=5.0)
+
+    # ------------------------------------------------------------ fetch_host
+
+    @torch.inference_mode()
+    def fetch_host(self, task: WriteTask, slots: torch.Tensor, key: str) -> torch.Tensor:
+        """Rows for `slots` of one not-yet-done JOIN_ON_FINISH task.
+
+        `_slot_ref` puts JOIN_NEXT_STEP tids in `join_tids` (wait then
+        pool). This path reads committer-written `chunk.host`, or the
+        device clone if that device→host has not landed.
+        """
+        if task.step_d2h_event is not None:
+            task.step_d2h_event.synchronize()
+        return self._rows_from(task, slots, key)
+
+    def _rows_from(self, task: WriteTask, slots: torch.Tensor, key: str) -> torch.Tensor:
+        """Map `slots` to rows across one or more `_WriteChunk`s; preserve caller order."""
+        s2r = task.slot_to_row()
+        idx = [s2r[int(s)] for s in slots.tolist()]
+        parts: list[torch.Tensor] = []
+        order: list[int] = []
+        pos = 0
+        rows_groups: dict[int, list[tuple[int, int]]] = {}
+        for si, ri in idx:
+            rows_groups.setdefault(si, []).append((pos, ri))
+            pos += 1
+        for si, items in rows_groups.items():
+            src = task.get_host_tensor(si, key)
+            if src is None:
+                continue
+            rows_idx = torch.tensor([ri for _, ri in items], dtype=torch.long)
+            picked = self._slice_rows(task, src, rows_idx, host=(src.device.type == "cpu"))
+            parts.append(picked)
+            order.extend(p for p, _ in items)
+        if not parts:
+            raise KeyError(f"key {key} not present in task {task.tid}")
+        cat = torch.cat(parts, dim=0)
+        out = torch.empty_like(cat)
+        out[torch.tensor(order, dtype=torch.long)] = cat
+        return out
+
+    def _slice_rows(self, task: WriteTask, src: torch.Tensor, rows_idx: torch.Tensor, host: bool) -> torch.Tensor:
+        n = int(rows_idx.numel())
+        # Ascending-run check without materializing an arange: endpoints plus
+        # a monotonic diff are enough, and the common case is one long run.
+        contiguous = (
+            n > 0 and int(rows_idx[-1]) - int(rows_idx[0]) == n - 1 and (n < 2 or bool((rows_idx.diff() == 1).all()))
+        )
+
+        def _pick() -> torch.Tensor:
+            return src[rows_idx[0] : rows_idx[0] + n] if contiguous else src.index_select(0, rows_idx)
+
+        if host or src.device.type == "cpu":
+            return _pick()
+        if self._read_stream is None:
+            return _pick().detach().cpu()
+        copied: list[torch.Tensor] = []
+
+        def _copy_to_cpu() -> None:
+            copied.append(_pick().to("cpu", non_blocking=True))
+
+        ev = self._d2h_on_stream(self._read_stream, task.freeze_event, _copy_to_cpu)
+        ev.synchronize()
+        return copied[0]
+
+    # ------------------------------------------------------------ eager mode
+
+    @torch.inference_mode()
+    def _run_eager(self, task: WriteTask) -> None:
+        """Eager stand-in for queue + worker: walk the whole chain inline."""
+        task.try_transition(TaskState.QUEUED)  # no-op if submit already queued it
+        if not task.claim_copy():
+            # Copy stage already ran (a held stub, or a prior escalate); finish the write.
+            if task.state is TaskState.HOST_READY:
+                self._scatter(task)
+            return
+        if task.schedule is WriteSchedule.JOIN_NEXT_STEP:
+            # Host is already a staging view (copied at save). Drop freeze.
+            # `step_d2h_event` is None on CPU; `mark_host_ready` skips wait.
+            task.mark_host_ready()
+        else:
+            # JOIN_ON_FINISH: no copy stream; freeze → owned host inline.
+            task.set_host_tensor(
+                [
+                    (chunk, k, t.detach().cpu() if t.device.type != "cpu" else t.clone())
+                    for chunk in task.chunks
+                    for k, t in chunk.tensors.items()
+                ]
+            )
+        self._release_staged_bytes(task)
+        self._scatter(task)
+
+    # ---------------------------------------------------------- worker loop
+
+    def _worker_loop(self) -> None:
+        # A dying committer would strand every join() forever, so the loop
+        # never propagates: it fails the offending task and keeps serving.
+        while True:
+            tid = None
+            try:
+                task: WriteTask | None = None
+                with self._wake:
+                    while not self._shutdown and not self._queue_hi and not self._queue_lo:
+                        if self._blocked:
+                            break
+                        # submit / escalate / shutdown all notify.
+                        self._wake.wait()
+                    if self._shutdown and not self._queue_hi and not self._queue_lo and not self._blocked:
+                        return
+                    if self._queue_hi:
+                        tid = self._queue_hi.popleft()
+                    elif self._queue_lo:
+                        tid = self._queue_lo.popleft()
+                    if tid is not None:
+                        task = self._tasks.get(tid)
+                        if task is not None:
+                            # Claim in the same critical section as the pop:
+                            # escalate holds `_wake` and sees COPYING.
+                            task.transition(TaskState.COPYING)
+                if task is not None:
+                    self._copy_task(task)
+                    with self._wake:
+                        assert task.tid not in self._blocked, f"task {task.tid} reached HOST_READY twice"
+                        self._blocked.append(task.tid)
+                self._scatter_host_ready()
+            except BaseException:
+                logger.exception("omni prefix cache committer failed on task %s; releasing waiters", tid)
+                self._fail_task(tid)
+
+    @torch.inference_mode()
+    def _copy_task(self, task: WriteTask) -> None:
+        """COPYING -> HOST_READY. Staging: wait the save-time device→host event.
+        Deferred: this is the device→host into owned `chunk.host` tensors.
+        """
+        if task.schedule is WriteSchedule.JOIN_NEXT_STEP:
+            # `chunk.host` is already a staging view; device→host ran at save.
+            # `mark_host_ready` waits `step_d2h_event` if one was recorded.
+            # No per-task copy. Pool write is `_scatter_host_ready`.
+            task.mark_host_ready()
+            self._release_staged_bytes(task)
+            return
+        # One device cat + one device→host per key, not one per chunk (a
+        # long request has one chunk per step).
+        chunk_bytes = self._config.copy_chunk_bytes
+        by_key: dict[str, list[_WriteChunk]] = {}
+        for chunk in task.chunks:
+            for k in chunk.tensors:
+                by_key.setdefault(k, []).append(chunk)
+        pending: list[tuple[str, list[_WriteChunk], list[torch.Tensor]]] = []
+        if self._copy_stream is None:
+            raise OmniPrefixCacheUnmatchError("deferred prefix cache copy requires a CUDA copy stream")
+        with torch.cuda.stream(self._copy_stream):
+            if task.freeze_event is not None:
+                self._copy_stream.wait_event(task.freeze_event)
+            for k, chunks in by_key.items():
+                srcs = [c.tensors[k] for c in chunks]
+                src = srcs[0] if len(srcs) == 1 else torch.cat(srcs, dim=0)
+                rows = int(src.shape[0])
+                row_bytes = max(1, src[:1].numel() * src.element_size())
+                step = max(1, rows if rows * row_bytes <= chunk_bytes else chunk_bytes // row_bytes)
+                parts = [src[s : s + step].to("cpu", non_blocking=True) for s in range(0, max(rows, 1), step)]
+                pending.append((k, chunks, parts))
+            ev = torch.cuda.Event()
+            ev.record()
+        ev.synchronize()
+        rows_out: list[tuple[_WriteChunk, str, torch.Tensor]] = []
+        for k, chunks, parts in pending:
+            host = parts[0] if len(parts) == 1 else torch.cat(parts, dim=0)
+            if len(chunks) == 1:
+                rows_out.append((chunks[0], k, host))
+                continue
+            for chunk, view in zip(chunks, torch.split(host, [int(c.tensors[k].shape[0]) for c in chunks], dim=0)):
+                rows_out.append((chunk, k, view))
+        task.set_host_tensor(rows_out)
+        self._release_staged_bytes(task)
+
+    def _fail_task(self, tid: int | None) -> None:
+        """-> FAILED: release waiters for a task the committer could not complete.
+
+        No-op once the task is terminal. Budget release is idempotent, so a
+        raise after a successful copy stage does not uncharge twice.
+        """
+        task = self._tasks.get(tid) if tid is not None else None
+        if task is None or not task.mark_failed(defer_wake=True):
+            return
+        self._release_staged_bytes(task)
+        with self._wake:
+            if tid in self._blocked:
+                self._blocked.remove(tid)
+        self._release_task_slot(task)
+        with self._lock:
+            # Publish the failure: rows behind already-published block hashes
+            # never landed, which the manager must raise on (hiding it would
+            # crash on every future hit that touches these slots).
+            self._failed.append(task.tid)
+        # Events last: a joiner woken by them must find the record on drain,
+        # not read never-written pool rows in a done-but-unpublished window.
+        task.wake_failed_waiters()
+
+    @torch.inference_mode()
+    def _scatter_host_ready(self) -> None:
+        """HOST_READY -> WRITTEN for every `_blocked` task that has reached HOST_READY."""
+        with self._wake:
+            ready = [tid for tid in self._blocked if (t := self._tasks.get(tid)) and t.state is TaskState.HOST_READY]
+            for tid in ready:
+                self._blocked.remove(tid)
+        for tid in ready:
+            task = self._tasks[tid]
+            try:
+                self._scatter(task)
+            except BaseException:
+                # Attribute the failure to THIS task: letting it propagate
+                # would fail whichever entry the worker loop happened to be
+                # copying, double-release its bytes, and strand this one's
+                # join() forever.
+                logger.exception("omni prefix cache scatter failed on task %s; releasing waiters", tid)
+                self._fail_task(tid)
+
+    @torch.inference_mode()
+    def _scatter(self, task: WriteTask) -> None:
+        for key, slots, host in task.scatter_rows():
+            self._pool.write(key, slots, host)
+        # `done` is set LAST: a join(done) waiter (the save barrier) must find
+        # the completion record on its next drain and the staging slot free —
+        # a done-but-undrained window would leave occupancy IN_TRANSIT and
+        # make the COW preserve skip the reused rows.
+        self._release_task_slot(task)
+        with self._lock:
+            self._completed.append(task.tid)
+        task.mark_done()
diff --git a/vllm_omni/core/prefix_cache/group_view.py b/vllm_omni/core/prefix_cache/group_view.py
new file mode 100644
index 00000000000..c935f72b6df
--- /dev/null
+++ b/vllm_omni/core/prefix_cache/group_view.py
@@ -0,0 +1,208 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""KV-cache group access for the omni prefix cache.
+
+The sole path through which the prefix cache touches vLLM scheduler
+internals (block tables, slot mappings). Group-spec rejection happens
+at kv-cache init via ``check_prefix_cache_kv_groups``; the factory only
+returns None when the input batch has no block table.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import torch
+
+from vllm_omni.core.prefix_cache.interface import OmniPrefixCacheUnmatchError, PrefixCacheConfig
+
+if TYPE_CHECKING:
+    from vllm.v1.worker.gpu_input_batch import InputBatch
+
+
+class FullAttentionGroupView:
+    """View over the first (full-attention) KV-cache group.
+
+    Step slots come from the CPU block table (`step_slots_cpu`), not the
+    device slot_mapping.
+    """
+
+    def __init__(self, input_batch: InputBatch, block_size: int):
+        self._input_batch = input_batch
+        self.block_size = block_size
+        check_prefix_cache_block_layout(input_batch.block_table[0], block_size)
+
+    def _block_table_cpu(self) -> torch.Tensor:
+        return self._input_batch.block_table[0].block_table.cpu
+
+    def batch_req_ids(self) -> list[str]:
+        return list(self._input_batch.req_ids)
+
+    def step_slots_cpu(self, req_ids: list[str], num_scheduled: dict[str, int]) -> torch.Tensor:
+        """This step's slot mapping, computed on CPU from the block table.
+
+        The device slot_mapping would need a stream sync to read back, which
+        stalls the whole forward; the CPU block table carries the same
+        information (positions are num_computed .. +num_scheduled per request).
+        """
+        block_table = self._block_table_cpu()
+        bs = self.block_size
+        max_blocks = int(block_table.shape[1])
+        computed = self._input_batch.num_computed_tokens_cpu
+        parts: list[torch.Tensor] = []
+        for req_id in req_ids:
+            n = int(num_scheduled.get(req_id, 0))
+            if n <= 0:
+                continue
+            req_idx = self._input_batch.req_id_to_index[req_id]
+            start = int(computed[req_idx])
+            pos = torch.arange(start, start + n, dtype=torch.long)
+            offs = pos // bs
+            if int(offs[-1]) >= max_blocks:
+                keep = offs < max_blocks
+                pos, offs = pos[keep], offs[keep]
+                if pos.numel() == 0:
+                    continue
+            parts.append(block_table[req_idx, offs].to(torch.long) * bs + (pos % bs))
+        return torch.cat(parts) if parts else torch.empty((0,), dtype=torch.long)
+
+
+def check_prefix_cache_block_layout(block_table: object, block_size: int) -> None:
+    """Reject block-table layouts ``step_slots_cpu`` cannot mirror.
+
+    The CPU slot math is ``table[req, pos // block_size] * block_size +
+    pos % block_size`` over allocator block ids. vLLM breaks that in two
+    cases: hybrid kernel blocks (the row holds ``blocks_per_kv_block``
+    kernel ids per allocator block, e.g. FlashInfer/FlashMLA with
+    ``--block-size 128``) and decode context parallel (tokens are striped
+    across ranks and hashed at ``block_size * dcp_world_size``).
+    """
+    if getattr(block_table, "use_hybrid_blocks", False) or int(getattr(block_table, "blocks_per_kv_block", 1)) != 1:
+        raise OmniPrefixCacheUnmatchError(
+            "omni prefix caching requires kernel_block_size == block_size; the attention backend "
+            f"splits each block into {getattr(block_table, 'blocks_per_kv_block', '?')} kernel blocks. "
+            "Pick a --block-size the backend supports natively or disable enable_prefix_caching"
+        )
+    if int(getattr(block_table, "dcp_world_size", 1)) != 1:
+        raise OmniPrefixCacheUnmatchError(
+            "omni prefix caching does not support decode context parallel "
+            f"(dcp_world_size={getattr(block_table, 'dcp_world_size', '?')}); disable enable_prefix_caching"
+        )
+    kv_bs = getattr(block_table, "kv_cache_block_size", block_size)
+    if int(kv_bs) != int(block_size):
+        raise OmniPrefixCacheUnmatchError(
+            f"omni prefix caching block_size {block_size} does not match the kv-cache block table ({kv_bs})"
+        )
+
+
+def check_prefix_cache_kv_groups(kv_cache_groups: object) -> None:
+    """Reject hybrid / multi-group models at kv-cache init, not first step.
+
+    Only needs ``kv_cache_config.kv_cache_groups``. ``FullAttentionSpec``
+    is imported here so ``tests/core`` can load this module without vllm.
+    """
+    groups = list(kv_cache_groups or ())
+    if len(groups) != 1:
+        raise OmniPrefixCacheUnmatchError(
+            "omni prefix caching requires a single full-attention kv-cache group; "
+            f"found {len(groups)}. disable enable_prefix_caching for this model"
+        )
+    from vllm.v1.kv_cache_interface import FullAttentionSpec
+
+    spec = getattr(groups[0], "kv_cache_spec", None)
+    if not isinstance(spec, FullAttentionSpec):
+        raise OmniPrefixCacheUnmatchError(
+            "omni prefix caching requires a single full-attention kv-cache group; "
+            f"found {type(spec).__name__}. disable enable_prefix_caching for this model"
+        )
+
+
+def check_prefix_cache_kv_transfer(kv_transfer_config: object) -> None:
+    """Reject kv_consumer / kv_both stages.
+
+    KV loaded from a producer also shows up as ``num_computed_tokens``; the
+    manager would read it as a local hit with no rows behind it.
+    """
+    if kv_transfer_config is not None and getattr(kv_transfer_config, "is_kv_consumer", False):
+        raise OmniPrefixCacheUnmatchError(
+            "omni prefix caching cannot tell locally cached tokens from KV received "
+            "through a KV connector; disable enable_prefix_caching on kv_consumer / "
+            "kv_both stages"
+        )
+
+
+def check_prefix_cache_token_accounting(cache_config: object, speculative_config: object) -> None:
+    """Reject configs where ``num_computed_tokens`` stops meaning "first
+    scheduled position, block aligned".
+
+    Speculative decoding: with async scheduling vLLM keeps
+    ``num_computed_tokens_cpu`` optimistic (all drafts accepted) during the
+    forward and corrects it after; ``step_slots_cpu`` would read the
+    uncorrected value and mirror rows at the wrong slots. Refused as a
+    whole until that path is verified. ``prefix_match_unit`` smaller than
+    the block enables sub-block hits, which the hit registry rejects as
+    unaligned on the first hit; refuse at init instead.
+    """
+    if speculative_config is not None:
+        raise OmniPrefixCacheUnmatchError(
+            "omni prefix caching is not supported together with speculative decoding; "
+            "disable enable_prefix_caching on this stage"
+        )
+    unit = getattr(cache_config, "prefix_match_unit", None)
+    block_size = getattr(cache_config, "block_size", None)
+    if unit is not None and block_size is not None and int(unit) != int(block_size):
+        raise OmniPrefixCacheUnmatchError(
+            f"omni prefix caching requires block-aligned hits; prefix_match_unit={unit} with block_size={block_size} "
+            "enables sub-block hits. Unset prefix_match_unit or disable enable_prefix_caching"
+        )
+
+
+def stage_prefix_cache_config(
+    *,
+    kv_cache_config: object,
+    cache_config: object,
+    kv_transfer_config: object,
+    scheduler_config: object,
+    model_config: object,
+    is_pooling_model: bool,
+    speculative_config: object = None,
+) -> PrefixCacheConfig | None:
+    """Runner-side gate shared by the GPU and NPU model runners.
+
+    Returns None when the stage does not run an omni prefix cache
+    (``enable_prefix_caching`` off, or a pooling stage that never saves).
+    Otherwise refuses kv_consumer / kv_both, speculative decoding,
+    sub-block matching and hybrid kv groups, then sizes the config from
+    the scheduler. One place so a platform runner cannot silently skip a
+    refusal the other one has.
+    """
+    if not getattr(cache_config, "enable_prefix_caching", False) or is_pooling_model:
+        return None
+    check_prefix_cache_kv_transfer(kv_transfer_config)
+    check_prefix_cache_token_accounting(cache_config, speculative_config)
+    check_prefix_cache_kv_groups(getattr(kv_cache_config, "kv_cache_groups", None))
+    return PrefixCacheConfig.from_vllm_config(
+        num_blocks=kv_cache_config.num_blocks,  # type: ignore[attr-defined]
+        block_size=cache_config.block_size,  # type: ignore[attr-defined]
+        scheduler_config=scheduler_config,
+        model_config=model_config,
+    )
+
+
+def get_prefix_cache_group_view(
+    input_batch: InputBatch,
+    block_size: int,
+    kv_cache_groups: object = None,
+) -> FullAttentionGroupView | None:
+    """Build the group view; None only if the batch has no block table.
+
+    Group spec is checked first (raises). Selection is by spec, not by
+    counting block tables: a hybrid model's group 0 is not necessarily
+    full attention, and a narrower per-group table would make
+    step_slots_cpu silently clamp.
+    """
+    check_prefix_cache_kv_groups(kv_cache_groups)
+    block_tables = getattr(input_batch.block_table, "block_tables", None)
+    if not block_tables:
+        return None
+    return FullAttentionGroupView(input_batch, block_size)
diff --git a/vllm_omni/core/prefix_cache/interface.py b/vllm_omni/core/prefix_cache/interface.py
new file mode 100644
index 00000000000..274706f7559
--- /dev/null
+++ b/vllm_omni/core/prefix_cache/interface.py
@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Interface types for the omni prefix cache.
+
+Naming aligns with vLLM's v1/core KV-cache design.
+"""
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, NamedTuple, TypeAlias
+
+import torch
+
+# Four identities (still str/int at runtime, not interchangeable):
+#   TensorName  which cached tensor (hidden / mm), not a prefix hash
+#   ReqId       vLLM request id
+#   Tid         WriteTask handle
+#   StepId      save_outputs id; materialize or discard exactly once
+TensorName: TypeAlias = str
+ReqId: TypeAlias = str
+Tid: TypeAlias = int
+StepId: TypeAlias = int
+
+# Reserved pool key for hidden states (mm keys are flat dotted names).
+# Identity only — whether a model caches it lives on ModelCachePolicy.
+HIDDEN_KEY: TensorName = "__hidden_states__"
+
+
+def is_hidden_key(key: TensorName) -> bool:
+    return key == HIDDEN_KEY
+
+
+def without_hidden(keys: Iterable[TensorName]) -> set[TensorName]:
+    """Drop the reserved hidden identity; the rest are mm names."""
+    return {k for k in keys if k != HIDDEN_KEY}
+
+
+class WriteSchedule(Enum):
+    """Write scheduling policy for one WriteTask."""
+
+    # Immediately-cached keys: device→host launched at save into the
+    # staging pool; committer waits that event and writes the CPU pool.
+    # The next save waits done (a reused slot must be pool-complete).
+    JOIN_NEXT_STEP = "join_next_step"
+    # Deferred mm: stays on the GPU clone until finish/abort (GPU-byte
+    # budget may force a copy earlier). One WriteTask per request.
+    JOIN_ON_FINISH = "join_on_finish"
+
+
+@dataclass(frozen=True)
+class PrefixCacheConfig:
+    """Sizing and flow-control knobs (mirrors KVCacheConfig)."""
+
+    num_blocks: int
+    block_size: int
+    # GPU-clone byte budget for JOIN_ON_FINISH; exceeding it forces a copy.
+    gpu_staging_bytes: int = 512 * 1024 * 1024
+    # Device→host staging: circular slots, one whole step each (not per request).
+    # Host memory per key ≈ staging_depth * staging_capacity_tokens * width * dtype.
+    # Prefer from_vllm_config so staging_capacity_tokens tracks max_num_batched_tokens.
+    staging_depth: int = 4
+    staging_capacity_tokens: int = 1024
+    # How long save waits for a free staging slot, and join/join_host_ready
+    # for the committer; exceeding it raises.
+    staging_claim_timeout_s: float = 30.0
+    # Device→host chunk size for JOIN_ON_FINISH (copied a piece at a time).
+    copy_chunk_bytes: int = 16 * 1024 * 1024
+
+    @classmethod
+    def from_vllm_config(
+        cls,
+        *,
+        num_blocks: int,
+        block_size: int,
+        scheduler_config: Any = None,
+        model_config: Any = None,
+    ) -> "PrefixCacheConfig":
+        """Size device→host staging from the running scheduler.
+
+        A slot holds one *step* (the whole batch), not one request:
+        ``staging_capacity_tokens`` is ``max_num_batched_tokens`` (falls back
+        to ``max_model_len``); ``staging_depth`` is how many unconsumed
+        step ids may exist at once, not ``max_num_seqs``.
+
+        Pinned staging is allocated lazily per key at
+        ``depth * capacity_tokens * width * dtype``. There is no clamp: a
+        step larger than capacity raises. A 16k-token thinking batch at
+        hidden=2048 bf16 is ~256 MiB for hidden alone; each mm key adds
+        another pool tensor.
+
+        ``staging_depth`` is the dataclass default (4). There is no CLI or
+        deploy YAML knob — changing it is a code change. Every save that
+        issues a step id claims one slot, including saves with only leftover
+        mm. A full pool waits for materialize/discard;
+        ``staging_claim_timeout_s`` then errors.
+        """
+        batched = getattr(scheduler_config, "max_num_batched_tokens", None)
+        model_len = getattr(scheduler_config, "max_model_len", None)
+        if not model_len and model_config is not None:
+            model_len = getattr(model_config, "max_model_len", None)
+        try:
+            capacity = int(batched or model_len or 1024)
+        except (TypeError, ValueError):
+            capacity = 1024
+        return cls(
+            num_blocks=num_blocks,
+            block_size=block_size,
+            staging_capacity_tokens=max(1, capacity),
+        )
+
+
+class StageCacheOutputs(NamedTuple):
+    """Plain value object: per-request merged stage outputs."""
+
+    # req -> full-prompt hidden states (None when policy skips them)
+    hidden_states: dict[ReqId, torch.Tensor] | None
+    # tensor name -> req -> payload element
+    mm_outputs: dict[TensorName, dict[ReqId, Any]]
+
+
+class OmniPrefixCacheUnmatchError(RuntimeError):
+    """Contract, config, or KV-occupancy error that must raise.
+
+    Includes hit spans that resolve to absent slots (omni cache diverged
+    from vLLM KV), a step id consumed twice or never saved, a step larger
+    than the staging page, and a failed write. Do not pretend these
+    were a miss.
+    """
+
+
+class OmniPrefixCacheStagingTimeoutError(OmniPrefixCacheUnmatchError):
+    """Save waited for a free staging slot and timed out."""
+
+
+@dataclass(frozen=True)
+class ModelCachePolicy:
+    """Replaces getattr probing on models for cache behavior decisions.
+
+    Hidden's *name* is ``HIDDEN_KEY`` (shared identity). This object
+    answers whether this model caches it, and which mm keys are deferred.
+    """
+
+    needs_full_hidden_states: bool = True
+    # Mm whose first dim is this step's token count; stays on the GPU
+    # clone until finish/abort (JOIN_ON_FINISH). Also skipped by the
+    # immediate on-device clone / device→host path.
+    deferred_keys: frozenset[TensorName] = frozenset()
+
+    @property
+    def hidden_key(self) -> TensorName | None:
+        """Pool key for hidden, or None when this model opts out."""
+        return HIDDEN_KEY if self.needs_full_hidden_states else None
+
+    def get_hit_keys(self, keys: Iterable[TensorName]) -> list[TensorName]:
+        """Keys to plan/prefetch for a hit: hidden first (if cached), then mm."""
+        mm = sorted(without_hidden(keys))
+        return [HIDDEN_KEY, *mm] if self.needs_full_hidden_states else mm
+
+    def skip_immediate_mm(self, key: TensorName) -> bool:
+        """Immediate on-device clone must not take hidden or deferred keys from mm."""
+        return is_hidden_key(key) or key in self.deferred_keys
+
+    @classmethod
+    def from_model(cls, model: Any) -> "ModelCachePolicy":
+        """Shim over legacy per-model attributes (deprecation window)."""
+        deferred = frozenset(getattr(model, "deferred_prefix_cache_mm_keys", ()) or ())
+        return cls(
+            needs_full_hidden_states=bool(getattr(model, "requires_full_prefix_cached_hidden_states", True)),
+            deferred_keys=deferred,
+        )
diff --git a/vllm_omni/core/prefix_cache/manager.py b/vllm_omni/core/prefix_cache/manager.py
new file mode 100644
index 00000000000..5294a25d4ac
--- /dev/null
+++ b/vllm_omni/core/prefix_cache/manager.py
@@ -0,0 +1,1475 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Omni prefix cache, manager side.
+
+Owns slot occupancy, the request-task table, the hit/span registry,
+per-step snapshots, and the merge. The controller owns the staging
+pool, copy queues, and writing rows into the CPU block pool. The
+state lock covers those tables only — never a wait-for-copy, a
+GPU-byte-budget flush, or a memcpy.
+
+Helper docstrings mark ``_state_lock`` (non-reentrant):
+
+    Caller holds   already inside a critical section; do not acquire
+    Takes          acquires here (``@_locked`` or ``with``)
+
+Two host stores:
+
+    StagingBufferPool   reusable step-sized pages. save copies this
+                        step's immediately-cached keys (hidden +
+                        non-deferred mm) device→host into one page.
+                        Per-task `chunk.host` is a view into that page,
+                        not a second copy.
+    PrefixBlockPool     durable (kv_slot, key) prefix cache. The
+                        committer only writes into it.
+
+Two write paths (which keys, not how many tokens):
+
+    JOIN_NEXT_STEP      immediately-cached keys. Device→host is already
+                        in flight at submit; the committer waits
+                        `step_d2h_event` then copies host→pool. The next
+                        save waits `done`: reused slots must not leave a
+                        pending pool write behind.
+    JOIN_ON_FINISH      deferred mm. Stays on the device clone; the
+                        committer does that device→host, then writes the
+                        pool. Forced onto the high-priority queue on
+                        finish/abort or GPU-byte-budget pressure.
+
+Per real scheduler_output, engine-thread order:
+
+    new_step_starts   before _update_states drops finished requests
+                      (register hits, start prefix prefetch)
+    forward
+    save_outputs      clone off live buffers + launch staging copy;
+                      returns step id
+    materialize or discard_step   exactly one of the two, once
+
+materialize may run on the async output builder while the engine is
+already in the next step. Warmup/dummy runs are never fed.
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from collections import deque
+from collections.abc import Iterable, Mapping
+from concurrent.futures import Future, ThreadPoolExecutor
+from dataclasses import dataclass, field
+from enum import IntEnum
+from typing import TYPE_CHECKING, Any, NamedTuple, NoReturn
+
+import torch
+
+from vllm_omni.core.prefix_cache.block_pool import PrefixBlockPool
+from vllm_omni.core.prefix_cache.controller import (
+    OmniPrefixCacheController,
+    StagingBufferHolder,
+    StepD2HClaim,
+    WriteTask,
+    _BudgetTicket,
+    _WriteChunk,
+)
+from vllm_omni.core.prefix_cache.interface import (
+    ModelCachePolicy,
+    OmniPrefixCacheStagingTimeoutError,
+    OmniPrefixCacheUnmatchError,
+    PrefixCacheConfig,
+    ReqId,
+    StageCacheOutputs,
+    StepId,
+    TensorName,
+    Tid,
+    WriteSchedule,
+    is_hidden_key,
+    without_hidden,
+)
+
+if TYPE_CHECKING:
+    from vllm.v1.core.sched.output import SchedulerOutput
+
+    from vllm_omni.core.prefix_cache.group_view import FullAttentionGroupView
+
+logger = logging.getLogger(__name__)
+
+
+class _Occupancy(IntEnum):
+    ABSENT = 0
+    IN_TRANSIT = 1
+    COMMITTED = 2
+
+
+def _is_step_token_tensor(val: Any, n: int, padded: int) -> bool:
+    """2D+ tensor whose first dim is this step's token count (``n`` or padded).
+
+    True means callers may take ``val[:n]``. Leftover tensors (``codes.ref``),
+    lists, and other shapes are False.
+    """
+    return isinstance(val, torch.Tensor) and val.ndim >= 2 and int(val.shape[0]) in (n, padded)
+
+
+def _raise_unreadable_hit(req_id: str, key: str, why: str) -> NoReturn:
+    raise OmniPrefixCacheUnmatchError(f"hit span for req {req_id} key={key} is not readable ({why})")
+
+
+def _snapshot_leftover_mm_cpu(
+    mm_outputs: dict[str, Any],
+    device_snapshot_keys: set[str],
+    num_tokens_unpadded: int,
+    num_tokens_padded: int | None = None,
+) -> tuple[dict[str, Any], torch.cuda.Event | None]:
+    """CPU copy of mm that did not land on the staging page.
+
+    Skip ``device_snapshot_keys`` (those already have a device→host page).
+    Copy the rest — deferred mm, lists, ``codes.ref`` — so materialize can
+    run after the next forward overwrites graph buffers. Slice ``[:n]``
+    only when ``shape[0] == n``; ``>= n`` would clip ``codes.ref``.
+
+    CUDA tensors land in pinned memory through a non-blocking copy on the
+    current stream: stream order keeps it ahead of the next forward, and
+    the engine thread does not wait for this forward to finish. The
+    returned event (None when nothing was on CUDA) must be synchronized
+    before the snapshot is read.
+    """
+    n = num_tokens_unpadded
+    padded = n if num_tokens_padded is None else int(num_tokens_padded)
+    on_cuda = False
+
+    def _copy(val: Any) -> Any:
+        nonlocal on_cuda
+        if isinstance(val, torch.Tensor):
+            t = val[:n] if _is_step_token_tensor(val, n, padded) and int(val.shape[0]) == n else val
+            t = t.detach()
+            if t.is_cuda:
+                host = torch.empty(t.shape, dtype=t.dtype, device="cpu", pin_memory=True)
+                host.copy_(t, non_blocking=True)
+                on_cuda = True
+                return host
+            # .cpu() copies other device tensors; CPU/pinned views still share storage.
+            copied = t.cpu() if t.device.type != "cpu" else t.clone()
+            return copied.contiguous()
+        if isinstance(val, Mapping):
+            return {k: _copy(v) for k, v in val.items()}
+        if isinstance(val, list):
+            return [_copy(v) for v in val]
+        if isinstance(val, tuple):
+            return tuple(_copy(v) for v in val)
+        return val
+
+    leftover = {
+        key: _copy(val) for key, val in mm_outputs.items() if key not in device_snapshot_keys and not is_hidden_key(key)
+    }
+    event = None
+    if on_cuda:
+        event = torch.cuda.Event()
+        event.record()
+    return leftover, event
+
+
+def _unpin_leftover(val: Any) -> Any:
+    """Clone pinned tensors out so the payload does not hold pinned pages."""
+    if isinstance(val, torch.Tensor):
+        return val.clone() if val.is_pinned() else val
+    if isinstance(val, Mapping):
+        return {k: _unpin_leftover(v) for k, v in val.items()}
+    if isinstance(val, list):
+        return [_unpin_leftover(v) for v in val]
+    if isinstance(val, tuple):
+        return tuple(_unpin_leftover(v) for v in val)
+    return val
+
+
+@dataclass
+class _StepOutputs:
+    """This step's outputs split by consumer.
+
+    A tensor whose first dim equals this step's token count (or the
+    CUDA-graph padded count) can be sliced ``[:n]`` into per-token rows.
+    ``codes.ref`` and lists are not that shape.
+
+    ``immediate``: those per-token rows copied device→host this step
+    (hidden + non-deferred mm). ``deferred_chunks``: per-token deferred
+    mm, packed per request for JOIN_ON_FINISH. ``leftover``: CPU replica
+    for this step's materialize of everything that did not get a staging
+    page.
+    A deferred per-token key is in both ``deferred_chunks`` (later cache
+    write) and ``leftover`` (this-step read) — two consumers, not a
+    duplicate store.
+
+    ``immediate_budget`` charges the immediate clones once; every
+    JOIN_NEXT_STEP task of the step pins it. Deferred chunks carry their
+    own shared ticket.
+    """
+
+    immediate: dict[str, torch.Tensor]
+    deferred_chunks: list[tuple[str, _WriteChunk]]
+    leftover: dict[str, Any]
+    # Completion of the leftover device→host copies; None when none ran on CUDA.
+    leftover_event: torch.cuda.Event | None = None
+    immediate_budget: _BudgetTicket | None = None
+    # Pool storage allocated (unlocked) for keys first seen this step;
+    # published into the pool / occupancy tables under the state lock.
+    new_key_storage: dict[str, torch.Tensor] = field(default_factory=dict)
+
+    @property
+    def deferred_budget(self) -> _BudgetTicket | None:
+        return self.deferred_chunks[0][1].budget if self.deferred_chunks else None
+
+    def freeze_targets(self) -> list[torch.Tensor]:
+        """Device clones the freeze event must cover."""
+        return list(self.immediate.values()) + [t for _, c in self.deferred_chunks for t in c.tensors.values()]
+
+    def budget_bytes(self) -> int:
+        return sum(t.nbytes for t in (self.immediate_budget, self.deferred_budget) if t is not None)
+
+
+def _locked(fn):
+    """Serialize public entry points: the async output builder calls
+    materialize() while the engine thread is in the next step."""
+
+    def wrapper(self, *args, **kwargs):
+        with self._state_lock:
+            return fn(self, *args, **kwargs)
+
+    wrapper.__name__ = fn.__name__
+    wrapper.__doc__ = fn.__doc__
+    return wrapper
+
+
+@dataclass
+class _SlotRef:
+    """Where one (req, key) span's slots live: planned under the lock, fetched outside it.
+
+    Schedule split, not a single read tier:
+    - JOIN_NEXT_STEP in-transit: ``join_tids``. Fetch waits ``done``,
+      drains, then reads the pool. Staging views are never sliced.
+    - JOIN_ON_FINISH in-transit: ``staged_list`` task refs. Fetch uses
+      ``fetch_host`` (device freeze / committer host).
+    - Already in the CPU pool: ``already_staged`` → pool.
+
+    A JOIN_NEXT_STEP task may disappear between plan and join (another
+    entry already published it into the pool); ``join`` no-ops and the
+    pool rows persist.
+    """
+
+    slots: torch.Tensor  # KV slot ids (PrefixBlockPool rows)
+    key: TensorName
+    req_id: ReqId
+    already_staged: bool  # this key is already in the CPU pool
+    staged_list: list[tuple[WriteTask, torch.Tensor]]  # JOIN_ON_FINISH only
+    join_tids: list[Tid] = field(default_factory=list)  # JOIN_NEXT_STEP in-transit
+    # Slot version snapshot at plan time, checked on fetch.
+    reserved_version: torch.Tensor | None = None
+    # Copy-on-write rescue: slot's committed rows for pending reads.
+    preserved: dict[int, torch.Tensor] = field(default_factory=dict)
+
+
+@dataclass(kw_only=True)
+class _StepContext:
+    """Save-time snapshot of one step; consumed exactly once.
+
+    Built on the engine thread in save_outputs so materialize (possibly on
+    the async builder) never reads the live batch. Host rows live on `d2h`
+    (empty views when this save only had leftover mm). materialize or
+    discard_step pops it and frees the staging slot. A later save waits
+    if all slots are still held.
+    """
+
+    # Packed layout in batch order: req -> [start, end) of this step's rows.
+    spans: dict[ReqId, tuple[int, int]]
+    num_tokens_unpadded: int = 0
+
+    # Hits snapshotted at new_step_starts. Prefetch fills [hit | empty tail]
+    # during forward; materialize writes the tail.
+    hits: dict[ReqId, tuple[int, list[int]]]  # (hit_upto, blocks)
+    hit_prefetch: dict[ReqId, dict[TensorName, Future]] = field(default_factory=dict)
+
+    # Key split frozen at save: recompute at materialize races ensure_key.
+    cached_keys: set[TensorName] = field(default_factory=set)
+    # Leftover mm copied to CPU at save (this-step deferred rows + mm
+    # that is not written to the pool).
+    mm_cpu_snapshot: dict[TensorName, Any] = field(default_factory=dict)
+    # Wait this before reading mm_cpu_snapshot (None when nothing was on CUDA).
+    mm_cpu_snapshot_event: torch.cuda.Event | None = None
+
+    # Staging slot for this step id (empty views when only leftover mm).
+    d2h: StepD2HClaim | None = None
+
+
+class _SlotStatus(NamedTuple):
+    """Occupancy row for one tensor name (views into the table, not copies)."""
+
+    state: torch.Tensor  # int8[num_slots]
+    tids: torch.Tensor  # Tid per kv slot; 0 = none
+    slot_version: torch.Tensor  # int64[num_slots]; bumped each time a new write claims the slot
+
+
+class _SlotStatusTable:
+    """Per (KV slot, tensor name): empty, being written, or already in the pool.
+
+    Hidden and a deferred mm field on the same slot are independent.
+    ``map_slots`` marks a write in progress; if another task still owns
+    the slot, the manager records those rows as no longer owned by it.
+    ``commit`` runs after the pool write: still-owned slots become
+    committed.
+    """
+
+    def __init__(self, num_slots: int) -> None:
+        self.num_slots = num_slots
+        self.state: dict[TensorName, torch.Tensor] = {}  # int8[num_slots]
+        self.tids: dict[TensorName, torch.Tensor] = {}  # Tid per kv slot; 0 = none
+        self.slot_versions: dict[TensorName, torch.Tensor] = {}  # int64[num_slots]; bumped on each new write claim
+        self.task_slots: dict[Tid, torch.Tensor] = {}  # kv slots
+        self.task_keys: dict[Tid, tuple[TensorName, ...]] = {}
+
+    def init_table(self, key: TensorName) -> None:
+        """Allocate occupancy tensors for ``key`` if they do not exist."""
+        if key in self.state:
+            return
+        self.state[key] = torch.zeros(self.num_slots, dtype=torch.int8)
+        self.tids[key] = torch.zeros(self.num_slots, dtype=torch.int64)
+        self.slot_versions[key] = torch.zeros(self.num_slots, dtype=torch.int64)
+
+    def get_slot_status(self, key: TensorName) -> _SlotStatus:
+        """Occupancy tensors for ``key``. ``init_table`` must have run."""
+        return _SlotStatus(state=self.state[key], tids=self.tids[key], slot_version=self.slot_versions[key])
+
+    def map_slots(
+        self, slots: torch.Tensor, tid: Tid, keys: Iterable[TensorName]
+    ) -> list[tuple[Tid, TensorName, torch.Tensor]]:
+        """Record ``tid`` on these (slot, key). Return in-transit rows
+        another write still owned (caller marks them skipped on it)."""
+        keys = tuple(keys)
+        stolen: list[tuple[Tid, TensorName, torch.Tensor]] = []
+        for key in keys:
+            status = self.get_slot_status(key)
+            cur = status.tids[slots]
+            stale = (status.state[slots] == _Occupancy.IN_TRANSIT) & (cur != tid) & (cur != 0)
+            if bool(stale.any()):
+                for old in {int(o) for o in cur[stale].tolist()}:
+                    stolen.append((old, key, slots[stale & (cur == old)]))
+            status.state[slots] = _Occupancy.IN_TRANSIT
+            status.tids[slots] = tid
+            # Bump the version so a reader that captured an older one detects
+            # this claim even after it later commits (COMMITTED, not IN_TRANSIT).
+            status.slot_version[slots] += 1
+        prev = self.task_slots.get(tid)
+        if prev is None:
+            self.task_slots[tid] = slots
+            self.task_keys[tid] = keys
+        else:
+            # Deferred tasks grow one `_WriteChunk` per step.
+            self.task_slots[tid] = torch.cat([prev, slots])
+            self.task_keys[tid] = tuple(dict.fromkeys(self.task_keys[tid] + keys))
+        return stolen
+
+    def commit(self, tids: Iterable[Tid]) -> None:
+        """Flip still-owned slots to COMMITTED and drop the reverse index."""
+        for tid in tids:
+            slots = self.task_slots.pop(tid, None)
+            keys = self.task_keys.pop(tid, ())
+            if slots is None:
+                continue
+            for key in keys:
+                status = self.get_slot_status(key)
+                still_ours = status.tids[slots] == tid
+                idx = slots[still_ours]
+                status.state[idx] = _Occupancy.COMMITTED
+                status.tids[idx] = 0
+
+
+class _RequestTaskTable:
+    """Per request: still live, which WriteTasks it opened, deferred task.
+
+    Also allocates ``tid`` and increments per-request ``write_n``.
+    Device→host copy and pool write stay on the controller.
+    """
+
+    def __init__(self) -> None:
+        self._next_tid: Tid = 1
+        self.write_n: dict[ReqId, int] = {}  # last write_n issued
+        self.tasks: dict[ReqId, set[Tid]] = {}
+        self.deferred: dict[ReqId, WriteTask] = {}
+        self.live_reqs: set[ReqId] = set()
+
+    def alloc_tid(self) -> Tid:
+        tid = self._next_tid
+        self._next_tid += 1
+        return tid
+
+    def increment_write_n(self, req_id: ReqId) -> int:
+        n = self.write_n.get(req_id, 0) + 1
+        self.write_n[req_id] = n
+        return n
+
+    def track(self, req_id: ReqId, tid: Tid) -> None:
+        self.tasks.setdefault(req_id, set()).add(tid)
+
+    def finish(self, req_id: ReqId) -> tuple[set[Tid], WriteTask | None]:
+        """Drop this request's rows. Returns owned tids + deferred task."""
+        self.live_reqs.discard(req_id)
+        self.write_n.pop(req_id, None)
+        tids = self.tasks.pop(req_id, set())
+        dtask = self.deferred.pop(req_id, None)
+        return tids, dtask
+
+    def drop_completed(self, tids: Iterable[Tid]) -> None:
+        done = set(tids)
+        if not done:
+            return
+        for req_tids in self.tasks.values():
+            req_tids -= done
+
+
+class OmniPrefixCacheManager:
+    def __init__(
+        self,
+        config: PrefixCacheConfig,
+        view: FullAttentionGroupView,
+        *,
+        eager: bool | None = None,
+    ):
+        self._config = config
+        self._view = view
+        self._pool = PrefixBlockPool(config)
+        self._controller = OmniPrefixCacheController(self._pool, config, eager=eager)
+        self._policy = ModelCachePolicy()
+        # Serializes engine vs async-builder public entries. Non-reentrant:
+        # those entries never call each other, and the lock must not cover
+        # a wait-for-copy, GPU-byte-budget flush, or device→host copy.
+        self._state_lock = threading.Lock()
+
+        self._slot_status = _SlotStatusTable(config.num_blocks * config.block_size)
+        # Hidden is known from the default policy; mm rows at init_table.
+        if (hk := self._policy.hidden_key) is not None:
+            self._slot_status.init_table(hk)
+        self._request_tasks = _RequestTaskTable()
+        # Join worklists — not occupancy, not the request-task table.
+        self._join_next_step_tids: list[Tid] = []
+        self._join_finished_tids: set[Tid] = set()  # escalated on finish/abort
+
+        # This step's hits (copied into _StepContext at save).
+        self._cur_num_scheduled: dict[ReqId, int] = {}
+        self._hit_spans: dict[ReqId, tuple[int, list[int]]] = {}  # (upto, blocks)
+        self._hit_prefetch: dict[ReqId, dict[TensorName, Future]] = {}
+
+        # Planned-but-unread slot refs. A write reusing their slots copies the
+        # old rows into ``_SlotRef.preserved`` before overwriting (COW). Guarded
+        # by ``_state_lock``; each ref is dropped when its fetch completes.
+        self._pending_reads: list[_SlotRef] = []
+        # Sticky fatal set on the first drained write failure; every later
+        # facade entry re-raises it (see _commit_drained_writes).
+        self._fatal_write_failure: str | None = None
+
+        # Prefix gather during forward (CPU work releases the GIL).
+        # One worker: complete in submit order; pop finished work from the head.
+        self._prefetch_pool = ThreadPoolExecutor(1, thread_name_prefix="omni-prefix-cache-prefetch")
+        self._prefetch_queue: deque[tuple[Future, _SlotRef]] = deque()
+
+        # One snapshot per step id; consume with materialize or discard_step.
+        self._next_step_id: StepId = 1
+        self._step_ctxs: dict[StepId, _StepContext] = {}
+
+    # ------------------------------------------------------ public entries
+
+    def register_policy(self, policy: ModelCachePolicy) -> None:
+        self._policy = policy
+        if (hk := policy.hidden_key) is not None:
+            self._slot_status.init_table(hk)
+
+    @torch.inference_mode()
+    def new_step_starts(self, scheduler_output: SchedulerOutput) -> None:
+        """Handle one scheduler_output.
+
+        Engine thread only; before _update_states removes finished
+        requests; exactly once per real step. Registers new-request prefix
+        hits (copying their block tables) and forces finished/aborted
+        requests' still-open writes onto the high-priority copy queue —
+        a block hash that entered the batch must land in the cache,
+        abort included. ``escalate`` (eager: the copy + pool write) runs
+        after ``_state_lock`` is released.
+        """
+        to_escalate: list[int] = []
+        with self._state_lock:
+            # 1. Publish writes the committer has already written into the pool.
+            self._commit_drained_writes()
+
+            # 2. Finished/aborted reqs: collect still-open writes. Abort too:
+            #    those block hashes are already in vLLM; dropping the write
+            #    would leave future hits ABSENT. The next save waits
+            #    join_host_ready. (Not leftover_mm — those are this-step reads.)
+            finished = getattr(scheduler_output, "finished_req_ids", None) or ()
+            for req_id in finished:
+                tids, dtask = self._request_tasks.finish(req_id)
+                if dtask is not None:
+                    tids.add(dtask.tid)
+                pending_tasks = [tid for tid in tids if self._controller.get_task(tid) is not None]
+                if pending_tasks:
+                    to_escalate.extend(pending_tasks)
+                    self._join_finished_tids.update(pending_tasks)
+
+            # 3. Copy this arrival's prefix-hit block ids. scheduled_new_reqs
+            #    is the only place they appear; after _update_states they sit
+            #    on the live request and grow as decode allocates more blocks.
+            #    materialize (async builder) must not reread that live table.
+            self._clear_hit_infos()
+            for new_req in getattr(scheduler_output, "scheduled_new_reqs", ()) or ():
+                req_id = new_req.req_id
+                if req_id in self._request_tasks.live_reqs:
+                    # Already live: async_chunk continuation, or a V2-runner
+                    # resume after preemption (V1 resumes via
+                    # scheduled_cached_reqs). Either way num_computed_tokens is
+                    # not mirrored as a hit span; see the design doc.
+                    continue
+                self._request_tasks.live_reqs.add(req_id)
+                num_computed = int(getattr(new_req, "num_computed_tokens", 0) or 0)
+                if num_computed > 0:
+                    # block_ids is per-kv-group; group 0 only.
+                    blocks = getattr(new_req, "block_ids", None)
+                    if blocks is not None and len(blocks) > 0 and not isinstance(blocks[0], int):
+                        blocks = blocks[0]
+                    if not blocks:
+                        # Fail at the cause: a hit we cannot snapshot now would
+                        # crash at materialize time with less context (materialize is
+                        # forbidden from reading the live batch).
+                        raise OmniPrefixCacheUnmatchError(
+                            f"prefix hit for req {req_id} ({num_computed} tokens) carries no block_ids"
+                        )
+                    bs = self._config.block_size
+                    if num_computed % bs != 0:
+                        raise OmniPrefixCacheUnmatchError(
+                            f"prefix hit not block aligned (req={req_id}, hit_upto={num_computed}, block_size={bs})"
+                        )
+                    hit_blocks = list(blocks[: num_computed // bs])
+                    self._hit_spans[req_id] = (num_computed, hit_blocks)
+
+            # 4. Gather those spans on the prefetch thread; overlaps this forward.
+            while self._prefetch_queue and self._prefetch_queue[0][0].done():
+                self._prefetch_queue.popleft()
+            self._cur_num_scheduled = dict(scheduler_output.num_scheduled_tokens)
+            if self._hit_spans:
+                self._prefetch_hit_spans()
+        if to_escalate:
+            self._controller.escalate(to_escalate)
+
+    @torch.inference_mode()
+    def save_outputs(
+        self,
+        hidden_states: torch.Tensor | None,
+        mm_outputs: dict[str, Any] | None,
+        *,
+        num_tokens_unpadded: int,
+        num_tokens_padded: int,
+    ) -> int:
+        """Write this step's outputs into the cache; returns the step id.
+
+        Engine thread only, after the forward and before materialize.
+        Immediately-cached rows: one on-device clone, one whole-step
+        device→host into the staging pool, then one JOIN_NEXT_STEP
+        WriteTask per request whose `chunk.host` is a view of that page.
+        Deferred rows stay on the device clone (JOIN_ON_FINISH); the
+        committer copies them later. Leftover mm (this-step deferred rows
+        + mm not written to the pool) is copied to CPU here so materialize
+        never reads live graph buffers.
+        Snapshots everything materialize needs. The returned step id MUST
+        be consumed exactly once — by materialize() or discard_step().
+        Every step id claims one staging slot (saves with only leftover mm
+        included); a later save waits for a free slot and times out if
+        none return.
+
+        The state lock never covers a blocking wait: the previous step's
+        JOIN_NEXT_STEP wait, the clone build, the GPU-byte-budget reserve
+        (which may flush), and the staging-slot claim all run unlocked.
+        """
+        # 1. Join the previous step's host copies (unlocked).
+        self._wait_for_host_ready()
+
+        # 2. Packed batch layout for this step (req -> [start, end)).
+        req_order = self._view.batch_req_ids()
+        num_sched = {r: int(self._cur_num_scheduled.get(r, 0)) for r in req_order}
+        query_start: dict[str, int] = {}
+        current_start_idx = 0
+        for req_id in req_order:
+            query_start[req_id] = current_start_idx
+            current_start_idx += num_sched[req_id]
+
+        slots_cpu: torch.Tensor | None = None
+        mm_outputs = mm_outputs or {}
+        freeze_event = None
+
+        # 3. Slot map, then split into immediate / deferred / leftover.
+        if num_tokens_unpadded > 0:
+            # Derive the slot mapping on CPU: reading the device one back
+            # would need a stream sync that waits on the whole forward.
+            slots_cpu = self._view.step_slots_cpu(req_order, num_sched)
+            if int(slots_cpu.numel()) != num_tokens_unpadded:
+                # Fail at the cause: skipping the save would leave rows absent
+                # behind hashes vLLM already published — a delayed crash at
+                # some future hit instead of a debuggable one here.
+                raise OmniPrefixCacheUnmatchError(
+                    f"slot mapping covers {int(slots_cpu.numel())} of {num_tokens_unpadded} scheduled tokens; "
+                    "CPU-side slot derivation out of sync with the batch"
+                )
+        step_outputs = self._split_step_outputs(
+            hidden_states,
+            mm_outputs,
+            num_tokens_unpadded,
+            num_tokens_padded,
+            slots_cpu=slots_cpu,
+            req_order=req_order,
+            num_sched=num_sched,
+            query_start=query_start,
+        )
+
+        # 4. Freeze the device clones and reserve the GPU-byte budget (unlocked).
+        freezed_tensors = step_outputs.freeze_targets()
+        if freezed_tensors:
+            if torch.cuda.is_available() and any(t.is_cuda for t in freezed_tensors):
+                freeze_event = torch.cuda.Event()
+                freeze_event.record()
+            # One ticket per clone (immediate step clone, shared deferred
+            # clone); per-request slices are views and charge nothing.
+            # Reserve may block on a flush: outside the lock. The flush may
+            # close a deferred task this step appends to; _stage_deferred
+            # then opens a fresh one, so a long request cannot pin the
+            # whole budget.
+            self._controller.reserve(step_outputs.budget_bytes())
+
+        # 5. Claim a staging slot (unlocked), optional device→host into it,
+        #    register the writes + store the step snapshot (locked), then
+        #    dispatch the queued writes (unlocked: in eager mode dispatch
+        #    is the copy + pool write itself). Saves with only leftover mm
+        #    still claim. Full pool waits; timeout lists unused step ids.
+        d2h_claim: StepD2HClaim | None = None
+        step_holder = StagingBufferHolder.for_step(self._next_step_id)
+        transferred = False
+        bound_tids: list[int] = []
+        try:
+            d2h_claim = self._stage_step_host(step_outputs.immediate, num_tokens_unpadded, freeze_event, step_holder)
+
+            step_id, queued = self._publish_saved_step(
+                req_order=req_order,
+                query_start=query_start,
+                num_sched=num_sched,
+                num_tokens_unpadded=num_tokens_unpadded,
+                step_outputs=step_outputs,
+                slots_cpu=slots_cpu,
+                mm_keys=set(mm_outputs.keys()),
+                freeze_event=freeze_event,
+                d2h_claim=d2h_claim,
+                bound_tids=bound_tids,
+            )
+            self._controller.dispatch(queued)
+            transferred = True
+            return step_id
+        finally:
+            # Slot claim is outside the lock; a later raise must release
+            # the step and any task that already bound this slot.
+            if not transferred and d2h_claim is not None:
+                # A dispatch failure has no caller that can consume this step.
+                with self._state_lock:
+                    self._step_ctxs.pop(step_holder.owner_id, None)
+                self._release_staging_on_failed_save(d2h_claim.staging_slot, step_holder, bound_tids)
+
+    @torch.inference_mode()
+    def materialize(self, step_id: int, req_ids: list[str]) -> StageCacheOutputs:
+        """Per-request merged outputs for the step saved as `step_id`.
+
+        Any thread. `req_ids` must be (a subset of) the save-time snapshot;
+        an outside id means the caller is reading the live batch.
+        A request without a hit is a plain miss and gets exactly
+        this step's rows — normal path, nothing logged. A hit span that
+        resolves to absent rows raises OmniPrefixCacheUnmatchError: fatal
+        by contract (do not pretend it was a miss).
+
+        Two phases: under the lock, publish finished writes and pin every
+        row source (task refs + masks, absent checks included) — not yet
+        reading the tensors. Unlocked: wait this step's `step_d2h_event`,
+        clone the staging views (then drop the step holder), and merge.
+        The engine thread never waits on this thread's device→host copy.
+        """
+        ctx = None
+        step_released = False
+        try:
+            with self._state_lock:
+                ctx = self._take_step_ctx(step_id)
+                self._commit_drained_writes()
+
+                # The builder must pass (a subset of) the req list captured at
+                # save time — an id outside the snapshot means it is reading the
+                # live batch, which the contract forbids. Not a fallback that
+                # serves a miss.
+                unknown = set(req_ids) - set(ctx.spans)
+                if unknown:
+                    raise OmniPrefixCacheUnmatchError(
+                        f"materialize(step {step_id}) got req ids outside the save snapshot: {sorted(unknown)[:8]}"
+                    )
+
+                cached_keys = ctx.cached_keys
+
+                hit_sources: dict[tuple[str, str], _SlotRef | Future] = {}
+                for req_id in req_ids:
+                    hit = ctx.hits.get(req_id)
+                    if not hit:
+                        continue
+                    hit_upto, hit_blocks = hit
+                    prefetched = ctx.hit_prefetch.get(req_id, {})
+                    slots = self._get_hit_slots(hit_upto, hit_blocks)
+                    keys = self._policy.get_hit_keys(cached_keys)
+                    for key in keys:
+                        fut = prefetched.get(key)
+                        if fut is not None:
+                            hit_sources[(req_id, key)] = fut
+                            continue
+                        hit_sources[(req_id, key)] = self._slot_ref(slots, key, req_id)
+
+            # ---- unlocked: data movement + merge ----
+            if ctx.mm_cpu_snapshot_event is not None:
+                ctx.mm_cpu_snapshot_event.synchronize()
+                ctx.mm_cpu_snapshot = _unpin_leftover(ctx.mm_cpu_snapshot)
+            current: dict[str, torch.Tensor] = {}
+            if ctx.d2h is not None:
+                # Whole-step device→host was launched at save. One event wait
+                # (usually already complete), then a contiguous copy-out per
+                # key so consumers no longer depend on the reusable slot.
+                if ctx.d2h.event is not None:
+                    ctx.d2h.event.synchronize()
+                current = {k: v.clone() for k, v in ctx.d2h.views.items()}
+                self._release_step_staging(ctx, step_id)
+                step_released = True
+
+            hidden_out: dict[str, torch.Tensor] | None = None
+            hidden_key = self._policy.hidden_key
+            if hidden_key is not None and hidden_key in current:
+                hidden_out = {}
+                for req_id in req_ids:
+                    hidden_out[req_id] = self._merge_cached_for_req(
+                        ctx, req_id, hidden_key, current[hidden_key], hit_sources
+                    )
+
+            mm_out: dict[str, dict[str, Any]] = {}
+            for key in cached_keys:
+                cur = current.get(key)
+                if cur is None:
+                    val = ctx.mm_cpu_snapshot.get(key)
+                    if not isinstance(val, torch.Tensor):
+                        continue
+                    # Leftover snapshot; spans stay within [0, n), no re-slice.
+                    cur = val
+                mm_out[key] = {
+                    req_id: self._merge_cached_for_req(ctx, req_id, key, cur, hit_sources) for req_id in req_ids
+                }
+
+            self._merge_uncached_mm(ctx, req_ids, cached_keys, mm_out)
+            return StageCacheOutputs(hidden_states=hidden_out, mm_outputs=mm_out)
+        finally:
+            if ctx is not None and not step_released:
+                self._release_step_staging(ctx, step_id)
+
+    @_locked
+    def discard_step(self, step_id: int) -> None:
+        """Consume the step context when nothing will materialize it.
+
+        Any thread; same exactly-once contract as materialize (unknown or
+        duplicate id raises). Only the read-side snapshot is dropped —
+        the cache write proceeds unchanged.
+        """
+        ctx = self._take_step_ctx(step_id)
+        self._release_step_staging(ctx, step_id)
+
+    def shutdown(self) -> None:
+        self._prefetch_pool.shutdown(wait=False, cancel_futures=True)
+        self._prefetch_queue.clear()
+        self._controller.shutdown()
+
+    # ------------------------------------------------------ new_step
+
+    def _clear_hit_infos(self) -> None:
+        """Drop the live hit / prefetch tables. Caller holds ``_state_lock``."""
+        self._hit_spans.clear()
+        self._hit_prefetch.clear()
+
+    def _prefetch_hit_spans(self) -> None:
+        """Caller holds ``_state_lock``. Plan each hit span not yet planned
+        and gather it on the prefetch thread.
+
+        Called twice per step: at new_step_starts (overlaps the forward)
+        and again at publish for spans that could not plan then — same-step
+        hits, whose rows this step's save has only now registered. Starting
+        the gather at publish, not at materialize, means it runs before the
+        next step can hand those blocks to a new tenant; a span that still
+        fails to plan is left to materialize, which raises if unread.
+        """
+        keys = self._policy.get_hit_keys(self._pool.keys())
+        for req_id, (hit_upto, hit_blocks) in self._hit_spans.items():
+            futs = self._hit_prefetch.setdefault(req_id, {})
+            if all(key in futs for key in keys):
+                continue
+            n_new = int(self._cur_num_scheduled.get(req_id, 0))
+            slots = self._get_hit_slots(hit_upto, hit_blocks)
+            for key in keys:
+                if key in futs:
+                    continue
+                try:
+                    src = self._slot_ref(slots, key, req_id)
+                except OmniPrefixCacheUnmatchError:
+                    continue
+                fut = self._prefetch_pool.submit(self._prefetch_hit, src, n_new)
+                self._prefetch_queue.append((fut, src))
+                futs[key] = fut
+            if not futs:
+                del self._hit_prefetch[req_id]
+
+    @torch.inference_mode()
+    def _prefetch_hit(self, src: _SlotRef, n_new: int) -> torch.Tensor:
+        """Prefetch thread: gather the hit span and pre-build the merged
+        buffer with the prefix filled. materialize writes only this step's
+        rows at the tail — the gather AND the prefix copy both happen while
+        the forward runs, and the cat leaves the critical path."""
+        rows = self._fetch_source(src)
+        out = torch.empty((rows.shape[0] + n_new, rows.shape[-1]), dtype=rows.dtype)
+        out[: rows.shape[0]] = rows
+        return out
+
+    # ---------------------------------------------------------- save
+
+    def _stage_step_host(
+        self,
+        device_snapshot: dict[str, torch.Tensor],
+        num_tokens_unpadded: int,
+        freeze_event: torch.cuda.Event | None,
+        step_holder: StagingBufferHolder,
+    ) -> StepD2HClaim:
+        """Claim a staging slot (wait + timeout) and copy device→host if this step has rows.
+
+        Unlocked. Timeout is annotated with the unconsumed sids and the
+        task count so a leaked consume or a stuck write is visible.
+        """
+        try:
+            return self._controller.stage_step_host(device_snapshot, num_tokens_unpadded, freeze_event, step_holder)
+        except OmniPrefixCacheStagingTimeoutError as e:
+            with self._state_lock:
+                ids = sorted(self._step_ctxs)
+            raise OmniPrefixCacheStagingTimeoutError(
+                f"{e}; unconsumed step contexts (ids={ids}) or a stuck write "
+                f"(in_flight_tasks={self._controller.in_flight_tasks()})"
+            ) from e
+
+    def _wait_for_host_ready(self) -> None:
+        """Pop last step's join worklists and wait them out, unlocked.
+
+        JOIN_NEXT_STEP waits ``done``, not ``host_ready``: this save may reuse
+        those slots, and a pool write still pending behind a reused slot is
+        unreadable for a delayed hit read (scatter skips reassigned rows).
+        Escalated deferred writes keep ``host_ready`` — their readers hold the
+        task in ``staged_list``. Lock covers only the pop.
+        """
+        with self._state_lock:
+            finished_ids = list(self._join_finished_tids)
+            next_step_ids = list(self._join_next_step_tids)
+            self._join_finished_tids.clear()
+            self._join_next_step_tids.clear()
+        if finished_ids:
+            self._controller.join_host_ready(finished_ids)
+        if next_step_ids:
+            self._controller.join(next_step_ids)
+
+    @_locked
+    def _publish_saved_step(
+        self,
+        *,
+        req_order: list[str],
+        query_start: dict[str, int],
+        num_sched: dict[str, int],
+        num_tokens_unpadded: int,
+        step_outputs: _StepOutputs,
+        slots_cpu: torch.Tensor | None,
+        mm_keys: set[str],
+        freeze_event: torch.cuda.Event | None,
+        d2h_claim: StepD2HClaim,
+        bound_tids: list[int],
+    ) -> tuple[StepId, list[WriteTask]]:
+        """Takes ``_state_lock``. Register this step's writes and store the
+        consume-once snapshot. Copies live hits into the snapshot, then
+        clears them. Returns the queued tasks for the caller to dispatch
+        unlocked; device→host, budget flush and the eager copy stay outside.
+        """
+        self._commit_drained_writes()
+        for key, storage in step_outputs.new_key_storage.items():
+            self._pool.install_key(key, storage)
+            self._slot_status.init_table(key)
+        queued: list[WriteTask] = []
+        if step_outputs.immediate:
+            queued = self._submit_step_writes(
+                req_order,
+                query_start,
+                num_sched,
+                step_outputs.immediate,
+                step_outputs.immediate_budget,
+                slots_cpu,
+                d2h_claim.views,
+                freeze_event,
+                d2h_claim.staging_slot,
+                d2h_claim.event,
+                bound_tids,
+            )
+        self._stage_deferred(step_outputs.deferred_chunks, freeze_event)
+        if self._hit_spans:
+            # Same-step hits: their rows are registered now (IN_TRANSIT on
+            # this step's tasks); start the gather before the next step.
+            self._prefetch_hit_spans()
+        step_id = self._next_step_id
+        self._next_step_id += 1
+        self._step_ctxs[step_id] = _StepContext(
+            spans={r: (query_start[r], query_start[r] + num_sched[r]) for r in req_order},
+            num_tokens_unpadded=num_tokens_unpadded,
+            hits=dict(self._hit_spans),
+            hit_prefetch=dict(self._hit_prefetch),
+            cached_keys=without_hidden(self._pool.keys()) & mm_keys,
+            mm_cpu_snapshot=step_outputs.leftover,
+            mm_cpu_snapshot_event=step_outputs.leftover_event,
+            d2h=d2h_claim,
+        )
+        self._clear_hit_infos()
+        return step_id, queued
+
+    def _split_step_outputs(
+        self,
+        hidden_states: torch.Tensor | None,
+        mm_outputs: dict[str, Any],
+        num_tokens_unpadded: int,
+        num_tokens_padded: int,
+        *,
+        slots_cpu: torch.Tensor | None,
+        req_order: list[str],
+        num_sched: dict[str, int],
+        query_start: dict[str, int],
+    ) -> _StepOutputs:
+        """Split this step's outputs into immediate / deferred / leftover.
+
+        Unlocked. One pass over ``mm_outputs``. ``n==0`` has only leftover
+        mm (no device clones). A deferred key whose first dim is this
+        step's token count is cloned for the JOIN_ON_FINISH write and
+        CPU-copied into leftover for this-step materialize. Talker
+        ``codes.audio`` stays unpadded while hidden is padded; both must
+        open a pool key.
+        Lists and other shapes stay leftover.
+        """
+        n = num_tokens_unpadded
+        immediate: dict[str, torch.Tensor] = {}
+        deferred_tensors: dict[str, torch.Tensor] = {}
+        new_key_storage: dict[str, torch.Tensor] = {}
+
+        def alloc_key(key: str, val: torch.Tensor) -> None:
+            # Pinned allocation, unlocked; installed under the lock at publish.
+            storage = self._pool.alloc_key(key, val.dtype, int(val.shape[-1]))
+            if storage is not None:
+                new_key_storage[key] = storage
+
+        if n > 0:
+            if hidden_states is not None and (hk := self._policy.hidden_key) is not None:
+                if hidden_states.ndim < 2 or hidden_states.shape[0] < n:
+                    rows = 0 if hidden_states.ndim < 2 else int(hidden_states.shape[0])
+                    raise OmniPrefixCacheUnmatchError(f"hidden_states has {rows} rows, need {n}")
+                alloc_key(hk, hidden_states)
+                immediate[hk] = hidden_states[:n].clone()
+            for key, val in mm_outputs.items():
+                is_step_rows = _is_step_token_tensor(val, n, num_tokens_padded)
+                if key in self._policy.deferred_keys:
+                    if is_step_rows:
+                        alloc_key(key, val)
+                        deferred_tensors[key] = val[:n].clone()
+                    continue
+                if self._policy.skip_immediate_mm(key) or not is_step_rows:
+                    continue
+                alloc_key(key, val)
+                immediate[key] = val[:n].clone()
+        leftover, leftover_event = _snapshot_leftover_mm_cpu(mm_outputs, set(immediate), n, num_tokens_padded)
+        deferred_chunks: list[tuple[str, _WriteChunk]] = []
+        if deferred_tensors:
+            assert slots_cpu is not None
+            deferred_chunks = self._pack_deferred_chunks(deferred_tensors, slots_cpu, req_order, num_sched, query_start)
+        immediate_budget = (
+            _BudgetTicket(nbytes=sum(t.numel() * t.element_size() for t in immediate.values())) if immediate else None
+        )
+        return _StepOutputs(
+            immediate=immediate,
+            deferred_chunks=deferred_chunks,
+            leftover=leftover,
+            leftover_event=leftover_event,
+            immediate_budget=immediate_budget,
+            new_key_storage=new_key_storage,
+        )
+
+    def _pack_deferred_chunks(
+        self,
+        deferred_tensors: dict[str, torch.Tensor],
+        slots_cpu: torch.Tensor,
+        req_order: list[str],
+        num_sched: dict[str, int],
+        query_start: dict[str, int],
+    ) -> list[tuple[str, _WriteChunk]]:
+        """Per-req views of already-cloned deferred tensors. No further clone."""
+        ticket = _BudgetTicket(nbytes=sum(t.numel() * t.element_size() for t in deferred_tensors.values()))
+        out: list[tuple[str, _WriteChunk]] = []
+        for req_id in req_order:
+            sched = num_sched[req_id]
+            if sched <= 0:
+                continue
+            start = query_start[req_id]
+            end = start + sched
+            out.append(
+                (
+                    req_id,
+                    _WriteChunk(
+                        slots_cpu=slots_cpu[start:end],
+                        tensors={k: v[start:end] for k, v in deferred_tensors.items()},
+                        budget=ticket,
+                    ),
+                )
+            )
+        return out
+
+    def _submit_step_writes(
+        self,
+        req_order: list[str],
+        query_start: dict[str, int],
+        num_sched: dict[str, int],
+        device_snapshot: dict[str, torch.Tensor],
+        budget: _BudgetTicket | None,
+        slots_cpu: torch.Tensor,
+        host_views: dict[str, torch.Tensor],
+        freeze_event,
+        staging_slot: int,
+        step_d2h_event,
+        bound_tids: list[int],
+    ) -> list[WriteTask]:
+        """Caller holds ``_state_lock``. Register one WriteTask per request;
+        returns them for the caller to dispatch once the lock is released.
+
+        Per-req views of the shared device snapshot: one on-device clone, req-scoped
+        finish/abort, reassigned rows, and completion. Appends bound tids to
+        `bound_tids` as it goes so a mid-loop raise still unwinds holders.
+        """
+        tasks: list[WriteTask] = []
+        for req_id in req_order:
+            start = query_start[req_id]
+            end = start + num_sched[req_id]
+            if end == start:
+                continue
+            tensors = {k: v[start:end] for k, v in device_snapshot.items()}
+            tid = self._request_tasks.alloc_tid()
+            chunk = _WriteChunk(slots_cpu=slots_cpu[start:end], tensors=tensors, budget=budget)
+            # Host rows are views into the slot; the committer only waits
+            # the shared step event. Device→host is already in flight.
+            chunk.host = {k: v[start:end] for k, v in host_views.items()}
+            task = WriteTask(
+                tid=tid,
+                req_id=req_id,
+                write_n=self._request_tasks.increment_write_n(req_id),
+                schedule=WriteSchedule.JOIN_NEXT_STEP,
+                chunks=[chunk],
+                freeze_event=freeze_event,
+                staging_slot=staging_slot,
+                step_d2h_event=step_d2h_event,
+            )
+            self._map_slots(slots_cpu[start:end], tid, tensors.keys())
+            # Bind and pin before register: the slot must never be holder-free
+            # while the task is live (released at its pool write).
+            self._controller.staging_bind(staging_slot, StagingBufferHolder.for_task(tid))
+            bound_tids.append(tid)
+            if budget is not None:
+                self._controller.pin_budget(budget, tid)
+            self._controller.register(task)
+            self._request_tasks.track(req_id, tid)
+            self._join_next_step_tids.append(tid)
+            tasks.append(task)
+        return tasks
+
+    def _stage_deferred(self, deferred_chunks: list[tuple[str, _WriteChunk]], freeze_event) -> None:
+        """Caller holds ``_state_lock``. Register pre-built deferred `_WriteChunk`s
+        (bytes already reserved by save_outputs).
+
+        A new write (``write_n`` + 1) starts when the open task was closed by
+        the budget flush, or when a chunk re-acquires a (key, slot) the task
+        already lost — appending there would let its own reassigned tombstone
+        drop the fresh rows at scatter. Hits read both through ``staged_list``.
+        """
+        for req_id, chunk in deferred_chunks:
+            task = self._request_tasks.deferred.get(req_id)
+            if task is not None and (
+                task.reassigned_intersects(chunk)
+                or self._controller.append_chunk(task, chunk, freeze_event) is not None
+            ):
+                task = None
+            if task is None:
+                task = WriteTask(
+                    tid=self._request_tasks.alloc_tid(),
+                    req_id=req_id,
+                    write_n=self._request_tasks.increment_write_n(req_id),
+                    schedule=WriteSchedule.JOIN_ON_FINISH,
+                    chunks=[chunk],
+                    freeze_event=freeze_event,
+                )
+                self._request_tasks.deferred[req_id] = task
+                self._request_tasks.track(req_id, task.tid)
+                self._controller.register(task, queued=False)
+            if chunk.budget is not None:
+                # Safe after register: queued=False keeps the task PENDING
+                # until escalate, which only this thread calls.
+                self._controller.pin_budget(chunk.budget, task.tid)
+            # Block reuse across deferred tenants (preemption path) is
+            # handled inside _map_slots: the old tenant's rows are skipped.
+            self._map_slots(chunk.slots_cpu, task.tid, chunk.tensors.keys())
+
+    # ----------------------------------------------------- occupancy
+
+    def _map_slots(self, slots: torch.Tensor, tid: int, keys: Iterable[str]) -> None:
+        """Caller holds ``_state_lock``. Record `tid` on these (slot, key);
+        if another write still owns them, mark those rows skipped on it."""
+        keys = tuple(keys)
+        # Copy committed rows aside before this claim overwrites them.
+        if self._pending_reads:
+            self._preserve_for_pending_reads(slots, keys)
+        for old, key, stolen in self._slot_status.map_slots(slots, tid, keys):
+            old_task = self._controller.get_task(old)
+            if old_task is not None:
+                old_task.add_reassigned(key, stolen)
+
+    def _preserve_for_pending_reads(self, new_slots: torch.Tensor, keys: tuple[str, ...]) -> None:
+        """Caller holds ``_state_lock``. Copy still-valid committed rows into
+        each pending ref before ``new_slots`` are claimed.
+
+        Only COMMITTED rows at the reserved version need rescuing: the save
+        barrier joins JOIN_NEXT_STEP writes to ``done`` and publish drains
+        before claiming, and JOIN_ON_FINISH in-transit rows are read through
+        ``staged_list`` task refs directly.
+        """
+        new_set = {int(s) for s in new_slots.tolist()}
+        for ref in self._pending_reads:
+            if ref.key not in keys or ref.reserved_version is None or not self._pool.has_key(ref.key):
+                continue
+            status = self._slot_status.get_slot_status(ref.key)
+            take: list[tuple[int, int]] = []  # (row index in ref, slot)
+            for i, s in enumerate(ref.slots.tolist()):
+                s = int(s)
+                if s not in new_set or s in ref.preserved:
+                    continue
+                committed = int(status.state[s]) == _Occupancy.COMMITTED
+                if committed and int(status.slot_version[s]) == int(ref.reserved_version[i]):
+                    take.append((i, s))
+            if not take:
+                continue
+            rows = self._pool.rows(ref.key, torch.tensor([s for _, s in take], dtype=torch.long))
+            for j, (_, s) in enumerate(take):
+                ref.preserved[s] = rows[j].clone()
+
+    @torch.inference_mode()
+    def _commit_drained_writes(self) -> None:
+        """Fold completed/failed writes into occupancy. Caller holds ``_state_lock``.
+
+        A failed write leaves rows absent behind hashes vLLM already
+        published — unservable and unrecoverable, so fatal. The fatality is
+        sticky: the drained record is one-shot and the first raise can land
+        in a swallowed path (a prefetch Future dropped by discard_step), so
+        every later entry must keep raising rather than serve zeros.
+        """
+        if self._fatal_write_failure is not None:
+            raise OmniPrefixCacheUnmatchError(self._fatal_write_failure)
+        failed = self._controller.drain_failed()
+        if failed:
+            self._fatal_write_failure = (
+                f"prefix cache write failed for task(s) {failed}; cached rows lost behind published hashes"
+            )
+            raise OmniPrefixCacheUnmatchError(self._fatal_write_failure)
+        drained = self._controller.drain_completed()
+        if drained:
+            self._slot_status.commit(drained)
+            self._request_tasks.drop_completed(drained)
+
+    # --------------------------------------------------- consume-once
+
+    def _take_step_ctx(self, step_id: int) -> _StepContext:
+        """Pop the context for this step id (exactly once). Caller holds ``_state_lock``."""
+        ctx = self._step_ctxs.pop(step_id, None)
+        if ctx is None:
+            raise OmniPrefixCacheUnmatchError(
+                f"step context {step_id} missing (have {sorted(self._step_ctxs)}); already consumed or never saved"
+            )
+        return ctx
+
+    def _release_step_staging_slot(self, slot: int, step_id: int) -> None:
+        self._controller.staging_release(slot, StagingBufferHolder.for_step(step_id))
+
+    def _release_step_staging(self, ctx: _StepContext, step_id: int) -> None:
+        """Drop this step's staging hold. Does not require ``_state_lock``.
+
+        materialize/discard: task holds leave at their pool write.
+        """
+        if ctx.d2h is not None:
+            self._release_step_staging_slot(ctx.d2h.staging_slot, step_id)
+
+    def _release_staging_on_failed_save(
+        self, slot: int, step_holder: StagingBufferHolder, bound_tids: list[int]
+    ) -> None:
+        """save raised after claiming the slot: drop the step hold and any
+        task holds. Does not require ``_state_lock``.
+        """
+        self._release_step_staging_slot(slot, step_holder.owner_id)
+        for tid in bound_tids:
+            self._controller.staging_release(slot, StagingBufferHolder.for_task(tid))
+
+    # -------------------------------------------------- slot ref / fetch
+
+    def _get_hit_slots(self, hit_upto: int, hit_blocks: list[int]) -> torch.Tensor:
+        """Prefix-hit block ids → KV slot ids. Alignment is checked at
+        ``new_step_starts``. Does not require ``_state_lock``.
+        """
+        bs = self._config.block_size
+        block_ids = torch.tensor(hit_blocks, dtype=torch.int64)
+        return (block_ids.unsqueeze(1) * bs + torch.arange(bs)).reshape(-1)[:hit_upto]
+
+    def _slot_ref(self, slots: torch.Tensor, key: str, req_id: str) -> _SlotRef:
+        """Caller holds ``_state_lock``. Pin a ``_SlotRef`` for `slots` (no data movement).
+
+        Rows still being written win over the CPU pool: they may not have
+        landed yet, and a pool read would return zero/stale values.
+        JOIN_NEXT_STEP tasks go in ``join_tids`` (wait-then-pool at
+        fetch). JOIN_ON_FINISH tasks stay as refs for fetch_host.
+
+        Hidden rejects any empty hole (prefetch skips; materialize
+        raises). Other keys only need a source — holes fall to the pool.
+
+        The ref is registered in ``_pending_reads`` so a write that later
+        reuses one of these slots copies the old row aside first (COW). Reads
+        are planned synchronously under the lock at hit time (prefetch runs at
+        ``new_step_starts`` / publish), before the block can be reused, so this
+        registration always precedes the reuse. ``_fetch_source`` unregisters.
+        """
+        status = self._slot_status.get_slot_status(key)
+        states = status.state[slots]
+        tids = status.tids[slots]
+        reserved_version = status.slot_version[slots].clone()
+        staged_mask = states == _Occupancy.IN_TRANSIT
+
+        staged: list[tuple[WriteTask, torch.Tensor]] = []
+        join_tids: list[int] = []
+        for tid in {int(t) for t in tids[staged_mask].tolist()}:
+            task = self._controller.get_task(tid) if tid != 0 else None
+            if task is None:
+                _raise_unreadable_hit(req_id, key, f"in-transit entry {tid} cannot serve them")
+            if task.schedule is WriteSchedule.JOIN_NEXT_STEP:
+                join_tids.append(task.tid)
+            else:
+                staged.append((task, staged_mask & (tids == tid)))
+
+        already_staged = self._pool.has_key(key)
+        has_source = already_staged or bool(staged) or bool(join_tids)
+        if is_hidden_key(key):
+            n_abs = int((states == _Occupancy.ABSENT).sum())
+            if n_abs or not has_source:
+                _raise_unreadable_hit(req_id, key, f"{n_abs} absent slots")
+        ref = _SlotRef(
+            slots=slots,
+            key=key,
+            req_id=req_id,
+            already_staged=already_staged,
+            staged_list=staged,
+            join_tids=join_tids,
+            reserved_version=reserved_version,
+        )
+        self._pending_reads.append(ref)
+        return ref
+
+    def _apply_preserved_rows(self, src: _SlotRef, out: torch.Tensor) -> torch.Tensor:
+        """Write ``src.preserved`` rows over the matching slots in ``out``."""
+        if not src.preserved:
+            return out
+        for i, s in enumerate(src.slots.tolist()):
+            row = src.preserved.get(int(s))
+            if row is not None:
+                out[i] = row
+        return out
+
+    def _unregister_pending_read(self, src: _SlotRef) -> None:
+        """Drop ``src`` from ``_pending_reads``. Identity, not dataclass eq
+        (tensors in the ref make ``==`` unusable). Safe if already removed."""
+        with self._state_lock:
+            self._pending_reads = [ref for ref in self._pending_reads if ref is not src]
+
+    def _fetch_source(self, src: _SlotRef) -> torch.Tensor:
+        """Fetch a planned row source (execute phase, no lock).
+
+        One key is one schedule: ``join_tids`` (JOIN_NEXT_STEP) and
+        ``staged_list`` (JOIN_ON_FINISH) do not coexist. Immediate: wait
+        ``done``, drain, read the pool. Deferred: pool rows already
+        written, overlay ``fetch_host`` on the still-in-progress mask.
+        Slots a later write reused are served from ``src.preserved``
+        (copied under the lock before that write claimed them).
+        """
+        try:
+            return self._fetch_source_inner(src)
+        finally:
+            self._unregister_pending_read(src)
+
+    def _fetch_source_inner(self, src: _SlotRef) -> torch.Tensor:
+        # For JOIN_NEXT_STEP, wait `done`, drain, read the pool
+        if src.join_tids:
+            self._controller.join(src.join_tids)
+            with self._state_lock:
+                self._commit_drained_writes()
+            joined = self._apply_preserved_rows(src, self._pool.rows(src.key, src.slots))
+            self._ensure_not_reassigned(
+                src.slots,
+                src.key,
+                req_id=src.req_id,
+                planned_version=src.reserved_version,
+                preserved_slots=src.preserved,
+            )
+            return joined
+
+        # For JOIN_ON_FINISH, pool rows already written, overlay `fetch_host`
+        n = int(src.slots.numel())
+        out: torch.Tensor | None = None
+        if src.already_staged:
+            out = self._pool.rows(src.key, src.slots)
+        in_transit = None
+        for task, mask in src.staged_list:
+            try:
+                rows = self._controller.fetch_host(task, src.slots[mask], src.key)
+            except KeyError:
+                _raise_unreadable_hit(
+                    src.req_id,
+                    src.key,
+                    f"entry {task.tid} (req {task.req_id}, write_n {task.write_n}) cannot serve them",
+                )
+            if out is None:
+                out = torch.zeros((n, rows.shape[-1]), dtype=rows.dtype)
+            out[mask] = rows
+            in_transit = mask if in_transit is None else in_transit | mask
+        if out is not None:
+            out = self._apply_preserved_rows(src, out)
+        self._ensure_not_reassigned(
+            src.slots,
+            src.key,
+            in_transit_mask=in_transit,
+            req_id=src.req_id,
+            planned_version=src.reserved_version,
+            preserved_slots=src.preserved,
+        )
+        if out is None:
+            _raise_unreadable_hit(src.req_id, src.key, "no source")
+        return out
+
+    def _ensure_not_reassigned(
+        self,
+        slots: torch.Tensor,
+        key: str,
+        *,
+        in_transit_mask: torch.Tensor | None = None,
+        req_id: str = "?",
+        planned_version: torch.Tensor | None = None,
+        preserved_slots: dict[int, torch.Tensor] | None = None,
+    ) -> None:
+        """Takes ``_state_lock``. Post-fetch check: rows read unlocked may
+        have been given to a newer write between plan and read (block reuse).
+
+        vLLM frees a request's blocks when it finishes or is aborted, one
+        step before ``finished_req_ids`` reaches us, and may reuse them at
+        once. A planned ``_SlotRef`` is registered in ``_pending_reads``;
+        the reusing write copy-on-writes those COMMITTED rows into
+        ``preserved`` before it claims the slots. Those slots are safe.
+        A version mismatch with no preserved copy means the pool rows are
+        a newer tenant's — raise for live and finished alike, never serve
+        them.
+
+        ``planned_version`` is the per-slot version captured at plan time.
+        ``in_transit_mask`` excludes JOIN_ON_FINISH slots this task itself
+        still serves through ``fetch_host``.
+        """
+        with self._state_lock:
+            status = self._slot_status.get_slot_status(key)
+            if planned_version is not None:
+                violated = status.slot_version[slots] != planned_version
+            else:
+                violated = status.state[slots] == _Occupancy.IN_TRANSIT
+            if in_transit_mask is not None:
+                violated &= ~in_transit_mask
+            if preserved_slots:
+                for i, s in enumerate(slots.tolist()):
+                    if int(s) in preserved_slots:
+                        violated[i] = False
+            if not bool(violated.any()):
+                return
+            live = req_id in self._request_tasks.live_reqs
+        _raise_unreadable_hit(
+            req_id,
+            key,
+            f"{int(violated.sum())} hit slots reassigned before this delayed read "
+            f"({'live' if live else 'finished'} req, block reuse)",
+        )
+
+    # ---------------------------------------------------------- merge
+
+    def _merge_cached_for_req(
+        self,
+        ctx: _StepContext,
+        req_id: str,
+        key: str,
+        current_cpu: torch.Tensor,
+        hit_sources: dict[tuple[str, str], _SlotRef | Future],
+    ) -> torch.Tensor:
+        """Hit prefix + this step's rows for one (req, key).
+
+        No hit → this step's slice only. Prefetch Future → write the
+        slice into the reserved tail. Else cat(fetch, new).
+        """
+        start, end = ctx.spans[req_id]
+        new_rows = current_cpu[start:end]
+        src = hit_sources.get((req_id, key))
+        if src is None:
+            return new_rows
+        if isinstance(src, Future):
+            # Prefetched during the forward, prefix already in place; only
+            # this step's rows land here. result() re-raises fetch/validation
+            # errors — unread hits still raise after the thread hop.
+            merged = src.result()
+            merged[merged.shape[0] - new_rows.shape[0] :] = new_rows
+            return merged
+        cached = self._fetch_source(src)
+        return torch.cat([cached, new_rows], dim=0)
+
+    def _merge_uncached_mm(
+        self,
+        ctx: _StepContext,
+        req_ids: list[str],
+        cached_keys: set[str],
+        mm_out: dict[str, dict[str, Any]],
+    ) -> None:
+        """Write leftover mm that is not a pool key into mm_out.
+
+        No hit concat: leftover mm was already copied to CPU at save
+        (``ctx.mm_cpu_snapshot``). cached_keys already went through
+        _merge_cached_for_req. ``req_ids`` is a subset of ``ctx.spans``.
+        """
+        leftover = {k: v for k, v in ctx.mm_cpu_snapshot.items() if k not in cached_keys and not is_hidden_key(k)}
+        if not leftover:
+            return
+        from vllm_omni.utils.mm_outputs import to_payload_element
+
+        order = list(ctx.spans)
+        total_length = sum(e - s for s, e in ctx.spans.values())
+        for key, val in leftover.items():
+            per_req: dict[str, Any] = {}
+            for req_id in req_ids:
+                idx = order.index(req_id)
+                start, end = ctx.spans[req_id]
+                per_req[req_id] = to_payload_element(
+                    val,
+                    idx,
+                    start=start,
+                    end=end,
+                    pass_lists_through=True,
+                    seq_len=total_length,
+                )
+            mm_out[key] = per_req
diff --git a/vllm_omni/core/prefix_cache/runner_mixin.py b/vllm_omni/core/prefix_cache/runner_mixin.py
new file mode 100644
index 00000000000..25fa4fe2b43
--- /dev/null
+++ b/vllm_omni/core/prefix_cache/runner_mixin.py
@@ -0,0 +1,148 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+"""Runner-facing access layer for the omni prefix cache.
+
+One copy of the integration rules shared by the GPU and NPU runners:
+one-shot manager construction, the model cache-policy snapshot, and the
+per-step lifecycle entry. The manager/controller state machines and the
+platform output-building flows stay in their owners.
+
+Not exported from the package ``__init__``; runners import this module
+directly. No module-level vLLM import (``get_pp_group`` is resolved at
+call time) so ``tests/core`` keeps loading the package without vLLM.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from vllm_omni.core.prefix_cache.group_view import get_prefix_cache_group_view
+from vllm_omni.core.prefix_cache.interface import (
+    ModelCachePolicy,
+    OmniPrefixCacheUnmatchError,
+    PrefixCacheConfig,
+)
+from vllm_omni.core.prefix_cache.manager import OmniPrefixCacheManager
+from vllm_omni.data_entry_keys import flatten_payload
+
+if TYPE_CHECKING:
+    import torch
+    from vllm.v1.core.sched.output import SchedulerOutput
+
+
+class PrefixCacheRunnerMixin:
+    """Prefix-cache integration for a model runner (no state machine here).
+
+    Host-class contract — the runner must provide:
+        ``input_batch``        live batch with the group-0 block table
+        ``kv_cache_config``    for ``kv_cache_groups`` at construction
+        ``omni_prefix_cache``  set here; ``None`` until first-step build
+        ``_omni_prefix_cache_cfg``  staged by the runner's kv-cache init
+                               (``stage_prefix_cache_config``), consumed here
+
+    No cooperative ``__init__``: the class attributes below are safe
+    defaults (``ModelCachePolicy`` is frozen); runners keep initializing
+    their instance fields as before.
+    """
+
+    # Host-class fields (annotation only; the runner initializes them).
+    input_batch: Any
+    kv_cache_config: Any
+    is_pooling_model: bool
+
+    omni_prefix_cache: OmniPrefixCacheManager | None = None
+    _omni_prefix_cache_cfg: PrefixCacheConfig | None = None
+    # Snapshotted once at load_model; the hot path must not re-probe model
+    # attributes every step. The same object is registered on the manager.
+    _omni_cache_policy: ModelCachePolicy = ModelCachePolicy()
+
+    def _snapshot_prefix_cache_model_policy(self, model) -> None:
+        """Freeze the model's cache policy at load_model."""
+        self._omni_cache_policy = ModelCachePolicy.from_model(model)
+
+    def _model_needs_full_prefix_hidden_states(self) -> bool:
+        """Opt-out hook for models whose postprocess only consumes the tail.
+
+        When False, we skip both the per-step hidden-state write into the
+        omni prefix cache and the merged-tensor reconstruction on hits;
+        postprocess receives the normal scheduled-token slice instead. Models
+        that need the full cached_prefix + new_tail span (default) are not
+        affected.
+        """
+        return self._omni_cache_policy.needs_full_hidden_states
+
+    def _ensure_omni_prefix_cache(self) -> None:
+        """One-shot construction (caller gates on the staged config).
+
+        Only the last PP rank writes and materializes the cache. Other ranks
+        would register hits they can never serve (save_outputs is last-rank
+        only), so skip construction there.
+        """
+        from vllm.distributed.parallel_state import get_pp_group
+
+        cfg = self._omni_prefix_cache_cfg
+        self._omni_prefix_cache_cfg = None
+        if cfg is None or not get_pp_group().is_last_rank:
+            return
+        view = get_prefix_cache_group_view(
+            self.input_batch,
+            cfg.block_size,
+            kv_cache_groups=getattr(self.kv_cache_config, "kv_cache_groups", None),
+        )
+        if view is None:
+            raise OmniPrefixCacheUnmatchError(
+                "omni prefix caching requires a block table on the input batch; "
+                "disable enable_prefix_caching for this model"
+            )
+        manager = OmniPrefixCacheManager(cfg, view)
+        manager.register_policy(self._omni_cache_policy)
+        self.omni_prefix_cache = manager
+
+    def _prefix_cache_step_begin(self, scheduler_output: SchedulerOutput) -> None:
+        """Per-step lifecycle entry; must run before ``_update_states``
+        removes finished requests (finished/abort escalation happens inside
+        ``new_step_starts``). Builds the manager on the first real step."""
+        if self.omni_prefix_cache is None and self._omni_prefix_cache_cfg is not None:
+            self._ensure_omni_prefix_cache()
+        if self.omni_prefix_cache is not None:
+            self.omni_prefix_cache.new_step_starts(scheduler_output)
+
+    def _prefix_cache_save_step(
+        self,
+        hidden_states: torch.Tensor,
+        multimodal_outputs: dict | None,
+        *,
+        num_tokens_unpadded: int,
+        num_tokens_padded: int,
+    ) -> int | None:
+        """Write this step's outputs into the cache.
+
+        None when this stage/rank does not write (pooling, cache off, or not
+        the last PP rank). The returned step id must be consumed exactly once
+        — materialize or discard_step — by the output path.
+        """
+        from vllm.distributed.parallel_state import get_pp_group
+
+        if self.is_pooling_model or self.omni_prefix_cache is None or not get_pp_group().is_last_rank:
+            return None
+        return self.omni_prefix_cache.save_outputs(
+            hidden_states,
+            flatten_payload(multimodal_outputs) if multimodal_outputs else {},
+            num_tokens_unpadded=num_tokens_unpadded,
+            num_tokens_padded=num_tokens_padded,
+        )
+
+    def _prefix_cache_materialize(
+        self, step_id: int | None, req_ids: list[str]
+    ) -> tuple[dict[str, torch.Tensor] | None, dict | None]:
+        """Per-request merged outputs for a saved step.
+
+        ``req_ids`` must be the save-time snapshot, never the live
+        ``input_batch`` (under async output this runs a step late).
+        ``step_id`` None means save did not run — nothing to consume.
+        ``mm_outputs`` is all-or-nothing; empty only when the step had no mm.
+        """
+        if step_id is None or self.omni_prefix_cache is None:
+            return None, None
+        outs = self.omni_prefix_cache.materialize(step_id, list(req_ids))
+        return outs.hidden_states, (outs.mm_outputs or None)
diff --git a/vllm_omni/deploy/qwen3_tts.yaml b/vllm_omni/deploy/qwen3_tts.yaml
index 4019f10aaa4..8f5ab584dfa 100644
--- a/vllm_omni/deploy/qwen3_tts.yaml
+++ b/vllm_omni/deploy/qwen3_tts.yaml
@@ -63,11 +63,12 @@ stages:
     max_num_seqs: 64
     gpu_memory_utilization: 0.3
     trust_remote_code: true
-    # Prefix caching on by default. The HS opt-out (talker only consumes the
-    # last token's hidden state) and deferred mm-output writes added in this
-    # PR make per-step bookkeeping negligible, and any text repetition across
-    # requests (same voice or shared ref_audio) is a net throughput win.
-    # Disable explicitly if memory headroom is tight on a single-GPU deploy.
+    # Omni prefix cache (reuse of talker codec rows on shared prefixes). Off
+    # by default; set true when text repeats across requests (same voice or
+    # shared ref_audio). The talker opts out of hidden-state caching and
+    # defers codes.audio writes, so per-step cost is small. Stage 1 (codec
+    # decoder) is not a supported prefix-cache stage: keep it false there.
+    # See docs/design/feature/prefix_caching.md for the stage matrix.
     enable_prefix_caching: false
     async_scheduling: true
     max_num_batched_tokens: 32768
diff --git a/vllm_omni/platforms/npu/worker/npu_ar_model_runner.py b/vllm_omni/platforms/npu/worker/npu_ar_model_runner.py
index f78b777a564..18353971c20 100644
--- a/vllm_omni/platforms/npu/worker/npu_ar_model_runner.py
+++ b/vllm_omni/platforms/npu/worker/npu_ar_model_runner.py
@@ -107,6 +107,9 @@ class ExecuteModelState(NamedTuple):
     cudagraph_stats: CUDAGraphStat | None
     batch_desc: BatchDescriptor
     multimodal_outputs: Any # Omni-Specific
+    # Omni: prefix-cache step id; its context must be consumed exactly
+    # once (materialize or discard_step) in sample_tokens.
+    prefix_cache_step_id: int | None = None
 
 class NPUARModelRunner(OmniNPUModelRunner, OmniConnectorModelRunnerMixin, DuplexSamplingRunnerMixin):
     """Autoregressive NPU model runner that returns hidden states per request."""
@@ -211,88 +214,6 @@ def _capture_talker_mtp_graphs(self) -> None:
         finally:
             set_cudagraph_capturing_enabled(False)
 
-    def _model_needs_full_prefix_hidden_states(self) -> bool:
-        """See gpu_ar_model_runner._model_needs_full_prefix_hidden_states."""
-        model = getattr(self, "model", None)
-        return bool(getattr(model, "requires_full_prefix_cached_hidden_states", True))
-
-    def _deferred_prefix_cache_mm_keys(self) -> set[str]:
-        """Model-declared multimodal keys whose prefix-cache writes are deferred."""
-        model = getattr(self, "model", None)
-        keys = getattr(model, "deferred_prefix_cache_mm_keys", ())
-        return set(keys or ())
-
-    def _stage_deferred_prefix_cache_mm_outputs(
-        self,
-        *,
-        scheduler_output: SchedulerOutput,
-        multimodal_outputs: Any,
-        query_start_loc_cpu: Any,
-    ) -> None:
-        """See gpu_ar_model_runner._stage_deferred_prefix_cache_mm_outputs."""
-        if self.omni_prefix_cache is None:
-            return
-
-        deferred_mm_cache_keys = self._deferred_prefix_cache_mm_keys()
-        if not deferred_mm_cache_keys:
-            return
-
-        self.omni_prefix_cache.stage_deferred_mm_outputs(
-            query_start_loc=query_start_loc_cpu,
-            input_batch=self.input_batch,
-            multimodal_outputs=flatten_payload(multimodal_outputs) if multimodal_outputs else multimodal_outputs,
-            num_scheduled_tokens=scheduler_output.num_scheduled_tokens,
-            deferred_mm_cache_keys=deferred_mm_cache_keys,
-        )
-
-    def _maybe_update_prefix_cache(
-        self,
-        hidden_states: torch.Tensor,
-        multimodal_outputs: dict,
-        num_tokens_unpadded: int,
-        num_tokens_padded: int,
-    ):
-        if self.omni_prefix_cache is not None and get_pp_group().is_last_rank:
-            hs_for_cache = hidden_states if self._model_needs_full_prefix_hidden_states() else None
-            slot_mapping_gpu = self.input_batch.block_table[0].slot_mapping.gpu
-            slot_mapping_cpu = slot_mapping_gpu[:num_tokens_padded].cpu()
-            self.omni_prefix_cache.update_omni_tensor_prefix_cache(
-                hidden_states=hs_for_cache,
-                multimodal_outputs=flatten_payload(multimodal_outputs) if multimodal_outputs else multimodal_outputs,
-                num_tokens_unpadded=num_tokens_unpadded,
-                slot_mapping=slot_mapping_cpu,
-                num_tokens_padded=num_tokens_padded,
-                skip_mm_cache_keys=self._deferred_prefix_cache_mm_keys(),
-            )
-
-    def _maybe_get_combined_prefix_cache_tensors(
-        self,
-        hidden_states: torch.Tensor,
-        multimodal_outputs: dict,
-        num_scheduled_tokens: dict[str, int],
-    ) -> tuple[dict[str, torch.Tensor] | None, dict | None]:
-        combined_hidden_states, combined_multimodal_outputs = None, None
-        if self.omni_prefix_cache is not None:
-            if (
-                not self._model_needs_full_prefix_hidden_states()
-                and not self.omni_prefix_cache.has_prefix_cached_new_req_ids()
-            ):
-                return None, None
-            if self._model_needs_full_prefix_hidden_states():
-                combined_hidden_states = self.omni_prefix_cache.get_merged_hidden_states(
-                    query_start_loc=self.query_start_loc.cpu,
-                    input_batch=self.input_batch,
-                    hidden_states=hidden_states,
-                    num_scheduled_tokens=num_scheduled_tokens,
-                )
-            combined_multimodal_outputs = self.omni_prefix_cache.get_merged_multimodal_states(
-                query_start_loc=self.query_start_loc.cpu,
-                input_batch=self.input_batch,
-                multimodal_outputs=flatten_payload(multimodal_outputs) if multimodal_outputs else multimodal_outputs,
-                num_scheduled_tokens=num_scheduled_tokens,
-            )
-        return combined_hidden_states, combined_multimodal_outputs
-
     @staticmethod
     def _resolve_req_hidden_states(
         hidden_states_cpu: torch.Tensor,
@@ -452,11 +373,8 @@ def execute_model(
                 if flush_ids:
                     self.flush_full_payload_outputs(flush_ids)
 
-        if self.omni_prefix_cache is not None and scheduler_output.finished_req_ids:
-            self.omni_prefix_cache.commit_deferred_mm_outputs(
-                set(scheduler_output.finished_req_ids),
-                self.input_batch,
-            )
+        # Exactly once per real scheduler_output, before _update_states.
+        self._prefix_cache_step_begin(scheduler_output)
 
         #  -------------------------------------- Omni-new -------------------------------------------------
         if self.speculative_config is not None and self.speculative_config.use_ngram_gpu():
@@ -782,9 +700,9 @@ def execute_model(
                 hidden_states, aux_hidden_states = hidden_states
 
             #  -------------------------------------- Omni-new -------------------------------------------------
-            self._maybe_update_prefix_cache(
-                hidden_states=hidden_states,
-                multimodal_outputs=multimodal_outputs,
+            prefix_cache_step_id = self._prefix_cache_save_step(
+                hidden_states,
+                multimodal_outputs,
                 num_tokens_unpadded=num_tokens_unpadded,
                 num_tokens_padded=num_tokens_padded,
             )
@@ -864,6 +782,7 @@ def execute_model(
                 cudagraph_stats,
                 batch_desc,
                 multimodal_outputs, # Omni-specific
+                prefix_cache_step_id,
             )
             self.kv_connector_output = kv_connector_output
 
@@ -956,6 +875,7 @@ def sample_tokens(
             cudagraph_stats,
             batch_desc,
             multimodal_outputs, # Omni-Specific
+            prefix_cache_step_id,
         ) = self.execute_model_state
         # Clear ephemeral state.
         self.execute_model_state = None
@@ -1106,9 +1026,15 @@ def propose_draft_token_ids(sampled_token_ids):
         hidden_states_cpu = None
         req_hidden_states_cpu: dict[str, torch.Tensor] | None = None
         audio_sparse_output = engine_output_type == "audio" and sparse_mm_req_ids is not None
+        _omni_cache_on = self.omni_prefix_cache is not None
         needs_scheduled_hidden_payload = needs_pooler_payload and (
-            self.omni_prefix_cache is None or not self._model_needs_full_prefix_hidden_states()
+            not _omni_cache_on or not self._model_needs_full_prefix_hidden_states()
         )
+        if not needs_pooler_payload and prefix_cache_step_id is not None:
+            # No consumer for this step's merge: consume the step context by
+            # id (exactly-once contract). The cache write still lands.
+            self.omni_prefix_cache.discard_step(prefix_cache_step_id)
+            prefix_cache_step_id = None
         if needs_scheduled_hidden_payload:
             num_valid_tokens = min(
                 int(scheduler_output.total_num_scheduled_tokens),
@@ -1131,27 +1057,17 @@ def propose_draft_token_ids(sampled_token_ids):
         if callable(query_start_loc_cpu):
             query_start_loc_cpu = query_start_loc_cpu()
 
-        self._stage_deferred_prefix_cache_mm_outputs(
-            scheduler_output=scheduler_output,
-            multimodal_outputs=multimodal_outputs,
-            query_start_loc_cpu=query_start_loc_cpu,
-        )
-
         pooler_output: list[dict[str, object]] | None = None
         if needs_pooler_payload:
             combined_hidden_states = None
             combined_multimodal_outputs = None
             mm_cpu = None
-            if self.omni_prefix_cache is not None:
+            if _omni_cache_on:
                 (
                     combined_hidden_states,
                     combined_multimodal_outputs,
-                ) = self._maybe_get_combined_prefix_cache_tensors(
-                    hidden_states,
-                    multimodal_outputs,
-                    scheduler_output.num_scheduled_tokens,
-                )
-            if self.omni_prefix_cache is None or combined_multimodal_outputs is None:
+                ) = self._prefix_cache_materialize(prefix_cache_step_id, list(req_ids_output_copy))
+            if not _omni_cache_on or combined_multimodal_outputs is None:
                 mm_cpu = build_mm_cpu(
                     flatten_payload(multimodal_outputs) if multimodal_outputs else multimodal_outputs
                 )
diff --git a/vllm_omni/platforms/npu/worker/npu_generation_model_runner.py b/vllm_omni/platforms/npu/worker/npu_generation_model_runner.py
index 59dfc88a3bb..d796dec8efe 100644
--- a/vllm_omni/platforms/npu/worker/npu_generation_model_runner.py
+++ b/vllm_omni/platforms/npu/worker/npu_generation_model_runner.py
@@ -459,6 +459,7 @@ def sample_tokens(
             cudagraph_stats,
             _batch_desc,
             multimodal_outputs_raw,  # Omni-Specific
+            _prefix_cache_step_id,  # generation stages never save to the prefix cache
         ) = self.execute_model_state
         # Clear ephemeral state.
         self.execute_model_state = None
diff --git a/vllm_omni/platforms/npu/worker/npu_model_runner.py b/vllm_omni/platforms/npu/worker/npu_model_runner.py
index bd7c7dce40f..d8e352d48e8 100644
--- a/vllm_omni/platforms/npu/worker/npu_model_runner.py
+++ b/vllm_omni/platforms/npu/worker/npu_model_runner.py
@@ -20,7 +20,7 @@
 from vllm_ascend.utils import enable_sp, lmhead_tp_enable
 from vllm_ascend.worker.model_runner_v1 import SEQ_LEN_WITH_MAX_PA_WORKSPACE
 
-from vllm_omni.core.prefix_cache import OmniTensorPrefixCache
+from vllm_omni.core.prefix_cache import stage_prefix_cache_config
 from vllm_omni.model_executor.models.output_templates import OmniOutput
 from vllm_omni.platforms.npu._310p import is_310p
 from vllm_omni.worker.gpu_model_runner import OmniGPUModelRunner
@@ -36,35 +36,32 @@
 
 class OmniNPUModelRunner(OmniGPUModelRunner, NPUModelRunner):
     def initialize_kv_cache(self, kv_cache_config) -> None:
-        """Create the omni tensor prefix cache.
-
-        The omni prefix cache is used to store the hidden states of the prefix tokens
-        """
+        """Stage the omni prefix-cache config (hidden / mm tensors reused on hits)."""
         NPUModelRunner.initialize_kv_cache(self, kv_cache_config)
-        if self.omni_prefix_cache is None and self.cache_config.enable_prefix_caching:
-            # Read num_blocks back off self.kv_cache_config: vllm-ascend
-            # deepcopies the config it was handed, so the value it stored is the
-            # authoritative one, not our caller's argument.
-            num_blocks = self.kv_cache_config.num_blocks
-            self.omni_prefix_cache = OmniTensorPrefixCache(
-                num_blocks=num_blocks,
-                block_size=self.cache_config.block_size,
-                hidden_size=self.model_config.get_hidden_size(),
-                hs_dtype=self.dtype,
-            )
-            logger.info(
-                "Initialized omni prefix cache on NPU (num_blocks=%d, block_size=%d, hidden_size=%d). "
-                "Hidden-state cache is pinned host memory of roughly %.1f GiB; each per-token "
-                "multimodal output key allocates another tensor of the same block shape.",
-                num_blocks,
-                self.cache_config.block_size,
-                self.model_config.get_hidden_size(),
-                num_blocks
-                * self.cache_config.block_size
-                * self.model_config.get_hidden_size()
-                * self.dtype.itemsize
-                / (1024**3),
+        if getattr(self, "_omni_prefix_cache_cfg", None) is None:
+            # Same gate as the GPU runner (pooling stage, kv_consumer /
+            # kv_both, hybrid kv groups). Read the config back off
+            # self.kv_cache_config: vllm-ascend deepcopies the one it was
+            # handed, so the stored value is the authoritative one.
+            # Controller runs in eager mode on NPU (no CUDA streams:
+            # dispatch() completes the copy+scatter synchronously). Built once
+            # on the first step via the inherited _ensure_omni_prefix_cache.
+            cfg = stage_prefix_cache_config(
+                kv_cache_config=self.kv_cache_config,
+                cache_config=self.cache_config,
+                kv_transfer_config=getattr(self.vllm_config, "kv_transfer_config", None),
+                scheduler_config=self.scheduler_config,
+                model_config=self.model_config,
+                is_pooling_model=self.is_pooling_model,
+                speculative_config=self.speculative_config,
             )
+            if cfg is not None:
+                self._omni_prefix_cache_cfg = cfg
+                logger.info(
+                    "Initialized omni prefix cache on NPU (eager mode, num_blocks=%d, block_size=%d).",
+                    cfg.num_blocks,
+                    cfg.block_size,
+                )
 
     def load_model(self, *args, **kwargs) -> None:
         if is_310p():
@@ -84,6 +81,8 @@ def load_model(self, *args, **kwargs) -> None:
             if callable(candidate):
                 override_fn = candidate
         self._sampled_token_ids_cpu_override = override_fn
+        self._snapshot_prefix_cache_model_policy(model)
+        self._pooler_payload_include_hidden_flag = bool(getattr(model, "omni_pooler_payload_include_hidden", True))
         self._omni_query_start_loc_model_kwarg = bool(getattr(model, "supports_omni_query_start_loc", False))
         self._maybe_enable_output_token_ids_for_model_sampler()
         self._init_talker_mtp()
diff --git a/vllm_omni/worker/gpu_ar_model_runner.py b/vllm_omni/worker/gpu_ar_model_runner.py
index 06fdfa18be7..b918b57f12c 100644
--- a/vllm_omni/worker/gpu_ar_model_runner.py
+++ b/vllm_omni/worker/gpu_ar_model_runner.py
@@ -342,6 +342,9 @@ class ExecuteModelState(NamedTuple):
     multimodal_outputs: Any
     # slot_mappings for attention/drafter (aligned with upstream v1 API)
     slot_mappings: dict[str, torch.Tensor] | list[dict[str, torch.Tensor]] | None = None
+    # OMNI: prefix-cache step id; the step context saved under it must be
+    # consumed exactly once (materialize or discard_step) in sample_tokens.
+    prefix_cache_step_id: int | None = None
 
 
 class GPUARModelRunner(OmniGPUModelRunner, OmniConnectorModelRunnerMixin, DuplexSamplingRunnerMixin):
@@ -565,7 +568,14 @@ def shutdown(self) -> None:
         CUDAGraphWrapper.clear_all_graphs()
         BreakableCUDAGraphWrapper.clear_all_graphs()
 
-        # 6. Delegate to upstream shutdown (model = None, KV caches, workspace).
+        # 6. Stop the prefix-cache committer before the CUDA context and the
+        # tensors it copies from are torn down.
+        cache = self.omni_prefix_cache
+        if cache is not None:
+            cache.shutdown()
+            self.omni_prefix_cache = None
+
+        # 7. Delegate to upstream shutdown (model = None, KV caches, workspace).
         super().shutdown()
 
     def _capture_talker_mtp_graphs(self) -> None:
@@ -625,18 +635,6 @@ def _capture_talker_mtp_graphs(self) -> None:
         finally:
             set_cudagraph_capturing_enabled(False)
 
-    def _model_needs_full_prefix_hidden_states(self) -> bool:
-        """Opt-out hook for models whose postprocess only consumes the tail.
-
-        When False, we skip both the per-step GPU->CPU hidden-state write into
-        OmniTensorPrefixCache and the merged-tensor reconstruction on hits;
-        postprocess receives the normal scheduled-token slice instead. Models
-        that need the full cached_prefix + new_tail span (default) are not
-        affected.
-        """
-        model = getattr(self, "model", None)
-        return bool(getattr(model, "requires_full_prefix_cached_hidden_states", True))
-
     def _get_runner_assisted_full_attention_metadata_request(
         self,
         *,
@@ -724,132 +722,34 @@ def _set_runner_assisted_full_attention_metadata_context(
         )
         return True
 
-    def _deferred_prefix_cache_mm_keys(self) -> set[str]:
-        """Model-declared multimodal keys whose prefix-cache writes are deferred."""
-        model = getattr(self, "model", None)
-        keys = getattr(model, "deferred_prefix_cache_mm_keys", ())
-        return set(keys or ())
-
-    def _maybe_update_prefix_cache(
-        self,
-        hidden_states: torch.Tensor,
-        hidden_states_cpu: torch.Tensor | None,
-        multimodal_outputs: dict,
-        num_tokens_unpadded: int,
-        num_tokens_padded: int,
-    ):
-        """If prefix caching is enabled and it's the last pipeline parallelism rank,
-        retrieve the hidden states & multimodal outputs from the prefix cache based
-        on our batch slot mappings.
-        """
-        # Cache hidden states if we've enabled hidden state prefix caching
-        # unless this isn't the last pipeline parallelism rank.
-        is_last_pp_rank = get_pp_group().is_last_rank
-        if hidden_states_cpu is not None and not is_last_pp_rank:
-            raise RuntimeError("hidden_states_cpu staging is only valid on the last pipeline parallel rank.")
-        if self.omni_prefix_cache is not None and is_last_pp_rank:
-            # If this happens, it generally means the model is not following the correct
-            # interface yet and is therefore currently not compatible with prefix cache.
-            hs_for_cache = hidden_states if self._model_needs_full_prefix_hidden_states() else None
-            # FIX: The .cpu attribute of slot_mapping is stale (not updated by the Triton
-            # _compute_slot_mapping_kernel which only writes to .gpu). We must use .gpu and
-            # sync back to CPU to get the correctly computed slot mapping.
-            slot_mapping_gpu = self.input_batch.block_table[0].slot_mapping.gpu
-            slot_mapping_cpu = slot_mapping_gpu[:num_tokens_padded].cpu()
-            self.omni_prefix_cache.update_omni_tensor_prefix_cache(
-                hidden_states=hs_for_cache,
-                multimodal_outputs=flatten_payload(multimodal_outputs) if multimodal_outputs else multimodal_outputs,
-                num_tokens_unpadded=num_tokens_unpadded,
-                slot_mapping=slot_mapping_cpu,
-                num_tokens_padded=num_tokens_padded,
-                skip_mm_cache_keys=self._deferred_prefix_cache_mm_keys(),
-                hidden_states_cpu=hidden_states_cpu,
-            )
-
-    def _maybe_get_combined_prefix_cache_tensors(
-        self,
-        hidden_states: torch.Tensor,
-        hidden_states_cpu: torch.Tensor | None,
-        multimodal_outputs: dict,
-        num_scheduled_tokens: dict[str, int],
-    ) -> tuple[dict[str, torch.Tensor] | None, dict | None]:
-        """If prefix caching is enabled, extract the merged hidden states and multimodal outputs for
-        all requests in the batch (including those that aren't a hit on Prefix cache).
-        """
-        # Prior to applying the post-processing func, extract
-        # the prefix cached hidden states and multimodal states.
-        combined_hidden_states, combined_multimodal_outputs = None, None
-        is_last_pp_rank = get_pp_group().is_last_rank
-        if hidden_states_cpu is not None and not is_last_pp_rank:
-            raise RuntimeError("hidden_states_cpu staging is only valid on the last pipeline parallel rank.")
-        if self.omni_prefix_cache is not None:
-            if not is_last_pp_rank:
-                raise RuntimeError("Omni prefix-cache tensor merge is only valid on the last pipeline parallel rank.")
-            if (
-                not self._model_needs_full_prefix_hidden_states()
-                and not self.omni_prefix_cache.has_prefix_cached_new_req_ids()
-            ):
-                return None, None
-            if self._model_needs_full_prefix_hidden_states():
-                combined_hidden_states = self.omni_prefix_cache.get_merged_hidden_states(
-                    query_start_loc=self.query_start_loc.cpu,
-                    input_batch=self.input_batch,
-                    hidden_states=hidden_states,
-                    hidden_states_cpu=hidden_states_cpu,
-                    num_scheduled_tokens=num_scheduled_tokens,
-                )
-            combined_multimodal_outputs = self.omni_prefix_cache.get_merged_multimodal_states(
-                query_start_loc=self.query_start_loc.cpu,
-                input_batch=self.input_batch,
-                multimodal_outputs=flatten_payload(multimodal_outputs) if multimodal_outputs else multimodal_outputs,
-                num_scheduled_tokens=num_scheduled_tokens,
-            )
-        return combined_hidden_states, combined_multimodal_outputs
-
-    def _stage_deferred_prefix_cache_mm_outputs(
-        self,
-        *,
-        scheduler_output: SchedulerOutput,
-        multimodal_outputs: Any,
-        query_start_loc_cpu: Any,
-    ) -> None:
-        if self.omni_prefix_cache is None:
-            return
-
-        deferred_mm_cache_keys = self._deferred_prefix_cache_mm_keys()
-        if not deferred_mm_cache_keys:
-            return
-
-        self.omni_prefix_cache.stage_deferred_mm_outputs(
-            query_start_loc=query_start_loc_cpu,
-            input_batch=self.input_batch,
-            multimodal_outputs=flatten_payload(multimodal_outputs) if multimodal_outputs else multimodal_outputs,
-            num_scheduled_tokens=scheduler_output.num_scheduled_tokens,
-            deferred_mm_cache_keys=deferred_mm_cache_keys,
-        )
-
     def _prepare_prefix_cache_pooler_payload_sources(
         self,
         *,
-        hidden_states: torch.Tensor,
         staged_hidden_states_cpu: torch.Tensor | None,
-        multimodal_outputs: Any,
-        scheduler_output: SchedulerOutput,
         needs_scheduled_hidden_payload: bool,
+        req_ids: list[str],
+        step_id: int | None,
     ) -> tuple[torch.Tensor | None, dict[str, torch.Tensor] | None, dict | None]:
+        """Prefix-cache payload sources for the pooler payload build.
+
+        req_ids must be the step's snapshot, not ``input_batch.req_ids``: under
+        async omni output this runs a step late, when the live batch has moved on.
+        """
+        if not get_pp_group().is_last_rank:
+            raise RuntimeError("Omni prefix-cache merge is only valid on the last pipeline parallel rank.")
         hidden_states_cpu = None
         if needs_scheduled_hidden_payload:
             if staged_hidden_states_cpu is None:
                 raise RuntimeError("Prefix-cache hidden-state payload requires staged CPU hidden states.")
             hidden_states_cpu = staged_hidden_states_cpu
-
-        combined_hidden_states, combined_multimodal_outputs = self._maybe_get_combined_prefix_cache_tensors(
-            hidden_states,
-            staged_hidden_states_cpu,
-            multimodal_outputs,
-            scheduler_output.num_scheduled_tokens,
-        )
-        return hidden_states_cpu, combined_hidden_states, combined_multimodal_outputs
+        if step_id is None:
+            # save_outputs did not run this step (no last-rank AR output), so
+            # there is no step context to consume; serve the fresh slice.
+            if hidden_states_cpu is None and staged_hidden_states_cpu is not None:
+                hidden_states_cpu = staged_hidden_states_cpu
+            return hidden_states_cpu, None, None
+        combined_hidden, combined_mm = self._prefix_cache_materialize(step_id, list(req_ids))
+        return hidden_states_cpu, combined_hidden, combined_mm
 
     def _build_omni_pooler_payload(
         self,
@@ -956,15 +856,9 @@ def execute_model(
             if hasattr(self.model, "_clear_warmup_state"):
                 self.model._clear_warmup_state()
 
-        # Async-write pipeline: apply any pending GPU->CPU prefix-cache writes
-        # whose copy event has already fired. Non-blocking — entries whose D2H
-        # is still in flight stay queued and will be picked up on the next
-        # step's drain. This guarantees any downstream read of
-        # ``omni_prefix_cache.hidden_states_cache`` /
-        # ``omni_prefix_cache.mm_outputs_cache`` in this step sees the
-        # state produced no later than the previous forward step.
-        if self.omni_prefix_cache is not None:
-            self.omni_prefix_cache.drain_ready_async_writes()
+        # Exactly once per real scheduler_output, before _update_states
+        # (dummy/warmup runs never reach execute_model).
+        self._prefix_cache_step_begin(scheduler_output)
 
         # [Omni] Handle KV transfer BEFORE updating states (which removes finished requests)
         finished_reqs = getattr(scheduler_output, "finished_requests_needing_kv_transfer", {})
@@ -988,12 +882,6 @@ def execute_model(
                 if flush_ids:
                     self.flush_full_payload_outputs(flush_ids)
 
-        if self.omni_prefix_cache is not None and scheduler_output.finished_req_ids:
-            self.omni_prefix_cache.commit_deferred_mm_outputs(
-                set(scheduler_output.finished_req_ids),
-                self.input_batch,
-            )
-
         if self.routed_experts_initialized:
             capturer = self.routed_experts_capturer
             if capturer is not None and hasattr(capturer, "finalize_pending_copy"):
@@ -1294,30 +1182,22 @@ def execute_model(
             else:
                 hidden_states, multimodal_outputs = self.extract_multimodal_outputs(model_output)
             hidden_states_cpu = None
-
-            # Async-write pipeline (replaces the per-step blocking
-            # ``.to("cpu")`` + ``aten::index_put_`` on pageable host memory).
-            # Schedules non-blocking GPU->CPU copies on a dedicated stream;
-            # the actual CPU scatter into ``hidden_states_cache`` /
-            # ``mm_outputs_cache`` happens in ``drain_ready_async_writes``
-            # at the top of subsequent execute_model() calls.
-            if not self.is_pooling_model and self.omni_prefix_cache is not None and get_pp_group().is_last_rank:
-                hs_for_cache = hidden_states if self._model_needs_full_prefix_hidden_states() else None
-                # Some models (e.g. qwen3-tts-talker) opt out of full-hidden-state
-                # prefix caching but the downstream pooler payload path still
-                # needs a CPU hidden-states view. Materialize it synchronously
-                # in that case; the legacy behavior is preserved.
-                if hs_for_cache is None and self._model_omni_pooler_payload_include_hidden():
-                    hidden_states_cpu = hidden_states[:num_tokens_unpadded].detach().to("cpu").contiguous()
-                slot_mapping_gpu = self.input_batch.block_table[0].slot_mapping.gpu
-                self.omni_prefix_cache.schedule_async_write(
-                    hidden_states_gpu=hs_for_cache,
-                    multimodal_outputs_gpu=(flatten_payload(multimodal_outputs) if multimodal_outputs else None),
-                    slot_mapping_gpu=slot_mapping_gpu,
-                    num_tokens_unpadded=num_tokens_unpadded,
-                    num_tokens_padded=num_tokens_padded,
-                    skip_mm_cache_keys=self._deferred_prefix_cache_mm_keys(),
-                )
+            # Prefix-cache write: freeze + submit; policy gating (full
+            # hidden, skip/deferred keys) happens inside the manager.
+            prefix_cache_step_id = self._prefix_cache_save_step(
+                hidden_states,
+                multimodal_outputs,
+                num_tokens_unpadded=num_tokens_unpadded,
+                num_tokens_padded=num_tokens_padded,
+            )
+            if (
+                prefix_cache_step_id is not None
+                and not self._model_needs_full_prefix_hidden_states()
+                and self._model_omni_pooler_payload_include_hidden()
+            ):
+                # Opt-out models keep the scheduled-slice CPU view for the
+                # pooler payload (runner-side bypass, legacy parity).
+                hidden_states_cpu = hidden_states[:num_tokens_unpadded].detach().to("cpu").contiguous()
 
             if not self.broadcast_pp_output:
                 # Common case.
@@ -1391,6 +1271,7 @@ def execute_model(
             cudagraph_stats,
             multimodal_outputs,
             slot_mappings,  # OMNI: pass slot_mappings for drafter
+            prefix_cache_step_id,
         )
         self.kv_connector_output = kv_connector_output
 
@@ -1673,12 +1554,12 @@ def _client_multimodal_output_keys(self) -> tuple[str, ...]:
         return raw
 
     def _model_omni_pooler_payload_include_hidden(self) -> bool:
-        return self._runner_model_omni_flag("omni_pooler_payload_include_hidden", default=True)
+        return self._pooler_payload_include_hidden_flag
 
     def _should_defer_full_payload_d2h(self) -> bool:
         """Keep opted-in full payloads on device until request completion."""
         return (
-            getattr(self, "omni_prefix_cache", None) is None
+            self.omni_prefix_cache is None
             and self._runner_model_omni_flag("omni_payload_at_request_end")
             and self._should_accumulate_full_payload_output()
         )
@@ -1707,8 +1588,6 @@ def _build_omni_step_outputs(
     def _should_use_async_omni_output(self) -> bool:
         if not self.use_async_scheduling:
             return False
-        if self.omni_prefix_cache is not None:
-            return False
         if self.speculative_config is not None:
             return False
 
@@ -1854,6 +1733,7 @@ def _build_omni_model_runner_output_from_snapshot(
         num_scheduled_tokens_np: np.ndarray,
         query_start_loc_cpu: Any,
         postprocess_already_applied: bool = False,
+        prefix_cache_step_id: int | None = None,
     ) -> OmniModelRunnerOutput:
         combined_hidden_states = None
         combined_multimodal_outputs = None
@@ -1877,12 +1757,11 @@ def _build_omni_model_runner_output_from_snapshot(
             and needs_pooler_payload
             and (self.omni_prefix_cache is None or not self._model_needs_full_prefix_hidden_states())
         )
-        self._stage_deferred_prefix_cache_mm_outputs(
-            scheduler_output=scheduler_output,
-            multimodal_outputs=multimodal_outputs,
-            query_start_loc_cpu=query_start_loc_cpu,
-        )
-
+        if not needs_pooler_payload and prefix_cache_step_id is not None:
+            # No consumer for this step's merge: consume the step context by
+            # id (exactly-once contract). The cache write still lands.
+            self.omni_prefix_cache.discard_step(prefix_cache_step_id)
+            prefix_cache_step_id = None
         if self.omni_prefix_cache is None and needs_scheduled_hidden_payload and not audio_sparse_output:
             num_valid_tokens = min(
                 int(scheduler_output.total_num_scheduled_tokens),
@@ -1916,11 +1795,10 @@ def _build_omni_model_runner_output_from_snapshot(
                     combined_hidden_states,
                     combined_multimodal_outputs,
                 ) = self._prepare_prefix_cache_pooler_payload_sources(
-                    hidden_states=hidden_states,
                     staged_hidden_states_cpu=staged_hidden_states_cpu,
-                    multimodal_outputs=multimodal_outputs,
-                    scheduler_output=scheduler_output,
                     needs_scheduled_hidden_payload=needs_scheduled_hidden_payload,
+                    step_id=prefix_cache_step_id,
+                    req_ids=req_ids_output_copy,
                 )
             if combined_multimodal_outputs is None:
                 flat_mm = flatten_payload(multimodal_outputs) if multimodal_outputs else multimodal_outputs
@@ -2060,6 +1938,7 @@ def sample_tokens(
             cudagraph_stats,
             multimodal_outputs,
             slot_mappings,  # OMNI: unpack slot_mappings for drafter
+            prefix_cache_step_id,
         ) = self.execute_model_state
         self.execute_model_state = None
 
@@ -2259,6 +2138,7 @@ def output_builder() -> OmniModelRunnerOutput:
                     num_scheduled_tokens_np=num_scheduled_tokens_np,
                     query_start_loc_cpu=query_start_loc_cpu,
                     postprocess_already_applied=omni_postprocess_already_applied,
+                    prefix_cache_step_id=prefix_cache_step_id,
                 )
 
         if not use_async_omni_output:
diff --git a/vllm_omni/worker/gpu_generation_model_runner.py b/vllm_omni/worker/gpu_generation_model_runner.py
index 4d80d3f8d28..6d780925c74 100644
--- a/vllm_omni/worker/gpu_generation_model_runner.py
+++ b/vllm_omni/worker/gpu_generation_model_runner.py
@@ -407,6 +407,7 @@ def sample_tokens(
             cudagraph_stats,
             multimodal_outputs_raw,
             slot_mappings,  # OMNI: unpack slot_mappings for upstream v1 API compatibility
+            _prefix_cache_step_id,  # generation stages never save to the prefix cache
         ) = self.execute_model_state
         self.execute_model_state = None
 
diff --git a/vllm_omni/worker/gpu_model_runner.py b/vllm_omni/worker/gpu_model_runner.py
index 37d2ac12206..48e9764f933 100644
--- a/vllm_omni/worker/gpu_model_runner.py
+++ b/vllm_omni/worker/gpu_model_runner.py
@@ -33,7 +33,8 @@
 from vllm.v1.worker.gpu_model_runner import GPUModelRunner, PerLayerAttnMetadata
 from vllm.v1.worker.ubatch_utils import maybe_create_ubatch_slices
 
-from vllm_omni.core.prefix_cache import OmniTensorPrefixCache
+from vllm_omni.core.prefix_cache import stage_prefix_cache_config
+from vllm_omni.core.prefix_cache.runner_mixin import PrefixCacheRunnerMixin
 from vllm_omni.data_entry_keys import OmniPayload
 from vllm_omni.engine.serialization import deserialize_additional_information
 from vllm_omni.model_executor.layers.rotary_embedding.mrope import OmniMRotaryEmbedding as MRotaryEmbedding
@@ -79,7 +80,7 @@ def _filter_mrope_kwargs_for_model(model: object, kwargs: dict[str, Any]) -> dic
     return {key: value for key, value in kwargs.items() if key in accepted}
 
 
-class OmniGPUModelRunner(GPUModelRunner):
+class OmniGPUModelRunner(PrefixCacheRunnerMixin, GPUModelRunner):
     intermediate_tensors: IntermediateTensors | None
 
     def __init__(self, *args, **kwargs):
@@ -87,11 +88,16 @@ def __init__(self, *args, **kwargs):
         self.model_intermediate_buffer: dict[str, dict[str, Any]] = {}
         self._omni_num_scheduled_tokens_np: np.ndarray | None = None
         self._omni_last_model_output: object | None = None
-        # The Omni tensor prefix cache will be allocated
-        # when we initialize the metadata builders if enabled
+        # Omni prefix cache (hidden / per-token mm tensors reused on prefix
+        # hits). Built once, on the first real step after load_model: the
+        # config is staged at kv-cache init and cleared after construction.
         self.omni_prefix_cache = None
+        self._omni_prefix_cache_cfg = None
         self._sampled_token_ids_cpu_override = None
         self._omni_query_start_loc_model_kwarg = False
+        # Output-payload constant snapshotted once in load_model; the cache
+        # policy counterpart lives on PrefixCacheRunnerMixin.
+        self._pooler_payload_include_hidden_flag = True
 
     def _to_list(self, sampled_token_ids: torch.Tensor) -> list[list[int]]:
         override_fn = self._sampled_token_ids_cpu_override
@@ -172,15 +178,20 @@ def initialize_metadata_builders(self, kv_cache_config, kernel_block_sizes):
                                 device=sm.device,
                             )
 
-        # Initialize the wrapper for both multimodal output tensors
-        # and for hidden states to be passed between stages
-        if self.cache_config.enable_prefix_caching:
-            self.omni_prefix_cache = OmniTensorPrefixCache(
-                num_blocks=kv_cache_config.num_blocks,
-                block_size=self.cache_config.block_size,
-                hidden_size=self.model_config.get_hidden_size(),
-                hs_dtype=self.dtype,
-            )
+        # Stage the config; the manager is built on the first step once
+        # input_batch exists. The gate (pooling stage, kv_consumer, hybrid
+        # kv groups) is shared with the NPU runner.
+        cfg = stage_prefix_cache_config(
+            kv_cache_config=kv_cache_config,
+            cache_config=self.cache_config,
+            kv_transfer_config=getattr(self.vllm_config, "kv_transfer_config", None),
+            scheduler_config=self.scheduler_config,
+            model_config=self.model_config,
+            is_pooling_model=self.is_pooling_model,
+            speculative_config=self.speculative_config,
+        )
+        if cfg is not None:
+            self._omni_prefix_cache_cfg = cfg
 
     @instrument(span_name="Loading (GPU)")
     def load_model(self, *args, **kwargs) -> None:
@@ -192,6 +203,8 @@ def load_model(self, *args, **kwargs) -> None:
             if callable(candidate):
                 override_fn = candidate
         self._sampled_token_ids_cpu_override = override_fn
+        self._snapshot_prefix_cache_model_policy(model)
+        self._pooler_payload_include_hidden_flag = bool(getattr(model, "omni_pooler_payload_include_hidden", True))
         self._omni_query_start_loc_model_kwarg = bool(getattr(model, "supports_omni_query_start_loc", False))
         self._maybe_enable_output_token_ids_for_model_sampler()
         self._init_talker_mtp()
@@ -515,10 +528,6 @@ def _update_states(self, scheduler_output: "SchedulerOutput") -> Callable | None
         The SamplingMetadata is updated and copied to the GPU if there is a
         new/resumed/paused/finished request in the batch.
         """
-        # Used for prefix cache
-        if self.omni_prefix_cache is not None:
-            self.omni_prefix_cache.reset_prefix_cached_new_req_ids()
-
         # Remove finished requests from the cached states.
         # cleanup_finished_request lives on OmniConnectorModelRunnerMixin and
         # is only safe to call once init_omni_connectors() has finished
@@ -535,8 +544,6 @@ def _update_states(self, scheduler_output: "SchedulerOutput") -> Callable | None
             self.requests.pop(req_id, None)
             self.model_intermediate_buffer.pop(req_id, None)
             self.num_prompt_logprobs.pop(req_id, None)
-            if self.omni_prefix_cache is not None:
-                self.omni_prefix_cache.discard_deferred_mm_outputs(req_id)
             if hasattr(self, "_downstream_payload_cache"):
                 self._downstream_payload_cache.pop(req_id, None)
             if hasattr(self, "_talker_mtp_generators"):
@@ -600,13 +607,6 @@ def _update_states(self, scheduler_output: "SchedulerOutput") -> Callable | None
                 reqs_to_add.append(req_state)
                 continue
 
-            # Since this is the first time the request has been scheduled,
-            # num_computed_tokens > 0 means that we have a hit in prefix
-            # caching; mark it so that we can manage the hidden states
-            # later on as needed.
-            if self.omni_prefix_cache is not None and new_req_data.num_computed_tokens > 0:
-                self.omni_prefix_cache.add_prefix_cached_new_req_id(req_id)
-
             sampling_params = new_req_data.sampling_params
             pooling_params = new_req_data.pooling_params
 

From f90c267ffb61c79e42f0165476909b995caedd83 Mon Sep 17 00:00:00 2001
From: psv666 <150513104+psv666@users.noreply.github.com>
Date: Sat, 19 Sep 2026 21:25:14 +0800
Subject: [PATCH 099/105] [Bugfix] Use monotonic clocks for test server startup
 timeouts (#7628)

Signed-off-by: psv666 <2693925048@qq.com>
Co-authored-by: amy-why-3459 <wuhaiyan17@huawei.com>
---
 tests/helpers/runtime.py                      | 16 ++--
 .../tests/test_runtime_startup_timeout.py     | 90 +++++++++++++++++++
 2 files changed, 100 insertions(+), 6 deletions(-)
 create mode 100644 tests/helpers/tests/test_runtime_startup_timeout.py

diff --git a/tests/helpers/runtime.py b/tests/helpers/runtime.py
index 975a6ddd25b..5c9c8076fc2 100644
--- a/tests/helpers/runtime.py
+++ b/tests/helpers/runtime.py
@@ -38,6 +38,8 @@
 
 logger = init_logger(__name__)
 
+SERVER_STARTUP_TIMEOUT_S = 1200
+
 PromptAudioInput = list[tuple[Any, int]] | tuple[Any, int] | None
 PromptImageInput = list[Any] | Any | None
 PromptVideoInput = list[Any] | Any | None
@@ -246,9 +248,10 @@ def _start_server(self) -> None:
             cwd=_omni_subprocess_cwd(),
         )
 
-        max_wait = 1200
-        start_time = time.time()
-        while time.time() - start_time < max_wait:
+        max_wait = SERVER_STARTUP_TIMEOUT_S
+        # System clock corrections must not shorten or extend startup waits.
+        start_time = time.monotonic()
+        while time.monotonic() - start_time < max_wait:
             ret = self.proc.poll()
             if ret is not None:
                 raise RuntimeError(f"Server processes exited with code {ret} before becoming ready.")
@@ -550,9 +553,10 @@ def _start_server(self) -> None:
             for replica_id in range(self.stage_replica_counts.get(stage_id, 1)):
                 self._launch_stage(stage_id, headless=True, replica_id=replica_id)
 
-        max_wait = 1200
-        start_time = time.time()
-        while time.time() - start_time < max_wait:
+        max_wait = SERVER_STARTUP_TIMEOUT_S
+        # System clock corrections must not shorten or extend startup waits.
+        start_time = time.monotonic()
+        while time.monotonic() - start_time < max_wait:
             self._ensure_stage_processes_alive()
             with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
                 sock.settimeout(1)
diff --git a/tests/helpers/tests/test_runtime_startup_timeout.py b/tests/helpers/tests/test_runtime_startup_timeout.py
new file mode 100644
index 00000000000..0eb6a91bf32
--- /dev/null
+++ b/tests/helpers/tests/test_runtime_startup_timeout.py
@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Startup deadlines must be independent of system clock corrections."""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+from tests.helpers import runtime
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+@pytest.fixture(params=["server", "stage_cli"])
+def startup_server(request, tmp_path, monkeypatch):
+    monkeypatch.setattr(runtime, "cleanup_test_environment", lambda: None)
+    proc = MagicMock(spec=runtime.subprocess.Popen)
+    proc.poll.return_value = None
+    monkeypatch.setattr(runtime.subprocess, "Popen", lambda *args, **kwargs: proc)
+    if request.param == "server":
+        # Exercise the wait-loop clock without reserving or inspecting real ports.
+        monkeypatch.setattr(runtime.OmniServer, "_reserve_port", lambda self: None)
+        monkeypatch.setattr(runtime.OmniServer, "_owns_listening_port", lambda self: True)
+        return runtime.OmniServer("fake-model", [])
+
+    config = tmp_path / "stages.yaml"
+    config.write_text("stages:\n  - stage_id: 0\n  - stage_id: 1\n")
+    server = runtime.OmniServerStageCli("fake-model", str(config), [])
+
+    def launch(stage_id, *, headless, replica_id=0):
+        server.stage_procs[(stage_id, replica_id)] = proc
+
+    monkeypatch.setattr(server, "_launch_stage", launch)
+    return server
+
+
+@pytest.mark.parametrize("wall_clock_jump", [3600, -3600])
+@pytest.mark.parametrize("becomes_ready", [True, False], ids=["ready", "timeout"])
+def test_startup_deadline_ignores_wall_clock_changes(startup_server, monkeypatch, wall_clock_jump, becomes_ready):
+    elapsed = 0.0
+    wall_offset = 0.0
+    first_probe_at = None
+    probes = 0
+
+    def sleep(seconds):
+        nonlocal elapsed
+        elapsed += seconds
+
+    # Replace only this module's clock, leaving pytest's own timing untouched.
+    monkeypatch.setattr(
+        runtime,
+        "time",
+        SimpleNamespace(
+            time=lambda: 1_700_000_000 + elapsed + wall_offset,
+            monotonic=lambda: elapsed,
+            perf_counter=lambda: elapsed,
+            sleep=sleep,
+        ),
+    )
+
+    def connect(address):
+        nonlocal probes, wall_offset, first_probe_at
+        assert address == (startup_server.host, startup_server.port)
+        if first_probe_at is None:
+            first_probe_at = elapsed
+        # Even a backwards clock correction must not extend the deadline.
+        assert elapsed - first_probe_at < runtime.SERVER_STARTUP_TIMEOUT_S, "startup exceeded its elapsed-time budget"
+        probes += 1
+        if probes == 1:
+            wall_offset += wall_clock_jump
+            return 111
+        return 0 if becomes_ready else 111
+
+    sock = MagicMock()
+    sock.__enter__.return_value = sock
+    sock.connect_ex.side_effect = connect
+    monkeypatch.setattr(runtime.socket, "socket", lambda *args, **kwargs: sock)
+
+    if becomes_ready:
+        startup_server._start_server()
+        assert probes == 2
+        assert first_probe_at is not None
+        assert elapsed - first_probe_at == 2
+    else:
+        with pytest.raises(RuntimeError, match=f"failed to start within {runtime.SERVER_STARTUP_TIMEOUT_S} seconds"):
+            startup_server._start_server()
+        assert first_probe_at is not None
+        assert elapsed - first_probe_at == runtime.SERVER_STARTUP_TIMEOUT_S

From 698f7160125d3071b8c0eef69b1b03fa8dfba766 Mon Sep 17 00:00:00 2001
From: TaffyOfficial <2587297563@qq.com>
Date: Sat, 19 Sep 2026 23:37:34 +0800
Subject: [PATCH 100/105] [Refactor] Reject unknown diffusion config fields
 (#5172)

Signed-off-by: TaffyOfficial <2324465096@qq.com>
Signed-off-by: zuiho <2324465096@qq.com>
Signed-off-by: Gao Han <hgaoaf@connect.ust.hk>
Co-authored-by: TaffyOfficial <2324465096@qq.com>
Co-authored-by: Gao Han <hgaoaf@connect.ust.hk>
---
 tests/config/test_omni_config.py              | 254 +++++++++++++-----
 tests/config/test_sleep_mode_deploy.py        |  51 ++++
 .../quantization/test_quantization_fp8.py     |  18 +-
 .../test_diffusion_config_propagation.py      |  19 +-
 .../omni_connectors/test_nixl_connector.py    |   1 +
 .../e2e/features/helpers/verl_omni_server.py  |  17 +-
 tests/engine/test_stage_engine_args.py        |   9 +-
 .../test_async_omni_diffusion_config.py       |  97 ++++++-
 tests/entrypoints/test_omni_sleep_mode.py     | 130 +++------
 vllm_omni/config/config_factory.py            |  25 +-
 vllm_omni/config/omni_config.py               | 231 ++++++++++++++--
 vllm_omni/diffusion/data.py                   | 109 +++++---
 vllm_omni/engine/stage_init_utils.py          |   9 +-
 13 files changed, 716 insertions(+), 254 deletions(-)
 create mode 100644 tests/config/test_sleep_mode_deploy.py

diff --git a/tests/config/test_omni_config.py b/tests/config/test_omni_config.py
index 3d356ad9111..1f6111d64e9 100644
--- a/tests/config/test_omni_config.py
+++ b/tests/config/test_omni_config.py
@@ -4,6 +4,7 @@
 
 from __future__ import annotations
 
+import warnings
 from dataclasses import fields
 from inspect import Parameter, signature
 from multiprocessing.reduction import ForkingPickler
@@ -24,6 +25,7 @@
 
 from tests.helpers.stage_config import get_deploy_config_path
 from vllm_omni.config import omni_config as omni_config_module
+from vllm_omni.config.config_factory import StageConfigFactory
 from vllm_omni.config.omni_config import (
     BaseVllmOmniStageConfig,
     OmniStageCacheConfig,
@@ -150,6 +152,30 @@ def test_nested_stage_override_deep_merges_structured_model_config() -> None:
     assert model_config["policy_server_config"]["action_space"] == "joint_position"
 
 
+def _build_single_diffusion_config(
+    *,
+    cli_overrides: dict | None = None,
+    engine_extras: dict | None = None,
+) -> VllmOmniConfig:
+    pipeline = PipelineConfig(
+        model_type="diffusion-owner-test",
+        stages=(
+            StagePipelineConfig(
+                stage_id=0,
+                model_stage="diffusion",
+                execution_type=StageExecutionType.DIFFUSION,
+                final_output=True,
+            ),
+        ),
+    )
+    deploy_stages = [StageDeployConfig(stage_id=0, engine_extras=engine_extras)] if engine_extras is not None else []
+    return VllmOmniConfig.from_pipeline_config(
+        pipeline,
+        user_deploy_config=DeployConfig(async_chunk=False, stages=deploy_stages),
+        cli_overrides=cli_overrides,
+    )
+
+
 @pytest.mark.parametrize("model_type", sorted(OMNI_PIPELINES))
 def test_vllm_omni_config_from_pipeline_config_matches_merge_pipeline_deploy(model_type: str):
     pipeline = _resolve_pipeline_or_skip(model_type)
@@ -475,7 +501,7 @@ def test_from_pipeline_config_normalizes_nested_parallel_config_aliases(field_na
     assert "data_parallel_master_ip" in stage.parallel_config._omni_explicit_fields
 
 
-def test_from_pipeline_config_accepts_diffusion_only_cli_fields_for_diffusion_stage():
+def test_from_pipeline_config_keeps_global_kv_cache_dtype_outside_diffusion_stage():
     stage = _from_pipeline_key(
         "dreamzero",
         deploy_config_path="dreamzero_tp1_cfg2",
@@ -483,11 +509,57 @@ def test_from_pipeline_config_accepts_diffusion_only_cli_fields_for_diffusion_st
     ).stage_by_id(0)
 
     assert isinstance(stage, VllmOmniDiffusionStageConfig)
-    assert stage.diffusion_config.diffusion_kv_cache_dtype == "fp8"
+    assert stage.diffusion_config.diffusion_kv_cache_dtype is None
 
 
 def test_stage_cli_field_selection_defers_ownership_validation_until_sources_are_merged():
-    assert omni_config_module._stage_cli_overrides(0, {"enable_lora": True}) == {"enable_lora": True}
+    assert omni_config_module._stage_cli_overrides(
+        0,
+        {"enable_lora": True},
+    ) == {"enable_lora": True}
+
+
+@pytest.mark.parametrize(
+    ("cli_overrides", "expected_dtype"),
+    [
+        ({}, torch.float32),
+        ({"dtype": None}, torch.float32),
+        ({"dtype": "float16"}, torch.float16),
+        ({"dtype": "auto"}, torch.bfloat16),
+        ({"stage_0_dtype": "bfloat16"}, torch.bfloat16),
+    ],
+)
+def test_diffusion_deploy_dtype_survives_unset_cli_overrides(cli_overrides, expected_dtype):
+    stage = _build_single_diffusion_config(
+        engine_extras={"dtype": "float32", "cache_backend": "tea_cache"},
+        cli_overrides=cli_overrides,
+    ).stage_by_id(0)
+
+    assert stage.diffusion_config.dtype == expected_dtype
+    assert stage.diffusion_config.cache_backend == "tea_cache"
+
+
+@pytest.mark.parametrize(
+    "coordination_kwargs",
+    [
+        {"omni_master_address": "127.0.0.1", "omni_master_port": 30000},
+        {"omni_dp_size_local": 2, "omni_heartbeat_timeout": 60.0, "omni_lb_policy": "random"},
+    ],
+)
+def test_diffusion_ingress_routes_coordination_fields_away(coordination_kwargs):
+    normalize = omni_config_module.normalize_and_validate_diffusion_engine_ingress_kwargs
+    assert normalize({**coordination_kwargs, "enable_sleep_mode": True}, stage_id=0) == {"enable_sleep_mode": True}
+    with pytest.raises(ValueError, match="omni_master_unknown_field"):
+        normalize({**coordination_kwargs, "omni_master_unknown_field": "unknown"}, stage_id=0)
+
+
+def test_diffusion_ingress_defers_defaults(monkeypatch):
+    monkeypatch.setenv("DIFFUSION_CACHE_BACKEND", "tea_cache")
+
+    assert omni_config_module.normalize_and_validate_diffusion_engine_ingress_kwargs({}, stage_id=0) == {}
+    assert omni_config_module.normalize_and_validate_diffusion_engine_ingress_kwargs(
+        {"dtype": None, "cache_backend": None}, stage_id=0
+    ) == {"dtype": None, "cache_backend": None}
 
 
 @pytest.mark.parametrize(
@@ -1415,18 +1487,19 @@ def test_diffusion_config_from_kwargs_reuses_legacy_normalization(monkeypatch):
     monkeypatch.setenv("DIFFUSION_CACHE_BACKEND", "TEA_CACHE")
     monkeypatch.setattr(current_omni_platform, "is_cuda", lambda: True)
 
-    cfg = omni_config_module._DiffusionConfigProjection.from_kwargs(
-        diffusion_attention_backend="flash_attn",
-        fa_deterministic=True,
-        kv_cache_dtype="fp8",
-        kv_cache_skip_steps="0-1",
-        kv_cache_skip_layers=[2],
-        static_lora_scale=0.25,
-        diffusion_kv_mode="paged_scheduler",
-        diffusion_kv_max_rows_per_request=2,
-        diffusers_load_kwargs=None,
-        diffusers_call_kwargs=None,
-    )
+    with pytest.warns(FutureWarning):
+        cfg = omni_config_module._DiffusionConfigProjection.from_kwargs(
+            diffusion_attention_backend="flash_attn",
+            fa_deterministic=True,
+            kv_cache_dtype="fp8",
+            kv_cache_skip_steps="0-1",
+            kv_cache_skip_layers=[2],
+            static_lora_scale=0.25,
+            diffusion_kv_mode="paged_scheduler",
+            diffusion_kv_max_rows_per_request=2,
+            diffusers_load_kwargs=None,
+            diffusers_call_kwargs=None,
+        )
 
     assert cfg.diffusion_attention_config.default.backend == "flash_attn"
     assert cfg.fa_deterministic is True
@@ -1463,47 +1536,6 @@ def test_diffusion_config_none_values_preserve_dataclass_defaults():
     assert config.enable_sleep_mode is False
 
 
-@pytest.mark.parametrize(
-    ("canonical_key", "alias_key", "canonical_value", "alias_value"),
-    [
-        ("lora_scale", "static_lora_scale", 0.75, 0.25),
-        (
-            "quantization_config",
-            "diffusion_quantization_config",
-            {"method": "canonical"},
-            {"method": "diffusion-alias"},
-        ),
-        (
-            "quantization_config",
-            "quantization",
-            {"method": "canonical"},
-            "legacy-alias",
-        ),
-        ("diffusion_kv_cache_dtype", "kv_cache_dtype", "fp8", "fp16"),
-        ("diffusion_kv_cache_skip_steps", "kv_cache_skip_steps", "0-1", "2-3"),
-        ("diffusion_kv_cache_skip_layers", "kv_cache_skip_layers", "1-2", "3-4"),
-        ("streaming_output", "diffusion_streaming_output", False, True),
-    ],
-)
-def test_diffusion_alias_conflicts_prefer_canonical_key(
-    canonical_key,
-    alias_key,
-    canonical_value,
-    alias_value,
-):
-    from vllm_omni.diffusion.data import normalize_omni_diffusion_kwargs
-
-    normalized = normalize_omni_diffusion_kwargs(
-        {
-            canonical_key: canonical_value,
-            alias_key: alias_value,
-        }
-    )
-
-    assert normalized[canonical_key] == canonical_value
-    assert alias_key not in normalized
-
-
 def test_from_pipeline_config_normalizes_diffusion_config_aliases_from_engine_args(tmp_path, monkeypatch):
     from vllm_omni.platforms import current_omni_platform
 
@@ -1528,10 +1560,11 @@ def test_from_pipeline_config_normalizes_diffusion_config_aliases_from_engine_ar
         )
     )
 
-    stage = _from_pipeline_key(
-        "dreamzero",
-        deploy_config_path=str(deploy_path),
-    ).stage_by_id(0)
+    with pytest.warns(FutureWarning):
+        stage = _from_pipeline_key(
+            "dreamzero",
+            deploy_config_path=str(deploy_path),
+        ).stage_by_id(0)
 
     assert isinstance(stage, VllmOmniDiffusionStageConfig)
     assert stage.diffusion_config.diffusion_attention_config.default.backend == "flash_attn"
@@ -1544,7 +1577,10 @@ def test_from_pipeline_config_normalizes_diffusion_config_aliases_from_engine_ar
     from vllm_omni.engine.stage_init_utils import build_engine_args_dict_from_omni_stage_config
 
     engine_args = build_engine_args_dict_from_omni_stage_config(stage, model=str(tmp_path))
-    od_config = OmniDiffusionConfig.from_kwargs(**engine_args)
+    diffusion_kwargs = omni_config_module.extract_diffusion_stage_config_kwargs(
+        engine_args, stage_id=stage.stage_id, include_engine_adapter_metadata=True
+    )
+    od_config = OmniDiffusionConfig.from_kwargs(**diffusion_kwargs)
     assert od_config.kv_transfer_config.engine_id == "dit-engine-1"
 
 
@@ -1697,10 +1733,8 @@ def test_video_output_transport_survives_stage_override_filtering() -> None:
 
 
 def test_video_output_transport_reaches_default_diffusion_stage() -> None:
-    from vllm_omni.engine.async_omni_engine import AsyncOmniEngine
-
     transport = {"enable_device_postprocess": True}
-    stages = AsyncOmniEngine._create_default_diffusion_stage_cfg(
+    stages = StageConfigFactory.create_default_diffusion(
         {
             "model": "unused",
             "model_class_name": "UnknownPipeline",
@@ -1830,3 +1864,95 @@ def test_diffusion_quantization_origin_survives_projection_and_transport(monkeyp
     restored = ForkingPickler.loads(ForkingPickler.dumps(cfg))
     assert restored.quantization_config_is_auto_detected is not explicit
     assert restored.quantization_config.w4a8_fallback_steps == ([] if explicit else [37])
+
+
+@pytest.mark.parametrize(
+    "factory",
+    [
+        omni_config_module._DiffusionConfigProjection.from_kwargs,
+        pytest.param(
+            lambda **kwargs: __import__(
+                "vllm_omni.diffusion.data",
+                fromlist=["OmniDiffusionConfig"],
+            ).OmniDiffusionConfig.from_kwargs(**kwargs),
+            id="runtime-config",
+        ),
+    ],
+)
+def test_diffusion_config_entrypoints_reject_unknown_none(factory):
+    with pytest.raises((ValueError, ValidationError), match="enable_sleep_mod"):
+        factory(enable_sleep_mod=None)
+
+
+def test_diffusion_config_projection_rejects_unknown_none():
+    with pytest.raises(ValueError, match="enable_sleep_mod"):
+        omni_config_module._DiffusionConfigProjection.from_kwargs(enable_sleep_mod=None)
+
+
+def test_runtime_diffusion_config_rejects_unknown_none():
+    from vllm_omni.diffusion.data import OmniDiffusionConfig
+
+    with pytest.raises(ValueError, match="enable_sleep_mod"):
+        OmniDiffusionConfig.from_kwargs(enable_sleep_mod=None)
+
+
+def test_direct_diffusion_aliases_promote_none_and_reject_real_conflicts(monkeypatch):
+    from vllm_omni.diffusion import data as diffusion_data
+    from vllm_omni.diffusion.data import OmniDiffusionConfig
+
+    monkeypatch.setattr(diffusion_data, "build_quant_config", lambda config: config)
+    with pytest.warns(FutureWarning) as warnings:
+        config = OmniDiffusionConfig.from_kwargs(
+            quantization={"method": "example"},
+            quantization_config=None,
+            kv_cache_dtype="fp8",
+            diffusion_kv_cache_dtype=None,
+            enable_sleep_mode=False,
+            request_batch_max_wait_ms=0.0,
+        )
+
+    warning_messages = [str(warning.message) for warning in warnings]
+    assert any("quantization" in message for message in warning_messages)
+    assert any("kv_cache_dtype" in message for message in warning_messages)
+    assert config.quantization_config == {"method": "example"}
+    assert config.diffusion_kv_cache_dtype == "fp8"
+    assert config.enable_sleep_mode is False
+    assert config.request_batch_max_wait_ms == 0.0
+    with pytest.raises(ValueError, match=r"quantization.*quantization_config"):
+        OmniDiffusionConfig.from_kwargs(quantization="fp8", quantization_config={"method": "example"})
+
+
+def test_structured_diffusion_stage_rejects_unknown_engine_extra():
+    with pytest.raises(ValueError, match=r"stage 0.*enable_sleep_mod"):
+        _build_single_diffusion_config(engine_extras={"enable_sleep_mod": None})
+
+    with pytest.raises(ValueError, match=r"stage 0.*enable_sleep_mod"):
+        _build_single_diffusion_config(cli_overrides={"enable_sleep_mod": None})
+
+    with pytest.raises(ValueError, match=r"stage 0.*enable_sleep_mod"):
+        _build_single_diffusion_config(cli_overrides={"stage_0_enable_sleep_mod": None})
+
+    with pytest.raises(ValueError, match=r"no structured config owner: parallel_config\.unknown_field"):
+        _build_single_diffusion_config(engine_extras={"parallel_config": {"unknown_field": 1}})
+
+
+def test_structured_diffusion_stage_keeps_shared_globals_outside_diffusion():
+    with warnings.catch_warnings(record=True) as caught:
+        stage = _build_single_diffusion_config(
+            cli_overrides={"kv_cache_dtype": "fp8", "seed": 7},
+        ).stage_by_id(0)
+
+    assert stage.diffusion_config.diffusion_kv_cache_dtype is None
+    assert not any(issubclass(warning.category, FutureWarning) for warning in caught)
+
+
+@pytest.mark.parametrize(
+    ("field_name", "config_kwargs"),
+    [
+        ("seed", {"cli_overrides": {"stage_0_seed": None}}),
+        ("kv_cache_dtype", {"engine_extras": {"kv_cache_dtype": "fp8"}}),
+    ],
+)
+def test_structured_diffusion_stage_rejects_explicit_shared_engine_field(field_name, config_kwargs):
+    with pytest.raises(ValueError, match=rf"stage 0.*{field_name}"):
+        _build_single_diffusion_config(**config_kwargs)
diff --git a/tests/config/test_sleep_mode_deploy.py b/tests/config/test_sleep_mode_deploy.py
new file mode 100644
index 00000000000..13040ebd91d
--- /dev/null
+++ b/tests/config/test_sleep_mode_deploy.py
@@ -0,0 +1,51 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Check the sleep/wake E2E topology before loading large BAGEL weights."""
+
+import pytest
+
+from tests.entrypoints.test_omni_sleep_mode import _sleep_deploy_config
+from vllm_omni.config.omni_config import (
+    VllmOmniConfig,
+    VllmOmniDiffusionStageConfig,
+    extract_diffusion_stage_config_kwargs,
+)
+from vllm_omni.config.pipeline_registry import resolve_pipeline_config
+from vllm_omni.config.stage_config import load_deploy_config
+from vllm_omni.diffusion.data import OmniDiffusionConfig
+from vllm_omni.engine.stage_init_utils import build_engine_args_dict_from_omni_stage_config
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu]
+
+
+@pytest.mark.parametrize("diffusion_only,tp_size", [(False, 1), (False, 2), (True, 2)])
+def test_sleep_deploy_resolves_expected_stages(diffusion_only, tp_size):
+    deploy = load_deploy_config(_sleep_deploy_config(diffusion_only=diffusion_only, tp_size=tp_size))
+    pipeline = resolve_pipeline_config(deploy.pipeline or "bagel")
+    config = VllmOmniConfig.from_pipeline_config(pipeline, user_deploy_config=deploy)
+
+    assert len(config.stage_configs) == (1 if diffusion_only else 2)
+    for stage in config.stage_configs:
+        is_diffusion = diffusion_only or stage.stage_id == 1
+        assert isinstance(stage, VllmOmniDiffusionStageConfig) == is_diffusion
+        # Keep BAGEL's batch budget: a single multimodal item needs 8625 tokens.
+        assert stage.scheduler_config.max_num_batched_tokens == 32768
+        assert stage.model_config.enable_sleep_mode is True
+        assert stage.parallel_config.tensor_parallel_size == tp_size
+        assert stage.runtime_config.devices == ",".join(str(stage.stage_id * tp_size + rank) for rank in range(tp_size))
+        if not is_diffusion:
+            assert stage.cache_config.gpu_memory_utilization == 0.8
+        if is_diffusion:
+            engine_args = build_engine_args_dict_from_omni_stage_config(stage, "test-bagel")
+            terminal = OmniDiffusionConfig.from_kwargs(
+                **extract_diffusion_stage_config_kwargs(
+                    engine_args, stage_id=stage.stage_id, include_engine_adapter_metadata=True
+                )
+            )
+            assert terminal.enable_sleep_mode is True
+            assert terminal.parallel_config.tensor_parallel_size == tp_size
+
+    if not diffusion_only:
+        assert config.stage_by_id(1).stage_pipeline_config.input_sources == (0,)
+        assert deploy.stages[1].input_connectors["from_stage_0"] == "shared_memory_connector"
diff --git a/tests/diffusion/quantization/test_quantization_fp8.py b/tests/diffusion/quantization/test_quantization_fp8.py
index 5aa7faaa6da..9f41a6a891f 100644
--- a/tests/diffusion/quantization/test_quantization_fp8.py
+++ b/tests/diffusion/quantization/test_quantization_fp8.py
@@ -414,18 +414,16 @@ def test_quantization_key_maps_to_quantization_config():
 
 
 @hardware_test(res={"cuda": ["L4", "B200"]})
-def test_quantization_config_key_takes_priority():
-    """When both 'quantization' and 'quantization_config' are set,
-    'quantization_config' takes priority."""
+def test_quantization_and_quantization_config_conflict():
+    """Two explicit quantization sources are rejected instead of silently merged."""
     from vllm_omni.diffusion.data import OmniDiffusionConfig
 
-    config = OmniDiffusionConfig.from_kwargs(
-        model="test",
-        quantization="fp8",
-        quantization_config={"method": "fp8", "activation_scheme": "static"},
-    )
-    assert config.quantization_config is not None
-    assert config.quantization_config.activation_scheme == "static"
+    with pytest.raises(ValueError, match=r"quantization.*quantization_config"):
+        OmniDiffusionConfig.from_kwargs(
+            model="test",
+            quantization="fp8",
+            quantization_config={"method": "fp8", "activation_scheme": "static"},
+        )
 
 
 @hardware_test(res={"cuda": ["L4", "B200"]})
diff --git a/tests/diffusion/test_diffusion_config_propagation.py b/tests/diffusion/test_diffusion_config_propagation.py
index 6f37f823dc9..7421dfb7974 100644
--- a/tests/diffusion/test_diffusion_config_propagation.py
+++ b/tests/diffusion/test_diffusion_config_propagation.py
@@ -11,6 +11,7 @@
 import torch
 
 from vllm_omni.config.config_factory import StageConfigFactory
+from vllm_omni.config.omni_config import extract_diffusion_stage_config_kwargs
 from vllm_omni.diffusion.data import (
     DiffusionParallelConfig,
     OmniDiffusionConfig,
@@ -40,7 +41,8 @@ def _roundtrip_diffusion_config(**kwargs) -> OmniDiffusionConfig:
     """
     stages = StageConfigFactory.create_default_diffusion(kwargs)
     engine_args = dict(stages[0]["engine_args"])
-    return OmniDiffusionConfig.from_kwargs(**engine_args)
+    diffusion_kwargs = extract_diffusion_stage_config_kwargs(engine_args, stage_id=0)
+    return OmniDiffusionConfig(**{name: value for name, value in diffusion_kwargs.items() if value is not None})
 
 
 class TestParallelConfigPropagation:
@@ -57,9 +59,7 @@ def test_tp4_devices_and_config(self):
         stages = StageConfigFactory.create_default_diffusion({"parallel_config": pc, "model": "x"})
         assert stages[0]["runtime"]["devices"] == "0,1,2,3"
 
-        # Let __post_init__ reconstruct from dict (real code path)
-        ea = dict(stages[0]["engine_args"])
-        od = OmniDiffusionConfig.from_kwargs(**ea)
+        od = _roundtrip_diffusion_config(parallel_config=pc, model="x")
         assert od.parallel_config.tensor_parallel_size == 4
         assert od.parallel_config.world_size == 4
 
@@ -193,6 +193,17 @@ def test_diffusion_kv_sizing_fields_roundtrip(self, monkeypatch):
         assert od.max_num_batched_tokens == 2048
         assert od.max_model_len == 4096
 
+    @pytest.mark.parametrize(
+        ("field_name", "value"),
+        [
+            ("enable_sleep_mod", None),
+            ("enable_lora", True),
+        ],
+    )
+    def test_unowned_raw_field_is_rejected(self, field_name, value):
+        with pytest.raises(ValueError, match=field_name):
+            StageConfigFactory.create_default_diffusion({"model": "x", field_name: value})
+
 
 def test_qwen_image_edit_plus_sets_generic_multimodal_limit():
     od_config = OmniDiffusionConfig(model="Qwen/Qwen-Image-Edit-2511", model_class_name="QwenImageEditPlusPipeline")
diff --git a/tests/distributed/omni_connectors/test_nixl_connector.py b/tests/distributed/omni_connectors/test_nixl_connector.py
index 5b2161eeeaf..ba333580d16 100644
--- a/tests/distributed/omni_connectors/test_nixl_connector.py
+++ b/tests/distributed/omni_connectors/test_nixl_connector.py
@@ -317,6 +317,7 @@ def transfer(pairs):
 
 
 @pytest.mark.parametrize("case", ["empty", "all_empty", "mixed", "scalar", "structured_empty", "structured_mixed"])
+@pytest.mark.usefixtures("reliable_claim_queries")
 def test_zero_byte_leaves_roundtrip_without_native_descriptors(producer, consumer, copying_native_agent, case):
     empty = torch.empty((2, 0, 3), dtype=torch.float64)
     other = torch.empty((0,), dtype=torch.int64)
diff --git a/tests/e2e/features/helpers/verl_omni_server.py b/tests/e2e/features/helpers/verl_omni_server.py
index a38a3a12e80..9d9815a1ece 100644
--- a/tests/e2e/features/helpers/verl_omni_server.py
+++ b/tests/e2e/features/helpers/verl_omni_server.py
@@ -10,11 +10,9 @@
 
 from __future__ import annotations
 
-import argparse
 import json
 import logging
 import os
-from dataclasses import asdict
 from enum import Enum
 from typing import Any
 
@@ -22,14 +20,13 @@
 from omegaconf import DictConfig, OmegaConf
 from pydantic import BaseModel, ConfigDict
 from vllm.entrypoints.openai.api_server import build_app
-from vllm.utils.argparse_utils import FlexibleArgumentParser
 
 import vllm_omni.entrypoints.cli.serve
-from vllm_omni.engine.arg_utils import OmniEngineArgs
 from vllm_omni.entrypoints.async_omni import AsyncOmni
 from vllm_omni.entrypoints.openai.api_server import omni_init_app_state
 from vllm_omni.inputs.data import OmniCustomPrompt, OmniDiffusionSamplingParams
 from vllm_omni.outputs import OmniRequestOutput
+from vllm_omni.utils.tracking_parser import TrackingArgumentParser, TrackingNamespace
 
 logger = logging.getLogger(__name__)
 
@@ -183,7 +180,6 @@ async def launch_server(self) -> None:
             "tensor_parallel_size": _cfg_get(self.config, "tensor_model_parallel_size", 1),
             "seed": self.replica_rank + int(_cfg_get(self.config, "seed", 0) or 0),
             "override_generation_config": json.dumps({}),
-            "scheduling_policy": _cfg_get(self.config, "scheduling_policy", "fcfs"),
             "compilation_config": compilation_config,
             **engine_kwargs,
         }
@@ -191,7 +187,7 @@ async def launch_server(self) -> None:
         model_path = str(_cfg_get(self.model_config, "local_path", None) or _cfg_get(self.model_config, "path"))
         server_args_list = ["serve", model_path] + build_cli_args_from_config(args)
 
-        parser = FlexibleArgumentParser(description="vLLM-Omni CLI")
+        parser = TrackingArgumentParser(description="vLLM-Omni CLI")
         subparsers = parser.add_subparsers(required=False, dest="subparser")
         cmds: dict[str, Any] = {}
         for cmd in vllm_omni.entrypoints.cli.serve.cmd_init():
@@ -204,11 +200,10 @@ async def launch_server(self) -> None:
 
         await self.run_server(parsed)
 
-    async def run_server(self, args: argparse.Namespace) -> None:
-        engine_args = OmniEngineArgs.from_cli_args(args)
-        engine_args = asdict(engine_args)
-
-        engine_args["enable_dummy_pipeline"] = True
+    async def run_server(self, args: TrackingNamespace) -> None:
+        # Match the production entrypoint: parser defaults are not user overrides.
+        engine_args = args.get_explicit_kwargs_dict()
+        engine_args["model"] = args.model
         engine_args["custom_pipeline_args"] = {"pipeline_class": CUSTOM_PIPELINE_CLASS}
 
         engine_client = AsyncOmni(**engine_args)
diff --git a/tests/engine/test_stage_engine_args.py b/tests/engine/test_stage_engine_args.py
index 6650c8e45cb..6d28280e0bf 100644
--- a/tests/engine/test_stage_engine_args.py
+++ b/tests/engine/test_stage_engine_args.py
@@ -29,6 +29,7 @@
     OmniStageSchedulerConfig,
     VllmOmniARStageConfig,
     VllmOmniConfig,
+    extract_diffusion_stage_config_kwargs,
 )
 from vllm_omni.config.pipeline_registry import OMNI_PIPELINES, resolve_pipeline_config
 from vllm_omni.config.stage_config import (
@@ -567,7 +568,9 @@ def test_engine_args_consume_stage_diffusion_attention_shorthand(tmp_path):
         assert engine_args.get("diffusion_attention_backend") is None
         assert isinstance(engine_args["diffusion_attention_config"], AttentionConfig)
         assert engine_args["diffusion_attention_config"].default.backend == "TORCH_SDPA"
-        od_config = OmniDiffusionConfig.from_kwargs(**engine_args)
+        od_config = OmniDiffusionConfig.from_kwargs(
+            **extract_diffusion_stage_config_kwargs(engine_args, stage_id=2, include_engine_adapter_metadata=True)
+        )
         assert od_config.diffusion_attention_config.default.backend == "TORCH_SDPA"
 
 
@@ -600,7 +603,9 @@ def test_engine_args_apply_cli_attention_shorthand_over_yaml_config(tmp_path, ya
         attention_config = engine_args["diffusion_attention_config"]
         assert attention_config.default.backend == "TORCH_SDPA"
         assert attention_config.per_role["cross"].backend == "SAGE_ATTN"
-        od_config = OmniDiffusionConfig.from_kwargs(**engine_args)
+        od_config = OmniDiffusionConfig.from_kwargs(
+            **extract_diffusion_stage_config_kwargs(engine_args, stage_id=2, include_engine_adapter_metadata=True)
+        )
         assert od_config.diffusion_attention_config.default.backend == "TORCH_SDPA"
 
 
diff --git a/tests/entrypoints/test_async_omni_diffusion_config.py b/tests/entrypoints/test_async_omni_diffusion_config.py
index 9b99af71233..ed886d02637 100644
--- a/tests/entrypoints/test_async_omni_diffusion_config.py
+++ b/tests/entrypoints/test_async_omni_diffusion_config.py
@@ -9,7 +9,7 @@
 from pydantic import ValidationError
 
 from vllm_omni.config.config_factory import StageConfigFactory
-from vllm_omni.config.omni_config import VllmOmniDiffusionStageConfig
+from vllm_omni.config.omni_config import VllmOmniDiffusionStageConfig, extract_diffusion_stage_config_kwargs
 from vllm_omni.config.resolver import OmniConfigResolution, resolve_omni_config
 from vllm_omni.diffusion.data import AttentionConfig, OmniDiffusionConfig
 from vllm_omni.engine import stage_init_utils
@@ -21,7 +21,8 @@
 
 
 def _terminal_config(stage_cfg: dict) -> OmniDiffusionConfig:
-    return OmniDiffusionConfig.from_kwargs(**stage_cfg["engine_args"])
+    kwargs = extract_diffusion_stage_config_kwargs(stage_cfg["engine_args"], stage_id=stage_cfg["stage_id"])
+    return OmniDiffusionConfig.from_kwargs(**kwargs)
 
 
 def test_default_stage_config_includes_cache_backend():
@@ -32,6 +33,9 @@ def test_default_stage_config_includes_cache_backend():
             "cache_config": '{"Fn_compute_blocks": 2}',
             "vae_use_slicing": True,
             "ulysses_degree": 2,
+            "seed": 7,
+            "kv_cache_dtype": "fp8",
+            "diffusion_kv_cache_dtype": "fp8_e4m3",
         }
     )[0]
 
@@ -42,6 +46,9 @@ def test_default_stage_config_includes_cache_backend():
     assert engine_args["vae_use_slicing"] is True
     assert engine_args["parallel_config"]["ulysses_degree"] == 2
     assert engine_args["model_stage"] == "diffusion"
+    assert "seed" not in engine_args
+    assert "kv_cache_dtype" not in engine_args
+    assert engine_args["diffusion_kv_cache_dtype"] == "fp8_e4m3"
 
 
 def test_default_stage_config_preserves_ulysses_a2a_permute() -> None:
@@ -130,6 +137,67 @@ def test_default_stage_rejects_unknown_nested_parallel_config_key():
         )
 
 
+def test_default_stage_routes_ar_profiler_away_before_diffusion_build(mocker):
+    stage_dict = StageConfigFactory.create_default_diffusion({"enable_ar_profiler": True})[0]
+    assert "enable_ar_profiler" not in stage_dict["engine_args"]
+
+
+@pytest.mark.parametrize(
+    ("field_name", "value"),
+    [
+        ("enable_sleep_mod", None),
+        ("enable_lora", True),
+        ("kv_cache_dtype", "fp8"),
+        ("seed", 7),
+    ],
+)
+def test_legacy_diffusion_stage_rejects_unowned_field(field_name, value):
+    from vllm_omni.config.config_factory import StageConfigFactory
+    from vllm_omni.config.yaml_util import create_config
+    from vllm_omni.engine.stage_init_utils import build_diffusion_config
+
+    stage_dict = StageConfigFactory.create_default_diffusion({"model": "unused"})[0]
+    stage_dict["engine_args"][field_name] = value
+    stage_cfg = create_config(stage_dict)
+    metadata = SimpleNamespace(stage_id=0, cfg_kv_collect_func=None)
+
+    with pytest.raises(ValueError, match=rf"stage 0.*{field_name}"):
+        build_diffusion_config("unused", stage_cfg, metadata)
+
+
+@pytest.mark.parametrize(
+    ("field_name", "value"),
+    [
+        ("enable_sleep_mod", None),
+        ("enable_lora", True),
+    ],
+)
+def test_default_diffusion_factory_rejects_unowned_field(field_name, value):
+    with pytest.raises(ValueError, match=rf"stage 0.*{field_name}"):
+        StageConfigFactory.create_default_diffusion({field_name: value})
+
+
+def test_legacy_default_stage_build_accepts_engine_adapter_metadata(monkeypatch):
+    from vllm_omni.config.config_factory import StageConfigFactory
+    from vllm_omni.config.yaml_util import create_config
+    from vllm_omni.engine import stage_init_utils
+
+    stage_dict = StageConfigFactory.create_default_diffusion(
+        {
+            "model": "unused",
+            "api_key": "frontend-owned",
+        }
+    )[0]
+    assert "api_key" not in stage_dict["engine_args"]
+    stage_cfg = create_config(stage_dict)
+    metadata = SimpleNamespace(stage_id=0, cfg_kv_collect_func=None)
+    monkeypatch.setattr(stage_init_utils.current_omni_platform, "get_device_count", lambda: 1)
+
+    config = stage_init_utils.build_diffusion_config("unused", stage_cfg, metadata)
+
+    assert config.model == "unused"
+
+
 def test_default_cache_config_used_when_missing():
     """Ensure default cache_config is synthesized when only backend is given."""
     stage_cfg = StageConfigFactory.create_default_diffusion(
@@ -671,10 +739,11 @@ def test_serve_cli_rejects_invalid_request_batch_max_wait_ms(bad_wait: str):
         )
 
 
-def test_serve_cli_accepts_additional_config():
+@pytest.mark.parametrize("subcommand_dest", ["command", "subparser"])
+def test_serve_cli_accepts_additional_config(subcommand_dest):
     """Ensure diffusion serve CLI exposes additional_config and forwards it to stage config."""
     parser = TrackingArgumentParser()
-    subparsers = parser.add_subparsers(dest="command")
+    subparsers = parser.add_subparsers(dest=subcommand_dest)
     OmniServeCommand().subparser_init(subparsers)
 
     args = parser.parse_args(
@@ -687,7 +756,7 @@ def test_serve_cli_accepts_additional_config():
         ]
     )
 
-    stage_cfg = StageConfigFactory.create_default_diffusion(vars(args))[0]
+    stage_cfg = StageConfigFactory.create_default_diffusion(args.get_explicit_kwargs_dict())[0]
 
     engine_args = stage_cfg["engine_args"]
 
@@ -757,6 +826,24 @@ def test_default_stage_config_includes_quantization_config():
     assert stage_cfg["engine_args"]["quantization_config"] == quantization_config
 
 
+@pytest.mark.parametrize("typed", [False, True], ids=["legacy", "typed"])
+def test_default_diffusion_factory_preserves_engine_quantization(typed, monkeypatch):
+    monkeypatch.setattr(OmniDiffusionConfig, "_resolve_master_port", lambda _self: 29500)
+    monkeypatch.setattr(OmniDiffusionConfig, "enrich_config", lambda _self: None)
+    kwargs = {"quantization": "fp8"}
+
+    if typed:
+        stage = StageConfigFactory.create_typed_default_diffusion("generic-diffusion", kwargs).stage_configs[0]
+        config = stage.diffusion_config
+        config.enrich_config()
+    else:
+        config = _terminal_config(StageConfigFactory.create_default_diffusion(kwargs)[0])
+
+    assert config.quantization_config is not None
+    assert config.quantization_config.get_name() == "fp8"
+    assert config.quantization_config_is_auto_detected is False
+
+
 @pytest.mark.parametrize("model_class_name", ["HeliosPipeline", "HunyuanVideo15Pipeline"])
 def test_generic_diffusion_uses_canonical_video_output_type(model_class_name):
     config = StageConfigFactory.create_typed_default_diffusion(
diff --git a/tests/entrypoints/test_omni_sleep_mode.py b/tests/entrypoints/test_omni_sleep_mode.py
index 9567cbc9620..c4900e9cac7 100644
--- a/tests/entrypoints/test_omni_sleep_mode.py
+++ b/tests/entrypoints/test_omni_sleep_mode.py
@@ -18,6 +18,7 @@
 from vllm import SamplingParams
 
 from tests.helpers.mark import hardware_test
+from tests.helpers.stage_config import get_deploy_config_path, modify_stage_config
 from vllm_omni.entrypoints.async_omni import AsyncOmni
 from vllm_omni.inputs.data import OmniDiffusionSamplingParams
 from vllm_omni.platforms import current_omni_platform
@@ -98,16 +99,6 @@ def get_ack_info(ack, key, default=None):
 MODEL_DIFF = "riverclouds/qwen_image_random"
 
 
-def get_dynamic_devices(stage_idx: int, num_stages: int, tp_size: int) -> str:
-    total_gpus = torch.accelerator.device_count()
-    gpus_per_stage = tp_size
-    start_idx = stage_idx * gpus_per_stage
-    if start_idx + gpus_per_stage > total_gpus:
-        start_idx = start_idx % total_gpus
-    device_ids = [str(start_idx + i) for i in range(gpus_per_stage)]
-    return ",".join(device_ids)
-
-
 async def _ensure_awake(engine: AsyncOmni, stage_ids: list[int]) -> None:
     """Best-effort full wake + resume so the next shared-engine test starts active."""
     try:
@@ -120,33 +111,28 @@ async def _ensure_awake(engine: AsyncOmni, stage_ids: list[int]) -> None:
         logger.warning("ensure_resume failed (stage_ids=%s): %s", stage_ids, e)
 
 
-def _build_llm_stages() -> tuple[list[dict], list[dict]]:
-    common_args = {
-        "worker_type": "ar",
-        "enable_sleep_mode": True,
-        "dtype": "bfloat16",
-        "trust_remote_code": True,
-        "max_model_len": 2048,
-        "max_num_batched_tokens": 8192,
-        "enforce_eager": True,
-    }
-    stages = [
-        {
-            "stage_id": 0,
-            "stage_type": "llm",
-            "runtime": {"process": True, "devices": "0", "max_batch_size": 1},
-            "engine_args": {**common_args, "model_stage": "thinker", "gpu_memory_utilization": 0.1},
-        },
-        {
-            "stage_id": 1,
-            "stage_type": "llm",
-            "engine_input_source": [0],
-            "runtime": {"process": True, "devices": "1", "max_batch_size": 1, "connector_type": "queue"},
-            "engine_args": {**common_args, "model_stage": "talker", "gpu_memory_utilization": 0.1},
+def _sleep_deploy_config(*, diffusion_only: bool = False, tp_size: int = 1) -> str:
+    """Use registered BAGEL topology and override only deployment settings."""
+    filename = "bagel_single_stage.yaml" if diffusion_only else "bagel.yaml"
+    stage_ids = (0,) if diffusion_only else (0, 1)
+    return modify_stage_config(
+        get_deploy_config_path(filename),
+        updates={
+            "stages": {
+                stage_id: {
+                    "devices": ",".join(str(stage_id * tp_size + rank) for rank in range(tp_size)),
+                    "tensor_parallel_size": tp_size,
+                    "enable_sleep_mode": True,
+                    "enforce_eager": True,
+                    "dtype": "bfloat16",
+                    # Stages use disjoint GPUs. On an 80 GiB H100, 40% cannot
+                    # fit TP=1 Thinker weights, activation peaks and KV cache.
+                    "gpu_memory_utilization": 0.8 if not diffusion_only and stage_id == 0 else 0.4,
+                }
+                for stage_id in stage_ids
+            }
         },
-    ]
-    connectors = [{"src_stage_id": 0, "dst_stage_id": 1, "connector_type": "queue"}]
-    return stages, connectors
+    )
 
 
 @pytest.fixture(scope="module", autouse=True)
@@ -163,11 +149,10 @@ def _module_device_cleanup():
 
 @pytest_asyncio.fixture(scope="class", loop_scope="class")
 async def llm_engine():
-    """Shared 2-stage BAGEL LLM engine for sleep/wake protocol tests."""
+    """Shared BAGEL Thinker + DiT engine for LLM sleep/wake protocol tests."""
     if current_omni_platform.is_rocm():
         clean_device_envs()
-    stages, connectors = _build_llm_stages()
-    engine = AsyncOmni(model=MODEL, stages=stages, connectors=connectors, init_timeout=600, enable_sleep_mode=True)
+    engine = AsyncOmni(model=MODEL, deploy_config=_sleep_deploy_config(), init_timeout=600, enable_sleep_mode=True)
     yield engine
     engine.shutdown()
     await asyncio.sleep(1.5)
@@ -178,27 +163,12 @@ async def diffusion_engine():
     """Shared BAGEL diffusion TP=2 engine for sleep/wake + generate checks."""
     if current_omni_platform.is_rocm():
         clean_device_envs()
-    stages = [
-        {
-            "stage_id": 0,
-            "stage_type": "diffusion",
-            "runtime": {"process": True, "devices": "0,1", "max_batch_size": 1},
-            "engine_args": {
-                "model_stage": "base",
-                "gpu_memory_utilization": 0.1,
-                "model_class_name": "BagelPipeline",
-                "enable_sleep_mode": True,
-                "enforce_eager": True,
-                "max_num_batched_tokens": 8192,
-                "parallel_config": {
-                    "tensor_parallel_size": 2,
-                },
-            },
-            "final_output": True,
-            "final_output_type": "image",
-        }
-    ]
-    engine = AsyncOmni(model=MODEL, stages=stages, init_timeout=600, enable_sleep_mode=True)
+    engine = AsyncOmni(
+        model=MODEL,
+        deploy_config=_sleep_deploy_config(diffusion_only=True, tp_size=2),
+        init_timeout=600,
+        enable_sleep_mode=True,
+    )
     yield engine
     engine.shutdown()
     await asyncio.sleep(1.5)
@@ -208,7 +178,7 @@ class TestOmniLlmSleepMode:
     """LLM sleep/wake protocol tests sharing one class-scoped engine."""
 
     @pytest.mark.asyncio(loop_scope="class")
-    @hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards=1)
+    @hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards=2)
     async def test_llm_sleep_ack(self, llm_engine: AsyncOmni):
         """LLM Thinker (GPU0) Signal and Physical Recycling Audit"""
         device_id = 0
@@ -333,11 +303,10 @@ class TP=2 BagelPipeline engine rather than a second default-config load).
             # --- integrity: baseline generate at original resolution/steps ---
             prompt = "A huge swimming pool, with many people swimming."
             sp = OmniDiffusionSamplingParams(num_inference_steps=4, height=512, width=512, seed=42)
-            llm_sp = SamplingParams()
 
             logger.info("Running Baseline Generation...")
             base_output = None
-            async for output in diffusion_engine.generate(prompt, request_id="base", sampling_params_list=[llm_sp, sp]):
+            async for output in diffusion_engine.generate(prompt, request_id="base", sampling_params=sp):
                 base_output = output
             assert base_output is not None and len(base_output.images) > 0
             logger.info("Baseline Generation successful.")
@@ -384,7 +353,7 @@ class TP=2 BagelPipeline engine rather than a second default-config load).
             # --- integrity + lifecycle: post-wake generate ---
             logger.info("Running Post-Wakeup Generation...")
             post_output = None
-            async for output in diffusion_engine.generate(prompt, request_id="post", sampling_params_list=[llm_sp, sp]):
+            async for output in diffusion_engine.generate(prompt, request_id="post", sampling_params=sp):
                 post_output = output
             assert post_output is not None
             assert len(base_output.images) == len(post_output.images)
@@ -458,41 +427,22 @@ async def test_coordinated_cross_device(self, llm_engine: AsyncOmni, diffusion_e
 @hardware_test(res={"cuda": "H100", "rocm": "MI325"}, num_cards=2)
 @pytest.mark.asyncio
 async def test_multistage_llm_diffusion_sleep_wake(tp_size: int):
-    """Explicit 2-stage (llm + diffusion) + connectors; sleep/wake both stages."""
+    """Registered BAGEL Thinker + DiT topology; sleep/wake both stages."""
     if current_omni_platform.is_rocm():
         clean_device_envs()
     num_gpus = torch.accelerator.device_count()
     if num_gpus < tp_size * 2:
         pytest.skip("Not enough GPUs")
 
-    stages = []
-    for i in range(2):
-        devs = get_dynamic_devices(i, 2, tp_size)
-        stages.append(
-            {
-                "stage_id": i,
-                "stage_type": "llm" if i == 0 else "diffusion",
-                "runtime": {"process": True, "devices": devs},
-                "engine_args": {
-                    "model": MODEL,
-                    "model_stage": "thinker" if i == 0 else "base",
-                    "tensor_parallel_size": tp_size,
-                    "gpu_memory_utilization": 0.4,
-                    "dtype": "bfloat16",
-                    "enable_sleep_mode": True,
-                    "trust_remote_code": True,
-                },
-            }
-        )
-
-    connectors = [{"src_stage_id": 0, "dst_stage_id": 1, "connector_type": "queue"}]
-
     engine = AsyncOmni(
-        model=MODEL, stages=stages, connectors=connectors, enable_sleep_mode=True, stage_init_timeout=1200
+        model=MODEL,
+        deploy_config=_sleep_deploy_config(tp_size=tp_size),
+        enable_sleep_mode=True,
+        stage_init_timeout=1200,
     )
     try:
         sp = OmniDiffusionSamplingParams(num_inference_steps=2)
-        async for _ in engine.generate("warmup", sampling_params_list=[SamplingParams(), sp]):
+        async for _ in engine.generate("warmup", sampling_params_list=[engine.default_sampling_params_list[0], sp]):
             pass
 
         acks = await engine.sleep(stage_ids=[0, 1], level=1)
@@ -500,7 +450,7 @@ async def test_multistage_llm_diffusion_sleep_wake(tp_size: int):
 
         await engine.wake_up(stage_ids=[0, 1])
         await engine.resume_generation(stage_ids=[0, 1])
-        async for _ in engine.generate("verify", sampling_params_list=[SamplingParams(), sp]):
+        async for _ in engine.generate("verify", sampling_params_list=[engine.default_sampling_params_list[0], sp]):
             pass
     finally:
         engine.shutdown()
diff --git a/vllm_omni/config/config_factory.py b/vllm_omni/config/config_factory.py
index 94decce9a73..af0ea3e817b 100644
--- a/vllm_omni/config/config_factory.py
+++ b/vllm_omni/config/config_factory.py
@@ -7,7 +7,7 @@
 import functools
 import json
 from collections.abc import Mapping
-from dataclasses import asdict, dataclass
+from dataclasses import asdict, dataclass, fields
 from pathlib import Path
 from typing import Any
 
@@ -18,7 +18,10 @@
 from vllm.transformers_utils.runai_utils import ObjectStorageModel, is_runai_obj_uri
 
 from vllm_omni.config.endpoint_policy import EndpointRestriction
-from vllm_omni.config.omni_config import VllmOmniConfig
+from vllm_omni.config.omni_config import (
+    VllmOmniConfig,
+    normalize_and_validate_diffusion_engine_ingress_kwargs,
+)
 from vllm_omni.config.pipeline_registry import OMNI_PIPELINES, resolve_pipeline_config
 from vllm_omni.config.stage_config import (
     _DEPLOY_DIR,
@@ -645,6 +648,14 @@ def _normalize_default_diffusion(
         kwargs: dict[str, Any],
     ) -> tuple[dict[str, Any], DiffusionParallelConfig, dict[str, Any], str]:
         """Normalize inputs shared by typed and compatibility diffusion builders."""
+        # Preserve the default builder's explicit top-level override of model
+        # extras before the strict same-source alias validator runs.
+        if kwargs.get("auxiliary_text_encoder") is not None:
+            kwargs = dict(kwargs)
+            extras = dict(kwargs.get("extras") or {})
+            extras.pop("auxiliary_text_encoder", None)
+            kwargs["extras"] = extras
+        kwargs = normalize_and_validate_diffusion_engine_ingress_kwargs(kwargs, stage_id=0)
         raw_sampling_params = kwargs.get("default_sampling_params")
         if isinstance(raw_sampling_params, str):
             try:
@@ -659,7 +670,15 @@ def _normalize_default_diffusion(
         parallel_config = DiffusionParallelConfig.from_stage_overrides(kwargs)
         if kwargs.get("num_gpus") is not None:
             parallel_config.resolve_data_parallel_size(int(kwargs["num_gpus"]))
-        engine_args = OmniDiffusionConfig.normalize_init_kwargs(kwargs)
+        # Ingress keeps the engine spelling; canonicalize it before filtering
+        # to terminal diffusion fields. Conflicts were validated at ingress.
+        quantization = kwargs.pop("quantization", None)
+        if quantization is not None:
+            kwargs["quantization_config"] = quantization
+        diffusion_config_fields = frozenset(config_field.name for config_field in fields(OmniDiffusionConfig))
+        engine_args = OmniDiffusionConfig.normalize_init_kwargs(
+            {name: value for name, value in kwargs.items() if name in diffusion_config_fields}
+        )
 
         extras = dict(engine_args.get("extras") or {})
         for key, default in (
diff --git a/vllm_omni/config/omni_config.py b/vllm_omni/config/omni_config.py
index f1e5de26a6e..5e51974a299 100644
--- a/vllm_omni/config/omni_config.py
+++ b/vllm_omni/config/omni_config.py
@@ -18,6 +18,7 @@
 from pathlib import Path
 from typing import Any, Literal, TypeAlias, TypedDict, cast
 
+import regex as re
 from pydantic import ConfigDict, Field, field_validator, model_validator
 from typing_extensions import Self
 from vllm.config import CacheConfig as VllmCacheConfig
@@ -74,10 +75,14 @@
     {
         "async_chunk",
         "disable_log_stats",
+        "command",
+        "headless",
         "model",
+        "model_tag",
         "omni",
         "output_modalities",
         "stage_id",
+        "subparser",
         "tokenizer",
     }
 )
@@ -95,6 +100,8 @@
 
 _QuantizationConfigType: TypeAlias = QuantizationConfig | str | Mapping[str, Any] | None
 
+_DIFFUSION_SHARED_ONLY_ENGINE_FIELDS = frozenset({"kv_cache_dtype", "seed"})
+
 
 class _QuantizationEngineOverrides(TypedDict, total=False):
     quantization_config: _QuantizationConfigType
@@ -290,10 +297,6 @@ class _DiffusionEngineOverrides:
 
     _values: dict[str, Any]
 
-    @classmethod
-    def from_engine(cls, engine: Mapping[str, Any]) -> _DiffusionEngineOverrides:
-        return cls(_select_engine_overrides(engine, _DIFFUSION_STAGE_ENGINE_FIELDS))
-
     def to_kwargs(self) -> dict[str, Any]:
         return {name: _copy_value(value) for name, value in self._values.items()}
 
@@ -359,12 +362,32 @@ def _stage_cli_overrides(
     *,
     execution_type: StageExecutionType | None = None,
 ) -> dict[str, Any]:
+    if execution_type == StageExecutionType.DIFFUSION:
+        stage_override_pattern = re.compile(r"^stage_\d+_")
+        stage_scoped = {
+            name: _copy_value(value) for name, value in cli_overrides.items() if stage_override_pattern.match(name)
+        }
+        global_inputs = {name: _copy_value(value) for name, value in cli_overrides.items() if name not in stage_scoped}
+        cli_overrides = {
+            **normalize_and_validate_diffusion_engine_ingress_kwargs(
+                global_inputs,
+                stage_id=stage_id,
+            ),
+            **stage_scoped,
+        }
     runtime_overrides = build_stage_runtime_overrides(stage_id, dict(cli_overrides))
     global_stage_fields = _global_stage_cli_fields()
     owned_fields = None if execution_type is None else _STAGE_ENGINE_FIELDS_BY_EXECUTION_TYPE[execution_type]
     result: dict[str, Any] = {}
     for key, value in runtime_overrides.items():
-        stage_specific = f"stage_{stage_id}_{key}" in cli_overrides
+        stage_key = f"stage_{stage_id}_{key}"
+        stage_specific = stage_key in cli_overrides
+        if (
+            execution_type == StageExecutionType.DIFFUSION
+            and key in _DIFFUSION_SHARED_ONLY_ENGINE_FIELDS
+            and not stage_specific
+        ):
+            continue
         if stage_specific or (key in global_stage_fields and (owned_fields is None or key in owned_fields)):
             result[key] = _copy_value(value)
 
@@ -372,6 +395,19 @@ def _stage_cli_overrides(
     # argument. Keep global and stage-scoped CLI values off AR/generation stages.
     if execution_type is not None and execution_type is not StageExecutionType.DIFFUSION:
         result.pop("step_execution", None)
+    if execution_type == StageExecutionType.DIFFUSION:
+        prefix = f"stage_{stage_id}_"
+        for key, value in cli_overrides.items():
+            if key.startswith(prefix):
+                field_name = key.removeprefix(prefix)
+                if field_name in {"model", "model_arch", "stage_id"}:
+                    raise ValueError(f"Diffusion stage {stage_id} cannot override identity field {field_name!r}.")
+                if field_name in _DIFFUSION_SHARED_ONLY_ENGINE_FIELDS:
+                    raise ValueError(
+                        f"Diffusion stage {stage_id} cannot override shared engine field {field_name!r}; "
+                        "it has no diffusion stage-config consumer."
+                    )
+                result.setdefault(field_name, _copy_value(value))
     return result
 
 
@@ -387,6 +423,10 @@ def _validate_global_stage_cli_ownership(
         field for stage in pipeline.stages for field in _STAGE_ENGINE_FIELDS_BY_EXECUTION_TYPE[stage.execution_type]
     }
     unowned_fields = explicit_global_fields - owned_fields
+    if any(stage.execution_type == StageExecutionType.DIFFUSION for stage in pipeline.stages):
+        # Mixed engine ingress accepts these shared globals, but diffusion
+        # stages deliberately leave them outside their terminal config.
+        unowned_fields -= _DIFFUSION_SHARED_ONLY_ENGINE_FIELDS
     if unowned_fields:
         names = ", ".join(sorted(unowned_fields))
         raise ValueError(
@@ -736,7 +776,7 @@ def __post_init__(self) -> None:
             self.world_size = other_parallel_world_size
 
 
-@config(config=ConfigDict(arbitrary_types_allowed=True))
+@config(config=ConfigDict(arbitrary_types_allowed=True, extra="forbid"))
 class _DiffusionConfigProjection:
     """Diffusion-specific per-stage settings.
 
@@ -852,15 +892,19 @@ def _normalize_kv_transfer_config(cls, value: Any) -> Any:
 
     @classmethod
     def from_kwargs(cls, **kwargs: Any) -> _DiffusionConfigProjection:
-        from vllm_omni.diffusion.data import normalize_omni_diffusion_kwargs
+        from vllm_omni.diffusion.data import (
+            normalize_omni_diffusion_kwargs,
+            validate_omni_diffusion_kwargs,
+        )
         from vllm_omni.diffusion.offloader.config import parse_diffusion_offload_config
 
-        config_kwargs = normalize_omni_diffusion_kwargs(kwargs)
+        valid_fields = frozenset(f.name for f in fields(cast(Any, cls)))
+        normalized = normalize_omni_diffusion_kwargs(kwargs)
+        validate_omni_diffusion_kwargs(normalized, valid_fields)
         # Validate before stage construction while retaining the raw mapping
         # needed by dataclass/config serialization across process boundaries.
-        parse_diffusion_offload_config(config_kwargs.get("diffusion_offload_config"))
-        valid_fields = {f.name for f in fields(cast(Any, cls))}
-        return cls(**{k: v for k, v in config_kwargs.items() if k in valid_fields})
+        parse_diffusion_offload_config(normalized.get("diffusion_offload_config"))
+        return cls(**{name: value for name, value in normalized.items() if value is not None})
 
     def __post_init__(self) -> None:
         # Keep diffusion imports lazy so importing vllm_omni.config does not
@@ -1095,20 +1139,7 @@ def enrich_config(self) -> None:
 
 _STAGE_DEPLOY_ENGINE_FIELDS: tuple[str, ...] = tuple(_STAGE_DEPLOY_FIELDS)
 
-_DIFFUSION_BACKCOMPAT_ENGINE_FIELDS = frozenset(
-    {
-        "diffusion_attention_backend",
-        "fastvideo_vsa_topk",
-        "kv_cache_dtype",
-        "kv_cache_skip_layers",
-        "kv_cache_skip_steps",
-        "static_lora_scale",
-    }
-)
-_DIFFUSION_STAGE_ENGINE_FIELDS = (_DIFFUSION_CONFIG_FIELDS | _DIFFUSION_BACKCOMPAT_ENGINE_FIELDS) - {
-    "model",
-    "stage_id",
-}
+_DIFFUSION_STAGE_ENGINE_FIELDS = _DIFFUSION_CONFIG_FIELDS - {"model", "stage_id"}
 
 
 def _upstream_engine_field_map(
@@ -1248,6 +1279,8 @@ def _validate_stage_engine_override_ownership(
     stage_id: int,
     execution_type: StageExecutionType,
     overrides: Mapping[str, Any],
+    *,
+    validate_top_level: bool = True,
 ) -> None:
     try:
         owner_fields = _STAGE_ENGINE_FIELDS_BY_EXECUTION_TYPE[execution_type]
@@ -1256,7 +1289,7 @@ def _validate_stage_engine_override_ownership(
     except KeyError as exc:
         raise ValueError(f"Unsupported stage execution type: {execution_type!r}") from exc
 
-    unowned_fields = set(overrides) - owner_fields
+    unowned_fields = set(overrides) - owner_fields if validate_top_level else set()
     parallel_config = overrides.get("parallel_config")
     if isinstance(parallel_config, Mapping):
         # Nested values traditionally use upstream config names, while flat
@@ -1273,6 +1306,144 @@ def _validate_stage_engine_override_ownership(
         )
 
 
+_DIFFUSION_STAGE_METADATA_FIELDS = frozenset(
+    {
+        "async_chunk",
+        "custom_process_next_stage_input_func",
+        "engine_output_type",
+        "has_sampling_extra_args",
+        "hf_config_name",
+        "model_arch",
+        "model_stage",
+        "retains_state_across_chunks",
+        "scheduler_cls",
+        "stage_connector_spec",
+        "worker_type",
+    }
+)
+
+_DIFFUSION_ENGINE_ADAPTER_METADATA_FIELDS = frozenset(
+    {
+        # Serialized shared model settings are consumed outside the terminal
+        # diffusion config; accepting them here does not widen raw ingress.
+        "duplex_max_sessions",
+        "has_sampling_extra_args",
+        "inline_diffusion",
+        "requires_full_payload_input",
+        "sampling_extra_args_keys",
+        "session_mode",
+    }
+)
+_DIFFUSION_DEFAULT_FACTORY_FIELDS = frozenset(
+    {"default_llama_model_id", "default_sampling_params", "devices", "stage_0_devices"}
+)
+
+
+def _frontend_cli_fields() -> frozenset[str]:
+    """Return vLLM server fields that are consumed before stage startup."""
+    from vllm.entrypoints.launchers.cli_args import FrontendArgs
+
+    return frozenset(config_field.name for config_field in fields(FrontendArgs))
+
+
+def normalize_and_validate_diffusion_engine_ingress_kwargs(
+    kwargs: Mapping[str, Any],
+    *,
+    stage_id: int | str,
+) -> dict[str, Any]:
+    """Normalize and validate raw diffusion input without inserting defaults."""
+    from vllm_omni.diffusion.data import (
+        OmniDiffusionConfig,
+        normalize_omni_diffusion_kwargs,
+        validate_omni_diffusion_kwargs,
+    )
+    from vllm_omni.engine.arg_utils import orchestrator_field_names
+
+    mixed_kwargs = {name: _copy_value(value) for name, value in kwargs.items()}
+    engine_owned = {
+        name: mixed_kwargs.pop(name)
+        for name in _DIFFUSION_SHARED_ONLY_ENGINE_FIELDS | {"quantization"}
+        if name in mixed_kwargs
+    }
+    normalized = normalize_omni_diffusion_kwargs(mixed_kwargs, apply_defaults=False)
+    if engine_owned.get("quantization") is not None and normalized.get("quantization_config") is not None:
+        raise ValueError("Diffusion config fields 'quantization' and 'quantization_config' cannot both be provided.")
+    normalized.update(engine_owned)
+
+    diffusion_fields = frozenset(config_field.name for config_field in fields(OmniDiffusionConfig))
+    stage_consumed_fields = (
+        diffusion_fields
+        | _DIFFUSION_OWNED_STAGE_ENGINE_FIELDS
+        | frozenset(_STAGE_DEPLOY_ENGINE_FIELDS)
+        | frozenset(_PIPELINE_DEPLOY_CLI_FIELDS)
+        | _DIFFUSION_STAGE_METADATA_FIELDS
+        | _DIFFUSION_DEFAULT_FACTORY_FIELDS
+    ) - _DIFFUSION_SHARED_ONLY_ENGINE_FIELDS
+    externally_consumed_fields = (
+        _DIFFUSION_SHARED_ONLY_ENGINE_FIELDS
+        | _NON_STAGE_ENGINE_CLI_FIELDS
+        | _frontend_cli_fields()
+        | orchestrator_field_names()
+        # Coordination fields also live on the typed orchestrator config, not
+        # all of them are present on the CLI-only OrchestratorArgs dataclass.
+        | frozenset(config_field.name for config_field in fields(VllmOmniOrchestratorConfig))
+    )
+    allowed_fields = stage_consumed_fields | externally_consumed_fields
+    validate_omni_diffusion_kwargs(normalized, allowed_fields, stage_id=stage_id)
+    return {name: value for name, value in normalized.items() if name in stage_consumed_fields}
+
+
+def extract_diffusion_stage_config_kwargs(
+    kwargs: Mapping[str, Any],
+    *,
+    stage_id: int | str,
+    include_engine_adapter_metadata: bool = False,
+) -> dict[str, Any]:
+    """Take the diffusion-owned payload from resolved mixed stage arguments."""
+    from vllm_omni.diffusion.data import (
+        OmniDiffusionConfig,
+        normalize_omni_diffusion_kwargs,
+        validate_omni_diffusion_kwargs,
+    )
+
+    shared_only_fields = sorted(_DIFFUSION_SHARED_ONLY_ENGINE_FIELDS.intersection(kwargs))
+    if shared_only_fields:
+        field_names = ", ".join(repr(name) for name in shared_only_fields)
+        raise ValueError(
+            f"Diffusion stage {stage_id} cannot consume shared engine field(s) {field_names}; "
+            "use diffusion-owned fields or request sampling parameters instead."
+        )
+
+    diffusion_fields = frozenset(config_field.name for config_field in fields(OmniDiffusionConfig))
+    fields_owned_elsewhere = (
+        frozenset(_STAGE_DEPLOY_ENGINE_FIELDS)
+        | frozenset(_PIPELINE_DEPLOY_CLI_FIELDS)
+        | _DIFFUSION_OWNED_STAGE_ENGINE_FIELDS
+        | _DIFFUSION_STAGE_METADATA_FIELDS
+    )
+    if include_engine_adapter_metadata:
+        fields_owned_elsewhere |= _DIFFUSION_ENGINE_ADAPTER_METADATA_FIELDS
+
+    # ``quantization`` is canonical in the mixed engine namespace. Hand it to
+    # the compatibility adapter without treating it as a deprecated alias.
+    mixed_kwargs = {name: _copy_value(value) for name, value in kwargs.items()}
+    engine_quantization = mixed_kwargs.pop("quantization", None)
+    normalized = normalize_omni_diffusion_kwargs(mixed_kwargs)
+    if engine_quantization is not None:
+        if normalized.get("quantization_config") is not None:
+            raise ValueError(
+                "Diffusion config fields 'quantization' and 'quantization_config' cannot both be provided."
+            )
+        normalized["quantization_config"] = engine_quantization
+
+    validate_omni_diffusion_kwargs(
+        normalized,
+        diffusion_fields | fields_owned_elsewhere,
+        stage_id=stage_id,
+    )
+    return {name: _copy_value(value) for name, value in normalized.items() if name in diffusion_fields}
+
+
 def _global_stage_cli_fields() -> frozenset[str]:
     # Lazy import avoids vllm_omni.config -> omni_config -> engine.arg_utils ->
     # vllm_omni.config during package-level config imports.
@@ -1285,6 +1456,7 @@ def _global_stage_cli_fields() -> frozenset[str]:
     )
     externally_consumed = (
         _NON_STAGE_ENGINE_CLI_FIELDS
+        | _frontend_cli_fields()
         | frozenset(f.name for f in fields(cast(Any, VllmOmniOrchestratorConfig)))
         | (orchestrator_field_names() - _STAGE_ENGINE_FIELDS)
     )
@@ -1343,10 +1515,15 @@ def _stage_engine_values(
                 engine[key] = _get_recursively_merged_dict(existing, dict(value))
             else:
                 engine[key] = _copy_value(value)
+    if topology.execution_type == StageExecutionType.DIFFUSION:
+        diffusion_kwargs = extract_diffusion_stage_config_kwargs(engine, stage_id=topology.stage_id)
+    else:
+        diffusion_kwargs = {}
     _validate_stage_engine_override_ownership(
         topology.stage_id,
         topology.execution_type,
         engine,
+        validate_top_level=topology.execution_type != StageExecutionType.DIFFUSION,
     )
     if topology.execution_type in {
         StageExecutionType.LLM_AR,
@@ -1383,7 +1560,7 @@ def _stage_engine_values(
         ),
         runtime=cast(_RuntimeEngineOverrides, _select_engine_overrides(engine, runtime_engine_fields)),
         parallel=cast(_ParallelEngineOverrides, _select_engine_overrides(engine, _PARALLEL_ENGINE_FIELDS)),
-        diffusion=_DiffusionEngineOverrides.from_engine(engine),
+        diffusion=_DiffusionEngineOverrides(_select_engine_overrides(diffusion_kwargs, _DIFFUSION_STAGE_ENGINE_FIELDS)),
         compilation_config=_copy_value(engine.get("compilation_config")),
         profiler_config=_copy_value(engine.get("profiler_config")),
     )
diff --git a/vllm_omni/diffusion/data.py b/vllm_omni/diffusion/data.py
index 53714893302..5bc5a229bfd 100644
--- a/vllm_omni/diffusion/data.py
+++ b/vllm_omni/diffusion/data.py
@@ -6,6 +6,7 @@
 import math
 import os
 import random
+import warnings
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass, field, fields
 from enum import Enum
@@ -44,55 +45,63 @@
 logger = init_logger(__name__)
 
 
-def normalize_omni_diffusion_kwargs(raw_kwargs: Mapping[str, Any]) -> dict[str, Any]:
-    """Normalize legacy diffusion kwargs before config construction."""
+def _move_diffusion_alias(
+    normalized: dict[str, Any],
+    legacy_name: str,
+    canonical_name: str,
+) -> None:
+    legacy_value = normalized.pop(legacy_name, None)
+    if legacy_value is None:
+        return
+    if normalized.get(canonical_name) is not None:
+        raise ValueError(f"Diffusion config fields {legacy_name!r} and {canonical_name!r} cannot both be provided.")
+    warnings.warn(
+        f"Diffusion config field {legacy_name!r} is deprecated; use {canonical_name!r}.",
+        FutureWarning,
+        stacklevel=3,
+    )
+    normalized[canonical_name] = legacy_value
+
+
+def normalize_omni_diffusion_kwargs(
+    raw_kwargs: Mapping[str, Any],
+    *,
+    apply_defaults: bool = True,
+) -> dict[str, Any]:
+    """Normalize diffusion kwargs, deferring defaults until sources are merged."""
     config_kwargs = dict(raw_kwargs)
 
     dtype = config_kwargs.get("dtype")
     if dtype is None:
-        config_kwargs["dtype"] = "auto"
+        if apply_defaults:
+            config_kwargs["dtype"] = "auto"
     elif isinstance(dtype, torch.dtype):
         config_kwargs["dtype"] = str(dtype).removeprefix("torch.")
     elif not isinstance(dtype, str):
         raise TypeError(f"Provided dtype must be a string or torch.dtype, got {type(dtype).__name__}")
 
-    # Backwards-compatibility: older callers may use a diffusion-specific
-    # "static_lora_scale" kwarg. Normalize it to the canonical "lora_scale".
-    if "static_lora_scale" in config_kwargs:
-        if "lora_scale" not in config_kwargs:
-            config_kwargs["lora_scale"] = config_kwargs["static_lora_scale"]
-        config_kwargs.pop("static_lora_scale", None)
-
-    diffusion_quantization = config_kwargs.pop("diffusion_quantization_config", None)
-    if config_kwargs.get("quantization_config") is None and diffusion_quantization is not None:
-        config_kwargs["quantization_config"] = diffusion_quantization
-
-    # Backwards-compatibility: map "quantization" to "quantization_config"
-    # so callers using the old field name still work.
-    if "quantization" in config_kwargs and config_kwargs.get("quantization_config", None) is None:
-        config_kwargs["quantization_config"] = config_kwargs.pop("quantization")
-    else:
-        config_kwargs.pop("quantization", None)
-
-    # Renamed from kv_cache_* to avoid clashing with vLLM's --kv-cache-dtype.
-    if config_kwargs.get("diffusion_kv_cache_dtype") is None and "kv_cache_dtype" in config_kwargs:
-        config_kwargs["diffusion_kv_cache_dtype"] = config_kwargs.pop("kv_cache_dtype")
-    else:
-        config_kwargs.pop("kv_cache_dtype", None)
-    if config_kwargs.get("diffusion_kv_cache_skip_steps") is None and "kv_cache_skip_steps" in config_kwargs:
-        config_kwargs["diffusion_kv_cache_skip_steps"] = config_kwargs.pop("kv_cache_skip_steps")
-    else:
-        config_kwargs.pop("kv_cache_skip_steps", None)
-    if config_kwargs.get("diffusion_kv_cache_skip_layers") is None and "kv_cache_skip_layers" in config_kwargs:
-        config_kwargs["diffusion_kv_cache_skip_layers"] = config_kwargs.pop("kv_cache_skip_layers")
-    else:
-        config_kwargs.pop("kv_cache_skip_layers", None)
+    for legacy, canonical in (
+        ("static_lora_scale", "lora_scale"),
+        ("quantization", "quantization_config"),
+        ("diffusion_quantization_config", "quantization_config"),
+        ("max_batch_size", "max_num_seqs"),
+        ("kv_cache_skip_steps", "diffusion_kv_cache_skip_steps"),
+        ("kv_cache_skip_layers", "diffusion_kv_cache_skip_layers"),
+    ):
+        _move_diffusion_alias(config_kwargs, legacy, canonical)
+    _move_diffusion_alias(config_kwargs, "kv_cache_dtype", "diffusion_kv_cache_dtype")
 
     # Handle "diffusion_attention_backend" shorthand: merge into
     # diffusion_attention_config before field filtering.
     diffusion_attn_backend = config_kwargs.pop("diffusion_attention_backend", None)
     fastvideo_vsa_topk = config_kwargs.pop("fastvideo_vsa_topk", None)
     if diffusion_attn_backend is not None or fastvideo_vsa_topk is not None:
+        if diffusion_attn_backend is not None:
+            warnings.warn(
+                "Diffusion config field 'diffusion_attention_backend' is deprecated; use 'diffusion_attention_config'.",
+                FutureWarning,
+                stacklevel=2,
+            )
         existing = config_kwargs.get("diffusion_attention_config")
         config_kwargs["diffusion_attention_config"] = parse_attention_config(
             existing,
@@ -100,12 +109,23 @@ def normalize_omni_diffusion_kwargs(raw_kwargs: Mapping[str, Any]) -> dict[str,
             fastvideo_vsa_topk=fastvideo_vsa_topk,
         )
 
+    auxiliary_text_encoder = config_kwargs.pop("auxiliary_text_encoder", None)
+    if auxiliary_text_encoder is not None:
+        extras = dict(config_kwargs.get("extras") or {})
+        if extras.get("auxiliary_text_encoder") is not None:
+            raise ValueError(
+                "Diffusion engine field 'auxiliary_text_encoder' cannot be provided both at the top level and in "
+                "'extras'."
+            )
+        extras["auxiliary_text_encoder"] = auxiliary_text_encoder
+        config_kwargs["extras"] = extras
+
     # Check environment variable as fallback for cache_backend.
     # Support both old DIFFUSION_CACHE_ADAPTER and new DIFFUSION_CACHE_BACKEND.
-    if "cache_backend" not in config_kwargs:
+    if "cache_backend" not in config_kwargs and apply_defaults:
         cache_backend = os.environ.get("DIFFUSION_CACHE_BACKEND") or os.environ.get("DIFFUSION_CACHE_ADAPTER")
         config_kwargs["cache_backend"] = cache_backend.lower() if cache_backend else "none"
-    elif config_kwargs["cache_backend"] is None:
+    elif "cache_backend" in config_kwargs and config_kwargs["cache_backend"] is None and apply_defaults:
         # Callers (e.g. example CLIs with `default=None`) pass an explicit
         # None for "no cache"; canonicalize it so every consumer sees the
         # declared `str` value instead of relying on per-model None handling.
@@ -162,6 +182,20 @@ def validate_dlo_host_registration_options(
     return value
 
 
+def validate_omni_diffusion_kwargs(
+    kwargs: Mapping[str, Any],
+    allowed_fields: set[str] | frozenset[str],
+    *,
+    stage_id: int | str | None = None,
+) -> None:
+    """Reject every field without an owner."""
+    unknown = set(kwargs) - allowed_fields
+    if unknown:
+        names = ", ".join(repr(name) for name in sorted(unknown))
+        suffix = "" if stage_id is None else f" for stage {stage_id}"
+        raise ValueError(f"Unknown diffusion config field(s){suffix}: {names}")
+
+
 def parse_kv_cache_skip_selector(
     selector: str | list[int] | tuple[int, ...] | set[int] | None,
 ) -> set[int] | None:
@@ -1631,8 +1665,9 @@ def enrich_config(self) -> None:
 
     @classmethod
     def normalize_init_kwargs(cls, raw_kwargs: Mapping[str, Any]) -> dict[str, Any]:
+        valid_fields = frozenset(f.name for f in fields(cls))
         config_kwargs = normalize_omni_diffusion_kwargs(raw_kwargs)
-        valid_fields = {f.name for f in fields(cls)}
+        validate_omni_diffusion_kwargs(config_kwargs, valid_fields)
         # Remaining ``None`` values mean "unset" at the CLI/deploy boundary.
         # Drop them so non-optional dataclass defaults are not overwritten.
         # Fields where ``None`` has normalization semantics (for example dtype
diff --git a/vllm_omni/engine/stage_init_utils.py b/vllm_omni/engine/stage_init_utils.py
index a10cf5861c7..f15e1238ff6 100644
--- a/vllm_omni/engine/stage_init_utils.py
+++ b/vllm_omni/engine/stage_init_utils.py
@@ -1965,13 +1965,20 @@ def build_diffusion_config(
     metadata: StageMetadata,
 ) -> Any:
     """Build diffusion config for a stage."""
+    from vllm_omni.config.omni_config import extract_diffusion_stage_config_kwargs
 
     engine_args_dict = (
         build_engine_args_dict_from_omni_stage_config(stage_cfg, model)
         if isinstance(stage_cfg, BaseVllmOmniStageConfig)
         else build_engine_args_dict(stage_cfg, model)
     )
-    od_config = OmniDiffusionConfig.from_kwargs(**engine_args_dict)
+    stage_id = engine_args_dict.get("stage_id", metadata.stage_id)
+    diffusion_kwargs = extract_diffusion_stage_config_kwargs(
+        engine_args_dict,
+        stage_id=stage_id,
+        include_engine_adapter_metadata=True,
+    )
+    od_config = OmniDiffusionConfig(**{name: value for name, value in diffusion_kwargs.items() if value is not None})
 
     num_devices_per_stage = od_config.parallel_config.world_size
     device_control_env = current_omni_platform.device_control_env_var

From 357101838c3ef0ab9d2c6e040157e69ff76ea855 Mon Sep 17 00:00:00 2001
From: Gao Han <hgaoaf@connect.ust.hk>
Date: Sat, 19 Sep 2026 23:55:41 +0800
Subject: [PATCH 101/105] [Bugfix] Preserve HunyuanImage3 DiT-only offline
 accuracy contract

Only construct AR inputs when the deployment contains an AR stage. Keep
the DiT-only accuracy request on the same string-prompt/bot_task=none path
as online serving, and explicitly enable expert parallelism in the shared
offline CLI so its default cannot override the deploy configuration.

Cover script existence, real CLI parsing and both DiT-only/AR+DiT request
construction. Patch only tokenizer loading in existing tests so model
imports can still access the rest of transformers.

Validation: 80 related unit tests and all applicable pre-commit hooks pass.
The new regressions fail twice against the original PR source as expected.
Both full accuracy cases pass on 4 L20X with a local Triton MoE override:
SSIM 0.987250, PSNR 35.653664 dB, with identical online/offline PNG hashes.
The exact nightly FlashInfer CUTLASS configuration cannot initialize on
L20X; H100/B200/A3 validation remains with CI. No thresholds were changed.

AI assistance: Codex inspected the review, implemented the code and tests,
and ran local validation.

Signed-off-by: Gao Han <hgaoaf@connect.ust.hk>
---
 .../text_to_image/text_to_image.py            |  7 +-
 .../test_hunyuan_image3_pixel_accuracy.py     |  3 +-
 .../test_shared_script_ar_integration.py      | 95 +++++++++++++++++--
 3 files changed, 95 insertions(+), 10 deletions(-)

diff --git a/examples/offline_inference/text_to_image/text_to_image.py b/examples/offline_inference/text_to_image/text_to_image.py
index adcc1066971..67f276e09e9 100644
--- a/examples/offline_inference/text_to_image/text_to_image.py
+++ b/examples/offline_inference/text_to_image/text_to_image.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 import argparse
 import functools
@@ -723,7 +723,10 @@ def main():
     # stop-token-ids declaratively from the plain prompt + extra_body, so this
     # example stays model-agnostic. Models without one are untouched.
     ar_input_builder = get_ar_input_builder(model_class_name)
-    if ar_input_builder is not None:
+    # A model can also be deployed with only its diffusion stage. Keep those
+    # requests on the string-prompt path, as in the single-stage images API.
+    has_ar_stage = any(not isinstance(params, OmniDiffusionSamplingParams) for params in sampling_params_list)
+    if ar_input_builder is not None and has_ar_stage:
         _apply_ar_stage_inputs(
             ar_input_builder,
             model=args.model,
diff --git a/tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py b/tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py
index 795c24302f2..15aa4d7396c 100644
--- a/tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py
+++ b/tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py
@@ -251,11 +251,12 @@ def _run_vllm_omni_hunyuan_image3_offline(*, model: str, deploy_config: str, out
             "--use-system-prompt",
             "en_unified",
             "--extra-body",
-            '{"bot_task": null}',
+            '{"bot_task": "none"}',
             "--trust-remote-code",
             "--model",
             model,
             "--enforce-eager",
+            "--enable-expert-parallel",
         ],
         check=True,
     )
diff --git a/tests/model_extras/test_shared_script_ar_integration.py b/tests/model_extras/test_shared_script_ar_integration.py
index f781ca5fbc4..eb43d97c8f8 100644
--- a/tests/model_extras/test_shared_script_ar_integration.py
+++ b/tests/model_extras/test_shared_script_ar_integration.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 """Integration coverage for the shared task examples' ``_apply_ar_stage_inputs``.
 
 The unit tests in ``test_model_extras.py`` cover ``get_ar_input_builder`` and
@@ -25,6 +25,7 @@
 import sys
 from dataclasses import dataclass
 from pathlib import Path
+from types import SimpleNamespace
 from typing import Any
 
 import pytest
@@ -36,6 +37,90 @@
 _REPO_ROOT = Path(__file__).resolve().parents[2]
 
 
+@pytest.mark.parametrize("with_ar_stage", [False, True])
+def test_text_to_image_only_builds_ar_inputs_for_ar_deployments(monkeypatch, tmp_path, with_ar_stage):
+    from PIL import Image
+    from vllm import SamplingParams
+
+    module = _load_module("_shared_text_to_image_deploy", "examples/offline_inference/text_to_image/text_to_image.py")
+    tokenizer_calls = _patch_tokenizer_loader(monkeypatch, module)
+    monkeypatch.setattr(module, "get_ar_tokenizer_validator", lambda _: None)
+    monkeypatch.setattr(
+        module, "current_omni_platform", SimpleNamespace(device_type="cpu", pre_register_and_update=lambda parser: None)
+    )
+    monkeypatch.setattr(module, "is_nextstep_model", lambda _: False)
+    monkeypatch.setattr(module, "get_model_class_name", lambda _: "HunyuanImage3ForCausalMM")
+    defaults = [OmniDiffusionSamplingParams()]
+    if with_ar_stage:
+        defaults.insert(0, SamplingParams())
+    captured: dict[str, Any] = {}
+
+    def generate(prompt, *, sampling_params_list):
+        captured.update(prompt=prompt, params=sampling_params_list)
+        return [SimpleNamespace(images=[Image.new("RGB", (8, 8))])]
+
+    monkeypatch.setattr(
+        module, "Omni", lambda **kwargs: SimpleNamespace(default_sampling_params_list=defaults, generate=generate)
+    )
+    output = tmp_path / "output.png"
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "text_to_image.py",
+            "--model",
+            "test-hunyuan",
+            "--prompt",
+            "A dog",
+            "--output",
+            str(output),
+            "--extra-body",
+            '{"bot_task": null}' if with_ar_stage else '{"bot_task": "none"}',
+            "--trust-remote-code",
+        ],
+    )
+    module.main()
+
+    assert output.is_file()
+    assert bool(tokenizer_calls) == with_ar_stage
+    assert ("prompt_token_ids" in captured["prompt"]) == with_ar_stage
+    if with_ar_stage:
+        assert captured["params"][0].stop_token_ids
+    else:
+        assert captured["prompt"] == {"prompt": "A dog", "modalities": ["image"]}
+        assert captured["params"][0].extra_args["bot_task"] == "none"
+
+
+def test_hunyuan_accuracy_offline_cli_contract(monkeypatch, tmp_path):
+    import subprocess
+
+    from PIL import Image
+
+    accuracy = _load_module("_hunyuan_accuracy", "tests/e2e/accuracy/test_hunyuan_image3_pixel_accuracy.py")
+    module = _load_module("_hunyuan_accuracy_cli", "examples/offline_inference/text_to_image/text_to_image.py")
+    output = tmp_path / "offline.png"
+
+    def run(argv, *, check):
+        assert check
+        assert Path(argv[1]).is_file()
+        monkeypatch.setattr(sys, "argv", argv[1:])
+        args = module.parse_args()
+        assert args.enable_expert_parallel
+        assert args.extra_body == {"bot_task": "none"}
+        assert args.use_system_prompt == "en_unified"
+        assert args.trust_remote_code
+        assert args.seed == accuracy.SEED
+        assert args.num_inference_steps == accuracy.NUM_INFERENCE_STEPS
+        assert args.output == str(output)
+        Image.new("RGB", (8, 8)).save(args.output)
+
+    monkeypatch.setattr(subprocess, "run", run)
+    image = accuracy._run_vllm_omni_hunyuan_image3_offline(
+        model="test-hunyuan", deploy_config="deploy.yaml", output_path=output
+    )
+    assert image.size == (8, 8)
+
+
 def _load_module(name: str, relpath: str):
     path = _REPO_ROOT / relpath
     spec = importlib.util.spec_from_file_location(name, path)
@@ -75,9 +160,7 @@ def from_pretrained(model: str, trust_remote_code: bool = False) -> _FakeHunyuan
             calls.append({"model": model, "trust_remote_code": trust_remote_code})
             return _FakeHunyuanTokenizer()
 
-    fake_transformers = type(sys)("transformers")
-    fake_transformers.AutoTokenizer = _FakeAutoTokenizer
-    monkeypatch.setitem(sys.modules, "transformers", fake_transformers)
+    monkeypatch.setattr("transformers.AutoTokenizer.from_pretrained", _FakeAutoTokenizer.from_pretrained)
     return calls
 
 
@@ -90,9 +173,7 @@ class _FailingAutoTokenizer:
         def from_pretrained(model: str, trust_remote_code: bool = False) -> Any:
             raise OSError("simulated tokenizer load failure")
 
-    fake_transformers = type(sys)("transformers")
-    fake_transformers.AutoTokenizer = _FailingAutoTokenizer
-    monkeypatch.setitem(sys.modules, "transformers", fake_transformers)
+    monkeypatch.setattr("transformers.AutoTokenizer.from_pretrained", _FailingAutoTokenizer.from_pretrained)
 
 
 @pytest.mark.parametrize(

From a21b939c72c568b21d07eca63fa0434d74f51238 Mon Sep 17 00:00:00 2001
From: Gao Han <hgaoaf@connect.ust.hk>
Date: Sun, 20 Sep 2026 00:09:06 +0800
Subject: [PATCH 102/105] [Bugfix] Drop obsolete mode from shared text-to-image
 config

The latest main rejects unknown diffusion configuration fields. The shared
offline example still supplied mode="text-to-image", which has no consumer
and makes the HunyuanImage3 offline accuracy launch fail before loading.
Remove it and exercise the real ingress validator in the request-building
regression test instead of allowing every mocked Omni keyword silently.

Validation on main 698f71601: 458 CPU tests passed, 2 skipped, 4 deselected;
all applicable pre-commit hooks passed. Four-card L20X/Triton offline
accuracy passed with SSIM 0.987251 and PSNR 35.653656 dB, matching the online
case and its PNG hash. Original accuracy thresholds remain unchanged.

AI assistance: Codex implemented and validated this compatibility fix.

Signed-off-by: Gao Han <hgaoaf@connect.ust.hk>
---
 .../offline_inference/text_to_image/text_to_image.py |  1 -
 .../test_shared_script_ar_integration.py             | 12 +++++++++---
 2 files changed, 9 insertions(+), 4 deletions(-)

diff --git a/examples/offline_inference/text_to_image/text_to_image.py b/examples/offline_inference/text_to_image/text_to_image.py
index 67f276e09e9..b19b7ca0594 100644
--- a/examples/offline_inference/text_to_image/text_to_image.py
+++ b/examples/offline_inference/text_to_image/text_to_image.py
@@ -558,7 +558,6 @@ def main():
         "vae_patch_parallel_size": args.vae_patch_parallel_size,
         "enable_expert_parallel": args.enable_expert_parallel,
         "enable_cpu_offload": args.enable_cpu_offload,
-        "mode": "text-to-image",
         "log_stats": args.log_stats,
         "enable_diffusion_pipeline_profiler": args.enable_diffusion_pipeline_profiler,
         "profiler_config": args.profiler_config,
diff --git a/tests/model_extras/test_shared_script_ar_integration.py b/tests/model_extras/test_shared_script_ar_integration.py
index eb43d97c8f8..4c24134e6a7 100644
--- a/tests/model_extras/test_shared_script_ar_integration.py
+++ b/tests/model_extras/test_shared_script_ar_integration.py
@@ -42,6 +42,8 @@ def test_text_to_image_only_builds_ar_inputs_for_ar_deployments(monkeypatch, tmp
     from PIL import Image
     from vllm import SamplingParams
 
+    from vllm_omni.config.omni_config import normalize_and_validate_diffusion_engine_ingress_kwargs
+
     module = _load_module("_shared_text_to_image_deploy", "examples/offline_inference/text_to_image/text_to_image.py")
     tokenizer_calls = _patch_tokenizer_loader(monkeypatch, module)
     monkeypatch.setattr(module, "get_ar_tokenizer_validator", lambda _: None)
@@ -59,9 +61,13 @@ def generate(prompt, *, sampling_params_list):
         captured.update(prompt=prompt, params=sampling_params_list)
         return [SimpleNamespace(images=[Image.new("RGB", (8, 8))])]
 
-    monkeypatch.setattr(
-        module, "Omni", lambda **kwargs: SimpleNamespace(default_sampling_params_list=defaults, generate=generate)
-    )
+    def create_omni(**kwargs):
+        # Exercise the real ingress validator so stale example-only options
+        # cannot silently pass this test while breaking model initialization.
+        normalize_and_validate_diffusion_engine_ingress_kwargs(kwargs, stage_id=0)
+        return SimpleNamespace(default_sampling_params_list=defaults, generate=generate)
+
+    monkeypatch.setattr(module, "Omni", create_omni)
     output = tmp_path / "output.png"
     monkeypatch.setattr(
         sys,

From 415005be22568f29c02c1e419a786dfebe747954 Mon Sep 17 00:00:00 2001
From: akshatvishu <akshatnayak197@gmail.com>
Date: Sat, 19 Sep 2026 21:46:38 +0530
Subject: [PATCH 103/105] [Model] Add circlestone-labs/Anima (#4083)

Signed-off-by: akshatvishu <akshatnayak197@gmail.com>
---
 docs/features/custom_pipeline.md              |   9 +-
 docs/models/supported_models.md               |   1 +
 .../offline_inference/text_to_image/README.md |  40 +-
 .../text_to_image/text_to_image.py            |  25 +-
 recipes/README.md                             |   1 +
 recipes/circlestone-labs/Anima.md             | 158 ++++
 tests/diffusion/models/anima/__init__.py      |   2 +
 tests/diffusion/models/anima/test_anima.py    | 454 ++++++++++
 tests/diffusion/test_worker_wrapper_base.py   |  28 +
 tests/e2e/offline_inference/test_anima.py     |  63 ++
 tests/e2e/online_serving/test_anima.py        |  77 ++
 tests/entrypoints/test_serve.py               |  46 +-
 tests/entrypoints/test_utils.py               |  64 ++
 tests/helpers/tests/test_check_test_marks.py  |  28 +
 tests/model_tests/conftest.py                 |  11 +-
 tests/model_tests/diffusion/anima_builder.py  | 116 +++
 tests/model_tests/diffusion/config_types.py   |  14 +-
 tests/model_tests/diffusion/model_settings.py |  10 +
 .../diffusion/test_common_offline.py          |  11 +-
 .../diffusion/test_common_online.py           |   6 +
 .../diffusion/test_native_model_settings.py   |  66 ++
 tests/model_tests/diffusion/utils.py          |   9 +-
 tools/pre_commit/check_test_marks.py          |   9 +
 vllm_omni/config/resolver.py                  |  24 +-
 vllm_omni/diffusion/data.py                   |  14 +
 vllm_omni/diffusion/models/anima/__init__.py  |   8 +
 .../models/anima/anima_text_conditioner.py    | 321 +++++++
 .../models/anima/anima_transformer.py         | 705 ++++++++++++++++
 .../diffusion/models/anima/pipeline_anima.py  | 795 ++++++++++++++++++
 vllm_omni/diffusion/registry.py               |  20 +
 .../diffusion/worker/diffusion_worker.py      |  18 +-
 vllm_omni/engine/arg_utils.py                 |   6 +-
 vllm_omni/entrypoints/cli/serve.py            |  14 +-
 33 files changed, 3127 insertions(+), 46 deletions(-)
 create mode 100644 recipes/circlestone-labs/Anima.md
 create mode 100644 tests/diffusion/models/anima/__init__.py
 create mode 100644 tests/diffusion/models/anima/test_anima.py
 create mode 100644 tests/e2e/offline_inference/test_anima.py
 create mode 100644 tests/e2e/online_serving/test_anima.py
 create mode 100644 tests/helpers/tests/test_check_test_marks.py
 create mode 100644 tests/model_tests/diffusion/anima_builder.py
 create mode 100644 tests/model_tests/diffusion/test_native_model_settings.py
 create mode 100644 vllm_omni/diffusion/models/anima/__init__.py
 create mode 100644 vllm_omni/diffusion/models/anima/anima_text_conditioner.py
 create mode 100644 vllm_omni/diffusion/models/anima/anima_transformer.py
 create mode 100644 vllm_omni/diffusion/models/anima/pipeline_anima.py

diff --git a/docs/features/custom_pipeline.md b/docs/features/custom_pipeline.md
index 887dfa76980..463798d6d82 100644
--- a/docs/features/custom_pipeline.md
+++ b/docs/features/custom_pipeline.md
@@ -1,7 +1,7 @@
 # Custom Pipeline Extension Guide
 
 Transformer already support Custom Pipeline via
-https://github.com/huggingface/diffusers/blob/main/docs/source/en/using-diffusers/custom_pipeline_overview.md
+<https://github.com/huggingface/diffusers/blob/main/docs/source/en/using-diffusers/custom_pipeline_overview.md>
 
 This guide demonstrates how to use the newly added features for extending vLLM-Omni's diffusion pipeline with custom functionality.
 
@@ -20,8 +20,9 @@ Three main features enable custom pipeline extension:
 `WorkerWrapperBase` is a wrapper class that creates `DiffusionWorker` instances with optional extension support. It enables dynamic inheritance, allowing you to add custom methods and functionality to workers without modifying the base worker class.
 
 **Key capabilities:**
+
 - Dynamic worker class extension via `worker_extension_cls`
-- Support for custom pipeline initialization via `custom_pipeline_args`
+- Support for custom pipeline initialization via `custom_pipeline_args["pipeline_class"]`
 - Method delegation to underlying worker
 - Attribute access forwarding
 
@@ -42,6 +43,7 @@ The `diffusion_load_format` parameter controls the initial diffusion model load.
 `CustomPipelineWorkerExtension` is a mixin class that extends `DiffusionWorker` with the ability to re-initialize the pipeline with a custom implementation.
 
 **Key method:**
+
 - `re_init_pipeline(custom_pipeline_args)`: Re-initializes the pipeline with custom arguments, properly cleaning up the old pipeline first
 
 **Location:** `vllm_omni/diffusion/worker/diffusion_worker.py`
@@ -150,6 +152,7 @@ omni = Omni(
     },
     worker_extension_cls=MyCustomExtension,
     # Note: worker_extension_cls is an internal parameter
-    # CustomPipelineWorkerExtension will automatically init pipeline when custom_pipeline_args is provided
+    # CustomPipelineWorkerExtension will automatically init pipeline when
+    # custom_pipeline_args includes "pipeline_class".
 )
 ```
diff --git a/docs/models/supported_models.md b/docs/models/supported_models.md
index f481154fb18..ec895f79430 100644
--- a/docs/models/supported_models.md
+++ b/docs/models/supported_models.md
@@ -113,6 +113,7 @@ th {
 | `GepardTalkerForConditionalGeneration` | Gepard-1.0 | `nineninesix/gepard-1.0` | ✅︎ | | | ✅︎ | — |
 | `HiDreamImagePipeline` | HiDream-I1-Full | `HiDream-ai/HiDream-I1-Full` | ✅︎ | ✅︎ | | | — |
 | `HiDreamO1ImagePipeline` | HiDream-O1-Image | `HiDream-ai/HiDream-O1-Image` | ✅︎ | | | | — |
+| `AnimaPipeline` | Anima | `circlestone-labs/Anima` | ✅︎ | ✅︎ | | | [Repository](https://github.com/vllm-project/vllm-omni/blob/main/recipes/circlestone-labs/Anima.md) |
 
 The `Recipe` column links the corresponding deployment recipe. `Published` is
 preferred when a corresponding `recipes.vllm.ai` page exists; otherwise the
diff --git a/examples/offline_inference/text_to_image/README.md b/examples/offline_inference/text_to_image/README.md
index cfe05255db5..7664bb32d2a 100644
--- a/examples/offline_inference/text_to_image/README.md
+++ b/examples/offline_inference/text_to_image/README.md
@@ -19,23 +19,23 @@ This folder provides several entrypoints for experimenting with text-to-image di
 
 ### Supported Models
 
-| Model | Image Shape  | Peak VRAM (GiB) * | Model Weights (GiB) |
+| Model | Image Shape | Peak VRAM (GiB) * | Model Weights (GiB) |
 | ----- | ----------- | ----------- | ----------------- |
 | `Qwen/Qwen-Image` | 1024 x 1024 | 60.0 | 53.7 |
-| `Qwen/Qwen-Image-2512` |1024 x 1024 | 60.0 | 53.7 |
+| `Qwen/Qwen-Image-2512` | 1024 x 1024 | 60.0 | 53.7 |
 | `Tongyi-MAI/Z-Image-Turbo` | 1024 x 1024 | 24.8 | 19.2 |
 | `stepfun-ai/NextStep-1.1` | 512 x 512 | 71.8 | 28.1 |
 | `meituan-longcat/LongCat-Image` | 1024 x 1024 | 71.2 | 27.3 |
 | `AIDC-AI/Ovis-Image-7B` | 1024 x 1024 | 71.8 | 17.1 |
-| `OmniGen2/OmniGen2` |  1024 x 1024 | 20.1 | 14.7 |
+| `OmniGen2/OmniGen2` | 1024 x 1024 | 20.1 | 14.7 |
 | `stabilityai/stable-diffusion-3.5-medium` | 1024 x 1024 | 20.1 | 15.6 |
 | `black-forest-labs/FLUX.1-dev` | 1024 x 1024 | 33.9 | 31.4 |
 | `black-forest-labs/FLUX.1-schnell` | 1024 x 1024 | 33.9 | 31.4 |
 | `black-forest-labs/FLUX.2-klein-4B` | 1024 x 1024 | 72.7 | 14.9 |
 | `black-forest-labs/FLUX.2-klein-9B` | 1024 x 1024 | 37.1 | 32.3 |
 | `black-forest-labs/FLUX.2-dev` | 1024 x 1024 | 65.7 | >80 (CPU offload required) |
-| `HunyuanImage-3.0` | 1024 x 1024 | 80.0 (TP≥3)  | 160 |
-| `HiDream-I1-Full` | 1024 x 1024 | 63.7  | 57.7 |
+| `HunyuanImage-3.0` | 1024 x 1024 | 80.0 (TP≥3) | 160 |
+| `HiDream-I1-Full` | 1024 x 1024 | 63.7 | 57.7 |
 | `krea/Krea-2-Raw`, `krea/Krea-2-Turbo` | 1024 (Raw) / 2048 (Turbo) | — | ~30 |
 
 !!! info
@@ -112,9 +112,9 @@ python text_to_image.py \
 | `--enable-cpu-offload` | flag | off | Enable CPU offloading for diffusion models |
 | `--lora-path` | str | — | Path to PEFT LoRA adapter folder or checkpoint file |
 | `--lora-scale` | float | `1.0` | Scale factor for LoRA weights |
-| `--lora-backend` | str |`"peft"`| LoRA backend for loading LoRA adapters. Default: peft. Available options: peft, distill |
-| `--use-system-prompt` | str | `None` | System prompt preset: `en_unified`, `en_vanilla`, `en_recaption`, `en_think_recaption`, `dynamic`, `None`, or custom text. Recommended: `en_unified`. Only for HunyuanImage-3.0.|
-| `--system-prompt` | str | `None` | Custom system prompt text. Only used when `--use-system-prompt` is set to `custom`. Only for HunyuanImage-3.0.|
+| `--lora-backend` | str | `"peft"` | LoRA backend for loading LoRA adapters. Default: peft. Available options: peft, distill |
+| `--use-system-prompt` | str | `None` | System prompt preset: `en_unified`, `en_vanilla`, `en_recaption`, `en_think_recaption`, `dynamic`, `None`, or custom text. Recommended: `en_unified`. Only for HunyuanImage-3.0. |
+| `--system-prompt` | str | `None` | Custom system prompt text. Only used when `--use-system-prompt` is set to `custom`. Only for HunyuanImage-3.0. |
 | `--auxiliary-text-encoder` | str | `None` | Supplementary auxiliary text encoder parameters model name or path (especially for Hidream-l1-full). |
 
 **NextStep-1.1 specific arguments:**
@@ -127,7 +127,7 @@ python text_to_image.py \
 | `--use-norm` | flag | off | Apply layer normalization to sampled tokens |
 
 > If you encounter OOM errors, try using `--vae-use-slicing` and `--vae-use-tiling` to reduce memory usage.
-
+>
 > Qwen-Image currently publishes best-effort presets at `1328x1328`, `1664x928`, `928x1664`, `1472x1140`, `1140x1472`, `1584x1056`, and `1056x1584`. Adjust `--height/--width` accordingly for the most reliable outcomes.
 
 ## More CLI Examples
@@ -216,6 +216,26 @@ python examples/offline_inference/text_to_image/text_to_image.py \
   --output /output.png
 ```
 
+### Anima Single-File Checkpoints
+
+Anima uses the official model dimensions by default. A checkpoint may provide a JSON file with the same stem (for example, `anima.json` beside `anima.safetensors`) containing `transformer` and `text_conditioner` configuration objects. These override the default dimensions and must match the checkpoint weights. The shared tiny-model tests use this to load small random-weight models. Components in `text_encoder/`, `vae/`, `tokenizer/`, `t5_tokenizer/`, and `scheduler/` beside the checkpoint are discovered automatically.
+
+To load Anima, point `--model` to the single-file checkpoint path, pass the native pipeline class name using `--model-class-name`, and supply the converted components directory using `--custom-pipeline-args`:
+
+```bash
+python examples/offline_inference/text_to_image/text_to_image.py \
+  --model /path/to/models/anima-official/split_files/diffusion_models/anima-base-v1.0.safetensors \
+  --model-class-name AnimaPipeline \
+  --custom-pipeline-args '{"components_path": "/path/to/models/anima-components"}' \
+  --prompt "A cinematic close-up of a glass teapot on a wooden table." \
+  --seed 42 \
+  --guidance-scale 4.0 \
+  --num-inference-steps 50 \
+  --height 1024 \
+  --width 1024 \
+  --output anima_output.png
+```
+
 ### Krea 2
 
 Krea 2 is published as diffusers-format checkpoints: `krea/Krea-2-Turbo` (few-step distilled) and `krea/Krea-2-Raw`.
@@ -336,7 +356,7 @@ python text_to_image.py \
 
 LoRA adapters must be in PEFT format. A typical adapter directory structure:
 
-```
+```text
 lora_adapter/
 ├── adapter_config.json
 └── adapter_model.safetensors
diff --git a/examples/offline_inference/text_to_image/text_to_image.py b/examples/offline_inference/text_to_image/text_to_image.py
index adcc1066971..71689b27208 100644
--- a/examples/offline_inference/text_to_image/text_to_image.py
+++ b/examples/offline_inference/text_to_image/text_to_image.py
@@ -1,5 +1,5 @@
 # SPDX-License-Identifier: Apache-2.0
-# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
 import argparse
 import functools
@@ -58,6 +58,7 @@ def parse_json_object(value: str, flag_name: str = "argument") -> dict[str, Any]
 
 
 parse_profiler_config = functools.partial(parse_json_object, flag_name="--profiler-config")
+parse_custom_pipeline_args = functools.partial(parse_json_object, flag_name="--custom-pipeline-args")
 
 
 def build_text_to_image_prompt(prompt: str, negative_prompt: str | None) -> dict[str, Any]:
@@ -379,6 +380,18 @@ def parse_args() -> argparse.Namespace:
         default=None,
         help="Supplementary auxiliary text encoder parameters model name or path (especially for Hidream-l1-full).",
     )
+    parser.add_argument(
+        "--model-class-name",
+        type=str,
+        default=None,
+        help="Override the diffusion pipeline class name (e.g. AnimaPipeline).",
+    )
+    parser.add_argument(
+        "--custom-pipeline-args",
+        type=parse_custom_pipeline_args,
+        default=None,
+        help='JSON object passed to native/custom pipelines (e.g. \'{"components_path": "/path"}\').',
+    )
     parser.add_argument(
         "--trust-remote-code",
         action="store_true",
@@ -576,9 +589,13 @@ def main():
         omni_kwargs["trust_remote_code"] = True
     if args.deploy_config:
         omni_kwargs["deploy_config"] = args.deploy_config
-    if use_nextstep:
+    if args.model_class_name:
+        omni_kwargs["model_class_name"] = args.model_class_name
+    elif use_nextstep:
         # NextStep-1.1 requires explicit pipeline class
         omni_kwargs["model_class_name"] = "NextStep11Pipeline"
+    if args.custom_pipeline_args is not None:
+        omni_kwargs["custom_pipeline_args"] = args.custom_pipeline_args
     # Cosmos3 loads its (gated) guardrail models at build time, so the guardrails
     # gate is an engine-level config (offline analog of the server's --no-guardrails).
     if args.extra_body and "guardrails" in args.extra_body:
@@ -614,6 +631,10 @@ def main():
         print(f"  LoRA: scale={args.lora_scale}")
     if args.deploy_config:
         print(f"  deploy-config: {args.deploy_config}")
+    if args.model_class_name:
+        print(f"  Model class name: {args.model_class_name}")
+    if args.custom_pipeline_args is not None:
+        print(f"  Custom pipeline args: {args.custom_pipeline_args}")
     print(f"{'=' * 60}\n")
 
     # Build LoRA request when --lora-path is set
diff --git a/recipes/README.md b/recipes/README.md
index a7c10ca145a..c84223510ed 100644
--- a/recipes/README.md
+++ b/recipes/README.md
@@ -49,6 +49,7 @@ recipes/
 | [`BosonAI/Higgs-Audio-V3-TTS.md`](./BosonAI/Higgs-Audio-V3-TTS.md) | Online + offline multilingual TTS with voice cloning | 1x H100 80GB |
 | [`BreezeBlue/Breeze-TTS-2.md`](./BreezeBlue/Breeze-TTS-2.md) | Online + offline TTS (plain / voice design / voice clone / voice direction, streaming PCM) | 1x NVIDIA L20 48GB |
 | [`ByteDance/Lance.md`](./ByteDance/Lance.md) | Unified AR+diffusion: text/img/video gen + understanding (Lance 3B) | 1x B300 / A100 80GB |
+| [`circlestone-labs/Anima.md`](./circlestone-labs/Anima.md) | Native single-file text-to-image serving | 1x AMD MI300X |
 | [`fishaudio/Fish-Speech-S2-Pro.md`](./fishaudio/Fish-Speech-S2-Pro.md) | Online serving for TTS | 1x A800 80GB |
 | [`Helios/Helios.md`](./Helios/Helios.md) | Text-to-video, image-to-video, and video-to-video generation | 1x NVIDIA H20 |
 | [`HiDream-ai/HiDream-O1-Image.md`](./HiDream-ai/HiDream-O1-Image.md) | Text-to-image with shared offline example | 1x or 2x H100 80GB |
diff --git a/recipes/circlestone-labs/Anima.md b/recipes/circlestone-labs/Anima.md
new file mode 100644
index 00000000000..bcaf8436483
--- /dev/null
+++ b/recipes/circlestone-labs/Anima.md
@@ -0,0 +1,158 @@
+# Anima
+
+> Native single-file diffusion text-to-image
+
+## Summary
+
+- Vendor: circlestone-labs
+- Model: [`circlestone-labs/Anima`](https://huggingface.co/circlestone-labs/Anima)
+- Task: text2img
+- Mode: Offline inference, Online serving (OpenAI-compatible API)
+- Maintainer: Community
+
+## When to use this recipe
+
+Use this recipe to run Anima via vLLM-Omni's native `AnimaPipeline`. Anima is a
+Cosmos-style diffusion transformer text-to-image model distributed as a
+single-file transformer checkpoint, not as a normal Hugging Face model
+directory.
+
+The native path reads the Anima transformer checkpoint directly, converts
+original Cosmos transformer keys when needed, and loads the Cosmos transformer
+and text conditioner into native vLLM-Omni modules. Non-denoiser components
+such as `text_encoder`, `tokenizer`, `t5_tokenizer`, `vae`, and optionally
+`scheduler` must be supplied through a Diffusers-layout components directory.
+
+Native Anima currently supports baseline single-GPU execution. Cache-DiT,
+TeaCache, CPU offload, layer-wise offload, quantization, TP/SP, CFG parallel,
+HSDP, and step execution are not supported by `AnimaPipeline` yet.
+
+## References
+
+- Offline example:
+  [`examples/offline_inference/text_to_image/README.md`](../../examples/offline_inference/text_to_image/README.md)
+- Supported model entry:
+  [`docs/models/supported_models.md`](../../docs/models/supported_models.md)
+- HuggingFace model page:
+  [circlestone-labs/Anima](https://huggingface.co/circlestone-labs/Anima)
+- Diffusers-layout components:
+  [circlestone-labs/Anima-Base-v1.0-Diffusers](https://huggingface.co/circlestone-labs/Anima-Base-v1.0-Diffusers)
+
+## Hardware Support
+
+## ROCm
+
+### 1x AMD MI300X
+
+#### Environment
+
+- OS: Ubuntu 22.04.5 LTS (x86_64)
+- Python: 3.12.13
+- Driver / runtime: ROCm 7.2.53211, HIP runtime 7.2.53211, MIOpen 3.5.1
+- PyTorch: 2.10.0+git8514f05 built with ROCm 7.2.53211
+- GPU: 1x AMD MI300X
+- vLLM version: 0.23.0
+- vLLM-Omni version or commit: 0.1.dev2002+g704724675.rocm
+
+Recommended environment variables:
+
+```bash
+export VLLM_WORKER_MULTIPROC_METHOD=spawn
+export VLLM_ROCM_USE_AITER=0
+export PYTORCH_ROCM_ARCH=gfx942
+export PYTORCH_NVML_BASED_CUDA_CHECK=1
+```
+
+#### Command - prepare assets
+
+Download the official transformer checkpoint and the Diffusers-layout component
+directory:
+
+```bash
+mkdir -p /path/to/models/anima-official
+mkdir -p /path/to/models/anima-components
+
+hf download circlestone-labs/Anima \
+    split_files/diffusion_models/anima-base-v1.0.safetensors \
+    --local-dir /path/to/models/anima-official
+
+hf download circlestone-labs/Anima-Base-v1.0-Diffusers \
+    --local-dir /path/to/models/anima-components
+
+export ANIMA_CHECKPOINT=/path/to/models/anima-official/split_files/diffusion_models/anima-base-v1.0.safetensors
+export ANIMA_COMPONENTS=/path/to/models/anima-components
+```
+
+The `ANIMA_COMPONENTS` directory must be in Diffusers `from_pretrained()`
+layout. Raw auxiliary files such as `qwen_3_06b_base.safetensors` and
+`qwen_image_vae.safetensors` are converter inputs; they are not accepted
+directly as `components_path`.
+
+#### Command - text-to-image
+
+```bash
+python examples/offline_inference/text_to_image/text_to_image.py \
+    --model "$ANIMA_CHECKPOINT" \
+    --model-class-name AnimaPipeline \
+    --custom-pipeline-args "{\"components_path\":\"$ANIMA_COMPONENTS\"}" \
+    --prompt "A cinematic close-up of a glass teapot on a wooden table." \
+    --seed 42 \
+    --guidance-scale 4.0 \
+    --num-inference-steps 50 \
+    --height 1024 \
+    --width 1024 \
+    --output /tmp/anima_output.png
+```
+
+Use 1024x1024, 50 denoising steps, `max_sequence_length=512`, one image per
+prompt, empty negative prompt, and CFG scale 4.0 when matching Anima's default
+Diffusers settings.
+
+#### Verification
+
+Check that `/tmp/anima_output.png` exists and contains a generated image.
+
+#### Notes
+
+- Key flags: `--model-class-name AnimaPipeline` selects the native Anima path;
+  `--custom-pipeline-args` supplies `components_path`.
+- Keep the default diffusion load format. No deploy config is required when a
+  local checkpoint and `--model-class-name AnimaPipeline` are provided.
+- Start with `max-concurrency=1` for correctness and latency validation.
+- Keep requests at the same resolution when comparing runs.
+- Do not enable parallelism, cache acceleration, offload, or quantized
+  checkpoint flags for Anima until support is added to `AnimaPipeline`.
+
+## Online Serving
+
+Anima supports text-to-image generation through the OpenAI-compatible image
+generation API.
+
+### Launch
+
+```bash
+vllm serve "$ANIMA_CHECKPOINT" \
+    --omni \
+    --port 8099 \
+    --model-class-name AnimaPipeline \
+    --custom-pipeline-args "{\"components_path\":\"$ANIMA_COMPONENTS\"}"
+```
+
+### Send requests
+
+```bash
+curl http://localhost:8099/v1/images/generations \
+    -H "Content-Type: application/json" \
+    -d "{
+      \"model\": \"$ANIMA_CHECKPOINT\",
+      \"prompt\": \"A cinematic close-up of a glass teapot on a wooden table.\",
+      \"size\": \"1024x1024\",
+      \"num_inference_steps\": 50,
+      \"guidance_scale\": 4.0,
+      \"seed\": 42
+    }"
+```
+
+The same generation knobs used by other text-to-image recipes apply:
+`num_inference_steps`, `seed`, `height` / `width` through `size`, and optional
+negative prompting.
diff --git a/tests/diffusion/models/anima/__init__.py b/tests/diffusion/models/anima/__init__.py
new file mode 100644
index 00000000000..4244ce4b4e1
--- /dev/null
+++ b/tests/diffusion/models/anima/__init__.py
@@ -0,0 +1,2 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
diff --git a/tests/diffusion/models/anima/test_anima.py b/tests/diffusion/models/anima/test_anima.py
new file mode 100644
index 00000000000..124171c9306
--- /dev/null
+++ b/tests/diffusion/models/anima/test_anima.py
@@ -0,0 +1,454 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import json
+from pathlib import Path
+from shutil import rmtree
+from types import SimpleNamespace
+
+import pytest
+import torch
+from safetensors.torch import save_file
+
+from tests.model_tests.diffusion.anima_builder import CHECKPOINT_FILENAME, tiny_anima_builder
+from vllm_omni.diffusion.attention import selector
+from vllm_omni.diffusion.attention.backends.sdpa import SDPABackend
+from vllm_omni.diffusion.data import DiffusionOutput, OmniDiffusionConfig
+from vllm_omni.diffusion.distributed.autoencoders.autoencoder_kl_qwenimage import DistributedAutoencoderKLQwenImage
+from vllm_omni.diffusion.models.anima import pipeline_anima
+from vllm_omni.diffusion.models.anima.anima_text_conditioner import AnimaTextConditioner
+from vllm_omni.diffusion.models.anima.anima_transformer import AnimaTransformer3DModel
+from vllm_omni.diffusion.models.anima.pipeline_anima import AnimaPipeline
+from vllm_omni.diffusion.request import OmniDiffusionRequest
+from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch
+from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+from vllm_omni.platforms import current_omni_platform
+
+pytestmark = [pytest.mark.core_model, pytest.mark.cpu, pytest.mark.diffusion]
+
+
+@pytest.mark.parametrize(
+    "offload_args",
+    [
+        {"enable_cpu_offload": True},
+        {"enable_layerwise_offload": True},
+        {"enable_distributed_layerwise_offload": True},
+        {"diffusion_offload_config": {"mode": "module", "components": ["dit"]}},
+        {
+            "diffusion_offload_config": {
+                "mode": "layer",
+                "components": ["dit"],
+                "layer_options": {"dit": {"weight_transfer": "rank-local"}},
+            }
+        },
+    ],
+)
+def test_native_anima_rejects_offload(offload_args):
+    config = OmniDiffusionConfig(model="anima.safetensors", **offload_args)
+    with pytest.raises(NotImplementedError, match="offload"):
+        AnimaPipeline(od_config=config, device=torch.device("cpu"))
+
+
+def test_native_anima_initializes_without_offload():
+    config = OmniDiffusionConfig(model="anima.safetensors")
+    AnimaPipeline(od_config=config, device=torch.device("cpu"))
+
+
+def test_anima_registration() -> None:
+    """The native Anima pipeline is registered and importable."""
+    from vllm_omni.diffusion.registry import DiffusionModelRegistry
+
+    assert DiffusionModelRegistry._try_load_model_cls("AnimaPipeline") is not None
+
+
+@pytest.mark.parametrize("model_class_name", ["AnimaPipeline", "AnimaModularPipeline"])
+def test_enrich_config_native_anima_checkpoint(tmp_path: Path, model_class_name: str) -> None:
+    """Native and reference Anima class names resolve to AnimaPipeline."""
+    dummy_checkpoint = tmp_path / "model.safetensors"
+    dummy_checkpoint.write_text("dummy")
+
+    config = OmniDiffusionConfig(
+        model=str(dummy_checkpoint),
+        model_class_name=model_class_name,
+    )
+    config.enrich_config()
+
+    assert config.diffusion_load_format == "default"
+    assert config.model_class_name == "AnimaPipeline"
+    assert config.diffusers_pipeline_cls is None
+
+
+def test_native_anima_component_paths_use_custom_pipeline_args() -> None:
+    """Anima resolves shared and component-specific paths from native args."""
+    pipeline = AnimaPipeline.__new__(AnimaPipeline)
+    pipeline.od_config = SimpleNamespace(
+        custom_pipeline_args={
+            "components_path": "/tmp/anima-components",
+            "vae_path": "/tmp/anima-vae",
+            "text_encoder_model": "/tmp/anima-text-encoder",
+        }
+    )
+
+    assert pipeline._component_path("vae", "/tmp/default") == "/tmp/anima-vae"
+    assert pipeline._component_path("text_encoder", "/tmp/default") == "/tmp/anima-text-encoder"
+    assert pipeline._component_path("tokenizer", "/tmp/default") == "/tmp/default"
+
+
+def test_native_anima_converts_original_cosmos_transformer_keys() -> None:
+    """Original Cosmos checkpoint names map to native module names."""
+    converted = AnimaPipeline._convert_original_transformer_state_dict(
+        {
+            "net.x_embedder.proj.1.weight": "patch",
+            "net.blocks.0.self_attn.q_proj.weight": "q",
+            "net.blocks.0.self_attn.q_norm.weight": "q_norm",
+            "net.blocks.0.mlp.layer1.weight": "mlp",
+            "net.final_layer.linear.weight": "out",
+            "net.accum_iteration": "drop",
+        }
+    )
+
+    assert converted == {
+        "patch_embed.proj.weight": "patch",
+        "transformer_blocks.0.attn1.to_q.weight": "q",
+        "transformer_blocks.0.attn1.norm_q.weight": "q_norm",
+        "transformer_blocks.0.ff.net.0.proj.weight": "mlp",
+        "proj_out.weight": "out",
+    }
+
+
+def test_native_anima_resolves_vae_scale_factor_from_loaded_vae() -> None:
+    """The loaded VAE determines the spatial scale factor."""
+    from vllm_omni.diffusion.models.anima.pipeline_anima import _anima_vae_scale_factor_from_vae
+
+    vae = SimpleNamespace(config=SimpleNamespace(spatial_compression_ratio=16))
+
+    assert _anima_vae_scale_factor_from_vae(vae) == 16
+
+
+@pytest.mark.parametrize("use_config_file", [False, True])
+def test_native_anima_loads_synthetic_checkpoint(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch, use_config_file: bool
+) -> None:
+    """Native modules load exact weights from an Anima safetensors checkpoint."""
+    tiny_transformer_config = {
+        "in_channels": 1,
+        "out_channels": 1,
+        "num_attention_heads": 1,
+        "attention_head_dim": 12,
+        "num_layers": 1,
+        "mlp_ratio": 1.0,
+        "text_embed_dim": 4,
+        "adaln_lora_dim": 3,
+        "max_size": (1, 2, 2),
+        "patch_size": (1, 1, 1),
+        "rope_scale": (1.0, 1.0, 1.0),
+        "concat_padding_mask": True,
+        "extra_pos_embed_type": None,
+    }
+    tiny_text_conditioner_config = {
+        "source_dim": 4,
+        "target_dim": 4,
+        "model_dim": 4,
+        "num_layers": 1,
+        "num_attention_heads": 1,
+        "target_vocab_size": 8,
+        "min_sequence_length": 4,
+    }
+    if use_config_file:
+        (tmp_path / "anima.json").write_text(
+            json.dumps({"transformer": tiny_transformer_config, "text_conditioner": tiny_text_conditioner_config})
+        )
+    else:
+        monkeypatch.setattr(pipeline_anima, "ANIMA_TRANSFORMER_CONFIG", tiny_transformer_config)
+        monkeypatch.setattr(pipeline_anima, "ANIMA_TEXT_CONDITIONER_CONFIG", tiny_text_conditioner_config)
+
+    monkeypatch.setattr(selector, "_cached_get_backend_cls", lambda *_args, **_kwargs: SDPABackend)
+    transformer = AnimaTransformer3DModel(**tiny_transformer_config)
+    text_conditioner = AnimaTextConditioner(**tiny_text_conditioner_config)
+    transformer_state = {name: tensor.detach().clone() for name, tensor in transformer.state_dict().items()}
+    text_conditioner_state = {name: tensor.detach().clone() for name, tensor in text_conditioner.state_dict().items()}
+    checkpoint_state = {
+        **{f"transformer.{name}": tensor for name, tensor in transformer_state.items()},
+        **{f"text_conditioner.{name}": tensor for name, tensor in text_conditioner_state.items()},
+    }
+
+    checkpoint_path = tmp_path / "anima.safetensors"
+    save_file(checkpoint_state, str(checkpoint_path))
+
+    pipeline = AnimaPipeline.__new__(AnimaPipeline)
+    pipeline.od_config = SimpleNamespace(model=str(checkpoint_path), dtype=torch.float32)
+    pipeline.device = torch.device("cpu")
+
+    def assert_loaded(loaded_transformer, loaded_text_conditioner):
+        for name, tensor in transformer_state.items():
+            assert torch.equal(loaded_transformer.state_dict()[name], tensor)
+        for name, tensor in text_conditioner_state.items():
+            assert torch.equal(loaded_text_conditioner.state_dict()[name], tensor)
+
+    loaded_transformer, loaded_text_conditioner = pipeline._load_native_denoiser_components(dict(checkpoint_state))
+    assert_loaded(loaded_transformer, loaded_text_conditioner)
+
+    loaded_transformer, loaded_text_conditioner = pipeline._load_native_denoiser_components()
+    assert_loaded(loaded_transformer, loaded_text_conditioner)
+
+    if use_config_file:
+        tiny_transformer_config["num_layers"] = 2
+        (tmp_path / "anima.json").write_text(
+            json.dumps({"transformer": tiny_transformer_config, "text_conditioner": tiny_text_conditioner_config})
+        )
+        with pytest.raises(RuntimeError, match="Missing key"):
+            pipeline._load_native_denoiser_components()
+
+
+def test_tiny_anima_generates_images(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Load every saved component and exercise CFG, decoding, and multiple outputs on CPU."""
+    monkeypatch.setattr(selector, "_cached_get_backend_cls", lambda *_args, **_kwargs: SDPABackend)
+    monkeypatch.setattr(current_omni_platform, "is_available", lambda: False)
+    monkeypatch.setattr(
+        DistributedAutoencoderKLQwenImage,
+        "init_distributed",
+        lambda self: setattr(self, "distributed_executor", SimpleNamespace(parallel_size=1)),
+    )
+    model_dir = tiny_anima_builder()
+    try:
+        config = OmniDiffusionConfig(
+            model=str(Path(model_dir) / CHECKPOINT_FILENAME), model_class_name="AnimaPipeline", dtype=torch.float32
+        )
+        pipeline = AnimaPipeline(od_config=config, device=torch.device("cpu"))
+        pipeline.load_weights()
+        pipeline.eval()
+        outputs = []
+        with torch.inference_mode():
+            for _ in range(2):
+                request = OmniDiffusionRequest(
+                    prompt="Dummy prompt",
+                    request_id="tiny-anima",
+                    sampling_params=OmniDiffusionSamplingParams(
+                        height=32,
+                        width=32,
+                        num_inference_steps=2,
+                        guidance_scale=4.0,
+                        num_outputs_per_prompt=2,
+                        generator=torch.Generator(device="cpu").manual_seed(42),
+                    ),
+                )
+                outputs.append(pipeline(DiffusionRequestBatch([request]))[0].output)
+        assert outputs[0].shape == (2, 3, 32, 32)
+        assert torch.isfinite(outputs[0]).all()
+        assert torch.equal(outputs[0], outputs[1])
+        assert not torch.equal(outputs[0][0], outputs[0][1])
+    finally:
+        rmtree(model_dir)
+
+
+def test_native_anima_profiler_setup_is_deferred_and_idempotent(monkeypatch: pytest.MonkeyPatch) -> None:
+    """Profiler targets are wrapped once, after deferred components are loaded."""
+    pipeline = AnimaPipeline.__new__(AnimaPipeline)
+    pipeline.od_config = SimpleNamespace(enable_diffusion_pipeline_profiler=True)
+    pipeline._profiler_initialized = False
+    pipeline.vae = SimpleNamespace(decode=lambda: "decoded")
+    pipeline.text_encoder = SimpleNamespace(forward=lambda: "encoded")
+
+    monkeypatch.setattr(current_omni_platform, "is_available", lambda: False)
+    pipeline._setup_profiler()
+    wrapped_decode = pipeline.vae.decode
+    wrapped_text_encoder = pipeline.text_encoder.forward
+    pipeline._setup_profiler()
+
+    assert pipeline.vae.decode is wrapped_decode
+    assert pipeline.text_encoder.forward is wrapped_text_encoder
+    assert pipeline.vae.decode() == "decoded"
+    assert pipeline.text_encoder.forward() == "encoded"
+    assert "AnimaPipeline.vae.decode" in pipeline.stage_durations
+    assert "AnimaPipeline.text_encoder.forward" in pipeline.stage_durations
+
+
+def _make_anima_forward_probe():
+    pipeline = AnimaPipeline.__new__(AnimaPipeline)
+    pipeline.device = torch.device("cpu")
+    pipeline.vae_scale_factor = 8
+    pipeline.transformer = SimpleNamespace(dtype=torch.float32)
+    pipeline.text_encoder = SimpleNamespace(dtype=torch.float32)
+    pipeline._current_timestep = None
+    pipeline._num_timesteps = 0
+    pipeline._guidance_scale = 0.0
+    captured = {}
+
+    def encode_prompt(**_kwargs):
+        return {
+            "qwen_prompt_embeds": torch.zeros(1, 2, 4),
+            "qwen_attention_mask": torch.ones(1, 2),
+            "t5_input_ids": torch.ones(1, 2, dtype=torch.long),
+            "t5_attention_mask": torch.ones(1, 2),
+            "negative_qwen_prompt_embeds": torch.zeros(1, 2, 4),
+            "negative_qwen_attention_mask": torch.ones(1, 2),
+            "negative_t5_input_ids": torch.ones(1, 2, dtype=torch.long),
+            "negative_t5_attention_mask": torch.ones(1, 2),
+        }
+
+    def condition_prompt_embeds(**_kwargs):
+        return torch.zeros(1, 2, 4)
+
+    def prepare_latents(**kwargs):
+        captured["prepare_latents"] = kwargs
+        return torch.zeros(1, 16, 1, kwargs["height"] // 8, kwargs["width"] // 8)
+
+    def diffuse(**kwargs):
+        captured["diffuse"] = kwargs
+        return kwargs["latents"]
+
+    pipeline.encode_prompt = encode_prompt
+    pipeline.condition_prompt_embeds = condition_prompt_embeds
+    pipeline.prepare_latents = prepare_latents
+    pipeline.prepare_timesteps = lambda **_kwargs: (torch.ones(1), 1)
+    pipeline.diffuse = diffuse
+
+    def decode_latents(latents, output_type="pil"):
+        captured["output_type"] = output_type
+        return DiffusionOutput(output=latents)
+
+    pipeline.decode_latents = decode_latents
+    return pipeline, captured
+
+
+def test_native_anima_forward_uses_official_default_resolution() -> None:
+    """Forward uses Anima's reference resolution when none is requested."""
+    pipeline, captured = _make_anima_forward_probe()
+    req = OmniDiffusionRequest(
+        prompt="a red cube",
+        sampling_params=OmniDiffusionSamplingParams(),
+        request_id="anima-defaults",
+    )
+
+    pipeline.forward(DiffusionRequestBatch([req]))
+
+    assert captured["prepare_latents"]["height"] == 1024
+    assert captured["prepare_latents"]["width"] == 1024
+
+
+def test_native_anima_forward_honors_sampling_output_type() -> None:
+    """Request-level output type controls Anima decoding."""
+    pipeline, captured = _make_anima_forward_probe()
+    req = OmniDiffusionRequest(
+        prompt="a red cube",
+        sampling_params=OmniDiffusionSamplingParams(output_type="latent"),
+        request_id="anima-output-type",
+    )
+
+    outputs = pipeline.forward(DiffusionRequestBatch([req]))
+
+    assert len(outputs) == 1
+    assert isinstance(outputs[0], DiffusionOutput)
+    assert outputs[0].output.shape == (1, 16, 1, 128, 128)
+    assert captured["output_type"] == "latent"
+
+
+@pytest.mark.parametrize("request_count", [0, 2])
+def test_native_anima_forward_rejects_non_single_request_batches(request_count: int) -> None:
+    pipeline, captured = _make_anima_forward_probe()
+    requests = [
+        OmniDiffusionRequest(
+            prompt="a red cube",
+            sampling_params=OmniDiffusionSamplingParams(),
+            request_id=f"anima-{index}",
+        )
+        for index in range(request_count)
+    ]
+
+    with pytest.raises(ValueError, match="supports one request per forward"):
+        pipeline.forward(DiffusionRequestBatch(requests))
+
+    assert captured == {}
+
+
+def test_native_anima_explicit_guidance_scale_drives_cfg_multiplier() -> None:
+    """An explicit guidance scale controls native classifier-free guidance."""
+    pipeline, captured = _make_anima_forward_probe()
+    req = OmniDiffusionRequest(
+        prompt="a red cube",
+        sampling_params=OmniDiffusionSamplingParams(guidance_scale=5.0),
+        request_id="anima-guidance",
+    )
+
+    pipeline.forward(DiffusionRequestBatch([req]))
+
+    assert captured["diffuse"]["do_true_cfg"] is True
+    assert captured["diffuse"]["true_cfg_scale"] == 5.0
+
+
+def test_native_anima_true_cfg_scale_overrides_guidance_multiplier() -> None:
+    """An explicit true-CFG scale overrides the guidance-scale multiplier."""
+    pipeline, captured = _make_anima_forward_probe()
+    req = OmniDiffusionRequest(
+        prompt="a red cube",
+        sampling_params=OmniDiffusionSamplingParams(guidance_scale=5.0, true_cfg_scale=3.0),
+        request_id="anima-true-cfg",
+    )
+
+    pipeline.forward(DiffusionRequestBatch([req]))
+
+    assert captured["diffuse"]["do_true_cfg"] is True
+    assert captured["diffuse"]["true_cfg_scale"] == 3.0
+
+
+def test_native_anima_cfg_equation() -> None:
+    """The denoising loop applies the standard true-CFG equation."""
+    pipeline = AnimaPipeline.__new__(AnimaPipeline)
+    pipeline.device = torch.device("cpu")
+    pipeline._interrupt = False
+
+    class MockProgressBar:
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc_val, exc_tb):
+            pass
+
+        def update(self):
+            pass
+
+    pipeline.progress_bar = lambda **_kwargs: MockProgressBar()
+
+    class MockTransformer:
+        dtype = torch.float32
+
+        def __call__(self, hidden_states, timestep, encoder_hidden_states, padding_mask, return_dict=False):
+            # Return double the encoder_hidden_states to simulate transformer output
+            return (encoder_hidden_states * 2.0,)
+
+    pipeline.transformer = MockTransformer()
+
+    class MockScheduler:
+        def set_begin_index(self, index):
+            pass
+
+        def step(self, noise_pred, t, latents, return_dict=False):
+            # Return the noise_pred itself to inspect it
+            return (noise_pred,)
+
+    pipeline.scheduler = MockScheduler()
+
+    prompt_embeds = torch.tensor([[[2.0, 3.0]]])
+    negative_prompt_embeds = torch.tensor([[[1.0, 2.0]]])
+    latents = torch.zeros(1, 16, 1, 16, 16)
+    padding_mask = torch.zeros(1, 1, 16, 16)
+    timesteps = torch.tensor([500.0])
+
+    # Cond = prompt_embeds * 2.0 = [4.0, 6.0]
+    # Uncond = negative_prompt_embeds * 2.0 = [2.0, 4.0]
+    # Expected noise_pred = uncond + true_cfg_scale * (cond - uncond)
+    #                     = [2.0, 4.0] + 4.0 * ([4.0, 6.0] - [2.0, 4.0])
+    #                     = [2.0, 4.0] + 4.0 * [2.0, 2.0]
+    #                     = [2.0, 4.0] + [8.0, 8.0] = [10.0, 12.0]
+    out_latents = pipeline.diffuse(
+        prompt_embeds=prompt_embeds,
+        negative_prompt_embeds=negative_prompt_embeds,
+        latents=latents,
+        padding_mask=padding_mask,
+        timesteps=timesteps,
+        do_true_cfg=True,
+        true_cfg_scale=4.0,
+    )
+
+    expected = torch.tensor([[[10.0, 12.0]]])
+    assert torch.allclose(out_latents, expected)
diff --git a/tests/diffusion/test_worker_wrapper_base.py b/tests/diffusion/test_worker_wrapper_base.py
index 709fc7283f2..fb765e8fdff 100644
--- a/tests/diffusion/test_worker_wrapper_base.py
+++ b/tests/diffusion/test_worker_wrapper_base.py
@@ -100,6 +100,28 @@ def test_basic_initialization(self, mocker: MockerFixture, mock_od_config):
             skip_load_model=False,
         )
 
+    def test_custom_pipeline_args_without_pipeline_class_loads_normally(self, mocker: MockerFixture, mock_od_config):
+        """Test native pipeline args do not trigger custom pipeline re-initialization."""
+        custom_args = {"components_path": "/tmp/anima-components"}
+        mock_worker_init = mocker.patch.object(DiffusionWorker, "__init__", return_value=None)
+
+        wrapper = WorkerWrapperBase(
+            gpu_id=0,
+            od_config=mock_od_config,
+            base_worker_class=DiffusionWorker,
+            custom_pipeline_args=custom_args,
+        )
+
+        assert wrapper.worker_extension_cls is None
+        assert CustomPipelineWorkerExtension not in wrapper.worker.__class__.__bases__
+        assert not hasattr(wrapper.worker, "re_init_pipeline")
+        mock_worker_init.assert_called_once_with(
+            local_rank=0,
+            rank=0,
+            od_config=mock_od_config,
+            skip_load_model=False,
+        )
+
 
 # -------------------------------------------------------------------------
 # Tests: Worker Extension Functionality
@@ -476,6 +498,12 @@ def test_custom_pipeline_args_initialization(self, mocker: MockerFixture, mock_o
             custom_pipeline_args=custom_args,
         )
 
+        mock_worker_class.assert_called_once_with(
+            local_rank=0,
+            rank=0,
+            od_config=mock_od_config,
+            skip_load_model=True,
+        )
         # Verify re_init_pipeline was called with custom_pipeline_args
         mock_worker_instance.re_init_pipeline.assert_called_once_with(custom_args)
 
diff --git a/tests/e2e/offline_inference/test_anima.py b/tests/e2e/offline_inference/test_anima.py
new file mode 100644
index 00000000000..877fcfe2d59
--- /dev/null
+++ b/tests/e2e/offline_inference/test_anima.py
@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Offline e2e smoke test for native Anima single-file checkpoints."""
+
+import os
+
+import pytest
+
+from tests.helpers.mark import hardware_test
+from tests.helpers.runtime import OmniRunner, OmniRunnerHandler
+from vllm_omni.inputs.data import OmniDiffusionSamplingParams
+
+CHECKPOINT_ENV = "ANIMA_CHECKPOINT_PATH"
+COMPONENTS_ENV = "ANIMA_COMPONENTS_PATH"
+CHECKPOINT_REPO = "circlestone-labs/Anima"
+CHECKPOINT_FILENAME = "split_files/diffusion_models/anima-base-v1.0.safetensors"
+COMPONENTS_REPO = "circlestone-labs/Anima-Base-v1.0-Diffusers"
+PROMPT = "A cinematic close-up of a glass teapot on a wooden table."
+
+
+def _resolve_anima_assets() -> tuple[str, str]:
+    checkpoint = os.environ.get(CHECKPOINT_ENV)
+    components = os.environ.get(COMPONENTS_ENV)
+    if checkpoint and components:
+        return checkpoint, components
+
+    from huggingface_hub import hf_hub_download, snapshot_download
+
+    if checkpoint is None:
+        checkpoint = hf_hub_download(
+            repo_id=CHECKPOINT_REPO,
+            filename=CHECKPOINT_FILENAME,
+        )
+    if components is None:
+        components = snapshot_download(repo_id=COMPONENTS_REPO)
+    return checkpoint, components
+
+
+@pytest.mark.full_model
+@pytest.mark.diffusion
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
+@pytest.mark.parametrize("guidance_scale", [1.0, 4.0])
+def test_anima_text_to_image(guidance_scale):
+    checkpoint, components = _resolve_anima_assets()
+    request_config = {
+        "model": checkpoint,
+        "prompt": PROMPT,
+        "sampling_params": OmniDiffusionSamplingParams(
+            height=256,
+            width=256,
+            num_inference_steps=1,
+            guidance_scale=guidance_scale,
+            seed=42,
+        ),
+    }
+    with OmniRunner(
+        checkpoint,
+        seed=42,
+        model_class_name="AnimaPipeline",
+        custom_pipeline_args={"components_path": components},
+    ) as runner:
+        OmniRunnerHandler(runner).send_diffusion_request(request_config)
diff --git a/tests/e2e/online_serving/test_anima.py b/tests/e2e/online_serving/test_anima.py
new file mode 100644
index 00000000000..d3dc76cce9f
--- /dev/null
+++ b/tests/e2e/online_serving/test_anima.py
@@ -0,0 +1,77 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Online e2e smoke test for native Anima single-file checkpoints."""
+
+import json
+import os
+
+import pytest
+
+from tests.helpers.mark import hardware_test
+from tests.helpers.runtime import OmniServer, OpenAIClientHandler, dummy_messages_from_mix_data
+
+CHECKPOINT_ENV = "ANIMA_CHECKPOINT_PATH"
+COMPONENTS_ENV = "ANIMA_COMPONENTS_PATH"
+CHECKPOINT_REPO = "circlestone-labs/Anima"
+CHECKPOINT_FILENAME = "split_files/diffusion_models/anima-base-v1.0.safetensors"
+COMPONENTS_REPO = "circlestone-labs/Anima-Base-v1.0-Diffusers"
+PROMPT = "A cinematic close-up of a glass teapot on a wooden table."
+
+
+def _resolve_anima_assets() -> tuple[str, str]:
+    checkpoint = os.environ.get(CHECKPOINT_ENV)
+    components = os.environ.get(COMPONENTS_ENV)
+    if checkpoint and components:
+        return checkpoint, components
+
+    from huggingface_hub import hf_hub_download, snapshot_download
+
+    if checkpoint is None:
+        checkpoint = hf_hub_download(
+            repo_id=CHECKPOINT_REPO,
+            filename=CHECKPOINT_FILENAME,
+        )
+    if components is None:
+        components = snapshot_download(repo_id=COMPONENTS_REPO)
+    return checkpoint, components
+
+
+@pytest.mark.full_model
+@pytest.mark.diffusion
+@hardware_test(res={"cuda": "L4", "rocm": "MI325"}, num_cards=1)
+@pytest.mark.parametrize("guidance_scale", [1.0, 4.0])
+def test_anima_text_to_image(guidance_scale):
+    checkpoint, components = _resolve_anima_assets()
+    server_args = [
+        "--model-class-name",
+        "AnimaPipeline",
+        "--custom-pipeline-args",
+        json.dumps({"components_path": components}),
+    ]
+    with OmniServer(checkpoint, server_args) as omni_server:
+        openai_client = OpenAIClientHandler(
+            host=omni_server.host,
+            port=omni_server.port,
+            api_key="EMPTY",
+            run_level="full_model",
+            log_stats=omni_server.log_stats,
+        )
+        _send_text_to_image_request(omni_server, openai_client, guidance_scale)
+
+
+def _send_text_to_image_request(omni_server: OmniServer, openai_client: OpenAIClientHandler, guidance_scale: float):
+    messages = dummy_messages_from_mix_data(content_text=PROMPT)
+    request_config = {
+        "model": omni_server.model,
+        "messages": messages,
+        "extra_body": {
+            "height": 256,
+            "width": 256,
+            "num_inference_steps": 1,
+            "guidance_scale": guidance_scale,
+            "seed": 42,
+        },
+    }
+
+    openai_client.send_diffusion_request(request_config)
diff --git a/tests/entrypoints/test_serve.py b/tests/entrypoints/test_serve.py
index 7f8b6a4a90f..0f51a432006 100644
--- a/tests/entrypoints/test_serve.py
+++ b/tests/entrypoints/test_serve.py
@@ -152,6 +152,37 @@ def test_omni_serve_accepts_explicit_model(argv: list[str], mocker: MockerFixtur
     cmd.validate(args)
 
 
+@pytest.mark.parametrize(
+    "model_class,exists,native",
+    [
+        ("AnimaPipeline", True, True),
+        ("AnimaModularPipeline", True, True),
+        ("AnimaPipeline", False, False),
+        ("FluxPipeline", True, False),
+        (None, True, False),
+    ],
+)
+def test_serve_native_checkpoint_validation(model_class, exists, native, tmp_path, mocker):
+    checkpoint = tmp_path / "anima.safetensors"
+    if exists:
+        checkpoint.touch()
+    argv = ["serve", str(checkpoint), "--omni"]
+    if model_class is not None:
+        argv.extend(["--model-class-name", model_class])
+    args = _parse_serve_args(argv)
+    detect_model = mocker.patch("vllm_omni.diffusion.utils.hf_utils.is_diffusion_model", return_value=False)
+    validate_llm = mocker.patch("vllm_omni.entrypoints.cli.serve.validate_parsed_serve_args")
+
+    OmniServeCommand().validate(args)
+
+    if native:
+        detect_model.assert_not_called()
+        validate_llm.assert_not_called()
+    else:
+        detect_model.assert_called_once_with(str(checkpoint))
+        validate_llm.assert_called_once_with(args)
+
+
 def test_serve_parser_accepts_strategy_config() -> None:
     """``--strategy-config`` must parse onto the ``strategy_config`` dest and be
     forwarded as an explicit kwarg so the engine can overlay the strategy."""
@@ -215,14 +246,23 @@ def test_tracking_namespace_is_picklable_for_spawned_api_workers() -> None:
     assert restored._omni_stage_client_configs == args._omni_stage_client_configs
 
 
-def test_serve_validate_rejects_multiple_api_servers_for_diffusion(mocker: MockerFixture) -> None:
+@pytest.mark.parametrize("native_checkpoint", [False, True])
+def test_serve_validate_rejects_multiple_api_servers_for_diffusion(
+    mocker: MockerFixture, tmp_path, native_checkpoint: bool
+) -> None:
     parser = TrackingArgumentParser()
     subparsers = parser.add_subparsers(dest="subcommand")
     cmd = OmniServeCommand()
     cmd.subparser_init(subparsers)
-    args = parser.parse_args(["serve", "fake-diffusion-model", "--omni", "--api-server-count", "2"])
+    argv = ["serve", "fake-diffusion-model", "--omni", "--api-server-count", "2"]
+    if native_checkpoint:
+        checkpoint = tmp_path / "anima.safetensors"
+        checkpoint.touch()
+        argv[1] = str(checkpoint)
+        argv.extend(["--model-class-name", "AnimaPipeline"])
+    args = parser.parse_args(argv)
 
-    mocker.patch("vllm_omni.diffusion.utils.hf_utils.is_diffusion_model", return_value=True)
+    mocker.patch("vllm_omni.diffusion.utils.hf_utils.is_diffusion_model", return_value=not native_checkpoint)
     validate = mocker.patch("vllm_omni.entrypoints.cli.serve.validate_parsed_serve_args")
 
     with pytest.raises(ValueError, match="not supported for diffusion"):
diff --git a/tests/entrypoints/test_utils.py b/tests/entrypoints/test_utils.py
index 65395265b9e..338df483358 100644
--- a/tests/entrypoints/test_utils.py
+++ b/tests/entrypoints/test_utils.py
@@ -303,6 +303,70 @@ def test_filters_omni_diffusion_config_union_dataclass(self):
 
 
 class TestResolveOmniConfig:
+    @pytest.mark.parametrize("model_class_name", ["AnimaPipeline", "AnimaModularPipeline"])
+    def test_native_anima_checkpoint_uses_default_diffusion_stage_without_model_config(
+        self, tmp_path, mocker: MockerFixture, model_class_name: str
+    ):
+        checkpoint = tmp_path / "anima.safetensors"
+        checkpoint.write_text("dummy")
+        custom_args = {"components_path": "/tmp/anima-components"}
+        mocker.patch(
+            "vllm_omni.config.resolver.StageConfigFactory.create_from_model",
+            side_effect=AssertionError("native Anima checkpoints should not require model config discovery"),
+        )
+
+        resolved = resolve_omni_config(
+            str(checkpoint),
+            trust_remote_code=False,
+            deploy_config_path=None,
+            cli_overrides={"model_class_name": model_class_name, "custom_pipeline_args": custom_args},
+            stage_overrides=None,
+            strategy_config_path=None,
+        )
+
+        assert resolved.config_path is None
+        assert len(resolved.stage_configs) == 1
+        stage_config = resolved.stage_configs[0]
+        assert stage_config.model_stage == "diffusion"
+        assert stage_config.diffusion_config.model_class_name == "AnimaPipeline"
+        assert stage_config.diffusion_config.custom_pipeline_args == custom_args
+
+    @pytest.mark.parametrize(
+        ("model_class_name", "checkpoint_exists", "deploy_config_path"),
+        [
+            ("AnimaPipeline", True, "deploy.yaml"),
+            ("AnimaPipeline", False, None),
+            ("FluxPipeline", True, None),
+        ],
+    )
+    def test_native_single_file_fallback_preserves_config_discovery(
+        self, tmp_path, mocker: MockerFixture, model_class_name, checkpoint_exists, deploy_config_path
+    ):
+        checkpoint = tmp_path / "model.safetensors"
+        if checkpoint_exists:
+            checkpoint.write_text("dummy")
+        create_from_model = mocker.patch(
+            "vllm_omni.config.resolver.StageConfigFactory.create_from_model", return_value=None
+        )
+
+        resolved = resolve_omni_config(
+            str(checkpoint),
+            trust_remote_code=False,
+            deploy_config_path=deploy_config_path,
+            cli_overrides={"model_class_name": model_class_name},
+            stage_overrides=None,
+            strategy_config_path=None,
+        )
+
+        create_from_model.assert_called_once_with(
+            str(checkpoint),
+            trust_remote_code=False,
+            cli_overrides={"model_class_name": model_class_name, "trust_remote_code": False},
+            deploy_config_path=deploy_config_path,
+            strategy_specs=None,
+        )
+        assert resolved.config_path == deploy_config_path
+
     def test_bare_deploy_name_returns_packaged_resolved_path(self, tmp_path, mocker: MockerFixture):
         deploy_name = "qwen3_omni_moe.yaml"
         deploy_path = tmp_path / deploy_name
diff --git a/tests/helpers/tests/test_check_test_marks.py b/tests/helpers/tests/test_check_test_marks.py
new file mode 100644
index 00000000000..8b29b6f3323
--- /dev/null
+++ b/tests/helpers/tests/test_check_test_marks.py
@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import pytest
+
+from tools.pre_commit import check_test_marks
+
+pytestmark = [pytest.mark.cpu, pytest.mark.core_model]
+
+
+@pytest.mark.parametrize("kind", ["offline", "online"])
+def test_common_diffusion_marks_are_checked_in_helper(kind, monkeypatch):
+    path = f"tests/model_tests/diffusion/test_common_{kind}.py"
+    assert check_test_marks.get_files_missing_markers([path]) == {}
+
+    read_file = check_test_marks.read_test_file
+    monkeypatch.setattr(
+        check_test_marks,
+        "read_test_file",
+        lambda filename: "" if filename.endswith("case_filtering.py") else read_file(filename),
+    )
+    assert check_test_marks.get_files_missing_markers([path]) == {path: ["Level", "Hardware"]}
+
+
+def test_unrelated_tests_cannot_inherit_diffusion_marks(monkeypatch):
+    path = "tests/test_missing_marks.py"
+    monkeypatch.setattr(check_test_marks, "read_test_file", lambda filename: "get_parametrized_options(settings)")
+    assert check_test_marks.get_files_missing_markers([path]) == {path: ["Level", "Hardware"]}
diff --git a/tests/model_tests/conftest.py b/tests/model_tests/conftest.py
index 7760fa25db5..28cfa8891af 100644
--- a/tests/model_tests/conftest.py
+++ b/tests/model_tests/conftest.py
@@ -1,3 +1,6 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 import json
 from shutil import rmtree
 
@@ -12,7 +15,7 @@ def tiny_model_paths(request, run_level, tmp_path_factory):
     """Build or download the tiny models for the selected tests.
 
     At core_model level, builds tiny models via the builder function.
-    At advanced_model / full_model level, uses the real HF model path.
+    At advanced_model / full_model level, uses the real HF model path or asset resolver.
 
     NOTE: this is session scoped to avoid churn in tiny model creation,
     but will ensure all the tiny models you need are created for the selected tests
@@ -45,7 +48,11 @@ def tiny_model_paths(request, run_level, tmp_path_factory):
                             built_paths.append(path)
                         else:
                             print(f"Run level is {run_level}; {model_name} will use the full model")
-                            path = settings.model
+                            if callable(settings.model):
+                                path = settings.model()
+                                built_paths.append(path)
+                            else:
+                                path = settings.model
                         model_paths[model_name] = path
                 data_file.write_text(json.dumps(model_paths))
 
diff --git a/tests/model_tests/diffusion/anima_builder.py b/tests/model_tests/diffusion/anima_builder.py
new file mode 100644
index 00000000000..ca0f9e29a54
--- /dev/null
+++ b/tests/model_tests/diffusion/anima_builder.py
@@ -0,0 +1,116 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Local random-weight Anima assets and real-checkpoint assets for common tests."""
+
+import json
+import tempfile
+from pathlib import Path
+
+import torch
+from diffusers import AutoencoderKLQwenImage, FlowMatchEulerDiscreteScheduler
+from huggingface_hub import hf_hub_download, snapshot_download
+from safetensors.torch import save_file
+from tokenizers import Tokenizer
+from tokenizers.models import Unigram, WordLevel
+from tokenizers.pre_tokenizers import Whitespace
+from tokenizers.processors import TemplateProcessing
+from transformers import PreTrainedTokenizerFast, Qwen3Config, Qwen3Model, T5TokenizerFast
+
+from vllm_omni.diffusion.models.anima.anima_text_conditioner import (
+    ANIMA_TEXT_CONDITIONER_CONFIG,
+    AnimaTextConditioner,
+)
+from vllm_omni.diffusion.models.anima.anima_transformer import ANIMA_TRANSFORMER_CONFIG, AnimaTransformer3DModel
+
+CHECKPOINT_FILENAME = "anima.safetensors"
+
+
+def tiny_anima_builder() -> str:
+    """Build all components locally, without downloading any model weights or tokenizers."""
+    model_dir = Path(tempfile.mkdtemp(prefix="tiny-anima-"))
+    transformer_config = {
+        **ANIMA_TRANSFORMER_CONFIG,
+        "num_attention_heads": 2,
+        "attention_head_dim": 32,
+        "num_layers": 1,
+        "mlp_ratio": 1.0,
+        "text_embed_dim": 32,
+        "adaln_lora_dim": 8,
+        "max_size": (1, 64, 64),
+    }
+    conditioner_config = {
+        **ANIMA_TEXT_CONDITIONER_CONFIG,
+        "source_dim": 32,
+        "target_dim": 32,
+        "model_dim": 32,
+        "num_layers": 1,
+        "num_attention_heads": 2,
+        "mlp_ratio": 1.0,
+        "target_vocab_size": 8,
+        "min_sequence_length": 8,
+    }
+    transformer = AnimaTransformer3DModel(**transformer_config).to(torch.bfloat16)
+    conditioner = AnimaTextConditioner(**conditioner_config).to(torch.bfloat16)
+    save_file(
+        {
+            **{f"transformer.{name}": tensor for name, tensor in transformer.state_dict().items()},
+            **{f"text_conditioner.{name}": tensor for name, tensor in conditioner.state_dict().items()},
+        },
+        str(model_dir / CHECKPOINT_FILENAME),
+    )
+    (model_dir / "anima.json").write_text(
+        json.dumps({"transformer": transformer_config, "text_conditioner": conditioner_config})
+    )
+    Qwen3Model(
+        Qwen3Config(
+            vocab_size=8,
+            hidden_size=32,
+            intermediate_size=64,
+            num_hidden_layers=1,
+            num_attention_heads=2,
+            num_key_value_heads=2,
+            head_dim=16,
+        )
+    ).to(torch.bfloat16).save_pretrained(model_dir / "text_encoder")
+    AutoencoderKLQwenImage(
+        base_dim=4,
+        z_dim=16,
+        dim_mult=[1, 1, 1, 1],
+        num_res_blocks=1,
+        latents_mean=[0.0] * 16,
+        latents_std=[1.0] * 16,
+    ).to(torch.bfloat16).save_pretrained(model_dir / "vae")
+    tokenizer = Tokenizer(WordLevel({"<pad>": 0, "</s>": 1, "<unk>": 2, "Dummy": 3, "prompt": 4}, unk_token="<unk>"))
+    tokenizer.pre_tokenizer = Whitespace()
+    tokenizer.post_processor = TemplateProcessing(single="$A </s>", special_tokens=[("</s>", 1)])
+    PreTrainedTokenizerFast(
+        tokenizer_object=tokenizer, pad_token="<pad>", eos_token="</s>", unk_token="<unk>"
+    ).save_pretrained(model_dir / "tokenizer")
+    t5_tokenizer = Tokenizer(
+        Unigram(
+            [("<pad>", 0.0), ("</s>", 0.0), ("<unk>", 0.0), ("▁", -1.0), ("Dummy", -1.0), ("prompt", -1.0)], unk_id=2
+        )
+    )
+    T5TokenizerFast(tokenizer_object=t5_tokenizer, extra_ids=0).save_pretrained(model_dir / "t5_tokenizer")
+    FlowMatchEulerDiscreteScheduler(shift=3.0).save_pretrained(model_dir / "scheduler")
+    return str(model_dir)
+
+
+def real_anima_model() -> str:
+    """Keep cached real assets intact; return a disposable directory of links."""
+    components = Path(
+        snapshot_download(
+            "circlestone-labs/Anima-Base-v1.0-Diffusers",
+            allow_patterns=["text_encoder/*", "vae/*", "tokenizer/*", "t5_tokenizer/*", "scheduler/*"],
+        )
+    )
+    checkpoint = hf_hub_download(
+        "circlestone-labs/Anima", filename="split_files/diffusion_models/anima-base-v1.0.safetensors"
+    )
+    model_dir = Path(tempfile.mkdtemp(prefix="real-anima-"))
+    (model_dir / CHECKPOINT_FILENAME).symlink_to(checkpoint)
+    for name in ("text_encoder", "vae", "tokenizer", "t5_tokenizer", "scheduler"):
+        if (components / name).is_dir():
+            (model_dir / name).symlink_to(components / name, target_is_directory=True)
+    return str(model_dir)
diff --git a/tests/model_tests/diffusion/config_types.py b/tests/model_tests/diffusion/config_types.py
index 634036ed48d..8b66af19163 100644
--- a/tests/model_tests/diffusion/config_types.py
+++ b/tests/model_tests/diffusion/config_types.py
@@ -1,10 +1,13 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 """
 Common definitions for controlling what tests run where.
 """
 
 from collections.abc import Callable
 from enum import Enum
-from typing import NamedTuple, TypeAlias
+from typing import Any, NamedTuple, TypeAlias
 
 from pytest import MarkDecorator
 
@@ -45,7 +48,9 @@ class DiffusionModelTestOpts(NamedTuple):
     # HF model name for real-weight tests (advanced_model / full_model level).
     # For now, whether we use the real weights vs tiny weights in the common tests
     # depends on the run level.
-    model: str
+    # A callable may assemble native assets in a temporary directory; the fixture
+    # removes that directory after the tests, so it must not return a cache root.
+    model: str | Callable[[], str]
 
     # Creates a tiny model for the given architecture. We should always use tiny
     # model weights for tests that do not require us to check the model quality.
@@ -81,9 +86,12 @@ class DiffusionModelTestOpts(NamedTuple):
     # set False for pipelines that mandate an image and fail closed without one (SANA-Video I2V).
     check_i2v_t2v_divergence: bool = True
 
+    # Native single-file models: builders/resolvers return the containing directory.
+    checkpoint_filename: str | None = None
+
 
 ### Mappings & utils for building offline Omni() instances given a list of enabled accelerations
-ACC_OMNI_KWARGS = {
+ACC_OMNI_KWARGS: dict[DiffusionAccs, dict[str, Any]] = {
     DiffusionAccs.VAE_PATCH_PARALLEL: {"vae_use_tiling": True},
     DiffusionAccs.CPU_OFFLOAD: {"enable_cpu_offload": True},
     DiffusionAccs.LAYERWISE_OFFLOAD: {"enable_layerwise_offload": True},
diff --git a/tests/model_tests/diffusion/model_settings.py b/tests/model_tests/diffusion/model_settings.py
index 083dba0ed57..8c5955c8de1 100644
--- a/tests/model_tests/diffusion/model_settings.py
+++ b/tests/model_tests/diffusion/model_settings.py
@@ -1,4 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 from tests.model_tests.diffusion import diff_model_builders
+from tests.model_tests.diffusion.anima_builder import CHECKPOINT_FILENAME, real_anima_model, tiny_anima_builder
 from tests.model_tests.diffusion.config_types import (
     DiffusionAccs,
     DiffusionModelTestOpts,
@@ -29,6 +33,12 @@
 # $ pytest test_common_offline.py -k test_pipeline_on_supported_tasks[Flux2KleinPipeline
 #   ^ Runs all test groups for Flux2KleinPipeline only
 DIFFUSION_TEST_SETTINGS = {
+    "AnimaPipeline": DiffusionModelTestOpts(
+        model=real_anima_model,
+        builder=tiny_anima_builder,
+        supported_tasks=[DiffusionTasks.TEXT_TO_IMAGE],
+        checkpoint_filename=CHECKPOINT_FILENAME,
+    ),
     "Flux2KleinPipeline": DiffusionModelTestOpts(
         model="black-forest-labs/FLUX.2-klein-4B",
         builder=diff_model_builders.tiny_flux2_klein_builder,
diff --git a/tests/model_tests/diffusion/test_common_offline.py b/tests/model_tests/diffusion/test_common_offline.py
index 9cecc31fd0e..b610ed013bd 100644
--- a/tests/model_tests/diffusion/test_common_offline.py
+++ b/tests/model_tests/diffusion/test_common_offline.py
@@ -1,6 +1,8 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
 
+from pathlib import Path
+
 import pytest
 
 from tests.model_tests.diffusion.case_filtering import get_parametrized_options
@@ -47,10 +49,17 @@ def test_pipeline_on_supported_tasks(
     # since starting the server can take 10+ seconds, even for tiny models.
     #
     # NOTE: Be sure to install pytest-subtests if you're running on pytest < 9
+    settings = DIFFUSION_TEST_SETTINGS[model_name]
+    model_path = tiny_model_paths[model_name]
+    model_kwargs = {}
+    if settings.checkpoint_filename is not None:
+        model_path = str(Path(model_path) / settings.checkpoint_filename)
+        model_kwargs["model_class_name"] = model_name
     omni = build_omni_from_diff_accelerations(
         accelerations=accelerations,
-        model=tiny_model_paths[model_name],
+        model=model_path,
         enforce_eager=True,
+        **model_kwargs,
     )
     try:
         for task_type in supported_tasks:
diff --git a/tests/model_tests/diffusion/test_common_online.py b/tests/model_tests/diffusion/test_common_online.py
index ed7f0e2fa65..ef444950136 100644
--- a/tests/model_tests/diffusion/test_common_online.py
+++ b/tests/model_tests/diffusion/test_common_online.py
@@ -7,6 +7,8 @@
 encoding) using tiny models.
 """
 
+from pathlib import Path
+
 import pytest
 from xdist import is_xdist_worker
 
@@ -68,6 +70,10 @@ def test_online_on_supported_tasks(
     model_path = tiny_model_paths[model_name]
     server_args = build_server_args_from_diff_accelerations(accelerations)
     server_args.append("--enforce-eager")
+    settings = DIFFUSION_TEST_SETTINGS[model_name]
+    if settings.checkpoint_filename is not None:
+        model_path = str(Path(model_path) / settings.checkpoint_filename)
+        server_args.extend(["--model-class-name", model_name])
 
     with OmniServer(model_path, server_args) as server:
         # TODO: We may want to revisit run_level validation here,
diff --git a/tests/model_tests/diffusion/test_native_model_settings.py b/tests/model_tests/diffusion/test_native_model_settings.py
new file mode 100644
index 00000000000..10db75d0567
--- /dev/null
+++ b/tests/model_tests/diffusion/test_native_model_settings.py
@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from contextlib import nullcontext
+from pathlib import Path
+from shutil import rmtree
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+
+from tests.model_tests.diffusion import anima_builder, test_common_offline, test_common_online
+from tests.model_tests.diffusion.config_types import DiffusionTasks
+
+pytestmark = [pytest.mark.cpu, pytest.mark.core_model, pytest.mark.diffusion]
+
+
+@pytest.mark.parametrize("model_name", ["AnimaPipeline", "FluxPipeline"])
+def test_common_runners_resolve_native_checkpoint(model_name, tmp_path, monkeypatch):
+    """Both entry points receive the file and class; directory models keep their existing arguments."""
+    paths = {model_name: str(tmp_path)}
+    subtests = SimpleNamespace(test=lambda **kwargs: nullcontext())
+    build_omni = MagicMock()
+    monkeypatch.setattr(test_common_offline, "build_omni_from_diff_accelerations", build_omni)
+    monkeypatch.setattr(test_common_offline, "run_and_validate_text_to_image_request", MagicMock())
+    test_common_offline.test_pipeline_on_supported_tasks(
+        model_name, None, [DiffusionTasks.TEXT_TO_IMAGE], False, False, False, paths, subtests
+    )
+    server = MagicMock()
+    monkeypatch.setattr(test_common_online, "OmniServer", server)
+    monkeypatch.setattr(test_common_online, "OnlineOmniClient", MagicMock())
+    monkeypatch.setattr(test_common_online, "run_and_validate_online_text_to_image_request", MagicMock())
+    test_common_online.test_online_on_supported_tasks(
+        model_name, None, [DiffusionTasks.TEXT_TO_IMAGE], False, False, paths, "core_model", subtests
+    )
+    if model_name == "AnimaPipeline":
+        checkpoint = str(tmp_path / anima_builder.CHECKPOINT_FILENAME)
+        build_omni.assert_called_once_with(
+            accelerations=None, model=checkpoint, enforce_eager=True, model_class_name=model_name
+        )
+        server.assert_called_once_with(checkpoint, ["--enforce-eager", "--model-class-name", model_name])
+    else:
+        build_omni.assert_called_once_with(accelerations=None, model=str(tmp_path), enforce_eager=True)
+        server.assert_called_once_with(str(tmp_path), ["--enforce-eager"])
+
+
+def test_real_anima_assets_leave_cache_intact(tmp_path, monkeypatch):
+    """The fixture may delete the assembled directory without deleting cached model assets."""
+    components = tmp_path / "components"
+    for name in ("text_encoder", "vae", "tokenizer", "t5_tokenizer"):
+        (components / name).mkdir(parents=True)
+        (components / name / "asset").write_text(name)
+    checkpoint = tmp_path / "real.safetensors"
+    checkpoint.write_bytes(b"checkpoint")
+    monkeypatch.setattr(anima_builder, "snapshot_download", lambda *args, **kwargs: str(components))
+    monkeypatch.setattr(anima_builder, "hf_hub_download", lambda *args, **kwargs: str(checkpoint))
+    directory = Path(anima_builder.real_anima_model())
+    try:
+        assert (directory / anima_builder.CHECKPOINT_FILENAME).read_bytes() == b"checkpoint"
+        assert (directory / "vae" / "asset").read_text() == "vae"
+        # Missing scheduler is supported by Anima's default scheduler fallback.
+        assert not (directory / "scheduler").exists()
+    finally:
+        rmtree(directory)
+    assert checkpoint.read_bytes() == b"checkpoint"
+    assert (components / "vae" / "asset").read_text() == "vae"
diff --git a/tests/model_tests/diffusion/utils.py b/tests/model_tests/diffusion/utils.py
index 35577b68f28..137eae12358 100644
--- a/tests/model_tests/diffusion/utils.py
+++ b/tests/model_tests/diffusion/utils.py
@@ -1,8 +1,12 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
 """
 Utilities for resolving real models to their tiny model equivalents.
 """
 
 import logging
+from pathlib import Path
 
 from tests.model_tests.diffusion.model_settings import DIFFUSION_TEST_SETTINGS
 from vllm_omni.diffusion.data import resolve_model_class_name
@@ -30,4 +34,7 @@ def resolve_tiny_model_path(model: str) -> str:
         )
         return model
 
-    return test_opts.builder()
+    model_path = test_opts.builder()
+    if test_opts.checkpoint_filename is not None:
+        return str(Path(model_path) / test_opts.checkpoint_filename)
+    return model_path
diff --git a/tools/pre_commit/check_test_marks.py b/tools/pre_commit/check_test_marks.py
index 6af0ae82546..2d84039def8 100644
--- a/tools/pre_commit/check_test_marks.py
+++ b/tools/pre_commit/check_test_marks.py
@@ -33,6 +33,12 @@
 # The helper implementation is the only file allowed to write pytest.mark.<SKU>.
 _ALLOWED_DIRECT_SKU_FILES = frozenset({"tests/helpers/mark.py"})
 
+# Common diffusion tests receive per-case marks from this parametrization helper.
+_DELEGATED_MARK_SOURCES = {
+    "tests/model_tests/diffusion/test_common_offline.py": "tests/model_tests/diffusion/case_filtering.py",
+    "tests/model_tests/diffusion/test_common_online.py": "tests/model_tests/diffusion/case_filtering.py",
+}
+
 # Match mark.X since we could also do `from pytest import mark`.
 # \b prevents matching prefixes (e.g., mark.slow vs mark.slow_test).
 HELPER_RE = re.compile(r"(?:" + "|".join(HARDWARE_HELPERS) + r")\s*\(")
@@ -146,6 +152,9 @@ def get_files_missing_markers(
             missing = []
             if has_direct_sku_marker(path, contents):
                 missing.append(DIRECT_SKU_MARKER)
+            mark_source = _DELEGATED_MARK_SOURCES.get(_normalize_path(path))
+            if mark_source is not None and "get_parametrized_options(" in contents:
+                contents += "\n" + (read_test_file(str(_repo_root() / mark_source)) or "")
             if not has_level_marker(contents):
                 missing.append(MISSING_LEVEL_MARKER)
             if not has_hardware_marker(contents):
diff --git a/vllm_omni/config/resolver.py b/vllm_omni/config/resolver.py
index 0db43676881..76740aa0613 100644
--- a/vllm_omni/config/resolver.py
+++ b/vllm_omni/config/resolver.py
@@ -5,6 +5,7 @@
 
 from collections.abc import Mapping
 from dataclasses import dataclass, fields, is_dataclass
+from pathlib import Path
 from typing import Any
 
 from vllm.logger import init_logger
@@ -15,7 +16,7 @@
 from vllm_omni.config.omni_config import VllmOmniConfig
 from vllm_omni.config.stage_config import PipelineConfig
 from vllm_omni.diffusion.data import resolve_model_class_name
-from vllm_omni.diffusion.registry import DiffusionModelRegistry
+from vllm_omni.diffusion.registry import DiffusionModelRegistry, resolve_native_single_file
 from vllm_omni.diffusion.utils.hf_utils import is_diffusion_model
 
 logger = init_logger(__name__)
@@ -204,17 +205,24 @@ def resolve_omni_config(
     """Resolve registry/deploy inputs through the single public entrypoint."""
     normalized_overrides = _convert_dataclasses_to_dict(dict(cli_overrides or {}))
     normalized_overrides = with_trust_remote_code_override(normalized_overrides, trust_remote_code)
+    native_single_file_model = resolve_native_single_file(normalized_overrides.get("model_class_name"))
+    is_native_single_file = native_single_file_model is not None and Path(model).is_file()
+    if is_native_single_file:
+        normalized_overrides["model_class_name"] = native_single_file_model
     registry_overrides = dict(normalized_overrides)
     _flatten_stage_overrides(registry_overrides, stage_overrides)
 
     strategy_specs = _load_strategy_specs(strategy_config_path)
-    structured_config = StageConfigFactory.create_from_model(
-        model,
-        trust_remote_code=trust_remote_code,
-        cli_overrides=registry_overrides,
-        deploy_config_path=deploy_config_path,
-        strategy_specs=strategy_specs,
-    )
+    structured_config = None
+    # Native checkpoint files have no HF config or pipeline index to discover.
+    if deploy_config_path is not None or not is_native_single_file:
+        structured_config = StageConfigFactory.create_from_model(
+            model,
+            trust_remote_code=trust_remote_code,
+            cli_overrides=registry_overrides,
+            deploy_config_path=deploy_config_path,
+            strategy_specs=strategy_specs,
+        )
     if structured_config is not None:
         return _build_registered_resolution(structured_config)
 
diff --git a/vllm_omni/diffusion/data.py b/vllm_omni/diffusion/data.py
index 5bc5a229bfd..e19470fa530 100644
--- a/vllm_omni/diffusion/data.py
+++ b/vllm_omni/diffusion/data.py
@@ -1379,6 +1379,10 @@ def __post_init__(self):
                     self.model,
                 )
 
+    @property
+    def is_single_file(self) -> bool:
+        return isinstance(self.model, str) and os.path.isfile(self.model)
+
     def _propagate_quantization_from_tf_config(self, tf_config: "TransformerConfig") -> None:
         if tf_config.quant_config is None:
             return
@@ -1483,12 +1487,22 @@ def enrich_config(self) -> None:
         """
         from vllm.transformers_utils.config import get_hf_file_to_dict
 
+        from vllm_omni.diffusion.registry import resolve_native_single_file
         from vllm_omni.diffusion.utils.hf_utils import (
             get_diffusion_model_index,
             resolve_native_diffusion_model_class,
         )
 
         assert self.model is not None
+
+        native_single_file_model = resolve_native_single_file(self.model_class_name)
+        if self.is_single_file and native_single_file_model is not None:
+            self.diffusion_load_format = "default"
+            self.model_class_name = native_single_file_model
+            self.diffusers_pipeline_cls = None
+            self.set_tf_model_config(TransformerConfig())
+            return
+
         try:
             config_dict = get_diffusion_model_index(
                 self.model,
diff --git a/vllm_omni/diffusion/models/anima/__init__.py b/vllm_omni/diffusion/models/anima/__init__.py
new file mode 100644
index 00000000000..ddbabbcee18
--- /dev/null
+++ b/vllm_omni/diffusion/models/anima/__init__.py
@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from vllm_omni.diffusion.models.anima.pipeline_anima import AnimaPipeline
+
+__all__ = [
+    "AnimaPipeline",
+]
diff --git a/vllm_omni/diffusion/models/anima/anima_text_conditioner.py b/vllm_omni/diffusion/models/anima/anima_text_conditioner.py
new file mode 100644
index 00000000000..84c3e4a2c00
--- /dev/null
+++ b/vllm_omni/diffusion/models/anima/anima_text_conditioner.py
@@ -0,0 +1,321 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from collections.abc import Iterable
+from types import SimpleNamespace
+from typing import Any
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from vllm.model_executor.model_loader.weight_utils import default_weight_loader
+
+from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
+from vllm_omni.diffusion.attention.layer import Attention
+
+ANIMA_TEXT_CONDITIONER_CONFIG = {
+    "source_dim": 1024,
+    "target_dim": 1024,
+    "model_dim": 1024,
+    "num_layers": 6,
+    "num_attention_heads": 16,
+    "mlp_ratio": 4.0,
+    "target_vocab_size": 32128,
+    "use_self_attention": True,
+    "use_layer_norm": False,
+    "min_sequence_length": 512,
+}
+
+
+def _rotate_half(hidden_states: torch.Tensor) -> torch.Tensor:
+    hidden_states_1 = hidden_states[..., : hidden_states.shape[-1] // 2]
+    hidden_states_2 = hidden_states[..., hidden_states.shape[-1] // 2 :]
+    return torch.cat((-hidden_states_2, hidden_states_1), dim=-1)
+
+
+def _apply_rotary_pos_emb(
+    hidden_states: torch.Tensor,
+    cos: torch.Tensor,
+    sin: torch.Tensor,
+    unsqueeze_dim: int = 1,
+) -> torch.Tensor:
+    cos = cos.unsqueeze(unsqueeze_dim)
+    sin = sin.unsqueeze(unsqueeze_dim)
+    return (hidden_states * cos) + (_rotate_half(hidden_states) * sin)
+
+
+class AnimaRotaryEmbedding(nn.Module):
+    def __init__(self, head_dim: int, rope_theta: float = 10000.0) -> None:
+        super().__init__()
+        inv_freq = 1.0 / (
+            rope_theta ** (torch.arange(0, head_dim, 2, dtype=torch.int64).to(dtype=torch.float32) / head_dim)
+        )
+        self.register_buffer("inv_freq", inv_freq, persistent=False)
+
+    def forward(self, hidden_states: torch.Tensor, position_ids: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        inv_freq_expanded = self.inv_freq[None, :, None].float().expand(position_ids.shape[0], -1, 1)
+        inv_freq_expanded = inv_freq_expanded.to(hidden_states.device)
+        position_ids_expanded = position_ids[:, None, :].float()
+
+        freqs = (inv_freq_expanded @ position_ids_expanded).transpose(1, 2)
+        emb = torch.cat((freqs, freqs), dim=-1)
+        cos = emb.cos()
+        sin = emb.sin()
+        return cos.to(dtype=hidden_states.dtype), sin.to(dtype=hidden_states.dtype)
+
+
+class AnimaTextConditionerAttention(nn.Module):
+    def __init__(
+        self,
+        query_dim: int,
+        context_dim: int,
+        num_attention_heads: int,
+        attention_head_dim: int,
+        prefix: str = "",
+    ) -> None:
+        super().__init__()
+        inner_dim = num_attention_heads * attention_head_dim
+
+        self.num_attention_heads = num_attention_heads
+        self.attention_head_dim = attention_head_dim
+        self.q_proj = nn.Linear(query_dim, inner_dim, bias=False)
+        self.q_norm = nn.RMSNorm(attention_head_dim, eps=1e-6)
+        self.k_proj = nn.Linear(context_dim, inner_dim, bias=False)
+        self.k_norm = nn.RMSNorm(attention_head_dim, eps=1e-6)
+        self.v_proj = nn.Linear(context_dim, inner_dim, bias=False)
+        self.o_proj = nn.Linear(inner_dim, query_dim, bias=False)
+        self.attn = Attention(
+            num_heads=num_attention_heads,
+            head_size=attention_head_dim,
+            softmax_scale=1.0 / (attention_head_dim**0.5),
+            causal=False,
+            num_kv_heads=num_attention_heads,
+            prefix=prefix,
+        )
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        attention_mask: torch.Tensor | None = None,
+        encoder_hidden_states: torch.Tensor | None = None,
+        position_embeddings: tuple[torch.Tensor, torch.Tensor] | None = None,
+        encoder_position_embeddings: tuple[torch.Tensor, torch.Tensor] | None = None,
+    ) -> torch.Tensor:
+        encoder_hidden_states = hidden_states if encoder_hidden_states is None else encoder_hidden_states
+        input_shape = hidden_states.shape[:-1]
+        encoder_input_shape = encoder_hidden_states.shape[:-1]
+
+        query = self.q_proj(hidden_states)
+        key = self.k_proj(encoder_hidden_states)
+        value = self.v_proj(encoder_hidden_states)
+
+        query = query.view(*input_shape, self.num_attention_heads, self.attention_head_dim)
+        key = key.view(*encoder_input_shape, self.num_attention_heads, self.attention_head_dim)
+        value = value.view(*encoder_input_shape, self.num_attention_heads, self.attention_head_dim)
+
+        query = self.q_norm(query)
+        key = self.k_norm(key)
+
+        if position_embeddings is not None:
+            if encoder_position_embeddings is None:
+                raise ValueError("encoder_position_embeddings is required with rotary embeddings.")
+            cos, sin = position_embeddings
+            query = _apply_rotary_pos_emb(query, cos, sin, unsqueeze_dim=2)
+            cos, sin = encoder_position_embeddings
+            key = _apply_rotary_pos_emb(key, cos, sin, unsqueeze_dim=2)
+
+        attn_metadata = AttentionMetadata(attn_mask=attention_mask) if attention_mask is not None else None
+        hidden_states = self.attn(query, key, value, attn_metadata=attn_metadata)
+        hidden_states = hidden_states.flatten(2, 3).contiguous()
+        return self.o_proj(hidden_states)
+
+
+class AnimaTextConditionerBlock(nn.Module):
+    def __init__(
+        self,
+        source_dim: int,
+        model_dim: int,
+        num_attention_heads: int = 16,
+        mlp_ratio: float = 4.0,
+        use_self_attention: bool = True,
+        use_layer_norm: bool = False,
+        prefix: str = "",
+    ) -> None:
+        super().__init__()
+        self.use_self_attention = use_self_attention
+        norm_cls = nn.LayerNorm if use_layer_norm else nn.RMSNorm
+        norm_kwargs = {} if use_layer_norm else {"eps": 1e-6}
+
+        if use_self_attention:
+            self.norm_self_attn = norm_cls(model_dim, **norm_kwargs)
+            self.self_attn = AnimaTextConditionerAttention(
+                query_dim=model_dim,
+                context_dim=model_dim,
+                num_attention_heads=num_attention_heads,
+                attention_head_dim=model_dim // num_attention_heads,
+                prefix=f"{prefix}.self_attn" if prefix else "self_attn",
+            )
+
+        self.norm_cross_attn = norm_cls(model_dim, **norm_kwargs)
+        self.cross_attn = AnimaTextConditionerAttention(
+            query_dim=model_dim,
+            context_dim=source_dim,
+            num_attention_heads=num_attention_heads,
+            attention_head_dim=model_dim // num_attention_heads,
+            prefix=f"{prefix}.cross_attn" if prefix else "cross_attn",
+        )
+        self.norm_mlp = norm_cls(model_dim, **norm_kwargs)
+        self.mlp = nn.Sequential(
+            nn.Linear(model_dim, int(model_dim * mlp_ratio)),
+            nn.GELU(),
+            nn.Linear(int(model_dim * mlp_ratio), model_dim),
+        )
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: torch.Tensor,
+        target_attention_mask: torch.Tensor | None = None,
+        source_attention_mask: torch.Tensor | None = None,
+        position_embeddings: tuple[torch.Tensor, torch.Tensor] | None = None,
+        source_position_embeddings: tuple[torch.Tensor, torch.Tensor] | None = None,
+    ) -> torch.Tensor:
+        if self.use_self_attention:
+            norm_hidden_states = self.norm_self_attn(hidden_states)
+            attn_hidden_states = self.self_attn(
+                norm_hidden_states,
+                attention_mask=target_attention_mask,
+                position_embeddings=position_embeddings,
+                encoder_position_embeddings=position_embeddings,
+            )
+            hidden_states = hidden_states + attn_hidden_states
+
+        norm_hidden_states = self.norm_cross_attn(hidden_states)
+        attn_hidden_states = self.cross_attn(
+            norm_hidden_states,
+            attention_mask=source_attention_mask,
+            encoder_hidden_states=encoder_hidden_states,
+            position_embeddings=position_embeddings,
+            encoder_position_embeddings=source_position_embeddings,
+        )
+        hidden_states = hidden_states + attn_hidden_states
+        hidden_states = hidden_states + self.mlp(self.norm_mlp(hidden_states))
+        return hidden_states
+
+
+def is_conditioner_block_module(name: str, module: nn.Module) -> bool:
+    return "blocks" in name and name.split(".")[-1].isdigit()
+
+
+class AnimaTextConditioner(nn.Module):
+    _repeated_blocks = ["AnimaTextConditionerBlock"]
+    _hsdp_shard_conditions = [is_conditioner_block_module]
+
+    def __init__(
+        self,
+        source_dim: int = 1024,
+        target_dim: int = 1024,
+        model_dim: int = 1024,
+        num_layers: int = 6,
+        num_attention_heads: int = 16,
+        mlp_ratio: float = 4.0,
+        target_vocab_size: int = 32128,
+        use_self_attention: bool = True,
+        use_layer_norm: bool = False,
+        min_sequence_length: int = 512,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__()
+        self.config = SimpleNamespace(
+            source_dim=source_dim,
+            target_dim=target_dim,
+            model_dim=model_dim,
+            num_layers=num_layers,
+            num_attention_heads=num_attention_heads,
+            mlp_ratio=mlp_ratio,
+            target_vocab_size=target_vocab_size,
+            use_self_attention=use_self_attention,
+            use_layer_norm=use_layer_norm,
+            min_sequence_length=min_sequence_length,
+            extra_config=kwargs,
+        )
+        self.embed = nn.Embedding(target_vocab_size, target_dim)
+        self.in_proj = nn.Linear(target_dim, model_dim) if model_dim != target_dim else nn.Identity()
+        self.rotary_emb = AnimaRotaryEmbedding(model_dim // num_attention_heads)
+        self.blocks = nn.ModuleList(
+            [
+                AnimaTextConditionerBlock(
+                    source_dim=source_dim,
+                    model_dim=model_dim,
+                    num_attention_heads=num_attention_heads,
+                    mlp_ratio=mlp_ratio,
+                    use_self_attention=use_self_attention,
+                    use_layer_norm=use_layer_norm,
+                    prefix=f"blocks.{i}",
+                )
+                for i in range(num_layers)
+            ]
+        )
+        self.out_proj = nn.Linear(model_dim, target_dim)
+        self.norm = nn.RMSNorm(target_dim, eps=1e-6)
+        self.gradient_checkpointing = False
+
+    @property
+    def dtype(self) -> torch.dtype:
+        return next(self.parameters()).dtype
+
+    @staticmethod
+    def _prepare_attention_mask(attention_mask: torch.Tensor | None) -> torch.Tensor | None:
+        if attention_mask is None:
+            return None
+        return attention_mask.to(torch.bool)
+
+    def forward(
+        self,
+        source_hidden_states: torch.Tensor,
+        target_input_ids: torch.Tensor,
+        target_attention_mask: torch.Tensor | None = None,
+        source_attention_mask: torch.Tensor | None = None,
+    ) -> torch.Tensor:
+        target_attention_mask = self._prepare_attention_mask(target_attention_mask)
+        source_attention_mask = self._prepare_attention_mask(source_attention_mask)
+
+        hidden_states = self.embed(target_input_ids).to(dtype=source_hidden_states.dtype)
+        hidden_states = self.in_proj(hidden_states)
+
+        position_ids = torch.arange(hidden_states.shape[1], device=hidden_states.device).unsqueeze(0)
+        source_position_ids = torch.arange(source_hidden_states.shape[1], device=hidden_states.device).unsqueeze(0)
+        position_embeddings = self.rotary_emb(hidden_states, position_ids)
+        source_position_embeddings = self.rotary_emb(hidden_states, source_position_ids)
+
+        for block in self.blocks:
+            hidden_states = block(
+                hidden_states,
+                source_hidden_states,
+                target_attention_mask=target_attention_mask,
+                source_attention_mask=source_attention_mask,
+                position_embeddings=position_embeddings,
+                source_position_embeddings=source_position_embeddings,
+            )
+
+        hidden_states = self.norm(self.out_proj(hidden_states))
+
+        if target_attention_mask is not None:
+            hidden_states = hidden_states * target_attention_mask.to(hidden_states).unsqueeze(-1)
+
+        if hidden_states.shape[1] < self.config.min_sequence_length:
+            hidden_states = F.pad(hidden_states, (0, 0, 0, self.config.min_sequence_length - hidden_states.shape[1]))
+
+        return hidden_states
+
+    def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
+        params = dict(self.named_parameters())
+        loaded = set()
+        for name, tensor in weights:
+            if name not in params:
+                continue
+            param = params[name]
+            weight_loader = getattr(param, "weight_loader", default_weight_loader)
+            weight_loader(param, tensor)
+            loaded.add(name)
+        return loaded
diff --git a/vllm_omni/diffusion/models/anima/anima_transformer.py b/vllm_omni/diffusion/models/anima/anima_transformer.py
new file mode 100644
index 00000000000..4c92a4ff390
--- /dev/null
+++ b/vllm_omni/diffusion/models/anima/anima_transformer.py
@@ -0,0 +1,705 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+from collections.abc import Iterable
+from types import SimpleNamespace
+from typing import Any
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from diffusers.models.embeddings import Timesteps, apply_rotary_emb
+from diffusers.models.modeling_outputs import Transformer2DModelOutput
+from vllm.model_executor.model_loader.weight_utils import default_weight_loader
+
+from vllm_omni.diffusion.attention.backends.abstract import AttentionMetadata
+from vllm_omni.diffusion.attention.layer import Attention
+from vllm_omni.diffusion.distributed.hsdp_utils import is_transformer_block_module
+
+ANIMA_TRANSFORMER_CONFIG = {
+    "in_channels": 16,
+    "out_channels": 16,
+    "num_attention_heads": 16,
+    "attention_head_dim": 128,
+    "num_layers": 28,
+    "mlp_ratio": 4.0,
+    "text_embed_dim": 1024,
+    "adaln_lora_dim": 256,
+    "max_size": (128, 240, 240),
+    "patch_size": (1, 2, 2),
+    "rope_scale": (1.0, 4.0, 4.0),
+    "concat_padding_mask": True,
+    "extra_pos_embed_type": None,
+}
+
+
+# NOTE: We import and use diffusers' `apply_rotary_emb` instead of a custom native implementation
+# to prevent numerical drift in bfloat16. Diffusers upcasts queries, keys, and rotary frequency
+# tensors to float32 before computing the rotation, and casts back to bfloat16 at the end.
+# Performing the entire computation in bfloat16 accumulates precision errors across the 28
+# transformer blocks, which is heavily amplified by Classifier-Free Guidance (CFG).
+
+
+class CosmosPatchEmbed(nn.Module):
+    def __init__(
+        self,
+        in_channels: int,
+        out_channels: int,
+        patch_size: tuple[int, int, int],
+        bias: bool = True,
+    ) -> None:
+        super().__init__()
+        self.patch_size = patch_size
+        self.proj = nn.Linear(in_channels * patch_size[0] * patch_size[1] * patch_size[2], out_channels, bias=bias)
+
+    def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
+        batch_size, num_channels, num_frames, height, width = hidden_states.shape
+        p_t, p_h, p_w = self.patch_size
+        hidden_states = hidden_states.reshape(
+            batch_size,
+            num_channels,
+            num_frames // p_t,
+            p_t,
+            height // p_h,
+            p_h,
+            width // p_w,
+            p_w,
+        )
+        hidden_states = hidden_states.permute(0, 2, 4, 6, 1, 3, 5, 7).flatten(4, 7)
+        return self.proj(hidden_states)
+
+
+class CosmosTimestepEmbedding(nn.Module):
+    def __init__(self, in_features: int, out_features: int) -> None:
+        super().__init__()
+        self.linear_1 = nn.Linear(in_features, out_features, bias=False)
+        self.activation = nn.SiLU()
+        self.linear_2 = nn.Linear(out_features, 3 * out_features, bias=False)
+
+    def forward(self, timesteps: torch.Tensor) -> torch.Tensor:
+        emb = self.linear_1(timesteps)
+        emb = self.activation(emb)
+        return self.linear_2(emb)
+
+
+class CosmosEmbedding(nn.Module):
+    def __init__(self, embedding_dim: int, condition_dim: int) -> None:
+        super().__init__()
+        self.time_proj = Timesteps(embedding_dim, flip_sin_to_cos=True, downscale_freq_shift=0.0)
+        self.t_embedder = CosmosTimestepEmbedding(embedding_dim, condition_dim)
+        self.norm = nn.RMSNorm(embedding_dim, eps=1e-6)
+
+    def forward(self, hidden_states: torch.Tensor, timestep: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]:
+        timesteps_proj = self.time_proj(timestep).type_as(hidden_states)
+        temb = self.t_embedder(timesteps_proj)
+        embedded_timestep = self.norm(timesteps_proj)
+        return temb, embedded_timestep
+
+
+class CosmosAdaLayerNorm(nn.Module):
+    def __init__(self, in_features: int, hidden_features: int) -> None:
+        super().__init__()
+        self.embedding_dim = in_features
+        self.activation = nn.SiLU()
+        self.norm = nn.LayerNorm(in_features, elementwise_affine=False, eps=1e-6)
+        self.linear_1 = nn.Linear(in_features, hidden_features, bias=False)
+        self.linear_2 = nn.Linear(hidden_features, 2 * in_features, bias=False)
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        embedded_timestep: torch.Tensor,
+        temb: torch.Tensor | None = None,
+    ) -> torch.Tensor:
+        embedded_timestep = self.activation(embedded_timestep)
+        embedded_timestep = self.linear_1(embedded_timestep)
+        embedded_timestep = self.linear_2(embedded_timestep)
+
+        if temb is not None:
+            embedded_timestep = embedded_timestep + temb[..., : 2 * self.embedding_dim]
+
+        shift, scale = embedded_timestep.chunk(2, dim=-1)
+        hidden_states = self.norm(hidden_states)
+
+        if embedded_timestep.ndim == 2:
+            shift, scale = (x.unsqueeze(1) for x in (shift, scale))
+
+        return hidden_states * (1 + scale) + shift
+
+
+class CosmosAdaLayerNormZero(nn.Module):
+    def __init__(self, in_features: int, hidden_features: int | None = None) -> None:
+        super().__init__()
+        self.norm = nn.LayerNorm(in_features, elementwise_affine=False, eps=1e-6)
+        self.activation = nn.SiLU()
+        self.linear_1 = (
+            nn.Identity() if hidden_features is None else nn.Linear(in_features, hidden_features, bias=False)
+        )
+        self.linear_2 = nn.Linear(hidden_features or in_features, 3 * in_features, bias=False)
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        embedded_timestep: torch.Tensor,
+        temb: torch.Tensor | None = None,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        embedded_timestep = self.activation(embedded_timestep)
+        embedded_timestep = self.linear_1(embedded_timestep)
+        embedded_timestep = self.linear_2(embedded_timestep)
+
+        if temb is not None:
+            embedded_timestep = embedded_timestep + temb
+
+        shift, scale, gate = embedded_timestep.chunk(3, dim=-1)
+        hidden_states = self.norm(hidden_states)
+
+        if embedded_timestep.ndim == 2:
+            shift, scale, gate = (x.unsqueeze(1) for x in (shift, scale, gate))
+
+        hidden_states = hidden_states * (1 + scale) + shift
+        return hidden_states, gate
+
+
+class CosmosGELU(nn.Module):
+    def __init__(self, dim: int, inner_dim: int, bias: bool = False) -> None:
+        super().__init__()
+        self.proj = nn.Linear(dim, inner_dim, bias=bias)
+
+    def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
+        return F.gelu(self.proj(hidden_states))
+
+
+class CosmosFeedForward(nn.Module):
+    def __init__(self, dim: int, mult: float = 4.0, bias: bool = False) -> None:
+        super().__init__()
+        inner_dim = int(dim * mult)
+        self.net = nn.ModuleList(
+            [
+                CosmosGELU(dim, inner_dim, bias=bias),
+                nn.Identity(),
+                nn.Linear(inner_dim, dim, bias=bias),
+            ]
+        )
+
+    def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
+        for module in self.net:
+            hidden_states = module(hidden_states)
+        return hidden_states
+
+
+class CosmosAttention(nn.Module):
+    def __init__(
+        self,
+        query_dim: int,
+        cross_attention_dim: int | None = None,
+        heads: int = 8,
+        dim_head: int = 64,
+        out_bias: bool = False,
+        img_context: bool = False,
+        prefix: str = "",
+    ) -> None:
+        super().__init__()
+        inner_dim = heads * dim_head
+        cross_attention_dim = query_dim if cross_attention_dim is None else cross_attention_dim
+
+        self.heads = heads
+        self.dim_head = dim_head
+        self.out_dim = inner_dim
+        self.query_dim = query_dim
+        self.to_q = nn.Linear(query_dim, inner_dim, bias=False)
+        self.to_k = nn.Linear(cross_attention_dim, inner_dim, bias=False)
+        self.to_v = nn.Linear(cross_attention_dim, inner_dim, bias=False)
+        self.norm_q = nn.RMSNorm(dim_head, eps=1e-6)
+        self.norm_k = nn.RMSNorm(dim_head, eps=1e-6)
+        self.to_out = nn.ModuleList([nn.Linear(inner_dim, query_dim, bias=out_bias), nn.Identity()])
+        self.attn = Attention(
+            num_heads=heads,
+            head_size=dim_head,
+            softmax_scale=1.0 / (dim_head**0.5),
+            causal=False,
+            num_kv_heads=heads,
+            prefix=prefix,
+        )
+
+        self.img_context = img_context
+        if img_context:
+            self.q_img = nn.Linear(query_dim, inner_dim, bias=False)
+            self.k_img = nn.Linear(query_dim, inner_dim, bias=False)
+            self.v_img = nn.Linear(query_dim, inner_dim, bias=False)
+            self.q_img_norm = nn.RMSNorm(dim_head, eps=1e-6)
+            self.k_img_norm = nn.RMSNorm(dim_head, eps=1e-6)
+            self.img_attn = Attention(
+                num_heads=heads,
+                head_size=dim_head,
+                softmax_scale=1.0 / (dim_head**0.5),
+                causal=False,
+                num_kv_heads=heads,
+                prefix=f"{prefix}.img_attn" if prefix else "img_attn",
+            )
+
+    def _attention(
+        self,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: torch.Tensor | None = None,
+        attention_mask: torch.Tensor | None = None,
+        image_rotary_emb: tuple[torch.Tensor, torch.Tensor] | None = None,
+    ) -> torch.Tensor:
+        encoder_hidden_states = hidden_states if encoder_hidden_states is None else encoder_hidden_states
+        batch_size, seq_len, _ = hidden_states.shape
+        encoder_seq_len = encoder_hidden_states.shape[1]
+
+        query = self.to_q(hidden_states).view(batch_size, seq_len, self.heads, self.dim_head)
+        key = self.to_k(encoder_hidden_states).view(batch_size, encoder_seq_len, self.heads, self.dim_head)
+        value = self.to_v(encoder_hidden_states).view(batch_size, encoder_seq_len, self.heads, self.dim_head)
+
+        query = self.norm_q(query)
+        key = self.norm_k(key)
+
+        if image_rotary_emb is not None:
+            # We use diffusers' apply_rotary_emb to leverage its internal float32 rotation upcasting
+            # logic, resolving the bfloat16 cumulative precision drift vs. the reference pipeline.
+            query = apply_rotary_emb(query, image_rotary_emb, sequence_dim=1, use_real_unbind_dim=-2)
+            key = apply_rotary_emb(key, image_rotary_emb, sequence_dim=1, use_real_unbind_dim=-2)
+
+        attn_metadata = AttentionMetadata(attn_mask=attention_mask) if attention_mask is not None else None
+        hidden_states = self.attn(query, key, value, attn_metadata=attn_metadata)
+        return hidden_states.flatten(2, 3).type_as(query)
+
+    def _image_attention(
+        self,
+        hidden_states: torch.Tensor,
+        img_context: torch.Tensor,
+        attention_mask: torch.Tensor | None = None,
+    ) -> torch.Tensor:
+        batch_size, seq_len, _ = hidden_states.shape
+        img_seq_len = img_context.shape[1]
+
+        query = self.q_img(hidden_states).view(batch_size, seq_len, self.heads, self.dim_head)
+        key = self.k_img(img_context).view(batch_size, img_seq_len, self.heads, self.dim_head)
+        value = self.v_img(img_context).view(batch_size, img_seq_len, self.heads, self.dim_head)
+
+        query = self.q_img_norm(query)
+        key = self.k_img_norm(key)
+
+        attn_metadata = AttentionMetadata(attn_mask=attention_mask) if attention_mask is not None else None
+        hidden_states = self.img_attn(query, key, value, attn_metadata=attn_metadata)
+        return hidden_states.flatten(2, 3).type_as(query)
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: torch.Tensor | tuple[torch.Tensor, torch.Tensor | None] | None = None,
+        attention_mask: torch.Tensor | tuple[torch.Tensor | None, torch.Tensor | None] | None = None,
+        image_rotary_emb: tuple[torch.Tensor, torch.Tensor] | None = None,
+    ) -> torch.Tensor:
+        if self.img_context:
+            if not isinstance(encoder_hidden_states, tuple):
+                raise ValueError("Expected encoder_hidden_states as (text_context, img_context).")
+            text_context, img_context = encoder_hidden_states
+            text_mask, img_mask = attention_mask if attention_mask is not None else (None, None)
+            query_states = hidden_states
+            hidden_states = self._attention(query_states, text_context, text_mask, image_rotary_emb)
+            if img_context is not None:
+                hidden_states = hidden_states + self._image_attention(query_states, img_context, img_mask)
+        else:
+            hidden_states = self._attention(hidden_states, encoder_hidden_states, attention_mask, image_rotary_emb)
+
+        hidden_states = self.to_out[0](hidden_states)
+        return self.to_out[1](hidden_states)
+
+
+class CosmosTransformerBlock(nn.Module):
+    def __init__(
+        self,
+        num_attention_heads: int,
+        attention_head_dim: int,
+        cross_attention_dim: int,
+        mlp_ratio: float = 4.0,
+        adaln_lora_dim: int = 256,
+        out_bias: bool = False,
+        img_context: bool = False,
+        before_proj: bool = False,
+        after_proj: bool = False,
+        prefix: str = "",
+    ) -> None:
+        super().__init__()
+        hidden_size = num_attention_heads * attention_head_dim
+
+        self.norm1 = CosmosAdaLayerNormZero(in_features=hidden_size, hidden_features=adaln_lora_dim)
+        self.img_context = img_context
+        self.attn1 = CosmosAttention(
+            query_dim=hidden_size,
+            cross_attention_dim=None,
+            heads=num_attention_heads,
+            dim_head=attention_head_dim,
+            out_bias=out_bias,
+            prefix=f"{prefix}.attn1" if prefix else "attn1",
+        )
+        self.norm2 = CosmosAdaLayerNormZero(in_features=hidden_size, hidden_features=adaln_lora_dim)
+        self.attn2 = CosmosAttention(
+            query_dim=hidden_size,
+            cross_attention_dim=cross_attention_dim,
+            heads=num_attention_heads,
+            dim_head=attention_head_dim,
+            out_bias=out_bias,
+            img_context=img_context,
+            prefix=f"{prefix}.attn2" if prefix else "attn2",
+        )
+        self.norm3 = CosmosAdaLayerNormZero(in_features=hidden_size, hidden_features=adaln_lora_dim)
+        self.ff = CosmosFeedForward(hidden_size, mult=mlp_ratio, bias=out_bias)
+
+        self.before_proj = nn.Linear(hidden_size, hidden_size) if before_proj else None
+        self.after_proj = nn.Linear(hidden_size, hidden_size) if after_proj else None
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: torch.Tensor | tuple[torch.Tensor, torch.Tensor | None],
+        embedded_timestep: torch.Tensor,
+        temb: torch.Tensor | None = None,
+        image_rotary_emb: tuple[torch.Tensor, torch.Tensor] | None = None,
+        extra_pos_emb: torch.Tensor | None = None,
+        attention_mask: torch.Tensor | tuple[torch.Tensor | None, torch.Tensor | None] | None = None,
+        controlnet_residual: torch.Tensor | None = None,
+        latents: torch.Tensor | None = None,
+        block_idx: int | None = None,
+    ) -> torch.Tensor | tuple[torch.Tensor, torch.Tensor]:
+        if self.before_proj is not None:
+            hidden_states = self.before_proj(hidden_states) + latents
+
+        if extra_pos_emb is not None:
+            hidden_states = hidden_states + extra_pos_emb
+
+        norm_hidden_states, gate = self.norm1(hidden_states, embedded_timestep, temb)
+        attn_output = self.attn1(norm_hidden_states, image_rotary_emb=image_rotary_emb)
+        hidden_states = hidden_states + gate * attn_output
+
+        norm_hidden_states, gate = self.norm2(hidden_states, embedded_timestep, temb)
+        attn_output = self.attn2(
+            norm_hidden_states, encoder_hidden_states=encoder_hidden_states, attention_mask=attention_mask
+        )
+        hidden_states = hidden_states + gate * attn_output
+
+        norm_hidden_states, gate = self.norm3(hidden_states, embedded_timestep, temb)
+        ff_output = self.ff(norm_hidden_states)
+        hidden_states = hidden_states + gate * ff_output
+
+        if controlnet_residual is not None:
+            if self.after_proj is not None:
+                raise ValueError("controlnet_residual is incompatible with after_proj.")
+            hidden_states = hidden_states + controlnet_residual
+
+        if self.after_proj is not None:
+            return hidden_states, self.after_proj(hidden_states)
+
+        return hidden_states
+
+
+class CosmosRotaryPosEmbed(nn.Module):
+    def __init__(
+        self,
+        hidden_size: int,
+        max_size: tuple[int, int, int] = (128, 240, 240),
+        patch_size: tuple[int, int, int] = (1, 2, 2),
+        base_fps: int = 24,
+        rope_scale: tuple[float, float, float] = (2.0, 1.0, 1.0),
+    ) -> None:
+        super().__init__()
+        self.max_size = [size // patch for size, patch in zip(max_size, patch_size)]
+        self.patch_size = patch_size
+        self.base_fps = base_fps
+
+        self.dim_h = hidden_size // 6 * 2
+        self.dim_w = hidden_size // 6 * 2
+        self.dim_t = hidden_size - self.dim_h - self.dim_w
+
+        self.h_ntk_factor = rope_scale[1] ** (self.dim_h / (self.dim_h - 2))
+        self.w_ntk_factor = rope_scale[2] ** (self.dim_w / (self.dim_w - 2))
+        self.t_ntk_factor = rope_scale[0] ** (self.dim_t / (self.dim_t - 2))
+
+    def forward(self, hidden_states: torch.Tensor, fps: float | None = None) -> tuple[torch.Tensor, torch.Tensor]:
+        _, _, num_frames, height, width = hidden_states.shape
+        pe_size = [num_frames // self.patch_size[0], height // self.patch_size[1], width // self.patch_size[2]]
+        device = hidden_states.device
+
+        h_theta = 10000.0 * self.h_ntk_factor
+        w_theta = 10000.0 * self.w_ntk_factor
+        t_theta = 10000.0 * self.t_ntk_factor
+
+        seq = torch.arange(max(self.max_size), device=device, dtype=torch.float32)
+        dim_h_range = torch.arange(0, self.dim_h, 2, device=device, dtype=torch.float32)[: self.dim_h // 2] / self.dim_h
+        dim_w_range = torch.arange(0, self.dim_w, 2, device=device, dtype=torch.float32)[: self.dim_w // 2] / self.dim_w
+        dim_t_range = torch.arange(0, self.dim_t, 2, device=device, dtype=torch.float32)[: self.dim_t // 2] / self.dim_t
+        h_spatial_freqs = 1.0 / (h_theta**dim_h_range)
+        w_spatial_freqs = 1.0 / (w_theta**dim_w_range)
+        temporal_freqs = 1.0 / (t_theta**dim_t_range)
+
+        emb_h = torch.outer(seq[: pe_size[1]], h_spatial_freqs)[None, :, None, :].repeat(pe_size[0], 1, pe_size[2], 1)
+        emb_w = torch.outer(seq[: pe_size[2]], w_spatial_freqs)[None, None, :, :].repeat(pe_size[0], pe_size[1], 1, 1)
+        if fps is None:
+            emb_t = torch.outer(seq[: pe_size[0]], temporal_freqs)
+        else:
+            emb_t = torch.outer(seq[: pe_size[0]] / fps * self.base_fps, temporal_freqs)
+        emb_t = emb_t[:, None, None, :].repeat(1, pe_size[1], pe_size[2], 1)
+
+        freqs = torch.cat([emb_t, emb_h, emb_w] * 2, dim=-1).flatten(0, 2).float()
+        return torch.cos(freqs), torch.sin(freqs)
+
+
+class CosmosLearnablePositionalEmbed(nn.Module):
+    def __init__(
+        self,
+        hidden_size: int,
+        max_size: tuple[int, int, int],
+        patch_size: tuple[int, int, int],
+        eps: float = 1e-6,
+    ) -> None:
+        super().__init__()
+        self.max_size = [size // patch for size, patch in zip(max_size, patch_size)]
+        self.patch_size = patch_size
+        self.eps = eps
+        self.pos_emb_t = nn.Parameter(torch.zeros(self.max_size[0], hidden_size))
+        self.pos_emb_h = nn.Parameter(torch.zeros(self.max_size[1], hidden_size))
+        self.pos_emb_w = nn.Parameter(torch.zeros(self.max_size[2], hidden_size))
+
+    def forward(self, hidden_states: torch.Tensor) -> torch.Tensor:
+        batch_size, _, num_frames, height, width = hidden_states.shape
+        pe_size = [num_frames // self.patch_size[0], height // self.patch_size[1], width // self.patch_size[2]]
+
+        emb_t = self.pos_emb_t[: pe_size[0]][None, :, None, None, :].repeat(batch_size, 1, pe_size[1], pe_size[2], 1)
+        emb_h = self.pos_emb_h[: pe_size[1]][None, None, :, None, :].repeat(batch_size, pe_size[0], 1, pe_size[2], 1)
+        emb_w = self.pos_emb_w[: pe_size[2]][None, None, None, :, :].repeat(batch_size, pe_size[0], pe_size[1], 1, 1)
+        emb = (emb_t + emb_h + emb_w).flatten(1, 3)
+
+        norm = torch.linalg.vector_norm(emb, dim=-1, keepdim=True, dtype=torch.float32)
+        norm = torch.add(self.eps, norm, alpha=np.sqrt(norm.numel() / emb.numel()))
+        return (emb / norm).type_as(hidden_states)
+
+
+class AnimaTransformer3DModel(nn.Module):
+    _repeated_blocks = ["CosmosTransformerBlock"]
+    _hsdp_shard_conditions = [is_transformer_block_module]
+
+    def __init__(
+        self,
+        in_channels: int = 16,
+        out_channels: int = 16,
+        num_attention_heads: int = 32,
+        attention_head_dim: int = 128,
+        num_layers: int = 28,
+        mlp_ratio: float = 4.0,
+        text_embed_dim: int = 1024,
+        adaln_lora_dim: int = 256,
+        max_size: tuple[int, int, int] = (128, 240, 240),
+        patch_size: tuple[int, int, int] = (1, 2, 2),
+        rope_scale: tuple[float, float, float] = (2.0, 1.0, 1.0),
+        concat_padding_mask: bool = True,
+        extra_pos_embed_type: str | None = "learnable",
+        use_crossattn_projection: bool = False,
+        crossattn_proj_in_channels: int = 1024,
+        encoder_hidden_states_channels: int = 1024,
+        controlnet_block_every_n: int | None = None,
+        img_context_dim_in: int | None = None,
+        img_context_num_tokens: int = 256,
+        img_context_dim_out: int = 2048,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__()
+        hidden_size = num_attention_heads * attention_head_dim
+        self.config = SimpleNamespace(
+            in_channels=in_channels,
+            out_channels=out_channels,
+            num_attention_heads=num_attention_heads,
+            attention_head_dim=attention_head_dim,
+            num_layers=num_layers,
+            mlp_ratio=mlp_ratio,
+            text_embed_dim=text_embed_dim,
+            adaln_lora_dim=adaln_lora_dim,
+            max_size=max_size,
+            patch_size=patch_size,
+            rope_scale=rope_scale,
+            concat_padding_mask=concat_padding_mask,
+            extra_pos_embed_type=extra_pos_embed_type,
+            use_crossattn_projection=use_crossattn_projection,
+            crossattn_proj_in_channels=crossattn_proj_in_channels,
+            encoder_hidden_states_channels=encoder_hidden_states_channels,
+            controlnet_block_every_n=controlnet_block_every_n,
+            img_context_dim_in=img_context_dim_in,
+            img_context_num_tokens=img_context_num_tokens,
+            img_context_dim_out=img_context_dim_out,
+            extra_config=kwargs,
+        )
+
+        patch_embed_in_channels = in_channels + 1 if concat_padding_mask else in_channels
+        self.patch_embed = CosmosPatchEmbed(patch_embed_in_channels, hidden_size, patch_size, bias=False)
+        self.rope = CosmosRotaryPosEmbed(
+            hidden_size=attention_head_dim,
+            max_size=max_size,
+            patch_size=patch_size,
+            rope_scale=rope_scale,
+        )
+        self.learnable_pos_embed: CosmosLearnablePositionalEmbed | None = None
+        if extra_pos_embed_type == "learnable":
+            self.learnable_pos_embed = CosmosLearnablePositionalEmbed(
+                hidden_size=hidden_size,
+                max_size=max_size,
+                patch_size=patch_size,
+            )
+        self.time_embed = CosmosEmbedding(hidden_size, hidden_size)
+        self.transformer_blocks = nn.ModuleList(
+            [
+                CosmosTransformerBlock(
+                    num_attention_heads=num_attention_heads,
+                    attention_head_dim=attention_head_dim,
+                    cross_attention_dim=text_embed_dim,
+                    mlp_ratio=mlp_ratio,
+                    adaln_lora_dim=adaln_lora_dim,
+                    out_bias=False,
+                    img_context=img_context_dim_in is not None and img_context_dim_in > 0,
+                    prefix=f"transformer_blocks.{i}",
+                )
+                for i in range(num_layers)
+            ]
+        )
+        self.norm_out = CosmosAdaLayerNorm(hidden_size, adaln_lora_dim)
+        self.proj_out = nn.Linear(hidden_size, patch_size[0] * patch_size[1] * patch_size[2] * out_channels, bias=False)
+
+        self.crossattn_proj: nn.Module | None = None
+        if use_crossattn_projection:
+            self.crossattn_proj = nn.Sequential(
+                nn.Linear(crossattn_proj_in_channels, encoder_hidden_states_channels, bias=True),
+                nn.GELU(),
+            )
+
+        self.img_context_proj: nn.Module | None = None
+        if img_context_dim_in:
+            self.img_context_proj = nn.Sequential(
+                nn.Linear(img_context_dim_in, img_context_dim_out, bias=True),
+                nn.GELU(),
+            )
+
+        self.gradient_checkpointing = False
+
+    @property
+    def dtype(self) -> torch.dtype:
+        return next(self.parameters()).dtype
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        timestep: torch.Tensor,
+        encoder_hidden_states: torch.Tensor | tuple[torch.Tensor, torch.Tensor | None],
+        block_controlnet_hidden_states: list[torch.Tensor] | None = None,
+        attention_mask: torch.Tensor | tuple[torch.Tensor | None, torch.Tensor | None] | None = None,
+        fps: float | None = None,
+        condition_mask: torch.Tensor | None = None,
+        padding_mask: torch.Tensor | None = None,
+        return_dict: bool = True,
+    ) -> Transformer2DModelOutput | tuple[torch.Tensor]:
+        batch_size, _, num_frames, height, width = hidden_states.shape
+
+        if condition_mask is not None:
+            hidden_states = torch.cat([hidden_states, condition_mask], dim=1)
+
+        if self.config.concat_padding_mask:
+            if padding_mask is None:
+                raise ValueError("padding_mask is required when concat_padding_mask=True.")
+            padding_mask_resized = F.interpolate(
+                padding_mask,
+                size=list(hidden_states.shape[-2:]),
+                mode="nearest",
+            )
+            hidden_states = torch.cat(
+                [hidden_states, padding_mask_resized.unsqueeze(2).repeat(batch_size, 1, num_frames, 1, 1)],
+                dim=1,
+            )
+
+        if isinstance(attention_mask, torch.Tensor) and attention_mask.ndim != 2:
+            attention_mask = attention_mask.squeeze(1).squeeze(1)
+
+        image_rotary_emb = self.rope(hidden_states, fps=fps)
+        extra_pos_emb = self.learnable_pos_embed(hidden_states) if self.learnable_pos_embed is not None else None
+
+        p_t, p_h, p_w = self.config.patch_size
+        post_patch_num_frames = num_frames // p_t
+        post_patch_height = height // p_h
+        post_patch_width = width // p_w
+
+        hidden_states = self.patch_embed(hidden_states)
+        hidden_states = hidden_states.flatten(1, 3)
+
+        if timestep.ndim == 1:
+            temb, embedded_timestep = self.time_embed(hidden_states, timestep)
+        elif timestep.ndim == 5:
+            if timestep.shape != (batch_size, 1, num_frames, 1, 1):
+                raise ValueError(f"Expected timestep shape [B, 1, T, 1, 1], got {timestep.shape}.")
+            timestep = timestep.flatten()
+            temb, embedded_timestep = self.time_embed(hidden_states, timestep)
+            temb, embedded_timestep = (
+                x.view(batch_size, post_patch_num_frames, 1, 1, -1)
+                .expand(-1, -1, post_patch_height, post_patch_width, -1)
+                .flatten(1, 3)
+                for x in (temb, embedded_timestep)
+            )
+        else:
+            raise ValueError(f"Expected timestep shape [B, 1, T, 1, 1] or [T], got {timestep.shape}.")
+
+        text_context, img_context = (
+            encoder_hidden_states if isinstance(encoder_hidden_states, tuple) else (encoder_hidden_states, None)
+        )
+        if self.config.use_crossattn_projection:
+            if self.crossattn_proj is None:
+                raise ValueError("crossattn_proj is required when use_crossattn_projection=True.")
+            text_context = self.crossattn_proj(text_context)
+        if img_context is not None and self.config.img_context_dim_in:
+            if self.img_context_proj is None:
+                raise ValueError("img_context_proj is required when img_context_dim_in is set.")
+            img_context = self.img_context_proj(img_context)
+        processed_encoder_hidden_states = (
+            (text_context, img_context) if isinstance(encoder_hidden_states, tuple) else text_context
+        )
+
+        controlnet_block_index_map = {}
+        if block_controlnet_hidden_states is not None:
+            n_blocks = len(self.transformer_blocks)
+            controlnet_block_index_map = {
+                block_idx: block_controlnet_hidden_states[idx]
+                for idx, block_idx in list(enumerate(range(0, n_blocks, self.config.controlnet_block_every_n)))
+            }
+
+        for block_idx, block in enumerate(self.transformer_blocks):
+            hidden_states = block(
+                hidden_states,
+                processed_encoder_hidden_states,
+                embedded_timestep,
+                temb,
+                image_rotary_emb,
+                extra_pos_emb,
+                attention_mask,
+                controlnet_block_index_map.get(block_idx),
+            )
+
+        hidden_states = self.norm_out(hidden_states, embedded_timestep, temb)
+        hidden_states = self.proj_out(hidden_states)
+        hidden_states = hidden_states.unflatten(2, (p_h, p_w, p_t, -1))
+        hidden_states = hidden_states.unflatten(1, (post_patch_num_frames, post_patch_height, post_patch_width))
+        hidden_states = hidden_states.permute(0, 7, 1, 6, 2, 4, 3, 5)
+        hidden_states = hidden_states.flatten(6, 7).flatten(4, 5).flatten(2, 3)
+
+        if not return_dict:
+            return (hidden_states,)
+
+        return Transformer2DModelOutput(sample=hidden_states)
+
+    def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]]) -> set[str]:
+        params = dict(self.named_parameters())
+        loaded = set()
+        for name, tensor in weights:
+            if name not in params:
+                continue
+            param = params[name]
+            weight_loader = getattr(param, "weight_loader", default_weight_loader)
+            weight_loader(param, tensor)
+            loaded.add(name)
+        return loaded
diff --git a/vllm_omni/diffusion/models/anima/pipeline_anima.py b/vllm_omni/diffusion/models/anima/pipeline_anima.py
new file mode 100644
index 00000000000..63fdb7794ef
--- /dev/null
+++ b/vllm_omni/diffusion/models/anima/pipeline_anima.py
@@ -0,0 +1,795 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+import inspect
+import json
+import logging
+import os
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any, cast
+
+import numpy as np
+import torch
+from diffusers.image_processor import VaeImageProcessor
+from diffusers.schedulers import FlowMatchEulerDiscreteScheduler
+from diffusers.utils.torch_utils import randn_tensor
+from safetensors.torch import load_file
+from torch import nn
+from transformers import AutoTokenizer, Qwen3Model, T5TokenizerFast
+
+from vllm_omni.diffusion.config import set_current_diffusion_config
+from vllm_omni.diffusion.data import DiffusionOutput, OmniDiffusionConfig
+from vllm_omni.diffusion.distributed.autoencoders.autoencoder_kl_qwenimage import DistributedAutoencoderKLQwenImage
+from vllm_omni.diffusion.distributed.utils import get_local_device
+from vllm_omni.diffusion.models.anima.anima_text_conditioner import (
+    ANIMA_TEXT_CONDITIONER_CONFIG,
+    AnimaTextConditioner,
+)
+from vllm_omni.diffusion.models.anima.anima_transformer import ANIMA_TRANSFORMER_CONFIG, AnimaTransformer3DModel
+from vllm_omni.diffusion.models.progress_bar import ProgressBarMixin
+from vllm_omni.diffusion.offloader.config import OffloadStrategy, resolve_offload_strategy
+from vllm_omni.diffusion.profiler.diffusion_pipeline_profiler import DiffusionPipelineProfilerMixin
+from vllm_omni.diffusion.utils.size_utils import normalize_min_aligned_size
+from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch
+
+logger = logging.getLogger(__name__)
+
+ANIMA_VAE_SCALE_FACTOR = 8
+
+
+def retrieve_timesteps(
+    scheduler: Any,
+    num_inference_steps: int | None = None,
+    device: str | torch.device | None = None,
+    timesteps: list[int] | None = None,
+    sigmas: list[float] | None = None,
+    **kwargs: Any,
+) -> tuple[torch.Tensor, int]:
+    if timesteps is not None and sigmas is not None:
+        raise ValueError("Only one of `timesteps` or `sigmas` can be passed. Please choose one to set custom values")
+    if timesteps is not None:
+        if "timesteps" not in inspect.signature(scheduler.set_timesteps).parameters:
+            raise ValueError(
+                f"The current scheduler class {scheduler.__class__}'s `set_timesteps` does not support custom"
+                f" timestep schedules. Please check whether you are using the correct scheduler."
+            )
+        scheduler.set_timesteps(timesteps=timesteps, device=device, **kwargs)
+        scheduler_timesteps = scheduler.timesteps
+        num_inference_steps = len(scheduler_timesteps)
+    elif sigmas is not None:
+        if "sigmas" not in inspect.signature(scheduler.set_timesteps).parameters:
+            raise ValueError(
+                f"The current scheduler class {scheduler.__class__}'s `set_timesteps` does not support custom"
+                f" sigmas schedules. Please check whether you are using the correct scheduler."
+            )
+        scheduler.set_timesteps(sigmas=sigmas, device=device, **kwargs)
+        scheduler_timesteps = scheduler.timesteps
+        num_inference_steps = len(scheduler_timesteps)
+    else:
+        scheduler.set_timesteps(num_inference_steps, device=device, **kwargs)
+        scheduler_timesteps = scheduler.timesteps
+    if num_inference_steps is None:
+        num_inference_steps = len(scheduler_timesteps)
+    return cast(torch.Tensor, scheduler_timesteps), num_inference_steps
+
+
+_ANIMA_ORIGINAL_TRANSFORMER_RENAMES = {
+    "t_embedder.1": "time_embed.t_embedder",
+    "t_embedding_norm": "time_embed.norm",
+    "blocks": "transformer_blocks",
+    "adaln_modulation_self_attn.1": "norm1.linear_1",
+    "adaln_modulation_self_attn.2": "norm1.linear_2",
+    "adaln_modulation_cross_attn.1": "norm2.linear_1",
+    "adaln_modulation_cross_attn.2": "norm2.linear_2",
+    "adaln_modulation_mlp.1": "norm3.linear_1",
+    "adaln_modulation_mlp.2": "norm3.linear_2",
+    "self_attn": "attn1",
+    "cross_attn": "attn2",
+    "q_proj": "to_q",
+    "k_proj": "to_k",
+    "v_proj": "to_v",
+    "output_proj": "to_out.0",
+    "q_norm": "norm_q",
+    "k_norm": "norm_k",
+    "mlp.layer1": "ff.net.0.proj",
+    "mlp.layer2": "ff.net.2",
+    "x_embedder.proj.1": "patch_embed.proj",
+    "final_layer.adaln_modulation.1": "norm_out.linear_1",
+    "final_layer.adaln_modulation.2": "norm_out.linear_2",
+    "final_layer.linear": "proj_out",
+}
+
+_ANIMA_ORIGINAL_TRANSFORMER_DROP_KEYS = (
+    "accum_video_sample_counter",
+    "accum_image_sample_counter",
+    "accum_iteration",
+    "accum_train_in_hours",
+    "pos_embedder.seq",
+    "pos_embedder.dim_spatial_range",
+    "pos_embedder.dim_temporal_range",
+    "_extra_state",
+)
+
+
+def _anima_vae_scale_factor_from_vae(vae: Any) -> int:
+    vae_config = getattr(vae, "config", None)
+    spatial_compression_ratio = getattr(vae_config, "spatial_compression_ratio", None)
+    if spatial_compression_ratio is not None:
+        return int(spatial_compression_ratio)
+    temporal_downsample = getattr(vae, "temperal_downsample", None)
+    if temporal_downsample is not None:
+        return int(2 ** len(temporal_downsample))
+    return ANIMA_VAE_SCALE_FACTOR
+
+
+def get_anima_post_process_func(od_config: OmniDiffusionConfig) -> Callable[[torch.Tensor], Any]:
+    image_processor = VaeImageProcessor(vae_scale_factor=ANIMA_VAE_SCALE_FACTOR)
+
+    def post_process_func(images: torch.Tensor) -> Any:
+        return image_processor.postprocess(images)
+
+    return post_process_func
+
+
+class AnimaPipeline(nn.Module, DiffusionPipelineProfilerMixin, ProgressBarMixin):
+    """Native Anima model path.
+
+    The Anima transformer checkpoint is distributed as a single safetensors
+    file. This loader builds the native pipeline components and runs the denoise
+    transformer/text-conditioner directly.
+    """
+
+    supports_step_execution = False
+
+    def __init__(self, *, od_config: OmniDiffusionConfig, device: torch.device | str | None = None) -> None:
+        super().__init__()
+        self.od_config = od_config
+        self.parallel_config = od_config.parallel_config
+        self.device = device or get_local_device()
+        self.weights_sources: list[str] = []
+
+        self._raise_unsupported_features()
+
+        self._interrupt = False
+        self._guidance_scale = 1.0
+        self._num_timesteps = 0
+        self._current_timestep = None
+        self._profiler_initialized = False
+
+    def _raise_unsupported_features(self) -> None:
+        pc = self.od_config.parallel_config
+        if pc.cfg_parallel_size > 1:
+            raise NotImplementedError("AnimaPipeline does not yet support CFG parallel. Validate native CFG first.")
+        if pc.sequence_parallel_size is not None and pc.sequence_parallel_size > 1:
+            raise NotImplementedError("AnimaPipeline does not yet support sequence parallelism. Add an _sp_plan first.")
+        if pc.tensor_parallel_size > 1:
+            raise NotImplementedError("AnimaPipeline does not yet support tensor parallelism. Port TP linears first.")
+        if pc.use_hsdp:
+            raise NotImplementedError("AnimaPipeline does not yet support HSDP. Validate sharding after native load.")
+        if self.od_config.cache_backend not in ("none", None):
+            raise NotImplementedError("AnimaPipeline does not yet support TeaCache or Cache-DiT.")
+        if self.od_config.quantization_config is not None:
+            raise NotImplementedError("AnimaPipeline does not yet support quantized checkpoints.")
+        if resolve_offload_strategy(self.od_config) is not OffloadStrategy.NONE:
+            raise NotImplementedError("AnimaPipeline does not yet support CPU offload.")
+
+    @staticmethod
+    def _sub_state_dict(state_dict: dict[str, torch.Tensor], prefix: str) -> dict[str, torch.Tensor]:
+        return {key.removeprefix(prefix): value for key, value in state_dict.items() if key.startswith(prefix)}
+
+    @staticmethod
+    def _convert_original_transformer_state_dict(state_dict: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
+        if "patch_embed.proj.weight" in state_dict:
+            return state_dict
+
+        # The raw Anima checkpoint uses the original training names for a
+        # Cosmos-style denoiser. Convert those keys to the local
+        # AnimaTransformer3DModel module names before strict loading.
+        converted_state_dict = {}
+        for key, value in state_dict.items():
+            new_key = key.removeprefix("net.")
+            if any(drop_key in new_key for drop_key in _ANIMA_ORIGINAL_TRANSFORMER_DROP_KEYS):
+                continue
+            for old_key, new_name in _ANIMA_ORIGINAL_TRANSFORMER_RENAMES.items():
+                new_key = new_key.replace(old_key, new_name)
+            if new_key in converted_state_dict:
+                raise ValueError(f"Duplicate converted Anima transformer key: {new_key}")
+            converted_state_dict[new_key] = value
+        return converted_state_dict
+
+    @staticmethod
+    def _split_single_file_state_dict(
+        state_dict: dict[str, torch.Tensor],
+    ) -> tuple[dict[str, torch.Tensor], dict[str, torch.Tensor]]:
+        transformer_state_dict = AnimaPipeline._sub_state_dict(state_dict, "transformer.")
+        text_conditioner_state_dict = AnimaPipeline._sub_state_dict(state_dict, "text_conditioner.")
+        if transformer_state_dict and text_conditioner_state_dict:
+            return transformer_state_dict, text_conditioner_state_dict
+
+        text_conditioner_state_dict = AnimaPipeline._sub_state_dict(state_dict, "net.llm_adapter.")
+        if text_conditioner_state_dict:
+            transformer_state_dict = {
+                key: value for key, value in state_dict.items() if not key.startswith("net.llm_adapter.")
+            }
+            return transformer_state_dict, text_conditioner_state_dict
+
+        raise ValueError(
+            "Anima native loader could not find text-conditioner weights. Expected either "
+            "`text_conditioner.*` Diffusers keys or `net.llm_adapter.*` original Anima keys."
+        )
+
+    def _load_native_denoiser_components(
+        self,
+        state_dict: dict[str, torch.Tensor] | None = None,
+    ) -> tuple[AnimaTransformer3DModel, AnimaTextConditioner]:
+        if state_dict is None:
+            model_path = self.od_config.model
+            if not isinstance(model_path, str) or not os.path.isfile(model_path):
+                raise ValueError(f"AnimaPipeline currently requires a local file path, got: {model_path}")
+
+            state_dict = load_file(model_path, device="cpu")
+        transformer_state_dict, text_conditioner_state_dict = self._split_single_file_state_dict(state_dict)
+        del state_dict
+        transformer_state_dict = self._convert_original_transformer_state_dict(transformer_state_dict)
+
+        config_path = Path(self.od_config.model).with_suffix(".json")
+        config = json.loads(config_path.read_text()) if config_path.is_file() else {}
+        text_conditioner_config = {**ANIMA_TEXT_CONDITIONER_CONFIG, **config.get("text_conditioner", {})}
+        transformer_config = {**ANIMA_TRANSFORMER_CONFIG, **config.get("transformer", {})}
+
+        native_text_conditioner = AnimaTextConditioner(**cast(dict[str, Any], text_conditioner_config))
+        native_text_conditioner.load_state_dict(text_conditioner_state_dict, strict=True)
+        native_text_conditioner.to(device=self.device, dtype=self.od_config.dtype)
+        del text_conditioner_state_dict
+
+        native_transformer = AnimaTransformer3DModel(**cast(dict[str, Any], transformer_config))
+        native_transformer.load_state_dict(transformer_state_dict, strict=True)
+        native_transformer.to(device=self.device, dtype=self.od_config.dtype)
+        del transformer_state_dict
+
+        return native_transformer, native_text_conditioner
+
+    def _component_path(self, name: str, default_model: str) -> str:
+        custom_args = self.od_config.custom_pipeline_args or {}
+        return str(custom_args.get(f"{name}_model", custom_args.get(f"{name}_path", default_model)))
+
+    @staticmethod
+    def _from_pretrained_kwargs(model: str, subfolder: str | None = None) -> dict[str, Any]:
+        kwargs: dict[str, Any] = {"local_files_only": os.path.exists(model)}
+        if subfolder is not None and os.path.isdir(os.path.join(model, subfolder)):
+            kwargs["subfolder"] = subfolder
+        return kwargs
+
+    def _load_outer_components(self) -> tuple[Any, Any, Any, Any, Any]:
+        custom_args = self.od_config.custom_pipeline_args or {}
+        components_model_value = custom_args.get("components_model", custom_args.get("components_path"))
+        if components_model_value is None:
+            if not isinstance(self.od_config.model, str):
+                raise ValueError("AnimaPipeline requires `model` or `components_model` to load outer components.")
+            checkpoint_dir = os.path.dirname(os.path.abspath(self.od_config.model))
+            components_model = checkpoint_dir if os.path.isdir(checkpoint_dir) else self.od_config.model
+        else:
+            components_model = str(components_model_value)
+
+        text_encoder_model = self._component_path("text_encoder", components_model)
+        vae_model = self._component_path("vae", components_model)
+        tokenizer_model = self._component_path("tokenizer", components_model)
+        t5_tokenizer_model = self._component_path("t5_tokenizer", components_model)
+
+        text_encoder = Qwen3Model.from_pretrained(
+            text_encoder_model,
+            torch_dtype=self.od_config.dtype,
+            **self._from_pretrained_kwargs(text_encoder_model, "text_encoder"),
+        ).to(self.device)
+        vae = DistributedAutoencoderKLQwenImage.from_pretrained(
+            vae_model,
+            torch_dtype=self.od_config.dtype,
+            **self._from_pretrained_kwargs(vae_model, "vae"),
+        ).to(self.device)
+        tokenizer = AutoTokenizer.from_pretrained(
+            tokenizer_model,
+            **self._from_pretrained_kwargs(tokenizer_model, "tokenizer"),
+        )
+        t5_tokenizer = T5TokenizerFast.from_pretrained(
+            t5_tokenizer_model,
+            **self._from_pretrained_kwargs(t5_tokenizer_model, "t5_tokenizer"),
+        )
+
+        scheduler_model = self._component_path("scheduler", components_model)
+        has_scheduler_config = os.path.isfile(os.path.join(scheduler_model, "scheduler_config.json")) or os.path.isdir(
+            os.path.join(scheduler_model, "scheduler")
+        )
+        if has_scheduler_config:
+            scheduler = FlowMatchEulerDiscreteScheduler.from_pretrained(
+                scheduler_model,
+                **self._from_pretrained_kwargs(scheduler_model, "scheduler"),
+            )
+        else:
+            scheduler = FlowMatchEulerDiscreteScheduler(shift=3.0)
+
+        return text_encoder, tokenizer, t5_tokenizer, vae, scheduler
+
+    def load_weights(self, weights: Iterable[tuple[str, torch.Tensor]] | None = None) -> set[str]:
+        logger.info("Loading Anima transformer/text-conditioner directly from single-file checkpoint.")
+        state_dict = dict(weights) if weights is not None else None
+        loaded = set(state_dict.keys()) if state_dict is not None else set()
+        if not state_dict:
+            state_dict = None
+        with set_current_diffusion_config(self.od_config):
+            native_transformer, native_text_conditioner = self._load_native_denoiser_components(state_dict)
+        text_encoder, tokenizer, t5_tokenizer, vae, scheduler = self._load_outer_components()
+
+        self.transformer = native_transformer
+        self.text_conditioner = native_text_conditioner
+        self.text_encoder = text_encoder
+        self.tokenizer = tokenizer
+        self.t5_tokenizer = t5_tokenizer
+        self.vae = vae
+        self.scheduler = scheduler
+        self.vae_scale_factor = _anima_vae_scale_factor_from_vae(self.vae)
+        self._setup_profiler()
+        return loaded
+
+    def _setup_profiler(self) -> None:
+        if self._profiler_initialized:
+            return
+        self.setup_diffusion_pipeline_profiler(
+            profiler_targets=["vae.decode", "diffuse", "text_encoder.forward"],
+            enable_diffusion_pipeline_profiler=self.od_config.enable_diffusion_pipeline_profiler,
+        )
+        self._profiler_initialized = True
+
+    def _extract_prompts(self, prompts: list[Any]) -> tuple[str | list[str] | None, str | list[str] | None]:
+        """Extract prompt and negative_prompt from OmniPromptType list."""
+        prompt = [p if isinstance(p, str) else (p.get("prompt") or "") for p in prompts] or None
+        if all(isinstance(p, str) or p.get("negative_prompt") is None for p in prompts):
+            negative_prompt = None
+        elif prompts:
+            negative_prompt = ["" if isinstance(p, str) else (p.get("negative_prompt") or "") for p in prompts]
+        else:
+            negative_prompt = None
+        return prompt, negative_prompt
+
+    def _get_qwen_prompt_embeds(
+        self,
+        prompt: str | list[str],
+        max_sequence_length: int,
+        device: torch.device,
+        dtype: torch.dtype,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        prompt = [prompt] if isinstance(prompt, str) else prompt
+
+        text_inputs = self.tokenizer(
+            prompt,
+            padding="longest",
+            max_length=max_sequence_length,
+            truncation=True,
+            return_tensors="pt",
+        )
+        text_input_ids = text_inputs.input_ids.to(device)
+        prompt_attention_mask = text_inputs.attention_mask.to(device)
+        if text_input_ids.shape[-1] == 0:
+            text_input_ids = text_input_ids.new_zeros((text_input_ids.shape[0], 1))
+            prompt_attention_mask = prompt_attention_mask.new_zeros((prompt_attention_mask.shape[0], 1))
+
+        prompt_embeds = self.text_encoder(
+            input_ids=text_input_ids,
+            attention_mask=prompt_attention_mask,
+            output_hidden_states=False,
+        ).last_hidden_state
+        prompt_embeds = prompt_embeds.to(dtype=dtype, device=device)
+        prompt_embeds = prompt_embeds * prompt_attention_mask.to(prompt_embeds).unsqueeze(-1)
+
+        return prompt_embeds, prompt_attention_mask
+
+    def _get_t5_prompt_ids(
+        self,
+        prompt: str | list[str],
+        max_sequence_length: int,
+        device: torch.device,
+    ) -> tuple[torch.Tensor, torch.Tensor]:
+        prompt = [prompt] if isinstance(prompt, str) else prompt
+
+        text_inputs = self.t5_tokenizer(
+            prompt,
+            padding="longest",
+            max_length=max_sequence_length,
+            truncation=True,
+            return_tensors="pt",
+        )
+        return text_inputs.input_ids.to(device), text_inputs.attention_mask.to(device)
+
+    def encode_prompt(
+        self,
+        prompt: str | list[str],
+        negative_prompt: str | list[str] | None = None,
+        prepare_unconditional_embeds: bool = True,
+        max_sequence_length: int = 512,
+        device: torch.device | None = None,
+        dtype: torch.dtype | None = None,
+    ) -> dict[str, torch.Tensor | None]:
+        device = device or self.device
+        dtype = dtype or self.text_encoder.dtype
+
+        prompt = [prompt] if isinstance(prompt, str) else prompt
+        batch_size = len(prompt)
+
+        prompt_embeds, prompt_attention_mask = self._get_qwen_prompt_embeds(
+            prompt=prompt,
+            max_sequence_length=max_sequence_length,
+            device=device,
+            dtype=dtype,
+        )
+        t5_input_ids, t5_attention_mask = self._get_t5_prompt_ids(
+            prompt=prompt,
+            max_sequence_length=max_sequence_length,
+            device=device,
+        )
+
+        negative_prompt_embeds = None
+        negative_prompt_attention_mask = None
+        negative_t5_input_ids = None
+        negative_t5_attention_mask = None
+        if prepare_unconditional_embeds:
+            if negative_prompt is None:
+                negative_prompt = ""
+            if isinstance(negative_prompt, str):
+                negative_prompt = [negative_prompt] * batch_size
+            elif len(negative_prompt) != batch_size:
+                raise ValueError(
+                    f"`negative_prompt` length ({len(negative_prompt)}) must match prompt batch size ({batch_size})."
+                )
+
+            negative_prompt_embeds, negative_prompt_attention_mask = self._get_qwen_prompt_embeds(
+                prompt=negative_prompt,
+                max_sequence_length=max_sequence_length,
+                device=device,
+                dtype=dtype,
+            )
+            negative_t5_input_ids, negative_t5_attention_mask = self._get_t5_prompt_ids(
+                prompt=negative_prompt,
+                max_sequence_length=max_sequence_length,
+                device=device,
+            )
+
+        return {
+            "qwen_prompt_embeds": prompt_embeds,
+            "qwen_attention_mask": prompt_attention_mask,
+            "t5_input_ids": t5_input_ids,
+            "t5_attention_mask": t5_attention_mask,
+            "negative_qwen_prompt_embeds": negative_prompt_embeds,
+            "negative_qwen_attention_mask": negative_prompt_attention_mask,
+            "negative_t5_input_ids": negative_t5_input_ids,
+            "negative_t5_attention_mask": negative_t5_attention_mask,
+        }
+
+    def condition_prompt_embeds(
+        self,
+        qwen_prompt_embeds: torch.Tensor,
+        qwen_attention_mask: torch.Tensor,
+        t5_input_ids: torch.Tensor,
+        t5_attention_mask: torch.Tensor,
+        device: torch.device | None = None,
+        conditioning_dtype: torch.dtype | None = None,
+        output_dtype: torch.dtype | None = None,
+    ) -> torch.Tensor:
+        device = device or self.device
+        conditioning_dtype = conditioning_dtype or self.text_conditioner.dtype
+        output_dtype = output_dtype or self.transformer.dtype
+
+        prompt_embeds = self.text_conditioner(
+            source_hidden_states=qwen_prompt_embeds.to(device=device, dtype=conditioning_dtype),
+            target_input_ids=t5_input_ids.to(device),
+            target_attention_mask=t5_attention_mask.to(device),
+            source_attention_mask=qwen_attention_mask.to(device),
+        )
+        return prompt_embeds.to(dtype=output_dtype, device=device)
+
+    def prepare_latents(
+        self,
+        batch_size: int,
+        num_channels_latents: int,
+        height: int,
+        width: int,
+        dtype: torch.dtype | None = None,
+        device: torch.device | None = None,
+        generator: torch.Generator | list[torch.Generator] | None = None,
+        latents: torch.Tensor | None = None,
+    ) -> torch.Tensor:
+        device = device or self.device
+        dtype = dtype or self.transformer.dtype
+        if latents is not None:
+            return latents.to(device=device, dtype=dtype)
+
+        latent_height = height // self.vae_scale_factor
+        latent_width = width // self.vae_scale_factor
+        shape = (batch_size, num_channels_latents, 1, latent_height, latent_width)
+
+        if isinstance(generator, list) and len(generator) != batch_size:
+            raise ValueError(
+                f"You have passed a list of generators of length {len(generator)}, but requested an effective batch"
+                f" size of {batch_size}. Make sure the batch size matches the length of the generators."
+            )
+
+        # Draw latents in float32 then cast
+        latents = randn_tensor(shape, generator=generator, device=device, dtype=torch.float32)
+        sigma_max = (
+            getattr(self.scheduler.config, "sigma_max", 1.0)
+            if hasattr(self, "scheduler") and hasattr(self.scheduler, "config")
+            else 1.0
+        )
+        return latents.to(dtype=dtype) * sigma_max
+
+    def prepare_timesteps(
+        self,
+        num_inference_steps: int,
+        sigmas: list[float] | None = None,
+        device: torch.device | None = None,
+    ) -> tuple[torch.Tensor, int]:
+        device = device or self.device
+        sigmas = np.linspace(1.0, 1 / num_inference_steps, num_inference_steps) if sigmas is None else sigmas
+        return retrieve_timesteps(
+            self.scheduler,
+            device=device,
+            sigmas=sigmas,
+        )
+
+    def diffuse(
+        self,
+        prompt_embeds: torch.Tensor,
+        negative_prompt_embeds: torch.Tensor | None,
+        latents: torch.Tensor,
+        padding_mask: torch.Tensor,
+        timesteps: torch.Tensor,
+        do_true_cfg: bool,
+        true_cfg_scale: float,
+    ) -> torch.Tensor:
+        self.scheduler.set_begin_index(0)
+
+        with self.progress_bar(total=len(timesteps)) as pbar:
+            for i, t in enumerate(timesteps):
+                if self.interrupt:
+                    continue
+                self._current_timestep = t
+
+                # Broadcast timestep to match batch size
+                timestep = t.expand(latents.shape[0]).to(dtype=self.transformer.dtype, device=latents.device)
+                timestep = timestep / 1000.0  # normalize to 0..1 range
+
+                # Predict noise
+                latent_model_input = latents.to(self.transformer.dtype)
+
+                # Positive pass
+                noise_pred = self.transformer(
+                    hidden_states=latent_model_input,
+                    timestep=timestep,
+                    encoder_hidden_states=prompt_embeds,
+                    padding_mask=padding_mask,
+                    return_dict=False,
+                )[0]
+
+                # Negative / uncond pass
+                if do_true_cfg and negative_prompt_embeds is not None:
+                    noise_pred_uncond = self.transformer(
+                        hidden_states=latent_model_input,
+                        timestep=timestep,
+                        encoder_hidden_states=negative_prompt_embeds,
+                        padding_mask=padding_mask,
+                        return_dict=False,
+                    )[0]
+                    noise_pred = noise_pred_uncond + true_cfg_scale * (noise_pred - noise_pred_uncond)
+
+                # Scheduler step
+                latents_dtype = latents.dtype
+                latents = self.scheduler.step(noise_pred.to(latents_dtype), t, latents, return_dict=False)[0]
+                if latents.dtype != latents_dtype:
+                    latents = latents.to(latents_dtype)
+
+                pbar.update()
+
+        return latents
+
+    def decode_latents(
+        self,
+        latents: torch.Tensor,
+        output_type: str = "pil",
+    ) -> DiffusionOutput:
+        """Decode final latents."""
+        if output_type == "latent":
+            return DiffusionOutput(
+                output=latents,
+                stage_durations=self.stage_durations if hasattr(self, "stage_durations") else None,
+            )
+
+        latents = latents.to(self.vae.dtype)
+        latents_mean = (
+            torch.tensor(self.vae.config.latents_mean)
+            .view(1, self.vae.config.z_dim, 1, 1, 1)
+            .to(latents.device, latents.dtype)
+        )
+        latents_std = (
+            torch.tensor(self.vae.config.latents_std)
+            .view(1, self.vae.config.z_dim, 1, 1, 1)
+            .to(latents.device, latents.dtype)
+        )
+        latents = latents * latents_std + latents_mean
+        image = self.vae.decode(latents, return_dict=False)[0][:, :, 0]
+        return DiffusionOutput(
+            output=image,
+            stage_durations=self.stage_durations if hasattr(self, "stage_durations") else None,
+        )
+
+    def forward(
+        self,
+        req: DiffusionRequestBatch,
+        prompt: str | list[str] | None = None,
+        negative_prompt: str | list[str] | None = None,
+        true_cfg_scale: float = 4.0,
+        height: int | None = None,
+        width: int | None = None,
+        num_inference_steps: int = 50,
+        sigmas: list[float] | None = None,
+        guidance_scale: float = 4.0,
+        num_images_per_prompt: int = 1,
+        generator: torch.Generator | list[torch.Generator] | None = None,
+        latents: torch.Tensor | None = None,
+        output_type: str | None = "pil",
+        max_sequence_length: int = 512,
+    ) -> list[DiffusionOutput]:
+        if req.num_reqs != 1:
+            raise ValueError("AnimaPipeline supports one request per forward.")
+        extracted_prompt, negative_prompt = self._extract_prompts(req.prompts)
+        prompt = extracted_prompt or prompt
+        if prompt is None:
+            prompt = ""
+
+        height = req.sampling_params.height or height or 1024
+        width = req.sampling_params.width or width or 1024
+        height, width = normalize_min_aligned_size(height, width, self.vae_scale_factor * 2)
+        if height is None or width is None:
+            raise ValueError("AnimaPipeline requires resolved height and width.")
+        height = int(height)
+        width = int(width)
+        if req.sampling_params.output_type is not None:
+            output_type = req.sampling_params.output_type
+        output_type = output_type or "pil"
+
+        num_inference_steps = req.sampling_params.num_inference_steps or num_inference_steps
+        sigmas = req.sampling_params.sigmas or sigmas
+        max_sequence_length = req.sampling_params.max_sequence_length or max_sequence_length
+        generator = req.sampling_params.generator or generator
+        if req.sampling_params.guidance_scale_provided:
+            guidance_scale = req.sampling_params.guidance_scale
+            if req.sampling_params.true_cfg_scale is None:
+                true_cfg_scale = guidance_scale
+        if req.sampling_params.true_cfg_scale is not None:
+            true_cfg_scale = req.sampling_params.true_cfg_scale
+        num_images_per_prompt = (
+            req.sampling_params.num_outputs_per_prompt
+            if req.sampling_params.num_outputs_per_prompt > 0
+            else num_images_per_prompt
+        )
+
+        self._guidance_scale = guidance_scale
+        self._interrupt = False
+
+        if isinstance(prompt, str):
+            batch_size = 1
+        else:
+            batch_size = len(prompt)
+
+        do_true_cfg = guidance_scale > 1.0
+
+        # Encode prompts
+        enc_out = self.encode_prompt(
+            prompt=prompt,
+            negative_prompt=negative_prompt,
+            prepare_unconditional_embeds=do_true_cfg,
+            max_sequence_length=max_sequence_length,
+            device=self.device,
+            dtype=self.text_encoder.dtype,
+        )
+        qwen_prompt_embeds = enc_out["qwen_prompt_embeds"]
+        qwen_attention_mask = enc_out["qwen_attention_mask"]
+        t5_input_ids = enc_out["t5_input_ids"]
+        t5_attention_mask = enc_out["t5_attention_mask"]
+        if (
+            qwen_prompt_embeds is None
+            or qwen_attention_mask is None
+            or t5_input_ids is None
+            or t5_attention_mask is None
+        ):
+            raise ValueError("Anima prompt encoding did not produce all required positive embeddings.")
+
+        # Condition prompt embeds
+        prompt_embeds = self.condition_prompt_embeds(
+            qwen_prompt_embeds=qwen_prompt_embeds,
+            qwen_attention_mask=qwen_attention_mask,
+            t5_input_ids=t5_input_ids,
+            t5_attention_mask=t5_attention_mask,
+            device=self.device,
+        )
+
+        negative_prompt_embeds = None
+        negative_qwen_prompt_embeds = enc_out["negative_qwen_prompt_embeds"]
+        if do_true_cfg and negative_qwen_prompt_embeds is not None:
+            negative_qwen_attention_mask = enc_out["negative_qwen_attention_mask"]
+            negative_t5_input_ids = enc_out["negative_t5_input_ids"]
+            negative_t5_attention_mask = enc_out["negative_t5_attention_mask"]
+            if (
+                negative_qwen_attention_mask is None
+                or negative_t5_input_ids is None
+                or negative_t5_attention_mask is None
+            ):
+                raise ValueError("Anima prompt encoding did not produce all required negative embeddings.")
+            negative_prompt_embeds = self.condition_prompt_embeds(
+                qwen_prompt_embeds=negative_qwen_prompt_embeds,
+                qwen_attention_mask=negative_qwen_attention_mask,
+                t5_input_ids=negative_t5_input_ids,
+                t5_attention_mask=negative_t5_attention_mask,
+                device=self.device,
+            )
+
+        # Repeat for num_images_per_prompt
+        _, seq_len, _ = prompt_embeds.shape
+        prompt_embeds = prompt_embeds.repeat(1, num_images_per_prompt, 1)
+        prompt_embeds = prompt_embeds.view(batch_size * num_images_per_prompt, seq_len, -1)
+
+        if negative_prompt_embeds is not None:
+            _, seq_len, _ = negative_prompt_embeds.shape
+            negative_prompt_embeds = negative_prompt_embeds.repeat(1, num_images_per_prompt, 1)
+            negative_prompt_embeds = negative_prompt_embeds.view(batch_size * num_images_per_prompt, seq_len, -1)
+
+        # Prepare latents
+        latents = self.prepare_latents(
+            batch_size=batch_size * num_images_per_prompt,
+            num_channels_latents=16,  # Cosmos/Anima has 16 channels
+            height=height,
+            width=width,
+            dtype=torch.float32,
+            device=self.device,
+            generator=generator,
+            latents=latents,
+        )
+
+        # Prepare padding mask
+        padding_mask = latents.new_zeros(1, 1, height, width, dtype=self.transformer.dtype)
+
+        # Prepare timesteps
+        timesteps, num_inference_steps = self.prepare_timesteps(
+            num_inference_steps=num_inference_steps,
+            sigmas=sigmas,
+            device=self.device,
+        )
+        self._num_timesteps = len(timesteps)
+
+        # Denoise loop
+        latents = self.diffuse(
+            prompt_embeds=prompt_embeds,
+            negative_prompt_embeds=negative_prompt_embeds,
+            latents=latents,
+            padding_mask=padding_mask,
+            timesteps=timesteps,
+            do_true_cfg=do_true_cfg,
+            true_cfg_scale=true_cfg_scale,
+        )
+
+        self._current_timestep = None
+        return [self.decode_latents(latents, output_type=output_type)]
+
+    @property
+    def guidance_scale(self) -> float:
+        return self._guidance_scale
+
+    @property
+    def num_timesteps(self) -> int:
+        return self._num_timesteps
+
+    @property
+    def current_timestep(self) -> torch.Tensor | None:
+        return self._current_timestep
+
+    @property
+    def interrupt(self) -> bool:
+        return self._interrupt
diff --git a/vllm_omni/diffusion/registry.py b/vllm_omni/diffusion/registry.py
index fadb712df00..17d8216db68 100644
--- a/vllm_omni/diffusion/registry.py
+++ b/vllm_omni/diffusion/registry.py
@@ -19,6 +19,19 @@
 
 logger = init_logger(__name__)
 
+_NATIVE_SINGLE_FILE_MODELS = {
+    "AnimaPipeline": ("AnimaModularPipeline",),
+}
+
+
+def resolve_native_single_file(model_class_name: str | None) -> str | None:
+    """Return the canonical native pipeline for a single-file model class."""
+    for canonical, aliases in _NATIVE_SINGLE_FILE_MODELS.items():
+        if model_class_name == canonical or model_class_name in aliases:
+            return canonical
+    return None
+
+
 _DIFFUSION_MODELS = {
     # arch:(mod_folder, mod_relname, cls_name)
     "QwenImagePipeline": (
@@ -361,6 +374,11 @@
         "pipeline_dreamzero",
         "DreamZeroPipeline",
     ),
+    "AnimaPipeline": (
+        "anima",
+        "pipeline_anima",
+        "AnimaPipeline",
+    ),
     "StableDiffusionXLPipeline": (
         "sdxl",
         "pipeline_sdxl",
@@ -387,6 +405,7 @@
 _NO_CACHE_ACCELERATION = {
     # Pipelines that do not support cache acceleration (cache_dit / tea_cache).
     "NextStep11Pipeline",
+    "AnimaPipeline",
     # π0 is a flow-matching VLA with a self-contained sample_actions loop and no
     # DiT-style ``.transformer`` block list, so cache_dit / tea_cache cannot apply
     # to it; list it here so a stray cache_backend override disables gracefully
@@ -564,6 +583,7 @@ def _apply_sequence_parallel_if_enabled(model, od_config: OmniDiffusionConfig) -
     # `post_process_func` function must be placed in {mod_folder}/{mod_relname}.py,
     # where mod_folder and mod_relname are  defined and mapped using `_DIFFUSION_MODELS` via the `arch` key
     "QwenImagePipeline": "get_qwen_image_post_process_func",
+    "AnimaPipeline": "get_anima_post_process_func",
     "QwenImageEditPipeline": "get_qwen_image_edit_post_process_func",
     "QwenImageEditPlusPipeline": "get_qwen_image_edit_plus_post_process_func",
     "GlmImagePipeline": "get_glm_image_post_process_func",
diff --git a/vllm_omni/diffusion/worker/diffusion_worker.py b/vllm_omni/diffusion/worker/diffusion_worker.py
index b9506f102d9..f934646dc63 100644
--- a/vllm_omni/diffusion/worker/diffusion_worker.py
+++ b/vllm_omni/diffusion/worker/diffusion_worker.py
@@ -1568,31 +1568,31 @@ def __init__(
             gpu_id: GPU device ID
             od_config: OmniDiffusionConfig configuration
             worker_extension_cls: Optional qualified name of worker extension class
-            custom_pipeline_args: Optional arguments for custom pipeline initialization
+            custom_pipeline_args: Optional arguments passed to native pipelines.
+                A ``pipeline_class`` entry triggers custom pipeline initialization.
         """
         self.gpu_id = gpu_id
         self.od_config = od_config
         self.base_worker_class = base_worker_class
         self.worker_extension_cls = worker_extension_cls
         self.custom_pipeline_args = custom_pipeline_args
+        self.uses_custom_pipeline = bool(custom_pipeline_args and "pipeline_class" in custom_pipeline_args)
 
         # Prepare worker class with extension support
         worker_class = self._prepare_worker_class()
 
         # Create the actual worker instance
-        # When custom_pipeline_args is provided, skip initial model loading
-        # since re_init_pipeline will handle it. This avoids allocating memory
-        # through CuMemAllocator twice, which causes assertion failures in
-        # sleep mode.
+        # Only dynamic custom pipelines skip initial loading; native pipelines
+        # may also use custom_pipeline_args for model-specific component paths.
         self.worker = worker_class(
             local_rank=gpu_id,
             rank=gpu_id,
             od_config=od_config,
-            skip_load_model=(self.custom_pipeline_args is not None),
+            skip_load_model=self.uses_custom_pipeline,
         )
 
         # Re-initialize pipeline with custom pipeline if provided
-        if self.custom_pipeline_args is not None:
+        if self.uses_custom_pipeline:
             self.worker.re_init_pipeline(self.custom_pipeline_args)
 
     def _prepare_worker_class(self) -> type:
@@ -1605,8 +1605,8 @@ def _prepare_worker_class(self) -> type:
         """
         worker_class = self.base_worker_class
 
-        # If custom_pipeline_args is provided, use CustomPipelineWorkerExtension
-        if self.custom_pipeline_args is not None:
+        # If custom pipeline initialization is requested, use CustomPipelineWorkerExtension.
+        if self.uses_custom_pipeline:
             # Set worker_extension_cls to CustomPipelineWorkerExtension if not already set
             if self.worker_extension_cls is None:
                 self.worker_extension_cls = CustomPipelineWorkerExtension
diff --git a/vllm_omni/engine/arg_utils.py b/vllm_omni/engine/arg_utils.py
index d1e53775a01..b6aba463bbc 100644
--- a/vllm_omni/engine/arg_utils.py
+++ b/vllm_omni/engine/arg_utils.py
@@ -181,9 +181,9 @@ class OmniEngineArgs(EngineArgs):
             (e.g. ["text", "audio"]). If None, all modalities supported by
             the model are used.
         log_stats: Whether to log engine statistics. Defaults to False.
-        custom_pipeline_args: Dictionary of arguments for custom pipeline
-            initialization (e.g., ``{"pipeline_class": "my.Module"}``).
-            Passed through to the diffusion stage engine.
+        custom_pipeline_args: Dictionary of arguments passed through to the
+            diffusion pipeline. When it contains ``pipeline_class``, it triggers
+            custom pipeline initialization.
     """
 
     stage_id: int = 0
diff --git a/vllm_omni/entrypoints/cli/serve.py b/vllm_omni/entrypoints/cli/serve.py
index 14e13cd4a13..10ae2166d9a 100644
--- a/vllm_omni/entrypoints/cli/serve.py
+++ b/vllm_omni/entrypoints/cli/serve.py
@@ -25,6 +25,7 @@
 from vllm.entrypoints.serve.utils.api_utils import VLLM_SUBCMD_PARSER_EPILOG
 from vllm.logger import init_logger
 
+from vllm_omni.diffusion.registry import resolve_native_single_file
 from vllm_omni.entrypoints.cli.logo import log_logo
 from vllm_omni.entrypoints.openai.api_server import (
     omni_run_server,
@@ -305,7 +306,8 @@ def validate(self, args: argparse.Namespace) -> None:
         from vllm_omni.diffusion.utils.hf_utils import is_diffusion_model
 
         model = getattr(args, "model_tag", None) or getattr(args, "model", None)
-        if model and is_diffusion_model(model):
+        native_single_file = resolve_native_single_file(getattr(args, "model_class_name", None))
+        if model and ((native_single_file is not None and os.path.isfile(model)) or is_diffusion_model(model)):
             if api_server_count is not None and api_server_count > 1:
                 raise ValueError("--api-server-count > 1 is not supported for diffusion models")
             logger.info("Detected diffusion model: %s", model)
@@ -636,6 +638,16 @@ def subparser_init(self, subparsers: argparse._SubParsersAction) -> TrackingArgu
                 '(e.g. \'{"num_inference_steps": 30, "guidance_scale": 7.5}\').'
             ),
         )
+        omni_config_group.add_argument(
+            "--custom-pipeline-args",
+            dest="custom_pipeline_args",
+            type=json.loads,
+            default=None,
+            help=(
+                "JSON object passed to native/custom diffusion pipelines. "
+                'Only args containing "pipeline_class" trigger custom pipeline re-initialization.'
+            ),
+        )
         omni_config_group.add_argument(
             "--usp",
             "--ulysses-degree",

From f9f53f2bd8ddf7c7990b167d448108daa50f992a Mon Sep 17 00:00:00 2001
From: boatman <1930807094@qq.com>
Date: Sun, 20 Sep 2026 00:19:14 +0800
Subject: [PATCH 104/105] [Bugfix]Include Reference Audio Cache Salt for
 HiggsAudio v2 (#7826)

Signed-off-by: boatman <109857087+sphinxkkkbc@users.noreply.github.com>
---
 .../openai_api/test_serving_speech.py         | 47 +++++++++++++++++++
 .../openai/tts_adapters/higgs_audio_v2.py     |  5 +-
 2 files changed, 51 insertions(+), 1 deletion(-)

diff --git a/tests/entrypoints/openai_api/test_serving_speech.py b/tests/entrypoints/openai_api/test_serving_speech.py
index 7cdeebc39b1..77117ed0dd5 100644
--- a/tests/entrypoints/openai_api/test_serving_speech.py
+++ b/tests/entrypoints/openai_api/test_serving_speech.py
@@ -1859,6 +1859,53 @@ async def test_higgs_v3_cache_salt_changes_with_ref_audio_cache_key(self, speech
         assert prompt_a["additional_information"]["ref_audio_cache_key"] == "key_aaa"
         assert prompt_b["additional_information"]["ref_audio_cache_key"] == "key_bbb"
 
+    @pytest.mark.asyncio
+    async def test_higgs_v2_cache_salt_changes_for_same_shaped_reference_audio(self, speech_server, mocker):
+        """Higgs v2 must salt identical placeholder prompts by resolved audio content."""
+        build_voice_clone_prompt = mocker.patch(
+            "vllm_omni.model_executor.models.higgs_audio_v2.higgs_audio_v2_tokenizer.build_voice_clone_prompt"
+        )
+        build_voice_clone_prompt.side_effect = lambda _processor, _input, wav, _sr, _ref_text: {
+            "prompt_token_ids": [1, 151700, 151700, 2],
+            "audio_input_ids": torch.tensor([[100 if wav[0] < 0.5 else 900, 2], [3, 4]], dtype=torch.long),
+            "audio_input_ids_mask": torch.ones(2, dtype=torch.bool),
+        }
+
+        speech_server._tts_model_type = "higgs_audio_v2"
+        speech_server._adapter = speech_server._get_tts_adapter()
+        speech_server._adapter._resolve_higgs_audio_v2_processor = mocker.AsyncMock(return_value=object())
+
+        req_a = OpenAICreateSpeechRequest(
+            input="hello",
+            ref_audio="file:///data/spk.wav",
+            ref_text="transcript",
+        )
+        req_b = OpenAICreateSpeechRequest(
+            input="hello",
+            ref_audio="file:///data/spk.wav",
+            ref_text="transcript",
+        )
+        speech_server._adapter._resolve_ref_audio = mocker.AsyncMock(
+            side_effect=[([0.1] * 48000, 24000, "key_aaa"), ([0.9] * 48000, 24000, "key_bbb")]
+        )
+
+        prompt_a = await speech_server._adapter._build_higgs_audio_v2_params(req_a)
+        prompt_b = await speech_server._adapter._build_higgs_audio_v2_params(req_b)
+
+        assert prompt_a["prompt_token_ids"] == [1, 151700, 151700, 2]
+        assert prompt_a["prompt_token_ids"] == prompt_b["prompt_token_ids"]
+        assert (
+            prompt_a["additional_information"]["audio_input_ids"].shape
+            == prompt_b["additional_information"]["audio_input_ids"].shape
+        )
+        assert not torch.equal(
+            prompt_a["additional_information"]["audio_input_ids"],
+            prompt_b["additional_information"]["audio_input_ids"],
+        )
+        assert prompt_a["cache_salt"] != prompt_b["cache_salt"]
+        assert prompt_a["additional_information"]["ref_audio_cache_key"] == "key_aaa"
+        assert prompt_b["additional_information"]["ref_audio_cache_key"] == "key_bbb"
+
     # ── MossReferenceEncoder: speaker cache invalidation ──
 
     @pytest.mark.asyncio
diff --git a/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v2.py b/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v2.py
index 33f16cf0a9b..761b5431a4e 100644
--- a/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v2.py
+++ b/vllm_omni/entrypoints/openai/tts_adapters/higgs_audio_v2.py
@@ -13,6 +13,7 @@
     ARTTSAdapter,
     PreparedRequest,
     apply_max_new_tokens,
+    conditioning_cache_salt,
     resolve_stage_model_path,
 )
 
@@ -55,7 +56,7 @@ async def _build_higgs_audio_v2_params(self, request: "OpenAICreateSpeechRequest
             prompt_token_ids = input_ids_to_python_list(inputs)
             return tokens_input(prompt_token_ids=prompt_token_ids)
 
-        wav_list, sr, _ = await self._resolve_ref_audio(request.ref_audio)
+        wav_list, sr, cache_key = await self._resolve_ref_audio(request.ref_audio)
         wav = np.asarray(wav_list, dtype=np.float32)
         out = await asyncio.to_thread(
             build_voice_clone_prompt,
@@ -75,7 +76,9 @@ async def _build_higgs_audio_v2_params(self, request: "OpenAICreateSpeechRequest
         prompt["additional_information"] = {
             "audio_input_ids": out["audio_input_ids"],
             "audio_input_ids_mask": out["audio_input_ids_mask"],
+            "ref_audio_cache_key": cache_key,
         }
+        prompt["cache_salt"] = conditioning_cache_salt(request, prompt["additional_information"])
         return prompt
 
     async def _resolve_higgs_audio_v2_processor(self):

From 23d8c83dab27037332205b376d4986dec158b366 Mon Sep 17 00:00:00 2001
From: NumberWan <wantszkin2003@gmail.com>
Date: Sun, 20 Sep 2026 00:34:11 +0800
Subject: [PATCH 105/105] [Bugfix][Qwen-Image] Keep AutoRound W4A16 on CPU when
 offloading; Fixes #7555 (#7579)

Signed-off-by: NumberWan <wantszkin2003@gmail.com>
---
 .../test_qwen_image_pipeline_device.py        | 131 ++++++++++++++++++
 ...st_qwen_image_autoround_w4a16_expansion.py |   4 +-
 .../models/qwen_image/pipeline_qwen_image.py  |  10 +-
 3 files changed, 141 insertions(+), 4 deletions(-)
 create mode 100644 tests/diffusion/models/qwen_image/test_qwen_image_pipeline_device.py

diff --git a/tests/diffusion/models/qwen_image/test_qwen_image_pipeline_device.py b/tests/diffusion/models/qwen_image/test_qwen_image_pipeline_device.py
new file mode 100644
index 00000000000..7f0ce51c8dc
--- /dev/null
+++ b/tests/diffusion/models/qwen_image/test_qwen_image_pipeline_device.py
@@ -0,0 +1,131 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: Copyright contributors to the vLLM-Omni project
+
+"""Encoder/VAE placement under cpu_offload; DiT follows the loader device context."""
+
+from types import SimpleNamespace
+from unittest.mock import MagicMock
+
+import pytest
+import torch
+from torch import nn
+
+pytestmark = [pytest.mark.core_model, pytest.mark.diffusion, pytest.mark.cpu]
+
+_DEVICE_STACK: list[str] = ["cpu"]
+_REAL_TORCH_DEVICE = torch.device
+
+
+class _FakeDevice:
+    def __init__(self, type_: str):
+        self.type = type_
+        self.index = 0
+
+    def __enter__(self):
+        _DEVICE_STACK.append(self.type)
+        return self
+
+    def __exit__(self, *args):
+        _DEVICE_STACK.pop()
+        return False
+
+
+def _fake_torch_device(spec):
+    if isinstance(spec, _FakeDevice):
+        return spec
+    if isinstance(spec, _REAL_TORCH_DEVICE):
+        return _FakeDevice(spec.type)
+    return _FakeDevice(str(spec).split(":")[0])
+
+
+class _RecordingTransformer(nn.Module):
+    def __init__(self, *args, **kwargs):
+        super().__init__()
+        self.probe_device_type = _DEVICE_STACK[-1]
+
+
+class _MoveableModule(nn.Module):
+    def __init__(self):
+        super().__init__()
+        self.placed_device = _FakeDevice("cpu")
+        self.weight = nn.Parameter(torch.zeros(1))
+
+    def to(self, device, *args, **kwargs):
+        if isinstance(device, _FakeDevice):
+            self.placed_device = device
+        elif isinstance(device, _REAL_TORCH_DEVICE):
+            self.placed_device = _FakeDevice(device.type)
+        else:
+            self.placed_device = _FakeDevice(str(device).split(":")[0])
+        return self
+
+    @property
+    def temperal_downsample(self):
+        return [True, True, True]
+
+
+def _run_pipeline_init(monkeypatch, *, enable_cpu_offload, loader_device):
+    import vllm_omni.diffusion.models.qwen_image.pipeline_qwen_image as pipe_mod
+    from vllm_omni.diffusion.models.qwen_image.pipeline_qwen_image import QwenImagePipeline
+
+    enc = _MoveableModule()
+    vae = _MoveableModule()
+    _DEVICE_STACK.clear()
+    _DEVICE_STACK.append(loader_device)
+
+    monkeypatch.setattr(pipe_mod, "get_local_device", lambda: _REAL_TORCH_DEVICE("cuda"))
+    monkeypatch.setattr(pipe_mod.torch, "device", _fake_torch_device)
+    monkeypatch.setattr(pipe_mod, "prefetch_subfolders", lambda *a, **k: None)
+    monkeypatch.setattr(pipe_mod, "get_transformer_config_kwargs", lambda *a, **k: {})
+    monkeypatch.setattr(pipe_mod, "QwenImageTransformer2DModel", _RecordingTransformer)
+    monkeypatch.setattr(
+        pipe_mod.FlowMatchEulerDiscreteScheduler,
+        "from_pretrained",
+        classmethod(lambda cls, *a, **k: MagicMock()),
+    )
+    monkeypatch.setattr(
+        pipe_mod.Qwen2Tokenizer,
+        "from_pretrained",
+        classmethod(lambda cls, *a, **k: MagicMock()),
+    )
+
+    def _prefetch(factory, *args, **kwargs):
+        subfolder = kwargs.get("subfolder")
+        if subfolder == "text_encoder":
+            return enc
+        if subfolder == "vae":
+            return vae
+        raise AssertionError(f"unexpected prefetch subfolder={subfolder!r}")
+
+    monkeypatch.setattr(pipe_mod, "from_pretrained_with_prefetch", _prefetch)
+    monkeypatch.setattr(
+        QwenImagePipeline,
+        "setup_diffusion_pipeline_profiler",
+        lambda self, **kwargs: None,
+    )
+
+    od_config = SimpleNamespace(
+        model="/tmp/unused-qwen-image",
+        parallel_config=SimpleNamespace(),
+        tf_model_config={},
+        quantization_config=None,
+        enable_cpu_offload=enable_cpu_offload,
+        enable_diffusion_pipeline_profiler=False,
+    )
+    return QwenImagePipeline(od_config=od_config)
+
+
+def test_pipeline_cpu_offload_parks_encoder_vae_on_cpu(monkeypatch):
+    """#7555: cpu_offload keeps BF16 encoder/VAE off the GPU during DiT init."""
+    pipe = _run_pipeline_init(monkeypatch, enable_cpu_offload=True, loader_device="cuda")
+    assert pipe.text_encoder.placed_device.type == "cpu"
+    assert pipe.vae.placed_device.type == "cpu"
+    assert pipe.transformer.probe_device_type == "cuda"
+
+
+def test_pipeline_dit_follows_loader_cpu_without_override(monkeypatch):
+    """Layerwise / HSDP: DiT must not be forced onto CUDA by the pipeline."""
+    pipe = _run_pipeline_init(monkeypatch, enable_cpu_offload=False, loader_device="cpu")
+    assert pipe.transformer.probe_device_type == "cpu"
+    assert pipe.text_encoder.placed_device.type == "cuda"
+    assert pipe.vae.placed_device.type == "cuda"
diff --git a/tests/e2e/offline_inference/test_qwen_image_autoround_w4a16_expansion.py b/tests/e2e/offline_inference/test_qwen_image_autoround_w4a16_expansion.py
index 3d370ec8b0f..3157551eff1 100644
--- a/tests/e2e/offline_inference/test_qwen_image_autoround_w4a16_expansion.py
+++ b/tests/e2e/offline_inference/test_qwen_image_autoround_w4a16_expansion.py
@@ -56,7 +56,7 @@ def test_qwen_image_autoround_w4a16_load():
     Verifies that quant_config is propagated to all transformer blocks
     and produces a valid, non-blank image.
     """
-    with OmniRunner(QUANTIZED_MODEL, enforce_eager=True) as runner:
+    with OmniRunner(QUANTIZED_MODEL, enforce_eager=True, enable_cpu_offload=True) as runner:
         outputs = runner.omni.generate(
             "a cup of coffee on a table",
             _sampling_params(),
@@ -85,7 +85,7 @@ def test_qwen_image_autoround_w4a16_generate():
         true_cfg_scale=5.0,
         generator=torch.Generator(device=current_omni_platform.device_type).manual_seed(42),
     )
-    with OmniRunner(QUANTIZED_MODEL, enforce_eager=True) as runner:
+    with OmniRunner(QUANTIZED_MODEL, enforce_eager=True, enable_cpu_offload=True) as runner:
         outputs = runner.omni.generate(
             "a cup of coffee on a wooden table, morning sunlight, photorealistic",
             params,
diff --git a/vllm_omni/diffusion/models/qwen_image/pipeline_qwen_image.py b/vllm_omni/diffusion/models/qwen_image/pipeline_qwen_image.py
index 0aa00abd92d..5e262ff1e01 100644
--- a/vllm_omni/diffusion/models/qwen_image/pipeline_qwen_image.py
+++ b/vllm_omni/diffusion/models/qwen_image/pipeline_qwen_image.py
@@ -337,14 +337,20 @@ def __init__(
             del visual_owner.visual
         else:
             logger.warning("Qwen-Image: vision tower not found on text encoder; skipping drop")
-        self.text_encoder = self.text_encoder.to(self.device)
+        # Under model-level CPU offload, keep the BF16 encoder/VAE on CPU so they
+        # do not share VRAM with DiT construction (#7555). The DiT follows the
+        # loader's default-device context (CUDA for online / AutoRound INT under
+        # offload, CPU for layerwise / unquantized HSDP defer).
+        cpu_offload = bool(getattr(self.od_config, "enable_cpu_offload", False))
+        enc_vae_device = torch.device("cpu") if cpu_offload else self.device
+        self.text_encoder = self.text_encoder.to(enc_vae_device)
         self.vae = from_pretrained_with_prefetch(
             DistributedAutoencoderKLQwenImage.from_pretrained,
             model,
             subfolder="vae",
             prefetch_list=qwen_subfolders,
             local_files_only=local_files_only,
-        ).to(self.device)
+        ).to(enc_vae_device)
         transformer_kwargs = get_transformer_config_kwargs(od_config.tf_model_config, QwenImageTransformer2DModel)
         self.transformer = QwenImageTransformer2DModel(
             od_config=od_config,